From 88957530a3e174bfc61e8358cb2b28fd8f1fbbb6 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 18:46:21 +0300 Subject: feat: import MyST swap mechanism + content for sagitta (replaces #1886) Replaces the broken #1886 with a fresh, properly-converted MyST set for the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897. This PR: - Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc fallback) on sagittas RST. Post-processed via the pipelines postprocess stage (10 ordered fixes for blanks, admonitions, label hyphens, pandoc artifacts, structural blanks, linter markers). Compared to the broken #1886 content (which was left over from an earlier stage-1-only run): zero raw `
` remnants. - For 23 stems where sagittas RST is byte-identical with currents RST (mostly stable policy/protocol pages and the 404 page), reuses currents already-validated md-*.md content rather than re-converting. - Drops cli and installation/cloud/aws from sagittas swap set: their RST has SEVERE/4 "Title level inconsistent" errors that crash rst-to-myst; they need an independent RST-source fix and are kept as RST-only for now. - Adds the per-page swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, the matching tests under tests/, _swap.txt with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile swap-wrapped targets, .readthedocs.yml swap pre/post hooks. - Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg static assets; flips html_logo to vyos-logo.webp. - Adds the MyST swap-related blocks to docs/conf.py only: myst_enable_extensions, myst_fence_as_directive, md-*.md exclude patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources setup hooks. github_version fallback set to 'sagitta' to match the branch (parallel to currents 'current' and circinuss 'circinus'). Deliberately excluded (per user direction): - llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will land separately for sagitta via #1870 plus a new sagitta-specific llms.txt template PR. The conf.py here does not pull those extensions in, so the build does not depend on the new pip packages. Verification before pushing: - 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1). - 0 files contain raw `
+ + Send ICMP echo requests to destination host. There are multiple options to + ping, inkl. VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + do-not-fragment + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + +``` + +```{eval-rst} +.. opcmd:: traceroute + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + Track network path to specified node + + + ipv4 Track network path to + ipv6 Track network path to + +``` + +### Advanced Connectivity Tests + +```{eval-rst} +.. opcmd:: monitor traceroute + + However, another helper is available which combines ping and traceroute + into a single tool. An example of its output is shown: + + .. code-block:: none + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + + .. note:: The output consumes the screen and will replace your command + prompt. + + Several options are available for changing the display output. Press `h` to + invoke the built in help system. To quit, just press `q` and you'll be + returned to the VyOS command prompt. +``` + +### IPv6 Topology Discovery + +IPv6 uses different techniques to discover its Neighbors/topology. + +#### Router Discovery + +```{eval-rst} +.. opcmd:: force ipv6-rd interface [address ] + + Discover routers via eth0. + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-rd interface eth0 + Soliciting ff02::2 (ff02::2) on eth0... + + Hop limit : 60 ( 0x3c) + Stateful address conf. : No + Stateful other conf. : No + Mobile home agent : No + Router preference : high + Neighbor discovery proxy : No + Router lifetime : 1800 (0x00000708) seconds + Reachable time : unspecified (0x00000000) + Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 +``` + +#### Neighbor Discovery + +```{eval-rst} +.. opcmd:: force ipv6-nd interface address + + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + + Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... + Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 + +``` + +## Interface names + +If you find the names of your interfaces have changed, this could be because +your MAC addresses have changed. + +- For example, you have a VyOS VM with 4 Ethernet interfaces named + eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different + host and find your interfaces now are eth4, eth5, eth6 and eth7. + + One way to fix this issue **taking control of the MAC addresses** is: + + Log into VyOS and run this command to display your interface settings. + + ```none + show interfaces detail + ``` + + Take note of MAC addresses. + + Now, in order to update a MAC address in the configuration, run this command + specifying the interface name and MAC address you want. + + ```none + set interfaces eth0 hw-id 00:0c:29:da:a4:fe + ``` + + If it is a VM, go into the settings of the host and set the MAC address to + the settings found in the config.boot file. You can also set the MAC to + static if the host allows so. + +- Another example could be when cloning VyOS VMs in GNS3 and you get into the + same issue: interface names have changed. + + And **a more generic way to fix it** is just deleting every MAC address at + the configuration file of the cloned machine. They will be correctly + regenerated automatically. + +## Monitoring + +VyOS features several monitoring tools. + +```none +vyos@vyos:~$ monitor +Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service +``` + +### Traffic Dumps + +To monitor interface traffic, issue the {code}`monitor traffic interface ` +command, replacing `` with your chosen interface. + +```none +vyos@vyos:~$ monitor traffic interface eth0 +tcpdump: verbose output suppressed, use -v or -vv for full protocol decode +listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes +15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 +15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 +15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 +15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 +^C +4 packets captured +4 packets received by filter +0 packets dropped by kernel +vyos@vyos:~$ +``` + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +```none +vyos@vyos:~$ monitor traffic interface eth0 +Possible completions: + Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file +``` + +### Interface Bandwidth Usage + +to take a quick view on the used bandwidth of an interface use the `monitor +bandwidth` command + +```none +vyos@vyos:~$ monitor bandwidth interface eth0 +``` + +show the following: + +```none + B (RX Bytes/second) +198.00 .|....|..................................................... +165.00 .|....|..................................................... +132.00 ||..|.|..................................................... + 99.00 ||..|.|..................................................... + 66.00 |||||||..................................................... + 33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + + KiB (TX Bytes/second) + 3.67 ......|..................................................... + 3.06 ......|..................................................... + 2.45 ......|..................................................... + 1.84 ......|..................................................... + 1.22 ......|..................................................... + 0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 +``` + +### Interface Performance + +To take a look on the network bandwidth between two nodes, the `monitor +bandwidth-test` command is used to run iperf. + +```none +vyos@vyos:~$ monitor bandwidth-test +Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test +``` + +- The `accept` command opens a listening iperf server on TCP Port 5001 +- The `initiate` command connects to that server to perform the test. + +```none +vyos@vyos:~$ monitor bandwidth-test initiate +Possible completions: + Initiate a bandwidth test to specified host (port TCP/5001) + + +``` + +### Monitor command + +The `monitor command` command allows you to repeatedly run a command to view +a continuously refreshed output. The command is run and output every 2 seconds, +allowing you to monitor the output continuously without having to re-run the +command. This can be useful to follow routing adjacency formation. + +```none +vyos@router:~$ monitor command "show interfaces" +``` + +Will clear the screen and show you the output of `show interfaces` every +2 seconds. + +```none +Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 + +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 192.168.1.1/24 u/u +eth0.5 198.51.100.4/24 u/u WAN +lo 127.0.0.1/8 u/u + ::1/128 +vti0 172.25.254.2/30 u/u +vti1 172.25.254.9/30 u/u +``` + +## Terminal/Console + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the `clear` command in Operational mode. + +to clear the console output + +```none +vyos@vyos:~$ clear console +``` + +to clear interface counters + +```none +# clear all interfaces +vyos@vyos:~$ clear interface ethernet counters +# clear specific interface +vyos@vyos:~$ clear interface ethernet eth0 counters +``` + +The command follow the same logic as the `set` command in configuration mode. + +```none +# clear all counters of a interface type +vyos@vyos:~$ clear interface counters +# clear counter of a interface in interface_type +vyos@vyos:~$ clear interface counters +``` + +to clear counters on firewall rulesets or single rules + +```none +vyos@vyos:~$ clear firewall name counters +vyos@vyos:~$ clear firewall name rule counters + +vyos@vyos:~$ clear firewall ipv6-name counters +vyos@vyos:~$ clear firewall ipv6-name rule counters +``` + +## System Information + +(boot-steps)= + +### Boot Steps + +VyOS 1.2 uses [Debian Jessie] as the base Linux operating system. Jessie was +the first version of Debian that uses [systemd] as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel `/boot/vmlinuz` +3. Kernel Launches Systemd `/lib/systemd/systemd` +4. Systemd loads the VyOS service file + `/lib/systemd/system/vyos-router.service` +5. The service file launches the VyOS router init script + `/usr/libexec/vyos/init/vyos-router` - this is part of the [vyatta-cfg] + Debian package + +> 1. Starts [FRR] - successor to [GNU Zebra] and [Quagga] +> 2. Initialises the boot configuration file - copies over +> `config.boot.default` if there is no configuration +> 3. Runs the configuration migration, if the configuration is for an older +> version of VyOS +> 4. Runs The pre-config script, if there is one +> `/config/scripts/vyos-preconfig-bootup.script` +> 5. If the config file was upgraded, runs any post upgrade scripts +> `/config/scripts/post-upgrade.d` +> 6. Starts `rl-system` and `firewall` +> 7. Mounts the `/boot` partition +> 8. The boot configuration file is then applied by `/opt/vyatta/sbin/ +> vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot` +> +> > 1. The config loader script writes log entries to +> > `/var/log/vyatta-config-loader.log` +> +> 09. Runs `telinit q` to tell the init system to reload `/etc/inittab` +> 10. Finally it runs the post-config script +> `/config/scripts/vyos-postconfig-bootup.script` + + + +[debian jessie]: https://www.debian.org/releases/jessie/ +[frr]: https://frrouting.org/ +[gnu zebra]: https://www.gnu.org/software/zebra/ +[pcap filter expressions]: http://www.tcpdump.org/manpages/pcap-filter.7.html +[quagga]: https://www.quagga.net/ +[systemd]: https://freedesktop.org/wiki/Software/systemd/ +[tshark]: https://www.wireshark.org/docs/man-pages/tshark.html +[vyatta-cfg]: https://github.com/vyos/vyatta-cfg -- cgit v1.2.3