Windows templates and sysprep · Proxmox VE

Cloning a Linux guest is a rename, a new SSH host key, a new machine-id and a new IP. Cloud-Init does all four before the first login prompt appears, and if you forget, you get a duplicate hostname and an SSH warning, both of which announce themselves immediately.

Cloning a Windows guest without generalising it produces machines that are externally distinct — different names, different addresses — and internally identical. Nothing warns you. The estate works. Then, somewhere between three weeks and two years later, patching stops reporting, or activation collapses, or a domain join starts failing for reasons that make no sense, and the common cause is a template built in an afternoon by someone who cloned a working server.

What Microsoft actually says

This is not a best practice. It is a support boundary, and the wording in the sysprep command-line reference is unusually direct:

Moving or copying a Windows image to a different computer without running the Sysprep /generalize command is not supported. You must use the Sysprep /generalize command to generalize a complete Windows installation before you can use the installation for deployment to a new computer, whether you use imaging, hard disk duplication, or another method.

“Hard disk duplication, or another method” includes qm clone. A Proxmox full clone or linked clone is hard disk duplication with a new VMID attached.

And the reference is equally clear that identical hardware does not exempt you:

If you intend to create an image of an installation for deployment to a different computer, you must run the Sysprep command together with the /generalize option, even if the other computer has the same hardware configuration.

That sentence exists because the objection it answers is so natural. Every clone of a Proxmox template has exactly the same virtual hardware. It makes no difference: the things sysprep removes are not hardware-derived.

What `/generalize` removes

Three items, given verbatim:

Prepares the Windows installation to be imaged. Sysprep removes all unique system information from the Windows installation. Sysprep resets the security ID (SID), clears any system restore points, and deletes event logs.

The next time that the computer starts, the specialize configuration pass runs. The configuration pass creates a new security ID (SID).

The SID is the one that matters, and the reason it matters is not the SID itself. It is everything derived from it.

Derived from the machine identity	What a duplicate looks like	How long it stays hidden
Machine SID	Local accounts and groups on every clone share RIDs	Indefinitely, until something enumerates across machines
Computer name	A name conflict on the network, or a rename that leaves stale references	Days
WSUS/Update client identifier	Clones collapse into one entry in the update server; patch compliance is fiction	Weeks — until an audit
KMS client machine identifier	The KMS host counts many machines as one, and the activation count never reaches its threshold	Weeks to months
Remote Desktop self-signed certificate	Every clone presents the same RDP certificate	Until somebody looks
Domain machine account material	Rejoin and trust failures that read as network faults	Variable, and always at the worst time

The middle two are the ones that cost money and reputation. Patch compliance reporting that silently covers a fraction of the estate is worse than no reporting, because it is believed. And a KMS host that never reaches its activation threshold produces an estate of machines in grace periods, all expiring around the same time.

The template that was cloned from a working server

The pattern is always the same, and it always looks reasonable at the time.

Somebody builds a good Windows Server VM: patched, hardened, monitoring agent installed, the corporate certificate store populated, three internal tools configured. It takes two days. Then a second server is needed, and cloning that VM saves two days, so the VM gets cloned. Then it becomes the informal template. Then it becomes qm template. Nobody ever ran sysprep, because at the moment of the first clone it was not a template, it was just a copy.

Six months later there are ninety machines descended from it. What surfaces first is usually patching: the update server shows twelve clients where there should be ninety, because the clones share an update client identifier and each new registration replaces the last. The compliance report has been green throughout.

The reason this is expensive is that the fix is not applicable retroactively to the running machines. Sysprep generalises an image; it does not repair an estate of already-deployed duplicates in place. Running sysprep /generalize on a production server takes it back through OOBE, drops it from the domain, and resets its SID — which is a rebuild with extra steps. Ninety machines have to be rebuilt, or re-identified individually with per-symptom workarounds, and neither is a small piece of work.

The moment to prevent it costs about twenty minutes, once, before the first clone.

Building the template

The workflow has five phases. Phase four is the one that is easy to get wrong.

1. Build the base

Install Windows following Lesson 1 — win11 or win10 ostype, q35, OVMF, virtio-scsi-single, and the storage driver loaded during setup. Install the VirtIO bundle, the guest agent and the balloon service from Lesson 2. Patch fully. Do not join the domain. A template should never carry a machine account.

2. Customise in audit mode

Audit mode exists exactly for this. It bypasses OOBE so you reach a desktop without creating a user account, and you can install applications and drivers there:

Audit mode enables you to add customizations to Windows images. Audit mode does not require that you apply settings in OOBE. By bypassing OOBE, you can access the desktop more quickly and perform your customizations.

Enter it with Sysprep /audit /reboot, or configure it in an answer file with the reseal mode setting. Everything you install in audit mode survives generalisation.

3. Write the answer file

An unattend.xml is what turns a template into unattended provisioning. It is processed in configuration passes; the two you care about for a Proxmox template are:

specialize — runs on first boot after generalisation, on the new machine. Computer name, domain join, product key. The reference notes that to activate automatically you specify a valid product key in the Microsoft-Windows-Shell-Setup ProductKey setting during this pass.
oobeSystem — runs immediately before OOBE. Locale, time zone, administrator password, skipping the OOBE screens.

Build it with Windows System Image Manager against your exact install media, not by editing a file from a blog post — the schema is version-specific and a setting that does not apply to your image is silently ignored, which is the worst possible failure mode for an answer file.

4. Generalise

Destructivegeneralise the image, from an elevated prompt inside the guest— Irreversible for this guest. It resets the SID, clears restore points and deletes event logs. The guest shuts down; do not boot it again except as a template.

# Full generalize, using an answer file, then shut down
C:\Windows\System32\Sysprep\Sysprep.exe /generalize /oobe /shutdown /quiet /unattend:C:\Windows\System32\Sysprep\unattend.xml

/quiet is not optional on Server Core. The reference is emphatic: you must run sysprep from the command line and specify /quiet on a Server Core installation, “Otherwise, the Sysprep UI won’t show, and the process will fail silently.”

There is a second mode worth knowing about, and a constraint that comes with it:

/mode:vm — Generalizes a Virtual Hard Disk (VHD) so that you can deploy the VHD as a VHD on the same Virtual Machine (VM) or hypervisor. After the VM restarts, the VM can boot to OOBE.

The only additional switches that apply to VM mode are /reboot, /shutdown, and /quit. You must deploy the VHD on a Virtual Machine (VM) or hypervisor with the same hardware profile. […] Deploying the VHD to a different VM with a different hardware profile might cause unexpected issues.

You can only run VM mode from inside a VM.

/mode:vm skips hardware re-detection, which makes first boot considerably faster. The price is the hardware-profile constraint, and for a Proxmox estate that constraint has teeth: the machine version pinned at creation (Lesson 1) is part of the hardware profile, and so is the firmware and the disk controller. A template generalised with /mode:vm on a pc-q35-10.0 OVMF guest is a template for pc-q35-10.0 OVMF guests.

Use /mode:vm when your estate is genuinely homogeneous and you clone from the template onto identical configuration. Use a plain /generalize when the template has to serve several profiles, or when you might move it to another hypervisor. If you are not sure, use the plain form; the cost is one slower first boot per clone.

5. Turn it into a Proxmox template

Configuration changeconvert the generalised VM into a template— qm template makes the disks read-only. The VM can no longer be started; only cloned. Verify the guest is shut down and generalised first.

VMID=9100

# The guest must be stopped, and stopped because sysprep shut it down
qm status "$VMID"

# Remove the install ISO and the VirtIO ISO from the template
qm set "$VMID" --delete ide2
qm set "$VMID" --ide0 none,media=cdrom

# Add a Cloud-Init drive; configdrive2 is the default for a Windows ostype
qm set "$VMID" --ide1 local-lvm:cloudinit

qm template "$VMID"

Cloud-Init on Windows: cloudbase-init

Part IX covered Cloud-Init for Linux templates. Windows has a reimplementation, and Proxmox supports it directly. From the Cloud-Init support documentation:

The default depends on the configured operating system type (ostype). We use the nocloud format for Linux, and configdrive2 for windows.

So citype has three allowed values — configdrive2, nocloud and opennebula — and the correct one for Windows is selected automatically by the ostype you set in Lesson 1. This is the second time that field has paid for itself: a Windows guest left at ostype: other gets a nocloud drive that cloudbase-init, configured with its default ConfigDrive service, will not consume. The symptom is a clone that boots with none of its Cloud-Init settings applied and no error anywhere.

The pieces:

Install cloudbase-init in the guest during audit mode, before generalising. Its installer offers to run sysprep at the end with its own unattend file; whether you use that or your own is a matter of taste, but use one or the other, not both.
Attach a Cloud-Init drive to the template, as in the command block above.
Set the per-clone values on the clone, not the template:

Configuration changeclone the template and set per-guest Cloud-Init values— Values are applied at the next start. Regenerating the drive on a running guest does nothing until it reboots.

TEMPLATE=9100
NEWID=151

qm clone "$TEMPLATE" "$NEWID" --name app-win-01 --full 1
qm set "$NEWID" \
--ciuser Administrator \
--ipconfig0 ip=192.0.2.61/24,gw=192.0.2.1 \
--nameserver 192.0.2.10 \
--searchdomain example.com

# Inspect exactly what the guest will be handed, before starting it
qm cloudinit dump "$NEWID" user
qm cloudinit dump "$NEWID" network

qm cloudinit dump is the verification step that can fail. It shows the generated configuration for user, network or meta without starting the guest, so a wrong gateway or a missing nameserver is visible before first boot rather than after a console session.

Do not put the password in cipassword for a domain-joined estate

cipassword exists and works, and the Cloud-Init documentation itself recommends SSH keys over it — advice that does not transfer to Windows, where there are no SSH keys in the same sense.

For a Windows estate the better answer is to not provision an interactive password at all: have the answer file join the domain during the specialize pass and let domain credentials be the access path, with the local administrator account left disabled or with a password set by your secret management at first boot. A cipassword value lives in the VM configuration under /etc/pve, which is readable by anyone with the right PVE privileges and is included in configuration backups.

If you must use it, treat it as a bootstrap credential with a lifetime of minutes, rotated by the first configuration-management run.

Under the hood

Why does a duplicated SID matter when every clone gets a different computer name and a different domain account anyway?

A Windows machine SID is the identifier for the local security authority. Every local account and group on that machine is that SID plus a relative identifier: the local Administrator is always machine-SID + RID 500, the Guests group is always machine-SID + RID 546. Domain accounts are different — they carry the domain SID — which is why the common claim that “duplicate SIDs do not matter on a domain” contains a grain of truth.

The grain is small. What breaks is everything that treats the machine SID as a unique key across machines, and Windows components do this more often than the architecture suggests they should:

The update client identifier is generated once and stored. Clone the stored value and two machines claim to be the same client; the server keeps the most recent registration.
The KMS client machine identifier is likewise generated once. A KMS host requires a minimum count of distinct clients before it will activate anything, and duplicated identifiers mean that count never rises.
Anything that resolves a local account by SID across machines — a centrally deployed ACL, a security scanner correlating findings, a backup agent keyed on machine identity — gets ambiguity instead of an answer.

The specialize pass is where the repair happens. Sysprep does not generate the new SID at generalisation time; it removes the old one and marks the image so that the next boot runs specialize, and that pass mints a new SID before the machine has a network identity. That ordering is why the generalised image is safe to copy: it has no identity at all in between.

It is also why you cannot generalise a running production server and keep it. The machine that comes back up has a different local security authority than the one that went down, which means new local account SIDs, a broken domain trust, and every local ACL referring to accounts that no longer exist under those identifiers.

What happens if sysprep fails with a fatal error?

Sysprep was not able to validate your Windows installation or A fatal error occurred while trying to sysprep the machine is the single most common template-building failure, and the dialog contains nothing useful.

The log is where the answer is, and the location depends on the pass. The reference gives them explicitly, because the generalize pass deletes the standard setup logs and therefore writes elsewhere:

Pass	Log path
Generalize	`%WINDIR%\System32\Sysprep\Panther`
Specialize	`%WINDIR%\Panther`
Unattended setup actions (OOBE)	`%WINDIR%\Panther\Unattendgc`

setupact.log is the main file. Open the generalize one and search for the first Error line; it names the component that refused.

The usual causes, in rough order of frequency:

A provisioned modern app installed for one user account but not provisioned system-wide. The log names the package. This is why you customise in audit mode, which does not create a user account, rather than by logging in as an administrator and installing things.
The machine is domain-joined. Remove it from the domain first. A template should never have been joined.
A pending reboot or a partly applied update. Complete it, reboot, retry.
Sysprep has already run on this image more times than the edition allows. The rearm counter is finite. If you are iterating on a template, iterate on clones of a pre-sysprep VM, not on the same image repeatedly.

Cause 4 is the argument for the win2022-golden-PRESYSPREP VM in the callout above, stated as an operational rule: generalise a copy, never the original. Every template refresh then starts from a clean counter.

Windows template build and release checklist

Build

Base install per Lesson 1, VirtIO drivers and agent per Lesson 2, fully patched.
Not joined to the domain. No machine account, ever.
Customised in audit mode (Sysprep /audit /reboot), not from a logged-in user session.
cloudbase-init installed, if you intend Cloud-Init provisioning.
Answer file built in Windows System Image Manager against this exact media, covering specialize and oobeSystem.
Snapshot or clone taken and kept as -PRESYSPREP, before generalising.

Release

Sysprep /generalize /oobe /shutdown /quiet /unattend:... — and the guest shut itself down, which is the evidence it completed.
Install ISO and VirtIO ISO removed; boot order has no CD-ROM in it.
Cloud-Init drive attached; ostype is a Windows value so citype resolves to configdrive2.
qm template run, and the template named with a date or a version.

Prove it before you trust it

Clone it once. Check qm cloudinit dump before first boot.
Boot the clone, and verify from the host that the agent answers and reports the new hostname: qm agent NEWID get-host-name.
Confirm the clone has a different machine SID from the template and from a previous clone. Two clones is the minimum meaningful test — one clone can look correct while sharing an identity with the template it came from.
Join it to the domain, patch it, and confirm it appears as a new client in the update server. That is the check that would have caught the ninety- machine case above.

Key takeaways

Microsoft does not support moving or copying a Windows image to a different computer without Sysprep /generalize, explicitly including hard disk duplication, and explicitly including identical hardware. qm clone is duplication.
/generalize resets the SID, clears restore points and deletes event logs. The new SID is minted by the specialize pass on first boot, which is why the generalised image is safe to copy.
Non-generalised clones fail late and quietly: update-client collapse, KMS counts that never reach threshold, and patch compliance reports that are believed.
/mode:vm is faster but binds the image to a hardware profile — which on Proxmox includes the pinned machine version, firmware and controller.
qm template is one-way. Keep a pre-sysprep VM so that iterating on a template does not consume the rearm counter and does not require a rebuild.
Windows Cloud-Init means cloudbase-init, and Proxmox selects configdrive2 automatically from a Windows ostype. A guest left at ostype: other gets a nocloud drive and silently applies nothing.

Knowledge check

Why this matters

Templates are where a virtualisation platform stops being a place to run servers and starts being a way to produce them. The whole value is that the hundredth machine costs the same as the second.

Windows makes you pay a specific admission fee for that: twenty minutes of generalisation, an answer file, and the discipline to build templates in audit mode from a copy rather than by cloning a server that happens to be good. Skip the fee and you still get the hundred machines. You just get them with one identity between them, and you find out at the worst possible moment — during an audit, during an activation renewal, or during the incident where patch compliance turns out to have been reporting on twelve of ninety machines all along.

The deeper point is about which errors a platform lets you make quietly. Proxmox will clone a non-generalised Windows guest without a murmur, because from the hypervisor’s position that is a perfectly ordinary disk copy. The guest will boot, run and serve traffic. Nothing in the stack is in a position to tell you that you have just started an estate on the wrong foot — which is precisely why it has to be a checklist item rather than something you expect a tool to catch.