Manage a Secure ESXi Configuration

You can use ESXCLI commands to list the secure ESXi configuration recovery key, rotate the recovery key, and change the TPM policies (for example, enforcing UEFI Secure Boot).

List the Contents of the Secure ESXi Configuration Recovery Key

You can use ESXCLI to show the contents of the secure ESXi configuration recovery key.

This task applies only to an ESXi host that has a TPM. In general, you list the contents of the secure ESXi configuration recovery key to create a backup, or as part of rotating recovery keys.

Prerequisites

• Have access to the ESXCLI command set. You can run ESXCLI commands remotely, or run them in the ESXi Shell.
• Required privilege for using ESXCLI standalone version or through PowerCLI: Host.Config.Settings

Procedure

1. Run the following command on the ESXi host.

   esxcli system settings encryption recovery list

2. Save the output in a secure, remote location as a backup, in case you must recover the secure configuration.

Results

The recovery key ID and key are displayed.

Example: List the Secure ESXi Configuration Recovery Key

[root@host1] esxcli system settings encryption recovery list

Recovery ID                             Key
--------------------------------------  ---
{2DDD5424-7F3F-406A-8DA8-D62630F6C8BC}  478269-039194-473926-430939-686855-231401-642208-184477-602511
-225586-551660-586542-338394-092578-687140-267425

Rotate the Secure ESXi Configuration Recovery Key

You can use ESXCLI to rotate the secure ESXi configuration recovery key.

This task applies only to an ESXi host that has a TPM. You can rotate the ESXi secure configuration recovery key as part of your security best practices.

Prerequisites

• Have access to the ESXCLI command set. You can run ESXCLI commands remotely, or run them in the ESXi Shell.
• Required privilege for using ESXCLI standalone version or through PowerCLI: Host.Config.Settings

Procedure

1. List the recovery key.
   See List the Contents of the Secure ESXi Configuration Recovery Key.
2. Run the following command.

   esxcli system settings encryption recovery rotate [-k keyID] -u uuid

   In this command, the optional keyID is the key ID in the VMkernel key cache and uuid is the Recovery ID (obtained from the esxcli system settings encryption recovery list command). If you do not supply the optional key ID, ESXi replaces the old recovery key with a new recovery key that is randomly generated.

Results

The recovery key is now set to the contents of the key referenced by key ID, if provided. Otherwise, ESXi provides a new key ID.

Troubleshooting and Recovering the Secure ESXi Configuration

You can troubleshoot and recover from boot problems that you might encounter with a secure ESXi Configuration.

If you clear a TPM (that is, the seed values in the TPM are reset), if a TPM fails, or if you replace the motherboard or TPM device, or both, you must take steps to recover the ESXi secure configuration. You must have the recovery key to recover the configuration. Until you recover the configuration, the ESXi host cannot boot. See Recover the Secure ESXi Configuration.

Although uncommon, it is possible that an ESXi host might fail to restore or decrypt the secure configuration, preventing the host from booting. Possible situations include:

• Change to secure boot setting (or other policy)
• Actual tampering
• The recovery key is unavailable

To troubleshoot these conditions, see the VMware knowledge base article at https://kb.vmware.com/s/article/81446.

Recover the Secure ESXi Configuration

If a TPM fails, or if you clear a TPM, you must recover the secure ESXi Configuration. Until you recover the configuration, the ESXi host cannot boot.

Recovering the secure ESXi configuration refers to the following situations:

• You cleared the TPM (that is, the seeds in the TPM were reset).
• The TPM failed.
• You replaced the motherboard or the TPM device, or both.

To troubleshoot other secure ESXi configuration problems, see the VMware knowledge base article at https://kb.vmware.com/s/article/81446.

Perform the recovery manually. Do not perform the recovery as part of an installation or upgrade script.

Prerequisites

Get your recovery key. You should have previously listed and stored the recover key. See List the Contents of the Secure ESXi Configuration Recovery Key.

Procedure

1. (Optional) If the TPM failed, move the disk (having the boot bank) to another host with a TPM.
2. Start the ESXi host.
3. When the ESXi installer window appears, press Shift+O to edit boot options.
4. To recover the configuration, at the command prompt, append the following boot option to any existing boot options.

   encryptionRecoveryKey=recovery_key

   The secure ESXi configuration is recovered and the ESXi host boots.
5. To persist the change, enter the following command:

   /sbin/auto-backup.sh

What to do next

When you enter the recovery key, it is temporarily displayed in an untrusted environment and is in memory. Though not necessary, as a best practice, you can remove residual traces of the key in memory by rebooting the host. Or, you can rotate the key. See Rotate the Secure ESXi Configuration Recovery Key.

Activate or Deactivate the Secure Boot Enforcement for a Secure ESXi Configuration

You can choose to activate UEFI secure boot enforcement, or deactivate a previously activated UEFI secure boot enforcement. You must use ESXCLI to change the setting in the TPM on the ESXi host.

This task applies only to ESXi hosts that have a TPM. UEFI Secure boot is a firmware setting for ensuring that the software launched by the firmware is trusted. To learn more, see UEFI Secure Boot for ESXi Hosts. The enablement of UEFI Secure boot can be enforced upon every boot by using the TPM.

Prerequisites

• Have access to the ESXCLI command set. You can run ESXCLI commands remotely, or run them in the ESXi Shell.
• Required privilege for using ESXCLI standalone version or through PowerCLI: Host.Config.Settings

Procedure

1. List the current settings on the ESXi host.

   esxcli system settings encryption get
      Mode: TPM
      Require Executables Only From Installed VIBs: false
      Require Secure Boot: true

   If secure boot enforcement is activated, Require Secure Boot displays true. If secure boot enforcement is deactivated, Require Secure Boot displays false.

   If Mode appears as NONE, you must activate the TPM in the firmware of the host and set the mode by running the following command:

   esxcli system settings encryption set --mode=TPM

2. Activate or deactivate the secure boot enforcement.

   Option	Description
   Activate	Shut down the host gracefully. For example, right-click the ESXi host in the vSphere Client and select Power > Shut Down. Activate secure boot in the firmware of the host. See your specific vendor hardware documentation. Restart the host. Run the following ESXCLI command. esxcli system settings encryption set --require-secure-boot=T Verify the change. esxcli system settings encryption get Mode: TPM Require Executables Only From Installed VIBs: false Require Secure Boot: true Confirm that Required Secure Boot displays true. To save the setting, run the following command. /bin/backup.sh 0
   Deactivate	Run the following ESXCLI command. esxcli system settings encryption set --require-secure-boot=F Verify the change. esxcli system settings encryption get Mode: TPM Require Executables Only From Installed VIBs: false Require Secure Boot: false Confirm that Require Secure Boot displays false. To save the setting, run the following command. /bin/backup.sh 0 You can choose to deactivate the secure boot in the firmware of the host, but at this point the dependency between the firmware setting and the TPM enforcement is no longer set.

Results

The ESXi host runs with secure boot enforcement activated or deactivated, depending on your choice.

Note:

If you do not activate a TPM when you install or upgrade to vSphere 7.0 Update 2 or later, you can do so later with the following command.

esxcli system settings encryption set --mode=TPM

Once you have activated the TPM, you cannot undo the setting.

The esxcli system settings encryption set command fails on some TPMs even when the TPM is activated for the host.

• In vSphere 7.0 Update 2: TPMs from NationZ (NTZ), Infineon Technologies (IFX), and certain new models (like NPCT75x) from Nuvoton Technologies Corporation (NTC)
• In vSphere 7.0 Update 3: TPMs from NationZ (NTZ)

If an installation or upgrade of vSphere 7.0 Update 2 or later is unable to use the TPM during the first boot, the installation or upgrade continues, and the mode defaults to NONE (that is, --mode=NONE). The resulting behavior is as though the TPM is not activated.

Activate or Deactivate the execInstalledOnly Enforcement for a Secure ESXi Configuration

You can choose to activate execInstalledOnly enforcement, or deactivate a previously enabled execInstalledOnly enforcement. You must use ESXCLI to change the setting in the TPM on the ESXi host. UEFI secure boot enforcement must be activated before you can activate the execInstalledOnly enforcement.

This task applies only to ESXi hosts that have a TPM. The execInstalledOnly advanced ESXi boot option, when set to TRUE, guarantees that the VMkernel executes only those binaries that have been packaged and signed as part of a VIB. The enablement of this boot option can be enforced upon every boot by using the TPM.

Prerequisites

• To activate the execInstalledOnly enforcement, you must first activate the UEFI secure boot enforcement. The execInstalledOnly enforcement is built on top of the UEFI secure boot enforcement. See Activate or Deactivate the Secure Boot Enforcement for a Secure ESXi Configuration.
• Have access to the ESXCLI command set. You can run ESXCLI commands remotely, or run them in the ESXi Shell.
• Required privilege for using ESXCLI standalone version or through PowerCLI: Host.Config.Settings

Procedure

1. List the current settings on the ESXi host.

   esxcli system settings encryption get
      Mode: TPM
      Require Executables Only From Installed VIBs: false
      Require Secure Boot: true

   If execInstalledOnly enforcement is activated, Require Executables Only From Installed VIBs displays true. If execInstalledOnly enforcement is deactivated, Require Executables Only From Installed VIBs displays false. To activate the execInstalledOnly enforcement, the secure boot enforcement must be activated, and Require Secure Boot displays true in this case.

   If Mode appears as NONE, you must enable the TPM in the firmware of the host and set the mode by running the following command:

   esxcli system settings encryption set --mode=TPM

   Also, if Require Secure Boot displays as False, see Activate or Deactivate the Secure Boot Enforcement for a Secure ESXi Configuration to activate the enforcement.
2. Activate or deactivate the execInstalledOnly enforcement.

   Option	Description
   Activate	Verify that the secure boot option is activated. esxcli system settings encryption get Mode: TPM Require Executables Only From Installed VIBs: false Require Secure Boot: true Confirm that Require Secure Boot displays true. If not, see Activate or Deactivate the Secure Boot Enforcement for a Secure ESXi Configuration. To configure the runtime value of the execInstalledOnly boot option to TRUE, run the following ESXCLI command. esxcli system settings kernel set -s execInstalledOnly -v TRUE Shut down the host gracefully. For example, right-click the ESXi host in the vSphere Client and select Power > Shut Down. Restart the host. To set the execInstalledOnly enforcement, run the following ESXCLI command. esxcli system settings encryption set --require-exec-installed-only=T Verify the change. esxcli system settings encryption get Mode: TPM Require Executables Only From Installed VIBs: true Require Secure Boot: true Confirm that Require Executables Only From Installed VIBs displays true. To save the setting, run the following command. /bin/backup.sh 0
   Deactivate	Run the following ESXCLI command. esxcli system settings encryption set --require-exec-installed-only=F Verify the change. esxcli system settings encryption get Mode: TPM Require Executables Only From Installed VIBs: false Require Secure Boot: true Confirm that Require Executables Only From Installed VIBs displays false. To save the setting, run the following command. /bin/backup.sh 0 The TPM no longer enforces the execInstalledOnly boot option.

Results

The ESXi host runs with execInstalledOnly enforcement activated or deactivated, depending on your choice.