From 7952a1291791fcaf96bfb937a06490b780c8d8c7 Mon Sep 17 00:00:00 2001 From: aapostoliuk Date: Tue, 27 Feb 2024 17:01:54 +0200 Subject: Rewritten the IPoE server documentation Fully rewritten IPoE server documentation. (cherry picked from commit 2c3553ef8828748fdbd4938f758e6bfb6170f869) --- docs/configuration/service/ipoe-server.rst | 476 ++++++++++++++++++++++------- 1 file changed, 367 insertions(+), 109 deletions(-) (limited to 'docs/configuration/service/ipoe-server.rst') diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index ed4ade1a..5608c27c 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -1,5 +1,3 @@ -.. include:: /_include/need_improvement.txt - .. _ipoe_server: ########### @@ -24,8 +22,9 @@ functionality as PPPoE, but in a less robust manner. will restart the ppp daemon and will reset existing IPoE sessions, in order to become effective. -Configuration -============= +*********************** +Configuring IPoE Server +*********************** 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 @@ -39,158 +38,417 @@ the configuration. .. code-block:: none - set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server name-server '10.10.1.1' - set service ipoe-server name-server '10.10.1.2' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' + set interfaces ethernet eth1 address '192.168.0.1/24' + set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 + set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 + set service ipoe-server authentication mode 'local' + set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' + set service ipoe-server default-pool 'IPOE-POOL' + set service ipoe-server gateway-address '192.168.0.1/24' + set service ipoe-server interface eth1 mode 'l2' + set service ipoe-server interface eth1 network 'vlan' + set service ipoe-server interface eth1 vlan '100-200' -The first address of the parameter ``client-subnet``, will be used as the -default gateway. Connected sessions can be checked via the ``show ipoe-server -sessions`` command. +.. cfgcmd:: set service ipoe-server authentication interface mac -.. code-block:: none + Creates local pppoe user with username=**** and + password=**** (mac-address) - vyos@vyos:~$ show ipoe-server sessions +.. cfgcmd:: set service ipoe-server authentication mode - 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 + Set authentication backend. The configured authentication backend is used + for all queries. + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + * **noauth**: Authentication disabled -IPv6 SLAAC and IA-PD --------------------- +.. cfgcmd:: set service ipoe-server client-ip-pool range -To configure IPv6 assignments for clients, two options need to be configured. -A global prefix which is terminated on the clients cpe and a delegated prefix, -the client can use for devices routed via the clients cpe. + Use this command to define the first IP address of a pool of + addresses to be given to l2tp clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. -IPv6 DNS addresses are optional. +.. cfgcmd:: set service ipoe-server default-pool -.. code-block:: none + Use this command to define default address pool name. - set service ipoe-server authentication interface eth3 mac 08:00:27:2F:D8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:1::/48' delegation-prefix '56' - set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8::/48' mask '64' - set service ipoe-server default-ipv6-pool IPv6-POOL - set service ipoe-server name-server '2001:db8::' - set service ipoe-server name-server '2001:db8:aaa::' - set service ipoe-server name-server '2001:db8:bbb::' - set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' +.. cfgcmd:: set service ipoe-server gateway-address + + Specifies address to be used as server ip address if radius can assign + only client address. In such case if client address is matched network + and mask then specified address and mask will be used. You can specify + multiple such options. + +.. cfgcmd:: set service ipoe-server interface mode + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **l2**: It means that clients are on same network where interface + is.**(default)** + * **local**: It means that client are behind some router. + +.. cfgcmd:: set service ipoe-server interface network + + Specify where interface is shared by multiple users or it is vlan-per-user. + + * **shared**: Multiple clients share the same network. **(default)** + * **vlan**: One VLAN per client. .. code-block:: none - vyos@ipoe-server# run sh ipoe-server sessions - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+---------------------------------+-----------------+------------+--------+----------+------------------ - ipoe0 | eth3 | 08:00:27:2f:d8:06 | 192.168.1.2 | 2001:db8::a00:27ff:fe2f:d806/64 | 2001:db8:1::/56 | | active | 01:02:59 | 4626faf71b12cc25 + vyos@vyos:~$ show ipoe-server sessions + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + --------+----------+-------------------+-------------+------------+------+------+--------+---------- + ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 + ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 -The clients :abbr:`CPE (Customer Premises Equipment)` can now communicate via -IPv4 or IPv6. All devices behind ``2001:db8::a00:27ff:fe2f:d806/64`` can use -addresses from ``2001:db8:1::/56`` and can globally communicate without the -need of any NAT rules. -Automatic VLAN creation ------------------------ +********************************* +Configuring RADIUS authentication +********************************* -To create VLANs per user during runtime, the following settings are required on -a per interface basis. VLAN ID and VLAN range can be present in the -configuration at the same time. +To enable RADIUS based authentication, the authentication mode needs to be +changed within 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. .. code-block:: none - set service ipoe-server interface eth2 network vlan - set service ipoe-server interface eth2 vlan-id 100 - set service ipoe-server interface eth2 vlan-id 200 - set service ipoe-server interface eth2 vlan-range 1000-2000 - set service ipoe-server interface eth2 vlan-range 2500-2700 + set service ipoe-server authentication mode radius + +.. cfgcmd:: set service ipoe-server authentication radius server key -RADIUS Setup ------------- + Configure RADIUS `` and its required shared `` for + communicating with the RADIUS server. -To use a RADIUS server for authentication and bandwidth-shaping, the following -example configuration can be used. +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: .. code-block:: none - set service ipoe-server authentication mode 'radius' - set service ipoe-server authentication radius server 10.100.100.1 key 'password' + set service ipoe-server authentication radius server 10.0.0.1 key 'foo' + set service ipoe-server authentication radius server 10.0.0.2 key 'foo' -Bandwidth Shaping -================= +.. 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. -Bandwidth rate limits can be set for local users within the configuration or -via RADIUS based attributes. +RADIUS source address +===================== -Bandwidth Shaping for local users ---------------------------------- +If you are using OSPF as IGP, always the closest interface connected to 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. -The rate-limit is set in kbit/sec. +.. cfgcmd:: set service ipoe-server authentication radius source-address
-.. code-block:: none + Source IPv4 address used in all RADIUS server queires. + +.. note:: The ``source-address`` must be configured on one of VyOS interface. + Best practice would be a loopback or dummy interface. + +RADIUS advanced options +======================= + +.. cfgcmd:: set service ipoe-server authentication radius server port + + Configure RADIUS `` and its required port for authentication requests. + +.. cfgcmd:: set service ipoe-server authentication radius server fail-time