Merge branch 'sagitta' of https://github.com/rebortg/vyos-documentation

1 files changed, 584 insertions, 0 deletions

diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst
new file mode 100644
index 00000000..f503ae84
--- /dev/null
+++ b/docs/configuration/interfaces/openvpn.rst
@@ -0,0 +1,584 @@
+.. _openvpn:
+
+#######
+OpenVPN
+#######
+
+Traditionally hardware routers implement IPsec exclusively due to relative
+ease of implementing it in hardware and insufficient CPU power for doing
+encryption in software. Since VyOS is a software router, this is less of a
+concern. OpenVPN has been widely used on UNIX platform for a long time and is
+a popular option for remote access VPN, though it's also capable of
+site-to-site connections.
+
+Advantages of OpenVPN are:
+
+* It uses a single TCP or UDP connection and does not rely on packet source
+  addresses, so it will work even through a double NAT: perfect for public
+  hotspots and such
+
+* It's easy to setup and offers very flexible split tunneling
+
+* There's a variety of client GUI frontends for any platform
+
+Disadvantages are:
+
+* It's slower than IPsec due to higher protocol overhead and the fact it runs
+  in user mode while IPsec, on Linux, is in kernel mode
+
+* None of the operating systems have client software installed by default
+
+In the VyOS CLI, a key point often overlooked is that rather than being
+configured using the `set vpn` stanza, OpenVPN is configured as a network
+interface using `set interfaces openvpn`.
+
+Site-To-Site
+============
+
+While many are aware of OpenVPN as a Client VPN solution, it is often
+overlooked as a site-to-site VPN solution due to lack of support for this mode
+in many router platforms.
+
+Site-to-site mode supports x.509 but doesn't require it and can also work with
+static keys, which is simpler in many cases. In this example, we'll configure
+a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key.
+
+First, one of the systems generate the key using the operational command
+``generate openvpn key <filename>``. This will generate a key with the name
+provided in the ``/config/auth/`` directory. Once generated, you will need to
+copy this key to the remote router.
+
+In our example, we used the filename ``openvpn-1.key`` which we will reference
+in our configuration.
+
+* The public IP address of the local side of the VPN will be 198.51.100.10
+* The remote will be 203.0.113.11
+* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote.
+* OpenVPN allows for either TCP or UDP. UDP will provide the lowest latency,
+  while TCP will work better for lossy connections; generally UDP is preferred
+  when possible.
+* The official port for OpenVPN is 1194, which we reserve for client VPN; we
+  will use 1195 for site-to-site VPN.
+* The ``persistent-tunnel`` directive will allow us to configure tunnel-related
+  attributes, such as firewall policy as we would on any normal network
+  interface.
+* If known, the IP of the remote router can be configured using the
+  ``remote-host`` directive; if unknown, it can be omitted. We will assume a
+  dynamic IP for our remote router.
+
+Local Configuration:
+
+.. code-block:: none
+
+  set interfaces openvpn vtun1 mode site-to-site
+  set interfaces openvpn vtun1 protocol udp
+  set interfaces openvpn vtun1 persistent-tunnel
+  set interfaces openvpn vtun1 local-host '198.51.100.10'
+  set interfaces openvpn vtun1 local-port '1195'
+  set interfaces openvpn vtun1 remote-port '1195'
+  set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key'
+  set interfaces openvpn vtun1 local-address '10.255.1.1'
+  set interfaces openvpn vtun1 remote-address '10.255.1.2'
+
+Remote Configuration:
+
+.. code-block:: none
+
+  set interfaces openvpn vtun1 mode site-to-site
+  set interfaces openvpn vtun1 protocol udp
+  set interfaces openvpn vtun1 persistent-tunnel
+  set interfaces openvpn vtun1 remote-host '198.51.100.10'
+  set interfaces openvpn vtun1 local-port '1195'
+  set interfaces openvpn vtun1 remote-port '1195'
+  set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key'
+  set interfaces openvpn vtun1 local-address '10.255.1.2'
+  set interfaces openvpn vtun1 remote-address '10.255.1.1'
+
+The configurations above will default to using 256-bit AES in GCM mode
+for encryption (if both sides supports NCP) and SHA-1 for HMAC authentication.
+SHA-1 is considered weak, but other hashing algorithms are available, as are
+encryption algorithms:
+
+For Encryption:
+
+This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or
+OpenVPN version < 2.4.0.
+
+.. code-block:: none
+
+  vyos@vyos# set interfaces openvpn vtun1 encryption cipher
+  Possible completions:
+    des          DES algorithm
+    3des         DES algorithm with triple encryption
+    bf128        Blowfish algorithm with 128-bit key
+    bf256        Blowfish algorithm with 256-bit key
+    aes128       AES algorithm with 128-bit key CBC
+    aes128gcm    AES algorithm with 128-bit key GCM
+    aes192       AES algorithm with 192-bit key CBC
+    aes192gcm    AES algorithm with 192-bit key GCM
+    aes256       AES algorithm with 256-bit key CBC
+    aes256gcm    AES algorithm with 256-bit key GCM
+
+This sets the accepted ciphers to use when version => 2.4.0 and NCP is
+enabled (which is default). Default NCP cipher for versions >= 2.4.0 is
+aes256gcm. The first cipher in this list is what server pushes to clients.
+
+.. code-block:: none
+
+  vyos@vyos# set int open vtun0 encryption ncp-ciphers
+  Possible completions:
+    des          DES algorithm
+    3des         DES algorithm with triple encryption
+    aes128       AES algorithm with 128-bit key CBC
+    aes128gcm    AES algorithm with 128-bit key GCM
+    aes192       AES algorithm with 192-bit key CBC
+    aes192gcm    AES algorithm with 192-bit key GCM
+    aes256       AES algorithm with 256-bit key CBC
+    aes256gcm    AES algorithm with 256-bit key GCM
+
+For Hashing:
+
+.. code-block:: none
+
+  vyos@vyos# set interfaces openvpn vtun1 hash
+  Possible completions:
+    md5          MD5 algorithm
+    sha1         SHA-1 algorithm
+    sha256       SHA-256 algorithm
+    sha512       SHA-512 algorithm
+
+If you change the default encryption and hashing algorithms, be sure that the
+local and remote ends have matching configurations, otherwise the tunnel will
+not come up.
+
+Static routes can be configured referencing the tunnel interface; for example,
+the local router will use a network of 10.0.0.0/16, while the remote has a
+network of 10.1.0.0/16:
+
+Local Configuration:
+
+.. code-block:: none
+
+  set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1
+
+Remote Configuration:
+
+.. code-block:: none
+
+  set protocols static interface-route 10.0.0.0/16 next-hop-interface vtun1
+
+Firewall policy can also be applied to the tunnel interface for `local`, `in`,
+and `out` directions and function identically to ethernet interfaces.
+
+If making use of multiple tunnels, OpenVPN must have a way to distinguish
+between different tunnels aside from the pre-shared-key. This is either by
+referencing IP address or port number. One option is to dedicate a public IP
+to each tunnel. Another option is to dedicate a port number to each tunnel
+(e.g. 1195,1196,1197...).
+
+OpenVPN status can be verified using the `show openvpn` operational commands.
+See the built-in help for a complete list of options.
+
+Server
+======
+
+Multi-client server is the most popular OpenVPN mode on routers. It always uses
+x.509 authentication and therefore requires a PKI setup. Refer this section
+**Generate X.509 Certificate and Keys** to generate a CA certificate,
+a server certificate and key, a certificate revocation list, a Diffie-Hellman
+key exchange parameters file. You do not need client certificates and keys for the server setup.
+
+In this example we will use the most complicated case: a setup where each
+client is a router that has its own subnet (think HQ and branch offices), since
+simpler setups are subsets of it.
+
+Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and
+all client subnets belong to 10.23.0.0/20. All clients need access to the
+192.168.0.0/16 network.
+
+First we need to specify the basic settings. 1194/UDP is the default. The
+``persistent-tunnel`` option is recommended, it prevents the TUN/TAP device from
+closing on connection resets or daemon reloads.
+
+.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is
+   used to renegotiate data channel after n seconds. When used at both server
+   and client, the lower value will trigger the renegotiation. If you set it to
+   0 on one side of the connection (to disable it), the chosen value on the
+   other side will determine when the renegotiation will occur.
+
+.. code-block:: none
+
+  set interfaces openvpn vtun10 mode server
+  set interfaces openvpn vtun10 local-port 1194
+  set interfaces openvpn vtun10 persistent-tunnel
+  set interfaces openvpn vtun10 protocol udp
+
+Then we need to specify the location of the cryptographic materials. Suppose
+you keep the files in `/config/auth/openvpn`
+
+.. code-block:: none
+
+  set interfaces openvpn vtun10 tls ca-cert-file /config/auth/openvpn/ca.crt
+  set interfaces openvpn vtun10 tls cert-file /config/auth/openvpn/server.crt
+  set interfaces openvpn vtun10 tls key-file /config/auth/openvpn/server.key
+  set interfaces openvpn vtun10 tls crl-file /config/auth/openvpn/crl.pem
+  set interfaces openvpn vtun10 tls dh-file /config/auth/openvpn/dh2048.pem
+
+Now we need to specify the server network settings. In all cases we need to
+specify the subnet for client tunnel endpoints. Since we want clients to access
+a specific network behind out router, we will use a push-route option for
+installing that route on clients.
+
+.. code-block:: none
+
+  set interfaces openvpn vtun10 server push-route 192.168.0.0/16
+  set interfaces openvpn vtun10 server subnet 10.23.1.0/24
+
+Since it's a HQ and branch offices setup, we will want all clients to have
+fixed addresses and we will route traffic to specific subnets through them. We
+need configuration for each client to achieve this.
+
+.. note:: Clients are identified by the CN field of their x.509 certificates,
+   in this example the CN is ``client0``:
+
+.. code-block:: none
+
+  set interfaces openvpn vtun10 server client client0 ip 10.23.1.10
+  set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25
+
+OpenVPN **will not** automatically create routes in the kernel for client
+subnets when they connect and will only use client-subnet association
+internally, so we need to create a route to the 10.23.0.0/20 network ourselves:
+
+.. code-block:: none
+
+  set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10
+
+Generate X.509 Certificate and Keys
+-----------------------------------
+
+OpenVPN ships with a set of scripts called Easy-RSA that can generate the
+appropriate files needed for an OpenVPN setup using X.509 certificates.
+Easy-RSA comes installed by default on VyOS routers.
+
+Copy the Easy-RSA scripts to a new directory to modify the values.
+
+.. code-block:: none
+
+  cp -r /usr/share/easy-rsa/ /config/my-easy-rsa-config
+  cd /config/my-easy-rsa-config
+
+To ensure the consistent use of values when generating the PKI, set default
+values to be used by the PKI generating scripts. Rename the vars.example filename
+to vars
+
+.. code-block:: none
+
+  mv vars.example vars
+
+Following is the instance of the file after editing. You may also change other values in
+the file at your discretion/need, though for most cases the defaults should be just fine.
+(do not leave any of these parameters blank)
+
+.. code-block:: none
+
+  set_var EASYRSA_DN      "org"
+  set_var EASYRSA_REQ_COUNTRY     "US"
+  set_var EASYRSA_REQ_PROVINCE    "California"
+  set_var EASYRSA_REQ_CITY        "San Francisco"
+  set_var EASYRSA_REQ_ORG "Copyleft Certificate Co"
+  set_var EASYRSA_REQ_EMAIL       "me@example.net"
+  set_var EASYRSA_REQ_OU          "My Organizational Unit"
+  set_var EASYRSA_KEY_SIZE        2048
+
+
+init-pki option will create a new pki directory or will delete any previously generated
+certificates stored in that folder. The term 'central' is used to refer server and
+'branch' for client
+
+.. note:: Remember the “CA Key Passphrase” prompted in build-ca command,
+   as it will be asked in signing the server/client certificate.
+
+.. code-block:: none
+
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa init-pki
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-ca
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-req central nopass
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa sign-req server central
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass
+
+To generate a certificate revocation list for any client, execute these commands:
+
+.. code-block:: none
+
+  vyos@vyos:/config/my-easy-rsa-config$./easyrsa revoke client1
+  vyos@vyos:/config/my-easy-rsa-config$ ./easyrsa gen-crl
+
+Copy the files to /config/auth/ovpn/ to use in OpenVPN tunnel creation
+
+.. code-block:: none
+
+  vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/ovpn
+  vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/ovpn
+  vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem  /config/auth/ovpn
+  vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/ovpn
+  vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt  /config/auth/ovpn
+  vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/ovpn
+
+Additionally, each client needs a copy of ca.crt and its own client key and cert files.
+The files are plaintext so they may be copied either manually,
+or through a remote file transfer tool like scp. Whichever method you use,
+the files need to end up in the proper location on each router.
+For example, Branch 1's router might have the following files:
+
+.. code-block:: none
+
+  vyos@branch1-rtr:$ ls /config/auth/ovpn
+  ca.crt branch1.crt branch1.key
+
+Client Authentication
+=====================
+
+LDAP
+----
+
+Enterprise installations usually ship a kind of directory service which is used
+to have a single password store for all employees. VyOS and OpenVPN support using
+LDAP/AD as single user backend.
+
+Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is
+shipped with every VyOS installation. A dedicated configuration file is required.
+It is best practise to store it in ``/config`` to survive image updates
+
+.. code-block:: none
+
+  set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+
+The required config file may look like:
+
+.. code-block:: none
+
+  <LDAP>
+  # LDAP server URL
+  URL             ldap://ldap.example.com
+  # Bind DN (If your LDAP server doesn't support anonymous binds)
+  BindDN          cn=LDAPUser,dc=example,dc=com
+  # Bind Password password
+  Password        S3cr3t
+  # Network timeout (in seconds)
+  Timeout         15
+  </LDAP>
+
+  <Authorization>
+  # Base DN
+  BaseDN          "ou=people,dc=example,dc=com"
+  # User Search Filter
+  SearchFilter    "(&(uid=%u)(objectClass=shadowAccount))"
+  # Require Group Membership - allow all users
+  RequireGroup    false
+  </Authorization>
+
+Active Directory
+^^^^^^^^^^^^^^^^
+
+Despite the fact that AD is a superset of LDAP
+
+.. code-block:: none
+
+  <LDAP>
+    # LDAP server URL
+    URL ldap://dc01.example.com
+    # Bind DN (If your LDAP server doesn’t support anonymous binds)
+    BindDN CN=LDAPUser,DC=example,DC=com
+    # Bind Password
+    Password mysecretpassword
+    # Network timeout (in seconds)
+    Timeout  15
+    # Enable Start TLS
+    TLSEnable no
+    # Follow LDAP Referrals (anonymously)
+    FollowReferrals no
+  </LDAP>
+
+  <Authorization>
+    # Base DN
+    BaseDN        "DC=example,DC=com"
+    # User Search Filter, user must be a member of the VPN AD group
+    SearchFilter  "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))"
+    # Require Group Membership
+    RequireGroup    false # already handled by SearchFilter
+    <Group>
+      BaseDN        "OU=Groups,DC=example,DC=com"
+      SearchFilter  "(|(cn=VPN))"
+      MemberAttribute  memberOf
+    </Group>
+  </Authorization>
+
+If you only want to check if the user account is enabled and can authenticate
+(against the primary group) the following snipped is sufficient:
+
+.. code-block:: none
+
+  <LDAP>
+    URL ldap://dc01.example.com
+    BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com
+    Password ThisIsTopSecret
+    Timeout  15
+    TLSEnable no
+    FollowReferrals no
+  </LDAP>
+
+  <Authorization>
+    BaseDN          "DC=example,DC=com"
+    SearchFilter    "sAMAccountName=%u"
+    RequireGroup    false
+  </Authorization>
+
+A complete LDAP auth OpenVPN configuration could look like the following example:
+
+.. code-block:: none
+
+  vyos@vyos# show interfaces openvpn
+   openvpn vtun0 {
+       mode server
+       openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix"
+       openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+       openvpn-option "--push redirect-gateway"
+       openvpn-option --duplicate-cn
+       openvpn-option --client-cert-not-required
+       openvpn-option --comp-lzo
+       openvpn-option --persist-key
+       openvpn-option --persist-tun
+       server {
+           domain-name example.com
+           max-connections 5
+           name-server 1.1.1.1
+           name-server 9.9.9.9
+           subnet 172.18.100.128/29
+       }
+       tls {
+           ca-cert-file /config/auth/ca.crt
+           cert-file /config/auth/server.crt
+           dh-file /config/auth/dh1024.pem
+           key-file /config/auth/server.key
+       }
+   }
+
+Client
+======
+
+VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients.
+You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client
+connecting to a VyOS OpenVPN server or any other OpenVPN server.
+
+Given the following example we have one VyOS router acting as OpenVPN server
+and another VyOS router acting as OpenVPN client. The Server also pushes a
+static client IP address to the OpenVPN client. Remember, clients are identified
+using their CN attribute in the SSL certificate.
+
+Server
+------
+
+.. code-block:: none
+
+  set interfaces openvpn vtun10 encryption cipher 'aes256'
+  set interfaces openvpn vtun10 hash 'sha512'
+  set interfaces openvpn vtun10 local-host '172.18.201.10'
+  set interfaces openvpn vtun10 local-port '1194'
+  set interfaces openvpn vtun10 mode 'server'
+  set interfaces openvpn vtun10 persistent-tunnel
+  set interfaces openvpn vtun10 protocol 'udp'
+  set interfaces openvpn vtun10 server client client1 ip '10.10.0.10'
+  set interfaces openvpn vtun10 server domain-name 'vyos.net'
+  set interfaces openvpn vtun10 server max-connections '250'
+  set interfaces openvpn vtun10 server name-server '172.16.254.30'
+  set interfaces openvpn vtun10 server subnet '10.10.0.0/24'
+  set interfaces openvpn vtun10 server topology 'subnet'
+  set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt'
+  set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt'
+  set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem'
+  set interfaces openvpn vtun10 tls key-file '/config/auth/server.key'
+  set interfaces openvpn vtun10 use-lzo-compression
+
+Client
+------
+
+.. code-block:: none
+
+  set interfaces openvpn vtun10 encryption cipher 'aes256'
+  set interfaces openvpn vtun10 hash 'sha512'
+  set interfaces openvpn vtun10 mode 'client'
+  set interfaces openvpn vtun10 persistent-tunnel
+  set interfaces openvpn vtun10 protocol 'udp'
+  set interfaces openvpn vtun10 remote-host '172.18.201.10'
+  set interfaces openvpn vtun10 remote-port '1194'
+  set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt'
+  set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt'
+  set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key'
+  set interfaces openvpn vtun10 use-lzo-compression
+
+Options
+=======
+
+We do not have CLI nodes for every single OpenVPN options. If an option is
+missing, a feature request should be opened at Phabricator_ so all users can
+benefit from it (see :ref:`issues_features`).
+
+If you are a hacker or want to try on your own we support passing raw OpenVPN
+options to OpenVPN.
+
+.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key'
+
+Will add ``persistent-key`` at the end of the generated OpenVPN configuration.
+Please use this only as last resort - things might break and OpenVPN won't start
+if you pass invalid options/syntax.
+
+.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'push &quot;keepalive 1 10&quot;'
+
+Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file.
+
+.. note:: Sometimes option lines in the generated OpenVPN configurarion require
+   quotes. This is done through a hack on our config generator. You can pass
+   quotes using the ``&quot;`` statement.
+
+
+Troubleshooting
+===============
+
+VyOS provides some operational commands on OpenVPN.
+
+Check status
+------------
+
+The following commands let you check tunnel status.
+
+.. opcmd:: show openvpn client
+
+   Use this command to check the tunnel status for OpenVPN client interfaces.
+
+.. opcmd:: show openvpn server
+
+   Use this command to check the tunnel status for OpenVPN server interfaces.
+
+.. opcmd:: show openvpn site-to-site
+
+   Use this command to check the tunnel status for OpenVPN site-to-site interfaces.
+
+
+Reset OpenVPN
+-------------
+
+The following commands let you reset OpenVPN.
+
+.. opcmd:: reset openvpn client <text>
+
+   Use this command to reset specified OpenVPN client.
+
+.. opcmd:: reset openvpn interface <interface>
+
+   Uset this command to reset the OpenVPN process on a specific interface.
+
+
+
+.. include:: /_include/common-references.txt