feat: activate 106 visual-validated canaries via swap

Imports 105 MD files (plus quick-start already present) from
origin/myst/current and adds them to docs/_swap.txt. The selection
is the BackstopJS visual-passers cohort: pages with <5% rendered
diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to
those with an RST counterpart on current and no cmdincludemd usage
(template-format reconciliation pending).

Local sphinx-build with all 106 swapped: succeeded with 100
warnings (vs 95 baseline). The 5 new warnings are all undefined
cross-reference labels, not build failures:
- contributing/development.md (missing 'coding-guidelines')
- operation/upgrade-recovery.md (3 missing 'how_it_works' /
  'cancelling_recovery')
- vpp/configuration/dataplane/{buffers,memory,unix}.md (missing
  'vpp_config_dataplane_*' labels)

Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt
BackstopJS report: claude/gifted-hertz-74b9f9 worktree
(visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build.

🤖 Generated by [robots](https://vyos.io)

5 files changed, 288 insertions, 0 deletions

diff --git a/docs/troubleshooting/md-index.md b/docs/troubleshooting/md-index.md
new file mode 100644
index 00000000..31dbd87b
--- /dev/null
+++ b/docs/troubleshooting/md-index.md
@@ -0,0 +1,17 @@
+(troubleshooting)=
+
+# Troubleshooting
+
+Sometimes things break or don't work as expected. This section describes
+several troubleshooting tools provided by VyOS that can help when something
+goes wrong.
+
+```{toctree}
+:maxdepth: 1
+
+connectivity
+interfaces
+monitoring
+terminal
+system
+```
diff --git a/docs/troubleshooting/md-interfaces.md b/docs/troubleshooting/md-interfaces.md
new file mode 100644
index 00000000..553cbf90
--- /dev/null
+++ b/docs/troubleshooting/md-interfaces.md
@@ -0,0 +1,36 @@
+# 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 ethernet 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.
diff --git a/docs/troubleshooting/md-monitoring.md b/docs/troubleshooting/md-monitoring.md
new file mode 100644
index 00000000..4016a949
--- /dev/null
+++ b/docs/troubleshooting/md-monitoring.md
@@ -0,0 +1,148 @@
+# 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 <name>`
+command, replacing `<name>` 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 {kbd}`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:
+  <Enter>       Execute the current command
+  filter        Monitor traffic matching filter conditions
+  save          Save traffic dump from an interface to a file
+```
+
+## Interface Bandwidth Usage
+
+To quickly view the bandwidth usage of an interface, use the `monitor bandwidth` command:
+
+```none
+vyos@vyos:~$ monitor bandwidth interface eth0
+```
+
+This shows 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:
+  <hostname>    Initiate a bandwidth test to specified host (port TCP/5001)
+  <x.x.x.x>
+  <h:h:h:h:h:h:h:h>
+```
+
+## 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
+```
diff --git a/docs/troubleshooting/md-system.md b/docs/troubleshooting/md-system.md
new file mode 100644
index 00000000..e855e385
--- /dev/null
+++ b/docs/troubleshooting/md-system.md
@@ -0,0 +1,48 @@
+# 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
diff --git a/docs/troubleshooting/md-terminal.md b/docs/troubleshooting/md-terminal.md
new file mode 100644
index 00000000..0d421972
--- /dev/null
+++ b/docs/troubleshooting/md-terminal.md
@@ -0,0 +1,39 @@
+# 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 follows the same logic as the `set` command in configuration mode.
+
+```none
+# clear all counters of an interface type
+vyos@vyos:~$ clear interface <interface_type> counters
+# clear counter of an interface in interface_type
+vyos@vyos:~$ clear interface <interface_type> <interface_name> counters
+```
+
+to clear counters on firewall rulesets or single rules
+
+```none
+vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters
+vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters
+
+vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters
+vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters
+```