feat(swap): import .md files and webp transition from myst/current

Selective import from origin/myst/current (cf9c9b34): - Add/update 255 .md files (full MyST conversion plus webp ref updates) - Delete 175 PNG/JPG from docs/_static/images (webp twins already present) - Delete 5 autotest topology.png (webp twins already present) Preserved on swap (untouched): - All .rst files (incremental swap pattern) - conf.py, _ext/, _include/*.txt, .gitignore - 115 canary md-*.md files - 7 superpowers/specs/*.md design docs - Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py) 🤖 Generated by [robots](https://vyos.io)
author: Yuriy Andamasov <yuriy@vyos.io> 2026-05-02 17:25:47 +0300
committer: Yuriy Andamasov <yuriy@vyos.io> 2026-05-06 16:18:03 +0300
commit: fa54a080fac977157454beb0853daf0ac0e6af66 (patch)
tree: 82b112cde06437b80515450d63eb793bee198ec6 /docs/installation
parent: 746195618941d8be8ed132f4b0be539763ec352d (diff)
download: vyos-documentation-fa54a080fac977157454beb0853daf0ac0e6af66.tar.gz
vyos-documentation-fa54a080fac977157454beb0853daf0ac0e6af66.zip
18 files changed, 2505 insertions, 0 deletions
diff --git a/docs/installation/bare-metal.md b/docs/installation/bare-metal.md
new file mode 100644
index 00000000..ed813545
--- /dev/null
+++ b/docs/installation/bare-metal.md
@@ -0,0 +1,626 @@
+(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.webp
+:alt: CSE-505-203B Back
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front.webp
+:alt: CSE-505-203B Front
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_open_1.webp
+:alt: CSE-505-203B Open 1
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_open_2.webp
+:alt: CSE-505-203B Open 2
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_open_3.webp
+:alt: CSE-505-203B Open 3
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_1.webp
+:alt: CSE-505-203B w/ 10GE Open 1
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_2.webp
+:alt: CSE-505-203B w/ 10GE Open 2
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_3.webp
+:alt: CSE-505-203B w/ 10GE Open 3
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/1u_vyos_front_10ge_open_4.webp
+: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.webp
+:alt: APU4 rack closed
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_2.webp
+:alt: APU4 rack front
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_3.webp
+:alt: 'APU4 rack module #1'
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_4.webp
+:alt: 'APU4 rack module #2'
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_rack_5.webp
+:alt: 'APU4 rack module #3 with PSU'
+:scale: 25 %
+:::
+
+##### VyOS custom print
+
+:::{figure} /_static/images/apu4_rack_vyos_print.webp
+:alt: APU4 custom VyOS powder coat
+:scale: 25 %
+:::
+
+#### Desktop / Bench Top
+
+:::{figure} /_static/images/apu4_desk_1.webp
+:alt: APU4 desktop closed
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_desk_2.webp
+:alt: APU4 desktop closed
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_desk_3.webp
+:alt: APU4 desktop back
+:scale: 25 %
+:::
+
+:::{figure} /_static/images/apu4_desk_4.webp
+: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.webp
+:::
+
+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.webp
+:::
+
+:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.webp
+:::
+
+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.webp
+:::
+
+:::{figure} ../_static/images/gowin-02.webp
+:::
+
+:::{figure} ../_static/images/gowin-03.webp
+:::
+
+:::{figure} ../_static/images/gowin-04.webp
+:::
+
+### 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/cloud/aws.md b/docs/installation/cloud/aws.md
new file mode 100644
index 00000000..de5da3aa
--- /dev/null
+++ b/docs/installation/cloud/aws.md
@@ -0,0 +1,188 @@
+---
+lastproofread: '2026-02-06'
+---
+
+# Amazon AWS
+
+## Deploy VM
+
+Deploy VyOS on Amazon {abbr}`AWS (Amazon Web Services)`.
+
+1. Click **Instances** and then click **Launch Instance**.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-01.webp
+```
+
+2. Search for "VyOS" in the Marketplace.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-02.webp
+```
+
+3. Choose the instance type. The recommended minimum is `m3.medium`.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-03.webp
+```
+
+4. Configure the instance for your requirements. Select the number of
+   instances, network, and subnet.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-04.webp
+```
+
+5. Configure additional storage. You can remove the additional storage
+   `/dev/sdb`. The root device will be `/dev/xvda`. You can skip this step.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-05.webp
+```
+
+6. Configure the security group. We recommend configuring SSH access
+   only from specific sources, or you can permit any IP address (the default).
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-06.webp
+```
+
+7. Select the SSH key pair and click **Launch Instances**.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-07.webp
+```
+
+8. Note your public IP address.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-aws-08.webp
+```
+
+9. Connect to the instance using your SSH key.
+
+```{eval-rst}
+
+  .. code-block:: none
+
+    ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3
+    vyos@ip-192-0-2-10:~$
+```
+
+
+## Amazon CloudWatch Agent Usage
+
+To use the Amazon CloudWatch agent, configure it in the Amazon Systems Manager
+Parameter Store. For instructions on creating a configuration, see
+{ref}`configuration_creation`.
+
+1. Create an {abbr}`IAM (Identity and Access Management)` role for the
+   {abbr}`EC2 (Elastic Compute Cloud)` instance to access CloudWatch service,
+   and name it CloudWatchAgentServerRole. The role should contain two default
+   policies: `CloudWatchAgentServerPolicy` and
+   `AmazonSSMManagedInstanceCore`.
+2. Attach the created role to your VyOS {abbr}`EC2 (Elastic Compute Cloud)`
+   instance.
+3. Ensure the amazon-cloudwatch-agent package is installed.
+
+```{eval-rst}
+
+  .. code-block:: none
+
+    $ sudo apt list --installed | grep amazon-cloudwatch-agent
+
+  .. note:: The amazon-cloudwatch-agent package is normally included in
+     VyOS 1.3.3+ and 1.4+
+```
+
+4. Retrieve an existing CloudWatch Agent configuration from the
+   {abbr}`SSM (Systems Manager)` Parameter Store.
+
+```{eval-rst}
+
+  .. code-block:: none
+
+    $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm:<your-configuration-name>
+
+  This step also enables systemd service and runs it.
+
+  .. note:: The VyOS platform-specific scripts feature is under development.
+     Thus, this step should be repeated manually after changing system image
+     (:doc:`/installation/update`)
+```
+
+(configuration_creation)=
+
+### CloudWatch SSM Configuration creation
+
+Creating the Amazon Cloudwatch Agent Configuration in Amazon
+{abbr}`SSM (Systems Manager)` Parameter Store.
+
+1. Create an {abbr}`IAM (Identity and Access Management)` role for your
+   {abbr}`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch
+   service. Name it `CloudWatchAgentAdminRole`. The role must contain at
+   least two policies: `CloudWatchAgentAdminPolicy` and
+   `AmazonSSMManagedInstanceCore`.
+
+```{eval-rst}
+
+  .. note:: CloudWatchAgentServerRole is too permissive and should be used only
+     for
+     creating and deploying a single configuration. After step 3, we recommend
+     replacing the ``CloudWatchAgentAdminRole`` with the
+     ``CloudWatchAgentServerRole``.
+```
+
+2. Run the CloudWatch configuration wizard.
+
+```{eval-rst}
+
+  .. code-block:: none
+
+    $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
+```
+
+3. When prompted, enter "yes" to the question "Do you want to store the
+   config in the SSM parameter store?".
+
+## AWS Gateway Load Balancer
+
+VyOS supports the AWS Gateway Load Balancer (GWLB) tunnel handler (`gwlbtun`),
+which enables VyOS to act as an inspection or processing target for GWLB. GWLB
+uses Geneve encapsulation with custom metadata to deliver traffic to VyOS for
+packet filtering, shaping, deep packet inspection, NAT, or other traffic
+manipulation functions. The tunnel handler automatically creates Linux tunnel
+interfaces (`gwi-*` for ingress and `gwo-*` for egress) per endpoint,
+allowing you to use standard Linux utilities like iptables, tc, and netfilter
+to implement your inspection or processing logic. This enables VyOS to serve as
+a centralized appliance for traffic inspection in your AWS infrastructure,
+supporting both single-endpoint (1-arm) and multi-endpoint (2-arm) deployment
+modes.
+
+For more information about integrating with AWS Gateway Load Balancer, see
+the following article from AWS:
+[How to integrate Linux instances with AWS Gateway Load Balancer](https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/).
+
+### Configuration Example
+
+Configure the AWS GWLB service with the following commands:
+
+```none
+set service aws glb script on-create '/config/scripts/glb-create.sh'
+set service aws glb script on-destroy '/config/scripts/glb-destroy.sh'
+set service aws glb status format 'simple'
+set service aws glb status port '8282'
+set service aws glb threads tunnel '4'
+set service aws glb threads tunnel-affinity '1-2'
+set service aws glb threads udp '4'
+set service aws glb threads udp-affinity '0-3'
+```
+
+
+## References
+
+- <https://console.aws.amazon.com/>
+- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-iam-roles-for-cloudwatch-agent.html>
+- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance-fleet.html>
+- <https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/>
+
diff --git a/docs/installation/cloud/azure.md b/docs/installation/cloud/azure.md
new file mode 100644
index 00000000..24b7b166
--- /dev/null
+++ b/docs/installation/cloud/azure.md
@@ -0,0 +1,98 @@
+---
+lastproofread: '2026-02-09'
+---
+
+# Azure
+
+## Deploy VM
+
+Deploy VyOS on Azure.
+
+1. Go to Azure services and click **Add new Virtual machine**.
+2. Choose a VM name, resource group, and region, then click **Browse all public
+   and private images**.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-azure-01.webp
+```
+
+3. Search for "VyOS" in the marketplace and choose the appropriate
+   subscription.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-azure-02.webp
+```
+
+4. Generate new SSH key pair or use existing.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-azure-03.webp
+```
+
+5. Configure the network, subnet, and public IP. Or use the defaults.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-azure-04.webp
+```
+
+6. Click **Review + create**. Your deployment completes in a few seconds.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-azure-05.webp
+```
+
+7. Select your new VM and note your public IP address.
+
+```{eval-rst}
+.. figure:: /_static/images/cloud-azure-06.webp
+```
+
+8. Connect to the instance with your SSH key.
+
+```{eval-rst}
+
+  .. code-block:: none
+
+    ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3
+    vyos@vyos-doc-r1:~$
+```
+
+
+## Add interface
+
+If your instance was deployed with one **eth0** (`WAN`) interface and you
+want to add another, you must shut down the instance. To add a new interface,
+such as **eth1** (`LAN`), attach it in the Azure portal and then restart the
+instance.
+
+:::{note}
+Azure doesn't allow you to attach an interface while the instance is
+running.
+:::
+
+## Absorbing Routes
+
+If you're using the VM as a router, you can use a route table to absorb some or
+all traffic from your virtual network (VNET) with your LAN interface.
+
+1. Create a route table and navigate to **Configuration**.
+2. Add one or more routes for the networks you want to route through the VyOS
+   VM. For **Next hop type**, select **Virtual Appliance** and set the **Next
+   Hop Address** to the VyOS `LAN` interface.
+
+:::{note}
+To create a default route for VMs on the subnet, use
+**Address Prefix** `0.0.0.0/0`. For a typical edge device configuration,
+configure masquerade NAT on the `WAN` interface.
+:::
+
+## Serial Console
+
+VyOS includes serial console support by default. However, if you replace the
+`config.boot` file and reboot, ensure this configuration is present:
+
+`set system console device ttyS0 speed '9600'`
+
+## References
+
+<https://azure.microsoft.com>
diff --git a/docs/installation/cloud/gcp.md b/docs/installation/cloud/gcp.md
new file mode 100644
index 00000000..828312cd
--- /dev/null
+++ b/docs/installation/cloud/gcp.md
@@ -0,0 +1,61 @@
+---
+lastproofread: '2026-02-09'
+---
+
+# Google Cloud Platform
+
+## Deploy VM
+
+To deploy VyOS on Google Cloud Platform (GCP):
+
+1. Generate an SSH key pair of type **ssh-rsa** on the host that will connect
+   to VyOS.
+
+   Example:
+
+   ```none
+   ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc"
+   ```
+
+:::{note}
+The SSH key comment must begin with `vyos@` because that's the
+default VyOS user. GCP uses this value to set the username on the instance.
+:::
+
+2. Open the GCP Console and navigate to **Metadata**. Select **SSH Keys** and
+   click **Edit**.
+
+:::{figure} /_static/images/cloud-gcp-01.webp
+Click **Add item**, paste your public SSH key, and click **Save**.
+:::
+
+:::{figure} /_static/images/cloud-gcp-02.webp
+:::
+
+3. Search for "VyOS" in the Marketplace.
+4. Configure the deployment name, zone, and machine type, then click **Deploy**.
+
+:::{figure} /_static/images/cloud-gcp-03.webp
+:::
+
+5. After a few seconds, select your **instance**.
+
+:::{figure} /_static/images/cloud-gcp-04.webp
+:::
+
+6. Note your external IP address.
+
+:::{figure} /_static/images/cloud-gcp-05.webp
+:::
+
+7. Connect to the instance using the SSH key you generated in step 1.
+
+```none
+ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3
+vyos@vyos-r1-vm:~$
+```
+
+
+## References
+
+<https://console.cloud.google.com/>
diff --git a/docs/installation/cloud/index.md b/docs/installation/cloud/index.md
new file mode 100644
index 00000000..cf7d447d
--- /dev/null
+++ b/docs/installation/cloud/index.md
@@ -0,0 +1,10 @@
+# Cloud Environments
+
+```{toctree}
+:caption: Content
+
+aws
+azure
+gcp
+oracle
+```
diff --git a/docs/installation/cloud/oracle.md b/docs/installation/cloud/oracle.md
new file mode 100644
index 00000000..f8cee52c
--- /dev/null
+++ b/docs/installation/cloud/oracle.md
@@ -0,0 +1,17 @@
+---
+lastproofread: '2026-02-09'
+---
+
+# Oracle
+
+:::{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.oracle.com/cloud/>
+
+<https://docs.oracle.com/en/cloud/paas/developer-cloud-classic/csdcc/deploy-application.html>
+
diff --git a/docs/installation/image.md b/docs/installation/image.md
new file mode 100644
index 00000000..a0fc89d4
--- /dev/null
+++ b/docs/installation/image.md
@@ -0,0 +1,113 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(image-mgmt)=
+
+# Image Management
+
+VyOS uses an image-based installation that creates a directory for each image
+on the storage device you select during installation.
+
+The boot device has the following directory structure:
+
+```none
+/
+/boot
+/boot/grub
+/boot/2025.07.16-0020-rolling.squashfs
+```
+
+The image directory contains the system kernel, a compressed root filesystem
+image, and a directory for persistent storage (such as configuration). During
+boot, the system extracts the OS image into memory and mounts the appropriate
+live-rw subdirectories to provide persistent storage for system configuration.
+
+This process ensures that the system always boots to a known working state,
+since the OS image is fixed and non-persistent. You can also install multiple
+VyOS releases on the same storage device. You can manually select the image at
+boot if needed, but the system boots the default image by default.
+
+```{opcmd} show system image
+
+List all available system images which can be booted on the current system.
+
+:::{code-block} none
+vyos@vyos:~$ show system image
+Name                     Default boot    Running
+-----------------------  --------------  ---------
+2025.07.16-0020-rolling  Yes             Yes
+1.4.1
+1.4.0
+:::
+```
+```{opcmd} delete system image [image-name]
+
+   Delete unused images from the system. You can specify an optional image name
+   to delete. Use the {opcmd}`show system image` command to list available
+   images.
+
+   :::{code-block} none
+   vyos@vyos:~$ delete system image
+   The following images are installed:
+           1: 2025.07.16-0020-rolling (running) (default boot)
+           2: 1.4.1
+           3: 1.4.0
+   Select an image to delete: 3
+   Do you really want to delete the image 1.4.0? [y/N] y
+   The image "1.4.0" was successfully deleted
+   :::
+```
+
+
+```{opcmd} show version
+
+Show current system image version.
+
+:::{code-block} none
+vyos@vyos:~$ show version
+Version:          VyOS 2025.07.16-0020-rolling
+Release train:    current
+Release flavor:   generic
+
+Built by:         autobuild@vyos.net
+Built on:         Wed 16 Jul 2025 00:21 UTC
+Build UUID:       20d432ee-6d55-4ebc-8462-46fe836246c9
+Build Commit ID:  f7ce0d8a692f2d
+
+Architecture:     x86_64
+Boot via:         installed image
+System type:      KVM guest
+Secure Boot:      n/a (BIOS)
+
+Hardware vendor:  QEMU
+Hardware model:   Standard PC (i440FX + PIIX, 1996)
+Hardware S/N:
+Hardware UUID:    b9831d42-c1fe-b2bd-7d3d-49db9418f5c9
+
+Copyright:        VyOS maintainers and contributors
+:::
+```
+
+## System rollback
+
+To roll back to a previous image, first view the available images by using the
+{opcmd}`show system image` command, then select your image with the following
+command:
+
+```{opcmd} set system image default-boot [image-name]
+
+Select the default boot image which will be started on the next boot
+of the system.
+```
+
+Then reboot the system.
+
+:::{note}
+VyOS automatically associates the configuration with each image,
+so you don't need to manage this separately. Each image has its own unique
+configuration copy.
+:::
+
+If you have console access, you can also select the boot image by restarting
+the system and using the GRUB menu at startup.
diff --git a/docs/installation/index.md b/docs/installation/index.md
new file mode 100644
index 00000000..4256aa9b
--- /dev/null
+++ b/docs/installation/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/install.md b/docs/installation/install.md
new file mode 100644
index 00000000..532bdc0c
--- /dev/null
+++ b/docs/installation/install.md
@@ -0,0 +1,466 @@
+---
+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.webp
+:::
+
+### 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.
+
+```{eval-rst}
+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.
+
+ .. code-block:: none
+
+  $ umount /dev/sdX*
+
+ 1. 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!
+
+ .. code-block:: none
+
+   # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync
+
+ 1. Wait for the operation to complete (bytes copied). On some systems, this
+    may take more than one minute.
+
+ 2. 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.
+
+ 3. Power on the computer and ensure it boots from the USB drive
+    (you may need to select the boot device or change boot settings).
+
+ 4. 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.
+
+```{eval-rst}
+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:
+
+ .. code-block:: 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.
+
+ .. code-block:: 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/secure-boot.md b/docs/installation/secure-boot.md
new file mode 100644
index 00000000..ecbc432d
--- /dev/null
+++ b/docs/installation/secure-boot.md
@@ -0,0 +1,194 @@
+---
+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.webp
+: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.webp
+:alt: Disable UEFI secure boot
+:::
+
+Select `Enroll MOK`
+
+:::{figure} /_static/images/uefi_secureboot_03.webp
+: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.webp
+:alt: Disable UEFI secure boot
+:::
+
+:::{figure} /_static/images/uefi_secureboot_05.webp
+:alt: Disable UEFI secure boot
+:::
+
+Now you need to enter the password you defined previously.
+
+:::{figure} /_static/images/uefi_secureboot_06.webp
+:alt: Disable UEFI secure boot
+:::
+
+Now reboot and re-enable UEFI Secure Boot.
+
+:::{figure} /_static/images/uefi_secureboot_07.webp
+: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/update.md b/docs/installation/update.md
new file mode 100644
index 00000000..e8b5f912
--- /dev/null
+++ b/docs/installation/update.md
@@ -0,0 +1,105 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(update_vyos)=
+
+# Update VyOS
+
+New system images can be added using the {opcmd}`add system image` command.
+This command extracts the image and prompts you to use the current system
+configuration and SSH security keys, allowing the new image to boot with your
+current configuration.
+
+:::{note}
+Only LTS releases are PGP-signed.
+:::
+
+```{opcmd} add system image \<url | path\> | [latest] [vrf name] [username user [password pass]]
+
+Use this command to install a new system image. You can retrieve the
+image from the web (``http://``, ``https://``) or from your local system.
+For example: /tmp/vyos-1.2.3-amd64.iso.
+
+   The ``add system image`` command also supports installing new VyOS versions
+   through an optional VRF. If the URL requires authentication, you can specify
+   an optional username and password on the command line, which will be passed
+   as "Basic-Auth" to the server.
+```
+
+If there isn't enough free disk space, the installation will be canceled.
+To delete images, use the {opcmd}`delete system image` command.
+
+
+VyOS associates configuration with each image, and each image has its own
+unique configuration copy. This differs from traditional network routers where
+the configuration is shared across all images.
+
+
+:::{note}
+If you have personal files such as scripts that you want to preserve
+during the upgrade, store them in `/config` since this directory is always
+copied to newly installed images.
+:::
+
+
+You can access files from a previous installation and copy them to your
+current image if they were stored in the `/config` directory. Use the
+{opcmd}`copy` command to do this. For example, to copy `/config/config.boot`
+from the VyOS `1.2.1` image, run:
+
+```none
+copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1
+```
+
+
+#### Example
+
+```none
+vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso
+Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100  338M  100  338M    0     0  3837k      0  0:01:30  0:01:30 --:--:-- 3929k
+ISO download succeeded.
+Checking for digital signature file...
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
+curl: (22) The requested URL returned error: 404 Not Found
+
+Unable to fetch digital signature file.
+Do you want to continue without signature check? (yes/no) [yes]
+Checking MD5 checksums of files on the ISO image...OK.
+Done!
+
+What would you like to name this image? [vyos-1.3-rolling-201912201452]:
+
+OK.  This image will be named: vyos-1.3-rolling-201912201452
+```
+
+You can use `latest` option. It loads the latest available Rolling release.
+
+```none
+vyos@vyos:~$ add system image latest
+```
+
+:::{note}
+To use the `latest` option, "system update-check url" must be
+configured appropriately for your installed release.
+
+For updates to the Rolling Release for AMD64, the following URL may be
+used:
+
+<https://raw.githubusercontent.com/vyos/vyos-nightly-build/refs/heads/current/version.json>
+:::
+
+:::{hint}
+You can access the latest Rolling Release for AMD64 from a web
+browser at:
+
+<https://vyos.net/get/nightly-builds/>
+:::
+
+After rebooting, verify the version you're running using the
+{opcmd}`show version` command.
diff --git a/docs/installation/virtual/docker.md b/docs/installation/virtual/docker.md
new file mode 100644
index 00000000..3489b94a
--- /dev/null
+++ b/docs/installation/virtual/docker.md
@@ -0,0 +1,72 @@
+---
+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/eve-ng.md b/docs/installation/virtual/eve-ng.md
new file mode 100644
index 00000000..1ee1c016
--- /dev/null
+++ b/docs/installation/virtual/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/gns3.md b/docs/installation/virtual/gns3.md
new file mode 100644
index 00000000..e4cb49c0
--- /dev/null
+++ b/docs/installation/virtual/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.webp
+:::
+
+Select **Qemu VMs** and then click the `New` button.
+
+:::{figure} /_static/images/gns3-02.webp
+:::
+
+Write a name for your VM, such as "VyOS", and click `Next`.
+
+:::{figure} /_static/images/gns3-03.webp
+:::
+
+Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM
+and click `Next`.
+
+:::{figure} /_static/images/gns3-04.webp
+:::
+
+Select **telnet** as your console type and click `Next`.
+
+:::{figure} /_static/images/gns3-05.webp
+:::
+
+Select **New image** for the base disk image of your VM and click
+`Create`.
+
+:::{figure} /_static/images/gns3-06.webp
+:::
+
+Use the defaults in the **Binary and format** window and click
+`Next`.
+
+:::{figure} /_static/images/gns3-07.webp
+:::
+
+Use the defaults in the **Qcow2 options** window and click `Next`.
+
+:::{figure} /_static/images/gns3-08.webp
+:::
+
+Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu
+image creator**.
+
+:::{figure} /_static/images/gns3-09.webp
+:::
+
+Click `Finish` to end the **New QEMU VM template** wizard.
+
+:::{figure} /_static/images/gns3-10.webp
+:::
+
+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.webp
+:::
+
+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.webp
+:::
+
+At the **HDD** tab, change the Disk interface to **sata** to speed up
+the boot process.
+
+:::{figure} /_static/images/gns3-13.webp
+:::
+
+At the **CD/DVD** tab click on `Browse...` and locate the VyOS image
+you want to install.
+
+:::{figure} /_static/images/gns3-14.webp
+:::
+
+:::{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.webp
+:::
+
+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.webp
+:::
+
+At the general **Preferences** window, click `OK` to save and close.
+
+:::{figure} /_static/images/gns3-17.webp
+:::
+
+(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.webp
+:::
+
+**CD/DVD** tab: Clear the **Image** entry field to unmount the installation
+image.
+
+:::{figure} /_static/images/gns3-21.webp
+:::
+
+Set the number of required network adapters. For example, set it to **4**.
+
+:::{figure} /_static/images/gns3-215.webp
+:::
+
+**Advanced** settings tab: Check the **Use as a linked
+base VM** checkbox and click `OK` to save the changes.
+
+:::{figure} /_static/images/gns3-22.webp
+:::
+
+The VyOS VM is now ready to be deployed.
diff --git a/docs/installation/virtual/index.md b/docs/installation/virtual/index.md
new file mode 100644
index 00000000..97579129
--- /dev/null
+++ b/docs/installation/virtual/index.md
@@ -0,0 +1,16 @@
+---
+lastproofread: '2026-02-02'
+---
+
+# Virtual Environments
+
+```{toctree}
+:caption: Content
+
+libvirt
+proxmox
+vmware
+gns3
+eve-ng
+docker
+```
diff --git a/docs/installation/virtual/libvirt.md b/docs/installation/virtual/libvirt.md
new file mode 100644
index 00000000..0a21a97a
--- /dev/null
+++ b/docs/installation/virtual/libvirt.md
@@ -0,0 +1,186 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(libvirt)=
+
+# Run VyOS on Libvirt QEMU/KVM
+
+Libvirt is an open-source API, daemon, and management tool for managing platform
+virtualization. You can deploy VyOS on libvirt KVM in several ways:
+using Virt-Manager or the native CLI. This example uses 4 gigabytes
+of memory, 2 CPU cores, and the 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-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 the VM with the 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 the console using the key combination
+`Ctrl + ]` and reboot the system.
+
+### Deploy from qcow2
+
+The benefit of using {abbr}`KVM (Kernel-based Virtual Machine)`
+images is that they don't require installation.
+Download the predefined VyOS `.qcow2` image.
+
+```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-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 the VM with the command `virsh console vyos_r2`
+
+```none
+$ virsh console vyos_r2
+
+Connected to domain vyos_r2
+Escape character is ^]
+
+vyos login: vyos
+Password:
+
+vyos@vyos:~$
+```
+
+If you cannot access the login screen, the KVM console may be set as the
+default boot option.
+
+Open a secondary session and run this command to reboot the VM:
+
+```none
+$ virsh reboot vyos_r2
+```
+
+Then go to the first session where you opened the console.
+Select `VyOS 1.4.x for QEMU (Serial console)` and press `Enter`.
+
+The system is fully operational.
+
+## Virt-Manager
+
+The Virt-Manager application is a desktop user interface for managing virtual
+machines through libvirt. On Linux, open the
+{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.webp
+:::
+
+3. Choose the path to the VyOS ISO image. Select any Debian-based operating
+   system.
+
+:::{figure} /_static/images/virt-libvirt-02.webp
+:::
+
+4. Choose Memory and CPU
+
+:::{figure} /_static/images/virt-libvirt-03.webp
+:::
+
+5. Disk size
+
+:::{figure} /_static/images/virt-libvirt-04.webp
+:::
+
+6. Name of VM and network selection
+
+:::{figure} /_static/images/virt-libvirt-05.webp
+:::
+
+7. Then the system will be taken to the console.
+
+:::{figure} /_static/images/virt-libvirt-06.webp
+:::
+
+(libvirt-virt-manager-qcow2)=
+
+### Deploy from qcow2
+
+Download the predefined VyOS `.qcow2` image.
+
+```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.webp
+:::
+
+3. Choose the path to the `vyos_kvm.qcow2` image that you downloaded.
+   Select any Debian-based operating system.
+
+:::{figure} /_static/images/virt-libvirt-qc-02.webp
+:::
+
+4. Choose Memory and CPU
+
+:::{figure} /_static/images/virt-libvirt-03.webp
+:::
+
+5. Name of VM and network selection
+
+:::{figure} /_static/images/virt-libvirt-05.webp
+:::
+
+6. Then the system will be taken to the console.
+
+:::{figure} /_static/images/virt-libvirt-qc-03.webp
+:::
diff --git a/docs/installation/virtual/proxmox.md b/docs/installation/virtual/proxmox.md
new file mode 100644
index 00000000..6b959341
--- /dev/null
+++ b/docs/installation/virtual/proxmox.md
@@ -0,0 +1,80 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(proxmox)=
+
+# Running on Proxmox
+
+Proxmox is an open-source platform for virtualization.
+
+## Deploy VyOS from CLI with qcow2 image
+
+1. Download the `.qcow2` image from <https://support.vyos.io/>.
+   Official images are available to users with a valid subscription.
+
+2. Copy the `.qcow2` image to a temporary directory on the Proxmox server.
+
+3. The following commands assume that virtual machine (VM) ID `200` is unused
+   and that the imported disk will be stored in a storage pool named `local-lvm`.
+
+   > ```none
+   > $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0
+   > $ qm importdisk 200 /var/lib/vz/images/vyos-<version>-proxmox-amd64.qcow2 local-lvm
+   > $ qm set 200 --virtio0 local-lvm:vm-200-disk-0
+   > $ qm set 200 --boot order=virtio0
+   > ```
+
+4. When using a `qcow2` image on Proxmox, the system
+   **does not include any preconfigured user accounts**.
+   You must define a user account using **Cloud-Init** before the
+   first boot. Otherwise, login access is not possible.
+
+   Attach a Cloud-Init data source to the VM. For example, using
+   `local-lvm` storage:
+
+   ```bash
+   $ qm set 200 --ide2 local-lvm:cloudinit
+   ```
+
+   Alternatively, add a Cloud-Init drive using the Proxmox GUI:
+
+   1. Open the VM and navigate to **Hardware**
+   2. Click **Add** → **CloudInit Drive**
+   3. Select a storage (for example, `local-lvm`)
+   4. Click **Add**
+
+5. Start the virtual machine using the Proxmox GUI or by running `qm start 200`.
+
+## Deploy VyOS from CLI with rolling release ISO
+
+1. Download the rolling release ISO from
+   <https://vyos.net/get/nightly-builds/>.
+2. Prepare the VM for ISO installation.
+   The commands below assume that the ISO image is available in the
+   `local` storage, a VM ID `200` is unused, and a 15GB disk will be
+   created on storage pool `local-lvm`.
+
+```none
+qm create 200 --name vyos --memory 4096 \
+--net0 virtio,bridge=vmbr0 \
+--scsihw virtio-scsi-pci \
+--scsi0 local-lvm:15 \
+--ide2 local:iso/vyos-<version>.iso,media=cdrom \
+--boot order=ide2
+```
+
+3. Start the VM using `qm start 200` or by clicking the **Start**
+   button in the Proxmox GUI.
+4. In the Proxmox GUI, open the virtual console for your new VM.
+   The login username and password are `vyos`/`vyos`.
+5. After booting 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`, then set the boot device
+   with `qm set 200 --boot order=scsi0`.
+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/vmware.md b/docs/installation/virtual/vmware.md
new file mode 100644
index 00000000..34fb2197
--- /dev/null
+++ b/docs/installation/virtual/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>
+
author	Yuriy Andamasov <yuriy@vyos.io>	2026-05-02 17:25:47 +0300
committer	Yuriy Andamasov <yuriy@vyos.io>	2026-05-06 16:18:03 +0300
commit	fa54a080fac977157454beb0853daf0ac0e6af66 (patch)
tree	82b112cde06437b80515450d63eb793bee198ec6 /docs/installation
parent	746195618941d8be8ed132f4b0be539763ec352d (diff)
download	vyos-documentation-fa54a080fac977157454beb0853daf0ac0e6af66.tar.gz vyos-documentation-fa54a080fac977157454beb0853daf0ac0e6af66.zip