summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/installation/virtual/docker.rst33
-rw-r--r--docs/installation/virtual/eve-ng.rst2
-rw-r--r--docs/installation/virtual/gns3.rst42
-rw-r--r--docs/installation/virtual/index.rst2
-rw-r--r--docs/installation/virtual/libvirt.rst71
-rw-r--r--docs/installation/virtual/proxmox.rst47
-rw-r--r--docs/installation/virtual/vmware.rst43
7 files changed, 125 insertions, 115 deletions
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 <http://www.gns3.com>`__ is a network emulation software you
-might use for it.
+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.
@@ -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 <installation>`
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
generated by cgit v1.2.3 (git 2.39.1) at 2026-07-14 10:25:16 +0000