Proxmox Debian Cloud-Init Scripts

CORESTREAM helper scripts for building and cloning Debian Cloud-Init templates on Proxmox.

Fixed install location

All new Proxmox hosts should use the same local path:

/opt/corestream/proxmox-debian-cloudinit

The installer also creates command symlinks:

/usr/local/sbin/build-debian-template
/usr/local/sbin/clone-vm

One-liner install on a new Proxmox host

curl -fsSL https://git.corestream.ch/corestream/proxmox-debian-cloudinit-scripts/~raw/master/install-on-proxmox.sh | bash

If you want to override the directory:

curl -fsSL https://git.corestream.ch/corestream/proxmox-debian-cloudinit-scripts/~raw/master/install-on-proxmox.sh | INSTALL_DIR=/opt/corestream/proxmox-debian-cloudinit bash

Important: the OneDev project must allow anonymous Code Reader access for raw-file downloads. If raw access is private, the one-liner returns 401 Not authorized.

Scripts

build-debian-template.sh — builds a Debian 13 Cloud-Init template from qcow2 on Proxmox.
clone-vm.sh — full-clones a VM from the template, sets IP config, and starts it.
install-on-proxmox.sh — installs the scripts to the fixed path and creates symlinks.

Quick start on Proxmox

Install scripts:

curl -fsSL https://git.corestream.ch/corestream/proxmox-debian-cloudinit-scripts/~raw/master/install-on-proxmox.sh | bash

Install prerequisites, prepare the Debian image, and verify the admin SSH key:

apt update
apt install -y libguestfs-tools wget curl
pvesm status --enabled
mkdir -p /mnt/pve/<STORE>/import
cd /mnt/pve/<STORE>/import
wget -O debian-13-generic-amd64.qcow2 https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2
wget -O SHA512SUMS https://cloud.debian.org/images/cloud/trixie/latest/SHA512SUMS
sha512sum -c --ignore-missing SHA512SUMS
test -s /root/.ssh/id_csgadmin.pub

The default admin key path is /root/.ssh/id_csgadmin.pub. If the intended admin key is already in another file, pass it explicitly with --user-key. For example, using all keys currently authorized for Proxmox root:

build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud --user-key /root/.ssh/authorized_keys

Warning: that example imports every key listed in root's authorized_keys. Prefer a dedicated public-key file when only one admin key should enter the VM.

Build the template. The NFS storage is used only as the qcow2 source. VM disks, EFI and Cloud-Init are placed on a local storage supporting Proxmox content type images. If several local targets are available, the script asks which one to use. Override explicitly with --target-store <STORE>.

The build uses a temporary local working copy, so the pristine qcow2 source on NFS is no longer modified. It bakes in qemu-guest-agent, SSH hardening, NoCloud datasource, and disables IPv6 via sysctl plus kernel parameter ipv6.disable=1:

build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud

Verify the template:

qm config 9000 | grep -E 'scsi1|cloudinit|ciuser|boot'

Create a test clone with the desired final disk size:

clone-vm 9000 901 test-debian dhcp --disk-size 32G

Static IPv4 example:

clone-vm 9000 121 app-staging 10.10.10.121/24 10.10.10.1 --disk-size 64G

The helper resizes scsi0 before first boot. Debian Cloud-Init/growpart then expands the guest partition and filesystem automatically. Disk shrinking is not supported; the requested size must be at least as large as the template disk.

Add one or more extra NICs before first boot:

clone-vm 9000 130 dualnic 10.10.10.130/24 10.10.10.1 --add-nic vmbr1 dhcp
clone-vm 9000 131 dualnic-static 10.10.10.131/24 10.10.10.1 --add-nic vmbr1 192.168.50.10/24

--add-nic BRIDGE IP is repeatable. Additional NICs intentionally have no second default gateway. The helper creates net1, net2, etc., sets matching Cloud-Init ipconfigN entries and regenerates the seed before starting.

The Debian 13 generic image uses Netplan as the configuration layer, normally rendered by systemd-networkd; DNS is handled by systemd-resolved. Verify in the guest with systemctl is-active systemd-networkd, systemctl is-active systemd-resolved, networkctl, and ls -l /etc/netplan/.

Verify the clone from inside the guest and from Proxmox:

cloud-init status --long
dpkg-query -W qemu-guest-agent
systemctl is-active qemu-guest-agent
sysctl net.ipv6.conf.all.disable_ipv6
cat /proc/cmdline
ip -6 addr

qm agent 901 ping

Expected: Cloud-Init is done, Guest Agent is active, the sysctl value is 1, /proc/cmdline contains ipv6.disable=1, and ip -6 addr shows no IPv6 addresses.

Important: never boot the template itself. Boot only clones.