From b6ff49dc4873e370083205d2f12bb2eb3894c7bc Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 17:23:58 +0300 Subject: chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The swap mechanism (RST-as-fallback for migrated MD pages) is dormant — docs/_rst_overrides.txt has been empty since the MyST flip trio (#1899/#1900/#1901) landed. The mechanism's surface area is dead weight and the rst-*.rst shadows scattered across the source tree cause Context7's parser to misclassify the project as RST. Sibling PR on rolling: yuriy/remove-rst-swap-mechanism Changes: - Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving subdirectory structure. They remain in the repo for reference; Sphinx excludes the folder via exclude_patterns. - Strip swap_sources.py invocation from docs/Makefile. - Strip jobs: pre_build/post_build block from .readthedocs.yml. - Strip rst-*.rst exclude entry and the _md_exclude.txt loader from docs/conf.py; replace with a single _rst_legacy exclude. - Delete scripts/swap_sources.py, tests/test_swap_sources.py, docs/_rst_overrides.txt. - Update AGENTS.md: drop the "RST override mechanism" section and the test-runner snippet for the deleted test. Verified: sphinx-build -b html with --keep-going produces identical warning set (68 unique), identical sitemap entry count (267), identical llms.txt entry count (22), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io) --- docs/configuration/interfaces/rst-bonding.rst | 727 ---------------- docs/configuration/interfaces/rst-bridge.rst | 424 ---------- docs/configuration/interfaces/rst-dummy.rst | 87 -- docs/configuration/interfaces/rst-ethernet.rst | 468 ----------- docs/configuration/interfaces/rst-geneve.rst | 100 --- docs/configuration/interfaces/rst-index.rst | 28 - docs/configuration/interfaces/rst-l2tpv3.rst | 167 ---- docs/configuration/interfaces/rst-loopback.rst | 65 -- docs/configuration/interfaces/rst-macsec.rst | 322 ------- .../interfaces/rst-openvpn-examples.rst | 877 ------------------- docs/configuration/interfaces/rst-openvpn.rst | 521 ------------ docs/configuration/interfaces/rst-pppoe.rst | 391 --------- .../interfaces/rst-pseudo-ethernet.rst | 54 -- docs/configuration/interfaces/rst-sstp-client.rst | 158 ---- docs/configuration/interfaces/rst-tunnel.rst | 307 ------- .../interfaces/rst-virtual-ethernet.rst | 117 --- docs/configuration/interfaces/rst-vti.rst | 43 - docs/configuration/interfaces/rst-vxlan.rst | 358 -------- docs/configuration/interfaces/rst-wireguard.rst | 435 ---------- docs/configuration/interfaces/rst-wireless.rst | 930 --------------------- docs/configuration/interfaces/rst-wwan.rst | 342 -------- 21 files changed, 6921 deletions(-) delete mode 100644 docs/configuration/interfaces/rst-bonding.rst delete mode 100644 docs/configuration/interfaces/rst-bridge.rst delete mode 100644 docs/configuration/interfaces/rst-dummy.rst delete mode 100644 docs/configuration/interfaces/rst-ethernet.rst delete mode 100644 docs/configuration/interfaces/rst-geneve.rst delete mode 100644 docs/configuration/interfaces/rst-index.rst delete mode 100644 docs/configuration/interfaces/rst-l2tpv3.rst delete mode 100644 docs/configuration/interfaces/rst-loopback.rst delete mode 100644 docs/configuration/interfaces/rst-macsec.rst delete mode 100644 docs/configuration/interfaces/rst-openvpn-examples.rst delete mode 100644 docs/configuration/interfaces/rst-openvpn.rst delete mode 100644 docs/configuration/interfaces/rst-pppoe.rst delete mode 100644 docs/configuration/interfaces/rst-pseudo-ethernet.rst delete mode 100644 docs/configuration/interfaces/rst-sstp-client.rst delete mode 100644 docs/configuration/interfaces/rst-tunnel.rst delete mode 100644 docs/configuration/interfaces/rst-virtual-ethernet.rst delete mode 100644 docs/configuration/interfaces/rst-vti.rst delete mode 100644 docs/configuration/interfaces/rst-vxlan.rst delete mode 100644 docs/configuration/interfaces/rst-wireguard.rst delete mode 100644 docs/configuration/interfaces/rst-wireless.rst delete mode 100644 docs/configuration/interfaces/rst-wwan.rst (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/rst-bonding.rst b/docs/configuration/interfaces/rst-bonding.rst deleted file mode 100644 index e0a374c3..00000000 --- a/docs/configuration/interfaces/rst-bonding.rst +++ /dev/null @@ -1,727 +0,0 @@ -:lastproofread: 2025-12-09 - -.. _bond-interface: - -####################### -Bond / link aggregation -####################### - -A **bonding interface** aggregates multiple network interfaces into a single -logical interface (referred to as a bond, :abbr:`LAG (Link Aggregation Group)`, -EtherChannel, or port-channel). - -The behavior of a bonding interface depends on the selected mode. Modes provide -either fault tolerance or a combination of load balancing and fault tolerance. -Additionally, the bonding interface can be configured for link integrity -monitoring. - - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bonding - :var1: bond0 - -Member interfaces -================= - -.. cfgcmd:: set interfaces bonding member interface - - **Add an interface to the bonding group.** - - **Example:** - - To configure eth0 and eth1 as members of the bonding interface bond0, execute - the following commands: - -.. code-block:: none - - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 - -Bond modes -============ - -.. cfgcmd:: set interfaces bonding mode <802.3ad | active-backup | - broadcast | round-robin | transmit-load-balance | adaptive-load-balance | - xor-hash> - - **Configure the bonding mode on the interface. The default mode is** - ``802.3ad``. - - The available modes are: - - * ``802.3ad`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - IEEE 802.3ad Dynamic Link Aggregation. Groups only member interfaces with - the same speed (e.g., 1 Gbps) and duplex settings. Member interfaces with - different speed and duplex settings are not included in the active bond. - - Provides load balancing and fault tolerance. Uses the :abbr:`LACP (Link - Aggregation Control Protocol)` to negotiate the bond with the switch. - * - **Traffic distribution:** - - Traffic is distributed according to the **transmit hash policy** - (default: XOR). - - The bonding driver applies an XOR operation to specific packet header fields, - generating a hash value that maps to a particular member interface. This - ensures the same network flow is consistently transmitted over the same member - interface. - - The transmit hash policy is configured via the ``hash-policy`` option. - * - **Failover:** - - If a member interface fails, the hash is recalculated to distribute - traffic among the remaining active member interfaces. - - .. note:: Not all transmit hash policies comply with 802.3ad, particularly - section 43.2.4. Using a non-compliant policy may result in out-of-order - packet delivery. - - * ``active-backup`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides fault tolerance. Only one member interface is active at a time. - Other member interfaces remain in a standby mode. - * - **Traffic distribution:** - - All traffic (incoming and outgoing) is routed via one active member interface. - * - **Failover:** - - If the designated member interface fails, all traffic is routed to - another member interface. The bonding driver sends a Gratuitous ARP - to update the peer's MAC address table, linking the bond's MAC address - to another physical port. - - * ``broadcast`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides maximum fault tolerance by duplicating traffic. - * - **Traffic distribution:** - - Every packet is duplicated and transmitted on **all** member interfaces. - * - **Failover:** - - Traffic flow is not interrupted as long as at least one member interface - remains active. - - * ``round-robin`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides load balancing and fault tolerance. - * - **Traffic distribution:** - - Packets are transmitted in sequential order across the member interfaces - (e.g., packet 1 > interface A, packet 2 > interface B, etc.). - * - **Failover:** - - If a member interface fails, the sequence skips the failed interface and - continues with the remaining active members. - - * ``transmit-load-balance`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing and fault tolerance. - * - **Traffic distribution:** - - **Outgoing:** Distributed across all active member interfaces based on - the current load. - - **Incoming:** Received by a designated member interface (active receiver). - * - **Failover:** - - If the active receiver fails, another member interface takes over as the new - active receiver. - - * ``adaptive-load-balance`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing identical to - ``transmit-load-balance``, receive load balancing for IPv4 traffic, and fault - tolerance for both incoming and outgoing traffic. - * - **Traffic distribution:** - - **Outgoing:** Identical to ``transmit-load-balance``. - - **Incoming:** Distributed based on ARP manipulation. For both local and remote - connections, the bonding driver intercepts ARP traffic and changes the source - MAC address to the MAC address of the least loaded member interface. - - All traffic from that peer is then routed to the chosen member interface. - * - **Failover:** - - If a member interface's state changes (fails, recovers, is added, or excluded), - the traffic is redistributed among all active member interfaces. - - * ``xor-hash``: Provides load balancing and fault tolerance based on a hash formula. - Distributes traffic and handles failover identically to ``802.3ad``, but operates - without the :abbr:`LACP (Link Aggregation Control Protocol)`. - -.. cfgcmd:: set interfaces bonding min-links <0-16> - - **Configure how many member interfaces must be active (in the link-up state) to - mark the bonding interface UP (carrier asserted).** - - This command applies only when the bonding interface is configured in 802.3ad - mode and functions like the Cisco EtherChannel min-links feature. It ensures - that a bonding interface is marked UP (carrier asserted) only when a specified - number of member interfaces are active (in the link-up state). This helps - guarantee a minimum level of bandwidth for higher-level services (such as - clustering) relying on the bonding interface. - - The default value is 0. This marks the bonding interface UP (carrier asserted) - whenever an active LACP aggregator exists, regardless of the number of member - interfaces in that aggregator. - - .. note:: In 802.3ad mode, a bond cannot be active without at least one active - member interface. Therefore, setting min-links to 0 or 1 has the same result: - the bonding interface is marked UP (carrier asserted). - -.. cfgcmd:: set interfaces bonding lacp-rate - - **Configure the rate at which the bonding interface requests its link - partner to send** :abbr:`LACPDUs (Link Aggregation Control Protocol Data - Units)` **in 802.3ad mode.** - - This command applies only when the bonding interface is configured in - 802.3ad mode. - - The following options are available: - - * **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. - - * **fast:** Requests the link partner to transmit LACPDUs every 1 second. - - -.. cfgcmd:: set interfaces bonding system-mac - - **Configure a specific MAC address for the bonding interface.** - - This sets the 802.3ad system MAC address, which is used for :abbr:`LACPDU (Link - Aggregation Control Protocol Data Unit)` exchanges with the link partner. - You can assign a fixed MAC address or generate a random one for these - :abbr:`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges. - - -.. cfgcmd:: set interfaces bonding hash-policy - - **Configure which transmit hash policy to use for distributing traffic across - member interfaces.** - - The following policies are available: - - * ``layer2`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Routes all traffic destined for a specific network peer through the same - member interface. The policy is 802.3ad-compliant. - * - **Hash inputs:** - - Source MAC address, destination MAC address, and Ethernet packet type ID. - * - **Formula:** - - .. code-block:: none - - hash = source MAC address XOR destination MAC address XOR packet type ID - member interface number = hash modulo member interface count - - * ``layer2+3`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Similar to ``layer2``, routes all traffic destined for a specific network - peer through the same member interface and is IEEE 802.3ad-compliant. Uses - both Layer 2 and Layer 3 information to provide a more balanced traffic distribution. - * - **Hash inputs:** - - * Source MAC address, destination MAC address, and Ethernet packet type ID. - * Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - * - **Formula:** - - .. code-block:: none - - hash = source MAC address XOR destination MAC address XOR packet type ID - hash = hash XOR source IP address XOR destination IP address - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) - member interface number = hash modulo member interface count - - For non-IP traffic, the formula is the same as for ``layer2``. - - * ``layer3+4`` - - .. list-table:: - :widths: 20 80 - - * - **Description:** - - Routes different connections (flows) destined for a specific network peer - through multiple member interfaces, but ensures each individual flow is - routed through only one member interface. - - .. note:: This policy is not fully 802.3ad-compliant. When a single TCP - or UDP flow contains both fragmented and unfragmented packets, the - algorithm may distribute them across different member interfaces. This - may result in out-of-order packet delivery, violating the 802.3ad standard. - * - **Hash inputs:** - - * Source port, destination port (if available). - * Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - * - **Formula:** - - .. code-block:: none - - hash = source port, destination port (as in the header) - hash = hash XOR source IP address XOR destination IP address - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) - member interface number = hash modulo member interface count - - For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the - source and destination port information is omitted. - - For non-IP traffic, the formula is the same as for ``layer2``. - -.. cfgcmd:: set interfaces bonding primary - - **Configure the primary member interface in the bond.** - - The primary member interface remains active as long as it is operational; - alternative member interfaces are used only if it fails. - - Use this configuration when a specific member interface is preferred, - such as one with higher throughput. - - This command applies only to ``active-backup``, ``transmit-load-balance``, and - ``adaptive-load-balance`` modes. - -.. cfgcmd:: set interfaces bonding arp-monitor interval