Developer Guide

  • 2021.2
  • 06/11/2021
  • Public

Create an Environment File

The environment file contains information about the tool environment. This file must be a well-formatted JavaScript* Object Notation (JSON) document containing all required information. This page covers:

JSON Description

The file defines two main types of information:
  • Information that allows the host to connect to the target system via SSH, such as hostname, username, password, and port.
  • Information that allows the tool to create and apply the capsule.
It is important to escape JSON-specific characters such as double-quotes and backslash:
Escape symbol
Environment file example:
{ "targets": { "target_name_1": { "target_info": "...", "processor_name": "AUTO", "reboot_command": "reboot", "connections_settings": { "hostname": "...", "username": "...", "password": "...", "port": 22, "connection_timeout":5, "reconnection_timeout":10, "reconnection_attempts":10 }, "capsule_settings": { "capsule_generate_script": "bash ./host_scripts/", "capsule_apply_script": "bash /usr/share/tcc_tools/tools/target_scripts/", "target_capsules_path": "/tmp/capsules", } } } }
The following table describes each field:
List of target systems in the following format: “target_name”: {TARGET_SECTION}
Unique identifier for the target system.
Optional information about the target system, such as a unique name to help you identify the system. The tool does not use this field in the tuning flow.
Optional. Processor name of the target system. For automated detection of the processor, type
. To specify the processor name: For 11th Gen Intel® Core™ processors, type
. For Intel Atom® x6000E Series processors, type
. (Default:
) In this release, the field is used by the data streams optimizer but not by the cache configurator.
Valid values are
or an empty line if no reboot is required. You can also create your own script (for example, to check something before rebooting) and input the command here.
Section that stores all connection-related data: hostname, username, password, and so on.
IP address or hostname of the target system.
Username to connect to the target system via SSH. An Authenticated User must have read/write permissions for the capsule location; for data streams optimizer, also must be able to execute the workload validation script.
Password to connect to the target system via SSH. If the SSH connection to the target system does not need a password or if you have created an SSH key and installed the SSH key on the target system, you can leave the password field empty. The tool also accepts environment files that do not contain a password field.
Port to connect to the target system via SSH.
Wait time before the SSH connection between the host and target system is considered failed, in seconds.
Delay between the next attempt to reconnect the host and target system via SSH, in seconds.
Optional. The maximum number of SSH reconnection attempts. Possible value is an integer from 1 to 255. (Default: 10)
Capsule-related information: script paths and target capsule path.
Command-line executable that generates the capsules on the host system. For more information about this script, see Capsule Create Script.
Command-line executable that applies the capsules to the target system. For more information about this script, see Capsule Apply Script.
Directory on the target system that will be used to store capsules from the host.

Tool Flow

For the reference implementation, the environment file affects the following steps:
  • Capsule-related fields are used to create, move, and apply the capsule.
  • SSH-related fields are used to connect the host to the target system via SSH.
  • The
    is used to reboot the target system.


The cache configurator changes the configuration of the target system by updating the firmware. For the reference implementation, the tool uses a capsule (binary file) to update certain areas of the BIOS, known as “subregions.”
The sample environment file defines all capsule-related fields for the reference BIOS. If you are using the reference BIOS, you do not need to update those fields.
For the Host-Target Reference Implementation, the capsule-related fields affect the following steps:
  1. When it is time to create the capsule, the tool runs the script specified in the
  2. The tool moves the capsule to the location identified in the
  3. The tool applies the capsule via the command specified in the

Using Your Own Bootloader

The reference implementation uses scripts to support UEFI BIOS. In this release, you cannot use other bootloaders.
If you are using a UEFI BIOS other than the reference BIOS binary, you can use the subregion capsule tool to sign the capsule and subregion. In this case, you will need to generate and enroll your certificate or public key into the BIOS. The flow requires working with your BIOS vendor to enroll the certificates/keys. The subregion data and the capsule must always be signed when generated to ensure the integrity of the generated capsule. The signature of the signed capsule and its payload (signed subregion data) will be authenticated by the BIOS before it is consumed.
When using an Intel-provided BIOS binary with Intel CRB/RVP, the authentication can be turned off, since users may not have the ability to provision their keys.


The tool provides samples in the following directory:
If you decide to copy the environment file to another location on your host system, be sure to change the relative paths in the environment file or replace them with full paths.
When you are ready to create your own file, you can make a copy of the example and modify it as needed.

Product and Performance Information


Performance varies by use, configuration and other factors. Learn more at