# vHSM Agent
The `vHSM Agent` is designed to simplify and scale your integration with vHSM, especially for environments where modifying application code isn't ideal. The agent works by rendering secrets into files or environment variables, allowing your applications to consume them seamlessly without directly interacting with vHSM APIs.
### What is vHSM Agent?
The `vHSM agent` is a lightweight client daemon that acts as a secure intermediary between your application and vHSM. It supports a variety of use cases to streamline secret management and authentication workflows.
#### Key Features:
* **Auto-Auth**: Automatically authenticate to vHSM and manage the lifecycle of the token.
* **API Proxy**: Proxy vHSM's API with optional or enforced use of Auto-Auth tokens.
* **Caching**: Locally cache tokens and leased secrets, including automatic renewal.
* **Windows Service**: Support for running the agent as a Windows Service.
* **Templating**: Render secrets from vHSM into files using user-defined templates.
* **Process Supervisor Mode**: Launch applications with secrets injected as environment variables.
### Auto-Auth
The `Auto-Auth` feature handles the initial authentication to Vault automatically and renews tokens when needed.
* Configuration is done via the `auto_auth` stanza.
* Works in a variety of environments (e.g., AWS, Kubernetes).
### API Proxy
The agent can act as a proxy to vHSM’s API through a configured listener. You can optionally force the use of the `Auto-Auth` token for all proxy requests.
* Configured via a `listener` block and an `api_proxy` stanza.
### Caching
vHSM Agent provides client-side caching of:
* Token creation responses.
* Leased secrets.
* Renewals of these tokens and leases.
### Quit API (Optional)
The agent supports a special API to shut itself down:
* Endpoint: `POST /agent/v1/quit`
* Disabled by default; enable via `agent_api` stanza in the `listener`.
{% hint style="info" %}
**Note**: Enable only on trusted interfaces. No auth is required to access this endpoint.
{% endhint %}
### Starting the vHSM Agent
Follow these steps to start the agent:
1. Download the vHSM binary on the client system such as a VM, container, or others.
2. Create a configuration file `agent-config.hcl` or `agent-config.json`, see [Example Configuration](#example-configuration).
3. Run the agent using:
```bash
vhsm agent -config=/etc/vault/agent-config.hcl
```
Additional Help
```bash
vhsm agent -h
```
#### Configuration Options
You can pass the `-config` flag in three ways:
* A single file: `-config=/path/to/file.hcl`
* Multiple files: `-config=file1 -config=file2`
* A directory: `-config=/path/to/config/dir`
#### Vault Agent Command Options
| Option | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-log-level` *(string: "info")* | Log verbosity level. Supported values (in order of descending detail): `trace`, `debug`, `info`, `warn`, and `error`. Can also be set via the `VAULT_LOG_LEVEL` environment variable. |
| `-log-format` *(string: "standard")* | Log format. Supported values: `standard` and `json`. Can also be set via the `VAULT_LOG_FORMAT` environment variable. |
| `-log-file` | Writes all Vault Agent log messages to a file. The value is used as a prefix for the log file name; a timestamp is appended.
- If the value ends with a path separator (/), vault-agent will be appended.
- If the filename has no extension, .log is appended.
- Example: setting -log-file=/var/log/ results in /var/log/vault-agent-{timestamp}.log.
Can be combined with -log-rotate-bytes and -log-rotate-duration for log rotation.
|
| `-log-rotate-bytes` | Specifies the **maximum file size (in bytes)** before the log is rotated. No limit is applied if this is not set. |
| `-log-rotate-duration` | Specifies the maximum duration a log file is written to before rotation. Accepts duration values like 30s, 1h, etc.
Default: 24h.
|
| `-log-rotate-max-files` | Specifies the maximum number of old log files to keep.
- Default: 0 (no deletion).
- Set to -1 to discard old logs when a new one is created.
|
### Example Configuration
Here’s a sample configuration showing the various features in use:
```hcl
pid_file = "./pidfile"
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 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/vault/server.key.ctmpl"
destination = "/etc/vault/server.key"
}
template {
source = "/etc/vault/server.crt.ctmpl"
destination = "/etc/vault/server.crt"
}
```