Virtual TPM

This guide outlines the implementation and configuration requirements for Virtual Trusted Platform Module (vTPM) v2.0 support in Private Cloud Director.

What is Virtual Trusted Platform Module (vTPM)

A Trusted Platform Module (TPM) is a specialized hardware chip on your computer's motherboard that is designed to enhance your computer's security by securely storing cryptographic keys that are used for encryption and decryption.

vTPM v2.0 is a software-based representation of a traditional TPM 2.0 chip. It carries out the same hardware-based security functions as a physical Trusted Platform Module, such as attestation, key and random number generation, but without the physical TPM chip being required.

Private Cloud Director's vTPM solution leverages open source Barbican service for encryption management. Private Cloud Director's Virtual TPM service enables TPM support by default on Private Cloud Director hypervisor hosts.

TPM Version and Models Supported

The Virtual TPM configuration is controlled through metadata that can be applied at the virtual machine image level.

Private Cloud Director currently only supports TPM version 2.0. PCD supports two models for vTPM

• tpm-tis: This option emulates a TPM device based on the TPM Interface Specification, which is the standard for TPM version 1.2.
• tpm-crb: This option emulates a TPM device based on the TPM 2.0 CRB (Chip Reference Board) specification.

Image Preparation and Configuration

When you add TPM metadata to an image, any VM created using the image will automatically enable vTPM with the specified configuration. The metadata parameters control:

• The TPM model type (tpm-tis or tpm-crb)

You can apply these configurations by adding metadata to the image as below:

Image-level Properties

Following is the TPM metadata that you need to associate with a virtual machine image in order to enable vTPM for the VMs created with the image.

YAML

hw_tpm_version = 2.0
hw_tpm_model = tpm-crb

For example, you might start with a standard Windows image without TPM support and later add TPM 2.0 support by updating the image metadata. Any new VMs created from this image will have TPM 2.0 enabled, while existing VMs remain unchanged.

Similarly, if you create a VM using an image with these tags, do not remove these metadata keys while you have active vTPM VMs as it may lead to unexpected failures.

Flavor-level Properties

To enable the support of vTPM live migration, ensure the flavor has the metadata

YAML

hw:tpm_secret_security = deployment

Please note that this can only be set on the flavor metadata, not the image metadata.

Shared swtpm State Directory

The directory /var/lib/libvirt/swtpm must be shared across all compute hosts. Use NFS with the following mount options:

vers=3,local_lock=all

Consistent swtpm UID Across Hosts

Ensure that the swtpm user ID matches across all hosts. Platform9 pins this to UID 64130 starting 2026.4 release. If your UIDs are not consistent across hosts, please fix them so they are consistent. While doing this, you may also have to change the ownership of /var/lib/swtpm-localca to the swtpm user again.

VM Deployment and Verification

1. Create a VM with vTPM support through the Private Cloud Director UI
2. Make sure that the VM reaches "Active" state
3. Perform TPM verification:

TPM Verification for Windows VMs

YAML

1. Press Windows key + R
2. Execute tpm.msc

TPM Verification For Linux VMs:

YAML

ls /dev | grep tpm    # Should show TPM device

General TPM Verification:

YAML

# List running VMs
virsh list

# Verify TPM configuration
virsh dumpxml <VM_ID>

Expected TPM configuration in XML:

YAML

<tpm model='tpm-crb'>
  <backend type='emulator' version='2.0' persistent_state='yes'>
    <encryption secret='<secret>'/>
  </backend>
  <alias name='tpm0'/>
</tpm>

Secret Management Verification

Run the following command to make sure that the secrets got created successfully:

YAML

openstack secret list

Each VM with TPM should have a corresponding secret entry.

vTPM State File

VTPM state files are located on directory /var/lib/libvirt/swtpm by default on the hypervisor host.

Live Migration of vTPM-Enabled VMs

Prerequisites for vTPM Live Migration

Live-migrating a VM with vTPM enabled requires additional setup beyond the standard live migration prerequisites. Because the vTPM emulator (swtpm) maintains state files for each VM, those files must be accessible on both the source and destination host during and after the migration.

All four conditions below must be satisfied before attempting live migration of a vTPM-enabled VM:

1. Flavor Must Include the TPM Secret Security Property

The VM's flavor must have the following extra spec set:

hw:tpm_secret_security = deployment

Without this property, the Compute Service will not attempt to transfer the vTPM secret during migration. The VM may migrate but the vTPM device will fail to start on the destination host.

This property can only be set on the flavor, not the image:

pcdctl flavor set <FLAVOR_NAME> --property hw:tpm_secret_security=deployment

This flavor property must be set before the VM is created. Updating the flavor after a VM has been created does not retroactively enable vTPM migration support for that VM.

2. Shared swtpm State Directory (NFS)

The swtpm state directory /var/lib/libvirt/swtpm must be mounted from the same NFS share on all compute hosts in the cluster. If the state directory is local to each host, the destination host will not have access to the VM's TPM state after migration.

Mount options must include:

vers=3,local_lock=all

Verify the mount is consistent across hosts:

# Run on each host — output should be identical
mount | grep swtpm

3. Consistent swtpm UID Across All Hosts

The swtpm user must have the same numeric UID on every compute host. Private Cloud Director pins this to UID 64130 starting with the 2026.4 release. If hosts were added at different times or from different base images, UIDs may differ, causing permission errors when the destination host tries to access the shared state directory.

Check the swtpm UID on each host:

id swtpm

If the UID is not 64130, update it:

sudo usermod -u 64130 swtpm
sudo chown -R swtpm /var/lib/swtpm-localca
sudo chown -R swtpm /var/lib/libvirt/swtpm

Restart libvirtd on the host after changing the UID:

sudo systemctl restart libvirtd

4. VM HA Shared Storage Requirements (If VM HA Is Enabled)

If your cluster has Virtual Machine High Availability (VM HA) enabled and the cluster contains vTPM VMs:

• The VM's ephemeral storage directory (the virtual machine storage path from the Cluster Blueprint) must be on shared storage mounted on all hypervisor hosts.
• The vTPM state directory (/var/lib/libvirt/swtpm) must also be on shared storage.
• Both directories must be owned by the pf9 user and pf9group group.

Diagnose vTPM Live Migration Failures

Symptom: Migration Fails with "swtpm" or "TPM" in the Error

If a live migration fails and the Compute Service log or virsh output references swtpm, tpm, or a permissions error, work through the following checks.

Check 1: Verify swtpm UID consistency

# On source host
id swtpm

# On destination host
id swtpm

If the UIDs differ, fix them using the steps in the "Consistent swtpm UID" section above.

Check 2: Verify the shared NFS mount is healthy

# On both source and destination hosts
ls -la /var/lib/libvirt/swtpm/

If the directory is empty on the destination host while the source has state files, the NFS mount is not working correctly. Check NFS mount status:

mount | grep swtpm
df -h /var/lib/libvirt/swtpm

Re-mount the NFS share if it has become stale:

sudo umount /var/lib/libvirt/swtpm
sudo mount /var/lib/libvirt/swtpm

Check 3: Verify the flavor property

Check that the VM's flavor includes hw:tpm_secret_security = deployment:

pcdctl flavor show <FLAVOR_NAME>

Look for hw:tpm_secret_security in the properties section. If it is absent, the flavor needs to be updated and a new VM created with the updated flavor — the property cannot be applied retroactively.

Check 4: Inspect the libvirt and swtpm logs

On the destination host, check for errors from swtpm after a failed migration attempt:

sudo journalctl -u swtpm@<VM_UUID> --since "10 minutes ago"

Also check the libvirt migration log on the source host:

sudo grep -i "swtpm\|tpm\|migration" /var/log/libvirt/libvirtd.log | tail -50

Symptom: VM Migrates Successfully but vTPM Is Unavailable After Migration

If the VM reaches ACTIVE on the destination host but the guest OS reports that the TPM device is missing or inaccessible:

1. Verify that the swtpm state file for the VM exists on the shared NFS path:

   ls /var/lib/libvirt/swtpm/<VM_UUID>/

2. Verify that the swtpm user on the destination host owns the state file:

   stat /var/lib/libvirt/swtpm/<VM_UUID>/

   The owner should be swtpm (UID 64130). If not, fix ownership:

   sudo chown -R swtpm:swtpm /var/lib/libvirt/swtpm/<VM_UUID>/

3. Perform a hard reboot of the VM to allow the guest to re-detect the TPM device:

   pcdctl server reboot --hard <VM_UUID>

Symptom: Maintenance Mode Does Not Migrate vTPM VMs

Maintenance Mode does not support live migration of vTPM-enabled VMs in releases prior to 2026.4. If you are running an earlier release and need to move a vTPM VM off a host for maintenance:

1. Shut down the VM (note: this causes downtime).
2. Perform a cold migration to the desired host.
3. Restart the VM on the destination host.

See Virtual Machine Migration for cold migration instructions.

Related Pages

• Virtual Machine Migration
• Virtual Machine High Availability (VM HA)
• Maintenance Mode
• VM Flavors