Merge pull request #1884 from vyos/fix/docs-typos-swap-current

docs: fix typos and grammar (ported from #1852 RST → MyST)

7 files changed, 597 insertions, 0 deletions

diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md
new file mode 100644
index 00000000..3489b94a
--- /dev/null
+++ b/docs/installation/virtual/md-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/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..e4cb49c0
--- /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.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/md-index.md b/docs/installation/virtual/md-index.md
new file mode 100644
index 00000000..97579129
--- /dev/null
+++ b/docs/installation/virtual/md-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/md-libvirt.md b/docs/installation/virtual/md-libvirt.md
new file mode 100644
index 00000000..0a21a97a
--- /dev/null
+++ b/docs/installation/virtual/md-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/md-proxmox.md b/docs/installation/virtual/md-proxmox.md
new file mode 100644
index 00000000..6b959341
--- /dev/null
+++ b/docs/installation/virtual/md-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/md-vmware.md b/docs/installation/virtual/md-vmware.md
new file mode 100644
index 00000000..66278ae9
--- /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>
+