upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-02-19 02:49:18 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

[DOCS] IA refresh (phase 2) (#30287)

Browse source
This commit is contained in:
Sarah Chavis 2025-04-29 17:08:14 -07:00 committed by GitHub
parent 1262d8b920
commit 485ccbc5da
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
425 changed files with 13512 additions and 10441 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
website/content/api-docs/auth/aws.mdx
View file

@ -8,8 +8,6 @@ description: This is the API documentation for the Vault AWS auth method.
@include 'x509-sha1-deprecation.mdx'
@include 'aws-sha1-deprecation.mdx'
This is the API documentation for the Vault AWS auth method. For
general information about the usage and operation of the AWS method, please
see the [Vault AWS method documentation](/vault/docs/auth/aws).
@ -309,6 +307,9 @@ set of AWS certificates built-in.
The `pkcs7` type is used to verify PKCS#7 signatures from the AWS
`http://169.254.169.254/latest/dynamic/instance-identity/pkcs7` and
`http://169.254.169.254/latest/dynamic/instance-identity/rsa2048` endpoints.
Vault does not support X.509 certificates with SHA-1 signatures. If you use AWS
[`/rsa2048` signature endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-rsa2048.html)
credentials, you must use the `pkcs7` login flow.
The `identity` type is used to verify signatures from the
`http://169.254.169.254/latest/dynamic/instance-identity/document` and

115
website/content/cli/commands/agent/generate-config.mdx Normal file
View file

@ -0,0 +1,115 @@
---
layout: docs
page_title: "agent generate-config - Vault CLI"
description: >-
Use vault agent generate-config to generate a basic Vault Agent configuration
file from secrets plugin data.
---
# `agent generate-config`
Use secrets plugin data to generate a basic
[configuration file](/vault/docs/agent-and-proxy/agent#configuration-file-options)
for running Vault Agent in [process supervisor mode](/vault/docs/agent-and-proxy/agent/process-supervisor).
<CodeBlockConfig hideClipboard>
```shell-session
$ vault agent generate-config -type <config_file_type> [options] [<file_path>]
```
</CodeBlockConfig>
## Description
`agent generate-config` composes configuration details for Vault Agent
based on the configuration `type` and writes a local configuration file for
running Vault agent in process supervisor mode.
<Tip title="Related API endpoints">
- None
</Tip>
### Limitations and warnings
Limitations:
- Plugin support limited to KV plugins.
- Configuration type limited to environment variable templates.
<Warning title="Not appropriate for production">
The file created by `agent generate-config` includes an `auto_auth` section
configured to use the `token_file` authentication method.
Token files are convenient for local testing, but **are not** appropriates for
production use. Refer to the full list of Vault Agent
[autoAuth methods](/vault/docs/agent-and-proxy/autoauth/methods) for available
production-ready authentication methods.
</Warning>
## Arguments
<br />
@include 'cli/agent/args/file_path.mdx'
## Options
None.
## Command Flags
<br />
@include 'cli/agent/flags/exec.mdx'
<br /><hr /><br />
@include 'cli/agent/flags/path.mdx'
<br /><hr /><br />
@include 'cli/agent/flags/type.mdx'
## Global flags
<br />
@include 'cli/standard-settings/all-standard-flags-but-format.mdx'
## Examples
Generate an environment variable template configuration for the `foo` secrets
plugin:
```shell-session
$ vault agent generate-config \
-type="env-template" \
-exec="./my-app arg1 arg2" \
-path="secret/foo"
Command output
```
Generate an environment variable template configuration for more than one
secrets plugin:
```shell-session
$ vault agent generate-config -type="env-template" \
-exec="./my-app arg1 arg2" \
-path="secret/foo" \
-path="secret/bar" \
-path="secret/my-app/*"
```

101
website/content/cli/commands/agent/index.mdx Normal file
View file

@ -0,0 +1,101 @@
---
layout: docs
page_title: "agent - Vault CLI"
description: >-
Use vault agent to start an instance of Vault Agent.
---
# `vault agent`
Start an instance of Vault Agent.
<CodeBlockConfig hideClipboard>
```shell-session
$ vault agent -config <config_file>
$ vault agent [-help | -h]
```
</CodeBlockConfig>
## Description
`vault agent` start an instance of Vault Agent, which automatically
authenticates and fetches secrets for client applications.
<Tip title="Related API endpoints">
**None**
</Tip>
## Command arguments
None.
## Command options
None.
## Command flags
<br />
@include 'cli/agent/flags/config.mdx'
<br /><hr /><br />
@include 'cli/agent/flags/exit-after-auth.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-file.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-format.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-level.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-rotate-bytes.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-rotate-duration.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-rotate-max-files.mdx'
## Standard flags
<br />
@include 'cli/standard-settings/all-standard-flags-but-format.mdx'
## Examples
Start Vault Agent with a single configuration file:
```shell-session
$ vault agent -config=/etc/vault/agent/config.hcl
```
Start Vault Agent with a two discrete configuration files:
```shell-session
$ vault agent \
-config=/etc/vault/agent/base-config.hcl \
-config=/etc/vault/agent/auto-auth-config.hcl
```
Start Vault Agent with a set of configuration files under the `` directory:
```shell-session
$ vault agent -config=/etc/vault/agent/config-files/
```

76
website/content/cli/commands/audit/disable.mdx Normal file
View file

@ -0,0 +1,76 @@
---
layout: docs
page_title: "audit disable - Vault CLI"
description: >-
Disable an audit device capturing log data from Vault.
---
# `audit disable`
Disable an audit device if it exists.
<CodeBlockConfig hideClipboard>
```shell-session
$ vault audit disable [flags] <device_path>
$ vault audit disable [-help | -h]
```
</CodeBlockConfig>
## Description
`vault audit disable` deactivates an audit device without destroying data
already logged by the device. The operation is idempotent and succeeds if the
audit device is properly disabled **or** if the device path does not
correspond to an active audit device.
<Tip title="Related API endpoints">
DisableAuditDevice - [`DELETE:/sys/audit/{mount-path}`](/vault/api-docs/system/audit#disable-audit-device)
</Tip>
### Limitations and warnings
- You cannot HMAC values for comparison against audit logs for a disabled audit
device.
- Vault does not preserve HMAC encryption if you reenable an audit device at the
same path. Each time you enable a device, Vault uses a new salt for hashing.
## Command arguments
<br />
@include 'cli/audit/args/device_path.mdx'
## Command options
- None
## Command flags
- None
## Standard flags
<br />
@include 'cli/standard-settings/all-standard-flags-but-format.mdx'
## Examples
Disable a file-type audit device at the default path, `file/`:
```shell-session
$ vault audit disable file/
Success! Disabled audit device (if it was enabled) at: file/
```
Disable a socket audit device at the path `audit/kv-socket`:
```shell-session
$ vault audit disable audit/kv-socket/
Success! Disabled audit device (if it was enabled) at: audit/kv-socket/
```

186
website/content/cli/commands/audit/enable.mdx Normal file
View file

@ -0,0 +1,186 @@
---
layout: docs
page_title: "audit enable - Vault CLI"
description: >-
Create and enable a new audit device to capture log data from Vault.
---
# `audit enable`
Enable a new audit device.
<CodeBlockConfig hideClipboard>
```shell-session
$ vault audit enable [flags] <device_type> [options] [<config_argument=value>...]
$ vault audit enable [-help | -h]
```
</CodeBlockConfig>
## Description
`audit enable` creates and enables an audit device at the given path or returns
an error if an audit device already exists at the given path. The device
configuration parameters depend on the audit device type.
<Tip title="Related API endpoints">
EnableAuditDevice - [`POST:/sys/audit/{mount-path}`](/vault/api-docs/system/audit#enable-audit-device)
</Tip>
## Command arguments
@include 'cli/audit/args/device_type.mdx'
Each audit device type also has a set of configuration arguments:
<Tabs>
<Tab heading="File">
<CodeBlockConfig hideClipboard>
```shell-session
$ vault audit enable [flags] file [options] \
file_path=<path/to/log/file> \
[mode=<file_permissions>]
```
</CodeBlockConfig>
<br />
@include 'cli/audit/args/file/file_path.mdx'
<br /><hr /><br />
@include 'cli/audit/args/file/mode.mdx'
</Tab>
<Tab heading="Socket">
<CodeBlockConfig hideClipboard>
```shell-session
$ vault audit enable [flags] socket [options] \
[address=<server_address>] \
[socket_type=<protocol>] \
[write_timeout=<wait_time>]
```
</CodeBlockConfig>
<br />
@include 'cli/audit/args/socket/address.mdx'
<br /><hr /><br />
@include 'cli/audit/args/socket/socket_type.mdx'
<br /><hr /><br />
@include 'cli/audit/args/socket/write_timeout.mdx'
</Tab>
<Tab heading="Syslog">
<CodeBlockConfig hideClipboard>
```shell-session
$ vault audit enable [flags] syslog [options] \
[facility=<process_entry_source>] \
[tag=<program_entry_source>]
```
</CodeBlockConfig>
<br />
@include 'cli/audit/args/syslog/facility.mdx'
<br /><hr /><br />
@include 'cli/audit/args/syslog/tag.mdx'
</Tab>
</Tabs>
## Command options
<br />
@include 'cli/audit/options/elide_list_responses.mdx'
<br /><hr /><br />
@include 'cli/audit/options/exclude.mdx'
<br /><hr /><br />
@include 'cli/audit/options/fallback.mdx'
<br /><hr /><br />
@include 'cli/audit/options/filter.mdx'
<br /><hr /><br />
@include 'cli/audit/options/format.mdx'
<br /><hr /><br />
@include 'cli/audit/options/hmac_accessor.mdx'
<br /><hr /><br />
@include 'cli/audit/options/log_raw.mdx'
<br /><hr /><br />
@include 'cli/audit/options/prefix.mdx'
## Command flags
<br />
@include 'cli/audit/flags/description.mdx'
<br /><hr /><br />
@include 'cli/audit/flags/local.mdx'
<br /><hr /><br />
@include 'cli/audit/flags/path.mdx'
## Standard flags
<br />
@include 'cli/standard-settings/all-standard-flags-but-format.mdx'
## Examples
Enable a `file` type audit device at the default path, `file/`:
```shell-session
$ vault audit enable file file_path=/tmp/my-file.txt
Success! Enabled the file audit device at: file/
```
Enable a `file` type audit device at the path, `audit/file`:
```shell-session
$ vault audit enable -path=audit/file file file_path=/tmp/my-file.txt
Success! Enabled the file audit device at: audit/file/
```

70
website/content/cli/commands/audit/list.mdx Normal file
View file

@ -0,0 +1,70 @@
---
layout: docs
page_title: "audit list - Vault CLI"
description: >-
List active audit devices for Vault.
---
# `audit list`
List information about active audit devices.
<CodeBlockConfig hideClipboard>
```shell-session
$ vault audit list [flags]
$ vault audit list [-help | -h]
```
</CodeBlockConfig>
## Description
`vault audit list` displays information about active audit devices.
<Tip title="Related API endpoints">
ListAuditDevices - [`GET:/sys/audit`](/vault/api-docs/system/audit#list-enabled-audit-devices)
</Tip>
## Command arguments
None.
## Command options
None.
## Command flags
<br />
@include 'cli/audit/flags/detailed.mdx'
## Standard flags
<br />
@include 'cli/standard-settings/all-standard-flags.mdx'
## Examples
List basic information for all active audit devices:
```shell-session
$ vault audit list
Path Type Description
---- ---- -----------
file/ file n/a
```
List detailed information for all active audit devices:
```shell-session
$ vault audit list -detailed
Path Type Description Replication Options
---- ---- ----------- ----------- -------
file/ file n/a replicated file_path=/var/log/audit.log
```

32
website/content/cli/commands/auth/disable.mdx Normal file
View file

@ -0,0 +1,32 @@
---
layout: docs
page_title: auth disable - Command
description: |-
The "auth disable" command disables an auth method at a given path, if one
exists. This command is idempotent, meaning it succeeds even if no auth method
is enabled at the path.
---
# auth disable
The `auth disable` command disables an auth method at a given path, if one
exists. This command is idempotent, meaning it succeeds even if no auth method
is enabled at the path.
Once an auth method is disabled, it can no longer be used for authentication.
**All access tokens generated via the disabled auth method are immediately
revoked.** This command will block until all tokens are revoked.
## Examples
Disable the auth method enabled at "userpass/":
```shell-session
$ vault auth disable userpass/
Success! Disabled the auth method (if it existed) at: userpass/
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

98
website/content/cli/commands/auth/enable.mdx Normal file
View file

@ -0,0 +1,98 @@
---
layout: docs
page_title: auth enable - Command
description: |-
The "auth enable" command enables an auth method at a given path. If an auth
method already exists at the given path, an error is returned. After the auth
method is enabled, it usually needs configuration.
---
# auth enable
The `auth enable` command enables an auth method at a given path. If an auth
method already exists at the given path, an error is returned. After the auth
method is enabled, it usually needs configuration. The configuration varies by
auth method.
An auth method is responsible for authenticating users or machines and assigning
them policies and a token with which they can access Vault. Authentication is
usually mapped to policy. Please see the [policies
concepts](/vault/docs/concepts/policies) page for more information.
## Examples
Enable the auth method "userpass" enabled at "userpass/":
```shell-session
$ vault auth enable userpass
Success! Enabled the userpass auth method at: userpass/
```
Create a user:
```shell-session
$ vault write auth/userpass/users/sethvargo password=secret
Success! Data written to: auth/userpass/users/sethvargo
```
For more information on the specific configuration options and paths, please see
the [auth method](/vault/docs/auth) documentation.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-audit-non-hmac-request-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the request data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
An example of this is provided in the [tune section](/vault/docs/commands/auth/tune).
- `-audit-non-hmac-response-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the response data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-default-lease-ttl` `(duration: "")` - The default lease TTL for this auth
method. If unspecified, this defaults to the Vault server's globally
configured default lease TTL, or a previously configured value for the auth
method. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `-passthrough-request-headers` `(string: "")` - request header values that will
be sent to the auth method. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-allowed-response-headers` `(string: "")` - response header values that the auth
method will be allowed to set. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-description` `(string: "")` - Human-friendly description for the purpose of
this auth method.
- `-listing-visibility` `(string: "")` - The flag to toggle whether to show the
mount in the UI-specific listing endpoint. Valid values are `"unauth"` or `"hidden"`,
with the default `""` being equivalent to `"hidden"`.
- `-local` `(bool: false)` - Mark the auth method as local-only. Local auth
methods are not replicated nor removed by replication.
- `-max-lease-ttl` `(string: "")` - The maximum lease duration, specified as
a string duration like "5s" or "30m".
- `-path` `(string: "")` - Place where the auth method will be accessible. This
must be unique across all auth methods. This defaults to the "type" of the
auth method. The auth method will be accessible at `/auth/<path>`.
- `-seal-wrap` `(bool: false)` - Enable seal wrapping for the mount, causing
values stored by the mount to be wrapped by the seal's encryption capability.
- `-token-type` `(string: "")` - Specifies the type of tokens that should be
returned by the auth method.
- `-trim-request-trailing-slashes` `(bool: false)` - If true, requests to
this mount with trailing slashes will have those slashes trimmed.
Necessary for some standards based APIs handled by Vault.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. If unspecified, implies the built-in or any matching unversioned plugin
that may have been registered.

43
website/content/cli/commands/auth/help.mdx Normal file
View file

@ -0,0 +1,43 @@
---
layout: docs
page_title: auth help - Command
description: The "auth help" command prints usage and help for an auth method.
---
# auth help
The `auth help` command prints usage and help for an auth method.
- If given a TYPE, this command prints the default help for the auth method of
that type.
- If given a PATH, this command prints the help output for the auth method
enabled at that path. This path must already exist.
Each auth method produces its own help output.
## Examples
Get usage instructions for the userpass auth method:
```shell-session
$ vault auth help userpass
Usage: vault login -method=userpass [CONFIG K=V...]
The userpass auth method allows users to authenticate using Vault's
internal user database.
# ...
```
Print usage for the auth method enabled at my-method/
```shell-session
$ vault auth help my-method/
# ...
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

79
website/content/cli/commands/auth/index.mdx Normal file
View file

@ -0,0 +1,79 @@
---
layout: docs
page_title: auth - Command
description: |-
The "auth" command groups subcommands for interacting with Vault's auth
methods. Users can list, enable, disable, and get help for different auth
methods.
---
# auth
The `auth` command groups subcommands for interacting with Vault's auth methods.
Users can list, enable, disable, and get help for different auth methods.
For more information, please see the [auth method
documentation](/vault/docs/auth) or the [authentication
concepts](/vault/docs/concepts/auth) page.
To authenticate to Vault as a user or machine, use the [`vault login`](/vault/docs/commands/login) command instead. This command is for
interacting with the auth methods themselves, not authenticating to Vault.
## Examples
Enable an auth method:
```shell-session
$ vault auth enable userpass
Success! Enabled userpass auth method at: userpass/
```
List all auth methods:
```shell-session
$ vault auth list
Path Type Description
---- ---- -----------
token/ token token based credentials
userpass/ userpass n/a
```
Get help about how to authenticate to a particular auth method:
```shell-session
$ vault auth help userpass/
Usage: vault login -method=userpass [CONFIG K=V...]
# ...
```
Disable an auth method:
```shell-session
$ vault auth disable userpass/
Success! Disabled the auth method (if it existed) at: userpass/
```
Tune an auth method:
```shell-session
$ vault auth tune -max-lease-ttl=30m userpass/
Success! Tuned the auth method at: userpass/
```
## Usage
```text
Usage: vault auth <subcommand> [options] [args]
# ...
Subcommands:
disable Disables an auth method
enable Enables a new auth method
help Prints usage for an auth method
list Lists enabled auth methods
tune Tunes an auth method configuration
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

72
website/content/cli/commands/auth/list.mdx Normal file
View file

@ -0,0 +1,72 @@
---
layout: docs
page_title: auth list - Command
description: |-
The "auth list" command lists the auth methods enabled. The output lists the
enabled auth methods and options for those methods.
---
# auth list
The `auth list` command lists the auth methods enabled. The output lists the
enabled auth methods and options for those methods.
## Deprecation status column
As of 1.12, all built-in auth engines will have an associated Deprecation
Status. This status will be reflected in the `Deprecation Status` column, seen
below. All auth engines which are not provided by built-in plugins will show a
`Deprecation Status` of "n/a".
## Version columns
The `-detailed` view displays some version information for each mount.
The Version field indicates the configured version for the plugin. Empty, or "n/a",
indicates the built-in or any matching unversioned plugin that may have been registered.
Running Version indicates the actual plugin version running, which may differ from
Version if the plugin hasn't been reloaded since the configured version was updated
using the `secrets tune` command. Finally, the Running SHA256 field indicates the
SHA256 sum of the running plugin's binary. This may be different from the SHA256
registered in the catalog if the plugin hasn't been reloaded since the plugin
version was overwritten in the catalog.
## Examples
List all auth methods:
```shell-session
$ vault auth list
Path Type Description
---- ---- -----------
token/ token token based credentials
userpass/ userpass n/a
```
List detailed auth method information:
```shell-session
$ vault auth list -detailed
Path Plugin Accessor Default TTL Max TTL Token Type Replication Seal Wrap External Entropy Access Options Description UUID Deprecation Status
---- ------ -------- ----------- ------- ---------- ----------- --------- ----------------------- ------- ----------- ---- ------------------
app-id/ app-id auth_app-id_c88ad56f system system default-service replicated false false map[] n/a a7c702b4-0dba-02b6-483c-2fd6be33240a pending removal
approle/ approle auth_approle_95df932e system system default-service replicated false false map[] n/a 931df9d1-8737-b7dc-4ca2-3e0e892fce92 supported
token/ token auth_token_aafab997 system system default-service replicated false false map[] token based credentials 6eb5db7b-ac7f-4304-1f52-9b802c6f06c1 n/a
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-detailed` `(bool: false)` - Print detailed information such as configuration
and replication status about each auth method.

48
website/content/cli/commands/auth/move.mdx Normal file
View file

@ -0,0 +1,48 @@
---
layout: docs
page_title: auth move - Command
description: |-
The "auth move" command moves an existing auth method to a new path. All
tokens from the old auth method are revoked, but all configurations
associated with the engine are preserved.
---
# auth move
The `auth move` command moves an existing auth method to a new path. Any
leases from the old auth method are revoked, but all configuration associated
with the engine is preserved. The command can be issued for a move within or across
namespaces, using namespace prefixes in the arguments.
The command will trigger a remount operation and uses the returned migration ID to poll the
status of the operation until a terminal state of `success` or `failure` is reached.
**Moving an existing auth method will revoke any leases from the old
method.**
## Examples
Move the existing auth method at ns1/approle/ to ns2/new-approle/:
```shell-session
$ vault auth move ns1/auth/approle/ ns2/auth/new-approle/
```
Move the existing auth method `auth/userpass` to the `education/certification/approle` namespace.
```shell-session
$ vault auth move auth/userpass education/certification/auth/userpass
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
## Post-move considerations
Each namespace has its own policies, auth methods, secrets engines, tokens,
identity entities and groups. You must consider the following after moving a mount across namespaces:
- Necessary policies exist in the target namespace
- Entities and groups might need updates after an auth method move

189
website/content/cli/commands/auth/tune.mdx Normal file
View file

@ -0,0 +1,189 @@
---
layout: docs
page_title: auth tune - Command
description: |-
The "auth tune" command tunes the configuration options for the auth method at
the given PATH.
---
# auth tune
The `auth tune` command tunes the configuration options for the auth method at
the given PATH.
<Note>
The argument corresponds to the **path** where the auth method is
enabled, not the auth **type**.
</Note>
## Examples
Before tuning the auth method configuration, view the current configuration of the
auth method enabled at `github/`.
```shell-session
$ vault read sys/auth/github/tune
Key Value
--- -----
default_lease_ttl 768h
description n/a
force_no_cache false
max_lease_ttl 768h
token_type default-service
```
The default lease for the auth method enabled at `github/` is currently set to
768 hours. Tune this value to 72 hours.
```shell-session
$ vault auth tune -default-lease-ttl=72h github/
Success! Tuned the auth method at: github/
```
Verify the updated configuration.
<CodeBlockConfig highlight="1,4">
```shell-session
$ vault read sys/auth/github/tune
Key Value
--- -----
default_lease_ttl 72h
description n/a
force_no_cache false
max_lease_ttl 768h
token_type default-service
```
</CodeBlockConfig>
To restore back to the system default, you can use `-1`.
```shell-session
$ vault auth tune -default-lease-ttl=-1 github/
Success! Tuned the auth method at: github/
```
Verify the updated configuration.
<CodeBlockConfig highlight="1,4">
```shell-session
$ vault read sys/auth/github/tune
Key Value
--- -----
default_lease_ttl 768h
description n/a
force_no_cache false
max_lease_ttl 768h
token_type default-service
```
</CodeBlockConfig>
You can specify multiple audit non-hmac request keys.
```shell-session
$ vault auth tune -audit-non-hmac-request-keys=value1 -audit-non-hmac-request-keys=value2 github/
Success! Tuned the auth method at: github/
```
### Enable user lockout
User lockout feature is only supported for
[userpass](/vault/docs/auth/userpass), [ldap](/vault/docs/auth/ldap), and
[approle](/vault/docs/auth/approle) auth methods.
Tune the `userpass/` auth method to lock out the user after 10 failed login
attempts within 10 minutes.
```shell-session
$ vault auth tune -user-lockout-threshold=10 -user-lockout-duration=10m userpass/
Success! Tuned the auth method at: userpass/
```
View the current configuration of the auth method enabled at `userpass/`.
<CodeBlockConfig highlight="1,11-13">
```shell-session
$ vault read sys/auth/userpass/tune
Key Value
--- -----
default_lease_ttl 768h
description n/a
force_no_cache false
max_lease_ttl 768h
token_type default-service
user_lockout_counter_reset_duration 0s
user_lockout_disable false
user_lockout_duration 10m
user_lockout_threshold 10
```
</CodeBlockConfig>
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-allowed-response-headers` `(string: "")` - response header values that the auth
method will be allowed to set.
- `-audit-non-hmac-request-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the request data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-audit-non-hmac-response-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the response data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-default-lease-ttl` `(duration: "")` - The default lease TTL for this auth
method. If unspecified, this defaults to the Vault server's globally
configured default lease TTL, or a previously configured value for the auth
method.
- `-description` `(string: "")` - Specifies the description of the auth method.
This overrides the current stored value, if any.
- `-listing-visibility` `(string: "")` - The flag to toggle whether to show the
mount in the UI-specific listing endpoint. Valid values are `"unauth"` or `"hidden"`.
Passing empty string leaves the current setting unchanged.
- `-max-lease-ttl` `(duration: "")` - The maximum lease TTL for this auth
method. If unspecified, this defaults to the Vault server's globally
configured [maximum lease TTL](/vault/docs/configuration#max_lease_ttl), or a
previously configured value for the auth method. This value is allowed to
override the server's global max TTL; it can be longer or shorter.
- `-passthrough-request-headers` `(string: "")` - request header values that will
be sent to the auth method. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-token-type` `(string: "")` - Specifies the type of tokens that should be
returned by the auth method.
- `-trim-request-trailing-slashes` `(bool: false)` - If true, requests to
this mount with trailing slashes will have those slashes trimmed.
Necessary for some standards based APIs handled by Vault.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. The new version will not start running until the mount is
[reloaded](/vault/docs/commands/plugin/reload).
- `-user-lockout-threshold` `(string: "")` - Specifies the number of failed login attempts
after which the user is locked out. User lockout feature was added in Vault 1.13.
- `-user-lockout-duration` `(duration: "")` - Specifies the duration for which a user will be locked out.
User lockout feature was added in Vault 1.13.
- `-user-lockout-counter-reset-duration` `(duration: "")` - Specifies the duration after which the lockout
counter is reset with no failed login attempts. User lockout feature was added in Vault 1.13.
- `-user-lockout-disable` `(bool: false)` - Disables the user lockout feature if set to true. User lockout feature was added in Vault 1.13.

182
website/content/cli/commands/debug.mdx Normal file
View file

@ -0,0 +1,182 @@
---
layout: docs
page_title: debug - Command
description: |-
The "debug" command monitors a Vault server, probing information about
it for a certain duration.
---
# debug
The `debug` command starts a process that monitors a Vault server, probing
information about it for a certain duration.
Gathering information about the state of the Vault cluster often requires the
operator to access all necessary information via various API calls and terminal
commands. The `debug` command aims to provide a simple workflow that produces a
consistent output to help operators retrieve and share information about the
server in question.
The `debug` command honors the same variables that the base command
accepts, such as the token stored via a previous login or the environment
variables `VAULT_TOKEN` and `VAULT_ADDR`. The token used determines the
permissions and, in turn, the information that `debug` may be able to collect.
The address specified determines the target server that will be probed against.
If the command is interrupted, the information collected up until that
point gets persisted to an output directory.
## Permissions
Regardless of whether a particular target is provided, the ability for `debug`
to fetch data for the target depends on the token provided. Some targets, such
as `server-status`, queries unauthenticated endpoints which means that it can be
queried all the time. Other targets require the token to have ACL permissions to
query the matching endpoint in order to get a proper response. Any errors
encountered during capture due to permissions or otherwise will be logged in the
index file.
The following policy can be used for generating debug packages with all targets:
```hcl
path "auth/token/lookup-self" {
capabilities = ["read"]
}
path "sys/pprof/*" {
capabilities = ["read"]
}
path "sys/config/state/sanitized" {
capabilities = ["read"]
}
path "sys/monitor" {
capabilities = ["read"]
}
path "sys/host-info" {
capabilities = ["read"]
}
path "sys/in-flight-req" {
capabilities = ["read"]
}
```
## Capture targets
The `-target` flag can be specified multiple times to capture specific
information when debug is running. By default, it captures all information.
| Target | Description |
| :------------------- | :-------------------------------------------------------------------------------- |
| `config` | Sanitized version of the configuration state. |
| `host` | Information about the instance running the server, such as CPU, memory, and disk. |
| `metrics` | Telemetry information. |
| `pprof` | Runtime profiling data, including heap, CPU, goroutine, and trace profiling. |
| `replication-status` | Replication status. |
| `server-status` | Health and seal status. |
Note that the `config`, `host`,`metrics`, and `pprof` targets are only queried
on active and performance standby nodes due to the the fact that the information
pertains to the local node and the request should not be forwarded.
Additionally, host information is not available on the OpenBSD platform due to
library limitations in fetching the data without enabling `cgo`.
[Enterprise] Telemetry can be gathered from a DR Secondary active node via the
`metrics` target if [unauthenticated_metrics_access](/vault/docs/configuration/listener/tcp#unauthenticated_metrics_access) is enabled.
## Output layout
The output of the bundled information, once decompressed, is contained within a
single directory. Each target, with the exception of profiling data, is captured
in a single file. For each of those targets collection is represented as a JSON
array object, with each entry captured at each interval as a JSON object.
```shell-session
$ tree vault-debug-2019-10-15T21-44-49Z/
vault-debug-2019-10-15T21-44-49Z/
├── 2019-10-15T21-44-49Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-45-19Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-45-49Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-46-19Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-46-49Z
│   ├── goroutine.prof
│   └── heap.prof
├── config.json
├── host_info.json
├── index.json
├── metrics.json
├── replication_status.json
└── server_status.json
```
## Examples
Start debug using reasonable defaults:
```shell-session
$ vault debug
```
Start debug with different duration, intervals, and metrics interval values, and
skip compression:
```shell-session
$ vault debug -duration=1m -interval=10s -metrics-interval=5s -compress=false
```
Start debug with specific targets:
```shell-session
$ vault debug -target=host -target=metrics
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-compress` `(bool: true)` - Toggles whether to compress output package The
default is true.
- `-duration` `(int or time string: "2m")` - Duration to run the command. The
default is 2m0s.
- `-interval` `(int or time string: "30s")` - The polling interval at which to
collect profiling data and server state. The default is 30s.
- `-log-format` `(string: "standard")` - Log format to be captured if "log"
target specified. Supported values are "standard" and "json". The default is
"standard".
- `-metrics-interval` `(int or time string: "10s")` - The polling interval at
which to collect metrics data. The default is 10s.
- `-output` `(string)` - Specifies the output path for the debug package. Defaults
to a time-based generated file name.
- `-target` `(string: all targets)` - Target to capture, defaulting to all if
none specified. This can be specified multiple times to capture multiple
targets. Available targets are: config, host, metrics, pprof,
replication-status, server-status.

42
website/content/cli/commands/delete.mdx Normal file
View file

@ -0,0 +1,42 @@
---
layout: docs
page_title: delete - Command
description: |-
The "delete" command deletes secrets and configuration from Vault at the given
path. The behavior of "delete" is delegated to the backend corresponding to
the given path.
---
# delete
The `delete` command deletes secrets and configuration from Vault at the given
path (wrapper command for HTTP DELETE). The behavior of "delete" is delegated to
the backend corresponding to the given path.
## Examples
Remove data in the static secrets engine:
```shell-session
$ vault delete secret/my-secret
```
Uninstall an encryption key in the transit backend:
```shell-session
$ vault delete transit/keys/my-key
```
Note: changing the `deletion_allowed` parameter to `true` is necessary for the
key to be successfully deleted, you can read more on key parameters [here](/vault/api-docs/secret/transit#update-key-configuration)
Delete an IAM role:
```shell-session
$ vault delete aws/roles/ops
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

102
website/content/cli/commands/events.mdx Normal file
View file

@ -0,0 +1,102 @@
---
layout: docs
page_title: events - Command
description: |-
The "events" command interacts with the Vault events notifications subsystem.
---
# events
<EnterpriseAlert product="vault" />
Use the `events` command to get a real-time display of
[event notifications](/vault/docs/concepts/events) generated by Vault and to subscribe to Vault
event notifications. Note that the `events subscribe` runs indefinitly and will not exit on
its own unless it encounters an unexpected error. Similar to `tail -f` in the
Unix world, you must terminate the process from the command line to end the
`events` command.
Specify the desired event types (also called "topics") as a glob pattern. To
match against multiple event types, use `*` as a wildcard. The command returns
serialized JSON objects in the default protobuf JSON serialization format with
one line per event received.
## Examples
Subscribe to all event notifications:
```shell-session
$ vault events subscribe '*'
```
Subscribe to all KV event notifications:
```shell-session
$ vault events subscribe 'kv*'
```
Subscribe to all `kv-v2/data-write` event notifications:
```shell-session
$ vault events subscribe kv-v2/data-write
```
Subscribe to all KV event notifications in the current and `ns1` namespaces for the secret `secret/data/foo` that do not involve writing data:
```shell-session
$ vault events subscribe -namespaces=ns1 -filter='data_path == secret/data/foo and operation != "data-write"' 'kv*'
```
## Usage
`events subscribe` supports the following flags in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Options
- `-timeout`: `(duration: "")` - close the WebSocket automatically after the
specified duration.
- `-namespaces` `(string)` - Additional **child** namespaces for the
subscription. Repeat the flag to add additional namespace patterns to the
subscription request. Vault automatically prepends the issuing namespace for
the request to the provided namespace. For example, if you include
`-namespaces=ns2` on a request made in the `ns1` namespace, Vault will attempt
to subscribe you to event notifications under the `ns1/ns2` and `ns1` namespaces. You can
use the `*` character to include wildcards in the namespace pattern. By
default, Vault will only subscribe to event notifications in the requesting namespace.
<Note>
To subscribe to event notifications across multiple namespaces, you must provide a root
token or a token associated with appropriate policies across all the targeted
namespaces. Refer to
the <a href="/vault/tutorials/enterprise/namespaces">Secure multi-tenancy with
namespaces</a>tutorial for configuring your Vault instance appropriately.
</Note>
- `-filter` `(string: "")` - Filter expression used to select event notifications to be sent
through the WebSocket.
Refer to the [Filter expressions](/vault/docs/concepts/filtering) guide for a complete
list of filtering options and an explanation on how Vault evaluates filter expressions.
The following values are available in the filter expression:
- `event_type`: the event type, e.g., `kv-v2/data-write`.
- `operation`: the operation name that caused the event notification, e.g., `write`.
- `source_plugin_mount`: the mount of the plugin that produced the event notification,
e.g., `secret/`
- `data_path`: the API path that can be used to access the data of the secret related to the event notification, e.g., `secret/data/foo`
- `namespace`: the path of the namespace that created the event notification, e.g., `ns1/`
The filter string is empty by default. Unfiltered subscription requests match to
all event notifications that the requestor has access to for the target event type. When the
filter string is not empty, Vault applies the filter conditions after the policy
checks to narrow the event notifications provided in the response.
Filters can be straightforward path matches like
`data_path == secret/data/foo`, which specifies that Vault should pass
return event notifications that refer to the `secret/data/foo` secret to the WebSocket.
Or more complex statements that exclude specific operations. For example:
```
data_path == secret/data/foo and operation != write
```

60
website/content/cli/commands/hcp/connect.mdx Normal file
View file

@ -0,0 +1,60 @@
---
layout: docs
page_title: hcp connect - Command
description: |-
Use "hcp connect" command to authenticate users and machines to HCP with explicit
credentials or an HCP token and interactive browser login.
---
# hcp connect
The `hcp connect` command authenticates users and machines to HCP with explicit
credentials or an HCP token and interactive browser login.
By default, the `hcp connect` command uses interactive authentication that requires
users to log into the HashiCorp Cloud Platform with a browser.
Non-interactive login requires a service principal credential that was
previously generated through the HCP portal. The service principal must have
access to the requested organization, project, and HCP Vault Dedicated cluster.
If authentication succeeds, the Vault CLI saves the returned HCP token and HCP
Vault address in the local cache.
## Examples
Connect to HCP interactively:
```shell-session
$ vault hcp connect
The default web browser has been opened at <auth_url>. Please continue the login in the web browser.
Success!
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-client-id` `(string: "")` - Client ID belonging to a service principal
credential generated in the HCP Portal. **Required for non-interactive
authentication**.
- `-secret-id` `(string: "")` - Secret ID belonging to a service principal
credential previously generated in the HCP Portal. **Required for
non-interactive authentication**.
- `-organization-id` `(string: "")` - Optional ID of the desired HCP
organization. If `organization-id` is empty and the user is associated with
multiple HCP organizations, the CLI prompts the user to select from a list
of available organizations.
- `-project-id` `(string: "")` - Optional ID of the desired HCP project. If
`project-id` is empty and the user is associated with more than one HCP
project, the CLI prompts the user to select from a list of available projects.
- `-cluster-id` `(string: "")` - Optional ID of the desired HCP Vault Dedicated cluster.
If `cluster-id` is empty and the user is associated with multiple HCP clusters,
the CLI prompts the user to select from a list of available clusters.

23
website/content/cli/commands/hcp/disconnect.mdx Normal file
View file

@ -0,0 +1,23 @@
---
layout: docs
page_title: hcp disconnect - Command
description: |-
Use "hcp disconnect" command invalidates live sessions to a HCP Vault Dedicated cluster.
---
# hcp disconnect
The `hcp disconnect` command invalidates live sessions to a HCP Vault Dedicated cluster.
## Examples
Disconnect from HCP:
```shell-session
$ vault hcp disconnect
```
## Usage
All [standard set of
flags](/vault/docs/commands) are included.

27
website/content/cli/commands/hcp/index.mdx Normal file
View file

@ -0,0 +1,27 @@
---
layout: docs
page_title: hcp - Command
description: |-
Use "hcp" commands to authenticate users and machines to HCP with explicit
credentials or an HCP token and interactive browser login and to invalidate any live authentication session.
---
# hcp
Use `hcp` commands to manage authentication to HCP via proxy,
which allows clients to connect to this cluster securely over the internet with a proxy address and to invalidate any live authentication session.
## Examples
Connect to HCP:
```shell-session
$ vault hcp connect
The default web browser has been opened at <auth_url>. Please continue the login in the web browser.
Success!
```
Disconnect from HCP:
```shell-session
$ vault hcp disconnect
```

48
website/content/cli/commands/kv/delete.mdx Normal file
View file

@ -0,0 +1,48 @@
---
layout: docs
page_title: kv delete - Command
description: |-
The "kv delete" command deletes the data for the provided path in the key/value secrets engine.
---
# kv delete
The `kv delete` command deletes the data for the provided path in
the key/value secrets engine. If using KV version 2, its versioned data will
not be fully removed, but marked as deleted and will no longer be returned in
normal get requests.
## Examples
Delete the latest version of the key "creds":
```shell-session
$ vault kv delete -mount=secret creds
Success! Data deleted (if it existed) at: secret/creds
```
**[KV version 2]** Delete version 11 of key "creds":
```shell-session
$ vault kv delete -mount=secret -versions=11 creds
Success! Data deleted (if it existed) at: secret/data/creds
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Command options
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.
- `-versions` `([]int: <required>)` - The versions to be deleted. The versioned
data will not be deleted, but it will no longer be returned in normal get
requests.
~> **NOTE:** The `-versions` command option is only for KV v2.

47
website/content/cli/commands/kv/destroy.mdx Normal file
View file

@ -0,0 +1,47 @@
---
layout: docs
page_title: kv destroy - Command
description: |-
The "kv destroy" command permanently removes the specified version data for
the provided key and version numbers from the key-value store.
---
# kv destroy
~> **NOTE:** This is a [KV version 2](/vault/docs/secrets/kv/kv-v2) secrets
engine command, and not available for Version 1.
The `kv destroy` command permanently removes the specified versions' data
from the key/value secrets engine. If no key exists at the path, no action is
taken.
## Examples
Destroy version 11 of the key "creds":
```shell-session
$ vault kv destroy -mount=secret -versions=11 creds
Success! Data written to: secret/destroy/creds
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.
- `-versions` `([]int: <required>)` - The versions to destroy. Their data will
be permanently deleted.

33
website/content/cli/commands/kv/enable-versioning.mdx Normal file
View file

@ -0,0 +1,33 @@
---
layout: docs
page_title: kv enable-versioning - Command
description: |-
The "kv enable-versioning" command turns on versioning for the backend
at the provided path.
---
# kv enable-versioning
The `kv enable-versioning` command turns on versioning for an existing
non-versioned key/value secrets engine (KV version 1) at its path.
## Examples
This command turns on versioning for the KV version 1 secrets engine enabled at
"secret".
```shell-session
$ vault kv enable-versioning secret
Success! Tuned the secrets engine at: secret/
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

80
website/content/cli/commands/kv/get.mdx Normal file
View file

@ -0,0 +1,80 @@
---
layout: docs
page_title: kv get - Command
description: |-
The "kv get" command retrieves the value from Vault's key-value store at the
given key name. If no key exists with that name, an error is returned. If a
key exists with that name but has no data, nothing is returned.
---
# kv get
The `kv get` command retrieves the value from KV secrets engine at the given
key name. If no key exists with that name, an error is returned. If a key exists
with the name but has no data, nothing is returned.
## Examples
Retrieve the data of the key "creds":
```shell-session
$ vault kv get -mount=secret creds
== Secret Path ==
secret/data/creds
======= Metadata =======
Key Value
--- -----
created_time 2022-06-15T20:23:40.067093Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
====== Data ======
Key Value
--- -----
passcode my-long-passcode
```
If KV version 1 secrets engine is enabled at "secret", the output has no
metadata since there is no versioning information associated with the data:
```shell-session
$ vault kv get -mount=secret creds
====== Data ======
Key Value
--- -----
passcode my-long-passcode
```
Return only the "creds" "passcode" key:
```shell-session
$ vault kv get -mount=secret -field=passcode creds
my-long-passcode
```
## Usage
### Output options
- `-field` `(string: "")` - Print only the field with the given name. Specifying
this option will take precedence over other formatting directives. The result
will not have a trailing newline making it ideal for piping to other
processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.
- `-version` `(int: 0)` - Specifies the version to return. If not set the
latest version is returned.

163
website/content/cli/commands/kv/index.mdx Normal file
View file

@ -0,0 +1,163 @@
---
layout: docs
page_title: kv - Command
description: |-
The "kv" command groups subcommands for interacting with Vault's key/value
secret engine.
---
# kv
The `kv` command groups subcommands for interacting with Vault's key/value
secrets engine (both [KV version 1](/vault/docs/secrets/kv/kv-v1) and [KV
Version 2](/vault/docs/secrets/kv/kv-v2).
## Syntax
Option flags for a given subcommand are provided after the subcommand, but before the arguments.
The path to where the secrets engine is mounted can be indicated with the `-mount` flag, such as `vault kv get -mount=secret creds`.
The deprecated path-like syntax can also be used (e.g. `vault kv get secret/creds`), but this should be avoided
for KV v2, because it is not actually the full API path to the secret
(secret/data/foo) and may cause confusion.
~> A `flag provided but not defined: -mount` error means you are using an older version of Vault before the
mount flag syntax was introduced. Upgrade to at least Vault 1.11, or refer to previous versions of the docs
which only use the old syntax to refer to the mount path.
## Mount flag syntax (KV)
All `kv` commands can alternatively refer to the path to the KV secrets engine using a flag-based syntax like `$ vault kv get -mount=secret password`
instead of `$ vault kv get secret/password`. The mount flag syntax was created to mitigate confusion caused by the fact that for KV v2 secrets,
their full path (used in policies and raw API calls) actually contains a nested `/data/` element (e.g. `secret/data/password`) which can be easily overlooked when using
the above KV v1-like syntax `secret/password`. To avoid this confusion, all KV-specific docs pages will use the `-mount` flag.
## Exit codes
The Vault CLI aims to be consistent and well-behaved unless documented
otherwise.
- Local errors such as incorrect flags, failed validations, or wrong numbers
of arguments return an exit code of 1.
- Any remote errors such as API failures, bad TLS, or incorrect API parameters
return an exit status of 2
Some commands override this default where it makes sense. These commands
document this anomaly.
## Examples
Create or update the key named "creds" in the KV version 2 enabled at "secret"
with the value "passcode=my-long-passcode":
```shell-session
$ vault kv put -mount=secret creds passcode=my-long-passcode
== Secret Path ==
secret/data/creds
======= Metadata =======
Key Value
--- -----
created_time 2022-06-15T20:14:17.107852Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
```
Read this value back:
```shell-session
$ vault kv get -mount=secret creds
== Secret Path ==
secret/data/creds
======= Metadata =======
Key Value
--- -----
created_time 2022-06-15T20:14:17.107852Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
====== Data ======
Key Value
--- -----
passcode my-long-passcode
```
Get metadata for the key named "creds":
```shell-session
$ vault kv metadata get -mount=secret creds
=== Metadata Path ===
secret/metadata/creds
========== Metadata ==========
Key Value
--- -----
cas_required false
created_time 2022-06-15T20:14:17.107852Z
current_version 1
custom_metadata <nil>
delete_version_after 0s
max_versions 0
oldest_version 0
updated_time 2022-06-15T20:14:17.107852Z
====== Version 1 ======
Key Value
--- -----
created_time 2022-06-15T20:14:17.107852Z
deletion_time n/a
destroyed false
```
Get a specific version of the key named "creds":
```shell-session
$ vault kv get -mount=secret -version=1 creds
== Secret Path ==
secret/data/creds
======= Metadata =======
Key Value
--- -----
created_time 2022-06-15T20:14:17.107852Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
====== Data ======
Key Value
--- -----
passcode my-long-passcode
```
## Usage
```text
Usage: vault kv <subcommand> [options] [args]
# ...
Subcommands:
delete Deletes versions in the KV store
destroy Permanently removes one or more versions in the KV store
enable-versioning Turns on versioning for a KV store
get Retrieves data from the KV store
list List data or secrets
metadata Interact with Vault's Key-Value storage
patch Sets or updates data in the KV store without overwriting
put Sets or updates data in the KV store
rollback Rolls back to a previous version of data
undelete Undeletes versions in the KV store
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

49
website/content/cli/commands/kv/list.mdx Normal file
View file

@ -0,0 +1,49 @@
---
layout: docs
page_title: kv list - Command
description: |-
The "kv list" command lists data from Vault's KV secrets engine at the given
path.
---
# kv list
The `kv list` command returns a list of key names at the specified location.
Folders are suffixed with /. The input must be a folder; list on a file will not
return a value. Note that no policy-based filtering is performed on keys; do not
encode sensitive information in key names. The values themselves are not
accessible via this command.
Use this command to list all existing key names at a specific path.
## Examples
List values under the key "my-app":
```shell-session
$ vault kv list -mount=secret my-app/
Keys
----
admin_creds
domain
eng_creds
qa_creds
release
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Output options
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

163
website/content/cli/commands/kv/metadata.mdx Normal file
View file

@ -0,0 +1,163 @@
---
layout: docs
page_title: kv metadata - Command
description: |-
The "kv metadata" command has subcommands for interacting with the metadata
endpoint in Vault's key-value store.
---
# kv metadata
~> **NOTE:** This is a [KV version 2](/vault/docs/secrets/kv/kv-v2) secrets
engine command, and not available for Version 1.
The `kv metadata` command has subcommands for interacting with the metadata and
versions for the versioned secrets (KV version 2 secrets engine) at the
specified path.
## Usage
```text
Usage: vault kv metadata <subcommand> [options] [args]
# ...
Subcommands:
delete Deletes all versions and metadata for a key in the KV store
get Retrieves key metadata from the KV store
put Sets or updates key settings in the KV store
```
### kv metadata delete
The `kv metadata delete` command deletes all versions and metadata for the
provided key.
#### Examples
Deletes all versions and metadata of the key "creds":
```shell-session
$ vault kv metadata delete -mount=secret creds
Success! Data deleted (if it existed) at: secret/metadata/creds
```
### kv metadata get
The `kv metadata get` command retrieves the metadata of the versioned secrets at
the given key name. If no key exists with that name, an error is returned.
#### Examples
Retrieves the metadata of the key name, "creds":
```shell-session
$ vault kv metadata get -mount=secret creds
=== Metadata Path ===
secret/metadata/creds
========== Metadata ==========
Key Value
--- -----
cas_required false
created_time 2019-06-28T15:53:30.395814Z
current_version 5
delete_version_after 0s
max_versions 0
oldest_version 0
updated_time 2019-06-28T16:01:47.40064Z
====== Version 1 ======
Key Value
--- -----
created_time 2019-06-28T15:53:30.395814Z
deletion_time n/a
destroyed false
====== Version 2 ======
Key Value
--- -----
created_time 2019-06-28T16:01:36.676912Z
deletion_time n/a
destroyed false
...
```
### kv metadata put
The `kv metadata put` command can be used to create a blank key in the KV v2
secrets engine or to update key configuration for a specified key.
#### Examples
Create a key in the KV v2 with no data at the key "creds":
```shell-session
$ vault kv metadata put -mount=secret creds
Success! Data written to: secret/metadata/creds
```
Set the maximum number of versions to keep for the key "creds":
```shell-session
$ vault kv metadata put -mount=secret -max-versions=5 creds
Success! Data written to: secret/metadata/creds
```
**NOTE:** If not set, the backend’s configured max version is used. Once a key
has more than the configured allowed versions the oldest version will be
permanently deleted.
Require Check-and-Set for the key "creds":
```shell-session
$ vault kv metadata put -mount=secret -cas-required creds
```
**NOTE:** When check-and-set is required, the key will require the `cas`
parameter to be set on all write requests. Otherwise, the backend’s
configuration will be used.
Set the length of time before a version is deleted for the key "creds":
```shell-session
$ vault kv metadata put -mount=secret -delete-version-after="3h25m19s" creds
```
**NOTE:** If not set, the backend's configured Delete-Version-After is used. If
set to a duration greater than the backend's, the backend's Delete-Version-After
setting will be used. Any changes to the Delete-Version-After setting will only
be applied to new versions.
#### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
#### Subcommand options
- `-cas-required` `(bool: false)` - If true the key will require the cas
parameter to be set on all write requests. If false, the backend’s
configuration will be used. The default is false.
- `-max-versions` `(int: 0)` - The number of versions to keep per key. If not
set, the backend’s configured max version is used. Once a key has more than the
configured allowed versions the oldest version will be permanently deleted.
- `-delete-version-after` `(string:"0s")` – Set the `delete-version-after` value
to a duration to specify the `deletion_time` for all new versions written to
this key. If not set, the backend's `delete_version_after` will be used. If
the value is greater than the backend's `delete_version_after`, the backend's
`delete_version_after` will be used. Accepts [duration format strings](/vault/docs/concepts/duration-format).
- `-custom-metadata` `(string: "")` - Specifies a key-value pair for the
`custom_metadata` field. This can be specified multiple times to add multiple
pieces of metadata.
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.

91
website/content/cli/commands/kv/patch.mdx Normal file
View file

@ -0,0 +1,91 @@
---
layout: docs
page_title: kv patch - Command
description: |-
The "kv patch" command writes the data to the given path in the key-value
store. The data can be of any type.
---
# kv patch
~> **NOTE:** This is a [KV version 2](/vault/docs/secrets/kv/kv-v2) secrets
engine command, and not available for Version 1.
The `kv patch` command writes the data to the given path in the KV v2 secrets
engine. The data can be of any type. Unlike the `kv put` command, the `patch`
command combines the change with existing data instead of replacing them.
Therefore, this command makes it easy to make a partial updates to an existing
data.
## Examples
If you wish to add an additional key-value (`ttl=48h`) to the existing data at
the key "creds":
```shell-session
$ vault kv patch -mount=secret creds ttl=48h
== Secret Path ==
secret/data/creds
======= Metadata =======
Key Value
--- -----
created_time 2019-06-06T16:46:22.090654Z
deletion_time n/a
destroyed false
version 6
```
**NOTE:** The `kv put` command requires both the existing data and
the data you wish to add in order to accomplish the same result.
```shell-session
$ vault kv put -mount=secret creds ttl=48h passcode=my-long-passcode
```
The data can also be consumed from a file on disk by prefixing with the "@"
symbol. For example:
```shell-session
$ vault kv patch -mount=secret creds @data.json
```
Or it can be read from stdin using the "-" symbol:
```shell-session
$ echo "abcd1234" | vault kv patch -mount=secret foo bar=-
```
## Usage
### Output options
- `-field` `(string: "")` - Print only the field with the given name. Specifying
this option will take precedence over other formatting directives. The result
will not have a trailing newline making it ideal for piping to other
processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-method` `(string: "patch")` - Specifies the patch method to use. Valid
methods are `patch` and `rw`. The `patch` method uses an HTTP `PATCH` request
to apply the partial update. The `rw` method will fetch the secret's data,
perform an in-memory update, and write the updated data.
- `-cas` `(int: 0)` - Specifies the value to use for the Check-And-Set operation.
This flag will only be used for the `patch` method. This flag is required if
`cas_required` is set to `true` on either the secret or the engine's config.
In order for a `patch` to be successful, `-cas` must be set to the current
version of the secret. This flag will be ignored for the `rw` method.
Instead, its value will be derived from fetching the current version of the
secret.
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.

74
website/content/cli/commands/kv/put.mdx Normal file
View file

@ -0,0 +1,74 @@
---
layout: docs
page_title: kv put - Command
description: |-
The "kv put" command writes the data to the given path in the KV secrets
engine. The data can be of any type.
---
# kv put
The `kv put` command writes the data to the given path in the KV secrets
engine.
If working with KV v2, this command creates a new version of a secret at the
specified location. If working with KV v1, this command stores the given secret
at the specified location.
Regardless of the KV version, if the value does not yet exist at the specified
path, the calling token must have an ACL policy granting the "create"
capability. If the value already exists, the calling token must have an ACL
policy granting the "update" capability.
## Examples
Writes the data to the key "creds":
```shell-session
$ vault kv put -mount=secret creds passcode=my-long-passcode
```
The data can also be consumed from a file on disk by prefixing with the "@"
symbol. For example:
```shell-session
$ vault kv put -mount=secret foo @data.json
```
Or it can be read from stdin using the "-" symbol:
```shell-session
$ echo "abcd1234" | vault kv put -mount=secret foo bar=-
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name. Specifying
this option will take precedence over other formatting directives. The result
will not have a trailing newline making it ideal for piping to other
processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-cas` `(int: 0)` - Specifies to use a Check-And-Set operation. If not set the
write will be allowed. In order for a write to be successful, `cas` must be set to
the current version of the secret. If set to 0 a write will only be allowed if
the key doesn’t exist as unset keys do not have any version information. Also
remember that soft deletes do not remove any underlying version data from storage.
In order to write to a soft deleted key, the cas parameter must match the key's
current version. The default is -1.
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.

54
website/content/cli/commands/kv/rollback.mdx Normal file
View file

@ -0,0 +1,54 @@
---
layout: docs
page_title: kv rollback - Command
description: |-
The "kv rollback" command restores a given previous version to the current
version at the given path.
---
# kv rollback
~> **NOTE:** This is a [KV version 2](/vault/docs/secrets/kv/kv-v2) secrets
engine command, and not available for Version 1.
The `kv rollback` command restores a given previous version to the current
version at the given path. The value is written as a new version; for instance,
if the current version is 5 and the rollback version is 2, the data from version
2 will become version 6. This command makes it easy to restore unintentionally
overwritten data.
## Examples
Restores the version 2 of the data at key "creds":
```shell-session
$ vault kv rollback -mount=secret -version=2 creds
Key Value
--- -----
created_time 2019-06-06T17:07:19.299831Z
deletion_time n/a
destroyed false
version 6
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.
- `-version` `(int: 0)` - Specifies the version number that should be made
current again.

48
website/content/cli/commands/kv/undelete.mdx Normal file
View file

@ -0,0 +1,48 @@
---
layout: docs
page_title: kv undelete - Command
description: |-
The "kv undelete" command undeletes the data for the provided version and path
in the key-value store. This restores the data, allowing it to be returned on
get requests.
---
# kv undelete
~> **NOTE:** This is a [KV version 2](/vault/docs/secrets/kv/kv-v2) secrets
engine command, and not available for Version 1.
The `kv undelete` command undoes the deletes of the data for the provided version
and path in the key-value store. This restores the data, allowing it to be
returned on get requests.
## Examples
Undelete version 3 of the key "creds":
```shell-session
$ vault kv undelete -mount=secret -versions=3 creds
Success! Data written to: secret/undelete/creds
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted.
If specified, the next argument will be interpreted as the secret path. If
this flag is not specified, the next argument will be interpreted as the
combined mount path and secret path, with /data/ automatically inserted for
KV v2 secrets.
- `-versions` `([]int: <required>)` - Specifies the version number that should
be made current again.

62
website/content/cli/commands/lease/index.mdx Normal file
View file

@ -0,0 +1,62 @@
---
layout: docs
page_title: lease - Command
description: |-
The "lease" command groups subcommands for interacting with leases attached to
secrets.
---
# lease
The `lease` command groups subcommands for interacting with leases attached to
secrets. For leases attached to tokens, use the [`vault token`](/vault/docs/commands/token) subcommand.
## Examples
Lookup a lease:
```shell-session
$ vault lease lookup database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
Key Value
--- -----
expire_time 2021-03-17T11:55:50.755313-05:00
id database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
issue_time 2021-03-17T11:45:50.755312-05:00
last_renewal <nil>
renewable true
ttl 9m52s
```
Renew a lease:
```shell-session
$ vault lease renew database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
Key Value
--- -----
lease_id database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
lease_duration 5m
lease_renewable true
```
Revoke a lease:
```shell-session
$ vault lease revoke database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
Success! Revoked lease: database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
```
## Usage
```text
Usage: vault lease <subcommand> [options] [args]
# ...
Subcommands:
lookup Lookup lease information by lease id
renew Renews the lease of a secret
revoke Revokes leases and secrets
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

34
website/content/cli/commands/lease/lookup.mdx Normal file
View file

@ -0,0 +1,34 @@
---
layout: docs
page_title: lease lookup - Command
description: |-
The "lease lookup" command retrieves information about a lease.
---
# lease lookup
The `lease lookup` command retrieves information on the lease of a secret.
Every secret in Vault has a lease associated with it. Users can look up
information on the lease by referencing the lease ID.
## Examples
Lookup a lease:
```shell-session
$ vault lease lookup database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
Key Value
--- -----
expire_time 2021-03-17T11:55:50.755313-05:00
id database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
issue_time 2021-03-17T11:45:50.755312-05:00
last_renewal <nil>
renewable true
ttl 9m52s
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

37
website/content/cli/commands/lease/renew.mdx Normal file
View file

@ -0,0 +1,37 @@
---
layout: docs
page_title: lease renew - Command
description: |-
The "lease renew" command renews the lease on a secret, extending the time
that it can be used before it is revoked by Vault.
---
# lease renew
The `lease renew` command renews the lease on a secret, extending the time that
it can be used before it is revoked by Vault.
Every secret in Vault has a lease associated with it. If the owner of the secret
wants to use it longer than the lease, then it must be renewed. Renewing the
lease does not change the contents of the secret.
## Examples
Renew a lease:
```shell-session
$ vault lease renew database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
Key Value
--- -----
lease_id database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
lease_duration 5m
lease_renewable true
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-increment` `(duration: "")` - Request a specific increment in seconds. Vault
is not required to honor this request.

45
website/content/cli/commands/lease/revoke.mdx Normal file
View file

@ -0,0 +1,45 @@
---
layout: docs
page_title: lease revoke - Command
description: |-
The "lease revoke" command revokes the lease on a secret, invalidating the
underlying secret.
---
# lease revoke
The `lease revoke` command revokes the lease on a secret, invalidating the
underlying secret.
## Examples
Revoke a lease:
```shell-session
$ vault lease revoke database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
Success! Revoked lease: database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
```
Revoke a lease which starts with a prefix:
```shell-session
$ vault lease revoke -prefix database/creds
Success! Revoked any leases with prefix: database/creds
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-force` `(bool: false)` - Delete the lease from Vault even if the secret
engine revocation fails. This is meant for recovery situations where the
secret in the target secrets engine was manually removed. If this flag is
specified, -prefix is also required. This is aliased as "-f". The default is
false.
- `-prefix` `(bool: false)` - Treat the ID as a prefix instead of an exact lease
ID. This can revoke multiple leases simultaneously. The default is false.
- `-sync` `(bool: false)` - Make the operation synchronous instead of queuing the
revocations to be done in the background.

52
website/content/cli/commands/license/get.mdx Normal file
View file

@ -0,0 +1,52 @@
---
layout: docs
page_title: license get - Command
description: |-
The "license get" command reports on the license in use.
---
# license get
The `license get` command reports on the license in use. With the `-signed`
flag, it will return the actual license string, but only if the license
is stored, as opposed to [autoloaded](/vault/docs/enterprise/license/autoloading).
## Examples
Describe current license:
```shell-session
$ vault license get
Key Value
--- -----
expiration_time 2022-05-17T23:59:59Z
features [HSM Performance Replication DR Replication MFA Sentinel Seal Wrapping Control Groups Performance Standby Namespaces KMIP Entropy Augmentation Transform Secrets Engine Lease Count Quotas Key Management Secrets Engine Automated Snapshots]
license_id 060d7820-fa59-f95c-832b-395db0aeb9ba
performance_standby_count 9999
start_time 2021-05-17T00:00:00Z
termination_time 2031-05-17T23:59:59Z
```
Get stored license string:
```shell-session
$ vault license get -signed
02MV4UU43BK5H...
```
Try to get stored license string when using autoloading:
```shell-session
$ vault license get -signed
License not found or using a temporary license.
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-signed` `(bool: false)` - Return the signed license string when using a
stored license.

60
website/content/cli/commands/license/index.mdx Normal file
View file

@ -0,0 +1,60 @@
---
layout: docs
page_title: license - Command
description: |-
The "license" command groups subcommands for interacting with Vault licenses.
---
# license
The `license` command groups subcommands for interacting with Vault licenses
For more information, please see the [license documentation](/vault/docs/enterprise/license)
## Examples
Query current license in use by a node:
```shell-session
$ vault license get
Key Value
--- -----
expiration_time 2022-05-17T23:59:59.999Z
features [HSM Performance Replication DR Replication MFA Sentinel Seal Wrapping Control Groups Performance Standby Namespaces KMIP Entropy Augmentation Transform Secrets Engine Lease Count Quotas Key Management Secrets Engine Automated Snapshots]
license_id 060d7820-fa59-f95c-832b-395db0aeb9ba
performance_standby_count 9999
start_time 2021-05-17T00:00:00Z
```
Inspect a license string:
```shell-session
$ vault license inspect ~/vaults/license
Source: /Users/ncc/vaults/license
Product: vault
License ID: 060d7820-fa59-f95c-832b-395db0aeb9ba
Customer ID: 5401ae3b-136b-3e47-3b43-432927fa03e7
Installation ID: *
Issue Time: 2021-05-17 19:33:47.93981585 +0000 UTC
Start Time: 2021-05-17 00:00:00 +0000 UTC
Expiration Time: 2022-05-17 23:59:59.999 +0000 UTC
{"license_id":"060d7820-fa59-f95c-832b-395db0aeb9ba","customer_id":"5401ae3b-136b-3e47-3b43-432927fa03e7","installation_id":"*","issue_time":"2021-05-17T19:33:47.93981585Z","start_time":"2021-05-17T00:00:00Z","expiration_time":"2022-05-17T23:59:59.999Z","flags":{"modules":["multi-dc-scale","governance-policy","advanced-data-protection"]},"features":["HSM","Performance Replication","DR Replication","MFA","Sentinel","Seal Wrapping","Control Groups","Performance Standby","Namespaces","KMIP","Entropy Augmentation","Transform Secrets Engine","Lease Count Quotas","Key Management Secrets Engine","Automated Snapshots"],"performance_standby_count":9999}
License is valid
```
## Usage
```text
Usage: vault license <subcommand> [options] [args]
# ...
Subcommands:
get Query Vault's license
inspect View the contents of a license string
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

58
website/content/cli/commands/license/inspect.mdx Normal file
View file

@ -0,0 +1,58 @@
---
layout: docs
page_title: license inspect - Command
description: |-
The "license inspect" command describes the contents of a signed license string.
---
# license inspect
The `license inspect` command describes the contents of a signed license string.
## Examples
Describe license in the environment (either `VAULT_LICENSE` for a raw value
or `VAULT_LICENSE_PATH` for the path to a file containing the value):
```shell-session
$ vault license inspect
Source: /Users/ncc/vaults/license
Product: vault
License ID: 060d7820-fa59-f95c-832b-395db0aeb9ba
Customer ID: 5401ae3b-136b-3e47-3b43-432927fa03e7
Installation ID: *
Issue Time: 2021-05-17 19:33:47.93981585 +0000 UTC
Start Time: 2021-05-17 00:00:00 +0000 UTC
Expiration Time: 2022-05-17 23:59:59.999 +0000 UTC
Termination Time: 2031-05-17 23:59:59.999 +0000 UTC
{"license_id":"060d7820-fa59-f95c-832b-395db0aeb9ba","customer_id":"5401ae3b-136b-3e47-3b43-432927fa03e7","installation_id":"*","issue_time":"2021-05-17T19:33:47.93981585Z","start_time":"2021-05-17T00:00:00Z","expiration_time":"2022-05-17T23:59:59.999Z","flags":{"modules":["multi-dc-scale","governance-policy","advanced-data-protection"]},"features":["HSM","Performance Replication","DR Replication","MFA","Sentinel","Seal Wrapping","Control Groups","Performance Standby","Namespaces","KMIP","Entropy Augmentation","Transform Secrets Engine","Lease Count Quotas","Key Management Secrets Engine","Automated Snapshots"],"performance_standby_count":9999}
License is valid
```
Describe license at given path:
```shell-session
$ vault license inspect ~/vaults/license
Source: /Users/ncc/vaults/license
Product: vault
License ID: 060d7820-fa59-f95c-832b-395db0aeb9ba
Customer ID: 5401ae3b-136b-3e47-3b43-432927fa03e7
Installation ID: *
Issue Time: 2021-05-17 19:33:47.93981585 +0000 UTC
Start Time: 2021-05-17 00:00:00 +0000 UTC
Expiration Time: 2022-05-17 23:59:59.999 +0000 UTC
Termination Time: 2031-05-17 23:59:59.999 +0000 UTC
{"license_id":"060d7820-fa59-f95c-832b-395db0aeb9ba","customer_id":"5401ae3b-136b-3e47-3b43-432927fa03e7","installation_id":"*","issue_time":"2021-05-17T19:33:47.93981585Z","start_time":"2021-05-17T00:00:00Z","expiration_time":"2022-05-17T23:59:59.999Z","flags":{"modules":["multi-dc-scale","governance-policy","advanced-data-protection"]},"features":["HSM","Performance Replication","DR Replication","MFA","Sentinel","Seal Wrapping","Control Groups","Performance Standby","Namespaces","KMIP","Entropy Augmentation","Transform Secrets Engine","Lease Count Quotas","Key Management Secrets Engine","Automated Snapshots"],"performance_standby_count":9999}
License is valid
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-installation-id` `(string: "")` - Installation ID to validate the license against

25
website/content/cli/commands/list.mdx Normal file
View file

@ -0,0 +1,25 @@
---
layout: docs
page_title: list - Command
description: |-
The "list" command lists data from Vault at the given path. This can be used
to list keys in a, given secrets engine.
---
# list
The `list` command lists data from Vault at the given path (wrapper command for
HTTP LIST). This can be used to list keys in a given secrets engine.
## Examples
List available entities by their identifiers:
```shell-session
$ vault list identity/entity/id
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

156
website/content/cli/commands/login.mdx Normal file
View file

@ -0,0 +1,156 @@
---
layout: docs
page_title: login - Command
description: |-
The "login" command authenticates users or machines to Vault using the
provided arguments. A successful authentication results in a Vault token -
conceptually similar to a session token on a website.
---
# login
The `login` command authenticates users or machines to Vault using the provided
arguments. A successful authentication results in a Vault token - conceptually
similar to a session token on a website. By default, this token is cached on the
local machine for future requests.
The `-method` flag allows using other auth methods, such as userpass,
github, or cert. For these, additional "K=V" pairs may be required. For more
information about the list of configuration parameters available for a given
auth method, use the "vault auth help TYPE" command. You can also use "vault
auth list" to see the list of enabled auth methods.
If an auth method is enabled at a non-standard path, the `-method`
flag still refers to the canonical type, but the `-path` flag refers to the
enabled path.
If the authentication is requested with response wrapping (via `-wrap-ttl`),
the returned token is automatically unwrapped unless:
- The `-token-only` flag is used, in which case this command will output
the wrapping token.
- The `-no-store` flag is used, in which case this command will output the
details of the wrapping token.
## Examples
By default, login uses a "token" method and reads from stdin:
```shell-session
$ vault login
Token (will be hidden):
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.nDj4BB2tK8NaFffwBZBxyIa1
token_accessor ZuaObqdTeCHZ4oa9HWmdQJuZ
token_duration ∞
token_renewable false
token_policies ["root"]
identity_policies []
policies ["root"]
```
Alternatively, the token may be provided as a command line argument (note that
this may be captured by shell history or process listings):
```shell-session
$ vault login s.3jnbMAKl1i4YS3QoKdbHzGXq
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.3jnbMAKl1i4YS3QoKdbHzGXq
token_accessor 7Uod1Rm0ejUAz77Oh7SxpAM0
token_duration 767h59m49s
token_renewable true
token_policies ["admin" "default"]
identity_policies []
policies ["admin" "default"]
```
To login with a different method, use `-method`:
```shell-session
$ vault login -method=userpass username=my-username
Password (will be hidden):
Success! You are now authenticated. The token information below is already
stored in the token helper. You do NOT need to run "vault login" again. Future
requests will use this token automatically.
Key Value
--- -----
token s.2y4SU3Sk46dK3p2Y8q2jSBwL
token_accessor 8J125x9SZyB76MI9uF2jSJZf
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_username my-username
```
~> Notice that the command option (`-method=userpass`) precedes the command
argument (`username=my-username`).
If a github auth method was enabled at the path "github-prod":
```shell-session
$ vault login -method=github -path=github-prod
Success! You are now authenticated. The token information below is already
stored in the token helper. You do NOT need to run "vault login" again. Future
requests will use this token automatically.
Key Value
--- -----
token s.2f3c5L1MHtnqbuNCbx90utmC
token_accessor JLUIXJ6ltUftTt2UYRl2lTAC
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_org hashicorp
token_meta_username my-username
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name, in the format
specified in the `-format` directive. The result will not have a trailing
newline making it ideal for piping to other processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-method` `(string "token")` - Type of authentication to use such as
"userpass" or "ldap". Note this corresponds to the TYPE, not the enabled path.
Use -path to specify the path where the authentication is enabled.
- `-no-print` `(bool: false)` - Do not display the token. The token will
still be stored to the configured token helper. The default is false.
- `-no-store` `(bool: false)` - Do not persist the token to the token helper
(usually the local filesystem) after authentication for use in future
requests. The token will only be displayed in the command output.
- `-path` `(string: "")` - Remote path in Vault where the auth method
is enabled. This defaults to the TYPE of method (e.g. userpass -> userpass/).
- `-token-only` `(bool: false)` - Output only the token with no verification.
This flag is a shortcut for "-field=token -no-store". Setting those
flags to other values will have no affect.

78
website/content/cli/commands/monitor.mdx Normal file
View file

@ -0,0 +1,78 @@
---
layout: docs
page_title: 'monitor - Vault CLI'
description: >-
Use vault monitor to stream server logs to stdout in real time.
---
# `monitor`
Stream Vault server logs in real-time to `stdout`.
<CodeBlockConfig hideClipboard>
```shell-session
$ vault monitor [flags]
$ vault monitor [-help | -h]
```
</CodeBlockConfig>
## Description
`vault monitor` streams Vault server logs to `stdout` in real time based on the
address stored in `VAULT_ADDR` or passed through `-address`. Use the
`-log-level` flag to override the default log level set for the Vault server.
<Tip title="Related API endpoints">
MonitorLogs - [`GET: /sys/monitor`](/vault/api-docs/system/monitor)
</Tip>
### Limitations and warnings
- `vault monitor` runs indefinitely and only exits if an unexpected error occurs.
- `vault monitor` may drop log lines if Vault is emitting log messages faster
than the receiver can process the input.
## Command arguments
None.
## Command options
None.
## Command flags
<br />
@include 'cli/shared/flags/log-level.mdx'
<br /><hr /><br />
@include 'cli/shared/flags/log-format.mdx'
## Standard flags
@include 'cli/standard-settings/all-standard-flags.mdx'
## Examples
Stream server logs at the `debug` log level:
```shell-session
$ vault monitor -log-level=debug
```

98
website/content/cli/commands/namespace.mdx Normal file
View file

@ -0,0 +1,98 @@
---
layout: docs
page_title: namespace - Command
description: The "namespace" command groups subcommands for interacting with namespaces.
---
# namespace
The `namespace` command groups subcommands for interacting with namespaces.
## Examples
List all namespaces:
```shell-session
$ vault namespace list
```
List all namespaces with additional details such as namespace ID and custom metadata:
```shell-session
$ vault namespace list -detailed
```
Create a namespace at the path `ns1/` with no custom metadata:
```shell-session
$ vault namespace create ns1/
```
Create a namespace at the path `ns1/` with multiple custom metadata keys:
```shell-session
$ vault namespace create -custom-metadata=foo=abc -custom-metadata=bar=123 ns1/
```
Patch an existing namespace at the path `ns1/` to add custom metadata key `bar` and remove key `foo`
```shell-session
$ vault namespace patch -custom-metadata=bar=123 -remove-custom-metadata=foo ns1/
```
Delete the namespace at path `ns1/`:
```shell-session
$ vault namespace delete ns1/
```
Lookup the namespace information at path `ns1/`:
```shell-session
$ vault namespace lookup ns1/
```
Lock the API for the current namespace:
```shell-session
$ vault namespace lock
```
Lock the API for a descendant namespace at path `current/namespace/ns1/`:
```shell-session
$ vault namespace lock ns1/
```
Unlock the API for the current namespace:
```shell-session
$ vault namespace unlock -unlock-key <unlock key>
```
Unlock the API for a descendant namespace at path `current/namespacens1/`:
```shell-session
$ vault namespace unlock -unlock-key <unlock key> ns1/
```
## Usage
```text
Usage: vault namespace <subcommand> [options] [args]
This command groups subcommands for interacting with Vault namespaces.
These set of subcommands operate on the context of the namespace that the
current logged in token belongs to.
Subcommands:
create Create a new namespace
delete Delete an existing namespace
list List child namespaces
lookup Look up an existing namespace
lock Lock the API for a namespace
unlock Unlock the API for a namespace
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

228
website/content/cli/commands/operator/diagnose.mdx Normal file
View file

@ -0,0 +1,228 @@
---
layout: docs
page_title: operator diagnose - Command
description: |-
"vault operator diagnose" is a new operator-centric command, focused on providing a clear description
of what is working in Vault, and what is not working. The command focuses on why Vault cannot serve requests,
but will also warn on configurations or statuses that it deems to be unsafe in some way.
---
# operator diagnose
The operator diagnose command should be used primarily when vault is down or
partially inoperational. The command can be used safely regardless of the state
vault is in, but may return meaningless results for some of the test cases if the
vault server is already running.
Note: if you run the diagnose command proactively, either before a server
starts or while a server is operational, please consult the documentation
on the individual checks below to see which checks are returning false error
messages or warnings.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
#### Output layout
The operator diagnose command will output a set of lines in the CLI.
Each line will begin with a prefix in parenthesis. These are:.
- `[ success ]` - Denotes that the check was successful.
- `[ warning ]` - Denotes that the check has passed, but that there may be potential
issues to look into that may relate to the issues vault is experiencing. Diagnose warns
frequently. These warnings are meant to serve as starting points in the debugging process.
- `[ failure ]` - Denotes that the check has failed. Failures are critical issues in the eyes
of the diagnose command.
In addition to these prefixed lines, there may be output lines that are not prefixed, but are
color-coded purple. These are advice lines from Diagnose, and are meant to offer general guidance
on how to go about fixing potential warnings or failures that may arise.
Warn or fail prefixes in nested checks will bubble up to the parent if the prefix superceeds the
parent prefix. Fail superceeds warn, and warn superceeds ok. For example, if the TLS checks under
the Storage check fails, the `[ failure ]` prefix will bubble up to the Storage check.
### Command options
- `-config` `(string; "")` - The path to the vault configuration file used by
the vault server on startup.
### Diagnose checks
The following section details the various checks that Diagnose runs. Check names in documentation
will be separated by slashes to denote that they are nested, when applicable. For example, a check
documented as `A / B` will show up as `B` in the `operator diagnose` output, and will be nested
(indented) under `A`.
#### Vault diagnose
`Vault Diagnose` is the top level check that contains the rest of the checks. It will report the status
of the check
#### Check operating system / check open file limit
`Check Open File Limit` verifies that the open file limit value is set high enough for vault
to run effectively. We recommend setting these limits to at least 1024768.
This check will be skipped on openbsd, arm, and windows.
#### Check operating system / check disk usage
`Check Disk Usage` will report disk usage for each partition. For each partition on a prod host,
we recommend having at least 5% of the partition free to use, and at least 1 GB of space.
This check will be skipped on openbsd and arm.
#### Parse configuration
`Parse Configuration` will check the vault server config file for syntax errors. It will check
for extra values in the configuration file, repeated stanzas, and stanzas that do not belong
in the configuration file (for example a "tcpp" listener as opposed to a tcp listener).
Currently, the `storage` stanza is not checked.
#### Check storage / create storage backend
`Create Storage Backend` ensures that the storage stanza configured in the vault server config
has enough information to create a storage object internally. Common errors will have to do
with misconfigured fields in the storage stanza.
#### Check storage / check consul TLS
`Check Consul TLS` verifies TLS information included in the storage stanza if the storage type
is consul. If a certificate chain is provided, Diagnose parses the root, intermediate, and leaf
certificates, and checks each one for correctness.
#### Check storage / check consul direct storage access
`Check Consul Direct Storage Access` is a consul-specific check that ensures Vault is not accessing
the consul server directly, but rather through a local agent.
#### Check storage / check raft folder permissions
`Check Raft Folder Permissions` computes the permissions on the raft folder, checks that a boltDB file
has been initialized within the folder previously, and ensures that the folder is not too permissive, but
at the same time has enough permissions to be used. The raft folder should not have `other` permissions, but
should have `group rw` or `owner rw`, depending on different setups. This check also warns if it detects a
symlink being used.
Note that this check will warn that a raft file has not been created if diagnose is run without any
pre-existing server runs.
This check will be skipped on windows.
#### Check storage / check raft folder ownership
`Check Raft Folder Ownership` ensures that vault does not need to run as root to access the boltDB folder.
Note that this check will warn that a raft file has not been created if diagnose is run without any
pre-existing server runs.
This check will be skipped on windows.
#### Check storage / check for raft quorum
`Check For Raft Quorum` uses the FSM to ensure that there were an odd number of voters in the raft quorum when
vault was last running.
Note that this check will warn that there are 0 voters if diagnose is run without any pre-existing server runs.
#### Check storage / check storage access
`Check Storage Access` will try to write a dud value, named `diagnose/latency/<uuid>`, to storage.
Ensure that there is no important data at this location before running diagnose, as this check
will overwrite that data. This check will then try to list and read the value it wrote to ensure
the name and value is as expected.
`Check Storage Access` will warn if any operation takes longer than 100ms, and error out if the
entire check takes longer than 30s.
#### Check service discovery / check consul service discovery TLS
`Check Consul Service Discovery TLS` verifies TLS information included in the service discovery
stanza if the storage type is consul. If a certificate chain is provided, Diagnose parses
the root, intermediate, and leaf certificates, and checks each one for correctness.
#### Check service discovery / check consul direct service discovery
`Check Consul Direct Service Discovery` is a consul-specific check that ensures Vault
is not accessing the consul server directly, but rather through a local agent.
#### Create Vault server configuration seals
`Create Vault Server Configuration Seals` creates seals from the vault configuration
stanza and verifies they can be initialized and finalized.
#### Check transit seal TLS
`Check Transit Seal TLS` checks the TLS client certificate, key, and CA certificate
provided in a transit seal stanza (if one exists) for correctness.
#### Create core configuration / initialize randomness for core
`Initialize Randomness for Core` ensures that vault has access to the randReader that
the vault core uses.
#### HA storage
This check and any nested checks will be the same as the `Check Storage` checks.
The only difference is that the checks here will be run on whatever is specified in the
`ha_storage` section of the vault configuration, as opposed to the `storage` section.
#### Determine redirect address
Ensures that one of the `VAULT_API_ADDR`, `VAULT_REDIRECT_ADDR`, or `VAULT_ADVERTISE_ADDR`
environment variables are set, or that the redirect address is specified in the vault
configuration.
#### Check cluster address
Parses the cluster address from the `VAULT_CLUSTER_ADDR` environment variable, or from the
redirect address or cluster address specified in the vault configuration, and checks that
the address is of the form `host:port`.
#### Check core creation
`Check Core Creation` verifies the logical configuration checks that vault does when it
creates a core object. These are runtime checks, meaning any errors thrown by this diagnose
test will also be thrown by the vault server itself when it is run.
#### Check for autoloaded license
`Check For Autoloaded License` is an enterprise diagnose check, which verifies that vault
has access to a valid autoloaded license that will not expire in the next 30 days.
#### Start listeners / check listener TLS
`Check Listener TLS` verifies the server certificate file and key are valid and matching.
It also checks the client CA file, if one is provided, for a valid certificate, and performs
the standard runtime listener checks on the listener configuration stanza, such as verifying
that the minimum and maximum TLS versions are within the bounds of what vault supports.
Like all the other Diagnose TLS checks, it will warn if any of the certificates provided are
set to expire within the next month.
#### Start listeners / create listeners
`Create Listeners` uses the listener configuration to initialize the listeners, erroring with
a server error if anything goes wrong.
#### Check autounseal encryption
`Check Autounseal Encryption` will initialize the barrier using the seal stanza, if the seal
type is not a shamir seal, and use it to encrypt and decrypt a dud value.
#### Check server before runtime
`Check Server Before Runtime` achieves parity with the server run command, running through
the runtime code checks before the server is initialized to ensure that nothing fails.
This check will never fail without another diagnose check failing.

94
website/content/cli/commands/operator/generate-root.mdx Normal file
View file

@ -0,0 +1,94 @@
---
layout: docs
page_title: operator generate-root - Command
description: |-
The "operator generate-root" command generates a new root token by combining a
quorum of share holders.
---
# operator generate-root
The `operator generate-root` command generates a new root token by combining a
quorum of share holders. With the `-dr-token` or `-recovery-token` options,
it can generate a DR operation token or a recovery token in the same way.
One of the following must be provided to start the root token generation:
- A base64-encoded one-time-password (OTP) provided via the `-otp` flag. Use the
`-generate-otp` flag to generate a usable value. The resulting token is XORed
with this value when it is returned. Use the `-decode` flag to output the
final value.
- A file containing a PGP key or a
[keybase](/vault/docs/concepts/pgp-gpg-keybase) username in the `-pgp-key`
flag. The resulting token is encrypted with this public key.
An unseal key may be provided directly on the command line as an argument to the
command. If key is specified as "-", the command will read from stdin. If a TTY
is available, the command will prompt for text.
Please see the [generate root guide](/vault/docs/troubleshoot/generate-root-token)
for step-by-step instructions.
## Examples
Generate an OTP code for the final token:
```shell-session
$ vault operator generate-root -generate-otp
```
Start a root token generation:
```shell-session
$ vault operator generate-root -init
```
Enter an unseal key to progress root token generation:
```shell-session
$ vault operator generate-root
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-cancel` `(bool: false)` - Reset the root token generation progress. This
will discard any submitted unseal keys or configuration.
- `-decode` `(string: "")` - Decode and output the generated root token. This
option requires the `-otp` flag be set to the OTP used during initialization.
If value is "-" then read the encoded token from stdin.
- `-generate-otp` `(bool: false)` - Generate and print a high-entropy
one-time-password (OTP) suitable for use with the "-init" flag.
- `-init` `(bool: false)` - Start a root token generation. This can only be done
if there is not currently one in progress.
- `-nonce` `(string; "")`- Nonce value provided at initialization. The same
nonce value must be provided with each unseal key.
- `-otp` `(string: "")` - OTP code to use with `-decode` or `-init`.
- `-pgp-key` `(keybase or pgp)`- Path to a file on disk containing a binary or
base64-encoded public PGP key. This can also be specified as a Keybase
username using the format `keybase:<username>`. When supplied, the generated
root token will be encrypted and base64-encoded with the given public key.
- `-status` `(bool: false)` - Print the status of the current attempt without
providing an unseal key. The default is false.
- `-dr-token` `(bool: false)` - Generate DR operation token
- `-recovery-token` `(bool: false)` - Generate recovery token

103
website/content/cli/commands/operator/import.mdx Normal file
View file

@ -0,0 +1,103 @@
---
layout: docs
page_title: operator import - Command
description: >-
The "operator import" command imports secrets from external systems
in to Vault.
---
# operator import
@include 'alerts/enterprise-only.mdx'
@include 'alerts/alpha.mdx'
The `operator import` command imports secrets from external systems in to Vault.
Secrets with the same name at the same storage path will be overwritten upon import.
<Note title="Imports can be long-running processes">
You can write import plans that read from as many sources as you want. The
amount of data migrated from each source depends on the filters applied and the
dataset available. Be mindful of the time needed to read from each source,
apply any filters, and store the data in Vault.
</Note>
## Examples
Read the config file `import.hcl` to generate a new import plan:
```shell-session
$ vault operator import -config import.hcl plan
```
Output:
<CodeBlockConfig hideClipboard>
-----------
Import plan
-----------
The following namespaces are missing:
* ns-1/
The following mounts are missing:
* ns-1/mount-1
Secrets to be imported to the destination "my-dest-1":
* secret-1
* secret-2
</CodeBlockConfig>
## Configuration
The `operator import` command uses a dedicated configuration file to specify the source,
destination, and mapping rules. To learn more about these types and secrets importing in
general, refer to the [Secrets Import documentation](/vault/docs/import).
```hcl
source_gcp {
name = "my-gcp-source-1"
credentials = "@/path/to/service-account-key.json"
}
destination_vault {
name = "my-dest-1"
address = "http://127.0.0.1:8200/"
token = "root"
namespace = "ns-1"
mount = "mount-1"
}
mapping_passthrough {
name = "my-map-1"
source = "my-gcp-1"
destination = "my-dest-1"
priority = 1
}
```
## Usage
### Arguments
- `plan` - Executes a read-only operation to let operators preview the secrets to import based on the configuration file.
- `apply` - Executes the import operations to read the specified secrets from the source and write them into Vault.
Apply first executes a plan, then asks the user to approve the results before performing the actual import.
### Flags
The `operator import` command accepts the following flags:
- `-config` `(string: "import.hcl")` - Path to the import configuration HCL file. The default path is `import.hcl`.
- `-auto-approve` `(bool: <false>)` - Automatically responds "yes" to all user-input prompts for the `apply` command.
- `-auto-create` `(bool: <false>)` - Automatically creates any missing namespaces and KVv2 mounts when
running the `apply` command.
- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in
order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. You can also set log-level with the `VAULT_LOG_LEVEL` environment variable.

68
website/content/cli/commands/operator/index.mdx Normal file
View file

@ -0,0 +1,68 @@
---
layout: docs
page_title: operator - Command
description: |-
The "operator" command groups subcommands for operators interacting with
Vault. Most users will not need to interact with these commands.
---
# operator
The `operator` command groups subcommands for operators interacting with Vault.
Most users will not need to interact with these commands.
## Examples
Initialize a new Vault cluster:
```shell-session
$ vault operator init
Unseal Key 1: sP/4C/fwIDjJmHEC2bi/1Pa43uKhsUQMmiB31GRzFc0R
Unseal Key 2: kHkw2xTBelbDFIMEgEC8NVX7NDSAZ+rdgBJ/HuJwxOX+
Unseal Key 3: +1+1ZnkQDfJFHDZPRq0wjFxEuEEHxDDOQxa8JJ/AYWcb
Unseal Key 4: cewseNJTLovmFrgpyY+9Hi5OgJlJgGGCg7PZyiVdPwN0
Unseal Key 5: wyd7rMGWX5fi0k36X4e+C4myt5CoTmJsHJ0rdYT7BQcF
Initial Root Token: 6662bb4a-afd0-4b6b-faad-e237fb564568
# ...
```
Force a Vault to resign leadership in a cluster:
```shell-session
$ vault operator step-down
Success! Stepped down: https://127.0.0.1:8200
```
Rotate Vault's underlying encryption key:
```shell-session
$ vault operator rotate
Success! Rotated key
Key Term 2
Install Time 01 Jan 07 12:30 UTC
```
## Usage
```text
Usage: vault operator <subcommand> [options] [args]
# ...
Subcommands:
generate-root Generates a new root token
import Import secrets from external systems into Vault
init Initializes a server
key-status Provides information about the active encryption key
rekey Generates new unseal keys
rotate Rotates the underlying encryption key
seal Seals the Vault server
step-down Forces Vault to resign active duty
unseal Unseals the Vault server
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

125
website/content/cli/commands/operator/init.mdx Normal file
View file

@ -0,0 +1,125 @@
---
layout: docs
page_title: operator init - Command
description: |-
The "operator init" command initializes a Vault server. Initialization is the
process by which Vault's storage backend is prepared to receive data. Since
Vault servers share the same storage backend in HA mode, you only need to
initialize one Vault to initialize the storage backend.
---
# operator init
The `operator init` command initializes a Vault server. Initialization is the
process by which Vault's storage backend is prepared to receive data. Since
Vault servers share the same storage backend in HA mode, you only need to
initialize one Vault to initialize the storage backend.
This command cannot be run against already-initialized Vault cluster.
During initialization, Vault generates a root key, which is stored in the storage backend alongside all other Vault data. The root key itself is encrypted and requires an _unseal key_ to decrypt it.
The default Vault configuration uses [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the root key into a configured number of shards (referred as key shares, or unseal keys). A certain threshold of shards is required to reconstruct the root key, which is then used to decrypt the Vault's encryption key.
Refer to the [Seal/Unseal](/vault/docs/concepts/seal#seal-unseal) documentation for further details.
## Examples
Start initialization with the default options:
```shell-session
$ vault operator init
```
Initialize, but encrypt the unseal keys with pgp keys:
```shell-session
$ vault operator init \
-key-shares=3 \
-key-threshold=2 \
-pgp-keys="keybase:hashicorp,keybase:jefferai,keybase:sethvargo"
```
Initialize Auto Unseal with a non-default threshold and number of recovery keys, and encrypt the recovery keys with pgp keys:
```shell-session
$ vault operator init \
-recovery-shares=7 \
-recovery-threshold=4 \
-recovery-pgp-keys="keybase:jeff,keybase:chris,keybase:brian,keybase:calvin,keybase:matthew,keybase:vishal,keybase:nick"
```
Encrypt the initial root token using a pgp key:
```shell-session
$ vault operator init -root-token-pgp-key="keybase:hashicorp"
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "")` - Print the output in the given format. Valid formats
are "table", "json", or "yaml". The default is table. This can also be
specified via the `VAULT_FORMAT` environment variable.
### Common options
- `-key-shares` `(int: 5)` - Number of key shares to split the generated master
key into. This is the number of "unseal keys" to generate. This is aliased as
`-n`.
- `-key-threshold` `(int: 3)` - Number of key shares required to reconstruct the
root key. This must be less than or equal to -key-shares. This is aliased as
`-t`.
- `-pgp-keys` `(string: "...")` - Comma-separated list of paths to files on disk
containing public PGP keys OR a comma-separated list of Keybase usernames
using the format `keybase:<username>`. When supplied, the generated unseal
keys will be encrypted and base64-encoded in the order specified in this list.
The number of entries must match -key-shares, unless -stored-shares are used.
- `-root-token-pgp-key` `(string: "")` - Path to a file on disk containing a
binary or base64-encoded public PGP key. This can also be specified as a
Keybase username using the format `keybase:<username>`. When supplied, the
generated root token will be encrypted and base64-encoded with the given
public key.
- `-status` `(bool": false)` - Print the current initialization status. An exit
code of 0 means the Vault is already initialized. An exit code of 1 means an
error occurred. An exit code of 2 means the Vault is not initialized.
### Consul options
- `-consul-auto` `(bool: false)` - Perform automatic service discovery using
Consul in HA mode. When all nodes in a Vault HA cluster are registered with
Consul, enabling this option will trigger automatic service discovery based on
the provided -consul-service value. When Consul is Vault's HA backend, this
functionality is automatically enabled. Ensure the proper Consul environment
variables are set (CONSUL_HTTP_ADDR, etc). When only one Vault server is
discovered, it will be initialized automatically. When more than one Vault
server is discovered, they will each be output for selection. The default is
false.
- `-consul-service` `(string: "vault")` - Name of the service in Consul under
which the Vault servers are registered.
### HSM and KMS options
- `-recovery-pgp-keys` `(string: "...")` - Behaves like `-pgp-keys`, but for the
recovery key shares. This is only available with [Auto Unseal](/vault/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals).
- `-recovery-shares` `(int: 5)` - Number of key shares to split the recovery key
into. This is only available with [Auto Unseal](/vault/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals).
- `-recovery-threshold` `(int: 3)` - Number of key shares required to
reconstruct the recovery key. This is only available with [Auto Unseal](/vault/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals).
- `-stored-shares` `(int: 0)` - Number of unseal keys to store on an HSM. This
must be equal to `-key-shares`.
-> **Recovery keys:** Refer to the
[Seal/Unseal](/vault/docs/concepts/seal#recovery-key) documentation to learn more
about recovery keys.

34
website/content/cli/commands/operator/key-status.mdx Normal file
View file

@ -0,0 +1,34 @@
---
layout: docs
page_title: operator key-status - Command
description: |-
The "operator key-status" provides information about the active encryption
key.
---
# operator key-status
The `operator key-status` provides information about the active encryption key.
Specifically, the current key term and the key installation time.
## Examples
Get the key status:
```shell-session
$ vault operator key-status
Key Term 2
Install Time 01 Jan 17 12:30 UTC
Encryption Count 4494
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

39
website/content/cli/commands/operator/members.mdx Normal file
View file

@ -0,0 +1,39 @@
---
layout: docs
page_title: operator members - Command
description: |-
The "operator members" command provides information about the nodes making up an HA cluster.
---
# operator members
The `operator members` lists the active node and the peers that it's heard from
since it became active.
## Examples
Get the key status:
```shell-session
$ vault operator members
Host Name API Address Cluster Address Active Node Version Upgrade Version Redundancy Zone Last Echo
--------- ----------- --------------- ----------- ------- --------------- --------------- ---------
josh-C02ZT9DYMD6R http://127.0.0.1:8200 https://127.0.0.1:8201 true 1.11.0 1.11.0 a n/a
josh-C02ZT9DYMD6R http://127.0.0.2:8200 https://127.0.0.2:8201 false 1.11.0 1.11.0 a 2022-05-23T15:51:19-07:00
josh-C02ZT9DYMD6R http://127.0.0.3:8200 https://127.0.0.3:8201 false 1.11.0 1.11.0 b 2022-05-23T15:51:19-07:00
josh-C02ZT9DYMD6R http://127.0.0.4:8200 https://127.0.0.4:8201 false 1.11.0 1.11.0 b 2022-05-23T15:51:22-07:00
josh-C02ZT9DYMD6R http://127.0.0.5:8200 https://127.0.0.5:8201 false 1.11.0 1.12.0 a 2022-05-23T15:51:20-07:00
~
```
Note that in the above output, `Upgrade Version` and `Redundancy Zone` are Enterprise-only fields.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

142
website/content/cli/commands/operator/migrate.mdx Normal file
View file

@ -0,0 +1,142 @@
---
layout: docs
page_title: operator migrate - Command
description: >-
The "operator migrate" command copies data between storage backends to
facilitate
migrating Vault between configurations. It operates directly at the storage
level, with no decryption involved.
---
# operator migrate
The `operator migrate` command copies data between storage backends to facilitate
migrating Vault between configurations. It operates directly at the storage
level, with no decryption involved. Keys in the destination storage backend will
be overwritten, and the destination should _not_ be initialized prior to the
migrate operation. The source data is not modified, with the exception of a small lock
key added during migration.
This is intended to be an offline operation to ensure data consistency, and Vault
will not allow starting the server if a migration is in progress.
## Examples
Migrate all keys:
```shell-session
$ vault operator migrate -config migrate.hcl
2018-09-20T14:23:23.656-0700 [INFO ] copied key: data/core/seal-config
2018-09-20T14:23:23.657-0700 [INFO ] copied key: data/core/wrapping/jwtkey
2018-09-20T14:23:23.658-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/archive/metadata
2018-09-20T14:23:23.660-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/metadata/5kKFZ4YnzgNfy9UcWOzxxzOMpqlp61rYuq6laqpLQDnB3RawKpqi7yBTrawj1P
...
```
Migration is done in a consistent, sorted order. If the migration is halted or
exits before completion (e.g. due to a connection error with a storage backend),
it may be resumed from an arbitrary key prefix:
```shell-session
$ vault operator migrate -config migrate.hcl -start "data/logical/fd"
```
## Configuration
The `operator migrate` command uses a dedicated configuration file to specify the source
and destination storage backends. The format of the storage stanzas is identical
to that used to [configure Vault](/vault/docs/configuration/storage),
with the only difference being that two stanzas are required: `storage_source` and `storage_destination`.
```hcl
storage_source "mysql" {
username = "user1234"
password = "secret123!"
database = "vault"
}
storage_destination "consul" {
address = "127.0.0.1:8500"
path = "vault/"
}
```
## Migrating to integrated raft storage
### Example configuration
The below configuration will migrate away from Consul storage to integrated
raft storage. The raft data will be stored on the local filesystem in the
defined `path`. `node_id` can optionally be set to identify this node.
[cluster_addr](/vault/docs/configuration#cluster_addr) must be set to the
cluster hostname of this node. For more configuration options see the [raft
storage configuration documentation](/vault/docs/configuration/storage/raft).
If the original configuration uses "raft" for `ha_storage` a different
`path` needs to be declared for the path in `storage_destination` and the new
configuration for the node post-migration.
```hcl
storage_source "consul" {
address = "127.0.0.1:8500"
path = "vault"
}
storage_destination "raft" {
path = "/path/to/raft/data"
node_id = "raft_node_1"
}
cluster_addr = "http://127.0.0.1:8201"
```
### Run the migration
Vault will need to be offline during the migration process. First, stop Vault.
Then, run the migration on the server you wish to become a the new Vault node.
```shell-session
$ vault operator migrate -config migrate.hcl
2018-09-20T14:23:23.656-0700 [INFO ] copied key: data/core/seal-config
2018-09-20T14:23:23.657-0700 [INFO ] copied key: data/core/wrapping/jwtkey
2018-09-20T14:23:23.658-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/archive/metadata
2018-09-20T14:23:23.660-0700 [INFO ] copied key: data/logical/fd1bed89-ffc4-d631-00dd-0696c9f930c6/31c8e6d9-2a17-d98f-bdf1-aa868afa1291/metadata/5kKFZ4YnzgNfy9UcWOzxxzOMpqlp61rYuq6laqpLQDnB3RawKpqi7yBTrawj1P
...
```
After migration has completed, the data is stored on the local file system. To
use the new storage backend with Vault, update Vault's configuration file as
described in the [raft storage configuration
documentation](/vault/docs/configuration/storage/raft). Then start and unseal the
vault server.
### Join additional nodes
After migration the raft cluster will only have a single node. Additional peers
should be joined to this node.
If the cluster was previously HA-enabled using "raft" as the `ha_storage`, the
nodes will have to re-join to the migrated node before unsealing.
## Usage
The following flags are available for the `operator migrate` command.
- `-config` `(string: <required>)` - Path to the migration configuration file.
- `-start` `(string: "")` - Migration starting key prefix. Only keys at or after this value will be copied.
- `-reset` - Reset the migration lock. A lock file is added during migration to prevent
starting the Vault server or another migration. The `-reset` option can be used to
remove a stale lock file if present.
- `-max-parallel` `int: 10` - Allows the operator to specify the maximum number of lightweight threads (goroutines)
which may be used to migrate data in parallel. This can potentially speed up migration on slower backends at
the cost of more resources (e.g. CPU, memory). Permitted values range from `1` (synchronous) to the maximum value
for an `integer`. If not supplied, a default of `10` parallel goroutines will be used.
~> Note: The maximum number of concurrent requests handled by a storage backend is ultimately governed by the
storage backend configuration setting, which enforces a maximum number of concurrent requests (`max_parallel`).

418
website/content/cli/commands/operator/raft.mdx Normal file
View file

@ -0,0 +1,418 @@
---
layout: docs
page_title: operator raft - Command
description: >-
The "operator raft" command is used to interact with the integrated Raft storage backend.
---
# operator raft
This command groups subcommands for operators to manage the Integrated Storage Raft backend.
```text
Usage: vault operator raft <subcommand> [options] [args]
This command groups subcommands for operators interacting with the Vault
integrated Raft storage backend. Most users will not need to interact with these
commands. Here are a few examples of the Raft operator commands:
Subcommands:
join Joins a node to the Raft cluster
list-peers Returns the Raft peer set
remove-peer Removes a node from the Raft cluster
snapshot Restores and saves snapshots from the Raft cluster
```
## join
This command is used to join a new node as a peer to the Raft cluster. In order
to join, there must be at least one existing member of the cluster. If Shamir
seal is in use, then unseal keys are to be supplied before or after the
join process, depending on whether it's being used exclusively for HA.
If raft is used for `storage`, the node must be joined before unsealing and the
`leader-api-addr` argument must be provided. If raft is used for `ha_storage`,
the node must be first unsealed before joining and the `leader-api-addr` must
_not_ be provided.
```text
Usage: vault operator raft join [options] <leader-api-addr>
Join the current node as a peer to the Raft cluster by providing the address
of the Raft leader node.
$ vault operator raft join "http://127.0.0.2:8200"
```
The `join` command also allows operators to specify cloud auto-join configuration
instead of a static IP address or hostname. When provided, Vault will attempt to
automatically discover and resolve potential leader addresses based on the provided
auto-join configuration.
Vault uses go-discover to support the auto-join functionality. Please see the
go-discover
[README](https://github.com/hashicorp/go-discover/blob/master/README.md) for
details on the format.
By default, Vault will attempt to reach discovered peers using HTTPS and port 8200.
Operators may override these through the `--auto-join-scheme` and `--auto-join-port`
CLI flags respectively.
```text
Usage: vault operator raft join [options] <auto-join-configuration>
Join the current node as a peer to the Raft cluster by providing cloud auto-join
metadata configuration.
$ vault operator raft join "provider=aws region=eu-west-1 ..."
```
### Parameters
The following flags are available for the `operator raft join` command.
- `-leader-ca-cert` `(string: "")` - CA cert to communicate with Raft leader.
- `-leader-client-cert` `(string: "")` - Client cert to authenticate to Raft leader.
- `-leader-client-key` `(string: "")` - Client key to authenticate to Raft leader.
- `-non-voter` `(bool: false) (enterprise)` - This flag is used to make the
server not participate in the Raft quorum, and have it only receive the data
replication stream. This can be used to add read scalability to a cluster in
cases where a high volume of reads to servers are needed. The default is false.
See [`retry_join_as_non_voter`](/vault/docs/configuration/storage/raft#retry_join_as_non_voter)
for the equivalent config option when using `retry_join` stanzas instead.
- `-retry` `(bool: false)` - Continuously retry joining the Raft cluster upon
failures. The default is false.
~> **Note:** Please be aware that the content (not the path to the file) of the certificate or key is expected for these parameters: `-leader-ca-cert`, `-leader-client-cert`, `-leader-client-key`.
## list-peers
This command is used to list the full set of peers in the Raft cluster.
```text
Usage: vault operator raft list-peers
Provides the details of all the peers in the Raft cluster.
$ vault operator raft list-peers
```
### Example output
```json
{
...
"data": {
"config": {
"index": 62,
"servers": [
{
"address": "127.0.0.2:8201",
"leader": true,
"node_id": "node1",
"protocol_version": "3",
"voter": true
},
{
"address": "127.0.0.4:8201",
"leader": false,
"node_id": "node3",
"protocol_version": "3",
"voter": true
}
]
}
}
}
```
Use the output of `list-peers` to ensure that your cluster is in an expected state.
If you've removed a server using `remove-peer`, the server should no longer be
listed in the `list-peers` output. If you've added a server using `add-peer` or
through `retry_join`, check the `list-peers` output to see that it has been added
to the cluster and (if the node has not been added as a non-voter)
it has been promoted to a voter.
## remove-peer
This command is used to remove a node from being a peer to the Raft cluster. In
certain cases where a peer may be left behind in the Raft configuration even
though the server is no longer present and known to the cluster, this command
can be used to remove the failed server so that it is no longer affects the Raft
quorum.
```text
Usage: vault operator raft remove-peer <server_id>
Removes a node from the Raft cluster.
$ vault operator raft remove-peer node1
```
<Note>
Once a node is removed, its Raft data needs to be deleted before it may be joined back into an existing cluster. This requires shutting down the Vault process, deleting the data, then restarting the Vault process on the removed node.
</Note>
## snapshot
This command groups subcommands for operators interacting with the snapshot
functionality of the integrated Raft storage backend. There are 2 subcommands
supported: `save` and `restore`.
```text
Usage: vault operator raft snapshot <subcommand> [options] [args]
This command groups subcommands for operators interacting with the snapshot
functionality of the integrated Raft storage backend.
Subcommands:
restore Installs the provided snapshot, returning the cluster to the state defined in it
save Saves a snapshot of the current state of the Raft cluster into a file
```
### snapshot save
Takes a snapshot of the Vault data. The snapshot can be used to restore Vault to
the point in time when a snapshot was taken.
```text
Usage: vault operator raft snapshot save <snapshot_file>
Saves a snapshot of the current state of the Raft cluster into a file.
$ vault operator raft snapshot save raft.snap
```
~> **Note:** Snapshot is not supported when Raft is used only for `ha_storage`.
### snapshot restore
Restores a snapshot of Vault data taken with `vault operator raft snapshot save`.
```text
Usage: vault operator raft snapshot restore <snapshot_file>
Installs the provided snapshot, returning the cluster to the state defined in it.
$ vault operator raft snapshot restore raft.snap
```
### snapshot inspect
Inspects a snapshot file taken from a Vault Raft cluster and prints a table showing the number of keys and the amount of space used.
```text
Usage: vault operator raft snapshot inspect <snapshot_file>
```
For example:
```shell-session
$ vault operator raft snapshot inspect raft.snap
```
## autopilot
This command groups subcommands for operators interacting with the autopilot
functionality of the integrated Raft storage backend. There are 3 subcommands
supported: `get-config`, `set-config` and `state`.
For a more detailed overview of autopilot features, see the [concepts page](/vault/docs/concepts/integrated-storage/autopilot).
```text
Usage: vault operator raft autopilot <subcommand> [options] [args]
This command groups subcommands for operators interacting with the autopilot
functionality of the integrated Raft storage backend.
Subcommands:
get-config Returns the configuration of the autopilot subsystem under integrated storage
set-config Modify the configuration of the autopilot subsystem under integrated storage
state Displays the state of the raft cluster under integrated storage as seen by autopilot
```
### autopilot state
Displays the state of the raft cluster under integrated storage as seen by
autopilot. It shows whether autopilot thinks the cluster is healthy or not.
State includes a list of all servers by nodeID and IP address.
```text
Usage: vault operator raft autopilot state
Displays the state of the raft cluster under integrated storage as seen by autopilot.
$ vault operator raft autopilot state
```
#### Example output
```text
Healthy: true
Failure Tolerance: 1
Leader: vault_1
Voters:
vault_1
vault_2
vault_3
Servers:
vault_1
Name: vault_1
Address: 127.0.0.1:8201
Status: leader
Node Status: alive
Healthy: true
Last Contact: 0s
Last Term: 3
Last Index: 61
Version: 1.17.3
Node Type: voter
vault_2
Name: vault_2
Address: 127.0.0.1:8203
Status: voter
Node Status: alive
Healthy: true
Last Contact: 564.765375ms
Last Term: 3
Last Index: 61
Version: 1.17.3
Node Type: voter
vault_3
Name: vault_3
Address: 127.0.0.1:8205
Status: voter
Node Status: alive
Healthy: true
Last Contact: 3.814017875s
Last Term: 3
Last Index: 61
Version: 1.17.3
Node Type: voter
```
The "Failure Tolerance" of a cluster is the number of nodes in the cluster that could
fail gradually without causing an outage.
When verifying the health of your cluster, check the following fields of each server:
- Healthy: whether Autopilot considers this node healthy or not
- Status: the voting status of the node. This will be `voter`, `leader`, or [`non-voter`](/vault/docs/concepts/integrated-storage#non-voting-nodes-enterprise-only).
- Last Index: the index of the last applied Raft log. This should be close to the "Last Index" value of the leader.
- Version: the version of Vault running on the server
- Node Type: the type of node. On CE, this will always be `voter`. See below for an explanation of Enterprise node types.
Vault Enterprise will include additional output related to automated upgrades, optimistic failure tolerance, and redundancy zones.
#### Example Vault enterprise output
```text
Redundancy Zones:
a
Servers: vault_1, vault_2, vault_5
Voters: vault_1
Failure Tolerance: 2
b
Servers: vault_3, vault_4
Voters: vault_3
Failure Tolerance: 1
Upgrade Info:
Status: await-new-voters
Target Version: 1.17.5
Target Version Voters:
Target Version Non-Voters: vault_5
Other Version Voters: vault_1, vault_3
Other Version Non-Voters: vault_2, vault_4
Redundancy Zones:
a
Target Version Voters:
Target Version Non-Voters: vault_5
Other Version Voters: vault_1
Other Version Non-Voters: vault_2
b
Target Version Voters:
Target Version Non-Voters:
Other Version Voters: vault_3
Other Version Non-Voters: vault_4
```
"Optimistic Failure Tolerance" describes the number of healthy active and
back-up voting servers that can fail gradually without causing an outage.
@include 'autopilot/node-types.mdx'
### autopilot get-config
Returns the configuration of the autopilot subsystem under integrated storage.
```text
Usage: vault operator raft autopilot get-config
Returns the configuration of the autopilot subsystem under integrated storage.
$ vault operator raft autopilot get-config
```
### autopilot set-config
Modify the configuration of the autopilot subsystem under integrated storage.
```text
Usage: vault operator raft autopilot set-config [options]
Modify the configuration of the autopilot subsystem under integrated storage.
$ vault operator raft autopilot set-config -server-stabilization-time 10s
```
Flags applicable to this command are the following:
- `cleanup-dead-servers` `(bool: false)` - Controls whether to remove dead servers from
the Raft peer list periodically or when a new server joins. This requires that
`min-quorum` is also set.
- `last-contact-threshold` `(string: "10s")` - Limit on the amount of time a server can
go without leader contact before being considered unhealthy.
- `dead-server-last-contact-threshold` `(string: "24h")` - Limit on the amount of time
a server can go without leader contact before being considered failed. This
takes effect only when `cleanup_dead_servers` is set. When adding new nodes
to your cluster, the `dead_server_last_contact_threshold` needs to be larger
than the amount of time that it takes to load a Raft snapshot, otherwise the
newly added nodes will be removed from your cluster before they have finished
loading the snapshot and starting up. If you are using an [HSM](/vault/docs/enterprise/hsm), your
`dead_server_last_contact_threshold` needs to be larger than the response
time of the HSM.
<Warning>
We strongly recommend keeping `dead_server_last_contact_threshold` at a high
duration, such as a day, as it being too low could result in removal of nodes
that aren't actually dead
</Warning>
- `max-trailing-logs` `(int: 1000)` - Amount of entries in the Raft Log that a server
can be behind before being considered unhealthy. If this value is too low,
it can cause the cluster to lose quorum if a follower falls behind. This
value only needs to be increased from the default if you have a very high
write load on Vault and you see that it takes a long time to promote new
servers to becoming voters. This is an unlikely scenario and most users
should not modify this value.
- `min-quorum` `(int)` - The minimum number of servers that should always be
present in a cluster. Autopilot will not prune servers below this number.
**There is no default for this value** and it should be set to the expected
number of voters in your cluster when `cleanup_dead_servers` is set as `true`.
Use the [quorum size guidance](/vault/docs/internals/integrated-storage#quorum-size-and-failure-tolerance)
to determine the proper minimum quorum size for your cluster.
- `server-stabilization-time` `(string: "10s")` - Minimum amount of time a server must be in a healthy state before it
can become a voter. Until that happens, it will be visible as a peer in the cluster, but as a non-voter, meaning it
won't contribute to quorum.
- `disable-upgrade-migration` `(bool: false)` - Controls whether to disable automated
upgrade migrations, an Enterprise-only feature.

161
website/content/cli/commands/operator/rekey.mdx Normal file
View file

@ -0,0 +1,161 @@
---
layout: docs
page_title: operator rekey - Command
description: |-
The "operator rekey" command generates a new set of unseal keys. This can
optionally change the total number of key shares or the required threshold of
those key shares to reconstruct the root key. This operation is zero
downtime, but it requires the Vault is unsealed and a quorum of existing
unseal keys are provided.
---
# operator rekey
The `operator rekey` command generates a new set of unseal keys. This can
optionally change the total number of key shares or the required threshold of
those key shares to reconstruct the root key. This operation is zero downtime,
but it requires the Vault is unsealed and a quorum of existing unseal keys are
provided.
An unseal key may be provided directly on the command line as an argument to the
command. If key is specified as "-", the command will read from stdin. If a TTY
is available, the command will prompt for text.
## Examples
Initialize a rekey:
```shell-session
$ vault operator rekey \
-init \
-key-shares=15 \
-key-threshold=9
```
Initialize a rekey when Auto Unseal is used for the Vault cluster:
```shell-session
$ vault operator rekey \
-target=recovery \
-init \
-key-shares=15 \
-key-threshold=9
```
Initialize a rekey and activate the verification process:
```shell-session
$ vault operator rekey \
-init \
-key-shares=15 \
-key-threshold=9 \
-verify
```
Rekey and encrypt the resulting unseal keys with PGP:
```shell-session
$ vault operator rekey \
-init \
-key-shares=3 \
-key-threshold=2 \
-pgp-keys="keybase:hashicorp,keybase:jefferai,keybase:sethvargo"
```
Rekey an Auto Unseal vault and encrypt the resulting recovery keys with PGP:
```shell-session
$ vault operator rekey \
-target=recovery \
-init \
-pgp-keys=keybase:grahamhashicorp
-key-shares=1
-key-threshold=1
```
Store encrypted PGP keys in Vault's core:
```shell-session
$ vault operator rekey \
-init \
-pgp-keys="..." \
-backup
```
Retrieve backed-up unseal keys:
```shell-session
$ vault operator rekey -backup-retrieve
```
Delete backed-up unseal keys:
```shell-session
$ vault operator rekey -backup-delete
```
Perform the verification of the rekey using the verification nonce:
```shell-session
$ vault operator rekey -verify -nonce="..."
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-cancel` `(bool: false)` - Reset the rekeying progress. This will discard any submitted unseal keys
or configuration. The default is false.
- `-init` `(bool: false)` - Initialize the rekeying operation. This can only be
done if no rekeying operation is in progress. Customize the new number of key
shares and key threshold using the `-key-shares` and `-key-threshold flags`.
- `-key-shares` `(int: 5)` - Number of key shares to split the generated master
key into. This is the number of "unseal keys" to generate. This is aliased as
`-n`
- `-key-threshold` `(int: 3)` - Number of key shares required to reconstruct the
root key. This must be less than or equal to -key-shares. This is aliased as
`-t`.
- `-nonce` `(string: "")` - Nonce value provided at initialization. The same
nonce value must be provided with each unseal key.
- `-pgp-keys` `(string: "...")` - Comma-separated list of paths to files on disk
containing public PGP keys OR a comma-separated list of Keybase usernames
using the format `keybase:<username>`. When supplied, the generated unseal
keys will be encrypted and base64-encoded in the order specified in this list.
- `-status` `(bool: false)` - Print the status of the current attempt without
providing an unseal key. The default is false.
- `-target` `(string: "barrier")` - Target for rekeying. "recovery" only applies
when HSM support is enabled or using [Auto Unseal](/vault/docs/concepts/seal#auto-unseal).
- `-verify` `(bool: false)` - Indicate during the phase `-init` that the
verification process is activated for the rekey. Along with `-nonce` option
it indicates that the nonce given is for the verification process.
### Backup options
- `-backup` `(bool: false)` - Store a backup of the current PGP encrypted unseal
keys in Vault's core. The encrypted values can be recovered in the event of
failure or discarded after success. See the -backup-delete and
\-backup-retrieve options for more information. This option only applies when
the existing unseal keys were PGP encrypted.
- `-backup-delete` `(bool: false)` - Delete any stored backup unseal keys.
- `-backup-retrieve` `(bool: false)` - Retrieve the backed-up unseal keys. This
option is only available if the PGP keys were provided and the backup has not
been deleted.

65
website/content/cli/commands/operator/rotate.mdx Normal file
View file

@ -0,0 +1,65 @@
---
layout: docs
page_title: operator rotate - Command
description: |-
The "operator rotate" rotates the underlying encryption key which is used to
secure data written to the storage backend. This installs a new key in the key
ring. This new key is used to encrypt new data, while older keys in the ring
are used to decrypt older data.
---
# operator rotate
The `operator rotate` command rotates the underlying encryption key, which
secures data written to storage. This installs a new key in the key ring.
This new key encrypts new data, while older keys in the ring decrypt
older data.
This is an online operation and does not cause downtime. This command runs
per-cluster (not per-server), since Vault servers in HA mode share the same
storage.
As of **Vault 1.7**, Vault will automatically rotate the encryption key before
reaching 2<sup>32</sup> encryption operations, in adherence with NIST SP800-32D
guidelines.
## Examples
Rotate Vault's encryption key:
```shell-session
$ vault operator rotate
Key Term 3
Install Time 01 May 17 10:30 UTC
```
View the current automatic rotation policy:
```shell-session
$ vault read sys/rotate/config
```
Configure a time interval for automatic key rotation:
```shell-session
$ vault write sys/rotate/config interval=2160h
Success! Data written to: sys/rotate/config
```
Configure the maximum number of encryption operations per key:
```shell-session
$ vault write sys/rotate/config max_operations=123456789
Success! Data written to: sys/rotate/config
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

42
website/content/cli/commands/operator/seal.mdx Normal file
View file

@ -0,0 +1,42 @@
---
layout: docs
page_title: operator seal - Command
description: >-
The "operator seal" command seals the Vault server. Sealing tells the Vault
server to
stop responding to any operations until it is unsealed. When sealed, the Vault
server discards its in-memory root key to unlock the data, so it is
physically blocked from responding to operations unsealed.
---
# operator seal
The `operator seal` seals the Vault server. Sealing tells the Vault server to
stop responding to any operations until it is unsealed. When sealed, the Vault
server discards its in-memory root key to unlock the data, so it is physically
blocked from responding to operations unsealed.
If an unseal is in progress, sealing the Vault will reset the unsealing process.
Users will have to re-enter their portions of the root key again.
This command does nothing if the Vault server is already sealed.
For more information on sealing and unsealing, please the [seal concepts
page](/vault/docs/concepts/seal).
## Examples
Seal a Vault server:
```shell-session
$ vault operator seal
Success! Vault is sealed.
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

44
website/content/cli/commands/operator/step-down.mdx Normal file
View file

@ -0,0 +1,44 @@
---
layout: docs
page_title: operator step-down - Command
description: |-
The "operator step-down" forces the Vault server at the given address to step
down from active duty.
---
# operator step-down
The `operator step-down` forces the active Vault node within an [HA cluster](/vault/docs/concepts/ha)
to step down from active duty. When executed against a non-active node, i.e. a
standby or [performance standby](/vault/docs/enterprise/performance-standby) node,
the request will be forwarded to the active node. While the
affected node will have a delay before attempting to acquire
the leader lock again, if no other Vault nodes acquire the
lock beforehand, it is possible for the same node to re-acquire
the lock and become active again. Due to the locking architecture, there may be a period of time
before another node grabs the lock and finishes transitioning to active operation where the cluster has no active node. During the period where none of the nodes are active, forwarding of requests to the leader node will fail.
## Examples
Force a Vault server to step down as the leader:
```shell-session
$ vault operator step-down
Success! Stepped down: http://127.0.0.1:8200
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
## Policy requirements
You must belong to a policy with `update` and `sudo` permissions to use the
`vault operator step-down` command:
```hcl
path "sys/step-down" {
capabilities = ["update", "sudo"]
}
```

62
website/content/cli/commands/operator/unseal.mdx Normal file
View file

@ -0,0 +1,62 @@
---
layout: docs
page_title: operator unseal - Command
description: |-
The "operator unseal" allows the user to provide a portion of the root key
to unseal a Vault server.
---
# operator unseal
The `operator unseal` allows the user to provide a portion of the root key to
unseal a Vault server. Vault starts in a sealed state. It cannot perform
operations until it is unsealed. This command accepts a portion of the master
key (an "unseal key").
The unseal key can be supplied as an argument to the command, but this is
not recommended as the unseal key will be available in your history:
```shell-session
$ vault operator unseal IXyR0OJnSFobekZMMCKCoVEpT7wI6l+USMzE3IcyDyo=
```
Instead, run the command with no arguments and it will prompt for the key:
```shell-session
$ vault operator unseal
Key (will be hidden): IXyR0OJnSFobekZMMCKCoVEpT7wI6l+USMzE3IcyDyo=
```
For more information on sealing and unsealing, please the [seal concepts
page](/vault/docs/concepts/seal).
## Examples
Provide an unseal key:
```shell-session
$ vault operator unseal
Key (will be hidden):
Sealed: false
Key Shares: 1
Key Threshold: 1
Unseal Progress: 0
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-migrate` `(bool: false)` - Indicate that this share is provided with the intent that it is part of a seal migration process.
- `-reset` `(bool: false)` - Discard any previously entered keys to the unseal
process.

75
website/content/cli/commands/operator/usage.mdx Normal file
View file

@ -0,0 +1,75 @@
---
layout: docs
page_title: operator usage - Command
description: |-
"operator usage" produces a report on active clients.
---
# operator usage
The `operator usage` command allows an administrator to retrieve a
[client count](/vault/docs/concepts/client-count) report
for the default reporting period, or for a specific time range of months.
The command output will list clients by distinct entities, non-entity tokens, ACME clients,
secret sync clients, and total active clients for each namespace, and the total
for the entire cluster. It may indicate that no data is available for the
requested time range, which may be because the client count reporting is
disabled, the time range is too far in the past, or no data has yet been
collected since the feature was enabled.
> Refer to the [Vault Usage Metrics](/vault/tutorials/monitoring/usage-metrics) tutorial to learn more about usage metrics,
> including required policy and data collection details.
## Examples
Retrieve the client counts for the default reporting period:
```shell-session
$ vault operator usage
Period start: 2019-11-01T00:00:00Z
Period end: 2020-10-31T23:59:59Z
Namespace path Distinct entities Non-Entity tokens Secret syncs ACME clients Active clients
-------------- ----------------- ----------------- ------------ ------------ --------------
[root] 1541 332 40 60 1973
Total 1541 332 40 60 1973
```
Retrieve the client counts for a specific month in the past:
```shell-session
$ vault operator usage -start-time=2020-01 -end-time=2020-01
Period start: 2020-01-01T00:00:00Z
Period end: 2020-01-31T23:59:59Z
Namespace path Distinct entities Non-Entity tokens Secret syncs ACME clients Active clients
-------------- ----------------- ----------------- ------------ ------------ --------------
[root] 934 176 20 30 1160
Total 934 176 20 30 1160
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-start-time` `(date)` - Start month of the report to generate. May be given as YYYY-MM-DD, YYYY-MM-DD,
a full RFC3339 timestamp, or a Unix epoch timestamp. Defaults to the configurable `default_report_months`
prior to `end-time`.
- `-end-time` `(date: previous month)` - End month of the report to generate. Defaults to the end of the
previous calendar month.
The output shows the exact time range being reported, which may not match the input parameters if a full
month is not available, or if the available reports are a subset of the months requested.

83
website/content/cli/commands/operator/utilization.mdx Normal file
View file

@ -0,0 +1,83 @@
---
layout: docs
page_title: operator utilization - Command
description: |-
The "operator utilization" generates license utilization reporting bundles for the Vault Enterprise users.
---
# operator utilization
The `operator utilization` allows the Vault Enterprise users to generate license
utilization reporting bundles. When users have disabled automated license
reporting, use this command to manually generate the report and send it to
HashiCorp.
<Note title="Vault Enterprise">
Refer to the [manual license utilization
reporting](/vault/docs/enterprise/license/manual-reporting) page to learn more
about reporting your Vault Enterprise license utilization.
</Note>
## Examples
Create a license utilization bundle that includes all persisted historical
snapshots and has the default bundle name
(`vault-utilization-<time_stamp>.json`):
```shell-session
$ vault operator utilization
Success! License utilization reporting bundle written to: vault-utilization-2024-02-16T22-23-25Z.json
```
Create a license utilization bundle with a message about the bundle, and output
the file at the specified path, `/utilization/reports/latest.json`.
```shell-session
$ vault operator utilization \
-message="Change Control 654987" \
-output="/utilization/reports/latest.json"
```
**Example output:**
<CodeBlockConfig hideClipboard>
```plaintext
Success! License utilization reporting bundle written to: /utilization/reports/latest.json
```
</CodeBlockConfig>
The message, `Change Control 654987`, is included in the _server log_, but not
in the bundle.
**Example entry in the server log:**
<CodeBlockConfig hideClipboard>
```plaintext
[INFO] reporting: generating license utilization bundle
[INFO] reporting: generating license utilization bundle: message="Change Control 654987"
```
</CodeBlockConfig>
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-message` `(string; "")` - Provide context about the conditions under which
the report was generated and submitted. This message is not included in the
license utilization bundle but will be included in the vault server logs.
- `-output` `(string; "")` - Specifies the output path for the bundle. Defaults
to a time-based generated file name.
- `-today-only` `(bool: false)` - To include only today’s snapshot, no
historical snapshots. If no snapshots were persisted in the last 24 hrs, it
takes a snapshot and exports it to a bundle.

87
website/content/cli/commands/patch.mdx Normal file
View file

@ -0,0 +1,87 @@
---
layout: docs
page_title: patch - Command
description: |-
The "patch" command updates data in Vault at the given path. The data can be
credentials, secrets, configuration, or arbitrary data. The specific behavior
of this command is determined at the thing mounted at the path.
---
# patch
The `patch` command updates data in Vault at the given path (wrapper command for
HTTP PATCH using the [JSON Patch format](https://datatracker.ietf.org/doc/html/rfc6902)).
The data can be credentials, secrets, configuration, or arbitrary data. The specific
behavior of the `patch` command is determined at the thing mounted at the path.
Data is specified as "**key=value**" pairs on the command line. If the value begins
with an "**@**", then it is loaded from a file. If the value for a key is "**-**", Vault
will read the value from stdin rather than the command line.
Some API fields require more advanced structures such as maps. These cannot
directly be represented on the command line. However, direct control of the
request parameters can be achieved by using `-` as the only data argument.
This causes `vault patch` to read a JSON blob containing all request parameters
from stdin. This argument will be ignored if used in conjunction with any
"key=value" pairs.
For a full list of examples and paths, please see the documentation that
corresponds to the secrets engines in use.
Unlike [the `write` command](/vault/docs/commands/write), the `patch` command only
modifies data specified on the command line.
## Examples
Updates a PKI role to modify a single parameter:
```shell-session
$ vault patch pki/roles/example allow_localhost=false
```
### API versus CLI
Updates a PKI role to modify the `allow_localhost` parameter:
```shell-session
$ vault patch pki/roles/example allow_localhost=false
```
Equivalent cURL command for this operation:
```shell-session
$ tee request_payload.json -<<EOF
{
"organization": "hashicorp"
}
EOF
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
--request PATCH \
--header 'Content-Type: application/merge-patch+json'
--data @request_payload.json \
$VAULT_ADDR/v1/pki/roles/example
```
The `vault patch` command simplifies the API call.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name, in the format
specified in the `-format` directive. The result will not have a trailing
newline making it ideal for piping to other processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-force` `(bool: false)` - Allow the operation to continue with no key=value
pairs. This allows writing to keys that do not need or expect data. This is
aliased as `-f`.

91
website/content/cli/commands/path-help.mdx Normal file
View file

@ -0,0 +1,91 @@
---
layout: docs
page_title: path-help - Command
description: |-
The "path-help" command retrieves API help for paths. All endpoints in Vault
provide built-in help in markdown format. This includes system paths, secret
engines, and auth methods.
---
# path-help
The `path-help` command retrieves API help for paths. All endpoints in Vault
provide built-in help in markdown format. This includes system paths, secret
engines, and auth methods.
The help system is the easiest way to learn how to use the various systems
in Vault, and also allows you to discover new 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
secrets engines in use. 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 PATH`. For example,
if you enabled the AWS secrets engine, you can use `vault path-help aws` to find
the paths supported by that backend. The paths are shown with regular
expressions, which can make them hard to parse, but they are also extremely
exact.
## Examples
Get help output for the KV secrets engine:
```shell-session
$ vault path-help secret
## DESCRIPTION
The KV backend reads and writes arbitrary secrets to the backend.
The secrets are encrypted/decrypted by Vault: they are never stored
unencrypted in the backend and the backend never has an opportunity to
see the unencrypted value.
Leases can be set on a per-secret basis. These leases will be sent down
when that secret is read, and it is assumed that some outside process will
revoke and/or replace the secret at that path.
## PATHS
The following paths are supported by this backend. To view help for
any of the paths below, use the help command with any route matching
the path pattern. Note that depending on the policy of your auth token,
you may or may not be able to access certain paths.
^.*$
Pass-through secret storage to the storage backend, allowing you to
read/write arbitrary data into secret storage.
```
Once you've found a path you like, you can learn more about it by using `vault path-help <path>` where "path" is a path that matches one of the regular
expressions from the backend help.
```shell-session
$ vault path-help secret/password
Request: password
Matching Route: ^.*$
Pass-through secret storage to the storage backend, allowing you to
read/write arbitrary data into secret storage.
## PARAMETERS
lease (string)
Lease time for this key when read. Ex: 1h
## DESCRIPTION
The pass-through backend reads and writes arbitrary data into secret storage,
encrypting it along the way.
A lease can be specified when writing with the "lease" field. If given, then
when the secret is read, Vault will report a lease with that duration. It
is expected that the consumer of this backend properly writes renewed keys
before the lease is up. In addition, revocation must be handled by the
user of this backend.
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

559
website/content/cli/commands/pki/health-check.mdx Normal file
View file

@ -0,0 +1,559 @@
---
layout: docs
page_title: pki health-check - Command
description: |-
The "pki health-check" command verifies the health of the given PKI secrets
engine mount against an optional configuration.
---
# pki health-check
The `pki health-check` command verifies the health of the given PKI secrets
engine mount against an optional configuration.
This runs with the permissions of the given token, reading various APIs from
the mount and `/sys` against the given Vault server
Mounts need to be specified with any namespaces prefixed in the path, e.g.,
`ns1/pki`.
## Examples
Performs a basic health check against the `pki-root` mount:
```shell-session
$ vault pki health-check pki-root/
```
Configuration can be specified using the `-health-config` flag:
```shell-session
$ vault pki health-check -health-config=mycorp-root.json pki-root/
```
Using the `-list` flag will show the list of health checks and any
known configuration values (with their defaults) that will be run
against this mount:
```shell-session
$ vault pki health-check -list pki-root/
```
## Usage
The following flags are unique to this command:
- `-default-disabled` - When specified, results in all health checks being
disabled by default unless enabled by the configuration file explicitly.
The default is `false`, meaning all default-enabled health checks will run.
- `-health-config` `(string: "")` - Path to JSON configuration file to
modify health check execution and parameters.
- `-list` - When specified, no health checks are run, but all known health
checks are printed. Still requires a positional mount argument. The default
is `false`, meaning no listing is printed and health checks will execute.
- `-return-indicator` `(string: "default")` - Behavior of the return value
(exit code) of this command:
- `permission`, for exiting with a non-zero code when the tool lacks
permissions or has a version mismatch with
the server;
- `critical`, for exiting with a non-zero code when a check returns a
critical status in addition to the above;
- `warning`, for exiting with a non-zero status when a check returns a
warning status in addition to the above;
- `informational`, for exiting with a non-zero status when a check
returns an informational status in addition to the above;
- `default`, for the default behavior based on severity of message
and only returning a zero exit status when all checks have passed
and no execution errors have occurred.
This command respects the `-format` parameter to control the presentation of
output sent to stdout. Fatal errors that prevent health checks from executing
may not follow this formatting.
## Return status and output
This command returns the following exit codes:
- `0` - Everything is good.
- `1` - Usage error (check CLI parameters).
- `2` - Informational message from a health check.
- `3` - Warning message from a health check.
- `4` - Critical message from a health check.
- `5` - A version mismatch between health check and Vault Server occurred,
preventing one or more health checks from being fully run.
- `6` - A permission denied message was returned from Vault Server for
one or more health checks.
Note that an exit code of `5` (due to a version mismatch) is not necessarily
fatal to the health check. For example, the `crl_validity_period` health
check will return an invalid version warning when run against Vault 1.11 as
no Delta CRL exists for this version of Vault, but this will not impact its
ability to check the complete CRL.
Each health check outputs one or results in a list. This list contains a
mapping of keys (`status`, `status_code`, `endpoint`, and `message`) to
values returned by the health check. An endpoint may occur in more than
one health check and is not necessarily guaranteed to exist on the server
(e.g., using wildcards to indicate all matching paths have the same
result). Tabular form elides the status code, as this is meant to be
consumed programatically.
These correspond to the following health check status values:
- status `not_applicable` / status code `0`: exit code `0`.
- status `ok` / status code `1`: exit code `0`
- status `informational` / status code `2`: exit code `2`.
- status `warning` / status code `3`: exit code `3`.
- status `critical` / status code `4`: exit code `4`.
- status `invalid_version` / status code `5`: exit code `5`.
- status `insufficient_permissions` / status code `6`: exit code `6`.
## Health checks
The following health checks are currently implemented. More health checks may
be added in future releases and may default to being enabled.
### CA validity period
**Name**: `ca_validity_period`
**Accessed APIs**:
- `LIST /issuers` (unauthenticated)
- `READ /issuer/:issuer_ref/json` (unauthenticated)
**Config Parameters**:
- `root_expiry_critical` `(duration: 182d)` - for a duration within which the root's lifetime is considered critical
- `intermediate_expiry_critical` `(duration: 30d)` - for a duration within which the intermediate's lifetime is considered critical
- `root_expiry_warning` `(duration: 365d)` - for a duration within which the root's lifetime is considered warning
- `intermediate_expiry_warning` `(duration: 60d)` - for a duration within which the intermediate's lifetime is considered warning
- `root_expiry_informational` `(duration: 730d)` - for a duration within which the root's lifetime is considered informational
- `intermediate_expiry_informational` `(duration: 180d)` - for a duration within which the intermediate's lifetime is considered informational
This health check will check each issuer in the mount for validity status, returning a list. If a CA expires within the next 30 days, the result will be critical. If a root CA expires within the next 12 months or an intermediate CA within the next 2 months, the result will be a warning. If a root CA expires within 24 months or an intermediate CA within 6 months, the result will be informational.
**Remediation steps**:
1. Perform a [CA rotation operation](/vault/docs/secrets/pki/rotation-primitives)
to check for CAs that are about to expire.
1. Migrate from expiring CAs to new CAs.
1. Delete any expired CAs with one of the following options:
- Run [tidy](/vault/api-docs/secret/pki#tidy) manually with `vault write <mount>/tidy tidy_expired_issuers=true`.
- Use the Vault API to call [delete issuer](/vault/api-docs/secret/pki#delete-issuer).
### CRL validity period
**Name**: `crl_validity_period`
**Accessed APIs**:
- `LIST /issuers` (unauthenticated)
- `READ /config/crl` (optional)
- `READ /issuer/:issuer_ref/crl` (unauthenticated)
- `READ /issuer/:issuer_ref/crl/delta` (unauthenticated)
**Config Parameters**:
- `crl_expiry_pct_critical` `(int: 95)` - the percentage of validity period after which a CRL should be considered critically close to expiry
- `delta_crl_expiry_pct_critical` `(int: 95)` - the percentage of validity period after which a Delta CRL should be considered critically close to expiry
This health check checks each issuer's CRL for validity status, returning a list. Unlike CAs, where a date-based duration makes sense due to effort required to successfully rotate, rotating CRLs are much easier, so a percentage based approach makes sense. If the chosen percentage exceeds that of the `grace_period` from the CRL configuration, an informational message will be issued rather than OK.
For informational purposes, it reads the CRL config and suggests enabling auto-rebuild CRLs if not enabled.
**Remediation steps**:
Use `vault write` to enable CRL auto-rebuild:
```shell-session
$ vault write <mount>/config/crl auto_rebuild=true
```
### Hardware-Backed root certificate
**Name**: `hardware_backed_root`
**APIs**:
- `LIST /issuers` (unauthenticated)
- `READ /issuer/:issuer_ref`
- `READ /key/:key_ref`
**Config Parameters**:
- `enabled` `(boolean: false)` - defaults to not being run.
This health check checks issuers for root CAs backed by software keys. While Vault is secure, for production root certificates, we'd recommend the additional integrity of KMS-backed keys. This is an informational check only. When all roots are KMS-backed, we'll return OK; when no issuers are roots, we'll return not applicable.
Read more about hardware-backed keys within [Vault Enterprise Managed Keys](/vault/docs/enterprise/managed-keys)
### Root certificate issued Non-CA leaves
**Name**: `root_issued_leaves`
**APIs**:
- `LIST /issuers` (unauthenticated)
- `READ /issuer/:issuer_ref/pem` (unauthenticated)
- `LIST /certs`
- `READ /certs/:serial` (unauthenticated)
**Config Parameters**:
- `certs_to_fetch` `(int: 100)` - a quantity of leaf certificates to fetch to see if any leaves have been issued by a root directly.
This health check verifies whether a proper CA hierarchy is in use. We do this by fetching `certs_to_fetch` leaf certificates (configurable) and seeing if they are a non-issuer leaf and if they were signed by a root issuer in this mount. If one is found, we'll issue a warning about this, and recommend setting up an intermediate CA.
**Remediation steps**:
1. Restrict the use of `sign`, `sign-verbatim`, `issue`, and ACME APIs against
the root issuer.
1. Create an intermediary issuer in a different mount.
1. Have the root issuer sign the new intermediary issuer.
1. Issue new leaf certificates using the intermediary issuer.
### Role allows implicit localhost issuance
**Name**: `role_allows_localhost`
**APIs**:
- `LIST /roles`
- `READ /roles/:name`
**Config Parameters**: (none)
Checks whether any roles exist that allow implicit localhost based issuance
(`allow_localhost=true`) with a non-empty `allowed_domains` value.
**Remediation steps**:
1. Set `allow_localhost` to `false` for all roles.
1. Update the `allowed_domains` field with an explicit list of allowed
localhost-like domains.
### Role allows Glob-Based wildcard issuance
**Name**: `role_allows_glob_wildcards`
**APIs**:
- `LIST /roles`
- `READ /roles/:name`
**Config Parameters**:
- `allowed_roles` `(list: nil)` - an allow-list of roles to ignore.
Check each role to see whether or not it allows wildcard issuance **and** glob
domains. Wildcards and globs can interact and result in nested wildcards among
other (potentially dangerous) quirks.
**Remediation steps**:
1. Split any role that need both of `allow_glob_domains` and `allow_wildcard_certificates` to be true into two roles.
1. Continue splitting roles until both of the following are true for all roles:
- The role has `allow_glob_domains` **or** `allow_wildcard_certificates`, but
not both.
- Roles with `allow_glob_domains` **and** `allow_wildcard_certificates` are
the only roles required for **all** SANs on the certificate.
1. Add the roles that allow glob domains and wildcards to `allowed_roles` so
Vault ignores them in future checks.
### Role sets `no_store=false` and performance
**Name**: `role_no_store_false`
**APIs**:
- `LIST /roles`
- `READ /roles/:name`
- `LIST /certs`
- `READ /config/crl`
**Config Parameters**:
- `allowed_roles` `(list: nil)` - an allow-list of roles to ignore.
Checks each role to see whether `no_store` is set to `false`.
<Warning>
Vault will provide warnings and performance will suffer if you have a large
number of certificates without temporal CRL auto-rebuilding and set `no_store`
to `true`.
</Warning>
**Remediation steps**:
1. Update none-ACME roles with `no_store=false`. **NOTE**: Roles used for ACME
issuance must have `no_store` set to `true`.
1. Set your certificate lifetimes as short as possible.
1. Use [BYOC revocations](/vault/api-docs/secret/pki#revoke-certificate) to
revoke certificates as needed.
### Accessibility of audit information
**Name**: `audit_visibility`
**APIs**:
- `READ /sys/mounts/:mount/tune`
**Config Parameters**:
- `ignored_parameters` `(list: nil)` - a list of parameters to ignore their HMAC status.
This health check checks whether audit information is accessible to log consumers, validating whether our list of safe and unsafe audit parameters are generally followed. These are informational responses, if any are present.
**Remediation steps**:
Use `vault secrets tune` to set the desired audit parameters:
```shell-session
$ vault secrets tune \
-audit-non-hmac-response-keys=certificate \
-audit-non-hmac-response-keys=issuing_ca \
-audit-non-hmac-response-keys=serial_number \
-audit-non-hmac-response-keys=error \
-audit-non-hmac-response-keys=ca_chain \
-audit-non-hmac-request-keys=certificate \
-audit-non-hmac-request-keys=issuer_ref \
-audit-non-hmac-request-keys=common_name \
-audit-non-hmac-request-keys=alt_names \
-audit-non-hmac-request-keys=other_sans \
-audit-non-hmac-request-keys=ip_sans \
-audit-non-hmac-request-keys=uri_sans \
-audit-non-hmac-request-keys=ttl \
-audit-non-hmac-request-keys=not_after \
-audit-non-hmac-request-keys=serial_number \
-audit-non-hmac-request-keys=key_type \
-audit-non-hmac-request-keys=private_key_format \
-audit-non-hmac-request-keys=managed_key_name \
-audit-non-hmac-request-keys=managed_key_id \
-audit-non-hmac-request-keys=ou \
-audit-non-hmac-request-keys=organization \
-audit-non-hmac-request-keys=country \
-audit-non-hmac-request-keys=locality \
-audit-non-hmac-request-keys=province \
-audit-non-hmac-request-keys=street_address \
-audit-non-hmac-request-keys=postal_code \
-audit-non-hmac-request-keys=permitted_dns_domains \
-audit-non-hmac-request-keys=permitted_email_addresses \
-audit-non-hmac-request-keys=permitted_ip_ranges \
-audit-non-hmac-request-keys=permitted_uri_domains \
-audit-non-hmac-request-keys=excluded_dns_domains \
-audit-non-hmac-request-keys=excluded_email_addresses \
-audit-non-hmac-request-keys=excluded_ip_ranges \
-audit-non-hmac-request-keys=excluded_uri_domains \
-audit-non-hmac-request-keys=policy_identifiers \
-audit-non-hmac-request-keys=ext_key_usage_oids \
-audit-non-hmac-request-keys=csr \
<mount>
```
### ACL policies allow problematic endpoints
**Name**: `policy_allow_endpoints`
**APIs**:
- `LIST /sys/policy`
- `READ /sys/policy/:name`
**Config Parameters**:
- `allowed_policies` `(list: nil)` - a list of policies to allow-list for access to insecure APIs.
This health check checks whether unsafe access to APIs (such as `sign-intermediate`, `sign-verbatim`, and `sign-self-issued`) are allowed. Any findings are a critical result and should be rectified by the administrator or explicitly allowed.
### Allow If-Modified-Since requests
**Name**: `allow_if_modified_since`
**APIs**:
- `READ /sys/internal/ui/mounts`
**Config Parameters**: (none)
This health check verifies if the `If-Modified-Since` header has been added to `passthrough_request_headers` and if `Last-Modified` header has been added to `allowed_response_headers`. This is an informational message if both haven't been configured, or a warning if only one has been configured.
**Remediation steps**:
1. Update `allowed_response_headers` and `passthrough_request_headers` for all
policies with `vault secrets tune`:
```shell-session
$ vault secrets tune \
-passthrough-request-headers="If-Modified-Since" \
-allowed-response-headers="Last-Modified" \
<mount>
```
1. Update ACME-specific headers with `vault secrets tune` (if you are using ACME):
```shell-session
$ vault secrets tune \
-passthrough-request-headers="If-Modified-Since" \
-allowed-response-headers="Last-Modified" \
-allowed-response-headers="Replay-Nonce" \
-allowed-response-headers="Link" \
-allowed-response-headers="Location" \
<mount>
```
### Auto-Tidy disabled
**Name**: `enable_auto_tidy`
**APIs**:
- `READ /config/auto-tidy`
**Config Parameters**:
- `interval_duration_critical` `(duration: 7d)` - the maximum allowed interval_duration to hit critical threshold.
- `interval_duration_warning` `(duration: 2d)` - the maximum allowed interval_duration to hit a warning threshold.
- `pause_duration_critical` `(duration: 1s)` - the maximum allowed pause_duration to hit a critical threshold.
- `pause_duration_warning` `(duration: 200ms)` - the maximum allowed pause_duration to hit a warning threshold.
This health check verifies that auto-tidy is enabled, with sane defaults for interval_duration and pause_duration. Any disabled findings will be informational, as this is a best-practice but not strictly required, but other findings w.r.t. `interval_duration` or `pause_duration` will be critical/warnings.
**Remediation steps**
Use `vault write` to enable auto-tidy with the recommended defaults:
```shell-session
$ vault write <mount>/config/auto-tidy \
enabled=true \
tidy_cert_store=true \
tidy_revoked_certs=true \
tidy_acme=true \
tidy_revocation_queue=true \
tidy_cross_cluster_revoked_certs=true \
tidy_revoked_cert_issuer_associations=true
```
### Tidy hasn't run
**Name**: `tidy_last_run`
**APIs**:
- `READ /tidy-status`
**Config Parameters**:
- `last_run_critical` `(duration: 7d)` - the critical delay threshold between when tidy should have last run.
- `last_run_warning` `(duration: 2d)` - the warning delay threshold between when tidy should have last run.
This health check verifies that tidy has run within the last run window. This can be critical/warning alerts as this can start to seriously impact Vault's performance.
**Remediation steps**:
1. Schedule a manual run of tidy with `vault write`:
```shell-session
$ vault write <mount>/tidy \
tidy_cert_store=true \
tidy_revoked_certs=true \
tidy_acme=true \
tidy_revocation_queue=true \
tidy_cross_cluster_revoked_certs=true \
tidy_revoked_cert_issuer_associations=true
```
1. Review the tidy status endpoint, `vault read <mount>/tidy-status` for
additional information.
1. Re-configure auto-tidy based on the log information and results of your
manual run.
### Too many certificates
**Name**: `too_many_certs`
**APIs**:
- `READ /tidy-status`
- `LIST /certs`
**Config Parameters**:
- `count_critical` `(int: 250000)` - the critical threshold at which there are too many certs.
- `count_warning` `(int: 50000)` - the warning threshold at which there are too many certs.
This health check verifies that this cluster has a reasonable number of certificates. Ideally this would be fetched from tidy's status or a new metric reporting format, but as a fallback when tidy hasn't run, a list operation will be performed instead.
**Remediation steps**:
1. Verify that tidy ran recently with `vault read`:
```shell-session
$ vault read <mount>/tidy-status
````
1. Schedule a manual run of tidy with `vault write`:
```shell-session
$ vault write <mount>/tidy \
tidy_cert_store=true \
tidy_revoked_certs=true \
tidy_acme=true \
tidy_revocation_queue=true \
tidy_cross_cluster_revoked_certs=true \
tidy_revoked_cert_issuer_associations=true
```
1. Enable `auto-tidy`.
1. Make sure that you are not renewing certificates too soon. Certificate
lifetimes should reflect the expected usage of the certificate. If the TTL is
set appropriately, most certificates renew at approximately 2/3 of their
lifespan.
1. Consider setting the `no_store` field for all roles to `true` and use [BYOC revocations](/vault/api-docs/secret/pki#revoke-certificate) to avoid storage.
### Enable ACME issuance
**Name**: `enable_acme_issuance`
**APIs**:
- `READ /config/acme`
- `READ /config/cluster`
- `LIST /issuers` (unauthenticated)
- `READ /issuer/:issuer_ref/json` (unauthenticated)
**Config Parameters**: (none)
This health check verifies that ACME is enabled within a mount that contains an intermediary issuer, as this is considered a best-practice to support a self-rotating PKI infrastructure.
Review the [ACME Certificate Issuance](/vault/api-docs/secret/pki#acme-certificate-issuance)
API documentation to learn about enabling ACME support in Vault.
### ACME response headers
**Name**: `allow_acme_headers`
**APIs**:
- `READ /sys/internal/ui/mounts`
**Config Parameters**: (none)
This health check verifies if the `"Replay-Nonce`, `Link`, and `Location` headers have been added to `allowed_response_headers`, when the ACME feature is enabled. The ACME protocol will not work if these headers are not added to the mount.
**Remediation steps**:
Use `vault secrets tune` to add the missing headers to `allowed_response_headers`:
```shell-session
$ vault secrets tune \
-allowed-response-headers="Last-Modified" \
-allowed-response-headers="Replay-Nonce" \
-allowed-response-headers="Link" \
-allowed-response-headers="Location" \
<mount>
```

94
website/content/cli/commands/pki/index.mdx Normal file
View file

@ -0,0 +1,94 @@
---
layout: docs
page_title: pki - Command
description: |-
The "pki" command groups subcommands for interacting with Vault's PKI
secrets engine.
---
# pki
The `pki` command groups subcommands for interacting with Vault's
[PKI Secrets Engine](/vault/docs/secrets/pki).
## Syntax
Option flags for a given subcommand are provided after the subcommand, but before the arguments.
## Example health check
To [health check](/vault/docs/commands/pki/health-check) a mount, use the
`vault pki health-check <mount>` command:
```
$ vault pki health-check pki
ca_validity_period
------------------
status endpoint message
------ -------- -------
ok /pki/issuer/da41ffb1-cc6d-5a5c-f147-e4d7beeb1b73 Issuer's validity (2032-12-17) is OK
... more output elided ...
```
## Example verify sign
To [verify](/vault/docs/commands/pki/verify-sign) the signature between two
issuer certificates, use the `vault pki verify-sign <parent> <child>` command:
```shell-session
$ vault pki verify-sign pki_root/issuer/root pki_int/issuer/FirstDepartment
issuer:pki_root/issuer/root
issued:pki_int/issuer/FirstDepartment
field value
----- -----
subject_match true
path_match true
trust_match true
key_id_match true
signature_match true
```
## Example list child issuers
To [list intermediate](/vault/docs/commands/pki/list-intermediates) certificates
potentially issued by a certificate inside vault, use the
`vault pki list-intermediates <parent>` command:
```shell-session
$ vault pki list-intermediates /pki_root/issuer/default
intermediate match?
------------ ------
pki_int_2/issuer/d4404ccc-3ad4-83a9-f5df-398637654b3b true
pki_int_2/issuer/db0b0a6c-6641-ac15-363a-4e5261315581 true
pki_root/issuer/9464c4fe-e8a6-d96a-0566-021575e7382c true
pki_int/issuer/2f958ec5-1838-336e-331b-07032379b958 true
pki_int/issuer/b8cc0b41-e0e9-1a92-12c4-6849c9d6f837 true
```
## Example issue
To [issue](/vault/docs/commands/pki/issue) a new issuer certificate, use the
`vault pki issue <parent-certificate-path> <mount>` command:
```shell-session
$ vault pki issue -issuer_name="FirstDepartment" /pki_root/issuer/default /pki_int/ common_name="first-department.example.com"
Key Value
--- -----
ca_chain [-----BEGIN CERTIFICATE-----
MIIDsDCCApigAwIBAgIULEPuHTW7UDtAQg+qcc18osNWgZIwDQYJKoZIhvcNAQEL...
```
## Example reissue
To [reissue](/vault/docs/commands/pki/reissue) an issuer certificate, using the
same fields as an existing issuer template, use the
`vault pki reissue <parent-certificate-path> <template> <mount>` command:
```shell-session
$ vault pki reissue -issuer_name="SecondDepartment" /pki_root/issuer/default /pki_int/issuer/FirstDepartment /pki_int_2/ common_name="second-department.example.com"
Key Value
--- -----
ca_chain [-----BEGIN CERTIFICATE-----
MIID0DCCArigAwIBAgIUdfRe05B5eRXsg3pvsJ/g94eYuWkwDQYJKoZIhvcNAQEL```

72
website/content/cli/commands/pki/issue.mdx Normal file
View file

@ -0,0 +1,72 @@
---
layout: docs
page_title: pki issue - Command
description: |-
The "pki issue" command issues a new intermediate ("issuer") certificate,
using a parent certificate in vault.
---
# pki issue
This command creates a intermediate certificate authority certificate signed by
the `<parent>` in the `<child_mount>`, using the options to determine the fields
on that certificate.
## Usage
Usage: `vault pki issue [flags] <parent> <child_mount> [options]`
- `[flags]` are optional arguments described below
- `<parent>` is the fully qualified path of the Certificate Authority in vault
which will issue the new intermediate certificate.
- `<child_mount>` is the path of the mount in vault where the new issuer is saved.
- `[options]` are the superset of the k=v options passed to generate-intermediate-csr
and sign-intermediate commands. At least one option must be set.
See [below](/vault/docs/commands/pki/issue#options).
### Flags
- `-type` `(string: "internal")` - This determines the type of key use for the
newly created certificate. Valid types are `"existing"` - where we link to
a key already present in the vault-backend to be used (and expect option
arguments `"key_ref"`) - `"internal"` - to generate a new key for this
certificate - or `"kms"` - to link to an external key. Exported keys are not
available through this API.
- `-issuer_name` `(string: "")` - If present, the newly created issuer will be
given this name.
### Options
Other than `type` (which is passed as a flag, see above), this command accepts
all options provided to the
[Generate CSR](/vault/api-docs/secret/pki#generate-intermediate-csr) and
[Sign Intermediate](/vault/api-docs/secret/pki#sign-intermediate) endpoints.
### Accessed APIs
Note that the vault user running this command will need to have access to the
following API endpoints, each representing a step in the process:
- `READ /:parent` - used to check validity
- `WRITE /:child_mount/intermediate/generate/:type` - used to generate the csr
- `WRITE /:parent/sign-intermediate` - used to sign the csr
- `WRITE /:child_mount/issuers/import/cert` - used to import the new issuer,
and the issuer chain
- `UPDATE /:child_mount/issuer/:issuer_refs` - used to both name the new
issuer, and also set the name of the parent in the issuer chain
- `READ /:child_mount/issuer/:new_issuer_ref` - used to verify completion,
generate the output
## Examples
```shell-session
$ vault pki issue -issuer_name="FirstDepartment" /pki_root/issuer/default /pki_int/ common_name="first-department.example.com"
Key Value
--- -----
ca_chain [-----BEGIN CERTIFICATE-----
MIIDsDCCApigAwIBAgIULEPuHTW7UDtAQg+qcc18osNWgZIwDQYJKoZIhvcNAQEL...
```

89
website/content/cli/commands/pki/list-intermediates.mdx Normal file
View file

@ -0,0 +1,89 @@
---
layout: docs
page_title: pki list-intermediates - Command
description: |-
The "pki list-intermediates" command searches a mount, or set of mounts for
child certificates.
---
# pki list-intermediates
This command determines which of a list of certificates were issued by a given
parent certificate.
## Usage
Usage: `vault pki list-intermediates [flags] <parent> [child] [child] [child...`
Lists the set of intermediate CAs issued by this parent issuer.
- `[flags]` listed below determine the type of match required between the `<parent>`
and each potential child, and the type of output
- `<parent>` is the certificate that might be the issuer which everything is
verified against.
- `[child]` is an optional path to a certificate to be compared to the `<parent>`,
or pki mounts to look for certificates on. If `[child]` is omitted entirely, the
list will be constructed from all accessible pki mounts.
This returns a list of issuing certificates and whether they are a match.
By default, the type of match required is whether the `<parent>` has the
expected subject, [authority/subject key id match](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.1), and could have (directly) signed this issuer.
The match criteria can be updated by changed the corresponding flag.
### Flags
- `-use_names` `(bool: "false")` - this determines how issuers are referred to
in the output, whether by issuer_id (the default), or by their name, or status
as default issuer (when use_names is true)
The following flags determine what sorts of relationship between the parent and
potential child issuers are considered a match.
- `-subject_match` `(bool: "true")` - determines whether the subject of the
parent-issuer must match the issuer of the potential child for this to be
considered a match
- `-key_id_match` `(bool: "true")` - determines whether the identifier of the
parent-issuer must match the IUI of the potential child for this to be
considered a match
- `-direct_verify` `(bool: "true")` - determines whether it is required for this
to be a match that someone trusting the parent certificate would trust the
potential-child certificate (without any more information)
- `-indirect-sign` `(bool: "true")` - determines whether it is required for this
to be a match that if someone trusted the first certificate, they would trust
the potential-child certificate (using the certificate chains available)
- `-path_contains` `(bool: "false")` - determines whether it is required for
this to be a match for the ca_chain of the potential child certificate to
contain the parent certificate
### Accessed APIs
Note that the vault user running this command will need to have access to the
following API endpoints, each representing a step in the process:
- `READ /:parent`
- `LIST /sys/mounts` - when no `[child]` argument is provided, this is used to
find a list of pki mounts
- `LIST /:child_mount/issuers/` - when no `[child]` argument is provided, or the
`[child]` argument is a mount rather than an issuer, this is used to find a list
of pki issuers on the mount
- `READ /:child` - each potential child issuer is read for comparison against
the parent
## Examples
```shell-session
$ vault pki list-intermediates /pki_root/issuer/default
intermediate match?
------------ ------
pki_int_2/issuer/d4404ccc-3ad4-83a9-f5df-398637654b3b true
pki_int_2/issuer/db0b0a6c-6641-ac15-363a-4e5261315581 true
pki_root/issuer/9464c4fe-e8a6-d96a-0566-021575e7382c true
pki_int/issuer/2f958ec5-1838-336e-331b-07032379b958 true
pki_int/issuer/b8cc0b41-e0e9-1a92-12c4-6849c9d6f837 true
```

88
website/content/cli/commands/pki/reissue.mdx Normal file
View file

@ -0,0 +1,88 @@
---
layout: docs
page_title: pki reissue - Command
description: |-
The "pki reissue" command issues a new intermediate ("issuer") certificate,
using an existing certificate in vault as a template, and using a parent
certificate in vault to issue the new certificate.
---
# pki reissue
Frequently, a reissued CA certificate is to be very similar to another.
This command enables reissuing a CA, using an existing issuer within
Vault as a template, but allowing modifications to the desired attributes.
## Usage
Usage: `vault pki reissue [flags] <parent> <template> <child_mount> [options]`
- `[flags]` are optional arguments described below.
- `<parent>` is the fully qualified path of the Certificate Authority in vault
which will issue the new intermediate certificate.
- `<template>` is the fully qualified path of an intermediate certificate in vault
which will be used to populate certificate fields not overridden by `[options]`.
~> **Note**: not all possible certificate fields are supported by Vault, and
this template reader covers only those vault generates as a best effort. If
unknown fields are set, such as when an external CA was imported into Vault,
there may not be a warning that those are missing from the new issuer.
- `<child_mount>` is the path of the mount in vault where the new issuer is saved.
- `[options]` are the superset of the k=v options passed to generate/intermediate
and sign-intermediate commands. See [below](/vault/docs/commands/pki/reissue#options).
The output of this command when it is successful is to read the resulting new
issuer entry.
### Flags
- `-type` `(string: "internal")` - This determines the type of key use for the
newly created certificate. Valid types are `"existing"` - where we link to
a key already present in the vault-backend to be used - `"internal"` - to
generate a new key for this certificate - or `"kms"` - to link to an external
key. Exported keys are not available through this API.
~> **Note**: It is only possible to generate a new certificate with an existing
key that exists in the same mount where that key-material exists. This
command is expected to fail should the template exist on a different mount,
`existing` is the selected type, and no `key_ref` for a key in the new issuer
mount is provided.
- `-issuer_name` `(string: "")` - If present, the newly created issuer will be
given this name.
### Options
Other than `type` (which is passed as a flag, see above), this command accepts
all options provided to the
[Generate CSR](/vault/api-docs/secret/pki#generate-intermediate-csr) and
[Sign Intermediate](/vault/api-docs/secret/pki#sign-intermediate) endpoints.
### Accessed APIs
Note that the vault user running this command will need to have access to the
following API endpoints, each representing a step in the process:
- `READ /:parent` - used to check validity
- `READ /:template` - used to generate the options for the new certificate
- `WRITE /:child_mount/intermediate/generate/:type` - used to generate the csr
- `WRITE /:parent/sign-intermediate` - used to sign the csr
- `WRITE /:child_mount/issuers/import/cert` - used to import the new issuer,
and the issuer chain
- `UPDATE /:child_mount/issuer/:issuer_refs` - used to both name the new
issuer, and also set the name of the parent in the issuer chain
- `READ /:child_mount/issuer/:new_issuer_ref` - used to verify completion,
generate the output
## Examples
```shell-session
$ vault pki reissue -issuer_name="SecondDepartment" /pki_root/issuer/default /pki_int/issuer/FirstDepartment /pki_int_2/ common_name="second-department.example.com"
Key Value
--- -----
ca_chain [-----BEGIN CERTIFICATE-----
MIID0DCCArigAwIBAgIUdfRe05B5eRXsg3pvsJ/g94eYuWkwDQYJKoZIhvcNAQEL```

56
website/content/cli/commands/pki/verify-sign.mdx Normal file
View file

@ -0,0 +1,56 @@
---
layout: docs
page_title: pki verify-sign - Command
description: |-
The "pki verify-sign" command verifies the relationship between two issuer
certificates in vault
---
# pki verify-sign
This command verifies whether the listed issuer has signed the listed issued
certificate.
This command returns five fields of information:
- `signature_match`: was the key of the issuer used to sign the issued.
- `path_match`: the possible issuer appears in the valid certificate chain
of the issued.
- `key_id_match`: does the [key id](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.1)
of the issuer match the key_id of the subject.
- `subject_match`: does the subject name of the issuer match the issuer
subject of the issued.
- `trust_match`: if someone trusted the parent issuer, is the chain
provided sufficient to trust the child issued.
## Usage
Usage: `vault pki verify-sign <parent> <child>`
- `<parent>` is the fully name-spaced path to the issuer certificate which will be
used to verify the `<child>` certificate
- `<child>` is the fully name-spaced path to the potential child-certificate to be
verified
A fully namespaced path looks like, for instance, 'ns1/mount1/issuer/issuerName/json'.
## Example
```shell-session
$ vault pki verify-sign pki_root/issuer/root pki_int/issuer/FirstDepartment
issuer:pki_root/issuer/root
issued:pki_int/issuer/FirstDepartment
field value
----- -----
subject_match true
path_match true
trust_match true
key_id_match true
signature_match true
```

30
website/content/cli/commands/plugin/deregister.mdx Normal file
View file

@ -0,0 +1,30 @@
---
layout: docs
page_title: plugin deregister - Command
description: |-
The "plugin deregister" command deregisters a new plugin in Vault's plugin
catalog.
---
# plugin deregister
The `plugin deregister` command deregisters an existing plugin from Vault's
plugin catalog. If the plugin does not exist, no error is returned. The plugin's
type of "auth", "database", or "secret" must be included.
## Examples
Deregister a plugin:
```shell-session
$ vault plugin deregister auth my-custom-plugin
Success! Deregistered plugin (if it was registered): my-custom-plugin
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-version` `(string: "")` - Semantic version of the plugin to deregister.
If unset, only an unversioned plugin may be deregistered.

71
website/content/cli/commands/plugin/index.mdx Normal file
View file

@ -0,0 +1,71 @@
---
layout: docs
page_title: plugin - Command
description: |-
The "plugin" command groups subcommands for interacting with
Vault's plugins and the plugin catalog.
---
# plugin
The `plugin` command groups subcommands for interacting with Vault's plugins and
the plugin catalog
## Examples
List all available secret plugins in the catalog:
```shell-session
$ vault plugin list secret
Name Version
---- -------
ad v0.14.0+builtin
alicloud v0.13.0+builtin
...
```
Register a new secret plugin to the catalog:
```shell-session
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
secret my-custom-plugin
Success! Registered plugin: my-custom-plugin
```
Get information about a plugin in the catalog:
```shell-session
$ vault plugin info secret my-custom-plugin
Key Value
--- -----
args []
builtin false
command my-custom-plugin
deprecation_status n/a
name my-custom-plugin
oci_image n/a
runtime n/a
sha256 33e72f3d30ff2acdbf3cf3c8fa1c8945b60dab876c4226ab25617a63c9f16cc5
version n/a
```
## Usage
```text
Usage: vault plugin <subcommand> [options] [args]
# ...
Subcommands:
deregister Deregister an existing plugin in the catalog
info Read information about a plugin in the catalog
list Lists available plugins
register Registers a new plugin in the catalog
reload Reload mounted plugin backend
reload-status Get the status of an active or recently completed global plugin reload
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

73
website/content/cli/commands/plugin/info.mdx Normal file
View file

@ -0,0 +1,73 @@
---
layout: docs
page_title: plugin info - Command
description: The "plugin info" command displays information about a plugin in the catalog.
---
# plugin info
The `plugin info` displays information about a plugin in the catalog.
The plugin's type of "auth", "database", or "secret" must be included.
## deprecation_status field
As of 1.12, all builtin plugins will have an associated Deprecation
Status. This status will be reflected in the `deprecation_status` key/value
pair, seen below.
## Examples
Display information about a plugin
```shell-session
$ vault plugin info -version=v1.0.0 auth my-custom-plugin
Key Value
--- -----
args []
builtin false
command my-custom-plugin
deprecation_status n/a
name my-custom-plugin
oci_image n/a
runtime n/a
sha256 04ce575260fa3a2cfc477d13ac327108c50838a03917ec4d6df38ecdc64452d1
version v1.0.0
```
```shell-session
$ vault plugin info database postgresql-database-plugin
Key Value
--- -----
args []
builtin true
command n/a
deprecation_status supported
name postgresql-database-plugin
oci_image n/a
runtime n/a
sha256 n/a
version n/a
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name. Specifying
this option will take precedence over other formatting directives. The result
will not have a trailing newline making it ideal for piping to other
processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-plugin-version` `(string: "")` - Semantic version of the plugin to read from
the catalog. If unspecified, refers to the unversioned plugin registered with
the same name and type, or the built-in plugin, in that order of precedence.

61
website/content/cli/commands/plugin/list.mdx Normal file
View file

@ -0,0 +1,61 @@
---
layout: docs
page_title: plugin list - Command
description: The "plugin list" command lists all available plugins in the plugin catalog.
---
# plugin list
The `plugin list` command lists all available plugins in the plugin catalog.
It can be used alone or with a type such as "auth", "database", or "secret".
## Deprecation status column
As of 1.12, all builtin plugins will have an associated Deprecation
Status. This status will be reflected in the `Deprecation Status` column, seen
below. All non-builtin plugins will show a `Deprecation Status` of "n/a".
## Examples
List all available plugins in the catalog.
```shell-session
$ vault plugin list
Name Type Version
---- ---- -------
alicloud auth v0.13.0+builtin
# ...
$ vault plugin list database
Name Version
---- -------
cassandra-database-plugin v1.13.0+builtin.vault
# ...
```
List detailed plugin information:
```shell-session
$ vault plugin list -detailed
Name Type Version Container Deprecation Status
---- ---- ------- --------- ------------------
alicloud auth v0.12.0+builtin false supported
app-id auth v1.12.0+builtin.vault false pending removal
# ...
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-detailed` `(bool: false)` - Print detailed information such as version and
deprecation status about each plugin.

69
website/content/cli/commands/plugin/register.mdx Normal file
View file

@ -0,0 +1,69 @@
---
layout: docs
page_title: plugin register - Command
description: |-
The "plugin register" command registers a new plugin in Vault's plugin
catalog.
---
# plugin register
The `plugin register` command registers a new plugin in Vault's plugin catalog.
The plugin's type of "auth", "database", or "secret" must be included.
## Examples
Register a plugin:
```shell-session
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
auth my-custom-plugin
Success! Registered plugin: my-custom-plugin
```
Register a plugin with custom args:
```shell-session
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
-args=--with-glibc,--with-curl-bindings \
auth my-custom-plugin
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-sha256` `(string: <required>)` - SHA256 of the plugin binary or the OCI image
provided. This is required for all plugins.
- `-args` `([]string: [])` - Argument to pass to the plugin when starting. This
flag can be specified multiple times to specify multiple args.
- `-command` `(string: "")` - Command to spawn the plugin. This defaults to the
name of the plugin if both `-oci_image` and `-command` are unspecified.
- `-env` `([]string: [])` - Environment variables to set for the plugin when
starting. This flag can be specified multiple times to specify multiple
environment variables.
- `-oci_image` `(string: "")` - OCI image to run. If specified, setting `-command`,
`-args`, and `-env` will update the container's entrypoint, args, and environment
variables (append-only) respectively.
- `-runtime` `(string: "")` - Vault plugin runtime to use if `-oci_image` is
specified.
- `-version` `(string: "")` - Semantic version of the plugin. Used as the tag
when specifying `-oci_image`, but any leading 'v' will automatically be trimmed.

72
website/content/cli/commands/plugin/reload.mdx Normal file
View file

@ -0,0 +1,72 @@
---
layout: docs
page_title: plugin reload - Command
description: |-
The "plugin reload" command reloads mounted plugins.
---
# plugin reload
The `plugin reload` command is used to reload mounted plugin backends. Either
the plugin name (`plugin`) or the desired plugin backend mounts (`mounts`)
must be provided, but not both. In the case that the plugin name is provided,
all mounted paths that use that plugin backend will be reloaded.
If run with a Vault namespace other than the root namespace, only plugins
running in the same namespace will be reloaded.
## Examples
Reload a plugin by type and name:
```shell-session
$ vault plugin reload -type=auth -plugin my-custom-plugin
Success! Reloaded plugin: my-custom-plugin
```
Reload an auth plugin by mount:
```shell-session
$ vault plugin reload \
-mounts auth/my-custom-plugin-1 \
-mounts auth/my-custom-plugin-2
Success! Reloaded mounts: [auth/my-custom-plugin-1/ auth/my-custom-plugin-2/]
```
Reload a secrets plugin by mount:
```shell-session
$ vault plugin reload \
-mounts my-custom-plugin-1 \
-mounts my-custom-plugin-2
Success! Reloaded mounts: [my-custom-plugin-1/ my-custom-plugin-2/]
```
Reload a secrets plugin named "my-custom-plugin" across all nodes and replicated clusters:
```shell-session
$ vault plugin reload \
-type=secret \
-plugin=my-custom-plugin \
-scope=global
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-plugin` `(string: "")` - The name of the plugin to reload, as registered in
the plugin catalog.
- `-type` `(string: "")` - The type of plugin to reload, one of auth, secret, or
database. Mutually exclusive with `-mounts`. If not provided, all plugins
with a matching name will be reloaded.
- `-mounts` `(array: [])` - Array or comma-separated string mount paths of the
plugin backends to reload.
- `-scope` `(string: "")` - The scope of the reload. For local reloads, omit this flag.
For reloads that span multiple Vault clusters, use `global`.

34
website/content/cli/commands/plugin/runtime/deregister.mdx Normal file
View file

@ -0,0 +1,34 @@
---
layout: docs
page_title: plugin runtime deregister - Command
description: |-
The "plugin runtime deregister" command deregisters a plugin runtime in Vault's plugin
runtime catalog.
---
# plugin runtime deregister
Deregister an existing plugin runtime in the catalog with the given name.
Returns an error if a registered plugin references the named plugin runtime or
the named runtime does not exist.
<Note title="Limited type support">
Support for runtime types is currently limited to `container`.
</Note>
## Examples
Deregister a plugin:
```shell-session
$ vault plugin runtime deregister -type=container my-plugin-runtime
Success! Deregistered plugin runtime: my-plugin-runtime
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-type` `(string: <required>)` - Plugin runtime type. Vault currently only supports
`container` runtime type.

83
website/content/cli/commands/plugin/runtime/index.mdx Normal file
View file

@ -0,0 +1,83 @@
---
layout: docs
page_title: plugin runtime - Command
description: |-
The "plugin runtime" command groups subcommands for interacting with
Vault's plugin runtimes, configuring the context within which external
plugins can be run.
---
# plugin runtime
The `plugin runtime` command groups subcommands for interacting with
and configuring the context within which your external plugins run.
<Note title="Limited type support">
Support for runtime types is currently limited to `container`.
</Note>
<Note title="Limited OS support">
Support for the 'container` runtime is currently limited to Linux.
</Note>
If you register a container plugin without referencing a plugin runtime, it will
use [gVisor's](https://gvisor.dev/) OCI runtime `runsc` by default, with no
resource limits. You can use plugin runtimes to configure other OCI-compliant
runtimes such as `runc`. Vault does not come packaged with any supporting
container runtimes, and you must separately install whichever you want to use.
To use a registered plugin runtime, use the `-runtime` option with the
[plugin registration command](/vault/docs/commands/plugin/register).
See [containerized plugins](/vault/docs/plugins/containerized-plugins) for more
details on running external plugins in containers.
## Examples
Register a new plugin runtime to the catalog:
```shell-session
$ vault plugin runtime register -type=container -oci_runtime=runc runc
Success! Registered plugin runtime: runc
```
List all available plugin runtimes in the catalog:
```shell-session
$ vault plugin runtime list
Name Type OCI Runtime Parent Cgroup CPU Nanos Memory Bytes
---- ---- ----------- ------------- --------- ------------
runc container runc n/a 0 0
```
Get information about a plugin runtime in the catalog:
```shell-session
$ vault plugin runtime info -type=container runc
Key Value
--- -----
cgroup_parent n/a
cpu_nanos 0
memory_bytes 0
name runc
oci_runtime runc
type container
```
## Usage
```text
Usage: vault plugin runtime <subcommand> [options] [args]
# ...
Subcommands:
deregister Deregister an existing plugin runtime in the catalog
info Read information about a plugin runtime in the catalog
list Lists available plugin runtimes
register Registers a new plugin runtime in the catalog
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

50
website/content/cli/commands/plugin/runtime/info.mdx Normal file
View file

@ -0,0 +1,50 @@
---
layout: docs
page_title: plugin runtime info - Command
description: The "plugin runtime info" command displays information about a plugin runtime in the catalog.
---
# plugin runtime info
Displays information about a plugin runtime in the catalog with the given name. If
the plugin runtime does not exist, an error is returned.
<Note title="Limited type support">
Support for runtime types is currently limited to `container`.
</Note>
## Examples
Display information about a plugin
```shell-session
$ vault plugin runtime info -type=container runc
Key Value
--- -----
cgroup_parent n/a
cpu_nanos 0
memory_bytes 0
name runc
oci_runtime runc
type container
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print information for the named field without a
trailing newline. The `-field` parameter takes precedence over other
formatting directives.
- `-format` `(string: "table")` - Print the output for the current command in
the given format. Valid formats are `table`, `json`, or `yaml`. Use the
`VAULT_FORMAT` environment variable to set your output preferences globally.
### Command options
- `-type` `(string: "")` - Plugin runtime type. Vault currently only supports
`container` runtime type.

40
website/content/cli/commands/plugin/runtime/list.mdx Normal file
View file

@ -0,0 +1,40 @@
---
layout: docs
page_title: plugin runtime list - Command
description: The "plugin runtime list" command lists all available plugin runtimes in the plugin runtime catalog.
---
# plugin list
List all plugin runtimes currently registered with Vault. Returns all the
available plugin runtimes or an error if the set of registered runtimes is empty.
Vault considers any registered plugin runtime "available", regardless of whether
it is currently in use.
## Examples
List all available plugin runtimes in the catalog.
```shell-session
$ vault plugin runtime list
Name Type OCI Runtime Parent Cgroup CPU Nanos Memory Bytes
---- ---- ----------- ------------- --------- ------------
runc container runc n/a 0 0
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output for the current command in
the given format. Valid formats are `table`, `json`, or `yaml`. Use the
`VAULT_FORMAT` environment variable to set your output preferences globally.
### Command options
- `-type` `(string: "")` - Plugin runtime type. Vault currently only supports
`container` runtime type.

62
website/content/cli/commands/plugin/runtime/register.mdx Normal file
View file

@ -0,0 +1,62 @@
---
layout: docs
page_title: plugin runtime register - Command
description: |-
The "plugin runtime register" command registers a new plugin runtime in Vault's plugin runtime
catalog.
---
# plugin runtime register
Register a new plugin runtime in the plugin runtime catalog of your Vault instance.
<Note title="Limited type support">
Support for runtime types is currently limited to `container`.
</Note>
To use a registered plugin runtime, use the `-runtime` option with the
[plugin registration command](/vault/docs/commands/plugin/register).
## Examples
Register a plugin runtime:
```shell-session
$ vault plugin runtime register -type=container -oci_runtime=runc runc
Success! Registered plugin runtime: runc
```
Register a plugin runtime with resource limits:
```shell-session
vault plugin runtime register \
-type=container \
-cpu_nanos=100000000 \
runsc
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-type` `(string: <required>)` - Plugin runtime type. Vault currently only
supports `container` as a runtime type.
- `-rootless` `(bool: false)` - Whether the container runtime is running as a
non-privileged user. Must be set if plugin container images are also configured
to run as a non-root user.
- `-cgroup_parent` `(string: "")` - Parent cgroup to set for each container.
Use `cgroup_parent` to control the total resource usage for a group of plugins.
- `-cpu_nanos` `(int: 0)` - CPU limit to set per container in billionths of a
CPU core. Defaults to no limit.
- `-memory_bytes` `(int: 0)` - Memory limit to set per container in bytes.
Defaults to no limit.
- `-oci_runtime` `(string: "")` - Open Container Initiative (OCI) compliant
container runtime to use. Default is the gVisor OCI runtime, `runsc`.

30
website/content/cli/commands/policy/delete.mdx Normal file
View file

@ -0,0 +1,30 @@
---
layout: docs
page_title: policy delete - Command
description: |-
The "policy delete" command deletes the policy named NAME in the Vault server.
Once the policy is deleted, all tokens associated with the policy are affected
immediately.
---
# policy delete
The `policy delete` command deletes the policy named NAME in the Vault server.
Once the policy is deleted, all tokens associated with the policy are affected
immediately.
Note that it is not possible to delete the "default" or "root" policies. These
are built-in policies.
## Examples
Delete the policy named "my-policy":
```shell-session
$ vault policy delete my-policy
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

27
website/content/cli/commands/policy/fmt.mdx Normal file
View file

@ -0,0 +1,27 @@
---
layout: docs
page_title: policy fmt - Command
description: |-
The "policy fmt" formats a local policy file to the policy specification. This
command will overwrite the file at the given PATH with the properly-formatted
policy file contents.
---
# policy fmt
The `policy fmt` formats a local policy file to the policy specification. This
command will overwrite the file at the given PATH with the properly-formatted
policy file contents.
## Examples
Format the local file "my-policy.hcl":
```shell-session
$ vault policy fmt my-policy.hcl
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

52
website/content/cli/commands/policy/index.mdx Normal file
View file

@ -0,0 +1,52 @@
---
layout: docs
page_title: policy - Command
description: |-
The "policy" command groups subcommands for interacting with policies. Users
can write, read, and list policies in Vault.
---
# policy
The `policy` command groups subcommands for interacting with policies. Users can
write, read, and list policies in Vault.
For more information, please see the [policy
documentation](/vault/docs/concepts/policies).
## Examples
List all enabled policies:
```shell-session
$ vault policy list
```
Create a policy named "my-policy" from contents on local disk:
```shell-session
$ vault policy write my-policy ./my-policy.hcl
```
Delete the policy named my-policy:
```shell-session
$ vault policy delete my-policy
```
## Usage
```text
Usage: vault policy <subcommand> [options] [args]
# ...
Subcommands:
delete Deletes a policy by name
list Lists the installed policies
read Prints the contents of a policy
write Uploads a named policy from a file
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

33
website/content/cli/commands/policy/list.mdx Normal file
View file

@ -0,0 +1,33 @@
---
layout: docs
page_title: policy list - Command
description: |-
The "policy list" command Lists the names of the policies that are installed
on the Vault server.
---
# policy list
The `policy list` command Lists the names of the policies that are installed on
the Vault server.
## Examples
List the available policies:
```shell-session
$ vault policy list
default
root
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

31
website/content/cli/commands/policy/read.mdx Normal file
View file

@ -0,0 +1,31 @@
---
layout: docs
page_title: policy read - Command
description: |-
The "policy read" command prints the contents and metadata of the Vault policy
named NAME. If the policy does not exist, an error is returned.
---
# policy read
The `policy read` command prints the contents and metadata of the Vault policy
named NAME. If the policy does not exist, an error is returned.
## Examples
Read the policy named "my-policy":
```shell-session
$ vault policy read my-policy
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

36
website/content/cli/commands/policy/write.mdx Normal file
View file

@ -0,0 +1,36 @@
---
layout: docs
page_title: policy write - Command
description: |-
The "policy write" command uploads a policy with name NAME from the contents
of a local file PATH or stdin. If PATH is "-", the policy is read from stdin.
Otherwise, it is loaded from the file at the given path on the local disk.
---
# policy write
The `policy write` command uploads a policy with name NAME from the contents of
a local file PATH or stdin. If PATH is "-", the policy is read from stdin.
Otherwise, it is loaded from the file at the given path on the local disk.
For details on the policy syntax, please see the [policy
documentation](/vault/docs/concepts/policies).
## Examples
Upload a policy named "my-policy" from "/tmp/policy.hcl" on the local disk:
```shell-session
$ vault policy write my-policy /tmp/policy.hcl
```
Upload a policy from stdin:
```shell-session
$ cat my-policy.hcl | vault policy write my-policy -
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.

18
website/content/cli/commands/print.mdx Normal file
View file

@ -0,0 +1,18 @@
---
layout: docs
page_title: version - Command
description: The "print" command prints the Vault token currently in use.
---
# print
The `print` command prints the Vault token currently in use. The only available subcommand is `token`.
## Examples
Print the current token.
```shell-session
$ vault print token
hvs.CAESICaie3Dm0_Hx001QuMabo1IXnyKkx_FuE14MH7zir_bqGh4KHGh2cy5wQnJsZzZ6WG82b29HUlI3eFdEQ0NPQzQ
```

9
website/content/cli/commands/proxy.mdx Normal file
View file

@ -0,0 +1,9 @@
---
layout: docs
page_title: proxy - Command
description: The "proxy" command is used to start Vault Proxy
---
# proxy
Please see the [Vault Proxy documentation page](/vault/docs/agent-and-proxy/proxy).

77
website/content/cli/commands/read.mdx Normal file
View file

@ -0,0 +1,77 @@
---
layout: docs
page_title: read - Command
description: |-
The "read" command reads data from Vault at the given path. This can be used
to read secrets, generate dynamic credentials, get configuration details, and
more.
---
# read
The `read` command reads data from Vault at the given path (wrapper command for
HTTP GET). You can use the command to read secrets, generate dynamic
credentials, get configuration details, and more.
## Examples
Read entity details of a given ID:
```shell-session
$ vault read identity/entity/id/2f09126d-d161-abb8-2241-555886491d97
```
Generate dynamic AWS credentials for a `my-role`:
```shell-session
$ vault read aws/creds/my-role
```
### API versus CLI
Assuming that you have KV version 2 (`kv-v2`) secrets engine enabled at
`secret/`, the following command reads secrets at the `secret/data/customers`
API path:
```shell-session
$ vault read secret/data/customers
```
This is equivalent to:
```shell-session
$ curl --request GET --header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/secret/data/customers
```
Since KV secrets engine is a commonly used feature, Vault CLI provides the
[`kv`](/vault/docs/commands/kv) command. Read secrets from the `secret/data/customers`
path using the `kv` CLI command:
```shell-session
$ vault kv get -mount=secret customers
```
-> **Comparison:** All three commands retrieve the same data, but display the
output in a different format. By default, `vault read` prints output in
key-value format. The `curl` command prints the response in JSON. Since the
`kv` command is designed to handle operations associated with KV secrets
engine, it prints the output in more structured format that is easy to read.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name, in the format
specified in the `-format` directive. The result will not have a trailing
newline making it ideal for piping to other processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", "yaml", or "raw". This can also be specified
via the `VAULT_FORMAT` environment variable.
For a full list of examples and paths, please see the documentation that
corresponds to the secrets engine in use.

49
website/content/cli/commands/secrets/disable.mdx Normal file
View file

@ -0,0 +1,49 @@
---
layout: docs
page_title: secrets disable - Command
description: |-
The "secrets disable" command disables an secrets engine at a given PATH. The
argument corresponds to the enabled PATH of the engine, not the TYPE! All
secrets created by this engine are revoked and its Vault data is removed.
---
# secrets disable
The `secrets disable` command disables an secrets engine at a given PATH. The
argument corresponds to the enabled PATH of the engine, not the TYPE! All
secrets created by this engine are revoked and its Vault data is removed.
When a secrets engine is disabled, **all secrets generated via the secrets
engine are immediately revoked.** Care should be taken when disabling a
secret mount with a large number of secrets, as it can cause a high load on
the system during revocation time.
## Examples
Disable the secrets engine enabled at aws/:
```shell-session
$ vault secrets disable aws/
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
## Force disable
Because `secrets disable` revokes secrets associated with this mount, possible
errors can prevent the secrets engine from being disabled if the revocation
fails.
The best way to resolve this is to figure out the underlying issue and then
disable the secrets engine once the underlying issue is resolved. Often, this
can be as simple as increasing the timeout (in the event of timeout errors).
For recovery situations where the secret was manually removed from the
secrets backing service, one can force a secrets engine disable in Vault by
performing a [prefix force revoke](/vault/docs/commands/lease/revoke) on the mount
prefix, followed by a `secrets disable` when that completes.
If the underlying secrets were not manually cleaned up, this method might result
in dangling credentials. This is meant for extreme circumstances.

120
website/content/cli/commands/secrets/enable.mdx Normal file
View file

@ -0,0 +1,120 @@
---
layout: docs
page_title: secrets enable - Command
description: |-
The "secrets enable" command enables a secrets engine at a given path. If an
secrets engine already exists at the given path, an error is returned. After
the secrets engine is enabled, it usually needs configuration. The
configuration varies by secrets engine.
---
# secrets enable
The `secrets enable` command enables a secrets engine at a given path. If an
secrets engine already exists at the given path, an error is returned. After the
secrets engine is enabled, it usually needs configuration. The configuration
varies by secrets engine.
By default, secrets engines are enabled at the path corresponding to their TYPE,
but users can customize the path using the `-path` option.
Some secrets engines persist data, some act as data pass-through, and some
generate dynamic credentials. The secrets engine will likely require
configuration after it is mounted. For details on the specific configuration
options, please see the [secrets engine
documentation](/vault/docs/secrets).
## Examples
Enable the AWS secrets engine at "aws/":
```shell-session
$ vault secrets enable aws
Success! Enabled the aws secrets engine at: aws/
```
Enable the SSH secrets engine at ssh-prod/:
```shell-session
$ vault secrets enable -path=ssh-prod ssh
```
Enable the database secrets engine with an explicit maximum TTL of 30m:
```shell-session
$ vault secrets enable -max-lease-ttl=30m database
```
Enable a custom plugin (after it is registered in the plugin registry):
```shell-session
$ vault secrets enable -path=my-secrets my-plugin
```
For more information on the specific configuration options and paths, please see
the [secrets engine](/vault/docs/secrets) documentation.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-audit-non-hmac-request-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the request data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
An example of this is provided in the [tune section](/vault/docs/commands/secrets/tune).
- `-audit-non-hmac-response-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the response data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-default-lease-ttl` `(duration: "")` - The default lease TTL for this secrets
engine. If unspecified, this defaults to the Vault server's globally
configured default lease TTL.
- `-description` `(string: "")` - Human-friendly description for the purpose of
this engine.
- `-force-no-cache` `(bool: false)` - Force the secrets engine to disable
caching. If unspecified, this defaults to the Vault server's globally
configured cache settings. This does not affect caching of the underlying
encrypted data storage.
- `-local` `(bool: false)` - Mark the secrets engine as local-only. Local
engines are not replicated or removed by replication.
- `-max-lease-ttl` `(duration: "")` The maximum lease TTL for this secrets
engine. If unspecified, this defaults to the Vault server's globally
configured maximum lease TTL.
- `-path` `(string: "")` Place where the secrets engine will be accessible. This
must be unique cross all secrets engines. This defaults to the "type" of the
secrets engine.
!> **Case-sensitive:** The path where you enable secrets engines is case-sensitive. For
example, the KV secrets engine enabled at `kv/` and `KV/` are treated as two
distinct instances of KV secrets engine.
- `-passthrough-request-headers` `(string: "")` - request header values that will
be sent to the secrets engine. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-allowed-response-headers` `(string: "")` - response header values that the secrets
engine will be allowed to set. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-allowed-managed-keys` `(string: "")` - Managed key name(s) that the mount
in question is allowed to access. Note that multiple keys may be specified
by providing this option multiple times, each time with 1 key.
- `-delegated-auth-accessors` `(string: "")` - An authorized accessor the auth
backend can delegate authentication to. To allow multiple accessors, provide
the `delegated-auth-accessors` multiple times, each time with 1 accessor.
- `-trim-request-trailing-slashes` `(bool: false)` - If true, requests to
this mount with trailing slashes will have those slashes trimmed.
Necessary for some standards based APIs handled by Vault.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. If unspecified, implies the built-in or any matching unversioned plugin
that may have been registered.

79
website/content/cli/commands/secrets/index.mdx Normal file
View file

@ -0,0 +1,79 @@
---
layout: docs
page_title: secrets - Command
description: |-
The "secrets" command groups subcommands for interacting with Vault's secrets
engines.
---
# secrets
The `secrets` command groups subcommands for interacting with Vault's secrets
engines. Each secrets engine behaves differently. Please see the documentation
for more information.
Some secrets engines persist data, some act as data pass-through, and some
generate dynamic credentials. The secrets engine will likely require
configuration after it is mounted. For details on the specific configuration
options, please see the [secrets engine
documentation](/vault/docs/secrets).
## Examples
Enable a secrets engine:
```shell-session
$ vault secrets enable database
Success! Enabled the database secrets engine at: database/
```
List all secrets engines:
```shell-session
$ vault secrets list
Path Type Description
---- ---- -----------
cubbyhole/ cubbyhole per-token private secret storage
database/ database n/a
secret/ kv key/value secret storage
sys/ system system endpoints used for control, policy and debugging
```
Move a secrets engine to a new path:
```shell-session
$ vault secrets move database/ db-prod/
Success! Moved secrets engine database/ to: db-prod/
```
Tune a secrets engine:
```shell-session
$ vault secrets tune -max-lease-ttl=30m db-prod/
Success! Tuned the secrets engine at: db-prod/
```
Disable a secrets engine:
```shell-session
$ vault secrets disable db-prod/
Success! Disabled the secrets engine (if it existed) at: db-prod/
```
## Usage
```text
Usage: vault secrets <subcommand> [options] [args]
# ...
Subcommands:
disable Disable a secrets engine
enable Enable a secrets engine
list List enabled secrets engines
move Move a secrets engine to a new path
tune Tune a secrets engine configuration
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

78
website/content/cli/commands/secrets/list.mdx Normal file
View file

@ -0,0 +1,78 @@
---
layout: docs
page_title: secrets list - Command
description: |-
The "secrets list" command lists the enabled secrets engines on the Vault
server. This command also outputs information about the enabled path including
configured TTLs and human-friendly descriptions. A TTL of "system" indicates
that the system default is in use.
---
# secrets list
The `secrets list` command lists the enabled secrets engines on the Vault server.
This command also outputs information about the enabled path including
configured TTLs and human-friendly descriptions. A TTL of "system" indicates
that the system default is in use.
## Deprecation status column
As of 1.12, all built-in secrets engines will have an associated Deprecation
Status. This status will be reflected in the `Deprecation Status` column, seen
below. All secrets engines which are not provided by built-in plugins will show a
`Deprecation Status` of "n/a".
## Version columns
The `-detailed` view displays some version information for each mount.
The Version field indicates the configured version for the plugin. Empty, or "n/a",
indicates the built-in or any matching unversioned plugin that may have been registered.
Running Version indicates the actual plugin version running, which may differ from
Version if the plugin hasn't been reloaded since the configured version was updated
using the `secrets tune` command. Finally, the Running SHA256 field indicates the
SHA256 sum of the running plugin's binary. This may be different from the SHA256
registered in the catalog if the plugin hasn't been reloaded since the plugin
version was overwritten in the catalog.
## Examples
List all enabled secrets engines:
```shell-session
$ vault secrets list
Path Type Accessor Description
---- ---- -------- -----------
cubbyhole/ cubbyhole cubbyhole_548b4dc5 per-token private secret storage
secret/ kv identity_aa00c06d key/value secret storage
sys/ system system_547412e3 system endpoints used for control, policy and debugging
```
List all enabled secrets engines with detailed output:
```shell-session
$ vault secrets list -detailed
Path Plugin Accessor Default TTL Max TTL Force No Cache Replication Seal Wrap External Entropy Access Options Description UUID Version Running Version Running SHA256 Deprecation Status
---- ------ -------- ----------- ------- -------------- ----------- --------- ----------------------- ------- ----------- ---- ------- --------------- -------------- ------------------
cubbyhole/ cubbyhole cubbyhole_b16d1bc0 n/a n/a false local false false map[] per-token private secret storage 8c64d56b-9d46-d667-1155-a8c1a83a5d01 n/a v1.12.0+builtin.vault n/a n/a
identity/ identity identity_3d67c936 system system false replicated false false map[] identity store 5aa1e59c-33b5-9dec-05d6-c80c9a800557 n/a v1.12.0+builtin.vault n/a n/a
postgresql/ postgresql postgresql_f0a54308 system system false replicated false false map[] n/a 8cdc1d2d-0713-eaa6-17e3-49790a60650b n/a v1.12.0+builtin.vault n/a deprecated
sys/ system system_c86bd362 n/a n/a false replicated true false map[] system endpoints used for control, policy and debugging e3193999-0875-d38d-3458-21d9f2762c80 n/a v1.12.0+builtin.vault n/a n/a
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-detailed` `(bool: false)` - Print detailed information such as configuration
and replication status about each secrets engine.

49
website/content/cli/commands/secrets/move.mdx Normal file
View file

@ -0,0 +1,49 @@
---
layout: docs
page_title: secrets move - Command
description: |-
The "secrets move" command moves an existing secrets engine to a new path. All
leases from the old secrets engine are revoked, but all configurations
associated with the engine are preserved.
---
# secrets move
The `secrets move` command moves an existing secrets engine to a new path. Any
leases from the old secrets engine are revoked, but all configuration associated
with the engine is preserved. The command can be issued for a move within or across
namespaces, using namespace prefixes in the arguments.
The command will trigger a remount operation and uses the returned migration ID to poll the
status of the operation until a terminal state of `success` or `failure` is reached.
**Moving an existing secrets engine will revoke any leases from the old
engine.**
## Examples
Move the existing secrets engine at ns1/secret/ to ns2/kv/:
```shell-session
$ vault secrets move ns1/secret/ ns2/kv/
```
Move the existing secrets in `team-vault` to the `vault-edu/` namespace.
```shell-session
$ vault secrets move team-vault \
vault-edu/team-vault
```
## Usage
There are no flags beyond the [standard set of flags](/vault/docs/commands)
included on all commands.
## Post-move considerations
Each namespace has its own policies, auth methods, secrets engines, tokens,
identity entities and groups. You must consider the following after moving a mount across namespaces:
- Necessary policies exist in the target namespace
- Entities and groups might need updating after an auth mount migration

106
website/content/cli/commands/secrets/tune.mdx Normal file
View file

@ -0,0 +1,106 @@
---
layout: docs
page_title: secrets tune - Command
description: |-
The "secrets tune" command tunes the configuration options for the secrets engine at the given PATH.
---
# secrets tune
The `secrets tune` command tunes the configuration options for the secrets
engine at the given PATH. The argument corresponds to the PATH where the secrets
engine is enabled, not the type.
## Examples
Before tuning the secret mount, view the current configuration of the
mount enabled at "pki/":
```shell-session
$ vault read sys/mounts/pki/tune
Key Value
--- -----
default_lease_ttl 12h
description Example PKI mount
force_no_cache false
max_lease_ttl 24h
```
Tune the default lease, exclude `common_name` and `serial_number` from being HMAC'd in the audit log for the PKI secrets engine:
```shell-session
$ vault secrets tune -default-lease-ttl=18h -audit-non-hmac-request-keys=common_name -audit-non-hmac-response-keys=serial_number pki/
Success! Tuned the secrets engine at: pki/
$ vault read sys/mounts/pki/tune
Key Value
--- -----
audit_non_hmac_request_keys [common_name]
audit_non_hmac_response_keys [serial_number]
default_lease_ttl 18h
description Example PKI mount
force_no_cache false
max_lease_ttl 24h
```
Specify multiple audit non-hmac request keys:
```shell-session
$ vault secrets tune -audit-non-hmac-request-keys=common_name -audit-non-hmac-request-keys=ttl pki/
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-allowed-response-headers` `(string: "")` - response header values that the
secrets engine will be allowed to set. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-audit-non-hmac-request-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the request data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-audit-non-hmac-response-keys` `(string: "")` - Key that will not be HMAC'd
by audit devices in the response data object. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-default-lease-ttl` `(duration: "")` - The default lease TTL for this secrets
engine. If unspecified, this defaults to the Vault server's globally
configured default lease TTL, or a previously configured value for the secrets
engine. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `-description` `(string: "")` - Specifies the description of the mount.
This overrides the current stored value, if any.
- `-listing-visibility` `(string: "")` - The flag to toggle whether to show the
mount in the UI-specific listing endpoint. Valid values are `"unauth"` or `"hidden"`.
Passing empty string leaves the current setting unchanged.
- `-max-lease-ttl` `(duration: "")` - The maximum lease TTL for this secrets
engine. If unspecified, this defaults to the Vault server's globally
configured [maximum lease TTL](/vault/docs/configuration#max_lease_ttl), or a
previously configured value for the secrets engine. This value is allowed to
override the server's global max TTL; it can be longer or shorter.
Uses [duration format strings](/vault/docs/concepts/duration-format).
- `-passthrough-request-headers` `(string: "")` - request header values that will
be sent to the secrets engine. Note that multiple keys may be
specified by providing this option multiple times, each time with 1 key.
- `-allowed-managed-keys` `(string: "")` - Managed key name(s) that the mount
in question is allowed to access. Note that multiple keys may be specified
by providing this option multiple times, each time with 1 key.
- `-delegated-auth-accessors` `(string: "")` - An authorized accessor the auth
backend can delegate authentication to. To allow multiple accessors, provide
the `delegated-auth-accessors` multiple times, each time with 1 accessor.
- `-trim-request-trailing-slashes` `(bool: false)` - If true, requests to
this mount with trailing slashes will have those slashes trimmed.
Necessary for some standards based APIs handled by Vault.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. The new version will not start running until the mount is
[reloaded](/vault/docs/commands/plugin/reload).

134
website/content/cli/commands/server.mdx Normal file
View file

@ -0,0 +1,134 @@
---
layout: docs
page_title: server - Command
description: |-
The "server" command starts a Vault server that responds to API requests. By
default, Vault will start in a "sealed" state. The Vault cluster must be
initialized before use.
---
# server
The `server` command starts a Vault server that responds to API requests. By
default, Vault will start in a "sealed" state. The Vault cluster must be
initialized before use, usually by the `vault operator init` command. Each Vault
server must also be unsealed using the `vault operator unseal` command or the
API before the server can respond to requests.
For more information, please see:
- [`operator init` command](/vault/docs/commands/operator/init) for information
on initializing a Vault server.
- [`operator unseal` command](/vault/docs/commands/operator/unseal) for
information on providing unseal keys.
- [Vault configuration](/vault/docs/configuration) for the syntax and
various configuration options for a Vault server.
## Examples
Start a server with a configuration file:
```shell-session
$ vault server -config=/etc/vault/config.hcl
```
Run in "dev" mode with a custom initial root token:
```shell-session
$ vault server -dev -dev-root-token-id="root"
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Command options
- `-config` `(string: "")` - Path to a configuration file or directory of
configuration files. This flag can be specified multiple times to load
multiple configurations. If the path is a directory, all files which end in
.hcl or .json are loaded.
- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in
order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. This can
also be specified via the `VAULT_LOG_LEVEL` environment variable.
- `-log-format` ((#\_log_format)) `(string: "standard")` - Log format. Supported values
are `standard` and `json`. This can also be specified via the
`VAULT_LOG_FORMAT` environment variable.
- `-log-file` ((#\_log_file)) - The absolute path where Vault should save log
messages in addition to other, existing outputs like journald / stdout. Paths
that end with a path separator use the default file name, `vault.log`. Paths
that do not end with a file extension use the default `.log` extension. If the
log file rotates, Vault appends the current timestamp to the file name
at the time of rotation. For example:
| `log-file` | Full log file | Rotated log file |
|-------------------------|-------------------------|-------------------------------------|
| `/var/log/` | `/var/log/vault.log` | `/var/log/vault-{timestamp}.log` |
| `/var/log/my-diary` | `/var/log/my-diary.log` | `/var/log/my-diary-{timestamp}.log` |
| `/var/log/my-diary.txt` | `/var/log/my-diary.txt` | `/var/log/my-diary-{timestamp}.txt` |
- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of
bytes that should be written to a log before it needs to be rotated. Unless specified,
there is no limit to the number of bytes that can be written to a log file.
- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum
duration a log should be written to before it needs to be rotated. Must be a duration
value such as 30s. Defaults to 24h.
- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum
number of older log file archives to keep. Defaults to 0 (no files are ever deleted).
Set to -1 to discard old log files when a new one is created.
- `-experiment` `(string array: [])` - The name of an experiment to enable for this node.
This flag can be specified multiple times to enable multiple experiments. Experiments
should NOT be used in production, and the associated APIs may have backwards incompatible
changes between releases. Additional experiments can also be specified via the
`VAULT_EXPERIMENTS` environment variable as a comma-separated list, or via the
[`experiments`](/vault/docs/configuration#experiments) config key.
- `-pprof-dump-dir` `(string: "")` - Directory where the generated profiles are
created. Vault does not generate profiles when `pprof-dump-dir` is unset.
Use `pprof-dump-dir` temporarily during debugging sessions. Do not use
`pprof-dump-dir` in regular production processes.
- `VAULT_ALLOW_PENDING_REMOVAL_MOUNTS` `(bool: false)` - (environment variable)
Allow Vault to be started with builtin engines which have the `Pending Removal`
deprecation state. This is a temporary stopgap in place in order to perform an
upgrade and disable these engines. Once these engines are marked `Removed` (in
the next major release of Vault), the environment variable will no longer work
and a downgrade must be performed in order to remove the offending engines. For
more information, refer to the [deprecation notices](/vault/docs/updates/deprecation).
### Dev options
- `-dev` `(bool: false)` - Enable development mode. In this mode, Vault runs
in-memory and starts unsealed. As the name implies, do not run "dev" mode in
production.
- `-dev-tls` `(bool: false)` - Enable TLS development mode. In this mode, Vault runs
in-memory and starts unsealed with a generated TLS CA, certificate and key.
As the name implies, do not run "dev" mode in production.
- `-dev-tls-cert-dir` `(string: "")` - Directory where generated TLS files are created if `-dev-tls` is specified. If left unset, files are generated in a temporary directory.
- `-dev-listen-address` `(string: "127.0.0.1:8200")` - Address to bind to in
"dev" mode. This can also be specified via the `VAULT_DEV_LISTEN_ADDRESS`
environment variable.
- `-dev-root-token-id` `(string: "")` - Initial root token. This only applies
when running in "dev" mode. This can also be specified via the
`VAULT_DEV_ROOT_TOKEN_ID` environment variable.
_Note:_ The token ID should not start with the `s.` prefix.
- `-dev-no-store-token` `(string: "")` - Do not persist the dev root token to
the token helper (usually the local filesystem) for use in future requests.
The token will only be displayed in the command output.
- `-dev-plugin-dir` `(string: "")` - Directory from which plugins are allowed to be loaded. Only applies in "dev" mode, it will automatically register all the plugins in the provided directory.

106
website/content/cli/commands/ssh.mdx Normal file
View file

@ -0,0 +1,106 @@
---
layout: docs
page_title: ssh - Command
description: |-
The "ssh" command establishes an SSH connection with the target machine using
credentials obtained from an SSH secrets engine.
---
# ssh
The `ssh` command establishes an SSH connection with the target machine.
This command uses one of the SSH secrets engines to authenticate and
automatically establish an SSH connection to a host. This operation requires
that the SSH secrets engine is mounted and configured.
The user must have `ssh` installed locally - this command will exec out to it
with the proper commands to provide an "SSH-like" consistent experience.
## Examples
SSH using the OTP mode (requires [sshpass](https://linux.die.net/man/1/sshpass)
for full automation):
```shell-session
$ vault ssh -mode=otp -role=my-role user@1.2.3.4
```
SSH using the CA mode:
```shell-session
$ vault ssh -mode=ca -role=my-role user@1.2.3.4
```
SSH using CA mode with host key verification:
```shell-session
$ vault ssh \
-mode=ca \
-role=my-role \
-host-key-mount-point=host-signer \
-host-key-hostnames=example.com \
user@example.com
```
For step-by-step guides and instructions for each of the available SSH
auth methods, please see the corresponding [SSH secrets
engine](/vault/docs/secrets/ssh).
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name, in the format
specified in the `-format` directive. The result will not have a trailing
newline making it ideal for piping to other processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### SSH options
- `-mode` `(string: "")` - Name of the authentication mode (ca, dynamic, otp)."
- `-mount-point` `(string: "ssh/")` - Mount point to the SSH secrets engine.
- `-no-exec` `(bool: false)` - Print the generated credentials, but do not
establish a connection.
- `-role` `(string: "")` - Name of the role to use to generate the key.
- `-strict-host-key-checking` `(string: "")` - Value to use for the SSH
configuration option "StrictHostKeyChecking". The default is ask. This can
also be specified via the `VAULT_SSH_STRICT_HOST_KEY_CHECKING` environment
variable.
- `-user-known-hosts-file` `(string: "~/.ssh/known_hosts")` - Value to use for
the SSH configuration option "UserKnownHostsFile". This can also be specified
via the `VAULT_SSH_USER_KNOWN_HOSTS_FILE` environment variable.
### CA mode options
- `-host-key-hostnames` `(string: "*")` - List of hostnames to delegate for the
CA. The default value allows all domains and IPs. This is specified as a
comma-separated list of values. This can also be specified via the
`VAULT_SSH_HOST_KEY_HOSTNAMES` environment variable.
- `-host-key-mount-point` `(string: "")` - Mount point to the SSH
secrets engine where host keys are signed. When given a value, Vault will
generate a custom "known_hosts" file with delegation to the CA at the provided
mount point to verify the SSH connection's host keys against the provided CA.
By default, host keys are validated against the user's local "known_hosts"
file. This flag forces strict key host checking and ignores a custom user
known hosts file. This can also be specified via the
`VAULT_SSH_HOST_KEY_MOUNT_POINT` environment variable.
- `-private-key-path` `(string: "~/.ssh/id_rsa")` - Path to the SSH private key
to use for authentication. This must be the corresponding private key to
`-public-key-path`.
- `-public-key-path` `(string: "~/.ssh/id_rsa.pub")` - Path to the SSH public
key to send to Vault for signing.

70
website/content/cli/commands/status.mdx Normal file
View file

@ -0,0 +1,70 @@
---
layout: docs
page_title: status - Command
description: |-
The "status" command prints the current state of Vault including whether it is
sealed and if HA mode is enabled. This command prints regardless of whether
the Vault is sealed.
---
# status
The `status` command prints the current state of Vault including whether it is
sealed and if HA mode is enabled. This command prints regardless of whether the
Vault is sealed.
The exit code reflects the seal status:
- 0 - unsealed
- 1 - error
- 2 - sealed
## Examples
Check the status:
```shell-session
$ vault status
Sealed: false
Key Shares: 5
Key Threshold: 3
Unseal Progress: 0
Unseal Nonce:
Version: x.y.z
Build Date: 2022-05-03T08:34:11Z
Cluster Name: vault-cluster-49ffd45f
Cluster ID: d2dad792-fb99-1c8d-452e-528d073ba205
High-Availability Enabled: false
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
By default, the output is displayed in "table" format.
#### Output fields
1. The field for total shares is displayed as `"n"` instead of `n` in yaml outputs.
2. The following fields in "table" format are displayed only when relevant:
- "Unseal Progress" and "Unseal Nonce" are displayed when vault is sealed.
- "HCP Link Status" and "HCP Link Resource ID" are displayed when HCP link is configured.
- "Seal Migration in Progress" is displayed when it is in progress.
- "Cluster Name" and "Cluster ID" are displayed if they have a value.
- "Raft Committed Index", "Raft Applied Index", "Last WAL" are diplayed if they are non-zero.
- "Warnings" are displayed if the warnings apply.
- The following fields are displayed only when HA mode is enabled and is unsealed:
- "HA Cluster".
- "HA Mode".
- "Active Since" is displayed if the node is active and has a valid active time.
- "Performance Standby" Node and "Performance Standby Last Remote WAL" are displayed for performance standby nodes.
- The "Removed From Cluster" field is only displayed when the storage or HA backend is raft.

50
website/content/cli/commands/token/capabilities.mdx Normal file
View file

@ -0,0 +1,50 @@
---
layout: docs
page_title: token capabilities - Command
description: |-
The "token capabilities" command fetches the capabilities of a token for a
given path.
---
# token capabilities
The `token capabilities` command fetches the capabilities of a token for a given
path.
If you pass a token value as an argument, this command uses the
`/sys/capabilities` endpoint and permission. In the absence of an explicit token
value, this command uses the `/sys/capabilities-self` endpoint and permission
with the locally authenticated token.
## Examples
List capabilities for the local token on the `secret/foo` path:
```shell-session
$ vault token capabilities secret/foo
read
```
The output shows the local token has read permission on the `secret/foo` path.
List capabilities for a token (`hvs.CAESI...WtiSW5mWUY`) on the `cubbyhole/foo`
path:
```shell-session
$ vault token capabilities hvs.CAESI...WtiSW5mWUY database/creds/readonly
deny
```
The output shows the token (`hvs.CAESI...WtiSW5mWUY`) has no permission to
operate on the `cubbyhole/foo` path.
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.

129
website/content/cli/commands/token/create.mdx Normal file
View file

@ -0,0 +1,129 @@
---
layout: docs
page_title: token create - Command
description: |-
The "token create" command creates a new token that can be used for
authentication. This token will be created as a child of the currently
authenticated token. The generated token will inherit all policies and
permissions of the currently authenticated token unless you explicitly define
a subset list policies to assign to the token.
---
# token create
The `token create` command creates a new token that can be used for
authentication. This token will be created as a child of the currently
authenticated token. The generated token will inherit all policies and
permissions of the currently authenticated token unless you explicitly define a
subset list policies to assign to the token.
A ttl can also be associated with the token. If a ttl is not associated with the
token, then it cannot be renewed. If a ttl is associated with the token, it will
expire after that amount of time unless it is renewed.
Metadata associated with the token (specified with `-metadata`) is written to
the audit log when the token is used.
If a role is specified, the role may override parameters specified here.
## Examples
Create a token attached to specific policies:
```shell-session
$ vault token create -policy=my-policy -policy=other-policy
Key Value
--- -----
token 95eba8ed-f6fc-958a-f490-c7fd0eda5e9e
token_accessor 882d4a40-3796-d06e-c4f0-604e8503750b
token_duration 768h
token_renewable true
token_policies [default my-policy other-policy]
```
Create a periodic token:
```shell-session
$ vault token create -period=30m
Key Value
--- -----
token fdb90d58-af87-024f-fdcd-9f95039e353a
token_accessor 4cd9177c-034b-a004-c62d-54bc56c0e9bd
token_duration 30m
token_renewable true
token_policies [my-policy]
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-field` `(string: "")` - Print only the field with the given name. Specifying
this option will take precedence over other formatting directives. The result
will not have a trailing newline making it ideal for piping to other processes.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-display-name` `(string: "")` - Name to associate with this token. This is a
non-sensitive value that can be used to help identify created secrets (e.g.
prefixes).
- `-entity-alias` `(string: "")` - Name of the entity alias to associate with
during token creation. Only works in combination with -role argument and used
entity alias must be listed in allowed_entity_aliases. If this has been
specified, the entity will not be inherited from the parent.
- `-explicit-max-ttl` `(duration: "")` - Explicit maximum lifetime for the
token. Unlike normal TTLs, the maximum TTL is a hard limit and cannot be
exceeded. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `-id` `(string: "")` - Value for the token. By default, this is an
auto-generated value. Specifying this value requires sudo permissions.
- `-metadata` `(k=v: "")` - Arbitrary key=value metadata to associate with the
token. This metadata will show in the audit log when the token is used. This
can be specified multiple times to add multiple pieces of metadata.
- `-no-default-policy` `(bool: false)` - Detach the "default" policy from the
policy set for this token.
- `-orphan` `(bool: false)` - Create the token with no parent. This prevents the
token from being revoked when the token which created it expires. Setting this
value requires sudo permissions.
- `-period` `(duration: "")` - If specified, every renewal will use the given
period. Periodic tokens do not expire as long as they are actively being
renewed (unless `-explicit-max-ttl` is also provided). Setting this value
requires sudo permissions. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `-policy` `(string: "")` - Name of a policy to associate with this token. This
can be specified multiple times to attach multiple policies.
- `-renewable` `(bool: true)` - Allow the token to be renewed up to it's maximum
TTL.
- `-role` `(string: "")` - Name of the role to create the token against.
Specifying -role may override other arguments. The locally authenticated Vault
token must have permission for `auth/token/create/<role>`.
- `-ttl` `(duration: "")` - Initial TTL to associate with the token. Token
renewals may be able to extend beyond this value, depending on the configured
maximumTTLs. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `-type` `(string: "service")` - The type of token to create. Can be "service" or "batch".
- `-use-limit` `(int: 0)` - Number of times this token can be used. After the
last use, the token is automatically revoked. By default, tokens can be used
an unlimited number of times until their expiration.
- `-wrap-ttl` `(duration: "")` - Wraps the response in a cubbyhole token with the
requested TTL. The response is available via the "vault unwrap" command. The TTL
is specified as a numeric string with suffix like "30s" or "5m". This can also be
specified via the `VAULT_WRAP_TTL` environment variable.

53
website/content/cli/commands/token/index.mdx Normal file
View file

@ -0,0 +1,53 @@
---
layout: docs
page_title: token - Command
description: |-
The "token" command groups subcommands for interacting with tokens. Users can
create, lookup, renew, and revoke tokens.
---
# token
The `token` command groups subcommands for interacting with tokens. Users can
create, lookup, renew, and revoke tokens.
For more information on tokens, please see the [token concepts
page](/vault/docs/concepts/tokens).
## Examples
Create a new token:
```shell-session
$ vault token create
```
Revoke a token:
```shell-session
$ vault token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017
```
Renew a token:
```shell-session
$ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017
```
## Usage
```text
Usage: vault token <subcommand> [options] [args]
# ...
Subcommands:
capabilities Print capabilities of a token on a path
create Create a new token
lookup Display information about a token
renew Renew a token lease
revoke Revoke a token and its children
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.

50
website/content/cli/commands/token/lookup.mdx Normal file
View file

@ -0,0 +1,50 @@
---
layout: docs
page_title: token lookup - Command
description: |-
The "token lookup" displays information about a token or accessor. If a TOKEN
is not provided, the locally authenticated token is used.
---
# token lookup
The `token lookup` displays information about a token or accessor. If a TOKEN is
not provided, the locally authenticated token is used.
## Examples
Get information about the locally authenticated token (this uses the
`/auth/token/lookup-self` endpoint and permission):
```shell-session
$ vault token lookup
```
Get information about a particular token (this uses the `/auth/token/lookup`
endpoint and permission):
```shell-session
$ vault token lookup 96ddf4bc-d217-f3ba-f9bd-017055595017
```
Get information about a token via its accessor:
```shell-session
$ vault token lookup -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(default: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-accessor` `(bool: false)` - Treat the argument as an accessor instead of a
token. When this option is selected, the output will NOT include the token.

68
website/content/cli/commands/token/renew.mdx Normal file
View file

@ -0,0 +1,68 @@
---
layout: docs
page_title: token renew - Command
description: |-
The "token renew" renews a token's lease, extending the amount of time it can
be used. If a TOKEN is not provided, the locally authenticated token is used.
Lease renewal will fail if the token is not renewable, the token has already
been revoked, or if the token has already reached its maximum TTL.
---
# token renew
The `token renew` renews a token's lease, extending the amount of time it can be
used. If a TOKEN is not provided, the locally authenticated token is used. Lease
renewal will fail if the token is not renewable, the token has already been
revoked, or if the token has already reached its maximum TTL.
## Examples
Renew a token (this uses the `/auth/token/renew` endpoint and permission):
```shell-session
$ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017
```
Renew the currently authenticated token (this uses the `/auth/token/renew-self`
endpoint and permission):
```shell-session
$ vault token renew
```
Renew a token requesting a specific increment value:
```shell-session
$ vault token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017
```
Fail if the requested TTL increment cannot be fully fulfilled:
```shell-session
$ vault token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017 --fail-if-not-fulfilled || vault login
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
### Output options
- `-format` `(default: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable.
### Command options
- `-increment` `(duration: "")` - Request a specific increment for renewal.
Vault will not honor this request for periodic tokens. If not supplied, Vault will use
the default TTL. This is specified as a numeric string with suffix like "30s"
or "5m". This is aliased as "-i".
- `-accessor` `(bool: false)` - Treat the argument as an accessor instead of a
token. When this option is selected, the output will NOT include the token.
- `--fail-if-not-fulfilled` - Fail if the requested TTL increment cannot be
fully fulfilled. Vault allows command chaining and token renewal request
completion with capped duration even if renew request fails.

52
website/content/cli/commands/token/revoke.mdx Normal file
View file

@ -0,0 +1,52 @@
---
layout: docs
page_title: token revoke - Command
description: |-
The "token revoke" revokes authentication tokens and their children. If a
TOKEN is not provided, the locally authenticated token is used.
---
# token revoke
The `token revoke` revokes authentication tokens and their children. If a TOKEN
is not provided, the locally authenticated token is used. The `-mode` flag can
be used to control the behavior of the revocation.
## Examples
Revoke a token and all the token's children:
```shell-session
$ vault token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017
Success! Revoked token (if it existed)
```
Revoke a token leaving the token's children:
```shell-session
$ vault token revoke -mode=orphan 96ddf4bc-d217-f3ba-f9bd-017055595017
Success! Revoked token (if it existed)
```
Revoke a token by accessor:
```shell-session
$ vault token revoke -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da
Success! Revoked token (if it existed)
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.
- `-accessor` `(bool: false)` - Treat the argument as an accessor instead of a
token.
- `-mode` `(string: "")` - Type of revocation to perform. If unspecified, Vault
will revoke the token and all of the token's children. If "orphan", Vault will
revoke only the token, leaving the children as orphans. If "path", tokens
created from the given authentication path prefix are deleted along with their
children.
- `-self` - Perform the revocation on the currently authenticated token.

Some files were not shown because too many files have changed in this diff Show more