wiki:BuildingUsingGenericBuildsystem

Version 67 (modified by Samuli Seppänen, 12 years ago) (diff)

--

Project structure

Look here for details.

Building natively on *NIX

Building natively on *NIX has not changed much, you can still use roughly the same process as before. If building from Git sources, first do a

$ autoreconf -vi

If building from a release tarball, you can skip the above step. To configure, build and install OpenVPN, use these commands:

$ ./configure <configure-options>
$ make
$ make install

In most cases, you'd use something like this:

$ ./configure

If you're using password authentication, you may be interested in support for password stored in (properly protected!) files:

$ ./configure --enable-password-save

Or, if you want to use smart cards and such, you should use

$ ./configure --enable-pkcs11

Cross-compiling on *NIX ("generic" subdir)

Installing prequisites

You can use the generic buildsystem from openvpn-build subproject to cross-compile OpenVPN using any toolchain to any target environment. The build host must have a *NIX-like environment, e.g. Linux, *BSD or Cygwin (on Windows). First make sure you have installed the correct tools before you start:

On Ubuntu 12.04 (64-bit) you the following commands should take care of everything except osslsigncode:

$ apt-get update
$ apt-get install git-core mingw-w64 gcc-4.6-arm-linux-gnueabi man2html dos2unix nsis

If you're building using Cygwin on Windows, it's best to configure Git not to translate LF to CR/LF. For this reason it's probably best to use Cygwin's Git. Also take a look at Cygwin's README to see which packages are required.

Checking out openvpn-build repository

Check out the openvpn-build subproject using Git:

$ git clone https://github.com/OpenVPN/openvpn-build.git

Then go to the generic directory:

$ cd openvpn-build/generic

Customizing the build

To customize the build options, refer to build.vars, it contains the defaults for building, most settings can be customized by setting environment variable before executing the build script.

If you want to use your own, local sources (e.g. for OpenSSL or OpenVPN), put them in sources directory, so that the generic buildsystem knows not to download them from a remote site. The cached tarballs will be used even if they're of a different version than what would be downloaded. This is useful for building custom version.

Building OpenVPN and it's dependencies

The ./build command fetches all the dependencies, builds them and builds OpenVPN. To build a native binary:

$ IMAGEROOT=`pwd`/image-native ./build

To build for Windows 32bit on Linux 64bit:

$ IMAGEROOT=`pwd`/image-win32 CHOST=i686-w64-mingw32 \
    CBUILD=x86_64-pc-linux-gnu ./build

To build for Windows 64bit on Linux 64bit:

$ IMAGEROOT=`pwd`/image-win64 CHOST=x86_64-w64-mingw32 \
    CBUILD=x86_64-pc-linux-gnu ./build

To build for Arm on Linux 64bit:

$ IMAGEROOT=`pwd`/image-arm CHOST=arm-linux-gnueabi \
    CBUILD=x86_64-pc-linux-gnu ./build

Building dependencies only

To build only dependencies (helpful for developers):

$ DO_ONLY_DEPS=1 IMAGEROOT=`pwd`/deps-win32 CHOST=i686-w64-mingw32 \
    CBUILD=x86_64-pc-linux-gnu ./build

For typical OpenVPN installations you'll most likely want to use something like this:

$ DEP=location of the dependencies
$ ./configure host=... \
    CFLAGS="-I$DEP/include" LDFLAGS="-L$DEB/lib" \
    --enable-pkcs11 \
    PKCS11_HELPER_CFLAGS=" " PKCS11_HELPER_LIBS="-lpkcs11-helper"

Cleaning up

If you want to start from scratch, do

$ cd openvpn-build/generic
$ rm -f sources/*
$ rm -rf image-*

Creating a NSIS installer ("windows-nsis" subdir)

You can use the scripts in openvpn-build/windows-nsis to create a NSIS installer for Windows. The scripts use the generic build system to build OpenVPN and it's dependencies (e.g. lzo, openssl), and use osslsigncode for signing the resulting binaries, if requested.

NSIS must be available on system. If installed not in path or standard location set MAKENSIS environment variable. Same goes for OSSLSIGNCODE.

First check out openvpn-build as described here. Check build-complete.vars for variables which you can set in the shell to point the build-complete script to the correct dependency packages (easy-rsa and tap-windows). Then, if you want to build an (unsigned) installer, do the following:

$ cd openvpn-build/windows-nsis
$ ./build-snapshot

If you want to build a signed installer (with all included libraries and executables signed) use something like this instead:

$ ./build-snapshot --sign --sign-pkcs12=signingkey.p12 --sign-pkcs12-pass=yourpassphrase --sign-timestamp="http://timestamp.domain.com"

Refer to ./build-complete --help and build-snapshot for more options.

NOTE: To make sure fresh tarballs are used, empty ./sources directory before building.

Building natively on Windows using the MSVC toolchain ("msvc" subdir)

Installing prequisites

MSVC build was written with least dependencies in mind. You'll need only Perl and Visual Studio 2010 (Express).

Checking out openvpn-build repository

Launch a Git Bash and follow these instructions. Next go to the msvc directory and build:

> cd openvpn-build/msvc
> build

This fetches all the dependencies, builds them and builds OpenVPN.

Building dependencies only

To build only dependencies (helpful for developers):

> set DO_ONLY_DEPS=true
> set TARGET=c:\Temp\build-deps
> build

Customizing the build

To customize the build options, refer to build-env.bat, it contains the defaults for building, most settings can be customized by setting environment variable before executing the build script.

You can also configure the build to use a Git repository or tarball of your liking, for example:

set OPENVPN_GIT=git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn.git
set OPENVPN_SOURCE=git
set OPENVPN_BRANCH=master

Build OpenVPN manually

Provided you built the dependencies you can use the MSVC build system within OpenVPN tree, edit build-env-local.bat which is loaded by build.bat. The variables defined in build-env-local.bat override the defaults given in build-env.bat. For example, you can manually define the location of dependencies:

set OPENVPN_DEPROOT=c:\Temp\build-deps

Then open IDE using:

> msvc-dev

Or build using:

> msvc-build

Building TAP-Windows

Required software: Recent Windows DDK, NSIS.

First clone the tap-windows repository, e.g. using Git Bash:

$ git clone https://github.com/OpenVPN/tap-windows

Next you need to set some environment variables. For self-signed test certificates use something like this:

set CODESIGN_PKCS12=c:\Users\John\tap-windows\my-self-signed-certificate.p12
set CODESIGN_PASS=mypassphrase
set CODESIGN_ISTEST=yes

For paid-for software publisher certificates (SPC) you'd use something like this:

set CODESIGN_PKCS12="c:\Users\John\tap-windows\my-software-publisher-certificate.p12"
set CODESIGN_PASS=mypassphrase
set CODESIGN_ISTEST=no
set CODESIGN_CROSS="C:\Users\John\tap-windows\ca-cross-certificate.crt"
set CODESIGN_TIMESTAMP="http://timestamp.domain.com"

If you imported the kernel-mode code-signing certicate using Internet Explorer, you can use certmgr.exe to export it in PFX (=PKCS12) format. Just make sure to include the private key in the file and to give it a sufficiently strong password, which you then define using CODESIGN_PASS variable. The CA cross certificate can be obtained from your CA and most likely needs no modifications. The URL for the timestamping service is CA-specific, but trivial to locate.

Next you configure the tap-windows build to use these using a Visual Studio command prompt:

> configure

This copies the variables to tap-windows\config-env.bat, which is included during build. All that's left is to build the tap-windows drivers:

> build

Further customization for MSVC can be done using config-local.m4 file which overrides variables or with environment variables which override auto detection code. This can be used, for example, to specify a custom DDK location. For details, see

> configure --help

Code-signing

The osslsigncode tool is used to sign OpenVPN installer, libraries and executables. SignTool is used to sign the TAP-drivers. Official OpenVPN releases will be signed with OpenVPN Technologies, Inc. code signing keys. However, it's fairly easy to build a custom version of OpenVPN and sign it with your own code-signing keys.

You need a recent version of osslsigncode (1.4+) for signing, although earlier versions can be used with minor modifications to the codesign() method in the scripts. More specifically, the assumption is that a pkcs12 keystore is used for signing, and osslsigncode 1.3 and earlier don't support pkcs12 yet. After fetching osslsigncode, make sure you have OpenSSL and Curl3 development libraries installed. On Ubuntu 12.04 you'd do

$ apt-get update
$ apt-get install libssl-dev libcurl4-openssl-dev

The latter is used for timestamping support. Extract the osslsigncode tarball and issue the usual commands:

$ ./configure
$ make
$ sudo make install

This will put osslsigncode in PATH where the build system can find it.

If you have code-signing certificates generated with MS tools (.spc and .pvk files), you can convert them into standard (pkcs12) format using this script. If that fails, look at this old version of this page for manual instructions.

You can also create self-signed certificate for testing like this:

$ openssl req -newkey rsa:1024 -new -x509 -subj "/CN=test1" -out test.crt	
$ openssl pkcs12 -export -inkey privkey.pem -in test.crt -out test.p12	

Once you have the pkcs12 archive, you can give it and it's password as argument to the buildsystem(s). For details, look here:

Making the release builds of OpenVPN

We've now described building the various components of OpenVPN in isolation. In this chapter we put all of it together.

Building signed Windows installers and executables

Building Windows executables and installers is one of the most painful parts of OpenVPN release process due to code-signing requirements etc. To generate universally useful installers you need the following:

  • Code-signing (=SPC) certificates
    • Kernel-mode code-signing certificate
    • CA's cross-certificate for kernel-mode code-signing
    • User-mode code-signing certificate (a.k.a. Microsoft Authenticode certificate)
  • A Windows build computer (for building and signing tap-windows)
  • *NIX build computer (for building and signing everything else)
  • Lots of patience

The build process is fairly straightforward:

  • Get the SPC certificates from a CA
  • Copy the kernel-mode and cross-certificates to the Windows build computer
  • Copy the user-mode code-signing certificate to the *NIX build computer
  • Generate an easy-rsa tarball and put it on a webserver
  • Generate an openvpn-gui tarball:
    • Clone the new openvpn-gui git repository
    • Run autoreconf -vi in the openvpn-gui directory
    • Append a version number to the directory name (e.g. "mv openvpn-gui openvpn-gui-1.0.6")
    • Tar and gzip the directory (e.g. "tar -zcf openvpn-gui-1.0.6.tar.gz openvpn-gui-1.0.6")
    • Put the resulting archive on a webserver
  • Build tap-windows and put the installer on a webserver
  • Setup openvpn-build/generic/build.vars to suit your needs:
    • dependency locations
    • build flags
  • Setup openvpn-build/windows-nsis/build-complete.vars to suit your needs:
    • easy-rsa tarball location
    • tap-windows installer location
  • Build the whole thing using openvpn-build/windows-nsis/build-complete
    • NOTE: build-snapshot is meant for building snapshots, not release packages

See corresponding sections for more detailed documentation.

External links

Official OpenVPN Git repositories

Unofficial Git repositores

Attachments (1)

Download all attachments as: .zip