basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    An Ubuntu template with cloud-init in Proxmox: a VM with a key and an address in a minute

    Turn the Ubuntu cloud image into a Proxmox template, and cloud-init sets the user, SSH key, address and hostname on a clone’s first boot. No installer needed: a new VM is qm clone, two lines of settings and qm start, and a minute later you log in with the key. Test servers for guides are made the same way.

    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

    1. 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: OK

      For Ubuntu 26.04 — the same with 26.04 in both URLs. The Debian 13 image is debian-13-genericcloud-amd64.qcow2 on cloud.debian.org; everything else is the same.

    2. 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.pub

      Several keys — one per line in the same file.

    3. 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=1
      Option What it does
      9000 the VM number; keep templates in their own range so they don’t mix with working VMs
      --cpu host the guest sees the host CPU in full: fastest, but live migration only to a node with the same CPU
      --net0 virtio,bridge=vmbr0 a VirtIO network card on the home bridge
      --scsihw virtio-scsi-single a 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 image
      discard=on space freed in the guest returns to the thin pool (Disk discard)
      --ide2 local-lvm:cloudinit the cloud-init disk Proxmox passes the settings on
      --serial0 socket --vga serial0 the console of cloud images goes to the serial port
      --agent enabled=1 Proxmox 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.

    4. 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 passwordless sudo; 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, --ciupgrade in 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 template VM 9000 becomes a template: it no longer starts, its disk is read-only, and its icon in the tree changes.

    5. 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 the local storage 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).

    6. 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) the hostname.
      • qm disk resize before 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 ciupgrade the updates too. It’s done when the console shows Cloud-init … finished.

    7. 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 them

      From 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 status and put yours into --scsi0 and --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 111 on 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 --sshkeys is empty, the key is the wrong one, or the user in --ciuser is different.
    Fix
    qm cloudinit dump 111 user — the output should have ssh_authorized_keys with the right key and the user’s name. Fix it with qm set and 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-networkd builds 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 before qm 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 --nameserver the 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

    1. qemu-guest-agent installs from vendor-data on the first boot of an Ubuntu 24.04 clone ↑