proofpoint-quarantine-portal/docs/configuration.md

Configuration reference

All configuration lives in config.toml (copy from config.example.toml). The file is round-tripped by the admin panel — comments and formatting are preserved on save, so keep comments meaningful. The file is written 0600; a config.toml.bak is kept from the previous save.

Zones: (S) server-only — edit the file directly, never shown/written by the panel. (A) admin-editable in the panel. (W) write-only secret — never returned by any API. live — applies immediately; otherwise a restart is required.

[pps] — connection to Proofpoint (A, live)

Key	Type	Notes
base_url	str	https://host:10000. http:// requires PPSQ_ALLOW_INSECURE=1.
username	str	API user with the Quarantine module role.
password	str (W)	Never returned; blank on save = unchanged.
verify_tls	bool | path	false skips verification; or a CA-bundle path.
timeout	int	Seconds per call, 5..600.
client_cert	path	Mutual-TLS client cert (combined PEM, or cert with client_key).
client_key	path	Private key, if client_cert is cert-only.

[quarantine] (A, live)

Key	Type	Notes
default_folder	str	Must be in folders. Per-user overridable.
folders	list[str]	Source of truth (API can't enumerate). Exact names, no commas.
deleted_folder	str	Target of Delete. Must be in folders.
default_limit	int	UI row cap 1..1000. Per-user overridable.
list_query	str	Search filter; from=* = match-all (API rejects folder-only).
default_days_back	int	How far back sync reaches (API alone gives 24h).
chunk_size	int	localguids per PPS POST, 1..500.
default_sort_field	str	subject|date|from|rcpt. Per-user overridable.
default_sort_dir	str	asc|desc. Per-user overridable.

[quarantine.report_release] (A, live)

Key	Type	Notes
steps	list[str]	Subsequence of ["move","release"], run in that fixed order.
move_target	str	Required if move in steps; must be in folders.
step_delay_seconds	int	0..3600 (default 60). Wait between steps, then re-read locations.

Outcomes: ["release"] delivers in place; ["move","release"] files the mail in move_target and delivers it from there. Report & Release never deletes — Delete is a separate action; a delete step in an old config is dropped on load.

Between two steps the worker waits step_delay_seconds for PPS's eventually-consistent backend to settle and then re-reads each message's current localguid by its stable guid — handles captured before the move are never reused. 0 disables both the wait and the re-read. The waiting job is parked back on the queue, so other jobs keep running.

A steps list in the old release-before-move order is migrated to the current order on load (and a delete entry is removed).

[app] (S, restart — except log_level)

Key	Notes
secret_key	Session signing key, ≥32 chars. Rotating it logs everyone out.
listen, port	Bind address. Keep loopback unless behind a reverse proxy.
db_path	SQLite file (jobs + prefs).
log_level	(A, live) INFO/DEBUG/…
worker_log, app_log	Rotating log file paths (5 MB × 5).
cookie_secure	true in production; false only for plain-http localhost.

[auth]

Key	Zone	Notes
mode	(S)	oidc (production) or static (dev). Not admin-editable.
denied_message	(A, live)	Shown to authenticated-but-unlisted users.
users	(A, live)	[[auth.users]] entries {email, role}; role admin|user.
[auth.static]	(S)	Dev shared account (username/password/email/role). Ignored under oidc.

[okta] (S, restart — never admin-editable)

Key	Notes
issuer	e.g. https://TENANT.okta.com/oauth2/default.
client_id	Okta app client id.
client_secret	(W) Okta app secret.
redirect_uri	Must EXACTLY match the Okta app registration. Ends in /authorize.

Environment variables

Var	Purpose
PPSQ_CONFIG	Path to the config file (default: ./config.toml).
PPSQ_ALLOW_INSECURE	Allow an http:// PPS base_url (dev only).
PPSQ_ALLOW_INSECURE_AUTH	Allow static auth on a non-loopback interface (dev only).

Live vs restart

Live: pps.*, quarantine.*, auth.users, auth.denied_message, app.log_level. Restart: app.secret_key/listen/port/db_path/worker_log/app_log/cookie_secure, auth.mode, all okta.*. The panel reports restart_required after a save.