Configuration Reference

13. Configuration Reference

Server Configuration (/etc/osprey/osprey.yaml)

database:
  host: localhost              # PostgreSQL host
  port: 5432                   # PostgreSQL port
  name: osprey                 # Database name
  user: osprey                 # Database user
  password: ${OSPREY_DB_PASSWORD}  # From environment
  max_connections: 40          # Per-service pool size (5 services x 40 = 200 total)
  ssl_mode: disable            # disable | require | verify-ca | verify-full

nats:
  url: ${OSPREY_NATS_URL}     # nats://localhost:4222
  token: ${OSPREY_NATS_TOKEN}  # Optional NATS auth token

api:
  listen: "127.0.0.1:8080"    # API listen address (nginx proxies from 443)
  ssh_recording: true          # Default for session recording; overridden by the ssh.session_recording system setting
  cors_origins:                # Allowed CORS origins
    - "https://your-domain.com"

auth:
  jwt_secret: ${OSPREY_JWT_SECRET}  # Must be 32+ bytes
  access_token_ttl: "15m"          # JWT token lifetime
  refresh_token_ttl: "168h"        # Refresh token lifetime (7 days)
  bcrypt_cost: 12                  # Password hashing cost
  secure_cookies: true             # HTTPS-only cookies

# Credential at-rest encryption (AES-256-GCM).
# Generate: openssl rand -base64 32
# If empty, credentials are stored in plaintext (backwards compatible).
encryption_key: ${OSPREY_ENCRYPTION_KEY:-}

# License file (Ed25519-signed). Upload via Admin UI or place file here.
# If missing/empty, runs in evaluation mode (32 nodes, full features).
license_file: /etc/osprey/license.key

topology:
  stale_retention_hours: 168   # 7 days; overridable via Admin > System Settings

snmp:
  discovery_interval_seconds: 21600  # Startup fallback only; overridden by per-network discovery_interval_hours (default 6h)
  stats_retention_days: 30         # Days to keep interface stats

bmp:
  listen_address: "127.0.0.1:11019"  # BMP TCP listener; change to 0.0.0.0:11019 to accept router connections
  # allowed_cidrs: []                # CIDR allowlist (empty = only bmp_target.router_ip allowed)
  max_connections: 50                # Maximum concurrent BMP sessions
  max_connections_per_ip: 2          # Per-source-IP connection limit
  allow_nat_fallback: false          # Match BMP sysName when source IP differs from target IP (NAT)

metrics:
  enabled: true
  listen: ":9090"             # Prometheus metrics endpoint

logging:
  level: info                 # debug | info | warn | error
  format: text                # json | text

Environment Variables (/etc/osprey/osprey.env)

Variable	Required	Description
OSPREY_DB_HOST	Yes	PostgreSQL host (default: localhost)
OSPREY_DB_PASSWORD	Yes	PostgreSQL password (auto-generated on install)
OSPREY_NATS_URL	Yes	NATS server URL (default: nats://127.0.0.1:4222)
OSPREY_NATS_TOKEN	No	NATS authentication token (auto-generated on install if NATS is configured with token auth)
OSPREY_JWT_SECRET	Yes	JWT signing secret (auto-generated, 32+ bytes)
OSPREY_ENCRYPTION_KEY	Recommended	AES-256 key for SNMP credential at-rest encryption (auto-generated, base64-encoded 32 bytes). If unset, credentials are stored in plaintext.
OSPREY_METRICS_LISTEN	No	Override metrics listen address per service. Set in each service's systemd unit: engine :9090, collector-manager :9091, SNMP poller :9092, API :9093, BMP server :9094.

The environment file is created at install time with PLACEHOLDER values that the postinst script replaces with randomly generated secrets. The file is owned by root:osprey with mode 0640 to protect credentials.

Service Ports

Service	Port	Purpose
API	8080	REST API + WebSocket
nginx	443 (HTTPS), 80 (redirects to 443)	HTTPS frontend + API proxy
BMP Server	11019 (TCP)	BGP Monitoring Protocol listener
Engine metrics	9090	Prometheus
Collector Manager metrics	9091	Prometheus
SNMP Poller metrics	9092	Prometheus
API metrics	9093	Prometheus
BMP Server metrics	9094	Prometheus
NATS	4222	Message bus
PostgreSQL	5432	Database

Systemd Services

Osprey runs as five systemd services grouped under osprey.target:

Service	Unit Name	Runs As	Description
Engine	osprey-engine	osprey	Topology processing, event correlation, snapshot creation
API	osprey-api	osprey	REST API, WebSocket, SSH proxy
Collector Manager	osprey-collector-manager	root	GRE tunnel and SNMP discovery collectors (requires NET_ADMIN + NET_RAW)
SNMP Poller	osprey-snmp-poller	osprey	Interface statistics and device enrichment
BMP Server	osprey-bmp-server	osprey	BGP Monitoring Protocol listener (TCP 11019)

All five services depend on PostgreSQL and NATS (After=postgresql.service nats-server.service). They automatically restart on failure (Restart=on-failure, RestartSec=5) and have a file descriptor limit of 65536 (LimitNOFILE=65536).

# Check all Osprey services at once
systemctl status osprey.target

# Restart all services
sudo systemctl restart osprey.target

# Restart a single service
sudo systemctl restart osprey-api

# View logs for a specific service (follow mode)
sudo journalctl -u osprey-api -f
sudo journalctl -u osprey-engine -f
sudo journalctl -u osprey-collector-manager -f
sudo journalctl -u osprey-snmp-poller -f
sudo journalctl -u osprey-bmp-server -f

# View recent logs (last 100 lines, no pager)
sudo journalctl -u osprey-engine --no-pager -n 100

# View logs since last boot
sudo journalctl -u osprey-api -b

# Enable/disable a service
sudo systemctl enable osprey-api
sudo systemctl disable osprey-snmp-poller

File Locations (Debian Package)

Path	Contents
/usr/bin/osprey	Main binary (all subcommands)
/etc/osprey/osprey.yaml	Server configuration
/etc/osprey/osprey.env	Environment secrets (0640 root:osprey)
/etc/osprey/nats.conf	NATS server configuration
/etc/osprey/certs/	TLS certificate and key
/usr/share/osprey/web/	Frontend static files (served by nginx)
/etc/nginx/sites-available/osprey	nginx site configuration
/var/lib/osprey/	Data directory (owned by osprey user)
/var/lib/nats/jetstream/	NATS JetStream data

nginx Configuration

The default nginx site (/etc/nginx/sites-available/osprey) provides:

• HTTP to HTTPS redirect (port 80 to 443)
• TLS termination with self-signed certificate
• API reverse proxy: /api/ requests forwarded to 127.0.0.1:8080
• WebSocket support: Upgrade and Connection headers proxied, with 86400s read timeout
• SPA fallback: all non-API, non-asset requests serve index.html
• Cache headers: hashed assets (/assets/) cached for 1 year with immutable; index.html is never cached
• Security headers: X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security