Skip to main content
Version: 5.3

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:

bash
brew tap hazelcast/hz
brew 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:

TaskCommand
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.

note

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:

ParameterDefault valueDescription
-o or --operationget-stateExecutes a cluster-wide operation. The Community Edition operations are get-state, change-state, shutdown, and get-cluster-version. The Enterprise Edition operations are force-start, partial-start, and change-cluster-version.
-s or --stateNoneUpdates the state of the cluster to a new state. New state can be active, no_migration, frozen, or passive. This is used with the operation change-state. This parameter has no default value; when you use this, you should provide a valid state.
-a or --address127.0.0.1Defines 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 --port5701Defines on which port Hazelcast is running on the local or remote machine.
-c or --clusternamedevDefines 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 --passworddev-passDefines the password of a cluster. The member checks the password only when security is enabled. See the Creating Clusters section.
-v or --versionNoneDefines the cluster version to change to. It is used in conjunction with the change-cluster-version operation.
-d or --debugOffPrints verbose output from curl.
--httpsOffUses HTTPS protocol for REST calls.
--cacertThe CA certificates that curl trusts by defaultDefines the path of the trusted PEM-encoded certificate file. It is used to verify member certificates.
--certNoneDefines the path of the PEM-encoded client certificate file. Only needed when client certificate authentication is used.
--keyNoneDefines the path of the PEM-encoded client private key file. Only needed when client certificate authentication is used.
--insecureOffDisables 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.

note

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:

TaskCommand
Get the cluster state./hz-cluster-admin -o get-state -a 172.16.254.1 -p 5702 -c test -P test
Change the cluster state to frozen./hz-cluster-admin -o change-state -s frozen -a 172.16.254.1 -p 5702 -c test -P test
Shut down the cluster./hz-cluster-admin -o shutdown -a 172.16.254.1 -p 5702 -c test -P test
Trigger a partial start (persistence enabled)./hz-cluster-admin -o partial-start -a 172.16.254.1 -p 5702 -c test -P test
Trigger a force start (persistence enabled)./hz-cluster-admin -o force-start -a 172.16.254.1 -p 5702 -c test -P test
Get the cluster version./hz-cluster-admin -o get-cluster-version -a 172.16.254.1 -p 5702 -c test -P test
Change the cluster version to X.Y./hz-cluster-admin -o change-cluster-version -v X.Y -a 172.16.254.1 -p 5702 -c test -P test

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:

sh
./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:

sh
./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:

sh
./hz-cluster-admin --https \
--key privkey.pem \
--cert cert.pem \
--operation get-state --address member1.example.com --port 5701
note

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 DataSerializer hook for your application, but do not update the corresponding /META-INF/services/com.hazelcast.DataSerializerHook file
  • You build an application with a plugin that merges dependency JARs into the application's executable JAR; the plugin might be misconfigured and DataSerializerHook files 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
hazelcast:
integrity-checker:
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.

shell
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