Server and agent CLI

Server: pf-central

The server binary is pf-central in the container image. With no arguments it prints help.

Command	What it does
pf-central serve	Starts the server: runs database migrations, prepares NATS, starts the broker (embedded mode) and the web server. The image’s default command.
pf-central admin setup token	Cancels open setup links and prints a new one, valid 24 hours. The link creates an owner.
pf-central admin enroll token	Prints a one-time enrollment token that any firewall can use.
pf-central admin seed	Development only. Creates test accounts for each role.
pf-central --version	Prints the version.

The admin commands read the same environment as serve and talk to the database directly. The server does not need to be running. They do not run migrations, so run them against a database that serve has started at least once.

Run in Docker or Kubernetes

# Docker Compose
docker compose exec pf-central pf-central admin setup token

# Kubernetes
kubectl exec -n pf-central deploy/pf-central -- pf-central admin enroll token --ttl 24h

admin enroll token flags

Flag	Default	Meaning
--ttl	1h	How long the token is valid, as a Go duration (30m, 24h, 168h).
--tenant-slug	default	The tenant the firewall joins. Leave the default.

$ pf-central admin enroll token --ttl 24h
╔══ pf-central device enrollment token ══════════════╗
║ Token:   device_3f9a…_c21b…
║ Tenant:  default   Expires in: 24h0m0s   Single-use
║ Give it to the agent as auth.bootstrap_token
…

A CLI token is not bound to a device. Any one firewall can use it, once. A token from Add device in the UI is bound to the UUID you entered. See Enroll firewalls.

Note

There is no migrate command. Migrations run on each serve, under a database lock, so several replicas can start at once.

Agent: nats-agent

The agent binary is /usr/local/bin/nats-agent on the firewall. The nats_agent service runs it; you rarely run it by hand.

Command	What it does
nats-agent run --config <file>	Runs the agent. If the configuration has a bootstrap token and no connect-secret yet, it enrolls first. run is the default command.
nats-agent --version	Prints the version.

The service passes --config /usr/local/etc/nats-agent/config.yaml. See Environment variables → Agent for the keys.

Service commands on pfSense

service nats_agent status
service nats_agent restart
service nats_agent stop
service nats_agent start
tail -f /var/log/nats_agent.log

The same actions are on Services → pfCentral → Status in the pfSense GUI.

Debug in the foreground

Stop the service, then run the agent with debug logs:

service nats_agent stop
PFCENTRAL_AGENT_LOG_LEVEL=debug nats-agent run --config /usr/local/etc/nats-agent/config.yaml

Press Ctrl+C to stop, then service nats_agent start.