Skip to main content

unix listener

The Unix listener configures OpenBao to listen on the specified Unix domain socket.

listener "unix" {
  address = "/run/openbao.sock"
}

The listener stanza may be specified more than once to make OpenBao listen on multiple sockets.

unix listener parameters​

  • address (string: "/run/openbao.sock", <required>) – Specifies the address to bind the Unix socket.

  • socket_mode (string: "", <optional>) – Changes the access permissions and the special mode flags of the Unix socket.

  • socket_user (string: "", <optional>) – Changes the user owner of the Unix socket.

  • socket_group (string: "", <optional>) – Changes the group owner of the Unix socket.

  • disable_unauthed_rekey_endpoints (bool: false) - Whether to disable requests to the legacy unauthenticated rekey endpoints (under /sys/rekey/* and /sys/rekey-recovery-key/*). These are a security risk to leave exposed on public listeners.

    warning

    In OpenBao v2.4.0, this parameter will default to true, forbidding any calls to the unauthenticated rekey endpoints. This will be a breaking change.

telemetry parameters​

  • unauthenticated_metrics_access (bool: false) - If set to true, allows unauthenticated access to the /v1/sys/metrics endpoint.

  • disallow_metrics (bool: false) - Specifies if the /v1/sys/metrics endpoint is disabled on this listener. This is useful for hardening a listener that handles general client traffic, preventing API clients from scraping metrics.

  • metrics_only (bool: false) - Specifies if the listener should only serve the /v1/sys/metrics endpoint, blocking all other API requests. This is useful for creating a dedicated, secure listener for monitoring systems.

  • metrics_path (string: "") - If present, specifies an alternative path the metrics should be reported on. Only allowed in conjunction with metrics_only=true.

unix listener examples​

Listening on multiple sockets​

This example shows OpenBao listening on a specified socket, as well as the default.

listener "unix" {}

listener "unix" {
  address = "/var/run/openbao.sock"
}

Listening on multiple interfaces​

This example shows OpenBao listening on TCP localhost, as well as Unix socket.

listener "unix" {
  address = "/var/run/openbao.sock"
}

listener "tcp" {
  address = "127.0.0.1:8200"
}

Configuring permissions​

This example shows changing access permissions and ownership of the Unix socket.

listener "unix" {
  address = "/var/run/openbao.sock"
  socket_mode = "644"
  socket_user = "1000"
  socket_group = "1000"
}

Configuring Metrics Security and Access​

This example configures two UNIX socket listeners to separate API traffic from metrics monitoring. Access to these sockets is controlled by file system permissions. The first socket handles API requests with metrics disabled, while a second socket is dedicated only to serving metrics for monitoring tools.

# Primary listener for general API traffic via a UNIX socket
# Metrics are disabled for security.
listener "unix" {
  path        = "/var/run/openbao.sock"
  socket_mode = "0660"
  telemetry {
    disallow_metrics = true
  }
}

# Dedicated listener for monitoring systems (e.g., Prometheus)
# Only serves metrics and blocks all other requests.
listener "unix" {
  path        = "/var/run/openbao-metrics.sock"
  socket_mode = "0660"
  telemetry {
    metrics_only = true
  }
}