This is a prerelease version.

View latest

Configuring with System Properties and Environment Variables

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

You can use system properties and environment variables to configure Hazelcast and override existing settings in a root configuration file. Environment variables are useful for configuring members in containerized environments.

Using Java?
If you use configuration builders or the new Config() constructor with the Java member API, you cannot override existing configuration with system properties and environment variables. To override existing configuration, you must use configuration loaders.
If you override a value in a configuration file, the other values in the same block are reset to their defaults. For example, if you override the hazelcast.map.backup-count value, all other settings within the map block are reset to their defaults. To avoid the other values being reset to their defaults, you must override all values in the block.

You can set system properties as name and value pairs through declarative configuration, programmatic configuration, or JVM arguments:

  • XML

  • YAML

  • Java

  • JVM

<hazelcast>
    ...
    <properties>
        <property name="hazelcast.property.foo">value</property>
    </properties>
    ...
</hazelcast>
hazelcast:
    ...
    properties:
      hazelcast.property.foo: value
    ...
Config config = new Config();
config.setProperty( "hazelcast.property.foo", "value" );
Java command
java -Dhazelcast.property.foo=value
JAVA_OPTS
JAVA_OPTS="-Dhazelcast.property.foo=value"

Naming System Properties and Environment Variables

The names of system properties and environment variables follow a consistent pattern, where the names match those in the YAML declarative configuration file. See Member Configuration Files.

All entries need to mirror the YAML configuration structure which differs slightly to XML. And, you cannot configure settings that use YAML lists.

The names of environment variables follow these rules:

  • Each configuration entry needs to start with HZ_ for member configuration or HZCLIENT_ for client configuration.

  • A new configuration level should be introduced with an underscore (_).

  • Dashes (-) should be removed.

  • Names should be in upper case.

The names of system properties must follow these rules:

  • Each configuration entry needs to start with hz. for member configuration or hz-client. for client configuration.

  • A new configuration level should be introduced with a dot (.).

  • Names should be in lower case.

For example, consider the following configuration settings.

hazelcast:
  cluster-name: dev
  network:
    port:
      auto-increment: true

You can override these settings by using the following environment variables or system properties:

Environment variables
HZ_CLUSTERNAME=dev
HZ_NETWORK_PORT_AUTOINCREMENT=true
System properties
hz.cluster-name=dev
hz.network.port.auto-increment=true
lifebuoy

Help and support