[pve-devel] [PATCH pve-docs] fix #4717: Expanded the section on VM templates

[Shannon Sterz]

On Mon Jul 14, 2025 at 2:41 PM CEST, Alexander Abraham wrote:
> The documentation on VM templates has been expanded and
> explanations added about advantages/disadvantages, how
> they can be worked with and how to create them.

generally we prefer commit message to use the present imperative. so:

Expand the documentation on VM templates and add explanations...

>
> Signed-off-by: Alexander Abraham <a.abraham at proxmox.com>
> ---
>  qm.adoc | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 77 insertions(+), 2 deletions(-)
>
> diff --git a/qm.adoc b/qm.adoc
> index 8b9e096..557cb1f 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -1749,8 +1749,83 @@ setting.
>  Virtual Machine Templates
>  -------------------------
>
> -One can convert a VM into a Template. Such templates are read-only,
> -and you can use them to create linked clones.
> +Virtual machine templates are fully pre-configured operating
> +system images that can be used to deploy KVM-based virtual

nit: the "KVM-based" is a bit redundant imo.

> +machines. In some cases creating a special template is
> +preferrable over cloning another virtual machine. PVE streamlines

typo: preferrable -> preferable

> +the process of using templates for deployment of a virtual machine
> +to such a degree that this process is very fast, easy, and if used
> +with linked clones, optimizes your storage by using base images
> +and thin-provisioning. Proxmox VE supported this functionality
> +since 2008 in the 3.x series. Additionally, templates for KVM-based
> +virtual machines can be created and deployed.

maybe i'm missing something, but this last sentence here seems to
superfluous?

> +
> +Advantages and Disadvantages
> +----------------------------
> +
> +Using virtual machine templates for deploying virtual machines makes it
> +possible to quickly deploy reproducible environments. The downside to
> +this is that if something has to be changed in the template,
> +re-deploying all virtual machines using this template may be a lengthy
> +process.
> +
> +Creating Virtual Machine Templates
> +----------------------------------
> +
> +Proxmox VE's web-based UI offers an option inside the context
> +menu of a virtual machine to convert that virtual machine
> +into a template. The following steps outline measures to
> +be taken to create a template.
> +
> +- 1.) Create a VM with all drivers and install a system with all needed
> +  software packages.
> +- 2.) Remove all user data and passwords. To do this on Windows, run
> +  `sysprep`. To achieve the same result on Linux, run any tools that
> +  do something similar.
> +- 3.) Right-click the VM and select "Convert to template".

i'd prefer an asciidoc ordered list here instead of an unordered list
that you manually add ordering to. you can simply change "- 1.)" to "1."
to do so.

> +
> +Once the virtual machine has been converted, it cannot be started
> +anymore. The icon in the web-based UI changes to symbolize this change.
> +To modify an existing template, the template will have to be deployed
> +and the steps outlined above must be repeated.
> +
> +OS-specific Notes for Templates
> +-------------------------------
> +
> +For productive usage it is highly recommended that a template does not
> +include any data, user accounts or SSH keys. You should remove all of
> +these pieces of data before you convert a virtual machine into a
> +template. On Linux systems you should remove SSH host keys, persistent
> +network MAC configuration, and user accounts and data. On Windows there
> +exist many tools to achieve this task, most notably `sysprep`. In a
> +testing environment it may be useful to use a fully-installed system as
> +a template. Listed below are some ways to achieve this on different
> +platforms.
> +
> +- GNU/Linux:
> +  - Ubuntu: Install Ubuntu in OEM mode (F4 must be pressed).
> +  - CentOS7: Most steps outlined here will also work for Proxmox VE.

nit: shouldn't there be a space between CentOS and 7?

since this is based on the wiki article im assuming you forgot porting
over this link for the "steps outlined here":

https://github.com/rharmonson/richtech/wiki/CentOS-7-1511-Minimal-oVirt-Template

but that guide is fairly old and CentOS 7 is EOL at this point, so maybe
you can find something that is more appropriate nowadays?

further, note that the recommended way of formatting nested unordered
lists in ascii doc look like this:

* GNU/Linux:
** Ubuntu: Install Ubuntu in OEM mode (F4 must be pressed).
** CentOS7: Most steps outlined here will also work for Proxmox VE.
* Windows: ...

[1]: https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/#nested-unordered-list

> +
> +- Windows: Please follow Microsoft's full guide
> +  https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-7/ee523217(v=ws.10)?redirectedfrom=MSDN[here].
> +
> +Deploy a Virtual Machine from a Template
> +----------------------------------------
> +
> +To deploy a virtual machine from a template, right-click the template
> +and select "Clone". This will deploy a virtual machine with the chosen
> +template. There are two types of deployments from a virtual machine
> +template: A full clone and a linked clone.
> +
> +A full-clone virtual machine is a complete copy and is fully independent
> +from the original virtual machine or resulting template, but it requires
> +the same disk space as the original.
> +
> +A linked-clone virtual machine requires less disk space but cannot run
> +without access to the base virtual machine template. Linked clones work
> +well with the following storage formats: Raw files, qcow2, vmdk (local
> +or on a network share), LVM-thin, ZFS, rbd, sheepdog, and nexenta. LVM

sheepdog has been dropped with PVE 6 and nexenta was removed with PVE
3.2, i think adding them here will just confuse users.

[2]: https://pve.proxmox.com/wiki/Roadmap#Proxmox_VE_6.0
[3]: https://pve.proxmox.com/wiki/Roadmap#Proxmox_VE_3.2

> +and ISCSI are not supported.
>
>  NOTE: It is not possible to start templates, because this would modify
>  the disk images. If you want to change the template, create a linked