KEI/VyOS_CloudInit/imageBuild.md

Image was built using Debian 12, kernel 6.1.0-50-cloud-amd64, Docker version 29.6.1, build 8900f1d 

Built date is 12/07/2026

# Install docker 

To install Docker, follow the installation tutorial available on the [official Docker website](https://docs.docker.com/engine/install/debian/)

# Prepare the VyOS builder container


First download the prerequisites and clone the repository

```bash
sudo apt update
sudo apt install git

git clone --branch rolling --single-branch \
    https://github.com/vyos/vyos-build.git

cd vyos-build
```

Then pull the docker image

```bash
sudo docker pull vyos/vyos-build:rolling
```

And then inside container edit the **data/build-flavors/proxmox-cloud.toml** file to include

```toml
image_format = "qcow2"

packages = [
    "cloud-init",
    "cloud-utils",
    "ifupdown",
    "qemu-guest-agent"
]

[boot_settings]
console_type = "ttyS"
console_num = "0"
console_speed = "115200"
```

Then add the Cloud-Init configuration

```bash
# Create the configuration directory
mkdir -p \
    data/live-build-config/includes.chroot/etc/cloud/cloud.cfg.d
    
# Select Proxmox-compatible data sources
cat > \
data/live-build-config/includes.chroot/etc/cloud/cloud.cfg.d/99-datasource.cfg \
<<'EOF'
datasource_list: [ NoCloud, ConfigDrive ]
EOF

#Disable generic Linux network configuration
cat > \
data/live-build-config/includes.chroot/etc/cloud/cloud.cfg.d/99-disable-network-config.cfg \
<<'EOF'
network:
  config: disabled
EOF
```

This prevents generic Cloud-Init from creating /etc/network/interfaces configuration that would conflict with VyOS configuration.


After that, add a live-build chroot hook 

```bash
cat > \
data/live-build-config/hooks/live/19-cloud-init-qemu.chroot \
<<'EOF'
#!/bin/sh

set -e

echo "I: Configuring Cloud-Init"

systemctl enable cloud-init.service

rm -f /etc/network/interfaces.d/50-cloud-init

echo "I: Configuring QEMU Guest Agent"

systemctl enable qemu-guest-agent.service

exit 0
EOF

chmod +x \
    data/live-build-config/hooks/live/19-cloud-init-qemu.chroot
```


Thereafter, start the docker build container 

```bash
sudo docker run --rm -it \
    --privileged \
    --sysctl net.ipv6.conf.lo.disable_ipv6=0 \
    -v "$PWD":/vyos \
    -w /vyos \
    vyos/vyos-build:rolling \
    bash
```

Then we come to building the qcow disk image. In this example flag **--disk-size 10** means that we are creating a 10 GB virtual disk.

```bash
sudo make clean

sudo ./build-vyos-image \
    --architecture amd64 \
    --build-by "yuru@shupogaki.org" \
    --disk-size 10 \
    proxmox-cloud
```


After the build completes, run the following command 

```bash
find build -maxdepth 1 -type f \
    \( -name '*.qcow2' -o -name 'manifest.json' \) \
    -ls
```

to verify that it resembles the following text

```
build/vyos-1.x-rolling-YYYYMMDDHHMM-proxmox-cloud-amd64.qcow2
```




# Errors


## Missing --allow-downgrades flag


If you get the following error when building the qcow2 virtual disk

```bash
E: Packages were downgraded and -y was used without --allow-downgrades.
E: An unexpected failure occurred, exiting...
```
Re-clone the repository and follow the commands and text below

Then it means that during bootstrap, Debian installed its current openssl and libssl3 packages. After the VyOS rolling repository was enabled, APT selected VyOS-provided versions that it classified as downgrades. 



To fix it, run the following command from the root of the cloned vyos-build repository and check the current line

```bash
grep -n -- '--apt-options' scripts/image-build/build-vyos-image
```

You shold see a result that looks simmilar to this 

```bash
vyos_bld@93f129e939ac:/vyos$ grep -n -- '--apt-options' scripts/image-build/build-vyos-image
655:                --apt-options "--yes" \
```

This means in file **scripts/image-build/build-vyos-image** on line 655 a **--yes --allow-downgrades** flag is missing. You can add it manually, or run the following command

```bash
sed -i \
  's/--apt-options "--yes"/--apt-options "--yes --allow-downgrades"/' \
  scripts/image-build/build-vyos-image
```


After that, apply the fix for the second error and start from the begining



## Missmatched shim package version

If you get the following error

```bash
The following packages have unmet dependencies:
 shim-helpers-amd64-signed : Depends: shim-unsigned (>= 16.1-2~deb12u1) but 16.0-1+vyos1 is to be installed
E: Unable to correct problems, you have held broken packages.
E: An unexpected failure occurred, exiting...
P: Begin unmounting filesystems...
P: Saving caches...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Traceback (most recent call last):
  File "/vyos/./build-vyos-image", line 810, in <module>
    build()
  File "/vyos/./build-vyos-image", line 721, in build
    cmd("lb build 2>&1")
  File "/vyos/scripts/image-build/utils.py", line 89, in cmd
    raise OSError(f"Command '{command}' failed")
OSError: Command 'lb build 2>&1' failed
```

First, re-clone the respository and run the following command

```bash
cat > \
data/live-build-config/archives/debian-shim.pref.chroot \
<<'EOF'
Package: shim-unsigned shim-signed shim-signed-common shim-helpers-amd64-signed
Pin: release o=Debian
Pin-Priority: 1001
EOF
```


<!--
Add the following file

```bash
vim data/live-build-config/archives/debian-shim.pref.chroot 
```

With the following contents

```bash
Package: shim-unsigned shim-signed shim-signed-common shim-helpers-amd64-signed
Pin: origin "deb.debian.org"
Pin-Priority: 1001
EOF
```

Or just run this command

```bash
cat > data/live-build-config/archives/debian-shim.pref.chroot <<'EOF'
Package: shim-unsigned shim-signed shim-signed-common shim-helpers-amd64-signed
Pin: origin "deb.debian.org"
Pin-Priority: 1001
EOF
```
-->

Then also apply the fix for the **--allow-downgrades** problem, and after that start from the beggining