Configuring rqlite

How to configure rqlite

This page explains each command-line flag for rqlite, and provides some usage guidelines.

Flag Usage
--extensions-path Comma-delimited list of paths to directories, zipfiles, or tar.gz files containing SQLite extensions.
--http-addr HTTP server bind address. To enable HTTPS, set X.509 certificate and key.

This is the interface rqlite will listen on for API requests. 0.0.0.0 is an acceptable address and will mean that rqlite will listen on all interfaces.
--http-adv-addr Advertised HTTP server network address If not set, same as HTTP server bind address.

This is the HTTP API address an rqlite node will advertise to other nodes (and clients) as needed. This will need to be set if your rqlite node binds to all network addresses via 0.0.0.0, or if it binds to a private network address behind a firewall.
--http-allow-origin Value to set for Access-Control-Allow-Origin HTTP header.

You usually need to set this if if you're using a browser-based application to interfact with rqlite. You should set it to the the website that is serving the browser-based application e.g. --http-allow-origin="https://example.com".
--auth Path to the authentication file. If not set, authentication is not enabled.
--auto-backup Path to the auto-backup file. If not set, automatic backup is not enabled.
--auto-restore Path to the auto-restore file. If not set, automatic restore is not enabled.
--http-ca-cert Path to the CA certificate file for HTTPS communications.

If this value is set rqlite will use this CA certificate to validate any other X509 certficate presented to it, if the node needs to contact another node's HTTP API. It also uses this CA to verify any X509 certificates presented to it by clients connecting to its HTTPS API.
--http-cert Path to the X509 certificate for the HTTPS server. If not set HTTPS is not enabled.

This is the certificate rqlite will present to any client connecting to it via HTTPS.
--http-key Path to the private key for the HTTPS server.

This is the private key corresponding to the X509 certificate.
--http-verify-client Whether the HTTP server should verify client X509 certificates.

This allows you to control which clients can connect to the HTTPS API, as only clients presenting certificates that have been signed by the CA will be able to connect to the node.
--node-ca-cert Path to the CA certificate file for inter-node communications. May not be set.

If this path is set, and nodes enable TLS inter-node communications i.e. over the Raft TCP port, then the certificates presented by a node must be signed by this Certificate Authority.
--node-cert Path to the X509 certificate for inter-node communications.

Setting this path enables TLS-encrypted inter-node communications. Specifically this is the certificate presented by this node when another node connects to it. If not set the node does not enable TLS.
--node-key Path to the X509 key for inter-node communications.

This is the private key corresponding to the node's X509 certificate, which it uses for inter-node communications.
--node-no-verify Disables checking other nodes' X509 certificates for validity. Checking is enabled by default.

Validity is defined as signed by an acceptable CA, that the hostname in the certificate matches the hostname of the connecting node, and that the presented certificates are not expired.
--node-verify-client Enable mutual TLS for node-to-node communication. Disabled by default.

This allows a node to control which other nodes can connect to it. If a node attempting to connect to this node does not present a certificate signed by an acceptable CA, the connection will be refused.
--node-verify-server-name Hostname to verify on certificates returned by nodes.

When node verifies a certificate it normally checks that the hostname in the certificate matches the hostname of the connecting node. This flags explicitly tells the node which hostname will actually be in the presented certificate. This allows you to sign a single certificate, with a single hostname, and distribute that to all nodes. It's mostly useful when enabling mutual TLS.
--node-id Unique Raft ID for the node. If not set, defaults to the advertised Raft address.

While not required, providing an explicit ID to a node makes cluster management simpler. Once set a node's ID cannot change. If you do change it your cluster will not operate correctly.
--raft-addr Bind network address for the Raft server in the form address:port.

This is the interace rqlite will listen on for connections from other node, as part of managing Raft consensus. 0.0.0.0 is an acceptable address and will mean that `rqlite` will listen on all interfaces.
--raft-adv-addr Advertised Raft server address. If not set, same as Raft server bind address.

This is the Raft address an rqlite node will advertise to other nodes, as part of managing Raft consensus. This will need to be set if your node binds to all network addresses via 0.0.0.0, or if it binds to a private network address behind a firewall.
--join List of Raft addresses to use for a join attempt. Comma-delimited list of nodes in host:port format.

The node will try each join addresss, one after the other, until one succeeds or the join-attempt limit is reached.
--join-attempts Number of times a node should attempt to join a cluster using a given address.
--join-interval Time between retrying failed join operations.
--join-as User to perform join attempts as. If not set, joins anonymously.

If joining a cluster requires credentials you can a tell a node to read those credentials from a credential file, for the specified user. By using this flag you can avoid setting credentials in the command line you pass to rqlite, which can expose those credentials if someone has access to the process table.
--bootstrap-expect Minimum number of nodes required for a bootstrap.

This flag provides the number of expected nodes in the cluster. Either this value should not be provided or the value must agree with other nodes in the cluster. When provided, rqlite waits until the specified number of servers are available and then bootstraps the cluster. This allows an initial leader to be elected automatically.
--bootstrap-expect-timeout Maximum time a bootstrap operation can take.

If a bootstrap operation does not succeed with this time, cluster formation will abort.
--disco-mode Discovery mode. If not set, no node discovery is performed.
--disco-key Discovery prefix key.

This allows you to use the same Discovery infrastructure e.g. Consul with multiple different rqlite clusters. Each rqlite cluster can use a different prefix key to separate its Discovery information from other clusters using the same infrastructure.
--disco-config Path to Discovery configuration file. May not be set..
--on-disk-path Path to the SQLite on-disk database file. If not set, uses a file in the data directory..

Generally speaking you shouldn't need to set this. Your system is easiest to manage if you let rqlite manage the SQLite database. However this can be useful under certain performance-sensitive scenarious.
--fk Enable SQLite foreign key constraints.

SQLite doesn't enable foreign key constraints by default. If you'd like rqlite to automatically do so then set this flag. This flag must be set on every node in your cluster.
--auto-vacuum-int Automatic VACUUM interval. Use 0s to disable. If not set, automatic VACUUM is not enabled.

If set to a non-zero interval rqlite will execute VACUUM on the specified interval. This can help reduce SQLite disk usage, but writes are blocked while a VACUUM takes place. See the SQLite documentation for more information.
--auto-optimize-int Automatic optimization interval. Use 0h to disable.

If set to a non-zero interval rqlite will execute PRAGMA OPTIMIZE on the specified interval. This can help SQLite query performance. See the SQLite documentation for more information.
--raft-log-level Minimum logging level for the Raft subsystem.

Acceptable log levels are ERROR, WARN, INFO and DEBUG.
--raft-non-voter Configure as a non-voting node.

Adding non-voting (also known as read-only) nodes can help scale out query performance. Read-only nodes don't particpate in the Raft consensus system, but do receive the same stream of updates from the Leader as voting nodes do.
--raft-snap Number of outstanding log entries that trigger a snapshot.

Snapshotting is a critical part of the Raft subsystem, which involves storing a copy of the SQLite database and then truncating the Raft log. Writes are blocked during the Snapshot process, but more regular snapshotting can mean faster start-up times, as there will generally be fewer logs to apply when a node restarts.
--raft-snap-wal-size Size of a SQLite WAL file which triggers a snapshot.Set to 0 to disable.

rqlite, by default, will also trigger a snapshot if the WAL gets larger than 4MB. Large SQLite WAL files can decrease query performance, and since snapshotting involves checkpointing the WAL file, snapshotting is an effective way to limit WAL size. However writes are blocked during the snapshotting process, so it's trade-off.
--raft-snap-int Snapshot threshold check interval.

This controls how often the Raft subsystem will check if snapshotting is required, either due to the number of oustanding log entries, or due to WAL size.
--raft-leader-lease-timeout Leader lease timeout. Use 0s for Raft default.

This is used to control how long the "lease" lasts for being the Leader without being able to contact a quorum If a Leader reaches this interval without contact, it will step down as Leader.
--raft-timeout Heartbeat timeout for Raft consensus.

Specifies the time a Follower will wait without contact from a Leader before the Follower initiates an election.
--raft-election-timeout Election timeout for Raft consensus.

Specifies the time a Candidate will wait without contact from a Leader before the Candidate initiates a new election.
--raft-apply-timeout Log-apply timeout.
--raft-remove-shutdown Shutdown Raft if the node is removed from the cluster.

This ensures a node doesn't self-elect itself as Leader if it finds itself as the sole node in a single-node cluster.
--raft-cluster-remove-shutdown Node removes itself from the cluster on shutdown.

If enabled a node will attempt to remove itself from the cluster just before it shuts down. This is a best effort operation, and only occurs if the node is shut down gracefully.
--raft-shutdown-stepdown Relinquish leadership on shutdown.

If a node is being shutdown, and it's the Leader, this helps minimize the time the cluster is without a Leader. The leader will stop accepting client requests, make sure a target node is up to date and starts the transfer with a _TimeoutNow_ message. This message has the same effect as if the election timeout on the target server fires.
--raft-reap-node-timeout Duration after which a non-reachable voting node is reaped. If not set, no reaping takes place.

Use this feature with caution, otherwise you may reap a node which has simply become unreachable.
--raft-reap-read-only-node-timeout Duration after which a non-reachable non-voting node is reaped. If not set, no reaping takes place.

This can be useful if you have a deployment where non-voting nodes tend to come and go, and you want to avoid explicitly removing those nodes.
--cluster-connect-timeout Timeout when connecting to another node in the cluster.

This sets the maximum time a node will wait when attempting to connect to another node over the inter-node network connection.
--write-queue-capacity Default capacity of execute queues.

The larger this value the more Queued Write requests can be queued up internally by the node. This queue is asynchronously drained, as requests are transmitted through the Raft log. Any time the queue is full Queued Writes requests are blocked.
--write-queue-batch-size Default batch size for execute queues.

The larger the batch size the more Queued Write statements will be batched from the internal queue and stored in a single Raft log entry. However, larger batches will consume more memory, and may increase latency.
--write-queue-timeout Time after which internally queued Queued Writes will be sent on if the batch size isn't reached.
--write-queue-tx Use a transaction when executing a Queued Write batch.
--cpu-profile Write CPU profie information to a file at this path.
--mem-profile Write memory profie information to a file at this path.
--trace-profile Write trace profie information to a file at this path.
Last modified December 3, 2024: Update _index.md (dbcf373)