diff options
Diffstat (limited to 'docs/installation/virtual')
| -rw-r--r-- | docs/installation/virtual/md-docker.md | 72 | ||||
| -rw-r--r-- | docs/installation/virtual/md-eve-ng.md | 14 | ||||
| -rw-r--r-- | docs/installation/virtual/md-gns3.md | 191 | ||||
| -rw-r--r-- | docs/installation/virtual/md-index.md | 16 | ||||
| -rw-r--r-- | docs/installation/virtual/md-libvirt.md | 186 | ||||
| -rw-r--r-- | docs/installation/virtual/md-proxmox.md | 80 | ||||
| -rw-r--r-- | docs/installation/virtual/md-vmware.md | 38 |
7 files changed, 0 insertions, 597 deletions
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 - -<https://www.eve-ng.net/> 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 <installation>` - as normal (that is, using the `install image` command). -- After successful installation, shut down the VM with the `poweroff` - command. -- **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -(vyos-vm-configuration)= - -## VyOS VM configuration - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -:::{figure} /_static/images/gns3-20.webp -::: - -**CD/DVD** tab: Clear the **Image** entry field to unmount the installation -image. - -:::{figure} /_static/images/gns3-21.webp -::: - -Set the number of required network adapters. For example, set it to **4**. - -:::{figure} /_static/images/gns3-215.webp -::: - -**Advanced** settings tab: Check the **Use as a linked -base VM** checkbox and click `OK` to save the changes. - -:::{figure} /_static/images/gns3-22.webp -::: - -The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md 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 <https://support.vyos.io/>. - Official images are available to users with a valid subscription. - -2. Copy the `.qcow2` image to a temporary directory on the Proxmox server. - -3. The following commands assume that virtual machine (VM) ID `200` is unused - and that the imported disk will be stored in a storage pool named `local-lvm`. - - > ```none - > $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 - > $ qm importdisk 200 /var/lib/vz/images/vyos-<version>-proxmox-amd64.qcow2 local-lvm - > $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 - > $ qm set 200 --boot order=virtio0 - > ``` - -4. When using a `qcow2` image on Proxmox, the system - **does not include any preconfigured user accounts**. - You must define a user account using **Cloud-Init** before the - first boot. Otherwise, login access is not possible. - - Attach a Cloud-Init data source to the VM. For example, using - `local-lvm` storage: - - ```bash - $ qm set 200 --ide2 local-lvm:cloudinit - ``` - - Alternatively, add a Cloud-Init drive using the Proxmox GUI: - - 1. Open the VM and navigate to **Hardware** - 2. Click **Add** → **CloudInit Drive** - 3. Select a storage (for example, `local-lvm`) - 4. Click **Add** - -5. Start the virtual machine using the Proxmox GUI or by running `qm start 200`. - -## Deploy VyOS from CLI with rolling release ISO - -1. Download the rolling release ISO from - <https://vyos.net/get/nightly-builds/>. -2. Prepare the VM for ISO installation. - The commands below assume that the ISO image is available in the - `local` storage, a VM ID `200` is unused, and a 15GB disk will be - created on storage pool `local-lvm`. - -```none -qm create 200 --name vyos --memory 4096 \ ---net0 virtio,bridge=vmbr0 \ ---scsihw virtio-scsi-pci \ ---scsi0 local-lvm:15 \ ---ide2 local:iso/vyos-<version>.iso,media=cdrom \ ---boot order=ide2 -``` - -3. Start the VM using `qm start 200` or by clicking the **Start** - button in the Proxmox GUI. -4. In the Proxmox GUI, open the virtual console for your new VM. - The login username and password are `vyos`/`vyos`. -5. After booting into the live system, type `install image` and follow - the prompts to install VyOS to the virtual drive. -6. After installation completes, remove the installation ISO using the - GUI or run `qm set 200 --ide2 none`, then set the boot device - with `qm set 200 --boot order=scsi0`. -7. Reboot the virtual machine using the GUI or run `qm reboot 200`. - -For more information about downloading and installing Proxmox, visit -<https://www.proxmox.com/en/>. - diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md 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 - -<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html> - |
