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.
|