Single Node Deployment
One lynxdb server process handles ingest, storage and queries.
Install
curl -fsSL https://lynxdb.org/install.sh | sh
lynxdb version
The script installs the binary only. Archives for Linux, macOS and Windows are also attached to each GitHub release.
To try it in the foreground with the defaults (localhost:3100, data in ~/.local/share/lynxdb):
lynxdb server
Production Setup
1. Create a user and directories
sudo useradd --system --no-create-home --shell /usr/sbin/nologin lynxdb
sudo mkdir -p /var/lib/lynxdb /etc/lynxdb
sudo chown lynxdb:lynxdb /var/lib/lynxdb
2. Write the config file
sudo lynxdb config init --system
This writes the commented template with every default to /etc/lynxdb/config.yaml. Edit the values you need:
listen: "0.0.0.0:3100"
data_dir: "/var/lib/lynxdb"
retention: "30d"
log_level: "info"
storage:
partition: "24h"
query:
max_concurrent: 32
ingest:
otlp:
http_listen: "" # set an address only if you ship OTLP; see Firewall
auth:
enabled: true
Check it:
sudo -u lynxdb lynxdb config validate --config /etc/lynxdb/config.yaml
3. Create the systemd unit
/etc/systemd/system/lynxdb.service:
[Unit]
Description=LynxDB log analytics database
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=lynxdb
Group=lynxdb
ExecStart=/usr/local/bin/lynxdb server --config /etc/lynxdb/config.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5s
LimitNOFILE=65536
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/lynxdb
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
Adjust the ExecStart path to where the binary is installed. If the syslog receiver listens on a port below 1024, add AmbientCapabilities=CAP_NET_BIND_SERVICE.
4. Start and verify
sudo systemctl daemon-reload
sudo systemctl enable --now lynxdb
sudo journalctl -u lynxdb -f
With auth.enabled: true, the first start prints a root key to the journal once. Save it, then:
lynxdb login --server http://localhost:3100
lynxdb health
lynxdb status
lynxdb query 'source=main | stats count() by host'
Settings by Environment Variable
Instead of editing the file, a systemd drop-in can set variables:
# /etc/systemd/system/lynxdb.service.d/env.conf
[Service]
Environment=LYNXDB_RETENTION=30d
Environment=LYNXDB_LOG_LEVEL=info
sudo systemctl daemon-reload
sudo systemctl restart lynxdb
See Environment Variables for the full list.
TLS and Authentication
# Self-signed certificate stored under <data_dir>/tls/
lynxdb server --config /etc/lynxdb/config.yaml --tls --auth
# Your own certificate
lynxdb server --config /etc/lynxdb/config.yaml \
--tls-cert /etc/lynxdb/tls/server.crt \
--tls-key /etc/lynxdb/tls/server.key \
--auth
Put the same settings in the tls and auth sections of the config file to keep ExecStart short. See TLS and Authentication.
Firewall
| Port | Purpose |
|---|---|
| 3100/tcp | HTTP API (listen) |
| 4318/tcp | OTLP/HTTP listener (ingest.otlp.http_listen, on all interfaces by default, without auth) |
| 5514/udp, 5514/tcp, 6514/tcp | Syslog, when configured |
sudo ufw allow 3100/tcp
# or
sudo firewall-cmd --permanent --add-port=3100/tcp && sudo firewall-cmd --reload
Reloading Configuration
sudo systemctl reload lynxdb
# or
sudo -u lynxdb lynxdb config reload --config /etc/lynxdb/config.yaml
A reload re-reads the config file and environment and applies log_level, the query.* settings except query.max_concurrent and query.job_ttl, and parts of ingest.* and syslog.*. retention, storage.*, listen addresses, data_dir, TLS and auth need a restart; the server logs the changes it left unapplied. The full list is in Configuration Overview.
Sizing
- Disk: every index keeps its events in compressed columnar part files under
data_dir. Putdata_diron SSD. Retention deletes whole time partitions (storage.partition, one day by default), so plan for the retention period plus one partition. See Retention for measuring the size of your data. - Memory: ingested events wait in memory until the store writes them, at most
storage.flush_interval(one second by default). Queries hold the rows they aggregate, sort or return. - CPU: the store merges parts in the background; queries share the cores among themselves.
Logs
The server writes its log to stdout (text format, level from log_level); under systemd it goes to the journal. Every HTTP request except /health is logged at INFO with its status and duration; see Monitoring.
Backup
The simplest backup is a copy of the data directory while the server is stopped:
sudo systemctl stop lynxdb
sudo tar czf /backups/lynxdb-$(date +%Y%m%d).tar.gz -C /var/lib lynxdb
sudo systemctl start lynxdb
See Backup and Restore for other strategies.