Environment variables

The server reads its settings from environment variables with the PFCENTRAL_ prefix. The server fails to start on an unknown value type or an invalid combination, and names the variable in the log.

Lists use semicolons

Variables that take a list use ; between items, not commas. For example PFCENTRAL_NATS_TLS_HOSTS=pf.example.com;10.0.0.5.

Minimum for production

PFCENTRAL_DATABASE_URL=postgres://pf_central:secret@db:5432/pf_central?sslmode=require
PFCENTRAL_SERVER_BASE_URL=https://pf.example.com
PFCENTRAL_TRUSTED_ORIGINS=https://pf.example.com
PFCENTRAL_TOKEN_PEPPER_CURRENT=<long random string>
PFCENTRAL_TOKEN_PEPPER_VERSIONS=<the same string>
PFCENTRAL_LOG_LEVEL=info

Add PFCENTRAL_NATS_TLS_ENABLED=true and PFCENTRAL_NATS_TLS_HOSTS when agents connect over the internet. See Plan your deployment.

Server

Core

Variable	Default	Meaning
PFCENTRAL_ENVIRONMENT	production	production or development. Development is needed for dev login shortcuts and admin seed.
PFCENTRAL_SERVER_ADDR	:2808	HTTP listen address. The server speaks plain HTTP; put a proxy in front for HTTPS.
PFCENTRAL_SERVER_BASE_URL	http://localhost:2808	The public URL of the web UI. Used in setup, invite and reset links.
PFCENTRAL_STATE_DIR	./data/state (/data/state in the image)	Where NATS keys, credentials, the NATS CA and JetStream data live. Back it up with the database.

Database

Variable	Default	Meaning
PFCENTRAL_DATABASE_URL	postgres://postgres:postgres@127.0.0.1:5432/pf_central?sslmode=disable	PostgreSQL connection string. Migrations run on every start.
PFCENTRAL_DATABASE_EMBEDDED	false	Development only. Starts a PostgreSQL inside the process and ignores DATABASE_URL.
PFCENTRAL_DATABASE_EMBEDDED_DATA_DIR	./data/postgres	Development only. Data directory for the embedded database.
PFCENTRAL_DATABASE_EMBEDDED_PORT	45433	Development only. Port for the embedded database.

Web sign-in and sessions

Variable	Default	Meaning
PFCENTRAL_TRUSTED_ORIGINS	http://localhost:2808;http://localhost:2810	Origins allowed to submit forms, with scheme and port. Must include the address users type in the browser.
PFCENTRAL_COOKIE_SECURE	true	Marks the session cookie Secure. Browsers then send it only over HTTPS. Set false only for a plain-HTTP lab.
PFCENTRAL_SUPERUSER_EMAIL	—	With the password below, creates the first owner at first start, without a setup link.
PFCENTRAL_SUPERUSER_PASSWORD	—	At least 12 characters.
PFCENTRAL_AUTHZ_ENFORCE	true	false turns role checks off: every signed-in member may do everything. A recovery switch only; the server logs a warning.
PFCENTRAL_SHOW_DEV_LOGINS	false	Development only. Shows login shortcuts on the sign-in page.

Sessions last 24 hours, and end after 30 minutes without activity. These times are fixed.

Tokens

Variable	Default	Meaning
PFCENTRAL_TOKEN_PEPPER_CURRENT	pepper-v1	Secret mixed into new hashes of device secrets, API tokens and one-time links. Change it before the first start. The default is public.
PFCENTRAL_TOKEN_PEPPER_VERSIONS	pepper-v1	All peppers accepted when checking a hash. Must include the current one. See Rotate the pepper.

NATS (embedded broker)

Variable	Default	Meaning
PFCENTRAL_NATS_MODE	embedded	embedded runs the broker inside pfCentral. external uses your own broker (below).
PFCENTRAL_NATS_LISTEN	nats://0.0.0.0:24222	Address and port where agents connect.
PFCENTRAL_NATS_TLS_ENABLED	false	TLS on the agent port. pfCentral makes a CA and a certificate on first start and serves the CA at /nats-ca.crt.
PFCENTRAL_NATS_TLS_HOSTS	127.0.0.1;localhost	Names and addresses in the certificate. Must include the host in every agent’s NATS URL.
PFCENTRAL_NATS_PING_INTERVAL	20s	How often the broker pings each client.
PFCENTRAL_NATS_MAX_PINGS_OUT	2	Unanswered pings before the broker drops a client.
PFCENTRAL_NATS_CALLOUT_TTL	1h	Lifetime of the pass each agent gets at login. Agents renew it on their own. Both modes.

NATS (external broker)

Read only when PFCENTRAL_NATS_MODE=external. See Bring your own NATS.

Variable	Default	Meaning
PFCENTRAL_NATS_URL	nats://127.0.0.1:24222	Your broker’s URL.
PFCENTRAL_NATS_CREDS_FILE	—	Required. Credentials for pfCentral’s main connection.
PFCENTRAL_NATS_CALLOUT_CREDS_FILE	—	Required. Credentials for the login-check (callout) connection.
PFCENTRAL_NATS_SENTINEL_CREDS_FILE	—	Required. The shared, permission-less login handed to agents at enrollment.
PFCENTRAL_NATS_SIGNING_KEY_PATH	—	Required. The account signing key seed pfCentral uses to sign agent passes.
PFCENTRAL_NATS_RESOURCE_PREFIX	—	Prefix for stream and bucket names, to share one account between installs.

Presence and caches

Variable	Default	Meaning
PFCENTRAL_NATS_REGISTRY_SWEEP_INTERVAL	5s	Presence check interval.
PFCENTRAL_NATS_REGISTRY_MAX_MISSED_SWEEPS	3	Missed checks before a device is offline. With the defaults: 5 s × 3 = 15 s.
PFCENTRAL_NATS_DISCOVERY_ENRICH_ATTEMPTS	5	Tries to read a device’s details when it first connects.
PFCENTRAL_NATS_DISCOVERY_ENRICH_TIMEOUT	500ms	Timeout for each try.
PFCENTRAL_NATS_DISCOVERY_ENRICH_BACKOFF	200ms	Wait between tries.
PFCENTRAL_STATE_CACHE_TTL	5m	How long the latest device state is kept in the device-state bucket.
PFCENTRAL_STATE_CACHE_REFRESH_COOLDOWN	30s	Minimum time between background refreshes of a cached list.

Rate limit and logging

Variable	Default	Meaning
PFCENTRAL_RATELIMIT_GLOBAL_RPM	600	Requests per minute for the whole server process, shared by all users and scripts. Over the limit: HTTP 429.
PFCENTRAL_LOG_LEVEL	debug	debug, info, warn or error. Set info in production.
PFCENTRAL_LOG_JSON	true	true for JSON lines; false for coloured text.

Email

All ignored unless PFCENTRAL_EMAIL_ENABLED=true. See Email delivery.

Variable	Default	Meaning
PFCENTRAL_EMAIL_ENABLED	false	Send invite and password-reset emails.
PFCENTRAL_EMAIL_ENCRYPTION_KEY	—	Required. Base64 of exactly 32 bytes (openssl rand -base64 32). Encrypts queued emails.
PFCENTRAL_EMAIL_PROVIDER	smtp	smtp, resend or cloudflare.
PFCENTRAL_EMAIL_FROM	—	Required. Sender address.
PFCENTRAL_EMAIL_FROM_NAME	pf-central	Sender name.
PFCENTRAL_EMAIL_REPLY_TO	—	Optional Reply-To.
PFCENTRAL_EMAIL_TIMEOUT	15s	Timeout for each send.
PFCENTRAL_EMAIL_RETRY_MAX	5	Attempts before an email is given up.
PFCENTRAL_EMAIL_RETENTION	720h	How long sent and failed email records are kept.
PFCENTRAL_EMAIL_SMTP_HOST	—	Required for smtp.
PFCENTRAL_EMAIL_SMTP_PORT	587
PFCENTRAL_EMAIL_SMTP_TLS	starttls	starttls, implicit, opportunistic or none.
PFCENTRAL_EMAIL_SMTP_AUTH	plain	plain, login or none.
PFCENTRAL_EMAIL_SMTP_USERNAME	—
PFCENTRAL_EMAIL_SMTP_PASSWORD	—
PFCENTRAL_EMAIL_RESEND_API_KEY	—	Required for resend.
PFCENTRAL_EMAIL_CLOUDFLARE_ACCOUNT_ID	—	Required for cloudflare.
PFCENTRAL_EMAIL_CLOUDFLARE_API_TOKEN	—	Required for cloudflare.

Agent

The agent reads /usr/local/etc/nats-agent/config.yaml. The pfSense package writes this file when you click Save in Services → pfCentral → Settings, so you rarely edit it. Most keys also have an environment variable, which wins over the file.

Key	Variable	Default	Meaning
device_id	PFCENTRAL_AGENT_DEVICE_ID	required	The SMBIOS UUID, lower case. Set by the package.
device_name	PFCENTRAL_AGENT_DEVICE_NAME	hostname	Name shown in pfCentral.
site	PFCENTRAL_AGENT_SITE	—	Free-text location label.
ip_address	—	detected	Address shown in pfCentral and used by Open WebUI.
model	—	—	Hardware model shown in pfCentral.
nats_url	PFCENTRAL_AGENT_NATS_URL	nats://127.0.0.1:24222 (package)	pfCentral’s NATS address. tls:// for TLS.
log_level	PFCENTRAL_AGENT_LOG_LEVEL	info	debug, info, warn, error.
log_json	PFCENTRAL_AGENT_LOG_JSON	false	JSON log lines.
binary_url	PFCENTRAL_AGENT_BINARY_URL	the public release	Where Download & Restart gets a new agent.
config_path	PFCENTRAL_AGENT_CONFIG_PATH	/cf/conf/config.xml	The pfSense configuration the agent reads and writes.
heartbeat_interval	—	5s	Presence heartbeat interval.
telemetry_interval	PFCENTRAL_AGENT_TELEMETRY_INTERVAL	2s	Telemetry interval. At least 1s. See Scaling.
auth.method	PFCENTRAL_AGENT_AUTH_METHOD	callout (package)	How the agent logs in. The package always uses callout.
auth.enroll_url	PFCENTRAL_AGENT_AUTH_ENROLL_URL	—	pfCentral’s /enroll URL.
auth.bootstrap_token	PFCENTRAL_AGENT_AUTH_BOOTSTRAP_TOKEN	—	One-time enrollment token.
auth.sentinel_creds_file	PFCENTRAL_AGENT_AUTH_SENTINEL_CREDS_FILE	—	Written at enrollment.
auth.connect_secret_file	PFCENTRAL_AGENT_AUTH_CONNECT_SECRET_FILE	—	Written at enrollment.
auth.ca_file	PFCENTRAL_AGENT_NATS_CA	—	CA for tls://. Empty means no TLS.

The installer script has its own variables; see Enroll firewalls.