Configuring with System Properties and Environment Variables

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.

important

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

xml

<hazelcast>
    ...
    <properties>
        <property name="hazelcast.property.foo">value</property>
    </properties>
    ...
</hazelcast>

YAML

yaml

hazelcast:
    ...
    properties:
      hazelcast.property.foo: value
    ...

Java

java

Config config = new Config();
config.setProperty( "hazelcast.property.foo", "value" );

JVM

Java command

shell

java -Dhazelcast.property.foo=value

JAVA_OPTS

shell

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.

note

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.

yaml

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

shell

HZ_CLUSTERNAME=dev
HZ_NETWORK_PORT_AUTOINCREMENT=true

System properties

shell

hz.cluster-name=dev
hz.network.port.auto-increment=true