Agent Configuration

Learn about configuring an Agent for vHSM

General Configuration Options

Option	Description
vault	Specifies the remote Vault server the Agent connects to.
auto_auth	Specifies the method and other options used for Auto-Auth functionality.
api_proxy	Specifies options used for API Proxy functionality.
cache	Specifies options used for Caching functionality.
listener	Specifies the addresses and ports on which the Agent will respond to requests.
pid_file	Path to the file in which the agent's Process ID (PID) should be stored.
exit_after_auth	If true, the agent exits with code 0 after a single successful auth.
disable_idle_connections	List of features (auto-auth, caching, proxying, templating) for which idle connections are disabled. Can be overridden by VAULT_AGENT_DISABLE_IDLE_CONNECTIONS.
disable_keep_alives	List of features (auto-auth, caching, proxying, templating) for which keep-alives are disabled. Can be overridden by VAULT_AGENT_DISABLE_KEEP_ALIVES.
template	Specifies options used for templating Vault secrets to files.
template_config	Specifies templating engine behavior.
exec	Options for the Vault agent to run a child process that injects secrets via env_template.
env_template	Multiple blocks accepted for templating Vault secrets as environment variables.
telemetry	Specifies the telemetry reporting system.
log_level	Equivalent to -log-level CLI flag.
log_format	Equivalent to -log-format CLI flag.
log_file	Equivalent to -log-file CLI flag.
log_rotate_duration	Equivalent to -log-rotate-duration CLI flag.
log_rotate_bytes	Equivalent to -log-rotate-bytes CLI flag.
log_rotate_max_files	Equivalent to -log-rotate-max-files CLI flag.

Note: On SIGHUP, vHSM Agent reloads TLS and log level configurations.

Vault Stanza

Option	Description
address	Vault server address (FQDN or IP). Overridable via VAULT_ADDR.
ca_cert	Path to a PEM-encoded CA certificate. Overridable via VAULT_CACERT.
ca_path	Directory of CA certificates. Overridable via VAULT_CAPATH.
client_cert	Path to PEM-encoded client certificate. Overridable via VAULT_CLIENT_CERT.
client_key	Path to matching private key for client_cert. Overridable via VAULT_CLIENT_KEY.
tls_skip_verify	Disable TLS certificate verification (not recommended). Overridable via VAULT_SKIP_VERIFY.
tls_server_name	TLS SNI server name. Overridable via VAULT_TLS_SERVER_NAME.

Retry Stanza (Inside vault stanza)

Option	Description
num_retries	Number of retries for failing requests. Default: 12. Set -1 to disable retries. Overridable via VAULT_MAX_RETRIES.

Note: Templating and caching subsystems may use different retry and backoff logic.

Listener Stanza

Option	Description
require_request_header	If true, requires X-Vault-Request: true header on all incoming HTTP requests.
role	Role of listener. Values: default (all APIs) or metrics_only.
agent_api	Optional stanza for managing agent-specific API endpoints.

Agent API Stanza (Inside listener)

Option	Description
enable_quit	Enables the quit API if set to true.

Telemetry Stanza

Metric	Description	Type
vault.agent.auth.failure	Number of authentication failures.	Counter
vault.agent.auth.success	Number of authentication successes.	Counter
vault.agent.proxy.success	Number of successfully proxied requests.	Counter
vault.agent.proxy.client_error	Vault returned errors during requests.	Counter
vault.agent.proxy.error	Failed proxy attempts by the agent.	Counter
vault.agent.cache.hit	Number of cache hits.	Counter
vault.agent.cache.miss	Number of cache misses.