Skip to main content
Version: 5.5

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.

FilenameDescription
hzStarts a Hazelcast member with customizable configuration.
hz-cli, hz-cli.batManages jobs and snapshots on a running cluster. Also used to launch the Hazelcast console and SQL shell.
hz-cluster-adminPerforms cluster lifecycle operations, such as force starts and upgrades.
hz-cluster-cp-adminManages the CP Subsystem. See Managing and Monitoring the CP Subsystem.
hz-healthcheckRetrieves cluster state from the HTTP health check endpoint. See Using the health check script.
hz-start, hz-start.batStarts a Hazelcast member with the default settings. Where possible, use hz start instead.
hz-stop, hz-stop.batStops all running Hazelcast members on the local device. hz-stop sends SIGTERM, and by default the member terminates without a graceful shutdown. To shut down gracefully, set the hazelcast.shutdownhook.policy property to GRACEFUL. hz-stop.bat always stops the member without a graceful shutdown.
common.bat, common.shShared 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:

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 using the default settings or a custom configuration

To 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

hz options​

The hz command has one subcommand, start, which starts a member. On its own, hz takes -h or --help to print its help, and -V or --version to print the Hazelcast version.

The hz start command takes the following options:

OptionDescription
-c, --config <file>Uses <file> as the member configuration. The file can be XML or YAML.
-p, --port <port>Binds the member to <port>. If the port is in use, the member uses the next free port. The default is 5701.
-i, --interface <interface>Binds the member to <interface> only.
-h, --helpPrints the help for hz start.

To stop a member after using hz start, exit the terminal with Ctrl+C. By default, the member terminates without a graceful shutdown. For a graceful shutdown, set the hazelcast.shutdownhook.policy property to GRACEFUL.

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​

tip

Consider using the Hazelcast Command Line Client (CLC) instead, as it has more features.

The hz-cli tool has a range of uses:

hz-cli options​

The hz-cli command takes one of the following subcommands:

SubcommandDescription
sqlStarts the SQL shell.
consoleStarts the Hazelcast console.
submit <jar file> [<arguments>]Submits the job in <jar file> to the cluster, and passes <arguments> to it. Options: -n, --name <name> sets the job name. -c, --class <class> sets the fully qualified name of the main class in the JAR file. -s, --snapshot <snapshot name> starts the job from the named snapshot.
list-jobsLists the running jobs. Options: -a, --all also lists completed and failed jobs.
suspend <job name or id>Suspends a running job.
resume <job name or id>Resumes a suspended job.
restart <job name or id>Restarts a running job.
cancel <job name or id>Cancels a running job.
save-snapshot <job name or id> <snapshot name>Exports a named snapshot of a job. Options: -C, --cancel cancels the job after the snapshot.
list-snapshotsLists the exported snapshots. Options: -F, --full-job-name shows job names in full.
delete-snapshot <snapshot name>Deletes a named snapshot.
clusterShows the cluster state and information about the members.
help <subcommand>Prints the help for <subcommand>.

The hz-cli command and every subcommand take the following options:

OptionDescription
-t, --targets [<cluster-name>@]<hostname>:<port>[,<hostname>:<port>]Connects to the given cluster instead of the one in the client configuration file. At least one address is required. The cluster name is optional.
-v, --verbosityShows verbose logs and the full stack trace of errors.
--ignore-version-mismatchConnects even if the client and member minor versions differ.

The hz-cli command also takes the following options before the subcommand:

OptionDescription
-f, --config <file>Uses <file> as the client configuration. The file can be XML or YAML. The default is config/hazelcast-client.xml.
-h, --helpPrints the help for hz-cli.
-V, --versionPrints the Hazelcast version.

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

hz-cluster-admin script​

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

The script calls the Community Edition REST API. To call the same endpoints without the script, see Managing Cluster's State. You can also perform these operations in Management Center, where force start and partial start are on the Persistence tab. See Persistence.

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.

To use hz-cluster-admin:

  • Ensure the curl command is available in your environment.
  • Enable the Community Edition REST API, and the endpoint group for each operation you use: CLUSTER_READ for get-state and get-cluster-version, CLUSTER_WRITE for change-state, shutdown, and change-cluster-version, and PERSISTENCE for force-start and partial-start. Only CLUSTER_READ is enabled by default.

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. For force-start, see Triggering a Force-Start.
-s or --stateNoneUpdates 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 --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.
-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.
-h or --helpNonePrints the help for hz-cluster-admin. It must be the first parameter.
--httpsOffEnables HTTPS for REST calls between hz-cluster-admin and the cluster. Applicable when TLS is enabled on the cluster.
--cacertThe CA certificates that curl trusts by defaultDefines trusted PEM-encoded certificate file path to verify member certificates. Applicable when TLS is enabled on the cluster.
--certNoneDefines PEM-encoded client certificate file path. Applicable when TLS is enabled on the cluster.
--keyNoneDefines PEM-encoded client private key file path. Applicable when TLS is enabled on the cluster.
--insecureOffDisables member certificate verification. Applicable when TLS is enabled on the cluster.

Examples​

In the following examples, a cluster named test runs on remote machines, and one member has the IP address 172.16.254.1 and port 5702. Run the commands from the bin directory:

TaskCommand
Get the cluster state./hz-cluster-admin -o get-state -a 172.16.254.1 -p 5702 -c test
Change the cluster state to frozen./hz-cluster-admin -o change-state -s frozen -a 172.16.254.1 -p 5702 -c test
Shut down the cluster./hz-cluster-admin -o shutdown -a 172.16.254.1 -p 5702 -c test
Trigger a partial start (persistence enabled)./hz-cluster-admin -o partial-start -a 172.16.254.1 -p 5702 -c test
Trigger a force start (persistence enabled)./hz-cluster-admin -o force-start -a 172.16.254.1 -p 5702 -c test
Get the cluster version./hz-cluster-admin -o get-cluster-version -a 172.16.254.1 -p 5702 -c 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

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

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. Example log output:

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