INSTALL

   1 Installation instructions for OpenVPN, a Secure Tunneling Daemon
   2
   3 Copyright (C) 2002-2022 OpenVPN 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 *************************************************************************
  16
  17 To download OpenVPN source code of releases, go to:
  18
  19     https://openvpn.net/community-downloads/
  20
  21 OpenVPN releases are also available as Debian/RPM packages:
  22
  23     https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos
  24
  25 OpenVPN development versions can be found here:
  26
  27     https://github.com/OpenVPN/openvpn
  28     https://gitlab.com/OpenVPN/openvpn
  29     https://sourceforge.net/p/openvpn/openvpn/ci/master/tree/
  30
  31 They should all be in sync at any time.
  32
  33 To download easy-rsa go to:
  34
  35     https://github.com/OpenVPN/easy-rsa
  36
  37 To download tap-windows (NDIS 6) driver source code go to:
  38
  39     https://github.com/OpenVPN/tap-windows6
  40
  41 To download ovpn-dco Windows driver source code go to:
  42
  43     https://github.com/OpenVPN/ovpn-dco-win
  44
  45 To get the cross-compilation environment go to:
  46
  47     https://github.com/OpenVPN/openvpn-build
  48
  49 For step-by-step instructions with real-world examples see:
  50
  51     https://community.openvpn.net/openvpn/wiki/GettingStartedwithOVPN
  52     https://community.openvpn.net/openvpn/wiki
  53     https://openvpn.net/community-resources/
  54
  55 Also see the man page for more information.
  56
  57 *************************************************************************
  58
  59 For a list of supported platforms and architectures, and for
  60 instructions how to port OpenVPN to a yet-unsupported architecture,
  61 see the file "PORTS".
  62
  63 *************************************************************************
  64
  65 SYSTEM REQUIREMENTS:
  66   (1) TUN and/or TAP driver to allow user-space programs to control
  67       a virtual point-to-point IP or Ethernet device.
  68       See TUN/TAP Driver References section below for more info.
  69   (2a) OpenSSL library, necessary for encryption, version 1.0.2 or higher
  70       required, available from http://www.openssl.org/
  71       or
  72   (2b) mbed TLS library, an alternative for encryption, version 2.0 or higher
  73       required, available from https://tls.mbed.org/
  74   (3) on Linux, "libnl-gen" is required for kernel netlink support
  75   (4) on Linux, "libcap-ng" is required for Linux capability handling
  76
  77 OPTIONAL:
  78   (5) LZO real-time compression library, required for link compression,
  79       available from http://www.oberhumer.com/opensource/lzo/
  80       (most supported operating systems have LZO in their installable
  81       packages repository.  It might be necessary to add LZO_CFLAGS=
  82       and LZO_LIBS= to the configure call to make it find the LZO pieces)
  83   (6) LZ4 compression library
  84
  85 OPTIONAL (for developers only):
  86   (1) Autoconf 2.59 or higher
  87       Automake 1.9 or higher
  88       Libtool
  89       Git
  90   (2) cmocka test framework (http://cmocka.org)
  91   (3) If using t_client.sh test framework, fping/fping6 is needed
  92       Note: t_client.sh needs an external configured OpenVPN server.
  93       See t_client.rc-sample for more info.
  94
  95 *************************************************************************
  96
  97 CHECK OUT SOURCE FROM SOURCE REPOSITORY:
  98
  99   Clone the repository:
 100
 101     git clone https://github.com/OpenVPN/openvpn
 102     git clone https://gitlab.com/OpenVPN/openvpn
 103     git clone git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn
 104
 105   Check out stable version:
 106
 107     git checkout release/2.6
 108
 109   Check out master (unstable) branch:
 110
 111     git checkout master
 112
 113
 114 *************************************************************************
 115
 116 BUILD COMMANDS FROM TARBALL:
 117
 118         ./configure
 119         make
 120         sudo make install
 121
 122 *************************************************************************
 123
 124 BUILD COMMANDS FROM SOURCE REPOSITORY CHECKOUT:
 125
 126         autoreconf -i -v -f
 127         ./configure
 128         make
 129         sudo make install
 130
 131 *************************************************************************
 132
 133 BUILD A TARBALL FROM SOURCE REPOSITORY CHECKOUT:
 134
 135         autoreconf -i -v -f
 136         ./configure
 137         make distcheck
 138
 139 *************************************************************************
 140
 141 TESTS (after BUILD):
 142
 143 make check (Run all tests below)
 144
 145 Test Crypto:
 146
 147 ./openvpn --genkey secret key
 148 ./openvpn --test-crypto --secret key
 149
 150 Test SSL/TLS negotiations (runs for 2 minutes):
 151
 152 ./openvpn --config sample/sample-config-files/loopback-client (In one window)
 153 ./openvpn --config sample/sample-config-files/loopback-server (Simultaneously in another window)
 154
 155 For more thorough client-server tests you can configure your own, private test
 156 environment. See tests/t_client.rc-sample for details.
 157
 158 To do the C unit tests, you need to have the "cmocka" test framework
 159 installed on your system.  More recent distributions already ship this
 160 as part of their packages/ports.  If your system does not have it,
 161 you can install cmocka with these commands:
 162
 163   $ git clone https://git.cryptomilk.org/projects/cmocka.git
 164   $ cd cmocka
 165   $ mkdir build
 166   $ cd build
 167   $ cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Debug ..
 168   $ make
 169   $ sudo make install
 170
 171
 172 *************************************************************************
 173
 174 OPTIONS for ./configure:
 175
 176   To get an overview of all the configure options, run "./configure --help"
 177
 178 ENVIRONMENT for ./configure:
 179
 180   For more fine-grained control on include + library paths for external
 181   components etc., configure can be called with environment variables on
 182   the command line, e.g.
 183
 184      ./configure OPENSSL_CFLAGS="-I/usr/local/include" ...
 185
 186   these are also explained in "./configure --help", so not repeated here.
 187
 188 *************************************************************************
 189
 190 Linux distribution packaging:
 191
 192 Each Linux distribution has their own way of doing packaging and their
 193 own set of guidelines of how proper packaging should be done.  It
 194 is therefore recommended to reach out to the Linux distributions you
 195 want to have OpenVPN packaged for directly.  The OpenVPN project wants
 196 to focus more on the OpenVPN development and less on the packaging
 197 and how packaging is done in all various distributions.
 198
 199 For more details:
 200
 201 * Arch Linux
 202   https://www.archlinux.org/packages/?name=openvpn
 203
 204 * Debian
 205   https://packages.debian.org/search?keywords=openvpn&searchon=names
 206   https://tracker.debian.org/pkg/openvpn
 207
 208 * Fedora / Fedora EPEL (Red Hat Enterprise Linux/CentOS/Scientific Linux)
 209   https://apps.fedoraproject.org/packages/openvpn/overview/
 210   https://src.fedoraproject.org/rpms/openvpn
 211
 212 * Gentoo
 213   https://packages.gentoo.org/packages/net-vpn/openvpn
 214   https://gitweb.gentoo.org/repo/gentoo.git/tree/net-vpn/openvpn
 215
 216 * openSUSE
 217   https://build.opensuse.org/package/show/network:vpn/openvpn
 218
 219 * Ubuntu
 220   https://packages.ubuntu.com/search?keywords=openvpn
 221
 222 In addition, the OpenVPN community provides best-effort package
 223 repositories for CentOS/Fedora, Debian and Ubuntu:
 224 https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos
 225
 226 *************************************************************************
 227
 228 TUN/TAP Driver References:
 229
 230 * Linux 2.6 or higher (with integrated TUN/TAP driver):
 231
 232   (1) load driver:              modprobe tun
 233   (2) enable routing:           echo 1 > /proc/sys/net/ipv4/ip_forward
 234
 235   Note that (1) needs to be done once per reboot.  If you install from RPM (see
 236   above) and use the openvpn.init script, these steps are taken care of for you.
 237
 238 * FreeBSD:
 239
 240   FreeBSD ships with the TUN/TAP driver, and the device nodes for tap0,
 241   tap1, tap2, tap3, tun0, tun1, tun2 and tun3 are made by default.
 242
 243   On FreeBSD versions prior to 12.0-RELEASE, there were independent
 244   TUN and TAP drivers, and the TAP driver needed to be loaded manually,
 245   using the command:
 246
 247         # kldload if_tap
 248
 249   For recent FreeBSD versions, TUN/TAP are integrated and always loaded.
 250
 251   FreeBSD 14 contains the ovpn(4) for kernel-level OpenVPN acceleration
 252   (DCO) which will be used by OpenVPN 2.6 and up if available.
 253
 254 * OpenBSD:
 255
 256   OpenBSD has dynamically created tun* devices so you only need
 257   to create an empty /etc/hostname.tun0 (tun1, tun2 and so on) for each tun
 258   you plan to use to create the device(s) at boot.
 259
 260 * Solaris:
 261
 262   You need a TUN/TAP kernel driver for OpenVPN to work:
 263
 264     http://www.whiteboard.ne.jp/~admin2/tuntap/
 265
 266 * Windows
 267
 268   OpenVPN on Windows needs a TUN/TAP kernel driver to work. OpenVPN installers
 269   include this driver, so installing it separately is not usually required.
 270
 271   Starting from Windows 10 2004 / Windows Server 2022, OpenVPN can use the
 272   dco-win driver for kernel-level acceleration for OpenVPN client setups.
 273   This driver is also included in the community-provided OpenVPN installers.
 274
 275 *************************************************************************
 276
 277 CAVEATS & BUGS:
 278
 279 * See the bug tracker on https://github.com/OpenVPN/openvpn/issues
 280   and the wiki on https://community.openvpn.net/wiki for more detailed
 281   caveats on operating systems, and for open and resolved bug reports.
 282 * Note: We only recently switched to GitHub for reporting new issues,
 283   old issues can be found at https://community.openvpn.net/openvpn/report