Files
proxmox-create-template/README.md
T
2026-11-02 23:45:31 +01:00

3.7 KiB

Proxmox Create Template

Script to create a Proxmox template VM using the newest Ubuntu or Debian Cloud Image, with a cloud-init drive.

What it does

  1. Looks up the newest release:
    • Ubuntu: from cloud-images.ubuntu.com (newest LTS by default)
    • Debian: current stable (from deb.debian.org), genericcloud image from cloud.debian.org
  2. Downloads the cloud image and verifies its checksum (SHA256 for Ubuntu, SHA512 for Debian).
  3. Optionally bakes qemu-guest-agent into the image with virt-customize (installs libguestfs-tools if missing).
  4. Creates the VM (virtio NIC, virtio-scsi-single, cpu host, guest agent enabled, serial console).
  5. Imports the image as scsi0 (discard, ssd, iothread) and resizes it to DISK_SIZE.
  6. Adds a cloud-init drive with user, SSH keys, optional password and DHCP networking.
  7. Converts the VM to a template.

Requirements

  • Run on the Proxmox host as root
  • curl
  • Internet access (for the image and, if needed, libguestfs-tools)

Usage

./create-template.sh

Override any setting via environment variables:

VMID=9001 STORAGE=local-zfs CHANNEL=latest ./create-template.sh

Debian template:

DISTRO=debian VMID=9002 ./create-template.sh

Then clone the template:

qm clone 9000 <newid> --name <name> --full && qm start <newid>

Configuration

Variable Default Description
DISTRO ubuntu ubuntu or debian
VMID 9000 ID of the template VM (must not exist yet)
STORAGE local-lvm Storage for the disk and cloud-init drive
BRIDGE vmbr0 Network bridge
CORES 2 CPU cores
MEMORY 2048 Memory in MiB
DISK_SIZE 20G Final root disk size (must be larger than the image, ~3.5G)
ARCH amd64 amd64 or arm64
CHANNEL lts Ubuntu only: lts = newest LTS, latest = newest release incl. interim. Debian always uses stable
CI_USER niklas Cloud-init default user
CI_PASSWORD (empty) Optional password; leave empty to rely on SSH keys only
SSH_KEY_FILE $HOME/.ssh/authorized_keys Public keys injected via cloud-init
INSTALL_QGA 1 Bake qemu-guest-agent into the image (0 to skip)
SNIPPET_STORAGE local Storage for the cloud-init snippet used by the QGA fallback

QEMU guest agent fallback

If virt-customize can't install qemu-guest-agent (usually no network/DNS inside the libguestfs appliance), the script falls back to a cloud-init vendor snippet (qga-vendor.yaml) on SNIPPET_STORAGE. Clones then install the agent on first boot, which requires internet access on the clone. The vendor data only adds to Proxmox's generated user data, so ciuser/sshkeys still apply.

The snippet storage must allow the snippets content type. Enable it by adding snippets to the existing content list, e.g.:

pvesm set local --content iso,vztmpl,backup,snippets

Otherwise, just run apt install qemu-guest-agent inside each clone.

Notes

  • If neither an SSH key file nor a password is set, you can't log in until you set one in the VM's Cloud-Init tab.
  • The script aborts if the VMID already exists or the storage doesn't exist.
  • Downloads happen in a temp directory that is removed on exit.