release/src/router/openvpn/INSTALL

   1 Installation instructions for OpenVPN, a Secure Tunneling Daemon
   2
   3 Copyright (C) 2002-2010 OpenVPN Technologies, 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   Cross-compile for Windows on Unix
  16
  17     See INSTALL-win32.txt
  18
  19   Compile OpenVPN with OpenSSL/LZO built from source tarballs
  20
  21     See INSTALL-nonstandard.txt
  22
  23 *************************************************************************
  24
  25 To download OpenVPN, go to:
  26
  27     http://openvpn.net/download.html
  28
  29 OpenVPN releases are also available as Debian/RPM packages:
  30
  31     https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos
  32
  33 To download easy-rsa go to:
  34
  35     https://github.com/OpenVPN/easy-rsa
  36
  37 To download tap-windows driver source code go to:
  38
  39     https://github.com/OpenVPN/tap-windows
  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     http://openvpn.net/howto.html
  48     https://community.openvpn.net/openvpn/wiki
  49
  50 For examples see:
  51
  52     http://openvpn.net/examples.html
  53
  54 Also see the man page for more information, usage examples, and information on
  55 firewall configuration.
  56
  57 *************************************************************************
  58
  59 SUPPORTED PLATFORMS:
  60   (1) Linux (kernel 2.6+)
  61   (2) Solaris
  62   (3) OpenBSD 5.1+
  63   (4) Mac OS X Darwin 10.5+
  64   (5) FreeBSD 7.4+
  65   (6) NetBSD 5.0+
  66   (7) Windows (WinXP and higher)
  67
  68 SUPPORTED PROCESSOR ARCHITECTURES:
  69    In general, OpenVPN is word size and endian independent, so
  70    most processors should be supported.  Architectures known to
  71    work include Intel x86, Alpha, Sparc, Amd64, and ARM.
  72
  73 REQUIRES:
  74   (1) TUN and/or TAP driver to allow user-space programs to control
  75       a virtual point-to-point IP or Ethernet device.  See
  76       TUN/TAP Driver Configuration section below for more info.
  77
  78   (2) PAM/PAM-Devel (Pluggable Authentication Modules).  In most
  79       Linux distributions, these packages are usually listed as
  80       the following (here is what they look like on Fedora):
  81
  82       pam-1.1.8-18.fc22.x86_64.rpm (64-bit package)
  83       pam-devel-1.1.8-18.fc.22.x86_64.rpm (64-bit package)
  84
  85 OPTIONAL (but recommended):
  86   (1) OpenSSL library, necessary for encryption, version 0.9.8 or higher
  87       required, available from http://www.openssl.org/.  If you build
  88       OpenSSL from source tarball, you will need to let OpenVPN-2.3.x
  89       know where the libraries and header files were installed to:
  90
  91       If you configured OpenSSL with stock options, it will install
  92       the headers (i.e. - .h files) in /usr/local/ssl/include and
  93       the libraries (i.e. - .a or .so files) in /usr/local/ssl/lib/openssl
  94
  95   (2) PolarSSL library, an alternative for encryption, version 1.1 or higher
  96       required, available from https://polarssl.org/
  97
  98   (3) LZO real-time compression library, required for link compression,
  99       available from http://www.oberhumer.com/opensource/lzo/
 100       OpenBSD users can use ports or packages to install lzo, but remember
 101       to add CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
 102       directives to "configure", since gcc will not find them otherwise.
 103
 104 OPTIONAL (for developers only):
 105   (1) Autoconf 2.59 or higher + Automake 1.9 or higher
 106       -- available from http://www.gnu.org/software/software.html
 107   (2) Dmalloc library
 108       -- available from http://dmalloc.com/
 109
 110 *************************************************************************
 111
 112 CHECK OUT SOURCE FROM SOURCE REPOSITORY:
 113
 114   Clone the repository:
 115
 116     git clone https://github.com/OpenVPN/openvpn
 117     git clone git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn
 118
 119   Check out stable version:
 120
 121     git checkout -b 2.2 remotes/origin/release/2.2
 122
 123   Check out master (unstable) branch:
 124
 125     git checkout master
 126
 127
 128 *************************************************************************
 129
 130 BUILD COMMANDS FROM TARBALL:
 131
 132         ./configure
 133         make
 134         make install
 135
 136 *************************************************************************
 137
 138 BUILD COMMANDS FROM SOURCE REPOSITORY CHECKOUT:
 139
 140         autoreconf -i -v -f
 141         ./configure
 142         make
 143         make install
 144
 145 *************************************************************************
 146
 147 BUILD A TARBALL FROM SOURCE REPOSITORY CHECKOUT:
 148
 149         autoreconf -i -v -f
 150         ./configure
 151         make dist
 152
 153 *************************************************************************
 154
 155 TESTS (after BUILD):
 156
 157 make check (Run all tests below)
 158
 159 Test Crypto:
 160
 161 ./openvpn --genkey --secret key
 162 ./openvpn --test-crypto --secret key
 163
 164 Test SSL/TLS negotiations (runs for 2 minutes):
 165
 166 ./openvpn --config sample/sample-config-files/loopback-client (In one window)
 167 ./openvpn --config sample/sample-config-files/loopback-server (Simultaneously in another window)
 168
 169 For more thorough client-server tests you can configure your own, private test
 170 environment. See tests/t_client.rc-sample for details.
 171
 172 *************************************************************************
 173
 174 OPTIONS for ./configure:
 175
 176   --disable-lzo           disable LZO compression support [default=yes]
 177   --enable-lzo-stub       don't compile LZO compression support but still
 178                           allow limited interoperability with LZO-enabled
 179                           peers [default=no]
 180   --disable-crypto        disable crypto support [default=yes]
 181   --disable-ssl           disable SSL support for TLS-based key exchange
 182                           [default=yes]
 183   --enable-x509-alt-username
 184                           enable the --x509-username-field feature
 185                           [default=no]
 186   --disable-multi         disable client/server support (--mode server +
 187                           client mode) [default=yes]
 188   --disable-server        disable server support only (but retain client
 189                           support) [default=yes]
 190   --disable-plugins       disable plug-in support [default=yes]
 191   --disable-management    disable management server support [default=yes]
 192   --enable-pkcs11         enable pkcs11 support [default=no]
 193   --disable-socks         disable Socks support [default=yes]
 194   --disable-http-proxy    disable HTTP proxy support [default=yes]
 195   --disable-fragment      disable internal fragmentation support (--fragment)
 196                           [default=yes]
 197   --disable-multihome     disable multi-homed UDP server support (--multihome)
 198                           [default=yes]
 199   --disable-port-share    disable TCP server port-share support (--port-share)
 200                           [default=yes]
 201   --disable-debug         disable debugging support (disable gremlin and verb
 202                           7+ messages) [default=yes]
 203   --enable-small          enable smaller executable size (disable OCC, usage
 204                           message, and verb 4 parm list) [default=yes]
 205   --enable-password-save  allow --askpass and --auth-user-pass passwords to be
 206                           read from a file [default=yes]
 207   --enable-iproute2       enable support for iproute2 [default=no]
 208   --disable-def-auth      disable deferred authentication [default=yes]
 209   --disable-pf            disable internal packet filter [default=yes]
 210   --enable-strict         enable strict compiler warnings (debugging option)
 211                           [default=no]
 212   --enable-pedantic       enable pedantic compiler warnings, will not generate
 213                           a working executable (debugging option) [default=no]
 214   --enable-strict-options enable strict options check between peers (debugging
 215                           option) [default=no]
 216   --enable-selinux        enable SELinux support [default=no]
 217   --enable-systemd        enable systemd suppport [default=no]
 218
 219 ENVIRONMENT for ./configure:
 220
 221   IFCONFIG    full path to ipconfig utility
 222   ROUTE       full path to route utility
 223   IPROUTE     full path to ip utility
 224   NETSTAT     path to netstat utility
 225   MAN2HTML    path to man2html utility
 226   GIT         path to git utility
 227   TAP_CFLAGS  C compiler flags for tap
 228   OPENSSL_CRYPTO_CFLAGS
 229               C compiler flags for OPENSSL_CRYPTO, overriding pkg-config
 230   OPENSSL_CRYPTO_LIBS
 231               linker flags for OPENSSL_CRYPTO, overriding pkg-config
 232   OPENSSL_SSL_CFLAGS
 233               C compiler flags for OPENSSL_SSL, overriding pkg-config
 234   OPENSSL_SSL_LIBS
 235               linker flags for OPENSSL_SSL, overriding pkg-config
 236   POLARSSL_CFLAGS
 237               C compiler flags for polarssl
 238   POLARSSL_LIBS
 239               linker flags for polarssl
 240   LZO_CFLAGS  C compiler flags for lzo
 241   LZO_LIBS    linker flags for lzo
 242   PKCS11_HELPER_CFLAGS
 243               C compiler flags for PKCS11_HELPER, overriding pkg-config
 244   PKCS11_HELPER_LIBS
 245               linker flags for PKCS11_HELPER, overriding pkg-config
 246
 247 *************************************************************************
 248
 249 BUILDING ON LINUX 2.6+ FROM RPM
 250
 251 You can build a binary RPM directly from the OpenVPN tarball file:
 252
 253         rpmbuild -tb [tarball]
 254
 255 This command will build a binary RPM file and place it in the system
 256 RPM directory.  You can then install the RPM with the standard RPM
 257 install command:
 258
 259         rpm -ivh [binary-rpm]
 260
 261 When you install the binary RPM, it will install
 262 sample-scripts/openvpn.init, which can be used to
 263 automatically start or stop one or more OpenVPN tunnels on system
 264 startup or shutdown, based on OpenVPN .conf files in /etc/openvpn.
 265 See the comments in openvpn.init for more information.
 266
 267 Installing the RPM will also configure the TUN/TAP device node
 268 for linux 2.6.
 269
 270 Note that the current openvpn.spec file, which instructs the rpm tool
 271 how to build a package, will build OpenVPN with all options enabled,
 272 including OpenSSL, LZO, and pthread linkage.  Therefore all of
 273 these packages will need to be present prior to the RPM build, unless
 274 you edit the openvpn.spec file.
 275
 276 *************************************************************************
 277
 278 TUN/TAP Driver Configuration:
 279
 280 * Linux 2.6 or higher (with integrated TUN/TAP driver):
 281
 282   (1) load driver:              modprobe tun
 283   (2) enable routing:           echo 1 > /proc/sys/net/ipv4/ip_forward
 284
 285   Note that (1) needs to be done once per reboot.  If you install from RPM (see
 286   above) and use the openvpn.init script, these steps are taken care of for you.
 287
 288 * FreeBSD:
 289
 290   FreeBSD ships with the TUN/TAP driver, and the device nodes for tap0,
 291   tap1, tap2, tap3, tun0, tun1, tun2 and tun3 are made by default.
 292   However, only the TUN driver is linked into the GENERIC kernel.
 293
 294   To load the TAP driver, enter:
 295
 296         kldload if_tap
 297
 298   See man rc(8) to find out how you can do this at boot time.
 299
 300   The easiest way is to install OpenVPN from the FreeBSD ports system,
 301   the port includes a sample script to automatically load the TAP driver
 302   at boot-up time.
 303
 304 * OpenBSD:
 305
 306   OpenBSD has dynamically created tun* devices so you only need
 307   to create an empty /etc/hostname.tun0 (tun1, tun2 and so on) for each tun
 308   you plan to use to create the device(s) at boot.
 309
 310 * Solaris:
 311
 312   You need a TUN/TAP kernel driver for OpenVPN to work:
 313
 314     http://www.whiteboard.ne.jp/~admin2/tuntap/
 315
 316 * Windows XP/2003/Vista/7:
 317
 318   OpenVPN on Windows needs a TUN/TAP kernel driver to work. OpenVPN installers
 319   include this driver, so installing it separately is not usually required.
 320   The driver source code is available here:
 321
 322     https://github.com/OpenVPN/tap-windows
 323
 324 *************************************************************************
 325
 326 CAVEATS & BUGS:
 327
 328 * I have noticed cases where TCP sessions tunneled over the Linux
 329   TAP driver (kernel 2.4.21 and 2.4.22) stall when lower --mssfix
 330   values are used.  The TCP sessions appear to unstall and resume
 331   normally when the remote VPN endpoint is pinged.
 332
 333 * If run through a firewall using OpenBSDs packet filter PF and the
 334   filter rules include a "scrub" directive, you may get problems talking
 335   to Linux hosts over the tunnel, since the scrubbing will kill packets
 336   sent from Linux hosts if they are fragmented. This is usually seen as
 337   tunnels where small packets and pings get through but large packets
 338   and "regular traffic" don't. To circumvent this, add "no-df" to
 339   the scrub directive so that the packet filter will let fragments with
 340   the "dont fragment"-flag set through anyway.
 341
 342 * Mixing OFB or CFB cipher modes with static key mode is not recommended,
 343   and is flagged as an error on OpenVPN versions 1.2.1 and greater.
 344   If you use the --cipher option to explicitly select an OFB or CFB
 345   cipher AND you are using static key mode, it is possible that there
 346   could be an IV collision if the OpenVPN daemons on both sides
 347   of the connection are started at exactly the same time, since
 348   OpenVPN uses a timestamp combined with a sequence number as the cipher
 349   IV for OFB and CFB modes.  This is not an issue if you are
 350   using CBC cipher mode (the default), or if you are using OFB or CFB
 351   cipher mode with SSL/TLS authentication.