DOC: Proofreading ethernet.rst (#1740)

* DOC: Proofreading ethernet.rst

* doc: indentation configuration

* Apply suggestions from code review

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

* Remove mentions of Metro Ethernet

---------

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

4 files changed, 234 insertions, 147 deletions

diff --git a/docs/_include/interface-eapol.txt b/docs/_include/interface-eapol.txt
index 640fc6e3..fc3d9e34 100644
--- a/docs/_include/interface-eapol.txt
+++ b/docs/_include/interface-eapol.txt
@@ -1,41 +1,82 @@
-:abbr:`EAP (Extensible Authentication Protocol)` over LAN (EAPoL) is a network
-port authentication protocol used in IEEE 802.1X (Port Based Network Access
-Control) developed to give a generic network sign-on to access network
-resources.
+**Overview**
 
-EAPoL comes with an identify option. We automatically use the interface MAC
-address as identity parameter.
+IEEE 802.1X is a security standard that enforces access control at the data link layer. It blocks all traffic on a port until the connecting device proves 
+its identity. The :abbr:`EAPOL (Extensible Authentication Protocol over LAN)` 
+protocol transports credentials between the client (supplicant) and the network 
+switch (authenticator). The switch forwards these credentials to a backend 
+authentication server, typically RADIUS, which verifies them and authorizes 
+the connection.
+
+The VyOS router acts as the supplicant, authenticating with upstream network 
+equipment such as ISP gateways or enterprise switches. Authentication uses 
+X.509 certificates to validate the identities of both the router and the 
+authentication server.
+
+The :abbr:`EAPOL (Extensible Authentication Protocol over LAN)` protocol 
+requires the supplicant (the router) to provide an identity string to the 
+authentication server during the initial handshake. If no identity is 
+configured, VyOS uses the Ethernet interface's MAC address as the identity 
+string.
+
+**Configuration**
+
+Prerequisites: Before configuring 802.1X (:abbr:`EAPOL (Extensible 
+Authentication Protocol over LAN)`) authentication, upload the required 
+:abbr:`CA (Certificate Authority)` certificate, client certificate, and 
+private key to the router and import them into the PKI system.
+
+.. note:: The client certificate and private key must share the **same** PKI 
+   name.
+
+.. seealso:: For more information about managing certificates and keys, see 
+   the :ref:`PKI <pki>` section.
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
   {{ var5 }} {{ var6 }} eapol ca-certificate <name>
 
-  Set the name of the SSL :abbr:`CA (Certificate Authority)` PKI entry used for
-  authentication of the remote side. If an intermediate CA certificate is
-  specified, then all parent CA certificates that exist in the PKI, such as the
-  root CA or additional intermediate CAs, will automatically be used during
-  certificate validation to ensure that the full chain of trust is available.
+  **Configure the trusted** :abbr:`CA (Certificate Authority)` **certificate for 
+  the interface.**
+  
+  The router uses this certificate to validate the authentication server’s 
+  identity.
+
+  ``<name>`` is the :abbr:`CA (Certificate Authority)` certificate name as 
+  defined in the PKI system.
+
+  .. note:: If you specify an intermediate :abbr:`CA (Certificate Authority)` 
+     certificate, ensure the full certificate chain, including the root and all 
+     higher-level intermediate :abbr:`CA (Certificate Authority)` certificates, is 
+     available to the system.
 
   Example:
 
   .. code-block:: none
 
-    set pki ca eapol-server-intermediate-ca <Server intermediate CA contents>
-    set pki ca eapol-server-root-ca <Server root CA contents>
+    set pki ca eapol-server-intermediate-ca <server intermediate CA contents>
+    set pki ca eapol-server-root-ca <server root CA contents>
     set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol ca-certificate eapol-server-intermediate-ca
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
   {{ var5 }} {{ var6 }} eapol certificate <name>
 
-  Set the name of the x509 client keypair used to authenticate against the
-  802.1x system. All parent CA certificates of the client certificate, such as
-  intermediate and root CAs, will be sent as part of the EAP-TLS handshake.
+  **Configure the client certificate for the interface.** 
+
+  The router uses this certificate to prove its identity to the authentication 
+  server.
+
+  ``<name>`` is the client certificate name as defined in the PKI system.
+
+  During authentication, all parent :abbr:`CA (Certificate Authority)` 
+  certificates of the client certificate, such as intermediate and root :abbr:`CA 
+  (Certificate Authority)` certificates, are automatically sent as part of the 
+  EAP-TLS handshake.
 
   Example:
 
   .. code-block:: none
 
-    set pki ca eapol-client-intermediate-ca <Client intermediate CA contents>
-    set pki ca eapol-client-root-ca <Client root CA contents>
-    set pki certificate eapol-client certificate <Client certificate contents>
-    set pki certificate eapol-client private key <Client private key contents>
+    set pki ca eapol-client-intermediate-ca <client intermediate CA contents>
+    set pki ca eapol-client-root-ca <client root CA contents>
+    set pki certificate eapol-client certificate <client certificate contents>
+    set pki certificate eapol-client private key <client private key contents>
     set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol certificate eapol-client
diff --git a/docs/_include/interface-evpn-uplink.txt b/docs/_include/interface-evpn-uplink.txt
index 84b09727..67bf2abc 100644
--- a/docs/_include/interface-evpn-uplink.txt
+++ b/docs/_include/interface-evpn-uplink.txt
@@ -6,7 +6,7 @@
   to the VXLAN overlay. To prevent traffic blackholing, the PE device forces a 
   protocol shutdown (protodown) of its downstream EVPN-MH interfaces.
 
-  The following example configures bond0 as an EVPN-MH uplink interface:
+  The following example configures {{ var1 }} as an EVPN-MH uplink interface:
 
   .. code-block:: none
 
diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt
index 0a1722dc..a6413679 100644
--- a/docs/_include/interface-vlan-8021ad.txt
+++ b/docs/_include/interface-vlan-8021ad.txt
@@ -1,32 +1,31 @@
-.. include:: /_include/need_improvement.txt
-
-IEEE 802.1ad_ was an Ethernet networking standard informally known as QinQ as
-an amendment to IEEE standard 802.1q VLAN interfaces as described above.
-802.1ad was incorporated into the base 802.1q_ standard in 2011. The technique
-is also known as provider bridging, Stacked VLANs, or simply QinQ or Q-in-Q.
-"Q-in-Q" can for supported devices apply to C-tag stacking on C-tag (Ethernet
-Type = 0x8100).
-
-The original 802.1q_ specification allows a single Virtual Local Area Network
-(VLAN) header to be inserted into an Ethernet frame. QinQ allows multiple
-VLAN tags to be inserted into a single frame, an essential capability for
-implementing Metro Ethernet network topologies. Just as QinQ extends 802.1Q,
-QinQ itself is extended by other Metro Ethernet protocols.
-
-In a multiple VLAN header context, out of convenience the term "VLAN tag" or
-just "tag" for short is often used in place of "802.1q_ VLAN header". QinQ
-allows multiple VLAN tags in an Ethernet frame; together these tags constitute
-a tag stack. When used in the context of an Ethernet frame, a QinQ frame is a
-frame that has 2 VLAN 802.1q_ headers (double-tagged).
-
-In VyOS the terms ``vif-s`` and ``vif-c`` stand for the ethertype tags that
-are used.
-
-The inner tag is the tag which is closest to the payload portion of the frame.
-It is officially called C-TAG (customer tag, with ethertype 0x8100). The outer
-tag is the one closer/closest to the Ethernet header, its name is S-TAG
-(service tag with Ethernet Type = 0x88a8).
+**Overview**
 
+IEEE 802.1ad_, commonly known as QinQ, is an Ethernet standard first published 
+as an amendment to 802.1q_ in 2005, then officially merged into the base 
+standard in 2011.
+
+Unlike the original 802.1q_, which allows a single VLAN header per Ethernet 
+frame, QinQ allows two VLAN headers per Ethernet frame, for the inner and the outer VLAN tags.
+Most often the inner VLAN tag comes from a customer while the outer tag is used by the service
+provider to differentiate between traffic of different customers.
+
+
+**Frame structure and ethertypes**
+
+The IEEE 802.1ad_ (QinQ) frame includes two VLAN tags:
+
+* **The outer service tag (S-TAG):** The S-TAG is typically added by the provider.
+It uses the Ethertype 0x88a8 by default. 
+
+* **The inner customer tag (C-TAG):** The C-TAG is generated by the customer's equipment and 
+  remains unchanged during transit. It uses the Ethertype 0x8100.
+
+**Implementation in VyOS**
+
+In VyOS, these tag types are associated with the following CLI options:
+
+* ``vif-s``: Corresponds to the S-TAG (Ethertype 0x88a8).
+* ``vif-c``: Corresponds to the C-TAG (Ethertype 0x8100).
 
 .. cmdinclude:: /_include/interface-address-with-dhcp.txt
    :var0: {{ var0 }}
diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst
index 8d31fc70..e6c385e7 100644
--- a/docs/configuration/interfaces/ethernet.rst
+++ b/docs/configuration/interfaces/ethernet.rst
@@ -1,4 +1,4 @@
-:lastproofread: 2023-01-20
+:lastproofread: 2026-01-19
 
 .. _ethernet-interface:
 
@@ -6,8 +6,12 @@
 Ethernet
 ########
 
-This will be the most widely used interface on a router carrying traffic to the
-real world.
+Ethernet interfaces (e.g., ``eth0``, ``eth1``) represent the host's physical 
+or virtual network ports.
+
+They are the most common interface type, serving as the base layer upon which 
+IP addresses, VLANs, and tunnels are configured to carry traffic across both 
+LANs and WANs.
 
 *************
 Configuration
@@ -20,15 +24,16 @@ Common interface configuration
    :var0: ethernet
    :var1: eth0
 
-.. cfgcmd:: set interface ethernet <interface> switchdev
+.. cfgcmd:: set interfaces ethernet <interface> switchdev
 
-  Switches this interface to `switchdev` mode that allows network interfaces to offload
-  certain networking functions directly to hardware, like a network switch or a SmartNIC.
-  This enables higher performance and lower latency for network processing by
-  bypassing the kernel's network stack for supported operations.
+  **Enable** ``switchdev`` **mode for the interface.**
+  
+  In ``switchdev`` mode, the interface offloads traffic switching between ports 
+  to the hardware, bypassing the host CPU. This increases the interface’s 
+  traffic-handling capacity and reduces its forwarding delay. 
 
-.. note:: This is only supported on certain physical network interfaces
-   and depends on specific models and drivers.
+.. note:: ``switchdev`` mode is available only on certain physical network 
+  interfaces and requires a switchdev-compatible driver.
 
 
 Ethernet options
@@ -36,40 +41,65 @@ Ethernet options
 
 .. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half>
 
-   Configure physical interface duplex setting.
+   **Configure duplex mode for the interface.** 
 
-   * auto - interface duplex setting is auto-negotiated
-   * full - always use full-duplex
-   * half - always use half-duplex
+   The following duplex modes are available: 
 
-   VyOS default will be `auto`.
+   * ``auto``: The interface negotiates the duplex mode with the connected device. 
+   * ``full``: The interface sends and receives data simultaneously. The 
+     connected device must also be set to full-duplex to avoid a duplex mismatch.
+   * ``half``: The interface either sends or receives data, but not both at the 
+     same time. 
 
+   The default duplex mode is ``auto``. 
+   
 .. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 |
   2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000>
 
-   Configure physical interface speed setting.
+   **Configure the interface's speed, in Mbit/s.**
+
+   The following options are available:
+
+   * ``auto``:  The interface negotiates the speed with the connected device.
+   * ``10, 100, 1000 ...``: The interface operates at the selected speed. The 
+     connected device must be set to the same speed to establish a connection. 
+
+   The default option is ``auto``.
+
+.. cfgcmd:: set interfaces ethernet <interface> ring-buffer rx <value>
+
+   **Configure the receive (RX) ring buffer size for the interface.**
+
+   The RX ring buffer size defines the number of incoming packets the interface 
+   can queue in hardware before the CPU processes them.
+
+   Higher values reduce the risk of drops when the NIC receives network traffic 
+   faster than the CPU can process it, though latency may increase. Lower values 
+   reduce latency but increase the risk of packet drops during incoming traffic 
+   bursts.
 
-   * auto - interface speed is auto-negotiated
-   * 10 - 10 MBit/s
-   * 100 - 100 MBit/s
-   * 1000 - 1 GBit/s
-   * 2500 - 2.5 GBit/s
-   * 5000 - 5 GBit/s
-   * 10000 - 10 GBit/s
-   * 25000 - 25 GBit/s
-   * 40000 - 40 GBit/s
-   * 50000 - 50 GBit/s
-   * 100000 - 100 GBit/s
+   To view supported values for a specific interface, use: 
 
-   VyOS default will be `auto`.
+.. code-block:: none
+   
+   ethtool -g <interface>
 
-.. cfgcmd:: set interface ethernet <interface> ring-buffer rx <value>
-.. cfgcmd:: set interface ethernet <interface> ring-buffer tx <value>
+.. cfgcmd:: set interfaces ethernet <interface> ring-buffer tx <value>
 
-  Configures the ring buffer size of the interface.
+   **Configure the transmit (TX) ring buffer size.**
 
-  The supported values for a specific interface can be obtained
-  with: `ethtool -g <interface>`
+   The TX ring buffer size defines the number of outgoing packets the interface 
+   can queue in hardware before they are transmitted onto the network.
+
+   Higher values reduce the risk of drops when the CPU generates traffic faster 
+   than the NIC can handle, though latency may increase. Lower values reduce 
+   latency but increase the risk of packet drops during outgoing traffic bursts.
+
+   To view supported values for a specific interface, use: 
+
+.. code-block:: none
+   
+   ethtool -g <interface>
 
 Interrupt Coalescing
 ----------
@@ -180,63 +210,79 @@ the CPU for every packet arrival or transmission.
 Offloading
 ----------
 
-.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | lro | rps |
-  sg | tso>
-
-  Enable different types of hardware offloading on the given NIC.
-
-  :abbr:`LRO (Large Receive Offload)` is a technique designed to boost the
-  efficiency of how your computer's network interface card (NIC) processes
-  incoming network traffic. Typically, network data arrives in smaller chunks
-  called packets. Processing each packet individually consumes CPU (central
-  processing unit) resources. Lots of small packets can lead to a performance
-  bottleneck. Instead of handing the CPU each packet as it comes in, LRO
-  instructs the NIC to combine multiple incoming packets into a single, larger
-  packet. This larger packet is then passed to the CPU for processing.
-
-  .. note:: Under some circumstances, LRO is known to modify the packet headers
-     of forwarded traffic, which breaks the end-to-end principle of computer
-     networking. LRO is also only able to offload TCP segments encapsulated in
-     IPv4 packets. Due to these limitations, it is recommended to use GRO
-     (Generic Receive Offload) where possible. More information on the
-     limitations of LRO can be found here: https://lwn.net/Articles/358910/
-
-  :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is
-  meant to deal with cases where device drivers cannot perform the offloads
-  described above. What occurs in GSO is that a given skbuff will have its data
-  broken out over multiple skbuffs that have been resized to match the MSS
-  provided via skb_shinfo()->gso_size.
-
-  Before enabling any hardware segmentation offload a corresponding software
-  offload is required in GSO. Otherwise it becomes possible for a frame to be
-  re-routed between devices and end up being unable to be transmitted.
-
-  :abbr:`GRO (Generic receive offload)` is the complement to GSO. Ideally any
-  frame assembled by GRO should be segmented to create an identical sequence of
-  frames using GSO, and any sequence of frames segmented by GSO should be able
-  to be reassembled back to the original by GRO. The only exception to this is
-  IPv4 ID in the case that the DF bit is set for a given IP header. If the
-  value of the IPv4 ID is not sequentially incrementing it will be altered so
-  that it is when a frame assembled via GRO is segmented via GSO.
-
-  :abbr:`RPS (Receive Packet Steering)` is logically a software implementation
-  of :abbr:`RSS (Receive Side Scaling)`. Being in software, it is necessarily
-  called later in the datapath. Whereas RSS selects the queue and hence CPU that
-  will run the hardware interrupt handler, RPS selects the CPU to perform
-  protocol processing above the interrupt handler. This is accomplished by
-  placing the packet on the desired CPU's backlog queue and waking up the CPU
-  for processing. RPS has some advantages over RSS:
-
-  - it can be used with any NIC
-  - software filters can easily be added to hash over new protocols
-  - it does not increase hardware device interrupt rate, although it does
-    introduce inter-processor interrupts (IPIs)
-
-  .. note:: In order to use TSO/LRO with VMXNET3 adapters, the SG offloading
-     option must also be enabled.
-
-Authentication (EAPoL)
-----------------------
+.. cfgcmd:: set interfaces ethernet <interface> offload <lro | tso | gso |  
+   gro |  rps | sg >
+  
+   **Configure the offloading features for the interface.** 
+
+   The interface offloading features define whether specific packet-processing tasks 
+   are performed by hardware (the NIC) or by software (the kernel). You can enable 
+   multiple offloading features for a single interface.
+
+
+    * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple 
+      incoming packets into one larger packet before sending it to the CPU.
+
+      .. note:: :abbr:`LRO (Large Receive Offload)` hardware support is often limited 
+        to TCP/IPv4 packets. For details on LRO limitations, see 
+        https://lwn.net/Articles/358910/
+
+      .. warning:: :abbr:`LRO (Large Receive Offload)` irreversibly alters packet 
+        headers during merging. This prevents the merged packet from being correctly 
+        split back into the original packets, causing packet drops and forwarding 
+        failures on routers and bridges. Use :abbr:`LRO (Large Receive Offload)` only 
+        for end-hosts that do not forward traffic.
+
+    * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP 
+      packets into smaller ones before transmitting them to the network. 
+
+      **Important:** :abbr:`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled 
+      for :abbr:`TSO (TCP Segmentation Offload)` to work. Additionally, :abbr:`GSO 
+      (Generic Segmentation Offload)` should be enabled as a safety fallback; it 
+      ensures that if traffic is rerouted to hardware without :abbr:`TSO (TCP 
+      Segmentation Offload)` support, the kernel can still segment the packets, 
+      preventing transmission failures.
+
+    * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split 
+      large packets into smaller ones before sending them to the NIC.
+
+      :abbr:`GSO (Generic Segmentation Offload)` serves as a software fallback for 
+      hardware that does not support :abbr:`TSO (TCP Segmentation Offload)` or for 
+      protocols (like UDP) that hardware cannot offload.
+
+      **Important:** :abbr:`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled 
+      for :abbr:`GSO (Generic Segmentation Offload)` to work.  
+
+    * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple 
+      incoming packets into one larger packet before passing it to upper protocol 
+      layers.
+
+      Unlike LRO, GRO preserves the necessary packet metadata so the merged packet 
+      can be correctly split back into the original packets. This makes GRO safe for 
+      use on routers and bridges.
+
+    .. note:: The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is 
+       set and IDs are not sequential, :abbr:`GSO (Generic Segmentation Offload)` 
+       alters them to maintain a consistent sequence for :abbr:`GSO (Generic 
+       Segmentation Offload)` compatibility.
+
+    * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute 
+      the processing of incoming packets across multiple CPU cores.
+
+      The kernel calculates a hash from packet headers (IP addresses and ports) to 
+      ensure packets from the same flow are processed by the same CPU core.
+
+    .. note:: :abbr:`RPS (Receive Packet Steering)` is a software version of 
+       :abbr:`RSS (Receive Side Scaling)` and is useful for NICs without hardware 
+       multi-queue support.
+
+    * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch 
+      data fragments from various RAM locations and transmit them as a single packet 
+      to the network, eliminating the need for the kernel to copy them into a 
+      contiguous block first.
+
+802.1X (EAPOL) authentication
+-----------------------------
 
 .. cmdinclude:: /_include/interface-eapol.txt
    :var0: ethernet
@@ -245,7 +291,7 @@ Authentication (EAPoL)
 EVPN Multihoming
 ----------------
 
-Uplink/Core tracking.
+Uplink/core tracking.
 
 .. cmdinclude:: /_include/interface-evpn-uplink.txt
    :var0: ethernet
@@ -261,15 +307,15 @@ Regular VLANs (802.1q)
    :var0: ethernet
    :var1: eth0
 
-QinQ (802.1ad)
+802.1ad (QinQ)
 --------------
 
 .. cmdinclude:: /_include/interface-vlan-8021ad.txt
    :var0: ethernet
    :var1: eth0
 
-Port Mirror (SPAN)
-==================
+SPAN port mirroring
+===================
 .. cmdinclude:: ../../_include/interface-mirror.txt
    :var0: ethernet
    :var1: eth1
@@ -295,7 +341,7 @@ Operation
 
 .. opcmd:: show interfaces ethernet <interface>
 
-   Show detailed information on given `<interface>`
+   Show detailed interface information.
 
    .. code-block:: none
 
@@ -314,7 +360,7 @@ Operation
 
 .. opcmd:: show interfaces ethernet <interface> physical
 
-   Show information about physical `<interface>`
+   Show interface hardware-level and driver details.
 
    .. code-block:: none
 
@@ -355,7 +401,7 @@ Operation
 
 .. opcmd:: show interfaces ethernet <interface> physical offload
 
-   Show available offloading functions on given `<interface>`
+   Show the status of the interface offloading features.
 
    .. code-block:: none
 
@@ -387,7 +433,8 @@ Operation
 
 .. opcmd:: show interfaces ethernet <interface> transceiver
 
-   Show transceiver information from plugin modules, e.g SFP+, QSFP
+   Show information about the transceiver module plugged into the interface 
+   (e.g., SFP+, QSFP).
 
    .. code-block:: none