vHSM Agent

Learn about using Agent for rendering secrets into files or environment variables, allowing your applications to consume them seamlessly without directly interacting with vHSM APIs.

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.

Note: Enable only on trusted interfaces. No auth is required to access this endpoint.

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.
3. Run the agent using:

   vhsm agent -config=/etc/vault/agent-config.hcl

Additional Help

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:

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"
}