How to prepare a TPM enabled ESXi host for hardware changes

Products

• VMware vSphere ESXi

Issue/Introduction

If an ESXi host utilizes a Trusted Platform Module (TPM), specific preparation steps are required before initiating any hardware changes while the host remains accessible via SSH. Following hardware maintenance, such as the replacement of a system board/motherboard, CMOS battery, CPU, or RAM, Purple Screen of Death (PSOD) errors are encountered when booting the host.

Refer to KB 312109 for a list of specific error messages associated with boot-time encryption failures.

Environment

• VMware vSphere ESXi 7.x

• VMware vSphere ESXi 8.x

Cause

Hardware modifications to an ESXi host can alter or reset the BIOS configuration. When a host is secured with a TPM, the security key can be wiped from the BIOS and must be manually restored. Configuration backups alone are insufficient for recovery; if a motherboard is replaced without the encryption recovery key, the host cannot be recovered and a complete rebuild is required.

Resolution

Preparation (Before Hardware Maintenance):

1. Connect to the ESXi host via SSH as the root user.

2. Verify the current encryption status to determine if "Require Secure Boot" or encryption is active:

   esxcli system settings encryption get
   

3. Generate the recovery key:

   esxcli system settings encryption recovery list
   

4. Store the generated recovery key in a secure, off-host location.

5. Generate and export a configuration backup to complement the encryption key:

   vim-cmd /hostsvc/firmware/sync_config
   vim-cmd /hostsvc/firmware/backup_config
   

Recovery (After Hardware Maintenance):

1. During the host boot sequence, press Shift+O to manually enter the recovery key.

2. Once the host has successfully booted, connect via SSH as the root user.

3. Bind the host configuration to the new TPM chip:

   esxcli system settings encryption set --mode=TPM

4. Persist the configuration changes:

   /sbin/auto-backup.sh

Additional Information

This procedure ensures an ESXi host can be safely recovered from a PSOD after hardware changes by successfully applying the TPM recovery key and rebinding the new hardware components.