132 lines
6.3 KiB
Plaintext
132 lines
6.3 KiB
Plaintext
|
[[license-management]]
|
|||
|
|
== Appendix 2. License Management
|
|||
|
|
|
|||
|
|
[float]
|
|||
|
|
==== Installing The License Plugin
|
|||
|
|
|
|||
|
|
To install the license plugin, you'll need to run the following command:
|
|||
|
|
|
|||
|
|
[source,shell]
|
|||
|
|
----------------------------------------------------------
|
|||
|
|
bin/plugin -i elasticsearch/license/latest
|
|||
|
|
----------------------------------------------------------
|
|||
|
|
|
|||
|
|
If your server doesn’t have direct Internet access, it is also possible to download the plugin separately and install
|
|||
|
|
it manually by following these steps:
|
|||
|
|
|
|||
|
|
1. Download the plugin package in https://download.elastic.co/elasticsearch/license/license-latest.zip
|
|||
|
|
|
|||
|
|
2. Transfer the compressed file to your server, then install the plugin using the `bin/plugin` script:
|
|||
|
|
|
|||
|
|
[source,shell]
|
|||
|
|
----------------------------------------------------
|
|||
|
|
bin/plugin -i license -u file://PATH_TO_ZIP_FILE <1>
|
|||
|
|
----------------------------------------------------
|
|||
|
|
<1> URI to license plugin zip distribution file (e.g. `file:///path/to/file/license-latest.zip`,
|
|||
|
|
note the three slashes at the beginning)
|
|||
|
|
|
|||
|
|
[[installing-license]]
|
|||
|
|
[float]
|
|||
|
|
==== Installing A License
|
|||
|
|
|
|||
|
|
When installing Shield for the first time, having the license plugin installed is the minimum required for Shield to work.
|
|||
|
|
You can just start up the node and everything will just work as expected. The first time you start up the node, a 30 days
|
|||
|
|
trial license will automatically be created which will enable Shield to be fully operational. Within these 30 days, you
|
|||
|
|
will be able to replace the trial license with another one that will be provided to you up on purchase. Updating the
|
|||
|
|
license can be done at runtime (no need to shutdown the nodes) using a dedicated API.
|
|||
|
|
|
|||
|
|
IMPORTANT: With a valid license, Shield will be fully operational. Upon license expiry, Shield will operate in a
|
|||
|
|
degraded mode, where cluster health, cluster stats, and index stats APIs will be blocked. All other operations will
|
|||
|
|
continue operating normally. Find out more about <<license-expiration, Shield license expiration>>.
|
|||
|
|
|
|||
|
|
|
|||
|
|
The license itself is a _JSON_ file containing all information about the license (e.g. feature name, expiry date, etc...).
|
|||
|
|
To install or update the license use the following REST API:
|
|||
|
|
|
|||
|
|
[source,shell]
|
|||
|
|
-----------------------------------------------------------------------
|
|||
|
|
curl -XPUT -u admin 'http://<host>:<port>/_licenses' -d @license.json
|
|||
|
|
-----------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
Where:
|
|||
|
|
|
|||
|
|
* `<host>` is the hostname of the elasticsearch node (`localhost` if executing locally)
|
|||
|
|
* `<port>` is the http port (defaults to `9200`)
|
|||
|
|
* `license.json` is the license json file
|
|||
|
|
|
|||
|
|
NOTE: The put license API is protected under the cluster admin privilege, therefore it has to be executed
|
|||
|
|
by a user with the appropriate permissions.
|
|||
|
|
|
|||
|
|
[float]
|
|||
|
|
=== Listing Currently Installed Licenses
|
|||
|
|
|
|||
|
|
You can list all currently installed licenses by executing the following REST API:
|
|||
|
|
|
|||
|
|
[source,shell]
|
|||
|
|
-----------------------------------------------------
|
|||
|
|
curl -XGET -u admin:password 'http://<host>:<port>/_licenses'
|
|||
|
|
-----------------------------------------------------
|
|||
|
|
|
|||
|
|
The response of this command will be a JSON listing all available licenses. In the case of Shield, the following
|
|||
|
|
entry will be shown:
|
|||
|
|
|
|||
|
|
[source,json]
|
|||
|
|
--------------------------------------------
|
|||
|
|
{
|
|||
|
|
licenses: [
|
|||
|
|
...
|
|||
|
|
{
|
|||
|
|
status: "active",
|
|||
|
|
uid: "sample_uid",
|
|||
|
|
type: "sample_type",
|
|||
|
|
subscription_type: "sample_subscription_type",
|
|||
|
|
"issue_date" : "2015-01-26T00:00:00.000Z",
|
|||
|
|
"issue_date_in_millis" : 1422230400000,
|
|||
|
|
feature: "shield",
|
|||
|
|
"expiry_date" : "2015-04-26T23:59:59.999Z",
|
|||
|
|
"expiry_date_in_millis" : 1430092799999,
|
|||
|
|
max_nodes: 1,
|
|||
|
|
issued_to: "sample customer",
|
|||
|
|
issuer: "elasticsearch"
|
|||
|
|
}
|
|||
|
|
...
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
--------------------------------------------
|
|||
|
|
|
|||
|
|
NOTE: The get license API is protected under the cluster admin privilege, therefore it has to be executed
|
|||
|
|
by a user with the appropriate permissions.
|
|||
|
|
|
|||
|
|
[[license-expiration]]
|
|||
|
|
[float]
|
|||
|
|
=== License Expiration
|
|||
|
|
|
|||
|
|
License expiration should never be a surprise. Beginning 30 days from license expiration, Shield will begin logging daily messages
|
|||
|
|
containing the license expiration date and a brief description of unlicensed behavior. Beginning 7 days from license expiration,
|
|||
|
|
Shield will begin logging error messages every 10 minutes with the same information. After expiration, Shield will continue to
|
|||
|
|
log error messages informing you that the license has expired. These messages will also be generated at node startup, to ensure
|
|||
|
|
that there are no surprises. Here is an example message:
|
|||
|
|
|
|||
|
|
[source,sh]
|
|||
|
|
---------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
[ERROR][shield.license] Shield license will expire on 1/1/1970. Cluster health, cluster stats and indices stats operations are
|
|||
|
|
blocked on Shield license expiration. All data operations (read and write) continue to work. If you have a new license, please
|
|||
|
|
update it. Otherwise, please reach out to your support contact.
|
|||
|
|
---------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
When the license for Shield is expired, Shield will block requests to the cluster health, cluster stats, and index stats APIs.
|
|||
|
|
Calls to these APIs will fail with a LicenseExpiredException, and will return HTTP status code 401. By disabling only these APIs,
|
|||
|
|
any automated cluster monitoring should detect the license failure, while users of the cluster should not be immediately impacted.
|
|||
|
|
It is not recommended to run for any length of time with a disabled Shield license; cluster health and stats APIs are critical
|
|||
|
|
for monitoring and management of an Elasticsearch cluster.
|
|||
|
|
|
|||
|
|
Example error response the clients will receive when license is expired and cluster health, cluster stats or index stats APIs are called:
|
|||
|
|
|
|||
|
|
[source,json]
|
|||
|
|
----------------------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
{"error":"LicenseExpiredException[license expired for feature [shield]]","status":401}
|
|||
|
|
----------------------------------------------------------------------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
If you receive a new license file and <<installing-license, install it>>, it will take effect immediately and the health and
|
|||
|
|
stats APIs will be available.
|