Managing Enterprise License Keys

To use Hazelcast Enterprise, you need an Enterprise license key. This topic explains how to get a license key, install it on a member, and manage it.

Getting an Enterprise License Key

Hazelcast Enterprise requires a license key. You can get a 30-day trial license from the Hazelcast website.

License keys have the following format:

<Hazelcast edition>#<Maximum members>#<License key>

<Hazelcast edition>: Name of the product.
<Maximum members>: Maximum number of members that may use the license at the same time.
<License key>: Machine-readable license key.

The first two strings up to the second hash (#) character are optional. These strings provide information about the license key. For example, both of the following formats are valid:

Full-form license

HazelcastEnterprise#2Nodes#1q2w3e4r5t

Short-form license

1q2w3e4r5t

These licenses are examples and will not work if you install them on members.

Configuring a License Key on Members

To use Hazelcast Enterprise, you need to configure a license key on all members in a cluster.

Hazelcast Enterprise license keys are required only for members. You do not need to set a license key for Java clients that are connected to members.

XML
YAML
Java
Environment Variable
System Property

<hazelcast>
    <license-key>Your Enterprise License Key</license-key>
</hazelcast>

hazelcast:
  license-key: Your Enterprise License Key

Add your license to the setLicenseKey() method.

Config config = new Config();
config.setLicenseKey( "Your Enterprise License Key" );

HZ_LICENSEKEY=<Your Enterprise License Key>

-Dhazelcast.enterprise.license.key=<Your Enterprise License Key>

Monitoring License Keys

It’s important to keep track of when your license key is due to expire. If you have an expired license, Hazelcast will not start.

When a license is about to expire, Hazelcast issues the following warning about approaching license expiry in the member logs:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ WARNING @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
HAZELCAST LICENSE WILL EXPIRE IN 29 DAYS.
Your Hazelcast cluster will stop working after this time.

Your license holder is [email protected], you should have them contact
our license renewal department, urgently on [email protected]
or call us on +1 (650) 521-5453

Please quote license id CUSTOM_TEST_KEY
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

The frequency of these warnings varies depending on the time remaining before the license expires.

Table 1. Frequency of warnings about license expiration
Time until expiry	Warning frequency
Two months	Daily
One month	Hourly
One week	Every 30 minutes

To get details about your current license, you can use the Management Center, JMX API, or REST API.

Getting License Details with the JMX API

The MBean HazelcastInstance.LicenseInfo holds all license details and can be accessed through Hazelcast’s JMX port (if enabled). The following parameters represent these details:

maxNodeCountAllowed: Maximum members allowed to form a cluster under the current license.
expiryDate: Expiration date of the current license.
typeCode: Type code of the current license.
type: Type of the current license.
ownerEmail: Email of the current license’s owner.
companyName: Company name on the current license.

Following is the list of license types and type codes:

MANAGEMENT_CENTER(1, "Management Center"),
ENTERPRISE(0, "Enterprise"),
ENTERPRISE_SECURITY_ONLY(2, "Enterprise only with security"),
ENTERPRISE_HD(3, "Enterprise HD"),
CUSTOM(4, "Custom");

Getting License Details with the REST API

You can access license details by sending a GET request to the /license endpoint.

curl -v http://localhost:5701/hazelcast/rest/license

Its output is similar to the following:

{
  "licenseInfo": {
    "expiryDate": 4090168799999,
    "maxNodeCount": 99,
    "type": 3,
    "companyName": null,
    "ownerEmail": null,"keyHash":"OsLh4O6vqDuKEq8lOANQuuAaRnmDfJfRPrFSEhA7T3Y="
  }
}

Getting License Details in Management Center

See Enterprise Licenses in the Management Center documentation.

Renewing a License Key

License keys are valid for a certain period of time; see the expiry date. You can do one of the following to get a new license to renew or upgrade:

Send an email to Sales.
Send an email to Support.
Call your sales representative.

If your license is expired on a running cluster or Management Center, do not restart the host device. Reach out to Hazelcast Support to resolve any issues with an expired license.

Updating a License Key at Runtime

When you receive the renewed or upgraded license, you can update it as follows:

Shut down the members.
Update the license key; see Configuring a License Key on Members.
Restart the members.

Alternatively, you can update the license key dynamically, without shutting down the members. You can use any of the dynamic configuration options to update a license key at runtime. For further information on these options, see the Adding Dynamic Configuration topic.

The example in this section uses the REST API option with its dedicated /license endpoint. To update a license key at runtime:

Enable the REST API.
Send a POST request to the /license endpoint:
```
curl --data "{cluster-name}&{password}&{license}" http://localhost:5001/hazelcast/rest/license
```
The request parameters must be URL-encoded as described in the REST Client section.

This command updates the license on all running Hazelcast members of the cluster. If successful, you should see something like the following:

{
  "status": "success",
  "licenseInfo": {
    "expiryDate": 1560380399161,
    "maxNodeCount": 10,
    "type": -1,
    "companyName": "ExampleCompany",
    "ownerEmail": "[email protected]",
    "keyHash": "ml/u6waTNQ+T4EWxnDRykJpwBmaV9uj+skZzv0SzDhs="
  },
  "message": "License updated at run time - please make sure to update the license in the persistent configuration to avoid losing the changes on restart."
}

If the update fails on some members, the whole operation fails, leaving the cluster in a potentially inconsistent state where some members have been switched to the new license while some have not. You must resolve this situation manually.

By default, if a member shuts down after you dynamically update the license key, its license key will not be persisted.

To persist the license key, you can either enable the persistence for dynamic configuration or update your members' configuration to include the new license key before you restart them.

For further information, see the following topics: