Skip to main content

OpenBao configuration

Outside of development mode, OpenBao servers are configured using a file. The format of this file is HCL or JSON.

Enabling the file permissions check via the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK allows OpenBao to check if the config directory and files are owned by the user running OpenBao. It also checks if there are no write or execute permissions for group or others. OpenBao allows operators to specify the user and permissions of the plugin directory and binaries using parameters plugin_file_uid and plugin_file_permissions in config if an operator needs those to be different. This check is disabled by default.

An example configuration is shown below:

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

After the configuration is written, use the -config flag with bao server to specify where the configuration is.

Parameters​

  • storage ([StorageBackend][storage-backend]: <required>) – Configures the storage backend where OpenBao data is stored. Please see the storage backends documentation for the full list of available storage backends. Running OpenBao in HA mode would require coordination semantics to be supported by the backend. If the storage backend supports HA coordination, HA backend options can also be specified in this parameter block. If not, a separate ha_storage parameter should be configured with a backend that supports HA, along with corresponding HA options.

  • ha_storage ([StorageBackend][storage-backend]: nil) – Configures the storage backend where OpenBao HA coordination will take place. This must be an HA-supporting backend. If not set, HA will be attempted on the backend given in the storage parameter. This parameter is not required if the storage backend supports HA coordination and if HA specific options are already specified with storage parameter.

  • listener ([Listener][listener]: <required>) – Configures how OpenBao is listening for API requests.

  • user_lockout ([UserLockout][user-lockout]: nil) – Configures the user-lockout behaviour for failed logins. For more information, please see the user lockout configuration documentation.

  • seal ([Seal][seal]: nil) – Configures the seal type to use for auto-unsealing, as well as for [seal wrapping][sealwrap] as an additional layer of data protection.

  • cluster_name (string: <generated>) – Specifies the identifier for the OpenBao cluster. If omitted, OpenBao will generate a value.

  • cache_size (string: "131072") – Specifies the size of the read cache used by the physical storage subsystem. The value is in number of entries, so the total cache size depends on the size of stored entries.

  • disable_cache (bool: false) – Disables all caches within OpenBao, including the read cache used by the physical storage subsystem. This will very significantly impact performance.

  • plugin_directory (string: "") – A directory from which plugins are allowed to be loaded. OpenBao must have permission to read files in this directory to successfully load plugins, and the value cannot be a symbolic link.

    Enabling the file permissions check via the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK allows OpenBao to check if the config directory and files are owned by the user running OpenBao. It also checks if there are no write or execute permissions for group or others. OpenBao allows operators to specify the user and permissions of the plugin directory and binaries using parameters plugin_file_uid and plugin_file_permissions in config if an operator needs those to be different. This check is disabled by default.

  • plugin_file_uid (integer: 0) – Uid of the plugin directories and plugin binaries if they are owned by an user other than the user running OpenBao. This only needs to be set if the file permissions check is enabled via the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK.

  • plugin_file_permissions (string: "") – Octal permission string of the plugin directories and plugin binaries if they have write or execute permissions for group or others. This only needs to be set if the file permissions check is enabled via the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK.

  • telemetry ([Telemetry][telemetry]: <none>) – Specifies the telemetry reporting system.

  • default_lease_ttl (string: "768h") – Specifies the default lease duration for tokens and secrets. This is specified using a label suffix like "30s" or "1h". This value cannot be larger than max_lease_ttl.

  • max_lease_ttl (string: "768h") – Specifies the maximum possible lease duration for tokens and secrets. This is specified using a label suffix like "30s" or "1h". Individual mounts can override this value by tuning the mount with the max-lease-ttl flag of the auth or secret commands.

  • default_max_request_duration (string: "90s") – Specifies the default maximum request duration allowed before OpenBao cancels the request. This can be overridden per listener via the max_request_duration value.

  • detect_deadlocks (string: "") - A comma separated string that specifies the internal mutex locks that should be monitored for potential deadlocks. Currently supported values include statelock, quotas and expiration which will cause "POTENTIAL DEADLOCK:" to be logged when an attempt at a core state lock appears to be deadlocked. Enabling this can have a negative effect on performance due to the tracking of each lock attempt.

  • raw_storage_endpoint (bool: false) – Enables the sys/raw endpoint which allows the decryption/encryption of raw data into and out of the security barrier. This is a highly privileged endpoint.

  • introspection_endpoint (bool: false) - Enables the sys/internal/inspect endpoint which allows users with a root token or sudo privileges to inspect certain subsystems inside OpenBao.

  • ui (bool: false) – Enables the built-in web UI, which is available on all listeners (address + port) at the /ui path. Browsers accessing the standard OpenBao API address will automatically redirect there. This can also be provided via the environment variable VAULT_UI. For more information, please see the ui configuration documentation.

  • pid_file (string: "") - Path to the file in which the OpenBao server's Process ID (PID) should be stored.

  • enable_response_header_hostname (bool: false) - Enables the addition of an HTTP header in all of OpenBao's HTTP responses: X-Vault-Hostname. This will contain the host name of the OpenBao node that serviced the HTTP request. This information is best effort and is not guaranteed to be present. If this configuration option is enabled and the X-Vault-Hostname header is not present in a response, it means there was some kind of error retrieving the host name from the operating system.

  • enable_response_header_raft_node_id (bool: false) - Enables the addition of an HTTP header in all of OpenBao's HTTP responses: X-Vault-Raft-Node-ID. If OpenBao is participating in a Raft cluster (i.e. using integrated storage), this header will contain the Raft node ID of the OpenBao node that serviced the HTTP request. If OpenBao is not participating in a Raft cluster, this header will be omitted, whether this configuration option is enabled or not.

  • 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 BAO_LOG_LEVEL environment variable.

warning

Note: On SIGHUP (sudo kill -s HUP pid of bao), if a valid value is specified, OpenBao will update the existing log level, overriding (even if specified) both the CLI flag and environment variable.

warning

Note: Not all parts of OpenBao's logging can have its log level be changed dynamically this way; in particular, secrets/auth plugins are currently not updated dynamically.

High availability parameters​

The following parameters are used on backends that support high availability.

  • api_addr (string: "") – Specifies the address (full URL) to advertise to other OpenBao servers in the cluster for client redirection. This value is also used for plugin backends. This can also be provided via the environment variable VAULT_API_ADDR. In general this should be set as a full URL that points to the value of the listener address. This can be dynamically defined with a go-sockaddr template that is resolved at runtime.

  • cluster_addr (string: "") – Specifies the address to advertise to other OpenBao servers in the cluster for request forwarding. This can also be provided via the environment variable VAULT_CLUSTER_ADDR. This is a full URL, like api_addr, but OpenBao will ignore the scheme (all cluster members always use TLS with a private key/certificate). This can be dynamically defined with a go-sockaddr template that is resolved at runtime.

  • disable_clustering (bool: false) – Specifies whether clustering features such as request forwarding are enabled. Setting this to true on one OpenBao node will disable these features only when that node is the active node. This parameter cannot be set to true if raft is the storage type.