keylime_registrar

Keylime registrar service for agent registration

Manual section:: 8
Author:: Keylime Developers
Date:: September 2025

SYNOPSIS

keylime_registrar

(Most operations require root privileges, use with sudo)

DESCRIPTION

The registrar is a long-running service used by agents. It maintains its own database where it stores data of registered agents. The service does not accept command-line options; behavior is configured via configuration files and environment variables, and is managed by keylime tenant.

CONFIGURATION

Primary configuration is read from /etc/keylime/registrar.conf (or an override via env). All options are under the [registrar] section.

Essential configuration options:

ip: Bind address
port: HTTP port
tls_port: HTTPS port
tls_dir: TLS material location (generate for auto-generate CA, keys, certs under $KEYLIME_DIR/reg_ca, default for shared verifier CA under $KEYLIME_DIR/cv_ca)
server_key, server_key_password, server_cert, trusted_client_ca: TLS files
database_url: SQLAlchemy URL; value sqlite maps to $KEYLIME_DIR/reg_data.sqlite
database_pool_sz_ovfl: Pool size, overflow (non-sqlite)
max_workers: Maximum worker processes; actual count is min(cpu_count, max_workers) (0 = no limit, default 16)
auto_migrate_db: Apply DB migrations on startup
max_upload_size: Request body limit (bytes)
tpm_identity: Allowed identity (default, ek_cert_or_iak_idevid, ek_cert, iak_idevid)
malformed_cert_action: warn (default), reject, or ignore
durable_attestation_import (optional): Python import path to enable Durable Attestation

ENVIRONMENT

KEYLIME_REGISTRAR_CONFIG: Path to registrar.conf (highest priority)
KEYLIME_LOGGING_CONFIG: Path to logging.conf
KEYLIME_DIR: Working directory (default: /var/lib/keylime)
KEYLIME_TEST: on/true/1 enables testing mode (looser checks; WORK_DIR becomes CWD)

FILES

/etc/keylime/registrar.conf: Registrar configuration file
/etc/keylime/logging.conf: Logging configuration
$KEYLIME_DIR/reg_data.sqlite: Database file when database_url = sqlite
$KEYLIME_DIR/reg_ca: TLS certificates when tls_dir = generate
$KEYLIME_DIR/cv_ca: Shared verifier certificates when tls_dir = default

RUNTIME

Start from system install:

sudo keylime_registrar

Start as a systemd service:

systemctl enable --now keylime_registrar

Open firewall ports (adjust if you changed ports):

firewall-cmd --add-port=8890/tcp --add-port=8891/tcp
firewall-cmd --runtime-to-permanent

NOTES

HTTPS is required for routes unless explicitly allowed insecure by the service.
With tls_dir = default, start the verifier before the registrar so the shared CA/certs exist in $KEYLIME_DIR/cv_ca.
The service forks worker processes (default: CPU count, capped by max_workers).
Registrar and verifier may run on the same host or on separate hosts.

BUGS

Report bugs at https://github.com/keylime/keylime/issues

keylime_registrar