PAM Wiring

PAM Wiring

Sentinel exposes one module: /usr/lib/security/pam_sentinel.so. It implements the auth PAM hook only — account, password, session fall through to whatever else is in the stack.

The recommended directive is:

auth   sufficient   pam_sentinel.so

sufficient means:

• Sentinel returns PAM_SUCCESS (user clicked Allow) → PAM stops processing the auth stack and returns success. No password is asked for.
• Sentinel returns anything else (PAM_AUTH_ERR from Deny, PAM_IGNORE from headless / disabled / parse error, PAM_AUTHINFO_UNAVAIL from a helper failure) → PAM continues to the next auth line.

So Sentinel is an additive fast-path: a successful confirm skips the password; everything else falls back to whatever was authenticating you before.

Caution

Always put pam_sentinel.so before the include system-auth line, never after. After means it never runs (auth has already succeeded or failed by then). Always keep a fall-through to the existing auth stack so a Sentinel failure doesn't lock you out.

sudo / sudo-rs

Both read /etc/pam.d/sudo.

Important

Distro packages (.deb, .rpm, AUR) do NOT modify /etc/pam.d/sudo. Silently rewriting that file would be a foot-gun (one bad packaging change locks every user out of sudo). Wiring sudo is opt-in.

To enable Sentinel for sudo after a package install:

sudo install -Dm644 /usr/share/doc/sentinel/sudo /etc/pam.d/sudo
# or edit /etc/pam.d/sudo yourself and add this line BEFORE the
# existing auth lines:
#   auth   sufficient   pam_sentinel.so

The shipped file is:

#%PAM-1.0
auth       sufficient pam_sentinel.so
auth       include    system-auth
account    include    system-auth
password   include    system-auth
session    include    system-auth

When using install.sh --enable-sudo from source, the script saves your existing /etc/pam.d/sudo to /etc/pam.d/sudo.pre-sentinel.bak and registers it in /var/lib/sentinel/install.state for clean rollback via uninstall.sh. Distro-package installs don't get this safety net, hence the manual step.

sudo-rs reads the same /etc/pam.d/sudo file — no extra wiring.

polkit

/etc/pam.d/polkit-1 is installed automatically. The shipped file:

#%PAM-1.0
auth       sufficient pam_sentinel.so
auth       include    system-auth
account    include    system-auth
password   include    system-auth
session    include    system-auth

Some distros use /etc/pam.d/polkit instead of /etc/pam.d/polkit-1 (rare). Check your polkit version:

pacman -Ql polkit | grep pam.d   # Arch
dpkg -L policykit-1 | grep pam.d # Debian
rpm -ql polkit | grep pam.d      # Fedora

If yours is polkit not polkit-1, copy the same file there.

su / su-l

/etc/pam.d/su:

auth       sufficient pam_sentinel.so
auth       include    system-auth
account    include    system-auth
password   include    system-auth
session    include    system-auth

/etc/pam.d/su-l (long-form su -) usually mirrors /etc/pam.d/su and needs the same edit.

login / sshd / gdm

Caution

Don't put Sentinel in front of login, sshd, or your display manager. The helper is graphical — there's no Wayland display at the point those services authenticate. With headless_action = "password" the module would just PAM_IGNORE anyway, so adding it there accomplishes nothing and increases your blast radius.

Running without system-auth

Some distros use common-auth (Debian) or password-auth (Fedora) instead of system-auth. Substitute as appropriate. The shipped configs assume system-auth; if your distro is different, edit the files in /etc/pam.d/ after install.

Per-service config overrides

Although the PAM directive is the same everywhere, per-service behaviour (timeout, randomization, etc) can differ via [services.<name>] in /etc/security/sentinel.conf. See Configuration.

Debugging the PAM stack

# Tail syslog while you sudo:
journalctl -t pam_sentinel -f

# Test against a fake service so you don't lock yourself out:
sudo install -m 644 /etc/pam.d/sudo /etc/pam.d/sentinel-test
echo 'sentinel-test test ' | pamtester sentinel-test "$USER" authenticate

Removing it from a service

If you only want to disable Sentinel for, say, polkit:

# Restore the pre-install backup if it exists:
sudo mv /etc/pam.d/polkit-1.pre-sentinel.bak /etc/pam.d/polkit-1
# or just edit:
sudo sed -i '/pam_sentinel/d' /etc/pam.d/polkit-1

To remove it entirely → pkexec ./uninstall.sh.