path: root/docs/automation/cloud-init.md

---
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]: <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