diff --git a/content/vault/global/partials/important-changes/summary-tables/1_21.mdx b/content/vault/global/partials/important-changes/summary-tables/1_21.mdx new file mode 100644 index 0000000000..12ec98c057 --- /dev/null +++ b/content/vault/global/partials/important-changes/summary-tables/1_21.mdx @@ -0,0 +1,15 @@ +### Breaking changes + +Introduced | Recommendations | Edition | Change +---------- | --------------- | ---------- | ------ +1.21.0 | **Yes** | All | [Audiences required for Kubernetes authentication roles](/vault/docs/v1.21.x/updates/important-changes#k8-audience-required) + + +### New behavior + +None. + + +### Known issues + +None. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/api-docs/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/index.mdx index 98a09f8865..298b68d25e 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/index.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/index.mdx @@ -340,4 +340,19 @@ A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests; this can be tuned per `listener` block in Vault's server configuration file. +Vault also supports several listener options to enforce payload size limits for to incoming JSON +request bodies. + +You can configure the payload limits individullly on each listener and give +administrators granular control over the: + +- maximum allowed nesting depth of a JSON object or array (`max_json_depth`). +- maximum allowed length for any single string value in the payload (`max_json_string_value_length`.) +- maximum number of key-value pairs allowed in a single JSON object (`max_json_object_entry_count`). +- maximum number of elements permitted in a single JSON array `max_json_array_element_count`. + +The configuration defaults provide intentionally generous limits to accommodate +a wide range of legitimate use cases while still guarding against most malicious +or malformed requests. + [proxy]: /vault/docs/agent-and-proxy/proxy#listener-stanza diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx index 7c6c586916..310bc9bd4c 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx @@ -8,8 +8,7 @@ description: This is the API documentation for the Vault Cubbyhole secrets engin This is the API documentation for the Vault Cubbyhole secrets engine. For general information about the usage and operation of the Cubbyhole secrets -engine, please see the -[Vault Cubbyhole documentation](/vault/docs/secrets/cubbyhole). +engine, please see the [Vault Cubbyhole documentation](/vault/docs/secrets/cubbyhole). This documentation assumes the Cubbyhole secrets engine is enabled at the `/cubbyhole` path in Vault. Since it is possible to enable secrets engines at @@ -25,8 +24,8 @@ This endpoint retrieves the secret at the specified location. ### Parameters -- `path` `(string: )` – Specifies the path of the secret to read. - This is specified as part of the URL. +- `path` `(string: )` – Specifies the path of the secret to read as + part of the URL. - `read_snapshot_id` `(string: )` - Query parameter specifing a loaded snapshot ID to read the secret. @@ -152,20 +151,17 @@ $ curl \ ## Recover secret -[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot. +[Recover](/vault/docs/sysadmin/snapshots/recover-a-secret) a secret at the +specified location from the given loaded snapshot. -| Method | Path | -|:----------|:-------------------| -| `RECOVER` | `/cubbyhole/:path` | +| Method | Path | +| :----- | :----------------- | +| `POST` | `/cubbyhole/:path?recover_snapshot_id=:recover_snapshot_id` | ### Query parameters -- `path` `(string: )` – The target path of the secrets you want to recover. - -### Headers - -- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path. -- `X-Vault-Recover-Source-Path` `(string: )` - The original path of the data in the snapshot, if different from the target path. +- `path` `(string: )` – The target path of the secrets you want to recover. +- `recover_snapshot_id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path. ### Sample request @@ -173,10 +169,8 @@ $ curl \ ```shell-session $ curl \ --header "X-Vault-Token: ..." \ - --request RECOVER \ - --header "X-Vault-Recover-Snapshot-Id: 2403d301-94f2-46a1-a39d-02be83e2831a" \ - --header "X-Vault-Recover-Source-Path: cubbyhole/my-old-secret" \ - https://127.0.0.1:8200/v1/cubbyhole/my-secret + --request POST \ + https://127.0.0.1:8200/v1/cubbyhole/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a ``` ## Delete secret diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx index e5cc3732d4..62a551ed73 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx @@ -43,12 +43,8 @@ has a number of parameters to further configure a connection. - `connection_url` `(string: )` - Specifies the Snowflake DSN. This field can be templated and supports passing the username and password - parameters in the format `{{field_name}}` when you use password authentication. - If you use root credential rotation for passwords, you must provide a templated - connection URL. Refer to the - [Snowflake secrets engine docs](/vault/docs/secrets/databases/snowflake#setup) - for more information on the connection URL format requirements for different - authentication methods. + parameters in the following format `{{field_name}}`. A templated connection URL is + required when using root credential rotation. - `max_open_connections` `(int: 4)` - Specifies the maximum number of open connections to the database. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx index 4c8f40487e..8633d961f4 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx @@ -28,7 +28,7 @@ This endpoint retrieves the secret at the specified location. - `path` `(string: )` – Specifies the path of the secret to read. This is specified as part of the URL. -- `read_snapshot_id` `(string: "")` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path. +- `recover_snapshot_id` `(string: )` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path. ### Sample requests @@ -83,7 +83,7 @@ this API. - `path` `(string: )` – Specifies the path of the secrets to list. This is specified as part of the URL. -- `read_snapshot_id` `(string: "")` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path. +- `recover_snapshot_id` `(string: )` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path. ### Sample requests @@ -165,30 +165,25 @@ $ curl \ ## Recover secret -[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a secret at the specified location from the given loaded snapshot. +[Recover](/vault/docs/sysadmin/snapshots/recover-a-secret) a secret at the +specified location from the given loaded snapshot. -| Method | Path | -|:----------|:----------------| -| `RECOVER` | `/secret/:path` | +| Method | Path | +| :----- | :------------------------------------------------------- | +| `POST` | `/secret/:path?recover_snapshot_id=:recover_snapshot_id` | ### Query parameters - `path` `(string: )` – The target path of the secrets you want to recover. - -### Headers - -- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path. -- `X-Vault-Recover-Source-Path` `(string: "")` - Optional header specifying the original path of the data in the snapshot, if recovering to a different path than the original path. +- `recover_snapshot_id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path. ### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ - --request RECOVER \ - --header "X-Vault-Recover-Snapshot-Id: 2403d301-94f2-46a1-a39d-02be83e2831a" \ - --header "X-Vault-Recover-Source-Path: secret/my-old-secret" \ - https://127.0.0.1:8200/v1/secret/my-secret + --request POST \ + https://127.0.0.1:8200/v1/secret/my-secret?recover_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a ``` ## Delete secret diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx index 2b7e205de2..d4d643cb15 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx @@ -42,6 +42,8 @@ to search and change entry passwords in LDAP. to use to generate passwords. Note that this accepts the name of the policy, not the policy itself. - `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords. Valid schemas include `openldap`, `ad`, and `racf`. +- `credential_type` `(string: "password")` - The type of password to generate. Valid values include `password` and `phrase`. + When set to `phrase`, the secrets engine will modify the RACF schema for all static roles to manage password phrases instead of passwords. - `userdn` `(string: )` - The base DN under which to perform user search in [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles). For example, `ou=Users,dc=hashicorp,dc=com`. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx index 3b6d745289..61ff1f1e9c 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx @@ -883,6 +883,7 @@ $ curl \ "enabled": true, "external_validation": {}, "last_updated": "2025-05-26T09:59:24-04:00", + "log_level" : "WARN", "restrict_ca_chain_to_issuer": true } } @@ -940,6 +941,8 @@ refer to the [SCEP documentation](/vault/docs/secrets/pki/scep). chain within GetCACert responses. Set `restrict_ca_chain_to_issuer` to `true` to make your PKI configuration compatible with Microsoft Intune. +- `log_level` `(string: "")` - the log level to use for logging SCEP-specific requests. One of standard log levels: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or use the empty string to reset to the vault-level default. (1.20.1+ only) + - `external_validation` `(map[string]map[string]string: "")` - a map specifying configuration for 3rd party validation of SCEP requests. Map keys can be any of the following: diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx index df75b10280..d96bfe7806 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/ssh.mdx @@ -559,8 +559,9 @@ $ curl \ ## Submit CA information This endpoint allows submitting the CA information for the secrets engine via an SSH -key pair. _If you have already set a certificate and key, they will be -overridden._ +key pair. If you call submit CA with an existing certificate or key, the +endpoint returns an error. To update existing values, call the delete CA +information endpoint before calling the submit endpoint. | Method | Path | | :----- | :--------------- | -------------------------- | @@ -639,28 +640,6 @@ This will return a `200` response if `generate_signing_key` was true: } ``` -## Recover CA information - -This endpoint recovers the CA information for the backend via an SSH key pair. - -| Method | Path | -|:----------|:-----------------| -| `RECOVER` | `/ssh/config/ca` | - -### Headers - -- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains SSH CA information. - -### Sample request - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --request RECOVER \ - --header "X-Vault-Recover-Snapshot-Id: 2403d301-94f2-46a1-a39d-02be83e2831a" \ - https://127.0.0.1:8200/v1/ssh/config/ca -``` - ## Delete CA information This endpoint deletes the CA information for the backend via an SSH key pair. @@ -711,11 +690,6 @@ This endpoint reads the configured/generated public key. | :----- | :--------------- | | `GET` | `/ssh/config/ca` | -### Query Parameters - -- `read_snapshot_id` `(string: "")` - Query parameter specifying the ID of a snapshot previously loaded into Vault that an SSH public key. - - ### Sample request ```shell-session @@ -724,15 +698,6 @@ $ curl \ http://127.0.0.1:8200/v1/ssh/config/ca ``` -To read the SSH pubic key from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`: - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - https://127.0.0.1:8200/v1/ssh/config/ca?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a -``` - - ### Sample response ```json diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx index 432aeea2cd..1c88c92414 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx @@ -70,8 +70,7 @@ values set here cannot be changed after key creation. - `aes256-cmac` - AES-256 CMAC (CMAC generation, verification) - `ml-dsa` - ML-DSA (asymmetric) (experimental) - `hybrid` - hybrid signatures combining a post-quantum algorithm and an elliptic curve algorithm (asymmetric) (experimental) - - `aes128-cbc` - AES-128 in CBC mode (symmetric, supports derivation and convergent encryption) - - `aes256-cbc` - AES-256 in CBC mode (symmetric, supports derivation and convergent encryption) + - `slh-dsa` - SLH-DSA (asymmetric) (experimental) ~> **Note**: In FIPS 140-3 mode, the following algorithms are not certified and thus should not be used: `chacha20-poly1305`. @@ -90,7 +89,7 @@ values set here cannot be changed after key creation. ~> **Note**: When key type is `hybrid`, `parameter_set`, `hybrid_key_type_pqc`, and `hybrid_key_type_ec` are required. - ~> **Warning**: ML-DSA and hybrid schemes are considered experimental functionality and + ~> **Warning**: ML-DSA, hybrid, and SLH-DSA schemes are considered experimental functionality and should not be used in production environments. - `key_size` `(int: "0", optional)` - The key size in bytes for algorithms @@ -102,8 +101,14 @@ values set here cannot be changed after key creation. hour. Uses [duration format strings](/vault/docs/concepts/duration-format). - `managed_key_name` `(string: "")` - The name of the managed key to use for this transit key. - `managed_key_id` `(string: "")` - The UUID of the managed key to use for this transit key. -- `parameter_set` `(string:"")` - The parameter set to use for ML-DSA. Required for -ML-DSA and hybrid keys. Valid values are `44`, `65`, and `87`. +- `parameter_set` `(string:"")` - The parameter set to use for ML-DSA or SLH-DSA. + Required for ML-DSA, SLH-DSA, and hybrid keys. Must be one of the following: + - ML-DSA - `44`, `65`, `87` + - SLH-DSA - `slh-dsa-sha2-128s`, `slh-dsa-shake-128s`, `slh-dsa-sha2-128f`, + `slh-dsa-shake-128`, `slh-dsa-sha2-192s`, + `slh-dsa-shake-192s`, `slh-dsa-sha2-192f`, `slh-dsa-shake-192f`, + `slh-dsa-sha2-256s`, `slh-dsa-shake-256s`, + `slh-dsa-sha2-256f`, and `slh-dsa-shake-256f` - `hybrid_key_type_pqc` `(string: "")` - The post-quantum algorithm to use for hybrid signatures. Currently, ML-DSA is the only supported key type. - `hybrid_key_type_ec` `(string: "")` - The elliptic curve algorithm to use for hybrid signatures. @@ -833,9 +838,10 @@ will be returned. - `context` `(string: "")` – Specifies the **base64 encoded** context for key derivation. This is required if key derivation is enabled for this key. -- `key_version` `(int: 0)` – Specifies the version of the key to use for - encryption. If not set, uses the latest version. Must be greater than or - equal to the key's `min_encryption_version`, if set. +- `key_version` `(int: 0)` – Specifies the version of the key to use for the + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `nonce` `(string: "")` – Specifies the **base64 encoded** nonce value. This must be provided if convergent encryption is enabled for this key and the key @@ -892,12 +898,6 @@ will be returned. decrypt) could be indicative of a security breach and should not be ignored. -- `iv` `(string: "")` - Specifies the base64-encoded IV value to use with - AES-CBC. The value must be exactly 128 bits (16 bytes) long and you must - ensure that the IV is never reused for any given context or encryption key. If - you do not provide an IV value, Vault generates and prepends a random IV value - to the ciphertext. - ~>**NOTE:** All plaintext data **must be base64-encoded**. The reason for this requirement is that Vault does not require that the plaintext is "text". It could be a binary file such as a PDF or image. The easiest safe transport @@ -1073,8 +1073,9 @@ functionality to untrusted users or scripts. derivation. This is required if key derivation is enabled. - `key_version` `(int: 0)` – Specifies the version of the key to use for the - operation. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key @@ -1180,6 +1181,11 @@ then made available to trusted users. It is recommended that the default of OAEP be used unless specific backwards compatibility is required. +- `key_version` `(int: 0)` – Specifies the version of the key to use for the + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. + ### Sample payload ```json @@ -1332,8 +1338,9 @@ be used. generate hmac against. This is specified as part of the URL. - `key_version` `(int: 0)` – Specifies the version of the key to use for the - operation. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: @@ -1462,9 +1469,10 @@ supports signing. - `name` `(string: )` – Specifies the name of the encryption key to use for signing. This is specified as part of the URL. -- `key_version` `(int: 0)` – Specifies the version of the key to use for - signing. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. +- `key_version` `(int: 0)` – Specifies the version of the key to use for the + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `hash_algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use for supporting key types (notably, not including `ed25519` which specifies its @@ -1864,8 +1872,9 @@ argument to verify returned CMACs. CMAC function. This is specified as part of the URL. - `key_version` `(int: 0)` – Specifies the version of the key to use for the - operation. If not set, uses the latest version. Must be greater than or equal - to the key's `min_encryption_version`, if set. + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of `input` or `batch_input` must be supplied. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx index bfb207c543..b6d69f6111 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/internal-counters.mdx @@ -211,6 +211,16 @@ The `start_time` in the response is the earliest time there is activity data in the queried period. The `end_time` is the end of the final month of the queried period. +The `/sys/internal/counters` endpoint only supports monthly granularity. As a +result, the `start_time` and `end_time` values in API reponses are normalized to +align with full calendar months. + +Normalization occurs whether you provide explicitly times in the request or use +the defaults: + +- `start_time` normalizes to the start of the month in which the effective `start_time` falls. +- `end_time` normalizes to the end of the month in which the effective `end_time` falls. + - If the `end_date` supplied to the API is the current month, exact activity information will be returned for all months in the queried period. The last element in the `months` response stanza will signify the current month. @@ -305,11 +315,11 @@ When `end_time` falls in the current month or a future month, Vault adjusts the end time to the last day of the previous month and includes the following warning along with the associated counts: - ```json - { - "warning": "end_time parameter can only be used to specify a date until the end of previous month. The value provided for this parameter was in the current month or in the future date and was therefore ignored. The response includes data until the end of the previous month." - } - ``` + ```json + { + "warning": "end_time parameter can only be used to specify a date until the end of previous month. The value provided for this parameter was in the current month or in the future date and was therefore ignored. The response includes data until the end of the previous month." + } + ``` For example, assume the current date is September 25, 2025 and you call the Get Client Count endpoint with `end_time` set to `2025-10-01`: @@ -1283,7 +1293,9 @@ There are a few things to keep in mind while using this API. - The response includes the actual time period covered, which may not exactly match the query parameters due to the month granularity of data or missing -months in the requested time range. +months in the requested time range. Vault always normalizes the effective +`start_time` and `end_time` to full calendar months by adjusting `start_time` to +the beginning of the month and `end_time` to the end of the month. - If the `end_date` supplied to the API is for the current month, the activity information returned by this API will include activity for this month, however @@ -1322,16 +1334,6 @@ $ curl \ http://127.0.0.1:8200/v1/sys/internal/counters/activity/export ``` -### Response fields - -- `token_creation_time` - the creation time of the token used by the client to - perform the request (previously `timestamp`). Token creation time is distinct - from the time the client was created and may lie outside of the queried time - period. - -- `client_first_usage_time` - timestamp representing the earliest usage of the - client during the queried time period. - ### Sample JSON response The entity alias names for userpass in the sample response records below are user-provided. They are @@ -1364,8 +1366,7 @@ single line. "mount_accessor": "auth_userpass_a005db73", "mount_type": "userpass", "mount_path": "auth/userpass/", - "token_creation_time": "2022-07-10T09:33:51Z", - "client_first_used_time":"2024-08-03T12:00:00Z", + "timestamp": "2024-07-10T09:33:51Z", "policies": [ "secret-read", "secret-list", @@ -1397,8 +1398,7 @@ single line. "mount_accessor": "auth_ns_token_e3119312", "mount_type": "ns_token", "mount_path": "auth/token/", - "token_creation_time": "2022-07-08T11:35:23Z", - "client_first_used_time":"2024-08-03T12:00:00Z", + "timestamp": "2024-07-08T11:35:23Z", "policies": [], "entity_metadata": {}, "entity_alias_metadata": {}, @@ -1417,8 +1417,7 @@ single line. "mount_accessor": "auth_ldap_a005db73", "mount_type": "ldap", "mount_path": "auth/ldap/", - "token_creation_time": "2022-07-08T11:47:57Z", - "client_first_used_time":"2024-08-03T12:00:00Z", + "timestamp": "2024-07-08T11:47:57Z", "policies": [ "secret-read" ], @@ -1445,8 +1444,7 @@ single line. "mount_accessor": "auth_userpass_01a6ea85", "mount_type": "userpass", "mount_path": "auth/userpass/", - "token_creation_time": "2022-07-21T14:51:36Z", - "client_first_used_time":"2024-08-03T12:00:00Z", + "timestamp": "2024-07-21T14:51:36Z", "policies": [ "secret-read" ], @@ -1472,8 +1470,7 @@ single line. "mount_accessor": "auth_kubernetes_b596406f", "mount_type": "kubernetes", "mount_path": "auth/kubernetes/", - "token_creation_time": "2022-07-10T09:33:51Z", - "client_first_used_time":"2024-08-03T12:00:00Z", + "timestamp": "2024-07-10T09:33:51Z", "policies": [ "secret-read" ], @@ -1499,8 +1496,7 @@ single line. "mount_accessor": "auth_aws_c223ff01", "mount_type": "aws", "mount_path": "auth/aws/", - "token_creation_time": "2022-07-10T09:33:51Z", - "client_first_used_time":"2024-08-03T12:00:00Z", + "timestamp": "2024-07-10T09:33:51Z", "policies": [ "secret-read" ], @@ -1521,16 +1517,16 @@ will be named using the field name and underlying index (e.g. `policies.0`, `pol (e.g. `entity_metadata.email_address`, `entity_alias_metadata.region`). A flattened field will only be added if at least one record contains it. If a top-level field (e.g. `entity_metadata`) is not populated in any of the records then there will not be any flattened fields of prefix -`entity_metadata.`. +`enttiy_metadata.`. ```text -entity_name,entity_alias_name,client_id,client_type,local_entity_alias,namespace_id,namespace_path,mount_accessor,mount_path,mount_type,token_creation_time,client_first_used_time,entity_alias_custom_metadata.contact_email,entity_alias_custom_metadata.group,entity_alias_custom_metadata.region,entity_metadata.email_address,entity_group_ids.0,policies.0,policies.1,policies.2,policies.4 -admin,admin,3f210722-7210-98e8-1f0d-e6a39ffb29c6,entity,false,root,,auth_userpass_a005db73,auth/userpass/,userpass,2022-07-10T09:33:51Z,2024-08-03T12:00:00Z,admin@example.com,san_francisco,west,admin@example.com,746fbaf9-ffeb-62b9-7f0b-42d79ca0883f,secret-read,secret-list,secret-write,secret-delete -,,590198f7-9178-57d6-c345-48746bb438d8,non-entity-token,false,YWZzu,ns1/a/,auth_ns_token_e3119312,auth/token/,ns_token,2022-07-08T11:35:23Z,2024-08-03T12:00:00Z,,,,,,,, -jdoe,jdoe,665a54bf-8652-c0c5-8121-40adf0d9786a,entity,false,wOsmr,ns1/a,auth_ldap_a005db73,auth/ldap/,ldap,2022-07-08T11:47:57Z,2024-08-03T12:00:00Z,jdoe@example.com,new_york,east,,9f18cd4a-4e64-a2b2-b001-7b6b0dfb1270,secret-read,,, -jdoe,jdoe,0640a8f0-b315-cc8a-c0c2-713f663774df,entity,false,oIiGy,ns1/b,auth_userpass_01a6ea85,auth/userpass/,userpass,2022-07-21T14:51:36Z,2024-08-03T12:00:00Z,,new_york,east,,76a374a1-72fd-30ca-2455-f51dfeaa805e,secret-read,,, +entity_name,entity_alias_name,client_id,client_type,local_entity_alias,namespace_id,namespace_path,mount_accessor,mount_path,mount_type,timestamp,entity_alias_custom_metadata.contact_email,entity_alias_custom_metadata.group,entity_alias_custom_metadata.region,entity_metadata.email_address,entity_group_ids.0,policies.0,policies.1,policies.2,policies.4 +admin,admin,3f210722-7210-98e8-1f0d-e6a39ffb29c6,entity,false,root,,auth_userpass_a005db73,auth/userpass/,userpass,2024-07-10T09:33:51Z,admin@example.com,san_francisco,west,admin@example.com,746fbaf9-ffeb-62b9-7f0b-42d79ca0883f,secret-read,secret-list,secret-write,secret-delete +,,590198f7-9178-57d6-c345-48746bb438d8,non-entity-token,false,YWZzu,ns1/a/,auth_ns_token_e3119312,auth/token/,ns_token,2024-07-08T11:35:23Z,,,,,,,,, +jdoe,jdoe,665a54bf-8652-c0c5-8121-40adf0d9786a,entity,false,wOsmr,ns1/a,auth_ldap_a005db73,auth/ldap/,ldap,2024-07-08T11:47:57Z,jdoe@example.com,new_york,east,,9f18cd4a-4e64-a2b2-b001-7b6b0dfb1270,secret-read,,, +jdoe,jdoe,0640a8f0-b315-cc8a-c0c2-713f663774df,entity,false,oIiGy,ns1/b,auth_userpass_01a6ea85,auth/userpass/,userpass,2024-07-21T14:51:36Z,,new_york,east,,76a374a1-72fd-30ca-2455-f51dfeaa805e,secret-read,,, ``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/secrets-sync.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/secrets-sync.mdx index 40a1a01e44..d1a2183fa3 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/secrets-sync.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/secrets-sync.mdx @@ -476,8 +476,6 @@ This endpoint creates a destination to synchronize action secrets with a GitHub - `name` `(string: )` - Specifies the name for this destination. This is specified as part of the URL. -- `enterprise_url` `(string: "")` - The URL of the GitHub Enterprise Server instance (self-hosted GitHub) to target for syncing secrets. - - `secrets_location` `(string: "repository")` - The GitHub location type of secrets to sync. Must be either `organization` or `repository`. - `access_token` `(string: ""` - Fine-grained or personal access token. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx index dd168f98a6..90ff85f68e 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/storage/raftautosnapshots.mdx @@ -58,20 +58,6 @@ environment variables or files on disk in predefined locations. or "google-gcs". The remaining parameters described below are all specific to the selected `storage_type` and prefixed accordingly. -- `autoload_enabled` `(bool: false)` - Have Vault automatically load the latest snapshot - after it is written. This will replace the previously loaded snapshot. - Note that this does not mean the snapshot is automatically applied to the - cluster, it is just loaded and available for recovery operations. Not allowed - for `storage_type=local`. Can only be enabled for one configuration at a time. - - - -If you set `autoload_enabled=true` for a configuration and that configuration's -`interval` is less than 1 hour, Vault will only load a new snapshot at most once -per hour. - - - #### storage_type=local - `local_max_space` `(integer: )` - For `storage_type=local`, the maximum @@ -154,7 +140,7 @@ parameters in the context of AWS EKS & S3 configuration. - `azure_account_name` `(string)` - Azure account name. -- `azure_auth_mode` `(string)` - One of `shared` or `managed`. +- `azure_auth_mode` `(string)` - One of `shared`, `managed`, or `environment`. If `environment` is set, Azure authentication details are retrieved from the environment variables: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`. - `azure_account_key` `(string)` - Azure account key. Used for `shared` authentication. @@ -298,43 +284,6 @@ $ curl \ } ``` -### Sample response with autoloading enabled - -```json -{ - "data": { - "last_snapshot_end": "2025-08-29T17:41:55+02:00", - "last_snapshot_error": "", - "last_snapshot_start": "2025-08-29T17:41:54+02:00", - "last_snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap", - "loaded_snapshot_expires_at": "2025-09-01T17:41:55+02:00", - "loaded_snapshot_id": "42596c4c-6f4b-c476-8eb0-90546cdda7f3", - "loaded_snapshot_status": "ready", - "next_snapshot_start": "2025-08-29T17:46:55+02:00", - "snapshot_start": "2025-08-29T17:41:55+02:00", - "snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap" - } -} -``` - -### Sample response with an autoloading failure - -```json -{ - "data": { - "last_snapshot_end": "2025-08-29T17:41:55+02:00", - "last_snapshot_error": "", - "last_snapshot_start": "2025-08-29T17:41:54+02:00", - "last_snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap", - "loading_error": "error loading snapshot: a snapshot is loaded already", - "next_snapshot_start": "2025-08-29T17:46:55+02:00", - "snapshot_start": "2025-08-29T17:41:55+02:00", - "snapshot_url": "https://example.com/snapshots/vault-snapshot-1603898241699731000.snap" - } -} -``` - - ## Load a snapshot from an automated snapshot configuration Load a new snapshot into the Vault cluster without overwriting the cluster with diff --git a/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx b/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx index f94a5139dc..bc8afc0d33 100644 --- a/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/about-vault/how-vault-works.mdx @@ -7,7 +7,6 @@ description: >- # How Vault works - Vault is an identity-based secrets and encryption management system that centralizes secret management, rotates old credentials, generates credentials on demand, audits client interactions, and supports regulatory @@ -35,7 +34,12 @@ them access to secrets or stored sensitive data. ## Core Vault workflow -Vault works primarily with tokens and a token is associated to the client's policy. Each policy is path-based and policy rules constrains the actions and accessibility to the paths for each client. With Vault, you can create tokens manually and assign them to your clients, or the clients can log in and obtain a token. The illustration below displays Vault's core workflow. +Vault works primarily with tokens associated to a client policy. The path-based +policy defines rules that constrain the actions and accessibility of the +associated paths for each client. + +Clients can authenticate against Vault to log in and obtain a token automatically +or you can create tokens manually and explicitly assign them to your clients. ![Vault Workflow](/img/vault-workflow-diagram1.png) diff --git a/content/vault/v1.21.x (rc)/content/docs/audit/best-practices.mdx b/content/vault/v1.21.x (rc)/content/docs/audit/best-practices.mdx new file mode 100644 index 0000000000..16b59897fc --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/audit/best-practices.mdx @@ -0,0 +1,104 @@ +--- +layout: docs +page_title: Audit logging best practices +description: Recommendations for setting up audit logging in HashiCorp Vault. +--- + +# Best practices for audit logging + +The following recommendations apply generally to most Vault deployments. You should always independently evaluate whether a given recommendation makes sense in the context of your deployment and use of Vault. + +## Test configuration changes + +Always test your audit logging changes in a non-production environment that closely mirrors your production environment. Your test environment should include performance benchmarking under production-like loads and match in all aspects relevant to the audit logging configuration you want to test. + +## Enable audit devices at cluster initialization + +Enable at least one audit device immediately after you initialize a new Vault cluster, and ensure that the configuration of your audit device is [valid for all Vault cluster nodes](/vault/docs/audit#enabling-and-disabling-audit-devices). + +Audit logging is disabled by default on new Vault clusters. By enabling at least one audit device post-initialization, you ensure that Vault will audit all subsequent API requests, including those for initial cluster configuration and root token revocation. + +## Enable at least two audit devices + +Enable at least two audit devices, of different types, on each Vault cluster. Configure *at least one* of those devices to forward logs to a remote system for analysis and long-term storage. + +Vault does not respond to client requests it cannot log. Enabling at least two audit devices reduces the risk of Vault not responding to client requests when the only audit device becomes partially or fully unavailable. + + + + Vault sends each audit log entry to all enabled devices, and guarantees that it writes the audit log entry successfully to at least one audit device. To ensure that you have a complete record of all API requests and responses, you **must** analyze audit log entries across all configured devices. You may deduplicate audit log entries based on the value of `.request.id`. + + + + + + + +If you enable a `file` audit device, use a dedicated volume or partition for Vault's audit logs to protect against other workloads on the system taking up the disk space intended for your log files. + +Additionally, establish a log rotation process that is appropriate for your organization, deployment, and policies, using a purpose-built system like *logrotate*. Configure your log rotation system to send Vault an `HUP` signal, which causes Vault to start writing audit log entries to the new log file. + + + + When running Vault on a Kubernetes cluster, a common approach is to configure a `file` audit device with `file_path` set to `stdout`. Vault will write audit logs to the standard output for the container, which lets you process the logs with a Kubernetes cluster-level log collector. + + If you choose this approach, we suggest configuring the audit device with a `prefix`, so your log collector can separate audit logs from server logs. + + + + + + + +To configure a `syslog` audit device, you must deploy Vault on Unix, and you must use the default syslog service running on the same host as the Vault server. If you enable a `syslog` audit device, use a TCP listener so that Vault can record large audit log entries that may exceed the size limit of UDP listeners. + + + + + +If you configure a `socket` audit device, configure a local service to bind a Unix socket. + +Socket devices using TCP and UDP listeners can result in lost audit log data if the TCP connection is interrupted or the receiving UDP endpoint becomes unavailable. Using a local socket helps protect against data loss. + + + + + +## Configure audit devices + +Review the configuration options that are specific to the type of audit device, as well as those [common](/vault/api-docs/system/audit#parameters) to all audit device types, and ensure that you configure all audit devices in a way that is appropriate for your organization and deployment. + +In general, we recommend the following options for all audit devices: + +- Set `elide_list_responses = true` to reduce the volume of log data produced by API list requests (see [Eliding list response bodies](/vault/docs/audit#eliding-list-response-bodies)). +- Set `hmac_accessor = false`. A token accessor is generally not considered sensitive information: it does not grant any access to Vault, but rather serves as a unique identifier for a single Vault token. A token accessor enables you to [revoke](/vault/docs/commands/token/revoke) its corresponding Vault token, even when you do not know the token itself. By disabling token accessor hashing, if you identify unusual access patterns in your audit logs, you can quickly revoke the corresponding Vault token through its accessor. + +## Monitor audit device health + +Configure monitoring and alerting on the health of your audit devices through Vault telemetry and device-specific monitoring (such as available disk space, disk IOPS, and log rotation status for `file` type audit devices). + +Vault produces several audit logging [telemetry metrics](/vault/docs/internals/telemetry/metrics/audit). We especially recommend monitoring the following metrics for spikes, which can indicate one or more audit devices failing: + +- [`vault.audit.log_request_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_request_failure) +- [`vault.audit.log_response_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_response_failure) +- [`vault.audit.{DEVICE}.log_request`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_request) +- [`vault.audit.{DEVICE}.log_response`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_response) + +## Configure attribute hashing + +Evaluate which request and response attributes need *not* be [hashed](/vault/docs/audit#hashing-sensitive-values) in the audit logs for each authentication backend and secrets engine mount you configure in Vault. Leave hashing enabled for attributes that are sensitive (e.g., passwords, private keys) or that may be excessively large for your audit log. + +You can disable hashing for individual request and response attributes with the `audit_non_hmac_request_keys` and `audit_non_hmac_response_keys` attributes in the following tuning endpoints: + +- [`/sys/auth/{path}/tune`](/vault/api-docs/system/auth#tune-auth-method) +- [`/sys/mounts/{path}/tune`](/vault/api-docs/system/mounts#tune-mount-configuration) + +## Monitor suspicious activity + +Configure monitoring and alerting for unusual or suspicious activity in your audit logs. Examples of events to monitor include: + +- Root token creation +- Root token usage +- Modifications to audit logging configuration +- Spikes in authentication failures +- Spikes in permission denied failures diff --git a/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx b/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx index a3abf8ffd7..85cc1c4716 100644 --- a/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/audit/index.mdx @@ -4,228 +4,146 @@ page_title: Audit Devices description: Audit devices are mountable devices that log requests and responses in Vault. --- -# Audit devices +# Audit logging -Audit devices are the components in Vault that collectively keep a detailed log of all -requests to Vault, and their responses. Because every operation with Vault is an API -request/response, when using a single audit device, the audit log contains _every_ interaction with -the Vault API, including errors - except for a few paths which do not go via the audit system. +With a small set of [exceptions](#excepted-api-endpoints), Vault audit devices record all API requests and responses in detail. An audit device can be a [file](/vault/docs/audit/file), a [syslog server](/vault/docs/audit/syslog), or a [socket](/vault/docs/audit/socket). -The non-audited paths are: +Refer to the [best practices](/vault/docs/audit/best-practices) page for important considerations before you configure your audit devices. - sys/init - sys/seal-status - sys/seal - sys/step-down - sys/unseal - sys/leader - sys/health - sys/rekey/init - sys/rekey/update - sys/rekey/verify - sys/rekey-recovery-key/init - sys/rekey-recovery-key/update - sys/rekey-recovery-key/verify - sys/storage/raft/bootstrap - sys/storage/raft/join - sys/internal/ui/feature-flags +Audit logs differ from server logs (also known as operational logs). Server logs emit information about the Vault server process, such as process errors and configuration warnings. Audit logs record the details of every request received and response sent by the Vault API. Refer to the [Troubleshoot Vault](/vault/tutorials/monitoring/troubleshooting-vault#vault-server-logs) tutorial for more information about server logs. -and also, if the relevant listener configuration settings allow unauthenticated access: +## Enabling and disabling audit devices ((#enabling-disabling-audit-devices)) - sys/metrics - sys/pprof/* - sys/in-flight-req +When you initialize a new Vault cluster, auditing is disabled. You must enable audit devices with the [Vault API](/vault/api-docs/system/audit#enable-audit-device), [Vault CLI](/vault/docs/commands/audit/enable), or tools like the [Terraform Vault provider](/vault/docs/configuration/programmatic-management). -## Enabling multiple devices +You can set [common](/vault/api-docs/system/audit#common-configuration-options) and type-specific options when you enable a new audit device. -When multiple audit devices are enabled, Vault will attempt to send the audit -logs to all of them. This allows you to not only have redundant copies, but also -a way to check for data tampering in the logs themselves. - -Vault considers a request to be successful if it can log to *at least* one -configured audit device (see: [Blocked Audit -Devices](/vault/docs/audit#blocked-audit-devices) section below). Therefore in order -to build a complete picture of all audited actions, use the aggregate/union of -the logs from each audit device. - -~> Note: It is **highly recommended** that you configure Vault to use multiple audit -devices. Audit failures can prevent Vault from servicing requests, so it is -important to provide at least one other device. +For example, the following command enables a `file` type audit device using a type-specific option to write to the file at `/var/log/vault_audit.log` and two common options to disable [elide list responses](#eliding-list-response-bodies) and [hashing](#hashing-sensitive-values) for token accessors. +```shell-session +$ vault audit enable file \ + file_path=/var/log/vault_audit.log \ + hmac_accessor=false \ + elide_list_responses=true +``` -## Format +Vault replicates audit device configurations to all nodes within a cluster. Vault Enterprise also replicates audit device configurations to performance secondary and disaster recovery secondary clusters unless you configure the audit device as [`local`](/vault/api-docs/system/audit#local) to the cluster. Before you enable an audit device, ensure that all Vault nodes to which the audit device configuration replicates can successfully log to that audit device. -Each line in the audit log is a JSON object. The `type` field specifies what -type of object it is. Currently, only two types exist: `request` and `response`. -The line contains all of the information for any given request and response. By -default, all the sensitive information is first hashed before logging in the -audit logs. +When you disable an audit device, Vault immediately stops writing information to the device, but leaves the existing log information untouched. -## Sensitive information +Once you disable an audit device, you can no longer [compute hashes](#hashing-sensitive-values) for the associated audit log entries. Even if you re-enable the audit device at the same path, Vault creates a new hashing key for the new log entries. -The audit logs contain the full request and response objects for every -interaction with Vault. The request and response can be matched utilizing a -unique identifier assigned to each request. + -Most strings contained within requests and responses are hashed with a salt using HMAC-SHA256. -The purpose of the hash is so that secrets aren't in plaintext within your audit logs. -However, you're still able to check the value of secrets by generating HMACs yourself; -this can be done with the audit device's hash function and salt by using the `/sys/audit-hash` -API endpoint (see the documentation for more details). +## Availability of audit devices ((#enabling-multiple-devices)) -~> Currently, only strings that come from JSON or returned in JSON are -HMAC'd. Other data types, like integers, booleans, and so on, are passed -through in plaintext. We recommend that all sensitive data be provided as string values -inside all JSON sent to Vault (i.e., that integer values are provided in quotes). +Vault sends the audit log entry of every API request and response to all enabled audit devices and guarantees that it saves to at least one of the enabled devices. As a result, if you have audit devices enabled and Vault cannot log information to at least one of the enabled devices, Vault refuses to service the corresponding API request. -While most strings are hashed, Vault can be configured to make some exceptions. -For example in auth methods and secrets engines, users can enable additional exceptions -using the [secrets enable](/vault/docs/commands/secrets/enable) command, and then -[tune](/vault/docs/commands/secrets/tune) it afterward. +When all enabled audit devices become unavailable, Vault in effect becomes unavailable as well. To prevent audit-related unavailability of Vault, HashiCorp recommends that you: -**see also**: +- Enable at least two audit devices. +- Analyze the combined audit log entries across all enabled audit devices to ensure a complete record of every API request and response. -[auth enable](/vault/docs/commands/auth/enable) +Refer to the [best practices](/vault/docs/audit/best-practices) page for additional information. -[auth tune](/vault/docs/commands/auth/tune) +## Hashing sensitive values ((#sensitive-information)) -## Audit request headers +By default, Vault only writes a keyed hash (HMAC-SHA256) of most string values to audit logs to protect the confidentiality of potentially sensitive information. -Use the [Vault API](/vault/api-docs/system/config-auditing) to configure request -headers to monitor and audit headers in incoming client request. +Vault does not hash non-string values, such as integers and booleans. We recommend sending all sensitive data to Vault as string values. For example, encapsulate sensitive integer values in quotes in JSON files: -By default, Vault **does not** encrypt request header values with HMAC if you -[create](/vault/api-docs/system/config-auditing#create-update-audit-request-header) -an exception to allow request headers in the audit log. To encrypt the header -values, you must [configure](/vault/api-docs/system/config-auditing#hmac) the -relevant headers individually. +```json +{ + "name": "sidon", + "age": "12" +} +``` -### Default headers +To calculate the keyed hash of any known value for a given audit device, use the [`/sys/audit-hash`](/vault/api-docs/system/audit-hash) API endpoint. +Alternatively, you can selectively exempt specific request or response attributes from hashing for each [authentication backend](/vault/docs/commands/auth/tune) and [secrets engine](/vault/docs/commands/secrets/tune) you enable. -To help correlate requests across distributed systems, Vault automatically -records the following headers in the audit log: +## Eliding list response bodies -- `correlation-id` -- `x-correlation-id` +Some Vault responses can be very large, especially with `LIST` requests. For example, listing all active leases could return a list that is tens of megabytes long. +Some audit backends cannot process individual audit records of larger sizes. To avoid overloading your audit devices, you can use the [`elide_list_responses`](/vault/api-docs/system/audit#elide_list_responses) option to replace `keys` and `key_info` values in audit log entries for `LIST` responses with the number of objects those fields contain. -To ensure Vault uses HMAC on the header values during logging, set the `hmac` value to true for the `config/auditing/request-headers` API call. +Using `elide_list_responses` [`elide_list_responses`](/vault/api-docs/system/audit#elide_list_responses) improves compatibility with audit devices and reduces the amount of audit data that audit devices ingest, store, and process, while retaining some level of information about what was returned to the client. -For example, to enable HMAC for `correlation-id` +For example, the following partial audit record shows an elided list where the `keys` field returns `4`, instead of the actual list of keys, which would have been `["a", "b", "c", "d"]`: -```shell -curl \ - --header "X-Vault-Token: ..." \ - http://127.0.0.1:8200/v1/sys/config/auditing/request-headers/correlation-id \ - --data '{ "hmac": true }' +```json +{ + "type": "response", + "request": { + "operation": "list" + }, + "response": { + "data": { + "keys": 4 + } + } +} ``` -Another way to identify the source of a request is through the User-Agent request header. -Vault will automatically record this value as `user-agent` within the `headers` of a -request entry within the audit log. - - -## Enabling/Disabling audit devices +## Logging request headers ((#audit-request-headers)) -When a Vault server is first initialized, no auditing is enabled. Audit -devices must be enabled by a root user using `vault audit enable`. +You can use the [`/sys/config/auditing`](/vault/api-docs/system/config-auditing#create-update-audit-request-header) endpoint to configure which incoming client request headers you want Vault to record in the corresponding audit log entries. -When enabling an audit device, options can be passed to it to configure it. -For example, the command below enables the file audit device: +By default, Vault records the following request headers: -```shell-session -$ vault audit enable file file_path=/var/log/vault_audit.log -``` - -In the command above, we passed the "file_path" parameter to specify the path -where the audit log will be written to. Each audit device has its own -set of parameters. See the documentation to the left for more details. +- `User-Agent` +- `Correlation-Id` +- `X-Correlation-Id` -~> Note: Audit device configuration is replicated to all nodes within a -cluster by default, and to performance/DR secondaries for Vault Enterprise clusters. -Before enabling an audit device, ensure that all nodes within the cluster(s) -will be able to successfully log to the audit device to avoid Vault being -blocked from serving requests. -An audit device can be limited to only within the node's cluster with the [`local`](/vault/api-docs/system/audit#local) parameter. +Vault does not hash request header values by default. You can [configure](/vault/api-docs/system/config-auditing#hmac) Vault to apply the [keyed hash](#hashing-sensitive-values) to any request header value you consider sensitive. -When an audit device is disabled, it will stop receiving logs immediately. -The existing logs that it did store are untouched. +## Exempted API endpoints -~> Note: Once an audit device is disabled, you will no longer be able to HMAC values -for comparison with entries in the audit logs. This is true even if you re-enable -the audit device at the same path, as a new salt will be created for hashing. +Vault does not audit requests and responses for the following API endpoints: -## Blocked audit devices - -Audit device logs are critically important and ignoring auditing failures opens an avenue for attack. Vault will not respond to requests when no enabled audit devices can record them. - -Vault can distinguish between two types of audit device failures. +``` +sys/init +sys/seal-status +sys/seal +sys/step-down +sys/unseal +sys/leader +sys/health +sys/rekey/init +sys/rekey/update +sys/rekey/verify +sys/rekey-recovery-key/init +sys/rekey-recovery-key/update +sys/rekey-recovery-key/verify +sys/storage/raft/bootstrap +sys/storage/raft/join +sys/internal/ui/feature-flags +``` -- A blocking failure is one where an attempt to write to the audit device never completes. This is unlikely with a local disk device, but could occure with a network-based audit device. +Additionally, Vault does not audit requests to the following endpoints when the associated listener configuration allows unauthenticated access: -- When multiple audit devices are enabled, if any of them fail in a non-blocking fashion, Vault requests can still complete successfully provided at least one audit device successfully writes the audit record. If any of the audit devices fail in a blocking fashion however, Vault requests will hang until the blocking is resolved. +``` +sys/metrics +sys/pprof/* +sys/in-flight-req +``` -In other words, Vault will not complete any requests until the blocked audit device can write. +## Additional resources -## Tutorial + -Refer to [Blocked Audit Devices](/vault/tutorials/monitoring/blocked-audit-devices) for a step-by-step tutorial. + -## API + - [Recover blocked audit devices](/vault/tutorials/monitoring/blocked-audit-devices) -Audit devices also have a full HTTP API. Please see the [Audit device API -docs](/vault/api-docs/system/audit) for more details. + -## Common configuration options + -@include 'audit-options-common.mdx' + - [Audit API](/vault/api-docs/system/audit) -## Eliding list response bodies + -Some Vault responses can be very large. Primarily, this affects list operations - -as Vault lacks pagination in its APIs, listing a very large collection can result -in a response that is tens of megabytes long. Some audit backends are unable to -process individual audit records of larger sizes. - -The contents of the response for a list operation is often not very interesting; -most contain only a "keys" field, containing a list of IDs. Select API endpoints -additionally return a "key_info" field, a map from ID to some additional -information about the list entry - `identity/entity/id/` is an example of this. -Even in this case, the response to a list operation is usually less-confidential -or public information, for which having the full response in the audit logs is of -lesser importance. - -The `elide_list_responses` audit option provides the flexibility to not write the -full list response data from the audit log, to mitigate the creation of very long -individual audit records. - -When enabled, it affects only audit records of `type=response` and -`request.operation=list`. The values of `response.data.keys` and -`response.data.key_info` will be replaced with a simple integer, recording how -many entries were contained in the list (`keys`) or map (`key_info`) - therefore -even with this feature enabled, it is still possible to see how many items were -returned by a list operation. - -This extra processing only affects the response data fields `keys` and `key_info`, -and only when they have the expected data types - in the event a list response -contains data outside of the usual conventions that apply to Vault list responses, -it will be left as is by this feature. - -Here is an example of an audit record that has been processed by this feature -(formatted with extra whitespace, and with fields not relevant to the example -omitted): -```json -{ - "type": "response", - "request": { - "operation": "list" - }, - "response": { - "data": { - "key_info": 4, - "keys": 4 - } - } -} -``` + diff --git a/content/vault/v1.21.x (rc)/content/docs/audit/schema.mdx b/content/vault/v1.21.x (rc)/content/docs/audit/schema.mdx new file mode 100644 index 0000000000..4d9389c2f2 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/audit/schema.mdx @@ -0,0 +1,376 @@ +--- +layout: docs +page_title: Audit log entry schema +description: Schema reference for Vault audit log entries. +--- + +# Audit log entry schema + +Vault logs audit entries as individual JSON objects separated by line breaks. Audit log entries include attributes that are common across all API endpoints and endpoint-specific request and response attributes. + +Audit log entries represent API requests received by Vault and API response sent by Vault. You can match response entries to the corresponding request entry with the ID field of the `request` object (`.request.id`) included in both entries. + +Attribute | Type | Description +---------------- | -------- | ----------- +`auth` | `object` | [`authentication`](#authentication-object) object describing the authenticated principal making the API call. +`error` | `string` | Error string generated by the request or returned in the response. Omitted for successful transactions. +`forwarded_from` | `string` | Host and port of the performance standby node forwarding the request. Omitted for requests not forwarded. +`request` | `object` | [`request`](#request-object) object describing the request details. +`response` | `object` | [`response`](#response-object) object describing response details. Omitted for request entries. +`time` | `string` | Date and time of the API request/response in ISO 8601 format. +`type` | `string` | Type of the audit log entry. One of `request` or `response`. + + + + + +```json +{ + "auth": , + "error": "error converting input {\"name\":\"John\"} for field \"data\": '' expected a map, got 'string'", + "forwarded_from": "vault-1.prod.corp.com:443", + "request": , + "time": "2025-06-05T16:10:22.292517Z", + "type": "request" +} +``` + + + + + +```json +{ + "auth": , + "error": "1 error occurred:\n\t* invalid request\n\n", + "forwarded_from": "vault-1.prod.corp.com:443", + "request": , + "response": , + "time": "2025-06-05T16:10:22.292639Z", + "type": "response" +} +``` + + + + + +## Authentication object + +Vault omits irrelevant `authentication` object attributes from the audit entry. For example, `accessor` and `client_token` are irrelevant for unauthenticated requests and `metadata` is irrelevant if the authentication token lacks metadata. + +| Attribute | Type | Description | +| :---- | :---- | :---- | +| `accessor` | `string` | Accessor of the Vault token that performed the request. This value is hashed by default; the example shows a *non-hashed* token accessor. Refer to [token accessors](/vault/docs/concepts/tokens#token-accessors) for more information. | +| `client_token` | `string` | Vault token that performed the request, in hashed form. | +| `display_name` | `string` | Name associated with the Vault token that performed the request. This is a non-sensitive value that can help identify tokens. If a display name is not set, `"token"` will be shown. | +| `token_type` | `string` | Whether the Vault token is a `service`, `batch`, or `periodic` token. Refer to [token types](/vault/docs/concepts/tokens#token-types). | +| `token_issue_time` | `string` | Date and time when the Vault token was issued, in ISO 8601 format. | +| `token_ttl` | `integer` | Validity period of the Vault token, in seconds and as of when the token was first issued, relative to `token_issue_time`. Note that this value is not updated when the token's lifetime is changed subsequent to initial issuance. | +| `metadata` | `object` | Metadata associated with the Vault token. | +| `num_uses` | `integer` | When the API request results in a token being issued, which token has a limited number of uses, the number of uses on that token. | +| `remaining_uses` | `integer` | If the Vault token has a limit on the number of uses, the number of uses remaining *prior to the current request*. | +| `entity_created` | `boolean` | Whether the request resulted in an entity being created, i.e. an authorized principal logs into Vault for the first time. Omitted when false. | +| `entity_id` | `string` | If the Vault token is associated with an entity, the ID of that entity. | +| `policies` | `list(string)` | List of the names of the ACL policies associated with either the Vault token or the corresponding entity. | +| `identity_policies` | `list(string)` | If the Vault token is associated with an entity, a list of the names of the ACL policies associated (directly or via group membership) with that entity. | +| `token_policies` | `list(string)` | A list of the names of the ACL policies associated directly with the Vault token. | +| `no_default_policy` | `boolean` | Whether the Vault token does **not** have Vault's "default" ACL policy associated with it. Omitted when false. | +| `external_namespace_ policies` | `object` | If the Vault token is associated with an entity, and that entity inherits ACL policies from a namespace other than the namespace in which the entity exists, a JSON object containing a boolean attribute `allowed` and `granting_policies`, a list of those inherited ACL policies. Refer to the JSON structure below for more information about `granting_policies`. | +| `policy_results` | `object` | JSON object containing a boolean attribute `allowed` and `granting_policies`, a list of ACL policies associated with either the Vault token or the corresponding entity that resulted in the request being allowed. Refer to the JSON structure below for more information about `granting_policies`. | + +```json +{ + "accessor": "", + "client_token": "", + "display_name": "", + "entity_created": "", + "entity_id": "", + "external_namespace_policies": { + "allowed": true, + "granting_policies": [ + { + "name": "", + "namespace_id": "", + "namespace_path": "", + "type": "" + } + ] + }, + "identity_policies": [""], + "metadata": {}, + "no_default_policy": false, + "num_uses": 10, + "policies": [""], + "policy_results": { + "allowed": true, + "granting_policies": [ + { + "name": "", + "namespace_id": "", + "namespace_path": "", + "type": "" + } + ] + }, + "remaining_uses": 5, + "token_policies": [""], + "token_issue_time": "", + "token_ttl": 3600, + "token_type": "" +} +``` + +## Request object ((#request)) + +The following request object definition includes example data with simple types (`string`, `bool`, `int`) and used in other JSON examples that include a `` object. + +| Attribute | Type | Description | +| :---- | :---- | :---- | +| `id` | `string` | Random ID generated by Vault to uniquely identify the API request. | +| `operation` | `string` | Whether the request is a `create`, `read`, `update`, `delete`, or `list` operation. | +| `namespace` | `object` | JSON object with the namespace's unique `id` and its `path`. | +| `path` | `string` | API path that received the request. | +| `request_uri` | `string` | The original request path from the HTTP request, if it differs from `path` (e.g., when the Vault namespace is specified as an HTTP header). | +| `mount_accessor` | `string` | Unique identifier of the Vault mount (secret engine or authentication backend) that received the API request. | +| `mount_type` | `string` | Type of Vault mount that received the API request. | +| `mount_running_version` | `string` | Version string for the Vault mount that received the API request. | +| `mount_running_sha256` | `string` | If the mount that received the API request is an external plugin, the SHA-256 hash of the plugin's running version. | +| `mount_is_external_ plugin` | `boolean` | Whether the mount that received the API request is an external plugin. | +| `remote_address` | `string` | IP address of the client making the request, as seen by Vault. Note that load balancers, proxies, and reverse proxies may all mask the true client's IP address. | +| `remote_port` | `integer` | Port number used by the client making the request, as seen by Vault. | +| `headers` | `object` | JSON object containing request headers [configured](/vault/docs/audit#logging-of-request-headers) to be logged. | +| `policy_override` | `boolean` | Whether the client requested an override of a [Sentinel policy](/vault/docs/enterprise/sentinel). | +| `client_id` | `string` | ID of the Vault [client](https://developer.hashicorp.com/vault/docs/concepts/client-count) making the request. | +| `client_token` | `string` | Vault token that performed the request, in hashed form. | +| `client_token_accessor` | `string` | Accessor of the Vault token that performed the request. This value is hashed by default; the example shows a *non-hashed* token accessor. Refer to [token accessors](/vault/docs/concepts/tokens#token-accessors) for more information. | +| `client_certificate_ serial_number` | `string` | If the client's connection to Vault is mutually authenticated, the serial number of the client's TLS certificate. | +| `wrap_ttl` | `integer` | If the client requested the response to be [wrapped](/vault/docs/concepts/response-wrapping), the number of seconds for which the wrapped response will be available. | +| `data` | `object` | JSON object containing the request's payload. This is dependent on the API endpoint called. | +| `replication_cluster` | `string` | If the request was forwarded from a Performance Replication secondary cluster, the name of the secondary cluster. | + +```json +{ + "client_certificate_serial_number": "", + "client_id": "", + "client_token": "", + "client_token_accessor": "", + "data": {}, + "id": "", + "headers": {}, + "mount_accessor": "", + "mount_class": "", + "mount_point": "", + "mount_type": "", + "mount_running_version": "", + "mount_running_sha256": "", + "mount_is_external_plugin": "", + "namespace": { + "id": "", + "path": "" + }, + "operation": "", + "path": "", + "policy_override": true, + "remote_address": "", + "remote_port": 1234, + "replication_cluster": "", + "request_uri": "", + "wrap_ttl": 60 +} +``` + +## Response object ((#response)) + +The following response object definition includes example data with simple types (`string`, `bool`, `int`) and used in other JSON examples that include a `` object. + +| Attribute | Type | Description | +| :---- | :---- | :---- | +| `auth` | `object` | If the request results in a token being created, an `authentication` object with the token information. See [`authentication`](#authentication-object) above. | +| `headers` | `object` | Set of HTTP response headers sent by the plugin that handled the API request. | +| `redirect` | `string` | For requests sent to authentication backends, the URL to which the authentication backend redirected the user for further authentication. | +| `warnings` | `list(string)` | If the API returned one or more warnings, a list of the warning messages. | +| `data` | `object` | JSON object containing the response payload. This is dependent on the API endpoint called. | +| `secret` | `object` | If the API returned a [leased secret](/vault/docs/concepts/lease), a JSON object with one attribute, `lease_id`, that identifies that leased secret. | +| `wrap_info` | `object` | If the API returned a [response-wrapped secret](/vault/docs/concepts/response-wrapping), a JSON object containing the properties of the wrapping token. See below for the attributes in the JSON object. | +| `mount_class` | `string` | Type of API mount, `auth` or `secret`. | +| `mount_accessor` | `string` | Unique identifier of the Vault mount (secret engine or authentication backend) that responded to the API request. | +| `mount_type` | `string` | Type of Vault mount that responded to the API request. | +| `mount_running_plugin_version` | `string` | Version string for the Vault mount that responded to the API request. | +| `mount_running_sha256` | `string` | If the mount that received the API request is an external plugin, the SHA-256 hash of the plugin's running version. | +| `mount_is_external_plugin` | `boolean` | Whether the mount that received the API request is an external plugin. | + +```json +{ + "auth": , + "data": {}, + "headers": {}, + "mount_accessor": "", + "mount_class": "", + "mount_is_external_plugin": false, + "mount_point": "", + "mount_running_sha256": "", + "mount_running_plugin_version": "", + "mount_type": "", + "redirect": "", + "secret": { + "lease_id": "" + }, + "wrap_info": { + "accessor": "", + "creation_path": "", + "creation_time": "", + "token": "", + "ttl": 60, + "wrapped_accessor": "" + }, + "warnings": [ + "" + ] +} +``` + +## JSON schemas + +
+Request audit entries + +@include 'audit/request-entry-json-schema.mdx' + +
+ +
+Response audit entries + +@include 'audit/response-entry-json-schema.mdx' + +
+ +## Full entry examples + + + + + +```json +{ + "auth": { + "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "client_token": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d", + "display_name": "userpass-alice", + "entity_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "metadata": { "username": "alice" }, + "policies": ["default"], + "policy_results": { + "allowed": true, + "granting_policies": [ + { "type": "" }, + { "name": "default", "namespace_id": "root", "type": "acl" } + ] + }, + "token_policies": ["default"], + "token_issue_time": "2025-06-04T16:01:31-04:00", + "token_ttl": 2764800, + "token_type": "service" + }, + "request": { + "client_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "client_token": "hmac-sha256:3431e8c2ce0e5f5e179a857fcf9d948afd83363de9f64a5e956851262e1285e0", + "client_token_accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "headers": { "user-agent": ["Go-http-client/1.1"] }, + "id": "79cc9b26-488f-eabf-2a97-303ed3bef0d6", + "mount_class": "auth", + "mount_point": "auth/token/", + "mount_running_version": "v1.19.1+builtin.vault", + "mount_type": "token", + "namespace": { "id": "root" }, + "operation": "read", + "path": "auth/token/lookup-self", + "remote_address": "127.0.0.1", + "remote_port": 64199 + }, + "time": "2025-06-04T20:02:46.117181Z", + "type": "request" +} +``` + + + + + +```json +{ + "auth": { + "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "client_token": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d", + "display_name": "userpass-alice", + "entity_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "metadata": { "username": "alice" }, + "policies": ["default"], + "policy_results": { + "allowed": true, + "granting_policies": [ + { "type": "" }, + { "name": "default", "namespace_id": "root", "type": "acl" } + ] + }, + "token_policies": ["default"], + "token_issue_time": "2025-06-04T16:01:31-04:00", + "token_ttl": 2764800, + "token_type": "service" + }, + "request": { + "client_id": "62ff123b-7609-1ed9-5707-ea621da72de7", + "client_token": "hmac-sha256:3431e8c2ce0e5f5e179a857fcf9d948afd83363de9f64a5e956851262e1285e0", + "client_token_accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "headers": { "user-agent": ["Go-http-client/1.1"] }, + "id": "79cc9b26-488f-eabf-2a97-303ed3bef0d6", + "mount_accessor": "auth_token_d43d387d", + "mount_class": "auth", + "mount_point": "auth/token/", + "mount_running_version": "v1.19.1+builtin.vault", + "mount_type": "token", + "namespace": { "id": "root" }, + "operation": "read", + "path": "auth/token/lookup-self", + "remote_address": "127.0.0.1", + "remote_port": 64199 + }, + "response": { + "data": { + "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3", + "creation_time": 1749067291, + "creation_ttl": 2764800, + "display_name": "hmac-sha256:e9fb3affb6ae22b7f747e1a60bdda5b57809c9e64ae6f39ebac24e371e6b9d89", + "entity_id": "hmac-sha256:d2458e3011b3567a0070f22bcdd5e513aeb3473457922e1866f01463ccce2b11", + "expire_time": "2025-07-06T16:01:31.771304-04:00", + "explicit_max_ttl": 0, + "id": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d", + "issue_time": "2025-06-04T16:01:31.771306-04:00", + "meta": { + "username": "hmac-sha256:b93081f3689ff25929e88d5c323631ccf7d6145cd9f33c0c5129a7a340248b9a" + }, + "num_uses": 0, + "orphan": true, + "path": "hmac-sha256:82f79af6be9e1d33d6821a8cfcfcba3196e5ec68512c1f5ed4c919acd8443dd6", + "policies": [ + "hmac-sha256:1b1a37ccd3a6a78da781140396f04eb50e3460504492d2da75b446d775d3325b" + ], + "renewable": true, + "ttl": 2764725, + "type": "hmac-sha256:b835fe7ff7616f2023c77f6dbddc7afd83ef5c6644aba61c574c378dda710809" + }, + "mount_accessor": "auth_token_d43d387d", + "mount_class": "auth", + "mount_point": "auth/token/", + "mount_running_plugin_version": "v1.19.1+builtin.vault", + "mount_type": "token" + }, + "time": "2025-06-04T20:02:46.117567Z", + "type": "response" +} +``` + + + + diff --git a/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx b/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx index f9f5707733..9560048e58 100644 --- a/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/auth/ldap.mdx @@ -183,8 +183,6 @@ Use `vault path-help` for more details. - `rotation_period` (string: "") - The amount of time, in [duration format](https://pkg.go.dev/time#ParseDuration), Vault should wait before rotating the root credential. -- `rotation_url` `(string: "")` – The LDAP server to perform a root config password - rotation on if it is different from the `url` parameter. See (#rotation-url) for more details. ### Other @@ -197,9 +195,11 @@ The root bindpass can be rotated to a Vault-generated value that is not accessib This will ensure that only Vault is able to access the "root" user that Vault uses to manipulate credentials. ```shell-session -vault write -f auth/ldap/rotate-root +vault write -f auth/ldap/config/rotate-root ``` +Vault logs manual root rotations to `vault.log` with a note that the rotation was `on user request`. + ### Schedule-based root credential rotation @include 'alerts/enterprise-only.mdx' @@ -240,19 +240,12 @@ of the root credential until the field is reset to `false`. If you use `rotation_period`, setting `disable_automated_rotation` also resets the credential TTL. -#### Rotation URL - -Use [`rotation_url`](/vault/api-docs/auth/ldap#rotation_url) to provide the -specific LDAP server URL that the bind account belongs to for rotating its -credential. By default, `rotation_url` uses the value of `url`. Setting an -explicit `rotation_url` parameter is useful when you need to configure an LDAP -forest where the bind account belongs to only a single domain behind a -load-balancer. - For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/auth/ldap#rotate-root) API docs. -## Examples scenarios +@include 'rotation-manager-logging.mdx' + +## Examples: ### Scenario 1 diff --git a/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx b/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx index cf243b6cf4..28e05d219d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/configuration/index.mdx @@ -280,6 +280,9 @@ can have a negative effect on performance due to the tracking of each lock attem [os.TempDir()](https://pkg.go.dev/os#TempDir) (usually `/tmp` on Unix systems). This can be updated on a running Vault process with a SIGHUP signal. +- `allow_audit_log_prefixing` `(bool: false)` - Enable to allow prefixes on audit log entries for + [file sinks](/vault/docs/audit/file). + ### High availability parameters The following parameters are used on backends that support [high availability][high-availability]. diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx index b4acd0b679..639ebe49a9 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/csi/installation.mdx @@ -46,28 +46,20 @@ more. ## Installation on OpenShift -We recommend using the [Vault agent injector on Openshift](/vault/docs/platform/k8s/helm/openshift) -instead of the Secrets Store CSI driver. OpenShift -[does not recommend](https://docs.openshift.com/container-platform/4.9/storage/persistent_storage/persistent-storage-hostpath.html) -using `hostPath` mounting in production or -[certify Helm charts](https://github.com/redhat-certification/chart-verifier/blob/dbf89bff2d09142e4709d689a9f4037a739c2244/docs/helm-chart-checks.md#table-2-helm-chart-default-checks) -using CSI objects because pods must run as privileged. Pods will have elevated access to -other pods on the same node, which OpenShift does not recommend. - You can run the Secrets Store CSI driver with additional security configurations on a OpenShift development or testing cluster. -Deploy the Secrets Store CSI driver and Vault Helm chart -to your OpenShift cluster. - -Then, patch the `DaemonSet` for the Vault CSI provider to -run with a privileged security context. +Deploy the Secrets Store CSI driver and Vault Helm chart to your OpenShift +cluster. Set the [provider container's securityContext](/vault/docs/deploy/kubernetes/helm/configuration#container-2) +to `privileged: true` in the Vault Helm chart values: -```shell-session -$ kubectl patch daemonset vault-csi-provider \ - --type='json' \ - --patch='[{"op": "add", "path": "/spec/template/spec/containers/0/securityContext", "value": {"privileged": true} }]' +```yaml +csi: + daemonSet: + securityContext: + container: + privileged: true ``` The Secrets Store CSI driver and Vault CSI provider need `hostPath` mount access. diff --git a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx index 22e85433a6..d3ed9a61bf 100644 --- a/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/deploy/kubernetes/index.mdx @@ -41,6 +41,8 @@ to the Vault cluster which can be used to [store audit logs](/vault/docs/audit). native integrations provided by Vault itself, any other tool built for Kubernetes can choose to leverage Vault. +@include 'kubernetes-supported-versions.mdx' + ## Getting started with Vault and kubernetes There are several ways to try Vault with Kubernetes in different environments. diff --git a/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx b/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx index 37472132e9..88d589d340 100644 --- a/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/enterprise/audit/filtering.mdx @@ -13,14 +13,16 @@ As of Vault 1.16.0, you can enable audit devices with a `filter` option to limit the audit entries written to a particular audit log and fine-tune your auditing process. - + Filtering audit logs is an advanced feature. Exclusively enabling filtered devices without configuring an audit fallback may lead to gaps in your audit logs. **Always** test your audit configuration in a non-production environment - before deploying filters to production. And make sure to read the + before deploying filters to production, including the + [performance impact](/vault/docs/concepts/filtering#performance) of your configured + filters. And make sure to read the [Vault security model](/vault/docs/internals/security) and [filtering overview](/vault/docs/concepts/filtering) to familiarize yourself with Vault auditing and filtering basics before enabling filtered audit @@ -169,19 +171,20 @@ The `/var/kv-audit.log` now includes four entries in total: The fallback device captured entries for the other commands. And the original audit file, `vault-audit.log`, continues to capture all audit events. +## Additional resources - - - - [Filtering](/vault/docs/concepts/filtering) + - + - [Filtering](/vault/docs/concepts/filtering) - + - - [Audit API](/vault/api-docs/system/audit#common-configuration-options) + - + - [Audit API](/vault/api-docs/system/audit#common-configuration-options) + + diff --git a/content/vault/v1.21.x (rc)/content/docs/index.mdx b/content/vault/v1.21.x (rc)/content/docs/index.mdx index 6f1596a778..6efce800f5 100644 --- a/content/vault/v1.21.x (rc)/content/docs/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/index.mdx @@ -6,11 +6,10 @@ description: >- common tasks, and best practices. --- -# Documentation +# Vault product documentation -Welcome to the Vault product documentation! + -If you are getting started with Vault, we recommend reading the -[What is Vault](/vault/docs/what-is-vault) docs before diving into our -[Vault Foundations tutorial set](/vault/tutorials/getting-started) -or our [Vault operator quickstart guide](/vault/docs/get-started/operations-qs). \ No newline at end of file +You are currently viewing documentation for an older version of Vault. + + diff --git a/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx b/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx index 1cb7b22eff..98629743d1 100644 --- a/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/internals/recommended-patterns.mdx @@ -18,6 +18,7 @@ Help keep your Vault environments operating effectively by implementing the foll | [Improve upgrade cadence](#improve-upgrade-cadence) | Enterprise, Community | | [Test before upgrades](#test-before-upgrades) | Enterprise, Community | | [Rotate audit device logs](#rotate-audit-device-logs) | Enterprise, Community | +| [Monitor limits and maximums](/vault/docs/internals/limits) | Enterprise, Community | | [Monitor metrics](#monitor-metrics) | Enterprise, Community | | [Establish usage baseline](#establish-usage-baseline) | Enterprise, Community | | [Minimize root token use](#minimize-root-token-use) | All | diff --git a/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx b/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx index fa00634e3d..f58684c623 100644 --- a/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx @@ -476,6 +476,10 @@ alphabetic order by name. @include 'telemetry-metrics/vault/raft-storage/transaction.mdx' +@include 'telemetry-metrics/vault/raft/thread/fsm/saturation.mdx' + +@include 'telemetry-metrics/vault/raft/thread/main/saturation.mdx' + @include 'telemetry-metrics/vault/raft-wal/head-truncations.mdx' @include 'telemetry-metrics/vault/raft-wal/tail-truncations.mdx' diff --git a/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx b/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx index 9a314122d0..341b56394e 100644 --- a/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/license/product-usage-reporting.mdx @@ -62,7 +62,7 @@ You will find the following entry in the server log: ```text - [DEBUG] activity: there is no reporting agent configured, skipping counts reporting + [DEBUG] product usage reporting is disabled; usage metrics data will not be collected ``` @@ -109,145 +109,152 @@ HashiCorp collects the following product usage metrics as part of the `metrics` [JSON payload that it collects for licence utilization](/vault/docs/enterprise/license/utilization-reporting#example-payloads). All of these metrics are numerical, and contain no sensitive values or additional metadata: -| Metric Name | Description | -|---------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| -| `vault.namespaces.count` | Total number of namespaces. | -| `vault.leases.count` | Total number of leases within Vault. | -| `vault.quotas.ratelimit.count` | Total number of rate limit quotas within Vault, considering any group_by modes. | -| `vault.quotas.ratelimit.ip.count` | Total number of rate limit quotas using "ip" group_by mode within Vault. | -| `vault.quotas.ratelimit.none.count` | Total number of rate limit quotas using "none" group_by mode within Vault. | -| `vault.quotas.ratelimit.entity_then_ip.count` | Total number of rate limit quotas using "entity_then_ip" group_by mode within Vault. | -| `vault.quotas.ratelimit.entity_then_ip_with_secondary_rate.count` | Total number of rate limit quotas using "entity_then_ip" group_by mode with secondary rate within Vault. | -| `vault.quotas.ratelimit.entity_then_none.count` | Total number of rate limit quotas using "entity_then_none" group_by mode within Vault. | -| `vault.quotas.ratelimit.entity_then_none_with_secondary_rate.count` | Total number of rate limit quotas using "entity_then_none" group_by mode with secondary rate within Vault. | -| `vault.quotas.leasecount.count` | Total number of lease count quotas within Vault. | -| `vault.kv.version1.secrets.count` | Total number of KVv1 secrets within Vault. | -| `vault.kv.version2.secrets.count` | Total number of KVv2 secrets within Vault. | -| `vault.kv.version1.secrets.namespace.max` | The highest number of KVv1 secrets in a namespace in Vault, e.g. `1000`. | -| `vault.kv.version2.secrets.namespace.max` | The highest number of KVv2 secrets in a namespace in Vault, e.g. `1000`. | -| `vault.kv.version1.secrets.namespace.min` | The lowest number of KVv1 secrets in a namespace in Vault, e.g. `2`. | -| `vault.kv.version2.secrets.namespace.min` | The highest number of KVv2 secrets in a namespace in Vault, e.g. `1000`. | -| `vault.kv.version1.secrets.namespace.mean` | The mean number of KVv1 secrets in namespaces in Vault, e.g. `52.8`. | -| `vault.kv.version2.secrets.namespace.mean` | The mean number of KVv2 secrets in namespaces in Vault, e.g. `52.8`. | -| `vault.auth.method.approle.count` | The total number of Approle auth mounts in Vault. | -| `vault.auth.method.alicloud.count` | The total number of Alicloud auth mounts in Vault. | -| `vault.auth.method.aws.count` | The total number of AWS auth mounts in Vault. | -| `vault.auth.method.appid.count` | The total number of App ID auth mounts in Vault. | -| `vault.auth.method.azure.count` | The total number of Azure auth mounts in Vault. | -| `vault.auth.method.cloudfoundry.count` | The total number of Cloud Foundry auth mounts in Vault. | -| `vault.auth.method.github.count` | The total number of GitHub auth mounts in Vault. | -| `vault.auth.method.gcp.count` | The total number of GCP auth mounts in Vault. | -| `vault.auth.method.jwt.count` | The total number of JWT auth mounts in Vault. | -| `vault.auth.method.kerberos.count` | The total number of Kerberos auth mounts in Vault. | -| `vault.auth.method.kubernetes.count` | The total number of Kubernetes auth mounts in Vault. | -| `vault.auth.method.ldap.count` | The total number of LDAP auth mounts in Vault. | -| `vault.auth.method.oci.count` | The total number of OCI auth mounts in Vault. | -| `vault.auth.method.okta.count` | The total number of Okta auth mounts in Vault. | -| `vault.auth.method.pcf.count` | The total number of PCF auth mounts in Vault. | -| `vault.auth.method.radius.count` | The total number of Radius auth mounts in Vault. | -| `vault.auth.method.saml.count` | The total number of SAML auth mounts in Vault. | -| `vault.auth.method.cert.count` | The total number of Cert auth mounts in Vault. | -| `vault.auth.method.oidc.count` | The total number of OIDC auth mounts in Vault. | -| `vault.auth.method.token.count` | The total number of Token auth mounts in Vault. | -| `vault.auth.method.userpass.count` | The total number of Userpass auth mounts in Vault. | -| `vault.auth.method.plugin.count` | The total number of custom plugin auth mounts in Vault. | -| `vault.db.cassandra.plugin.count` | The total number of Cassandra database plugin connections in Vault. | -| `vault.db.couchbase.plugin.count` | The total number of Couchbase database plugin connections in Vault. | -| `vault.db.elasticsearch.plugin.count` | The total number of Elasticsearch database plugin connections in Vault. | -| `vault.db.hana.plugin.count` | The total number of Hana database plugin connections in Vault. | -| `vault.db.influxdb.plugin.count` | The total number of InfluxDB database plugin connections in Vault. | -| `vault.db.mongodb.plugin.count` | The total number of MongoDB database plugin connections in Vault. | -| `vault.db.mongodbatlas.plugin.count` | The total number of MongoDB Atlas database plugin connections in Vault. | -| `vault.db.mssql.plugin.count` | The total number of MSSQL database plugin connections in Vault. | -| `vault.db.mysql.plugin.count` | The total number of MySQL database plugin connections in Vault. | -| `vault.db.postgres.plugin.count` | The total number of Postgres databse plugin connections in Vault. | -| `vault.db.redshift.plugin.count` | The total number of Redshift database plugin connections in Vault. | -| `vault.db.redis.plugin.count` | The total number of Redis database plugin connections in Vault. | -| `vault.db.rediselasticache.plugin.count` | The total number of Redis Elasticache database plugin connections in Vault. | -| `vault.db.snowflake.plugin.count` | The total number of Snowflake database plugin connections in Vault. | -| `vault.db.unknown.plugin.count` | The total number of custom or unknown database plugin connections in Vault. | -| `vault.secret.engine.activedirectory.count` | The total number of Active Directory secret engines in Vault. | -| `vault.secret.engine.alicloud.count` | The total number of Alicloud secret engines in Vault. | -| `vault.secret.engine.aws.count` | The total number of AWS secret engines in Vault. | -| `vault.secret.engine.azure.count` | The total number of Azure secret engines in Vault. | -| `vault.secret.engine.consul.count` | The total number of Consul secret engines in Vault. | -| `vault.secret.engine.gcp.count` | The total number of GCP secret engines in Vault. | -| `vault.secret.engine.gcpkms.count` | The total number of GCPKMS secret engines in Vault. | -| `vault.secret.engine.kubernetes.count` | The total number of Kubernetes secret engines in Vault. | -| `vault.secret.engine.cassandra.count` | The total number of Cassandra secret engines in Vault. | -| `vault.secret.engine.keymgmt.count` | The total number of Keymgmt secret engines in Vault. | -| `vault.secret.engine.kv.count` | The total number of KV secret engines in Vault. | -| `vault.secret.engine.kmip.count` | The total number of KMIP secret engines in Vault. | -| `vault.secret.engine.mongodb.count` | The total number of MongoDB secret engines in Vault. | -| `vault.secret.engine.mongodbatlas.count` | The total number of MongoDBAtlas secret engines in Vault. | -| `vault.secret.engine.mssql.count` | The total number of MSSql secret engines in Vault. | -| `vault.secret.engine.mysql.count` | The total number of MySQL secret engines in Vault. | -| `vault.secret.engine.postgresql.count` | The total number of Postgresql secret engines in Vault. | -| `vault.secret.engine.nomad.count` | The total number of Nomad secret engines in Vault. | -| `vault.secret.engine.ldap.count` | The total number of LDAP secret engines in Vault. | -| `vault.secret.engine.openldap.count` | The total number of OpenLDAP secret engines in Vault. | -| `vault.secret.engine.pki.count` | The total number of PKI secret engines in Vault. | -| `vault.secret.engine.rabbitmq.count` | The total number of RabbitMQ secret engines in Vault. | -| `vault.secret.engine.ssh.count` | The total number of SSH secret engines in Vault. | -| `vault.secret.engine.terraform.count` | The total number of Terraform secret engines in Vault. | -| `vault.secret.engine.totp.count` | The total number of TOTP secret engines in Vault. | -| `vault.secret.engine.transform.count` | The total number of Transform secret engines in Vault. | -| `vault.secret.engine.transit.count` | The total number of Transit secret engines in Vault. | -| `vault.secret.engine.database.count` | The total number of Database secret engines in Vault. | -| `vault.secret.engine.plugin.count` | The total number of custom plugin secret engines in Vault. | -| `vault.secretsync.sources.count` | The total number of secret sources configured for secret sync. | -| `vault.secretsync.destinations.count` | The total number of secret destinations configured for secret sync. | -| `vault.secretsync.destinations.aws-sm.count` | The total number of AWS-SM secret destinations configured for secret sync. | -| `vault.secretsync.destinations.azure-kv.count` | The total number of Azure-KV secret destinations configured for secret sync. | -| `vault.secretsync.destinations.gcp-sm.count` | The total number of secret sync destinations to GCP-SM configured. | -| `vault.secretsync.destinations.gh.count` | The total number of GH secret destinations configured for secret sync. | -| `vault.secretsync.destinations.vault.count` | The total number of Vault secret destinations configured for secret sync. | -| `vault.secretsync.destinations.vercel-project.count` | The total number of Vercel Project secret destinations configured for secret sync. | -| `vault.secretsync.destinations.terraform.count` | The total number of Terraform secret destinations configured for secret sync. | -| `vault.secretsync.destinations.gitlab.count` | The total number of GitLab secret destinations configured for secret sync. | -| `vault.secretsync.destinations.inmem.count` | The total number of InMem secret destinations configured for secret sync. | -| `vault.pki.roles.count` | The total roles in all PKI mounts across all namespaces. | -| `vault.pki.issuers.count` | The total issuers from all PKI mounts across all namespaces. | -| `vault.identity.case_sensitive_mode` | Whether or not the cluster is using case-sensitive identity name matching caused by historical duplicates. | -| `vault.identity.force_deduplication_activated` | Whether or not the cluster has had the force_identity_deduplication activation flag activated. | -| `vault.ui.enabled` | Whether or not the UI is enabled for the cluster. | -| `vault.ui.custom_banners.authenticated` | How many authenticated custom banners have been enabled across all namespaces. | -| `vault.ui.custom_banners.unauthenticated` | How many unauthenticated custom banners have been enabled across all namespaces. | -| `vault.storage.max_entry_size` | The value of `max_entry_size` parameter for the storage stanza in the config. | -| `vault.storage.max_mount_and_namespace_table_entry_size` | The value of `max_mount_and_namespace_table_entry_size` parameter for the storage stanza in the config. | -| `vault.operator.import.kv.version2.secrets.source.vault.count` | The total number of secrets imported from Vault using operator import command. | -| `vault.operator.import.kv.version2.secrets.source.aws.count` | The total number of secrets imported from AWS using operator import command. | -| `vault.operator.import.kv.version2.secrets.source.gcp.count` | The otal number of secrets imported from GCP using operator import command. | -| `vault.operator.import.kv.version2.secrets.source.azure.count` | The total number of secrets imported from Azure using operator import command. | -| `vault.operator.import.kv.version2.secrets.count` | The total number of secrets imported from using operator import command. | -| `vault.telemetry.stanzas.count` | The count of telemetry stanzas configured in this cluster. | -| `vault.telemetry.filters.count` | The count of metric prefix filters specified in the telemetry stanza in config file. | -| `vault.replication.secret.non_local_mounts` | The number of replicated secret mounts on Enterprise clusters. | -| `vault.replication.secret.local_mounts` | The number of local secret mounts on Enterprise clusters. | -| `vault.replication.auth.local_mounts` | The number of local auth mounts on Enterprise clusters. | -| `vault.replication.auth.non_local_mounts` | The number of replicated auth mounts on Enterprise clusters. | -| `vault.replication.num_nodes` | The number of nodes in a HA cluster. | -| `vault.adaptive_overload_protection_enabled` | Whether or not Adaptive Overload Protection is enabled for the cluster. | -| `vault.policies.egp.count` | The total number of Enterprise Governance Policies (EGP) across all namespaces in Vault. | -| `vault.policies.rgp.count` | The total number of Replication Governance Policies (RGP) across all namespaces in Vault. | -| `vault.policies.acl.count` | The total number of Access Control List (ACL) policies across all namespaces in Vault. | -| `vault.policies.acl.control_group.count` | The total number of control groups in this cluster. | -| `vault.policies.acl.recover.count` | The total number of Access Control List (ACL) policies with a recover capability across all namesapces in Vault. | -| `vault.autopilot_upgrade_enabled` | Whether or not Autopilot Upgrade is enabled for the cluster. | -| `vault.audit.device.file.count` | The total number of audit devices of type file configured for this cluster. | -| `vault.audit.device.syslog.count` | The total total number of audit devices of type syslog configured for this cluster. | -| `vault.audit.device.socket.udp.count` | The total total number of audit devices of type UDP socket configured for this cluster. | -| `vault.audit.device.socket.tcp.count` | The total total number of audit devices of type TCP socket configured for this cluster. | -| `vault.audit.device.socket.unix.count` | The total total number of audit devices of type UNIX socket configured for this cluster. | -| `vault.audit.exclusion.stanza.count` | The total number of audit exclusion stanzas in the HCL configuration for this cluster. | -| `vault.loadedsnapshots.manual.count` | The total number of manual (local) snapshots loaded for recovery. | -| `vault.loadedsnapshots.cloud.google-gcs.count` | The total number of Google GCS snapshots loaded for recovery. | -| `vault.loadedsnapshots.cloud.aws-s3.count` | The total number of AWS S3 snapshots loaded for recovery. | -| `vault.loadedsnapshots.cloud.azure-blob.count` | The total number of Azure Blob snapshots loaded for recovery. | -| `vault.autosnapshots.local.count` | The total number of automated snapshot configurations with storage type local. | -| `vault.autosnapshots.google-gcs.count` | The total of automated snapshot configurations with storage type Google GCS. | -| `vault.autosnapshots.aws-s3.count` | The total number of automated snapshot configurations with storage type AWS S3. | -| `vault.autosnapshots.azure-blob.count` | The total number of automated snapshot configurations with storage type Azure Blob. | +| Metric Name | Description | +|---------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| `vault.namespaces.count` | Total number of namespaces. | +| `vault.leases.count` | Total number of leases within Vault. | +| `vault.quotas.ratelimit.count` | Total number of rate limit quotas within Vault, considering any group_by modes. | +| `vault.quotas.ratelimit.ip.count` | Total number of rate limit quotas using "ip" group_by mode within Vault. | +| `vault.quotas.ratelimit.none.count` | Total number of rate limit quotas using "none" group_by mode within Vault. | +| `vault.quotas.ratelimit.entity_then_ip.count` | Total number of rate limit quotas using "entity_then_ip" group_by mode within Vault. | +| `vault.quotas.ratelimit.entity_then_ip_with_secondary_rate.count` | Total number of rate limit quotas using "entity_then_ip" group_by mode with secondary rate within Vault. | +| `vault.quotas.ratelimit.entity_then_none.count` | Total number of rate limit quotas using "entity_then_none" group_by mode within Vault. | +| `vault.quotas.ratelimit.entity_then_none_with_secondary_rate.count` | Total number of rate limit quotas using "entity_then_none" group_by mode with secondary rate within Vault. | +| `vault.quotas.leasecount.count` | Total number of lease count quotas within Vault. | +| `vault.kv.version1.secrets.count` | Total number of KVv1 secrets within Vault. | +| `vault.kv.version2.secrets.count` | Total number of KVv2 secrets within Vault. | +| `vault.kv.version1.secrets.namespace.max` | The highest number of KVv1 secrets in a namespace in Vault, e.g. `1000`. | +| `vault.kv.version2.secrets.namespace.max` | The highest number of KVv2 secrets in a namespace in Vault, e.g. `1000`. | +| `vault.kv.version1.secrets.namespace.min` | The lowest number of KVv1 secrets in a namespace in Vault, e.g. `2`. | +| `vault.kv.version2.secrets.namespace.min` | The highest number of KVv2 secrets in a namespace in Vault, e.g. `1000`. | +| `vault.kv.version1.secrets.namespace.mean` | The mean number of KVv1 secrets in namespaces in Vault, e.g. `52.8`. | +| `vault.kv.version2.secrets.namespace.mean` | The mean number of KVv2 secrets in namespaces in Vault, e.g. `52.8`. | +| `vault.auth.method.approle.count` | The total number of Approle auth mounts in Vault. | +| `vault.auth.method.alicloud.count` | The total number of Alicloud auth mounts in Vault. | +| `vault.auth.method.aws.count` | The total number of AWS auth mounts in Vault. | +| `vault.auth.method.appid.count` | The total number of App ID auth mounts in Vault. | +| `vault.auth.method.azure.count` | The total number of Azure auth mounts in Vault. | +| `vault.auth.method.cloudfoundry.count` | The total number of Cloud Foundry auth mounts in Vault. | +| `vault.auth.method.github.count` | The total number of GitHub auth mounts in Vault. | +| `vault.auth.method.gcp.count` | The total number of GCP auth mounts in Vault. | +| `vault.auth.method.jwt.count` | The total number of JWT auth mounts in Vault. | +| `vault.auth.method.kerberos.count` | The total number of Kerberos auth mounts in Vault. | +| `vault.auth.method.kubernetes.count` | The total number of Kubernetes auth mounts in Vault. | +| `vault.auth.method.ldap.count` | The total number of LDAP auth mounts in Vault. | +| `vault.auth.method.oci.count` | The total number of OCI auth mounts in Vault. | +| `vault.auth.method.okta.count` | The total number of Okta auth mounts in Vault. | +| `vault.auth.method.pcf.count` | The total number of PCF auth mounts in Vault. | +| `vault.auth.method.radius.count` | The total number of Radius auth mounts in Vault. | +| `vault.auth.method.saml.count` | The total number of SAML auth mounts in Vault. | +| `vault.auth.method.cert.count` | The total number of Cert auth mounts in Vault. | +| `vault.auth.method.oidc.count` | The total number of OIDC auth mounts in Vault. | +| `vault.auth.method.token.count` | The total number of Token auth mounts in Vault. | +| `vault.auth.method.userpass.count` | The total number of Userpass auth mounts in Vault. | +| `vault.auth.method.plugin.count` | The total number of custom plugin auth mounts in Vault. | +| `vault.db.cassandra.plugin.count` | The total number of Cassandra database plugin connections in Vault. | +| `vault.db.couchbase.plugin.count` | The total number of Couchbase database plugin connections in Vault. | +| `vault.db.elasticsearch.plugin.count` | The total number of Elasticsearch database plugin connections in Vault. | +| `vault.db.hana.plugin.count` | The total number of Hana database plugin connections in Vault. | +| `vault.db.influxdb.plugin.count` | The total number of InfluxDB database plugin connections in Vault. | +| `vault.db.mongodb.plugin.count` | The total number of MongoDB database plugin connections in Vault. | +| `vault.db.mongodbatlas.plugin.count` | The total number of MongoDB Atlas database plugin connections in Vault. | +| `vault.db.mssql.plugin.count` | The total number of MSSQL database plugin connections in Vault. | +| `vault.db.mysql.plugin.count` | The total number of MySQL database plugin connections in Vault. | +| `vault.db.postgres.plugin.count` | The total number of Postgres databse plugin connections in Vault. | +| `vault.db.redshift.plugin.count` | The total number of Redshift database plugin connections in Vault. | +| `vault.db.redis.plugin.count` | The total number of Redis database plugin connections in Vault. | +| `vault.db.rediselasticache.plugin.count` | The total number of Redis Elasticache database plugin connections in Vault. | +| `vault.db.snowflake.plugin.count` | The total number of Snowflake database plugin connections in Vault. | +| `vault.db.unknown.plugin.count` | The total number of custom or unknown database plugin connections in Vault. | +| `vault.secret.engine.activedirectory.count` | The total number of Active Directory secret engines in Vault. | +| `vault.secret.engine.alicloud.count` | The total number of Alicloud secret engines in Vault. | +| `vault.secret.engine.aws.count` | The total number of AWS secret engines in Vault. | +| `vault.secret.engine.aws.dynamic.role.count` | The total number of AWS dynamic roles in Vault. | +| `vault.secret.engine.aws.static.role.count` | The total number of AWS static roles in Vault. | +| `vault.secret.engine.azure.count` | The total number of Azure secret engines in Vault. | +| `vault.secret.engine.azure.dynamic.role.count` | The total number of Azure dynamic roles in Vault. | +| `vault.secret.engine.consul.count` | The total number of Consul secret engines in Vault. | +| `vault.secret.engine.gcp.count` | The total number of GCP secret engines in Vault. | +| `vault.secret.engine.gcp.impersonated.account.count` | The total number of GCP impersonated accounts in Vault. | +| `vault.secret.engine.gcp.roleset.count` | The total number of GCP rolesets in Vault. | +| `vault.secret.engine.gcp.static.role.count` | The total number of GCP static roles in Vault. | +| `vault.secret.engine.gcpkms.count` | The total number of GCPKMS secret engines in Vault. | +| `vault.secret.engine.kubernetes.count` | The total number of Kubernetes secret engines in Vault. | +| `vault.secret.engine.cassandra.count` | The total number of Cassandra secret engines in Vault. | +| `vault.secret.engine.keymgmt.count` | The total number of Keymgmt secret engines in Vault. | +| `vault.secret.engine.kv.count` | The total number of KV secret engines in Vault. | +| `vault.secret.engine.kmip.count` | The total number of KMIP secret engines in Vault. | +| `vault.secret.engine.mongodb.count` | The total number of MongoDB secret engines in Vault. | +| `vault.secret.engine.mongodbatlas.count` | The total number of MongoDBAtlas secret engines in Vault. | +| `vault.secret.engine.mssql.count` | The total number of MSSql secret engines in Vault. | +| `vault.secret.engine.mysql.count` | The total number of MySQL secret engines in Vault. | +| `vault.secret.engine.postgresql.count` | The total number of Postgresql secret engines in Vault. | +| `vault.secret.engine.nomad.count` | The total number of Nomad secret engines in Vault. | +| `vault.secret.engine.ldap.count` | The total number of LDAP secret engines in Vault. | +| `vault.secret.engine.ldap.dynamic.role.count` | The total number of LDAP dynamic roles in Vault. | +| `vault.secret.engine.ldap.static.role.count` | The total number of LDAP static roles in Vault. | +| `vault.secret.engine.openldap.count` | The total number of OpenLDAP secret engines in Vault. | +| `vault.secret.engine.openldap.dynamic.role.count` | The total number of OpenLDAP dynamic roles in Vault. | +| `vault.secret.engine.openldap.static.role.count` | The total number of OpenLDAP static roles in Vault. | +| `vault.secret.engine.pki.count` | The total number of PKI secret engines in Vault. | +| `vault.secret.engine.rabbitmq.count` | The total number of RabbitMQ secret engines in Vault. | +| `vault.secret.engine.ssh.count` | The total number of SSH secret engines in Vault. | +| `vault.secret.engine.terraform.count` | The total number of Terraform secret engines in Vault. | +| `vault.secret.engine.totp.count` | The total number of TOTP secret engines in Vault. | +| `vault.secret.engine.transform.count` | The total number of Transform secret engines in Vault. | +| `vault.secret.engine.transit.count` | The total number of Transit secret engines in Vault. | +| `vault.secret.engine.database.count` | The total number of Database secret engines in Vault. | +| `vault.secret.engine.database.dynamic.role.count` | The total number of Database dynamic roles in Vault. | +| `vault.secret.engine.database.static.role.count` | The total number of Database static roles in Vault. | +| `vault.secret.engine.plugin.count` | The total number of custom plugin secret engines in Vault. | +| `vault.secretsync.sources.count` | The total number of secret sources configured for secret sync. | +| `vault.secretsync.destinations.count` | The total number of secret destinations configured for secret sync. | +| `vault.secretsync.destinations.aws-sm.count` | The total number of AWS-SM secret destinations configured for secret sync. | +| `vault.secretsync.destinations.azure-kv.count` | The total number of Azure-KV secret destinations configured for secret sync. | +| `vault.secretsync.destinations.gcp-sm.count` | The total number of secret sync destinations to GCP-SM configured. | +| `vault.secretsync.destinations.gh.count` | The total number of GH secret destinations configured for secret sync. | +| `vault.secretsync.destinations.vault.count` | The total number of Vault secret destinations configured for secret sync. | +| `vault.secretsync.destinations.vercel-project.count` | The total number of Vercel Project secret destinations configured for secret sync. | +| `vault.secretsync.destinations.terraform.count` | The total number of Terraform secret destinations configured for secret sync. | +| `vault.secretsync.destinations.gitlab.count` | The total number of GitLab secret destinations configured for secret sync. | +| `vault.secretsync.destinations.inmem.count` | The total number of InMem secret destinations configured for secret sync. | +| `vault.pki.roles.count` | The total roles in all PKI mounts across all namespaces. | +| `vault.pki.issuers.count` | The total issuers from all PKI mounts across all namespaces. | +| `vault.identity.case_sensitive_mode` | Whether or not the cluster is using case-sensitive identity name matching caused by historical duplicates. | +| `vault.identity.force_deduplication_activated` | Whether or not the cluster has had the force_identity_deduplication activation flag activated. | +| `vault.ui.enabled` | Whether or not the UI is enabled for the cluster. | +| `vault.ui.custom_banners.authenticated` | How many authenticated custom banners have been enabled across all namespaces. | +| `vault.ui.custom_banners.unauthenticated` | How many unauthenticated custom banners have been enabled across all namespaces. | +| `vault.storage.max_entry_size` | The value of `max_entry_size` parameter for the storage stanza in the config. | +| `vault.storage.max_mount_and_namespace_table_entry_size` | The value of `max_mount_and_namespace_table_entry_size` parameter for the storage stanza in the config. | +| `vault.operator.import.kv.version2.secrets.source.vault.count` | The total number of secrets imported from Vault using operator import command. | +| `vault.operator.import.kv.version2.secrets.source.aws.count` | The total number of secrets imported from AWS using operator import command. | +| `vault.operator.import.kv.version2.secrets.source.gcp.count` | The otal number of secrets imported from GCP using operator import command. | +| `vault.operator.import.kv.version2.secrets.source.azure.count` | The total number of secrets imported from Azure using operator import command. | +| `vault.operator.import.kv.version2.secrets.count` | The total number of secrets imported from using operator import command. | +| `vault.telemetry.stanzas.count` | The count of telemetry stanzas configured in this cluster. | +| `vault.telemetry.filters.count` | The count of metric prefix filters specified in the telemetry stanza in config file. | +| `vault.replication.secret.non_local_mounts` | The number of replicated secret mounts on Enterprise clusters. | +| `vault.replication.secret.local_mounts` | The number of local secret mounts on Enterprise clusters. | +| `vault.replication.auth.local_mounts` | The number of local auth mounts on Enterprise clusters. | +| `vault.replication.auth.non_local_mounts` | The number of replicated auth mounts on Enterprise clusters. | +| `vault.replication.num_nodes` | The number of nodes in a HA cluster. | +| `vault.adaptive_overload_protection_enabled` | Whether or not Adaptive Overload Protection is enabled for the cluster. | +| `vault.policies.egp.count` | The total number of Enterprise Governance Policies (EGP) across all namespaces in Vault. | +| `vault.policies.rgp.count` | The total number of Replication Governance Policies (RGP) across all namespaces in Vault. | +| `vault.policies.acl.count` | The total number of Access Control List (ACL) policies across all namespaces in Vault. | +| `vault.policies.acl.control_group.count` | The total number of control groups in this cluster. | +| `vault.autopilot_upgrade_enabled` | Whether or not Autopilot Upgrade is enabled for the cluster. | +| `vault.audit.device.file.count` | The total number of audit devices of type file configured for this cluster. | +| `vault.audit.device.syslog.count` | The total total number of audit devices of type syslog configured for this cluster. | +| `vault.audit.device.socket.udp.count` | The total total number of audit devices of type UDP socket configured for this cluster. | +| `vault.audit.device.socket.tcp.count` | The total total number of audit devices of type TCP socket configured for this cluster. | +| `vault.audit.device.socket.unix.count` | The total total number of audit devices of type UNIX socket configured for this cluster. | +| `vault.audit.exclusion.stanza.count` | The total number of audit exclusion stanzas in the HCL configuration for this cluster. | +| `vault.loadedsnapshots.manual.count` | The total number of manual (local) snapshots loaded for recovery. | +| `vault.loadedsnapshots.cloud.google-gcs.count` | The total number of Google GCS snapshots loaded for recovery. | +| `vault.loadedsnapshots.cloud.aws-s3.count` | The total number of AWS S3 snapshots loaded for recovery. | +| `vault.loadedsnapshots.cloud.azure-blob.count` | The total number of Azure Blob snapshots loaded for recovery. | ## Usage metadata list diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx index d30107f0c8..849b49193a 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/changelog.mdx @@ -9,6 +9,12 @@ description: Release notes for the Vault EKM Provider for Microsoft SQL Server. Each version is available to download from the [releases](https://releases.hashicorp.com/vault-mssql-ekm-provider/) page. +## 0.3.0 (August 7th, 2025) + +FEATURES + +* The provider supports pinning the transit key version to use previous key versions after the transit key is rotated. + ## 0.2.2 (August 10th, 2023) BUGS diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx index d7ed680719..8b69c16154 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/installation.mdx @@ -50,7 +50,7 @@ EKM provider to use it. -> **Note:** After authenticating to Vault with the AppRole, the EKM provider will re-use the token it receives until it expires, at which point it will authenticate using the AppRole credentials again; it will not attempt to renew -its token. The example AppRole configuraiton here will work for this, but keep +its token. The example AppRole configuration here will work for this, but keep that in mind if you choose to use a different AppRole configuration. 1. Retrieve the AppRole ID and secret ID for use later when configuring SQL Server: @@ -140,8 +140,10 @@ The remaining steps are all run on the database server. ### Configure the EKM provider using SQL -Open Microsoft SQL Server Management Studio, and run the queries below to complete -installation. +Open Microsoft SQL Server Management Studio, and run the queries below to encrypt a +DB using the EKM provider. + +-> **Note:** If restoring a backup encrypted with the EKM provider, refer to steps 1 through 3. 1. Enable the EKM feature and create a cryptographic provider using the folder you just installed the EKM provider into. @@ -201,6 +203,21 @@ installation. Vault is misconfigured, this step is likely to fail. See [troubleshooting](/vault/docs/platform/mssql/troubleshooting) for tips on specific error codes. + The above steps use the latest version of the specified Transit key as the asymmetric Key Encryption Key (KEK). To + use a different version of the Transit key, please specify the version as shown below. + + ```sql + CREATE ASYMMETRIC KEY TransitVaultAsymmetricV1 + FROM PROVIDER TransitVaultProvider + WITH + CREATION_DISPOSITION = OPEN_EXISTING, + PROVIDER_KEY_NAME = 'ekm-encryption-key?version=1'; + ``` + -> **Note:** Specifying the version + of the Transit key can be useful when sharing KEKs across different SQL Server instances, or in cases of restoring + a database backup that was protected by an older Transit key. + **Note:** This requires vault-mssql-ekm-provider version >= 0.3.0. + 1. Create another login from the new asymmetric key: ```sql diff --git a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx index d70c42839e..94b06c7434 100644 --- a/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/platform/mssql/rotation.mdx @@ -61,3 +61,15 @@ go ALTER DATABASE ENCRYPTION KEY ENCRYPTION BY SERVER ASYMMETRIC KEY TransitVaultAsymmetricV2; ``` + +The above steps will wrap the DEK with the latest version of the specified Transit key as the asymmetric KEK. To use a different version of the Transit key, please specify the version as shown below. + +```sql +CREATE ASYMMETRIC KEY TransitVaultAsymmetricV1 +FROM PROVIDER TransitVaultProvider +WITH CREATION_DISPOSITION = OPEN_EXISTING, +PROVIDER_KEY_NAME = 'ekm-encryption-key?version=1'; +``` + +-> **Note:** This requires vault-mssql-ekm-provider version >= 0.3.0. + diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx index 4b9f05825d..71f3a4facb 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/index.mdx @@ -105,6 +105,8 @@ TTL. For more details on rotating root credentials in the DB Secrets engine, refer to the [Rotate Root credentials](/vault/api-docs/secret/databases#rotate-root-credentials) API docs. +@include 'rotation-manager-logging.mdx' + ## Setup Most secrets engines must be configured in advance before they can perform their @@ -397,6 +399,8 @@ or otherwise, it will not be rotated until the next scheduled rotation. !> The `rotation_period` and `rotation_schedule` fields are mutually exclusive. One of them must be set but not both. +Vault logs rotations with reference to the `name` of the role and `error` if the rotation failed. The logs also indicate if the rotation was part of a `periodic function`. + ## Password generation Passwords are generated via [Password Policies](/vault/docs/concepts/password-policies). diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx index e6d82cdb8c..99f11a6799 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/databases/oracle.mdx @@ -71,6 +71,8 @@ For the Enterprise Oracle database plugin, see the following table: | Plugin release | Instant Client version | | ---------------| -----------------------| +| 0.12.3+ent | 19.26 | +|----------------|------------------------| | 0.11.0+ent | 19.26 | The following privileges are needed by the plugin for minimum functionality. Additional privileges may be needed diff --git a/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx b/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx index 4fa8ac41e8..abe947a910 100644 --- a/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/secrets/ldap.mdx @@ -158,6 +158,8 @@ TTL. For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/secret/ldap#rotate-root) API docs. +@include 'rotation-manager-logging.mdx' + ## Static credentials ### Setup @@ -194,11 +196,17 @@ role, the response will include the time before the next rotation (`ttl`). The `binddn` account used by Vault should be rotated using the `rotate-root` endpoint to generate a password only Vault will know. +As with the rotation manager, Vault logs rotations with reference to the +`name` of the role and `error` if the rotation failed. The logs also indicate + if the rotation was part of a `periodic function`. + ### Manual rotation Static roles can be manually rotated using the `rotate-role` endpoint. When manually rotated the rotation period will start over. +Logging for manual rotation records the same information as other rotation logging with an additional reference that the rotation happened `on user request`. + ### Deleting static roles Passwords are not rotated upon deletion of a static role. The password should be manually diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx index 1cdfbd1fc1..70bda09923 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/automate.mdx @@ -15,8 +15,8 @@ local or cloud storage. ## Before you start -- **You must a working knowledge of how Vault saves data**. -- **You must have a valid Vault cluster configuration using integratd storage**. +- **You must have a working knowledge of how Vault saves data**. +- **You must have a valid Vault cluster configuration using integrated storage**. - **You must know, and be able to contact your unseal/recovery key holders**. - **You must have permission to access encrypted data in backed storage**. - **You should have a secure location, away from your Vault cluster @@ -32,11 +32,11 @@ maintenance, we recommend saving your autosnapshot settings to a JSON file. ### Local storage example The following JSON file, `local-snapshot.json`, defines an automated snapshot -configuration that uses local storage with custom file and path prefixs. The +configuration that uses local storage with custom file and path prefixes. The configuration also sets a 120 minute snapshot frequency, a retention window of 7 snapshots before deleting, and limits the amount of local storage consumed by the snapshot files so Vault stops writing snapshot data if the combined file -size exceed 250 MB (262144000 bytes). +size exceeds 250 MB (262144000 bytes). ```json { @@ -100,7 +100,7 @@ $ vault write \ ``` For example, to configure automated snapshots with local storage in an -unreplicated envionrment: +unreplicated environment: @@ -142,7 +142,7 @@ $ curl \ ``` For example, to configure automated snapshots with local storage in an -unreplicated envionrment called `local-snaps`: +unreplicated environment called `local-snaps`: @@ -173,102 +173,3 @@ $ curl \ - -## Step 3 (Optional): Enable autoloading - -You can configure Vault to automatically load the latest snapshot after -it is written. This is useful if you want to quickly be able to [recover individual -secrets](/vault/docs/sysadmin/recover-a-secret) from a snapshot without having to -manually load the snapshot. - -Only one automated snapshot configuration can have autoloading enabled at a time. -Automated snapshot configurations with their storage type set to `local` cannot -have autoloading enabled. - -If the interval for the automated snapshot configuration is set to less than 1 hour, -Vault will only autoload snapshots every hour. This is to prevent excessive load on the cluster. - -To enable autoloading, set the `autoload_enabled` parameter to `true` when creating or updating -the automated snapshot configuration. For example, we can update the previous AWS S3 example to enable -autoloading: - -```json -{ - "storage_type": "aws-s3", - "file_prefix": "paris", - "interval": "8h", - "retain": 30, - "autoload_enabled": true, - "local_max_space": 2621440000, - "path_prefix": "primary", - "aws_s3_bucket": "vault-snapshots", - "aws_s3_region": "eu-west-3", - "aws_access_key_id": "ASI...COFFEE", - "aws_secret_access_key": "wJalr...COFFEEKEY", - "aws_session_token": "IQoJb3JpZ2luX2IQ...COFFEE", - "aws_s3_server_side_encryption": "true" -} -``` - -and update the configuration in our Vault cluster: - - - - - -Run `vault write` with the -[`/sys/storage/raft/snapshot-auto`](/vault/api-docs/system/storage/raftautosnapshots#create-update-an-automated-snapshots-config) -path and your snapshot configuration to update an automated snapshot configuration: - -```shell-session -$ vault write \ - sys/storage/raft/snapshot-auto/config/ \ - @ -``` - -To update the previous AWS S3 example to enable autoloading: - - -```shell-session -$ vault write \ - sys/storage/raft/snapshot-auto/config/paris-primary \ - @aws-snapshot.json -``` - - - - - - - -Call the -[`/sys/storage/raft/snapshot-auto`](/vault/api-docs/system/storage/raftautosnapshots#create-update-an-automated-snapshots-config) -endpoint with your configuration file to update an automated snapshot configuration: - -```shell-session -$ curl \ - --request POST \ - --header "X-Vault-Token: ${VAULT_TOKEN}" \ - --data @ \ - ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/config/ -``` - - -To update the previous AWS S3 example to enable autoloading: - - - -```shell-session -$ curl \ - --request POST \ - --header "X-Vault-Token: ${VAULT_TOKEN}" \ - --data @aws-snapshot.json \ - ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/config/paris-primary -``` - - - - - - - diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx index 7721fce13e..44439cf295 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/index.mdx @@ -31,8 +31,8 @@ Step-by-step instructions: - [Save a snapshot](/vault/docs/sysadmin/snapshots/save) - [Restore a snapshot](/vault/docs/sysadmin/snapshots/restore) -- [Recover discrete secrets in a replicated evironment](/vault/docs/sysadmin/snapshots/reocver-a-secret/replicated-cluster) -- [Recover discrete secrets in a non-replicated evironment](/vault/docs/sysadmin/snapshots/reocver-a-secret/single-cluster) +- [Recover discrete secrets in a replicated environment](/vault/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster) +- [Recover discrete secrets in a non-replicated environment](/vault/docs/sysadmin/snapshots/recover-a-secret/single-cluster) - [Automate snapshots](/vault/docs/sysadmin/snapshots/recover-a-secret) - [Recover discrete secrets](/vault/docs/sysadmin/snapshots/recover-a-secret) @@ -53,7 +53,7 @@ Detailed tutorials: - [Vault with integrated storage reference architecture](/vault/tutorials/day-one-raft/raft-reference-architecture) - Learn about architectural and operational best practices for deploying Vault - with integraged storage backends in a production environment. + with integrated storage backends in a production environment. - [Configure Vault cluster with integrated storage](/vault/tutorials/raft/raft-storage#automated-snapshots) - Follow a detailed walkthrough for configuring and using automated snapshots. diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx index 70da50a713..05deb0dade 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/index.mdx @@ -18,7 +18,7 @@ can access the data and assign a snapshot ID. Then you can use the snapshot ID to read, list, and recover individual paths from the snapshot. To recover the data, Vault reads the secret at the path from the snapshot to -retrieve that version of the data and sends it to the assocaited plugin backend +retrieve that version of the data and sends it to the associated plugin backend to perform the necessary recover operations. The plugin backend uses the provided data and its own information to create or update data at the specified path in live storage. @@ -39,7 +39,7 @@ supported plugins and paths. Secret restoration has limitations in replicated environments: -- If the active node changes, the loaded snapshot status changes to`error` and +- If the active node changes, the loaded snapshot status changes to `error` and Vault cannot use it for recover operations. You must unload and reload the snapshot to use it again. - Disaster recovery secondaries cannot load snapshots. diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx index a30b5a9e37..ed0fb9bc33 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/recover-a-secret/replicated-cluster.mdx @@ -31,7 +31,7 @@ Load the snapshot holding the secret you want to recover: - For performance replication clusters, you can load snapshots on any cluster, but secondary clusters can only perform snapshot operations on paths that - correspond to local mounts. You must use the primary performance node to peform + correspond to local mounts. You must use the primary performance node to perform snapshot operations on shared paths. @@ -94,29 +94,7 @@ Status key | Description `ready` | Loading completed successfully. You can read data from the snapshot. `error` | Loading failed. Refer to the logs and error details for troubleshooting. -### Use an autoloaded snapshot -If you configured automated snapshots with [autoloading enabled](/vault/docs/sysadmin/snapshots/automate#step-3-optional-enable-autoloading), -Vault Enterprise will automatically load a snapshot when the cluster starts and keep -updating the loaded snapshot as new automated snapshots are created. - -You can check for a loaded snapshot by listing the loaded snapshots: - - - - - -@include 'sysadmin/snapshots/list-snapshots/cli.mdx' - - - - - -@include 'sysadmin/snapshots/list-snapshots/api.mdx' - - - - ## Step 2: Recover the secret diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx index 29305366ac..442e312dfa 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/restore.mdx @@ -11,10 +11,10 @@ Manually restore data for a Vault cluster leader node with a saved snapshot. ## Before you start -- **You must a working knowledge of how Vault saves data**. -- **You must have a valid Vault cluster configuration using integratd storage**. +- **You must have a working knowledge of how Vault saves data**. +- **You must have a valid Vault cluster configuration using integrated storage**. - **You must know, and be able to contact your unseal/recovery key holders**. In - addition to the new root token generated during reinitalization, you need the + addition to the new root token generated during reinitialization, you need the original cluster unseal keys to unseal Vault after restoring the snapshot. - **You must have permission to access encrypted data in backed storage**. @@ -114,7 +114,7 @@ $ curl \ Have each person with an unseal key share run `vault operator unseal` with their original unseal -key until reaching the number of key shares required by your origial quroum +key until reaching the number of key shares required by your original quorum configuration to unseal your Vault cluster: @@ -138,7 +138,7 @@ Unseal Key (will be hidden): Have each person with an unseal key share run [`v1/sys/unseal`](/vault/api-docs/system/unseal) with their original unseal -key until reaching the number of key shares required by your origial quorum +key until reaching the number of key shares required by your original quorum configuration to unseal your Vault cluster: ```shell-session diff --git a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx index 05660d69af..23eb37c056 100644 --- a/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/sysadmin/snapshots/save.mdx @@ -21,8 +21,8 @@ tutorial to learn how you can automate your upgrades with autopilot. ## Before you start -- **You must a working knowledge of how Vault saves data**. -- **You must have a valid Vault cluster configuration using integratd storage**. +- **You must have a working knowledge of how Vault saves data**. +- **You must have a valid Vault cluster configuration using integrated storage**. - **You must know, and be able to contact your unseal/recovery key holders**. - **You must have permission to access encrypted data in backed storage**. - **You should have a secure location, away from your Vault cluster @@ -71,7 +71,7 @@ $ curl \ ## Save a DR replication cluster snapshot -Take a snapshot of a cluster participating in disater recovery replication. +Take a snapshot of a cluster participating in disaster recovery replication. diff --git a/content/vault/v1.21.x (rc)/content/docs/updates/change-tracker.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/change-tracker.mdx index d21102bc41..705514a548 100644 --- a/content/vault/v1.21.x (rc)/content/docs/updates/change-tracker.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/updates/change-tracker.mdx @@ -5,27 +5,31 @@ description: >- History of important upgrade changes for Vault updateds --- -# Vault change tracker +# Vault change tracker Summary tables of important changes that may affect your ability to upgrade Vault. +## Changes for 1.21.x + +@include '../../../global/partials/important-changes/summary-tables/1_20.mdx' + ## Changes for 1.20.x -@include 'release-notes/change-summary/1_20.mdx' +@include '../../../global/partials/important-changes/summary-tables/1_20.mdx' ## Changes for 1.19.x -@include 'release-notes/change-summary/1_19.mdx' +@include '../../../global/partials/important-changes/summary-tables/1_19.mdx' ## Changes for 1.18.x -@include 'release-notes/change-summary/1_18.mdx' +@include '../../../global/partials/important-changes/summary-tables/1_18.mdx' ## Changes for 1.17.x -@include 'release-notes/change-summary/1_17.mdx' +@include '../../../global/partials/important-changes/summary-tables/1_17.mdx' ## Changes for 1.16.x -@include 'release-notes/change-summary/1_16.mdx' \ No newline at end of file +@include '../../../global/partials/important-changes/summary-tables/1_16.mdx' \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx index c9562dd01a..8939266103 100644 --- a/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx @@ -6,99 +6,33 @@ description: >- for upgrading Vault. valid_change_types: >- - - Bug --> must include workaround/recommendation info - - New default - - New behavior - - Breaking --> must include workaround/recommendation info - Change in support + - New behavior (new defaults, new requirements, etc.) + - Breaking change --> workaround/recommendation recommended + - Known issue --> workaround/recommendation required --- # Important changes -**Last updated**: 2025-06-30 +**Last updated**: 2025-10-04 Always review important or breaking changes and remediation recommendations before upgrading Vault. -## New behavior - -### Key pair authentication for Snowflake DB secrets engine - -| Change | Affected version | Affected deployments -| ------------ | ---------------- | -------------------- -| New behavior | 1.20.0 | any - -As of version 1.20.0, Vault supports -[Snowflake database authentication using key pairs](/vault/api-docs/secret/databases#configure-connection) -as an alternative to password authentication, which Snowflake plans to disable -in November 2025. Vault support for password authentication with Snowflake is -now deprecated and will be removed in a future release. - -Vault currently does not support rotate root for key pairs. To manually rotate key pairs, users can: - - - update the root configuration in Vault with the new private key - - update the public key associated with the user in Snowflake - -For more information on rotating key pairs, please refer -to the official [Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation). - ## Breaking changes -### Breaking configuration change for disable_mlock ((#disable_mlock-config)) - -| Change | Affected version | Fixed version -| ------------ | ---------------- | -------------------- -| Breaking | 1.20.0 | N/A - -In Vault 1.20.0 `disable_mlock` is a required configuration setting for -clusters using *integrated storage*. This means that if you are not explicitly -setting a value for `disable_mlock`, the following changes must be made prior -to upgrading. +### Audiences required for Kubernetes authentication roles (##k8-audience-required) - +All tokens for Kubernetes authentication roles must provide explicit audience +details. Vault validates the audience claim in the JWT token to ensure that the +token is actually intended for Vault and not another service. -Clusters missing this config value will fail to start after the upgrade to 1.20.0. +If you do not provide an audience, authentication fails. - - -Before upgrading to Vault 1.20.0, administrators must explicitly add a value for -`disable_mlock` to the outermost level of the server configuration. Refer to the [documentation](/vault/docs/configuration#parameters). -This must be done for all server nodes. Prior to Vault 1.20, the default setting -for `disable_mlock` was false. Therefore, if you do not currently have a value -set for `disable_mlock`, you are using the default setting. If you wish to -maintain this behavior, you will need to explicitly set -`disable_mlock = false` prior to upgrade. - -For clusters that already set a value for `disable_mlock`, no change is required. - -| Cluster Type | `disable_mlock` required | Note -|----------------------------|--------------------------|----- -| Primary | Yes | value depends on cluster specifics. [See docs](/vault/docs/configuration#disable_mlock) -| Performance Secondary | Yes | value depends on cluster specifics. [See docs](/vault/docs/configuration#disable_mlock) -| DR Secondary | Yes | value depends on cluster specifics. [See docs](/vault/docs/configuration#disable_mlock) - - -### One of bound_group_ids or bound_service_principal_ids Must Be Specified in the Role Definition for Azure Authentication Roles - -Azure authentication roles must specify either `bound_group_ids` or `bound_service_principal_ids` in the role definition to prevent -excessively permissive access. This ensures that the role is tailored to the specific needs of the application or service. More information about Azure -authentication roles can be found [here](/vault/docs/auth/azure). Here's an updated example for reference: - -```shell-session -$ vault write auth/azure/role/dev-role \ - policies="prod,dev" \ - bound_subscription_ids=6a1d5988-5917-4221-b224-904cd7e24a25 \ - bound_resource_groups=vault \ - bound_service_principal_ids=3cb88732-1356-4782-b671-4877166be01a -``` - -### Audiences Will Be Required for Kubernetes Authentication Roles in Vault 1.21+ - -Starting in Vault 1.21+, specifying an **audience** will be **mandatory** for all Kubernetes authentication roles. This ensures that the JWT token's aud (audience) claim is explicitly validated, confirming that the token is intended for Vault and not another service. - -Currently, creating or updating a Kubernetes auth role without an audience will result in a warning. However, once Vault 1.21 is released, **any role that does not specify an audience will fail authentication.** +#### Recommendation -To prepare for this change, make sure to include the audience parameter when defining Kubernetes auth roles. More information about Kubernetes authentication roles can be found [here](/vault/docs/auth/kubernetes). Here's an updated example: +Update your Kubernetes authentication roles to include the audience parameter. +For example: ```shell-session vault write auth/kubernetes/role/demo \ @@ -108,158 +42,15 @@ vault write auth/kubernetes/role/demo \ ttl=1h ``` -#### Additional Considerations - -- **Autopilot** - New 1.20.0 nodes are added to the cluster until there is a - quorum of upgraded nodes. Each of these new nodes will need to have a value - for `disable_mlock` set. - -- **Rolling upgrades** - Standby nodes are stopped and upgraded one at a time. - These node configurations will need to be updated before restarting the vault - process on the node. - -- **`dev` mode** - If no config is provided, dev mode will start as usual. If a - config is provided, it must have a value for `disable_mlock`. - - -### Rekey cancellations use a nonce ((#rekey-cancel-nonce)) +Refer to the [Kubernetes authentication docs](/vault/docs/auth/kubernetes) for +more information. -| Change | Affected version | Fixed version -| ------------ | ----------------------------------------- | -------------------- -| Breaking | 1.20.0, 1.19.6, 1.18.11, 1.17.18, 1.16.21 | N/A -Vault 1.20.0, 1.19.6, 1.18.11, 1.17.18, and 1.16.21 require a nonce to cancel -[rekey](/vault/api-docs/system/rekey) and -[rekey recovery key](/vault/api-docs/system/rekey-recovery-key) operations -within 10 minutes of initializing a rekey request. Cancellation requests after -the 10 minute window do not require a nonce and succeed as expected. - -#### Recommendation - -To cancel a rekey operation, provide the nonce value from the -`/sys/rekey/init` or `sys/rekey-recovery-key/init` response. - - -## Bugs +## New behavior None. ## Known issues -### Snowflake DB secrets engine key pair authentication not refreshing credentials successfully ((#snowflake-keypair-refresh)) - -| Change | Status | Affected version | Fixed version -| ----------- | ------ | -------------------------------------- | -------------------- -| Known issue | Open | 1.20.x, 1.19.x, 1.18.x+ent, 1.17.x+ent, 1.16.x+ent | None - -Users using keypair authentication with Snowflake databases may receive errors -due to improper credential refreshes and stale connections in the connection pool. -When two or more concurrent operations occur, Vault tries to reuse an idle -connection from the pool and the request fails due to session timeout in the -Snowflake database. - -#### Recommendation - -As a workaround, you can set the `max_connection_lifetime` to a value below `SESSION_IDLE_TIMEOUT_MINS`. - -### UI KV v2 overview for secret paths containing underscores ((#ui-kvv2-underscore-secrets)) - -| Change | Affected version | Fixed version -| ------------ | ---------------- | -------------------- -| Known issue | 1.20.0 | 1.20.1 - -Users receive an error when navigating to a KV v2 secret with an underscore in the name (e.g. `my_secret`) -if the user does not have policy permissions granting `read` access to the [`/subkeys` endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-subkeys). - -#### Recommendation - -As a workaround, you can use the [GUI CLI emulator](/vault/docs/ui/web-cli) to read secret data or metadata. - -You can also use the API explorer to make any HTTP request: - -1. Select **Tools** from the Vault GUI sidebar. -1. Click **API Explorer**. -1. Enter the KV v2 plugin mount path in the "Filter by tag" search bar. -1. Expand the endpoint for the action you wish to perform and click **Try it out**. -1. Provide the required parameters. For example, to read a KV v2 secret the `path` must be provided. -1. Provide any optional parameters desired. -1. Click **Execute** to perform the HTTP request. - -### UI login fails for auth mounts with underscores and unauthenticated listing ((#ui-login-underscore)) - -| Change | Affected version | Fixed version -| ------------ | ---------------- | -------------------- -| Known issue | 1.20.0 | 1.20.1 - -Login requests to auth methods mounted at paths using underscores (e.g. `oidc_test`) -with `listing_visibility="unauth"` fail because the GUI calls the wrong -endpoint. Mounts with dashes (e.g. `oidc-test`) work correctly. - -#### Recommendation - -As a workaround, you can log in to the GUI using the following steps: - -1. Navigate directly to the URL for the desired method type (e.g. `${VAULT_ADDR}/ui/vault/auth?with=oidc`) -1. Click "Sign in with other methods ->" -1. Select the method type from the dropdown -1. Click **Advanced settings** and provide the correct path (e.g., `oidc_test`). - -We also recommend creating a [custom GUI message](/vault/docs/ui/custom-message) describing the workaround steps for users. - -### Duplicate unseal/seal wrap HSM keys ((#hsm-keys)) - -| Change | Status | Affected version | Fixed version -| ----------- | ------ | -------------------------------------- | -------------------- -| Known issue | Open | 1.20.x, 1.19.x, 1.18.x, 1.17.x, 1.16.x | None - -In HSM-HA configurations migrating from Shamir to HSM-backed unseal/seal wraps, -Vault may create duplicate HSM keys when you migrate from Shamir to an -HSM-backed unseal configuration for high availability (HA) HSM deployments. Key -duplication can happen even after a seal migration to HSM that initially -appears successful. - -Duplicate HSM keys can cause the following errors: - -- intermittent read failures with errors such as `CKR_SIGNATURE_INVALID` and `CKR_KEY_HANDLE_INVALID` for -[seal-wrapped values](/vault/docs/enterprise/sealwrap#wrapped-parameters). -- nodes fail to unseal after a restart with errors such as `CKR_DATA_INVALID`. - -#### Recommendation - -Always run Vault with `generate_key = false` and manually create all required -keys within the HSM during the setup process. - -### Duplicate LDAP Password Rotations on Standby Node Check-In ((#ldap-checkin)) - -| Change | Affected version | Fixed version -| ------------ | ----------------------------------------- | -------------------- -| Known issue | 1.12.0+ | N/A - -Vault check-ins for LDAP service accounts performed on a performance standby node or a node in a -performance replication secondary cluster can trigger duplicate password changes on the LDAP server. -Duplication occurs because the LDAP client on the local node successfully modifies the password before Vault -forwards the check-in request to the active node, which then performs a second password update. -While users still receive the latest password, it may lead to unexpected LDAP activity and cause -confusion interpreting audit logs. - -### Recommendation: - -Send check-in requests directly to the active node of the primary cluster to prevent duplicate password -rotations on the LDAP server. - -### Development cluster setting overwritten on secondary cluster reload ((#development-cluster-reload)) - -| Change | Affected version | Fixed version -| ------------ |------------------| -------------------- -| Known issue | 1.20.0 | 1.20.1 - -If the Vault process receives a `SIGHUP` and reloads a secondary performance -replication cluster, the cluster reverts to the locally configured -`development_cluster` value instead of following the value configured on the -primary cluster. - -#### Recommendation: - -Ensure all clusters in a performance replication group have the same `development_cluster` value configured in HCL to -prevent unexpected changes to the reported value. +None. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/docs/updates/lts-tracker.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/lts-tracker.mdx new file mode 100644 index 0000000000..b5f0b27ab5 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/docs/updates/lts-tracker.mdx @@ -0,0 +1,29 @@ +--- +layout: docs +page_title: LTS Vault change tracker +description: >- + General guidance and important changes at a glance for LTS upgrades +--- + +# LTS Vault change tracker + +[Long-term support](/vault/docs/enterprise/) offers extended maintenance through +minor releases for select, major Vault Enterprise versions. + +Current LTS release | Extended maintenance release +------------------- | ---------------------------- +1.19.x | 1.16.x + +Before you perform a direct LTS upgrade from an extended maintenance release to +the current LTS release, we recommend reviewing the following summary of +functional changes and known issues to determine the likely impact on your Vault +deployment. + +Functional changes affect how Vault works including new requirements, new +defaults, new behavior, and breaking changes. In some cases, we recommend specific +actions before or after upgrading to mitigate the impact of a functional change. + +Unresolved nown issues may have suggested workarounds or mitagation strategies +you should consider before upgrading. + +@include '../../../global/partials/important-changes/summary-tables/lts/1_16-to-1_19.mdx' diff --git a/content/vault/v1.21.x (rc)/content/docs/updates/release-notes.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/release-notes.mdx index c6fe872c9a..cbd07a787b 100644 --- a/content/vault/v1.21.x (rc)/content/docs/updates/release-notes.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/updates/release-notes.mdx @@ -7,376 +7,44 @@ description: >- # Vault release notes -- **Version**: 1.20.x -- **GA date**: 2025-06-25 +- **Version**: 1.21.x +- **GA date**: TBD @include 'release-notes/intro.mdx' -## Executive summary - -Vault Enterprise 1.20.0 streamlines the user experience, and improves visibility -and transparency around billing, auditing, and Vault usage. The latest version -of Vault also introduces new capabilities related to cryptography, secret -recovery, and provides enhanced ecosystem integrations for centralizing secrets. +@include 'tips/change-tracker.mdx' +## Executive summary +Pending. ### Highlights -- Improves support for chargeback and showback with enhanced visibility into the - underlying source of costs. - -- Simplifies and enhances the user experience by improving namespace navigation, - providing a customizable login function, and releasing a new secret recovery - function. - -- Enhances and expands secure integrations by reducing friction on plugin - distribution and supporting key-value-compatible secret import from AWS, Azure, - and GCP. - -- Adds SCEP protocol support in Vault PKI for certificate automation and reduces - IT footprint by eliminating the need for alternate PKI solutions explictly for - SCEP integration. - -- Verified Vault PKI SCEP integrations with Azure Intune and JAMF for - certificate automation reduce operational burdens such as outages or security - breachs due to certificate expiry. - -- Enhances resilience by providing reliability improvements, control over - traffic flows, and the ability to ensure fairness of Vault consumption across - users and applications. - -- Better auditability and visibility into audit logs, certificates, Vault - feature usage, and opinionated suggestions for improving Vault usage, including - benchmarking that supports migrating from Consul to integrated storage. - +Pending. ## Feature deprecations and EOL -Deprecated in 1.20.x | Retired in 1.20.x +Deprecated in 1.21.x | Retired in 1.21.x -------------------- | --------------- -[Duplicate HCL attributes](/vault/docs/updates/deprecation#duplicate-hcl-attributes) | None -[Snowflake DB password authentication](/vault/docs/updates/deprecation#snowflake-db-password-authentication) |   +None | None @include 'release-notes/deprecation-note.mdx' -## Important changes - -@include 'release-notes/change-summary/1_20.mdx' - +## Feature updates: System administration and operational updates +None. -## System administration and operational updates - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
UpdateTypeLicenseDescription
- Product usage data updates - EnhancedEnterprise - Vault collects and reports additional data points to Hashicorp for - improved product usage tracking. -

- Learn more: Anonymous product usage reporting -
- Production vs. non-production cluster assignment - GAEnterprise - Designate individual clusters as production or non-production. Vault - reports individual cluster status to Hashicorp. -

- Learn more: Development cluster configuration -
- Default login methods - GAEnterprise - Configure default and back up login methods for Vault GUI to reduce - complexity and confusion. -

- Learn more: Manage custom login settings -
- Client count dashboard updates - EnhancedEnterprise - Provides improved visibility into client count attribution, increases - accuracy by removing estimates, and sets the current billing period in - Vault GUI based on the current Vault configuration. -

- Learn more: Client usage overview -
- Client count current month accuracy - EnhancedEnterprise - Removed partial month estimates from client count to improve client count - accuracy for the current month. -

- Learn more: Partial month client count endpoint -
- GUI Namespace picker updates - EnhancedEnterprise - Search, filter, and navigate to namespaces in the GUI without having to - reauthenticate while enjoying reduced performance load and enhanced - accessibility. -

- Learn more: Manage namespaces in the Vault GUI -
- HTTP status telemetry - GAEnterprise - Use Vault telemetry to track running total count by HTTP status codes. -

- Learn more: vault.core.response_status_code -
- Cluster wide client telemetry - GAEnterprise - Capture Vault telemetry to track the total count of distinct clients in a - cluster. The metric updates every 10 minutes to support live reporting and - alerting. -

- Learn more: vault.client.billing_period.activity -
- Identity-based rate limit quotas - GAEnterprise - Apply rate limit quotas by entity ID instead of IP for more granular and - flexible control over traffic flow and easier management of misbehaving - applications and users. -

- Learn more: Resource quotas overview -
- Collective rate limit quotas - GAEnterprise - Apply collective rate limit quotas to all traffic globally or by targeting - a namespace, path, or mount to enforce collective limits without having to - account for individual IP addresses. -

- Learn more: Resource quotas overview -
- Secret recovery - GAEnterprise - Recover an accidentally changed or deleted secret without performing a - full cluster snapshot restoration, degrading the cluster, or impacting - other items in the cluster. -

- Learn more: Item recovery from a snapshot -
- GUI for TOTP - GACommunity - Users with TOTP access can use the Vault GUI to view their accounts, add a - new account, see their hidden-by-default TOTP codes, and view timers for - when their TOTPs expire. -
- Utilization reporting - GAEnterprise - Review and identify the features used in a given cluster to determine - where you might want to leverage additional Vault functionality. -

- Learn more: /sys/utilization-report reference -
- Secrets import - BetaEnterprise - Migrate existing secrets to Vault to centralize secrets management and - realize the value of Vault faster. -

- Learn more: Secrets import overview -
- Event notifications data consistency - GAEnterprise - Event notifications include metadata to prevent stale data reads from - secondary nodes during periods of high Vault load. -

- Learn more: Event notifications overview -
- Plugin downloads - BetaEnterprise - Use new endpoints to simplify downloading official HashiCorp secret and - auth plugins from releases.hashicorp.com. -

- Learn more: Register external plugins -
- Ephemeral resources support - GAEnterprise - Use the Vault provider for Terraform with ephemeral resources and write-only - attributes in key-value and database secret engines. -

- Learn more: Vault provider for Terraform -
- -## Manage 3rd-party secrets +## Feature updates: Manage 3rd-party secrets @include 'release-notes/section-notes/3rd-party.mdx' - - - - - - - - - - - - - - - - - - - - - - - -
UpdateTypeLicenseDescription
- Snowflake authentication support for key pairs - GACommunity - Implement enhanced authentication security with key pair authentication in - the Snowflake database secrets engine. -

- Learn more: Snowflake overview -
- Terraform support for dynamic team tokens - GACommunity - Implement dynamic team token generation in the Terraform Cloud secrets engine. -

- Learn more: Terraform Cloud overview -
- +None. -## Manage certificates +## Feature updates: Manage certificates @include 'release-notes/section-notes/certs.mdx' - - - - - - - - - - - - - - - - - -
UpdateTypeLicenseDescription
- PKI support for SCEP certificate enrollment - GACommunity - Automate certificate enrollment of end-user and network devices that - support SCEP protocol. End-user device integration validations include - Azure In-Tune and Jamf MDM platforms. -
+None. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx b/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx index d285751b46..f8cf60f2b0 100644 --- a/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/cli/audit/args/file/mode.mdx @@ -3,7 +3,8 @@ **`mode (string : "0600")`** The `chmod`-style octal permissions for the audit file. Set `mode` to "0000" to -prevent Vault from modifying the file mode. +prevent Vault from modifying the file mode. File audit devices cannot use file +modes with executable permissions (e.g., 0777, 0755). -**Example**: `mode="0755"` +**Example**: `mode="0644"` diff --git a/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx b/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx index 049d484623..0d35f29382 100644 --- a/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/global-settings/both/client-cert.mdx @@ -4,7 +4,7 @@ Path to a PEM-encoded CA certificate file on the local disk. Used for TLS communication with the server. **The specified certificate must match to the -private key specified with `-client-cert`**. +private key specified with `-client-key`**. **Examples**: diff --git a/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx b/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx index 37efe4b033..ff2de18675 100644 --- a/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/kubernetes-supported-versions.mdx @@ -4,10 +4,10 @@ The following [Kubernetes minor releases][k8s-releases] are currently supported. The latest version is tested against each Kubernetes version. It may work with other versions of Kubernetes, but those are not supported. +* 1.33 * 1.32 * 1.31 * 1.30 * 1.29 -* 1.28 [k8s-releases]: https://kubernetes.io/releases/ diff --git a/content/vault/v1.21.x (rc)/content/partials/rotation-manager-logging.mdx b/content/vault/v1.21.x (rc)/content/partials/rotation-manager-logging.mdx new file mode 100644 index 0000000000..75c26c62b3 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/rotation-manager-logging.mdx @@ -0,0 +1,12 @@ +### Rotation logging + +The rotation manager emits logs to the standard `vault.log` on any successful or +failed rotation. + +In the case of success, Vault notes: + +- the rotated credential as the first parameter, `rotationID`. +- the anticipated time of the next rotation as `expire_time`. + +In the case of failure, Vault sets `rotationID` to `err` and may emit additional +logs depending on the configured log level. diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx index 768709dd0f..7bee52a261 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/disabled-mount-warning.mdx @@ -1,9 +1,9 @@ You cannot read, list, or recover information from a snapshot for disabled - mount paths. Even if you reenable the same plugin at the same path, Vault + mount paths. Even if you re-enable the same plugin at the same path, Vault treats it as a new mount with different internal identifiers and cannot - associate the reenabled mount with the underlying storage entries within the + associate the re-enabled mount with the underlying storage entries within the snapshot. diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx index 8a457e5a9c..084a86a74a 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/load-snapshot/api/auto.mdx @@ -1,4 +1,4 @@ -Use the `/sys/storage/raft/snapshot-load` endpoint with the snapshot +Use the `/sys/storage/raft/snapshot-auto/snapshot-load` endpoint with the snapshot configuration name and cloud storage URL to load a snapshot file and assign a snapshot ID: @@ -7,7 +7,7 @@ $ curl \ --request POST \ --header "X-Vault-Token: ${VAULT_TOKEN}" \ --data '{"url": ""}' \ - ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/ + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/snapshot-load/ ``` For example: @@ -19,7 +19,7 @@ $ curl \ --request POST \ --header "X-Vault-Token: ${VAULT_TOKEN}" \ --data '{"url": "https://bucket.example.com/vault-snapshots/primary/paris-backup.snap"}' \ - ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-load/paris-primary | jq + ${VAULT_ADDR}/v1/sys/storage/raft/snapshot-auto/snapshot-load/paris-primary | jq { "data": { diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx index 4c84229b65..ef7a582859 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-requirements/load-snapshots.mdx @@ -1,10 +1,8 @@ - **You must have an integrated storage snapshot**. You can only restore data - from [automatically](/vault/docs/sysadmin/snapshots/automat) or + from [automatically](/vault/docs/sysadmin/snapshots/automate) or [manually](/vault/docs/sysadmin/snapshots/save) saved snapshots for integrated storage. - **You must have a snapshot from the cluster targeted for restoration**. -- **You must have access to the unseal keys, or the people with unseal keys, for - the target cluster** - **The cluster must have [mlock](/vault/docs/configuration#disable_mlock) disabled**. -- **The cluster cannot have anoter snapshot loaded**. +- **The cluster cannot have another snapshot loaded**. diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx index a15afddbb4..c92ed232f0 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/restore-secret-support.mdx @@ -1,6 +1,5 @@ -| Plugin | Path | Supported snapshot operations | Vault version | -|-----------|----------------------------|-------------------------------|---------------| -| cubbyhole | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 | -| kv (v1) | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 | -| databases | `/static-roles/:role_name` | `recover`, `read`, `list` | 1.20.4 | -| databases | `/static-creds/:role_name` | `read` | 1.20.4 | \ No newline at end of file +Plugin | Path | Supported snapshot operations | Vault version +--------- | --------------- | ----------------------------- | -------------- +cubbyhole | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 +kv (v1) | `/:secret_name` | `recover`, `read`, `list` | 1.20.0 +ssh | `/config/ca` | `recover`, `read` | 1.20.3 diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx index 80f6c4ee68..680477d2d4 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/api.mdx @@ -1,20 +1,12 @@ - -In the following examples, we set the HTTP method to `RECOVER`. Vault also supports -using the `PUT` or `POST` HTTP method for recover operations. If the request contains -the `X-Vault-Recover-Snapshot-Id` header, then Vault will treat the request as a -recover operation. - - -Use the `X-Vault-Recover-Snapshot-Id` header and the snapshot ID to read from +Use the `recover_snapshot_id` query parameter and the snapshot ID to read from the secret path and write the recovered data to the corresponding mount path on the Vault server: ```shell-session -$ curl \ - --request RECOVER \ - --header "X-Vault-Token: ${VAULT_TOKEN}" \ - --header "X-Vault-Recover-Snapshot-Id: " \ - ${VAULT_ADDR}/v1// +$ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1//?recover_snapshot_id= ``` For example, to recover secrets at `telemetry-systems/api-key` from a key/value @@ -23,41 +15,10 @@ version 1 plugin mounted at the default path, call the `/kv/{secret_path}` endpo ```shell-session -$ curl \ - --request RECOVER \ - --header "X-Vault-Token: ${VAULT_TOKEN}" \ - --header "X-Vault-Recover-Snapshot-Id: 9465df92-8236-4af9-8cc8-b7460d882e41" \ - ${VAULT_ADDR}/v1/kv/telemetry-systems/api-key +$ curl \ + --request GET \ + --header "X-Vault-Token: ${VAULT_TOKEN}" \ + ${VAULT_ADDR}/v1/kv/telemetry-systems/api-key?recover_snapshot_id=9465df92-8236-4af9-8cc8-b7460d882e41 ``` - -You can also recover data to a different path than the original path in the -snapshot, so long as both paths are on the same mount. Use the `X-Vault-Recover-Source-Path` -header to specify the original path of the data in the snapshot: - -```shell-session -$ curl \ - --request RECOVER \ - --header "X-Vault-Token: ${VAULT_TOKEN}" \ - --header "X-Vault-Recover-Snapshot-Id: " \ - --header "X-Vault-Recover-Source-Path: /" \ - ${VAULT_ADDR}/v1// -``` - -For example, to recover secrets at `telemetry-systems/api-key` from a key/value -version 1 plugin mounted at the default path, but write the recovered data to -`telemetry-systems/api-key-recovered`, call the `/kv/{new_secret_path}` endpoint: - - - -```shell-session -$ curl \ - --request RECOVER \ - --header "X-Vault-Token: ${VAULT_TOKEN}" \ - --header "X-Vault-Recover-Snapshot-Id: 9465df92-8236-4af9-8cc8-b7460d882e41" \ - --header "X-Vault-Recover-Source-Path: kv/telemetry-systems/api-key" \ - ${VAULT_ADDR}/v1/kv/telemetry-systems/api-key-recovered -``` - - \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/cli.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/cli.mdx index 02ccd8fc1c..4a897c2e7c 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/cli.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/recover/cli.mdx @@ -1,8 +1,8 @@ -Use `vault recover` with the snapshot ID to read from the secret path and write +Use `vault read` with the snapshot ID to read from the secret path and write the recovered data to the corresponding mount path on the Vault server: ```shell-session -$ vault recover \ +$ vault read \ -snapshot-id \ / ``` @@ -11,35 +11,10 @@ For example: - ```shell-session - $ vault recover \ +```shell-session +$ vault read \ -snapshot-id 9465df92-8236-4af9-8cc8-b7460d882e41s \ kv/telemetry-systems/api-key - ``` - - - -You can also recover data to a different path than the original path in the -snapshot, so long as both paths are on the same mount. Use the `-from` -flag to specify the original path of the data in the snapshot: - -```shell-session -$ vault recover \ - -snapshot-id \ - -from / \ - / ``` -For example, to recover secrets at `telemetry-systems/api-key` from a key/value -version 1 plugin mounted at the default path, but write the recovered data to -`telemetry-systems/api-key-recovered`: - - - -```shell-session -$ vault recover \ - -snapshot-id 9465df92-8236-4af9-8cc8-b7460d882e41s \ - -from kv/telemetry-systems/api-key \ - kv/telemetry-systems/api-key-recovered -``` - \ No newline at end of file + diff --git a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx index e00a2c66a2..fb9f2f29a8 100644 --- a/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx +++ b/content/vault/v1.21.x (rc)/content/partials/sysadmin/snapshots/secret-restore/verify/api.mdx @@ -1,6 +1,6 @@ To verify secret recovery, read the secret from the expected path. For example, -if you recovered secrets at `telemetry-systems/api-key` from a key/value plugin -mounted at the default path, call the `/kv/data/{secret_path}` endpoint: +if you recovered secrets at `telemetry-systems/api-key` from a key/value version +1 plugin mounted at the default path, call the `/kv/{secret_path}` endpoint: ```shell-session $ curl \ diff --git a/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/fsm/saturation.mdx b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/fsm/saturation.mdx new file mode 100644 index 0000000000..64d3451bdf --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/fsm/saturation.mdx @@ -0,0 +1,8 @@ +### vault.raft.thread.fsm.saturation ((#vault-raft-thread-fsm-saturation)) + +Metric type | Value | Description +----------- | ----------- | ----------- +gauge | percentage | Approximate proportion of time the raft FSM goroutine could not accept new work + +High saturation of the raft goroutines can increase latency in the rest of the +system and cause cluster instability. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/main/saturation.mdx b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/main/saturation.mdx new file mode 100644 index 0000000000..7a00edefcb --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/telemetry-metrics/vault/raft/thread/main/saturation.mdx @@ -0,0 +1,8 @@ +### vault.raft.thread.main.saturation ((#vault-raft-thread-main-saturation)) + +Metric type | Value | Description +----------- | ----------- | ----------- +gauge | percentage | Approximate proportion of time the main raft goroutine could not accept new work + +High saturation of the raft goroutines can increase latency in the rest of the +system and cause cluster instability. \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/partials/tips/change-tracker.mdx b/content/vault/v1.21.x (rc)/content/partials/tips/change-tracker.mdx new file mode 100644 index 0000000000..a1b6836b27 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/tips/change-tracker.mdx @@ -0,0 +1,7 @@ + + +Review historic breaking changes, new behavior, and known issues at a +glance with the [historic change tracker](/vault/docs/updates/change-tracker) and +[LTS update tracker](/vault/docs/updates/lts-tracker) pages. + + \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/data/docs-nav-data.json b/content/vault/v1.21.x (rc)/data/docs-nav-data.json index 57ea340139..577dad811d 100644 --- a/content/vault/v1.21.x (rc)/data/docs-nav-data.json +++ b/content/vault/v1.21.x (rc)/data/docs-nav-data.json @@ -293,13 +293,17 @@ "title": "Deprecation notices", "path": "updates/deprecation" }, + { + "title": "LTS Vault tracker", + "path": "updates/lts-tracker" + }, { "title": "Change tracker", "path": "updates/change-tracker" }, { "title": "Full changelog", - "href": "https://raw.githubusercontent.com/hashicorp/vault/refs/heads/main/CHANGELOG.md" + "href": "https://github.com/hashicorp/vault/blob/main/CHANGELOG.md" } ] }, @@ -982,10 +986,6 @@ "title": "Manual upgrade for HA deployments", "path": "upgrade/vault-ha-upgrade" }, - { - "title": "LTS Vault upgrades", - "path": "upgrade/lts-upgrade" - }, { "title": "Rollback an upgrade", "path": "upgrade/rollback" @@ -2674,12 +2674,20 @@ ] }, { - "title": "Audit Devices", + "title": "Audit logging", "routes": [ { "title": "Overview", "path": "audit" }, + { + "title": "Auditing schema", + "path": "audit/schema" + }, + { + "title": "Best practices", + "path": "audit/best-practices" + }, { "title": "File", "path": "audit/file" diff --git a/content/vault/v1.21.x (rc)/img/vault-client-workflows.png b/content/vault/v1.21.x (rc)/img/vault-client-workflows.png new file mode 100755 index 0000000000..180cffe286 Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/vault-client-workflows.png differ diff --git a/content/vault/v1.21.x (rc)/img/vault-clients.png b/content/vault/v1.21.x (rc)/img/vault-clients.png new file mode 100755 index 0000000000..670f87f39d Binary files /dev/null and b/content/vault/v1.21.x (rc)/img/vault-clients.png differ diff --git a/content/vault/v1.21.x (rc)/redirects.jsonc b/content/vault/v1.21.x (rc)/redirects.jsonc index a36b2cb975..750b21d7a6 100644 --- a/content/vault/v1.21.x (rc)/redirects.jsonc +++ b/content/vault/v1.21.x (rc)/redirects.jsonc @@ -1,92 +1,94 @@ /** * Copyright (c) HashiCorp, Inc. * SPDX-License-Identifier: BUSL-1.1 - */ + * + * Refer to the redirect docs for examples and regex information: + * + * https://github.com/hashicorp/web-unified-docs/blob/main/docs/redirects.md + **/ + [ - // example redirect: - // { - // "source": "/vault/docs/some/path", - // "destination": "/vault/docs/some/other/path", - // "permanent": true, - // }, + /***************************************************************************** + * Pre-2023 redirects + *****************************************************************************/ + { "source": "/vault/docs/plugins/plugin-portal", "destination": "/vault/integrations", "permanent": true }, + + + /***************************************************************************** + * ~2023 IA update: Combine agent and new proxy docs under /docs/agent-and-proxy + *****************************************************************************/ + + // Redirect from deleted overview to first available method { "source": "/vault/docs/agent-and-proxy/autoauth/methods", "destination": "/vault/docs/agent-and-proxy/autoauth/methods/alicloud", "permanent": true }, + + // Redirect /agent/autoauth/* paths to /agent-and-proxy/autoauth/* { - "source": "/vault/docs/agent/autoauth/:slug(.*)", - "destination": "/vault/docs/agent-and-proxy/autoauth/:slug", - "permanent": true - }, - { - "source": "/vault/docs/agent/template", - "destination": "/vault/docs/agent-and-proxy/agent/template", - "permanent": true - }, - { - "source": "/vault/docs/agent/winsvc", - "destination": "/vault/docs/agent-and-proxy/agent/winsvc", + "source": "/vault/docs/agent/autoauth/:slug*", + "destination": "/vault/docs/agent-and-proxy/autoauth/:slug*", "permanent": true }, + + // Redirect the other docs/agent/* paths to /agent-and-proxy/agent/* { - "source": "/vault/docs/agent/versions", - "destination": "/vault/docs/agent-and-proxy/agent/versions", - "permanent": true - }, - { - "source": "/vault/docs/agent/apiproxy", - "destination": "/vault/docs/agent-and-proxy/agent/apiproxy", - "permanent": true - }, - { - "source": "/vault/docs/agent", - "destination": "/vault/docs/agent-and-proxy/agent", - "permanent": true - }, - { - "source": "/vault/docs/agent/caching", - "destination": "/vault/docs/agent-and-proxy/agent/caching", - "permanent": true - }, - { - "source": "/vault/docs/agent/caching/:slug(.*)", - "destination": "/vault/docs/agent-and-proxy/agent/caching/:slug", - "permanent": true - }, - { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent", - "destination": "/vault/docs/:version/agent/", - "permanent": true - }, - { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/template", - "destination": "/vault/docs/:version/agent/template", + "source": "/vault/docs/agent/:slug((?!autoauth$).*)", + "destination": "/vault/docs/agent-and-proxy/agent/:slug", "permanent": true }, + + /** + Backfacing redirects for agent-and-proxy/autoauth/* to legacy URLs + + - Source: {version}/agent-and-proxy/autoauth/* (new URL) + Target: {version}/agent/autoauth/* + Range: 1.4.x through 1.13.x + **/ { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/caching", - "destination": "/vault/docs/:version/agent/caching", + "source": "/vault/docs/:version(v1\\.(?:[4-9]|1[0-3])\\.x)/agent-and-proxy/autoauth/:slug*", + "destination": "/vault/docs/:version/agent/autoauth/:slug*", "permanent": true }, + + /** + Backfacing redirects for agent-and-proxy/agent/* to legacy URLs + + - Source: {version}/agent-and-proxy/proxy/apiproxy (new URL) + Target: {version}/agent/apiproxy + Range: 1.4.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/* (new URL) + Target: {version}/agent/* + Range: 1.4.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/caching/* (new URL) + Target: {version}/agent/* + Range: 1.8.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/winsvc (new URL) + Target: {version}/agent/winsvc + Range: 1.7.x - 1.13.x + - Source: {version}/agent-and-proxy/agent/generate-config (new URL) + Target: {version}/agent/template-config + Range: 1.8.x - 1.9.x + **/ { - "source": "/vault/docs/:version(v1\\.(?:4|5|6|7|8|9|10|11|12|13)\\.x)/agent-and-proxy/autoauth/:slug(.*)", - "destination": "/vault/docs/:version/agent/autoauth/:slug", + "source": "/vault/docs/:version(v1\\.(?:[4-9]|1[0-3])\\.x)/agent-and-proxy/agent/:slug((?!autoauth$|caching$|winsvc$|generate-config$).*)", + "destination": "/vault/docs/:version/agent/:slug", "permanent": true }, { - "source": "/vault/docs/:version(v1\\.(?:8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/caching/:slug(.*)", - "destination": "/vault/docs/:version/agent/caching/:slug", + "source": "/vault/docs/:version(v1\\.(?:8|9|1[0-3])\\.x)/agent-and-proxy/agent/caching/:slug*", + "destination": "/vault/docs/:version/agent/caching/:slug*", "permanent": true }, { - "source": "/vault/docs/:version(v1\\.(?:7|8|9|10|11|12|13)\\.x)/agent-and-proxy/agent/winsvc", + "source": "/vault/docs/:version(v1\\.(?:[7-9]|1[0-3])\\.x)/agent-and-proxy/agent/winsvc", "destination": "/vault/docs/:version/agent/winsvc", "permanent": true }, @@ -95,21 +97,35 @@ "destination": "/vault/docs/:version/agent/template-config", "permanent": true }, + + + /***************************************************************************** + 2024 | Active Directory plugin EOL + *****************************************************************************/ + + // Redirect AD guides to the replacement plugin (LDAP) { - "source": "/vault/docs/v1.13.x/agent-and-proxy/agent/versions", - "destination": "/vault/docs/v1.13.x/agent/versions", + "source": "/vault/api-docs/secret/ad", + "destination": "/vault/api-docs/secret/ldap", "permanent": true }, { - "source": "/vault/docs/v1.13.x/agent-and-proxy/agent/apiproxy", - "destination": "/vault/docs/v1.13.x/agent/apiproxy", + "source": "/vault/docs/secrets/ad", + "destination": "/vault/docs/secrets/ldap", "permanent": true }, + + // Redirect the AD migration guide to the last supported version { - "source": "/vault/api-docs/system/plugins-reload-backend", - "destination": "/vault/api-docs/system/plugins-reload", + "source": "/vault/docs/secrets/ad/migration-guide", + "destination": "/vault/docs/v1.18.x/secrets/ad/migration-guide", "permanent": true }, + + + /***************************************************************************** + 2024-2025 | IA update: Deprecation redirects + *****************************************************************************/ { "source": "/vault/docs/deprecation/faq", "destination": "/vault/docs/deprecation", @@ -120,36 +136,34 @@ "destination": "/vault/docs/updates/deprecation", "permanent": true }, + + + + /***************************************************************************** + 2024-2025 | IA update: CLI content refresh + *****************************************************************************/ { - "source": "/vault/docs/concepts/lease-explosions", - "destination": "/vault/docs/configuration/prevent-lease-explosions", - "permanent": true - }, - { - "source": "/vault/docs/troubleshoot/lease-explosions", - "destination": "/vault/docs/configuration/prevent-lease-explosions", - "permanent": true - }, - { - "source": "/vault/docs/concepts/lease-count-quota-exceeded", - "destination": "/vault/docs/troubleshoot/lease-count-quota-exceeded", + "source": "/vault/api-docs/system/plugins-reload-backend", + "destination": "/vault/api-docs/system/plugins-reload", "permanent": true }, { - "source": "/vault/docs/command/web", + "source": "/vault/docs/commands/web", "destination": "/vault/docs/ui/web-cli", "permanent": true }, { - "source": "/vault/docs/:version(v1\\.(?:8|9)\\.x)/agent-and-proxy/agent/generate-config", - "destination": "/vault/docs/:version/agent/template-config", - "permanent": true - }, - { - "source": "/vault/docs/faq/ssct", - "destination": "/vault/docs/v1.10.x/faq/ssct", + "source": "/vault/docs/commands/hcp", + "destination": "/vault/docs/commands/hcp/connect", "permanent": true }, + + + /***************************************************************************** + 2025 | IA update: Upgrade guides + *****************************************************************************/ + + // Standard redirects { "source": "/vault/docs/upgrading", "destination": "/vault/docs/upgrade", @@ -171,60 +185,154 @@ "permanent": true }, { - "source": "/vault/docs/upgrading/deduplication/:slug(.*)", - "destination": "/vault/docs/secrets/identity/deduplication/:slug", + "source": "/vault/docs/upgrading/deduplication/:slug*", + "destination": "/vault/docs/secrets/identity/deduplication/:slug*", "permanent": true }, + + /** + Versioned redirects for /upgrading/upgrade-to-{version} to versioned URLs + + NOTE: Before v1.9, the upgrade guide for version X of Vault was published + under version X+1 of the docs and every patch update had its own upgrade + guide. For simplicity, we redirect version-specific upgrade guides prior to + 1.9 to the versioned instance of that guide under the 1.9.x docs + + - Source: /upgrading/upgrade-to-{version}.{patch} + Target: v1.9.x/upgrading/upgrade-to-{version}.{patch} + Range: 0.5.* - 0.11.*, 1.0.* - 1.8.* (page name) + - Source: /upgrading/upgrade-to-{version}.x + Target: {version}.x/upgrading/upgrade-to-{version}.x + Range: 1.9.x - 1.18.x + - Source: /upgrading/upgrade-to-19.x + Target: v1.19.x/updates/important-changes + Range: 1.19.x + **/ + + // Redirect 0.5.* through 0.11.* guides to their v1.9.x instance { - "source": "/vault/docs/upgrading/upgrade-to-:version(0\\.(?:5|6|7|8|9|10|11)).:patch(.*)", + "source": "/vault/docs/upgrading/upgrade-to-:version(0\\.(?:[5-9]|10|11)).:patch(.*)", "destination": "/vault/docs/v1.9.x/upgrading/upgrade-to-:version.:patch", "permanent": true }, + // Redirect 1.0.* through 1.8.* guides to their v1.9.x instance { - "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:0|1|2|3|4|5|6|7|8)).:patch(.*)", + "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:[0-8])).:patch(.*)", "destination": "/vault/docs/v1.9.x/upgrading/upgrade-to-:version.:patch", "permanent": true }, + // Redirect 1.9.x through 1.18.x guides to the instance under the corresponding + // docset version { - "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:9|10|11|12|13|14|15|16|17|18)\\.x)", + "source": "/vault/docs/upgrading/upgrade-to-:version(1\\.(?:9|1[0-8])\\.x)", "destination": "/vault/docs/v:version/upgrading/upgrade-to-:version", "permanent": true }, + // The URL changed with version 1.19.x { "source": "/vault/docs/upgrading/upgrade-to-1.19.x", "destination": "/vault/docs/v1.19.x/updates/important-changes", "permanent": true }, - { - "source": "/vault/docs/v:version(1\\.(?:9|10|11|12|13|14|15|16|17|18)\\.x)/updates/important-changes", + + /** + Backfacing redirects for /updates/important-changes to legacy URLs + + - Source: {version}/updates/important-changes (new URL) + Target: {version}/upgrading/upgrade-to-{version} + Range: 1.9.x through 1.18.x + **/ + { + "source": "/vault/docs/v:version(1\\.(?:9|1[0-8])\\.x)/updates/important-changes", "destination": "/vault/docs/v:version/upgrading/upgrade-to-:version", "permanent": true }, + + + /***************************************************************************** + 2025 | IA update - Relase notes + *****************************************************************************/ + + /** + Versioned redirects for /release-notes/{version}.{patch} to versioned URLs + + NOTE: Release notes started with 1.5.0 and before v1.9, the release notes + for version X of Vault was published under version X+1 of the docs. For + simplicity, we redirect version-specific release notes from 1.5 through to + 1.9 to the versioned instance of that guide under the 1.9.x docs + + - Source: /release-notes/{version}.{patch} + Target: v1.9.x/release-notes/{version}.{patch} + Range: 1.5.x - 1.8.x + - Source: /release-notes/{version}.{patch} + Target: {version}.x/release-notes/{version}.{patch} + Range: 1.9.x - 1.18.x + - Source: /upgrading/upgrade-to-19.x + Target: v1.19.x/release-notes/1.19.0 + Range: 1.19.x + **/ + + // Redirect 1.5.0 through 1.8.0 guides to their v1.9.x instance + { + "source": "/vault/docs/release-notes/:version(1\\.[5-8]).:patch(.*)", + "destination": "/vault/docs/v1.9.x/release-notes/:version.:patch", + "permanent": true + }, + + // Redirect the guides for 1.9.0 through 1.18.0 to the instance under the + // corresponding docset version { - "source": "/vault/docs/release-notes/1.19.0", - "destination": "/vault/docs/v1.19.x/updates/release-notes", + "source": "/vault/docs/release-notes/:version(1\\.(?:9|1[0-8])).:patch(.*)", + "destination": "/vault/docs/v:version.x/release-notes/:version.:patch", "permanent": true }, + + // The URL changed with version 1.19.x { - "source": "/vault/docs/v:version(1\\.(?:4|5|6|7|8|9|10|11|12|13|14|15|17|18)).x/updates/release-notes", - "destination": "/vault/docs/v:version.x/release-notes/:version.0", + "source": "/vault/docs/release-notes/1.19.0", + "destination": "/vault/docs/v1.19.x/updates/release-notes", "permanent": true }, + + /** + Backfacing redirects for /updates/release-notes to legacy URLs + + - Source: {version}.x/updates/release-notes (new URL) + Target: 1.9.x/release-notes/{version}.0 + Range: 1.5 through 1.9 (1.4 does not have release notes) + - Source: {version}.x/updates/release-notes (new URL) + Target: {version}.x/release-notes/{version}.0 + Range: 1.10 through 1.18.x, except 1.16.x + - Source: 1.16.x/updates/release-notes (new URL) + Target: 1.16.x/release-notes/1.16.1 + Range: 1.16 only (1.16.x GAed with 1.16.1 instead of 1.16.0) + **/ + + // Redirect 1.4.x through 1.9.x to the v1.9.x version of the old URL { - "source": "/vault/docs/v1.16.x/updates/release-notes", - "destination": "/vault/docs/v1.16.x/release-notes/1.16.1", + "source": "/vault/docs/v:version(1\\.[5-9]).x/updates/release-notes", + "destination": "/vault/docs/v1.9.x/release-notes/:version.0", "permanent": true }, + + // Redirect 1.10.x through 1.18.x, except 1.16.x { - "source": "/vault/docs/release-notes/:version(1\\.(?:4|5|6|7|8|9|10|11|12|13|14|15|17|18)).0", + "source": "/vault/docs/v:version(1\\.1(?:[0-5]|[7-8])).x/updates/release-notes", "destination": "/vault/docs/v:version.x/release-notes/:version.0", "permanent": true }, + + // Redirect 1.16.x separately since 1.16.x GAed with 1.16.1 instead of 1.16.0 { - "source": "/vault/docs/release-notes/1.16.1", + "source": "/vault/docs/v1.16.x/updates/release-notes", "destination": "/vault/docs/v1.16.x/release-notes/1.16.1", "permanent": true }, + + + /***************************************************************************** + 2025 | IA update - About Vault pages + *****************************************************************************/ { "source": "/vault/docs/what-is-vault", "destination": "/vault/docs/about-vault/what-is-vault", @@ -241,50 +349,83 @@ "permanent": true }, { - "source": "/vault/docs/v:version(1\\.(?:4|5|6|7|8|9|10|11|12|13|14|15|16|17|18)\\.x)/partners", - "destination": "/vault/docs/v:version/interoperability-matrix", + "source": "/vault/docs/partnerships", + "destination": "/vault/docs/partners/program", "permanent": true }, { - "source": "/vault/docs/partnerships", - "destination": "/vault/docs/partners/program", + "source": "/vault/docs/browser-support", + "destination": "/vault/docs/ui/browser-support", + "permanent": true + }, + + /** + Backfacing redirects for /partners to legacy URLs + + - Source: {version}/partners (new URL) + Target: {version}/interoperability-matrix + Range: 1.11 through 1.18 + **/ + { + "source": "/vault/docs/v:version(1\\.1[1-8]\\.x)/partners/:slug*", + "destination": "/vault/docs/v:version/interoperability-matrix", "permanent": true }, + + /***************************************************************************** + 2025 | IA update - Get Vault + Deploy Vault + *****************************************************************************/ { "source": "/vault/docs/run-as-service", "destination": "/vault/docs/deploy/run-as-service", "permanent": true }, { - "source": "/vault/docs/install/:slug(.*)", - "destination": "/vault/docs/get-vault/:slug", + "source": "/vault/docs/install/:slug*", + "destination": "/vault/docs/get-vault/:slug*", "permanent": true }, { - "source": "/vault/docs/platform/aws/:slug(.*)", - "destination": "/vault/docs/deploy/aws/:slug", + "source": "/vault/docs/platform/aws/:slug*", + "destination": "/vault/docs/deploy/aws/:slug*", "permanent": true }, { - "source": "/vault/docs/platform/k8s/:slug(.*)", - "destination": "/vault/docs/deploy/kubernetes/:slug", + "source": "/vault/docs/platform/k8s/:slug*", + "destination": "/vault/docs/deploy/kubernetes/:slug*", "permanent": true }, + + /** + Version-tracking redirects for defunct path: /platform/k8s/*: + + - Source: {version}/platform/k8s/* + Target: {version}/deploy/kybernetes/* + Range: 1.19.x onward + **/ { - "source": "/vault/api-docs/secret/ad", - "destination": "/vault/api-docs/secret/ldap", + "source": "/vault/docs/v:version(1\\.(?:19|2[0-9])\\.x)/platform/k8s/:slug*", + "destination": "/vault/docs/v:version/deploy/kubernetes/:slug*", "permanent": true }, + + /***************************************************************************** + 2025 | IA update - Leasing redirects + *****************************************************************************/ + + // Concept docs { - "source": "/vault/docs/secrets/ad", - "destination": "/vault/docs/secrets/ldap", + "source": "/vault/docs/concepts/lease-explosions", + "destination": "/vault/docs/configuration/prevent-lease-explosions", "permanent": true }, { - "source": "/vault/docs/secrets/ad/migration-guide", - "destination": "/vault/docs/v1.18.x/secrets/ad/migration-guide", + "source": "/vault/docs/concepts/lease-count-quota-exceeded", + "destination": "/vault/docs/troubleshoot/lease-count-quota-exceeded", "permanent": true }, + + // Enterprise docs { "source": "/vault/docs/enterprise/license", "destination": "/vault/docs/license", @@ -315,39 +456,96 @@ "destination": "/vault/docs/license", "permanent": true }, + + // Troubleshooting docs + { + "source": "/vault/docs/troubleshoot/lease-explosions", + "destination": "/vault/docs/configuration/prevent-lease-explosions", + "permanent": true + }, + + /***************************************************************************** + FAQ redirects + *****************************************************************************/ + { + "source": "/vault/docs/faq/ssct", + "destination": "/vault/docs/v1.10.x/faq/ssct", + "permanent": true + }, + + + /***************************************************************************** + 2025 | IA update - Sys admin redirects + *****************************************************************************/ + + // Redirect the enterprise/ and concepts/ URLs for snapshots to the new + // sysadmin/ folder { "source": "/vault/docs/enterprise/automated-integrated-storage-snapshots", "destination": "/vault/docs/sysadmin/snapshots/automation-overview", "permanent": true }, { - "source": "/vault/docs/v:version(1\\.(?:7|8|9|10|11|12|13|14|15|16|17|18|19)\\.x)/sysadmin/snapshots/automation-overview", + "source": "/vault/docs/concepts/integrated-storage/snapshot-recover", + "destination": "/vault/docs/sysadmin/snapshots/recover-a-secret", + "permanent": true + }, + + /** + Backfacing redirects: + + - Source: {version}/sysadmin/snapshots/automation-overview (new URL) + Target: {version}/enterprise/automated-integrated-storage-snapshots + Range: 1.7 through 1.19 + **/ + { + "source": "/vault/docs/v:version(1\\.(?:[7-9]|1[0-9])\\.x)/sysadmin/snapshots/automation-overview", "destination": "/vault/docs/v:version/enterprise/automated-integrated-storage-snapshots", "permanent": true }, + + /***************************************************************************** + 2025 | R&D - client count refresh + *****************************************************************************/ + { "source": "/vault/docs/concepts/client-count/usage-metrics", "destination": "/vault/docs/concepts/client-count/client-usage", "permanent": true }, + + /** + Backfacing redirects: + + - Source: {version}/concepts/client-count/client-usage (new URL) + Target: {version}/concepts/client-count/usage-metrics + Range: 1.18 and 1.19 + **/ { - "source": "/vault/docs/:version(v1\\.*\\.x)/v:ver(1\\.*\\.x)/:slug(.*)", - "destination": "/vault/docs/:version/:slug", - "permanent": true - }, - { - "source": "/vault/docs/commands/web", - "destination": "/vault/docs/ui/web-cli", + "source": "/vault/docs/:version(v1\\.1[8-9]\\.x)/concepts/client-count/client-usage", + "destination": "/vault/docs/:version/concepts/client-count/usage-metrics", "permanent": true }, + + /***************************************************************************** + N/A | One-off corrections/moves + *****************************************************************************/ + { - "source": "/vault/docs/browser-support", - "destination": "/vault/docs/ui/browser-support", + "source": "/vault/docs/upgrade/lts-upgrade", + "destination": "/vault/docs/updates/lts-tracker", "permanent": true }, + + + /***************************************************************************** + Temporary bandaids + *****************************************************************************/ + + // Corrected double-versioned URLs to just take the first version in the string { - "source": "/vault/docs/commands/hcp", - "destination": "/vault/docs/commands/hcp/connect", + "source": "/vault/docs/:version(v1\\.*\\.x)/v:ver(1\\.*\\.x)/:slug*", + "destination": "/vault/docs/:version/:slug*", "permanent": true } -] +] \ No newline at end of file