Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)

* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism

Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta's (not current's).

Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
  Sphinx builds, restore after; writes _build/_swap_state.json and
  _build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
  trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
  loader; _prefer_webp builder hook so html prefers webp over png

Content:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
  alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
  (already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
  PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
  default, revert a page by removing its stem from _swap.txt

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

* feat(conf): copy .md sources into HTML output for plain-text serving

Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.

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

* docs: address review feedback (backport from PR #1857)

Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.

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

* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857

Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.

- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
  scripts/swap_sources.py --swap before the Sphinx build and --restore
  after. Without this, the swap mechanism ships but never runs on RTD
  builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
  when self.state._renderer is not present. Required for cfgcmd /
  opcmd / cmdincludemd directives to render correctly when included
  from MyST pages (the swap mechanism's whole point). Sagitta-only
  delta on _ext/vyos.py (the path = str(path) line on 224) is
  intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
  swap scripts. The scripts on this branch are byte-identical to
  current's, so the same tests apply. Travels with the branch so CI
  catches per-branch regressions if the scripts ever drift.

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

* fix(conf): skip md-*.md staging files in _copy_md_sources

Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc

Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

7 files changed, 544 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..964b9f64
--- /dev/null
+++ b/docs/installation/virtual/md-docker.md
@@ -0,0 +1,65 @@
+# 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..b1bb2a1d
--- /dev/null
+++ b/docs/installation/virtual/md-gns3.md
@@ -0,0 +1,208 @@
+# 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 `installation` page
+- A working GNS3 installation. For further information see the
+  [GNS3 documentation](https://docs.gns3.com/).
+
+## 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>
+<img src="/_static/images/gns3-01.webp" />
+</figure>
+
+Select **Quemu VMs** and then click on the `New` button.
+
+<figure>
+<img src="/_static/images/gns3-02.webp" />
+</figure>
+
+Write a name for your VM, for instance "VyOS", and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-03.webp" />
+</figure>
+
+Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM
+and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-04.webp" />
+</figure>
+
+Select **telnet** as your console type and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-05.webp" />
+</figure>
+
+Select **New image** for the base disk image of your VM and click
+`Create`.
+
+<figure>
+<img src="/_static/images/gns3-06.webp" />
+</figure>
+
+Use the defaults in the **Binary and format** window and click
+`Next`.
+
+<figure>
+<img src="/_static/images/gns3-07.webp" />
+</figure>
+
+Use the defaults in the **Qcow2 options** window and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-08.webp" />
+</figure>
+
+Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu
+image creator**.
+
+<figure>
+<img src="/_static/images/gns3-09.webp" />
+</figure>
+
+Click `Finish` to end the **New QEMU VM template** wizard.
+
+<figure>
+<img src="/_static/images/gns3-10.webp" />
+</figure>
+
+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>
+<img src="/_static/images/gns3-11.webp" />
+</figure>
+
+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>
+<img src="/_static/images/gns3-12.webp" />
+</figure>
+
+At the **HDD** tab, change the Disk interface to **sata** to speed up
+the boot process.
+
+<figure>
+<img src="/_static/images/gns3-13.webp" />
+</figure>
+
+At the **CD/DVD** tab click on `Browse...` and locate the VyOS image
+you want to install.
+
+<figure>
+<img src="/_static/images/gns3-14.webp" />
+</figure>
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+You probably will want to accept to copy the .iso file to your
+default image directory when you are asked.
+
+</div>
+
+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>
+<img src="/_static/images/gns3-15.webp" />
+</figure>
+
+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>
+<img src="/_static/images/gns3-16.webp" />
+</figure>
+
+At the general **Preferences** window, click `OK` to save and close.
+
+<figure>
+<img src="/_static/images/gns3-17.webp" />
+</figure>
+
+## 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.
+- `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
+
+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>
+<img src="/_static/images/gns3-20.webp" />
+</figure>
+
+**CD/DVD** tab: Unmount the installation image file by clearing the
+**Image** entry field.
+
+<figure>
+<img src="/_static/images/gns3-21.webp" />
+</figure>
+
+Set the number of required network adapters, for example **4**.
+
+<figure>
+<img src="/_static/images/gns3-215.webp" />
+</figure>
+
+**Advanced** settings tab: Mark the checkbox **Use as a linked
+base VM** and click `OK` to save the changes.
+
+<figure>
+<img src="/_static/images/gns3-22.webp" />
+</figure>
+
+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..7ed572e4
--- /dev/null
+++ b/docs/installation/virtual/md-index.md
@@ -0,0 +1,12 @@
+# Running VyOS in Virtual Environments
+
+<div class="toctree" caption="Content">
+
+libvirt
+proxmox
+vmware
+gns3
+eve-ng
+docker
+
+</div>
diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md
new file mode 100644
index 00000000..04a05ad0
--- /dev/null
+++ b/docs/installation/virtual/md-libvirt.md
@@ -0,0 +1,176 @@
+# 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 `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
+`VMM (Virtual Machine Manager)`.
+
+### Deploy from ISO
+
+1.  Open `VMM (Virtual Machine Manager)` and Create a new
+    `VM (Virtual Machine)`
+2.  Choose `Local install media` (ISO)
+
+<figure>
+<img src="/_static/images/virt-libvirt-01.webp" />
+</figure>
+
+3.  Choose path to iso vyos.iso. Operating System can be any Debian based.
+
+<figure>
+<img src="/_static/images/virt-libvirt-02.webp" />
+</figure>
+
+4.  Choose Memory and CPU
+
+<figure>
+<img src="/_static/images/virt-libvirt-03.webp" />
+</figure>
+
+5.  Disk size
+
+<figure>
+<img src="/_static/images/virt-libvirt-04.webp" />
+</figure>
+
+6.  Name of VM and network selection
+
+<figure>
+<img src="/_static/images/virt-libvirt-05.webp" />
+</figure>
+
+7.  Then you will be taken to the console.
+
+<figure>
+<img src="/_static/images/virt-libvirt-06.webp" />
+</figure>
+
+### 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 `VMM (Virtual Machine Manager)` and Create a new
+    `VM (Virtual Machine)`
+2.  Choose `Import existing disk` image
+
+<figure>
+<img src="/_static/images/virt-libvirt-qc-01.webp" />
+</figure>
+
+3.  Choose the path to the image `vyos_kvm.qcow2` that was previously
+    downloaded . Operation System can be any Debian based.
+
+<figure>
+<img src="/_static/images/virt-libvirt-qc-02.webp" />
+</figure>
+
+4.  Choose Memory and CPU
+
+<figure>
+<img src="/_static/images/virt-libvirt-03.webp" />
+</figure>
+
+5.  Name of VM and network selection
+
+<figure>
+<img src="/_static/images/virt-libvirt-05.webp" />
+</figure>
+
+6.  Then you will be taken to the console.
+
+<figure>
+<img src="/_static/images/virt-libvirt-qc-03.webp" />
+</figure>
diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md
new file mode 100644
index 00000000..da4bd03b
--- /dev/null
+++ b/docs/installation/virtual/md-proxmox.md
@@ -0,0 +1,43 @@
+# 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 <span class="title-ref">local-lvm</span>.
+
+``` 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 <span class="title-ref">local</span> storage pool with the name <span class="title-ref">seed.iso</span>.
+
+``` 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 `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..6d693455
--- /dev/null
+++ b/docs/installation/virtual/md-vmware.md
@@ -0,0 +1,35 @@
+# 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 <span class="title-ref">install image</span>.
+
+:::{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>