Documentation
VyOS Documentation
Getting Started with VyOS
VyOS Installation and Image Management

VyOS Installation and Image Management

VyOS can be installed on a variety of platforms: physical hardware, virtual machines, and cloud environments.

System requirements

Minimum requirements

  • CPU: 1 CPU core (64-bit)
  • Memory: 512 MB RAM
  • Disk space: 2 GB

Recommended requirements

  • CPU: 2+ CPU cores
  • Memory: 2 GB RAM or more
  • Disk space: 10 GB or more

Prerequisites for virtual installations

Important: When installing on virtual machines, make sure that the MAC addresses of the network interfaces are not locally administered. Locally administered addresses are defined by setting the second least significant bit of the first octet to 1.

Example of a locally administered MAC address (not recommended):

02:00:00:00:00:01

Recommended MAC address format:

00:50:56:xx:xx:xx

Downloading the image

Download the VyOS ISO image:

Available versions

  • VyOS 1.5.x (Circinus) - Rolling release (current development)
  • VyOS 1.4.x (Sagitta) - LTS (Long Term Support)

Installation types

1. Live installation

The live image lets you run VyOS without installing it to disk. This is useful for:

  • Testing VyOS
  • Disaster recovery
  • Temporary use

After booting from the ISO, log in to the system:

  • Username: vyos
  • Password: vyos

2. Permanent installation

To install VyOS to disk, run the command:

vyos@vyos:~$ install image

The installation wizard will ask the following questions:

Would you like to continue? (Yes/No) [Yes]: Yes
Partition (Auto/Parted/Skip) [Auto]: Auto
Install the image on? [sda]: sda
Continue? (Yes/No) [No]: Yes
How big of a root partition should I create? (2000MB - 20000MB) [20000]:
What would you like to name this image? [1.5.x-latest]:
Copy config to new image? (Yes/No) [No]: No
Enter password for user 'vyos': ********
Retype password for user 'vyos': ********
Which drive should GRUB modify the boot partition on? [sda]: sda

Installation parameters:

  • Partition: Automatic disk partitioning
  • Install the image on: Target disk (usually sda)
  • Root partition size: Size of the root partition
  • Image name: Image name (for version management)
  • Copy config: Whether to copy the current configuration
  • Password: Password for the vyos user
  • GRUB: Bootloader installation

After installation, reboot the system:

vyos@vyos:~$ reboot

Installation in different environments

Virtual environments

Libvirt/KVM/QEMU

virt-install \
  --name vyos \
  --ram 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/vyos.qcow2,size=10 \
  --os-variant debian10 \
  --network bridge=virbr0 \
  --graphics vnc \
  --console pty,target_type=serial \
  --cdrom /path/to/vyos.iso

Proxmox VE

  1. Upload the ISO to Proxmox storage
  2. Create a new virtual machine:
    • OS Type: Linux (6.x - 2.6 Kernel)
    • Memory: minimum 512MB, recommended 2GB
    • Network: VirtIO (paravirtualization)
    • Disk: VirtIO SCSI, minimum 2GB
  3. Boot from the ISO and run install image

VMware ESXi

  1. Create a new virtual machine:
    • Guest OS: Other Linux (64-bit)
    • Memory: minimum 512MB
    • Network Adapter: VMXNET3
    • SCSI Controller: VMware Paravirtual
  2. Attach the VyOS ISO image
  3. Boot and run the installation

Cloud environments

Amazon AWS

VyOS is available in the AWS Marketplace:

  1. Find the VyOS AMI in the Marketplace
  2. Launch an EC2 instance
  3. Connect via SSH using your EC2 key

Initial configuration:

ssh -i your-key.pem vyos@<instance-ip>

Microsoft Azure

  1. Find VyOS in the Azure Marketplace
  2. Create a virtual machine
  3. Connect via SSH

Google Cloud Platform

  1. Find VyOS in the GCP Marketplace
  2. Create a Compute Engine instance
  3. Connect via SSH through the GCP console or the gcloud CLI

Yandex Cloud

VyOS is available in Yandex Cloud through the Marketplace. Deployment uses images optimized for the cloud environment.

Deploying from the Marketplace
  1. Go to the Yandex Cloud Marketplace
  2. Find VyOS (versions 1.4 LTS and 1.5 Current are available)
  3. Create a virtual machine from the image
  4. Specify your SSH key in the metadata when creating it
Important notes for Yandex Cloud

Automatic configuration on first boot:

  • The image is automatically configured on first boot via cloud-init
  • A user is created from the instance metadata (instead of the default vyos)
  • SSH keys are added automatically from the Yandex Cloud metadata
  • Password authentication is disabled after the SSH keys are set up
  • Cloud-init is disabled after first boot for security
  • Network configuration is fully managed by VyOS (cloud-init does not manage the network)

Accessing the instance:

ssh -l <your-username> <instance-ip>

Where <your-username> is the username from the Yandex Cloud metadata (usually the same as your console login).

Optimizations for Yandex Cloud:

  • qemu-guest-agent is enabled for hypervisor integration
  • VirtIO offloading is configured (GSO, GRO, TSO, SG)
  • The TCP stack is optimized (BBR congestion control)
  • The console is configured over the serial port (ttyS0) for access through the Yandex Cloud Console
  • The root partition is automatically expanded to the full disk size

Metadata service:

datasource_list: [ Ec2 ]
datasource:
  Ec2:
    metadata_urls: [ 'http://169.254.169.254' ]
    strict_id: false

Network configuration disabled in cloud-init:

network: {config: disabled}

This gives VyOS full control over the network configuration.

Physical hardware

Supported platforms

VyOS runs on a variety of x86_64 hardware:

  • Supermicro A2SDi (Atom C3000)
  • PC Engines APU4
  • Qotom Q355G4
  • Partaker i5
  • Acrosser AND-J190N1
  • Gowin GW-FN-1UR1-10G
  • Any x86_64 server with VGA/Serial console support

Installation process

  1. Write the ISO to a USB drive:
dd if=vyos-1.5.x.iso of=/dev/sdX bs=4M status=progress
sync
  1. Boot from the USB drive
  2. Run install image
  3. Remove the USB drive and reboot the system

PXE Boot

VyOS supports network booting via PXE:

  1. Set up a TFTP server
  2. Extract the kernel and initrd from the ISO
  3. Configure the PXE setup:
LABEL vyos
    MENU LABEL VyOS
    KERNEL vyos/vmlinuz
    APPEND initrd=vyos/initrd.img boot=live

Updating VyOS

Adding a new image

Download and install a new image:

vyos@vyos:~$ add system image https://example.com/vyos-1.5.x-latest.iso

Or from a local file:

vyos@vyos:~$ add system image /tmp/vyos-1.5.x-latest.iso

Viewing installed images

vyos@vyos:~$ show system image
The system currently has the following image(s) installed:

   1: 1.5.x-latest (default boot)
   2: 1.5.x-previous
   3: 1.4.x-stable

Selecting an image to boot

Setting the default image:

vyos@vyos:~$ set system image default-boot 1.5.x-latest

Removing old images

vyos@vyos:~$ delete system image 1.4.x-stable

System rollback

VyOS supports rolling back to previous image versions.

Rollback via GRUB

While the system is booting:

  1. Interrupt the automatic boot (press any key)
  2. Select the desired image from the list
  3. Boot from the selected image

Configuration rollback

After booting a previous image, you can restore the configuration:

vyos@vyos:~$ configure
vyos@vyos# rollback 1
vyos@vyos# commit
vyos@vyos# save

Secure Boot

VyOS supports Secure Boot starting from version 1.5.x.

Installing with Secure Boot

  1. Make sure Secure Boot is enabled in UEFI/BIOS
  2. Boot from the ISO (a signed image)
  3. Run the standard installation:
vyos@vyos:~$ install image

Updating the image with Secure Boot

When adding a new image, make sure it is signed:

vyos@vyos:~$ add system image https://example.com/vyos-1.5.x-signed.iso

Verifying Secure Boot

Check the Secure Boot status:

vyos@vyos:~$ show system boot secure-boot
Secure Boot: enabled

Troubleshooting Secure Boot

If the system does not boot with Secure Boot enabled:

  1. Verify that a signed image is being used
  2. Make sure the certificates are correctly installed in UEFI
  3. Try disabling Secure Boot temporarily for diagnostics

Backup and restore

Backing up the configuration

Copying the configuration to a remote server:

vyos@vyos:~$ save /tmp/config.boot
vyos@vyos:~$ scp /tmp/config.boot user@backup-server:/backups/

Restoring the configuration

vyos@vyos:~$ scp user@backup-server:/backups/config.boot /tmp/
vyos@vyos:~$ configure
vyos@vyos# load /tmp/config.boot
vyos@vyos# commit
vyos@vyos# save

Known issues

MAC address issues

When cloning virtual machines, make sure that the network interface MAC addresses are unique.

Boot issues

If the system does not boot after installation:

  1. Check the BIOS/UEFI settings
  2. Make sure GRUB is installed on the correct disk
  3. Try booting from the ISO and reinstalling GRUB

Secure Boot issues

If Secure Boot is not working:

  1. Make sure a signed image is being used
  2. Verify that the Platform Key (PK) is correctly installed
  3. Try resetting the UEFI settings to factory defaults

Next steps

After installing VyOS, continue with:

Reviewed by OpenNix LLC · Last updated on
VyOS Quick Start - Build a NAT Gateway in 10 MinutesVyOS CLI - Operational Mode and Configuration