Configuration
Keylime is configured by files installed by default in /etc/keylime.
The files are loaded following a hierarchical order in which the values set for
the options can be overridden by the next level.
For each component, a base configuration file (e.g.
/etc/keylime/verifier.conf) is loaded, setting the base values.
Then, the configuration snippets placed in the respective directory (e.g.
/etc/keylime/verifier.conf.d) are loaded, overriding the previously set
values.
Finally, options can be overridden via environment variables.
The following components can be configured:
Component |
Default base config file |
Default snippets directory |
|---|---|---|
agent |
|
|
verifier |
|
|
registrar |
|
|
tenant |
|
|
ca |
|
|
logging |
|
|
Note
For push-model attestation, the verifier must be configured with mode = push
in the [verifier] section. The push-model agent uses the same
/etc/keylime/agent.conf file (TOML format) but with additional options such
as verifier_url and attestation_interval_seconds. See
Push-Model Attestation for details.
The next sections contain details of the configuration files
Configuration file processing order
The configurations are loaded in the following order:
Default (hardcoded) option values
Base configuration options, overriding previously set values
By default, located in
/etc/keylime/<component>.conffor each component
Configuration snippets, overriding previously set values
By default, located in
/etc/keylime/<component>.conf.dfor each componentThe configuration snippets are loaded in lexicographic order
Environment variables, overriding previously set values
The environment variables are in the form
KEYLIME_{COMPONENT}_[SECTION_]{OPTION}, for exampleKEYLIME_VERIFIER_SERVER_KEY.
Configuration file format
The configuration files for all components are written in INI format, except for the agent which is written in TOML format.
Each component contains a main section named after the component name (for
historical reasons). For example, the main section of verifier.conf is
[verifier].
Override configurations via configuration snippets
To override a configuration option using a configuration snippet, simply create
a file in the component’s configuration snippets directory (e.g.
/etc/keylime/verifier.conf.d to override options from
/etc/keylime/verifier.conf).
Note that the configuration snippets are loaded and processed in
lexicographic order, keeping the last value set for each option.
It is recommended to use a numeric prefix for the files to control the order in
which they should be processed (e.g. 001-custom.conf).
The configuration snippets need the section to be explicitly provided, meaning that the snippets are required to be valid INI (or TOML in the case of the agent) files.
For example, the following snippet placed in
/etc/keylime/verifier.conf.d/0001-ip.conf can override the default verifier ip
address:
[verifier]
ip = 172.30.1.10
For the verifier listener, the ip option can also be set to a wildcard
address to bind to all interfaces. Use 0.0.0.0 for all IPv4 interfaces:
[verifier]
ip = 0.0.0.0
or :: for all IPv6 interfaces (which on most dual-stack hosts also accepts
incoming IPv4 connections):
[verifier]
ip = ::
These wildcard addresses only control where the verifier listens for incoming connections. Other components still need a concrete verifier address or DNS name when they connect to the verifier.
Override configurations via environment variables
It is possible to override configuration options by setting the desired value
through environment variables.
The environment variables are defined as
KEYLIME_{COMPONENT}_[SECTION_]{OPTION}
The section can be omitted if the option to set is located in the main section (the section named after the component). Otherwise the section is required.
For example, to set the webhook_url option from the [revocations] section in
the verifier.conf file, the environment variable to set is
KEYLIME_VERIFIER_REVOCATIONS_WEBHOOK_URL.
To set an option located in the main section, for example the server_key
option from the [verifier] section in the verifier.conf, the environment
variable to set is KEYLIME_VERIFIER_SERVER_KEY (note that the section can be
omitted).
Configuration upgrades
When updating keylime, it is also recommended to upgrade the configuration to make sure that the used configuration is compatible with the keylime version.
The keylime_upgrade_config script is installed by default with the keylime
components, and is the script that performs the configuration upgrade following
the upgrade mappings and templates.
By default, the configuration templates are installed in
/usr/share/keylime/templates. For each configuration version a respective
directory is installed in the templates directory.
The keylime_upgrade_config will take the current configuration files as input
(by default from /etc/keylime/). For each component, the version of the
configuration file is checked against the available upgrade template versions to
decide if an upgrade is necessary or not. In case an upgrade is not necessary,
meaning all the components configuration files are up-to-date, the script does
not modify the configuration files.
For each component that needs upgrade, the script will process all the
transformations needed by each configuration version. For example, suppose the
installed configuration file is in version 1.0 and there are upgrade templates
available for the versions 2.0 and 3.0. The upgrade script will process the
transformations defined from the version 1.0 to the version 2.0 and then
from the version 2.0 to the version 3.0.
For each configuration upgrade template version, there are the following files:
mapping.json: This file defines the transformations that should be performed, mapping the configuration option from the older version to the configuration options in the new version. If the mapping has theupdatetype, then it describes operations to transform the previous version to the next (adding, removing, or replacing options)<component>.j2: These are templates for the configuration files. It defines the output format for the configuration file for each component.adjust.py: This is an optional script that defines special adjustments that cannot be specified through themapping.jsonfile. It is executed after the mapping transformations are applied.
The main goal of the upgrade script is to keep the configuration changes made by the user and keep the configuration files up-to-date. For new options, the default values are used.
The configuration upgrade script keylime_upgrade_script
Run keylime_upgrade_config --help for the description of the supported
options.
When executed by the root user, the default output directory for the
keylime_upgrade_config script is the /etc/keylime directory. The existing
configuration files are kept intact as backup and renamed with the .bkp extension
appended to the file names.
In case the --output option is provided to the keylime_upgrade_config
script, the configuration files are written even when they were already
up-to-date using the available templates. It can be seen as a way to force the
creation of the configuration files, fitting the options read into the new
templates.
Passing the --debug option to the keylime_upgrade_config, the logging level
is set to DEBUG, making the script more verbose.
The templates directory to be processed can be passed via the --templates
option. If provided, the script will try to find the configuration upgrade
templates in the provided path instead of the default location
(/usr/share/keylime/templates)
To output files only for a subset of the components, the --component can be
provided multiple times.
To override input files (by default the /etc/keylime/<component>.conf for each
component), the --input option can be passed multiple times. Unknown
components are ignored.
To stop the processing in a target version, set the target version with the
--version option.
To ignore the input files and use the default value for all options, the
--defaults option can be provided
Finally, to process a single mapping file, the mapping file path can be passed
via the --mapping option
Attestation Models: Pull vs Push
Keylime supports two attestation models that determine how the verifier obtains attestation evidence from agents:
Pull Model (Traditional)
In the pull model, the verifier actively polls agents at regular intervals to retrieve attestation evidence. This is the default and traditional mode of operation.
Use Cases:
Traditional deployments where the verifier can directly connect to agents
Environments with stable network connectivity
When you need fine-grained control over attestation frequency
Push Model (Agent-Driven)
In the push model, agents periodically push their attestation evidence to the verifier. This mode is useful when the verifier cannot directly connect to agents (e.g., agents behind firewalls or NAT).
Use Cases:
Agents deployed behind firewalls or NAT
Cloud or edge deployments where direct connectivity is limited
When agents need to control their own attestation schedule
Note
The push model options were introduced in configuration version 2.5 and require the push attestation agent.
Configuration Options Reference
This section provides comprehensive tables of all configuration options for each Keylime component, including default values, environment variable overrides, and applicability to pull/push attestation models.
Verifier Configuration (/etc/keylime/verifier.conf)
Common Options (Both Models)
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.6 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
|
2.5 |
|
|
(empty) |
2.5 |
|
|
|
2.6 |
|
Pull Model Specific Options
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
Push Model Specific Options
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
Revocations Section
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
Registrar Configuration (/etc/keylime/registrar.conf)
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.6 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.1 |
|
|
|
2.4 |
|
|
|
2.5 |
|
|
(empty) |
2.5 |
|
Tenant Configuration (/etc/keylime/tenant.conf)
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
(empty) |
2.0 |
|
|
(empty) |
2.0 |
|
CA Configuration (/etc/keylime/ca.conf)
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
Agent Configuration (/etc/keylime/agent.conf)
Warning
The Python agent is deprecated and will be removed in version 7.0.0! Please migrate to the Rust-based agent from https://github.com/keylime/rust-keylime/
Common Options (Both Models)
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.0 |
|
|
|
2.4 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.0 |
|
|
|
2.1 |
|
|
|
2.1 |
|
|
|
2.1 |
|
|
|
2.1 |
|
|
|
2.3 |
|
|
|
2.3 |
|
|
|
2.3 |
|
|
|
2.3 |
|
|
|
2.1 |
|
|
|
2.1 |
|
|
|
2.0 |
|
|
|
2.2 |
|
|
|
2.2 |
|
Push Model Specific Options
Option |
Default |
Version |
Environment Variable |
|---|---|---|---|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
|
|
2.5 |
|
Logging Configuration (/etc/keylime/logging.conf)
The logging configuration follows Python’s standard logging configuration format.
See the Python logging documentation for details on configuring handlers, formatters,
and loggers. The version option can be overridden with KEYLIME_LOGGING_VERSION.
Configuration Version History
Version |
Changes |
|---|---|
2.0 |
Base configuration structure, pull model support |
2.1 |
Added IAK/IDevID support, |
2.2 |
Added |
2.3 |
Added persisted key handles for IAK/IDevID ( |
2.4 |
Added |
2.5 |
Push model support: Added |
2.6 |
Added |
For detailed information on all configuration options for each component, refer
to the configuration files in /etc/keylime/ and their inline documentation.