What you’ll end up with
template 9000 tpl-ubuntu-2404: Ubuntu 24.04 cloud image, cloud-init, guest agent
VM 111 web1: a template clone, 30 GB disk, address 10.0.0.11, example-user logs in by key
time from clone to SSH login — about a minute; a few minutes if cloud-init installs updates
A cloud image is an already installed Ubuntu without a user or password, about 600 MB. Everything the installer
does — user, key, network, hostname — cloud-init does on the first boot. Proxmox hands it the settings on a small
virtual CD-ROM (ide2), and cloud-init in the guest reads it. VPS providers use the same mechanism (cloud-init).
Commands run in the node’s Shell as root. The network is the vmbr0 bridge and the home 10.0.0.0/24 with router
10.0.0.1 (Proxmox networking); the disk storage is local-lvm, or local-zfs on ZFS.
Steps
Download the cloud image and check the sum
mkdir -p /root/images && cd /root/images wget https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img wget https://cloud-images.ubuntu.com/releases/24.04/release/SHA256SUMS sha256sum -c --ignore-missing SHA256SUMS # …cloudimg-amd64.img: OKFor Ubuntu 26.04 — the same with
26.04in both URLs. The Debian 13 image isdebian-13-genericcloud-amd64.qcow2on cloud.debian.org; everything else is the same.Put down the key the VMs will accept
The public key from the computer you’ll log in from (SSH keys) goes into a file on the host:
echo 'ssh-ed25519 AAAA…the whole line… example-user@laptop' > /root/example-user.pubSeveral keys — one per line in the same file.
Create a VM from the image
qm create 9000 --name tpl-ubuntu-2404 --ostype l26 \ --cores 2 --cpu host --memory 2048 \ --net0 virtio,bridge=vmbr0 \ --scsihw virtio-scsi-single \ --scsi0 local-lvm:0,import-from=/root/images/ubuntu-24.04-server-cloudimg-amd64.img,discard=on \ --ide2 local-lvm:cloudinit \ --boot order=scsi0 \ --serial0 socket --vga serial0 \ --agent enabled=1Option What it does 9000the VM number; keep templates in their own range so they don’t mix with working VMs --cpu hostthe guest sees the host CPU in full: fastest, but live migration only to a node with the same CPU --net0 virtio,bridge=vmbr0a VirtIO network card on the home bridge --scsihw virtio-scsi-singlea VirtIO SCSI controller per disk — so each disk can have its own I/O thread --scsi0 …,import-from=…0— no size given: the disk is created from the image, the size of the imagediscard=onspace freed in the guest returns to the thin pool (Disk discard) --ide2 local-lvm:cloudinitthe cloud-init disk Proxmox passes the settings on --serial0 socket --vga serial0the console of cloud images goes to the serial port --agent enabled=1Proxmox will talk to the guest agent: shutdown, addresses, disk freeze during backup (Guest agent) The same, line by line, in the VM config — Proxmox VM config.
Set up cloud-init and turn it into a template
qm set 9000 --ciuser example-user --sshkeys /root/example-user.pub \ --nameserver "1.1.1.1 9.9.9.9" --ipconfig0 ip=dhcp qm template 9000--ciuser— a user with passwordlesssudo; no password is set, login is key only.--nameserver— without it the VM takes DNS from the host’s settings.--ipconfig0 ip=dhcp— by default an address from the router; a clone gets its own.- On the first boot cloud-init updates packages: the Upgrade packages option,
--ciupgradein the console. For speed it’s turned off (--ciupgrade 0), and then you update yourself after logging in.
Don’t start the VM before
qm template. After the first boot the image gets its own/etc/machine-id, and every clone gets a copy of it: their DHCP identifiers and addresses will clash.After
qm templateVM 9000 becomes a template: it no longer starts, its disk is read-only, and its icon in the tree changes.Add the guest agent to the template
The Ubuntu cloud image has no
qemu-guest-agent. To avoid installing it by hand in every VM, give cloud-init one more file — vendor-data. First allow thelocalstorage to hold snippets: Datacenter › Storage ›local› Edit › Content — add Snippets. Then:cat > /var/lib/vz/snippets/vendor-agent.yaml <<'EOF' #cloud-config packages: - qemu-guest-agent runcmd: - systemctl start qemu-guest-agent EOF qm set 9000 --cicustom "vendor=local:snippets/vendor-agent.yaml"Proxmox still writes the user, key and network itself:
vendor=replaces only the vendor-data and leaves the other cloud-init parts alone. The agent installs on each clone’s first boot1; if not, install it by hand,sudo apt install qemu-guest-agent(Guest agent).Clone a VM
qm clone 9000 111 --name web1 --full qm set 111 --ipconfig0 ip=10.0.0.11/24,gw=10.0.0.1 qm disk resize 111 scsi0 30G qm set 111 --onboot 1 qm start 111 qm terminal 111 # shows the boot; exit with Ctrl+O--full— a full clone, an independent copy of the disk. Without it the clone is linked: smaller and created instantly, but it rests on the template’s disk — the template then can’t be deleted while any clone lives.- cloud-init makes the VM name (
--name) thehostname. qm disk resizebefore the first boot: cloud-init grows the partition to 30 GB itself.--onboot 1— the VM starts after the host reboots.
The first boot takes longer than later ones: cloud-init creates the user, installs the agent, and with
ciupgradethe updates too. It’s done when the console showsCloud-init … finished.Log in
ssh [email protected] cloud-init status # status: done hostname # web1 df -h / # /dev/sda1 29G …From the host — check that the agent answers:
qm guest cmd 111 ping # empty output and exit code 0 — the agent is there qm guest cmd 111 network-get-interfaces # the VM's addresses as the agent sees themFrom here the VM is a regular Ubuntu server: first login and hardening — First login to a server, Docker — Docker on Ubuntu.
If it doesn’t work
qm create fails: storage 'local-lvm' does not exist
- Cause
- The host was installed on ZFS: the disk storage is called
local-zfs. - Fix
- Look up the names in
pvesm statusand put yours into--scsi0and--ide2. Or set it once,STORAGE=local-zfs, and then write$STORAGE:0,….
The VM console in noVNC is empty or says starting serial terminal
- Cause
- The VM has
--vga serial0: there’s no screen, the console goes to the serial port, and Ubuntu cloud images print the boot there. - Fix
- Console › xterm.js in the UI or
qm terminal 111on the host; exit with Ctrl+O. If the boot isn’t visible, press Enter — a login prompt appears.
ssh [email protected] — Permission denied (publickey)
- Cause
- The key didn’t make it into cloud-init: the file in
--sshkeysis empty, the key is the wrong one, or the user in--ciuseris different. - Fix
qm cloudinit dump 111 user— the output should havessh_authorized_keyswith the right key and the user’sname. Fix it withqm setand recreate the VM from the template: cloud-init applies the user only on the first boot.
Two clones get the same address from the router
- Cause
- The template was booted before it became a template: it kept its
/etc/machine-id, and the clones share it.systemd-networkdbuilds the DHCP identifier from it, and the router sees one device. - Fix
- In each clone:
sudo truncate -s 0 /etc/machine-id && sudo rm -f /var/lib/dbus/machine-id && sudo reboot. From now on don’t start the template beforeqm template.
The disk was enlarged, but df -h / shows the old size
- Cause
- cloud-init grows the partition only on the first boot. The disk was enlarged after it.
- Fix
- In the VM:
sudo growpart /dev/sda 1 && sudo resize2fs /dev/sda1.
The VM pings 1.1.1.1, but names don’t resolve
- Cause
- Without
--nameserverthe VM takes DNS from the host’s settings. If the host points at a DNS server unreachable from the guest network, names in the guest don’t resolve. - Fix
qm set 111 --nameserver "1.1.1.1 9.9.9.9"and reboot the VM — cloud-init rewrites the network.
How to check
A second clone — the same command with a different number, name and address:
qm clone 9000 112 --name web2 --full && qm set 112 --ipconfig0 ip=10.0.0.12/24,gw=10.0.0.1 && qm start 112
A minute later ssh [email protected] logs in with the key, hostname prints web2, and in the Proxmox tree
VM 112’s Summary tab shows its addresses — passed on by the guest agent. Both VMs answer on their addresses, and
their cat /etc/machine-id differ.
Not verified yet
- qemu-guest-agent installs from vendor-data on the first boot of an Ubuntu 24.04 clone ↑