From 6bc7cb64b54e0fb78e89aba2da19bb3bcb0d842c Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Tue, 17 Mar 2026 21:15:01 +0100 Subject: DOC: Proofread pppoe.rst (#1790) Remove superfluous information not related to PPPoE interface configuration in VyOS Co-authored-by: Daniil Baturin --- docs/configuration/interfaces/pppoe.rst | 362 +++++++++++++++----------------- 1 file 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 access-concentrator - 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 ``. + 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 authentication 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 authentication 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 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 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 default-route-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 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 idle-timeout