diff options
Diffstat (limited to 'docs/configuration/interfaces/pppoe.md')
| -rw-r--r-- | docs/configuration/interfaces/pppoe.md | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/pppoe.md b/docs/configuration/interfaces/pppoe.md new file mode 100644 index 00000000..b79f41a2 --- /dev/null +++ b/docs/configuration/interfaces/pppoe.md @@ -0,0 +1,419 @@ +--- +lastproofread: '2026-03-03' +--- + +(pppoe-interface)= + +# PPPoE + +{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +that encapsulates PPP frames within Ethernet frames. +It's often used for connecting ISP clients to a broadband access server. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: pppoe +:var1: pppoe0 +``` + + +### PPPoE options + +```{cfgcmd} set interfaces pppoe \<interface\> access-concentrator \<name\> + +**Configure the name of the target access concentrator for the PPPoE session.** + +During the PPPoE discovery process, the client sends a PPPoE initiation packet. +Multiple access concentrators may respond with offer packets, and the client +selects one of them. + +This setting restricts the client to establishing sessions only with the +specified access concentrator. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> authentication username \<username\> + +**Configure the username for PPPoE session authentication.** + +Although authentication is optional in the interface configuration, most ISPs +require it to establish a connection. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> authentication password \<password\> + +**Configure the password for PPPoE session authentication.** + +Although authentication is optional in the interface configuration, most ISPs +require it to establish a connection. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> connect-on-demand + +**Enable dial-on-demand on the PPPoE interface.** + +When enabled, the system establishes a PPPoE connection only when traffic +passes through the interface. If the connection fails, it is reestablished when +traffic resumes. + +For on-demand connections, you must also configure an ``idle-timeout`` period +to disconnect the session after inactivity. + +:::{note} +Setting the idle timeout to zero, or leaving it unconfigured, keeps +the connection active continuously once established. +::: + +By default, the PPPoE connection is established at boot and remains active +continuously; if the connection fails, it is reestablished immediately. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> no-default-route + +Request an IP address from the PPPoE server without installing a default route. + +Example: + +:::{code-block} none +set interfaces pppoe pppoe0 no-default-route +::: + +:::{note} +Introduced in VyOS 1.4, this command inverts the logic of the former +``default-route`` CLI option. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> default-route-distance \<distance\> + +Configure the distance for the default gateway provided by the PPPoE server. + +Example: + +:::{code-block} none +set interfaces pppoe pppoe0 default-route-distance 220 +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> mru \<mru\> + +**Configure the** {abbr}`MRU (Maximum Receive Unit)` **for the PPPoE +interface.** + +This setting instructs the pppd daemon to restrict the remote peer from sending +packets larger than the configured MRU. Allowed MRU values range from 128 to +16384 bytes. + +An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header +and 256 bytes for data). + +The default MRU is 1492 bytes. + +:::{note} +When using the IPv6 protocol, the MRU must be at least 1280 bytes. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> idle-timeout \<time\> + +**Configure the idle timeout for on-demand PPPoE sessions.** + +This setting defines how long the connection remains active without any traffic +before being disconnected. + +:::{note} +Setting the idle timeout to zero, or leaving it unconfigured, keeps +the connection active continuously once established. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> holdoff \<time\> + +**Configure the redial delay for persistent PPPoE sessions.** + +If a persistent session (with ``connect-on-demand`` disabled) is terminated by +the remote peer or drops unexpectedly, the router waits the specified interval +before attempting to reconnect. + +The default redial delay is 30 seconds. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> local-address \<address\> + +**Configure the local endpoint IP address for PPPoE sessions.** + +By default, this IP address is negotiated. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> no-peer-dns + +Disable the installation of advertised DNS nameservers on the local system. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> remote-address \<address\> + +**Configure the remote endpoint IP address for PPPoE sessions.** + +By default, this IP address is negotiated. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> service-name \<name\> + +**Configure the service name of the target access concentrator for the PPPoE +session.** + +By default, the PPPoE interface connects to any available access concentrator. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> source-interface \<source-interface\> + +**Configure the underlying interface for the PPPoE connection.** + +Each PPPoE connection is established over an underlying interface, which can be +an Ethernet interface, a VIF, or a bonding interface. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for + IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). + This option is recommended to automatically set the proper value. + +:::{note} +Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface <name> adjust-mss <value>`` syntax. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ip disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv4 forwarding is +disabled on it. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ip source-validation \<strict | loose | disable\> + +**Configure source IP address validation using** +{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** +{rfc}`3704`. + +The following options are available: + +* ``strict``: Each incoming packet’s source IP address is checked against the + {abbr}`FIB (Forwarding Information Base)`. If the interface is not the best + route back to that source, validation fails, and the packet is dropped. +* ``loose``: Each incoming packet’s source IP address is checked against the + {abbr}`FIB (Forwarding Information Base)`. If the source IP address is + unreachable through any interface, validation fails. +* ``disable``: No source IP address validation is performed. All incoming + packets are accepted. + +{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as +DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` +mode. +``` + + +#### IPv6 + +```{cfgcmd} set interfaces pppoe \<interface\> ipv6 address autoconf + +Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address +Auto-Configuration)` on this interface. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ipv6 adjust-mss \<mss | clamp-mss-to-pmtu\> + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for + IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). + This option is recommended to automatically set the proper value. + +:::{note} +Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface <name> adjust-mss <value>`` syntax. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ipv6 disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv6 forwarding is +disabled on it. +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: pppoe +:var1: pppoe0 +``` + + +## Operation + +```{opcmd} show interfaces pppoe \<interface\> + +Show detailed information about a specific PPPoE interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces pppoe pppoe0 +pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 +::: +``` + +```{opcmd} show interfaces pppoe \<interface\> queue + +Show queue information for a specific PPPoE interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces pppoe pppoe0 queue +qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 +::: +``` + + +### Connect/disconnect + +```{opcmd} disconnect interface \<interface\> + +Disconnect the specified interface. +``` + +```{opcmd} connect interface \<interface\> + +Initiate a session on the specified interface. +``` + + +## Example + +### PPPoE over DSL + +**Configuration scenario:** + +- Your ISP's DSL modem is connected to the `eth0` interface on your VyOS + router. +- Your ISP does not require VLAN tagging. +- PPPoE credentials are provided by your ISP. The typical username format is + `name@host.net`, though this may vary. + +**Configuration notes:** + +- The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are + switching from a DHCP-based ISP (e.g., a standard cable connection), ensure + VPN links have MTU sizes adjusted accordingly. +- To ignore ISP-provided nameservers and use only your statically configured + ones, set the `name-server` option to `none`. +- A default route is automatically installed once the interface is up. To + change this behavior, use the `no-default-route` CLI option. + +:::{note} +The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is +automatically migrated during an upgrade. +::: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +Secure your setup by creating rules matching the `pppoe0` interface in the +firewall chains: + +```none +set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' +set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' +``` + + +### PPPoE over VLAN + +Some ISPs require PPPoE connections to be +established over a VLAN interface. This specific topology is fully supported by +VyOS. + +The following configuration establishes the PPPoE connection through VLAN 7, +which is the default VLAN for Deutsche Telekom: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0.7' +``` + + +#### IPv6 DHCPv6 prefix delegation + +**Configuration scenario:** + +The following configuration establishes a PPPoE session on the `eth1` +interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns +a `/64` subnet from that delegation to the `eth0` interface. + +**Configuration notes:** + +- The IPv6 address assigned to `eth0` is `<prefix>::1/64`. +- If you do not know your delegated prefix size, begin with `sla-len 0`. +- To advertise the prefix on the `eth0` link, configure IPv6 Router + Advertisement. + +```none +set interfaces pppoe pppoe0 authentication username vyos +set interfaces pppoe pppoe0 authentication password vyos +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 source-interface eth1 + +set service router-advert interface eth0 prefix ::/64 +``` |