Skip to main content

Server Settings

Top-Level Keys​

KeyFlagEnv varDefaultDescription
listen--addrLYNXDB_LISTENlocalhost:3100HTTP listen address (host:port). Use 0.0.0.0:3100 to accept remote and container traffic.
data_dir--data-dirLYNXDB_DATA_DIR$XDG_DATA_HOME/lynxdb or ~/.local/share/lynxdbRoot directory of the indexes, the API keys, the self-signed certificate and the PID file. Empty keeps the indexes in a temporary directory that is removed at shutdown.
retentionnoneLYNXDB_RETENTION7dEvents older than this are dropped, a whole time partition at a time. 0 keeps everything. See Storage Settings.
log_level--log-levelLYNXDB_LOG_LEVELinfodebug, info, warn or error. Reloadable.
lynxdb server --addr 0.0.0.0:3100 --data-dir /var/lib/lynxdb
LYNXDB_RETENTION=30d lynxdb server

Empty Data Directory​

lynxdb server --data-dir ""

With an empty data_dir the server keeps its indexes in a temporary directory and removes it at shutdown, so nothing outlives the process. The features that keep files next to the data are unavailable: API key authentication (the server runs without auth even when --auth is set) and the self-signed certificate (--tls without a certificate refuses to start). The PID file goes to $XDG_RUNTIME_DIR or the system temp directory.

TLS​

KeyFlagEnv varDefault
tls.enabled--tlsLYNXDB_TLS_ENABLEDfalse
tls.cert_file--tls-certLYNXDB_TLS_CERT_FILEempty
tls.key_file--tls-keyLYNXDB_TLS_KEY_FILEempty

The certificate and key must be set together. The --tls-cert and --tls-key flags turn TLS on by themselves; in the config file, set tls.enabled: true with them. With TLS on and no certificate, the server generates a self-signed certificate under <data_dir>/tls/ and prints its SHA-256 fingerprint at startup. The minimum protocol version is TLS 1.2. Certificate changes need a restart.

lynxdb server --tls
lynxdb server --tls-cert /etc/lynxdb/tls/server.crt --tls-key /etc/lynxdb/tls/server.key

Authentication​

KeyFlagEnv varDefault
auth.enabled--authLYNXDB_AUTH_ENABLEDfalse

With auth on, API routes under /api/ require an API key. Keys are stored in <data_dir>/auth/. On the first start with no keys, the server generates a root key and prints it once to stderr. Manage keys with lynxdb auth create, list, revoke and rotate-root, which take the root key; scopes are ingest, query, admin and full.

See TLS and Authentication for the request schemes, the routes that stay open, and the client setup.

HTTP​

KeyEnv varDefaultDescription
http.idle_timeoutLYNXDB_HTTP_IDLE_TIMEOUT120sKeep-alive idle timeout. Minimum 1s.
http.shutdown_timeoutLYNXDB_HTTP_SHUTDOWN_TIMEOUT30sGraceful shutdown deadline for requests in flight. Minimum 1s. Reloadable.
http.read_header_timeoutnone10sDeadline for reading request headers.
http.rate_limitLYNXDB_HTTP_RATE_LIMIT0Requests per second per client IP, with bursts of twice that. 0 disables the limiter.

Server Flags​

Every flag of lynxdb server, with the config key it sets:

FlagConfig key
--config <path>config file path (global flag)
--addrlisten
--data-dirdata_dir
--log-levellog_level
--tlstls.enabled
--tls-cert, --tls-keytls.cert_file, tls.key_file
--authauth.enabled
--syslog <addr>syslog.udp and syslog.tcp (port 5514 when omitted)
--syslog-udp, --syslog-tcpsyslog.udp, syslog.tcp
--syslog-tlssyslog.tls (TCP port 6514 when omitted)
--syslog-parser, --syslog-indexsyslog.parser, syslog.index
--ingest-es-enabledingest.es_compat.enabled
--ingest-es-versioningest.es_compat.advertised_version
--otlp-http-listen, --otlp-grpc-listeningest.otlp.http_listen, ingest.otlp.grpc_listen
--otlp-grpc-max-recv-bytesingest.otlp.grpc_max_recv_bytes
--ingest-max-compressed-body-bytesingest.limits.max_compressed_body_bytes
--ingest-max-decompressed-body-bytesingest.limits.max_decompressed_body_bytes
--profile-runtimenone: turns on mutex and block profiling for the pprof endpoints under /api/v1/debug/pprof/ (2 to 5% overhead)

The startup banner lists the config file in use and every environment variable and flag that overrode it.

Complete Example​

listen: "0.0.0.0:3100"
data_dir: "/var/lib/lynxdb"
retention: "30d"
log_level: "info"

tls:
enabled: true
cert_file: "/etc/lynxdb/tls/server.crt"
key_file: "/etc/lynxdb/tls/server.key"

auth:
enabled: true

http:
idle_timeout: "120s"
shutdown_timeout: "30s"
rate_limit: 200