src/openvpn/INSTALL

   1 Installation instructions for OpenVPN, a Secure Tunneling Daemon
   2
   3 Copyright (C) 2002-2005 OpenVPN Solutions LLC. 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 To download OpenVPN, go to:
  11
  12         http://openvpn.net/download.html
  13
  14 For step-by-step installation instructions with real-world
  15 examples see:
  16
  17         http://openvpn.net/howto.html
  18
  19 For examples see:
  20
  21         http://openvpn.net/examples.html
  22
  23 *************************************************************************
  24
  25 SUPPORTED PLATFORMS:
  26   (1) Linux 2.2+
  27   (2) Solaris
  28   (3) OpenBSD 3.0+ (Comes with OpenSSL and TUN devices by default)
  29   (4) Mac OS X Darwin
  30   (5) FreeBSD
  31   (6) NetBSD
  32   (7) Windows (Win 2K and higher)
  33
  34 SUPPORTED PROCESSOR ARCHITECTURES:
  35    In general, OpenVPN is word size and endian independent, so
  36    most processors should be supported.  Architectures known to
  37    work include Intel x86, Alpha, Sparc, Amd64, and ARM.
  38
  39 REQUIRES:
  40   (1) TUN and/or TAP driver to allow user-space programs to control
  41       a virtual point-to-point IP or Ethernet device.  See
  42       TUN/TAP Driver Configuration section below for more info.
  43
  44 OPTIONAL (but recommended):
  45   (1) OpenSSL library, necessary for encryption, version 0.9.5 or higher
  46       required, available from http://www.openssl.org/
  47   (2) LZO real-time compression library, required for link compression,
  48       available from http://www.oberhumer.com/opensource/lzo/
  49       OpenBSD users can use ports or packages to install lzo, but remember
  50       to add "--with-lzo-headers" and "--with-lzo-lib" directives to
  51       "configure", pointing to /usr/local/include and /usr/local/lib
  52       respectively since gcc will not find them otherwise.
  53   (3) Pthread library.
  54
  55 OPTIONAL (for developers only):
  56   (1) Autoconf 2.50 or higher + Automake 1.5 or higher
  57       -- available from http://www.gnu.org/software/software.html
  58   (2) Dmalloc library
  59       -- available from http://dmalloc.com/
  60
  61 *************************************************************************
  62
  63 BUILD COMMANDS FROM TARBALL:
  64
  65         ./configure
  66         make
  67         make install
  68
  69 *************************************************************************
  70
  71 BUILD COMMANDS FROM CVS:
  72
  73         autoreconf -i -v
  74         ./configure
  75         make
  76         make install
  77
  78 *************************************************************************
  79
  80 BUILD A TARBALL FROM CVS:
  81
  82         autoreconf -i -v
  83         ./configure
  84         make dist
  85
  86 *************************************************************************
  87
  88 LOOPBACK TESTS (after BUILD):
  89
  90 make check (Run all tests below)
  91
  92 Test Crypto:
  93
  94 ./openvpn --genkey --secret key
  95 ./openvpn --test-crypto --secret key
  96
  97 Test SSL/TLS negotiations (runs for 2 minutes):
  98
  99 ./openvpn --config sample-config-files/loopback-client  (In one window)
 100 ./openvpn --config sample-config-files/loopback-server  (Simultaneously in another window)
 101
 102 *************************************************************************
 103
 104 OPTIONS for ./configure:
 105
 106   --enable-pthread          Compile pthread support for
 107                             improved latency during SSL/TLS key
 108                             negotiations (Linux or Solaris only)
 109
 110   --disable-lzo             Do not compile LZO compression support
 111   --disable-crypto          Do not compile OpenSSL crypto support
 112   --disable-ssl             Do not compile OpenSSL SSL support for
 113                             TLS-based key exchange
 114
 115   --with-ssl-headers=DIR    Crypto/SSL Include files location
 116   --with-ssl-lib=DIR        Crypto/SSL Library location
 117   --with-lzo-headers=DIR    LZO Include files location
 118   --with-lzo-lib=DIR        LZO Library location
 119
 120   --with-ifconfig-path=PATH   Path to ifconfig tool (only need to
 121                               specify if in a non-standard location)
 122
 123   --with-leak-check=TYPE    Build with memory leak checking
 124                             TYPE = dmalloc or ssl
 125
 126   --enable-strict           Enable strict compiler warnings
 127
 128   --enable-strict-options   Enable strict options check between peers
 129
 130 *************************************************************************
 131
 132 BUILDING ON LINUX 2.4+ FROM RPM
 133
 134 You can build a binary RPM directly from the OpenVPN tarball file:
 135
 136         rpmbuild -tb [tarball]
 137
 138 This command will build a binary RPM file and place it in the system
 139 RPM directory.  You can then install the RPM with the standard RPM
 140 install command:
 141
 142         rpm -ivh [binary-rpm]
 143
 144 When you install the binary RPM, it will install
 145 sample-scripts/openvpn.init, which can be used to
 146 automatically start or stop one or more OpenVPN tunnels on system
 147 startup or shutdown, based on OpenVPN .conf files in /etc/openvpn.
 148 See the comments in openvpn.init for more information.
 149
 150 Installing the RPM will also configure the TUN/TAP device node
 151 for linux 2.4.
 152
 153 Note that the current openvpn.spec file, which instructs the rpm tool
 154 how to build a package, will build OpenVPN with all options enabled,
 155 including OpenSSL, LZO, and pthread linkage.  Therefore all of
 156 these packages will need to be present prior to the RPM build, unless
 157 you edit the openvpn.spec file.
 158
 159 *************************************************************************
 160
 161 TUN/TAP Driver Configuration:
 162
 163 * Linux 2.4 or higher (with integrated TUN/TAP driver):
 164
 165   (1)  make device node:         mknod /dev/net/tun c 10 200
 166   (2a) add to /etc/modules.conf: alias char-major-10-200 tun
 167   (2b) load driver:              modprobe tun
 168   (3)  enable routing:           echo 1 > /proc/sys/net/ipv4/ip_forward
 169
 170   Note that either of steps (2a) or (2b) is sufficient.  While (2a)
 171   only needs to be done once per install, (2b) needs to be done once
 172   per reboot.  If you install from RPM (see above) and use the
 173   openvpn.init script, these steps are taken care of for you.
 174
 175 * Linux 2.2 or Solaris:
 176
 177   You should obtain
 178   version 1.1 of the TUN/TAP driver from
 179   http://vtun.sourceforge.net/tun/
 180   and follow the installation instructions.
 181
 182   If you use OpenVPN on Linux 2.2 or 2.4 or Solaris, you may be
 183   suffering from a bug which causes connections to hang under heavy load.
 184   The symptoms are very similar to the MTU problems discussed frequently
 185   in the OpenVPN mailing lists. But it turns out that this bug is not caused by
 186   MTU problems. It's a bug in the tun/tap driver.  A patch is provided here:
 187
 188   http://openvpn.net/patch/tun-sb.patch
 189
 190 * Solaris
 191
 192   For 64 bit, I used the tun-1.1.tar.gz source and compiled it.
 193
 194   Of course there is a but :)
 195   In the tun-1-1\solaris\Makefile I changed a line so it compiles with 64 bit
 196
 197   CFLAGS = $(DEFS) -m64 -O2 -Wall -D_KERNEL -I.
 198
 199   I just added -m64 and it worked.
 200
 201   The tun driver works fine as said previously, however we noticed there is a
 202   minor problem when creating multiple tunnels on Solaris.
 203   Mr Tycho Fruru changed the code in tun.c file where he locked the tun device
 204   number to -1. This way it is impossible to specify the name of the tun device
 205   but it is still possible to have multiple devices.
 206   The modification will increment automatically meaning starting from tun0 --->
 207   tunX I know you are not responsible for the tun coding but if you think the
 208   modification can be useful for you feel free to use it.
 209
 210   http://openvpn.net/solaris/tun.c
 211
 212 * FreeBSD 4.1.1+:
 213
 214   FreeBSD ships with the TUN/TAP driver, and the device nodes for tap0,
 215   tap1, tap2, tap3, tun0, tun1, tun2 and tun3 are made by default.
 216   However, only the TUN driver is linked into the GENERIC kernel.
 217
 218   To load the TAP driver, enter:
 219
 220         kldload if_tap
 221
 222   See man rc(8) to find out how you can do this at boot time.
 223
 224   The easiest way is to install OpenVPN from the FreeBSD ports system,
 225   the port includes a sample script to automatically load the TAP driver
 226   at boot-up time.
 227
 228 * OpenBSD:
 229
 230   OpenBSD ships with tun0 and tun1 installed by default on pre-3.5 systems,
 231   while 3.5 and later have dynamically created tun* devices so you only need
 232   to create an empty /etc/hostname.tun0 (tun1, tun2 and so on) for each tun
 233   you plan to use to create the device(s) at boot.
 234
 235 * Mac OS X:
 236
 237   2005.02.13: Angelo Laub has developed a GUI for OS X:
 238
 239   http://rechenknecht.net/OpenVPN-GUI/
 240
 241   2004.10.26: Mattias Nissler has developed a new TUN/TAP driver for
 242   MAC OS X:
 243
 244   http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
 245
 246   Christoph Pfisterer's old TUN driver can be obtained at
 247   http://chrisp.de/en/projects/tunnel.html -- note that it
 248   is no longer being maintained.
 249
 250 * Solaris9 Sparc/64
 251
 252   The kernel module for solaris
 253   can be generated by adding the -m64 switch to a modern
 254   gcc compiler (I'm using 3.2)  The resulting kernel driver
 255   needs to be manually copied to /kernel/drv/sparcv9/ and then a
 256   reconfiguration reboot. (boot -r).
 257
 258 * Windows 2000 and XP
 259
 260   See INSTALL-win32.txt for more info
 261
 262  See the man page for more information, usage examples, and
 263  information on firewall configuration.
 264
 265 *************************************************************************
 266
 267 CAVEATS & BUGS:
 268
 269 * I have noticed cases where TCP sessions tunneled over the Linux
 270   TAP driver (kernel 2.4.21 and 2.4.22) stall when lower --mssfix
 271   values are used.  The TCP sessions appear to unstall and resume
 272   normally when the remote VPN endpoint is pinged.
 273
 274 * If run through a firewall using OpenBSDs packet filter PF and the
 275   filter rules include a "scrub" directive, you may get problems talking
 276   to Linux hosts over the tunnel, since the scrubbing will kill packets
 277   sent from Linux hosts if they are fragmented. This is usually seen as
 278   tunnels where small packets and pings get through but large packets
 279   and "regular traffic" don't. To circumvent this, add "no-df" to
 280   the scrub directive so that the packet filter will let fragments with
 281   the "dont fragment"-flag set through anyway.
 282
 283 * Mixing OFB or CFB cipher modes with static key mode is not recommended,
 284   and is flagged as an error on OpenVPN versions 1.2.1 and greater.
 285   If you use the --cipher option to explicitly select an OFB or CFB
 286   cipher AND you are using static key mode, it is possible that there
 287   could be an IV collision if the OpenVPN daemons on both sides
 288   of the connection are started at exactly the same time, since
 289   OpenVPN uses a timestamp combined with a sequence number as the cipher
 290   IV for OFB and CFB modes.  This is not an issue if you are
 291   using CBC cipher mode (the default), or if you are using OFB or CFB
 292   cipher mode with SSL/TLS authentication.