/sys/mounts

The /sys/mounts endpoint is used to manage secrets engines in OpenBao.

List mounted secrets engines

This endpoints lists all the mounted secrets engines.

Method	Path
GET	/sys/mounts

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/mounts

Sample response

{
  "request_id": "48d2c601-97a0-3904-f549-4fcbc740d718",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "cubbyhole/": {
      "accessor": "cubbyhole_eb4503de",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0
      },
      "description": "per-token private secret storage",
      "external_entropy_access": false,
      "local": true,
      "options": null,
      "plugin_version": "",
      "running_plugin_version": "v1.12.0+builtin.openbao",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "cubbyhole",
      "uuid": "79ddaa52-fa07-6f19-653a-f0777f6439fd"
    },
    "identity/": {
      "accessor": "identity_68a03448",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0
      },
      "description": "identity store",
      "external_entropy_access": false,
      "local": false,
      "options": null,
      "plugin_version": "",
      "running_plugin_version": "v1.12.0+builtin.openbao",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "identity",
      "uuid": "45f79a67-58f7-3f87-892c-9032084e7801"
    },
    "secret/": {
      "accessor": "kv_aedd93c1",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0
      },
      "deprecation_status": "supported",
      "description": "key/value secret storage",
      "external_entropy_access": false,
      "local": false,
      "options": {
        "version": "2"
      },
      "plugin_version": "",
      "running_plugin_version": "v0.13.0+builtin",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "kv",
      "uuid": "8074a73f-6921-c0cd-589a-016405dc46ec"
    },
    "sys/": {
      "accessor": "system_f8df2902",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0,
        "passthrough_request_headers": ["Accept"]
      },
      "description": "system endpoints used for control, policy and debugging",
      "external_entropy_access": false,
      "local": false,
      "options": null,
      "plugin_version": "",
      "running_plugin_version": "v1.12.0+builtin.openbao",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "system",
      "uuid": "c79f4f66-4cfa-4521-9d31-b1238b0a6800"
    }
  },
  "warnings": null
}

default_lease_ttl or max_lease_ttl values of 0 mean that the system defaults are used by this backend.

Enable secrets engine

This endpoint enables a new secrets engine at the given path.

Method	Path
POST	/sys/mounts/:path

Parameters

• path (string: <required>) – Specifies the path where the secrets engine will be mounted. This is specified as part of the URL.

danger

NOTE: Use ASCII printable characters to specify the desired path.

• type (string: <required>) – Specifies the type of the backend, such as "kv".

• description (string: "") – Specifies the human-friendly description of the mount.

• config (map<string|string>: nil) – Specifies configuration options for this mount; if set on a specific mount, values will override any global defaults (e.g. the system TTL/Max TTL)

  • default_lease_ttl (string: "") - The default lease duration, specified as a string duration like "5s" or "30m".

  • max_lease_ttl (string: "") - The maximum lease duration, specified as a string duration like "5s" or "30m".

  • force_no_cache (bool: false) - Disable caching.

  • audit_non_hmac_request_keys (array: []) - List of keys that will not be HMAC'd by audit devices in the request data object.

  • audit_non_hmac_response_keys (array: []) - List of keys that will not be HMAC'd by audit devices in the response data object.

  • listing_visibility (string: "") - Specifies whether to show this mount in the UI-specific listing endpoint. Valid values are "unauth" or "hidden". If not set, behaves like "hidden".

  • passthrough_request_headers (array: []) - List of headers to allow and pass from the request to the plugin.

  • allowed_response_headers (array: []) - List of headers to allow, allowing a plugin to include them in the response.

  • plugin_version (string: "") – Specifies the semantic version of the plugin to use, e.g. "v1.0.0". If unspecified, the server will select any matching unversioned plugin that may have been registered, the latest versioned plugin registered, or a built-in plugin in that order of precendence.

• options (map<string|string>: nil) - Specifies mount type specific options that are passed to the backend.

  Key/Value (KV)

  • version (string: "1") - The version of the KV to mount. Set to "2" for mount KV v2.

Sample payload

{
  "type": "kv",
  "config": {
    "force_no_cache": true
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/mounts/my-mount

Disable secrets engine

This endpoint disables the mount point specified in the URL.

Method	Path
DELETE	/sys/mounts/:path	204 (empty body)

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/mounts/my-mount

Force disable

Because disabling a secrets engine revokes secrets associated with this mount, possible errors can prevent the secrets engine from being disabled if the revocation fails.

The best way to resolve this is to figure out the underlying issue and then disable the secrets engine once the underlying issue is resolved. Often, this can be as simple as increasing the timeout (in the event of timeout errors).

For recovery situations where the secret was manually removed from the secrets backing service, one can force a secrets engine disable in OpenBao by performing a force revoke on the mount prefix, followed by a secrets disable when that completes. If the underlying secrets were not manually cleaned up, this method might result in dangling credentials. This is meant for extreme circumstances.

Get the configuration of a secret engine

This endpoint returns the configuration of a specific secret engine.

Method	Path
GET	/sys/mounts/:path

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/mounts/cubbyhole

Sample response

{
  "config": {
    "default_lease_ttl": 0,
    "force_no_cache": false,
    "max_lease_ttl": 0
  },
  "description": "per-token private secret storage",
  "accessor": "cubbyhole_db85f061",
  "external_entropy_access": false,
  "options": null,
  "uuid": "9c0e211a-904d-e41d-e1a2-7f1ff2bb8461",
  "type": "cubbyhole",
  "local": true,
  "seal_wrap": false,
  "request_id": "efdab917-ade2-1802-b8fa-fe2e6486d4e5",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "accessor": "cubbyhole_db85f061",
    "config": {
      "default_lease_ttl": 0,
      "force_no_cache": false,
      "max_lease_ttl": 0
    },
    "description": "per-token private secret storage",
    "external_entropy_access": false,
    "local": true,
    "options": null,
    "plugin_version": "",
    "running_plugin_version": "v1.12.0+builtin.openbao",
    "running_sha256": "",
    "seal_wrap": false,
    "type": "cubbyhole",
    "uuid": "9c0e211a-904d-e41d-e1a2-7f1ff2bb8461"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Read mount configuration

This endpoint reads the given mount's configuration. Unlike the mounts endpoint, this will return the current time in seconds for each TTL, which may be the system default or a mount-specific value.

Method	Path
GET	/sys/mounts/:path/tune

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/mounts/my-mount/tune

Sample response

{
  "default_lease_ttl": 3600,
  "max_lease_ttl": 7200,
  "force_no_cache": false
}

Tune mount configuration

This endpoint tunes configuration parameters for a given mount point.

Method	Path
POST	/sys/mounts/:path/tune

Parameters

• default_lease_ttl (int: 0) – Specifies the default time-to-live. This overrides the global default. A value of 0 is equivalent to the system default TTL.

• max_lease_ttl (int: 0) – Specifies the maximum time-to-live. This overrides the global default. A value of 0 are equivalent and set to the system max TTL.

• description (string: "") – Specifies the description of the mount. This overrides the current stored value, if any.

• audit_non_hmac_request_keys (array: []) - Specifies the list of keys that will not be HMAC'd by audit devices in the request data object.

• audit_non_hmac_response_keys (array: []) - Specifies the list of keys that will not be HMAC'd by audit devices in the response data object.

• listing_visibility (string: "") - Specifies whether to show this mount in the UI-specific listing endpoint. Valid values are "unauth" or "hidden". If not set, behaves like "hidden".

• passthrough_request_headers (array: []) - List of headers to allow and pass from the request to the plugin.

• allowed_response_headers (array: []) - List of headers to allow, allowing a plugin to include them in the response.

• plugin_version (string: "") – Specifies the semantic version of the plugin to use, e.g. "v1.0.0". Changes will not take effect until the mount is reloaded.

Sample payload

{
  "default_lease_ttl": 1800,
  "max_lease_ttl": 3600
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/mounts/my-mount/tune