Operate

CLI reference

Both binaries print their own usage with help, and everything on this page is reachable without opening the dashboard. Commands that check something exit non-zero when the answer is no, so they work inside a provisioning run.

torwarden-agent

torwarden-agent [-config PATH]      run the agent (this is what the service does)
torwarden-agent check [-config PATH] [-v] [-timeout D]
                                    check the configuration and the server connection
torwarden-agent version             print the version
torwarden-agent help                print usage

check

Validates the configuration file and proves the agent can reach the server and authenticate. Run it after installing and before starting the service.

$ torwarden-agent check
ok    configuration /etc/torwarden/agent.conf
ok    hostname web-01, reporting every 30s
ok    reached https://torwarden.example.com
ok    the API key is accepted

This agent is configured correctly. Start it with:
  systemctl start torwarden-agent

It never stores a reading. The check authenticates with a request the server cannot decode, so a valid key is confirmed and nothing is written. Running it does not make a host look like it is up before its agent has started.

Exit status is 0 when everything passed and 1 otherwise, with the reason on stderr.

Windows service management

torwarden-agent install      # register the Windows service
torwarden-agent start
torwarden-agent stop
torwarden-agent uninstall

torwarden-server

torwarden-server [-config PATH] [-no-tls]
                                  run the server
torwarden-server check            check configuration, data directory and database
torwarden-server backup --to FILE consistent backup while the server keeps running
torwarden-server tls status       show the installed certificate and when it expires
torwarden-server tls import -cert FILE -key FILE [-hostname NAME] [-enable]
                                  install a certificate from files
torwarden-server seed             generate a synthetic fleet, for testing
torwarden-server stats            print database and retention figures
torwarden-server bench            measure ingest and query throughput
torwarden-server version          print the version
torwarden-server help             print usage

check

Validates the configuration, that the data directory exists and is writable, and that the database opens — which runs every pending migration, the part most likely to fail on an upgrade and the part there is otherwise no way to test without starting the server for real.

$ sudo torwarden-server check
ok    configuration /etc/torwarden/server.conf
ok    listening on :8080
ok    data directory /var/lib/torwarden is writable
ok    database opens and is up to date
ok    42 host(s) registered
warn  no certificate installed — this server is serving plain HTTP
      Install one with `torwarden-server tls import -cert FILE -key FILE`.

This server is configured correctly.

backup

Takes a consistent backup without stopping the server, and writes it as a gzipped tar in the layout the restore procedure expects.

$ sudo torwarden-server backup --to /var/backups/torwarden-2026-09-03.tar.gz
Backing up 5 databases from /var/lib/torwarden while the server runs.
  fleet.db                           456.0 KiB
  metrics/2026-09-03.db              1.4 MiB
  rollups/1h/2026-01-01.db            40.0 KiB
  rollups/1m/2026-09-03.db            1.2 MiB
  rollups/5m/2026-09-01.db           280.0 KiB

Wrote /var/backups/torwarden-2026-09-03.tar.gz (978.9 KiB from 3.4 MiB of database).

Each database is snapshotted with VACUUM INTO inside a read transaction, so what lands is one consistent instant rather than a file, a log and a shared-memory index copied at three different moments. Every copy is integrity-checked before the archive is written; pass --skip-verify to skip that on a very large estate, bearing in mind that the check is the difference between a backup and a directory of files.

The archive carries ownership by name as well as by number, so a backup taken on one distribution restores correctly onto another where the torwarden account has a different user id. Restore with tar xzf … -C /.

tls import

Installs a certificate and key from PEM files. The material is validated first — chain order, whether the key matches the certificate, whether it covers the hostname, expiry, weak algorithms — using the same checks the settings page runs. Material that would leave a server unable to start is refused rather than stored.

sudo torwarden-server tls import \
  -cert /etc/letsencrypt/live/torwarden.example.com/fullchain.pem \
  -key  /etc/letsencrypt/live/torwarden.example.com/privkey.pem \
  -hostname torwarden.example.com -enable

The listener binds at start, so a renewal takes effect on restart:

sudo systemctl restart torwarden-server

tls status

Prints the installed certificate, its names, its expiry and whether HTTPS is on. Exits non-zero when the certificate cannot be served, so it doubles as a check on the monitoring server itself — the one machine Torwarden cannot watch for you.

$ torwarden-server tls status
subject     CN=torwarden.example.com
issuer      CN=E5
names       torwarden.example.com
key         ECDSA P-256
valid from  2026-08-29T13:15:26Z
expires     2026-11-27T13:15:26Z (90 days)
https       on on :443

Renewal from cron

Everything needed for an unattended renewal is here, which is why these commands exist:

#!/bin/sh
set -e
certbot renew --quiet
torwarden-server tls import \
  -cert /etc/letsencrypt/live/torwarden.example.com/fullchain.pem \
  -key  /etc/letsencrypt/live/torwarden.example.com/privkey.pem
systemctl restart torwarden-server
torwarden-server tls status

-no-tls

Ignores the stored HTTPS configuration and serves plain HTTP. The way back in after installing a certificate that will not load, or switching HTTPS on before DNS was ready.

seed, stats and bench

Testing tools rather than day-to-day operations. seed generates a synthetic fleet with history; stats reports database size and retention; bench measures ingest and query throughput on your hardware. Each takes -h for its own flags.

Exit status

Every command in this reference returns 0 on success and 1 on failure, with the reason on stderr. Anything that fails says what to do about it where there is something to say.