> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/raft-cluster/raft-system-variables.md). # Raft System Variables A detailed reference for the system variables used by the Raft consensus implementation. These variables configure cluster heartbeat behavior, election timeouts, log management, and flow control ## List of Raft System Variables ### raft-vote-timeout Time candidate waits for a majority of granted votes during election. Uses exponential backoff up to raft\_max\_vote\_timeout. | Property | Value | | ------------ | ----------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (ms) | | Range | 100 to 4294967295 | | Default | 200 | ### raft-data-dir Data directory where to store replication logs and other node persistent state. | Property | Value | | ------------ | ------ | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | ./ | ### raft-applied-event-memory-limit Maximum size, in bytes, of received but not-yet-applied write set payloads before event delivery pauses. Set to `0` to disable the limit. | Property | Value | | ------------ | ----------------------------------- | | Command Line | --raft-applied-event-memory-limit=# | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (Bytes) | | Range | 0 to 18446744073709551615 | | Default | 134217728 (128 MB) | ### raft-event-store-file-size Maximum size of single log file in bytes. When a log file reaches this size, a new file is created. | Property | Value | | ------------ | -------------------------------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (Bytes) | | Range | 1048576 (1 MB) to 1048576000 (1000 MB) | | Default | 128MB | ### raft-event-store-max-memory Maximum size of the in-memory event store buffer in bytes. Events are cached in memory for faster access before being written to disk. | Property | Value | | ------------ | ---------------------------------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (Bytes) | | Range | 1048576 (1 MB) to 10485760000 (10000 MB) | | Default | 32MB | ### raft-event-store-max-size Maximum total size of the event store on disk in bytes. Older log files are purged when this limit is exceeded. | Property | Value | | ------------ | -------------------------------------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (Bytes) | | Range | 1048576 (1 MB) to 1048576000000 (1000000 MB) | | Default | 512MB | ### raft-flow-control-drift-limit Maximum index drift allowed between nodes before flow control throttling activates. When the difference between the slowest and fastest node commit positions exceeds this limit, the leader begins throttling requests. | Property | Value | | ------------ | --------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric | | Range | 0 to 4294967295 | | Default | 100 | ### raft-flow-control-max-throttle-rate Maximum request rate (requests per second) to sustain when flow control throttling is active. Lower values provide more aggressive throttling. | Property | Value | | ------------ | --------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric | | Range | 0 to 4294967295 | | Default | 100 | ### raft-election-timeout Time follower waits without leader messages before starting election. Should be significantly larger than raft\_heartbeat\_timeout to avoid unnecessary elections. | Property | Value | | ------------ | ----------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (ms) | | Range | 500 to 4294967295 | | Default | 5000 | ### raft-heartbeat-timeout Interval at which leader sends heartbeat messages (milliseconds). Shorter intervals provide faster failure detection but increase network traffic. | Property | Value | | ------------ | ----------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (ms) | | Range | 100 to 4294967295 | | Default | 1000 | ### raft-leadership-priority Priority for the current node to become leader. Nodes with a higher priority are preferred when a leader is elected. A leader that detects a follower with a higher priority steps down immediately, rather than waiting for the heartbeat timeout to expire. The priority can also be changed at runtime, without restarting the session — see [Leadership Priority](/docs/raft-cluster/mariadb-raft-cluster-quickstart-guide.md#leadership-priority) in the quickstart guide. | Property | Value | | ------------ | ------------------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric | | Range | -2147483647 to 2147483647 | | Default | 0 | {% hint style="warning" %} Leadership priority changes the cluster protocol, and is **not** backwards compatible with the 0.9.0 technical preview release. All nodes must run the same release. {% endhint %} ### raft-bind-address The local network address the node uses for its Raft cluster communication. The node binds its listening sockets to this address — both the acceptor for incoming cluster connections and the acceptor for incoming SST connections — and uses it as the source address when connecting out to the other nodes. On a host with several network interfaces, this confines all Raft traffic to one chosen interface, for example a dedicated internal or replication network, instead of the node listening on every interface. The value must be a local IPv4 or IPv6 address, without a port and without hostnames. By default the value is empty, so the node listens on all interfaces and the operating system selects the source address. | Property | Value | | ------------ | ------------------------ | | Command Line | --raft-bind-address=name | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-listen-port Port to listen for incoming cluster connections. | Property | Value | | ------------ | -------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric (Port) | | Range | 0 to 65535 | | Default | 50002 | ### raft-log-durability Durability level of Raft log writes. | Property | Value | | ------------ | -------------------------- | | Command Line | --raft-log-durability=name | | Scope | Global | | Dynamic | No | | Data Type | Enumeration | | Range | FLUSH, SYNC | | Default | FLUSH | ### raft-log-filter In order to reduce amount of logging on DEBUG level, this filter can be used to select output from specific operations. The format is comma separated list of strings, e.g. 'rvc\_send,rvc\_recv'. The actual useful values for filter depend on underlying Craft implementation and is subject to change. | Property | Value | | ------------ | ---------------------------------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | String | | Range | | | Default | admin,client,server,replication\_service | ### raft-log-level Verbosity level for logging. Supported values are ERROR, WARN, INFO and DEBUG. The DEBUG setting may get very verbose, so it should be used sparingly (see also raft\_log\_filter). | Property | Value | | ------------ | ------------------------ | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Enumeration | | Range | ERROR, WARN, INFO, DEBUG | | Default | INFO | ### raft-max-vote-timeout Upper bound for raft\_vote\_timeout after exponential backoff. Limits how long a candidate will wait between election attempts. | Property | Value | | ------------ | ----------------- | | Command Line | | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (ms) | | Range | 100 to 4294967295 | | Default | 1500 | ### raft-max-reconnect-attempts Number of attempts to reconnect to the cluster after ending up in non-primary state. | Property | Value | | ------------ | --------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric | | Range | 1 to 4294967295 | | Default | 5 | ### raft-node-id Unique node identifier. The identifier can be either a human-readable string up to 15 characters long or a UUID. If human-readable name is used, it must be unique within the cluster. If another node with the same name already exists in the cluster, the newly added node will fail connecting the cluster. The special value 'auto' is reserved for generating a UUID whenever the server starts from a clean state. This is mainly useful for test scenarios where the grastate.dat is removed, and the node is expected to rejoin the cluster before the previous instance is evicted from the group. | Property | Value | | ------------ | -------------------------------------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | Human-readable string (max 15 chars) or UUID | | Default | auto | ### raft-node-weight Node weight for replication and voting quorum. The default weight is 1, all nodes in the cluster have the same weight in voting and replication. {% hint style="danger" %} **PRODUCTION WARNING:** Using unequal weights in a cluster is unsafe for production workloads. Weighted quorum does not guarantee that data is replicated on the majority of servers before log events are committed on the leader, which can lead to data loss scenarios. This setting is mainly useful for testing and should not be used in production. {% endhint %} | Property | Value | | ------------ | -------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric | | Range | 1 to 256 | | Default | 1 | ### raft-liveness-timeout Timeout after which the node is considered unresponsive. If no replication events appear in the log within this period, the node moves to non-primary state. | Property | Value | | ------------ | ------------------ | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric (ms) | | Range | 1000 to 4294967295 | | Default | 20000 | ### raft-eviction-timeout Timeout after which session to replication system is considered expired if there is no activity. If the node cannot communicate with the leader within this time period, it will be evicted from the cluster. | Property | Value | | ------------ | ------------------ | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric (ms) | | Range | 1000 to 4294967295 | | Default | 15000 | ### raft-key-rotation-check-interval Interval, in seconds, at which the Raft plugin checks whether the binary log master key has been rotated and, if it has, pushes the new key to the Raft server. This variable has an effect only when `encrypt_binlog` is enabled. See [Data-at-Rest Encryption](/docs/raft-cluster/mariadb-raft-cluster-quickstart-guide.md#data-at-rest-encryption). | Property | Value | | ------------ | ------------------------------------ | | Command Line | --raft-key-rotation-check-interval=# | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (s) | | Range | 1 to 4294967295 | | Default | 60 | ### raft-sst-listen-port Port to listen for SST requests. | Property | Value | | ------------ | -------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric (Port) | | Range | 0 to 65535 | | Default | 50001 | ### raft-segment-id Read-only datacenter segment identifier. The identifier can be either a human-readable string up to 15 characters long or a UUID. By default it is unset, meaning no segmentation is applied. | Property | Value | | ------------ | -------------------------------------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | Human-readable string (max 15 chars) or UUID | | Default | (unset) | ### raft-key-rotation-check-interval Interval, in seconds, at which the plugin checks for a rotated binary log master key and gives the updated key to the Raft server. Effective only when `encrypt_binlog` is `ON`. See [Raft Event Log Encryption](/docs/raft-cluster/mariadb-raft-cluster-quickstart-guide.md#raft-event-log-encryption). | Property | Value | | ------------ | ------------------------------------ | | Command Line | --raft-key-rotation-check-interval=# | | Scope | Global | | Dynamic | Yes | | Data Type | Numeric (s) | | Range | 1 to 4294967295 | | Default | 60 | ## TLS Variables {% hint style="info" %} The variables `raft_have_ssl` and `raft_ssl_verify_server_cert` were removed in Raft Cluster 1.0.0. Use [raft-tls-mode](#raft-tls-mode). A node does not start with a removed variable in its configuration. {% endhint %} ### raft-tls-mode Protection of the Raft cluster connections. This variable is read-only and must be set at server startup. | Value | Meaning | | ----------- | ------------------------------------------------------------------------------------------------------ | | `DISABLED` | No TLS. Connections are plaintext. | | `ENCRYPT` | TLS without peer authentication. Any peer is accepted, so an active man-in-the-middle is not excluded. | | `VERIFY_CA` | TLS. Both ends validate the peer certificate against `raft_ssl_ca` or `raft_ssl_capath`. | `VERIFY_CA` needs this configuration. Without it, the node does not start: * A CA: `raft_ssl_ca` or `raft_ssl_capath`. * A certificate and key for this node: `raft_ssl_cert` and `raft_ssl_key`, or one of them alone if that file holds both. Each node accepts and initiates connections, and the peer requires a certificate on both. The default is `VERIFY_CA`, so a node with no TLS configuration does not start. Under `VERIFY_CA`, the node also validates its own certificates as a peer would, at startup and at `FLUSH SSL`. See [TLS Configuration Checks](/docs/raft-cluster/mariadb-raft-cluster-quickstart-guide.md#tls-configuration-checks). The node does not check a host name or a subject. A configured certificate does not change the mode. It changes only what the node presents. The node logs the mode at startup, and logs a warning when the mode does not authenticate the peer (`DISABLED` or `ENCRYPT`). The same mode applies to the connections of the plugin, of the Raft server process, and of the state transfer client. {% hint style="warning" %} You cannot change from `DISABLED` to `ENCRYPT` or `VERIFY_CA` with a rolling restart. The change needs a full cluster outage. A change from `ENCRYPT` to `VERIFY_CA` can be done with rolling restarts. See [Choose a TLS Setup](/docs/raft-cluster/mariadb-raft-cluster-quickstart-guide.md#choose-a-tls-setup-on-each-node). {% endhint %} | Property | Value | | ------------ | ----------------------------- | | Command Line | --raft-tls-mode=name | | Scope | Global | | Dynamic | No | | Data Type | Enumeration | | Range | DISABLED, ENCRYPT, VERIFY\_CA | | Default | VERIFY\_CA | ### raft-ssl-key Path to the SSL private key file in PEM format. This variable is read-only and must be set at server startup. The key must not have a passphrase. One file can hold the key and the certificate. Then this option alone is a complete configuration. The node does not start if all accounts can write the key file. It logs a warning if the group or other accounts have any access to it. This applies to each file that holds a private key. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-cert Path to the SSL certificate file in PEM format. This variable is read-only and must be set at server startup. The file can hold intermediate CA certificates after the node certificate. If the file also holds the key, this option alone is a complete configuration. The node presents this certificate on the connections it accepts. It also presents it on the connections it initiates, unless `raft_ssl_client_cert` or `raft_ssl_client_key` is set. Under `VERIFY_CA`, a certificate with an extended key usage must then include `serverAuth` and `clientAuth`. If neither this nor `raft_ssl_key` is set, the node generates a self-signed certificate at startup for the connections it accepts. No CA signs it, so only `ENCRYPT` can use it. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-client-cert Path to the certificate file in PEM format that the node presents on the connections it initiates. The file can hold intermediate CA certificates after the certificate. If the file also holds the key, this option alone is a complete configuration. This variable is read-only and must be set at server startup. Use it when the CA issues a certificate for one TLS role only. Then `raft_ssl_cert` holds a `serverAuth` certificate, and this option holds a `clientAuth` certificate. When neither this nor `raft_ssl_client_key` is set, `raft_ssl_cert` and `raft_ssl_key` serve both roles. | Property | Value | | ------------ | --------------------------- | | Command Line | --raft-ssl-client-cert=name | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-client-key Path to the private key file in PEM format for `raft_ssl_client_cert`. The same rules apply as for [raft-ssl-key](#raft-ssl-key). This variable is read-only and must be set at server startup. | Property | Value | | ------------ | -------------------------- | | Command Line | --raft-ssl-client-key=name | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-ca Path to the CA certificate file in PEM format used to verify peer certificates. This variable is read-only and must be set at server startup. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-capath Path to a directory containing CA certificate files in PEM format. This variable is read-only and must be set at server startup. The TLS library does not read the directory. It opens a CA by its hashed name, `<8 hex digits>.`. Run `openssl rehash` on the directory to make these names. A directory with the certificates under other names gives no CA. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-cipher OpenSSL cipher list for TLS 1.2 and below. Uses OpenSSL cipher string format. This variable is read-only and must be set at server startup. When unset, only forward-secret AEAD suites are used: ECDHE or DHE key exchange with AES-GCM or ChaCha20-Poly1305. The node does not start if the list selects no cipher that the TLS library supports. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-crl Path to the Certificate Revocation List (CRL) file. This variable is read-only and must be set at server startup. When `raft_ssl_crl` or `raft_ssl_crlpath` is set, revocation is checked for each certificate in the peer chain, not only for the peer certificate. Thus each CA in the chain must have a current list. A CA without a list, or with an expired list, causes validation to fail. If nothing is revoked, configure an empty list. Issue a new list before the `Next Update` time of the current one. The file can hold the lists of more than one CA. The lists are read when a TLS context is built. To put a changed list in force, use `FLUSH SSL`. See [Reloading TLS Material](/docs/raft-cluster/mariadb-raft-cluster-quickstart-guide.md#reloading-tls-material). | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-crlpath Path to a directory containing Certificate Revocation List files. This variable is read-only and must be set at server startup. The same rules apply as for [raft-ssl-crl](#raft-ssl-crl). The TLS library opens a list by its hashed name, `<8 hex digits>.r`. Run `openssl rehash` on the directory to make these names. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-tls-version Comma-separated list of allowed TLS protocol versions: `TLSv1.2` and `TLSv1.3`. The default includes both. TLS 1.2 is the lowest version that the node negotiates. Renegotiation and TLS compression are always disabled. This variable is read-only and must be set at server startup. | Property | Value | | ------------ | ---------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Set | | Range | TLSv1.2, TLSv1.3 | | Default | TLSv1.2,TLSv1.3 | ### raft-ssl-ciphersuites List of permitted TLS 1.3 ciphersuites. This is separate from raft\_ssl\_cipher which applies to earlier TLS versions. This variable is read-only and must be set at server startup. When unset, the node uses `TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256`. The node does not start if the list selects no suite that the TLS library supports. | Property | Value | | ------------ | ------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | String | | Range | | | Default | (empty) | ### raft-ssl-verbose Verbose logging level for SSL context initialization: `0` disables verbose logging, `1` enables it, and `2` also enables SSL diagnostic callbacks. This variable is read-only and must be set at server startup. | Property | Value | | ------------ | -------------------- | | Command Line | --raft-ssl-verbose=# | | Scope | Global | | Dynamic | No | | Data Type | Numeric | | Range | 0 to 2 | | Default | 0 | ### raft-ssl-verify-depth Maximum depth for certificate chain verification. This variable is read-only and must be set at server startup. | Property | Value | | ------------ | --------------- | | Command Line | | | Scope | Global | | Dynamic | No | | Data Type | Numeric | | Range | 0 to 4294967295 | | Default | 9 | *This page is: Copyright © 2026 MariaDB. All rights reserved.*