# VyOS Installation and Image Management

> Install VyOS on physical hardware, VMs, and cloud platforms (Yandex Cloud, VK Cloud, AWS, Azure, GCP) with version management

Source: https://opennix.org/en/docs/vyos/first-steps/vyos-installation/


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:

- **Official release**: https://vyos.io/
- **Nightly builds**: https://vyos.net/get/nightly-builds/

### 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

```bash
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:
```bash
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:**
```bash
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:**
```yaml
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:
```bash
dd if=vyos-1.5.x.iso of=/dev/sdX bs=4M status=progress
sync
```

2. Boot from the USB drive
3. Run `install image`
4. 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:

- [Quick Start](/docs/vyos/first-steps/vyos-quick-start/) - basic NAT gateway configuration
- [Command-Line Interface](/docs/vyos/first-steps/vyos-cli/) - learning the CLI
- [Configuration Overview](/docs/vyos/first-steps/vyos-config-overview/) - understanding the configuration structure