Cluster Configuration Parameters

GridGain 9 cluster configuration is shared across the whole cluster. Regardless of which node you apply the configuration on, it will be propagated to all nodes in the cluster.

In GridGain 9, you can create and maintain configuration in either HOCON or JSON. The configuration file has a single root "node," called ignite. All configuration sections are children, grandchildren, etc., of that node.

Setting Initial Cluster Configuration

When starting a cluster, it uses default parameters unless otherwise specified. You can provide custom configuration parameters in the --config parameter, or a path to the configuration file in the --config-files parameter. You also need to pass a valid license using the --license key.

cluster init --name=sampleCluster --license=/valid-license.conf --config-files=/cluster-config.conf

Checking Cluster Configuration

To get cluster configuration, use the CLI tool.

Start the CLI tool and connect to any node in the cluster.
Run the cluster config show command.

The CLI tool will print the full cluster configuration. If you only need a part of the configuration, you can narrow down the search by providing the properties you need as the command argument, for example:

cluster config show ignite.transaction

Changing Cluster Configuration

Cluster configuration is changed from the CLI tool. You can update it both in the interactive (REPL) and non-interactive mode by passing a configuration file with the --file parameter.

Update via REPL:

Start the CLI tool and connect to any node in the cluster.

Run the cluster config update command and provide the updated configuration as the command argument, for example:
```
cluster config update ignite.system.idleSafeTimeSyncIntervalMillis=600
```
To update one or more parameters, pass the configuration file to the cluster config update command:
```
cluster config update --file ../gridgain-config.conf
```

You also can update the configuration combining both approaches:

cluster config update --file ../gridgain-config.conf ignite.system.idleSafeTimeSyncIntervalMillis=600

The updated configuration will automatically be applied across the cluster.

Update via Non-Interactive Mode

You can also modify cluster configuration via non-interactive CLI mode without starting the CLI tool first.

Pass the configuration file with the --file parameter:

bin/gridgain9 cluster config update --file ../gridgain-config.conf

The updated configuration will automatically be applied across the cluster.

Exporting Cluster Configuration

If you need to export cluster configuration to file, use the following command:

bin/gridgain9 cluster config show > cluster-config.conf

Configuration Parameters

Encryption Configuration

{
  "ignite" : {
    "encryption" : {
      "activeProvider" : "",
      "enabled" : false,
      "providers" : { }
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
activeProvider	""	The name of the currently active encryption provider.	Yes	No	A name from the provider map
enabled	false	Whether the encryption is enabled.	Yes	No	true, false
providers		A named list (map) of the available encryption providers.	Yes	No	A valid provider map

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

activeProvider

The name of the currently active encryption provider.

Yes

A name from the provider map

enabled

false

Whether the encryption is enabled.

Yes

true, false

providers

A named list (map) of the available encryption providers.

Yes

A valid provider map

Event Log Configuration

{
  "ignite" : {
    "eventlog" : {
      "channels" : { },
      "sinks" : { }
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
channels		A named list of event log channels.	Yes	No	Valid channels
sinks		A named list of event log sinks.	Yes	No	Valid sinks

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

channels

A named list of event log channels.

Yes

Valid channels

sinks

A named list of event log sinks.

Yes

Valid sinks

Garbage Collection Configuration

{
  "ignite" : {
    "gc" : {
      "batchSize" : 5,
      "lowWatermark" : {
        "dataAvailabilityTimeMillis" : 600000,
        "updateIntervalMillis" : 300000
      },
      "threads" : 16
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
batchSize	5	The number of entries to be removed by the garbage collection batch for each partition	Yes	No	0 - inf
lowWatermark.dataAvailabilityTimeMillis	600000	The duration the outdated versions are available for, in milliseconds.	Yes	No	1000 - inf
lowWatermark.updateIntervalMillis	300000	The interval of the low watermark updates.	Yes	No	0 - inf
threads	Runtime.getRuntime().availableProcessors()	The number of threads used by the garbage collector.	Yes	Yes	1 - inf

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

batchSize

The number of entries to be removed by the garbage collection batch for each partition

Yes

0 - inf

lowWatermark.dataAvailabilityTimeMillis

600000

The duration the outdated versions are available for, in milliseconds.

Yes

1000 - inf

lowWatermark.updateIntervalMillis

300000

The interval of the low watermark updates.

Yes

0 - inf

threads

Runtime.getRuntime().availableProcessors()

The number of threads used by the garbage collector.

Yes

1 - inf

License Configuration

{
  "ignite" : {
    "license" : {
        "content" : "********",
        "signature" : "********"
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
content	""	License content; a JSON string.	Yes	No	A JSON string with valid constraints
signature	""	Signature for the license content.	Yes	No	A valid HEX string

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

content

License content; a JSON string.

Yes

A JSON string with valid constraints

signature

Signature for the license content.

Yes

A valid HEX string

Metrics Configuration

{
  "ignite" : {
    "metrics" : {
      "exporters" : [ ]
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
exporters		The list of metric exporters currently used.	Yes	No	Valid exporters

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

exporters

The list of metric exporters currently used.

Yes

Valid exporters

Replication Configuration

{
  "ignite" : {
    "replication" : {
      "batchSizeBytes" : 8192,
      "idleSafeTimePropagationDurationMillis" : 1000,
      "leaseAgreementAcceptanceTimeLimitMillis" : 120000,
      "leaseExpirationIntervalMillis" : 5000,
      "replicaOperationRetryIntervalMillis" : 10,
      "rpcTimeoutMillis" : 60000
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
batchSizeBytes	8192	Batch size (in bytes) to be written into physical storage. Used to limit the size of an atomical Write.	Yes	No	1 - Integer.MAX_VALUE
idleSafeTimePropagationDurationMillis	1000	Interval between Partition Safe Time updates.	No	N/A	1 - inf
leaseAgreementAcceptanceTimeLimitMillis	120000	The maximum duration of an election for a new partition leaseholder, in milliseconds.	Yes	N/A	5000 - inf
leaseExpirationIntervalMillis	5000	The duration of a single lease.	Yes	N/A	2000 - 120000
replicaOperationRetryIntervalMillis	10	The retry interval for replica operations.	Yes	N/A	1 - inf
rpcTimeoutMillis	60000	Replication request processing timeout.	Yes	No	0 - inf

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

batchSizeBytes

8192

Batch size (in bytes) to be written into physical storage. Used to limit the size of an atomical Write.

Yes

1 - Integer.MAX_VALUE

idleSafeTimePropagationDurationMillis

1000

Interval between Partition Safe Time updates.

N/A

1 - inf

leaseAgreementAcceptanceTimeLimitMillis

120000

The maximum duration of an election for a new partition leaseholder, in milliseconds.

Yes

N/A

5000 - inf

leaseExpirationIntervalMillis

5000

The duration of a single lease.

Yes

N/A

2000 - 120000

replicaOperationRetryIntervalMillis

The retry interval for replica operations.

Yes

N/A

1 - inf

rpcTimeoutMillis

60000

Replication request processing timeout.

Yes

0 - inf

Schema Sync Configuration

{
  "ignite" : {
    "schemaSync" : {
      "delayDurationMillis" : 500,
      "maxClockSkewMillis" : 500
    }
  }
}

Property Default Description Changeable Requires Restart Acceptable Values

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
delayDurationMillis	500	The delay after which a schema update becomes active. Should exceed the typical time to deliver a schema update to all cluster nodes, otherwise delays in handling operations are possible. Should not be less than `metaStorage.idleSyncTimeIntervalMillis`. The optimal value is `metaStorage.idleSyncTimeIntervalMillis` * 2.	No	N/A	1 - inf
maxClockSkewMillis	500	Maximum physical clock skew (ms) tolerated by the cluster. If the difference between physical clocks of two nodes in the cluster exceeds this value, the cluster might demonstrate abnormal behavior.	No	N/A	0 - inf

delayDurationMillis

500

The delay after which a schema update becomes active. Should exceed the typical time to deliver a schema update to all cluster nodes, otherwise delays in handling operations are possible. Should not be less than metaStorage.idleSyncTimeIntervalMillis. The optimal value is metaStorage.idleSyncTimeIntervalMillis * 2.

N/A

1 - inf

maxClockSkewMillis

500

Maximum physical clock skew (ms) tolerated by the cluster. If the difference between physical clocks of two nodes in the cluster exceeds this value, the cluster might demonstrate abnormal behavior.

N/A

0 - inf

Security Configuration

{
  "ignite": {
    "security": {
      "authentication": {
        "providers": {
          "default": {
            "type": "basic",
            "users": {
              "ignite": {
                "displayName": "ignite",
                "password": "********",
                "passwordEncoding": "PLAIN",
                "roles": [
                  "system"
                ]
              }
            }
          }
        }
      },
      "authorization": {
        "roles": {
          "system": {
            "displayName": "system",
            "privileges": { }
          }
        }
      },
      "enabled": false,
      "jwt": {
        "keyTtl": 1209600000,
        "ttl": 28800000
      }
    }
  }
}

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
Authentication parameters
providers.name	default	The name of the authentication provider.	Yes	No	A valid string
providers.type	basic	The authentication provider type.	Yes	No	basic, ldap
providers.users		The list of users registered with the specific provider.
providers.users.displayName	ignite	Case sensitive user name.	No	N/A	A valid username
providers.users.password	**	User password.	Yes	No	A valid password
providers.users.passwordEncoding	PLAIN	User password’s encoding.	Yes	No	PLAIN, BCRYPT
providers.users.roles	system	The list of roles assigned to the user.	Yes	No	A valid role
providers.users.username	ignite	Case-insensitive user name.	Yes	No	A valid user name
Authorization parameters
roles.displayName	system	Case-sensitive role name.	Yes	No	A valid role name
roles.name	system	Case-insensitive role name.	Yes	No	A valid role name
roles.privileges		A list of privileges available to users with the role.
roles.privileges.action	""	The action the privilege relates to.	Yes	No	A valid action
roles.privileges.name	""	A privilege name on privilege list .	No	N/A	A valid name
roles.privileges.on	""	The name of the object the privilege applies to.	Yes	No	A valid object name or empty
Security parameters
enabled	false	Whether authentication is enabled.	Yes	No	true, false
JWT parameters
jwt.keyTtl	1209600000	TTL for JWT security tokens.	Yes	No	A valid LONG value
jwt.ttl	28800000	The frequency of private key updates used to issue JWT tokens.	Yes	No	A valid LONG value

Property

Default

Description

Changeable

Requires Restart

Acceptable Values

Authentication parameters

providers.name

default

The name of the authentication provider.

Yes

A valid string

providers.type

basic

The authentication provider type.

Yes

basic, ldap

providers.users

The list of users registered with the specific provider.

providers.users.displayName

ignite

Case sensitive user name.

N/A

A valid username

providers.users.password

User password.

Yes

A valid password

providers.users.passwordEncoding

PLAIN

User password’s encoding.

Yes

PLAIN, BCRYPT

providers.users.roles

system

The list of roles assigned to the user.

Yes

A valid role

providers.users.username

ignite

Case-insensitive user name.

Yes

A valid user name

Authorization parameters

roles.displayName

system

Case-sensitive role name.

Yes

A valid role name

roles.name

system

Case-insensitive role name.

Yes

A valid role name

roles.privileges

A list of privileges available to users with the role.

roles.privileges.action

The action the privilege relates to.

Yes

A valid action

roles.privileges.name

A privilege name on privilege list .

N/A

A valid name

roles.privileges.on

The name of the object the privilege applies to.

Yes

A valid object name or empty

Security parameters

enabled

false

Whether authentication is enabled.

Yes

true, false

JWT parameters

jwt.keyTtl

1209600000

TTL for JWT security tokens.

Yes

A valid LONG value

jwt.ttl

28800000

The frequency of private key updates used to issue JWT tokens.

Yes

A valid LONG value

Snapshots Configuration

{
  "ignite": {
    "snapshot": {
      "snapshotTombstonesTtlMinutes": 1440,
      "paths": [
        {
          "default": false,
          "name": "local-default-relative-example",
          "type": "LOCAL",
          "uri": "file:/snapshots"
        },
        {
          "default": false,
          "name": "remote-absolute-example",
          "type": "REMOTE",
          "uri": "file:///absolute/path/to/snapshots"
        }
      ]
    }
  }
}

Property Default Description Changeable Requires Restart Acceptable Values

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
snapshotTombstonesTtlMinutes	1440	TTL for snapshot tombstones in minutes.	Yes	No	Non-negative `long` value
paths.default	false	If set to `true`, this path is used as the default when no `--source` or `--destination` option is specified in the snapshot command. Only one path can be marked as default. If no default is set, the system falls back to the LOCAL path `file:/snapshots` when no `--source` or `--destination` is provided.	Yes	No	boolean
paths.name		The name of the snapshot path.	Yes	No	A valid string
paths.type	LOCAL	The snapshot path’s type. LOCAL paths are not shared between nodes; REMOTE ones are shared. The REMOTE paths use a single-copy algorithm, which saves only one copy of meta and partition files	Yes	No	LOCAL, REMOTE
paths.uri		The base URI where snapshots will be stored. Use either `scheme:///absolute-path` for absolute paths or `scheme:/relative-path` for relative paths. Currently, only the `file` scheme is supported. If an absolute path is provided, it is treated as a REMOTE path and used "as is". For LOCAL paths, a subfolder named after the node is appended: `/absolute-path/node-name`. Relative paths are resolved from the node’s working directory: `{GRIDGAIN_HOME}/work/relative-path`.	Yes	No	A valid URI

snapshotTombstonesTtlMinutes

1440

TTL for snapshot tombstones in minutes.

Yes

Non-negative long value

paths.default

false

If set to true, this path is used as the default when no --source or --destination option is specified in the snapshot command. Only one path can be marked as default. If no default is set, the system falls back to the LOCAL path file:/snapshots when no --source or --destination is provided.

Yes

boolean

paths.name

The name of the snapshot path.

Yes

A valid string

paths.type

LOCAL

The snapshot path’s type. LOCAL paths are not shared between nodes; REMOTE ones are shared. The REMOTE paths use a single-copy algorithm, which saves only one copy of meta and partition files

Yes

LOCAL, REMOTE

paths.uri

The base URI where snapshots will be stored. Use either scheme:///absolute-path for absolute paths or scheme:/relative-path for relative paths. Currently, only the file scheme is supported. If an absolute path is provided, it is treated as a REMOTE path and used "as is". For LOCAL paths, a subfolder named after the node is appended: /absolute-path/node-name. Relative paths are resolved from the node’s working directory: {GRIDGAIN_HOME}/work/relative-path.

Yes

A valid URI

SQL Configuration

{
  "ignite" : {
    "sql" : {
      "offloadingEnabled" : false,
      "planner" : {
        "estimatedNumberOfQueries" : 1024,
        "maxPlanningTimeMillis" : 15000
      },
      "statementMemoryQuota" : "100%"
    }
  }
}

Property Default Description Changeable Requires Restart Acceptable Values

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
offloadingEnabled	false	Determines if SQL memory offloading	Yes	no	true, false
planner.estimatedNumberOfQueries	1024	The estimated number of unique queries that are planned to be executed in the cluster in a certain period of time. Used to optimize internal caches and processes. Optional.	Yes	Yes	0 - Integer.MAX_VALUE
planner.maxPlanningTimeMillis	15000	Query planning timeout in milliseconds. Plan optimization process stops when the timeout is reached. `0` means no timeout.	Yes	Yes	0 - Long.MAX_VALUE
statementMemoryQuota	100%	The amount of memory that can be used by a single SQL statement. A number with a dimension identifier: % - percentage of the node’s heap memory k - Kb m - Mb g - Gb `0` with any of the dimension identifiers turns the memory tracking off.	Yes	No	0 - 100% 0 - 9223372036854775807k/m/g

offloadingEnabled

false

Determines if SQL memory offloading

Yes

true, false

planner.estimatedNumberOfQueries

1024

The estimated number of unique queries that are planned to be executed in the cluster in a certain period of time. Used to optimize internal caches and processes. Optional.

Yes

0 - Integer.MAX_VALUE

planner.maxPlanningTimeMillis

15000

Query planning timeout in milliseconds. Plan optimization process stops when the timeout is reached. 0 means no timeout.

Yes

0 - Long.MAX_VALUE

statementMemoryQuota

100%

The amount of memory that can be used by a single SQL statement. A number with a dimension identifier:

% - percentage of the node’s heap memory
k - Kb
m - Mb
g - Gb

0 with any of the dimension identifiers turns the memory tracking off.

Yes

0 - 100%
0 - 9223372036854775807k/m/g

System Configuration

This section describes internal properties used by various GridGain components.

You can edit these properties using the cluster config update CLI command, just like any other configuration option. However, we recommend discussing any changes with the GridGain support team before applying them.

These properties may apply to the entire cluster (see below) or to a specific node.

{
  "ignite" : {
    "system" : {
      "properties":{},
      "idleSafeTimeSyncIntervalMillis" : 250
    }
  }
}

Property Default Description Changeable Requires Restart Acceptable Values

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
system.properties		System properties used by the GridGain components.	Yes	Yes	A map of properties.
idleSafeTimeSyncIntervalMillis	250	Period (in milliseconds) used to determine how often to issue time sync commands when Metastorage is idle (no Writes are issued). Should not exceed `schemaSync.delayDurationMillis`. The optimal value is `schemaSync.delayDurationMillis` / 2.	Yes	No (becomes effective on Metastorage leader reelection)	1 - inf

system.properties

System properties used by the GridGain components.

Yes

A map of properties.

idleSafeTimeSyncIntervalMillis

250

Period (in milliseconds) used to determine how often to issue time sync commands when Metastorage is idle (no Writes are issued). Should not exceed schemaSync.delayDurationMillis. The optimal value is schemaSync.delayDurationMillis / 2.

Yes

No (becomes effective on Metastorage leader reelection)

1 - inf

Transactions Configuration

{
  "ignite" : {
    "transaction" : {
      "readOnlyTimeoutMillis" : 600000,
      "readWriteTimeoutMillis" : 30000
    }
  }
}

Property Default Description Changeable Requires Restart Acceptable Values

Property	Default	Description	Changeable	Requires Restart	Acceptable Values
readOnlyTimeoutMillis	600000	Timeout for read-only transactions. It defines how long the transaction holds acquired resources on participating nodes. If no timeout is specified, or it is set to `0`, a default value of 10 minutes is applied. The transaction is guaranteed to remain active until the timeout expires. Once the timeout is reached, the transaction is aborted but may persist briefly beyond the timeout while corresponding resources are cleaned up. Use instead of `readOnlyTimeout`.	Yes	No	1 - inf
readWriteTimeoutMillis	30000	Timeout for read-write transactions. It defines how long the transaction holds acquired resources on participating nodes. If no timeout is specified, or it is set to `0`, a default value of 30 seconds is applied. The transaction is guaranteed to remain active until the timeout expires. Once the timeout is reached, the transaction is aborted but may persist briefly beyond the timeout while corresponding resources are cleaned up. Use instead of `readWriteTimeout`.	Yes	No	1 - inf
abandonedCheckTs	5000	Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	Yes	0 - inf
attemptsObtainLock	3	Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	Yes	0 - inf
deadlockPreventionPolicy.txIdComparator	NATURAL	Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	Yes	NATURAL, REVERSED, NONE
deadlockPreventionPolicy.waitTimeout	0	Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	Yes	0 - inf
readOnlyTimeout	600000	Deprecated. Use `readOnlyTimeoutMillis` instead. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	No	1 - inf
readWriteTimeout	30000	Deprecated. Use `readWriteTimeoutMillis` instead. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	No	1 - inf
rpcTimeout	60000	Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	Yes	0 - inf
txnResourceTtl	30000	Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.	Yes	Yes	0 - inf

readOnlyTimeoutMillis

600000

Timeout for read-only transactions. It defines how long the transaction holds acquired resources on participating nodes. If no timeout is specified, or it is set to 0, a default value of 10 minutes is applied. The transaction is guaranteed to remain active until the timeout expires. Once the timeout is reached, the transaction is aborted but may persist briefly beyond the timeout while corresponding resources are cleaned up. Use instead of readOnlyTimeout.

Yes

1 - inf

readWriteTimeoutMillis

30000

Timeout for read-write transactions. It defines how long the transaction holds acquired resources on participating nodes. If no timeout is specified, or it is set to 0, a default value of 30 seconds is applied. The transaction is guaranteed to remain active until the timeout expires. Once the timeout is reached, the transaction is aborted but may persist briefly beyond the timeout while corresponding resources are cleaned up. Use instead of readWriteTimeout.

Yes

1 - inf

abandonedCheckTs

5000

Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

0 - inf

attemptsObtainLock

Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

0 - inf

deadlockPreventionPolicy.txIdComparator

NATURAL

Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

NATURAL, REVERSED, NONE

deadlockPreventionPolicy.waitTimeout

Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

0 - inf

readOnlyTimeout

600000

Deprecated. Use readOnlyTimeoutMillis instead. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

1 - inf

readWriteTimeout

30000

Deprecated. Use readWriteTimeoutMillis instead. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

1 - inf

rpcTimeout

60000

Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

0 - inf

txnResourceTtl

30000

Deprecated. This property is obsolete and should not be used as it will not be supported in the future releases.

Yes

0 - inf

© 2025 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Oct 06, 2025