Intel AMT Features > Remote Control > Detailed Description > Intel® One-Click Recovery

Intel® One Click Recovery

Intel® One-Click Recovery allows initiating a recovery process with a single command from a remote Management Console to return a device’s operating system to its last good known state in a secure manner with minimum down time and effort for the user. This includes reliable recovery of devices from bad states, bare-metal situations, or any connectivity issues. Using the Intel AMT remote OOB (out of band) network connection that operates below the OS, Intel AMT enables configuration and trigger of a recovery (or diagnostics) session, to a boot path specified by IT.

The feature is available on vPro SKUs, starting with Tiger Lake platforms using Intel CSME 15 firmware.

Usage

Discovering the platform’s boot options and enablement status

Configuring the platform for the boot

Triggering reboot of the platform

Monitoring the platform

Configuring a Filter for Logging Intel One-Click Recovery Events

Transmitting Parameters from the Console to BIOS via Intel AMT

Parameter Types

The following added boot capabilities enable using Intel AMT for Intel One-Click Recovery OS recovery:

   Boot to MSFT Win RE: Equivalent to a physical user pushing a button on the platform. This method can automatically recover the Windows OS when pre-configured by IT with an answers file. If manual actions by IT are required, the Intel AMT KVM feature can be used to (for example) manually select the Microsoft recovery path.

   Boot to UEFI HTTPS Network boot to a URI specified by the remote console (this method is OS agnostic). This method can be used instead of the existing Intel AMT USB Storage redirection solution for secure network boot to a remote image. In Intel CSME 15 support is limited to wired LAN connection only. Starting with Intel CSME 16.0, wireless LAN connection is supported as well. See UEFI BIOS/Intel® CSME WiFi Profile Sharing.

   Boot to a locally-installed recovery or diagnostics pre-boot application (PBA) (this method is OS agnostic). This method requires a recovery solution pre-installed on the system by the OEM or ISV.

If the platform is provisioned in CCM mode, or provisioned in ACM mode but the console has required user consent for UEFI boot options, Intel AMT will request user consent before triggering the boot.

Invoking these new boot options via Intel AMT is subject to the same Intel AMT authentication and authorization that is required for invoking the legacy boot options. The same rules apply to the prerequisites for accessing these options.

Usage

Intel One-Click Recovery is enabled by:

   Adding new boot sources to the Intel AMT Remote Control Boot Configuration options and extending the WS-MAN remote control boot configuration interface.

   Adding the ability to configure one of these new boot sources and its parameters so that it will be used as the boot source when a reboot is triggered by the remote console.

The Intel One-Click Recovery flow consists of the following steps:

   Checking whether Intel One-Click Recovery is enabled by the Intel AMT firmware

   Discovering the platform’s boot capabilities, as enabled by the OEM in the BIOS

   Configuring the platform’s boot options (chosen from the supported and enabled capabilities)

   Triggering reboot of the platform

   Monitoring the platform's state during the triggered reboot

Note: To enable the BIOS to use the network (including executing Intel One-Click Recovery) over wired LAN in an 802.1x environment, the AMT_8021XProfile.PxeTimeout field must first be set to a value greater than zero.

Discovering the platform’s boot options and enablement status

To check whether Intel One-Click Recovery is enabled by the Intel AMT firmware, read CIM_BootService.EnabledState. If it is not enabled in the firmware, enable it by using CIM_BootService.RequestStateChange (the same method can be used to disable it). This action requires the ADMIN_SECURITY_ADMINISTRATION_REALM.

To discover the Intel One-Click Recovery options that the platform supports, the management console needs to run AMT_BootCapabilities.Get() . This function returns the boot options supported by the platform, including the following new Intel One-Click Recovery boot options:

   ForceWinREBoot: Supports Intel AMT invoking boot to WinRE

   ForceUEFILocalPBABoot: Supports booting to an ISV’s PBA

   ForceUEFIHTTPSBoot: Supports Intel AMT invoking HTTPS boot

   AMTSecureBootControl: Determines whether Intel AMT is privileged by BIOS to disable secure boot for an AMT triggered boot option. If true, the BIOS allows Intel AMT to control the secure boot (i.e., to disable secure boot in recovery from HTTPS under certain conditions).

To discover which of the platform’s Intel One-Click Recovery boot options are enabled in the BIOS, and to discover the Boot Guard state: The management console needs to invoke AMT_BootSettingData.Get(). This function shows which of the supported boot options are enabled:

   WinREBootEnabled: Specifies whether the Win RE boot option is enabled in BIOS

   UEFILocalPBABootEnabled: Specifies whether the option to boot to an ISV’s PBA is enabled in BIOS

   UEFIHTTPSBootEnabled: Specifies whether the option to allow Intel AMT to invoke an HTTPS boot is enabled in BIOS

   SecureBootControlEnabled: Determines whether Intel AMT is privileged by BIOS to disable secure boot for an Intel AMT triggered HTTPS boot option. If not, EnforceSecureBoot must be set to TRUE.

To view all the available recovery boot sources, the management console should run CIM_BootSourceSetting.Enumerate() and then for each instance it should run CIM_BootSourceSetting.Get(). For each Intel One-Click Recovery boot source there is a CIM_BootSourceSetting instance. The Intel One-Click Recovery boot sources are identified via the following fields in the CIM_BootSourceSetting structure:

Field

Description

StructuredBootString

A string identifying the boot source using the format "<OrgID>:<identifier>:<index>".

For Intel One-Click Recovery boot options:

Intel(r)AMT:OCR-UEFI-Boot-Option:<index>

BIOSBootString

BIOS description of the boot option as registered by the BIOS with Intel AMT – identifies the vendor and name of the recovery solution.

BootString

BIOS description of the EFI device path as registered by the BIOS with Intel AMT.

Note:

   Intel AMT returns only the available boot sources. For example, if Intel One-Click Recovery boot to HTTPS is disabled or not supported by the BIOS, Intel AMT does not return a corresponding boot source.

   Intel AMT returns boot sources related to Intel One-Click Recovery only if the network connection between the console and Intel AMT is secured by TLS.

Configuring the platform for the boot

To configure parameters for the Intel One-Click Recovery boot, the management console should set the boot parameters by invoking AMT_BootSettingData.Put().

   To set parameters for Intel One-Click Recovery, the console should set AMT_BootSettingData.UefiBootParametersArray and AMT_BootSettingData.UefiBootNumberOfParams.

   UefiBootParametersArray is a TLV parameters array with a maximum size of 1024 bytes.

   UefiBootNumberOfParams indicates the number of parameters in UefiBootParametersArray. To pass it in the WS-MAN command, it must first be encoded with Base64.

   EnforceSecureBoot: Indicates whether Secure Boot is required. Should be set to TRUE unless recovery is from HTTPS and the BIOS allows Intel AMT to control this setting and Intel AMT was provisioned in ACM mode.

Other boot options that can be set along with Intel One-Click Recovery:

   KVM boot

   ForcedProgressEvents: so that progress events of Intel One-Click Recovery will be registered in the event log. See progress events for Intel One-Click Recovery in the Intel AMT event log and also how to update an event filter.

   KeyboardLock

   UserPasswordBypass

To specify the UEFI boot option (HTTPS/WinRE/PBA) for the next boot, the management console should set the chosen boot source as the first boot source, and specify that this boot configuration should be applied only to the next boot. For details, see Boot Configuration Details.

Triggering reboot of the platform

To remotely trigger reboot of the platform: The management console should invoke CIM_PowerManagementService.Requestpowerstatechange().

Monitoring the platform

There are 2 methods by which the Management Server/Console can monitor the status of the boot:

   Using Boot Progress / Error Alerts: During the boot, the BIOS sends ASF PET alerts to Intel AMT to notify regarding the boot progress. The Management Console can set the WS-MAN AMT_BootSettingData.ForcedProgressEvents and configure a filter for these events.

   Polling the status provided by BIOS to Intel AMT: The BIOS notifies Intel AMT with the boot progress. Before the BIOS passes control to execute the PBA or ISO, the BIOS updates Intel AMT with Success or Failed. The Management Console uses the WS-MAN command AMT_BootSettingData.BIOSLastStatus to read this status.

   Using Intel AMT KVM to monitor the boot process

Configuring a Filter for Logging Intel One-Click Recovery Events

Logging Intel One-Click Recovery events in the Intel AMT Event log requires that:

   ForceProgressEvents is set in AMT_BootSettingData.ForcedProgressEvents().

   An Event Filter is configured to log the Intel vendor specific BIOS progress and error events

The following values must be set for an event filter that filters Intel One-Click Recovery events:

   EventSensorType = 0X0F

   EventOffset = 0x03 for vendor specific BIOS error events and 0x05 for BIOS progress events.

The current default event filters log only DMTF-defined BIOS progress and error events: all events with EventSensorType == 0X0F are BIOS progress and error events. This includes filters 6, 7, 9 and 10 (see the table of Intel AMT default event filters). The EventOffset is set to 0x00, 0x01, 0x02, 0x82 which does not include vendor specific events. One of the default filters needs to be modified so that the Intel One-Click Recovery events are also captured. For instance, for the console to update filter 9 so it covers all BIOS error and progress events (if the default filters have not been changed by the console), the console needs to do the following:

1. Enumerate AMT_PETFilterSetting

2. Find filter with PolicyID == 9

3. Verify that EventSensorType = 0X0F

4. Change the EventOffset from 0x02 to 0x0F which is for ANY.

5. Set EnableFilter = True

6. Set LogOnEvent = True

If the filters have already been modified by the console, the console may select any filter that it does not need and then set it to the values required above.

More information on creating event filters

Once the Intel One-Click Recovery flow is complete, the console can set EventOffset back to 0x02 if there is no need to capture other OEM-specific BIOS progress or error events.

Modifying an event filter

Transmitting Parameters from the Console to BIOS via Intel AMT

The management console can pass parameters to the BIOS via Intel AMT (e.g., for Intel One-Click Recovery boot operation). The values in each element need to be in little-endian format, and the entire array must be converted to Base64 format before it is transmitted to Intel AMT. Maximum size before conversion to Base64: 1024 bytes

Each parameter in the array of array of uint8 needs to have the following structure:

     Typedef struct _PARAMETER_TLV {
               PARAMETER_TYPE      Type;     //See table of parameter types below
               uint32                  Length;  // The size in bytes of Value. For a string, this does not include the NULL terminator.
               uint8                   Value[]; // Array of uint8. The content of value is determined by parameterTypeID
          } PARAMETER_TLV;

Parameter Type is defined as:

     Typedef Union {
               uint32 Parameter_Type;
               Struct {
                      uint16 VendorID;        // The ID of the vendor that defined ParameterTypeID. For Intel-defined parameters use 0x8086.
                      uint16 ParameterTypeID; // The type of parameter (see table below)
               }
          } PARAMETER_TYPE;

Parameter Types

The following table lists the Intel parameter types for Intel One-Click Recovery. The OEM/ISV can add their own proprietary parameters, as needed by the BIOS.

 

ParameterTypeID MaximumTypeSize Description Comments
OCR_EFI_NETWORK_DEVICE_PATH = 1 300 (bytes) URI to which the BIOS will boot (can include IP address or FQDN of the HTTPS Server). Mandatory for boot to HTTPS
OCR_EFI_FILE_DEVICE_PATH = 2 300 (bytes) Device path to PBA.efi of type FILEPATH_DEVICE_PATH as defined in UEFI spec Used only when console wishes to specify a device path that was not registered by BIOS with Intel AMT and for which there is no CIM_BootSourceSetting instance.
OCR_EFI_DEVICE_PATH_LEN = 3 UINT16 The length of the device path Mandatory when OCR_EFI_FILE_DEVICE_PATH is provided
OCR_BOOT_IMAGE_ HASH_SHA256 = 4 32 bytes SHA256 hash of the efi boot loader file Optional for boot to HTTPS. Providing the image hash is mandatory when the image is not signed and secure boot cannot be disabled due to BIOS policy. This parameter may appear more than once.
OCR_BOOT_IMAGE_ HASH_SHA384 = 5 48 bytes SHA384 hash of the efi boot loader file Optional for boot to HTTPS. Providing the image hash is mandatory when the image is not signed and secure boot cannot be disabled due to BIOS policy. This parameter may appear more than once.
OCR_BOOT_IMAGE_ HASH_SHA512 = 6 64 bytes SHA512 hash of the efi boot loader file Optional for boot to HTTPS. Providing the image hash is mandatory when the image is not signed and secure boot cannot be disabled due to BIOS policy. This parameter may appear more than once.
OCR_EFI_BOOT_OPTIONAL_DATA = 10 50 bytes Used for passing parameters in binary data format to loaded image Optional
OCR_HTTPS_CERT_SYNC_ROOT_CA = 20 BOOLEAN TRUE: BIOS should sync Root CAs with Intel AMT. FALSE: BIOS should not sync Root CAs with Intel AMT Optional for HTTPS boot. Required if BIOS does not have a root CA for the HTTPS Server certificate configured
OCR_HTTPS_CERT_SERVER_NAME = 21 256 bytes The name to compare with the subject name field in the certificate provided by the HTTPS server Optional for HTTPS boot.
OCR_HTTPS_SERVER_NAME_VERIFY_METHOD = 22 UINT16 The comparison method that should be used by the BIOS when it verifies that the subject name field in the Server certificate matches the value set in OCR_HTTPS_CERT_SERVER_NAME parameter. ValueMap={1, 2, 3, ..} Values={ FullName, DomainSuffix, Other} For values 1 and 2: Compare the Common Name (CN) attribute. Supported for UTF8 encoded Common Name only. Optional for HTTPS boot
OCR_HTTPS_SERVER_CERT_HASH_SHA256 = 23 32 bytes The hash of the HTTPS Server certificate. Can be provided by the console instead of, or in addition to, the following 3 parameters: OCR_HTTPS_CERT_SYNC_ROOT_CA, OCR_HTTPS_CERT_SERVER_NAME and OCR_HTTPS_SERVER_NAME_VERIFY_METHOD
OCR_HTTPS_SERVER_CERT_HASH_SHA384 = 24 48 bytes The hash of the HTTPS Server certificate. Can be provided by the console instead of, or in addition to, the following 3 parameters: OCR_HTTPS_CERT_SYNC_ROOT_CA, OCR_HTTPS_CERT_SERVER_NAME and OCR_HTTPS_SERVER_NAME_VERIFY_METHOD
OCR_HTTPS_SERVER_CERT_HASH_SHA512 = 25 64 bytes The hash of the HTTPS Server certificate. Can be provided by the console instead of, or in addition to, the following 3 parameters: OCR_HTTPS_CERT_SYNC_ROOT_CA, OCR_HTTPS_CERT_SERVER_NAME and OCR_HTTPS_SERVER_NAME_VERIFY_METHOD
OCR_HTTPS_REQUEST_TIMEOUT = 30 UINT16 Timeout in seconds for the UEFI HTTP Request. When set to 0, BIOS uses its default timeout. Optional for HTTPS boot
OCR_HTTPS_DIGEST_USER_NAME = 40 MAX_USER_NAME = 16 bytes In UTF-8 encoding. Optional for HTTPS boot
OCR_HTTPS_DIGEST_PASSWORD = 41 MAX_PASSWORD_LENGTH = 16 bytes In UTF-8 encoding. Optional for HTTPS boot

See Also:

   Retrieve the Boot Configuration Settings

   Get the Boot Configuration for the next Boot

   Get Boot Details for a Boot Configuration Setting Instance

   Set or Disable Boot Configuration Settings for the Next Boot

Copyright © 2006-2022, Intel Corporation. All rights reserved.