How pfCentral works

pfCentral has three parts. You install two of them; the third is built in.

Part	Where it runs	What it does
Server	A container or VM on your network	Serves the web UI and API, stores users and devices in PostgreSQL, and sends commands to firewalls.
Agent	On each pfSense firewall	Connects out to the server, reports health, and carries out changes on the firewall. Installed as a pfSense package.
NATS	Inside the server	The messaging system that links the server and the agents. You do not install it separately.

The one idea to understand

Classic management tools connect in to each firewall over HTTPS or SSH. That needs an open port on every firewall and a route from the management network to every site.

pfCentral turns this around. Each agent connects out to the server and keeps that connection open. The server sends commands down the connection that the agent opened. If a firewall can browse to the server, it can be managed.

Press play, or step through with the arrows:

1. 1. Nothing listens on your firewalls

   Your firewalls sit at remote sites, often behind NAT. They accept no incoming management connections, and pfCentral never asks you to open one.

2. 2. Each agent dials out

   The agent on each firewall opens one outbound connection to the server's NATS port, the same way a browser opens a website. If the firewall can reach the server, it works.

3. 3. The connection stays open

   Every few seconds the agent sends a heartbeat and live stats (CPU, memory, traffic) up the connection. This is how the UI knows a firewall is online.

4. 4. You click Save

   The server publishes a request to an address called a subject. Only fw-hq-01 listens on pfsense.fw-hq-01.…, so only it receives the request. It travels down the connection the agent already opened.

5. 5. The agent applies it and replies

   The agent writes the change to the pfSense configuration, applies it, and sends the result back the same way. The UI shows you the outcome.

6. 6. Each firewall only hears its own subjects

   When an agent connects, the server gives it a pass that allows pfsense.<its-id>.> only. One firewall can never read or answer messages for another.

← Pause →

fig. — how a change reaches a firewall

What is NATS, in one paragraph?

NATS is a message broker: a post office for programs. Programs send messages to an address called a subject, such as pfsense.fw-hq-01.firewall.rules.list. Programs that listen on that subject receive the message and can reply. The sender does not need to know where the receiver is, only the subject. pfCentral uses this so the server can talk to any firewall through one open port on the server.

You never write NATS configuration to use pfCentral. If you want the longer, illustrated version, read NATS for firewall admins.

What happens when you click Save

1. You change a firewall rule in the web UI and click Save.
2. The server checks your role. Viewers cannot make changes; operators and above can.
3. The server sends a request on the subject for that firewall, for example pfsense.<device-id>.firewall.rules.create.
4. The agent on that firewall receives it, validates it, and writes it to pfSense’s config.xml. It locks the file first, so it never writes at the same time as the pfSense GUI.
5. The agent replies with the result, and the UI shows it. If the agent does not answer within a few seconds, the UI shows an error instead.

Save, then Apply

As in the pfSense GUI, Save stores the change in the configuration, and Apply makes the running firewall use it (for example, it reloads the firewall rules). Most areas have an Apply button. A saved change that is not applied yet still survives a reboot.

What happens all the time, without you

• Heartbeats. Each agent sends a small “I am alive” message every few seconds. If they stop, the firewall shows as offline within about 15 seconds. See Online, offline and telemetry.
• Telemetry. Each agent streams CPU, memory, disk, temperature and per-interface traffic, so dashboards update live.
• Short-lived passes. Each time an agent connects, the server issues it a pass that allows only that firewall’s own subjects, and the pass expires. See Enrollment and identity.

Where data lives

Data	Location
Firewall configuration	On each firewall, in pfSense’s own config.xml. pfCentral reads and writes it through the agent; it does not keep a separate copy.
Users, roles, devices, sessions, audit events	PostgreSQL
Keys, NATS certificates, internal credentials	The server’s state directory (/data in the container)
Live telemetry	In NATS, kept for a few hours

Next: try it yourself with the Quickstart.