VyOS cloud-init

VyOS instances in cloud and virtualized environments are initialized using the industry-standard cloud-init. Through cloud-init, VyOS injects SSH keys, configures network settings, and applies custom configurations during the initial instance boot.

Configuration sources

VyOS cloud-init obtains configuration data from the following sources:

  • meta-data: Instance-specific details provided by the cloud platform or hypervisor. In some cloud environments, this data is available via an HTTP endpoint at http://169.254.169.254.

  • network configuration: Network settings such as IP addresses, routes, and DNS (only available on certain cloud and virtualization platforms).

  • user-data: User-supplied CLI configuration commands.

User-data

Major cloud providers support injecting user-data as plain text or base64 encoding text during initial instance boot. As user-data has a strict size limit of ~16384 bytes, long configuration command lists can be compressed using gzip.

The recommended method for configuring VyOS instances via user-data is to use the cloud-config syntax described below.

Cloud-config modules

By default, VyOS enables only two cloud-config modules:

  • write_files: Inserts user-provided files such as encryption keys, certificates, or config.boot into the filesystem during the initial instance boot. See [Cloud-init-write_files] for file syntax and file format requirements.

  • vyos_userdata: Executes user-provided CLI configuration commands during the initial instance boot.

The files to insert and the CLI commands to execute must be provided in a cloud-config YAML file.

Cloud-config file format

cloud-config files are written in YAML and must begin with the #cloud-config line. Only vyos_config_commands and write_files are supported as top-level keys. The use of these keys is described in the following two sections.

Vyos_config_commands key

Use the vyos_config_commands key to define configuration commands for initializing your VyOS instance. Commands must follow the set-style syntax and can include both set and delete statements.

Syntax requirements:

  • Place one command per line.

  • Enclose values in single quotes.

  • Avoid single quotes within commands or values.

Applying commands from cloud-config overrides both settings configured via meta-data and default VyOS settings. After commands are applied, cloud-init automatically performs commit and save.

The following is an example of a cloud-config file:

#cloud-config
vyos_config_commands:
  - set system host-name 'vyos-prod-ashburn'
  - set service ntp server 1.pool.ntp.org
  - set service ntp server 2.pool.ntp.org
  - delete interfaces ethernet eth1 address 'dhcp'
  - set interfaces ethernet eth1 address '192.0.2.247/24'
  - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1'

Instance defaults/fallbacks

If no external configuration data is provided, VyOS applies the following defaults:

  • SSH: port 22.

  • Credentials: vyos/vyos.

  • Networking: DHCP is enabled on the first Ethernet interface.

All defaults can be overridden via user-data configurations.

Write_files key

VyOS allows you to run custom scripts during the initial instance boot to execute operational, configuration, and standard Linux commands.

Use the write_files key to insert these scripts into the /opt/vyatta/etc/config/scripts/ directory.

Depending on when your commands need to run, use one of the following paths:

  • /opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script: Commands defined here are executed before the system configuration is applied.

  • /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script: Commands defined here are executed after the system configuration is applied.

In both cases, commands are executed with root privileges.

Note

Use the /opt/vyatta/etc/config/ path instead of /config/scripts/ as referenced in the Command scripting section. The /config/scripts/ directory is not mounted when the write_files module runs.

The following example shows how to use write_files to execute an operational command after the initial configuration is complete:

#cloud-config
write_files:
  - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
    owner: root:vyattacfg
    permissions: '0775'
    content: |
      #!/bin/vbash
      source /opt/vyatta/etc/functions/script-template
      filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log
      run show ip bgp summary >> $filename

You can combine standard Linux commands to fetch data and VyOS configuration commands (like set and commit) in the same script.

The following example sets the hostname based on the instance identifier obtained from the EC2 Instance Metadata Service (IMDS).

#cloud-config
write_files:
  - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
    owner: root:vyattacfg
    permissions: '0775'
    content: |
      #!/bin/vbash
      source /opt/vyatta/etc/functions/script-template
      hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id`
      configure
      set system host-name $hostname
      commit
      exit

NoCloud

Injecting configuration data is not limited to cloud platforms. The NoCloud data source allows you to inject user-data and meta-data on virtualization platforms such as VMware, Hyper-V, and KVM.

The simplest way to use the NoCloud data source is to create a seed.iso file and attach it to the virtual machine as a CD drive. The volume must be formatted as a VFAT or ISO 9660 file system with the label cidata or CIDATA.

Create text files named user-data and meta-data. On Linux-based systems, use the mkisofs utility to create the seed.iso file. The following syntax adds these files to the ISO 9660 file system:

mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data

Once generated, attach the seed.iso file to your virtual machine. The following example shows how to attach the file as a CD drive using KVM:

$ virt-install -n vyos_r1 \
   --ram 4096 \
   --vcpus 2 \
   --cdrom seed.iso \
   --os-type linux \
   --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

For more information on the NoCloud data source, visit the [NoCloud] page in the cloud-init documentation.

Troubleshooting

If your configuration does not apply as expected, follow these troubleshooting steps:

  1. Validate your YAML: Ensure your cloud-config file follows proper YAML syntax. Online resources such as YAML Lint provide simple validation tools.

  2. Check the logs: cloud-init writes logs to /var/log/cloud-init.log. Filter for VyOS-specific entries using:

sudo grep vyos /var/log/cloud-init.log

Cloud-init on Proxmox

Before you begin, review the cloud-init [network-config-docs] to understand how to import user and network configuration data.

Key considerations:

  • Define VyOS configuration commands in the user-data file.

  • Avoid including network configuration data in the user-data file.

  • If no network configuration data is provided, the DHCP client is enabled on the first interface. This happens at the OS level and is not reflected in the VyOS CLI.

The following example shows how to disable the DHCP client on eth0 to address this behavior.

In this example:

  • Proxmox IP address: 192.168.0.253/24.

  • Storage: The local volume is mounted at /var/lib/vz and contains all content types, including snippets.

The goal is to remove the default DHCP client from the first interface and apply a custom configuration during the initial instance boot using cloud-init.

Generate .qcow2 image

First, generate a VyOS .qcow2 image with cloud-init support from the [vyos-vm-images] repository:

  1. Clone the vyos-vm-images repository and comment out the download-iso role in qemu.yml.

  2. Download your preferred VyOS .iso file and save it as /tmp/vyos.iso.

  3. Generate the .qcow2 image (using a 10G disk size for this example):

sudo ansible-playbook qemu.yml -e disk_size=10 \
 -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.5.0 \
 -e cloud_init=true -e cloud_init_ds=NoCloud

This generates your new image at /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2.

  1. Copy the resulting image to the Proxmox server:

sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 [email protected]:/tmp/

Prepare cloud-init files

Create the following files on your Proxmox server to proceed with this setup:

  • user-data: Contains VyOS configuration commands.

  • network-config: Disables the DHCP client on the first interface.

  • meta-data: An empty file (required by cloud-init).

All files must be placed in the /tmp/ directory.

Follow these steps to create the required files:

  1. Navigate to the /tmp/ directory:

    cd /tmp/

  2. Create the user-data file. Begin the file with #cloud-config and include VyOS configuration commands.

    #cloud-config
vyos_config_commands:
  - set system host-name 'vyos-BRAS'
  - set service ntp server '1.pool.ntp.org'
  - set service ntp server '2.pool.ntp.org'
  - delete interfaces ethernet eth0 address 'dhcp'
  - set interfaces ethernet eth0 address '198.51.100.2/30'
  - set interfaces ethernet eth0 description 'WAN - ISP01'
  - set interfaces ethernet eth1 address '192.168.25.1/24'
  - set interfaces ethernet eth1 description 'Coming through VLAN 25'
  - set interfaces ethernet eth2 address '192.168.26.1/24'
  - set interfaces ethernet eth2 description 'Coming through VLAN 26'
  - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1'

  3. Create the network-config file. Include the following:

    version: 2
ethernets:
  eth0:
    dhcp4: false
    dhcp6: false

  4. Create the required empty meta-data file.

Create seed.iso

Once you have created the necessary files, generate the seed.iso image and mount it as a CD drive to the new VM.

mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \
user-data network-config

Note

Be careful while copying and pasting the above commands. Double quotes may need to be corrected.

Create the VM

Note that the following settings apply to this particular example and may require adjustment for other setups:

  • VM ID: 555.

  • VM and .iso file storage: The local volume (directory type, mounted at /var/lib/vz).

  • VM resources: Can be modified as needed.

The seed.iso file was previously created in the /tmp/ directory. Move it to /var/lib/vz/template/iso:

mv /tmp/seed.iso /var/lib/vz/template/iso/

On the Proxmox server:

## Create VM, import disk and define boot order
qm create 555 --name vyos-1.5.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0
qm importdisk 555 vyos-1.5.0-cloud-init-10G-qemu.qcow2 local
qm set 555 --virtio0 local:555/vm-555-disk-0.raw
qm set 555 --boot order=virtio0

## Import seed.iso for cloud init
qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso

## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26)
qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25
qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26

Power on and verify the VM

Power on the VM using the CLI or GUI. After it boots, verify the configuration.

References

  • Cloud-init [network-config-docs].

  • Proxmox [Cloud-init-Support]. [cloud-init-support]: https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init [cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files [network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html [nocloud]: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html [vyos-vm-images]: https://github.com/vyos/vyos-vm-images