Configuration

Configuration

Sentinel reads /etc/security/sentinel.conf (TOML). The PAM module loads this on every authentication attempt, so changes take effect immediately — no reload, no daemon to restart.

Default

[general]
enabled = true
timeout = 30
randomize_buttons = true
headless_action = "password"
show_process_info = true
log_attempts = true
min_display_time_ms = 500

[appearance]
title = "Authentication Required"
message = 'The application "%p" is requesting elevated privileges.'
secondary = 'Click "Allow" to continue or "Deny" to cancel.'

[general]

Key	Type	Default	Meaning
enabled	bool	true	Master switch. false = PAM module returns PAM_IGNORE immediately; auth falls through.
timeout	u64 seconds	30	Auto-deny after this many seconds. 0 = no auto-deny.
randomize_buttons	bool	true	Swap Allow/Deny positions randomly to deter scripted clickers.
headless_action	enum	"password"	What to do when no Wayland display is available. See below.
show_process_info	bool	true	Show the requesting process's executable path in the dialog card.
log_attempts	bool	true	Log allow/deny/timeout to syslog (auth.info).
min_display_time_ms	u64	500	Allow button is disabled for this long after the dialog appears, blocking instant scripted clicks.

headless_action

Decides what pam_sentinel.so does when $WAYLAND_DISPLAY is unset (SSH session, console login, headless server):

Value	Behaviour
"password"	Return PAM_IGNORE; PAM continues to the next module (typically pam_unix → password prompt). This is the safe default.
"allow"	Return PAM_SUCCESS. Dangerous; only use if you're sure no one without your consent can reach the headless interface.
"deny"	Return PAM_AUTH_ERR. Stops auth dead.

[appearance]

Key	Type	Substitutions allowed
title	string	no
message	string	yes
secondary	string	yes

Substitution tokens

In message and secondary:

Token	Meaning
%u	Target user (the user being authenticated to, often root)
%s	PAM service name (sudo, polkit-1, su, …)
%p	Requesting process executable path (e.g. /usr/bin/sudo)
%%	Literal %

Example

[appearance]
title = "Privilege escalation"
message = '%u: "%p" wants root via %s'
secondary = "Confirm only if you started this action."

Title / message / secondary localization

Since v0.5, if you leave title, message, or secondary at their exact built-in default, the helper substitutes the locale's translation (12 locales ship: en-US, de-DE, es-ES, fr-FR, it-IT, ja-JP, nl-NL, pl-PL, pt-BR, ru-RU, tr-TR, zh-CN). Any custom value you set passes through verbatim — admin's text is admin's text. So you can either translate the strings yourself in this file, or trust the built-in translations by leaving the defaults in place.

[audio] (since v0.5.1)

UAC-style audio cue when the dialog appears. Optional.

Key	Type	Default
sound_name	string	"dialog-warning"

sound_name is a freedesktop sound naming spec name (NOT a file path). Common values: dialog-warning, bell, message, dialog-question. Resolution goes through the user's sound theme via canberra-gtk-play (part of libcanberra, installed by default on most Linux desktops). Set to "" to disable.

[audio]
sound_name = "bell"

If canberra-gtk-play isn't installed, the dialog still renders — just silently. There's no startup error.

[services.<name>] overrides

Per-PAM-service overrides. The service name matches the PAM service exactly — sudo, polkit-1, su, login, etc. Any key from [general] can be overridden:

[services.sudo]
enabled = true
timeout = 30
randomize = true

[services.polkit-1]
timeout = 60                    # be more lenient with polkit
randomize_buttons = false       # GNOME Shell users might prefer stable button positions
log_attempts = true

[services.su]
enabled = false                 # don't gate `su` at all

Reloading

Changes are picked up automatically — the module re-reads the file every auth attempt. If you want to test:

just helper-test                                 # local UI smoke test
sudo -k && sudo true                             # force a fresh sudo auth

If pam_sentinel.so fails to parse the config, it logs to syslog and returns PAM_IGNORE — fail-open, so a typo in the config doesn't lock you out.

Logging

With log_attempts = true the PAM module writes to syslog (facility auth, level info). Inspect with:

journalctl -t pam_sentinel --since "10 min ago"

The format is roughly:

pam_sentinel: service=sudo user=atay process=/usr/bin/sudo result=allow