mirror of
https://github.com/hashicorp/vault.git
synced 2026-04-29 10:09:01 -04:00
Docs for license autoloading. (#11886)
This commit is contained in:
Nick Cabatoff
GitHub
parent
abf1dd776d
commit
ec91c24ab5
9 changed files with 374 additions and 6 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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: <required>)` – The text of the license.
|
||||
- `text` `(string: <required>)` – The text of the license.
|
||||
|
||||
_DR Secondary Specific Parameters_
|
||||
|
||||
- `dr_operation_token` `(string: <required>)` - 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"
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
51
website/content/docs/commands/license/get.mdx
Normal file
51
website/content/docs/commands/license/get.mdx
Normal file
|
|
@ -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.
|
||||
67
website/content/docs/commands/license/index.mdx
Normal file
67
website/content/docs/commands/license/index.mdx
Normal file
|
|
@ -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 <subcommand> [options] [args]
|
||||
|
||||
# ...
|
||||
|
||||
Subcommands:
|
||||
get Query Vault's license
|
||||
inspect View the contents of a license string
|
||||
```
|
||||
|
||||
For more information, examples, and usage about a subcommand, click on the name
|
||||
of the subcommand in the sidebar.
|
||||
56
website/content/docs/commands/license/inspect.mdx
Normal file
56
website/content/docs/commands/license/inspect.mdx
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
30
website/content/docs/enterprise/license/autoloading.mdx
Normal file
30
website/content/docs/enterprise/license/autoloading.mdx
Normal file
|
|
@ -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.
|
||||
|
|
@ -481,6 +481,23 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "<code>license</code>",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "commands/license"
|
||||
},
|
||||
{
|
||||
"title": "<code>get</code>",
|
||||
"path": "commands/license/get"
|
||||
},
|
||||
{
|
||||
"title": "<code>inspect</code>",
|
||||
"path": "commands/license/inspect"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "<code>list</code>",
|
||||
"path": "commands/list"
|
||||
|
|
@ -1614,6 +1631,10 @@
|
|||
"title": "Overview",
|
||||
"path": "enterprise/license"
|
||||
},
|
||||
{
|
||||
"title": "Autoloading",
|
||||
"path": "enterprise/license/autoloading"
|
||||
},
|
||||
{
|
||||
"title": "FAQs",
|
||||
"path": "enterprise/license/faqs"
|
||||
|
|
|
|||
Loading…
Reference in a new issue