From 3fd1787d50dda76619647dd95ea6e1d421204734 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 17:19:31 +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 in May 2026. The mechanism's surface area (scripts/swap_sources.py, its 245-line test, RTD pre/post hooks, Makefile glue, conf.py dynamic loader) is dead weight, and the rst-*.rst shadows scattered across the source tree cause Context7's parser to misclassify the project as RST. 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; Context7 excludes it via excludeFolders. - Strip swap_sources.py invocation from docs/Makefile (swap/restore targets, : swap deps, trap chains). - 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 context7.json: add docs/_rst_legacy to excludeFolders; fix stale "Branch current tracks…" rule to "Branch rolling tracks…" (default branch was renamed 2026-05-10). - Update AGENTS.md: drop the "RST override mechanism" section and the test-runner snippet for the deleted test; describe _rst_legacy as archive only. Verified: sphinx-build -b html with --keep-going produces identical warning set (68 unique), identical sitemap entry count (257), identical llms.txt entry count (22), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io) --- docs/configuration/interfaces/rst-bonding.rst | 767 ----------------- 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 | 929 -------------------- 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 | 308 ------- .../interfaces/rst-virtual-ethernet.rst | 117 --- docs/configuration/interfaces/rst-vti.rst | 115 --- docs/configuration/interfaces/rst-vxlan.rst | 358 -------- docs/configuration/interfaces/rst-wireguard.rst | 439 ---------- docs/configuration/interfaces/rst-wireless.rst | 931 --------------------- docs/configuration/interfaces/rst-wwan.rst | 342 -------- 21 files changed, 7091 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 7637790c..00000000 --- a/docs/configuration/interfaces/rst-bonding.rst +++ /dev/null @@ -1,767 +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