diff --git a/website/source/api/auth/app-id/index.html.md b/website/source/api/auth/app-id/index.html.md index 3ae1564b23d6..e242a781c8e8 100644 --- a/website/source/api/auth/app-id/index.html.md +++ b/website/source/api/auth/app-id/index.html.md @@ -16,5 +16,5 @@ general information about the usage and operation of the App ID method, please see the [Vault App ID method documentation](/docs/auth/app-id.html). This documentation assumes the App ID method is mounted at the `/auth/app-id` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. diff --git a/website/source/api/auth/approle/index.html.md b/website/source/api/auth/approle/index.html.md index 8ee95a3710d5..77c587f68c58 100644 --- a/website/source/api/auth/approle/index.html.md +++ b/website/source/api/auth/approle/index.html.md @@ -13,7 +13,7 @@ general information about the usage and operation of the AppRole method, please see the [Vault AppRole method documentation](/docs/auth/approle.html). This documentation assumes the AppRole method is mounted at the `/auth/approle` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## List Roles diff --git a/website/source/api/auth/aws/index.html.md b/website/source/api/auth/aws/index.html.md index 9922cdb5d97f..95f0903d6824 100644 --- a/website/source/api/auth/aws/index.html.md +++ b/website/source/api/auth/aws/index.html.md @@ -13,7 +13,7 @@ general information about the usage and operation of the AWS method, please see the [Vault AWS method documentation](/docs/auth/aws.html). This documentation assumes the AWS method is mounted at the `/auth/aws` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Configure Client diff --git a/website/source/api/auth/cert/index.html.md b/website/source/api/auth/cert/index.html.md index 7c78faf0bd13..71ae2f5763c2 100644 --- a/website/source/api/auth/cert/index.html.md +++ b/website/source/api/auth/cert/index.html.md @@ -14,7 +14,7 @@ method. For general information about the usage and operation of the TLS Certificate method, please see the [Vault TLS Certificate method documentation](/docs/auth/cert.html). This documentation assumes the TLS Certificate method is mounted at the -`/auth/cert` path in Vault. Since it is possible to mount auth methods at any +`/auth/cert` path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Create CA Certificate Role diff --git a/website/source/api/auth/gcp/index.html.md b/website/source/api/auth/gcp/index.html.md index 2463dd5a7bba..a38ec10ad485 100644 --- a/website/source/api/auth/gcp/index.html.md +++ b/website/source/api/auth/gcp/index.html.md @@ -14,7 +14,7 @@ plugin. To learn more about the usage and operation, see the [Vault GCP method documentation](/docs/auth/gcp.html). This documentation assumes the plugin method is mounted at the -`/auth/gcp` path in Vault. Since it is possible to mount auth methods +`/auth/gcp` path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Configure @@ -42,7 +42,7 @@ to confirm signed JWTs passed in during login. for that server's machine. - `google_certs_endpoint` `(string: "")`: The Google OAuth2 endpoint to obtain public certificates for. This is used - primarily for testing and should generally not be set. If not set, will default to the [Google public certs + primarily for testing and should generally not be set. If not set, will default to the [Google public certs endpoint](https://www.googleapis.com/oauth2/v3/certs) ### Sample Payload @@ -145,29 +145,32 @@ entities attempting to login. A comma-separated list of service account emails or ids. Defines the service accounts that login is restricted to. If set to `\*`, all service accounts are allowed (role will still be bound by project). Will be - inferred from service account used to issue metadata token for GCE instances. + inferred from service account used to issue metadata token for GCE instances. **`iam`-only params**: - `max_jwt_exp` `(string: "")` - Optional, defaults to 900 (15min). Number of seconds past the time of authentication that the login param JWT must expire within. For example, if a user attempts to login with a token that expires within an hour and this is set to 15 minutes, Vault will return - an error prompting the user to create a new signed JWT with a shorter `exp`. + an error prompting the user to create a new signed JWT with a shorter `exp`. The GCE metadata tokens currently do not allow the `exp` claim to be customized. + - `allow_gce_inference` `(bool: true)` - A flag to determine if this role should - allow GCE instances to authenticate by inferring service accounts from the + allow GCE instances to authenticate by inferring service accounts from the GCE identity metadata token. - + **`gce`-only params**: -- `bound_zone` `(string: "")`: If set, determines the zone that a GCE instance must belong to. + +- `bound_zone` `(string: "")`: If set, determines the zone that a GCE instance must belong to. If bound_instance_group is provided, it is assumed to be a zonal group and the group must belong to this zone. -- `bound_region` `(string: "")`: If set, determines the region that a GCE instance must belong to. - If bound_instance_group is provided, it is assumed to be a regional group and the group must belong to this region. + +- `bound_region` `(string: "")`: If set, determines the region that a GCE instance must belong to. + If bound_instance_group is provided, it is assumed to be a regional group and the group must belong to this region. **If bound_zone is provided, region will be ignored.** - `bound_instance_group` `(string: "")`: If set, determines the instance group that an authorized instance must belong to. bound_zone or bound_region must also be set if bound_instance_group is set. - `bound_labels` `(array: [])`: A comma-separated list of Google Cloud Platform labels formatted as "$key:$value" strings that - must be set on authorized GCE instances. Because GCP labels are not currently ACL'd, we recommend that this be used in + must be set on authorized GCE instances. Because GCP labels are not currently ACL'd, we recommend that this be used in conjunction with other restrictions. ### Sample Payload @@ -282,7 +285,7 @@ service accounts on the role. - `name` `(string: )` - Name of an existing `gce` role. Returns error if role is not an `gce` role. - `add` `(array: [])` - List of `$key:$value` labels to add to the GCE role's bound labels. - `remove` `(array: [])` - List of label keys to remove from the role's bound labels. - + ### Sample Payload ```json @@ -424,7 +427,7 @@ entity and then authorizes the entity for the given role. - `jwt` `(string: "")` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT). For `iam`, this is a JWT generated using the IAM API method [signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt) - or a self-signed JWT. For `gce`, this is an [identity metadata token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature). + or a self-signed JWT. For `gce`, this is an [identity metadata token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature). ### Sample Payload diff --git a/website/source/api/auth/index.html.md b/website/source/api/auth/index.html.md index 72e60092a586..55634f82ce44 100644 --- a/website/source/api/auth/index.html.md +++ b/website/source/api/auth/index.html.md @@ -10,9 +10,9 @@ description: |- # Auth Methods Each auth method publishes its own set of API paths and methods. These endpoints -are documented in this section. Auth methods are mount at a path, but the -documentation will assume the default mount points for simplicity. If you are -mounting at a different path, you should adjust your API calls accordingly. +are documented in this section. Auth methods are enabled at a path, but the +documentation will assume the default paths for simplicity. If you are enabling +at a different path, you should adjust your API calls accordingly. For the API documentation for a specific auth method, please choose a auth method from the navigation. diff --git a/website/source/api/auth/kubernetes/index.html.md b/website/source/api/auth/kubernetes/index.html.md index d73e85724b64..b52c2ae69b85 100644 --- a/website/source/api/auth/kubernetes/index.html.md +++ b/website/source/api/auth/kubernetes/index.html.md @@ -13,7 +13,7 @@ learn more about the usage and operation, see the [Vault Kubernetes auth method](/docs/auth/kubernetes.html). This documentation assumes the Kubernetes method is mounted at the -`/auth/kubernetes` path in Vault. Since it is possible to mount auth methods at +`/auth/kubernetes` path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Configure Method diff --git a/website/source/api/auth/ldap/index.html.md b/website/source/api/auth/ldap/index.html.md index 6c29964752e1..b8342ec733df 100644 --- a/website/source/api/auth/ldap/index.html.md +++ b/website/source/api/auth/ldap/index.html.md @@ -13,7 +13,7 @@ general information about the usage and operation of the LDAP method, please see the [Vault LDAP method documentation](/docs/auth/ldap.html). This documentation assumes the LDAP method is mounted at the `/auth/ldap` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Configure LDAP diff --git a/website/source/api/auth/okta/index.html.md b/website/source/api/auth/okta/index.html.md index 58e78d12f82e..a66f4177fa0e 100644 --- a/website/source/api/auth/okta/index.html.md +++ b/website/source/api/auth/okta/index.html.md @@ -13,7 +13,7 @@ general information about the usage and operation of the Okta method, please see the [Vault Okta method documentation](/docs/auth/okta.html). This documentation assumes the Okta method is mounted at the `/auth/okta` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Create Configuration diff --git a/website/source/api/auth/radius/index.html.md b/website/source/api/auth/radius/index.html.md index a107be4fab94..72023d7eb830 100644 --- a/website/source/api/auth/radius/index.html.md +++ b/website/source/api/auth/radius/index.html.md @@ -13,7 +13,7 @@ general information about the usage and operation of the RADIUS method, please see the [Vault RADIUS method documentation](/docs/auth/radius.html). This documentation assumes the RADIUS method is mounted at the `/auth/radius` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Configure RADIUS diff --git a/website/source/api/auth/userpass/index.html.md b/website/source/api/auth/userpass/index.html.md index a80471fbf81a..3bb0a53c8766 100644 --- a/website/source/api/auth/userpass/index.html.md +++ b/website/source/api/auth/userpass/index.html.md @@ -14,7 +14,7 @@ general information about the usage and operation of the Username and Password m see the [Vault Userpass method documentation](/docs/auth/userpass.html). This documentation assumes the Username & Password method is mounted at the `/auth/userpass` -path in Vault. Since it is possible to mount auth methods at any location, +path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ## Create/Update User diff --git a/website/source/api/secret/cassandra/index.html.md b/website/source/api/secret/cassandra/index.html.md index 3e28e5b1cc64..e504087bfa19 100644 --- a/website/source/api/secret/cassandra/index.html.md +++ b/website/source/api/secret/cassandra/index.html.md @@ -19,7 +19,7 @@ please see the [Vault Cassandra backend documentation](/docs/secrets/cassandra/index.html). This documentation assumes the Cassandra backend is mounted at the `/cassandra` -path in Vault. Since it is possible to mount secrets engines at any location, +path in Vault. Since it is possible to enable secrets engines at any location, please update your API calls accordingly. ## Configure Connection diff --git a/website/source/api/system/audit-hash.html.md b/website/source/api/system/audit-hash.html.md index 74d9f93cc075..280b77108e7d 100644 --- a/website/source/api/system/audit-hash.html.md +++ b/website/source/api/system/audit-hash.html.md @@ -3,19 +3,19 @@ layout: "api" page_title: /sys/audit-hash - HTTP API" sidebar_current: "docs-http-system-audit-hash" description: |- - The `/sys/audit-hash` endpoint is used to hash data using an audit backend's + The `/sys/audit-hash` endpoint is used to hash data using an audit device's hash function and salt. --- # `/sys/audit-hash` The `/sys/audit-hash` endpoint is used to calculate the hash of the data used by -an audit backend's hash function and salt. This can be used to search audit logs +an audit device's hash function and salt. This can be used to search audit logs for a hashed value when the original value is known. ## Calculate Hash -This endpoint hashes the given input data with the specified audit backend's +This endpoint hashes the given input data with the specified audit device's hash function and salt. This endpoint can be used to discover whether a given plaintext string (the `input` parameter) appears in the audit log in obfuscated form. @@ -31,7 +31,7 @@ should also be base64-encoded to supply into the `input` parameter. ### Parameters -- `path` `(string: )` – Specifies the path of the audit backend to +- `path` `(string: )` – Specifies the path of the audit device to generate hashes for. This is part of the request URL. - `input` `(string: )` – Specifies the input string to hash. diff --git a/website/source/api/system/audit.html.md b/website/source/api/system/audit.html.md index 060756bceb1b..5a63674ca143 100644 --- a/website/source/api/system/audit.html.md +++ b/website/source/api/system/audit.html.md @@ -3,19 +3,19 @@ layout: "api" page_title: "/sys/audit - HTTP API" sidebar_current: "docs-http-system-audit/" description: |- - The `/sys/audit` endpoint is used to enable and disable audit backends. + The `/sys/audit` endpoint is used to enable and disable audit devices. --- # `/sys/audit` -The `/sys/audit` endpoint is used to list, mount, and unmount audit backends. -Audit backends must be enabled before use, and more than one backend may be +The `/sys/audit` endpoint is used to list, enable, and disable audit devices. +Audit devices must be enabled before use, and more than one device may be enabled at a time. -## List Mounted Audit Backends +## List Enabled Audit Devices -This endpoint lists only the mounted audit backends (it does not list all -available audit backends). +This endpoint lists only the enabled audit devices (it does not list all +available audit devices). - **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities. @@ -46,9 +46,9 @@ $ curl \ } ``` -## Mount Audit Backend +## Enable Audit Device -This endpoint mounts a new audit backend at the supplied path. The path can be a +This endpoint enables a new audit device at the supplied path. The path can be a single word name or a more complex, nested path. - **`sudo` required** – This endpoint requires `sudo` capability in addition to @@ -60,23 +60,22 @@ single word name or a more complex, nested path. ### Parameters -- `path` `(string: )` – Specifies the path in which to mount the audit - backend. This is part of the request URL. +- `path` `(string: )` – Specifies the path in which to enable the audit + device. This is part of the request URL. - `description` `(string: "")` – Specifies a human-friendly description of the - audit backend. + audit device. - `options` `(map: nil)` – Specifies configuration options to - pass to the audit backend itself. This is dependent on the audit backend type. + pass to the audit device itself. This is dependent on the audit device type. -- `type` `(string: )` – Specifies the type of the audit backend. +- `type` `(string: )` – Specifies the type of the audit device. Additionally, the following options are allowed in Vault open-source, but relevant functionality is only supported in Vault Enterprise: -- `local` `(bool: false)` – Specifies if the audit backend is a local mount - only. Local mounts are not replicated nor (if a secondary) removed by - replication. +- `local` `(bool: false)` – Specifies if the audit device is a local only. Local + audit devices are not replicated nor (if a secondary) removed by replication. ### Sample Payload @@ -99,9 +98,9 @@ $ curl \ https://vault.rocks/v1/sys/audit/example-audit ``` -## Unmount Audit Backend +## Disable Audit Device -This endpoint un-mounts the audit backend at the given path. +This endpoint disables the audit device at the given path. - **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities. @@ -112,7 +111,7 @@ This endpoint un-mounts the audit backend at the given path. ### Parameters -- `path` `(string: )` – Specifies the path of the audit backend to +- `path` `(string: )` – Specifies the path of the audit device to delete. This is part of the request URL. ### Sample Request diff --git a/website/source/api/system/auth.html.md b/website/source/api/system/auth.html.md index a75be97c6dc6..93cfa871e835 100644 --- a/website/source/api/system/auth.html.md +++ b/website/source/api/system/auth.html.md @@ -47,13 +47,13 @@ $ curl \ } ``` -## Mount Auth Method +## Enable Auth Method -This endpoint enables a new auth method. After mounting, the auth method can +This endpoint enables a new auth method. After enabling, the auth method can be accessed and configured via the auth path specified as part of the URL. This auth path will be nested under the `auth` prefix. -For example, mounting the "foo" auth method will make it accessible at +For example, enable the "foo" auth method will make it accessible at `/auth/foo`. - **`sudo` required** – This endpoint requires `sudo` capability in addition to @@ -65,7 +65,7 @@ For example, mounting the "foo" auth method will make it accessible at ### Parameters -- `path` `(string: )` – Specifies the path in which to mount the auth +- `path` `(string: )` – Specifies the path in which to enable the auth method. This is part of the request URL. - `description` `(string: "")` – Specifies a human-friendly description of the @@ -75,7 +75,7 @@ For example, mounting the "foo" auth method will make it accessible at method type, such as "github" or "token". - `config` `(map: nil)` – Specifies configuration options for - this mount. These are the possible values: + this auth method. These are the possible values: - `plugin_name` @@ -89,9 +89,8 @@ For example, mounting the "foo" auth method will make it accessible at Additionally, the following options are allowed in Vault open-source, but relevant functionality is only supported in Vault Enterprise: -- `local` `(bool: false)` – Specifies if the auth method is a local mount - only. Local mounts are not replicated nor (if a secondary) removed by - replication. +- `local` `(bool: false)` – Specifies if the auth method is a local only. Local + auth methods are not replicated nor (if a secondary) removed by replication. ### Sample Payload @@ -112,9 +111,9 @@ $ curl \ https://vault.rocks/v1/sys/auth/my-auth ``` -## Unmount Auth Method +## Disable Auth Method -This endpoint un-mounts the auth method at the given auth path. +This endpoint disables the auth method at the given auth path. - **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities. @@ -125,7 +124,7 @@ This endpoint un-mounts the auth method at the given auth path. ### Parameters -- `path` `(string: )` – Specifies the path to unmount. This is part of +- `path` `(string: )` – Specifies the path to disable. This is part of the request URL. ### Sample Request diff --git a/website/source/api/system/index.html.md b/website/source/api/system/index.html.md index 5be5c42ead3a..e81c8e9b9760 100644 --- a/website/source/api/system/index.html.md +++ b/website/source/api/system/index.html.md @@ -4,14 +4,14 @@ page_title: "System Backend - HTTP API" sidebar_current: "docs-http-system" description: |- The system backend is a default backend in Vault that is mounted at the `/sys` - endpoint. This endpoint cannot be unmounted or moved, and is used to configure + endpoint. This endpoint cannot be disabled or moved, and is used to configure Vault and interact with many of Vault's internal features. --- # System Backend The system backend is a default backend in Vault that is mounted at the `/sys` -endpoint. This endpoint cannot be unmounted or moved, and is used to configure +endpoint. This endpoint cannot be disabled or moved, and is used to configure Vault and interact with many of Vault's internal features. For more information about a particular path, please click on it in the sidebar. diff --git a/website/source/api/system/mounts.html.md b/website/source/api/system/mounts.html.md index d60e0b60be46..3e8b078be191 100644 --- a/website/source/api/system/mounts.html.md +++ b/website/source/api/system/mounts.html.md @@ -54,9 +54,9 @@ $ curl \ `default_lease_ttl` or `max_lease_ttl` values of 0 mean that the system defaults are used by this backend. -## Mount Secrets Engine +## Enable Secrets Engine -This endpoint mounts a new secrets engine at the given path. +This endpoint enables a new secrets engine at the given path. | Method | Path | Produces | | :------- | :--------------------------- | :--------------------- | @@ -88,7 +88,7 @@ This endpoint mounts a new secrets engine at the given path. catalog to use. These control the default and maximum lease time-to-live, force - disabling backend caching, and option plugin name for plugin backends + disabling backend caching, and option plugin name for plugin backends respectively. The first three options override the global defaults if set on a specific mount. The plugin_name can be provided in the config map or as a top-level option, with the former taking precedence. @@ -125,9 +125,9 @@ $ curl \ https://vault.rocks/v1/sys/mounts/my-mount ``` -## Unmount Secrets Engine +## Disable Secrets Engine -This endpoint un-mounts the mount point specified in the URL. +This endpoint disables the mount point specified in the URL. | Method | Path | Produces | | :------- | :--------------------------- | :--------------------- | diff --git a/website/source/api/system/remount.html.md b/website/source/api/system/remount.html.md index 4e233c8c0984..02efe5ad89f0 100644 --- a/website/source/api/system/remount.html.md +++ b/website/source/api/system/remount.html.md @@ -10,9 +10,9 @@ description: |- The `/sys/remount` endpoint is used remount a mounted backend to a new endpoint. -## Remount Backend +## Move Backend -This endpoint remounts an already-mounted backend to a new mount point. +This endpoint moves an already-mounted backend to a new mount point. | Method | Path | Produces | | :------- | :--------------------------- | :--------------------- | diff --git a/website/source/docs/commands/help.html.md b/website/source/docs/commands/help.html.md index 408bbcd0f745..72f3d5dda33b 100644 --- a/website/source/docs/commands/help.html.md +++ b/website/source/docs/commands/help.html.md @@ -27,11 +27,11 @@ properly to execute this command to look up paths. Before using `path-help`, it is important to understand "paths" within Vault. Paths are the parameters used for `vault read`, `vault write`, etc. An example path is `secret/foo`, or `aws/config/root`. The paths available -depend on the mounted secret backends. Because of this, the interactive +depend on the enabled secrets engines. Because of this, the interactive help is an indispensable tool to finding what paths are supported. To discover what paths are supported, use `vault path-help `. -For example, if you mounted the AWS secret backend, you can use +For example, if you mounted the AWS secrets engine, you can use `vault path-help aws` to find the paths supported by that backend. The paths will be shown with regular expressions, which can make them hard to parse, but they're also extremely exact. diff --git a/website/source/docs/concepts/auth.html.md b/website/source/docs/concepts/auth.html.md index 33d32eae5625..1382a6305192 100644 --- a/website/source/docs/concepts/auth.html.md +++ b/website/source/docs/concepts/auth.html.md @@ -29,7 +29,7 @@ backends must be enabled before use. To enable an auth method: $ vault write sys/auth/my-auth type=userpass ``` -This mounts the "userpass" auth method at the path "my-auth". This +This enables the "userpass" auth method at the path "my-auth". This authentication will be accessible at the path "my-auth". Often you will see authentications at the same path as their name, but this is not a requirement. diff --git a/website/source/docs/concepts/dev-server.html.md b/website/source/docs/concepts/dev-server.html.md index 446f5980b888..18ca7d9ff9ad 100644 --- a/website/source/docs/concepts/dev-server.html.md +++ b/website/source/docs/concepts/dev-server.html.md @@ -44,7 +44,7 @@ The properties of the dev server: ## Use Case The dev server should be used for experimentation with Vault features, such -as different auth methods, secrets engines, audit backends, etc. +as different auth methods, secrets engines, audit devices, etc. If you're new to Vault, you may want to pick up with [Your First Secret](/intro/getting-started/first-secret.html) in our getting started guide. diff --git a/website/source/docs/concepts/response-wrapping.html.md b/website/source/docs/concepts/response-wrapping.html.md index 373961aaa597..ed6e209aa57a 100644 --- a/website/source/docs/concepts/response-wrapping.html.md +++ b/website/source/docs/concepts/response-wrapping.html.md @@ -160,7 +160,7 @@ Validation is best performed by the following steps: what you expect, it is possible that the data contained inside was read and then put into a new response-wrapping token. (This is especially likely if the path starts with `cubbyhole` or `sys/wrapping/wrap`.) Particular care - should be taken with `kv` mounts: exact matches on the path are best + should be taken with `kv` secrets engine: exact matches on the path are best there. For example, if you expect a secret to come from `secret/foo` and the interceptor provides a token with `secret/bar` as the path, simply checking for a prefix of `secret/` is not enough. diff --git a/website/source/docs/concepts/tokens.html.md b/website/source/docs/concepts/tokens.html.md index 16d990b453e2..b8d559d0957b 100644 --- a/website/source/docs/concepts/tokens.html.md +++ b/website/source/docs/concepts/tokens.html.md @@ -111,10 +111,10 @@ correlated with a particular job ID. When the job is complete, the accessor can be used to instantly revoke the token given to the job and all of its leased credentials, limiting the chance that a bad actor will discover and use them. -Audit backends can optionally be set to not obfuscate token accessors in audit +Audit devices can optionally be set to not obfuscate token accessors in audit logs. This provides a way to quickly revoke tokens in case of an emergency. -However, it also means that the audit logs can be used to perform a -larger-scale denial of service attack. +However, it also means that the audit logs can be used to perform a larger-scale +denial of service attack. Finally, the only way to "list tokens" is via the `auth/token/accessors` command, which actually gives a list of token accessors. While this is still a diff --git a/website/source/docs/internals/architecture.html.md b/website/source/docs/internals/architecture.html.md index b74f07de929c..848c5bf84783 100644 --- a/website/source/docs/internals/architecture.html.md +++ b/website/source/docs/internals/architecture.html.md @@ -8,69 +8,77 @@ description: |- # Architecture -Vault is a complex system that has many different pieces. To help both users and developers of Vault -build a mental model of how it works, this page documents the system architecture. +Vault is a complex system that has many different pieces. To help both users and +developers of Vault build a mental model of how it works, this page documents +the system architecture. -~> **Advanced Topic!** This page covers technical details -of Vault. You don't need to understand these details to -effectively use Vault. The details are documented here for -those who wish to learn about them without having to go -spelunking through the source code. However, if you're an -operator of Vault, we recommend learning about the architecture -due to the importance of Vault in an environment. +~> **Advanced Topic!** This page covers technical details of Vault. You don't +need to understand these details to effectively use Vault. The details are +documented here for those who wish to learn about them without having to go +spelunking through the source code. However, if you're an operator of Vault, we +recommend learning about the architecture due to the importance of Vault in an +environment. # Glossary Before describing the architecture, we provide a glossary of terms to help clarify what is being discussed: -* **Storage Backend** - A storage backend is responsible for durable storage of _encrypted_ data. - Backends are not trusted by Vault and are only expected to provide durability. The storage - backend is configured when starting the Vault server. - -* **Barrier** - The barrier is cryptographic steel and concrete around the Vault. All data that - flows between Vault and the Storage Backend passes through the barrier. The barrier ensures - that only encrypted data is written out, and that data is verified and decrypted on the way - in. Much like a bank vault, the barrier must be "unsealed" before anything inside can be accessed. - -* **Secrets Engine** - A secrets engine is responsible for managing secrets. Simple secrets engines - like the "kv" backend simply return the same secret when queried. Some backends support - using policies to dynamically generate a secret each time they are queried. This allows for - unique secrets to be used which allows Vault to do fine-grained revocation and policy updates. - As an example, a MySQL backend could be configured with a "web" policy. When the "web" secret - is read, a new MySQL user/password pair will be generated with a limited set of privileges - for the web server. - -* **Audit Backend** - An audit backend is responsible for managing audit logs. Every request to Vault - and response from Vault goes through the configured audit backends. This provides a simple - way to integrate Vault with multiple audit logging destinations of different types. - -* **auth method** - An auth method is used to authenticate users or applications which - are connecting to Vault. Once authenticated, the backend returns the list of applicable policies - which should be applied. Vault takes an authenticated user and returns a client token that can - be used for future requests. As an example, the `userpass` backend uses a username and password - to authenticate the user. Alternatively, the `github` backend allows users to authenticate - via GitHub. - -* **Client Token** - A client token is a conceptually similar to a session cookie on a web site. - Once a user authenticates, Vault returns a client token which is used for future requests. - The token is used by Vault to verify the identity of the client and to enforce the applicable - ACL policies. This token is passed via HTTP headers. - -* **Secret** - A secret is the term for anything returned by Vault which contains confidential - or cryptographic material. Not everything returned by Vault is a secret, for example - system configuration, status information, or backend policies are not considered Secrets. - Secrets always have an associated lease. This means clients cannot assume that the secret - contents can be used indefinitely. Vault will revoke a secret at the end of the lease, and - an operator may intervene to revoke the secret before the lease is over. This contract - between Vault and its clients is critical, as it allows for changes in keys and policies - without manual intervention. - -* **Server** - Vault depends on a long-running instance which operates as a server. - The Vault server provides an API which clients interact with and manages the - interaction between all the backends, ACL enforcement, and secret lease revocation. - Having a server based architecture decouples clients from the security keys and policies, - enables centralized audit logging and simplifies administration for operators. +- **Storage Backend** - A storage backend is responsible for durable storage of + _encrypted_ data. Backends are not trusted by Vault and are only expected to + provide durability. The storage backend is configured when starting the Vault + server. + +- **Barrier** - The barrier is cryptographic steel and concrete around the + Vault. All data that flows between Vault and the storage backend passes + through the barrier. The barrier ensures that only encrypted data is written + out, and that data is verified and decrypted on the way in. Much like a bank + vault, the barrier must be "unsealed" before anything inside can be accessed. + +- **Secrets Engine** - A secrets engine is responsible for managing secrets. + Simple secrets engines like the "kv" secrets engine simply return the same + secret when queried. Some secrets engines support using policies to + dynamically generate a secret each time they are queried. This allows for + unique secrets to be used which allows Vault to do fine-grained revocation and + policy updates. As an example, a MySQL secrets engine could be configured with + a "web" policy. When the "web" secret is read, a new MySQL user/password pair + will be generated with a limited set of privileges for the web server. + +- **Audit Device** - An audit device is responsible for managing audit logs. + Every request to Vault and response from Vault goes through the configured + audit devices. This provides a simple way to integrate Vault with multiple + audit logging destinations of different types. + +- **Auth Method** - An auth method is used to authenticate users or applications + which are connecting to Vault. Once authenticated, the auth method returns the + list of applicable policies which should be applied. Vault takes an + authenticated user and returns a client token that can be used for future + requests. As an example, the `userpass` auth method uses a username and + password to authenticate the user. Alternatively, the `github` auth method + allows users to authenticate via GitHub. + +- **Client Token** - A client token (aka "Vault Token") is a conceptually + similar to a session cookie on a web site. Once a user authenticates, Vault + returns a client token which is used for future requests. The token is used by + Vault to verify the identity of the client and to enforce the applicable ACL + policies. This token is passed via HTTP headers. + +- **Secret** - A secret is the term for anything returned by Vault which + contains confidential or cryptographic material. Not everything returned by + Vault is a secret, for example system configuration, status information, or + policies are not considered secrets. Secrets always have an associated lease. + This means clients cannot assume that the secret contents can be used + indefinitely. Vault will revoke a secret at the end of the lease, and an + operator may intervene to revoke the secret before the lease is over. This + contract between Vault and its clients is critical, as it allows for changes + in keys and policies without manual intervention. + +- **Server** - Vault depends on a long-running instance which operates as a + server. The Vault server provides an API which clients interact with and + manages the interaction between all the secrets engines, ACL enforcement, and + secret lease revocation. Having a server based architecture decouples clients + from the security keys and policies, enables centralized audit logging and + simplifies administration for operators. # High-Level Overview @@ -78,80 +86,90 @@ A very high level overview of Vault looks like this: [![Architecture Overview](/assets/images/layers.png)](/assets/images/layers.png) -Let's begin to break down this picture. There is a clear separation of components -that are inside or outside of the security barrier. Only the storage backend and -the HTTP API are outside, all other components are inside the barrier. - -The storage backend is untrusted and is used to durably store encrypted data. When -the Vault server is started, it must be provided with a storage backend so that data -is available across restarts. The HTTP API similarly must be started by the Vault server -on start so that clients can interact with it. - -Once started, the Vault is in a _sealed_ state. Before any operation can be performed -on the Vault it must be unsealed. This is done by providing the unseal keys. When -the Vault is initialized it generates an encryption key which is used to protect all the -data. That key is protected by a master key. By default, Vault uses a technique known -as [Shamir's secret sharing algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing) -to split the master key into 5 shares, any 3 of which are required to reconstruct the master +Let's begin to break down this picture. There is a clear separation of +components that are inside or outside of the security barrier. Only the storage +backend and the HTTP API are outside, all other components are inside the +barrier. + +The storage backend is untrusted and is used to durably store encrypted data. +When the Vault server is started, it must be provided with a storage backend so +that data is available across restarts. The HTTP API similarly must be started +by the Vault server on start so that clients can interact with it. + +Once started, the Vault is in a _sealed_ state. Before any operation can be +performed on the Vault it must be unsealed. This is done by providing the unseal +keys. When the Vault is initialized it generates an encryption key which is used +to protect all the data. That key is protected by a master key. By default, +Vault uses a technique known as [Shamir's secret sharing +algorithm](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing) to split the +master key into 5 shares, any 3 of which are required to reconstruct the master key. [![Vault Shamir Secret Sharing Algorithm](/assets/images/vault-shamir-secret-sharing.svg)](/assets/images/vault-shamir-secret-sharing.svg) -The number of shares and the minimum threshold required can both be specified. Shamir's -technique can be disabled, and the master key used directly for unsealing. Once Vault -retrieves the encryption key, it is able to decrypt the data in the storage backend, -and enters the _unsealed_ state. Once unsealed, Vault loads all of the configured -audit devices, auth methods, and secrets engines. +The number of shares and the minimum threshold required can both be specified. +Shamir's technique can be disabled, and the master key used directly for +unsealing. Once Vault retrieves the encryption key, it is able to decrypt the +data in the storage backend, and enters the _unsealed_ state. Once unsealed, +Vault loads all of the configured audit devices, auth methods, and secrets +engines. -The configuration of those backends must be stored in Vault since they are security -sensitive. Only users with the correct permissions should be able to modify them, -meaning they cannot be specified outside of the barrier. By storing them in Vault, -any changes to them are protected by the ACL system and tracked by audit logs. +The configuration of those audit devices, auth methods, and secrets engines must +be stored in Vault since they are security sensitive. Only users with the +correct permissions should be able to modify them, meaning they cannot be +specified outside of the barrier. By storing them in Vault, any changes to them +are protected by the ACL system and tracked by audit logs. -After the Vault is unsealed, requests can be processed from the HTTP API to the Core. -The core is used to manage the flow of requests through the system, enforce ACLs, -and ensure audit logging is done. +After the Vault is unsealed, requests can be processed from the HTTP API to the +Core. The core is used to manage the flow of requests through the system, +enforce ACLs, and ensure audit logging is done. When a client first connects to Vault, it needs to authenticate. Vault provides configurable auth methods providing flexibility in the authentication mechanism used. Human friendly mechanisms such as username/password or GitHub might be -used for operators, while applications may use public/private keys or tokens to authenticate. -An authentication request flows through core and into an auth method, which determines -if the request is valid and returns a list of associated policies. - -Policies are just a named ACL rule. For example, the "root" policy is built-in and -permits access to all resources. You can create any number of named policies with -fine-grained control over paths. Vault operates exclusively in a whitelist mode, meaning -that unless access is explicitly granted via a policy, the action is not allowed. -Since a user may have multiple policies associated, an action is allowed if any policy -permits it. Policies are stored and managed by an internal policy store. This internal store -is manipulated through the system backend, which is always mounted at `sys/`. +used for operators, while applications may use public/private keys or tokens to +authenticate. An authentication request flows through core and into an auth +method, which determines if the request is valid and returns a list of +associated policies. + +Policies are just a named ACL rule. For example, the "root" policy is built-in +and permits access to all resources. You can create any number of named policies +with fine-grained control over paths. Vault operates exclusively in a whitelist +mode, meaning that unless access is explicitly granted via a policy, the action +is not allowed. Since a user may have multiple policies associated, an action is +allowed if any policy permits it. Policies are stored and managed by an internal +policy store. This internal store is manipulated through the system backend, +which is always mounted at `sys/`. Once authentication takes place and an auth method provides a set of applicable -policies, a new client token is generated and managed by the token store. This client token -is sent back to the client, and is used to make future requests. This is similar to -a cookie sent by a website after a user logs in. The client token may have a lease associated -with it depending on the auth method configuration. This means the client token -may need to be periodically renewed to avoid invalidation. - -Once authenticated, requests are made providing the client token. The token is used -to verify the client is authorized and to load the relevant policies. The policies -are used to authorize the client request. The request is then routed to the secrets engine, -which is processed depending on the type of backend. If the backend returns a secret, -the core registers it with the expiration manager and attaches a lease ID. -The lease ID is used by clients to renew or revoke their secret. If a client allows the -lease to expire, the expiration manager automatically revokes the secret. - -The core handles logging of requests and responses to the audit broker, which fans the -request out to all the configured audit backends. Outside of the request flow, the core -performs certain background activity. Lease management is critical, as it allows -expired client tokens or secrets to be revoked automatically. Additionally, Vault handles -certain partial failure cases by using write ahead logging with a rollback manager. -This is managed transparently within the core and is not user visible. +policies, a new client token is generated and managed by the token store. This +client token is sent back to the client, and is used to make future requests. +This is similar to a cookie sent by a website after a user logs in. The client +token may have a lease associated with it depending on the auth method +configuration. This means the client token may need to be periodically renewed +to avoid invalidation. + +Once authenticated, requests are made providing the client token. The token is +used to verify the client is authorized and to load the relevant policies. The +policies are used to authorize the client request. The request is then routed to +the secrets engine, which is processed depending on its type. If the secrets +engine returns a secret, the core registers it with the expiration manager and +attaches a lease ID. The lease ID is used by clients to renew or revoke their +secret. If a client allows the lease to expire, the expiration manager +automatically revokes the secret. + +The core handles logging of requests and responses to the audit broker, which +fans the request out to all the configured audit devices. Outside of the request +flow, the core performs certain background activity. Lease management is +critical, as it allows expired client tokens or secrets to be revoked +automatically. Additionally, Vault handles certain partial failure cases by +using write ahead logging with a rollback manager. This is managed transparently +within the core and is not user visible. # Getting in Depth This has been a brief high-level overview of the architecture of Vault. There are more details available for each of the sub-systems. -For other details, either consult the code, ask in IRC or reach out to the mailing list. +For other details, either consult the code, ask in IRC or reach out to the +mailing list. diff --git a/website/source/docs/plugin/index.html.md b/website/source/docs/plugin/index.html.md index 277e673179a5..d6d5285a744b 100644 --- a/website/source/docs/plugin/index.html.md +++ b/website/source/docs/plugin/index.html.md @@ -14,29 +14,28 @@ builtin backends. These backends can be either authentication or secrets engines Detailed information regarding the plugin system can be found in the [internals documentation](https://www.vaultproject.io/docs/internals/plugins.html). -# Mounting/unmounting Plugin Backends +# Enabling/Disabling Plugin Backends Before a plugin backend can be mounted, it needs to be registered via the [plugin catalog](https://www.vaultproject.io/docs/internals/plugins.html#plugin-catalog). After the plugin is registered, it can be mounted by specifying the registered plugin name: -``` -$ vault mount -path=my-secrets -plugin-name=passthrough-plugin plugin +```text +$ vault secrets enable -path=my-secrets -plugin-name=passthrough-plugin plugin Successfully mounted plugin 'passthrough-plugin' at 'my-secrets'! ``` -Listing mounts will display backends that are mounted as plugins, along with the -name of plugin backend that is mounted: +Listing secrets engines will display secrets engines that are mounted as +plugins: -``` -$ vault mounts +```text +$ vault secrets list Path Type Accessor Plugin Default TTL Max TTL Force No Cache Replication Behavior Description my-secrets/ plugin plugin_deb84140 passthrough-plugin system system false replicated -... ``` -Unmounting a plugin backend is the identical to unmounting internal backends: +Disabling a plugin backend is the identical to disabling internal secrets engines: -``` -$ vault unmount my-secrets +```text +$ vault secrets disable my-secrets ``` diff --git a/website/source/docs/secrets/identity/index.html.md b/website/source/docs/secrets/identity/index.html.md index f9eac66e85b0..544682c769a7 100644 --- a/website/source/docs/secrets/identity/index.html.md +++ b/website/source/docs/secrets/identity/index.html.md @@ -31,7 +31,7 @@ get inherited from entities are computed at request time. This provides flexibility in controlling the access of tokens that are already issued. This secrets engine will be mounted by default. This secrets engine cannot be -unmounted or remounted. +disabled or moved. ## API diff --git a/website/source/docs/secrets/pki/index.html.md b/website/source/docs/secrets/pki/index.html.md index 31bd5dbbd0b2..a96c3de1c997 100644 --- a/website/source/docs/secrets/pki/index.html.md +++ b/website/source/docs/secrets/pki/index.html.md @@ -159,7 +159,7 @@ while keeping CRLs valid from the old CA certificate; simply mount a new secrets engine and issue from there. A common pattern is to have one mount act as your root CA and to use this CA -only to sign intermediate CA CSRs from other PKI mounts. +only to sign intermediate CA CSRs from other PKI secrets engines. ### Keep certificate lifetimes short, for CRL's sake diff --git a/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md b/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md index efd5b6c6d7bb..74fffde5bb97 100644 --- a/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md +++ b/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md @@ -43,10 +43,10 @@ must be mounted before use. Successfully mounted 'ssh' at 'ssh-client-signer'! ``` - This mounts the SSH secrets engine at the path "ssh-client-signer". It is possible - to mount the same secrets engine multiple times using different `-path` - arguments. The name "ssh-client-signer" is not special - it can be any name, - but this documentation will assume "ssh-client-signer". + This enables the SSH secrets engine at the path "ssh-client-signer". It is + possible to mount the same secrets engine multiple times using different + `-path` arguments. The name "ssh-client-signer" is not special - it can be + any name, but this documentation will assume "ssh-client-signer". 1. Configure Vault with a CA for signing client keys using the `/config/ca` endpoint. If you do not have an internal CA, Vault can generate a keypair for diff --git a/website/source/guides/replication.html.md b/website/source/guides/replication.html.md index 92bcb7ac5b07..9537de355a5e 100644 --- a/website/source/guides/replication.html.md +++ b/website/source/guides/replication.html.md @@ -143,7 +143,7 @@ secondaries. Mounts can also be marked local (via the `-local` flag on the Vault CLI or setting the `local` parameter to `true` in the API). This can only be performed at mount time; if a mount is local but should have been replicated, or vice -versa, you must unmount the backend and mount a new instance at that path with +versa, you must disable the backend and mount a new instance at that path with the local flag enabled. Local mounts do not propagate data from the primary to secondaries, and local @@ -153,16 +153,16 @@ state where replication is disabled; all data, including local mounts, is deleted at this time (as the encryption keys will have changed so data in local mounts would be unable to be read). -### Audit Backends +### Audit Devices -In normal Vault usage, if Vault has at least one audit backend configured and -is unable to successfully log to at least one backend, it will block further +In normal Vault usage, if Vault has at least one audit device configured and +is unable to successfully log to at least one device, it will block further requests. Replicated audit mounts must be able to successfully log on all replicated -clusters. For example, if using the file backend, the configured path must be -able to be written to by all secondaries. It may be useful to use at least one -local audit mount on each cluster to prevent such a scenario. +clusters. For example, if using the file audit device, the configured path must +be able to be written to by all secondaries. It may be useful to use at least +one local audit mount on each cluster to prevent such a scenario. ### Never Have Two Primaries diff --git a/website/source/guides/upgrading/upgrade-to-0.6.3.html.md b/website/source/guides/upgrading/upgrade-to-0.6.3.html.md index 6b41acb9e1e4..51cf62c70999 100644 --- a/website/source/guides/upgrading/upgrade-to-0.6.3.html.md +++ b/website/source/guides/upgrading/upgrade-to-0.6.3.html.md @@ -26,11 +26,11 @@ will be utilized. A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests. -## Any Audit Backend Successfully Activated Allows Active Duty +## Any Audit Device Successfully Activated Allows Active Duty Previously, when a new Vault node was taking over service in an HA cluster, all -audit backends were required to be active successfully to take over active +audit devices were required to be active successfully to take over active duty. This behavior now matches the behavior of the audit logging system -itself: at least one audit backend must successfully be activated. The server +itself: at least one audit device must successfully be activated. The server log contains an error when this occurs. This helps keep a Vault HA cluster working when there is a misconfiguration on a standby node. diff --git a/website/source/intro/vs/chef-puppet-etc.html.md b/website/source/intro/vs/chef-puppet-etc.html.md index a35a82a0f60d..df1eea3be0d9 100644 --- a/website/source/intro/vs/chef-puppet-etc.html.md +++ b/website/source/intro/vs/chef-puppet-etc.html.md @@ -34,7 +34,7 @@ encrypted storage, it couldn't be read without multiple keys which are generally distributed to multiple individuals. This is known as _unsealing_, and happens once whenever Vault starts. -For an unsealed Vault, every interaction is logged in via the audit backends. +For an unsealed Vault, every interaction is logged in via the audit devices. Even erroneous requests (invalid access tokens, for example) are logged. To access any data, an access token is required. This token is usually associated with an identity coming from a system such as GitHub, LDAP, etc. diff --git a/website/source/intro/vs/keywhiz.html.md b/website/source/intro/vs/keywhiz.html.md index 1624513c9630..ddb9f3232ca6 100644 --- a/website/source/intro/vs/keywhiz.html.md +++ b/website/source/intro/vs/keywhiz.html.md @@ -27,7 +27,7 @@ operator usage. Vault and Keywhiz expose secrets via an API. The Vault [ACL system](/docs/concepts/policies.html) is used to protect secrets and gate access, similarly to the Keywhiz ACL system. With Vault, all auditing is done -server side using [audit backends](/docs/audit/index.html). +server side using [audit devices](/docs/audit/index.html). Keywhiz focuses on storage and distribution of secrets and supports rotation through secret versioning, which is possible in the Keywhiz UI and command-line @@ -41,4 +41,3 @@ from Vault have an associated lease which enables operators to audit key usage, perform key rolling, and ensure automatic revocation. Vault provides multiple revocation mechanisms to give operators a clear "break glass" procedure after a potential compromise. -