Cluster utilities
This section provides information about the Hazelcast command line and other programmatic utilities you can use to listen to the cluster events, to change the state of your cluster, to check whether the cluster and/or members are safe before shutting down a member and to define the minimum number of cluster members required for the cluster to remain up and running. It also gives information about the Hazelcast Lite Member.
Hazelcast command line tool
This is a tool using which you can install and run Hazelcast and Management Center on your Unix-like local environments. You need JRE 8 or later as a prerequisite.
You can install this tool using its Homebrew, RPM, or Debian packages:
- Homebrew
- Debian
- RPM
brew tap hazelcast/hz
brew install hazelcast@5.3.8
wget -qO - https://repository.hazelcast.com/api/gpg/key/public | gpg --dearmor | sudo tee /usr/share/keyrings/hazelcast-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/hazelcast-archive-keyring.gpg] https://repository.hazelcast.com/debian stable main" | sudo tee -a /etc/apt/sources.list
sudo apt update && sudo apt install hazelcast=5.3.8
wget https://repository.hazelcast.com/rpm/stable/hazelcast-rpm-stable.repo -O hazelcast-rpm-stable.repo
sudo mv hazelcast-rpm-stable.repo /etc/yum.repos.d/
sudo yum install hazelcast-5.3.8
Alternatively, you can manually download and install this tool using the TAR package on its GitHub repository. After you download and extract the package, you see the hazelcast-<version> directory. Run the following commands to install it:
cd hazelcast-<version>/bin
./hz
You are now ready to use the tool. You can use it for the following tasks:
| Task | Command |
|---|---|
| Start a standalone Hazelcast member with the default configuration | ./hz start |
| Start Hazelcast Management Center | ./hz mc start |
See the tool's documentation for all the other usages.
Using the hz-cluster-admin script
You can use the script hz-cluster-admin, which comes with the Hazelcast package, to get or change the state of your cluster, to shut down your cluster, and to force your cluster to clean its persisted data and make a fresh start. The latter is the force-start operation of Persistence. See the Force-start section.
The script hz-cluster-admin uses curl command and curl must be installed to be able to use the script.
hz-cluster-admin options
If you do not set a parameter, the script uses its default value. The hz-cluster-admin script takes the following parameters:
| Parameter | Default value | Description |
|---|---|---|
-o or --operation | get- | Executes a cluster-wide operation. The Community Edition operations are get-, change-, shutdown, and get-. The Enterprise Edition operations are force-, partial-, and change-. |
-s or --state | None | Updates the state of the cluster to a new state. New state can be active, no_, frozen, or passive. This is used with the operation change-. This parameter has no default value; when you use this, you should provide a valid state. |
-a or --address | 127. | Defines the IP address of a cluster member. If you want to manage your cluster remotely, you should use this parameter to provide the IP address of a member to this script. |
-p or --port | 5701 | Defines on which port Hazelcast is running on the local or remote machine. |
-c or --clustername | dev | Defines the name of a cluster which is used for a simple authentication. When security is enabled, the member uses this value as the username. See the Creating Clusters section. |
-P or --password | dev- | Defines the password of a cluster. The member checks the password only when security is enabled. See the Creating Clusters section. |
-v or --version | None | Defines the cluster version to change to. It is used in conjunction with the change- operation. |
-d or --debug | Off | Prints verbose output from curl. |
--https | Off | Uses HTTPS protocol for REST calls. |
--cacert | The CA certificates that curl trusts by default | Defines the path of the trusted PEM-encoded certificate file. It is used to verify member certificates. |
--cert | None | Defines the path of the PEM-encoded client certificate file. Only needed when client certificate authentication is used. |
--key | None | Defines the path of the PEM-encoded client private key file. Only needed when client certificate authentication is used. |
--insecure | Off | Disables member certificate verification. |
The script hz-cluster-admin is self-documented; you can see the parameter descriptions using the command ./hz-cluster-admin -h or ./hz-cluster-admin --help.
You can perform the above operations using Hazelcast Management Center or using the REST API. Force start and partial start are on the Persistence tab of Management Center. See the Persistence and Managing Cluster's State sections in the Hazelcast Management Center documentation.
Examples
In the following examples, a cluster runs on remote machines, and one member has the IP address 172.16.254.1 and port 5702. The cluster name and password are both test. Every option also has a long name, for example --port for -p:
| Task | Command |
|---|---|
| Get the cluster state | ./hz- |
Change the cluster state to frozen | ./hz- |
| Shut down the cluster | ./hz- |
| Trigger a partial start (persistence enabled) | ./hz- |
| Trigger a force start (persistence enabled) | ./hz- |
| Get the cluster version | ./hz- |
Change the cluster version to X. | ./hz- |
The cluster version is in the major.minor format, for example 3.12. The member also accepts a patch version or suffix, such as 3.12.1, but uses only the major and minor numbers. Other formats result in a failure. To learn when to change the cluster version, see Rolling Member Upgrades.
When the members use TLS, add --https:
./hz-cluster-admin --https \
--operation get-state --address member1.example.com --port 5701
If your certificate authority is not in the default trusted set, for example with a self-signed certificate, set --cacert to a file that contains the root certificates:
./hz-cluster-admin --https \
--cacert /path/to/ca-certs.pem \
--operation get-state --address member1.example.com --port 5701
When TLS mutual authentication is enabled, also set the client certificate and its private key:
./hz-cluster-admin --https \
--key privkey.pem \
--cert cert.pem \
--operation get-state --address member1.example.com --port 5701
This script is not supported on Windows.
Integrity checker
The integrity checker is a utility developed for Java developers who build Hazelcast applications. It checks the classpath of your applications built with Hazelcast JAR dependencies (e.g., hazelcast or hazelcast-sql, using the assembly or other uber-JAR plugins). This check involves the verification of all serializer hooks are loaded during a Hazelcast member startup, that is, it verifies that the executable of your application contains all the required META-INF/services files.
For example, there may be cases where:
- You add a new
DataSerializerhook for your application, but do not update the corresponding/META-INF/services/com.hazelcast.DataSerializerHookfile - You build an application with a plugin that merges dependency JARs into the application's executable JAR; the plugin might be misconfigured and
DataSerializerHookfiles are not merged correctly, resulting in a corrupted executable
The integrity checker is disabled by default, and can be used for development clusters on your local machines. It is not recommended for production clusters, where the integrity of applications are already verified, because it is a compute-intensive check.
Enable it in the configuration as follows:
- YAML
- XML
- Java member API
- System Prop
- Environment Variable
hazelcast:
integrity-checker:
enabled: true
<hazelcast>
<integrity-checker enabled="true"/>
</hazelcast>
Config config = new Config();
config.getIntegrityCheckerConfig().setEnabled(true);
HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance(config);
-Dhz.integritychecker.enabled=true
HZ_INTEGRITYCHECKER_ENABLED=true
If the verification fails, the member does not start and the checker prints which hook is missing its corresponding /META-INF/services/com.hazelcast.DataSerializerHook. An example log output in the terminal is as follows.
SEVERE: [192.168.56.1]:5701 [dev] [5.3.8] Node creation failed
com.hazelcast.core.HazelcastException: Failed to verify distribution integrity, unable to load DataSerializerHook: com.hazelcast.aggregation.impl.AggregatorDataSerializerHook