From deacf2bc08f21c0f8b60c2cbcf672e1e5a6ce9a0 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Wed, 9 Sep 2026 18:48:38 +0200 Subject: docs: Update PPPoE server page to VyOS 1.5 standards (#2223) * docs: Update PPPoE server page to VyOS 1.5 standards * Update pppoe-server.md * Update pppoe-server.md * Clarify the meaning of `noauth` --------- Co-authored-by: Daniil Baturin --- docs/configuration/service/pppoe-server.md | 1711 +++++++++++++++++++++------- 1 file changed, 1315 insertions(+), 396 deletions(-) (limited to 'docs') diff --git a/docs/configuration/service/pppoe-server.md b/docs/configuration/service/pppoe-server.md index 805740e4..85b17870 100644 --- a/docs/configuration/service/pppoe-server.md +++ b/docs/configuration/service/pppoe-server.md @@ -1,711 +1,1564 @@ --- -lastproofread: '2022-09-17' +myst: + html_meta: + description: | + The PPPoE server terminates PPPoE sessions from subscribers, + authenticates them locally or via RADIUS, assigns IPv4 and IPv6 + addresses, and enforces per-subscriber bandwidth limits. + keywords: pppoe-server, pppoe, radius, ppp, coa, prefix-delegation, vlan --- (pppoe-server)= -# PPPoE Server +# PPPoE server + +Defined in +[RFC 2516](https://datatracker.ietf.org/doc/html/rfc2516), the +{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` server accepts +PPPoE sessions from subscribers connected over an Ethernet network +and acts as the provider-side endpoint of each session. Service +providers use the PPPoE server to authenticate individual +subscribers, assign them IPv4 and IPv6 addresses, account for their +traffic, and enforce per-subscriber bandwidth limits. + +The PPPoE server is configured under `service pppoe-server`. PPPoE +sessions are authenticated in one of the following ways: locally, via +a {abbr}`RADIUS (Remote Authentication Dial-In User Service)` server +as defined in +[RFC 2865](https://datatracker.ietf.org/doc/html/rfc2865), or not at +all. + +```{note} +Commits that change `interface`, `client-ip-pool`, +`client-ipv6-pool`, `authentication mode`, `authentication +protocols`, any option under `authentication radius`, +`ppp-options ipv6-peer-interface-id`, or +`ppp-options ipv6-peer-interface-id-secret` restart the PPPoE server +and terminate all active sessions. Adding or removing an interface +under `vpp settings interface` or `interfaces vpp bonding` has the +same effect when the PPPoE server listens on that interface or on +one of its VLANs. All other changes keep active sessions. +``` + +## Configuration -VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide PPPoE server functionality. It can -be used with local authentication or a connected RADIUS server. +```{cfgcmd} set service pppoe-server access-concentrator \ + +**Configure the access concentrator name that the PPPoE server +announces to clients during PPPoE discovery.** + +The name may contain letters, digits, hyphens, and underscores. + +The default is `vyos-ac`. +``` + +Example: + +```none +set service pppoe-server access-concentrator PPPoE-AC-01 +``` + +```{cfgcmd} set service pppoe-server authentication mode \ + +**Configure how the PPPoE server authenticates clients:** + +- `local`: Clients are authenticated against the locally configured + usernames and passwords. +- `radius`: Clients are authenticated by the configured RADIUS + servers. +- `noauth`: Authentication is not required to connect. + +The default is `local`. + +In `local` and `noauth` modes, at least one `client-ip-pool` or +`client-ipv6-pool` must be configured. Otherwise, the commit fails. +``` + +Example: + +```none +set service pppoe-server authentication mode radius +``` + +```{cfgcmd} set service pppoe-server authentication local-users username \ password \ + +**Create a locally authenticated PPPoE user with the given password.** + +In `local` authentication mode, at least one local user must be +configured, and every user needs a password. Otherwise, the commit +fails. +``` + +Example: + +```none +set service pppoe-server authentication local-users username user01 password secret +``` + +```{cfgcmd} set service pppoe-server client-ip-pool \ range \ + +**Configure an IPv4 address range as part of the named client pool.** + +Specify the range either as an IPv4 prefix or as an address range +whose endpoints lie within a common /24 network. Repeat the command +to add several ranges to the same pool. +``` + +Example: + +```none +set service pppoe-server client-ip-pool PPPOE-POOL range 192.0.2.10-192.0.2.99 +set service pppoe-server client-ip-pool PPPOE-POOL range 198.51.100.0/24 +``` + +```{cfgcmd} set service pppoe-server default-pool \ + +**Configure the client pool from which IPv4 addresses are assigned by +default.** + +A RADIUS-provided address or pool, when present, takes precedence. + +A client pool with this name must be configured under +`client-ip-pool`. Otherwise, the commit fails. + +In `local` and `noauth` authentication modes, if at least one +`client-ip-pool` is configured but `default-pool` is not set, the +commit succeeds with a warning. +``` + +Example: + +```none +set service pppoe-server default-pool PPPOE-POOL +``` + +```{cfgcmd} set service pppoe-server interface \ + +**Configure an interface on which the PPPoE server listens for PPPoE +clients.** + +Repeat the command to listen on several interfaces. + +At least one listen interface must be configured. Otherwise, the +commit fails. +``` + +Example: + +```none +set service pppoe-server interface eth1 +``` + +```{cfgcmd} set service pppoe-server gateway-address \ + +**Configure the local IPv4 address of the PPP interfaces created for +client sessions.** + +For every session, the PPPoE server creates a PPP interface on the +router, and `gateway-address` becomes its local address. This address +is also sent to clients as their default gateway. + +If `gateway-address` is not set, the commit succeeds with a warning, +and IPv4 sessions cannot be established. +``` + +Example: + +```none +set service pppoe-server gateway-address 192.0.2.254 +``` + +## RADIUS authentication + +To enable RADIUS-based authentication, the authentication mode needs +to be changed to `radius`. Existing settings, such as local users, +remain in the configuration but are not used while the mode is +`radius`. When the mode is set back to `local`, the PPPoE server uses +the local users again. + +```{cfgcmd} set service pppoe-server authentication radius server \ key \ + +**Configure a RADIUS server by its IPv4 address and the shared +secret.** + +The shared secret authenticates the exchange of queries and replies +between the router and the RADIUS server +([RFC 2865](https://datatracker.ietf.org/doc/html/rfc2865)). The same +secret must be configured on the RADIUS server. + +A single RADIUS server is a single point of failure. Repeat the +command to configure multiple servers for redundancy. + +In `radius` authentication mode, at least one server must be +configured, and every server needs a shared secret. Otherwise, the +commit fails. +``` + +```{note} +Some RADIUS servers use an access control list that allows or denies +queries. Make sure to add your VyOS router to the allowed client +list. +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 key 'first-radius-secret' +set service pppoe-server authentication radius server 198.51.100.10 key 'second-radius-secret' +``` + +```{cfgcmd} set service pppoe-server authentication radius server \ priority \<1-255\> + +**Configure the weight of the specified RADIUS server when the router +distributes queries across multiple servers.** +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 priority 10 +``` + +```{cfgcmd} set service pppoe-server authentication radius server \ backup + +**Configure the specified RADIUS server as a backup, used only when +all other servers have failed.** +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.10 backup +``` + +### Source address + +By default, the router selects the source address of each RADIUS +query based on the route to that server. This address may change if +routing changes. The following command configures a single source +address for all RADIUS queries. + +```{cfgcmd} set service pppoe-server authentication radius source-address \ + +**Configure the source IPv4 address used in all queries to RADIUS +servers.** + +Use an address configured on one of the router's interfaces. +Typically, this is a loopback or dummy interface address. +``` + +Example: + +```none +set service pppoe-server authentication radius source-address 192.0.2.1 +``` + +### Advanced options + +```{cfgcmd} set service pppoe-server authentication radius server \ port \<1-65535\> + +**Configure the UDP port the router uses to send client +authentication requests to the specified RADIUS server.** + +The default is 1812. +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 port 1645 +``` + +```{cfgcmd} set service pppoe-server authentication radius server \ acct-port \<1-65535\> + +**Configure the UDP port to which the router sends accounting +requests for the specified RADIUS server.** + +The default is 1813. +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 acct-port 1646 +``` + +```{cfgcmd} set service pppoe-server authentication radius server \ disable-accounting + +**Stop sending accounting requests to the specified RADIUS server.** +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 disable-accounting +``` + +```{cfgcmd} set service pppoe-server authentication radius server \ fail-time \<0-600\> + +**Mark the specified RADIUS server as unavailable for the given time, +in seconds, after it fails to respond.** + +The default is 0. +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 fail-time 60 +``` + +```{cfgcmd} set service pppoe-server authentication radius server \ disable + +**Disable the specified RADIUS server without removing it from the +configuration.** +``` + +Example: + +```none +set service pppoe-server authentication radius server 198.51.100.9 disable +``` + +```{cfgcmd} set service pppoe-server authentication radius acct-timeout \<0-60\> + +**Configure the time, in seconds, to wait for a reply to +Interim-Update accounting packets before terminating the session.** + +Setting the value to 0 keeps the session active regardless of +accounting replies. + +The default is 3. +``` + +Example: + +```none +set service pppoe-server authentication radius acct-timeout 30 +``` + +```{cfgcmd} set service pppoe-server authentication radius accounting-interim-interval \<1-3600\> + +**Configure the interval, in seconds, at which the router sends +accounting updates for active sessions.** + +A RADIUS server may override this interval with the +Acct-Interim-Interval attribute. +``` + +Example: + +```none +set service pppoe-server authentication radius accounting-interim-interval 300 +``` + +```{cfgcmd} set service pppoe-server authentication radius acct-interim-jitter \<1-60\> + +**Configure the largest random offset, in seconds, applied to the +accounting update interval.** + +Spreading the updates keeps sessions from sending them all at once. +``` + +Example: + +```none +set service pppoe-server authentication radius acct-interim-jitter 10 +``` + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \ + +**Configure the local IPv4 address on which the router accepts +{abbr}`CoA (Change of Authorization)` and Disconnect requests from +the RADIUS server.** + +A Disconnect request terminates an active session. A CoA request +changes the authorization attributes of an active session. Both are +defined in +[RFC 5176](https://datatracker.ietf.org/doc/html/rfc5176), Dynamic +Authorization Extensions to RADIUS. + +`dynamic-author key` must also be configured. Otherwise, the commit +fails. +``` + +Example: + +```none +set service pppoe-server authentication radius dynamic-author server 192.0.2.1 +``` + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author port \<1-65535\> + +**Configure the UDP port on which the router accepts CoA and +Disconnect requests.** + +The default is 1700. +``` + +Example: + +```none +set service pppoe-server authentication radius dynamic-author port 3799 +``` + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author key \ + +**Configure the shared secret that authenticates incoming CoA and +Disconnect requests.** +``` + +Example: + +```none +set service pppoe-server authentication radius dynamic-author key 'coa-secret' +``` + +```{cfgcmd} set service pppoe-server authentication radius max-try \<1-20\> + +**Configure the maximum number of attempts to send Access-Request and +Accounting-Request queries to a RADIUS server.** + +The default is 3. +``` + +Example: + +```none +set service pppoe-server authentication radius max-try 5 +``` + +```{cfgcmd} set service pppoe-server authentication radius timeout \<1-60\> + +**Configure the time, in seconds, to wait for a reply from a RADIUS +server.** + +The default is 3. +``` + +Example: + +```none +set service pppoe-server authentication radius timeout 10 +``` + +```{cfgcmd} set service pppoe-server authentication radius nas-identifier \ + +**Configure the value the router sends to RADIUS servers in the +NAS-Identifier attribute.** + +In RADIUS, the router acts as a {abbr}`NAS (Network Access Server)`, +a device through which clients get access to the network. The RADIUS +server uses the NAS-Identifier value to identify which NAS originated +a request. The attribute is defined in +[RFC 2865 section 5.32](https://datatracker.ietf.org/doc/html/rfc2865#section-5.32). +``` + +Example: + +```none +set service pppoe-server authentication radius nas-identifier pppoe-gw01 +``` + +```{cfgcmd} set service pppoe-server authentication radius nas-ip-address \ + +**Configure the IPv4 address the router sends to RADIUS servers in +the NAS-IP-Address attribute.** + +NAS-IP-Address identifies the router to the RADIUS server by IPv4 +address, as NAS-Identifier does by name. The attribute is defined in +[RFC 2865 section 5.4](https://datatracker.ietf.org/doc/html/rfc2865#section-5.4). +The attribute does not change the source address of RADIUS queries. +``` + +Example: + +```none +set service pppoe-server authentication radius nas-ip-address 192.0.2.1 +``` + +```{cfgcmd} set service pppoe-server authentication radius preallocate-vif + +**Create the PPP interface of a session before authentication, so +that the router can send NAS-Port-Id in the Access-Request.** +``` + +Example: + +```none +set service pppoe-server authentication radius preallocate-vif +``` + +```{cfgcmd} set service pppoe-server authentication radius called-sid-format \ + +**Configure the format of the Called-Station-Id attribute the router +sends to RADIUS servers:** + +- `ifname`: The name of the interface that accepted the request, for + example `eth1`. +- `ifname:mac`: The interface name and its MAC address, for example + `eth1:00:00:00:00:00:00`. +``` + +Example: + +```none +set service pppoe-server authentication radius called-sid-format ifname:mac +``` + +```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \ + +**Configure which RADIUS attribute carries the rate information.** + +The default is `Filter-Id`. When using a custom attribute, define it +in the RADIUS dictionaries of both the RADIUS server and the router. +``` + +Example: + +```none +set service pppoe-server authentication radius rate-limit attribute Mikrotik-Rate-Limit +``` + +```{cfgcmd} set service pppoe-server authentication radius rate-limit enable + +**Enable bandwidth shaping of client sessions based on rate +information received from the RADIUS server.** +``` + +Example: + +```none +set service pppoe-server authentication radius rate-limit enable +``` + +```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor \ + +**Configure the RADIUS vendor whose vendor-specific attribute carries +the rate information.** + +Use a vendor name that exists in the RADIUS dictionaries in +`/usr/share/accel-ppp/radius`. +``` + +Example: + +```none +set service pppoe-server authentication radius rate-limit vendor Mikrotik +``` + +```{cfgcmd} set service pppoe-server authentication radius rate-limit multiplier \<0.001-1000\> + +**Configure the factor by which the router multiplies the rate +received from the RADIUS server.** + +Use this option when the RADIUS server sends rates in a unit other +than kbit/s. + +The default is 1. +``` + +Example: + +```none +set service pppoe-server authentication radius rate-limit multiplier 0.001 +``` + +### RADIUS attributes + +When included in a RADIUS reply, the attributes below determine the +client's IP address and prefix assignment, taking precedence over the +corresponding CLI configuration. If an attribute is omitted, the CLI +configuration applies. + +The following table outlines the allocation behaviors for different +RADIUS attributes: + +% stop_vyoslinter + +| RADIUS attribute | Allocation behavior with the RADIUS attribute | Allocation behavior without the RADIUS attribute | +|---|---|---| +| `Framed-IP-Address` | The IPv4 address carried in the attribute is assigned directly to the client. Example: `192.0.2.50` | IPv4 address assigned from the pool set as `default-pool`. Example: `192.0.2.15` from `PPPOE-POOL` | +| `Framed-Pool` | IPv4 address assigned from a pool named by the attribute value and defined with `client-ip-pool`. Example: `198.51.100.20` from `PREMIUM-V4` | IPv4 address assigned from the pool set as `default-pool`. Example: `192.0.2.15` from `PPPOE-POOL` | +| `Stateful-IPv6-Address-Pool` | IPv6 network assigned from the prefix ranges of a pool named by the attribute value and defined with `client-ipv6-pool`. Example: `2001:db8:aaaa:20::/64` from the prefix `2001:db8:aaaa::/48` of `PREMIUM-V6` | IPv6 network assigned from the pool set as `default-ipv6-pool`. Example: `2001:db8:8002:20::/64` from `IPV6-POOL` | +| `Delegated-IPv6-Prefix-Pool` | Delegated prefix assigned from the delegate ranges of a pool named by the attribute value and defined with `client-ipv6-pool`. Example: `2001:db8:bbbb:100::/56` from the delegate `2001:db8:bbbb::/48` of `PREMIUM-V6` | Delegated prefix assigned from the pool set as `default-ipv6-pool`. Example: `2001:db8:8003::/56` from `IPV6-POOL` | + +```{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are +defined in +[RFC 6911](https://datatracker.ietf.org/doc/html/rfc6911). If your +RADIUS server does not already define them, add them to its RADIUS +dictionary using the definitions from the +[accel-ppp RFC 6911 dictionary](https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911). +``` +% start_vyoslinter + +```{note} +A session can be placed into a +{abbr}`VRF (Virtual Routing and Forwarding)` via the RADIUS +Access-Accept packet, or moved to another VRF via a CoA request, +using the `Accel-VRF-Name` attribute. It is a vendor-specific +ACCEL-PPP attribute. Define it on your RADIUS server. +``` + +### Rename client's session interfaces + +If the RADIUS server sends the `NAS-Port-Id` attribute, the router +renames the client's session interface to the attribute value. + +The value of the `NAS-Port-Id` attribute must be shorter than 16 +characters. If it is 16 characters or longer, the router cannot +rename the interface and terminates the session. + +## Automatic VLAN creation + +```{cfgcmd} set service pppoe-server interface \ vlan \<1-4094 | start-end\> + +**Configure the VLANs of the specified interface on which the PPPoE +server serves clients.** + +Specify either a single VLAN ID or a range in the form `start-end`, +for example `500-1000`. Repeat the command to combine several IDs and +ranges on the same interface. +``` + +Example: + +```none +set service pppoe-server interface eth3 vlan 100 +set service pppoe-server interface eth3 vlan 500-1000 +``` + +```{cfgcmd} set service pppoe-server interface \ combined + +**Serve clients on the base interface in addition to the VLANs +configured with `vlan`.** + +Without this option, an interface with `vlan` serves clients only on +those VLANs. +``` + +Example: + +```none +set service pppoe-server interface eth3 combined +``` + +```{cfgcmd} set service pppoe-server interface \ vlan-mon + +**Automatically create VLAN interfaces on the specified interface when +traffic arrives on the VLANs configured with `vlan`.** + +The PPPoE server removes a created VLAN interface after 60 seconds +without traffic. + +`vlan` must be configured on the same interface. Otherwise, the +commit fails. +``` + +Example: + +```none +set service pppoe-server interface eth3 vlan 100 +set service pppoe-server interface eth3 vlan-mon +``` + +## Bandwidth shaping + +Bandwidth rate limits can be set for local users or via RADIUS +attributes. + +### Local rate limits + +```{cfgcmd} set service pppoe-server authentication local-users username \ rate-limit download \<1-10000000\> + +**Limit the download bandwidth of the specified user, in kbit/s.** + +Both `download` and `upload` must be configured. Otherwise, the +commit fails. +``` + +Example: + +```none +set service pppoe-server authentication local-users username user01 rate-limit download 20480 +``` + +```{cfgcmd} set service pppoe-server authentication local-users username \ rate-limit upload \<1-10000000\> + +**Limit the upload bandwidth of the specified user, in kbit/s.** + +Both `download` and `upload` must be configured. Otherwise, the +commit fails. +``` + +Example: + +```none +set service pppoe-server authentication local-users username user01 rate-limit upload 10240 +``` + +### RADIUS rate limits + +By default, the rate information is taken from the `Filter-Id` +attribute. Configure it on the RADIUS server in the form +`Filter-Id=2000/3000`, where 2000 is the downstream rate and 3000 the +upstream rate, both in kbit/s. + +The following command enables bandwidth shaping based on the rate +information received from the RADIUS server: + +```none +set service pppoe-server authentication radius rate-limit enable +``` + +## Load balancing + +Delaying {abbr}`PADO (PPPoE Active Discovery Offer)` replies balances +sessions across PPPoE servers. Clients usually connect to the server +that answers first, so a longer delay steers new clients toward other +servers. + +```{cfgcmd} set service pppoe-server pado-delay \<1-999999\> + +**Delay PADO replies by the given number of milliseconds while the +number of active sessions stays below every count configured with +`sessions`.** + +By default, PADO replies are not delayed. Only one delay may be +configured without `sessions`, and its value cannot be `disable`. +Otherwise, the commit fails. +``` + +Example: + +```none +set service pppoe-server pado-delay 20 +``` + +```{cfgcmd} set service pppoe-server pado-delay \<1-999999 | disable\> sessions \<1-999999\> + +**Delay PADO replies by the given number of milliseconds once the +number of active sessions reaches the given count.** + +The value `disable` stops the PPPoE server from accepting new +connections at that session count. -:::{note} -Please be aware, due to an upstream bug, config -changes/commits will restart the ppp daemon and will reset existing -PPPoE connections from connected users, in order to become effective. -::: +Repeat the command with a different delay to configure several +thresholds. -## Configuring PPPoE Server +If `disable` is used, it must be configured for the highest session +count of all delays. Otherwise, the commit fails. +``` + +Example: ```none -set service pppoe-server access-concentrator PPPoE-Server -set service pppoe-server authentication mode local -set service pppoe-server authentication local-users username test password 'test' -set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 -set service pppoe-server default-pool 'PPPOE-POOL' -set service pppoe-server gateway-address 192.168.255.1 -set service pppoe-server interface eth0 +set service pppoe-server pado-delay 50 sessions 500 +set service pppoe-server pado-delay disable sessions 1000 ``` -```{cfgcmd} set service pppoe-server access-concentrator \ +## IPv6 address assignment - Use this command to set a name for this PPPoE-server access - concentrator. -``` +```{cfgcmd} set service pppoe-server ppp-options ipv6 \ +**Configure whether the PPPoE server negotiates IPv6 with clients:** -```{cfgcmd} set service pppoe-server authentication mode \ +- `require`: Requires IPv6 negotiation. +- `prefer`: Asks the client for IPv6 negotiation. Does not fail if + the client rejects it. +- `allow`: Negotiates IPv6 only if the client requests it. +- `deny`: Does not negotiate IPv6. -Set authentication backend. The configured authentication backend is used -for all queries. +The default is `deny`. +``` + +Example: -* **radius**: All authentication queries are handled by a configured RADIUS -server. -* **local**: All authentication queries are handled locally. -* **noauth**: Authentication disabled. +```none +set service pppoe-server ppp-options ipv6 allow ``` +```{cfgcmd} set service pppoe-server client-ipv6-pool \ prefix \ mask \<48-128\> -```{cfgcmd} set service pppoe-server authentication local-users username \ password \ +**Configure an IPv6 prefix as part of the named client pool.** -Create `` for local authentication on this system. The users password -will be set to ``. -``` +From this prefix, each client is assigned an individual network of +the configured `mask` length. The client forms its address inside +that network. +Repeat the command to add several prefixes to the same pool. + +The default mask is 64. +``` -```{cfgcmd} set service pppoe-server client-ip-pool \ range \ +Example: -Use this command to define the first IP address of a pool of -addresses to be given to pppoe 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. +```none +set service pppoe-server client-ipv6-pool IPV6-POOL prefix 2001:db8:8002::/48 mask 64 ``` +```{cfgcmd} set service pppoe-server client-ipv6-pool \ delegate \ delegation-prefix \<32-64\> -```{cfgcmd} set service pppoe-server default-pool \ +**Configure an IPv6 prefix from which the named pool delegates +prefixes of the configured `delegation-prefix` length to clients via +DHCPv6 prefix delegation +([RFC 3633](https://datatracker.ietf.org/doc/html/rfc3633)).** -Use this command to define default address pool name. -``` +Repeat the command to add several prefixes to the same pool. +The same pool must also have a `prefix` configured with +`client-ipv6-pool prefix`. Otherwise, the commit fails. +``` -```{cfgcmd} set service pppoe-server interface \ +Example: -Use this command to define the interface the PPPoE server will use to -listen for PPPoE clients. +```none +set service pppoe-server client-ipv6-pool IPV6-POOL prefix 2001:db8:8002::/48 mask 64 +set service pppoe-server client-ipv6-pool IPV6-POOL delegate 2001:db8:8003::/48 delegation-prefix 56 ``` +```{cfgcmd} set service pppoe-server default-ipv6-pool \ -```{cfgcmd} set service pppoe-server gateway-address \ +**Configure the client pool from which IPv6 addresses and delegated +prefixes are assigned by default.** -Specifies single `` IP address to be used as local address of PPP -interfaces. -``` +A RADIUS-provided pool, when present, takes precedence. -## Configuring RADIUS authentication +In `local` and `noauth` authentication modes, if at least one +`client-ipv6-pool` is configured but `default-ipv6-pool` is not set, +the commit succeeds with a warning. +``` -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. +Example: ```none -set service pppoe-server authentication mode radius +set service pppoe-server default-ipv6-pool IPV6-POOL ``` -```{cfgcmd} set service pppoe-server authentication radius server \ key \ +### Advanced options -Configure RADIUS `` and its required shared `` for -communicating with the RADIUS server. +```{cfgcmd} set service pppoe-server ppp-options ipv6-accept-peer-interface-id + +**Accept the interface identifier that the client proposes for its own +side of the session during IPv6 negotiation +([RFC 5072](https://datatracker.ietf.org/doc/html/rfc5072)).** + +By default, the router does not accept it and uses the identifier +from `ipv6-peer-interface-id` instead. ``` -Since the RADIUS server would be a single point of failure, multiple RADIUS -servers can be setup and will be used subsequentially. -For example: +Example: ```none -set service pppoe-server authentication radius server 10.0.0.1 key 'foo' -set service pppoe-server authentication radius server 10.0.0.2 key 'foo' +set service pppoe-server ppp-options ipv6-accept-peer-interface-id ``` -:::{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. -::: - +```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \ -### RADIUS source address +**Configure the interface identifier used on the router's side of +client sessions:** +- `x:x:x:x`: Use the given fixed interface identifier. +- `random`: Use a random interface identifier. -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. +By default, a fixed interface identifier is used. +``` -```{cfgcmd} set service pppoe-server authentication radius source-address \ +Example: -Source IPv4 address used in all RADIUS server queries. +```none +set service pppoe-server ppp-options ipv6-interface-id random ``` -:::{note} -The `source-address` must be configured on one of VyOS interface. -Best practice would be a loopback or dummy interface. -::: +```{cfgcmd} set service pppoe-server ppp-options ipv6-peer-interface-id \ +**Configure the interface identifier used on the client's side of +sessions:** -### RADIUS advanced options +- `x:x:x:x`: Use the given fixed interface identifier. +- `random`: Use a random interface identifier. +- `ipv4-addr`: Derive the interface identifier from the client's IPv4 + address, for example `192:168:0:1`. +- `calling-sid`: Derive the interface identifier from the client's + calling station ID. With `calling-sid`, + `ipv6-peer-interface-id-secret` must also be configured. Otherwise, + the commit fails. +``` -```{cfgcmd} set service pppoe-server authentication radius server \ port \ +Example: -Configure RADIUS `` and its required port for authentication requests. +```none +set service pppoe-server ppp-options ipv6-peer-interface-id calling-sid +set service pppoe-server ppp-options ipv6-peer-interface-id-secret 'ChangeMeToARandomKey1234' ``` +```{cfgcmd} set service pppoe-server ppp-options ipv6-peer-interface-id-secret \ -```{cfgcmd} set service pppoe-server authentication radius server \ fail-time \ +**Configure the secret key used to derive client interface identifiers +when `ipv6-peer-interface-id` is set to `calling-sid`.** -Mark RADIUS server as offline for this given `