Skip to main content

Preparing VM templates

Every desktop pool clones from a template. Planeon never builds a guest operating system from scratch — it clones an existing Proxmox VE template VM, then customizes each clone (hostname, optionally a domain join, health checks) before handing it to a user. The quality of that template determines whether provisioning goes smoothly: a template missing the guest agent or VirtIO drivers is the most common cause of desktops that never reach Ready.

This guide walks through preparing a template for either Windows or Linux, and how to confirm it's ready before you point a pool at it. If you haven't created your first pool yet, see the quickstart.

General rules, any OS​

These apply regardless of guest operating system:

  • Install the QEMU guest agent inside the guest. Planeon relies on it for OS detection, hostname configuration, and health checks during provisioning — a clone without it never reaches Ready.
  • Enable the QEMU Guest Agent option on the VM itself, in the VM's Options tab in the Proxmox VE UI. Installing the agent inside the guest isn't enough — Proxmox VE also needs to know to talk to it.
  • Use VirtIO devices for storage and network (VirtIO SCSI controller, VirtIO network adapter) rather than emulated hardware, for both performance and driver consistency across your fleet of clones.
  • Clean up before converting to a template — remove installer leftovers and temporary files, and complete the OS-specific steps below — so every clone starts from the same known-good state.

Windows 10, Windows 11, and Windows Server​

  1. Attach the VirtIO drivers ISO during installation. Windows doesn't include VirtIO drivers out of the box, so mount the virtio-win driver ISO alongside the installation media and load the VirtIO SCSI and network drivers when Setup asks for them — this lets Windows see the VirtIO disk and network adapter from the start.

  2. Install the QEMU guest agent. The virtio-win ISO includes a guest-agent folder with a qemu-ga MSI installer; run it inside the guest and confirm the QEMU Guest Agent service is running.

  3. Enable Remote Desktop and allow it through the firewall. Turn on Remote Desktop in Windows Settings and confirm the Remote Desktop firewall rule is enabled. Planeon's default health check for Windows desktops requires the Remote Desktop service to be running, and RDP is how most users will actually reach the desktop.

  4. Apply Windows updates before templating, so every clone starts patched rather than needing updates on first boot.

  5. Generalize the image with Sysprep. From an elevated command prompt:

    %WINDIR%\System32\Sysprep\sysprep.exe /generalize /oobe /shutdown

    This strips machine-specific state (SID, drivers cache) and shuts the VM down at the end of the out-of-box experience, so every clone gets a clean, unique identity on first boot. Planeon's provisioning already waits out this first-boot setup on cloned Windows VMs before marking them ready, so don't skip Sysprep to save time — an ungeneralized image causes SID and identity conflicts across clones instead.

  6. Convert the VM to a template in Proxmox VE. Once the VM has shut itself down after Sysprep, right-click it in the Proxmox VE UI and select Convert to Template.

Linux​

  1. Install and enable the QEMU guest agent, using your distribution's package manager, for example:

    sudo apt-get install -y qemu-guest-agent
    sudo systemctl enable --now qemu-guest-agent

  2. Install and enable xrdp so the desktop is reachable over RDP the same way Windows desktops are:

    sudo apt-get install -y xrdp
    sudo systemctl enable --now xrdp

    A desktop environment needs to be installed for xrdp to present a session — install one if your base image doesn't already have one.

  3. Cloud-init is optional. If you already provision Linux VMs with a Cloud-Init drive for networking or user setup, you can keep using it — Planeon's clone-and-customize path doesn't require it, but doesn't conflict with it either.

  4. Clean up machine identity before templating, so every clone doesn't inherit the same identity as the template:

    sudo truncate -s 0 /etc/machine-id
    sudo rm -f /etc/ssh/ssh_host_*

    Regenerate the SSH host keys on first boot (most distributions do this automatically when the keys are missing and the SSH service starts; if yours doesn't, reconfigure the openssh-server package instead).

  5. Shut the VM down, then convert it to a template in Proxmox VE — right-click it in the Proxmox VE UI and select Convert to Template.

Verify the template is ready​

Two checks before you point a pool at the template:

  1. The guest agent responds. While the VM is still running as a normal VM (before you convert it), open it in the Proxmox VE UI and check the Summary tab — once the agent is installed, enabled, and running, an IP address appears there. No IP means the agent isn't answering yet; revisit the guest-agent steps above before continuing.
  2. Planeon's inventory shows it as eligible. After you've converted the VM to a template in Proxmox VE, open Templates → Register Existing in the Planeon web console and check the PVE template VM picker — only VMs Proxmox VE itself marks as templates appear there. If yours shows up, it's eligible to register and use in a pool.