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

7 files changed, 527 insertions, 0 deletions

diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md
new file mode 100644
index 00000000..10da8d41
--- /dev/null
+++ b/docs/installation/virtual/md-docker.md
@@ -0,0 +1,67 @@
+(docker)=
+
+# Running in Docker Container
+
+Docker is an open-source project for deploying applications as standardized
+units called containers. Deploying VyOS in a container provides a simple and
+lightweight mechanism for both testing and packet routing for container
+workloads.
+
+## IPv6 Support for docker
+
+VyOS requires an IPv6-enabled docker network. Currently linux distributions
+do not enable docker IPv6 support by default. You can enable IPv6 support in
+two ways.
+
+### Method 1: Create a docker network with IPv6 support
+
+Here is a example using the macvlan driver.
+
+```none
+docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet
+```
+
+### Method 2: Add IPv6 support to the docker daemon
+
+Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and to specify
+the `fixed-cidr-v6` to your desired IPv6 subnet.
+
+```none
+{
+  "ipv6": true,
+  "fixed-cidr-v6": "2001:db8::/64"
+}
+```
+
+Reload the docker configuration.
+
+```none
+$ sudo systemctl reload docker
+```
+
+## Deploy container from ISO
+
+Download the ISO on which you want to base the container. In this example,
+the name of the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you
+created a custom IPv6-enabled network, the `docker run` command below
+will require that this network be included as the `--net` parameter to
+`docker run`.
+
+```none
+$ mkdir vyos && cd vyos
+$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso
+$ mkdir rootfs
+$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs
+$ sudo apt-get install -y squashfs-tools
+$ mkdir unsquashfs
+$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs
+$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249
+$ sudo umount rootfs
+$ cd ..
+$ sudo rm -rf vyos
+$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \
+> vyos:1.4-rolling-202111281249 /sbin/init
+$ docker exec -ti vyos su - vyos
+```
+
+You can execute `docker stop vyos` when you are finished with the container.
diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md
new file mode 100644
index 00000000..3e32e61f
--- /dev/null
+++ b/docs/installation/virtual/md-eve-ng.md
@@ -0,0 +1,5 @@
+# EVE-NG
+
+## References
+
+<https://www.eve-ng.net/>
diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md
new file mode 100644
index 00000000..d903c9a4
--- /dev/null
+++ b/docs/installation/virtual/md-gns3.md
@@ -0,0 +1,187 @@
+(vyos-on-gns3)=
+
+# Running on GNS3
+
+Sometimes you may want to test VyOS in a lab environment.
+[GNS3](http://www.gns3.com) is a network emulation software you
+might use for it.
+
+This guide will provide the necessary steps for installing
+and setting up VyOS on GNS3.
+
+## Requirements
+
+The following items are required:
+
+- A VyOS installation image (.iso file). You
+  can find how to get it on the {ref}`installation` page
+- A working GNS3 installation. For further information see the
+  [GNS3 documentation](https://docs.gns3.com/).
+
+(vm-setup)=
+
+## VM setup
+
+First, a virtual machine (VM) for the VyOS installation must be created
+in GNS3.
+
+Go to the GNS3 **File** menu, click **New template** and choose select
+**Manually create a new Template**.
+
+:::{figure} /_static/images/gns3-01.png
+:::
+
+Select **Quemu VMs** and then click on the `New` button.
+
+:::{figure} /_static/images/gns3-02.png
+:::
+
+Write a name for your VM, for instance "VyOS", and click `Next`.
+
+:::{figure} /_static/images/gns3-03.png
+:::
+
+Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM
+and click `Next`.
+
+:::{figure} /_static/images/gns3-04.png
+:::
+
+Select **telnet** as your console type and click `Next`.
+
+:::{figure} /_static/images/gns3-05.png
+:::
+
+Select **New image** for the base disk image of your VM and click
+`Create`.
+
+:::{figure} /_static/images/gns3-06.png
+:::
+
+Use the defaults in the **Binary and format** window and click
+`Next`.
+
+:::{figure} /_static/images/gns3-07.png
+:::
+
+Use the defaults in the **Qcow2 options** window and click `Next`.
+
+:::{figure} /_static/images/gns3-08.png
+:::
+
+Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu
+image creator**.
+
+:::{figure} /_static/images/gns3-09.png
+:::
+
+Click `Finish` to end the **New QEMU VM template** wizard.
+
+:::{figure} /_static/images/gns3-10.png
+:::
+
+Now the VM settings have to be edited.
+
+Being again at the **Preferences** window, having **Qemu VMs**
+selected and having our new VM selected, click the `Edit` button.
+
+:::{figure} /_static/images/gns3-11.png
+:::
+
+In the **General settings** tab of your **QEMU VM template
+configuration**, do the following:
+
+- Click on the `Browse...` button to choose the **Symbol** you want to
+  have representing your VM.
+- In **Category** select in which group you want to find your VM.
+- Set the **Boot priority** to **CD/DVD-ROM**.
+
+:::{figure} /_static/images/gns3-12.png
+:::
+
+At the **HDD** tab, change the Disk interface to **sata** to speed up
+the boot process.
+
+:::{figure} /_static/images/gns3-13.png
+:::
+
+At the **CD/DVD** tab click on `Browse...` and locate the VyOS image
+you want to install.
+
+:::{figure} /_static/images/gns3-14.png
+:::
+
+:::{note}
+You probably will want to accept to copy the .iso file to your
+default image directory when you are asked.
+:::
+
+In the **Network** tab, set **0** as the number of adapters, set the
+**Name format** to **eth\{0}** and the **Type** to **Paravirtualized
+Network I/O (virtio-net-pci)**.
+
+:::{figure} /_static/images/gns3-15.png
+:::
+
+In the **Advanced** tab, unmark the checkbox **Use as a linked base
+VM** and click `OK`, which will save and close the **QEMU VM template
+configuration** window.
+
+:::{figure} /_static/images/gns3-16.png
+:::
+
+At the general **Preferences** window, click `OK` to save and close.
+
+:::{figure} /_static/images/gns3-17.png
+:::
+
+(vyos-installation)=
+
+## VyOS installation
+
+- Create a new project.
+- Drag the newly created VyOS VM into it.
+- Start the VM.
+- Open a console.
+  The console should show the system booting. It will ask for the login
+  credentials, you are at the VyOS live system.
+- {ref}`Install VyOS <installation>`
+  as normal (that is, using the `install image` command).
+- After a successful installation, shutdown the VM with the `poweroff`
+  command.
+- **Delete the VM** from the GNS3 project.
+
+The *VyOS-hda.qcow2* file now contains a working VyOS image and can be
+used as a template. But it still needs some fixes before we can deploy
+VyOS in our labs.
+
+(vyos-vm-configuration)=
+
+## VyOS VM configuration
+
+To turn the template into a working VyOS machine, further steps are
+necessary as outlined below:
+
+**General settings** tab: Set the boot priority to **HDD**
+
+:::{figure} /_static/images/gns3-20.png
+:::
+
+**CD/DVD** tab: Unmount the installation image file by clearing the
+**Image** entry field.
+
+:::{figure} /_static/images/gns3-21.png
+:::
+
+Set the number of required network adapters, for example **4**.
+
+:::{figure} /_static/images/gns3-215.png
+:::
+
+**Advanced** settings tab: Mark the checkbox **Use as a linked
+base VM** and click `OK` to save the changes.
+
+:::{figure} /_static/images/gns3-22.png
+:::
+
+The VyOS VM is now ready to be deployed.
diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md
new file mode 100644
index 00000000..12ac179e
--- /dev/null
+++ b/docs/installation/virtual/md-index.md
@@ -0,0 +1,13 @@
+# Running VyOS in Virtual Environments
+
+```{eval-rst}
+.. toctree::
+   :caption: Content
+
+   libvirt
+   proxmox
+   vmware
+   gns3
+   eve-ng
+   docker
+```
diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md
new file mode 100644
index 00000000..5acefd43
--- /dev/null
+++ b/docs/installation/virtual/md-libvirt.md
@@ -0,0 +1,171 @@
+(libvirt)=
+
+# Running on Libvirt Qemu/KVM
+
+Libvirt is an open-source API, daemon and management tool for managing platform
+virtualization. There are several ways to deploy VyOS on libvirt kvm.
+Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes
+of memory, 2 cores CPU and default network virbr0.
+
+## CLI
+
+### Deploy from ISO
+
+Create VM name `vyos_r1`. You must specify the path to the `ISO` image,
+the disk `qcow2` will be created automatically. The `default` network is
+the virtual network (type Virtio) created by the hypervisor with NAT.
+
+```none
+$ virt-install -n vyos_r1 \
+  --ram 4096 \
+  --vcpus 2 \
+  --cdrom /var/lib/libvirt/images/vyos.iso \
+  --os-type linux \
+  --os-variant debian10 \
+  --network network=default \
+  --graphics vnc \
+  --hvm \
+  --virt-type kvm \
+  --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \
+  --noautoconsole
+```
+
+Connect to VM with command `virsh console vyos_r1`
+
+```none
+$ virsh console vyos_r1
+
+Connected to domain vyos_r1
+Escape character is ^]
+
+vyos login: vyos
+Password:
+
+vyos@vyos:~$ install image
+```
+
+After installation - exit from the console using the key combination
+`Ctrl + ]` and reboot the system.
+
+### Deploy from qcow2
+
+The convenience of using {abbr}`KVM (Kernel-based Virtual Machine)`
+images is that they don't need to be installed.
+Download predefined VyOS.qcow2 image for `KVM`
+
+```none
+curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2
+```
+
+Create VM with `import` qcow2 disk option.
+
+```none
+$ virt-install -n vyos_r2 \
+   --ram 4096 \
+   --vcpus 2 \
+   --os-type linux \
+   --os-variant debian10 \
+   --network network=default \
+   --graphics vnc \
+   --hvm \
+   --virt-type kvm \
+   --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \
+   --import \
+   --noautoconsole
+```
+
+Connect to VM with command `virsh console vyos_r2`
+
+```none
+$ virsh console vyos_r2
+
+Connected to domain vyos_r2
+Escape character is ^]
+
+vyos login: vyos
+Password:
+
+vyos@vyos:~$
+```
+
+The system is fully operational.
+
+## Virt-manager
+
+The virt-manager application is a desktop user interface for managing virtual
+machines through libvirt. On the linux open
+{abbr}`VMM (Virtual Machine Manager)`.
+
+(libvirt-virt-manager-iso)=
+
+### Deploy from ISO
+
+1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new
+   {abbr}`VM (Virtual Machine)`
+2. Choose `Local install media` (ISO)
+
+:::{figure} /_static/images/virt-libvirt-01.png
+:::
+
+3. Choose path to iso vyos.iso. Operating System can be any Debian based.
+
+:::{figure} /_static/images/virt-libvirt-02.png
+:::
+
+4. Choose Memory and CPU
+
+:::{figure} /_static/images/virt-libvirt-03.png
+:::
+
+5. Disk size
+
+:::{figure} /_static/images/virt-libvirt-04.png
+:::
+
+6. Name of VM and network selection
+
+:::{figure} /_static/images/virt-libvirt-05.png
+:::
+
+7. Then you will be taken to the console.
+
+:::{figure} /_static/images/virt-libvirt-06.png
+:::
+
+(libvirt-virt-manager-qcow2)=
+
+### Deploy from qcow2
+
+Download predefined VyOS.qcow2 image for `KVM`
+
+```none
+curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2
+```
+
+1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new
+   {abbr}`VM (Virtual Machine)`
+2. Choose `Import existing disk` image
+
+:::{figure} /_static/images/virt-libvirt-qc-01.png
+:::
+
+3. Choose the path to the image `vyos_kvm.qcow2` that was previously
+   downloaded . Operation System can be any Debian based.
+
+:::{figure} /_static/images/virt-libvirt-qc-02.png
+:::
+
+4. Choose Memory and CPU
+
+:::{figure} /_static/images/virt-libvirt-03.png
+:::
+
+5. Name of VM and network selection
+
+:::{figure} /_static/images/virt-libvirt-05.png
+:::
+
+6. Then you will be taken to the console.
+
+:::{figure} /_static/images/virt-libvirt-qc-03.png
+:::
diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md
new file mode 100644
index 00000000..cad22137
--- /dev/null
+++ b/docs/installation/virtual/md-proxmox.md
@@ -0,0 +1,45 @@
+(proxmox)=
+
+# Running on Proxmox
+
+Proxmox is an open-source platform for virtualization. Please visit
+<https://vyos.io> to see how to get a qcow2 image that can be imported
+into Proxmox.
+
+## Deploy VyOS from CLI with qcow2 image
+
+1. Copy the qcow2 image to a temporary directory on the Proxmox server.
+2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`.
+
+```none
+$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0
+$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm
+$ qm set 200 --virtio0 local-lvm:vm-200-disk-0
+$ qm set 200 --boot order=virtio0
+```
+
+3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`.
+
+```none
+$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso
+```
+
+4. Start the virtual machine in the proxmox GUI or CLI using `qm start 200`.
+
+## Deploy VyOS from CLI with rolling release ISO
+
+1. Download the rolling release iso from <https://vyos.net/get/nightly-builds/>. Non-subscribers can always get the LTS release by building it from source. Instructions can be found in the {ref}`build` section of this manual. VyOS source code repository is available <https://github.com/vyos/vyos-build>.
+2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB.
+
+```none
+qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15
+```
+
+3. Start the VM using the command `qm start 200` or using the start button located in the proxmox GUI.
+4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is `vyos/vyos`.
+5. Once booted into the live system, type `install image` into the command line and follow the prompts to install VyOS to the virtual drive.
+6. After installation has completed, remove the installation iso using the GUI or `qm set 200 --ide2 none`.
+7. Reboot the virtual machine using the GUI or `qm reboot 200`.
+
+Visit <https://www.proxmox.com/en/> for more information about the download
+and installation of this hypervisor.
diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md
new file mode 100644
index 00000000..0338067c
--- /dev/null
+++ b/docs/installation/virtual/md-vmware.md
@@ -0,0 +1,39 @@
+(vyosonvmware)=
+
+# Running on VMware ESXi
+
+## ESXi 5.5 or later
+
+.ova files are available for supporting users, and a VyOS can also be stood up
+using a generic Linux instance, and attaching the bootable ISO file and
+installing from the ISO using the normal process around `install image`.
+
+:::{NOTE}
+There have been previous documented issues with GRE/IPSEC tunneling
+using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been
+advised.
+:::
+
+### Memory Contention Considerations
+
+When the underlying ESXi host is approaching ~92% memory utilisation it will
+start the balloon process in a 'soft' state to start reclaiming memory from
+guest operating systems. This causes an artificial pressure using the vmmemctl
+driver on memory usage on the virtual guest. As VyOS by default does not have
+a swap file, this vmmemctl pressure is unable to force processes to move in
+memory data to the paging file, and blindly consumes memory forcing the
+virtual guest into a low memory state with no way to escape. The balloon
+can expand to 65% of guest allocated memory, so a VyOS guest running >35% of
+memory usage, can encounter an out of memory situation, and trigger the kernel
+oom_kill process. At this point a weighted lottery favouring memory hungry
+processes will be run with the unlucky winner being terminated by the kernel.
+
+It is advised that VyOS routers are configured in a resource group with
+adequate memory reservations so that ballooning is not inflicted on
+virtual VyOS guests.
+
+### References
+
+
+<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html>
+