Appendix 2. License Managementedit

Installing The License Pluginedit

To install the license plugin, you’ll need to run the following command:

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:
bin/plugin -i license -u file://PATH_TO_ZIP_FILE 

URI to license plugin zip distribution file (e.g. file:///path/to/file/license-latest.zip, note the three slashes at the beginning)

Installing A Licenseedit

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.

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

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

The put license API is protected under the cluster admin privilege, therefore it has to be executed by a user with the appropriate permissions.

Listing Currently Installed Licensesedit

You can list all currently installed licenses by executing the following REST API:

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:

{
  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"
    }
    ...
  ]
}

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 Expirationedit

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:

[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:

{"error":"LicenseExpiredException[license expired for feature [shield]]","status":401}

If you receive a new license file and install it, it will take effect immediately and the health and stats APIs will be available.