Managing Shield Licenses

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 Your Shield License

edit

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 Installed Licenses

edit

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 Expiration

edit

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.

« Using Kibana with Shield Example Shield Deployments »