vault/website/content/docs/agent-and-proxy/agent/index.mdx

---
layout: docs
page_title: What is Vault Agent?
description: >-
  Vault Agent is a client-side daemon that securely extracts secrets from Vault
  for clients without the complexity of API calls.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# What is Vault Agent?

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

![Vault Agent workflow](/img/vault-agent-workflow.png)

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.
- [API proxy][apiproxy] (deprecated) - Allows Vault Agent to act as a proxy for
  Vault's API. This feature has been deprected from Vault Agent. Use [Vault
  Proxy](/vault/docs/agent-and-proxy/proxy) as a Vault API proxy.
- [Caching][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][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.
- [Process Supervisor Mode][process-supervisor] - Runs a child process with Vault
  secrets injected as environment variables.

## Auto-auth

Vault Agent allows 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.

## API

### Quit

This endpoint triggers shutdown of the agent. By default, it is disabled, and can
be enabled per listener using the [`agent_api`][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](/vault/docs/agent-and-proxy/agent/caching#api) page for details on the cache API.

## Configuration

### Command options

- `-log-level` ((#\_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 `VAULT_LOG_LEVEL` environment variable.

- `-log-format` ((#\_log_format)) `(string: "standard")` - Log format. Supported values
  are `standard` and `json`. This can also be specified via the
  `VAULT_LOG_FORMAT` environment variable.

- `-log-file` ((#\_log_file)) - the absolute path where Vault 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, Vault 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` ((#\_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` ((#\_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` ((#\_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` <code>([vault][vault]: <optional\>)</code> - Specifies the remote Vault server the Agent connects to.

- `auto_auth` <code>([auto_auth][autoauth]: <optional\>)</code> - Specifies the method and other options used for auto-auth functionality.

- `api_proxy` <code>([api_proxy][apiproxy]: <optional\>)</code> - Specifies options used for API proxy functionality.

- `cache` <code>([cache][caching]: <optional\>)</code> - Specifies options used for Caching functionality.

- `listener` <code>([listener][listener]: <optional\>)</code> - Specifies the addresses and ports on which the Agent will respond to requests.

  <Highlight>

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

  </Highlight>

- `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. If you have
  `template` stanzas defined in your agent configuration, the agent
  waits for the configured templates to render successfully before
  exiting. If you use environment templates (`env_template` ) and set
  `exit_after_auth` to true, Vault agent will not run the child processes
  defined in your `exec` stanza.

- `disable_idle_connections` `(string array: [])` - A list of strings that disables idle connections for various features in Vault 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 Vault 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` <code>([template][template]: <optional\>)</code> - Specifies options used for templating Vault secrets to files.

- `template_config` <code>([template_config][template-config]: <optional\>)</code> - Specifies templating engine behavior.

- `exec` <code>([exec][process-supervisor]: <optional\>)</code> - Specifies options for vault agent to run a child process
  that injects secrets (via `env_template` stanzas) as environment variables.

- `env_template` <code>([env_template][template]: <optional\>)</code> - Multiple blocks accepted. Each block contains
  the options used for templating Vault secrets as environment variables via the
  [process supervisor mode](/vault/docs/agent-and-proxy/agent/process-supervisor).

- `telemetry` <code>([telemetry][telemetry]: <optional\>)</code> – Specifies the telemetry
  reporting system. See the [telemetry Stanza](/vault/docs/agent-and-proxy/agent#telemetry-stanza) section below
  for a list of metrics specific to Agent.

- `log_level` - Equivalent to the [`-log-level` command-line flag](#_log_level).

  <Highlight>
  
  On `SIGHUP` (`kill -SIGHUP $(pidof vault)`), Vault Agent will update the log level to the value
  specified by configuration file (including overriding values set using CLI or environment variable parameters).

  </Highlight>

- `log_format` - Equivalent to the [`-log-format` command-line flag](#_log_format).

- `log_file` - Equivalent to the [`-log-file` command-line flag](#_log_file).

- `log_rotate_duration` - Equivalent to the [`-log-rotate-duration` command-line flag](#_log_rotate_duration).

- `log_rotate_bytes` - Equivalent to the [`-log-rotate-bytes` command-line flag](#_log_rotate_bytes).

- `log_rotate_max_files` - Equivalent to the [`-log-rotate-max-files` command-line flag](#_log_rotate_max_files).

### 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 Vault server to
  connect to. This should be a Fully Qualified Domain Name (FQDN) or IP
  such as `https://vault-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 Vault 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 Vault 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 Vault 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 Vault 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.

- `namespace` `(string: <optional>)` - Namespace to use for all of Vault Agent's
  requests to Vault. This can also be specified by command line or environment variable.
  The order of precedence is: this setting lowest, followed by the environment variable
  `VAULT_NAMESPACE`, and then the highest precedence command-line option `-namespace`.
  If none of these are specified, defaults to the root namespace.

#### 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 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`][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"), 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 Vault 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

Vault Agent supports one or more [listener][listener_main] stanzas. Listeners
can be configured with or without [caching][caching], but will use the cache if it
has been configured, and will enable the [API proxy][apiproxy]. 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` <code>([agent_api][agent-api]: <optional\>)</code> - Manages optional Agent API endpoints.

#### agent_api stanza

- `enable_quit` `(bool: false)` - If set to `true`, the agent will enable the [quit](/vault/docs/agent-and-proxy/agent#quit) API.

### telemetry stanza

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

| Metric                           | Description                                          | Type    |
| -------------------------------- | ---------------------------------------------------- | ------- |
| `vault.agent.authenticated`      | Current authentication status (1 - has valid token,  | gauge   |
|                                  | 0 - no valid token)                                  |         |
| `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 Vault 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 |

### IMPORTANT: `VAULT_ADDR` usage

If you export the `VAULT_ADDR` environment variable on the Vault Agent instance, that value takes precedence over the value in the configuration file. The Vault Agent uses that to connect to Vault and this can create an infinite loop where the value of `VAULT_ADDR` is used to make a connection, and the Vault Agent ends up trying to connect to itself instead of the server.

When the connection fails, the Vault Agent increments the port and tries again. The agent repeats these attempts, which leads to port exhaustion.

This problem is a result of the precedence order of the 3 different ways to configure the Vault address. They are, in increasing order of priority:

1. Configuration files
1. Environment variables
1. CLI flags

## Start Vault Agent

To run Vault Agent:

1. [Download](/vault/downloads) the Vault binary where the client application runs
   (virtual machine, Kubernetes pod, etc.)

1. Create a Vault Agent configuration file. (See the [Example
   Configuration](#example-configuration) section for an example configuration.)

1. Start a Vault Agent with the configuration file.

   **Example:**

   ```shell-session
   $ vault agent -config=/etc/vault/agent-config.hcl
   ```

   To get help, run:

   ```shell-session
   $ vault agent -h
   ```

As with Vault, 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:

```hcl
pid_file = "./pidfile"

log_file = "/var/log/vault-agent.log"

vault {
  address = "https://vault-fqdn: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 {
  // An empty cache stanza still enables caching
}

template_config {
  static_secret_render_interval = "10m"
  exit_on_retry_failure = true
  max_connections_per_host = 20
}

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]: /vault/docs/agent-and-proxy/agent#vault-stanza
[autoauth]: /vault/docs/agent-and-proxy/autoauth
[caching]: /vault/docs/agent-and-proxy/agent/caching
[apiproxy]: /vault/docs/agent-and-proxy/agent/apiproxy
[persistent-cache]: /vault/docs/agent-and-proxy/agent/caching/persistent-caches
[template]: /vault/docs/agent-and-proxy/agent/template
[process-supervisor]: /vault/docs/agent-and-proxy/agent/process-supervisor
[template-config]: /vault/docs/agent-and-proxy/agent/template#template-configurations
[agent-api]: /vault/docs/agent-and-proxy/agent/#agent_api-stanza
[listener]: /vault/docs/agent-and-proxy/agent#listener-stanza
[listener_main]: /vault/docs/configuration/listener/tcp
[winsvc]: /vault/docs/agent-and-proxy/agent/winsvc
[telemetry]: /vault/docs/configuration/telemetry