From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/installation/virtual/docker.md | 72 +++++++++++ docs/installation/virtual/docker.rst | 75 ------------ docs/installation/virtual/eve-ng.md | 14 +++ docs/installation/virtual/eve-ng.rst | 14 --- docs/installation/virtual/gns3.md | 191 ++++++++++++++++++++++++++++++ docs/installation/virtual/gns3.rst | 177 --------------------------- docs/installation/virtual/index.md | 16 +++ docs/installation/virtual/index.rst | 15 --- docs/installation/virtual/libvirt.md | 186 +++++++++++++++++++++++++++++ docs/installation/virtual/libvirt.rst | 186 ----------------------------- docs/installation/virtual/md-docker.md | 72 ----------- docs/installation/virtual/md-eve-ng.md | 14 --- docs/installation/virtual/md-gns3.md | 191 ------------------------------ docs/installation/virtual/md-index.md | 16 --- docs/installation/virtual/md-libvirt.md | 186 ----------------------------- docs/installation/virtual/md-proxmox.md | 80 ------------- docs/installation/virtual/md-vmware.md | 38 ------ docs/installation/virtual/proxmox.md | 80 +++++++++++++ docs/installation/virtual/proxmox.rst | 91 -------------- docs/installation/virtual/rst-docker.rst | 75 ++++++++++++ docs/installation/virtual/rst-eve-ng.rst | 14 +++ docs/installation/virtual/rst-gns3.rst | 177 +++++++++++++++++++++++++++ docs/installation/virtual/rst-index.rst | 15 +++ docs/installation/virtual/rst-libvirt.rst | 186 +++++++++++++++++++++++++++++ docs/installation/virtual/rst-proxmox.rst | 91 ++++++++++++++ docs/installation/virtual/rst-vmware.rst | 41 +++++++ docs/installation/virtual/vmware.md | 38 ++++++ docs/installation/virtual/vmware.rst | 41 ------- 28 files changed, 1196 insertions(+), 1196 deletions(-) create mode 100644 docs/installation/virtual/docker.md delete mode 100644 docs/installation/virtual/docker.rst create mode 100644 docs/installation/virtual/eve-ng.md delete mode 100644 docs/installation/virtual/eve-ng.rst create mode 100644 docs/installation/virtual/gns3.md delete mode 100644 docs/installation/virtual/gns3.rst create mode 100644 docs/installation/virtual/index.md delete mode 100644 docs/installation/virtual/index.rst create mode 100644 docs/installation/virtual/libvirt.md delete mode 100644 docs/installation/virtual/libvirt.rst delete mode 100644 docs/installation/virtual/md-docker.md delete mode 100644 docs/installation/virtual/md-eve-ng.md delete mode 100644 docs/installation/virtual/md-gns3.md delete mode 100644 docs/installation/virtual/md-index.md delete mode 100644 docs/installation/virtual/md-libvirt.md delete mode 100644 docs/installation/virtual/md-proxmox.md delete mode 100644 docs/installation/virtual/md-vmware.md create mode 100644 docs/installation/virtual/proxmox.md delete mode 100644 docs/installation/virtual/proxmox.rst create mode 100644 docs/installation/virtual/rst-docker.rst create mode 100644 docs/installation/virtual/rst-eve-ng.rst create mode 100644 docs/installation/virtual/rst-gns3.rst create mode 100644 docs/installation/virtual/rst-index.rst create mode 100644 docs/installation/virtual/rst-libvirt.rst create mode 100644 docs/installation/virtual/rst-proxmox.rst create mode 100644 docs/installation/virtual/rst-vmware.rst create mode 100644 docs/installation/virtual/vmware.md delete mode 100644 docs/installation/virtual/vmware.rst (limited to 'docs/installation/virtual') 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/docker.rst b/docs/installation/virtual/docker.rst deleted file mode 100644 index d62c011b..00000000 --- a/docs/installation/virtual/docker.rst +++ /dev/null @@ -1,75 +0,0 @@ -: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. - -.. code-block:: 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. - -.. code-block:: none - - { - "ipv6": true, - "fixed-cidr-v6": "2001:db8::/64" - } - -Reload the Docker configuration. - -.. code-block:: 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``. - -.. code-block:: 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 + + diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst deleted file mode 100644 index f3db28fe..00000000 --- a/docs/installation/virtual/eve-ng.rst +++ /dev/null @@ -1,14 +0,0 @@ -:lastproofread: 2026-02-02 - -###### -EVE-NG -###### - -.. note:: This page is a stub and needs expansion. Contributions - welcome via the `VyOS documentation repository - `_. - -References -========== - -https://www.eve-ng.net/ \ No newline at end of file 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 ` + 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/gns3.rst b/docs/installation/virtual/gns3.rst deleted file mode 100644 index 2c0b5224..00000000 --- a/docs/installation/virtual/gns3.rst +++ /dev/null @@ -1,177 +0,0 @@ -:lastproofread: 2026-02-02 - -.. _vyos-on-gns3: - -############### -Run VyOS on GNS3 -############### - -You may want to test VyOS in a lab environment. -`GNS3 `__ 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 `__. - -.. _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.* - -Select **Qemu VMs** and then click the ``New`` button. - -.. figure:: /_static/images/gns3-02.* - -Write a name for your VM, such as "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.* - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.* - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.* - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.* - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.* - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.* - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.* - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.* - -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.* - -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.* - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.* - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.* - -.. 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.* - -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.* - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.* - - -.. _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 ` - 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.* - -**CD/DVD** tab: Clear the **Image** entry field to unmount the installation -image. - -.. figure:: /_static/images/gns3-21.* - -Set the number of required network adapters. For example, set it to **4**. - -.. figure:: /_static/images/gns3-215.* - -**Advanced** settings tab: Check the **Use as a linked -base VM** checkbox and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.* - -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/index.rst b/docs/installation/virtual/index.rst deleted file mode 100644 index e1a3caf5..00000000 --- a/docs/installation/virtual/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -: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/libvirt.rst b/docs/installation/virtual/libvirt.rst deleted file mode 100644 index 7374e42c..00000000 --- a/docs/installation/virtual/libvirt.rst +++ /dev/null @@ -1,186 +0,0 @@ -: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. - -.. code-block:: 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`` - -.. code-block:: 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. - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: 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`` - -.. code-block:: 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: - -.. code-block:: 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.* - -3. Choose the path to the VyOS ISO image. Select any Debian-based operating - system. - -.. figure:: /_static/images/virt-libvirt-02.* - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.* - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.* - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.* - -7. Then the system will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.* - -.. _libvirt:virt-manager_qcow2: - -Deploy from qcow2 ------------------ - -Download the predefined VyOS ``.qcow2`` image. - -.. code-block:: 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.* - -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.* - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.* - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.* - -6. Then the system will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.* - - - diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md deleted file mode 100644 index 3489b94a..00000000 --- a/docs/installation/virtual/md-docker.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -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 deleted file mode 100644 index 1ee1c016..00000000 --- a/docs/installation/virtual/md-eve-ng.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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 - - diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md deleted file mode 100644 index e4cb49c0..00000000 --- a/docs/installation/virtual/md-gns3.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -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 ` - 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 deleted file mode 100644 index 97579129..00000000 --- a/docs/installation/virtual/md-index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 deleted file mode 100644 index 0a21a97a..00000000 --- a/docs/installation/virtual/md-libvirt.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -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 deleted file mode 100644 index 6b959341..00000000 --- a/docs/installation/virtual/md-proxmox.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -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 . - 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--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 - . -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-.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 -. - diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md deleted file mode 100644 index 66278ae9..00000000 --- a/docs/installation/virtual/md-vmware.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -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 - - - 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 . + 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--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 + . +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-.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 +. + diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst deleted file mode 100644 index d34be290..00000000 --- a/docs/installation/virtual/proxmox.rst +++ /dev/null @@ -1,91 +0,0 @@ -: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``. - - - .. code-block:: none - - $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 - $ qm importdisk 200 /var/lib/vz/images/vyos--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: - - .. code-block:: bash - - $ qm set 200 --ide2 local-lvm:cloudinit - - Alternatively, add a Cloud-Init drive using the Proxmox GUI: - - #. Open the VM and navigate to **Hardware** - #. Click **Add** → **CloudInit Drive** - #. Select a storage (for example, ``local-lvm``) - #. 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`. - -.. code-block:: none - - qm create 200 --name vyos --memory 4096 \ - --net0 virtio,bridge=vmbr0 \ - --scsihw virtio-scsi-pci \ - --scsi0 local-lvm:15 \ - --ide2 local:iso/vyos-.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/rst-docker.rst b/docs/installation/virtual/rst-docker.rst new file mode 100644 index 00000000..d62c011b --- /dev/null +++ b/docs/installation/virtual/rst-docker.rst @@ -0,0 +1,75 @@ +: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. + +.. code-block:: 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. + +.. code-block:: none + + { + "ipv6": true, + "fixed-cidr-v6": "2001:db8::/64" + } + +Reload the Docker configuration. + +.. code-block:: 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``. + +.. code-block:: 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/rst-eve-ng.rst b/docs/installation/virtual/rst-eve-ng.rst new file mode 100644 index 00000000..f3db28fe --- /dev/null +++ b/docs/installation/virtual/rst-eve-ng.rst @@ -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 + `_. + +References +========== + +https://www.eve-ng.net/ \ No newline at end of file diff --git a/docs/installation/virtual/rst-gns3.rst b/docs/installation/virtual/rst-gns3.rst new file mode 100644 index 00000000..2c0b5224 --- /dev/null +++ b/docs/installation/virtual/rst-gns3.rst @@ -0,0 +1,177 @@ +:lastproofread: 2026-02-02 + +.. _vyos-on-gns3: + +############### +Run VyOS on GNS3 +############### + +You may want to test VyOS in a lab environment. +`GNS3 `__ 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 `__. + +.. _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.* + +Select **Qemu VMs** and then click the ``New`` button. + +.. figure:: /_static/images/gns3-02.* + +Write a name for your VM, such as "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.* + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.* + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.* + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.* + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.* + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.* + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.* + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.* + +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.* + +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.* + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.* + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.* + +.. 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.* + +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.* + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.* + + +.. _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 ` + 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.* + +**CD/DVD** tab: Clear the **Image** entry field to unmount the installation +image. + +.. figure:: /_static/images/gns3-21.* + +Set the number of required network adapters. For example, set it to **4**. + +.. figure:: /_static/images/gns3-215.* + +**Advanced** settings tab: Check the **Use as a linked +base VM** checkbox and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.* + +The VyOS VM is now ready to be deployed. + diff --git a/docs/installation/virtual/rst-index.rst b/docs/installation/virtual/rst-index.rst new file mode 100644 index 00000000..e1a3caf5 --- /dev/null +++ b/docs/installation/virtual/rst-index.rst @@ -0,0 +1,15 @@ +:lastproofread: 2026-02-02 + +#################### +Virtual Environments +#################### + +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng + docker diff --git a/docs/installation/virtual/rst-libvirt.rst b/docs/installation/virtual/rst-libvirt.rst new file mode 100644 index 00000000..7374e42c --- /dev/null +++ b/docs/installation/virtual/rst-libvirt.rst @@ -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. + +.. code-block:: 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`` + +.. code-block:: 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. + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + +Create VM with ``import`` qcow2 disk option. + +.. code-block:: 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`` + +.. code-block:: 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: + +.. code-block:: 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.* + +3. Choose the path to the VyOS ISO image. Select any Debian-based operating + system. + +.. figure:: /_static/images/virt-libvirt-02.* + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.* + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.* + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.* + +7. Then the system will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.* + +.. _libvirt:virt-manager_qcow2: + +Deploy from qcow2 +----------------- + +Download the predefined VyOS ``.qcow2`` image. + +.. code-block:: 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.* + +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.* + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.* + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.* + +6. Then the system will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.* + + + diff --git a/docs/installation/virtual/rst-proxmox.rst b/docs/installation/virtual/rst-proxmox.rst new file mode 100644 index 00000000..d34be290 --- /dev/null +++ b/docs/installation/virtual/rst-proxmox.rst @@ -0,0 +1,91 @@ +: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``. + + + .. code-block:: none + + $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 + $ qm importdisk 200 /var/lib/vz/images/vyos--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: + + .. code-block:: bash + + $ qm set 200 --ide2 local-lvm:cloudinit + + Alternatively, add a Cloud-Init drive using the Proxmox GUI: + + #. Open the VM and navigate to **Hardware** + #. Click **Add** → **CloudInit Drive** + #. Select a storage (for example, ``local-lvm``) + #. 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`. + +.. code-block:: none + + qm create 200 --name vyos --memory 4096 \ + --net0 virtio,bridge=vmbr0 \ + --scsihw virtio-scsi-pci \ + --scsi0 local-lvm:15 \ + --ide2 local:iso/vyos-.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/rst-vmware.rst b/docs/installation/virtual/rst-vmware.rst new file mode 100644 index 00000000..e18ea4c8 --- /dev/null +++ b/docs/installation/virtual/rst-vmware.rst @@ -0,0 +1,41 @@ +: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 +---------- + +.. stop_vyoslinter + +https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html + +.. start_vyoslinter \ No newline at end of file diff --git a/docs/installation/virtual/vmware.md b/docs/installation/virtual/vmware.md new file mode 100644 index 00000000..66278ae9 --- /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 + + + diff --git a/docs/installation/virtual/vmware.rst b/docs/installation/virtual/vmware.rst deleted file mode 100644 index e18ea4c8..00000000 --- a/docs/installation/virtual/vmware.rst +++ /dev/null @@ -1,41 +0,0 @@ -: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 ----------- - -.. stop_vyoslinter - -https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html - -.. start_vyoslinter \ No newline at end of file -- cgit v1.2.3