diff options
| -rw-r--r-- | docs/configuration/service/pppoe-server.md | 1615 |
1 files changed, 1267 insertions, 348 deletions
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 \<name\> -:::{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. -::: +**Configure the access concentrator name that the PPPoE server +announces to clients during PPPoE discovery.** -## Configuring PPPoE Server +The name may contain letters, digits, hyphens, and underscores. -```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 +The default is `vyos-ac`. ``` -```{cfgcmd} set service pppoe-server access-concentrator \<name\> +Example: - Use this command to set a name for this PPPoE-server access - concentrator. +```none +set service pppoe-server access-concentrator PPPoE-AC-01 ``` +```{cfgcmd} set service pppoe-server authentication mode \<local | radius | noauth\> -```{cfgcmd} set service pppoe-server authentication mode \<local | radius\> +**Configure how the PPPoE server authenticates clients:** -Set authentication backend. The configured authentication backend is used -for all queries. +- `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. -* **radius**: All authentication queries are handled by a configured RADIUS -server. -* **local**: All authentication queries are handled locally. -* **noauth**: Authentication disabled. +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 \<name\> password \<password\> -Create `<user>` for local authentication on this system. The users password -will be set to `<pass>`. +**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: -```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> +```none +set service pppoe-server authentication local-users username user01 password secret +``` + +```{cfgcmd} set service pppoe-server client-ip-pool \<name\> range \<x.x.x.x/x | x.x.x.x-x.x.x.x\> + +**Configure an IPv4 address range as part of the named client pool.** -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. +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 \<name\> -```{cfgcmd} set service pppoe-server default-pool \<POOL-NAME\> +**Configure the client pool from which IPv4 addresses are assigned by +default.** -Use this command to define default address pool name. +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 \<interface\> -Use this command to define the interface the PPPoE server will use to -listen for PPPoE clients. +**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: -```{cfgcmd} set service pppoe-server gateway-address \<address\> +```none +set service pppoe-server interface eth1 +``` + +```{cfgcmd} set service pppoe-server gateway-address \<ipv4-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 \<ipv4-address\> key \<secret\> + +**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. -Specifies single `<gateway>` IP address to be used as local address of PPP -interfaces. +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. ``` -## Configuring RADIUS authentication +```{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. +``` -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 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 \<ipv4-address\> 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 \<server\> key \<secret\> +```{cfgcmd} set service pppoe-server authentication radius server \<ipv4-address\> backup -Configure RADIUS `<server>` and its required shared `<secret>` for -communicating with the RADIUS server. +**Configure the specified RADIUS server as a backup, used only when +all other servers have failed.** ``` -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 authentication radius server 198.51.100.10 backup ``` -:::{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. -::: +### 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. -### RADIUS source address +```{cfgcmd} set service pppoe-server authentication radius source-address \<ipv4-address\> +**Configure the source IPv4 address used in all queries to RADIUS +servers.** -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. +Use an address configured on one of the router's interfaces. +Typically, this is a loopback or dummy interface address. +``` -```{cfgcmd} set service pppoe-server authentication radius source-address \<address\> +Example: -Source IPv4 address used in all RADIUS server queries. +```none +set service pppoe-server authentication radius source-address 192.0.2.1 ``` -:::{note} -The `source-address` must be configured on one of VyOS interface. -Best practice would be a loopback or dummy interface. -::: +### Advanced options +```{cfgcmd} set service pppoe-server authentication radius server \<ipv4-address\> port \<1-65535\> -### RADIUS advanced options +**Configure the UDP port the router uses to send client +authentication requests to the specified RADIUS server.** -```{cfgcmd} set service pppoe-server authentication radius server \<server\> port \<port\> +The default is 1812. +``` + +Example: -Configure RADIUS `<server>` and its required port for authentication requests. +```none +set service pppoe-server authentication radius server 198.51.100.9 port 1645 ``` +```{cfgcmd} set service pppoe-server authentication radius server \<ipv4-address\> acct-port \<1-65535\> -```{cfgcmd} set service pppoe-server authentication radius server \<server\> fail-time \<time\> +**Configure the UDP port to which the router sends accounting +requests for the specified RADIUS server.** -Mark RADIUS server as offline for this given `<time>` in seconds. +The default is 1813. ``` +Example: -```{cfgcmd} set service pppoe-server authentication radius server \<server\> disable +```none +set service pppoe-server authentication radius server 198.51.100.9 acct-port 1646 +``` + +```{cfgcmd} set service pppoe-server authentication radius server \<ipv4-address\> 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 \<ipv4-address\> 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 \<ipv4-address\> 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 +``` -Temporary disable this RADIUS server. +```{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. +``` -```{cfgcmd} set service pppoe-server authentication radius acct-timeout \<timeout\> +Example: -Timeout to wait reply for Interim-Update packets. (default 3 seconds) +```none +set service pppoe-server authentication radius acct-interim-jitter 10 ``` +```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \<ipv4-address\> + +**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. -```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \<address\> +`dynamic-author key` must also be configured. Otherwise, the commit +fails. +``` + +Example: -Specifies IP address for Dynamic Authorization Extension server (DM/CoA). -This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +```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\> -```{cfgcmd} set service pppoe-server authentication radius dynamic-author port \<port\> +**Configure the UDP port on which the router accepts CoA and +Disconnect requests.** -UDP port for Dynamic Authorization Extension server (DM/CoA) +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 \<secret\> -Secret for Dynamic Authorization Extension server (DM/CoA) +**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. +``` -```{cfgcmd} set service pppoe-server authentication radius max-try \<number\> +Example: -Maximum number of tries to send Access-Request/Accounting-Request queries +```none +set service pppoe-server authentication radius max-try 5 ``` +```{cfgcmd} set service pppoe-server authentication radius timeout \<1-60\> -```{cfgcmd} set service pppoe-server authentication radius timeout \<timeout\> +**Configure the time, in seconds, to wait for a reply from a RADIUS +server.** -Timeout to wait response from server (seconds) +The default is 3. ``` +Example: + +```none +set service pppoe-server authentication radius timeout 10 +``` ```{cfgcmd} set service pppoe-server authentication radius nas-identifier \<identifier\> -Value to send to RADIUS server in NAS-Identifier attribute and to be matched -in DM/CoA requests. +**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 \<ipv4-address\> -```{cfgcmd} set service pppoe-server authentication radius nas-ip-address \<address\> +**Configure the IPv4 address the router sends to RADIUS servers in +the NAS-IP-Address attribute.** -Value to send to RADIUS server in NAS-IP-Address attribute and to be matched -in DM/CoA requests. Also DM/CoA server will bind to that address. +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 source-address \<address\> +```{cfgcmd} set service pppoe-server authentication radius preallocate-vif -Source IPv4 address used in all RADIUS server queries. +**Create the PPP interface of a session before authentication, so +that the router can send NAS-Port-Id in the Access-Request.** ``` +Example: -```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \<attribute\> +```none +set service pppoe-server authentication radius preallocate-vif +``` + +```{cfgcmd} set service pppoe-server authentication radius called-sid-format \<ifname | ifname:mac\> -Specifies which RADIUS server attribute contains the rate limit information. -The default attribute is ``Filter-Id``. +**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`. ``` -:::{note} -If you set a custom RADIUS attribute you must define it on both -dictionaries at RADIUS server and client. -::: +Example: -```{cfgcmd} set service pppoe-server authentication radius rate-limit enable +```none +set service pppoe-server authentication radius called-sid-format ifname:mac +``` -Enables bandwidth shaping via RADIUS. +```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \<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: -```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor +```none +set service pppoe-server authentication radius rate-limit attribute Mikrotik-Rate-Limit +``` + +```{cfgcmd} set service pppoe-server authentication radius rate-limit enable -Specifies the vendor dictionary, dictionary needs to be in -/usr/share/accel-ppp/radius. +**Enable bandwidth shaping of client sessions based on rate +information received from the RADIUS server.** ``` -Received RADIUS attributes have a higher priority than parameters defined within -the CLI configuration, refer to the explanation below. +Example: + +```none +set service pppoe-server authentication radius rate-limit enable +``` +```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor \<vendor\> -### Allocation clients ip addresses by RADIUS +**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`. +``` -If the RADIUS server sends the attribute `Framed-IP-Address` then this IP -address will be allocated to the client and the option `default-pool` -within the CLI config is being ignored. +Example: +```none +set service pppoe-server authentication radius rate-limit vendor Mikrotik +``` -If the RADIUS server sends the attribute `Framed-Pool`, IP address will -be allocated from a predefined IP pool whose name equals the attribute value. +```{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.** -If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, -IPv6 address will be allocated from a predefined IPv6 pool `prefix` -whose name equals the attribute value. +Use this option when the RADIUS server sends rates in a unit other +than kbit/s. +The default is 1. +``` -If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, -IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate` -whose name equals the attribute value. +Example: +```none +set service pppoe-server authentication radius rate-limit multiplier 0.001 +``` -:::{note} -`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` -are defined in RFC6911. If they are not defined in your RADIUS server, -add new [dictionary]. -::: +### 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. -User interface can be put to VRF context via RADIUS Access-Accept packet, -or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. -It is custom [ACCEL-PPP attribute]. Define it in your RADIUS server. +The following table outlines the allocation behaviors for different +RADIUS attributes: +% stop_vyoslinter -### Renaming clients interfaces by RADIUS +| 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 -If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be -renamed. +```{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 -:::{note} -The value of the attribute `NAS-Port-Id` must be less than 16 -characters, otherwise the interface won't be renamed. -::: +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 +## Automatic VLAN creation -```{cfgcmd} set service pppoe-server interface \<interface\> vlan \<id | range\> +```{cfgcmd} set service pppoe-server interface \<interface\> vlan \<1-4094 | start-end\> -VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module -named ``vlan_mon``, which is monitoring incoming vlans and creates the -necessary VLAN if required and allowed. VyOS supports the use of either -VLAN ID's or entire ranges, both values can be defined at the same time for -an interface. +**Configure the VLANs of the specified interface on which the PPPoE +server serves clients.** -When configured, PPPoE will create the necessary VLANs when required. Once -the user session has been cancelled and the VLAN is not needed anymore, VyOS -will remove it again. +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 200 set service pppoe-server interface eth3 vlan 500-1000 -set service pppoe-server interface eth3 vlan 2000-3000 ``` -## Bandwidth Shaping +```{cfgcmd} set service pppoe-server interface \<interface\> combined +**Serve clients on the base interface in addition to the VLANs +configured with `vlan`.** -Bandwidth rate limits can be set for local users or RADIUS based +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 \<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 \<name\> rate-limit download \<1-10000000\> -### For Local Users +**Limit the download bandwidth of the specified user, in kbit/s.** + +Both `download` and `upload` must be configured. Otherwise, the +commit fails. +``` -```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit download \<bandwidth\> +Example: -Download bandwidth limit in kbit/s for `<user>`. +```none +set service pppoe-server authentication local-users username user01 rate-limit download 20480 ``` +```{cfgcmd} set service pppoe-server authentication local-users username \<name\> rate-limit upload \<1-10000000\> -```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit upload \<bandwidth\> +**Limit the upload bandwidth of the specified user, in kbit/s.** -Upload bandwidth limit in kbit/s for `<user>`. +Both `download` and `upload` must be configured. Otherwise, the +commit fails. ``` + +Example: + ```none -set service pppoe-server access-concentrator 'ACN' -set service pppoe-server authentication local-users username foo password 'bar' -set service pppoe-server authentication local-users username foo rate-limit download '20480' -set service pppoe-server authentication local-users username foo rate-limit upload '10240' -set service pppoe-server authentication mode 'local' -set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' -set service pppoe-server default-pool 'IP-POOL' -set service pppoe-server name-server '10.100.100.1' -set service pppoe-server name-server '10.100.200.1' -set service pppoe-server interface 'eth1' -set service pppoe-server gateway-address '10.1.1.2' +set service pppoe-server authentication local-users username user01 rate-limit upload 10240 ``` -Once the user is connected, the user session is using the set limits and -can be displayed via `show pppoe-server sessions`. +### 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 -show pppoe-server sessions -ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes --------+----------+------------+-------------------+-------------+--------+----------+----------+---------- -ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +set service pppoe-server authentication radius rate-limit enable ``` -### For RADIUS users +## Load balancing -The current attribute `Filter-Id` is being used as default and can be -setup within RADIUS: +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. -Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit -up-stream rate) +```{cfgcmd} set service pppoe-server pado-delay \<1-999999\> -The command below enables it, assuming the RADIUS connection has been -setup and is working. +**Delay PADO replies by the given number of milliseconds while the +number of active sessions stays below every count configured with +`sessions`.** -```{cfgcmd} set service pppoe-server authentication radius rate-limit enable +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. +``` - Use this command to enable bandwidth shaping via RADIUS. +Example: + +```none +set service pppoe-server pado-delay 20 ``` -Other attributes can be used, but they have to be in one of the -dictionaries in */usr/share/accel-ppp/radius*. +```{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.** -## Load Balancing +The value `disable` stops the PPPoE server from accepting new +connections at that session count. -```{cfgcmd} set service pppoe-server pado-delay \<number-of-ms\> sessions \<number-of-sessions\> +Repeat the command with a different delay to configure several +thresholds. -Use this command to enable the delay of PADO (PPPoE Active Discovery -Offer) packets, which can be used as a session balancing mechanism -with other PPPoE servers. +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 pado-delay 50 sessions '500' -set service pppoe-server pado-delay 100 sessions '1000' -set service pppoe-server pado-delay 300 sessions '3000' +set service pppoe-server pado-delay 50 sessions 500 +set service pppoe-server pado-delay disable sessions 1000 ``` -In the example above, the first 499 sessions connect without delay. PADO -packets will be delayed 50 ms for connection from 500 to 999, this trick -allows other PPPoE servers send PADO faster and clients will connect to -other servers. Last command says that this PPPoE server can serve only -3000 clients. +## IPv6 address assignment + +```{cfgcmd} set service pppoe-server ppp-options ipv6 \<require | prefer | allow | deny\> +**Configure whether the PPPoE server negotiates IPv6 with clients:** -## IPv6 +- `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. -```{cfgcmd} set service pppoe-server ppp-options ipv6 \<require | prefer | allow | deny\> +The default is `deny`. +``` -Specifies IPv6 negotiation preference. +Example: -* **require** - Require IPv6 negotiation -* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects -* **allow** - Negotiate IPv6 only if client requests -* **deny** - Do not negotiate IPv6 (default value) +```none +set service pppoe-server ppp-options ipv6 allow ``` +```{cfgcmd} set service pppoe-server client-ipv6-pool \<name\> prefix \<ipv6net\> mask \<48-128\> + +**Configure an IPv6 prefix as part of the named client pool.** + +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. -```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> +The default mask is 64. +``` + +Example: -Use this command to set the IPv6 address pool from which a PPPoE client -will get an IPv6 prefix of your defined length (mask) to terminate the -PPPoE endpoint at their side. The mask length can be set from 48 to 128 -bit long, the default value is 64. +```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 \<name\> delegate \<ipv6net\> delegation-prefix \<32-64\> + +**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)).** -```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> +Repeat the command to add several prefixes to the same pool. -Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on -PPPoE. You will have to set your IPv6 pool and the length of the -delegation prefix. From the defined IPv6 pool you will be handing out -networks of the defined length (delegation-prefix). The length of the -delegation prefix can be set from 32 to 64 bit long. +The same pool must also have a `prefix` configured with +`client-ipv6-pool <name> prefix`. Otherwise, the commit fails. +``` + +Example: + +```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 \<name\> -```{cfgcmd} set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\> +**Configure the client pool from which IPv6 addresses and delegated +prefixes are assigned by default.** -Use this command to define default IPv6 address pool name. +A RADIUS-provided pool, when present, takes precedence. + +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. ``` +Example: ```none -set service pppoe-server ppp-options ipv6 allow -set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' -set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' -set service pppoe-server default-ipv6-pool IPv6-POOL +set service pppoe-server default-ipv6-pool IPV6-POOL ``` -### IPv6 Advanced Options +### Advanced options ```{cfgcmd} set service pppoe-server ppp-options ipv6-accept-peer-interface-id -Accept peer interface identifier. By default is not defined. +**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. +``` + +Example: + +```none +set service pppoe-server ppp-options ipv6-accept-peer-interface-id +``` + +```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<x:x:x:x | random\> + +**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. + +By default, a fixed interface identifier is used. +``` + +Example: + +```none +set service pppoe-server ppp-options ipv6-interface-id random ``` +```{cfgcmd} set service pppoe-server ppp-options ipv6-peer-interface-id \<x:x:x:x | random | ipv4-addr | calling-sid\> -```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\> +**Configure the interface identifier used on the client's side of +sessions:** -Specifies fixed or random interface identifier for IPv6. -By default is fixed. +- `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. +``` + +Example: -* **random** - Random interface identifier for IPv6 -* **x:x:x:x** - Specify interface identifier for IPv6 +```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 \<secret\> + +**Configure the secret key used to derive client interface identifiers +when `ipv6-peer-interface-id` is set to `calling-sid`.** -```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\> +The secret must be 16 to 128 characters long. It may contain ASCII +letters, digits, and symbols, but not spaces. +``` -Specifies peer interface identifier for IPv6. By default is fixed. +Example: -* **random** - Random interface identifier for IPv6 -* **x:x:x:x** - Specify interface identifier for IPv6 -* **ipv4-addr** - Calculate interface identifier from IPv4 address. -* **calling-sid** - Calculate interface identifier from calling-station-id. +```none +set service pppoe-server ppp-options ipv6-peer-interface-id-secret 'ChangeMeToARandomKey1234' ``` ## Scripting -```{cfgcmd} set service pppoe-server extended-scripts on-change \<path_to_script\> +Store scripts under `/config` so that they are migrated to a new +image when the system is upgraded. + +```{cfgcmd} set service pppoe-server extended-scripts on-change \<path\> + +**Configure a script to run when the router changes a session +interface upon a RADIUS CoA request.** -Script to run when session interface changed by RADIUS CoA handling +The script file must exist and be executable. Otherwise, the commit +fails. ``` +Example: -```{cfgcmd} set service pppoe-server extended-scripts on-down \<path_to_script\> +```none +set service pppoe-server extended-scripts on-change /config/scripts/pppoe-change.sh +``` + +```{cfgcmd} set service pppoe-server extended-scripts on-down \<path\> + +**Configure a script to run when a client session is about to +terminate.** -Script to run when session interface going to terminate +The script file must exist and be executable. Otherwise, the commit +fails. +``` + +Example: + +```none +set service pppoe-server extended-scripts on-down /config/scripts/pppoe-down.sh ``` +```{cfgcmd} set service pppoe-server extended-scripts on-pre-up \<path\> -```{cfgcmd} set service pppoe-server extended-scripts on-pre-up \<path_to_script\> +**Configure a script to run before the PPP interface of a client +session comes up.** -Script to run before session interface comes up +The script file must exist and be executable. Otherwise, the commit +fails. ``` +Example: -```{cfgcmd} set service pppoe-server extended-scripts on-up \<path_to_script\> +```none +set service pppoe-server extended-scripts on-pre-up /config/scripts/pppoe-pre-up.sh +``` + +```{cfgcmd} set service pppoe-server extended-scripts on-up \<path\> -Script to run when session interface is completely configured and started +**Configure a script to run when the PPP interface of a client session +is completely configured and started.** + +The script file must exist and be executable. Otherwise, the commit +fails. ``` -## Advanced Options +Example: +```none +set service pppoe-server extended-scripts on-up /config/scripts/pppoe-up.sh +``` + +## Advanced options -### Authentication Advanced Options +### Authentication -```{cfgcmd} set service pppoe-server authentication local-users username \<user\> disable +```{cfgcmd} set service pppoe-server authentication local-users username \<name\> disable -Disable `<user>` account. +**Disable the specified user account without removing it from the +configuration.** ``` +Example: -```{cfgcmd} set service pppoe-server authentication local-users username \<user\> static-ip \<address\> +```none +set service pppoe-server authentication local-users username user01 disable +``` -Assign static IP address to `<user>` account. +```{cfgcmd} set service pppoe-server authentication local-users username \<name\> static-ip \<ipv4-address\> + +**Assign a fixed IPv4 address to the specified user.** + +Without this option, the user's address is allocated from the pool +set as `default-pool`. ``` +Example: + +```none +set service pppoe-server authentication local-users username user01 static-ip 192.0.2.50 +``` ```{cfgcmd} set service pppoe-server authentication protocols \<pap | chap | mschap | mschap-v2\> -Require the peer to authenticate itself using one of the following protocols: -pap, chap, mschap, mschap-v2. +**Configure the authentication protocols the PPPoE server accepts +from clients:** + +- `pap`: Password Authentication Protocol + ([RFC 1334](https://datatracker.ietf.org/doc/html/rfc1334)) +- `chap`: Challenge Handshake Authentication Protocol + ([RFC 1994](https://datatracker.ietf.org/doc/html/rfc1994)) +- `mschap`: Microsoft CHAP + ([RFC 2433](https://datatracker.ietf.org/doc/html/rfc2433)) +- `mschap-v2`: Microsoft CHAP version 2 + ([RFC 2759](https://datatracker.ietf.org/doc/html/rfc2759)) + +Repeat the command to accept several protocols. + +By default, all four protocols are accepted. ``` -### Client IP Pool Advanced Options +Example: -```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> +```none +set service pppoe-server authentication protocols mschap-v2 +``` + +```{cfgcmd} set service pppoe-server authentication any-login + +**Accept any username during PAP, CHAP, and MS-CHAPv1 +authentication.** + +The password is still checked. MS-CHAPv2 is not covered by this +option. +``` + +Example: + +```none +set service pppoe-server authentication any-login +``` + +### Client IP pool + +```{cfgcmd} set service pppoe-server client-ip-pool \<name\> next-pool \<name\> -Use this command to define the next address pool name. +**Configure the next pool, from which client addresses are allocated +once the specified client pool is exhausted.** + +The following requirements are enforced when the configuration is +committed: + +- The specified client pool must have a `range`. +- The pool named in `next-pool` must be configured under + `client-ip-pool`. +- The chain of pools must not form a loop. ``` -### PPP Advanced Options +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 OVERFLOW-POOL range 198.51.100.10-198.51.100.99 +set service pppoe-server client-ip-pool PPPOE-POOL next-pool OVERFLOW-POOL +``` + +### PPP ```{cfgcmd} set service pppoe-server ppp-options disable-ccp -Disable Compression Control Protocol (CCP). -CCP is enabled by default. +**Disable {abbr}`CCP (Compression Control Protocol)` negotiation with +clients.** + +CCP ([RFC 1962](https://datatracker.ietf.org/doc/html/rfc1962)) is +the part of PPP where the two ends of a session agree on compressing +session traffic. By default, the PPPoE server negotiates CCP. + +{abbr}`MPPE (Microsoft Point-to-Point Encryption)` is negotiated as +part of CCP, so `disable-ccp` also disables MPPE, whatever +`ppp-options mppe` is set to. +``` + +Example: + +```none +set service pppoe-server ppp-options disable-ccp ``` +```{cfgcmd} set service pppoe-server ppp-options interface-cache \<1-256000\> -```{cfgcmd} set service pppoe-server ppp-options interface-cache \<number\> +**Configure the number of PPP interfaces kept in a cache after their +sessions end, for reuse by new sessions.** -Specifies number of interfaces to keep in cache. It means that don’t -destroy interface after corresponding session is destroyed, instead -place it to cache and use it later for new sessions repeatedly. -This should reduce kernel-level interface creation/deletion rate lack. -Default value is **0**. +Reusing cached interfaces reduces how often the kernel creates and +deletes interfaces. + +By default, interfaces are not cached. ``` +Example: + +```none +set service pppoe-server ppp-options interface-cache 1000 +``` ```{cfgcmd} set service pppoe-server ppp-options ipv4 \<require | prefer | allow | deny\> -Specifies IPv4 negotiation preference. +**Configure whether the PPPoE server negotiates IPv4 with clients:** -* **require** - Require IPv4 negotiation -* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects -* **allow** - Negotiate IPv4 only if client requests (Default value) -* **deny** - Do not negotiate IPv4 +- `require`: Requires IPv4 negotiation. +- `prefer`: Asks the client for IPv4 negotiation. Does not fail if + the client rejects it. +- `allow`: Negotiates IPv4 only if the client requests it. +- `deny`: Does not negotiate IPv4. ``` +Example: + +```none +set service pppoe-server ppp-options ipv4 require +``` ```{cfgcmd} set service pppoe-server ppp-options lcp-echo-failure \<number\> -Defines the maximum `<number>` of unanswered echo requests. Upon reaching the -value `<number>`, the session will be reset. Default value is **3**. +**Configure the maximum number of {abbr}`LCP (Link Control Protocol)` +Echo-Request packets the PPPoE server may send without receiving a +valid reply.** + +When the limit is exceeded, the session is terminated. The value must +be a positive integer. + +The default is 3. ``` +Example: + +```none +set service pppoe-server ppp-options lcp-echo-failure 5 +``` ```{cfgcmd} set service pppoe-server ppp-options lcp-echo-interval \<interval\> -If this option is specified and is greater than 0, then the PPP module will -send LCP pings of the echo request every `<interval>` seconds. -Default value is **30**. +**Configure the interval, in seconds, between LCP Echo-Request packets +sent to the client.** + +The value must be a positive integer. + +The default is 30. +``` + +Example: + +```none +set service pppoe-server ppp-options lcp-echo-interval 10 ``` +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-timeout \<timeout\> + +**Configure the time, in seconds, to wait for any client activity.** + +Setting this option enables adaptive LCP echo, and `lcp-echo-failure` +is then not used. The value must be a positive integer. -```{cfgcmd} set service pppoe-server ppp-options lcp-echo-timeout +The default is 0, which leaves adaptive LCP echo off. +``` + +Example: -Specifies timeout in seconds to wait for any peer activity. If this option -specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" -is not used. Default value is **0**. +```none +set service pppoe-server ppp-options lcp-echo-timeout 120 ``` +```{cfgcmd} set service pppoe-server ppp-options min-mtu \<68-65535\> + +**Configure the smallest +{abbr}`MTU (Maximum Transmission Unit)` value, in bytes, that the +PPPoE server accepts from clients.** -```{cfgcmd} set service pppoe-server ppp-options min-mtu \<number\> +If a client tries to negotiate a lower MTU, the PPPoE server rejects +the value and suggests an acceptable one. If the client also rejects +the greater MTU, the PPPoE server disconnects it. -Defines minimum acceptable MTU. If client will try to negotiate less then -specified MTU then it will be NAKed or disconnected if rejects greater MTU. -Default value is **100**. +The default is 1280. ``` +Example: + +```none +set service pppoe-server ppp-options min-mtu 1400 +``` ```{cfgcmd} set service pppoe-server ppp-options mppe \<require | prefer | deny\> -Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation -preference. +**Configure the negotiation of MPPE with clients:** + +- `require`: Ask the client for MPPE. If the client rejects it, drop + the connection. +- `prefer`: Ask the client for MPPE. If the client rejects it, + continue without MPPE. +- `deny`: Do not use MPPE. -* **require** - ask client for mppe, if it rejects drop connection -* **prefer** - ask client for mppe, if it rejects don't fail. (Default value) -* **deny** - deny mppe +The default is `prefer`. -Default behavior - don't ask client for mppe, but allow it if client wants. -Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy -attribute. +A RADIUS server may override this option with the +MS-MPPE-Encryption-Policy attribute. +``` + +Example: + +```none +set service pppoe-server ppp-options mppe require ``` +```{cfgcmd} set service pppoe-server ppp-options mru \<68-65535\> -```{cfgcmd} set service pppoe-server ppp-options mru \<number\> +**Configure the preferred {abbr}`MRU (Maximum Receive Unit)`, in +bytes, that the PPPoE server announces to clients.** -Defines preferred MRU. By default is not defined. +By default, no preferred MRU is configured. ``` -### Global Advanced options +Example: + +```none +set service pppoe-server ppp-options mru 1492 +``` + +### Global ```{cfgcmd} set service pppoe-server description \<description\> -Set description. +**Set a description for the PPPoE server configuration.** + +The description may be up to 255 characters long. ``` +Example: + +```none +set service pppoe-server description 'PPPoE access for example.com subscribers' +``` ```{cfgcmd} set service pppoe-server limits burst \<value\> -Burst count +**Configure how many PPPoE discovery requests the PPPoE server accepts +from a single client before it enforces the rate set with +`limits connection-limit`.** ``` +Example: -```{cfgcmd} set service pppoe-server limits connection-limit \<value\> +```none +set service pppoe-server limits burst 100 +``` + +```{cfgcmd} set service pppoe-server limits connection-limit \<n/min | n/sec\> + +**Configure the rate of PPPoE discovery requests the PPPoE server +accepts from a single client, for example `10/min` or `60/sec`.** -Acceptable rate of connections (e.g. 1/min, 60/sec) +Requests above this rate are ignored, so the client receives no +reply. ``` +Example: + +```none +set service pppoe-server limits connection-limit 10/min +``` ```{cfgcmd} set service pppoe-server limits timeout \<value\> -Timeout in seconds +**Configure how long, in seconds, a single client must send no +requests for its request count to be reset.** +``` + +Example: + +```none +set service pppoe-server limits timeout 60 +``` + +```{cfgcmd} set service pppoe-server log level \<0-5\> + +**Configure how much detail the PPPoE server writes to the system +log:** + +- `0`: Nothing. +- `1`: Errors. +- `2`: Errors and warnings. +- `3`: Errors, warnings, and basic information. +- `4`: Errors, warnings, and full information. +- `5`: Everything, including debug messages. + +The default is 3. ``` +Example: -```{cfgcmd} set service pppoe-server mtu +```none +set service pppoe-server log level 4 +``` + +```{cfgcmd} set service pppoe-server mtu \<128-16384\> + +**Configure the MTU for client sessions, in bytes.** -Maximum Transmission Unit (MTU) (default: **1492**) +The default is 1492. +``` + +Example: + +```none +set service pppoe-server mtu 1460 ``` +```{cfgcmd} set service pppoe-server max-concurrent-sessions \<0-65535\> -```{cfgcmd} set service pppoe-server max-concurrent-sessions +**Limits how many client sessions may start at the same time.** -Maximum number of concurrent session start attempts +The value 0 means no limit. By default, the number of sessions +starting at the same time is not limited. ``` +Example: + +```none +set service pppoe-server max-concurrent-sessions 100 +``` ```{cfgcmd} set service pppoe-server name-server \<address\> -Connected client should use `<address>` as their DNS server. This -command accepts both IPv4 and IPv6 addresses. Up to two nameservers -can be configured for IPv4, up to three for IPv6. +**Configure a DNS server address that clients should use.** + +Repeat the command to configure multiple addresses. Both IPv4 and +IPv6 addresses are accepted. At most two IPv4 and three IPv6 name +servers may be configured. Otherwise, the commit fails. +``` + +Example: + +```none +set service pppoe-server name-server 192.0.2.53 +set service pppoe-server name-server 2001:db8::53 +``` + +```{cfgcmd} set service pppoe-server service-name \<name\> + +**Configure a Service-Name the PPPoE server answers to during PPPoE +discovery ([RFC 2516](https://datatracker.ietf.org/doc/html/rfc2516)).** + +The name may be up to 100 characters long and may contain letters, +digits, and hyphens. + +Repeat the command to configure multiple service names. + +If no service name is configured, the PPPoE server accepts any +Service-Name and echoes the client's Service-Name back. +``` + +Example: + +```none +set service pppoe-server service-name internet +``` + +```{cfgcmd} set service pppoe-server accept-any-service + +**Accept any Service-Name in a PADR request, while still announcing +the names configured with `service-name`.** + +Use this option when clients select the PPPoE server by the +Service-Name they see in PADO replies. +``` + +Example: + +```none +set service pppoe-server accept-any-service ``` +```{cfgcmd} set service pppoe-server accept-blank-service -```{cfgcmd} set service pppoe-server service-name \<names\> +**Accept a blank Service-Name even when `service-name` is +configured.** +``` -Specifies Service-Name to respond. If absent any Service-Name is -acceptable and client’s Service-Name will be sent back. Also possible -set multiple service-names: `sn1,sn2,sn3` +Example: + +```none +set service pppoe-server accept-blank-service ``` -Per default the user session is being replaced if a second -authentication request succeeds. Such session requests can be either -denied or allowed entirely, which would allow multiple sessions for a -user in the latter case. If it is denied, the second session is being -rejected even if the authentication succeeds, the user has to terminate -its first session and can then authentication again. +```{cfgcmd} set service pppoe-server session-control \<deny | disable | replace\> -```{cfgcmd} set service pppoe-server session-control +**Configure what happens when a user who already has an active +session is authorized for a second session:** -* **disable**: Disables session control. -* **deny**: Deny second session authorization. -* **replace**: Terminate first session when second is authorized **(default)** +- `deny`: Deny the second session. +- `disable`: Disable session control. Users may hold multiple + sessions at once. +- `replace`: Terminate the first session when the second one is + authorized. + +The default is `replace`. ``` +Example: + +```none +set service pppoe-server session-control deny +``` ```{cfgcmd} set service pppoe-server shaper fwmark \<1-2147483647\> -Match firewall mark value +**Exclude traffic carrying the given firewall mark from bandwidth +shaping.** ``` +Example: + +```none +set service pppoe-server shaper fwmark 223 +``` ```{cfgcmd} set service pppoe-server snmp master-agent -Enable SNMP +**Configure the PPPoE server to serve +{abbr}`SNMP (Simple Network Management Protocol)` requests for its +own statistics.** + +By default, the PPPoE server does not serve these requests itself. +``` + +Example: + +```none +set service pppoe-server snmp master-agent ``` +```{cfgcmd} set service pppoe-server thread-count \<all | half | 1-512\> -```{cfgcmd} set service pppoe-server wins-server \<address\> +**Configure how many worker threads the PPPoE server runs:** -Windows Internet Name Service (WINS) servers propagated to client +- `all`: One thread per CPU core. +- `half`: One thread per two CPU cores. +- `1-512`: The given number of threads. + +A change to this option takes effect when the PPPoE server restarts. + +The default is `all`. ``` -## Monitoring +Example: -```{opcmd} show pppoe-server sessions +```none +set service pppoe-server thread-count half +``` + +```{cfgcmd} set service pppoe-server wins-server \<ipv4-address\> + +**Configure a {abbr}`WINS (Windows Internet Name Service)` server +address propagated to clients.** + +Repeat the command to configure a second address. -Use this command to locally check the active sessions in the PPPoE -server. +At most two WINS servers may be configured. Otherwise, the commit +fails. ``` + +Example: + ```none -show pppoe-server sessions -ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes --------+----------+------------+-------------------+-------------+--------+----------+----------+---------- -ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +set service pppoe-server wins-server 192.0.2.11 +``` + +## Operation + +### Show + +```{opcmd} show pppoe-server sessions + +**Show active PPPoE server sessions.** +``` + +```{opcmd} show pppoe-server statistics + +**Show PPPoE server statistics.** +``` + +```{opcmd} show pppoe-server interfaces + +**Show the interfaces on which the PPPoE server listens.** +``` + +### Reset + +```{opcmd} reset pppoe-server all + +**Terminate all PPPoE sessions.** +``` + +```{opcmd} reset pppoe-server interface \<interface\> + +**Terminate the PPPoE session running on the specified PPP +interface.** +``` + +```{opcmd} reset pppoe-server username \<username\> + +**Terminate the PPPoE sessions of the specified user.** +``` + +### Restart + +```{opcmd} restart pppoe-server + +**Restart the PPPoE server.** + +All active PPPoE sessions are terminated. +``` + +### Maintenance mode + +```{opcmd} set pppoe-server maintenance-mode enable + +**Stop accepting new PPPoE sessions and shut the PPPoE server down +once the last active session ends.** +``` + +```{opcmd} set pppoe-server maintenance-mode cancel + +**Resume accepting new PPPoE sessions.** ``` ## Examples + +### Configure PPPoE Server + +The following example configures a minimal PPPoE server with local +authentication: + +```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 +``` + ### IPv4 -The example below uses ACN as access-concentrator name, assigns an -address from the pool 10.1.1.100-111, terminates at the local endpoint -10.1.1.1 and serves requests only on eth1. +The following example uses ACN as the access concentrator name, +assigns client addresses from the range 10.1.1.100-10.1.1.111, uses +10.1.1.2 as the local address of the PPP interfaces, and serves +clients on eth1 only. ```none set service pppoe-server access-concentrator 'ACN' @@ -719,18 +1572,88 @@ set service pppoe-server name-server '10.100.100.1' set service pppoe-server name-server '10.100.200.1' ``` -### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation +### Automatic VLAN creation + +```none +set service pppoe-server interface eth3 vlan 100 +set service pppoe-server interface eth3 vlan 200 +set service pppoe-server interface eth3 vlan 500-1000 +set service pppoe-server interface eth3 vlan 2000-3000 +``` + +### Bandwidth shaping for a local user + +The following example configures a local user with a download limit +of 20480 kbit/s and an upload limit of 10240 kbit/s. + +```none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication local-users username foo rate-limit download '20480' +set service pppoe-server authentication local-users username foo rate-limit upload '10240' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +set service pppoe-server interface 'eth1' +set service pppoe-server gateway-address '10.1.1.2' +``` + +Once the user is connected, the user session uses the configured +limits and can be displayed via `show pppoe-server sessions`. + +```none +show pppoe-server sessions + +% stop_vyoslinter +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` +% start_vyoslinter + +### Load balancing with PADO delays + +In the following example, PADO replies are delayed by 20 ms while +fewer than 500 sessions are active, by 50 ms from 500 active +sessions, by 100 ms from 1000, and by 300 ms from 3000. None of these +delays limits the number of sessions. + +```none +set service pppoe-server pado-delay 20 +set service pppoe-server pado-delay 50 sessions '500' +set service pppoe-server pado-delay 100 sessions '1000' +set service pppoe-server pado-delay 300 sessions '3000' +``` + +### IPv6 address assignment + +The following example enables IPv6 for client sessions and configures +a pool that assigns each client a /64 network and delegates a /56 +prefix for use in the client's own network. + +```none +set service pppoe-server ppp-options ipv6 allow +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' +set service pppoe-server default-ipv6-pool IPV6-POOL +``` + +### Dual-stack IPv4/IPv6 provisioning with prefix delegation -The example below covers a dual-stack configuration. +The following example serves both IPv4 and IPv6. Each client receives +an IPv4 address, an IPv6 network for the client side of the session, +and a delegated prefix for the client's own network. ```none set service pppoe-server authentication local-users username test password 'test' set service pppoe-server authentication mode 'local' set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24' set service pppoe-server default-pool 'IP-POOL' -set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' -set service pppoe-server default-ipv6-pool IPv6-POOL +set service pppoe-server client-ipv6-pool IPV6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server default-ipv6-pool IPV6-POOL set service pppoe-server ppp-options ipv6 allow set service pppoe-server name-server '10.1.1.1' set service pppoe-server name-server '2001:db8:4860::8888' @@ -738,16 +1661,12 @@ set service pppoe-server interface 'eth2' set service pppoe-server gateway-address '10.100.100.1' ``` -The client, once successfully authenticated, will receive an IPv4 and an -IPv6 /64 address to terminate the PPPoE endpoint on the client side and -a /56 subnet for the clients internal use. - ```none -vyos@pppoe-server:~$ sh pppoe-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes ---------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- - ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB -``` +vyos@pppoe-server:~$ show pppoe-server sessions -[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel -[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +% stop_vyoslinter +ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- +ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB +``` +% start_vyoslinter |