Creating a new Debian virtual machine from scratch every time can be repetitive, especially in a homelab environment. A reusable Cloud-Init template makes the process much faster by giving you a lightweight base VM that can be cloned and customized in just a few steps.
In this tutorial, we will build a Debian 13 Cloud-Init template on Proxmox VE 9.2 using the official Debian genericcloud image, local-zfs storage, VirtIO networking, and VirtIO SCSI. The result is a small and practical template suitable for general-purpose Linux servers, Docker hosts, application servers, and other homelab workloads.
Environment
:::bash
Proxmox VE : 9.2
CPU : Intel Core i3-9100T
CPU Type : host
Network Bridge : vmbr0
Import Storage : local
Import Path : /var/lib/vz/import
VM Storage : local-zfs
ZFS Pool : rpool/data
Template VMID : 9000
:::
Default Cloud-Init configuration:
:::bash
Username : debian
Password : debian
IPv4 : DHCP
:::
1. Download Debian 13 Cloud Image
Download the official Debian 13 genericcloud image into the Proxmox import storage:
:::bash
mkdir -p /var/lib/vz/import
:::
:::bash
wget -O /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2 https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2
:::
Verify:
:::bash
ls -lh /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2
:::
The source image is stored on:
:::bash
Storage : local
Path : /var/lib/vz/import
:::
2. Create the Base VM
Create VM 9000:
:::bash
qm create 9000 --name debian-13-cloudinit --ostype l26 --memory 1024 --cores 1 --cpu host --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0
:::
This creates a lightweight base configuration:
| Setting |
Value |
| CPU |
1 Core |
| CPU Type |
host |
| RAM |
1024 MB |
| Network |
VirtIO |
| Bridge |
vmbr0 |
| SCSI Controller |
VirtIO SCSI Single |
CPU and RAM can be increased after cloning according to the workload.
3. Import and Attach the Debian Disk
Import the Debian QCOW2 image into local-zfs:
:::bash
qm disk import 9000 /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2 local-zfs
:::
Verify the imported disk:
:::bash
qm config 9000 | grep unused
:::
On a clean VMID 9000, the result should be:
:::bash
unused0: local-zfs:vm-9000-disk-0
:::
Attach it as the primary SCSI disk and set the boot order:
:::bash
qm set 9000 --scsi0 local-zfs:vm-9000-disk-0,discard=on,iothread=1 --boot order=scsi0
:::
Increase the base disk to 16 GB:
:::bash
qm resize 9000 scsi0 16G
:::
Because local-zfs is sparse, a 16 GB virtual disk does not immediately consume 16 GB of physical storage.
4. Configure Cloud-Init
Add the Cloud-Init drive using SCSI:
:::bash
qm set 9000 --scsi1 local-zfs:cloudinit
:::
Configure the standard VGA console and keep a serial console available as a fallback:
:::bash
qm set 9000 --vga std --serial0 socket
:::
The standard Proxmox noVNC console remains the primary console. The serial console is available only as a fallback and does not replace VGA.
Configure the default Cloud-Init user, password, and DHCP:
:::bash
qm set 9000 --ciuser debian --cipassword debian --ipconfig0 ip=dhcp
:::
Default credentials:
:::bash
Username : debian
Password : debian
:::
The password is useful for console access in a homelab.
For SSH access, SSH public-key authentication is still recommended.
5. Install QEMU Guest Agent
Before converting the VM into a template, install qemu-guest-agent for better integration between Proxmox and the Debian guest.
Enable QEMU Guest Agent in the Proxmox VM configuration:
:::bash
qm set 9000 --agent enabled=1
:::
Start the VM:
:::bash
qm start 9000
:::
Open VM 9000 > Console and use the standard noVNC console.
Log in using:
:::bash
Username : debian
Password : debian
:::
Inside the Debian VM, install QEMU Guest Agent:
:::bash
sudo apt update
sudo apt install -y qemu-guest-agent
sudo systemctl restart qemu-guest-agent
:::
Verify the QEMU Guest Agent:
:::bash
systemctl is-active qemu-guest-agent
:::
Expected result:
:::bash
active
:::
Clean the downloaded APT package cache:
:::bash
sudo apt clean
:::
Because the base VM has now been booted, reset the Cloud-Init state and machine ID before using it as a reusable golden image:
:::bash
sudo cloud-init clean --logs --machine-id
:::
Shut down the VM:
:::bash
sudo poweroff
:::
Wait until the VM status in Proxmox shows Stopped.
6. Verify and Convert to Template
Check the complete configuration:
:::bash
qm config 9000
:::
The important settings should look similar to:
:::bash
root@pve:~# qm config 9000
agent: enabled=1
boot: order=scsi0
cipassword: **********
ciuser: debian
cores: 1
cpu: host
ipconfig0: ip=dhcp
memory: 1024
meta: creation-qemu=11.0.0,ctime=1787587632
name: debian-13-cloudinit
net0: virtio=BC:24:11:6A:6C:E7,bridge=vmbr0
ostype: l26
scsi0: local-zfs:vm-9000-disk-0,discard=on,iothread=1,size=16G
scsi1: local-zfs:vm-9000-cloudinit,media=cdrom
scsihw: virtio-scsi-single
serial0: socket
smbios1: uuid=52c24c2e-4874-4ea8-836b-9a1336d8ae87
vga: std
vmgenid: 3f2eb19d-0129-438e-86e3-53c805033057
root@pve:~#
:::
Verify that the VM is stopped:
:::bash
qm status 9000
:::
Expected result:
:::bash
status: stopped
:::
Convert VM 9000 into a template:
:::bash
qm template 9000
:::
The lightweight Debian 13 Cloud-Init template is now ready.
Deploy a New Debian VM
In the Proxmox GUI:
debian-13-cloudinit > Right Click > Clone
For a normal standalone VM use:
:::bash
Mode : Full Clone
Storage : local-zfs
:::
Before the first boot, you can modify the Cloud-Init settings if necessary:
VM > Cloud-Init
Default configuration inherited from the template:
:::bash
User : debian
Password : debian
IPv4 : DHCP
:::
CPU, RAM, disk size, hostname, and network settings can also be adjusted according to the VM workload.
Then start the VM.
Cloud-Init will configure the instance automatically during its first boot.
QEMU Guest Agent is already installed and enabled in the template, so it does not need to be installed again on each cloned VM.
Verify QEMU Guest Agent inside the cloned VM if required:
:::bash
systemctl is-active qemu-guest-agent
:::
Expected result:
:::bash
active
:::
Remove the Source Image (Optional)
The original QCOW2 file is no longer required by the template after it has been imported into local-zfs.
However, keeping the image is useful if you want to rebuild the template later without downloading Debian again.
If you want to remove it:
:::bash
rm /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2
:::
Final Lightweight Configuration
| Component |
Configuration |
| OS |
Debian 13 Trixie |
| Image |
genericcloud |
| Template VMID |
9000 |
| CPU |
1 Core |
| CPU Type |
host |
| RAM |
1024 MB |
| Disk |
16 GB |
| VM Storage |
local-zfs |
| ZFS Pool |
rpool/data |
| System Disk |
SCSI0 |
| Cloud-Init |
SCSI1 |
| Controller |
VirtIO SCSI Single |
| IO Thread |
Enabled |
| Discard/TRIM |
Enabled |
| QEMU Guest Agent |
Installed / Enabled |
| Display |
Standard VGA / noVNC |
| Serial Console |
Available as fallback |
| Network |
VirtIO |
| Bridge |
vmbr0 |
| IPv4 |
DHCP |
| Default User |
debian |
| Default Password |
debian |
| Desktop Environment |
None |
This provides a small and reusable Debian 13 base suitable for homelab servers, Docker hosts, application servers, and other lightweight Linux workloads.
Code Summary
:::code
# Lightweight Proxmox Debian 13 Cloud-Init Template - Quick Command Summary
# Environment:
# PVE 9.2
# VMID 9000
# CPU type: host
# Bridge: vmbr0
# Import storage: local -> /var/lib/vz/import
# VM storage: local-zfs -> rpool/data
# Default user/password: debian / debian
# Network: DHCP
# Disk: 16 GB
# ============================================================
# 1. Download Debian 13 Generic Cloud Image
# ============================================================
# Create import directory if it does not exist
mkdir -p /var/lib/vz/import
# Download official Debian 13 genericcloud image
wget -O /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2 https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2
# Verify image
ls -lh /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2
# ============================================================
# 2. Create Base VM
# ============================================================
# Create lightweight Debian VM
qm create 9000 --name debian-13-cloudinit --ostype l26 --memory 1024 --cores 1 --cpu host --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0
# ============================================================
# 3. Import and Attach Debian Disk
# ============================================================
# Import QCOW2 image to local-zfs
qm disk import 9000 /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2 local-zfs
# Check imported disk name
qm config 9000 | grep unused
# Expected on a clean VMID:
# unused0: local-zfs:vm-9000-disk-0
# Attach imported disk as SCSI0 and enable discard + IO thread
qm set 9000 --scsi0 local-zfs:vm-9000-disk-0,discard=on,iothread=1 --boot order=scsi0
# Resize system disk to 16 GB
qm resize 9000 scsi0 16G
# ============================================================
# 4. Configure Cloud-Init
# ============================================================
# Add Cloud-Init drive
qm set 9000 --scsi1 local-zfs:cloudinit
# Keep standard VGA/noVNC as primary console
# serial0 remains available as fallback
qm set 9000 --vga std --serial0 socket
# Configure default user, password, and DHCP
qm set 9000 --ciuser debian --cipassword debian --ipconfig0 ip=dhcp
# ============================================================
# 5. Enable and Install QEMU Guest Agent
# ============================================================
# Run on the Proxmox host
qm set 9000 --agent enabled=1
qm start 9000
# ------------------------------------------------------------
# Run the following commands INSIDE the Debian VM
# Login from Proxmox noVNC Console:
# Username: debian
# Password: debian
# ------------------------------------------------------------
# Update repositories
sudo apt update
# Install QEMU Guest Agent
sudo apt install -y qemu-guest-agent
# Restart guest agent
sudo systemctl restart qemu-guest-agent
# Verify guest agent
systemctl is-active qemu-guest-agent
# Expected:
# active
# ============================================================
# 6. OPTIONAL - Enable SSH Password Login
# ============================================================
# Debian genericcloud normally expects SSH public-key authentication.
# Use this only if you want SSH login using debian/debian.
sudo mkdir -p /etc/ssh/sshd_config.d
echo 'PasswordAuthentication yes' | sudo tee /etc/ssh/sshd_config.d/99-password-auth.conf
sudo systemctl restart ssh
# Verify effective SSH setting
sudo sshd -T | grep passwordauthentication
# Expected:
# passwordauthentication yes
# ============================================================
# 7. Prepare Golden Image
# ============================================================
# Run INSIDE the Debian VM
# Clean downloaded APT package cache
sudo apt clean
# Reset Cloud-Init state and machine ID
sudo cloud-init clean --logs --machine-id
# Shut down VM
sudo poweroff
# ============================================================
# 8. Verify and Convert to Template
# ============================================================
# Run on the Proxmox host after VM is stopped
# Verify VM status
qm status 9000
# Expected:
# status: stopped
# Review final configuration
qm config 9000
# Convert VM to template
qm template 9000
# ============================================================
# 9. Deploy
# ============================================================
# Proxmox GUI:
# debian-13-cloudinit -> Right Click -> Clone
#
# Recommended:
# Mode : Full Clone
# Storage : local-zfs
#
# Cloud-Init defaults:
# User : debian
# Password : debian
# IPv4 : DHCP
# ============================================================
# 10. Optional - Remove Downloaded Source Image
# ============================================================
# Skip this if you want to keep the image for future rebuilds.
# rm /var/lib/vz/import/debian-13-genericcloud-amd64.qcow2
# ============================================================
# Cleanup / Restart From Scratch
# ============================================================
# This removes VM/template 9000 and its VM disks.
# The downloaded Debian QCOW2 image is NOT removed.
VMID=9000
IMAGE="/var/lib/vz/import/debian-13-genericcloud-amd64.qcow2"
if qm status "$VMID" >/dev/null 2>&1; then
STATUS=$(qm status "$VMID" | awk '{print $2}')
if [ "$STATUS" = "running" ]; then
qm stop "$VMID"
fi
qm destroy "$VMID" --purge 1 --destroy-unreferenced-disks 1
fi
# Remove leftover ZFS volumes for VMID 9000, if any
zfs list -H -t volume -o name -r rpool/data 2>/dev/null | grep "/vm-$VMID-" | while read -r VOL; do
[ -n "$VOL" ] && zfs destroy "$VOL"
done
# Verify VMID 9000 is gone
qm list
# Verify no leftover ZFS volume
zfs list -H -t volume -o name -r rpool/data 2>/dev/null | grep "/vm-$VMID-" || echo "No VMID $VMID ZFS volumes"
# Verify Debian source image is still kept
ls -lh "$IMAGE"
:::
:::toc enable
Post a Comment for "Build a Lightweight Debian 13 Cloud-Init Template on Proxmox VE 9.2"
Post a Comment