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 `<div class=>` 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 `<div class=` (the breakage that took down /en/1.5/).
- conf.py copyright/version/release preserve sagittas values
  (2024 / 1.4 / "1.4.x (sagitta)") - not currents.
- html_title from currents conf.py removed - PR #1880 is the right place
  for sagittas branch-localized title.

Supersedes / closes on merge:

- #1886 (broken converter output, would break /en/1.4/ if merged).

Generated by robots https://vyos.io

5 files changed, 497 insertions, 0 deletions

diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md
new file mode 100644
index 00000000..ea077c8a
--- /dev/null
+++ b/docs/operation/md-boot-options.md
@@ -0,0 +1,53 @@
+(boot-options)=
+
+# Boot Options
+
+:::{warning}
+This function may be highly disruptive.
+It may cause major service interruption, so make sure you really
+need it and verify your input carefully.
+:::
+
+VyOS has several kernel command line options to modify the normal boot
+process.
+To add an option, select the desired image in GRUB menu at load
+time, press **e**, edit the first line, and press **Ctrl-x** to boot when
+ready.
+
+```{image} /_static/images/boot-options.png
+:align: center
+:width: 80%
+```
+
+## Specify custom config file
+
+Tells the system to use specified file instead of `/config/config.boot`.
+If specified file does not exist or is not readable, fall back to
+default config. No additional verification is performed, so make sure
+you specify a valid config file.
+
+```none
+vyos-config=/path/to/file
+```
+
+To load the *factory default* config, use:
+
+```none
+vyos-config=/opt/vyatta/etc/config.boot.default
+```
+
+## Disable specific boot process steps
+
+These options disable some boot steps. Make sure you understand the
+{ref}`boot process <boot-steps>` well before using them!
+
+```{eval-rst}
+.. glossary::
+
+    no-vyos-migrate
+      Do not perform config migration.
+
+    no-vyos-firewall
+      Do not initialize default firewall chains, renders any firewall
+      configuration unusable.
+```
diff --git a/docs/operation/md-index.md b/docs/operation/md-index.md
new file mode 100644
index 00000000..f4328541
--- /dev/null
+++ b/docs/operation/md-index.md
@@ -0,0 +1,12 @@
+# Operation Mode
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   information
+   boot-options
+   password-recovery
+   raid
+```
diff --git a/docs/operation/md-information.md b/docs/operation/md-information.md
new file mode 100644
index 00000000..314811ec
--- /dev/null
+++ b/docs/operation/md-information.md
@@ -0,0 +1,159 @@
+---
+lastproofread: '2021-07-07'
+---
+
+(information)=
+
+# Information
+
+VyOS features a rich set of operational level commands to retrieve arbitrary
+information about your running system.
+
+## Hardware
+
+(hardware_usb)=
+
+### USB
+
+In the past serial interface have been defined as ttySx and ttyUSBx where x was
+an instance number of the serial interface. It was discovered that from system
+boot to system boot the mapping of USB based serial interfaces will differ,
+depending which driver was loaded first by the operating system. This will
+become rather painful if you not only have serial interfaces for a console
+server connected but in addition also a serial backed {ref}`wwan-interface`.
+
+To overcome this issue and the fact that in almost 50% of all cheap USB to
+serial converters there is no serial number programmed, the USB to serial
+interface is now directly identified by the USB root bridge and bus it connects
+to. This somehow mimics the new network interface definitions we see in recent
+Linux distributions.
+
+For additional details you can refer to <https://vyos.dev/T2490>.
+
+```{eval-rst}
+.. opcmd:: show hardware usb
+
+  Retrieve a tree like representation of all connected USB devices.
+
+  .. note:: If a device is unplugged and re-plugged it will receive a new
+    Port, Dev, If identification.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show hardware usb
+    /:  Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M
+        |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M
+            |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M
+            |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M
+            |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M
+            |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M
+    /:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M
+    /:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M
+        |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M
+        |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M
+            |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+            |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M
+                |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M
+                    |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                    |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                    |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                    |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+                |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M
+
+```
+
+```{eval-rst}
+.. opcmd:: show hardware usb serial
+
+  Retrieve a list and description of all connected USB serial devices. The
+  device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing
+  the serial console as console-server device.
+
+  .. code-block:: none
+
+    vyos@vyos$ show hardware usb serial
+    Device           Model               Vendor
+    ------           ------              ------
+    usb0b1.3p1.0     MC7710              Sierra Wireless, Inc.
+    usb0b1.3p1.2     MC7710              Sierra Wireless, Inc.
+    usb0b1.3p1.3     MC7710              Sierra Wireless, Inc.
+    usb0b1p1.0       USB-Serial_Controller_D Prolific Technology, Inc.
+    usb0b2.3.3.4p1.0 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.3.4p1.1 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.3.4p1.2 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.3.4p1.3 Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.0   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.1   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.2   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.3.4p1.3   Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.0     Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.1     Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.2     Quad_RS232-HS       Future Technology Devices International, Ltd
+    usb0b2.4p1.3     Quad_RS232-HS       Future Technology Devices International, Ltd
+```
+
+(information-version)=
+
+## Version
+
+```{eval-rst}
+.. opcmd:: show version
+
+  Return the current running VyOS version and build information. This includes
+  also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus``
+  on VyOS 1.3 and ``sagitta`` on VyOS 1.4.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show version
+
+    Version:          VyOS 1.4-rolling-202106270801
+    Release Train:    sagitta
+
+    Built by:         autobuild@vyos.net
+    Built on:         Sun 27 Jun 2021 09:50 UTC
+    Build UUID:       ab43e735-edcb-405a-9f51-f16a1b104e52
+    Build Commit ID:  f544d75eab758f
+
+    Architecture:     x86_64
+    Boot via:         installed image
+    System type:      KVM guest
+
+    Hardware vendor:  QEMU
+    Hardware model:   Standard PC (i440FX + PIIX, 1996)
+    Hardware S/N:
+    Hardware UUID:    Unknown
+
+    Copyright:        VyOS maintainers and contributors
+```
+
+```{eval-rst}
+.. opcmd:: show version kernel
+
+  Return version number of the Linux Kernel used in this release.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show version kernel
+    5.10.46-amd64-vyos
+```
+
+```{eval-rst}
+.. opcmd:: show version frr
+
+  Return version number of FRR (Free Range Routing - https://frrouting.org/)
+  used in this release. This is the routing control plane and a successor to GNU
+  Zebra and Quagga.
+
+    .. code-block:: none
+
+      vyos@vyos:~$ show version frr
+      FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos).
+      Copyright 1996-2005 Kunihiro Ishiguro, et al.
+```
diff --git a/docs/operation/md-password-recovery.md b/docs/operation/md-password-recovery.md
new file mode 100644
index 00000000..91f3d60f
--- /dev/null
+++ b/docs/operation/md-password-recovery.md
@@ -0,0 +1,24 @@
+(password-recovery)=
+
+# Password Recovery
+
+Using the console, restart the VyOS router. The GRUB menu appears.
+Select the relevant option from the GRUB menu and press Enter.
+The option must start with “Lost password change.”
+
+:::{figure} /_static/images/password-recovery-01.png
+:width: 600
+:::
+
+The stand-alone user-password recovery tool starts running and prompts
+you to reset the local system user password.
+
+```console
+Do you wish to reset the admin password? (y or n)
+y
+Which admin account do you want to reset?[vyos]
+my_username
+Enter my_username password:
+Retype my_username password:
+System will reboot in 10 seconds...
+```
diff --git a/docs/operation/md-raid.md b/docs/operation/md-raid.md
new file mode 100644
index 00000000..71a6ad5e
--- /dev/null
+++ b/docs/operation/md-raid.md
@@ -0,0 +1,249 @@
+(raid)=
+
+# RAID-1
+
+A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives
+to improve disk speed, store more data, and/or provide fault tolerance.
+There are several storage schemes possible in a RAID array, each offering a
+different combination of storage, reliability, and/or performance.
+The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more
+disks to mirror one another to provide system fault tolerance. In a RAID 1
+solution, every sector of one disk is duplicated onto every sector of all
+disks in the array. Provided even one disk in the RAID 1 set is operational,
+the system continues to run, even through disk replacement (provided that the
+hardware supports in-service replacement of drives).
+RAID 1 can be implemented using special hardware or it can be implemented in
+software. The VyOS system supports software RAID 1 on two disks.
+The VyOS implementation of RAID 1 allows the following:
+
+- Detection and reporting of disk failure
+- The ability to maintain system operation with one failed disk
+- The ability to boot the system with one failed disk
+- The ability to replace a failed disk and initiate re-mirroring
+- The ability to monitor the status of remirroring
+
+(raid-instalation)=
+
+## Installation Implications
+
+The VyOS systems installation utility provides several options for installing
+to a RAID 1 set. You can:
+
+- Use the install system to create the RAID 1 set
+- Use the underlying Linux commands to create a RAID 1 set before running the
+  install system command.
+- Use a previously-created RAID 1 set.
+
+:::{note}
+Before a permanent installation, VyOS runs a live installation
+:::
+
+## Configuration
+
+### Single disk, install as normal
+
+When the VyOS system is installed, it automatically detects the presence of two
+disks not currently part of a RAID array. In these cases, the VyOS
+installation utility automatically offers you the option of configuring RAID 1
+mirroring for the drives, with the following prompt.
+
+```none
+Would you like to configure RAID 1 mirroring on them?
+```
+
+- If you do not want to configure RAID 1 mirroring, enter “No” at the prompt
+  and continue with installation in the normal way.
+
+### Empty 2+ Disk
+
+If VyOS system detect two identical disks that are not currently part of a
+RAID-1 set, the VyOS installation utility automatically offers you the option
+of configuring RAID 1 mirroring for the drives, with the following prompt.
+
+```none
+Would you like to configure RAID 1 mirroring on them?
+```
+
+1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system
+detects a filesystem on the partitions being used for RAID 1 it will prompt you
+to indicate whether you want to continue creating the RAID 1 array.
+
+```none
+Continue creating array?
+```
+
+2 - To overwrite the old filesystem, enter “Yes”.
+
+3 - The system informs you that all data on both drives will be erased. You are
+prompted to confirm that you want to continue
+
+```none
+Are you sure you want to do this?
+```
+
+4 - Enter “Yes” at the prompt to retain the current VyOS configuration once
+installation is complete. Enter “No” to delete the current VyOS
+configuration.
+
+```none
+Would you like me to save the data on it before I delete it?
+```
+
+5 - Enter “Yes” at the prompt to retain the current VyOS configuration once
+installation is complete. Enter “No” to delete the current VyOS configuration.
+
+6 - Continue with installation in the normal way.
+
+### Present RAID-1
+
+When the VyOS software on a system with a RAID 1 set already configured,
+the installation utility will detect the array and will display the following
+prompt:
+
+```none
+Would you like to use this one?
+```
+
+1 - To break apart the current RAID 1 set, enter “No” at the prompt. The
+
+installation utility detects that there are two identical disks and offers you
+the option of configuring RAID 1 mirroring on them, displaying the following
+prompt:
+
+```none
+Would you like to configure RAID 1 mirroring on them?
+```
+
+2 - To decline to set up a new RAID 1 configuration on the disks, enter “No”
+at the prompt. The system prompts you to indicate which partition you would
+like the system installed on.
+
+```none
+Which partition should I install the root on? [sda1]:
+```
+
+3 - Enter the partition where you would like the system installed. The system
+then prompts you to indicate whether you want to save the old configuration
+data. This represents the current VyOS configuration.
+
+```none
+Would you like me to save the data on it before I delete it?
+```
+
+4 - Enter “Yes” at the prompt to retain the current VyOS configuration once
+installation is complete. Enter “No” to delete the current VyOS configuration.
+
+5 - Continue with installation in the normal way.
+
+### Detecting and Replacing a Failed RAID 1 Disk
+
+The VyOS system automatically detects a disk failure within a RAID 1 set and
+reports it to the system console. You can verify the failure by issuing the
+show raid command.
+
+To replace a bad disk within a RAID 1 set, perform the following steps:
+
+1 - Remove the failed disk from the RAID 1 set by issuing the following
+command:
+
+```{eval-rst}
+.. opcmd:: delete raid <RAID‐1‐device> member <disk‐partition>
+
+   where RAID-1-device is the name of the RAID 1 device (for example, md0) and
+   disk-partition is the name of the failed disk partition (for example, sdb2).
+```
+
+2- Physically remove the failed disk from the system. If the drives are not
+hot-swappable, then you must shut down the system before removing the disk.
+
+3 - Replace the failed drive with a drive of the same size or larger.
+
+4 - Format the new disk for RAID 1 by issuing the following command:
+
+```{eval-rst}
+.. opcmd:: format disk <disk‐device1> like <disk‐device2>
+
+   where disk-device1 is the replacement disk (for example, sdb) and
+   disk-device2 is the existing healthy disk (for example, sda).
+```
+
+5-Add the replacement disk to the RAID 1 set by issuing the following command:
+
+```{eval-rst}
+.. opcmd:: add raid <RAID‐1‐device> member <disk‐partition>
+
+   where RAID-1-device is the name of the RAID 1 device (for example, md0) and
+   disk-partition is the name of the replacement disk partition
+   (for example, sdb2).
+```
+
+## Operation
+
+This part introduces how to add a disk partition to a RAID-1 set initiates
+mirror synchronization, check and display information.
+
+```{eval-rst}
+.. opcmd:: add raid <RAID‐1‐device> member <disk‐partition>
+
+   Use this command to add a member disk partition to the RAID 1 set. Adding a
+   disk partition to a RAID 1 set initiates mirror synchronization, where all
+   data on the existing member partition is copied to the new partition.
+```
+
+```{eval-rst}
+.. opcmd:: format disk <disk‐device1> like <disk‐device2>
+
+   This command is typically used to prepare a disk to be added to a preexisting
+   RAID 1 set (of which disk-device2 is already a member).
+```
+
+```{eval-rst}
+.. opcmd:: show raid <RAID‐1‐device>
+
+   shows output for show raid md0 as sdb1 is being added to the RAID 1
+   set and is in the process of being resynchronized.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show raid md0
+      /dev/md0:
+            Version : 00.90
+      Creation Time : Wed Oct 29 09:19:09 2008
+         Raid Level : raid1
+         Array Size : 1044800 (1020.48 MiB 1069.88 MB)
+      Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB)
+       Raid Devices : 2
+      Total Devices : 2
+      Preferred Minor : 0
+        Persistence : Superblock is persistent
+        Update Time : Wed Oct 29 19:34:23 2008
+              State : active, degraded, recovering
+      Active Devices : 1
+      Working Devices : 2
+      Failed Devices : 0
+      Spare Devices : 1
+      Rebuild Status : 17% complete
+               UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f
+             Events : 0.103
+        Number   Major   Minor   RaidDevice State
+           0       8        1        0      active sync   /dev/sda1
+           2       8       17        1      spare rebuilding   /dev/sdb1
+```
+
+```{eval-rst}
+.. opcmd:: show raid <RAID‐1‐device>
+
+   Use this command to display the formatting of a hard disk.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show disk sda format
+      Disk /dev/sda: 1073 MB, 1073741824 bytes
+      85 heads, 9 sectors/track, 2741 cylinders
+      Units = cylinders of 765 * 512 = 391680 bytes
+      Disk identifier: 0x000b7179
+       Device Boot      Start         End      Blocks   Id  System
+      /dev/sda1               6        2737     1044922+  fd  Linux raid autodetect
+
+
+```