From 485ccbc5daed6d64330dd1eb3004d70ce7d8d5fb Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Tue, 29 Apr 2025 17:08:14 -0700 Subject: [PATCH] [DOCS] IA refresh (phase 2) (#30287) --- website/content/api-docs/auth/aws.mdx | 5 +- .../cli/commands/agent/generate-config.mdx | 115 ++ website/content/cli/commands/agent/index.mdx | 101 ++ .../content/cli/commands/audit/disable.mdx | 76 + website/content/cli/commands/audit/enable.mdx | 186 ++ website/content/cli/commands/audit/list.mdx | 70 + website/content/cli/commands/auth/disable.mdx | 32 + website/content/cli/commands/auth/enable.mdx | 98 + website/content/cli/commands/auth/help.mdx | 43 + website/content/cli/commands/auth/index.mdx | 79 + website/content/cli/commands/auth/list.mdx | 72 + website/content/cli/commands/auth/move.mdx | 48 + website/content/cli/commands/auth/tune.mdx | 189 ++ website/content/cli/commands/debug.mdx | 182 ++ website/content/cli/commands/delete.mdx | 42 + website/content/cli/commands/events.mdx | 102 ++ website/content/cli/commands/hcp/connect.mdx | 60 + .../content/cli/commands/hcp/disconnect.mdx | 23 + website/content/cli/commands/hcp/index.mdx | 27 + website/content/cli/commands/kv/delete.mdx | 48 + website/content/cli/commands/kv/destroy.mdx | 47 + .../cli/commands/kv/enable-versioning.mdx | 33 + website/content/cli/commands/kv/get.mdx | 80 + website/content/cli/commands/kv/index.mdx | 163 ++ website/content/cli/commands/kv/list.mdx | 49 + website/content/cli/commands/kv/metadata.mdx | 163 ++ website/content/cli/commands/kv/patch.mdx | 91 + website/content/cli/commands/kv/put.mdx | 74 + website/content/cli/commands/kv/rollback.mdx | 54 + website/content/cli/commands/kv/undelete.mdx | 48 + website/content/cli/commands/lease/index.mdx | 62 + website/content/cli/commands/lease/lookup.mdx | 34 + website/content/cli/commands/lease/renew.mdx | 37 + website/content/cli/commands/lease/revoke.mdx | 45 + website/content/cli/commands/license/get.mdx | 52 + .../content/cli/commands/license/index.mdx | 60 + .../content/cli/commands/license/inspect.mdx | 58 + website/content/cli/commands/list.mdx | 25 + website/content/cli/commands/login.mdx | 156 ++ website/content/cli/commands/monitor.mdx | 78 + website/content/cli/commands/namespace.mdx | 98 + .../cli/commands/operator/diagnose.mdx | 228 +++ .../cli/commands/operator/generate-root.mdx | 94 + .../content/cli/commands/operator/import.mdx | 103 ++ .../content/cli/commands/operator/index.mdx | 68 + .../content/cli/commands/operator/init.mdx | 125 ++ .../cli/commands/operator/key-status.mdx | 34 + .../content/cli/commands/operator/members.mdx | 39 + .../content/cli/commands/operator/migrate.mdx | 142 ++ .../content/cli/commands/operator/raft.mdx | 418 +++++ .../content/cli/commands/operator/rekey.mdx | 161 ++ .../content/cli/commands/operator/rotate.mdx | 65 + .../content/cli/commands/operator/seal.mdx | 42 + .../cli/commands/operator/step-down.mdx | 44 + .../content/cli/commands/operator/unseal.mdx | 62 + .../content/cli/commands/operator/usage.mdx | 75 + .../cli/commands/operator/utilization.mdx | 83 + website/content/cli/commands/patch.mdx | 87 + website/content/cli/commands/path-help.mdx | 91 + .../content/cli/commands/pki/health-check.mdx | 559 ++++++ website/content/cli/commands/pki/index.mdx | 94 + website/content/cli/commands/pki/issue.mdx | 72 + .../cli/commands/pki/list-intermediates.mdx | 89 + website/content/cli/commands/pki/reissue.mdx | 88 + .../content/cli/commands/pki/verify-sign.mdx | 56 + .../cli/commands/plugin/deregister.mdx | 30 + website/content/cli/commands/plugin/index.mdx | 71 + website/content/cli/commands/plugin/info.mdx | 73 + website/content/cli/commands/plugin/list.mdx | 61 + .../content/cli/commands/plugin/register.mdx | 69 + .../content/cli/commands/plugin/reload.mdx | 72 + .../commands/plugin/runtime/deregister.mdx | 34 + .../cli/commands/plugin/runtime/index.mdx | 83 + .../cli/commands/plugin/runtime/info.mdx | 50 + .../cli/commands/plugin/runtime/list.mdx | 40 + .../cli/commands/plugin/runtime/register.mdx | 62 + .../content/cli/commands/policy/delete.mdx | 30 + website/content/cli/commands/policy/fmt.mdx | 27 + website/content/cli/commands/policy/index.mdx | 52 + website/content/cli/commands/policy/list.mdx | 33 + website/content/cli/commands/policy/read.mdx | 31 + website/content/cli/commands/policy/write.mdx | 36 + website/content/cli/commands/print.mdx | 18 + website/content/cli/commands/proxy.mdx | 9 + website/content/cli/commands/read.mdx | 77 + .../content/cli/commands/secrets/disable.mdx | 49 + .../content/cli/commands/secrets/enable.mdx | 120 ++ .../content/cli/commands/secrets/index.mdx | 79 + website/content/cli/commands/secrets/list.mdx | 78 + website/content/cli/commands/secrets/move.mdx | 49 + website/content/cli/commands/secrets/tune.mdx | 106 ++ website/content/cli/commands/server.mdx | 134 ++ website/content/cli/commands/ssh.mdx | 106 ++ website/content/cli/commands/status.mdx | 70 + .../cli/commands/token/capabilities.mdx | 50 + website/content/cli/commands/token/create.mdx | 129 ++ website/content/cli/commands/token/index.mdx | 53 + website/content/cli/commands/token/lookup.mdx | 50 + website/content/cli/commands/token/renew.mdx | 68 + website/content/cli/commands/token/revoke.mdx | 52 + .../content/cli/commands/transform/import.mdx | 62 + .../content/cli/commands/transform/index.mdx | 32 + .../content/cli/commands/transit/import.mdx | 62 + .../content/cli/commands/transit/index.mdx | 32 + website/content/cli/commands/unwrap.mdx | 45 + .../content/cli/commands/version-history.mdx | 32 + website/content/cli/commands/version.mdx | 21 + website/content/cli/commands/write.mdx | 130 ++ website/content/cli/index.mdx | 323 ++++ website/content/cli/token-helper.mdx | 326 ++++ .../docs/about-vault/how-vault-works.mdx | 121 ++ .../docs/about-vault/what-is-vault.mdx | 129 ++ .../why-use-vault/3rd-party-secrets.mdx | 122 ++ .../why-use-vault/certificates.mdx | 42 + .../about-vault/why-use-vault/identities.mdx | 127 ++ .../docs/about-vault/why-use-vault/index.mdx | 29 + .../why-use-vault/regulatory-compliance.mdx | 50 + .../why-use-vault/sensitive-data.mdx | 90 + .../why-use-vault/static-secrets.mdx | 46 + .../content/docs/agent-and-proxy/upgrade.mdx | 15 + website/content/docs/auth/aws.mdx | 10 +- website/content/docs/auth/login-mfa/faq.mdx | 2 +- website/content/docs/browser-support.mdx | 22 - website/content/docs/commands/server.mdx | 2 +- .../docs/concepts/client-count/counting.mdx | 2 - .../docs/concepts/client-count/index.mdx | 2 +- website/content/docs/configuration/index.mdx | 5 + .../docs/configuration/replication.mdx | 4 +- .../docs/configuration/storage/index.mdx | 2 +- website/content/docs/deploy/aws/index.mdx | 18 + .../aws/lambda-extension.mdx | 0 .../docs/{platform => deploy}/aws/run.mdx | 0 .../kubernetes}/consul-to-raft.mdx | 0 .../kubernetes}/csi/configurations.mdx | 0 .../kubernetes}/csi/examples.mdx | 0 .../k8s => deploy/kubernetes}/csi/index.mdx | 0 .../kubernetes}/csi/installation.mdx | 0 .../kubernetes}/helm/configuration.mdx | 0 .../kubernetes}/helm/enterprise.mdx | 0 .../kubernetes}/helm/examples/development.mdx | 0 .../helm/examples/enterprise-dr-with-raft.mdx | 0 .../examples/enterprise-perf-with-raft.mdx | 0 .../helm/examples/enterprise-with-raft.mdx | 0 .../kubernetes}/helm/examples/external.mdx | 0 .../kubernetes}/helm/examples/ha-tls.mdx | 0 .../helm/examples/ha-with-consul.mdx | 0 .../helm/examples/ha-with-raft.mdx | 0 .../kubernetes}/helm/examples/index.mdx | 0 .../examples/injector-tls-cert-manager.mdx | 0 .../helm/examples/injector-tls.mdx | 0 .../helm/examples/kubernetes-auth.mdx | 0 .../helm/examples/standalone-audit.mdx | 0 .../examples/standalone-load-balanced-ui.mdx | 0 .../helm/examples/standalone-tls.mdx | 0 .../k8s => deploy/kubernetes}/helm/index.mdx | 0 .../kubernetes}/helm/openshift.mdx | 0 .../k8s => deploy/kubernetes}/helm/run.mdx | 0 .../kubernetes}/helm/terraform.mdx | 0 .../k8s => deploy/kubernetes}/index.mdx | 7 +- .../kubernetes}/injector-csi.mdx | 0 .../kubernetes}/injector/annotations.mdx | 0 .../kubernetes}/injector/examples.mdx | 0 .../kubernetes}/injector/index.mdx | 0 .../kubernetes}/injector/installation.mdx | 0 .../kubernetes}/vso/api-reference.mdx | 0 .../kubernetes}/vso/examples.mdx | 0 .../k8s => deploy/kubernetes}/vso/helm.mdx | 0 .../k8s => deploy/kubernetes}/vso/index.mdx | 0 .../kubernetes}/vso/installation.mdx | 0 .../kubernetes}/vso/openshift.mdx | 0 .../kubernetes}/vso/secret-transformation.mdx | 0 .../kubernetes}/vso/sources/hvs.mdx | 0 .../kubernetes}/vso/sources/index.mdx | 0 .../vso/sources/vault/auth/aws.mdx | 0 .../vso/sources/vault/auth/gcp.mdx | 0 .../vso/sources/vault/auth/index.mdx | 0 .../vso/sources/vault/client-cache.mdx | 0 .../kubernetes}/vso/sources/vault/index.mdx | 0 .../vso/sources/vault/instant-updates.mdx | 0 .../kubernetes}/vso/telemetry.mdx | 0 .../docs/{ => deploy}/run-as-service.mdx | 0 .../content/docs/enterprise/consistency.mdx | 1 - website/content/docs/enterprise/hsm/index.mdx | 2 +- .../docs/enterprise/license/autoloading.mdx | 35 - .../content/docs/enterprise/license/faq.mdx | 183 -- .../content/docs/enterprise/license/index.mdx | 45 - website/content/docs/enterprise/lts.mdx | 2 +- website/content/docs/faq/index.mdx | 11 - website/content/docs/faq/ssct.mdx | 127 -- .../build-from-code.mdx | 0 website/content/docs/get-vault/index.mdx | 51 + .../{install => get-vault}/install-binary.mdx | 2 +- website/content/docs/index.mdx | 14 +- website/content/docs/install/index.mdx | 35 - .../docs/internals/recommended-patterns.mdx | 2 +- .../content/docs/interoperability-matrix.mdx | 198 --- website/content/docs/license/autoloading.mdx | 46 + .../content/docs/license/change-license.mdx | 49 + website/content/docs/license/index.mdx | 85 + .../license/product-usage-reporting.mdx | 0 .../utilization/auto-reporting.mdx} | 0 .../utilization}/manual-reporting.mdx | 0 .../content/docs/partners/external-keys.mdx | 93 + website/content/docs/partners/hsm.mdx | 69 + website/content/docs/partners/index.mdx | 19 + website/content/docs/partners/program.mdx | 318 ++++ website/content/docs/partners/protocols.mdx | 63 + website/content/docs/partnerships.mdx | 187 -- website/content/docs/platform/aws/index.mdx | 22 - website/content/docs/platform/index.mdx | 10 - website/content/docs/plugins/index.mdx | 193 +- .../docs/plugins/plugin-architecture.mdx | 245 +-- .../docs/plugins/plugin-development.mdx | 6 + .../docs/plugins/plugin-management.mdx | 126 +- website/content/docs/plugins/register.mdx | 55 + website/content/docs/plugins/rollback.mdx | 48 + website/content/docs/plugins/upgrade.mdx | 56 + website/content/docs/release-notes/1.10.0.mdx | 170 -- website/content/docs/release-notes/1.11.0.mdx | 113 -- website/content/docs/release-notes/1.12.0.mdx | 161 -- website/content/docs/release-notes/1.13.0.mdx | 141 -- website/content/docs/release-notes/1.14.0.mdx | 292 --- website/content/docs/release-notes/1.15.0.mdx | 265 --- website/content/docs/release-notes/1.16.1.mdx | 266 --- website/content/docs/release-notes/1.17.0.mdx | 238 --- website/content/docs/release-notes/1.18.0.mdx | 161 -- website/content/docs/release-notes/1.5.0.mdx | 63 - website/content/docs/release-notes/1.6.0.mdx | 52 - website/content/docs/release-notes/1.7.0.mdx | 64 - website/content/docs/release-notes/1.8.0.mdx | 62 - website/content/docs/release-notes/1.9.0.mdx | 119 -- website/content/docs/release-notes/index.mdx | 17 - .../deduplication/acl-policy-templates.mdx | 2 +- .../deduplication/different-case.mdx | 2 +- .../identity}/deduplication/entity-group.mdx | 6 +- .../identity}/deduplication/index.mdx | 4 +- .../deduplication/terraform-refs.mdx | 0 website/content/docs/ui/browser-support.mdx | 23 + website/content/docs/updates/changelog.mdx | 10 + .../index.mdx => updates/deprecation.mdx} | 0 .../docs/updates/important-changes.mdx | 280 +++ .../1.19.0.mdx => updates/release-notes.mdx} | 43 +- website/content/docs/upgrade/index.mdx | 118 ++ .../docs/{upgrading => upgrade}/raft-wal.mdx | 0 .../replicated-deployment.mdx} | 166 +- website/content/docs/upgrade/rollback.mdx | 64 + website/content/docs/upgrading/plugins.mdx | 186 -- .../docs/upgrading/upgrade-to-0.10.0.mdx | 161 -- .../docs/upgrading/upgrade-to-0.10.2.mdx | 26 - .../docs/upgrading/upgrade-to-0.10.4.mdx | 34 - .../docs/upgrading/upgrade-to-0.11.0.mdx | 147 -- .../docs/upgrading/upgrade-to-0.11.2.mdx | 23 - .../docs/upgrading/upgrade-to-0.11.6.mdx | 19 - .../docs/upgrading/upgrade-to-0.5.0.mdx | 141 -- .../docs/upgrading/upgrade-to-0.5.1.mdx | 59 - .../docs/upgrading/upgrade-to-0.6.0.mdx | 54 - .../docs/upgrading/upgrade-to-0.6.1.mdx | 103 -- .../docs/upgrading/upgrade-to-0.6.2.mdx | 75 - .../docs/upgrading/upgrade-to-0.6.3.mdx | 35 - .../docs/upgrading/upgrade-to-0.6.4.mdx | 83 - .../docs/upgrading/upgrade-to-0.7.0.mdx | 45 - .../docs/upgrading/upgrade-to-0.8.0.mdx | 52 - .../docs/upgrading/upgrade-to-0.9.0.mdx | 121 -- .../docs/upgrading/upgrade-to-0.9.1.mdx | 55 - .../docs/upgrading/upgrade-to-0.9.2.mdx | 55 - .../docs/upgrading/upgrade-to-0.9.3.mdx | 15 - .../docs/upgrading/upgrade-to-0.9.6.mdx | 26 - .../docs/upgrading/upgrade-to-1.0.0.mdx | 48 - .../docs/upgrading/upgrade-to-1.1.0.mdx | 46 - .../docs/upgrading/upgrade-to-1.1.1.mdx | 68 - .../docs/upgrading/upgrade-to-1.1.2.mdx | 28 - .../docs/upgrading/upgrade-to-1.10.x.mdx | 144 -- .../docs/upgrading/upgrade-to-1.11.x.mdx | 53 - .../docs/upgrading/upgrade-to-1.12.x.mdx | 223 --- .../docs/upgrading/upgrade-to-1.13.x.mdx | 206 --- .../docs/upgrading/upgrade-to-1.14.x.mdx | 82 - .../docs/upgrading/upgrade-to-1.15.x.mdx | 142 -- .../docs/upgrading/upgrade-to-1.16.x.mdx | 250 --- .../docs/upgrading/upgrade-to-1.17.x.mdx | 221 --- .../docs/upgrading/upgrade-to-1.18.x.mdx | 156 -- .../docs/upgrading/upgrade-to-1.19.x.mdx | 110 -- .../docs/upgrading/upgrade-to-1.2.0.mdx | 119 -- .../docs/upgrading/upgrade-to-1.2.1.mdx | 22 - .../docs/upgrading/upgrade-to-1.2.4.mdx | 41 - .../docs/upgrading/upgrade-to-1.2.5.mdx | 20 - .../docs/upgrading/upgrade-to-1.2.6.mdx | 18 - .../docs/upgrading/upgrade-to-1.2.7.mdx | 14 - .../docs/upgrading/upgrade-to-1.3.0.mdx | 57 - .../docs/upgrading/upgrade-to-1.3.10.mdx | 14 - .../docs/upgrading/upgrade-to-1.3.2.mdx | 16 - .../docs/upgrading/upgrade-to-1.3.3.mdx | 14 - .../docs/upgrading/upgrade-to-1.3.4.mdx | 14 - .../docs/upgrading/upgrade-to-1.3.5.mdx | 32 - .../docs/upgrading/upgrade-to-1.3.8.mdx | 20 - .../docs/upgrading/upgrade-to-1.3.9.mdx | 18 - .../docs/upgrading/upgrade-to-1.4.0.mdx | 26 - .../docs/upgrading/upgrade-to-1.4.1.mdx | 34 - .../docs/upgrading/upgrade-to-1.4.4.mdx | 20 - .../docs/upgrading/upgrade-to-1.4.5.mdx | 18 - .../docs/upgrading/upgrade-to-1.4.6.mdx | 14 - .../docs/upgrading/upgrade-to-1.5.0.mdx | 93 - .../docs/upgrading/upgrade-to-1.5.1.mdx | 20 - .../docs/upgrading/upgrade-to-1.5.2.mdx | 18 - .../docs/upgrading/upgrade-to-1.5.3.mdx | 14 - .../docs/upgrading/upgrade-to-1.6.0.mdx | 54 - .../docs/upgrading/upgrade-to-1.6.1.mdx | 18 - .../docs/upgrading/upgrade-to-1.6.2.mdx | 18 - .../docs/upgrading/upgrade-to-1.6.3.mdx | 18 - .../docs/upgrading/upgrade-to-1.7.x.mdx | 59 - .../docs/upgrading/upgrade-to-1.8.x.mdx | 71 - .../docs/upgrading/upgrade-to-1.9.x.mdx | 127 -- .../docs/upgrading/vault-ha-upgrade.mdx | 107 -- website/content/docs/use-cases.mdx | 63 - website/content/docs/what-is-vault.mdx | 105 -- .../content/partials/alerts/deprecated.mdx | 6 +- .../partials/alerts/ipv6-compliance.mdx | 2 +- .../partials/alerts/partner-program.mdx | 8 + website/content/partials/alpine-314.mdx | 9 - ...n-of-sentinel-rgps-via-identity-groups.mdx | 5 - .../partials/aws-auth-metadata-fix.mdx | 35 - .../partials/aws-auth-metadata-issue.mdx | 51 - .../partials/aws-imds-timeout-upgrade.mdx | 9 - .../partials/aws-invalid-header-fix.mdx | 9 - .../content/partials/aws-invalid-header.mdx | 25 - .../content/partials/aws-sha1-deprecation.mdx | 5 - website/content/partials/aws-sts-issue.mdx | 9 - .../content/partials/builds-without-ui.mdx | 4 - .../consul-dataplane-upgrade-note.mdx | 2 - .../content/partials/content-footer-title.mdx | 7 - .../content/partials/enterprise-licenses.mdx | 6 - .../content/partials/entity-alias-mapping.mdx | 7 - .../1_13-reload-census-panic-standby.mdx | 21 - ...it-file-sighup-does-not-trigger-reload.mdx | 47 - ...-audit-panic-handling-with-eventlogger.mdx | 24 - ...terprise-perf-standby-logs-all-headers.mdx | 27 - .../known-issues/1_15-auto-upgrade.mdx | 27 - ...-use-of-log-raw-applies-to-all-devices.mdx | 51 - .../1_15_openldap-rotate-credentials.mdx | 14 - .../1_16-default-lcq-pre-1_9-upgrade.mdx | 47 - ..._16-default-policy-needs-to-be-updated.mdx | 45 - .../1_16-jwt_auth_bound_audiences.mdx | 34 - .../known-issues/1_16-jwt_auth_config.mdx | 18 - ...ldap_auth_login_anonymous_group_search.mdx | 16 - ...6-ldap_auth_login_missing_entity_alias.mdx | 16 - .../1_16_azure-secrets-engine-client-id.mdx | 18 - .../1_16_secrets-sync-chroot-activation.mdx | 15 - .../autopilot-upgrade-upgrade-version.mdx | 16 - .../partials/known-issues/aws-auth-panics.mdx | 18 - .../known-issues/aws-static-roles.mdx | 16 - .../duplicate-identity-groups.mdx | 12 - .../ephemeral-loggers-memory-leak.mdx | 20 - .../expiration-metrics-fatal-error.mdx | 22 - ...nternal-error-namespace-missing-policy.mdx | 143 -- .../partials/known-issues/kv2-url-change.mdx | 24 - .../perf-secondary-many-mounts-deadlock.mdx | 34 - .../perf-standbys-revert-to-standby.mdx | 61 - .../sublogger-levels-unchanged-on-reload.mdx | 32 - .../transit-managed-keys-panics.mdx | 23 - .../transit-managed-keys-sign-fails.mdx | 23 - .../known-issues/ui-collapsed-navbar.mdx | 16 - .../known-issues/ui-pki-control-groups.mdx | 17 - .../known-issues/ui-safari-login-screen.mdx | 13 - .../update-primary-addrs-panic.mdx | 16 - .../known-issues/update-primary-data-loss.mdx | 57 - .../known-issues/user-lockout-logging.mdx | 9 - .../lts}/lts-upgrade-path.mdx | 0 .../why-use-vault/manage-3p-secrets.mdx | 2 + .../why-use-vault/manage-certificates.mdx | 2 + .../why-use-vault/manage-identities.mdx | 2 + .../why-use-vault/manage-static-secrets.mdx | 2 + .../why-use-vault/regulatory-compliance.mdx | 2 + .../why-use-vault/secure-sensitive-data.mdx | 2 + .../content/partials/ldap-upndomain-issue.mdx | 6 - .../partials/lease-count-quota-upgrade.mdx | 5 - .../partials/okta-group-pagination.mdx | 8 - ...tandby-token-create-forwarding-failure.mdx | 19 - website/content/partials/pgx-params.mdx | 5 - .../partials/pki-double-migration-bug.mdx | 30 - .../content/partials/pki-forwarding-bug.mdx | 10 - .../plugin-file-permissions-check.mdx | 18 +- website/content/partials/plugins/enable.mdx | 92 + .../partials/plugins/pin-and-reload.mdx | 139 ++ website/content/partials/plugins/register.mdx | 140 ++ .../partials/plugins/verify-status.mdx | 115 ++ .../partials/primary-cluster-addr-change.mdx | 16 - .../partials/raft-panic-old-tls-key.mdx | 17 - .../partials/raft-retry-join-failure.mdx | 24 - .../release-notes/deprecation-note.mdx | 6 +- website/content/partials/social-bar.mdx | 49 + .../content/partials/svg/partner-badge.mdx | 1 + website/content/partials/tips/get-plugins.mdx | 6 + website/content/partials/tips/try-hvd.mdx | 11 + .../tokenization-rotation-persistence.mdx | 14 - .../content/partials/transform-upgrade.mdx | 8 - .../ui-pki-control-groups-known-issue.mdx | 17 - .../partials/ui-safari-login-screen.mdx | 13 - website/content/partials/version-syntax.mdx | 13 + website/content/partials/versions.mdx | 20 - .../why-use-vault/manage-3p-secrets-large.mdx | 22 + .../why-use-vault/manage-3p-secrets-small.mdx | 19 + .../manage-certificates-large.mdx | 20 + .../manage-certificates-small.mdx | 17 + .../why-use-vault/manage-identities-large.mdx | 20 + .../why-use-vault/manage-identities-small.mdx | 18 + .../manage-static-secrets-large.mdx | 21 + .../manage-static-secrets-small.mdx | 18 + .../regulatory-compliance-large.mdx | 20 + .../regulatory-compliance-small.mdx | 17 + .../secure-sensitive-data-large.mdx | 20 + .../secure-sensitive-data-small.mdx | 17 + .../partials/x509-sha1-deprecation.mdx | 4 +- website/data/docs-nav-data.json | 1584 +++++++---------- .../why-use-vault/manage-3p-secrets_dark.png | Bin 0 -> 36480 bytes .../why-use-vault/manage-3p-secrets_light.png | Bin 0 -> 34623 bytes .../manage-certificates_dark.png | Bin 0 -> 36082 bytes .../manage-certificates_light.png | Bin 0 -> 34757 bytes .../why-use-vault/manage-identities_dark.png | Bin 0 -> 31496 bytes .../why-use-vault/manage-identities_light.png | Bin 0 -> 30776 bytes .../manage-static-secrets_dark.png | Bin 0 -> 31621 bytes .../manage-static-secrets_light.png | Bin 0 -> 30393 bytes .../regulatory-compliance_dark.png | Bin 0 -> 28987 bytes .../regulatory-compliance_light.png | Bin 0 -> 28401 bytes .../secure-sensitive-data_dark.png | Bin 0 -> 26009 bytes .../secure-sensitive-data_light.png | Bin 0 -> 24881 bytes website/redirects.js | 136 +- 425 files changed, 13512 insertions(+), 10441 deletions(-) create mode 100644 website/content/cli/commands/agent/generate-config.mdx create mode 100644 website/content/cli/commands/agent/index.mdx create mode 100644 website/content/cli/commands/audit/disable.mdx create mode 100644 website/content/cli/commands/audit/enable.mdx create mode 100644 website/content/cli/commands/audit/list.mdx create mode 100644 website/content/cli/commands/auth/disable.mdx create mode 100644 website/content/cli/commands/auth/enable.mdx create mode 100644 website/content/cli/commands/auth/help.mdx create mode 100644 website/content/cli/commands/auth/index.mdx create mode 100644 website/content/cli/commands/auth/list.mdx create mode 100644 website/content/cli/commands/auth/move.mdx create mode 100644 website/content/cli/commands/auth/tune.mdx create mode 100644 website/content/cli/commands/debug.mdx create mode 100644 website/content/cli/commands/delete.mdx create mode 100644 website/content/cli/commands/events.mdx create mode 100644 website/content/cli/commands/hcp/connect.mdx create mode 100644 website/content/cli/commands/hcp/disconnect.mdx create mode 100644 website/content/cli/commands/hcp/index.mdx create mode 100644 website/content/cli/commands/kv/delete.mdx create mode 100644 website/content/cli/commands/kv/destroy.mdx create mode 100644 website/content/cli/commands/kv/enable-versioning.mdx create mode 100644 website/content/cli/commands/kv/get.mdx create mode 100644 website/content/cli/commands/kv/index.mdx create mode 100644 website/content/cli/commands/kv/list.mdx create mode 100644 website/content/cli/commands/kv/metadata.mdx create mode 100644 website/content/cli/commands/kv/patch.mdx create mode 100644 website/content/cli/commands/kv/put.mdx create mode 100644 website/content/cli/commands/kv/rollback.mdx create mode 100644 website/content/cli/commands/kv/undelete.mdx create mode 100644 website/content/cli/commands/lease/index.mdx create mode 100644 website/content/cli/commands/lease/lookup.mdx create mode 100644 website/content/cli/commands/lease/renew.mdx create mode 100644 website/content/cli/commands/lease/revoke.mdx create mode 100644 website/content/cli/commands/license/get.mdx create mode 100644 website/content/cli/commands/license/index.mdx create mode 100644 website/content/cli/commands/license/inspect.mdx create mode 100644 website/content/cli/commands/list.mdx create mode 100644 website/content/cli/commands/login.mdx create mode 100644 website/content/cli/commands/monitor.mdx create mode 100644 website/content/cli/commands/namespace.mdx create mode 100644 website/content/cli/commands/operator/diagnose.mdx create mode 100644 website/content/cli/commands/operator/generate-root.mdx create mode 100644 website/content/cli/commands/operator/import.mdx create mode 100644 website/content/cli/commands/operator/index.mdx create mode 100644 website/content/cli/commands/operator/init.mdx create mode 100644 website/content/cli/commands/operator/key-status.mdx create mode 100644 website/content/cli/commands/operator/members.mdx create mode 100644 website/content/cli/commands/operator/migrate.mdx create mode 100644 website/content/cli/commands/operator/raft.mdx create mode 100644 website/content/cli/commands/operator/rekey.mdx create mode 100644 website/content/cli/commands/operator/rotate.mdx create mode 100644 website/content/cli/commands/operator/seal.mdx create mode 100644 website/content/cli/commands/operator/step-down.mdx create mode 100644 website/content/cli/commands/operator/unseal.mdx create mode 100644 website/content/cli/commands/operator/usage.mdx create mode 100644 website/content/cli/commands/operator/utilization.mdx create mode 100644 website/content/cli/commands/patch.mdx create mode 100644 website/content/cli/commands/path-help.mdx create mode 100644 website/content/cli/commands/pki/health-check.mdx create mode 100644 website/content/cli/commands/pki/index.mdx create mode 100644 website/content/cli/commands/pki/issue.mdx create mode 100644 website/content/cli/commands/pki/list-intermediates.mdx create mode 100644 website/content/cli/commands/pki/reissue.mdx create mode 100644 website/content/cli/commands/pki/verify-sign.mdx create mode 100644 website/content/cli/commands/plugin/deregister.mdx create mode 100644 website/content/cli/commands/plugin/index.mdx create mode 100644 website/content/cli/commands/plugin/info.mdx create mode 100644 website/content/cli/commands/plugin/list.mdx create mode 100644 website/content/cli/commands/plugin/register.mdx create mode 100644 website/content/cli/commands/plugin/reload.mdx create mode 100644 website/content/cli/commands/plugin/runtime/deregister.mdx create mode 100644 website/content/cli/commands/plugin/runtime/index.mdx create mode 100644 website/content/cli/commands/plugin/runtime/info.mdx create mode 100644 website/content/cli/commands/plugin/runtime/list.mdx create mode 100644 website/content/cli/commands/plugin/runtime/register.mdx create mode 100644 website/content/cli/commands/policy/delete.mdx create mode 100644 website/content/cli/commands/policy/fmt.mdx create mode 100644 website/content/cli/commands/policy/index.mdx create mode 100644 website/content/cli/commands/policy/list.mdx create mode 100644 website/content/cli/commands/policy/read.mdx create mode 100644 website/content/cli/commands/policy/write.mdx create mode 100644 website/content/cli/commands/print.mdx create mode 100644 website/content/cli/commands/proxy.mdx create mode 100644 website/content/cli/commands/read.mdx create mode 100644 website/content/cli/commands/secrets/disable.mdx create mode 100644 website/content/cli/commands/secrets/enable.mdx create mode 100644 website/content/cli/commands/secrets/index.mdx create mode 100644 website/content/cli/commands/secrets/list.mdx create mode 100644 website/content/cli/commands/secrets/move.mdx create mode 100644 website/content/cli/commands/secrets/tune.mdx create mode 100644 website/content/cli/commands/server.mdx create mode 100644 website/content/cli/commands/ssh.mdx create mode 100644 website/content/cli/commands/status.mdx create mode 100644 website/content/cli/commands/token/capabilities.mdx create mode 100644 website/content/cli/commands/token/create.mdx create mode 100644 website/content/cli/commands/token/index.mdx create mode 100644 website/content/cli/commands/token/lookup.mdx create mode 100644 website/content/cli/commands/token/renew.mdx create mode 100644 website/content/cli/commands/token/revoke.mdx create mode 100644 website/content/cli/commands/transform/import.mdx create mode 100644 website/content/cli/commands/transform/index.mdx create mode 100644 website/content/cli/commands/transit/import.mdx create mode 100644 website/content/cli/commands/transit/index.mdx create mode 100644 website/content/cli/commands/unwrap.mdx create mode 100644 website/content/cli/commands/version-history.mdx create mode 100644 website/content/cli/commands/version.mdx create mode 100644 website/content/cli/commands/write.mdx create mode 100644 website/content/cli/index.mdx create mode 100644 website/content/cli/token-helper.mdx create mode 100644 website/content/docs/about-vault/how-vault-works.mdx create mode 100644 website/content/docs/about-vault/what-is-vault.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/3rd-party-secrets.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/certificates.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/identities.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/index.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/regulatory-compliance.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/sensitive-data.mdx create mode 100644 website/content/docs/about-vault/why-use-vault/static-secrets.mdx create mode 100644 website/content/docs/agent-and-proxy/upgrade.mdx delete mode 100644 website/content/docs/browser-support.mdx create mode 100644 website/content/docs/deploy/aws/index.mdx rename website/content/docs/{platform => deploy}/aws/lambda-extension.mdx (100%) rename website/content/docs/{platform => deploy}/aws/run.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/consul-to-raft.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/csi/configurations.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/csi/examples.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/csi/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/csi/installation.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/configuration.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/enterprise.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/development.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/enterprise-dr-with-raft.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/enterprise-perf-with-raft.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/enterprise-with-raft.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/external.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/ha-tls.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/ha-with-consul.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/ha-with-raft.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/injector-tls-cert-manager.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/injector-tls.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/kubernetes-auth.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/standalone-audit.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/standalone-load-balanced-ui.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/examples/standalone-tls.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/openshift.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/run.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/helm/terraform.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/index.mdx (97%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/injector-csi.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/injector/annotations.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/injector/examples.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/injector/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/injector/installation.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/api-reference.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/examples.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/helm.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/installation.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/openshift.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/secret-transformation.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/hvs.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/vault/auth/aws.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/vault/auth/gcp.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/vault/auth/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/vault/client-cache.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/vault/index.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/sources/vault/instant-updates.mdx (100%) rename website/content/docs/{platform/k8s => deploy/kubernetes}/vso/telemetry.mdx (100%) rename website/content/docs/{ => deploy}/run-as-service.mdx (100%) delete mode 100644 website/content/docs/enterprise/license/autoloading.mdx delete mode 100644 website/content/docs/enterprise/license/faq.mdx delete mode 100644 website/content/docs/enterprise/license/index.mdx delete mode 100644 website/content/docs/faq/index.mdx delete mode 100644 website/content/docs/faq/ssct.mdx rename website/content/docs/{install => get-vault}/build-from-code.mdx (100%) create mode 100644 website/content/docs/get-vault/index.mdx rename website/content/docs/{install => get-vault}/install-binary.mdx (99%) delete mode 100644 website/content/docs/install/index.mdx delete mode 100644 website/content/docs/interoperability-matrix.mdx create mode 100644 website/content/docs/license/autoloading.mdx create mode 100644 website/content/docs/license/change-license.mdx create mode 100644 website/content/docs/license/index.mdx rename website/content/docs/{enterprise => }/license/product-usage-reporting.mdx (100%) rename website/content/docs/{enterprise/license/utilization-reporting.mdx => license/utilization/auto-reporting.mdx} (100%) rename website/content/docs/{enterprise/license => license/utilization}/manual-reporting.mdx (100%) create mode 100644 website/content/docs/partners/external-keys.mdx create mode 100644 website/content/docs/partners/hsm.mdx create mode 100644 website/content/docs/partners/index.mdx create mode 100644 website/content/docs/partners/program.mdx create mode 100644 website/content/docs/partners/protocols.mdx delete mode 100644 website/content/docs/partnerships.mdx delete mode 100644 website/content/docs/platform/aws/index.mdx delete mode 100644 website/content/docs/platform/index.mdx create mode 100644 website/content/docs/plugins/register.mdx create mode 100644 website/content/docs/plugins/rollback.mdx create mode 100644 website/content/docs/plugins/upgrade.mdx delete mode 100644 website/content/docs/release-notes/1.10.0.mdx delete mode 100644 website/content/docs/release-notes/1.11.0.mdx delete mode 100644 website/content/docs/release-notes/1.12.0.mdx delete mode 100644 website/content/docs/release-notes/1.13.0.mdx delete mode 100644 website/content/docs/release-notes/1.14.0.mdx delete mode 100644 website/content/docs/release-notes/1.15.0.mdx delete mode 100644 website/content/docs/release-notes/1.16.1.mdx delete mode 100644 website/content/docs/release-notes/1.17.0.mdx delete mode 100644 website/content/docs/release-notes/1.18.0.mdx delete mode 100644 website/content/docs/release-notes/1.5.0.mdx delete mode 100644 website/content/docs/release-notes/1.6.0.mdx delete mode 100644 website/content/docs/release-notes/1.7.0.mdx delete mode 100644 website/content/docs/release-notes/1.8.0.mdx delete mode 100644 website/content/docs/release-notes/1.9.0.mdx delete mode 100644 website/content/docs/release-notes/index.mdx rename website/content/docs/{upgrading => secrets/identity}/deduplication/acl-policy-templates.mdx (99%) rename website/content/docs/{upgrading => secrets/identity}/deduplication/different-case.mdx (98%) rename website/content/docs/{upgrading => secrets/identity}/deduplication/entity-group.mdx (97%) rename website/content/docs/{upgrading => secrets/identity}/deduplication/index.mdx (96%) rename website/content/docs/{upgrading => secrets/identity}/deduplication/terraform-refs.mdx (100%) create mode 100644 website/content/docs/ui/browser-support.mdx create mode 100644 website/content/docs/updates/changelog.mdx rename website/content/docs/{deprecation/index.mdx => updates/deprecation.mdx} (100%) create mode 100644 website/content/docs/updates/important-changes.mdx rename website/content/docs/{release-notes/1.19.0.mdx => updates/release-notes.mdx} (74%) create mode 100644 website/content/docs/upgrade/index.mdx rename website/content/docs/{upgrading => upgrade}/raft-wal.mdx (100%) rename website/content/docs/{upgrading/index.mdx => upgrade/replicated-deployment.mdx} (58%) create mode 100644 website/content/docs/upgrade/rollback.mdx delete mode 100644 website/content/docs/upgrading/plugins.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.10.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.10.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.10.4.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.11.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.11.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.11.6.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.5.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.5.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.6.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.6.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.6.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.6.3.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.6.4.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.7.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.8.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.9.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.9.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.9.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.9.3.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-0.9.6.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.0.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.1.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.1.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.1.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.10.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.11.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.12.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.13.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.14.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.15.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.16.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.17.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.18.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.19.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.2.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.2.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.2.4.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.2.5.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.2.6.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.2.7.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.10.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.3.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.4.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.5.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.8.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.3.9.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.4.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.4.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.4.4.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.4.5.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.4.6.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.5.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.5.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.5.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.5.3.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.6.0.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.6.1.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.6.2.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.6.3.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.7.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.8.x.mdx delete mode 100644 website/content/docs/upgrading/upgrade-to-1.9.x.mdx delete mode 100644 website/content/docs/upgrading/vault-ha-upgrade.mdx delete mode 100644 website/content/docs/use-cases.mdx delete mode 100644 website/content/docs/what-is-vault.mdx create mode 100644 website/content/partials/alerts/partner-program.mdx delete mode 100644 website/content/partials/alpine-314.mdx delete mode 100644 website/content/partials/application-of-sentinel-rgps-via-identity-groups.mdx delete mode 100644 website/content/partials/aws-auth-metadata-fix.mdx delete mode 100644 website/content/partials/aws-auth-metadata-issue.mdx delete mode 100644 website/content/partials/aws-imds-timeout-upgrade.mdx delete mode 100644 website/content/partials/aws-invalid-header-fix.mdx delete mode 100644 website/content/partials/aws-invalid-header.mdx delete mode 100644 website/content/partials/aws-sha1-deprecation.mdx delete mode 100644 website/content/partials/aws-sts-issue.mdx delete mode 100644 website/content/partials/builds-without-ui.mdx delete mode 100644 website/content/partials/consul-dataplane-upgrade-note.mdx delete mode 100644 website/content/partials/content-footer-title.mdx delete mode 100644 website/content/partials/enterprise-licenses.mdx delete mode 100644 website/content/partials/entity-alias-mapping.mdx delete mode 100644 website/content/partials/known-issues/1_13-reload-census-panic-standby.mdx delete mode 100644 website/content/partials/known-issues/1_15-audit-file-sighup-does-not-trigger-reload.mdx delete mode 100644 website/content/partials/known-issues/1_15-audit-panic-handling-with-eventlogger.mdx delete mode 100644 website/content/partials/known-issues/1_15-audit-vault-enterprise-perf-standby-logs-all-headers.mdx delete mode 100644 website/content/partials/known-issues/1_15-auto-upgrade.mdx delete mode 100644 website/content/partials/known-issues/1_15_audit-use-of-log-raw-applies-to-all-devices.mdx delete mode 100644 website/content/partials/known-issues/1_15_openldap-rotate-credentials.mdx delete mode 100644 website/content/partials/known-issues/1_16-default-lcq-pre-1_9-upgrade.mdx delete mode 100644 website/content/partials/known-issues/1_16-default-policy-needs-to-be-updated.mdx delete mode 100644 website/content/partials/known-issues/1_16-jwt_auth_bound_audiences.mdx delete mode 100644 website/content/partials/known-issues/1_16-jwt_auth_config.mdx delete mode 100644 website/content/partials/known-issues/1_16-ldap_auth_login_anonymous_group_search.mdx delete mode 100644 website/content/partials/known-issues/1_16-ldap_auth_login_missing_entity_alias.mdx delete mode 100644 website/content/partials/known-issues/1_16_azure-secrets-engine-client-id.mdx delete mode 100644 website/content/partials/known-issues/1_16_secrets-sync-chroot-activation.mdx delete mode 100644 website/content/partials/known-issues/autopilot-upgrade-upgrade-version.mdx delete mode 100644 website/content/partials/known-issues/aws-auth-panics.mdx delete mode 100644 website/content/partials/known-issues/aws-static-roles.mdx delete mode 100644 website/content/partials/known-issues/duplicate-identity-groups.mdx delete mode 100644 website/content/partials/known-issues/ephemeral-loggers-memory-leak.mdx delete mode 100644 website/content/partials/known-issues/expiration-metrics-fatal-error.mdx delete mode 100644 website/content/partials/known-issues/internal-error-namespace-missing-policy.mdx delete mode 100644 website/content/partials/known-issues/kv2-url-change.mdx delete mode 100644 website/content/partials/known-issues/perf-secondary-many-mounts-deadlock.mdx delete mode 100644 website/content/partials/known-issues/perf-standbys-revert-to-standby.mdx delete mode 100644 website/content/partials/known-issues/sublogger-levels-unchanged-on-reload.mdx delete mode 100644 website/content/partials/known-issues/transit-managed-keys-panics.mdx delete mode 100644 website/content/partials/known-issues/transit-managed-keys-sign-fails.mdx delete mode 100644 website/content/partials/known-issues/ui-collapsed-navbar.mdx delete mode 100644 website/content/partials/known-issues/ui-pki-control-groups.mdx delete mode 100644 website/content/partials/known-issues/ui-safari-login-screen.mdx delete mode 100644 website/content/partials/known-issues/update-primary-addrs-panic.mdx delete mode 100644 website/content/partials/known-issues/update-primary-data-loss.mdx delete mode 100644 website/content/partials/known-issues/user-lockout-logging.mdx rename website/content/partials/{assets => ld-images/lts}/lts-upgrade-path.mdx (100%) create mode 100644 website/content/partials/ld-images/why-use-vault/manage-3p-secrets.mdx create mode 100644 website/content/partials/ld-images/why-use-vault/manage-certificates.mdx create mode 100644 website/content/partials/ld-images/why-use-vault/manage-identities.mdx create mode 100644 website/content/partials/ld-images/why-use-vault/manage-static-secrets.mdx create mode 100644 website/content/partials/ld-images/why-use-vault/regulatory-compliance.mdx create mode 100644 website/content/partials/ld-images/why-use-vault/secure-sensitive-data.mdx delete mode 100644 website/content/partials/ldap-upndomain-issue.mdx delete mode 100644 website/content/partials/lease-count-quota-upgrade.mdx delete mode 100644 website/content/partials/okta-group-pagination.mdx delete mode 100644 website/content/partials/perf-standby-token-create-forwarding-failure.mdx delete mode 100644 website/content/partials/pgx-params.mdx delete mode 100644 website/content/partials/pki-double-migration-bug.mdx delete mode 100644 website/content/partials/pki-forwarding-bug.mdx create mode 100644 website/content/partials/plugins/enable.mdx create mode 100644 website/content/partials/plugins/pin-and-reload.mdx create mode 100644 website/content/partials/plugins/register.mdx create mode 100644 website/content/partials/plugins/verify-status.mdx delete mode 100644 website/content/partials/primary-cluster-addr-change.mdx delete mode 100644 website/content/partials/raft-panic-old-tls-key.mdx delete mode 100644 website/content/partials/raft-retry-join-failure.mdx create mode 100644 website/content/partials/social-bar.mdx create mode 100644 website/content/partials/svg/partner-badge.mdx create mode 100644 website/content/partials/tips/get-plugins.mdx create mode 100644 website/content/partials/tips/try-hvd.mdx delete mode 100644 website/content/partials/tokenization-rotation-persistence.mdx delete mode 100644 website/content/partials/transform-upgrade.mdx delete mode 100644 website/content/partials/ui-pki-control-groups-known-issue.mdx delete mode 100644 website/content/partials/ui-safari-login-screen.mdx create mode 100644 website/content/partials/version-syntax.mdx delete mode 100644 website/content/partials/versions.mdx create mode 100644 website/content/partials/why-use-vault/manage-3p-secrets-large.mdx create mode 100644 website/content/partials/why-use-vault/manage-3p-secrets-small.mdx create mode 100644 website/content/partials/why-use-vault/manage-certificates-large.mdx create mode 100644 website/content/partials/why-use-vault/manage-certificates-small.mdx create mode 100644 website/content/partials/why-use-vault/manage-identities-large.mdx create mode 100644 website/content/partials/why-use-vault/manage-identities-small.mdx create mode 100644 website/content/partials/why-use-vault/manage-static-secrets-large.mdx create mode 100644 website/content/partials/why-use-vault/manage-static-secrets-small.mdx create mode 100644 website/content/partials/why-use-vault/regulatory-compliance-large.mdx create mode 100644 website/content/partials/why-use-vault/regulatory-compliance-small.mdx create mode 100644 website/content/partials/why-use-vault/secure-sensitive-data-large.mdx create mode 100644 website/content/partials/why-use-vault/secure-sensitive-data-small.mdx create mode 100644 website/public/img/why-use-vault/manage-3p-secrets_dark.png create mode 100644 website/public/img/why-use-vault/manage-3p-secrets_light.png create mode 100644 website/public/img/why-use-vault/manage-certificates_dark.png create mode 100644 website/public/img/why-use-vault/manage-certificates_light.png create mode 100644 website/public/img/why-use-vault/manage-identities_dark.png create mode 100644 website/public/img/why-use-vault/manage-identities_light.png create mode 100644 website/public/img/why-use-vault/manage-static-secrets_dark.png create mode 100644 website/public/img/why-use-vault/manage-static-secrets_light.png create mode 100644 website/public/img/why-use-vault/regulatory-compliance_dark.png create mode 100644 website/public/img/why-use-vault/regulatory-compliance_light.png create mode 100644 website/public/img/why-use-vault/secure-sensitive-data_dark.png create mode 100644 website/public/img/why-use-vault/secure-sensitive-data_light.png diff --git a/website/content/api-docs/auth/aws.mdx b/website/content/api-docs/auth/aws.mdx index d8f4662507..bd1a55f352 100644 --- a/website/content/api-docs/auth/aws.mdx +++ b/website/content/api-docs/auth/aws.mdx @@ -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 diff --git a/website/content/cli/commands/agent/generate-config.mdx b/website/content/cli/commands/agent/generate-config.mdx new file mode 100644 index 0000000000..d8942d456f --- /dev/null +++ b/website/content/cli/commands/agent/generate-config.mdx @@ -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). + + + +```shell-session +$ vault agent generate-config -type [options] [] +``` + + + +## 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. + + + + - None + + + +### Limitations and warnings + +Limitations: + +- Plugin support limited to KV plugins. +- Configuration type limited to environment variable templates. + + + + 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. + + + +## Arguments + +
+ +@include 'cli/agent/args/file_path.mdx' + + + +## Options + +None. + + + +## Command Flags + +
+ +@include 'cli/agent/flags/exec.mdx' + +


+ +@include 'cli/agent/flags/path.mdx' + +


+ +@include 'cli/agent/flags/type.mdx' + + + +## Global flags + +
+ +@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/*" +``` \ No newline at end of file diff --git a/website/content/cli/commands/agent/index.mdx b/website/content/cli/commands/agent/index.mdx new file mode 100644 index 0000000000..6b60b4d82f --- /dev/null +++ b/website/content/cli/commands/agent/index.mdx @@ -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. + + + +```shell-session +$ vault agent -config + +$ vault agent [-help | -h] +``` + + + +## Description + +`vault agent` start an instance of Vault Agent, which automatically +authenticates and fetches secrets for client applications. + + + + **None** + + + +## Command arguments + +None. + +## Command options + +None. + +## Command flags + +
+ +@include 'cli/agent/flags/config.mdx' + +


+ +@include 'cli/agent/flags/exit-after-auth.mdx' + +


+ +@include 'cli/shared/flags/log-file.mdx' + +


+ +@include 'cli/shared/flags/log-format.mdx' + +


+ +@include 'cli/shared/flags/log-level.mdx' + +


+ +@include 'cli/shared/flags/log-rotate-bytes.mdx' + +


+ +@include 'cli/shared/flags/log-rotate-duration.mdx' + +


+ +@include 'cli/shared/flags/log-rotate-max-files.mdx' + +## Standard flags + +
+ +@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/ +``` \ No newline at end of file diff --git a/website/content/cli/commands/audit/disable.mdx b/website/content/cli/commands/audit/disable.mdx new file mode 100644 index 0000000000..0eb0aea58e --- /dev/null +++ b/website/content/cli/commands/audit/disable.mdx @@ -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. + + + +```shell-session +$ vault audit disable [flags] + +$ vault audit disable [-help | -h] +``` + + + +## 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. + + + + DisableAuditDevice - [`DELETE:/sys/audit/{mount-path}`](/vault/api-docs/system/audit#disable-audit-device) + + + +### 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 + +
+ +@include 'cli/audit/args/device_path.mdx' + +## Command options + +- None + +## Command flags + +- None + +## Standard flags + +
+ +@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/ +``` \ No newline at end of file diff --git a/website/content/cli/commands/audit/enable.mdx b/website/content/cli/commands/audit/enable.mdx new file mode 100644 index 0000000000..711a7901ff --- /dev/null +++ b/website/content/cli/commands/audit/enable.mdx @@ -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. + + + +```shell-session +$ vault audit enable [flags] [options] [...] + +$ vault audit enable [-help | -h] +``` + + + +## 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. + + + + EnableAuditDevice - [`POST:/sys/audit/{mount-path}`](/vault/api-docs/system/audit#enable-audit-device) + + + + + +## Command arguments + +@include 'cli/audit/args/device_type.mdx' + +Each audit device type also has a set of configuration arguments: + + + + + + + +```shell-session +$ vault audit enable [flags] file [options] \ + file_path= \ + [mode=] +``` + + + +
+ +@include 'cli/audit/args/file/file_path.mdx' + +


+ +@include 'cli/audit/args/file/mode.mdx' + +
+ + + + + +```shell-session +$ vault audit enable [flags] socket [options] \ + [address=] \ + [socket_type=] \ + [write_timeout=] +``` + + + +
+ +@include 'cli/audit/args/socket/address.mdx' + +


+ +@include 'cli/audit/args/socket/socket_type.mdx' + +


+ +@include 'cli/audit/args/socket/write_timeout.mdx' + +
+ + + + + +```shell-session +$ vault audit enable [flags] syslog [options] \ + [facility=] \ + [tag=] +``` + + + +
+ +@include 'cli/audit/args/syslog/facility.mdx' + +


+ +@include 'cli/audit/args/syslog/tag.mdx' + +
+ +
+ +## Command options + +
+ +@include 'cli/audit/options/elide_list_responses.mdx' + +


+ +@include 'cli/audit/options/exclude.mdx' + +


+ +@include 'cli/audit/options/fallback.mdx' + +


+ +@include 'cli/audit/options/filter.mdx' + +


+ +@include 'cli/audit/options/format.mdx' + +


+ +@include 'cli/audit/options/hmac_accessor.mdx' + +


+ +@include 'cli/audit/options/log_raw.mdx' + +


+ +@include 'cli/audit/options/prefix.mdx' + +## Command flags + +
+ +@include 'cli/audit/flags/description.mdx' + +


+ +@include 'cli/audit/flags/local.mdx' + +


+ +@include 'cli/audit/flags/path.mdx' + +## Standard flags + +
+ +@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/ +``` + diff --git a/website/content/cli/commands/audit/list.mdx b/website/content/cli/commands/audit/list.mdx new file mode 100644 index 0000000000..22afcc67fe --- /dev/null +++ b/website/content/cli/commands/audit/list.mdx @@ -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. + + + +```shell-session +$ vault audit list [flags] + +$ vault audit list [-help | -h] +``` + + + +## Description + +`vault audit list` displays information about active audit devices. + + + + ListAuditDevices - [`GET:/sys/audit`](/vault/api-docs/system/audit#list-enabled-audit-devices) + + + +## Command arguments + +None. + +## Command options + +None. + +## Command flags + +
+ +@include 'cli/audit/flags/detailed.mdx' + +## Standard flags + +
+ +@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 +``` \ No newline at end of file diff --git a/website/content/cli/commands/auth/disable.mdx b/website/content/cli/commands/auth/disable.mdx new file mode 100644 index 0000000000..fd451aa465 --- /dev/null +++ b/website/content/cli/commands/auth/disable.mdx @@ -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. diff --git a/website/content/cli/commands/auth/enable.mdx b/website/content/cli/commands/auth/enable.mdx new file mode 100644 index 0000000000..ccf24c9839 --- /dev/null +++ b/website/content/cli/commands/auth/enable.mdx @@ -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/`. + +- `-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. diff --git a/website/content/cli/commands/auth/help.mdx b/website/content/cli/commands/auth/help.mdx new file mode 100644 index 0000000000..3bb4adb736 --- /dev/null +++ b/website/content/cli/commands/auth/help.mdx @@ -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. diff --git a/website/content/cli/commands/auth/index.mdx b/website/content/cli/commands/auth/index.mdx new file mode 100644 index 0000000000..5e7d73a7bc --- /dev/null +++ b/website/content/cli/commands/auth/index.mdx @@ -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 [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. diff --git a/website/content/cli/commands/auth/list.mdx b/website/content/cli/commands/auth/list.mdx new file mode 100644 index 0000000000..3ac64313da --- /dev/null +++ b/website/content/cli/commands/auth/list.mdx @@ -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. diff --git a/website/content/cli/commands/auth/move.mdx b/website/content/cli/commands/auth/move.mdx new file mode 100644 index 0000000000..6961e03e05 --- /dev/null +++ b/website/content/cli/commands/auth/move.mdx @@ -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 diff --git a/website/content/cli/commands/auth/tune.mdx b/website/content/cli/commands/auth/tune.mdx new file mode 100644 index 0000000000..248d271474 --- /dev/null +++ b/website/content/cli/commands/auth/tune.mdx @@ -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. + + + +The argument corresponds to the **path** where the auth method is +enabled, not the auth **type**. + + + +## 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. + + + +```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 +``` + + + +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. + + + +```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 +``` + + + +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/`. + + + +```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 +``` + + + + +## 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. + diff --git a/website/content/cli/commands/debug.mdx b/website/content/cli/commands/debug.mdx new file mode 100644 index 0000000000..12e880bd9d --- /dev/null +++ b/website/content/cli/commands/debug.mdx @@ -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. diff --git a/website/content/cli/commands/delete.mdx b/website/content/cli/commands/delete.mdx new file mode 100644 index 0000000000..57ea7cd495 --- /dev/null +++ b/website/content/cli/commands/delete.mdx @@ -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. diff --git a/website/content/cli/commands/events.mdx b/website/content/cli/commands/events.mdx new file mode 100644 index 0000000000..51a91c81be --- /dev/null +++ b/website/content/cli/commands/events.mdx @@ -0,0 +1,102 @@ +--- +layout: docs +page_title: events - Command +description: |- + The "events" command interacts with the Vault events notifications subsystem. +--- + +# events + + + +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. + + + 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 Secure multi-tenancy with + namespacestutorial for configuring your Vault instance appropriately. + + +- `-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 + ``` diff --git a/website/content/cli/commands/hcp/connect.mdx b/website/content/cli/commands/hcp/connect.mdx new file mode 100644 index 0000000000..6430287c88 --- /dev/null +++ b/website/content/cli/commands/hcp/connect.mdx @@ -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 . 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. diff --git a/website/content/cli/commands/hcp/disconnect.mdx b/website/content/cli/commands/hcp/disconnect.mdx new file mode 100644 index 0000000000..c8db929afc --- /dev/null +++ b/website/content/cli/commands/hcp/disconnect.mdx @@ -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. diff --git a/website/content/cli/commands/hcp/index.mdx b/website/content/cli/commands/hcp/index.mdx new file mode 100644 index 0000000000..52e2776936 --- /dev/null +++ b/website/content/cli/commands/hcp/index.mdx @@ -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 . Please continue the login in the web browser. +Success! +``` + +Disconnect from HCP: +```shell-session +$ vault hcp disconnect +``` diff --git a/website/content/cli/commands/kv/delete.mdx b/website/content/cli/commands/kv/delete.mdx new file mode 100644 index 0000000000..3ddcfd3c55 --- /dev/null +++ b/website/content/cli/commands/kv/delete.mdx @@ -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: )` - 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. diff --git a/website/content/cli/commands/kv/destroy.mdx b/website/content/cli/commands/kv/destroy.mdx new file mode 100644 index 0000000000..e7d3b8816f --- /dev/null +++ b/website/content/cli/commands/kv/destroy.mdx @@ -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: )` - The versions to destroy. Their data will + be permanently deleted. diff --git a/website/content/cli/commands/kv/enable-versioning.mdx b/website/content/cli/commands/kv/enable-versioning.mdx new file mode 100644 index 0000000000..98cb3d03ac --- /dev/null +++ b/website/content/cli/commands/kv/enable-versioning.mdx @@ -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. diff --git a/website/content/cli/commands/kv/get.mdx b/website/content/cli/commands/kv/get.mdx new file mode 100644 index 0000000000..c20e29afd9 --- /dev/null +++ b/website/content/cli/commands/kv/get.mdx @@ -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 +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. diff --git a/website/content/cli/commands/kv/index.mdx b/website/content/cli/commands/kv/index.mdx new file mode 100644 index 0000000000..7eac7f0315 --- /dev/null +++ b/website/content/cli/commands/kv/index.mdx @@ -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 +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 +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 +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 +deletion_time n/a +destroyed false +version 1 + +====== Data ====== +Key Value +--- ----- +passcode my-long-passcode +``` + +## Usage + +```text +Usage: vault kv [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. diff --git a/website/content/cli/commands/kv/list.mdx b/website/content/cli/commands/kv/list.mdx new file mode 100644 index 0000000000..c28c0cc154 --- /dev/null +++ b/website/content/cli/commands/kv/list.mdx @@ -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. diff --git a/website/content/cli/commands/kv/metadata.mdx b/website/content/cli/commands/kv/metadata.mdx new file mode 100644 index 0000000000..c1c571845d --- /dev/null +++ b/website/content/cli/commands/kv/metadata.mdx @@ -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 [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. diff --git a/website/content/cli/commands/kv/patch.mdx b/website/content/cli/commands/kv/patch.mdx new file mode 100644 index 0000000000..c0f87e47d2 --- /dev/null +++ b/website/content/cli/commands/kv/patch.mdx @@ -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. diff --git a/website/content/cli/commands/kv/put.mdx b/website/content/cli/commands/kv/put.mdx new file mode 100644 index 0000000000..4384a2942b --- /dev/null +++ b/website/content/cli/commands/kv/put.mdx @@ -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. diff --git a/website/content/cli/commands/kv/rollback.mdx b/website/content/cli/commands/kv/rollback.mdx new file mode 100644 index 0000000000..58897c1e33 --- /dev/null +++ b/website/content/cli/commands/kv/rollback.mdx @@ -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. diff --git a/website/content/cli/commands/kv/undelete.mdx b/website/content/cli/commands/kv/undelete.mdx new file mode 100644 index 0000000000..5933b00cca --- /dev/null +++ b/website/content/cli/commands/kv/undelete.mdx @@ -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: )` - Specifies the version number that should + be made current again. diff --git a/website/content/cli/commands/lease/index.mdx b/website/content/cli/commands/lease/index.mdx new file mode 100644 index 0000000000..b1de95902f --- /dev/null +++ b/website/content/cli/commands/lease/index.mdx @@ -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 +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 [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. diff --git a/website/content/cli/commands/lease/lookup.mdx b/website/content/cli/commands/lease/lookup.mdx new file mode 100644 index 0000000000..6d9aed6d3c --- /dev/null +++ b/website/content/cli/commands/lease/lookup.mdx @@ -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 +renewable true +ttl 9m52s +``` + +## Usage + +There are no flags beyond the [standard set of flags](/vault/docs/commands) +included on all commands. diff --git a/website/content/cli/commands/lease/renew.mdx b/website/content/cli/commands/lease/renew.mdx new file mode 100644 index 0000000000..f90ec757d7 --- /dev/null +++ b/website/content/cli/commands/lease/renew.mdx @@ -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. diff --git a/website/content/cli/commands/lease/revoke.mdx b/website/content/cli/commands/lease/revoke.mdx new file mode 100644 index 0000000000..dc8618fc8d --- /dev/null +++ b/website/content/cli/commands/lease/revoke.mdx @@ -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. diff --git a/website/content/cli/commands/license/get.mdx b/website/content/cli/commands/license/get.mdx new file mode 100644 index 0000000000..afddfbc51c --- /dev/null +++ b/website/content/cli/commands/license/get.mdx @@ -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. diff --git a/website/content/cli/commands/license/index.mdx b/website/content/cli/commands/license/index.mdx new file mode 100644 index 0000000000..4ebe8c193b --- /dev/null +++ b/website/content/cli/commands/license/index.mdx @@ -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 [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. diff --git a/website/content/cli/commands/license/inspect.mdx b/website/content/cli/commands/license/inspect.mdx new file mode 100644 index 0000000000..40b973e13a --- /dev/null +++ b/website/content/cli/commands/license/inspect.mdx @@ -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 diff --git a/website/content/cli/commands/list.mdx b/website/content/cli/commands/list.mdx new file mode 100644 index 0000000000..9caed719a0 --- /dev/null +++ b/website/content/cli/commands/list.mdx @@ -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. diff --git a/website/content/cli/commands/login.mdx b/website/content/cli/commands/login.mdx new file mode 100644 index 0000000000..58070604b3 --- /dev/null +++ b/website/content/cli/commands/login.mdx @@ -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. diff --git a/website/content/cli/commands/monitor.mdx b/website/content/cli/commands/monitor.mdx new file mode 100644 index 0000000000..60a62e8259 --- /dev/null +++ b/website/content/cli/commands/monitor.mdx @@ -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`. + + + +```shell-session +$ vault monitor [flags] + +$ vault monitor [-help | -h] +``` + + + +## 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. + + + +MonitorLogs - [`GET: /sys/monitor`](/vault/api-docs/system/monitor) + + + + +### 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 + +
+ +@include 'cli/shared/flags/log-level.mdx' + +


+ +@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 +``` diff --git a/website/content/cli/commands/namespace.mdx b/website/content/cli/commands/namespace.mdx new file mode 100644 index 0000000000..d52a3fa88a --- /dev/null +++ b/website/content/cli/commands/namespace.mdx @@ -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 the API for a descendant namespace at path `current/namespacens1/`: + +```shell-session +$ vault namespace unlock -unlock-key ns1/ +``` + +## Usage + +```text +Usage: vault namespace [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. diff --git a/website/content/cli/commands/operator/diagnose.mdx b/website/content/cli/commands/operator/diagnose.mdx new file mode 100644 index 0000000000..65d780ec95 --- /dev/null +++ b/website/content/cli/commands/operator/diagnose.mdx @@ -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/`, 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. diff --git a/website/content/cli/commands/operator/generate-root.mdx b/website/content/cli/commands/operator/generate-root.mdx new file mode 100644 index 0000000000..429f17bafd --- /dev/null +++ b/website/content/cli/commands/operator/generate-root.mdx @@ -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:`. 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 diff --git a/website/content/cli/commands/operator/import.mdx b/website/content/cli/commands/operator/import.mdx new file mode 100644 index 0000000000..8144b1c927 --- /dev/null +++ b/website/content/cli/commands/operator/import.mdx @@ -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. + + + +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. + + + +## Examples + +Read the config file `import.hcl` to generate a new import plan: + +```shell-session +$ vault operator import -config import.hcl plan +``` + +Output: + + + + ----------- + 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 + + + +## 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: )` - Automatically responds "yes" to all user-input prompts for the `apply` command. + +- `-auto-create` `(bool: )` - 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. diff --git a/website/content/cli/commands/operator/index.mdx b/website/content/cli/commands/operator/index.mdx new file mode 100644 index 0000000000..f5e29c04bb --- /dev/null +++ b/website/content/cli/commands/operator/index.mdx @@ -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 [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. diff --git a/website/content/cli/commands/operator/init.mdx b/website/content/cli/commands/operator/init.mdx new file mode 100644 index 0000000000..d8b3558b55 --- /dev/null +++ b/website/content/cli/commands/operator/init.mdx @@ -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:`. 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:`. 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. diff --git a/website/content/cli/commands/operator/key-status.mdx b/website/content/cli/commands/operator/key-status.mdx new file mode 100644 index 0000000000..e39545e744 --- /dev/null +++ b/website/content/cli/commands/operator/key-status.mdx @@ -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. diff --git a/website/content/cli/commands/operator/members.mdx b/website/content/cli/commands/operator/members.mdx new file mode 100644 index 0000000000..1b9029fef1 --- /dev/null +++ b/website/content/cli/commands/operator/members.mdx @@ -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. diff --git a/website/content/cli/commands/operator/migrate.mdx b/website/content/cli/commands/operator/migrate.mdx new file mode 100644 index 0000000000..111db24718 --- /dev/null +++ b/website/content/cli/commands/operator/migrate.mdx @@ -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: )` - 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`). diff --git a/website/content/cli/commands/operator/raft.mdx b/website/content/cli/commands/operator/raft.mdx new file mode 100644 index 0000000000..59fa0ead31 --- /dev/null +++ b/website/content/cli/commands/operator/raft.mdx @@ -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 [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] + + 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] + 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 + + Removes a node from the Raft cluster. + + $ vault operator raft remove-peer node1 +``` + + + 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. + + +## 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 [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 + + 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 + + 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 +``` + +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 [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. + + + + 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 + + + +- `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. diff --git a/website/content/cli/commands/operator/rekey.mdx b/website/content/cli/commands/operator/rekey.mdx new file mode 100644 index 0000000000..c9fa922dc0 --- /dev/null +++ b/website/content/cli/commands/operator/rekey.mdx @@ -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:`. 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. diff --git a/website/content/cli/commands/operator/rotate.mdx b/website/content/cli/commands/operator/rotate.mdx new file mode 100644 index 0000000000..671b64ffe0 --- /dev/null +++ b/website/content/cli/commands/operator/rotate.mdx @@ -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 232 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. diff --git a/website/content/cli/commands/operator/seal.mdx b/website/content/cli/commands/operator/seal.mdx new file mode 100644 index 0000000000..9edbb885a0 --- /dev/null +++ b/website/content/cli/commands/operator/seal.mdx @@ -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. diff --git a/website/content/cli/commands/operator/step-down.mdx b/website/content/cli/commands/operator/step-down.mdx new file mode 100644 index 0000000000..4726318cb3 --- /dev/null +++ b/website/content/cli/commands/operator/step-down.mdx @@ -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"] +} +``` diff --git a/website/content/cli/commands/operator/unseal.mdx b/website/content/cli/commands/operator/unseal.mdx new file mode 100644 index 0000000000..700224ace7 --- /dev/null +++ b/website/content/cli/commands/operator/unseal.mdx @@ -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. diff --git a/website/content/cli/commands/operator/usage.mdx b/website/content/cli/commands/operator/usage.mdx new file mode 100644 index 0000000000..32d321c744 --- /dev/null +++ b/website/content/cli/commands/operator/usage.mdx @@ -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. diff --git a/website/content/cli/commands/operator/utilization.mdx b/website/content/cli/commands/operator/utilization.mdx new file mode 100644 index 0000000000..eb639d2010 --- /dev/null +++ b/website/content/cli/commands/operator/utilization.mdx @@ -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. + + + +Refer to the [manual license utilization +reporting](/vault/docs/enterprise/license/manual-reporting) page to learn more +about reporting your Vault Enterprise license utilization. + + + +## Examples + +Create a license utilization bundle that includes all persisted historical +snapshots and has the default bundle name +(`vault-utilization-.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:** + + + +```plaintext +Success! License utilization reporting bundle written to: /utilization/reports/latest.json +``` + + + +The message, `Change Control 654987`, is included in the _server log_, but not +in the bundle. + +**Example entry in the server log:** + + + +```plaintext +[INFO] reporting: generating license utilization bundle +[INFO] reporting: generating license utilization bundle: message="Change Control 654987" +``` + + + +## 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. diff --git a/website/content/cli/commands/patch.mdx b/website/content/cli/commands/patch.mdx new file mode 100644 index 0000000000..882f64025d --- /dev/null +++ b/website/content/cli/commands/patch.mdx @@ -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 -<` 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. diff --git a/website/content/cli/commands/pki/health-check.mdx b/website/content/cli/commands/pki/health-check.mdx new file mode 100644 index 0000000000..4b237db091 --- /dev/null +++ b/website/content/cli/commands/pki/health-check.mdx @@ -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 /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 /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`. + + + +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`. + + + + +**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 \ + +``` + +### 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" \ + + ``` + +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" \ + + ``` + +### 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 /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 /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 /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 /tidy-status + ```` +1. Schedule a manual run of tidy with `vault write`: + ```shell-session + $ vault write /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" \ + +``` diff --git a/website/content/cli/commands/pki/index.mdx b/website/content/cli/commands/pki/index.mdx new file mode 100644 index 0000000000..0a98b34e0b --- /dev/null +++ b/website/content/cli/commands/pki/index.mdx @@ -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 ` 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 ` 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 ` 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 ` 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