Table Of Contents

2. Configuration

2.1. QuasarDB Daemon

QuasarDB stores its configuration options in a qdbd.conf file. The precise location on where this file resides depends on on your method of installation, but is typically /etc/qdb/qdbd.conf.

This section is organised per component, and describes the configuration options relevant to each of those.

2.1.1. License

You can set a license either by file or by putting the license key as a string directly into your configuration.

Variable

Description

local.user.license_file

Absolute location to the license file. Be careful to ensure the license file is readable by the qdb user, otherwise the license will not activate.

local.user.license_key

License key as a string.

2.1.2. Storage

Variable

Description

global.cluster.storage.engine

Specifies which storage engine to use. Accepted values: rocksdb or helium. Defaults to rocksdb.

local.depot.rocksdb.root

Location to the root folder of where your database files are stored. Defaults to /var/lib/qdb.

local.depot.rocksdb.disable_wal

Disables the Write-Ahead-Log (WAL). Will cause significant performance increases if disabled, but you will lose single-server durability. Disable with caution.

local.depot.rocksdb.threads

Should be increased if the daemon is under constant insertion pressure, and there is still available CPU: it increases the amount of threads the storage engine has available for background operations such as compaction.

local.depot.rocksdb.hi_threads

The number of high-priority threads, in addition to local.depot.rocksdb.threads. Should typically be left to 2.

2.1.3. Networking

Variable

Description

local.network.listen_on

Local address and port to bind to for accepting new connections. Can also refer to network adapter, e.g. eth0:2836. Defaults to 127.0.0.1:2836.

local.network.advertise_as

Specify if the local address we bind to is not the same as other nodes or clients should use to connect to the daemon (e.g. when behind a NAT). Defaults to 127.0.0.1:2836.

local.network.idle_timeout

Time (in milliseconds) until a server socket is automatically recycled.

local.network.client_timeout

Time (in milliseconds) until a client connection without activity is automatically disconnected.

local.network.max_in_buffer_size

Size of the buffer the server allocates for receiving data from clients. Increase this size if you experience unexpected closed connections from the client, or the server logs mention cannot send data: Broken pipe.

local.network.max_out_buffer_size

Size of the buffer the server allocates for sending data to clients. Increase this size if you experience unexpected closed connections from the client, or the server logs mention cannot send data: Broken pipe.

2.1.4. Clustering

Variable

Description

local.chord.node_id

Unique identifier for this node. See also: Node ID configuration.

local.chord.bootstrapping_peers

One or more peers that should be connected to to discover and bootstrap the cluster. Peers should be specified as a JSON array of tuples of address:port, e.g. ``[“192.168.1.1:2836”, “192.168.1.2:2836”].

local.chord.replication_factor

Replication factor of data stored inside the cluster. Must be equal to or lower than the amount of nodes in your cluster, and not higher than 4. A replication factor of 1 means no replication.

2.1.5. Security

Variable

Description

global.security.enabled

Boolean that determines whether security should be enabled. Valid values are true and false. Defaults to false. Enabling this to true requires you to set valid values for user_list and cluster_private_file.

global.security.user_list

Absolute location to the file that contains the QuasarDB users. Typically should be /etc/qdb/users.txt. The file can be created and managed using the QuasarDB user management tool, and needs to be identically replicated accross all QuasarDB daemon nodes.

global.security.cluster_private_file

Absolute location to the cluster private key file. Typically should be /etc/qdb/cluster_private.key. The file can be created and managed using the QuasarDB cluster keygen, and needs to be identically replicated accross all QuasarDB daemon nodes.

global.security.encrypt_traffic

Boolean that determines whether node-to-node communication should be encrypted. Valid values are true and false. Defaults to false.

2.1.6. Performance tuning

Variable

Description

local.network.server_sessions

How many sessions (connections) each server thread is able to handle concurrently. Too few will cause significant performance degradations. Increase this value if you see “out of free server sessions” messages in the logs.

local.network.partitions_count

Determines the amount of threads in the main worker pool. Handles blocking I/O operations, and should be increased if your clients are waiting on the server but the server is not at 100% CPU.

local.depot.rocksdb.max_open_files

Maximum number of open files that the storage engine is allowed to use. This should typically be close to the number of files the qdb user is allowed to open (i.e. the output of ulimit -n). Too low will cause significant performance degradations, and you are recommended to use at least 60000 in production.

local.limiter.max_bytes_soft

The maximum amount of memory (in bytes) QuasarDB will use. Any usage above this will cause QuasarDB to evict entries from its cache.

local.limiter.max_bytes_hard

Same like local.limiter.max_bytes_soft, except that processing is temporarily halted when this limit is reached.

2.1.7. Observability

Variable

Description

local.logger.log_level

An integer representing verbosity. Use 0 for most verbose logs, 5 for only fatal logs. Defaults to 2. Level 1 (debug) will also enable separate storage engine logs.

local.logger.log_directory

Absolute path where log files will be written into. Defaults to /var/log/qdb.

local.network.profile_performance

Enables performance profiling from the server side, so that clients can start running performance traces. It has a small performance impact, and is disabled by default.

global.cluster.enable_statistics

Enables runtime statistics collected server side. It has a small performance impact, and is disabled by default.

global.cluster.statistics_refresh_interval

Time (in milliseconds) between refreshes of the statistics. Should typically be set to the interval in which you query the node statistics; e.g. if you only poll your statistics once a minute, this value should be 60000.

2.1.8. Asynchronous Timeseries Inserter

The asynchronous timeseries inserter is a mechanism in QuasarDB to buffer inserts server-side, which you can tune using the configuration options below.

Variable

Description

local.depot.async_ts.pipelines

The number of asynchronous time series pipelines. Increase this number if you are experiencing slow inserts, but CPU is not yet at 100%.

local.depot.pipeline_buffer_size

Maximum size of the buffer in bytes for each of the pipelines. Increase this value to if you are experiencing slow inserts and CPU is at 100%.

local.depot.pipeline_queue_length

Maximum number of entries to buffer for each of the pipelines. Increase this value to if you are experiencing slow inserts and CPU is at 100%.

2.2. QuasarDB Rest Server

The QuasarDB Rest Server qdb_rest can be configured using either command line arguments, a json config file or environmental variables. See below for examples of each configuration as well as the various configuration options:

# Environment variable based configuration
QDB_CLUSTER_URI=qdb://192.168.0.1:2837 qdb_rest

# Command line based configuration
qdb_rest --cluster=qdb://192.168.0.1:2837

# File based configuration
qdb_rest --gen-config > rest.conf # Generate a new config file and edit
qdb_rest --config-file rest.conf

Command Line Variable

Environment Variable

Description

Default

--allowed-origins

Allowed origins for cross origin resource sharing

[]

--cluster

QDB_CLUSTER_URI

URI of the cluster to connect to

qdb://127.0.0.1:2836

--cluster-public-key-file

QDB_CLUSTER_PUBLIC_KEY_FILE

Key file used for cluster security

--tls-certificate

TLS_CERTIFICATE

The certificate to use for secure connections

--tls-key

TLS_PRIVATE_KEY

The private key to use for secure conections

--tls-port

TLS_PORT

The port to listen on for secure connections

40493

--host

HOST

The IP to listen on

localhost

--port

PORT

The port to listen on for insecure connections

40080

--log-file

QDB_REST_LOG_FILE

The path to the log file

/var/log/qdb/qdb_rest.log

--assets-dir

QDB_REST_ASSETS_DIR

The path to the directory served by the rest api

/var/lib/qdb/assets

2.3. Docker

As it can a bit tedious to edit a configuration file inside a Docker container, the bureau14/qdb docker container provides several environment variables you can use to configure the most common configuration options.

Below you find an overview of the different environment variables the image supports:

Variable

Description

Example usage

QDB_LICENSE

QuasarDB license key (as string)

docker run -d \
       -e QDB_LICENSE="$your_license_key" \
       bureau14/qdb

QDB_LICENSE_FILE

QuasarDB license key (as file)

docker run -d \
       -v /path/to/my/qdb.key:/qdb.key \
       -e QDB_LICENSE_FILE=/qdb.key \
       bureau14/qdb

QDB_ENABLE_SECURITY

If “true”, enables security; requires private key and user list to be specified

docker run -d \
       -e QDB_ENABLE_SECURITY=true \
       -e QDB_CLUSTER_PRIVATE_KEY=... \
       -e QDB_USER_LIST=... \
       bureau14/qdb

QDB_PRIVATE_KEY

QuasarDB cluster private key (as string)

docker run -d  \
       -e QDB_ENABLE_SECURITY=true \
       -e QDB_CLUSTER_PRIVATE_KEY=... \
       -e QDB_USER_LIST=... \
       bureau14/qdb

QDB_PRIVATE_KEY_FILE

QuasarDB cluster private key (as file)

docker run -d \
       -e QDB_ENABLE_SECURITY=true \
       \
       -v /path/to/my/qdb/private.key:/private.key \
       -e QDB_CLUSTER_PRIVATE_KEY_FILE=/private.key \
       \
       -e QDB_USER_LIST=... \
       bureau14/qdb

QDB_USER_LIST

QuasarDB user list (as string)

docker run -d \
       -e QDB_ENABLE_SECURITY=true \
       -e QDB_CLUSTER_PRIVATE_KEY=... \
       -e QDB_USER_LIST=... \
       bureau14/qdb

QDB_USER_LIST_FILE

QuasarDB user list (as file)

docker run -d \
       -e QDB_ENABLE_SECURITY=true \
       -e QDB_CLUSTER_PRIVATE_KEY=... \
       \
       -v /path/to/my/qdb/user.list:/user.list \
       -e QDB_USER_LIST_FILE=/user.list \
       \
       bureau14/qdb
arrow_backPrevious
1. Installation
Next arrow_forward
3. Routine maintenance tasks