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