[IPoE] Initial documentation with working examples

2 files changed, 83 insertions, 0 deletions

diff --git a/docs/services/index.rst b/docs/services/index.rst
index e4a95a4d..57471cf8 100644
--- a/docs/services/index.rst
+++ b/docs/services/index.rst
@@ -19,6 +19,7 @@ This chapter descriptes the available system/network services provided by VyOS.
    lldp
    mdns-repeater
    pppoe-server
+   ipoe-server
    udp-broadcast-relay
    snmp
    ssh
diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst
new file mode 100644
index 00000000..2178882b
--- /dev/null
+++ b/docs/services/ipoe-server.rst
@@ -0,0 +1,82 @@
+IPoE server
+------------
+
+VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be
+used with local authentication (mac-address) or a connected RADIUS server.
+
+.. note:: **Please be aware, due to an upstream bug, config changes/commits
+   will restart the ppp daemon and will reset existing IPoE sessions,
+   in order to become effective.**
+
+Configuration
+^^^^^^^^^^^^^
+
+IPoE can be configure on different interfaces, it will depend on each specific situation which interface will provide IPoE to clients.
+The clients mac address and the incoming interface is being used as control parameter, to authenticate a client.
+
+The example comnfiguration below will assign an IP to the client on the incoming interface eth2 with the client mac address 08:00:27:2f:d8:06.
+Other DHCP discovery requests will be ignored, unless the client mac has been enabled in the configuration.
+
+.. code-block:: sh
+
+  set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06
+  set service ipoe-server authentication mode 'local'
+  set service ipoe-server dns-server server-1 '8.8.8.8'
+  set service ipoe-server dns-server server-2 '8.8.4.4'
+  set service ipoe-server interface eth2 client-subnet '192.168.0.0/24'
+
+
+The first address of the paramter ``client-subnet``, will be used as the default gateway. 
+Connected sessions can be checked via the ``show ipoe-server sessions`` command.
+
+.. code-block:: sh
+
+  vyos@vyos:~$ show ipoe-server sessions 
+
+  ifname | called-sid |    calling-sid    |     ip      | ip6 | ip6-dp | rate-limit | state  |  uptime  |        sid       
+  -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------
+  ipoe0  | eth2       | 08:00:27:2f:d8:06 | 192.168.0.2 |     |        |            | active | 00:45:05 | dccc870fd3134612 
+
+
+RADIUS Setup
+^^^^^^^^^^^^
+
+To use a RADIUS server for authentication and bandwidth-shaping, the following example configuration can be used.
+
+.. code-block:: sh
+
+  set service ipoe-server authentication mode 'radius'
+  set service ipoe-server authentication radius-server 10.100.100.1 secret 'password'
+
+
+Bandwidth Shaping
+^^^^^^^^^^^^^^^^^
+
+Bandwidth rate limits can be set for local users within the configuration or via RADIUS based attributes.
+
+
+Bandwidth Shaping for local users 
+=================================
+
+The rate-limit is set in kbit/sec.
+
+.. code-block:: sh
+
+  set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500'
+  set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500'
+  set service ipoe-server authentication mode 'local'
+  set service ipoe-server dns-server server-1 '8.8.8.8'
+  set service ipoe-server dns-server server-2 '8.8.4.4'
+  set service ipoe-server interface eth2 client-subnet '192.168.0.0/24'
+
+
+.. code-block:: sh
+
+  vyos@vyos# run show ipoe-server sessions 
+
+  ifname | called-sid |    calling-sid    |     ip      | ip6 | ip6-dp | rate-limit | state  |  uptime  |        sid       
+  -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------
+  ipoe0  | eth2       | 08:00:27:2f:d8:06 | 192.168.0.2 |     |        | 500/500    | active | 00:00:05 | dccc870fd31349fb
+
+
+.. _`accel-ppp`: https://accel-ppp.org/