diff options
Diffstat (limited to 'docs/configuration/interfaces')
| -rw-r--r-- | docs/configuration/interfaces/pppoe.rst | 362 |
1 files changed, 175 insertions, 187 deletions
diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index 65081e1c..d2f8271c 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-07-27 +:lastproofread: 2026-03-03 .. _pppoe-interface: @@ -6,53 +6,9 @@ PPPoE ##### -:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol -for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, -in the context of the boom of DSL as the solution for tunneling packets -over the DSL connection to the :abbr:`ISPs (Internet Service Providers)` -IP network, and from there to the rest of the Internet. A 2005 networking -book noted that "Most DSL providers use PPPoE, which provides authentication, -encryption, and compression." Typical use of PPPoE involves leveraging the -PPP facilities for authenticating the user with a username and password, -predominately via the PAP protocol and less often via CHAP. - -*************** -Operating Modes -*************** - -VyOS supports setting up PPPoE in two different ways to a PPPoE internet -connection. This is because most ISPs provide a modem that is also a wireless -router. - -Home Users -========== - -In this method, the DSL Modem/Router connects to the ISP for you with your -credentials preprogrammed into the device. This gives you an :rfc:`1918` -address, such as ``192.168.1.0/24`` by default. - -For a simple home network using just the ISP's equipment, this is usually -desirable. But if you want to run VyOS as your firewall and router, this -will result in having a double NAT and firewall setup. This results in a -few extra layers of complexity, particularly if you use some NAT or -tunnel features. - -Business Users -============== - -In order to have full control and make use of multiple static public IP -addresses, your VyOS will have to initiate the PPPoE connection and control -it. In order for this method to work, you will have to figure out how to make -your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL -Transceiver device to connect between the Ethernet link of your VyOS and the -phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no -IP address from it. Please make sure you connect to the Ethernet Port 1 if -your DSL Transceiver has a switch, as some of them only work this way. - -Once you have an Ethernet device connected, i.e. `eth0`, then you can -configure it to open the PPPoE session for you and your DSL Transceiver -(Modem/Router) just acts to translate your messages in a way that -vDSL/aDSL understands. +: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 @@ -82,47 +38,49 @@ PPPoE options .. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> - Use this command to restrict the PPPoE session on a given access - concentrator. Normally, a host sends a PPPoE initiation packet to start the - PPPoE discovery process, a number of access concentrators respond with offer - packets and the host selects one of the responding access concentrators to - serve this session. + **Configure the name of the target access concentrator for the PPPoE session.** - This command allows you to select a specific access concentrator when you - know the access concentrators `<name>`. + 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> - Use this command to set the username for authenticating with a remote PPPoE - endpoint. Authentication is optional from the system's point of view but - most service providers require it. + **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> - Use this command to set the password for authenticating with a remote PPPoE - endpoint. Authentication is optional from the system's point of view but - most service providers require it. + **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 - When set the interface is enabled for "dial-on-demand". + **Enable dial-on-demand on the PPPoE interface.** - Use this command to instruct the system to establish a PPPoE connection - automatically once traffic passes through the interface. A disabled on-demand - connection is established at boot time and remains up. If the link fails for - any reason, the link is brought back up immediately. + 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. - Enabled on-demand PPPoE connections bring up the link only when traffic needs - to pass this link. If the link fails for any reason, the link is brought - back up automatically once traffic passes the interface again. If you - configure an on-demand PPPoE connection, you must also configure the idle - timeout period, after which an idle PPPoE link will be disconnected. A - non-zero idle timeout will never disconnect the link after it first came up. + 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 - Only request an address from the PPPoE server but do not install any default - route. + Request an IP address from the PPPoE server without installing a default route. Example: @@ -130,12 +88,12 @@ PPPoE options set interfaces pppoe pppoe0 no-default-route - .. note:: This command got added in VyOS 1.4 and inverts the logic from the old - ``default-route`` CLI option. + .. 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> - Set the distance for the default gateway sent by the PPPoE server. + Configure the distance for the default gateway provided by the PPPoE server. Example: @@ -145,129 +103,151 @@ PPPoE options .. cfgcmd:: set interfaces pppoe <interface> mru <mru> - Set the :abbr:`MRU (Maximum Receive Unit)` to `mru`. PPPd will ask the peer to - send packets of no more than `mru` bytes. The value of `mru` must be between 128 - and 16384. + **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. - A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256 - bytes of data). + An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header + and 256 bytes for data). - The default is 1492. + The default MRU is 1492 bytes. - .. note:: When using the IPv6 protocol, MRU must be at least 1280 bytes. + .. note:: When using the IPv6 protocol, the MRU must be at least 1280 bytes. .. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> - Use this command to set the idle timeout interval to be used with on-demand - PPPoE sessions. When an on-demand connection is established, the link is - brought up only when traffic is sent and is disabled when the link is idle - for the interval specified. + **Configure the idle timeout for on-demand PPPoE sessions.** - If this parameter is not set or 0, an on-demand link will not be taken down - when it is idle and after the initial establishment of the connection. It - will stay up forever. + 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> - Use this command to set re-dial delay time to be used with persist PPPoE - sessions. When the PPPoE session is terminated by peer, and on-demand - option is not set, the router will attempt to re-establish the PPPoE link. + **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. - If this parameter is not set, the default holdoff time is 30 seconds. + The default redial delay is 30 seconds. .. cfgcmd:: set interfaces pppoe <interface> local-address <address> - Use this command to set the IP address of the local endpoint of a PPPoE - session. If it is not set it will be negotiated. + **Configure the local endpoint IP address for PPPoE sessions.** + + By default, this IP address is negotiated. .. cfgcmd:: set interfaces pppoe <interface> no-peer-dns - Use this command to not install advertised DNS nameservers into the local - system. + Disable the installation of advertised DNS nameservers on the local system. .. cfgcmd:: set interfaces pppoe <interface> remote-address <address> - Use this command to set the IP address of the remote endpoint of a PPPoE - session. If it is not set it will be negotiated. + **Configure the remote endpoint IP address for PPPoE sessions.** + + By default, this IP address is negotiated. .. cfgcmd:: set interfaces pppoe <interface> service-name <name> - Use this command to specify a service name by which the local PPPoE interface - can select access concentrators to connect with. It will connect to any - access concentrator if not set. + **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> - Use this command to link the PPPoE connection to a physical interface. Each - PPPoE connection must be established over a physical interface. Interfaces - can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. + **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> - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. + **Configure the** :abbr:`MSS (Maximum Segment Size)` **advertised in outgoing + TCP SYN packets on the specified interface.** - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss <value>`` + 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. - .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in - 1452 bytes on a 1492 byte MTU. + The following options are available: - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. + * ``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 interface-specific Host/Router behaviour. If set, the interface will - switch to host mode and IPv6 forwarding will be disabled on this interface. + **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> - Enable policy for source validation by reversed path, as specified in - :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict - mode to prevent IP spoofing from DDos attacks. If using asymmetric routing - or other complicated routing, then loose mode is recommended. + **Configure source IP address validation using** + :abbr:`RPF (Reverse Path Forwarding)` **on this interface, as specified in** + :rfc:`3704`. - - strict: Each incoming packet is tested against the FIB and if the interface - is not the best reverse path the packet check will fail. By default failed - packets are discarded. + The following options are available: - - loose: Each incoming packet's source address is also tested against the FIB - and if the source address is not reachable via any interface the packet - check will fail. + * ``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. - - disable: No source validation + :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 - Use this command to enable acquisition of IPv6 address using stateless - autoconfig (SLAAC). + 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> - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. + **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. - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss <value>`` + The following options are available: - .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in - 1432 bytes on a 1492 byte MTU. + * ``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. - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. .. cfgcmd:: set interfaces pppoe <interface> ipv6 disable-forwarding - Configure interface-specific Host/Router behaviour. If set, the interface will - switch to host mode and IPv6 forwarding will be disabled on this interface. + **Configure the interface for host or router behavior.** + + If configured, the interface switches to host mode, and IPv6 forwarding is + disabled on it. .. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt :var0: pppoe @@ -279,7 +259,7 @@ Operation .. opcmd:: show interfaces pppoe <interface> - Show detailed information on given `<interface>` + Show detailed information about a specific PPPoE interface. .. code-block:: none @@ -296,7 +276,7 @@ Operation .. opcmd:: show interfaces pppoe <interface> queue - Displays queue information for a PPPoE interface. + Show queue information for a specific PPPoE interface. .. code-block:: none @@ -305,43 +285,45 @@ Operation Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) backlog 0b 0p requeues 0 -Connect/Disconnect +Connect/disconnect ================== .. opcmd:: disconnect interface <interface> - Test disconnecting given connection-oriented interface. `<interface>` can be - ``pppoe0`` as the example. + Disconnect the specified interface. .. opcmd:: connect interface <interface> - Test connecting given connection-oriented interface. `<interface>` can be - ``pppoe0`` as the example. + Initiate a session on the specified interface. ******* Example ******* -Requirements: +PPPoE over DSL +============== + +**Configuration scenario:** -* Your ISPs modem is connected to port ``eth0`` of your VyOS box. -* No VLAN tagging required by your ISP. -* You need your PPPoE credentials from your DSL ISP in order to configure - this. The usual username is in the form of name@host.net but may vary - depending on ISP. -* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. - If you are switching from a DHCP based ISP like cable then be aware that - things like VPN links may need to have their MTU sizes adjusted to work - within this limit. -* With the ``name-server`` option set to ``none``, VyOS will ignore the - nameservers your ISP sends you and thus you can fully rely on the ones you - have configured statically. +* 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. -.. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically - migrated during an upgrade. +**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. -.. note:: A default route is automatically installed once the interface is up. - To change this behavior use the ``no-default-route`` CLI option. .. code-block:: none @@ -350,22 +332,23 @@ Requirements: set interfaces pppoe pppoe0 source-interface 'eth0' -You should add a firewall to your configuration above as well by -assigning it to the pppoe0 itself as shown here: +Secure your setup by creating rules matching the ``pppoe0`` interface in the +firewall chains: .. code-block:: none - set firewall interface pppoe0 in name NET-IN - set firewall interface pppoe0 local name NET-LOCAL - set firewall interface pppoe0 out name NET-OUT + 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 +=============== -VLAN Example -============ +Some ISPs require PPPoE connections to be +established over a VLAN interface. This specific topology is fully supported by +VyOS. -Some recent ISPs require you to build the PPPoE connection through a VLAN -interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS -can easily create a PPPoE session through an encapsulated VLAN interface. -The following configuration will run your PPPoE connection through VLAN7 +The following configuration establishes the PPPoE connection through VLAN 7, which is the default VLAN for Deutsche Telekom: .. code-block:: none @@ -375,18 +358,23 @@ which is the default VLAN for Deutsche Telekom: set interfaces pppoe pppoe0 source-interface 'eth0.7' -IPv6 DHCPv6-PD Example ----------------------- +IPv6 DHCPv6 prefix delegation +----------------------------- .. stop_vyoslinter -The following configuration will setup a PPPoE session source from eth1 and -assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0. -The IPv6 address assigned to eth0 will be <prefix>::1/64. If you do not know -the prefix size delegated to you, start with sla-len 0. +**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:** -In addition we setup IPv6 :abbr:`RA (Router Advertisements)` to make the -prefix known on the eth0 link. +* 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. .. start_vyoslinter |