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   Windows MinGW, using MSYS bash shell:
  16     ./domake-win (see comments in the script for more info)
  17
  18   Windows Visual Studio:
  19     python win\build_all.py
  20
  21 *************************************************************************
  22
  23 To download OpenVPN, go to:
  24
  25         http://openvpn.net/download.html
  26
  27 For step-by-step installation instructions with real-world
  28 examples see:
  29
  30         http://openvpn.net/howto.html
  31
  32 For examples see:
  33
  34         http://openvpn.net/examples.html
  35
  36 *************************************************************************
  37
  38 SUPPORTED PLATFORMS:
  39   (1) Linux 2.2+
  40   (2) Solaris
  41   (3) OpenBSD 3.0+ (Comes with OpenSSL and TUN devices by default)
  42   (4) Mac OS X Darwin
  43   (5) FreeBSD
  44   (6) NetBSD
  45   (7) Windows (WinXP and higher)
  46
  47 SUPPORTED PROCESSOR ARCHITECTURES:
  48    In general, OpenVPN is word size and endian independent, so
  49    most processors should be supported.  Architectures known to
  50    work include Intel x86, Alpha, Sparc, Amd64, and ARM.
  51
  52 REQUIRES:
  53   (1) TUN and/or TAP driver to allow user-space programs to control
  54       a virtual point-to-point IP or Ethernet device.  See
  55       TUN/TAP Driver Configuration section below for more info.
  56
  57 OPTIONAL (but recommended):
  58   (1) OpenSSL library, necessary for encryption, version 0.9.5 or higher
  59       required, available from http://www.openssl.org/
  60   (2) LZO real-time compression library, required for link compression,
  61       available from http://www.oberhumer.com/opensource/lzo/
  62       OpenBSD users can use ports or packages to install lzo, but remember
  63       to add CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
  64       directives to "configure", since gcc will not find them otherwise.
  65   (3) Pthread library.
  66
  67 OPTIONAL (for developers only):
  68   (1) Autoconf 2.59 or higher + Automake 1.9 or higher
  69       -- available from http://www.gnu.org/software/software.html
  70   (2) Dmalloc library
  71       -- available from http://dmalloc.com/
  72
  73 *************************************************************************
  74
  75 CHECK OUT SOURCE FROM SOURCE REPOSITORY:
  76
  77   git clone https://github.com/OpenVPN/openvpn
  78
  79   Check out stable version:
  80
  81   git checkout -b 2.2 remotes/origin/release/2.2
  82
  83   Check out master (unstable) branch:
  84
  85   git checkout master
  86
  87
  88 *************************************************************************
  89
  90 BUILD COMMANDS FROM TARBALL:
  91
  92         ./configure
  93         make
  94         make install
  95
  96 *************************************************************************
  97
  98 BUILD COMMANDS FROM SOURCE REPOSITORY CHECKOUT:
  99
 100         autoreconf -i -v -f
 101         ./configure
 102         make
 103         make install
 104
 105 *************************************************************************
 106
 107 BUILD A TARBALL FROM SOURCE REPOSITORY CHECKOUT:
 108
 109         autoreconf -i -v -f
 110         ./configure
 111         make dist
 112
 113 *************************************************************************
 114
 115 LOOPBACK TESTS (after BUILD):
 116
 117 make check (Run all tests below)
 118
 119 Test Crypto:
 120
 121 ./openvpn --genkey --secret key
 122 ./openvpn --test-crypto --secret key
 123
 124 Test SSL/TLS negotiations (runs for 2 minutes):
 125
 126 ./openvpn --config sample/sample-config-files/loopback-client (In one window)
 127 ./openvpn --config sample/sample-config-files/loopback-server (Simultaneously in another window)
 128
 129 *************************************************************************
 130
 131 OPTIONS for ./configure:
 132
 133   --disable-lzo           disable LZO compression support [default=yes]
 134   --enable-lzo-stub       don't compile LZO compression support but still
 135                           allow limited interoperability with LZO-enabled
 136                           peers [default=no]
 137   --disable-crypto        disable crypto support [default=yes]
 138   --disable-ssl           disable SSL support for TLS-based key exchange
 139                           [default=yes]
 140   --enable-x509-alt-username
 141                           enable the --x509-username-field feature
 142                           [default=no]
 143   --disable-multi         disable client/server support (--mode server +
 144                           client mode) [default=yes]
 145   --disable-server        disable server support only (but retain client
 146                           support) [default=yes]
 147   --disable-plugins       disable plug-in support [default=yes]
 148   --disable-eurephia      disable support for the eurephia plug-in
 149                           [default=yes]
 150   --disable-management    disable management server support [default=yes]
 151   --enable-pkcs11         enable pkcs11 support [default=no]
 152   --disable-socks         disable Socks support [default=yes]
 153   --disable-http-proxy    disable HTTP proxy support [default=yes]
 154   --disable-fragment      disable internal fragmentation support (--fragment)
 155                           [default=yes]
 156   --disable-multihome     disable multi-homed UDP server support (--multihome)
 157                           [default=yes]
 158   --disable-port-share    disable TCP server port-share support (--port-share)
 159                           [default=yes]
 160   --disable-debug         disable debugging support (disable gremlin and verb
 161                           7+ messages) [default=yes]
 162   --enable-small          enable smaller executable size (disable OCC, usage
 163                           message, and verb 4 parm list) [default=yes]
 164   --enable-password-save  allow --askpass and --auth-user-pass passwords to be
 165                           read from a file [default=yes]
 166   --enable-iproute2       enable support for iproute2 [default=no]
 167   --disable-def-auth      disable deferred authentication [default=yes]
 168   --disable-pf            disable internal packet filter [default=yes]
 169   --enable-strict         enable strict compiler warnings (debugging option)
 170                           [default=no]
 171   --enable-pedantic       enable pedantic compiler warnings, will not generate
 172                           a working executable (debugging option) [default=no]
 173   --enable-strict-options enable strict options check between peers (debugging
 174                           option) [default=no]
 175   --enable-selinux        enable SELinux support [default=no]
 176   --enable-systemd        enable systemd suppport [default=no]
 177
 178 ENVIRONMENT for ./configure:
 179
 180   IFCONFIG    full path to ipconfig utility
 181   ROUTE       full path to route utility
 182   IPROUTE     full path to ip utility
 183   NETSTAT     path to netstat utility
 184   MAN2HTML    path to man2html utility
 185   GIT         path to git utility
 186   TAP_CFLAGS  C compiler flags for tap
 187   OPENSSL_CRYPTO_CFLAGS
 188               C compiler flags for OPENSSL_CRYPTO, overriding pkg-config
 189   OPENSSL_CRYPTO_LIBS
 190               linker flags for OPENSSL_CRYPTO, overriding pkg-config
 191   OPENSSL_SSL_CFLAGS
 192               C compiler flags for OPENSSL_SSL, overriding pkg-config
 193   OPENSSL_SSL_LIBS
 194               linker flags for OPENSSL_SSL, overriding pkg-config
 195   POLARSSL_CFLAGS
 196               C compiler flags for polarssl
 197   POLARSSL_LIBS
 198               linker flags for polarssl
 199   LZO_CFLAGS  C compiler flags for lzo
 200   LZO_LIBS    linker flags for lzo
 201   PKCS11_HELPER_CFLAGS
 202               C compiler flags for PKCS11_HELPER, overriding pkg-config
 203   PKCS11_HELPER_LIBS
 204               linker flags for PKCS11_HELPER, overriding pkg-config
 205
 206 *************************************************************************
 207
 208 BUILDING ON LINUX 2.4+ FROM RPM
 209
 210 You can build a binary RPM directly from the OpenVPN tarball file:
 211
 212         rpmbuild -tb [tarball]
 213
 214 This command will build a binary RPM file and place it in the system
 215 RPM directory.  You can then install the RPM with the standard RPM
 216 install command:
 217
 218         rpm -ivh [binary-rpm]
 219
 220 When you install the binary RPM, it will install
 221 sample-scripts/openvpn.init, which can be used to
 222 automatically start or stop one or more OpenVPN tunnels on system
 223 startup or shutdown, based on OpenVPN .conf files in /etc/openvpn.
 224 See the comments in openvpn.init for more information.
 225
 226 Installing the RPM will also configure the TUN/TAP device node
 227 for linux 2.4.
 228
 229 Note that the current openvpn.spec file, which instructs the rpm tool
 230 how to build a package, will build OpenVPN with all options enabled,
 231 including OpenSSL, LZO, and pthread linkage.  Therefore all of
 232 these packages will need to be present prior to the RPM build, unless
 233 you edit the openvpn.spec file.
 234
 235 *************************************************************************
 236
 237 TUN/TAP Driver Configuration:
 238
 239 * Linux 2.4 or higher (with integrated TUN/TAP driver):
 240
 241   (1)  make device node:         mknod /dev/net/tun c 10 200
 242   (2a) add to /etc/modules.conf: alias char-major-10-200 tun
 243   (2b) load driver:              modprobe tun
 244   (3)  enable routing:           echo 1 > /proc/sys/net/ipv4/ip_forward
 245
 246   Note that either of steps (2a) or (2b) is sufficient.  While (2a)
 247   only needs to be done once per install, (2b) needs to be done once
 248   per reboot.  If you install from RPM (see above) and use the
 249   openvpn.init script, these steps are taken care of for you.
 250
 251 * Linux 2.2 or Solaris:
 252
 253   You should obtain
 254   version 1.1 of the TUN/TAP driver from
 255   http://vtun.sourceforge.net/tun/
 256   and follow the installation instructions.
 257
 258   If you use OpenVPN on Linux 2.2 or 2.4 or Solaris, you may be
 259   suffering from a bug which causes connections to hang under heavy load.
 260   The symptoms are very similar to the MTU problems discussed frequently
 261   in the OpenVPN mailing lists. But it turns out that this bug is not caused by
 262   MTU problems. It's a bug in the tun/tap driver.  A patch is provided here:
 263
 264   http://openvpn.net/patch/tun-sb.patch
 265
 266 * Solaris
 267
 268   For 64 bit, I used the tun-1.1.tar.gz source and compiled it.
 269
 270   Of course there is a but :)
 271   In the tun-1-1\solaris\Makefile I changed a line so it compiles with 64 bit
 272
 273   CFLAGS = $(DEFS) -m64 -O2 -Wall -D_KERNEL -I.
 274
 275   I just added -m64 and it worked.
 276
 277   The tun driver works fine as said previously, however we noticed there is a
 278   minor problem when creating multiple tunnels on Solaris.
 279   Mr Tycho Fruru changed the code in tun.c file where he locked the tun device
 280   number to -1. This way it is impossible to specify the name of the tun device
 281   but it is still possible to have multiple devices.
 282   The modification will increment automatically meaning starting from tun0 --->
 283   tunX I know you are not responsible for the tun coding but if you think the
 284   modification can be useful for you feel free to use it.
 285
 286   http://openvpn.net/solaris/tun.c
 287
 288 * FreeBSD 4.1.1+:
 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 ships with tun0 and tun1 installed by default on pre-3.5 systems,
 307   while 3.5 and later have dynamically created tun* devices so you only need
 308   to create an empty /etc/hostname.tun0 (tun1, tun2 and so on) for each tun
 309   you plan to use to create the device(s) at boot.
 310
 311 * Mac OS X:
 312
 313   2005.02.13: Angelo Laub has developed a GUI for OS X:
 314
 315   http://rechenknecht.net/OpenVPN-GUI/
 316
 317   2004.10.26: Mattias Nissler has developed a new TUN/TAP driver for
 318   MAC OS X:
 319
 320   http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
 321
 322   Christoph Pfisterer's old TUN driver can be obtained at
 323   http://chrisp.de/en/projects/tunnel.html -- note that it
 324   is no longer being maintained.
 325
 326 * Solaris9 Sparc/64
 327
 328   The kernel module for solaris
 329   can be generated by adding the -m64 switch to a modern
 330   gcc compiler (I'm using 3.2)  The resulting kernel driver
 331   needs to be manually copied to /kernel/drv/sparcv9/ and then a
 332   reconfiguration reboot. (boot -r).
 333
 334 * Windows XP/2003/Vista
 335
 336   See domake-win for building instructions.
 337   See INSTALL-win32.txt for usage info.
 338
 339  See the man page for more information, usage examples, and
 340  information on firewall configuration.
 341
 342 *************************************************************************
 343
 344 CAVEATS & BUGS:
 345
 346 * I have noticed cases where TCP sessions tunneled over the Linux
 347   TAP driver (kernel 2.4.21 and 2.4.22) stall when lower --mssfix
 348   values are used.  The TCP sessions appear to unstall and resume
 349   normally when the remote VPN endpoint is pinged.
 350
 351 * If run through a firewall using OpenBSDs packet filter PF and the
 352   filter rules include a "scrub" directive, you may get problems talking
 353   to Linux hosts over the tunnel, since the scrubbing will kill packets
 354   sent from Linux hosts if they are fragmented. This is usually seen as
 355   tunnels where small packets and pings get through but large packets
 356   and "regular traffic" don't. To circumvent this, add "no-df" to
 357   the scrub directive so that the packet filter will let fragments with
 358   the "dont fragment"-flag set through anyway.
 359
 360 * Mixing OFB or CFB cipher modes with static key mode is not recommended,
 361   and is flagged as an error on OpenVPN versions 1.2.1 and greater.
 362   If you use the --cipher option to explicitly select an OFB or CFB
 363   cipher AND you are using static key mode, it is possible that there
 364   could be an IV collision if the OpenVPN daemons on both sides
 365   of the connection are started at exactly the same time, since
 366   OpenVPN uses a timestamp combined with a sequence number as the cipher
 367   IV for OFB and CFB modes.  This is not an issue if you are
 368   using CBC cipher mode (the default), or if you are using OFB or CFB
 369   cipher mode with SSL/TLS authentication.