From ec91c24ab5b98d09764800eab0492eb72f034efa Mon Sep 17 00:00:00 2001 From: Nick Cabatoff Date: Fri, 18 Jun 2021 18:19:18 +0200 Subject: [PATCH] Docs for license autoloading. (#11886) --- .../content/api-docs/system/config-reload.mdx | 10 +- website/content/api-docs/system/license.mdx | 130 +++++++++++++++++- website/content/docs/commands/index.mdx | 11 ++ website/content/docs/commands/license/get.mdx | 51 +++++++ .../content/docs/commands/license/index.mdx | 67 +++++++++ .../content/docs/commands/license/inspect.mdx | 56 ++++++++ website/content/docs/configuration/index.mdx | 4 + .../docs/enterprise/license/autoloading.mdx | 30 ++++ website/data/docs-nav-data.json | 21 +++ 9 files changed, 374 insertions(+), 6 deletions(-) create mode 100644 website/content/docs/commands/license/get.mdx create mode 100644 website/content/docs/commands/license/index.mdx create mode 100644 website/content/docs/commands/license/inspect.mdx create mode 100644 website/content/docs/enterprise/license/autoloading.mdx diff --git a/website/content/api-docs/system/config-reload.mdx b/website/content/api-docs/system/config-reload.mdx index 8cbded1e01..f69bec60a7 100644 --- a/website/content/api-docs/system/config-reload.mdx +++ b/website/content/api-docs/system/config-reload.mdx @@ -19,9 +19,13 @@ Currently, it only supports reloading license information from files on disk. ## Reload License File -When the `:subsystem` URL parameter is specified as `license`, Vault re-reads the license file pointed to by the `license_path` configuration option and applies the license -to Vault. Vault may enable or disable various features when this happens, depending on if the features of the given -license have changed from the license Vault is currently using. +~> **Enterprise Only** – This endpoint requires Vault Enterprise. + +When the `:subsystem` URL parameter is specified as `license`, Vault re-reads +the license file if the license was provided using the `license_path` configuration +option or the `VAULT_LICENSE_PATH` environment variable. The updated license is +applied to Vault, and Vault will then enable/disable licensed features if the features +of the given license are different from those of the license Vault is currently using. ### Sample Request diff --git a/website/content/api-docs/system/license.mdx b/website/content/api-docs/system/license.mdx index bd31a6c624..fe44c5eb87 100644 --- a/website/content/api-docs/system/license.mdx +++ b/website/content/api-docs/system/license.mdx @@ -8,13 +8,17 @@ description: |- # `/sys/license` -~> **Enterprise Only** – These endpoints require Vault Enterprise. +~> **Enterprise Only** – These endpoints require Vault Enterprise. The `/sys/license` endpoint is used to view and update the license used in Vault. ## Read License +~> This API is deprecated and will be removed in a future version of Vault. +Please use [license autoloading](/docs/enterprise/license/autoloading) instead, +and see [License Status](#license-status) below for the non-deprecated equivalent API. + This endpoint returns information about the currently installed license. | Method | Path | @@ -45,6 +49,9 @@ $ curl \ ## Read Signed License +~> This API is deprecated and will be removed in a future version of Vault. +Please use [license autoloading](/docs/enterprise/license/autoloading) instead. + This endpoint returns the signed license blob for the currently installed license. | Method | Path | @@ -71,7 +78,11 @@ $ curl \ ## Install License -This endpoint is used to install a license into Vault. +~> This API is deprecated and will be removed in a future version of Vault. +Please use [license autoloading](/docs/enterprise/license/autoloading) instead. + +This endpoint is used to install a license into Vault. This will return an +error if license autoloading is in use. | Method | Path | | :----- | :------------- | @@ -79,11 +90,14 @@ This endpoint is used to install a license into Vault. ### Parameters -- `text` `(string: )` – The text of the license. +- `text` `(string: )` – The text of the license. _DR Secondary Specific Parameters_ - `dr_operation_token` `(string: )` - DR operation token used to authorize this request. +Note that this is the legacy mechanism for providing a DR operation token. It is +equally valid to provide the DR operation token in the `X-Vault-Token` header, as +with a regular vault token. ### Sample Payload @@ -102,3 +116,113 @@ $ curl \ --data @payload.json \ http://127.0.0.1:8200/v1/sys/license ``` + +## Delete License + +~> This API is deprecated and will be removed in a future version of Vault. +Please use [license autoloading](/docs/enterprise/license/autoloading) instead. + +This endpoint is used to delete a stored license in Vault. This will return +an error unless license autoloading is in use. + +| Method | Path | +| :----- | :------------- | +| `DELETE` | `/sys/license` | + + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/sys/license +``` + +## License Status + +This endpoint returns information about licensing. It returns similar information +to a GET of `sys/license`, but whereas that endpoint reports solely on the +license Vault is currently using, this one reports on all licensing +information the Vault cluster has. See +[license autoloading](/docs/enterprise/license/autoloading) for background. + +In the response: +* `autoloading_used` will be true if an autoloaded license was provided to the + node, false otherwise. +* `autoloaded` is the autoloaded license if autoloading_used is true. +* `persisted_autoload` is the autoloaded license the active node last wrote to + storage; this is only used to detect inconsistently licensed nodes in the + cluster. It cannot be used as a license itself. +* `stored` is the stored license if any, i.e. one written using `PUT sys/license`. + +`autoloaded`, `persisted_autoload`, and `stored` all have the same structure, +which is also the same structure as the top-level `data` returned by `GET sys/license`. + +| Method | Path | +| :----- | :------------- | +| `GET` | `/sys/license/status` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/license/status +``` + +### Sample Response + +```json +{ + "data": { + "autoloading_used": true, + "autoloaded": { + "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" + }, + "persisted_autoload": { + "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" + } + }, +} +``` diff --git a/website/content/docs/commands/index.mdx b/website/content/docs/commands/index.mdx index 56049b4a62..526808e303 100644 --- a/website/content/docs/commands/index.mdx +++ b/website/content/docs/commands/index.mdx @@ -246,6 +246,17 @@ when in High Availability mode. Provide Vault output (read/status/write) in the specified format. Valid formats are "table", "json", or "yaml". +### `VAULT_LICENSE` + +[Enterprise, Server only] Specify a license to use for this node. This takes +precedence over [#VAULT_LICENSE_PATH](#vault_license_path) and +[license_path in config](/docs/configuration#license_path). + +### `VAULT_LICENSE_PATH` + +[Enterprise, Server only] Specify a path to a license on disk to use for this node. +This takes precedence over [license_path in config](/docs/configuration#license_path). + ### `VAULT_MAX_RETRIES` Maximum number of retries when a `5xx` error code is encountered. The default is diff --git a/website/content/docs/commands/license/get.mdx b/website/content/docs/commands/license/get.mdx new file mode 100644 index 0000000000..56ac668b54 --- /dev/null +++ b/website/content/docs/commands/license/get.mdx @@ -0,0 +1,51 @@ +--- +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](/docs/enterprise/license/autoloading). + +## Examples + +Describe current license: + +```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 +``` + +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](/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/docs/commands/license/index.mdx b/website/content/docs/commands/license/index.mdx new file mode 100644 index 0000000000..77ebf6862b --- /dev/null +++ b/website/content/docs/commands/license/index.mdx @@ -0,0 +1,67 @@ +--- +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](/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 +``` + +Query signed license string (only when using a deprecated stored license) + +```shell-session +$ vault license get -signed +02MV4UU43BK5H... +``` + +Inspect a signed 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/docs/commands/license/inspect.mdx b/website/content/docs/commands/license/inspect.mdx new file mode 100644 index 0000000000..03b1804e9b --- /dev/null +++ b/website/content/docs/commands/license/inspect.mdx @@ -0,0 +1,56 @@ +--- +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 +{"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 +{"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](/docs/commands) included on all commands. + +### Command Options + +- `-installation-id` `(string: "")` - Installation ID to validate the license against diff --git a/website/content/docs/configuration/index.mdx b/website/content/docs/configuration/index.mdx index f61aad3234..fb66eee3a3 100644 --- a/website/content/docs/configuration/index.mdx +++ b/website/content/docs/configuration/index.mdx @@ -204,6 +204,10 @@ The following parameters are only used with Vault Enterprise node will disable this feature when this node is Active or Standby. It's recommended to sync this setting across all nodes in the cluster. +- `license_path` `(string: "")` - Path to license file. This can also be + provided via the environment variable `VAULT_LICENSE_PATH`, or the license + itself can be provided in the environment variable `VAULT_LICENSE`. + [storage-backend]: /docs/configuration/storage [listener]: /docs/configuration/listener [seal]: /docs/configuration/seal diff --git a/website/content/docs/enterprise/license/autoloading.mdx b/website/content/docs/enterprise/license/autoloading.mdx new file mode 100644 index 0000000000..99e4433b7a --- /dev/null +++ b/website/content/docs/enterprise/license/autoloading.mdx @@ -0,0 +1,30 @@ +--- +layout: docs +page_title: License Autoloading +description: An overview of license autoloading. +--- + +Prior to Vault 1.8, Vault Enterprise would be licensed using special binaries +that contained embedded licenses, or via a license written into Vault storage +using the [PUT sys/license API](/docs/system/license#install-license). + +As of Vault 1.8 those options still exist but are deprecated, and the recommended +mechanism for managing licenses is called License Autoloading. New clusters are +required to use the autoloading method. + +License Autoloading can be done using one of these mechanisms, in increasing order +of priority (i.e. `VAULT_LICENSE` takes precedence over `VAULT_LICENSE_PATH`, which +takes precedence over `license_path` in config.) +* [license_path in config](/docs/configuration#license_path) +* [VAULT_LICENSE_PATH environment variable](/docs/commands#vault_license_path) +* [VAULT_LICENSE environment variable](/docs/commands#vault_license) + +Nodes within a cluster should be consistently licensed. All nodes in a cluster +should use autoloading, or none should. If autoloading is used, all nodes should +use the same license string. Warnings will be written to the log when there +are discrepancies. + +If autoloading is used, any existing stored license will be ignored. The presence +of a stored license in conjunction with an autoloaded license will also result in +logged warnings. Once a migration to autoloading is completed, it is recommended to use +the [DELETE API](/docs/system/license#delete-license) to remove the stored license. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index bebeab4562..ce745c6d52 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -481,6 +481,23 @@ } ] }, + { + "title": "license", + "routes": [ + { + "title": "Overview", + "path": "commands/license" + }, + { + "title": "get", + "path": "commands/license/get" + }, + { + "title": "inspect", + "path": "commands/license/inspect" + } + ] + }, { "title": "list", "path": "commands/list" @@ -1614,6 +1631,10 @@ "title": "Overview", "path": "enterprise/license" }, + { + "title": "Autoloading", + "path": "enterprise/license/autoloading" + }, { "title": "FAQs", "path": "enterprise/license/faqs"