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. |
hz-, hz- | Manages jobs and snapshots on a running cluster. Also used to launch the Hazelcast console and SQL shell. |
hz- | Performs cluster lifecycle operations, such as force starts and upgrades. |
hz- | Manages the CP Subsystem. See Managing and Monitoring the CP Subsystem. |
hz- | Retrieves cluster state from the HTTP health check endpoint. See Using the health check script. |
hz-, hz- | Starts a Hazelcast member with the default settings. Where possible, use hz start instead. |
hz-, hz- | Stops all running Hazelcast members on the local device. hz- sends SIGTERM, and by default the member terminates without a graceful shutdown. To shut down gracefully, set the hazelcast. property to GRACEFUL. hz- always stops the member without a graceful shutdown. |
common., common. | Shared code called by other scripts. You should not run this directly. |
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:
-
Navigate to the
bindirectory in your Hazelcast package. -
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 5705To specify a custom configuration file:
bash./hz start -c path/to/file.xmlFor the full list of options, refer to the CLI help:
bash./hz start -h
-
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
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:
./hz-cli -h
For a tutorial showing how to start a cluster and run the SQL shell, see Start a Local Cluster from Binary.
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 cluster version, or shutting down the cluster.
To use hz-cluster-admin:
- Ensure the
curlcommand is available in your environment. - Enable the Community Edition REST API.
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-. For force-, 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_, 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. |
-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 | Enables HTTPS for REST calls between hz- and the cluster. Applicable when TLS is enabled on the cluster. |
--cacert | The CA certificates that curl trusts by default | Defines the path of the trusted PEM-encoded certificate file to verify member certificates. Applicable when TLS is enabled on the cluster. |
--cert | None | Defines the path of the PEM-encoded client certificate file. Applicable when TLS is enabled on the cluster. |
--key | None | Defines the path of the PEM-encoded client private key file. Applicable when TLS is enabled on the cluster. |
--insecure | Off | 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.
You can also 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 Persistence in the Hazelcast Management Center documentation and Managing Cluster's State.
The REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development.
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:
| 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 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
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.4.5] Node creation failed
com.hazelcast.core.HazelcastException: Failed to verify distribution integrity, unable to load DataSerializerHook: com.hazelcast.aggregation.impl.AggregatorDataSerializerHook