Chapter 13. Configuration

Table of Contents

13.1. Configuring Hazelcast for full TCP/IP cluster
13.2. Configuring Hazelcast for EC2 Auto Discovery
13.3. Creating Separate Clusters
13.4. Specifying network interfaces
13.5. Partition Group Configuration
13.6. Listener Configurations
13.7. Map Index Configuration
13.8. Network Partitioning (Split-Brain Syndrome)
13.9. Wildcard Configuration
13.10. Advanced Configuration Properties
13.11. Logging Configuration
13.12. Setting License Key (Enterprise Edition Only)

Hazelcast can be configured through xml or using configuration api or even mix of both.

  1. Xml Configuration

    If you are using default Hazelcast instance (Hazelcast.getDefaultInstance()) or creating new Hazelcast instance with passing null parameter (Hazelcast.newHazelcastInstance(null)), Hazelcast will look into two places for the configuration file:

    • System property: Hazelcast will first check if "hazelcast.config" system property is set to a file path. Example: -Dhazelcast.config=C:/myhazelcast.xml.

    • Classpath: If config file is not set as a system property, Hazelcast will check classpath for hazelcast.xml file.

    If Hazelcast doesn't find any config file, it will happily start with default configuration (hazelcast-default.xml) located in hazelcast.jar. (Before configuring Hazelcast, please try to work with default configuration to see if it works for you. Default should be just fine for most of the users. If not, then consider custom configuration for your environment.)

    <hazelcast xsi:schemaLocation="http://www.hazelcast.com/schema/config hazelcast-config-2.0.xsd"
        xmlns="http://www.hazelcast.com/schema/config"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <group>
            <name>dev</name>
            <password>dev-pass</password>
        </group>
        <network>
            <port auto-increment="true">5701</port>
            <join>
                <multicast enabled="true">
                    <multicast-group>224.2.2.3</multicast-group>
                    <multicast-port>54327</multicast-port>
                </multicast>
                <tcp-ip enabled="false">
                    <interface>127.0.0.1</interface>
                </tcp-ip>
                <aws enabled="false">
                    <access-key>my-access-key</access-key>
                    <secret-key>my-secret-key</secret-key>
                    <region>us-east-1</region>
                </aws>
            </join>
            <interfaces enabled="false">
                <interface>10.10.1.*</interface>
            </interfaces>

            <symmetric-encryption enabled="false">
                <!--
                   encryption algorithm such as DES/ECB/PKCS5Padding, PBEWithMD5AndDES,
                   AES/CBC/PKCS5Padding, Blowfish, DESede
                -->
                <algorithm>PBEWithMD5AndDES</algorithm>
                <!-- salt value to use when generating the secret key -->
                <salt>thesalt</salt>
                <!-- pass phrase to use when generating the secret key -->
                <password>thepass</password>
                <!-- iteration count to use when generating the secret key -->
                <iteration-count>19</iteration-count>
            </symmetric-encryption>
            <asymmetric-encryption enabled="false">
                <!-- encryption algorithm -->
                <algorithm>RSA/NONE/PKCS1PADDING</algorithm>
                <!-- private key password -->
                <keyPassword>thekeypass</keyPassword>
                <!-- private key alias -->
                <keyAlias>local</keyAlias>
                <!-- key store type -->
                <storeType>JKS</storeType>
                <!-- key store password -->
                <storePassword>thestorepass</storePassword>
                <!-- path to the key store -->
                <storePath>keystore</storePath>
            </asymmetric-encryption>
        </network>
        <executor-service>
            <core-pool-size>16</core-pool-size>
            <max-pool-size>64</max-pool-size>
            <keep-alive-seconds>60</keep-alive-seconds>
        </executor-service>
        <queue name="default">
            <!--
                Maximum size of the queue. When a JVM's local queue size reaches the maximum,
                all put/offer operations will get blocked until the queue size
                of the JVM goes down below the maximum. Any integer between 0 and Integer.MAX_VALUE
                0 means Integer.MAX_VALUE. Default is 0.
            -->
            <max-size-per-jvm>0</max-size-per-jvm>
            <!--
                Name of the map configuration that will be used for the backing distributed
                map for this queue.
            -->
            <backing-map-ref>default</backing-map-ref>
        </queue>

        <map name="default">
            <!--
                Number of backups. If 1 is set as the backup-count for example, then all entries of 
                the map will be copied to another JVM for fail-safety. 0 means no backup.
            -->
            <backup-count>1</backup-count>
            <!-- 
                Maximum number of seconds for each entry to stay in the map. Entries that are
                older than <time-to-live-seconds> and not updated for <time-to-live-seconds>
                will get automatically evicted from the map.
                Any integer between 0 and Integer.MAX_VALUE. 0 means infinite. Default is 0.
            -->
            <time-to-live-seconds>0</time-to-live-seconds>
            <!--
                Maximum number of seconds for each entry to stay idle in the map. Entries that are
                idle(not touched) for more than <max-idle-seconds> will get
                automatically evicted from the map. Entry is touched if get, put or containsKey is called.
                Any integer between 0 and Integer.MAX_VALUE. 0 means infinite. Default is 0.
            -->
            <max-idle-seconds>0</max-idle-seconds>
            <!--
                Valid values are:
                NONE (no eviction),
                LRU (Least Recently Used),
                LFU (Least Frequently Used).
                NONE is the default.
            -->
            <eviction-policy>NONE</eviction-policy>
            <!--
                Maximum size of the map. When max size is reached,
                map is evicted based on the policy defined.
                Any integer between 0 and Integer.MAX_VALUE. 0 means
                Integer.MAX_VALUE. Default is 0.
            -->
            <max-size policy="cluster_wide_map_size">0</max-size>
            <!--
                When max. size is reached, specified percentage of
                the map will be evicted. Any integer between 0 and 100.
                If 25 is set for example, 25% of the entries will
                get evicted.
            -->
            <eviction-percentage>25</eviction-percentage>
            <!--
                While recovering from split-brain (network partitioning),
                map entries in the small cluster will merge into the bigger cluster
                based on the policy set here. When an entry merge into the
                cluster, there might an existing entry with the same key already.
                Values of these entries might be different for that same key.
                Which value should be set for the key? Conflict is resolved by
                the policy set here. Default policy is hz.ADD_NEW_ENTRY
    
                There are built-in merge policies such as
                hz.NO_MERGE      ; no entry will merge.
                hz.ADD_NEW_ENTRY ; entry will be added if the merging entry's key
                                   doesn't exist in the cluster.
                hz.HIGHER_HITS   ; entry with the higher hits wins.
                hz.LATEST_UPDATE ; entry with the latest update wins.
            -->
            <merge-policy>hz.ADD_NEW_ENTRY</merge-policy>
        </map>
    </hazelcast>
    

    If you want to specify your own configuration file to create Config, Hazelcast supports several ways including filesystem, classpath, InputStream, URL etc.:

    • Config cfg = new XmlConfigBuilder(xmlFileName).build();

    • Config cfg = new XmlConfigBuilder(inputStream).build();

    • Config cfg = new ClasspathXmlConfig(xmlFileName);

    • Config cfg = new FileSystemXmlConfig(configFilename);

    • Config cfg = new UrlXmlConfig(url);

    • Config cfg = new InMemoryXmlConfig(xml);

  2. Programmatic Configuration

    To configure Hazelcast programmatically, just instantiate a Config object and set/change its properties/attributes due to your needs.

    Config cfg = new Config();
    cfg.setPort(5900);
    cfg.setPortAutoIncrement(false);
            
    NetworkConfig network = cfg.getNetworkConfig();
    Join join = network.getJoin();
    join.getMulticastConfig().setEnabled(false);
    join.getTcpIpConfig().addMember("10.45.67.32").addMember("10.45.67.100")
                .setRequiredMember("192.168.10.100").setEnabled(true);
    network.getInterfaces().setEnabled(true).addInterface("10.45.67.*");
            
    MapConfig mapCfg = new MapConfig();
    mapCfg.setName("testMap");
    mapCfg.setBackupCount(2);
    mapCfg.getMaxSizeConfig().setSize(10000);
    mapCfg.setTimeToLiveSeconds(300);
            
    MapStoreConfig mapStoreCfg = new MapStoreConfig();
    mapStoreCfg.setClassName("com.hazelcast.examples.DummyStore").setEnabled(true);
    mapCfg.setMapStoreConfig(mapStoreCfg);
    
    NearCacheConfig nearCacheConfig = new NearCacheConfig();
    nearCacheConfig.setMaxSize(1000).setMaxIdleSeconds(120).setTimeToLiveSeconds(300);
    mapCfg.setNearCacheConfig(nearCacheConfig);
    
    cfg.addMapConfig(mapCfg);

After creating Config object, you can use it to initialize default Hazelcast instance or create a new Hazelcast instance.

HazelcastInstance with a name:

13.1. Configuring Hazelcast for full TCP/IP cluster

If multicast is not prefered way of discovery for your environment, then you can configure Hazelcast for full TCP/IP cluster. As configuration below shows, while enable attribute of multicast is set to false, tcp-ip has to be set to true. For the none-multicast option, all or subset of cluster members' hostnames and/or ip addreses must be listed. Note that all of the cluster members don't have to be listed there but at least one of them has to be active in cluster when a new member joins. The tcp-ip tag accepts an attribute called "conn-timeout-seconds". The default value is 5. Increasing this value is recommended if you have many IP's listed and members can not properly build up the cluster.

<hazelcast>
    ...
    <network>
        <port auto-increment="true">5701</port>
        <join>
            <multicast enabled="false">
                <multicast-group>224.2.2.3</multicast-group>
                <multicast-port>54327</multicast-port>
            </multicast>
            <tcp-ip enabled="true">
                <hostname>machine1</hostname>
                <hostname>machine2</hostname>
                <hostname>machine3:5799</hostname>
                <interface>192.168.1.0-7</interface>     
                <interface>192.168.1.21</interface> 
            </tcp-ip>
        </join>
        ...
    </network>
    ...
</hazelcast>