INSTALL

   1 Installation instructions for OpenVPN, a Secure Tunneling Daemon
   2
   3 Copyright (C) 2002-2019 OpenVPN Inc. This program is free software;
   4 you can redistribute it and/or modify
   5 it under the terms of the GNU General Public License version 2
   6 as published by the Free Software Foundation.
   7
   8 *************************************************************************
   9
  10 QUICK START:
  11
  12   Unix:
  13     ./configure && make && make install
  14
  15 *************************************************************************
  16
  17 To download OpenVPN source code of releases, go to:
  18
  19     https://openvpn.net/community-downloads/
  20
  21 OpenVPN releases are also available as Debian/RPM packages:
  22
  23     https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos
  24
  25 OpenVPN development versions can be found here:
  26
  27    https://github.com/OpenVPN/openvpn
  28    https://gitlab.com/OpenVPN/openvpn
  29    https://sourceforge.net/p/openvpn/openvpn/ci/master/tree/
  30
  31 They should all be in sync at any time.
  32
  33 To download easy-rsa go to:
  34
  35     https://github.com/OpenVPN/easy-rsa
  36
  37 To download tap-windows (NDIS 6) driver source code go to:
  38
  39     https://github.com/OpenVPN/tap-windows6
  40
  41 To get the cross-compilation environment go to:
  42
  43     https://github.com/OpenVPN/openvpn-build
  44
  45 For step-by-step instructions with real-world examples see:
  46
  47     https://community.openvpn.net/openvpn/wiki/GettingStartedwithOVPN
  48     https://community.openvpn.net/openvpn/wiki
  49     https://openvpn.net/community-resources/
  50
  51 Also see the man page for more information.
  52
  53 *************************************************************************
  54
  55 SUPPORTED PLATFORMS:
  56   (1) Linux (kernel 2.6+)
  57   (2) Solaris
  58   (3) OpenBSD 5.1+
  59   (4) Mac OS X Darwin 10.5+
  60   (5) FreeBSD 7.4+
  61   (6) NetBSD 5.0+
  62   (7) Windows Vista or later for OpenVPN 2.4
  63   (8) Windows XP or later for OpenVPN 2.3
  64
  65 SUPPORTED PROCESSOR ARCHITECTURES:
  66    In general, OpenVPN is word size and endian independent, so
  67    most processors should be supported.  Architectures known to
  68    work include Intel x86, Alpha, Sparc, Amd64, and ARM.
  69
  70 REQUIRES:
  71   (1) TUN and/or TAP driver to allow user-space programs to control
  72       a virtual point-to-point IP or Ethernet device.  See
  73       TUN/TAP Driver Configuration section below for more info.
  74
  75 OPTIONAL (but recommended):
  76   (1) OpenSSL library, necessary for encryption, version 1.0.1 or higher
  77       required, available from http://www.openssl.org/
  78   (2) mbed TLS library, an alternative for encryption, version 2.0 or higher
  79       required, available from https://tls.mbed.org/
  80   (3) LZO real-time compression library, required for link compression,
  81       available from http://www.oberhumer.com/opensource/lzo/
  82       OpenBSD users can use ports or packages to install lzo, but remember
  83       to add CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
  84       directives to "configure", since gcc will not find them otherwise.
  85
  86 OPTIONAL (for developers only):
  87   (1) Autoconf 2.59 or higher + Automake 1.9 or higher
  88       -- available from http://www.gnu.org/software/software.html
  89   (2) Dmalloc library
  90       -- available from http://dmalloc.com/
  91   (3) If using t_client.sh test framework, fping/fping6 is needed
  92       -- Available from http://www.fping.org/
  93       Note: t_client.sh needs an external configured OpenVPN server.
  94       See t_client.rc-sample for more info.
  95
  96 *************************************************************************
  97
  98 CHECK OUT SOURCE FROM SOURCE REPOSITORY:
  99
 100   Clone the repository:
 101
 102     git clone https://github.com/OpenVPN/openvpn
 103     git clone https://gitlab.com/OpenVPN/openvpn
 104     git clone git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn
 105
 106   Check out stable version:
 107
 108     git checkout release/2.4
 109
 110   Check out master (unstable) branch:
 111
 112     git checkout master
 113
 114
 115 *************************************************************************
 116
 117 BUILD COMMANDS FROM TARBALL:
 118
 119         ./configure
 120         make
 121         make install
 122
 123 *************************************************************************
 124
 125 BUILD COMMANDS FROM SOURCE REPOSITORY CHECKOUT:
 126
 127         autoreconf -i -v -f
 128         ./configure
 129         make
 130         make install
 131
 132 *************************************************************************
 133
 134 BUILD A TARBALL FROM SOURCE REPOSITORY CHECKOUT:
 135
 136         autoreconf -i -v -f
 137         ./configure
 138         make distcheck
 139
 140 *************************************************************************
 141
 142 TESTS (after BUILD):
 143
 144 make check (Run all tests below)
 145
 146 Test Crypto:
 147
 148 ./openvpn --genkey secret key
 149 ./openvpn --test-crypto --secret key
 150
 151 Test SSL/TLS negotiations (runs for 2 minutes):
 152
 153 ./openvpn --config sample/sample-config-files/loopback-client (In one window)
 154 ./openvpn --config sample/sample-config-files/loopback-server (Simultaneously in another window)
 155
 156 For more thorough client-server tests you can configure your own, private test
 157 environment. See tests/t_client.rc-sample for details.
 158
 159 To do the C unit tests, you need to have the "cmocka" test framework
 160 installed on your system.  More recent distributions already ship this
 161 as part of their packages/ports.  If your system does not have it,
 162 you can install cmocka with these commands:
 163
 164   $ git clone https://git.cryptomilk.org/projects/cmocka.git
 165   $ cd cmocka
 166   $ mkdir build
 167   $ cd build
 168   $ cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Debug ..
 169   $ make
 170   $ sudo make install
 171
 172
 173 *************************************************************************
 174
 175 OPTIONS for ./configure:
 176
 177   --disable-lzo           disable LZO compression support [default=yes]
 178   --disable-lz4           Disable LZ4 compression support
 179   --enable-comp-stub      Don't compile compression support but still allow limited interoperability with compression-enabled peers
 180   --disable-crypto        disable crypto support [default=yes]
 181   --disable-ofb-cfb       disable support for OFB and CFB cipher modes
 182                           [default=yes]
 183   --enable-x509-alt-username
 184                           enable the --x509-username-field feature
 185                           [default=no]
 186   --disable-server        disable server support only (but retain client
 187                           support) [default=yes]
 188   --disable-plugins       disable plug-in support [default=yes]
 189   --disable-management    disable management server support [default=yes]
 190   --enable-pkcs11         enable pkcs11 support [default=no]
 191   --disable-fragment      disable internal fragmentation support (--fragment)
 192                           [default=yes]
 193   --disable-multihome     disable multi-homed UDP server support (--multihome)
 194                           [default=yes]
 195   --disable-port-share    disable TCP server port-share support (--port-share)
 196                           [default=yes]
 197   --disable-debug         disable debugging support (disable gremlin and verb
 198                           7+ messages) [default=yes]
 199   --enable-small          enable smaller executable size (disable OCC, usage
 200                           message, and verb 4 parm list) [default=no]
 201   --enable-iproute2       enable support for iproute2 [default=no]
 202   --disable-def-auth      disable deferred authentication [default=yes]
 203   --disable-pf            disable internal packet filter [default=yes]
 204   --disable-plugin-auth-pam
 205                           disable auth-pam plugin [default=platform specific]
 206   --disable-plugin-down-root
 207                           disable down-root plugin [default=platform specific]
 208   --enable-pam-dlopen     dlopen libpam [default=no]
 209   --enable-strict         enable strict compiler warnings (debugging option)
 210                           [default=no]
 211   --enable-pedantic       enable pedantic compiler warnings, will not generate
 212                           a working executable (debugging option) [default=no]
 213   --enable-werror         promote compiler warnings to errors, will cause
 214                           builds to fail if the compiler issues warnings
 215                           (debugging option) [default=no]
 216   --enable-strict-options enable strict options check between peers (debugging
 217                           option) [default=no]
 218   --enable-selinux        enable SELinux support [default=no]
 219   --enable-systemd        enable systemd support [default=no]
 220   --enable-async-push     enable async-push support for plugins providing
 221                           deferred authentication [default=no]
 222
 223 ENVIRONMENT for ./configure:
 224
 225   PLUGINDIR   Path of plug-in directory [default=LIBDIR/openvpn/plugins]
 226   IFCONFIG    full path to ipconfig utility
 227   ROUTE       full path to route utility
 228   IPROUTE     full path to ip utility
 229   NETSTAT     path to netstat utility
 230   MAN2HTML    path to man2html utility
 231   GIT         path to git utility
 232   SYSTEMD_ASK_PASSWORD
 233               path to systemd-ask-password utility
 234   SYSTEMD_UNIT_DIR
 235               Path of systemd unit directory [default=LIBDIR/systemd/system]
 236   TMPFILES_DIR
 237               Path of tmpfiles directory [default=LIBDIR/tmpfiles.d]
 238
 239 ENVIRONMENT variables adjusting parameters related to dependencies
 240
 241   TAP_CFLAGS  C compiler flags for tap
 242   LIBPAM_CFLAGS
 243               C compiler flags for libpam
 244   LIBPAM_LIBS linker flags for libpam
 245   PKCS11_HELPER_CFLAGS
 246               C compiler flags for PKCS11_HELPER, overriding pkg-config
 247   PKCS11_HELPER_LIBS
 248               linker flags for PKCS11_HELPER, overriding pkg-config
 249   OPENSSL_CFLAGS
 250               C compiler flags for OpenSSL
 251   OPENSSL_LIBS
 252               linker flags for OpenSSL
 253   MBEDTLS_CFLAGS
 254               C compiler flags for mbedtls
 255   MBEDTLS_LIBS
 256               linker flags for mbedtls
 257   LZO_CFLAGS  C compiler flags for lzo
 258   LZO_LIBS    linker flags for lzo
 259   LZ4_CFLAGS  C compiler flags for lz4
 260   LZ4_LIBS    linker flags for lz4
 261   libsystemd_CFLAGS
 262               C compiler flags for libsystemd, overriding pkg-config
 263   libsystemd_LIBS
 264               linker flags for libsystemd, overriding pkg-config
 265   P11KIT_CFLAGS
 266               C compiler flags for P11KIT, overriding pkg-config
 267   P11KIT_LIBS linker flags for P11KIT, overriding pkg-config
 268
 269 *************************************************************************
 270
 271 Linux distribution packaging:
 272
 273 Each Linux distribution has their own way of doing packaging and their
 274 own set of guidelines of how proper packaging should be done.  It
 275 is therefore recommended to reach out to the Linux distributions you
 276 want to have OpenVPN packaged for directly.  The OpenVPN project wants
 277 to focus more on the OpenVPN development and less on the packaging
 278 and how packaging is done in all various distributions.
 279
 280 For more details:
 281
 282 * Arch Linux
 283   https://www.archlinux.org/packages/?name=openvpn
 284
 285 * Debian
 286   https://packages.debian.org/search?keywords=openvpn&searchon=names
 287   https://tracker.debian.org/pkg/openvpn
 288
 289 * Fedora / Fedora EPEL (Red Hat Enterprise Linux/CentOS/Scientific Linux)
 290   https://apps.fedoraproject.org/packages/openvpn/overview/
 291   https://src.fedoraproject.org/rpms/openvpn
 292
 293 * Gentoo
 294   https://packages.gentoo.org/packages/net-vpn/openvpn
 295   https://gitweb.gentoo.org/repo/gentoo.git/tree/net-vpn/openvpn
 296
 297 * openSUSE
 298   https://build.opensuse.org/package/show/network:vpn/openvpn
 299
 300 * Ubuntu
 301   https://packages.ubuntu.com/search?keywords=openvpn
 302
 303 In addition, the OpenVPN community provides a best-effort APT repository
 304 for Debian and Ubuntu:
 305 https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos
 306
 307 *************************************************************************
 308
 309 TUN/TAP Driver Configuration:
 310
 311 * Linux 2.6 or higher (with integrated TUN/TAP driver):
 312
 313   (1) load driver:              modprobe tun
 314   (2) enable routing:           echo 1 > /proc/sys/net/ipv4/ip_forward
 315
 316   Note that (1) needs to be done once per reboot.  If you install from RPM (see
 317   above) and use the openvpn.init script, these steps are taken care of for you.
 318
 319 * FreeBSD:
 320
 321   FreeBSD ships with the TUN/TAP driver, and the device nodes for tap0,
 322   tap1, tap2, tap3, tun0, tun1, tun2 and tun3 are made by default.
 323   However, only the TUN driver is linked into the GENERIC kernel.
 324
 325   To load the TAP driver, enter:
 326
 327         kldload if_tap
 328
 329   See man rc(8) to find out how you can do this at boot time.
 330
 331   The easiest way is to install OpenVPN from the FreeBSD ports system,
 332   the port includes a sample script to automatically load the TAP driver
 333   at boot-up time.
 334
 335 * OpenBSD:
 336
 337   OpenBSD has dynamically created tun* devices so you only need
 338   to create an empty /etc/hostname.tun0 (tun1, tun2 and so on) for each tun
 339   you plan to use to create the device(s) at boot.
 340
 341 * Solaris:
 342
 343   You need a TUN/TAP kernel driver for OpenVPN to work:
 344
 345     http://www.whiteboard.ne.jp/~admin2/tuntap/
 346
 347 * Windows
 348
 349   OpenVPN on Windows needs a TUN/TAP kernel driver to work. OpenVPN installers
 350   include this driver, so installing it separately is not usually required.
 351   Windows XP/2003 must use the NDIS 5 (tap-windows) driver, whereas on more
 352   recent Windows versions it is recommended to use the NDIS 6 driver
 353   (tap-windows6) instead.
 354
 355 *************************************************************************
 356
 357 CAVEATS & BUGS:
 358
 359 * I have noticed cases where TCP sessions tunneled over the Linux
 360   TAP driver (kernel 2.4.21 and 2.4.22) stall when lower --mssfix
 361   values are used.  The TCP sessions appear to unstall and resume
 362   normally when the remote VPN endpoint is pinged.
 363
 364 * If run through a firewall using OpenBSDs packet filter PF and the
 365   filter rules include a "scrub" directive, you may get problems talking
 366   to Linux hosts over the tunnel, since the scrubbing will kill packets
 367   sent from Linux hosts if they are fragmented. This is usually seen as
 368   tunnels where small packets and pings get through but large packets
 369   and "regular traffic" don't. To circumvent this, add "no-df" to
 370   the scrub directive so that the packet filter will let fragments with
 371   the "dont fragment"-flag set through anyway.
 372
 373 * Mixing OFB or CFB cipher modes with static key mode is not recommended,
 374   and is flagged as an error on OpenVPN versions 1.2.1 and greater.
 375   If you use the --cipher option to explicitly select an OFB or CFB
 376   cipher AND you are using static key mode, it is possible that there
 377   could be an IV collision if the OpenVPN daemons on both sides
 378   of the connection are started at exactly the same time, since
 379   OpenVPN uses a timestamp combined with a sequence number as the cipher
 380   IV for OFB and CFB modes.  This is not an issue if you are
 381   using CBC cipher mode (the default), or if you are using OFB or CFB
 382   cipher mode with SSL/TLS authentication.