| Installation instructions for OpenVPN, a Secure Tunneling Daemon |
| |
| Copyright (C) 2002-2019 OpenVPN Inc. This program is free software; |
| you can redistribute it and/or modify |
| it under the terms of the GNU General Public License version 2 |
| as published by the Free Software Foundation. |
| |
| ************************************************************************* |
| |
| QUICK START: |
| |
| Unix: |
| ./configure && make && make install |
| |
| ************************************************************************* |
| |
| To download OpenVPN source code of releases, go to: |
| |
| https://openvpn.net/community-downloads/ |
| |
| OpenVPN releases are also available as Debian/RPM packages: |
| |
| https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos |
| |
| OpenVPN development versions can be found here: |
| |
| https://github.com/OpenVPN/openvpn |
| https://gitlab.com/OpenVPN/openvpn |
| https://sourceforge.net/p/openvpn/openvpn/ci/master/tree/ |
| |
| They should all be in sync at any time. |
| |
| To download easy-rsa go to: |
| |
| https://github.com/OpenVPN/easy-rsa |
| |
| To download tap-windows (NDIS 6) driver source code go to: |
| |
| https://github.com/OpenVPN/tap-windows6 |
| |
| To get the cross-compilation environment go to: |
| |
| https://github.com/OpenVPN/openvpn-build |
| |
| For step-by-step instructions with real-world examples see: |
| |
| https://community.openvpn.net/openvpn/wiki/GettingStartedwithOVPN |
| https://community.openvpn.net/openvpn/wiki |
| https://openvpn.net/community-resources/ |
| |
| Also see the man page for more information. |
| |
| ************************************************************************* |
| |
| SUPPORTED PLATFORMS: |
| (1) Linux (kernel 2.6+) |
| (2) Solaris |
| (3) OpenBSD 5.1+ |
| (4) Mac OS X Darwin 10.5+ |
| (5) FreeBSD 7.4+ |
| (6) NetBSD 5.0+ |
| (7) Windows Vista or later for OpenVPN 2.4 |
| (8) Windows XP or later for OpenVPN 2.3 |
| |
| SUPPORTED PROCESSOR ARCHITECTURES: |
| In general, OpenVPN is word size and endian independent, so |
| most processors should be supported. Architectures known to |
| work include Intel x86, Alpha, Sparc, Amd64, and ARM. |
| |
| REQUIRES: |
| (1) TUN and/or TAP driver to allow user-space programs to control |
| a virtual point-to-point IP or Ethernet device. See |
| TUN/TAP Driver Configuration section below for more info. |
| (2) OpenSSL library, necessary for encryption, version 1.0.2 or higher |
| required, available from http://www.openssl.org/ |
| or |
| (3) mbed TLS library, an alternative for encryption, version 2.0 or higher |
| required, available from https://tls.mbed.org/ |
| |
| OPTIONAL: |
| (3) LZO real-time compression library, required for link compression, |
| available from http://www.oberhumer.com/opensource/lzo/ |
| OpenBSD users can use ports or packages to install lzo, but remember |
| to add CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" |
| directives to "configure", since gcc will not find them otherwise. |
| |
| OPTIONAL (for developers only): |
| (1) Autoconf 2.59 or higher + Automake 1.9 or higher |
| -- available from http://www.gnu.org/software/software.html |
| (2) Dmalloc library |
| -- available from http://dmalloc.com/ |
| (3) If using t_client.sh test framework, fping/fping6 is needed |
| -- Available from http://www.fping.org/ |
| Note: t_client.sh needs an external configured OpenVPN server. |
| See t_client.rc-sample for more info. |
| |
| ************************************************************************* |
| |
| CHECK OUT SOURCE FROM SOURCE REPOSITORY: |
| |
| Clone the repository: |
| |
| git clone https://github.com/OpenVPN/openvpn |
| git clone https://gitlab.com/OpenVPN/openvpn |
| git clone git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn |
| |
| Check out stable version: |
| |
| git checkout release/2.4 |
| |
| Check out master (unstable) branch: |
| |
| git checkout master |
| |
| |
| ************************************************************************* |
| |
| BUILD COMMANDS FROM TARBALL: |
| |
| ./configure |
| make |
| make install |
| |
| ************************************************************************* |
| |
| BUILD COMMANDS FROM SOURCE REPOSITORY CHECKOUT: |
| |
| autoreconf -i -v -f |
| ./configure |
| make |
| make install |
| |
| ************************************************************************* |
| |
| BUILD A TARBALL FROM SOURCE REPOSITORY CHECKOUT: |
| |
| autoreconf -i -v -f |
| ./configure |
| make distcheck |
| |
| ************************************************************************* |
| |
| TESTS (after BUILD): |
| |
| make check (Run all tests below) |
| |
| Test Crypto: |
| |
| ./openvpn --genkey secret key |
| ./openvpn --test-crypto --secret key |
| |
| Test SSL/TLS negotiations (runs for 2 minutes): |
| |
| ./openvpn --config sample/sample-config-files/loopback-client (In one window) |
| ./openvpn --config sample/sample-config-files/loopback-server (Simultaneously in another window) |
| |
| For more thorough client-server tests you can configure your own, private test |
| environment. See tests/t_client.rc-sample for details. |
| |
| To do the C unit tests, you need to have the "cmocka" test framework |
| installed on your system. More recent distributions already ship this |
| as part of their packages/ports. If your system does not have it, |
| you can install cmocka with these commands: |
| |
| $ git clone https://git.cryptomilk.org/projects/cmocka.git |
| $ cd cmocka |
| $ mkdir build |
| $ cd build |
| $ cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Debug .. |
| $ make |
| $ sudo make install |
| |
| |
| ************************************************************************* |
| |
| OPTIONS for ./configure: |
| |
| --disable-lzo disable LZO compression support [default=yes] |
| --disable-lz4 Disable LZ4 compression support |
| --enable-comp-stub Don't compile compression support but still allow limited interoperability with compression-enabled peers |
| --disable-crypto disable crypto support [default=yes] |
| --disable-ofb-cfb disable support for OFB and CFB cipher modes |
| [default=yes] |
| --enable-x509-alt-username |
| enable the --x509-username-field feature |
| [default=no] |
| --disable-server disable server support only (but retain client |
| support) [default=yes] |
| --disable-plugins disable plug-in support [default=yes] |
| --disable-management disable management server support [default=yes] |
| --enable-pkcs11 enable pkcs11 support [default=no] |
| --disable-fragment disable internal fragmentation support (--fragment) |
| [default=yes] |
| --disable-multihome disable multi-homed UDP server support (--multihome) |
| [default=yes] |
| --disable-port-share disable TCP server port-share support (--port-share) |
| [default=yes] |
| --disable-debug disable debugging support (disable gremlin and verb |
| 7+ messages) [default=yes] |
| --enable-small enable smaller executable size (disable OCC, usage |
| message, and verb 4 parm list) [default=no] |
| --enable-iproute2 enable support for iproute2 [default=no] |
| --disable-def-auth disable deferred authentication [default=yes] |
| --disable-pf disable internal packet filter [default=yes] |
| --disable-plugin-auth-pam |
| disable auth-pam plugin [default=platform specific] |
| --disable-plugin-down-root |
| disable down-root plugin [default=platform specific] |
| --enable-pam-dlopen dlopen libpam [default=no] |
| --enable-strict enable strict compiler warnings (debugging option) |
| [default=no] |
| --enable-pedantic enable pedantic compiler warnings, will not generate |
| a working executable (debugging option) [default=no] |
| --enable-werror promote compiler warnings to errors, will cause |
| builds to fail if the compiler issues warnings |
| (debugging option) [default=no] |
| --enable-strict-options enable strict options check between peers (debugging |
| option) [default=no] |
| --enable-selinux enable SELinux support [default=no] |
| --enable-systemd enable systemd support [default=no] |
| --enable-async-push enable async-push support for plugins providing |
| deferred authentication [default=no] |
| |
| ENVIRONMENT for ./configure: |
| |
| PLUGINDIR Path of plug-in directory [default=LIBDIR/openvpn/plugins] |
| IFCONFIG full path to ipconfig utility |
| ROUTE full path to route utility |
| IPROUTE full path to ip utility |
| NETSTAT path to netstat utility |
| GIT path to git utility |
| SYSTEMD_ASK_PASSWORD |
| path to systemd-ask-password utility |
| SYSTEMD_UNIT_DIR |
| Path of systemd unit directory [default=LIBDIR/systemd/system] |
| TMPFILES_DIR |
| Path of tmpfiles directory [default=LIBDIR/tmpfiles.d] |
| RST2MAN Path to rst2man utility |
| RST2HTML Path to rst2html utility |
| |
| ENVIRONMENT variables adjusting parameters related to dependencies |
| |
| TAP_CFLAGS C compiler flags for tap |
| LIBPAM_CFLAGS |
| C compiler flags for libpam |
| LIBPAM_LIBS linker flags for libpam |
| PKCS11_HELPER_CFLAGS |
| C compiler flags for PKCS11_HELPER, overriding pkg-config |
| PKCS11_HELPER_LIBS |
| linker flags for PKCS11_HELPER, overriding pkg-config |
| OPENSSL_CFLAGS |
| C compiler flags for OpenSSL |
| OPENSSL_LIBS |
| linker flags for OpenSSL |
| MBEDTLS_CFLAGS |
| C compiler flags for mbedtls |
| MBEDTLS_LIBS |
| linker flags for mbedtls |
| LZO_CFLAGS C compiler flags for lzo |
| LZO_LIBS linker flags for lzo |
| LZ4_CFLAGS C compiler flags for lz4 |
| LZ4_LIBS linker flags for lz4 |
| libsystemd_CFLAGS |
| C compiler flags for libsystemd, overriding pkg-config |
| libsystemd_LIBS |
| linker flags for libsystemd, overriding pkg-config |
| P11KIT_CFLAGS |
| C compiler flags for P11KIT, overriding pkg-config |
| P11KIT_LIBS linker flags for P11KIT, overriding pkg-config |
| |
| ************************************************************************* |
| |
| Linux distribution packaging: |
| |
| Each Linux distribution has their own way of doing packaging and their |
| own set of guidelines of how proper packaging should be done. It |
| is therefore recommended to reach out to the Linux distributions you |
| want to have OpenVPN packaged for directly. The OpenVPN project wants |
| to focus more on the OpenVPN development and less on the packaging |
| and how packaging is done in all various distributions. |
| |
| For more details: |
| |
| * Arch Linux |
| https://www.archlinux.org/packages/?name=openvpn |
| |
| * Debian |
| https://packages.debian.org/search?keywords=openvpn&searchon=names |
| https://tracker.debian.org/pkg/openvpn |
| |
| * Fedora / Fedora EPEL (Red Hat Enterprise Linux/CentOS/Scientific Linux) |
| https://apps.fedoraproject.org/packages/openvpn/overview/ |
| https://src.fedoraproject.org/rpms/openvpn |
| |
| * Gentoo |
| https://packages.gentoo.org/packages/net-vpn/openvpn |
| https://gitweb.gentoo.org/repo/gentoo.git/tree/net-vpn/openvpn |
| |
| * openSUSE |
| https://build.opensuse.org/package/show/network:vpn/openvpn |
| |
| * Ubuntu |
| https://packages.ubuntu.com/search?keywords=openvpn |
| |
| In addition, the OpenVPN community provides a best-effort APT repository |
| for Debian and Ubuntu: |
| https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos |
| |
| ************************************************************************* |
| |
| TUN/TAP Driver Configuration: |
| |
| * Linux 2.6 or higher (with integrated TUN/TAP driver): |
| |
| (1) load driver: modprobe tun |
| (2) enable routing: echo 1 > /proc/sys/net/ipv4/ip_forward |
| |
| Note that (1) needs to be done once per reboot. If you install from RPM (see |
| above) and use the openvpn.init script, these steps are taken care of for you. |
| |
| * FreeBSD: |
| |
| FreeBSD ships with the TUN/TAP driver, and the device nodes for tap0, |
| tap1, tap2, tap3, tun0, tun1, tun2 and tun3 are made by default. |
| However, only the TUN driver is linked into the GENERIC kernel. |
| |
| To load the TAP driver, enter: |
| |
| kldload if_tap |
| |
| See man rc(8) to find out how you can do this at boot time. |
| |
| The easiest way is to install OpenVPN from the FreeBSD ports system, |
| the port includes a sample script to automatically load the TAP driver |
| at boot-up time. |
| |
| * OpenBSD: |
| |
| OpenBSD has dynamically created tun* devices so you only need |
| to create an empty /etc/hostname.tun0 (tun1, tun2 and so on) for each tun |
| you plan to use to create the device(s) at boot. |
| |
| * Solaris: |
| |
| You need a TUN/TAP kernel driver for OpenVPN to work: |
| |
| http://www.whiteboard.ne.jp/~admin2/tuntap/ |
| |
| * Windows |
| |
| OpenVPN on Windows needs a TUN/TAP kernel driver to work. OpenVPN installers |
| include this driver, so installing it separately is not usually required. |
| Windows XP/2003 must use the NDIS 5 (tap-windows) driver, whereas on more |
| recent Windows versions it is recommended to use the NDIS 6 driver |
| (tap-windows6) instead. |
| |
| ************************************************************************* |
| |
| CAVEATS & BUGS: |
| |
| * I have noticed cases where TCP sessions tunneled over the Linux |
| TAP driver (kernel 2.4.21 and 2.4.22) stall when lower --mssfix |
| values are used. The TCP sessions appear to unstall and resume |
| normally when the remote VPN endpoint is pinged. |
| |
| * If run through a firewall using OpenBSDs packet filter PF and the |
| filter rules include a "scrub" directive, you may get problems talking |
| to Linux hosts over the tunnel, since the scrubbing will kill packets |
| sent from Linux hosts if they are fragmented. This is usually seen as |
| tunnels where small packets and pings get through but large packets |
| and "regular traffic" don't. To circumvent this, add "no-df" to |
| the scrub directive so that the packet filter will let fragments with |
| the "dont fragment"-flag set through anyway. |
| |
| * Mixing OFB or CFB cipher modes with static key mode is not recommended, |
| and is flagged as an error on OpenVPN versions 1.2.1 and greater. |
| If you use the --cipher option to explicitly select an OFB or CFB |
| cipher AND you are using static key mode, it is possible that there |
| could be an IV collision if the OpenVPN daemons on both sides |
| of the connection are started at exactly the same time, since |
| OpenVPN uses a timestamp combined with a sequence number as the cipher |
| IV for OFB and CFB modes. This is not an issue if you are |
| using CBC cipher mode (the default), or if you are using OFB or CFB |
| cipher mode with SSL/TLS authentication. |
