--- lastproofread: '2026-04-13' --- (cloud-init)= # 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: ```yaml #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 {ref}`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: ```yaml #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). ```yaml #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: ```none 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: ```none $ 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](https://www.yamllint.com/) provide simple validation tools. 2. **Check the logs**: `cloud-init` writes logs to `/var/log/cloud-init.log`. Filter for VyOS-specific entries using: ```none 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): ```sh 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`. 4. Copy the resulting image to the Proxmox server: ```sh sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/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: ```sh cd /tmp/ ``` 2. Create the `user-data` file. Begin the file with `#cloud-config` and include VyOS configuration commands. ```none #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: ```none 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. ```sh 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`: ```sh mv /tmp/seed.iso /var/lib/vz/template/iso/ ``` On the Proxmox server: ```none ## 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]: [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