Unlocking the operating system drive with a certificate bundle
Use the following procedure when an appliance that uses an external KMS cannot unlock its operating system drives during a restart because its KMS client certificates have expired.
Before you start, prepare the certificate bundle and place it on a host that the appliance can reach.
See Preparing a certificate bundle for unlock recovery.
This procedure is performed at the appliance console, through IPMI, a privileged access solution, or a physical console. No web interface or API is available at this point in the boot sequence.
To unlock the operating system drive with a certificate bundle
- At the console, when the appliance reports that it cannot obtain the key from the external KMS because the certificates have expired, select the option to retrieve certificates from a remote host.
- Enter the host name or IP address of the remote host, a user name and a password for that host, and the full path to the bundle file.
The password is not displayed as you type it.
- Compare the SHA-256 fingerprint of the SSH host key that the appliance displays with the fingerprint of the remote host, and confirm that it matches.
The appliance does not transfer the bundle until you confirm the fingerprint. If the fingerprint does not match what you expect, do not confirm it. Investigate why the host that answered is not the host you intended before you try again.
- The appliance retrieves the bundle, validates it, uses the temporary certificates to obtain the encryption key from the external KMS, unlocks the drives, and continues to start up.
If any of these steps fails - for example, the path to the bundle file is wrong, the user name or the password is incorrect, the bundle does not pass validation, or the certificates in the bundle have expired - the appliance displays the reason as an error message and prompts you again. Correct the detail that was wrong and continue.
- After the appliance has started, import valid long-term certificates for the external KMS.
See Editing an external key management service (KMS).
This step is required, not optional. The temporary certificates are discarded once the drives are unlocked and the appliance's stored KMS configuration is unchanged, so the next restart uses the same expired certificates and fails in the same way.
Note:
The temporary certificates and the encryption key are held only in volatile storage and are removed when the operation finishes, whether it succeeds or fails. They are not written to the appliance configuration, and the appliance's record of which KMS and which key it uses is left unchanged.
Note:
If the unlock fails, the appliance drops to an emergency shell. The log of the unlock attempt is available in that shell as /tmp/os-disk-unlock.log. This file does not persist across a restart. It is copied to /mnt/kms-data/os-disk-unlock-timestamp.log only after the appliance restarts successfully, so an appliance that repeatedly fails to boot has the log only in /tmp. If you cannot recover from the emergency shell, review /tmp/os-disk-unlock.log there and collect a copy of it before you restart the appliance again. Provide the log if you contact Support.