What is OpenBao Agent?

OpenBao Agent aims to remove the initial hurdle to adopt OpenBao by providing a more scalable and simpler way for applications to integrate with OpenBao, by providing the ability to render templates containing the secrets required by your application, without requiring changes to your application.

OpenBao Agent workflow

OpenBao Agent is a client daemon that provides the following features:

Auto-Auth - Automatically authenticate to OpenBao and manage the token renewal process for locally-retrieved dynamic secrets.
API Proxy - Allows OpenBao Agent to act as a proxy for OpenBao's API, optionally using (or forcing the use of) the Auto-Auth token.
Caching - Allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens. The agent also manages the renewals of the cached tokens and leases.
Windows Service - Allows running the OpenBao Agent as a Windows service.
Templating - Allows rendering of user-supplied templates by OpenBao Agent, using the token generated by the Auto-Auth step.
Process Supervisor Mode - Runs a child process with OpenBao secrets injected as environment variables.

Auto-Auth

OpenBao Agent allows easy authentication to OpenBao in a wide variety of environments. Please see the Auto-Auth docs for information.

Auto-Auth functionality takes place within an auto_auth configuration stanza.

API proxy

OpenBao Agent can act as an API proxy for OpenBao, allowing you to talk to OpenBao's API via a listener defined for Agent. It can be configured to optionally allow or force the automatic use of the Auto-Auth token for these requests. Please see the API Proxy docs for more information.

API Proxy functionality takes place within a defined listener, and its behaviour can be configured with an api_proxy stanza.

Caching

OpenBao Agent allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens. Please see the Caching docs for information.

API

Quit

This endpoint triggers shutdown of the agent. By default, it is disabled, and can be enabled per listener using the agent_api stanza. It is recommended to only enable this on trusted interfaces, as it does not require any authorization to use.

Method	Path
`POST`	`/agent/v1/quit`

Cache

See the caching page for details on the cache API.

Configuration

Command options

-log-level (string: "info") - Log verbosity level. Supported values (in order of descending detail) are trace, debug, info, warn, and error. This can also be specified via the BAO_LOG_LEVEL environment variable.
-log-format (string: "standard") - Log format. Supported values are standard and json. This can also be specified via the BAO_LOG_FORMAT environment variable.

-log-file - the absolute path where OpenBao Agent should save log messages. Paths that end with a path separator use the default file name, agent.log. Paths that do not end with a file extension use the default .log extension. If the log file rotates, OpenBao Agent appends the current timestamp to the file name at the time of rotation. For example:

`log-file`	Full log file	Rotated log file
`/var/log`	`/var/log/agent.log`	`/var/log/agent-{timestamp}.log`
`/var/log/my-diary`	`/var/log/my-diary.log`	`/var/log/my-diary-{timestamp}.log`
`/var/log/my-diary.txt`	`/var/log/my-diary.txt`	`/var/log/my-diary-{timestamp}.txt`

-log-rotate-bytes - to specify the number of bytes that should be written to a log before it needs to be rotated. Unless specified, there is no limit to the number of bytes that can be written to a log file.
-log-rotate-duration - to specify the maximum duration a log should be written to before it needs to be rotated. Must be a duration value such as 30s. Defaults to 24h.
-log-rotate-max-files - to specify the maximum number of older log file archives to keep. Defaults to 0 (no files are ever deleted). Set to -1 to discard old log files when a new one is created.

Configuration file options

These are the currently-available general configuration options:

vault (vault: <optional>) - Specifies the remote OpenBao server the Agent connects to.
auto_auth (auto_auth: <optional>) - Specifies the method and other options used for Auto-Auth functionality.
api_proxy (api_proxy: <optional>) - Specifies options used for API Proxy functionality.
cache (cache: <optional>) - Specifies options used for Caching functionality.
listener (listener: <optional>) - Specifies the addresses and ports on which the Agent will respond to requests.

warning

Note: On SIGHUP (kill -SIGHUP $(pidof bao)), OpenBao Agent will attempt to reload listener TLS configuration. This method can be used to refresh certificates used by OpenBao Agent without having to restart its process.

pid_file (string: "") - Path to the file in which the agent's Process ID (PID) should be stored
exit_after_auth (bool: false) - If set to true, the agent will exit with code 0 after a single successful auth, where success means that a token was retrieved and all sinks successfully wrote it
disable_idle_connections (string array: []) - A list of strings that disables idle connections for various features in OpenBao Agent. Valid values include: auto-auth, caching, proxying, and templating. proxying configures this for the API proxy, which is identical in function to caching for historical reasons. Can also be configured by setting the VAULT_AGENT_DISABLE_IDLE_CONNECTIONS environment variable as a comma separated string. This environment variable will override any values found in a configuration file.
disable_keep_alives (string array: []) - A list of strings that disables keep alives for various features in OpenBao Agent. Valid values include: auto-auth, caching, proxying, and templating. proxying configures this for the API proxy, which is identical in function to caching for historical reasons. Can also be configured by setting the VAULT_AGENT_DISABLE_KEEP_ALIVES environment variable as a comma separated string. This environment variable will override any values found in a configuration file.
template (template: <optional>) - Specifies options used for templating OpenBao secrets to files.
template_config (template_config: <optional>) - Specifies templating engine behavior.
exec (exec: <optional>) - Specifies options for OpenBao agent to run a child process that injects secrets (via env_template stanzas) as environment variables.
env_template (env_template: <optional>) - Multiple blocks accepted. Each block contains the options used for templating OpenBao secrets as environment variables via the process supervisor mode.
telemetry (telemetry: <optional>) – Specifies the telemetry reporting system. See the telemetry Stanza section below for a list of metrics specific to Agent.
log_level - Equivalent to the -log-level command-line flag.

warning

Note: On SIGHUP (kill -SIGHUP $(pidof bao)), OpenBao Agent will update the log level to the value specified by configuration file (including overriding values set using CLI or environment variable parameters).

log_format - Equivalent to the -log-format command-line flag.
log_file - Equivalent to the -log-file command-line flag.
log_rotate_duration - Equivalent to the -log-rotate-duration command-line flag.
log_rotate_bytes - Equivalent to the -log-rotate-bytes command-line flag.
log_rotate_max_files - Equivalent to the -log-rotate-max-files command-line flag.

vault stanza

There can at most be one top level vault block, and it has the following configuration entries:

address (string: \<optional>) - The address of the OpenBao server to connect to. This should be a Fully Qualified Domain Name (FQDN) or IP such as https://openbao-fqdn:8200 or https://172.16.9.8:8200. This value can be overridden by setting the VAULT_ADDR environment variable.
ca_cert (string: \<optional>) - Path on the local disk to a single PEM-encoded CA certificate to verify the OpenBao server's SSL certificate. This value can be overridden by setting the VAULT_CACERT environment variable.
ca_path (string: \<optional>) - Path on the local disk to a directory of PEM-encoded CA certificates to verify the OpenBao server's SSL certificate. This value can be overridden by setting the VAULT_CAPATH environment variable.
client_cert (string: \<optional>) - Path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the OpenBao server. This value can be overridden by setting the VAULT_CLIENT_CERT environment variable.
client_key (string: \<optional>) - Path on the local disk to a single PEM-encoded private key matching the client certificate from client_cert. This value can be overridden by setting the VAULT_CLIENT_KEY environment variable.
tls_skip_verify (string: \<optional>) - Disable verification of TLS certificates. Using this option is highly discouraged as it decreases the security of data transmissions to and from the OpenBao server. This value can be overridden by setting the VAULT_SKIP_VERIFY environment variable.
tls_server_name (string: \<optional>) - Name to use as the SNI host when connecting via TLS. This value can be overridden by setting the VAULT_TLS_SERVER_NAME environment variable.

retry stanza

The vault stanza may contain a retry stanza that controls how failing OpenBao requests are handled, whether these requests are issued in order to render templates, or are proxied requests coming from the api proxy subsystem. Auto-auth, however, has its own notion of retrying and is not affected by this section.

For requests from the templating engine, Vaul Agent will reset its retry counter and perform retries again once all retries are exhausted. This means that templating will retry on failures indefinitely unless exit_on_retry_failure from the template_config stanza is set to true.

Here are the options for the retry stanza:

num_retries (int: 12) - Specify how many times a failing request will be retried. A value of 0 translates to the default, i.e. 12 retries. A value of -1 disables retries. The environment variable VAULT_MAX_RETRIES overrides this setting.

There are a few subtleties to be aware of here. First, requests originating from the proxy cache will only be retried if they resulted in specific HTTP result codes: any 50x code except 501 ("not implemented"). Requests coming from the template subsystem are retried regardless of the failure.

Second, templating retries may be performed by both the templating engine and the cache proxy if OpenBao Agent persistent cache is enabled. This is due to the fact that templating requests go through the cache proxy when persistence is enabled.

Third, the backoff algorithm used to set the time between retries differs for the template and cache subsystems. This is a technical limitation we hope to address in the future.

listener stanza

OpenBao Agent supports one or more listener stanzas. Listeners can be configured with or without caching, but will use the cache if it has been configured, and will enable the API proxy. In addition to the standard listener configuration, an Agent's listener configuration also supports the following:

require_request_header (bool: false) - Require that all incoming HTTP requests on this listener must have an X-Vault-Request: true header entry. Using this option offers an additional layer of protection from Server Side Request Forgery attacks. Requests on the listener that do not have the proper X-Vault-Request header will fail, with a HTTP response status code of 412: Precondition Failed.
role (string: default) - role determines which APIs the listener serves. It can be configured to metrics_only to serve only metrics, or the default role, default, which serves everything (including metrics). The require_request_header does not apply to metrics_only listeners.
agent_api (agent_api: <optional>) - Manages optional Agent API endpoints.

agent_api stanza

enable_quit (bool: false) - If set to true, the agent will enable the quit API.

telemetry stanza

OpenBao Agent supports the telemetry stanza and collects various runtime metrics about its performance, the auto-auth and the cache status:

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 requests successfully proxied	counter
`vault.agent.proxy.client_error`	Number of requests for which OpenBao returned an error	counter
`vault.agent.proxy.error`	Number of requests the agent failed to proxy	counter
`vault.agent.cache.hit`	Number of cache hits	counter
`vault.agent.cache.miss`	Number of cache misses	counter

Start OpenBao agent

To run OpenBao Agent:

Download the OpenBao binary where the client application runs (virtual machine, Kubernetes pod, etc.)
Create an OpenBao Agent configuration file. (See the Example Configuration section for an example configuration.)
Start an OpenBao Agent with the configuration file.

Example:
```
$ bao agent -config=/etc/openbao/agent-config.hcl
```
To get help, run:
```
$ bao agent -h
```

As with OpenBao, the -config flag can be used in three different ways:

Use the flag once to name the path to a single specific configuration file.
Use the flag multiple times to name multiple configuration files, which will be composed at runtime.
Use the flag to name a directory of configuration files, the contents of which will be composed at runtime.

Example configuration

An example configuration, with very contrived values, follows:

pid_file = "./pidfile"

vault {
  address = "https://openbao-fqdn:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "kubernetes" {
    config = {
      role = "foobar"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/file-foo"
    }
  }

  sink "file" {
    wrap_ttl = "5m"
    aad_env_var = "TEST_AAD_ENV"
    dh_type = "curve25519"
    dh_path = "/tmp/file-foo-dhpath2"
    config = {
      path = "/tmp/file-bar"
    }
  }
}

cache {
  // An empty cache stanza still enables caching
}

api_proxy {
  use_auto_auth_token = true
}

listener "unix" {
  address = "/path/to/socket"
  tls_disable = true

  agent_api {
    enable_quit = true
  }
}

listener "tcp" {
  address = "127.0.0.1:8100"
  tls_disable = true
}

template {
  source = "/etc/openbao/server.key.ctmpl"
  destination = "/etc/openbao/server.key"
}

template {
  source = "/etc/openbao/server.crt.ctmpl"
  destination = "/etc/openbao/server.crt"
}

Auto-Auth​

API proxy​

Caching​

API​

Quit​

Cache​

Configuration​

Command options​

Configuration file options​

vault stanza​

retry stanza​

listener stanza​

agent_api stanza​

telemetry stanza​

Start OpenBao agent​

Example configuration​