Skip to content

Proxmox Template Installations

For Proxmox VPS, two options are available for reinstallations:

This page describes installations via OS templates. Cloning a prepared template is significantly faster than a PXE deployment.

OS Template Plans

OS template plans define which templates are available for VPS installations and how each template behaves. These plans are assigned to VPS plans. When a VPS is provisioned, the assigned template plan ID is stored in the Proxmox connection details. This allows specific templates to be offered only to specific VPS plans or virtual servers. The assigned plan can later be changed in the server's Proxmox connection settings.

Template-based installations support first boot scripts, post-install callbacks, and can be linked to PXE profiles for advanced workflows.

To create or manage OS template plans, open "Virtualization" → "VPS Plans", edit a VPS plan, and use the "OS Template Plan" option to assign or create plans.

Display Name

The OS name shown on the reinstallation page.

Recommended format: OS name version (for example: Ubuntu 24.04, CloudLinux 9).

Using identical display names as your PXE profiles is recommended. This way billing integrations like WHMCS only need to maintain one set of operating system names instead of separate configurations for PXE and template-based installations.

Template Name

The exact Proxmox template name as shown in the Proxmox VE web interface.

Allow Remote Node

Enable this option when the template resides on shared storage and may be located on a different node. Tenantos still prefers templates on the local node but can fall back to shared-storage templates when this option is enabled. Disable it when each node maintains its own dedicated copy.

Linked Clone

Determines whether Tenantos creates a linked or full clone.

  • Linked clone - Fast and storage efficient, but the VM stays tied to the template's datastore and the template must remain available. No VM migrations are possible.
  • Full clone (recommended) - Creates an independent VM that can later be moved to a different storage or node.

Disable Cloud-Init Auto Update

Prevents cloud-init from running package upgrades during deployment. This is useful when a linked PXE profile already performs system updates through scripts.

Works with Proxmox VE 8.0 and newer. If the Proxmox node is running an older version, this option is ignored.

OS Configuration Type

Defines how Tenantos configures the guest after cloning.

  • Linux (Cloud-Init) - Standard choice for Linux templates.
  • Windows (Cloud-Init) - Uses Cloud-Init, only works reliably on Proxmox VE 8.2.4 and newer. Older versions require community patches (further information can be found in the Proxmox forum). It is highly recommended to install and configure the QEMU guest agent alongside Cloudbase-Init.
  • Windows (QEMU Agent - recommended) - Relies on the QEMU guest agent to configure Windows (hostname, networking, password, disk expansion, trial rearm for evaluation builds, etc.). Only the guest agent must be installed in the template. Tenantos automatically executes additional steps for you (such as trial rearm, disk expansion, and password complexity configuration), making this much simpler than cloud-init.

Linked PXE Profile

Each template can optionally inherit a PXE profile. Linked templates adopt that profile's restrictions (tags, roles, allowed locations), customer-facing options (hostname, SSH keys, password fields), first boot scripts, and the "installation completed" trigger behaviour. Scripts are executed after the VM boots.

OS Configuration

During a template-based installation, Tenantos replaces the existing VM with a clone of the selected template while restoring the VPS resources such as CPU and memory configuration afterwards.

Installation Flow

  1. Create a snapshot of the current VM configuration (CPU, memory, NUMA, devices, hotplug, etc) and save a firewall snapshot including rules, aliases, and IP sets.
  2. Clone the selected template to the original VMID.
  3. Restore the saved configuration so CPU, memory, storage assignments, display settings, and other VM options match the server's state before the reinstall. Template-specific values such as BIOS, machine type, and OS type are inherited from the template.
  4. Recreate additional disks exactly as they existed before, resize the primary disk to its previous size, and add or remove the cloud-init disk depending on the selected OS configuration type.
  5. Apply built-in safeguards to automatically correct common configuration issues, such as enabling the QEMU guest agent flag, adding a missing Cloud-Init disk, or repairing an unconfigured boot order.
  6. Power on the VM, apply the operating system configuration based on the selected OS configuration type, and execute both linked and user-defined scripts once the guest is running.
  7. Mark the installation as completed immediately or after a callback, depending on the PXE profile settings.

Preserved Configuration

Tenantos re-applies the values that were present on the server before the reinstall, including:

  • CPU topology, memory size, ballooning, hotplug, additional devices, HA preferences, etc.
  • Network interfaces, MAC addresses, IPv4 and IPv6 assignments, and per-interface firewall behaviour such as the IP spoof filter.
  • Firewall rules, aliases, IP sets.

Certain items deliberately remain controlled by the template (for example BIOS type, machine type, and OS type) to avoid compatibility issues.

Disk Handling

The content of ALL disks is deleted. Data of additional disks are NOT preserved.

Disks are reconstructed from the saved configuration:

  • The primary disk is resized to its previous capacity.
  • Additional disks are recreated with their original size, storage, cache, and format, and EFI or TPM disks are recreated when required.
  • Cloud-init disks are added automatically when the OS configuration type needs them and removed otherwise.

Installation Completion

Tenantos uses two completion modes depending on the OS configuration type and linked PXE profile configuration:

Template Mode (Immediate Completion): The installation is marked as completed immediately after the VM boots. This is the default behavior when no PXE profile is linked or when no scripts are executed after the first boot.

Callback Mode (Deferred Completion): The VM reports back to Tenantos after all configuration steps and scripts have finished executing. The installation is marked as completed only after receiving this callback. The exact timing of the callback depends on the PXE profile's completion trigger setting.

Callback mode is used when:

  • A PXE profile with user-defined scripts is linked (Linux Cloud-Init and Windows Cloud-Init)
  • Windows QEMU Agent configuration is selected (always uses callback mode, regardless of PXE profile configuration)

Linux (Cloud-Init)

Tenantos writes the hostname, SSH keys, generated root password, IPv4/IPv6 configuration, and DNS resolvers into cloud-init metadata. If cloud-init auto-update is enabled (or not explicitly disabled), Cloud-Init handles package upgrades. Scripts run after the first boot.

Since some official cloud images disable root logins, Tenantos automatically ensures that the SSH server accepts root logins. So if the template does not support root logins, Tenantos will enable it. If you don't want that, you can attach a first-boot script that disables root logins.

Windows (QEMU Agent)

This method avoids cloud-init entirely and relies on the QEMU guest agent:

  • The Administrator password is set.
  • IPv4/IPv6 settings, DNS resolvers, hostname, and optional interface resets are applied automatically.
  • The primary disk is expanded, and evaluation builds receive a trial rearm so the licence period is reset.
  • Linked or selected scripts are executed.
  • Temporary files and Windows event logs are cleared.

This is the recommended method for Windows template installations. It is easier to maintain and works across all modern Windows versions.

Windows (Cloud-Init)

Requires a template prepared with Cloudbase-Init, sysprepped, and compatible with Proxmox's cloud-init integration. It is highly recommended to also install the QEMU guest agent.

Windows cloud-init support requires Proxmox VE 8.2.4 or newer. Earlier versions may need community patches (further information can be found in the Proxmox forum) and may not work in all environments.

For more details, refer to the Proxmox Wiki.

Creating Templates

Tenantos does not provide templates. You must build your own KVM templates.

Helpful Proxmox resources:

For Linux, you can usually use the official cloud images provided by distributions (such as Ubuntu Cloud Images, Debian Cloud Images, or Rocky Linux Cloud Images). These images come pre-configured with cloud-init.

How to Switch Existing VMs from PXE to Templates

Once an OS template plan has been created, its plan ID can be added to the Proxmox connection of the respective server. The OS template plan ID is displayed in the VPS plan dropdown and when editing an OS template plan.

  1. Add the plan ID under "OS Template Plan ID" and enable "OS Installation" in the Proxmox connection.
  2. Click "Update" in the Proxmox connection.
  3. Remove the PXE connection assignment and, optionally, the DHCP assignment.

Bulk Updating

The app servers:updateServerConnections tool is interactive and provides a preview of all affected servers before applying changes.

To update multiple servers at once and switch from PXE-based to template-based installations, use the app servers:updateServerConnections CLI tool.

  1. Log in via SSH to your Tenantos server.
  2. Run the following command to view all available options:
app servers:updateServerConnections

Example

Update all Proxmox VPS to assign the OS template plan ID 1 and remove both the DHCP and PXE connections:

app servers:updateServerConnections --connectionType=proxmox --field=osTemplatePlanId --value=1 --alsoRemoveConnections=pxe,dhcp

Troubleshooting

Installation Does Not Complete

If an installation hangs and never reaches the completion step, this is typically caused by one of two issues:

Template Configuration Issue: The template may not be properly configured for the selected OS configuration type. For example, a Linux Cloud-Init installation requires cloud-init to be installed and properly configured in the template. A Windows QEMU Agent installation requires the QEMU guest agent to be installed and running on boot.

Callback Issue: When using callback mode, the VM may be unable to report back to Tenantos. This can occur if first boot scripts fail, the QEMU guest agent is not responding, or network connectivity issues prevent the callback from reaching Tenantos.

Checking Logs: Installation logs are stored in /var/www/html/storage/logs/. These logs contain detailed information about each step of the installation process and can help identify where the installation failed.

Forceful Cancellation: Template-based installations cannot normally be canceled. However, administrators have access to the "Forcefully cancel installation" option in the installation status dialog. This option marks the installation as completed in the database only and should be used when an installation is stuck or has encountered a problem. This option is available to administrators only, is not visible to regular users, and is useful for testing purposes.

Screenshots

OS Template Plan Configuration