--- layout: docs page_title: Vault Agent description: |- Vault Agent is a client-side daemon that can be used to perform some Vault functionality automatically. --- # Vault Agent Vault Agent is a client daemon that provides the following features: - [Auto-Auth][autoauth] - Automatically authenticate to Vault and manage the token renewal process for locally-retrieved dynamic secrets. - [Caching][caching] - Allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens. - [Windows Service][winsvc] - Allows running the Vault Agent as a Windows service. - [Templating][template] - Allows rendering of user supplied templates by Vault Agent, using the token generated by the Auto-Auth step. To get help, run: ```shell-session $ vault agent -h ``` ## Auto-Auth Vault Agent allows for easy authentication to Vault in a wide variety of environments. Please see the [Auto-Auth docs][autoauth] for information. Auto-Auth functionality takes place within an `auto_auth` configuration stanza. ## Caching Vault 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][caching] for information. ## Configuration These are the currently-available general configuration option: - `vault` ([vault][vault]: ) - Specifies the remote Vault server the Agent connects to. - `auto_auth` ([auto_auth][autoauth]: ) - Specifies the method and other options used for Auto-Auth functionality. - `cache` ([cache][caching]: ) - Specifies options used for Caching functionality. - `listener` ([listener][listener]: ) - Specifies the addresses and ports on which the Agent will respond to requests. - `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 - `template` ([template][template]: ) - Specifies options used for templating Vault secrets to files. - `template_config` ([template_config][template-config]: ) - Specifies templating engine behavior. ### vault Stanza There can at most be one top level `vault` block and it has the following configuration entries: - `address` `(string: )` - The address of the Vault server. This should be a complete URL such as `https://127.0.0.1:8200`. This value can be overridden by setting the `VAULT_ADDR` environment variable. - `ca_cert` `(string: )` - Path on the local disk to a single PEM-encoded CA certificate to verify the Vault server's SSL certificate. This value can be overridden by setting the `VAULT_CACERT` environment variable. - `ca_path` `(string: )` - Path on the local disk to a directory of PEM-encoded CA certificates to verify the Vault server's SSL certificate. This value can be overridden by setting the `VAULT_CAPATH` environment variable. - `client_cert` `(string: )` - Path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the Vault server. This value can be overridden by setting the `VAULT_CLIENT_CERT` environment variable. - `client_key` `(string: )` - 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: )` - Disable verification of TLS certificates. Using this option is highly discouraged as it decreases the security of data transmissions to and from the Vault server. This value can be overridden by setting the `VAULT_SKIP_VERIFY` environment variable. - `tls_server_name` `(string: )` - 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 Vault requests are handled, whether these requests are issued in order to render templates, or are proxied requests coming from the proxy cache subsystem. Auto-auth, however, has its own notion of retrying and is not affected by this section. For requests from the templating engine, 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_after_retry_failure` from the [`template_config`][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 couple of 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"), as well as 412 ("precondition failed"); 412 is used in Vault Enterprise 1.7+ to indicate a stale read due to eventual consistency. 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 Agent [persistent cache][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 Agent supports one or more [listener][listener_main] stanzas. In addition to the standard listener configuration, an Agent's listener configuration also supports an additional optional entry: - `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`. ## Example Configuration An example configuration, with very contrived values, follows: ```python pid_file = "./pidfile" vault { address = "https://127.0.0.1:8200" retry { num_retries = 5 } } auto_auth { method "aws" { mount_path = "auth/aws-subaccount" config = { type = "iam" 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 { use_auto_auth_token = true } listener "unix" { address = "/path/to/socket" tls_disable = true } listener "tcp" { address = "127.0.0.1:8100" tls_disable = true } template { source = "/etc/vault/server.key.ctmpl" destination = "/etc/vault/server.key" } template { source = "/etc/vault/server.crt.ctmpl" destination = "/etc/vault/server.crt" } ``` [vault]: /docs/agent#vault-stanza [autoauth]: /docs/agent/autoauth [caching]: /docs/agent/caching [persistent-cache]: /docs/agent/caching/persistent-caches [template]: /docs/agent/template [template-config]: /docs/agent/template-config [listener]: /docs/agent#listener-stanza [listener_main]: /docs/configuration/listener/tcp [winsvc]: /docs/agent/winsvc