Merge pull request #91 from DmitriyEshenko/patch-8

Recovery L2TP documentation for 1.2.1-1.2.2

1 files changed, 36 insertions, 141 deletions

diff --git a/docs/vpn/l2tp.rst b/docs/vpn/l2tp.rst
index 0dd5fe3e..5835b8c6 100644
--- a/docs/vpn/l2tp.rst
+++ b/docs/vpn/l2tp.rst
@@ -1,13 +1,7 @@
 .. _l2tp:
 
-L2TP
------------
-
-VyOS utilizes accel-ppp_ to provide SSTP server functionality. It can be used
-with local authentication or a connected RADIUS server.
-
 L2TP over IPsec
-===============
+---------------
 
 Example for configuring a simple L2TP over IPsec VPN for remote access (works
 with native Windows and Mac VPN clients):
@@ -18,26 +12,25 @@ with native Windows and Mac VPN clients):
   set vpn ipsec nat-traversal enable
   set vpn ipsec nat-networks allowed-network 0.0.0.0/0
 
-  set vpn l2tp remote-access outside-address 192.0.2.2
-  set vpn l2tp remote-access outside-nexthop 192.168.255.1
-  set vpn l2tp remote-access client-ip-pool start 192.168.255.2
+  set vpn l2tp remote-access outside-address 203.0.113.2
+  set vpn l2tp remote-access client-ip-pool start 192.168.255.1
   set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
   set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret
   set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret>
   set vpn l2tp remote-access authentication mode local
-  set vpn l2tp remote-access authentication local-users username test password 'test'
+  set vpn l2tp remote-access authentication local-users username <username> password <password>
 
-In the example above an external IP of 192.0.2.2 is assumed. Nexthop IP address
-192.168.255.1 uses as client tunnel termination point.
+In the example above an external IP of 203.0.113.2 is assumed.
 
 If a local firewall policy is in place on your external interface you will need
-to allow the ports below:
+to open:
 
 * UDP port 500 (IKE)
 * IP protocol number 50 (ESP)
 * UDP port 1701 for IPsec
 
-As well as the below to allow NAT-traversal:
+In addition when NAT is detected by the VPN client ESP is encapsulated in UDP
+for NAT-traversal:
 
 * UDP port 4500 (NAT-T)
 
@@ -46,6 +39,7 @@ Example:
 .. code-block:: sh
 
   set firewall name OUTSIDE-LOCAL rule 40 action 'accept'
+  set firewall name OUTSIDE-LOCAL rule 40 destination port '50'
   set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp'
   set firewall name OUTSIDE-LOCAL rule 41 action 'accept'
   set firewall name OUTSIDE-LOCAL rule 41 destination port '500'
@@ -58,8 +52,8 @@ Example:
   set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec'
   set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp'
 
-To allow VPN-clients access via your external address, a NAT rule is required:
-
+Also note that if you wish to allow the VPN to be used for external access you
+will need to add the appropriate source NAT rules to your configuration.
 
 .. code-block:: sh
 
@@ -67,9 +61,8 @@ To allow VPN-clients access via your external address, a NAT rule is required:
   set nat source rule 110 source address '192.168.255.0/24'
   set nat source rule 110 translation address masquerade
 
-
-VPN-clients will request configuration parameters, optionally you can DNS
-parameter to the client.
+To be able to resolve when connected to the VPN, the following DNS rules are
+needed as well.
 
 .. code-block:: sh
 
@@ -80,153 +73,56 @@ parameter to the client.
    public available servers from Quad9_ (9.9.9.9) or Cloudflare_ (1.1.1.1).
 
 Established sessions can be viewed using the **show vpn remote-access**
-operational command, or **show l2tp-server sessions**
-
-.. code-block:: sh
-
-  vyos@vyos:~$ show vpn remote-access
-   ifname | username | calling-sid  |      ip       | rate-limit | type | comp | state  |  uptime
-  --------+----------+--------------+---------------+------------+------+------+--------+----------
-   ppp0   | vyos     | 192.168.0.36 | 192.168.255.1 |            | l2tp |      | active | 00:06:13
-
-
-LNS (L2TP Network Server)
-=========================
-
-LNS are often used to connect to a LAC (L2TP Access Concentrator).
-
-Below is an example to configure a LNS:
+operational command.
 
 .. code-block:: sh
 
-  set vpn l2tp remote-access outside-address 192.0.2.2
-  set vpn l2tp remote-access outside-nexthop 192.168.255.1
-  set vpn l2tp remote-access client-ip-pool start 192.168.255.2
-  set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
-  set vpn l2tp remote-access lns shared-secret 'secret'
-  set vpn l2tp remote-access ccp-disable
-  set vpn l2tp remote-access authentication mode local
-  set vpn l2tp remote-access authentication local-users username test password 'test'
-
-The example above uses 192.0.2.2 as external IP address, the nexthop is supposed
-to be 192.168.255.1 and is used as client termination point. A LAC normally
-requires an authentication password, which is set in the example configuration
-to ``lns shared-secret 'secret'``. This setup requires the Compression Control
-Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access ccp-disable``
-accomplishes that.
-
-
-Bandwidth Shaping
-=================
-
-Bandwidth rate limits can be set for local users or via RADIUS based attributes.
-
-Bandwidth Shaping for local users
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The rate-limit is set in kbit/sec.
-
-.. code-block:: sh
-
-  set vpn l2tp remote-access outside-address 192.0.2.2
-  set vpn l2tp remote-access outside-nexthop 192.168.255.1
-  set vpn l2tp remote-access client-ip-pool start 192.168.255.2
-  set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
-  set vpn l2tp remote-access authentication mode local
-  set vpn l2tp remote-access authentication local-users username test password test
-  set vpn l2tp remote-access authentication local-users username test rate-limit download 20480
-  set vpn l2tp remote-access authentication local-users username test rate-limit upload 10240
-
   vyos@vyos:~$ show vpn remote-access
-  ifname | username | calling-sid  |      ip       | rate-limit  | type | comp | state  |  uptime
-  -------+----------+--------------+---------------+-------------+------+------+--------+-----------
-  ppp0   | test     | 192.168.0.36 | 192.168.255.2 | 20480/10240 | l2tp |      | active | 00:06:30
+  Active remote access VPN sessions:
+  User            Proto Iface     Tunnel IP       TX byte RX byte  Time
+  ----            ----- -----     ---------       ------- -------  ----
+  vyos            L2TP  l2tp0     192.168.255.1      3.2K    8.0K  00h06m13s
 
 RADIUS authentication
-======================
+^^^^^^^^^^^^^^^^^^^^^
 
-To enable RADIUS based authentication, the authentication mode needs to be
-changed withing the configuration. Previous settings like the local users, still
-exists within the configuration, however they are not used if the mode has been
-changed from local to radius. Once changed back to local, it will use all local
-accounts again.
+The above configuration made use of local accounts on the VyOS router for
+authenticating L2TP/IPSec clients. In bigger environments usually something
+like RADIUS_ (FreeRADIUS_ or Microsoft `Network Policy Server`_, NPS) is used.
+
+VyOS supports either `local` or `radius` user authentication:
 
 .. code-block:: sh
 
   set vpn l2tp remote-access authentication mode <local|radius>
 
-Since the RADIUS server would be a single point of failure, multiple RADIUS
-servers can be setup and will be used subsequentially.
+In addition one or more RADIUS_ servers can be configured to server for user
+authentication. This is done using the `radius server` and `radius server key`
+nodes:
 
 .. code-block:: sh
 
-  set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo'
-  set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo'
+  set vpn l2tp remote-access authentication radius server 1.1.1.1 key 'foo'
+  set vpn l2tp remote-access authentication radius server 2.2.2.2 key 'foo'
 
-.. note:: Some RADIUS_ severs use an access control list which allows or denies
-   queries, make sure to add your VyOS router to the allowed client list.
+.. note:: Some RADIUS_ severs make use of an access control list who is allowed
+   to query the server. Please configure your VyOS router in the allowed client
+   list.
 
 RADIUS source address
-^^^^^^^^^^^^^^^^^^^^^
+*********************
 
-If you are using OSPF as IGP always the closets interface connected to the RADIUS
+If you are using e.g. OSPF as IGP always the nearest interface facing the RADIUS
 server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests to a
 single source IP e.g. the loopback interface.
 
 .. code-block:: sh
 
-  set vpn l2tp remote-access authentication radius source-address 10.0.0.3
+  set vpn l2tp remote-access authentication radius source-address 3.3.3.3
 
-Above command will use `10.0.0.3` as source IPv4 address for all RADIUS queries
+Above command will use `3.3.3.3` as source IPv4 address for all RADIUS queries
 on this NAS.
 
-.. note:: The ``source-address`` must be configured on one of VyOS interface.
-   Best proctice would be a loopback or dummy interface.
-
-RADIUS bandwidth shaping attribute
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To enable bandwidth shaping via RADIUS, the option rate-limit needs to be enabled.
-
-.. code-block:: sh
-
-  set vpn l2tp remote-access authentication radius rate-limit enable
-
-The default RADIUS attribute for rate limiting is ``Filter-Id``, but you may also
-redefine it.
-
-.. code-block:: sh
-
-  set vpn l2tp remote-access authentication radius rate-limit attribute Download-Speed
-
-.. note:: If you set a custom RADIUS attribute you must define it on both
-   dictionaries at RADIUS server and client, which is the vyos router in our
-   example.
-
-The RADIUS dictionaries in VyOS are located at ``/usr/share/accel-ppp/radius/``
-
-RADIUS advanced features
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Received RADIUS attributes have a higher priority than parameters defined within
-the CLI configuration, refer to the explanation below.
-
-Allocation clients ip addresses by RADIUS
-*****************************************
-
-If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP
-address will be allocated to the client and the option ip-pool within the CLI
-config is being ignored.
-
-Renaming clients interfaces by RADIUS
-*************************************
-
-If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be
-renamed.
-
-.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16
-   characters, otherwise the interface won't be renamed.
-
 
 .. _`Google Public DNS`: https://developers.google.com/speed/public-dns
 .. _Quad9: https://quad9.net
@@ -234,4 +130,3 @@ renamed.
 .. _RADIUS: https://en.wikipedia.org/wiki/RADIUS
 .. _FreeRADIUS: https://freeradius.org
 .. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server
-.. _accel-ppp: https://accel-ppp.org/