DOC: Proofreading ethernet.rst #1740
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the ethernet.rst documentation file and related includes with comprehensive proofreading improvements. The changes enhance clarity, accuracy, and consistency across the Ethernet interface documentation.
Changes:
- Expanded and clarified Ethernet interface descriptions and configuration options
- Improved technical explanations of offloading features (LRO, TSO, GSO, GRO, RPS, SG)
- Enhanced 802.1X (EAPOL) authentication documentation with better structure and prerequisites
- Updated QinQ (802.1ad) documentation with clearer frame structure explanations
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/configuration/interfaces/ethernet.rst | Major rewrite of interface descriptions, configuration options, and offloading features with improved technical accuracy and clarity |
| docs/_include/interface-vlan-8021ad.txt | Restructured QinQ documentation with clearer sections on frame structure and VyOS implementation |
| docs/_include/interface-evpn-uplink.txt | Updated example to use variable placeholder instead of hardcoded interface name |
| docs/_include/interface-eapol.txt | Completely restructured with overview, prerequisites, and clearer configuration instructions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * ``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. |
There was a problem hiding this comment.
Inconsistent indentation for the nested list items. The list items for 'tso', 'gso', 'gro', 'rps', and 'sg' should align with the first list item 'lro' at the same indentation level. Currently, items starting from line 131 have an extra space of indentation compared to line 118.
| 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. |
There was a problem hiding this comment.
The note describes GRO's behavior but incorrectly attributes the ID alteration to GSO. The first instance of "GSO" in line 160 should be "GRO" since this note is under the GRO section and describes what GRO does (altering IPv4 IDs). The second instance in lines 161-162 correctly refers to GSO as the reason for maintaining compatibility. The corrected text should read: "If the 'Don't Fragment' (DF) bit is set and IDs are not sequential, GRO alters them to maintain a consistent sequence for GSO compatibility."
| 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. | |
| set and IDs are not sequential, :abbr:`GRO (Generic Receive Offload)` alters | |
| them to maintain a consistent sequence for :abbr:`GSO (Generic Segmentation | |
| Offload)` compatibility. |
| ---------------- | ||
|
|
||
| Uplink/Core tracking. | ||
| Uplink/core tracking. |
There was a problem hiding this comment.
Inconsistent capitalization in section header. The word "Uplink" is capitalized in the section header "Uplink/core tracking" while it should follow the same pattern. Since this is a documentation change from "Uplink/Core tracking" to "Uplink/core tracking", the capitalization is being made inconsistent. Either both should be capitalized ("Uplink/Core") or both should be lowercase ("uplink/core"). The original capitalization appears more appropriate for a header or technical term.
| Uplink/core tracking. | |
| Uplink/Core tracking. |
| set pki ca eapol-server-intermediate-ca <server intermediate CA contents> | ||
| set pki ca eapol-server-root-ca <server root CA contents> |
There was a problem hiding this comment.
Inconsistent capitalization in code example placeholders. The placeholders use lowercase "server" and "client" (e.g., "server intermediate CA contents", "client certificate contents") while the previous context uses capitalized forms ("Server intermediate CA contents", "Client certificate contents"). For consistency with typical documentation conventions where placeholders describe what should be inserted, the capitalization should be consistent throughout the examples.
| 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> |
There was a problem hiding this comment.
Inconsistent capitalization in code example placeholders. Similar to the earlier example, the placeholders use lowercase "client" (e.g., "client intermediate CA contents", "client certificate contents") while maintaining consistency with the documentation style would suggest using capitalized forms. All placeholder descriptions should follow the same capitalization pattern throughout the file.
| IEEE 802.1X is a security standard that enforces access control at the physical | ||
| port level. It blocks all traffic on a port until the connecting device proves |
There was a problem hiding this comment.
| IEEE 802.1X is a security standard that enforces access control at the physical | |
| port level. It blocks all traffic on a port until the connecting device proves | |
| 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 |
It will let the device send Ethernet frames if the client is authenticated, so it's not right to say it's done at the physical port level since it will not tie client devices to ports in any way.
| Unlike the original 802.1q_, which allows a single VLAN header per Ethernet | ||
| frame, QinQ allows multiple VLAN headers per Ethernet frame. |
There was a problem hiding this comment.
| Unlike the original 802.1q_, which allows a single VLAN header per Ethernet | |
| frame, QinQ allows multiple VLAN headers per Ethernet frame. | |
| 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. |
| In the evolution of Ethernet, QinQ serves as a bridge: it extends 802.1q_ and | ||
| forms the basis for later Metro Ethernet technologies. Its support for multiple | ||
| VLAN headers is essential for Metro Ethernet, allowing service providers to | ||
| encapsulate and segregate customer traffic on shared infrastructure. |
There was a problem hiding this comment.
| In the evolution of Ethernet, QinQ serves as a bridge: it extends 802.1q_ and | |
| forms the basis for later Metro Ethernet technologies. Its support for multiple | |
| VLAN headers is essential for Metro Ethernet, allowing service providers to | |
| encapsulate and segregate customer traffic on shared infrastructure. |
This is factually incorrect. The concept of "Metro Ethernet" predates QinQ. In https://web.archive.org/web/20140327090207/http://metroethernetforum.org/Assets/Technical_Specifications/PDF/MEF4.pdf (published in 2004), you will find:
The MEF architecture model is based
on the principle of layer network decomposition, where each layer network is constructed from a
particular set of networking technologies (e.g., Ethernet, SONET/SDH, MPLS, etc.)
Note that the definitions are intentionally abstracted away from any particular way to separate Ethernet traffic flow:
The Ethernet Virtual Connection (EVC) is the architecture construct that supports the association
of UNI reference points for the purpose of delivering an Ethernet flow between subscriber sites
across the MEN.
Development of QinQ started in 2002 so anything marketed as Metro Ethernet and based on standards would have to use something else.
In practice, all such networks are built on top of MPLS cores now. I cannot find the original technical specifications but my suspicious is that anything built on top of QinQ alone would ever satisfy the requirements of the Metro Ethernet Forum specs that define a lot of things about EVCs and their attributes related to frame delivery policies.
It's best not to mention Metro Ethernet here at all.
| * **The outer service tag (S-TAG):** Located closest to the Ethernet header, | ||
| the S-TAG is typically added by the provider's edge bridge to route traffic | ||
| through the Metro Ethernet network. It uses the Ethertype 0x88a8. |
There was a problem hiding this comment.
| * **The outer service tag (S-TAG):** Located closest to the Ethernet header, | |
| the S-TAG is typically added by the provider's edge bridge to route traffic | |
| through the Metro Ethernet network. It uses the Ethertype 0x88a8. | |
| * **The outer service tag (S-TAG):** The S-TAG is typically added by the provider. | |
| It uses the Ethertype 0x88a8 by default. | |
I'd say it is a part of the header. In any case, that information is irrelevant for the user — people who are curious about the frame header format can look it up.
Regarding the protocol, there is an option to set it to 802.1q (set interfaces ethernet ethX vif-s <N> protocol <802.1ad|802.1q>. It's not used often anymore now that 802.1ad is a standard but some legacy, pre-standard implementations may still exist in the wild.
| The IEEE 802.1ad_ (QinQ) frame includes two nested 802.1q_ VLAN headers, | ||
| commonly referred to as VLAN tags, or simply tags: |
There was a problem hiding this comment.
| The IEEE 802.1ad_ (QinQ) frame includes two nested 802.1q_ VLAN headers, | |
| commonly referred to as VLAN tags, or simply tags: | |
| The IEEE 802.1ad_ (QinQ) frame includes two VLAN tags: |
They are not nested, just placed next to each other in the header.
| * **The inner customer tag (C-TAG):** Encapsulated within the S-TAG and located | ||
| closest to the payload, the C-TAG is generated by the customer's equipment and | ||
| remains unchanged during transit. It uses the Ethertype 0x8100. |
There was a problem hiding this comment.
| * **The inner customer tag (C-TAG):** Encapsulated within the S-TAG and located | |
| closest to the payload, the C-TAG is generated by the customer's equipment and | |
| remains unchanged during transit. It uses the Ethertype 0x8100. | |
| * **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 represented as: |
There was a problem hiding this comment.
| In VyOS, these tag types are represented as: | |
| In VyOS, these tag types are associated with the following CLI options: |
2 participants
Change Summary
DOC: Proofreading ethernet.rst
Related Task(s)
Related PR(s)
Backport
Checklist: