Files and directories

Server state directory

PFCENTRAL_STATE_DIR, by default ./data/state, and /data/state in the container image (the image declares /data as a volume). The server creates it on first start.

• Directorystate/

  • Directorynats/

    • operator.nk NATS operator key
    • op-sk-1.nk operator signing key
    • Directoryaccounts/

      • Directory…/ one folder per NATS account, with its keys

        • …
    • Directoryjwt/ account records the broker loads

      • …
    • Directoryusers/

      • backend.creds pfCentral’s own connection
      • sys.creds system events (connects and disconnects)
      • auth.creds the login check (callout)
      • sentinel.creds the shared login given to agents
    • Directoryjs/ JetStream data: telemetry, presence, device state

      • …
    • Directorytls/ only with PFCENTRAL_NATS_TLS_ENABLED=true

      • ca.crt the CA agents download
      • server.crt
      • server.key

Path	Safe to lose?
nats/js/	Yes. It holds at most 6 hours of telemetry and short-lived caches, and is rebuilt.
nats/tls/	Recoverable. A new CA is made on start; every agent must download it again. See Rotate.
Everything else	No. The keys must match the database. Losing them means a fresh install and re-enrolling every firewall.

Danger

The state directory holds private keys. Restrict access to it, encrypt its backups, and back it up together with the database. See Back up and restore.

In external NATS mode, the credentials and signing key come from the files you name in PFCENTRAL_NATS_*_FILE and PFCENTRAL_NATS_SIGNING_KEY_PATH, and JetStream data lives on your broker.

Agent files on pfSense

Path	Purpose
/usr/local/bin/nats-agent	The agent binary
/usr/local/etc/nats-agent/config.yaml	Agent settings. The package rewrites it on each Save in Services → pfCentral.
/usr/local/etc/nats-agent/ca.crt	The pinned NATS CA, for tls://
/usr/local/etc/nats-agent/sentinel.creds	The shared login, written at enrollment
/usr/local/etc/nats-agent/connect.secret	This firewall’s secret, written at enrollment. If it exists, the firewall is enrolled.
/var/run/nats-agent.status.json	Live status, rewritten every 10 seconds. The Status tab reads it.
/var/run/nats_agent.pid	Process ID
/var/log/nats_agent.log	The agent log
/usr/local/etc/rc.d/nats_agent	The service script
/cf/conf/config.xml	The pfSense configuration the agent reads and changes

The files in /usr/local/etc/nats-agent/ are readable by root only (mode 0600).

To re-enroll a firewall by hand, delete connect.secret and sentinel.creds, put a new token in Services → pfCentral → Settings, and Save. The GUI does the same when you paste a new token.

Logs

Component	Where
Server	Standard error. JSON lines by default. In Docker: docker compose logs pf-central.
Agent	/var/log/nats_agent.log on the firewall. Use log_level: debug only while you debug.