Troubleshooting

Troubleshooting

I'm locked out of sudo

The fastest recovery, in order of preference:

1. Another root shell on a different TTY

Switch to a free TTY (Ctrl+Alt+F2 … F6), log in directly as root (if root login is enabled) or as another user that doesn't go through Sentinel:

# Inside the second shell, with root:
mv /etc/pam.d/sudo.pre-sentinel.bak /etc/pam.d/sudo
# or:
sed -i '/pam_sentinel/d' /etc/pam.d/sudo
# or:
/path/to/sentinel-source/uninstall.sh --yes

2. Single-user mode

Reboot. At the boot loader (GRUB / systemd-boot), edit the kernel command line and append init=/bin/bash. Boot. Filesystem will be mounted read-only — remount r/w:

mount -o remount,rw /
mv /etc/pam.d/sudo.pre-sentinel.bak /etc/pam.d/sudo
sync && reboot -f

3. Live USB

Boot any Linux live USB, mount your root partition, edit <mountpoint>/etc/pam.d/sudo directly. Same fix as above.

4. The full uninstall path

If the install state file is intact, the cleanest recovery from any of the above is:

cd /path/to/sentinel-source
./uninstall.sh --yes        # already running as root in the recovery shell

This restores every file Sentinel touched (including any pre-existing polkit-1 / sudo you'd customised before installing).

The dialog never appears

Check, in order:

# 1. Is the PAM module loaded? (you should see this every sudo attempt)
journalctl -t pam_sentinel -f

# 2. Is the helper installed and runnable?
ls -l /usr/lib/sentinel-helper /usr/lib/security/pam_sentinel.so

# 3. Does the helper run by hand?
/usr/lib/sentinel-helper --timeout 10 --randomize --process-exe /usr/bin/sudo

# 4. Is your compositor providing zwlr-layer-shell-v1?
grep -r layer_shell /usr/share/wayland-sessions   # rough check
# or: weston-info | grep layer-shell  (if weston-info is installed)

# 5. Are you on GNOME/Mutter? (Mutter doesn't implement layer-shell)
echo "$XDG_CURRENT_DESKTOP"

If WAYLAND_DISPLAY isn't set in the user environment that PAM sees (some screen lockers / login flows scrub it), the helper exits DENY silently and PAM falls through to pam_unix — you get a password prompt instead of the dialog. With headless_action = "password" this is the correct fallback.

"wrong mode" / "wrong ownership" install error

The install script's verify step caught a file with the wrong permissions. Likely cause: a previous failed install left a half-written file. Easiest fix:

pkexec ./uninstall.sh --yes      # cleans up via state file
pkexec ./install.sh

Helper compiles but won't run: "WAYLAND_DISPLAY not set"

The helper is Wayland-only. It doesn't run on X11, headless, or SSH. This is intentional — for headless paths, the PAM module returns PAM_IGNORE and the password fallback runs at the PAM layer.

You can still smoke-test the helper from a Wayland session:

just helper-test

"ext-session-lock-v1 path not yet implemented"

You're on a pre-0.2.0 build. The session-lock plan was dropped in v0.2.0 — upgrade and the warning is gone.

GNOME / Mutter

GNOME (Mutter) doesn't implement zwlr-layer-shell-v1, so the overlay won't render. Two options:

1. Run with --windowed (debug fallback to xdg-toplevel — doesn't block input or grab keyboard, just a regular window).
2. Use a different Wayland compositor (cosmic-comp, Hyprland, Sway, KWin/Wayland) for sessions that you want gated by Sentinel.

This is a Mutter limitation we can't work around from inside the helper.

Helper hangs after Allow / Deny

The helper exits via cosmic::iced::exit(). If it hangs, the compositor probably refused to destroy the layer surface — kill it:

pkill sentinel-helper

PAM's safety-margin poll (helper timeout + 5 s) will SIGKILL it automatically; users won't be permanently stuck.

syslog spam

If log_attempts = true is too chatty, set it to false per service:

[services.polkit-1]
log_attempts = false

Or globally in [general]. The default is true because losing the audit trail on a security tool is worse than the syslog noise.

Debug logging

The PAM module logs to syslog facility auth. To get more verbose logs, build with RUST_LOG=debug and add debug to the PAM line:

auth   sufficient   pam_sentinel.so   debug

This is recognised by libpam as a generic flag and is forwarded to the module. Most third-party PAM modules treat it as "log everything"; pam_sentinel follows the same convention.

Upgrading

# Source build:
git pull
pkexec ./install.sh           # re-runs all of install, replacing files

# AUR:
yay -Syu sentinel             # or sentinel-git

# Debian / RPM:
sudo apt install ./sentinel_$NEW_VERSION-1_amd64.deb
sudo dnf install ./sentinel-$NEW_VERSION-1.x86_64.rpm

install.sh is idempotent — re-running it is the supported upgrade path. The state file and .pre-sentinel.bak files are preserved across re-runs (your original pre-Sentinel files don't get overwritten).