From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 21:50:08 +0300 Subject: feat: flip swap mechanism on sagitta — MD as primary, RST as override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 210 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty - conf.py exclude_patterns flipped: rst-*.rst excluded by default - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt - scripts/swap_sources.py imported from current (post-#1899 rewrite, with inverted rename direction) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py imported from current (post-#1899 rewrite) Side-effect: fixes the same 404 on /en/1.4/ View page source links that #1899 fixed for /en/rolling/ and #1900 fixed for /en/1.5/. Per-branch differences vs #1899: - sagitta has 210 stems vs current's 254 (sagitta has no vpp pages and fewer current-only features; cli + installation/cloud/aws are still RST-only on sagitta pending the title-level fix follow-up) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io --- docs/configuration/interfaces/bonding.md | 671 ++++++++++++++++ docs/configuration/interfaces/bonding.rst | 645 --------------- docs/configuration/interfaces/bridge.md | 367 +++++++++ docs/configuration/interfaces/bridge.rst | 339 -------- docs/configuration/interfaces/dummy.md | 94 +++ docs/configuration/interfaces/dummy.rst | 84 -- docs/configuration/interfaces/ethernet.md | 324 ++++++++ docs/configuration/interfaces/ethernet.rst | 305 -------- docs/configuration/interfaces/geneve.md | 101 +++ docs/configuration/interfaces/geneve.rst | 87 --- docs/configuration/interfaces/index.md | 28 + docs/configuration/interfaces/index.rst | 30 - docs/configuration/interfaces/l2tpv3.md | 198 +++++ docs/configuration/interfaces/l2tpv3.rst | 191 ----- docs/configuration/interfaces/loopback.md | 80 ++ docs/configuration/interfaces/loopback.rst | 73 -- docs/configuration/interfaces/macsec.md | 305 ++++++++ docs/configuration/interfaces/macsec.rst | 285 ------- docs/configuration/interfaces/md-bonding.md | 671 ---------------- docs/configuration/interfaces/md-bridge.md | 367 --------- docs/configuration/interfaces/md-dummy.md | 94 --- docs/configuration/interfaces/md-ethernet.md | 324 -------- docs/configuration/interfaces/md-geneve.md | 101 --- docs/configuration/interfaces/md-index.md | 28 - docs/configuration/interfaces/md-l2tpv3.md | 198 ----- docs/configuration/interfaces/md-loopback.md | 80 -- docs/configuration/interfaces/md-macsec.md | 305 -------- docs/configuration/interfaces/md-openvpn.md | 867 --------------------- docs/configuration/interfaces/md-pppoe.md | 443 ----------- .../configuration/interfaces/md-pseudo-ethernet.md | 68 -- docs/configuration/interfaces/md-sstp-client.md | 173 ---- docs/configuration/interfaces/md-tunnel.md | 281 ------- .../interfaces/md-virtual-ethernet.md | 118 --- docs/configuration/interfaces/md-vti.md | 40 - docs/configuration/interfaces/md-vxlan.md | 366 --------- docs/configuration/interfaces/md-wireguard.md | 434 ----------- docs/configuration/interfaces/md-wireless.md | 698 ----------------- docs/configuration/interfaces/md-wwan.md | 372 --------- docs/configuration/interfaces/openvpn.md | 867 +++++++++++++++++++++ docs/configuration/interfaces/openvpn.rst | 867 --------------------- docs/configuration/interfaces/pppoe.md | 443 +++++++++++ docs/configuration/interfaces/pppoe.rst | 403 ---------- docs/configuration/interfaces/pseudo-ethernet.md | 68 ++ docs/configuration/interfaces/pseudo-ethernet.rst | 67 -- 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 ++++++++ docs/configuration/interfaces/sstp-client.md | 173 ++++ docs/configuration/interfaces/sstp-client.rst | 150 ---- docs/configuration/interfaces/tunnel.md | 281 +++++++ docs/configuration/interfaces/tunnel.rst | 286 ------- docs/configuration/interfaces/virtual-ethernet.md | 118 +++ docs/configuration/interfaces/virtual-ethernet.rst | 110 --- docs/configuration/interfaces/vti.md | 40 + docs/configuration/interfaces/vti.rst | 40 - docs/configuration/interfaces/vxlan.md | 366 +++++++++ docs/configuration/interfaces/vxlan.rst | 349 --------- docs/configuration/interfaces/wireguard.md | 434 +++++++++++ docs/configuration/interfaces/wireguard.rst | 428 ---------- docs/configuration/interfaces/wireless.md | 698 +++++++++++++++++ docs/configuration/interfaces/wireless.rst | 618 --------------- docs/configuration/interfaces/wwan.md | 372 +++++++++ docs/configuration/interfaces/wwan.rst | 338 -------- 80 files changed, 11723 insertions(+), 11723 deletions(-) create mode 100644 docs/configuration/interfaces/bonding.md delete mode 100644 docs/configuration/interfaces/bonding.rst create mode 100644 docs/configuration/interfaces/bridge.md delete mode 100644 docs/configuration/interfaces/bridge.rst create mode 100644 docs/configuration/interfaces/dummy.md delete mode 100644 docs/configuration/interfaces/dummy.rst create mode 100644 docs/configuration/interfaces/ethernet.md delete mode 100644 docs/configuration/interfaces/ethernet.rst create mode 100644 docs/configuration/interfaces/geneve.md delete mode 100644 docs/configuration/interfaces/geneve.rst create mode 100644 docs/configuration/interfaces/index.md delete mode 100644 docs/configuration/interfaces/index.rst create mode 100644 docs/configuration/interfaces/l2tpv3.md delete mode 100644 docs/configuration/interfaces/l2tpv3.rst create mode 100644 docs/configuration/interfaces/loopback.md delete mode 100644 docs/configuration/interfaces/loopback.rst create mode 100644 docs/configuration/interfaces/macsec.md delete mode 100644 docs/configuration/interfaces/macsec.rst delete mode 100644 docs/configuration/interfaces/md-bonding.md delete mode 100644 docs/configuration/interfaces/md-bridge.md delete mode 100644 docs/configuration/interfaces/md-dummy.md delete mode 100644 docs/configuration/interfaces/md-ethernet.md delete mode 100644 docs/configuration/interfaces/md-geneve.md delete mode 100644 docs/configuration/interfaces/md-index.md delete mode 100644 docs/configuration/interfaces/md-l2tpv3.md delete mode 100644 docs/configuration/interfaces/md-loopback.md delete mode 100644 docs/configuration/interfaces/md-macsec.md delete mode 100644 docs/configuration/interfaces/md-openvpn.md delete mode 100644 docs/configuration/interfaces/md-pppoe.md delete mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/md-sstp-client.md delete mode 100644 docs/configuration/interfaces/md-tunnel.md delete mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/md-vti.md delete mode 100644 docs/configuration/interfaces/md-vxlan.md delete mode 100644 docs/configuration/interfaces/md-wireguard.md delete mode 100644 docs/configuration/interfaces/md-wireless.md delete mode 100644 docs/configuration/interfaces/md-wwan.md create mode 100644 docs/configuration/interfaces/openvpn.md delete mode 100644 docs/configuration/interfaces/openvpn.rst create mode 100644 docs/configuration/interfaces/pppoe.md delete mode 100644 docs/configuration/interfaces/pppoe.rst create mode 100644 docs/configuration/interfaces/pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/pseudo-ethernet.rst create mode 100644 docs/configuration/interfaces/rst-bonding.rst create mode 100644 docs/configuration/interfaces/rst-bridge.rst create mode 100644 docs/configuration/interfaces/rst-dummy.rst create mode 100644 docs/configuration/interfaces/rst-ethernet.rst create mode 100644 docs/configuration/interfaces/rst-geneve.rst create mode 100644 docs/configuration/interfaces/rst-index.rst create mode 100644 docs/configuration/interfaces/rst-l2tpv3.rst create mode 100644 docs/configuration/interfaces/rst-loopback.rst create mode 100644 docs/configuration/interfaces/rst-macsec.rst create mode 100644 docs/configuration/interfaces/rst-openvpn.rst create mode 100644 docs/configuration/interfaces/rst-pppoe.rst create mode 100644 docs/configuration/interfaces/rst-pseudo-ethernet.rst create mode 100644 docs/configuration/interfaces/rst-sstp-client.rst create mode 100644 docs/configuration/interfaces/rst-tunnel.rst create mode 100644 docs/configuration/interfaces/rst-virtual-ethernet.rst create mode 100644 docs/configuration/interfaces/rst-vti.rst create mode 100644 docs/configuration/interfaces/rst-vxlan.rst create mode 100644 docs/configuration/interfaces/rst-wireguard.rst create mode 100644 docs/configuration/interfaces/rst-wireless.rst create mode 100644 docs/configuration/interfaces/rst-wwan.rst create mode 100644 docs/configuration/interfaces/sstp-client.md delete mode 100644 docs/configuration/interfaces/sstp-client.rst create mode 100644 docs/configuration/interfaces/tunnel.md delete mode 100644 docs/configuration/interfaces/tunnel.rst create mode 100644 docs/configuration/interfaces/virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/virtual-ethernet.rst create mode 100644 docs/configuration/interfaces/vti.md delete mode 100644 docs/configuration/interfaces/vti.rst create mode 100644 docs/configuration/interfaces/vxlan.md delete mode 100644 docs/configuration/interfaces/vxlan.rst create mode 100644 docs/configuration/interfaces/wireguard.md delete mode 100644 docs/configuration/interfaces/wireguard.rst create mode 100644 docs/configuration/interfaces/wireless.md delete mode 100644 docs/configuration/interfaces/wireless.rst create mode 100644 docs/configuration/interfaces/wwan.md delete mode 100644 docs/configuration/interfaces/wwan.rst (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md new file mode 100644 index 00000000..ef6988e5 --- /dev/null +++ b/docs/configuration/interfaces/bonding.md @@ -0,0 +1,671 @@ +--- +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 + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: bonding + :var1: bond0 +``` + +### Member Interfaces + +```{eval-rst} +.. cfgcmd:: set interfaces bonding member interface + + Enslave `` interface to bond ``. +``` + +### Bond options + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding arp-monitor interval