arrange: interfaces

1 files changed, 0 insertions, 584 deletions

diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst
deleted file mode 100644
index c6934335..00000000
--- a/docs/vpn/openvpn.rst
+++ /dev/null
@@ -1,584 +0,0 @@
-.. _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:: ../common-references.rst