TLS for the agent link

By default agents connect to NATS in plain text (nats://). Turn on TLS (tls://) for every link you do not fully trust. With the embedded broker, pfCentral makes and serves its own certificates, so there is nothing to buy or install.

How it works

 first start with TLS on                         every agent
 ┌─────────────────────────────────┐             ┌─────────────────────────────────────┐
 │ pfCentral                       │  HTTPS once │ pfSense package                     │
 │  makes  state/nats/tls/ca.crt  ─┼────────────▶│  downloads /nats-ca.crt → ca.crt    │
 │         state/nats/tls/server.* │             │                                     │
 │  serves GET /nats-ca.crt        │  TLS 24222  │  dials tls://pf.example.com:24222   │
 │  NATS presents server.crt  ◀────┼─────────────┤  trusts only ca.crt                 │
 └─────────────────────────────────┘             └─────────────────────────────────────┘

• On the first start with PFCENTRAL_NATS_TLS_ENABLED=true, the server creates a private CA (valid 10 years) and a server certificate (valid 2 years) for the names in PFCENTRAL_NATS_TLS_HOSTS.
• It serves the CA certificate at GET /nats-ca.crt. The endpoint needs no login and exists only while TLS is on.
• The agent pins that CA: it trusts no other. The certificate is not in any public trust store, so an agent without the CA cannot connect.

Turn it on

1. List every name agents dial. Separate them with ;. Include public and internal names if some firewalls use each.

   PFCENTRAL_NATS_TLS_ENABLED=true
   PFCENTRAL_NATS_TLS_HOSTS=pf.example.com;pf.corp.internal;10.0.0.15

2. Restart the server. The log shows the certificates being created. Check:

   curl -fsS https://pf.example.com/nats-ca.crt | openssl x509 -noout -subject -enddate

3. Point agents at tls://. In Services → pfCentral → Settings set NATS URL to tls://pf.example.com:24222 and leave NATS CA on Automatic. On Save the package downloads https://<enroll host>/nats-ca.crt into /usr/local/etc/nats-agent/ca.crt and restarts the agent.

   For new installs, pass the URLs to the installer:

   … | 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=… sh

Get the names right before the first TLS start

The server creates the certificate once. Changing PFCENTRAL_NATS_TLS_HOSTS later has no effect until you delete state/nats/tls/ and restart, which also creates a new CA that every agent must download again. See Rotate certificates.

Moving existing agents from nats:// to tls://

TLS on the server applies to the whole listener: agents still on nats:// stop connecting when you turn it on. Plan a short window:

1. Turn TLS on and restart the server.
2. On each firewall, change NATS URL to tls://… and click Save. The agent downloads the CA and reconnects within seconds.

Credentials do not change, so no re-enrollment is needed.

Check an agent

On the firewall:

openssl s_client -connect pf.example.com:24222 -CAfile /usr/local/etc/nats-agent/ca.crt \
  -verify_hostname pf.example.com </dev/null 2>/dev/null | grep "Verify return code"
# Verify return code: 0 (ok)

Any other code means the agent cannot connect either. A name that is not in the certificate gives a hostname mismatch here and a TLS error in /var/log/nats_agent.log.

External brokers

With your own NATS, use the broker’s TLS. pfCentral does not create certificates in that mode. Use a CA your agents trust, or set NATS CA to Custom URL with a URL where the firewall can download it.