From 3f9df96e6b5125a4bfb488aa619aa1748687e45d Mon Sep 17 00:00:00 2001 From: Quill <69414602+teslazonda@users.noreply.github.com> Date: Mon, 16 Feb 2026 21:17:22 +0900 Subject: Proofread docs in /installation/virtual directory (#1752) * docker.rst * eve-ng.rst * gns3.rst * libvirt.rst * proxmox.rst * vmware.rst --- docs/installation/virtual/docker.rst | 33 ++++++++-------- docs/installation/virtual/eve-ng.rst | 2 + docs/installation/virtual/gns3.rst | 42 +++++++++++---------- docs/installation/virtual/index.rst | 2 + docs/installation/virtual/libvirt.rst | 71 ++++++++++++++++------------------- docs/installation/virtual/proxmox.rst | 47 +++++++++++++++-------- docs/installation/virtual/vmware.rst | 43 ++++++++++----------- 7 files changed, 125 insertions(+), 115 deletions(-) (limited to 'docs') diff --git a/docs/installation/virtual/docker.rst b/docs/installation/virtual/docker.rst index 0abb4f26..282e4e63 100644 --- a/docs/installation/virtual/docker.rst +++ b/docs/installation/virtual/docker.rst @@ -1,34 +1,36 @@ +:lastproofread: 2026-02-02 + .. _docker: -*************************** -Running in Docker Container -*************************** +****************************** +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 +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 +VyOS requires an IPv6-enabled Docker network. Currently Linux distributions +do not enable Docker IPv6 support by default. You can enable IPv6 support in two ways. Method 1: Create a docker network with IPv6 support --------------------------------------------------- -Here is a example using the macvlan driver. +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 +Method 2: Add IPv6 support to the Docker daemon ----------------------------------------------- -Edit /etc/docker/daemon.json to set the ``ipv6`` key to ``true`` and to specify +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 @@ -38,7 +40,7 @@ the ``fixed-cidr-v6`` to your desired IPv6 subnet. "fixed-cidr-v6": "2001:db8::/64" } -Reload the docker configuration. +Reload the Docker configuration. .. code-block:: none @@ -48,11 +50,10 @@ Reload the docker configuration. Deploy container from ISO ========================= -Download the ISO on which you want to base the container. In this example, -the name of the ISO is ``vyos-1.4-rolling-202308240020-amd64.iso``. If you -created a custom IPv6-enabled network, the ``docker run`` command below -will require that this network be included as the ``--net`` parameter to -``docker run``. +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 @@ -71,4 +72,4 @@ will require that this network be included as the ``--net`` parameter to > vyos:1.4-rolling-202111281249 /sbin/init $ docker exec -ti vyos su - vyos -You can execute ``docker stop vyos`` when you are finished with the container. +To stop the container, run ``docker stop vyos``. diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst index d5134838..855daeb0 100644 --- a/docs/installation/virtual/eve-ng.rst +++ b/docs/installation/virtual/eve-ng.rst @@ -1,3 +1,5 @@ +:lastproofread: 2026-02-02 + ###### EVE-NG ###### diff --git a/docs/installation/virtual/gns3.rst b/docs/installation/virtual/gns3.rst index f95bd9c9..31bb6887 100644 --- a/docs/installation/virtual/gns3.rst +++ b/docs/installation/virtual/gns3.rst @@ -1,12 +1,14 @@ +:lastproofread: 2026-02-02 + .. _vyos-on-gns3: ############### -Running on GNS3 +Run VyOS on GNS3 ############### -Sometimes you may want to test VyOS in a lab environment. -`GNS3 `__ is a network emulation software you -might use for it. +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. @@ -30,16 +32,16 @@ VM setup First, a virtual machine (VM) for the VyOS installation must be created in GNS3. -Go to the GNS3 **File** menu, click **New template** and choose select +Go to the GNS3 **File** menu, click **New template**, and select **Manually create a new Template**. .. figure:: /_static/images/gns3-01.png -Select **Quemu VMs** and then click on the ``New`` button. +Select **Qemu VMs** and then click the ``New`` button. .. figure:: /_static/images/gns3-02.png -Write a name for your VM, for instance "VyOS", and click ``Next``. +Write a name for your VM, such as "VyOS", and click ``Next``. .. figure:: /_static/images/gns3-03.png @@ -75,10 +77,10 @@ Click ``Finish`` to end the **New QEMU VM template** wizard. .. figure:: /_static/images/gns3-10.png -Now the VM settings have to be edited. +Now you need to edit the VM settings. -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the ``Edit`` button. +In the **Preferences** window, with **Qemu VMs** selected and your new VM +selected, click the ``Edit`` button. .. figure:: /_static/images/gns3-11.png @@ -105,8 +107,8 @@ you want to install. .. 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 **0** as the number of adapters, set the -**Name format** to **eth{0}** and the **Type** to **Paravirtualized +In the **Network** tab, set the number of adapters to **0**, set the +**Name format** to **eth{0}**, and set the **Type** to **Paravirtualized Network I/O (virtio-net-pci)**. .. figure:: /_static/images/gns3-15.png @@ -131,12 +133,12 @@ VyOS installation * Drag the newly created VyOS VM into it. * Start the VM. * Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. + 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 a successful installation, shutdown the VM with the ``poweroff`` +* After successful installation, shut down the VM with the ``poweroff`` command. * **Delete the VM** from the GNS3 project. @@ -157,17 +159,17 @@ necessary as outlined below: .. figure:: /_static/images/gns3-20.png -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. +**CD/DVD** tab: Clear the **Image** entry field to unmount the installation +image. .. figure:: /_static/images/gns3-21.png -Set the number of required network adapters, for example **4**. +Set the number of required network adapters. For example, set it to **4**. .. figure:: /_static/images/gns3-215.png -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click ``OK`` to save the changes. +**Advanced** settings tab: Check the **Use as a linked +base VM** checkbox and click ``OK`` to save the changes. .. figure:: /_static/images/gns3-22.png diff --git a/docs/installation/virtual/index.rst b/docs/installation/virtual/index.rst index 1654ff9e..e1a3caf5 100644 --- a/docs/installation/virtual/index.rst +++ b/docs/installation/virtual/index.rst @@ -1,3 +1,5 @@ +:lastproofread: 2026-02-02 + #################### Virtual Environments #################### diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst index 5bc16273..20b3ff1a 100644 --- a/docs/installation/virtual/libvirt.rst +++ b/docs/installation/virtual/libvirt.rst @@ -1,13 +1,15 @@ +:lastproofread: 2026-02-02 + .. _libvirt: -*************************** -Running on Libvirt Qemu/KVM -*************************** +**************************** +Run VyOS on Libvirt QEMU/KVM +**************************** -Libvirt is an open-source API, daemon and management tool for managing platform -virtualization. There are several ways to deploy VyOS on libvirt kvm. -Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes -of memory, 2 cores CPU and default network virbr0. +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 === @@ -33,7 +35,7 @@ the virtual network (type Virtio) created by the hypervisor with NAT. --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ --noautoconsole -Connect to VM with command ``virsh console vyos_r1`` +Connect to the VM with the command ``virsh console vyos_r1`` .. code-block:: none @@ -47,14 +49,14 @@ Connect to VM with command ``virsh console vyos_r1`` vyos@vyos:~$ install image -After installation - exit from the console using the key combination +After installation, exit the console using the key combination ``Ctrl + ]`` and reboot the system. Deploy from qcow2 ----------------- -The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` -images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for ``KVM`` +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 @@ -76,7 +78,7 @@ Create VM with ``import`` qcow2 disk option. --import \ --noautoconsole -Connect to VM with command ``virsh console vyos_r2`` +Connect to the VM with the command ``virsh console vyos_r2`` .. code-block:: none @@ -90,35 +92,25 @@ Connect to VM with command ``virsh console vyos_r2`` vyos@vyos:~$ -If you can not go to this screen +If you cannot access the login screen, the KVM console may be set as the +default boot option. -.. code-block:: none - - vyos login: vyos - Password: - -Stayed in this stage. This is because the KVM console is chosen as the default boot option. - -.. code-block:: none - - Connected to domain vyos_r2 - Escape character is ^] - -Open a secondary/parallel session and use this command to reboot the VM: +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`` +Select ``VyOS 1.4.x for QEMU (Serial console)`` and press ``Enter``. The system is fully operational. -Virt-manager +Virt-Manager ============ -The virt-manager application is a desktop user interface for managing virtual -machines through libvirt. On the linux open + +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: @@ -126,14 +118,15 @@ machines through libvirt. On the linux open Deploy from ISO --------------- -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new +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.png -3. Choose path to iso vyos.iso. Operating System can be any Debian based. +3. Choose the path to the VyOS ISO image. Select any Debian-based operating + system. .. figure:: /_static/images/virt-libvirt-02.png @@ -149,7 +142,7 @@ Deploy from ISO .. figure:: /_static/images/virt-libvirt-05.png -7. Then you will be taken to the console. +7. Then the system will be taken to the console. .. figure:: /_static/images/virt-libvirt-06.png @@ -158,22 +151,22 @@ Deploy from ISO Deploy from qcow2 ----------------- -Download predefined VyOS.qcow2 image for ``KVM`` +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 +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.png -3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously - downloaded . Operation System can be any Debian based. +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.png @@ -185,7 +178,7 @@ Download predefined VyOS.qcow2 image for ``KVM`` .. figure:: /_static/images/virt-libvirt-05.png -6. Then you will be taken to the console. +6. Then the system will be taken to the console. .. figure:: /_static/images/virt-libvirt-qc-03.png diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst index e44aa65a..070627aa 100644 --- a/docs/installation/virtual/proxmox.rst +++ b/docs/installation/virtual/proxmox.rst @@ -1,18 +1,21 @@ +:lastproofread: 2026-02-02 + .. _proxmox: ****************** Running on Proxmox ****************** -Proxmox is an open-source platform for virtualization. Please visit -https://vyos.io to see how to get a qcow2 image that can be imported -into Proxmox. +Proxmox is an open-source platform for virtualization. Visit +https://vyos.io to download a ``.qcow2`` image that you can import into +Proxmox. Deploy VyOS from CLI with qcow2 image ===================================== -1. Copy the qcow2 image to a temporary directory on the Proxmox server. -2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. +1. Copy the ``.qcow2`` image to a temporary directory on the Proxmox server. +2. The commands assume virtual machine ID 200 is unused and you want + the disk stored in a storage pool named `local-lvm`. .. code-block:: none @@ -21,36 +24,48 @@ Deploy VyOS from CLI with qcow2 image $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 $ qm set 200 --boot order=virtio0 -3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. +3. You can optionally attach a CDROM with an ISO as a cloud-init data + source. The command assumes the ISO is uploaded to the `local` + storage pool as `seed.iso`. .. code-block:: none $ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso -4. Start the virtual machine in the proxmox GUI or CLI using ``qm start 200``. +4. Start the virtual machine using the Proxmox GUI or run ``qm start 200``. Deploy VyOS from CLI with rolling release ISO ============================================= -1. Download the rolling release iso from https://vyos.net/get/nightly-builds/. Non-subscribers can always get the LTS release by building it from source. Instructions can be found in the :ref:`build` section of this manual. VyOS source code repository is available https://github.com/vyos/vyos-build. -2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. +1. Download the rolling release ISO from + https://vyos.net/get/nightly-builds/. Non-subscribers can use the + LTS release by building from source. For instructions, see the + :ref:`build` section. The VyOS source code repository + is available at https://github.com/vyos/vyos-build. +2. Prepare the VM for ISO installation. The commands assume your ISO is + in storage pool 'local', you want VM ID '200', and you want to create + a new 15GB disk on storage pool 'local-lvm'. .. code-block:: none qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 -3. Start the VM using the command ``qm start 200`` or using the start button located in the proxmox GUI. -4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is ``vyos/vyos``. -5. Once booted into the live system, type ``install image`` into the command line and follow the prompts to install VyOS to the virtual drive. -6. After installation has completed, remove the installation iso using the GUI or ``qm set 200 --ide2 none``. -7. Reboot the virtual machine using the GUI or ``qm reboot 200``. +3. Start the VM using ``qm start 200`` or the start button in the + Proxmox GUI. +4. Open the virtual console for your VM using the Proxmox web GUI. + Login username and password are both ``vyos``. +5. Once booted into the live system, type ``install image`` and follow + the prompts to install VyOS to the virtual drive. +6. After installation completes, remove the installation ISO using the + GUI or run ``qm set 200 --ide2 none``. +7. Reboot the virtual machine using the GUI or run ``qm reboot 200``. -Visit https://www.proxmox.com/en/ for more information about the download -and installation of this hypervisor. +For more information about downloading and installing Proxmox, visit +https://www.proxmox.com/en/. diff --git a/docs/installation/virtual/vmware.rst b/docs/installation/virtual/vmware.rst index a522dc78..e18ea4c8 100644 --- a/docs/installation/virtual/vmware.rst +++ b/docs/installation/virtual/vmware.rst @@ -1,3 +1,5 @@ +:lastproofread: 2026-02-02 + .. _vyosonvmware: Running on VMware ESXi @@ -6,34 +8,27 @@ Running on VMware ESXi ESXi 5.5 or later ***************** -.ova files are available for supporting users, and a VyOS can also be stood up -using a generic Linux instance, and attaching the bootable ISO file and -installing from the ISO using the normal process around `install image`. +``.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:: There have been previous documented issues with GRE/IPSEC tunneling - using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been - advised. +.. 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 is approaching ~92% memory utilisation it will -start the balloon process in a 'soft' state to start reclaiming memory from -guest operating systems. This causes an artificial pressure using the vmmemctl -driver on memory usage on the virtual guest. As VyOS by default does not have -a swap file, this vmmemctl pressure is unable to force processes to move in -memory data to the paging file, and blindly consumes memory forcing the -virtual guest into a low memory state with no way to escape. The balloon -can expand to 65% of guest allocated memory, so a VyOS guest running >35% of -memory usage, can encounter an out of memory situation, and trigger the kernel -oom_kill process. At this point a weighted lottery favouring memory hungry -processes will be run with the unlucky winner being terminated by the kernel. - -It is advised that VyOS routers are configured in a resource group with -adequate memory reservations so that ballooning is not inflicted on -virtual VyOS guests. - - - +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 -- cgit v1.2.3