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)

10 files changed, 1689 insertions, 0 deletions

diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md
new file mode 100644
index 00000000..cf7d447d
--- /dev/null
+++ b/docs/installation/cloud/md-index.md
@@ -0,0 +1,10 @@
+# Cloud Environments
+
+```{toctree}
+:caption: Content
+
+aws
+azure
+gcp
+oracle
+```
diff --git a/docs/installation/md-bare-metal.md b/docs/installation/md-bare-metal.md
new file mode 100644
index 00000000..7017b6a2
--- /dev/null
+++ b/docs/installation/md-bare-metal.md
@@ -0,0 +1,623 @@
+(vyosonbaremetal)=
+
+# Bare Metal Deployment
+
+## Supermicro A2SDi (Atom C3000)
+
+I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it.
+Running VyOS on an UEFI only device is supported as of VyOS release 1.2.
+
+### Supermicro Shopping Cart
+
+- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU)
+- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F)
+- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN
+  with Intel C3000 SoC 1GbE)
+- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200)
+- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS)
+- 1x Supermicro MCP-320-81302-0B (optional FAN tray)
+
+### Optional (10GE)
+
+If you want to get additional ethernet ports or even 10GE connectivity
+the following optional parts will be required:
+
+- 1x Supermicro RSC-RR1U-E8 (Riser Card)
+- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket)
+
+Latest VyOS rolling releases boot without any problem on this board. You also
+receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no
+information about [OpenBMC](https://www.openbmc.org/) so far on this
+motherboard).
+
+### Pictures
+
+:::{figure} /_static/images/1u_vyos_back.jpg
+:alt: CSE-505-203B Back
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front.jpg
+:alt: CSE-505-203B Front
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_open_1.jpg
+:alt: CSE-505-203B Open 1
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_open_2.jpg
+:alt: CSE-505-203B Open 2
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_open_3.jpg
+:alt: CSE-505-203B Open 3
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_1.jpg
+:alt: CSE-505-203B w/ 10GE Open 1
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_2.jpg
+:alt: CSE-505-203B w/ 10GE Open 2
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_3.jpg
+:alt: CSE-505-203B w/ 10GE Open 3
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_4.jpg
+:alt: CSE-505-203B w/ 10GE Open
+:scale: 25 %
+:::
+
+(pc-engines-apu4)=
+
+## PC Engines APU4
+
+As this platform seems to be quite common in terms of noise, cost, power and
+performance it makes sense to write a small installation manual.
+
+This guide was developed using an APU4C4 board with the following specs:
+
+- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI
+  support, 32K data + 32K instruction cache per core, shared 2MB L2 cache.
+- 4 GB DDR3-1333 DRAM, with optional ECC support
+- About 6 to 10W of 12V DC power depending on CPU load
+- 2 miniPCI express (one with SIM socket for 3G modem).
+- 4 Gigabit Ethernet channels using Intel i211AT NICs
+
+The board can be powered via 12V from the front or via a 5V onboard connector.
+
+(vyos-on-baremetal-apu4-shopping)=
+
+### APU4 Shopping Cart
+
+- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM
+- 1x Kingston SUV500MS/120G
+- 1x VARIA Group Item 326745 19" dual rack for APU4
+
+The 19" enclosure can accommodate up to two APU4 boards - there is a single and
+dual front cover.
+
+#### Extension Modules
+
+##### WiFi
+
+Refer to {ref}`wireless-interface` for additional information, below listed
+modules have been tested successfully on this Hardware platform:
+
+- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1.
+- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1.
+  (see {ref}`wireless-interface-intel-ax200`)
+
+##### WWAN
+
+Refer to {ref}`wwan-interface` for additional information, below listed modules
+have been tested successfully on this Hardware platform using VyOS 1.3
+(equuleus):
+
+- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE)
+- Huawei ME909u-521 miniPCIe card (LTE)
+
+### VyOS 1.4 (sagitta)
+
+Depending on the VyOS versions you intend to install there is a difference in
+the serial port settings ({vytask}`T1327`).
+
+Create a bootable USB pendrive using e.g. [Rufus] on a Windows machine.
+
+Connect serial port to a PC through null modem cable (RXD / TXD crossed over).
+Set terminal emulator to 115200 8N1.
+
+```none
+PC Engines apu4
+coreboot build 20171130
+BIOS version v4.6.4
+4080 MB ECC DRAM
+SeaBIOS (version rel-1.11.0.1-0-g90da88d)
+
+Press F10 key now for boot menu:
+
+Select boot device:
+
+1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes)
+2. USB MSC Drive Generic Flash Disk 8.07
+3. Payload [memtest]
+4. Payload [setup]
+```
+
+Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing
+`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter`
+to continue.
+
+```none
+lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk
+x                      VyOS - Boot Menu                      x
+tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu
+x Live system (amd64-vyos)                                   x
+x Live system (amd64-vyos fail-safe mode)                    x
+x Live system (amd64-vyos) - Serial console                  x
+x                                                            x
+mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj
+```
+
+The image will be loaded and the last lines you will get will be:
+
+```none
+Loading /live/vmlinuz... ok
+Loading /live/initrd.img...
+...
+Welcome to VyOS - vyos ttyS0
+
+vyos login:
+```
+
+You can now proceed with a regular image installation as described in
+{ref}`installation`.
+
+(vyos-on-baremetal-apu4-pictures)=
+
+### Pictures
+
+:::{note}
+Both device types operate without any moving parts and emit zero
+noise.
+:::
+
+#### Rack Mount
+
+:::{figure} /_static/images/apu4_rack_1.jpg
+:alt: APU4 rack closed
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_2.jpg
+:alt: APU4 rack front
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_3.jpg
+:alt: 'APU4 rack module #1'
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_4.jpg
+:alt: 'APU4 rack module #2'
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_5.jpg
+:alt: 'APU4 rack module #3 with PSU'
+:scale: 25 %
+:::
+
+##### VyOS custom print
+
+:::{figure} /_static/images/apu4_rack_vyos_print.jpg
+:alt: APU4 custom VyOS powder coat
+:scale: 25 %
+:::
+
+#### Desktop / Bench Top
+
+:::{figure} /_static/images/apu4_desk_1.jpg
+:alt: APU4 desktop closed
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_desk_2.jpg
+:alt: APU4 desktop closed
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_desk_3.jpg
+:alt: APU4 desktop back
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_desk_4.jpg
+:alt: APU4 desktop back
+:scale: 25 %
+:::
+
+## Qotom Q355G4
+
+The install on this Q355G4 box is pretty much plug and play. The port numbering
+the OS does might differ from the labels on the outside, but the UEFI firmware
+has a port blink test built in with MAC addresses so you can very quickly
+identify which is which. MAC labels are on the inside as well, and this test
+can be done from VyOS or plain Linux too. Default settings in the UEFI will
+make it boot, but depending on your installation wishes (i.e. storage type,
+boot type, console type) you might want to adjust them. This Qotom company
+seems to be the real OEM/ODM for many other relabelling companies like
+Protectli.
+
+### Hardware
+
+There are a number of other options, but they all seem to be close to Intel
+reference designs, with added features like more serial ports, more network
+interfaces and the likes. Because they don't deviate too much from standard
+designs all the hardware is well-supported by mainline. It accepts one LPDDR3
+SO-DIMM, but chances are that if you need more than that, you'll also want
+something even beefier than an i5. There are options for antenna holes, and SIM
+slots, so you could in theory add an LTE/Cell modem (not tested so far).
+
+The chassis is a U-shaped alu extrusion with removable I/O plates and removable
+bottom plate. Cooling is completely passive with a heatsink on the SoC with
+internal and external fins, a flat interface surface, thermal pad on top of
+that, which then directly attaches to the chassis, which has fins as well. It
+comes with mounting hardware and rubber feet, so you could place it like a
+desktop model or mount it on a VESA mount, or even wall mount it with the
+provided mounting plate. The closing plate doubles as internal 2.5" mounting
+place for an HDD or SSD, and comes supplied with a small SATA cable and SATA
+power cable.
+
+Power supply is a 12VDC barrel jack, and included switching power supply, which
+is why SATA power regulation is on-board. Internally it has a NUC-board-style
+on-board 12V input header as well, the molex locking style.
+
+There are WDT options and auto-boot on power enable, which is great for remote
+setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled
+in enforcement mode, which is good but also means no coreboot option), yet has
+most options available to configure (so it's not locked out like most firmwares
+are).
+
+An external RS232 serial port is available, internally a GPIO header as well.
+It does have Realtek based audio on board for some reason, but you can disable
+that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS
+mode and HDMI BIOS mode depends on what is connected at startup; it goes into
+serial mode if you disconnect HDMI and plug in serial, in all other cases it's
+HDMI mode.
+
+## Partaker i5
+
+:::{figure} ../_static/images/600px-Partaker-i5.jpg
+:::
+
+I believe this is actually the same hardware as the Protectli. I purchased it
+in June 2018. It came pre-loaded with pfSense.
+
+[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html).
+
+### Installation
+
+- Write VyOS ISO to USB drive of some sort
+- Plug in VGA, power, USB keyboard, and USB drive
+- Press "SW" button on the front (this is the power button; I don't know what
+  "SW" is supposed to mean).
+- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick,
+  but with a few tries you should be able to get into the BIOS.
+- Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0
+  (EHCI) to Enabled. Without doing this, the USB drive won't boot.
+- Boot to the VyOS installer and install as usual.
+
+Warning the interface labels on my device are backwards; the left-most "LAN4"
+port is eth0 and the right-most "LAN1" port is eth3.
+
+## Acrosser AND-J190N1
+
+:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg
+:::
+
+:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg
+:::
+
+This microbox network appliance was build to create OpenVPN bridges. It can
+saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN
+
+You may have to add your own RAM and HDD/SSD. There is no VGA connector. But
+Acrosser provides a DB25 adapter for the VGA header on the motherboard (not
+used).
+
+### BIOS Settings:
+
+First thing you want to do is getting a more user friendly console to configure
+BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead.
+
+For practical issues change speed from 115200 to 9600. 9600 is the default
+speed at which both linux kernel and VyOS will reconfigure the serial port
+when loading.
+
+Connect to serial (115200bps). Power on the appliance and press Del in the
+console when requested to enter BIOS settings.
+
+Advanced > Serial Port Console Redirection > Console Redirection Settings:
+
+- Terminal Type : VT100+
+- Bits per second : 9600
+
+Save, reboot and change serial speed to 9600 on your client.
+
+Some options have to be changed for VyOS to boot correctly. With XHCI enabled
+the installer can’t access the USB key. Enable EHCI instead.
+
+Reboot into BIOS, Chipset > South Bridge > USB Configuration:
+
+- Disable XHCI
+- Enable USB 2.0 (EHCI) Support
+
+Perform Image installation using `install image` CLI command.
+
+(gowin-gw-fn-1ur1-10g)=
+
+## Gowin GW-FN-1UR1-10G
+
+A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W.
+Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation).
+
+The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210
+where one supports IEEE802.3at PoE+ (Typical 30W).
+
+In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available.
+
+**NOTE:** This is the entry level platform. Other derivates exists with
+i3-N305 CPU and 2x 25GbE!
+
+### Gowin Shopping Cart
+
+- 1x Gowin GW-FN-1UR1-10G
+- 2x 128GB M.2 NVMe SSDs
+
+### Optional (WiFi + WWAN)
+
+- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to
+  a Kernel crash)
+- 1x HP LT4120 Snapdragon X5 LTE WWAN module
+
+### Pictures
+
+:::{figure} ../_static/images/gowin-01.png
+:::
+
+:::{figure} ../_static/images/gowin-02.png
+:::
+
+:::{figure} ../_static/images/gowin-03.png
+:::
+
+:::{figure} ../_static/images/gowin-04.png
+:::
+
+### Cooling
+
+The device itself is passivly cooled, whereas the power supply has an active fan.
+Even if the main processor is powered off, the power supply fan is operating and
+the entire chassis draws 7.5W. During operation the chassis drew arround 38W.
+
+### BIOS Settings
+
+No settings needed to be altered, everything worked out of the box!
+
+### Installation
+
+The system provides a regular RS232 console port using 115200,8n1 setting which
+is sufficient to install VyOS from a USB pendrive.
+
+### First Boot
+
+Please note that there is a weirdness on the network interface mapping.
+The interface \<-> MAC mapping is going upwards but the NICs are placed
+somehow swapped on the mainboard/MACs programmed in a swapped order.
+
+See interface description for more detailed mapping.
+
+```none
+vyos@vyos:~$ show interfaces
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface    IP Address      MAC                VRF        MTU  S/L    Description
+-----------  --------------  -----------------  -------  -----  -----  -------------
+eth0         -               00:f0:cb:00:00:99  default   1500  u/D    Intel I226-V - Front eth2
+eth1         -               00:f0:cb:00:00:9a  default   1500  u/D    Intel I226-V - Front eth1
+eth2         -               00:f0:cb:00:00:9b  default   1500  u/D    Intel I210 - Front eth4
+eth3         -               00:f0:cb:00:00:9c  default   1500  u/D    Intel I210 - Front eth3
+eth4         -               00:f0:cb:00:00:9d  default   1500  u/D    Intel I210 - Front POE
+eth5         -               00:02:c9:00:00:30  default   1500  u/D    Mellanox ConnectX-3 - SFP2
+eth6         -               00:02:c9:00:00:31  default   1500  u/D    Mellanox ConnectX-3 - SFP1
+lo           127.0.0.1/8     00:00:00:00:00:00  default  65536  u/u
+             ::1/128
+wwan0        -               d2:39:76:8e:05:12  default   1500  A/D
+```
+
+#### VyOS 1.4 (sagitta)
+
+Connect serial port to a PC through a USB \<-> RJ45 console cable. Set terminal
+emulator to 115200 8N1. You can also perform the installation using VGA or HDMI
+ports.
+
+In this example I choose to install VyOS as RAID-1 on both NVMe drives. However,
+a previous installation on the 128GB eMMC storage worked without any issues,
+too.
+
+```none
+Welcome to VyOS - vyos ttyS0
+vyos login:
+```
+
+Perform Image installation using `install image` CLI command. This installation
+uses two 128GB NVMe disks setup as RAID1.
+
+```none
+Welcome to VyOS!
+
+   ┌── ┐
+   . VyOS 1.4.0
+   └ ──┘  sagitta
+
+* Support portal: https://support.vyos.io
+* Documentation:  https://docs.vyos.io/en/sagitta
+* Project news:   https://blog.vyos.io
+* Bug reports:    https://vyos.dev
+
+You can change this banner using "set system login banner post-login" command.
+
+VyOS is a free software distribution that includes multiple components,
+you can check individual component licenses under /usr/share/doc/*/copyright
+Use of this pre-built image is governed by the EULA you can find in
+/usr/share/vyos/EULA
+
+vyos@vyos:~$ install image
+
+Welcome to VyOS installation!
+This command will install VyOS to your permanent storage.
+Would you like to continue? [y/N] y
+
+What would you like to name this image? (Default: 1.4.0)
+
+Please enter a password for the "vyos" user:
+Please confirm password for the "vyos" user:
+
+What console should be used by default? (K: KVM, S: Serial)? (Default: S)
+
+Probing disks
+4 disk(s) found
+Would you like to configure RAID-1 mirroring? [Y/n] y
+
+The following disks were found:
+      /dev/sda (14.4 GB)
+      /dev/mmcblk0 (116.5 GB)
+Would you like to configure RAID-1 mirroring on them? [Y/n] n
+
+Would you like to choose two disks for RAID-1 mirroring? [Y/n] y
+Disks available:
+      1: /dev/sda     (14.4 GB)
+      2: /dev/mmcblk0 (116.5 GB)
+      3: /dev/nvme1n1 (119.2 GB)
+      4: /dev/nvme0n1 (119.2 GB)
+Select first disk: 3
+
+Remaining disks:
+      1: /dev/sda     (14.4 GB)
+      2: /dev/mmcblk0 (116.5 GB)
+      3: /dev/nvme0n1 (119.2 GB)
+Select second disk: 3
+
+Installation will delete all data on both drives. Continue? [y/N] y
+
+Searching for data from previous installations
+No previous installation found
+Creating partitions on /dev/nvme1n1
+Creating partition table...
+Creating partitions on /dev/nvme0n1
+Creating partition table...
+Creating RAID array
+Updating initramfs
+Creating filesystem on RAID array
+The following config files are available for boot:
+      1: /opt/vyatta/etc/config/config.boot
+      2: /opt/vyatta/etc/config.boot.default
+
+Which file would you like as boot config? (Default: 1)
+Creating temporary directories
+Mounting new partitions
+Creating a configuration file
+Copying system image files
+Installing GRUB configuration files
+Installing GRUB to the drives
+Cleaning up
+Unmounting target filesystems
+Removing temporary files
+The image installed successfully; please reboot now.
+```
+
+### Hardware
+
+```none
+vyos@vyos:~$ lspci
+00:00.0 Host bridge: Intel Corporation Device 461c
+00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics]
+00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01)
+00:0d.0 USB controller: Intel Corporation Device 464e
+00:14.0 USB controller: Intel Corporation Device 54ed
+00:14.2 RAM memory: Intel Corporation Device 54ef
+00:15.0 Serial bus controller: Intel Corporation Device 54e8
+00:16.0 Communication controller: Intel Corporation Device 54e0
+00:1a.0 SD Host controller: Intel Corporation Device 54c4
+00:1c.0 PCI bridge: Intel Corporation Device 54b8
+00:1c.2 PCI bridge: Intel Corporation Device 54ba
+00:1c.3 PCI bridge: Intel Corporation Device 54bb
+00:1c.6 PCI bridge: Intel Corporation Device 54be
+00:1d.0 PCI bridge: Intel Corporation Device 54b0
+00:1f.0 ISA bridge: Intel Corporation Device 5481
+00:1f.4 SMBus: Intel Corporation Device 54a3
+00:1f.5 Serial bus controller: Intel Corporation Device 54a4
+01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04)
+04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04)
+05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter
+06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01)
+07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01)
+09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03)
+0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03)
+0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03)
+0d:00.0 Non-Volatile memory controller: Device 1ed0:2283
+0f:00.0 Non-Volatile memory controller: Device 1ed0:2283
+11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3]
+```
+
+```none
+vyos@vyos:~$ lsusb
+Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
+Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device
+Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard
+Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE
+Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub
+Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
+Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub
+Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
+Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
+```
+
+#### WWAN
+
+The LTE module can be enabled as simple as this config snippet:
+
+```none
+interfaces {
+   wwan wwan0 {
+      address "dhcp"
+      apn "YOUR-APN-GOES-HERE"
+   }
+}
+```
+
+For more information please refer to chapter: {ref}`wwan-interface`
+
+[rufus]: https://rufus.ie/
diff --git a/docs/installation/md-index.md b/docs/installation/md-index.md
new file mode 100644
index 00000000..4256aa9b
--- /dev/null
+++ b/docs/installation/md-index.md
@@ -0,0 +1,30 @@
+---
+lastproofread: '2026-01-26'
+---
+
+# Installation and Image Management
+
+:::{note}
+This information applies primarily to virtual installations:
+
+When installing VyOS, ensure that the MAC address you select for your NICs
+is not a locally administered MAC address. Locally administered addresses are
+distinguished from universally administered addresses by setting the
+second-least-significant bit of the first octet to 1:
+
+Example: `02:00:00:00:00:01`, where the second-least-significant bit
+(`02` in hexadecimal) is set to `1`.
+:::
+
+```{toctree}
+:caption: Content
+:maxdepth: 2
+
+install
+virtual/index
+cloud/index
+bare-metal
+update
+image
+secure-boot
+```
diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md
new file mode 100644
index 00000000..789b0ec9
--- /dev/null
+++ b/docs/installation/md-install.md
@@ -0,0 +1,460 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(installation)=
+
+# Installation
+
+VyOS installation requires a VyOS .iso file. This file is a live installation
+image that you can use to boot a live VyOS system. From there, you can proceed
+with a permanent installation on a hard drive or other storage device.
+
+:::{list-table} Comparison of VyOS image releases
+:header-rows: 1
+:widths: 15 35 15 25 15 15
+
+* - Release Type
+  - Description
+  - Release Cycle
+  - Intended Use
+  - Access to Images
+  - Access to Source
+
+* - Nightly (Current)
+  - Automatically built from the current branch. Always up to date
+    with cutting edge development but guaranteed to contain bugs.
+  - Every night
+  - Developing VyOS, testing new features, experimenting.
+  - Everyone
+  - Everyone
+
+* - Stream
+  - VyOS Stream serves as a technology preview and a quality gate
+    for the upcoming LTS release. Allows everyone to try new features
+    and check if they work well or need improvements.
+  - Every quarter
+  - Non-critical production environments, preparing for the LTS
+    release.
+  - Everyone
+  - Everyone
+
+* - Release Candidate
+  - Rather stable. All development focuses on testing and hunting
+    down remaining bugs following the feature freeze.
+  - Irregularly until EPA comes out
+  - Labs, small offices and non-critical production systems backed
+    by a high-availability setup.
+  - Everyone
+  - Everyone
+
+* - Early Production Access
+  - Highly stable with no known bugs. Needs to be tested repeatedly
+    under different conditions before it can become the final
+    release.
+  - Irregularly until LTS comes out
+  - Non-critical production environments, preparing for the LTS
+    release.
+  - Everyone
+  - Everyone
+
+* - Long-Term Support
+  - Guaranteed to be stable and carefully maintained for several
+    years after the release. No features are introduced but security
+    updates are released in a timely manner.
+  - Every major version
+  - Large-scale enterprise networks, internet service providers,
+    critical production environments that call for minimum downtime.
+  - Subscribers, contributors, non-profits, emergency services,
+    academic institutions
+  - Subscribers, contributors, non-profits, emergency services,
+    academic institutions
+:::
+
+## Hardware requirements
+
+The minimum system requirements for VyOS are 4 GB RAM and 10 GB storage.
+Depending on your use case, you might need additional RAM and CPU resources.
+
+## Download
+
+### Registered Subscribers
+
+Registered subscribers can log into <https://support.vyos.io/> to access
+a variety of different downloads via the "Downloads" link. These
+downloads include LTS (Long-Term Support), the associated hot-fix releases,
+early public access releases, pre-built VM images, as well as device
+specific installation ISOs. See this [article] for more information on
+downloads.
+
+:::{note}
+The `.qcow2` image provided for Proxmox deployment can also be
+used to deploy VyOS on KVM environments. This image includes cloud-init
+support. See {ref}`cloud-init` for more information.
+:::
+
+:::{figure} /_static/images/vyosnew-downloads.png
+:::
+
+### Building from source
+
+Subscribers can download the source code for the LTS release from the
+"Downloads" link. Non-subscribers can access the source code for the
+Rolling release. For instructions, see the {ref}`build` section. The
+VyOS source code repository is available at
+<https://github.com/vyos/vyos-build>.
+
+### Rolling Release
+
+Everyone can download bleeding-edge VyOS rolling images from:
+<https://downloads.vyos.io/>
+
+:::{note}
+Rolling releases contain the latest enhancements and fixes.
+This means there may be new bugs. If you encounter a bug, follow the
+guide at {ref}`bug_report`. We depend on your feedback to improve VyOS.
+:::
+
+The following link contains the most recent VyOS builds for AMD64
+systems from the `current` branch: <https://vyos.net/get/nightly-builds/>
+
+### Download Verification
+
+LTS images are signed with the VyOS lead package maintainer's private key.
+You can verify the authenticity of the package using the official public key
+and Minisign.
+
+(minisign-verification)=
+
+#### Minisign verification
+
+VyOS uses [Minisign](https://github.com/jedisct1/minisign) for release
+signing. Minisign is a tool for signing files and verifying signatures.
+
+OpenBSD introduced signify in 2015. Minisign is an alternative
+implementation of the same protocol, available for Windows, macOS, and
+most GNU/Linux distributions. Minisign is portable, lightweight, and
+uses the Ed25519 public-key signature system.
+
+{vytask}`T2108` switched the validation system to prefer Minisign over GPG keys.
+
+To verify a VyOS image starting with VyOS `1.3.0-rc6`, run:
+
+```none
+$ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig
+
+Signature and comment signature verified
+Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso    hashed
+```
+
+During an image upgrade, VyOS runs the following command:
+
+```none
+$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig
+Signature and comment signature verified
+Trusted comment: timestamp:1629997936   file:vyos-1.3.0-rc6-amd64.iso
+```
+
+:::{note}
+Starting with version `1.4.3`, VyOS uses Minisign exclusively.
+If you see an unexpected verification error, update your system to version
+`1.4.2` first. Support for GnuPG signatures has been
+removed ({vytask}`T7301`).
+:::
+
+(live_installation)=
+
+## Live installation
+
+:::{note}
+To permanently install VyOS, you must first complete a live
+installation.
+:::
+
+You can test VyOS without installing it on your hard drive. **Using your
+downloaded VyOS .iso file, you can create a bootable USB drive to boot
+into a fully functional VyOS system**. After testing it, you can start a
+{ref}`permanent_installation` on your hard drive or power off your system
+and remove the USB drive.
+
+If you have a GNU/Linux system, you can create a bootable VyOS USB drive using
+the `dd` command:
+
+1. Open your terminal emulator.
+
+2. Find the device name of your USB drive (use the `lsblk` command).
+
+3. Unmount the USB drive. Replace `X` with your device letter and keep the
+   asterisk (*) to unmount all partitions.
+
+```none
+$ umount /dev/sdX*
+```
+
+4. Write the image (your VyOS .iso file) to the USB drive. Use the device
+   name (for example, `/dev/sdb`), not the partition name
+   (for example, `/dev/sdb1`).
+
+**Warning**: This will destroy all data on the USB drive!
+
+```none
+# dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync
+```
+
+5. Wait for the operation to complete (bytes copied). On some systems, this
+   may take more than one minute.
+
+6. Once `dd` has finished, pull the USB drive out and plug it into
+   the powered-off computer where you want to install (or test) VyOS.
+
+7. Power on the computer and ensure it boots from the USB drive
+   (you may need to select the boot device or change boot settings).
+
+8. When VyOS finishes loading, sign in using the default credentials
+   (login: `vyos`, password: `vyos`).
+
+If you encounter issues with this method, prefer a different operating
+system, or want a GUI program, you can use other tools to create a
+bootable USB drive, such as [balenaEtcher] (GNU/Linux, macOS, and Windows),
+[Rufus] (Windows), and [many others]. Follow their instructions to create
+a bootable USB drive from an `.iso` file.
+
+:::{hint}
+The default username and password for the live system is *vyos*.
+:::
+
+(permanent_installation)=
+
+## Permanent installation
+
+:::{note}
+Before a permanent installation, VyOS requires a
+{ref}`live_installation`.
+:::
+
+Unlike general-purpose Linux distributions, VyOS uses "image installation",
+which mimics the user experience of traditional hardware routers and allows
+you to keep multiple VyOS versions installed simultaneously. This lets you
+switch to a previous version if something breaks or misbehaves after an
+image upgrade.
+
+Each version is contained in its own squashfs image mounted in a union
+filesystem along with a directory for mutable data such as configurations,
+keys, and custom scripts.
+
+In order to proceed with a permanent installation:
+
+1. Sign in to the VyOS live system using the default credentials
+   (login: `vyos`, password: `vyos`).
+
+2. Run the `install image` command and follow the wizard:
+
+```none
+vyos@vyos:~$ install image
+Welcome to VyOS installation!
+This command will install VyOS to your permanent storage.
+Would you like to continue? [y/N] y
+What would you like to name this image? (Default: 2025.09.17-0018-rolling)
+Please enter a password for the "vyos" user:
+Please confirm password for the "vyos" user:
+What console should be used by default? (K: KVM, S: Serial)? (Default: S)
+Probing disks
+1 disk(s) found
+The following disks were found:
+Drive: /dev/vda (10.0 GB)
+Which one should be used for installation? (Default: /dev/vda)
+Installation will delete all data on the drive. Continue? [y/N] y
+Searching for data from previous installations
+No previous installation found
+Would you like to use all the free space on the drive? [Y/n] Y
+Creating partition table...
+The following config files are available for boot:
+        1: /opt/vyatta/etc/config/config.boot
+        2: /opt/vyatta/etc/config.boot.default
+Which file would you like as boot config? (Default: 1)
+Creating temporary directories
+Mounting new partitions
+Creating a configuration file
+Copying system image files
+Installing GRUB configuration files
+Installing GRUB to the drive
+Cleaning up
+Unmounting target filesystems
+Removing temporary files
+The image installed successfully; please reboot now.
+```
+
+3. After installation completes, remove the live USB drive or CD.
+
+4. Reboot the system.
+
+```none
+vyos@vyos:~$ reboot
+Proceed with reboot? (Yes/No) [No] Yes
+```
+
+You will boot now into a permanent VyOS system.
+
+## PXE Boot
+
+You can also install VyOS using PXE, a more complex installation method that
+allows you to deploy VyOS over the network.
+
+**Requirements**
+
+- A machine (client) with a PXE-enabled NIC.
+- {ref}`dhcp-server`
+- {ref}`tftp-server`
+- Webserver (HTTP). Optional, but speeds up installation.
+- VyOS ISO image (do not use images prior to VyOS `1.2.3`).
+- Files *pxelinux.0* and *ldlinux.c32* from the
+  [Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/).
+
+### Configuration
+
+#### Step 1: DHCP
+
+Configure a DHCP server to provide the client with:
+
+- An IP address
+- The TFTP server address (DHCP option 66), sometimes referred to as the
+  *boot server*
+- The *bootfile name* (DHCP option 67): *pxelinux.0*
+
+In this example we configured an existent VyOS as the DHCP server:
+
+```none
+vyos@vyos# show service dhcp-server
+ shared-network-name mydhcp {
+     subnet 192.168.1.0/24 {
+         option {
+             bootfile-name pxelinux.0
+             bootfile-server 192.168.1.50
+             default-router 192.168.1.50
+         }
+         range 0 {
+             start 192.168.1.70
+             stop 192.168.1.100
+         }
+         subnet-id 1
+     }
+ }
+```
+
+(install_from_tftp)=
+
+#### Step 2: TFTP
+
+Configure a TFTP server to serve the following:
+
+- The *pxelinux.0* file from the Syslinux distribution
+- The *ldlinux.c32* file from the Syslinux distribution
+- The VyOS kernel you want to deploy (*vmlinuz* file from the
+  */live* directory in the extracted ISO file)
+- The VyOS initial ramdisk (*initrd.img* file from the */live* directory
+  in the extracted ISO file). Do not use an empty (0 bytes) initrd.img
+  file; the correct file may have a longer name.
+- A directory named *pxelinux.cfg* containing the configuration file.
+  By default, the VyOS configuration file is named [default].
+
+In the example you configured your existent VyOS as the TFTP server too:
+
+```none
+vyos@vyos# show service tftp-server
+ directory /config/tftpboot
+ listen-address 192.168.1.50
+```
+
+Example of the contents of the TFTP server:
+
+```none
+vyos@vyos# ls -hal /config/tftpboot/
+total 29M
+drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 .
+drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 ..
+-r--r--r-- 1 root vyattacfg  25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos
+-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32
+-rw-r--r-- 1 root vyattacfg  46K Oct 13 23:24 pxelinux.0
+drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg
+-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz
+
+vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg
+total 12K
+drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 .
+drwxr-sr-x 3 tftp tftp      4.0K Oct 14 00:23 ..
+-rw-r--r-- 1 root root       191 Oct 14 01:10 default
+```
+
+Example of simple (no menu) configuration file:
+
+```none
+vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default
+DEFAULT VyOS123
+
+LABEL VyOS123
+ KERNEL vmlinuz
+ APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs
+```
+
+#### Step 3: HTTP
+
+You also need to provide the *filesystem.squashfs* file. Because this is a
+large file and TFTP is slow, you can send it through HTTP to speed up the
+transfer. In our example, we do this—see the configuration file above.
+
+1. Start a web server. You can use one like
+   [Python's SimpleHTTPServer] to serve the `filesystem.squashfs` file.
+   The file is in the `/live` directory of the extracted ISO file.
+2. Edit the {ref}`install_from_tftp` configuration file to show the correct
+   URL: `fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs`.
+
+:::{note}
+Do not rename the *filesystem.squashfs* file. If you're working with
+different versions, create different directories instead.
+:::
+
+3. restart the TFTP service. If you're using VyOS as your TFTP server, restart
+   the service with `sudo service tftpd-hpa restart`.
+
+:::{note}
+Ensure the directories and files on both the TFTP and HTTP servers
+have the correct permissions for the booting clients to access them.
+:::
+
+### Client Boot
+
+Finally, power on your PXE-enabled clients. They will automatically receive an
+IP address from the DHCP server and boot into VyOS live using files from the
+TFTP and HTTP servers.
+
+Once finished you will be able to proceed with the `install image`
+command as in a regular VyOS installation.
+
+## Known Issues
+
+This is a list of known issues that can arise during installation.
+
+### Black screen on install
+
+GRUB redirects all output to a serial port to facilitate installation
+on headless hosts. On some hardware that lacks a serial port, this causes
+a hard lockup and displays a black screen after you select the
+`Live system` option from the installation image.
+
+The workaround is to press `e` when the boot menu appears and edit the
+GRUB boot options. Specifically, remove the:
+
+`console=ttyS0,115200`
+
+option, and type CTRL-X to boot.
+
+Installation can then continue as outlined above.
+
+[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913
+[balenaetcher]: https://www.balena.io/etcher/
+[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config
+[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration
+[many others]: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems
+[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html
+[rufus]: https://rufus.ie/
+[syslinux]: http://www.syslinux.org/
diff --git a/docs/installation/md-secure-boot.md b/docs/installation/md-secure-boot.md
new file mode 100644
index 00000000..3c2013a4
--- /dev/null
+++ b/docs/installation/md-secure-boot.md
@@ -0,0 +1,191 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(secure-boot)=
+
+# Secure Boot
+
+Initial UEFI Secure Boot support is available ({vytask}`T861`). VyOS uses
+`shim` from Debian 12 (Bookworm), which is properly signed by the UEFI
+Secure Boot key from Microsoft.
+
+:::{note}
+There is yet no signed version of `shim` for VyOS, thus we
+provide no signed image for secure boot yet. If you are interested in
+secure boot you can build an image on your own.
+:::
+
+To generate a custom ISO with your own secure boot keys, run the following
+commands prior to your ISO image build:
+
+```bash
+cd vyos-build
+CA_DIR="data/certificates"
+SHIM_CERT_NAME="vyos-dev-2025-shim"
+VYOS_KERNEL_CERT_NAME="vyos-dev-2025-linux"
+
+openssl req -new -x509 -newkey rsa:4096 -keyout ${CA_DIR}/${SHIM_CERT_NAME}.key -out ${CA_DIR}/${SHIM_CERT_NAME}.der \
+  -outform DER -days 36500 -subj "/CN=VyOS Networks Secure Boot CA/" -nodes
+openssl x509 -inform der -in ${CA_DIR}/${SHIM_CERT_NAME}.der -out ${CA_DIR}/${SHIM_CERT_NAME}.pem
+
+openssl req -newkey rsa:4096 -sha256 -nodes -keyout ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.key \
+  -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -outform PEM -days 3650 \
+  -subj "/CN=VyOS Networks Secure Boot Signer 2025 - linux/"
+openssl x509 -req -in ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -CA ${CA_DIR}/${SHIM_CERT_NAME}.pem \
+  -CAkey ${CA_DIR}/${SHIM_CERT_NAME}.key -CAcreateserial -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.pem -days 3650 -sha256
+```
+
+## Installation
+
+As our version of `shim` is not signed by Microsoft we need to enroll the
+previously generated {abbr}`MOK (Machine Owner Key)` to the system.
+
+First, disable UEFI Secure Boot for the installation.
+
+:::{figure} /_static/images/uefi_secureboot_01.png
+:alt: Disable UEFI secure boot
+:::
+
+Proceed with the standard VyOS {ref}`installation <permanent_installation>` on
+your system. Instead of the final `reboot` command, enroll the
+{abbr}`MOK (Machine Owner Key)`.
+
+```none
+vyos@vyos:~$ install mok
+input password:
+input password again:
+```
+
+You can set the `input password` to any value you choose. You'll need this
+password after reboot when MOK Manager launches to permanently install the keys.
+
+With the next reboot, MOK Manager will automatically launch
+
+:::{figure} /_static/images/uefi_secureboot_02.png
+:alt: Disable UEFI secure boot
+:::
+
+Select `Enroll MOK`
+
+:::{figure} /_static/images/uefi_secureboot_03.png
+:alt: Disable UEFI secure boot
+:::
+
+You can now view the key to be installed and continue with key installation.
+
+:::{figure} /_static/images/uefi_secureboot_04.png
+:alt: Disable UEFI secure boot
+:::
+
+:::{figure} /_static/images/uefi_secureboot_05.png
+:alt: Disable UEFI secure boot
+:::
+
+Now you need to enter the password you defined previously.
+
+:::{figure} /_static/images/uefi_secureboot_06.png
+:alt: Disable UEFI secure boot
+:::
+
+Now reboot and re-enable UEFI Secure Boot.
+
+:::{figure} /_static/images/uefi_secureboot_07.png
+:alt: Disable UEFI secure boot
+:::
+
+VyOS will now launch in UEFI Secure Boot mode. You can verify this by running
+one of the following commands:
+
+```none
+vyos@vyos:~$ show secure-boot
+SecureBoot enabled
+```
+
+```none
+vyos@vyos:~$ show log kernel | match Secure
+Oct 08 19:15:41 kernel: Secure boot enabled
+```
+
+```none
+vyos@vyos:~$    show version
+Version:          VyOS 1.5-secureboot
+Release train:    current
+Release flavor:   generic
+
+Built by:         autobuild@vyos.net
+Built on:         Tue 08 Oct 2024 18:00 UTC
+Build UUID:       5702ca38-e6f4-470f-b89e-ffc29baee474
+Build commit ID:  9eb61d3b6cf426
+
+Architecture:     x86_64
+Boot via:         installed image
+System type:      KVM guest
+Secure Boot:      enabled   <-- UEFI secure boot indicator
+
+Hardware vendor:  QEMU
+Hardware model:   Standard PC (i440FX + PIIX, 1996)
+Hardware S/N:
+Hardware UUID:    1f6e7f5c-fb52-4c33-96c9-782fbea36436
+
+Copyright:        VyOS maintainers and contributors
+```
+
+## Image Update
+
+:::{note}
+Currently, there is no signed version of `shim` for VyOS. If you
+want Secure Boot support, you can build a custom image with your own keys.
+:::
+
+During image installation, you install your {abbr}`MOK (Machine Owner Key)`
+into the UEFI variables to add trust to this key. After you re-enable Secure
+Boot in UEFI, you can only boot into your signed image.
+
+You can no longer boot into a CI-generated rolling release because those
+are not signed by a trusted party ({vytask}`T861` work in progress). This
+also means you must sign all successor builds with the same key; otherwise,
+you'll see this error:
+
+```none
+error: bad shim signature
+error: you need to load the kernel first
+```
+
+## Linux Kernel
+
+In addition to Secure Boot support, VyOS uses ephemeral key signing of Linux
+Kernel modules for an extra security layer in both Secure and non-Secure boot
+images.
+
+<https://patchwork.kernel.org/project/linux-integrity/patch/20210218220011.67625-5-nayna@linux.ibm.com/>
+
+When the CI system builds a Kernel package and required third-party modules,
+it generates a temporary (ephemeral) key pair for signing the modules. The
+public key is embedded in the Kernel binary to verify loaded modules.
+
+After the Kernel CI build completes, the generated key is discarded, meaning
+we can no longer sign additional modules with that key. The Kernel configuration
+also includes the option `CONFIG_MODULE_SIG_FORCE=y`, which enforces signature
+verification for all modules. If you try to load an unsigned module, you'll
+get this error:
+
+`insmod: ERROR: could not insert module malicious.ko: Key was rejected by
+service`
+
+This prevents loading any malicious code after the image is assembled into the
+Kernel as a module. You can disable this behavior on custom builds if needed.
+
+## Troubleshoot
+
+In most cases, if something goes wrong during system boot, you'll see this
+error message:
+
+```none
+error: bad shim signature
+error: you need to load the kernel first
+```
+
+This error means the Machine Owner Key used to sign the Kernel is not trusted
+by your UEFI. Install the MOK using the `install mok` command as described
+above.
diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md
new file mode 100644
index 00000000..901483bb
--- /dev/null
+++ b/docs/installation/virtual/md-docker.md
@@ -0,0 +1,70 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(docker)=
+
+# Run VyOS in a 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's an 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 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 you want to base the container on. In this example,
+the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you
+created a custom IPv6-enabled network, include it 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
+```
+
+To stop the container, run `docker stop vyos`.
diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md
new file mode 100644
index 00000000..1ee1c016
--- /dev/null
+++ b/docs/installation/virtual/md-eve-ng.md
@@ -0,0 +1,14 @@
+---
+lastproofread: '2026-02-02'
+---
+
+# EVE-NG
+
+:::{note}
+This page is a stub and needs expansion. Contributions
+welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation).
+:::
+
+## 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..aeac7bbf
--- /dev/null
+++ b/docs/installation/virtual/md-gns3.md
@@ -0,0 +1,191 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(vyos-on-gns3)=
+
+# Run VyOS on GNS3
+
+You may want to test VyOS in a lab environment.
+[GNS3](http://www.gns3.com) is a network emulation software that you
+can use for this purpose.
+
+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 select
+**Manually create a new Template**.
+
+:::{figure} /_static/images/gns3-01.png
+:::
+
+Select **Qemu VMs** and then click the `New` button.
+
+:::{figure} /_static/images/gns3-02.png
+:::
+
+Write a name for your VM, such as "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 you need to edit the VM settings.
+
+In the **Preferences** window, with **Qemu VMs** selected and your 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 the number of adapters to **0**, set the
+**Name format** to **eth\{0}**, and set 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 displays the system booting. It prompts for login
+  credentials. You're now at the VyOS live system.
+- {ref}`Install VyOS <installation>`
+  as normal (that is, using the `install image` command).
+- After successful installation, shut down 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: Clear the **Image** entry field to unmount the installation
+image.
+
+:::{figure} /_static/images/gns3-21.png
+:::
+
+Set the number of required network adapters. For example, set it to **4**.
+
+:::{figure} /_static/images/gns3-215.png
+:::
+
+**Advanced** settings tab: Check the **Use as a linked
+base VM** checkbox 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-proxmox.md b/docs/installation/virtual/md-proxmox.md
new file mode 100644
index 00000000..0eddc2c7
--- /dev/null
+++ b/docs/installation/virtual/md-proxmox.md
@@ -0,0 +1,62 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(proxmox)=
+
+# Running on Proxmox
+
+Proxmox is an open-source platform for virtualization. Visit
+<https://vyos.io> to download a `.qcow2` image that you can import 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 assume virtual machine ID 200 is unused and you want
+   the disk stored in a storage pool named `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. You can optionally attach a CDROM with an ISO as a cloud-init data
+   source. The command assumes the ISO is uploaded to the `local`
+   storage pool as `seed.iso`.
+
+```none
+$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso
+```
+
+4. Start the virtual machine using the Proxmox GUI or run `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 use the
+   LTS release by building from source. For instructions, see the
+   {ref}`build` section. The VyOS source code repository
+   is available at <https://github.com/vyos/vyos-build>.
+2. Prepare the VM for ISO installation. The commands assume your ISO is
+   in storage pool 'local', you want VM ID '200', and you want to create
+   a new 15GB disk on storage pool 'local-lvm'.
+
+```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 `qm start 200` or the start button in the
+   Proxmox GUI.
+4. Open the virtual console for your VM using the Proxmox web GUI.
+   Login username and password are both `vyos`.
+5. Once booted into the live system, type `install image` and follow
+   the prompts to install VyOS to the virtual drive.
+6. After installation completes, remove the installation ISO using the
+   GUI or run `qm set 200 --ide2 none`.
+7. Reboot the virtual machine using the GUI or run `qm reboot 200`.
+
+For more information about downloading and installing Proxmox, visit
+<https://www.proxmox.com/en/>.
diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md
new file mode 100644
index 00000000..34fb2197
--- /dev/null
+++ b/docs/installation/virtual/md-vmware.md
@@ -0,0 +1,38 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(vyosonvmware)=
+
+# Running on VMware ESXi
+
+## ESXi 5.5 or later
+
+`.ova` files are available for supporting users. You can also set up VyOS
+using a generic Linux instance by attaching the bootable ISO file and
+installing using the `install image` command.
+
+:::{NOTE}
+Previous issues have been documented with GRE/IPSEC tunneling
+using the E1000 adapter on VyOS guests. Use the VMXNET3 adapter instead.
+:::
+
+### Memory Contention Considerations
+
+When the underlying ESXi host reaches approximately 92% memory utilization,
+it begins the balloon process to reclaim memory from guest operating systems.
+This creates artificial memory pressure through the `vmmemctl` driver. Because
+VyOS does not have a swap file by default, this pressure cannot move memory
+data to a paging file. Instead, it consumes memory and forces the guest into
+a low memory state with no recovery option. The balloon can expand to 65% of
+guest allocated memory, so a VyOS guest using more than 35% of memory can
+encounter an out-of-memory situation and trigger the kernel `oom_kill`
+process. The `oom_kill` process then terminates memory-hungry processes.
+
+To prevent ballooning, configure VyOS routers in a resource group with
+adequate memory reservations.
+
+### References
+
+<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html>
+