From eb85660173a3a0b0e3dcd63221ec104471948958 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Mon, 16 Feb 2026 13:13:04 +0100 Subject: DOC: Proofreading ethernet.rst (#1740) * DOC: Proofreading ethernet.rst * doc: indentation configuration * Apply suggestions from code review Co-authored-by: Daniil Baturin * Remove mentions of Metro Ethernet --------- Co-authored-by: Daniil Baturin --- docs/_include/interface-eapol.txt | 81 +++++++++++++++++++++++++-------- docs/_include/interface-evpn-uplink.txt | 2 +- docs/_include/interface-vlan-8021ad.txt | 55 +++++++++++----------- 3 files changed, 89 insertions(+), 49 deletions(-) (limited to 'docs/_include') 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 ` section. .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} eapol ca-certificate - 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. + + ```` 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 - set pki ca eapol-server-root-ca + set pki ca eapol-server-intermediate-ca + set pki ca eapol-server-root-ca set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol ca-certificate eapol-server-intermediate-ca .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} eapol certificate - 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. + + ```` 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 - set pki ca eapol-client-root-ca - set pki certificate eapol-client certificate - set pki certificate eapol-client private key + set pki ca eapol-client-intermediate-ca + set pki ca eapol-client-root-ca + set pki certificate eapol-client certificate + set pki certificate eapol-client private key 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 }} -- cgit v1.2.3