Run it with a clear view.

Docker deployment#

Published images cover linux/amd64 and linux/arm64. The image runs as a non-root user and persists state under /var/lib/kervan/data. A built-in health check probes port 8080. Set KERVAN_ADMIN_PASSWORD in your environment before running the example.

docker run --name kervan \
  -p 2121:2121 -p 2222:2222 -p 8080:8080 \
  -p 50000-50100:50000-50100 \
  -e KERVAN_ADMIN_PASSWORD \
  -v kervan-data:/var/lib/kervan/data \
  ghcr.io/kervanserver/kervan:0.9.0

A service on your own host#

The repository includes deploy/systemd/kervan.service as an example Linux service. Provision the kervan user, binary, configuration and data directory first. The unit uses a non-root identity, restart handling and CAP_NET_BIND_SERVICE for privileged ports.

Review the unit’s paths and permissions for your installation rather than enabling it unchanged on an unprepared host. Use the documented install steps in the product README.

Sessions, transfers and metrics#

The shared session registry reports protocol, client address and activity. Transfer tracking records in-flight and recent transfers with byte counts and duration. The WebUI receives live snapshots over WebSocket.

Prometheus-style /metrics output includes active sessions, transfer counters, uptime and HTTP request counters and latency aggregates. The REST API exposes the corresponding operational data. Structured HTTP access logs include request and trace identifiers.

# A running local instance
curl http://localhost:8080/health
 
# Supply a bearer token or scoped API key for protected metrics
curl -H "Authorization: Bearer $KERVAN_TOKEN" \
  http://localhost:8080/metrics

Keep the record of truth#

JSONL file audit outputs record authentication, file activity, sessions and administration. HMAC-SHA256 integrity chaining is enabled by default. Preserve the audit key with your logs if you need to verify their chain.

File outputs apply backpressure rather than dropping queued events. HTTP, webhook and syslog outputs have independent bounded queues and best-effort delivery; remote events can be dropped when collectors fall behind. Keep a file output as the record of truth and monitor dropped-event metrics.

audit:
  enabled: true
  integrity:
    enabled: true
  outputs:
    - type: file
      path: ./data/audit.jsonl
      max_size_mb: 100
      max_backups: 10
    - type: syslog
      url: tls://siem.example.com:6514
      format: rfc5424

Back up, verify, recover#

The operational backup CLI packages the embedded store, audit log and active configuration in a ZIP with a checksum manifest. Verification checks archive structure and recorded hashes. Restore with the server stopped for the cleanest recovery.

Plan separate backups for transferred file payloads, object-store data, SSH host keys and other deployment secrets as appropriate. An operational archive is not a substitute for a tested full-data recovery plan.

./kervan backup create --config ./kervan.yaml \
  --output ./backups/kervan-backup.zip
./kervan backup verify --input ./backups/kervan-backup.zip
 
# With the server stopped
./kervan backup restore --config ./kervan.yaml \
  --input ./backups/kervan-backup.zip --force