From e7a0bebdb5dc4b436b8b610bcb4f01afc33152e0 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 17:27:05 +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 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 PRs: - yuriy/remove-rst-swap-mechanism (rolling) - yuriy/remove-rst-swap-mechanism-circinus Changes: - Move 210 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 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. Note: .readthedocs.yml on sagitta has no jobs: block to remove (the swap was wired only at build-time via the Makefile chain on this branch). Verified: sphinx-build -b html with --keep-going produces identical warning set (409 unique — pre-existing cli.rst/aws.rst title-level warnings on this branch), identical sitemap entry count (215), identical llms.txt entry count (23), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io) --- docs/configuration/interfaces/rst-bonding.rst | 645 --------------- docs/configuration/interfaces/rst-bridge.rst | 339 -------- docs/configuration/interfaces/rst-dummy.rst | 84 -- docs/configuration/interfaces/rst-ethernet.rst | 305 -------- docs/configuration/interfaces/rst-geneve.rst | 87 --- docs/configuration/interfaces/rst-index.rst | 30 - docs/configuration/interfaces/rst-l2tpv3.rst | 191 ----- docs/configuration/interfaces/rst-loopback.rst | 73 -- docs/configuration/interfaces/rst-macsec.rst | 285 ------- docs/configuration/interfaces/rst-openvpn.rst | 867 --------------------- docs/configuration/interfaces/rst-pppoe.rst | 403 ---------- .../interfaces/rst-pseudo-ethernet.rst | 67 -- docs/configuration/interfaces/rst-sstp-client.rst | 150 ---- docs/configuration/interfaces/rst-tunnel.rst | 286 ------- .../interfaces/rst-virtual-ethernet.rst | 110 --- docs/configuration/interfaces/rst-vti.rst | 40 - docs/configuration/interfaces/rst-vxlan.rst | 349 --------- docs/configuration/interfaces/rst-wireguard.rst | 428 ---------- docs/configuration/interfaces/rst-wireless.rst | 618 --------------- docs/configuration/interfaces/rst-wwan.rst | 338 -------- 20 files changed, 5695 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.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 27f1bbed..00000000 --- a/docs/configuration/interfaces/rst-bonding.rst +++ /dev/null @@ -1,645 +0,0 @@ -:lastproofread: 2021-06-30 - -.. _bond-interface: - -####################### -Bond / Link Aggregation -####################### - -The bonding interface provides a method for aggregating multiple network -interfaces into a single logical "bonded" interface, or LAG, or ether-channel, -or port-channel. The behavior of the bonded interfaces depends upon the mode; -generally speaking, modes provide either hot standby or load balancing services. -Additionally, link integrity monitoring may be performed. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bonding - :var1: bond0 - -Member Interfaces -================= - -.. cfgcmd:: set interfaces bonding member interface - - Enslave `` interface to bond ``. - -Bond options -============ - -.. cfgcmd:: set interfaces bonding mode <802.3ad | active-backup | - broadcast | round-robin | transmit-load-balance | adaptive-load-balance | - xor-hash> - - Specifies one of the bonding policies. The default is 802.3ad. Possible - values are: - - * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation - groups that share the same speed and duplex settings. Utilizes all slaves - in the active aggregator according to the 802.3ad specification. - - Slave selection for outgoing traffic is done according to the transmit - hash policy, which may be changed from the default simple XOR policy via - the :cfgcmd:`hash-policy` option, documented below. - - .. note:: Not all transmit policies may be 802.3ad compliant, particularly - in regards to the packet misordering requirements of section 43.2.4 - of the 802.3ad standard. - - * ``active-backup`` - Active-backup policy: Only one slave in the bond is - active. A different slave becomes active if, and only if, the active slave - fails. The bond's MAC address is externally visible on only one port - (network adapter) to avoid confusing the switch. - - When a failover occurs in active-backup mode, bonding will issue one or - more gratuitous ARPs on the newly active slave. One gratuitous ARP is - issued for the bonding master interface and each VLAN interfaces - configured above it, provided that the interface has at least one IP - address configured. Gratuitous ARPs issued for VLAN interfaces are tagged - with the appropriate VLAN id. - - This mode provides fault tolerance. The :cfgcmd:`primary` option, - documented below, affects the behavior of this mode. - - * ``broadcast`` - Broadcast policy: transmits everything on all slave - interfaces. - - This mode provides fault tolerance. - - * ``round-robin`` - Round-robin policy: Transmit packets in sequential - order from the first available slave through the last. - - This mode provides load balancing and fault tolerance. - - * ``transmit-load-balance`` - Adaptive transmit load balancing: channel - bonding that does not require any special switch support. - - Incoming traffic is received by the current slave. If the receiving slave - fails, another slave takes over the MAC address of the failed receiving - slave. - - * ``adaptive-load-balance`` - Adaptive load balancing: includes - transmit-load-balance plus receive load balancing for IPV4 traffic, and - does not require any special switch support. The receive load balancing - is achieved by ARP negotiation. The bonding driver intercepts the ARP - Replies sent by the local system on their way out and overwrites the - source hardware address with the unique hardware address of one of the - slaves in the bond such that different peers use different hardware - addresses for the server. - - Receive traffic from connections created by the server is also balanced. - When the local system sends an ARP Request the bonding driver copies and - saves the peer's IP information from the ARP packet. When the ARP Reply - arrives from the peer, its hardware address is retrieved and the bonding - driver initiates an ARP reply to this peer assigning it to one of the - slaves in the bond. A problematic outcome of using ARP negotiation for - balancing is that each time that an ARP request is broadcast it uses the - hardware address of the bond. Hence, peers learn the hardware address - of the bond and the balancing of receive traffic collapses to the current - slave. This is handled by sending updates (ARP Replies) to all the peers - with their individually assigned hardware address such that the traffic - is redistributed. Receive traffic is also redistributed when a new slave - is added to the bond and when an inactive slave is re-activated. The - receive load is distributed sequentially (round robin) among the group - of highest speed slaves in the bond. - - When a link is reconnected or a new slave joins the bond the receive - traffic is redistributed among all active slaves in the bond by initiating - ARP Replies with the selected MAC address to each of the clients. The - updelay parameter (detailed below) must be set to a value equal or greater - than the switch's forwarding delay so that the ARP Replies sent to the - peers will not be blocked by the switch. - - * ``xor-hash`` - XOR policy: Transmit based on the selected transmit - hash policy. The default policy is a simple [(source MAC address XOR'd - with destination MAC address XOR packet type ID) modulo slave count]. - Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` - option, described below. - - This mode provides load balancing and fault tolerance. - -.. cfgcmd:: set interfaces bonding min-links <0-16> - - Specifies the minimum number of links that must be active before asserting - carrier. It is similar to the Cisco EtherChannel min-links feature. This - allows setting the minimum number of member ports that must be up (link-up - state) before marking the bond device as up (carrier on). This is useful for - situations where higher level services such as clustering want to ensure a - minimum number of low bandwidth links are active before switchover. - - This option only affects 802.3ad mode. - - The default value is 0. This will cause the carrier to be asserted - (for 802.3ad mode) whenever there is an active aggregator, - regardless of the number of available links in that aggregator. - - .. note:: Because an aggregator cannot be active without at least one - available link, setting this option to 0 or to 1 has the exact same - effect. - -.. cfgcmd:: set interfaces bonding lacp-rate - - Option specifying the rate in which we'll ask our link partner to transmit - LACPDU packets in 802.3ad mode. - - This option only affects 802.3ad mode. - - * slow: Request partner to transmit LACPDUs every 30 seconds - - * fast: Request partner to transmit LACPDUs every 1 second - - The default value is slow. - -.. cfgcmd:: set interfaces bonding system-mac - - This option allow to specifies the 802.3ad system MAC address.You can set a - random mac-address that can be used for these LACPDU exchanges. - -.. cfgcmd:: set interfaces bonding hash-policy - - * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field - to generate the hash. The formula is - - .. code-block:: none - - hash = source MAC XOR destination MAC XOR packet type ID - slave number = hash modulo slave count - - This algorithm will place all traffic to a particular network peer on - the same slave. - - This algorithm is 802.3ad compliant. - - * **layer2+3** - This policy uses a combination of layer2 and layer3 - protocol information to generate the hash. Uses XOR of hardware MAC - addresses and IP addresses to generate the hash. The formula is: - - .. code-block:: none - - hash = source MAC XOR destination MAC XOR packet type ID - hash = hash XOR source IP XOR destination IP - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) - - And then hash is reduced modulo slave count. - - If the protocol is IPv6 then the source and destination addresses are - first hashed using ipv6_addr_hash. - - This algorithm will place all traffic to a particular network peer on the - same slave. For non-IP traffic, the formula is the same as for the layer2 - transmit hash policy. - - This policy is intended to provide a more balanced distribution of traffic - than layer2 alone, especially in environments where a layer3 gateway - device is required to reach most destinations. - - This algorithm is 802.3ad compliant. - - * **layer3+4** - This policy uses upper layer protocol information, when - available, to generate the hash. This allows for traffic to a particular - network peer to span multiple slaves, although a single connection will - not span multiple slaves. - - The formula for unfragmented TCP and UDP packets is - - .. code-block:: none - - hash = source port, destination port (as in the header) - hash = hash XOR source IP XOR destination IP - hash = hash XOR (hash RSHIFT 16) - hash = hash XOR (hash RSHIFT 8) - - And then hash is reduced modulo slave count. - - If the protocol is IPv6 then the source and destination addresses are - first hashed using ipv6_addr_hash. - - For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol - traffic, the source and destination port information is omitted. For - non-IP traffic, the formula is the same as for the layer2 transmit hash - policy. - - This algorithm is not fully 802.3ad compliant. A single TCP or UDP - conversation containing both fragmented and unfragmented packets will see - packets striped across two interfaces. This may result in out of order - delivery. Most traffic types will not meet these criteria, as TCP rarely - fragments traffic, and most UDP traffic is not involved in extended - conversations. Other implementations of 802.3ad may or may not tolerate - this noncompliance. - -.. cfgcmd:: set interfaces bonding primary - - An `` specifying which slave is the primary device. The specified - device will always be the active slave while it is available. Only when the - primary is off-line will alternate devices be used. This is useful when one - slave is preferred over another, e.g., when one slave has higher throughput - than another. - - The primary option is only valid for active-backup, transmit-load-balance, - and adaptive-load-balance mode. - -.. cfgcmd:: set interfaces bonding arp-monitor interval