PPPoE

PPPoE 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

set interfaces pppoe <interface> description <description>

Configure a clear, descriptive alias for the interface.

This alias appears in the show interfaces command and SNMP-based monitoring tools.

Example:

set interfaces pppoe pppoe0 description 'This is an interface running on VyOS.'
set interfaces pppoe <interface> disable

Disable the interface.

The interface will be set to the administratively down (A/D) state.

Example:

set interfaces pppoe pppoe0 disable
set interfaces pppoe <interface> mtu <mtu>

Configure the MTU on the interface.

This value defines the largest packet size, in bytes, that the interface transmits without fragmentation.

Example:

set interfaces pppoe pppoe0 mtu 1600
set interfaces pppoe <interface> vrf <vrf>

Assign the interface to a specific VRF instance.

See also

For information on configuring a VRF, refer to the VRF section.

Example:

set interfaces pppoe pppoe0 vrf red

PPPoE options

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.

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.

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.

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.

set interfaces pppoe <interface> no-default-route

Request an IP address from the PPPoE server without installing a default route.

Example:

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.

set interfaces pppoe <interface> default-route-distance <distance>

Configure the distance for the default gateway provided by the PPPoE server.

Example:

set interfaces pppoe pppoe0 default-route-distance 220
set interfaces pppoe <interface> mru <mru>

Configure the MRU 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.

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.

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.

set interfaces pppoe <interface> local-address <address>

Configure the local endpoint IP address for PPPoE sessions.

By default, this IP address is negotiated.

set interfaces pppoe <interface> no-peer-dns

Disable the installation of advertised DNS nameservers on the local system.

set interfaces pppoe <interface> remote-address <address>

Configure the remote endpoint IP address for PPPoE sessions.

By default, this IP address is negotiated.

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.

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.

set interfaces pppoe <interface> ip adjust-mss <mss | clamp-mss-to-pmtu>

Configure the MSS 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 PMTUD 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.

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.

set interfaces pppoe <interface> ip source-validation <strict | loose | disable>

Configure source IP address validation using RPF 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 FIB. 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 FIB. 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

set interfaces pppoe <interface> ipv6 address autoconf

Enable IPv6 address assignment via SLAAC on this interface.

set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu>

Configure the MSS 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 PMTUD 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.

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.

DHCPv6 Prefix Delegation (PD)

VyOS supports DHCPv6 Prefix Delegation (DHCPv6-PD) as described in RFC 3633. DHCPv6-PD is supported by most ISPs that provide native IPv6 for consumers on fixed networks.

set interfaces pppoe <interface> dhcpv6-options pd <id> length <length>

Configure a specific prefix length for DHCPv6-PD requests on this interface.

Some ISPs provide only a /64 prefix by default. Use this command to request a different prefix length for a specific DHCPv6-PD request, ranging from /32 (if allowed by your ISP) down to /64. <id> is a unique identifier for the DHCPv6-PD request.

The default value is 64.

To request a /56 prefix from your ISP, use:

set interfaces pppoe pppoe0 dhcpv6-options pd 0 length 56
set interfaces pppoe <interface> dhcpv6-options pd <id> interface <delegatee> address <address>

Configure the IPv6 interface identifier (host portion) for the delegatee interface.

The value must be a decimal integer. It is appended to the delegated prefix and the configured SLA ID to form the final IPv6 address.

By default, the host portion is generated based on the parent interface’s MAC address (EUI-64 format).

Example:

If a /64 prefix is delegated to interface eth8 and you configure the host portion as 65535, the resulting IPv6 address will end with ::ffff, as 65535 corresponds to ffff in hexadecimal notation.

set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth8 address 65534
set interfaces pppoe <interface> dhcpv6-options pd <id> interface <delegatee> sla-id <id>

Configure the SLA ID for the delegatee interface.

The value must be a decimal integer greater than 0 and fit in the length of SLA IDs. It is converted to hexadecimal and appended to the delegated prefix to form the specific subnet prefix for the delegatee interface.

Example:

If SLA ID is 1 and the delegated prefix is 2001:db8:ffff::/48, the resulting subnet prefix for the delegatee interface will be 2001:db8:ffff:1::/64.

set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth8 sla-id 1

Operation

show interfaces pppoe <interface>

Show detailed information about a specific PPPoE interface.

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
show interfaces pppoe <interface> queue

Show queue information for a specific PPPoE interface.

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

disconnect interface <interface>

Disconnect the specified interface.

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.

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:

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:

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.

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