INSTALL

Installation instructions for OpenVPN, a Secure Tunneling Daemon

Copyright (C) 2002-2022 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 download ovpn-dco Windows driver source code go to:

    https://github.com/OpenVPN/ovpn-dco-win

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.

*************************************************************************

For a list of supported platforms and architectures, and for
instructions how to port OpenVPN to a yet-unsupported architecture,
see the file "PORTS".

*************************************************************************

SYSTEM REQUIREMENTS:
  (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 References section below for more info.
  (2a) OpenSSL library, necessary for encryption, version 1.1.0 or higher
      required, available from http://www.openssl.org/
      or
  (2b) mbed TLS library, an alternative for encryption, version 2.0 or higher
      required, available from https://tls.mbed.org/
  (3) on Linux, "libnl-gen" is required for kernel netlink support
  (4) on Linux, "libcap-ng" is required for Linux capability handling

OPTIONAL:
  (5) LZO real-time compression library, required for link compression,
      available from http://www.oberhumer.com/opensource/lzo/
      (most supported operating systems have LZO in their installable
      packages repository.  It might be necessary to add LZO_CFLAGS=
      and LZO_LIBS= to the configure call to make it find the LZO pieces)
  (6) LZ4 compression library

OPTIONAL (for developers only):
  (1) Autoconf 2.59 or higher
      Automake 1.9 or higher
      Libtool
      Git
  (2) cmocka test framework (http://cmocka.org)
  (3) If using t_client.sh test framework, fping/fping6 is needed
      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.6

  Check out master (unstable) branch:

    git checkout master


*************************************************************************

BUILD COMMANDS FROM TARBALL:

	./configure
	make
	sudo make install

*************************************************************************

BUILD COMMANDS FROM SOURCE REPOSITORY CHECKOUT:

	autoreconf -i -v -f
	./configure
	make
	sudo 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:

  To get an overview of all the configure options, run "./configure --help"

ENVIRONMENT for ./configure:

  For more fine-grained control on include + library paths for external
  components etc., configure can be called with environment variables on
  the command line, e.g.

     ./configure OPENSSL_CFLAGS="-I/usr/local/include" ...

  these are also explained in "./configure --help", so not repeated here.

*************************************************************************

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 best-effort package
repositories for CentOS/Fedora, Debian and Ubuntu:
https://community.openvpn.net/openvpn/wiki/OpenvpnSoftwareRepos

*************************************************************************

TUN/TAP Driver References:

* 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.

  On FreeBSD versions prior to 12.0-RELEASE, there were independent
  TUN and TAP drivers, and the TAP driver needed to be loaded manually,
  using the command:

	# kldload if_tap

  For recent FreeBSD versions, TUN/TAP are integrated and always loaded.

  FreeBSD 14 contains the ovpn(4) for kernel-level OpenVPN acceleration
  (DCO) which will be used by OpenVPN 2.6 and up if available.

* 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/

* Haiku:

   Haiku can't yet dynamically create TUN/TAP devices, so you need to manually
   create one before running openvpn:

     # ifconfig tun/0 up

   A standard reference the dev as "tun" in your config is all that's needed
   to use the tunnel device.

* 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.

  Starting from Windows 10 2004 / Windows Server 2022, OpenVPN can use the
  dco-win driver for kernel-level acceleration for OpenVPN client setups.
  This driver is also included in the community-provided OpenVPN installers.

*************************************************************************

CAVEATS & BUGS:

* See the bug tracker on https://github.com/OpenVPN/openvpn/issues
  and the wiki on https://community.openvpn.net/wiki for more detailed
  caveats on operating systems, and for open and resolved bug reports.
* Note: We only recently switched to GitHub for reporting new issues,
  old issues can be found at https://community.openvpn.net/openvpn/report