Configuring rqlite

How to configure rqlite

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

Flag	Usage
`-version`	Show version information and exit.
`-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 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 interact 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 authentication and authorization file. If not set, not enabled.
`-auto-backup`	Path to automatic backup configuration file. If not set, not enabled.
`-auto-restore`	Path to automatic restore configuration file. If not set, not enabled.
`-http-ca-cert`	Path to X.509 CA certificate for HTTPS. If this value is set rqlite will use this CA certificate to validate any other X509 certificate 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 HTTPS X.509 certificate. This is the certificate rqlite will present to any client connecting to it via HTTPS.
`-http-key`	Path to HTTPS X.509 private key. This is the private key corresponding to the X509 certificate.
`-http-verify-client`	Enable mutual TLS for HTTPS. 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 X.509 CA certificate for node-to-node encryption. If this path is set, and nodes enable TLS inter-node communications i.e. over the Raft TCP connection, then the certificates presented by other nodes must be signed by this Certificate Authority.
`-node-cert`	Path to X.509 certificate for node-to-node mutual authentication and encryption. 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 X.509 private key for node-to-node mutual authentication and encryption. This is the private key corresponding to the node's X509 certificate, which it uses for encrypting inter-node communications.
`-node-no-verify`	Skip verification of any node-node certificate. 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. 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 certificate returned by a node. 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 ID for node. If not set, set to 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`	Raft communication bind address. This is the interface 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 communication address. If not set, same as Raft 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`	Comma-delimited list of nodes, in host:port form, through which a cluster can be joined. The node will try each join address, one after the other, until one succeeds or the join-attempt limit is reached.
`-join-attempts`	Number of join attempts to make. This value determines the number of times a node should attempt to join a cluster using a given address.
`-join-interval`	Period between join attempts.
`-join-as`	Username in authentication file to join 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 for bootstrap process. If a bootstrap operation does not succeed with this time, cluster formation will abort.
`-disco-mode`	Choose clustering discovery mode. If not set, no node discovery is performed.
`-disco-key`	Key prefix for cluster discovery service. 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`	Set discovery config, or path to cluster discovery config file.
`-on-disk-path`	Path for SQLite on-disk database file. If not set, use a file in 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`	Period between automatic VACUUMs. It not set, 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`	Period between automatic 'PRAGMA optimize'. Set to 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 log level for Raft module. Acceptable log levels are ERROR, WARN, INFO and DEBUG.
`-raft-non-voter`	Configure as 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 which triggers Raft 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`	SQLite WAL file size in bytes which triggers Raft 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 outstanding log entries, or due to WAL size.
`-raft-leader-lease-timeout`	Raft 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`	Raft heartbeat timeout. Specifies the time a Follower will wait without contact from a Leader before the Follower initiates an election.
`-raft-election-timeout`	Raft election timeout. Specifies the time a Candidate will wait without contact from a Leader before the Candidate initiates a new election.
`-raft-apply-timeout`	Raft apply timeout.
`-raft-remove-shutdown`	Shutdown Raft if node removed from 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 cluster on graceful 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`	If leader, stepdown before shutting down. Enabled by default. 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`	Time after which a non-reachable voting node will be 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`	Time after which a non-reachable non-voting node will be 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 for initial connection to other nodes. 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`	QueuedWrites queue capacity. 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`	QueuedWrites queue batch size. 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`	QueuedWrites queue timeout.
`-write-queue-tx`	Use a transaction when processing a queued write.
`-cpu-profile`	Path to file for CPU profiling information.
`-mem-profile`	Path to file for memory profiling information. If set then memory profile information will be written to a file at the given path. This information can then be analyzed using the `go tool pprof`.
`-trace-profile`	Path to file for trace profiling information.

Last modified January 19, 2025: Adding missing > (4d64ca3)