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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 in the quickstart guide.
Command Line
Scope
Global
Dynamic
Yes
Data Type
Numeric
Range
-2147483647 to 2147483647
Default
0
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
Command Line
Scope
Global
Dynamic
No
Data Type
String
Range
Human-readable string (max 15 chars) or UUID
Default
(unset)
TLS Variables
raft-tls-mode
Protection of the Raft cluster connections. This variable is read-only and must be set at server startup.
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_caorraft_ssl_capath.A certificate and key for this node:
raft_ssl_certandraft_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. 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.
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.
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.
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.
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. This variable is read-only and must be set at server startup.
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.
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>.<n>. Run openssl rehash on the directory to make these names. A directory with the certificates under other names gives no CA.
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.
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.
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. The TLS library opens a list by its hashed name, <8 hex digits>.r<n>. Run openssl rehash on the directory to make these names.
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.
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.
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.
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.
Command Line
Scope
Global
Dynamic
No
Data Type
Numeric
Range
0 to 4294967295
Default
9
This page is: Copyright © 2026 MariaDB. All rights reserved.
Last updated
Was this helpful?

