pfSense package

The agent ships as a pfSense package, pfSense-pkg-nats-agent. It needs pfSense 2.7.0 or later on amd64. It adds Services → pfCentral to the pfSense GUI with two tabs, Settings and Status, and the nats_agent service.

Settings tab

Device

Field	Meaning
Device ID	Read-only. The firewall’s SMBIOS UUID. pfCentral scopes this firewall’s credentials to it.
Device Name	The name shown in pfCentral. Defaults to the pfSense hostname.
Site	Optional location label, for example office-syd.

pfCentral Server

Field	Meaning
NATS URL	Required. Where the agent connects, for example nats://pf.example.com:24222, or tls://pf.example.com:24222 with TLS.
Enroll URL	Required. pfCentral’s enrollment address, for example https://pf.example.com/enroll.
NATS CA	Automatic downloads /nats-ca.crt from the Enroll URL’s host. Custom URL downloads it from another address. Only used with tls://.
NATS CA URL	Shown with Custom URL.

Caution

The help text under NATS URL shows port 4222 as an example. pfCentral’s embedded broker listens on 24222.

Enrollment

The section shows Enrolled or Awaiting enrollment.

Field	Meaning
Bootstrap Token	The one-time token from pfCentral (Add device, or pf-central admin enroll token). Leave it empty once the firewall is enrolled. A new token makes the firewall enroll again: Save deletes the old credentials first.

The help text says server admin enroll token. The command is pf-central admin enroll token.

Agent

Field	Meaning
Binary Source	Default uses the public release. Custom URL uses your own mirror.
Binary URL	Shown with Custom URL. The agent binary used by Download & Restart.
Log Level	Debug, Info, Warn or Error. Default Info.

What Save does

1. Stores the settings in the pfSense configuration.
2. With tls://, downloads the NATS CA. If that fails, Save stops with “Configuration saved, but the NATS CA download failed. The agent was not restarted.”
3. Writes /usr/local/etc/nats-agent/config.yaml.
4. Restarts the agent. With a new token, the agent enrolls as it starts.

Status tab

The page updates on its own every few seconds.

Part	Shows
Banner	Healthy — connected & enrolled, Awaiting enrollment, Disconnected or Agent stopped
Tiles	Process, NATS, Enrollment, Credential (auto-renews), Uptime, Version
Buttons	Start, Stop, Restart, Download & Restart
Identity & Connection	Device ID, name, the server it is connected to, the credential scope (pfsense.<id>.>), last update
Subjects	Every NATS subject this agent answers

“Status file is stale (>30s old)” means the agent has not written its status for 30 seconds. It is stuck or stopped; check /var/log/nats_agent.log and restart it.

Installer script

install.sh installs or upgrades the package and the agent, and on the first install writes the settings for you:

fetch -o - https://github.com/danielmichaels/pf-central-artifacts/releases/latest/download/install.sh | \
  NATS_URL=tls://pf.example.com:24222 \
  ENROLL_URL=https://pf.example.com/enroll \
  NATS_CA_URL=https://pf.example.com/nats-ca.crt \
  BOOTSTRAP_TOKEN=device_… \
  SITE=office-syd \
  sh

The variables are listed in Enroll firewalls. They only apply on the first install; later runs upgrade the package and binary and keep the settings.

Remove

pkg delete pfSense-pkg-nats-agent

This stops the agent and removes the binary, the service and /usr/local/etc/nats-agent/. Delete the device in pfCentral too; see Suspend or retire a firewall.