Cluster utilities

Hazelcast Platform is provided with a range of programmatic utilities that you can use to manage your Hazelcast clusters, including command line interfaces and scripts.

These utilities are included in the bin directory in your Hazelcast package and are designed for Unix-like systems. Utilities with a .bat version are compatible with Microsoft Windows.

bin contains the following files.

Filename	Description
hz	Starts a Hazelcast member with customizable configuration. See hz command line interface.
hz-cli, hz-cli.bat	Manages jobs and snapshots on a running cluster. Also used to launch the Hazelcast console and SQL shell. See hz-cli command line interface.
hz-cluster-admin	Performs cluster lifecycle operations, such as force starts and upgrades. See hz-cluster-admin script.
hz-cluster-cp-admin	Manages the CP Subsystem. See Manage and monitor the CP subsystem.
hz-healthcheck	Retrieves cluster state from the HTTP health check endpoint. See Using the health check script.
hz-start, hz-start.bat	Starts a Hazelcast member with the default settings. Where possible, use hz start instead — see hz command line interface.
hz-stop, hz-stop.bat	Gracefully shuts down all running Hazelcast members on the local device.
common.bat, common.sh	Shared code called by other scripts. You should not run this directly.

note

Hazelcast also provides a suite of products for managing and monitoring your Hazelcast deployment. For more information, see the following:

• Management Center
• Platform Operator
• Command Line Client (CLC)

hz command line interface

The hz CLI allows you to start a Hazelcast instance from the shell. The CLI automates the steps required to install and start the software and supports several options to override the default settings.

To create and start a Hazelcast member:

1. Navigate to the bin directory in your Hazelcast package.

2. Start the software.

   • Start the software with the default settings:

     bash

     ./hz start

   • Alternatively, add an option to override the default configuration. For example, to specify a port number:

     bash

     ./hz start -p 5705

     To specify a custom configuration file:

     bash

     ./hz start -c path/to/file.xml

     For the full list of options, refer to the CLI help:

     bash

     ./hz start -h

To gracefully shut down a member after using hz start, exit the terminal with Ctrl+C.

For a tutorial showing how to start a cluster with this tool, see Start a Local Cluster with the CLI.

hz-cli command line interface

The hz-cli tool has a range of uses:

• Managing Jet streaming jobs and job snapshots.
• Launching the SQL shell, which you can use to run SQL queries.
• Launching the Hazelcast console, which you can use to write data to a map for testing and evaluation (not recommended for production).

For the full list of options, refer to the CLI help:

bash

./hz-cli -h

For a tutorial showing how to start a cluster and run the SQL shell, see Start a Local Cluster from Binary.

tip

You should consider using the Hazelcast Command Line Client (CLC), which supports more features.

hz-cluster-admin script

You can use the script hz-cluster-admin to perform cluster lifecycle operations such as changing state, changing the software version or shutting down the cluster.

To use hz-cluster-admin:

• Ensure the curl command is available in your environment.
• Enable the Community Edition REST API.

hz-cluster-admin takes the following parameters. If these parameters are not provided, the default values are used.

Parameter	Default Value	Description
-o or --operation	get-state	Executes a cluster-wide operation. Operations can be the following: Community Edition operations: get-state, change-state, shutdown and get-cluster-version. Enterprise Edition operations: force-start, partial-start and change-cluster-version. For force-start, see Triggering a Force-Start.
-s or --state	None	Updates the state of the cluster to a new state. New state can be active, no_migration, frozen, 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 --address	127.0.0.1	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. See the Creating Clusters section.
-P or --password	dev-pass	Defines the password of a cluster (valid only for Hazelcast releases older than 3.8.2).
-v or --version	no argument expected	Defines the cluster version to change to. It is used in conjunction with the change-cluster-version operation.
-d or --debug	no argument expected	Prints error output.
--https	no argument expected	Enables HTTPS for REST calls between hz-cluster-admin and the cluster. Applicable when TLS is enabled on the cluster.
--cacert	set of well-known CA certificates	Defines trusted PEM-encoded certificate file path to verify member certificates. Applicable when TLS is enabled on the cluster.
--cert	None	Defines PEM-encoded client certificate file path. Applicable when TLS is enabled on the cluster.
--key	None	Defines PEM-encoded client private key file path. Applicable when TLS is enabled on the cluster.
--insecure	no argument expected	Disables member certificate verification. Applicable when TLS is enabled on the cluster.

For the full list of options, refer to the script help: ./hz-cluster-admin -h.

note

You can also perform the above operations using the Persistence tab of Hazelcast Management Center or using the REST API. See Persistence in the Hazelcast Management Center documentation and Managing Cluster's State.

Deprecation Notice for the Community Edition REST API

The Community Edition REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved Enterprise version of this feature is available and actively being developed. For more information, see Enterprise REST API.

Using hz-cluster-admin

In the following examples, there is a cluster named test running on remote machines with a Hazelcast using IP address 172.16.254.1, port 5702. All commands are run from the bin directory.

Getting the cluster state:

To get the state of the cluster:

./hz-cluster-admin -o get-state -a 172.16.254.1 -p 5702 -g test

Changing the cluster state:

To change the state of the cluster to frozen:

./hz-cluster-admin -o change-state -s frozen -a 172.16.254.1 -p 5702 -g test

Shutting down the cluster:

To shut down the cluster:

./hz-cluster-admin -o shutdown -a 172.16.254.1 -p 5702 -g test

Triggering a partial-start on the cluster:

To trigger a partial-start when Persistence is enabled:

./hz-cluster-admin -o partial-start -a 172.16.254.1 -p 5702 -g test

Triggering a force-start the cluster:

To trigger a force-start when Persistence is enabled:

./hz-cluster-admin -o force-start -a 172.16.254.1 -p 5702 -g test

Getting the current cluster version:

To get the cluster version:

./hz-cluster-admin -o get-cluster-version -a 172.16.254.1 -p 5702 -g test

Changing the cluster version:

See Rolling Upgrades to learn more about the cases when you should change the cluster version.

To change the cluster version to X.Y:

./hz-cluster-admin -o change-cluster-version -v X.Y -a 172.16.254.1 -p 5702 -g test

The cluster version is always in the major.minor format, e.g., 3.12. Using other formats results in a failure.

Calls against the TLS protected members (using HTTPS protocol):

When the member has TLS configured, use the --https argument to instruct hz-cluster-admin to use the proper URL scheme:

sh

./hz-cluster-admin --https \
  --operation get-state --address member1.example.com --port 5701

If the default set of trusted certificate authorities is not sufficient, e.g. you use a self-signed certificate, you can provide a custom file with the root certificates:

sh

./hz-cluster-admin --https \
  --cacert /path/to/ca-certs.pem \
  --operation get-state --address member1.example.com --port 5701

When the TLS mutual authentication is enabled, you have to provide the client certificate and related private key:

sh

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

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 your development clusters on your local machines (not recommended for production clusters where the integrity of applications are already verified, and since it is a compute-intensive check).

You can enable it in the configuration as follows.

YAML

yaml

hazelcast:
  integrity-checker:
    enabled: true

XML

xml

<hazelcast>
    <integrity-checker enabled="true"/>
</hazelcast>

Java member API

java

Config config = new Config();
config.setIntegrityCheckerEnabled(true);

HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance(config);

System Prop

shell

-Dhz.integritychecker.enabled=true

Environment Variable

shell

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/service/com.hazelcast.DataSerializerHook. An example log output in the terminal is as follows.

shell

SEVERE: [192.168.56.1]:5701 [dev] [6.0.0-SNAPSHOT] Node creation failed
com.hazelcast.core.HazelcastException: Failed to verify distribution integrity, unable to load DataSerializerHook: com.hazelcast.aggregation.impl.AggregatorDataSerializerHook