OpenSearch/shield/docs/public/managing-shield-licenses.asciidoc

[[license-management]]
== Managing Your License

When you initially install Shield, a 30 day trial license is installed that allows access to all features. At the end of the trial period, you can https://www.elastic.co/subscriptions/[purchase a subscription] to keep using the full functionality of Shield along with Marvel and Watcher. 

IMPORTANT:  When your license expires, Shield operates in a degraded mode where access to the Elasticsearch cluster health, cluster stats, and index stats APIs is blocked. Shield keeps on protecting your cluster, but you won't be able to monitor its operation until you update your license. For more information, see  <<license-expiration, License Expiration>>.

[float]
[[installing-license]]
=== Updating Your License

You can update your license at runtime without shutting down your nodes. License updates take 
effect immediately. The license is provided as a _JSON_ file that you install with the `license` 
API. You need cluster admin privileges to install the license.

To update your license:

. Send a request to the `license` API and specify the file that contains your new license: 
+
[source,shell]
-----------------------------------------------------------------------
curl -XPUT -u admin 'http://<host>:<port>/_license' -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

. If the license you are installing does not support all of the features available with your
previous license, you will be notified in the response. To complete the license installation, 
you must resubmit the license update request and set the `acknowledge` parameter to `true` to 
indicate that you are aware of the changes.
+
[source,shell]
-----------------------------------------------------------------------
curl -XPUT -u admin 'http://<host>:<port>/_license?acknowledge=true' -d @license.json
-----------------------------------------------------------------------

[float]
[[listing-licenses]]
=== Viewing the Installed License

You can also use the `license` API to retrieve the currently installed license:

[source,shell]
-----------------------------------------------------
curl -XGET -u admin:password 'http://<host>:<port>/_license'
{
  "license" : {
    "status" : "active",
    "uid" : "0a98411f-73f4-4c67-954c-724874ed5488",
    "type" : "trial",
    "issue_date" : "2015-10-13T18:18:20.709Z",
    "issue_date_in_millis" : 1444760300709,
    "expiry_date" : "2015-11-12T18:18:20.709Z",
    "expiry_date_in_millis" : 1447352300709,
    "max_nodes" : 1000,
    "issued_to" : "elasticsearch",
    "issuer" : "elasticsearch"
  }
}
--------------------------------------------

NOTE: You need cluster admin privileges to retrieve the license.

[float]
[[license-expiration]]
=== License Expiration

License expiration should never be a surprise. If you're using Marvel, a license expiration
warning is displayed prominently if your license expires within 30 days. Warnings are 
also displayed on startup and written to the Elasticsearch log starting 30  days from the expiration date. These error messages tell you when the license expires and what features will be disabled if 
you fail to update it:

[source,sh]
--------------------------------------------
# License will expire on [Thursday, November 12, 2015]. If you have a new license, please update it.
# Otherwise, please reach out to your support contact.
# 
# Commercial plugins operate with reduced functionality on license expiration:
# - marvel
#  - The agent will stop collecting cluster and indices metrics
# - shield
#  - Cluster health, cluster stats and indices stats operations are blocked
#  - All data operations (read and write) continue to work
--------------------------------------------

Once the license expires, calls to the cluster health, cluster stats, and index stats APIs 
fail with a `ElasticsearchSecurityException` and return a 401 HTTP status code: 

[source,sh]
--------------------------------------------
{
  "error": {
    "root_cause": [{
      "type": "security_exception",
      "reason": "current license is non-compliant for [shield]",
      "license.expired.feature": "shield"
    }],
    "type": "security_exception",
    "reason": "current license is non-compliant for [shield]",
    "license.expired.feature": "shield"
  },
  "status": 401
}
--------------------------------------------

This enables  automatic monitoring systems to easily detect the license failure without immediately impacting other users. 

IMPORTANT: You should update your license as soon as possible. You're essentially flying blind when running with an expired license. Access to the cluster health and stats APIs is critical
for monitoring and managing an Elasticsearch cluster.