DOC: Proofread pppoe.rst (#1790)

Remove superfluous information not related
to PPPoE interface configuration in VyOS

Co-authored-by: Daniil Baturin <daniil@baturin.org>

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