Authentication and PAM

Before you read. You run passwd, type a new password, and get back BAD PASSWORD: The password is shorter than 8 characters.

You did not configure that. There is no minimum length in /etc/passwd and none in /etc/shadow. The passwd command is a small program for writing one field in one file, and it does not contain a dictionary, a length policy, or an opinion.

So which program made that decision, and where is it written down?

Not passwd. passwd asked something else, and repeated the answer.

Every program that establishes who you are (login, sshd, su, sudo, passwd, cron, a screen locker) asks the same library the same way, and that library reads a file named after the program asking. The file lists small modules to run in order, and one of them has opinions about password length. That indirection is PAM, the Pluggable Authentication Modules system, and it is why one file can change how every login on the machine behaves. In both directions.

Some words you will need

authentication

Establishing that you are who you claim to be. A password, a key, a token, a fingerprint.

authorization

Given that you are who you say, deciding whether you may do a particular thing. A separate question, answered by separate machinery.

accounting

Recording what happened: who logged in, from where, when, and what they did.

PAM

Pluggable Authentication Modules. A library, libpam, that programs call instead of reading password files themselves.

module

A shared object such as pam_unix.so that answers one narrow question. It returns success or failure and nothing else.

stack

The ordered list of modules for one service and one module type. Read top to bottom, like a program.

control flag

The middle column of a stack line. It decides what a module's success or failure does to the rest of the stack.

service file

A file in /etc/pam.d named for the program that will use it. /etc/pam.d/sshd is consulted when sshd authenticates somebody.

What breaks without this

You cannot enforce a password policy, or explain the one already in force. Length, complexity, history, and lockout are all module settings, and none of them live in the account files you already know.

A restriction you carefully added never runs. A line below a module that short-circuits the stack is unreachable code, and nothing warns you. The configuration looks correct in review and does nothing in production.

Your change disappears at the next package update, because on a RHEL-family machine the file you edited is generated from somewhere else and says so in its first three lines.

You lock every account out of the machine, including root. A broken shared stack refuses console logins, SSH, su, and sudo at the same moment, and the recovery is a rescue boot.

Three questions that get run together

“Auth” is used for two different things in conversation, and there are three:

They fail differently and you diagnose them differently. A wrong password is an authentication failure. A correct password from a user whose account expired last Friday is an authorization failure: the identity was proved and the account may not be used. Different log lines, different fixes, and “she cannot log in” tells you neither. PAM touches all three, which is why the split gets blurred, but what it does not do is decide whether you may restart a service or read a file.

What happens when you log in

The programs really are linked against the library:

# AlmaLinux 10.2, x86_64
$ ldd /usr/bin/su | grep pam
	libpam.so.0 => /lib64/libpam.so.0 (0x0000ffff8851c000)
	libpam_misc.so.0 => /lib64/libpam_misc.so.0 (0x0000ffff88515000)

su does not open /etc/shadow. It calls libpam, which decides what opening /etc/shadow would even mean here: a local file, a directory server, a smart card. The sequence for an interactive login:

1. The program collects a username and tells the library which service it is. sshd says sshd, su says su, passwd says passwd.
2. The library opens /etc/pam.d/<service> and reads it.
3. The program calls for authentication. The auth stack runs.
4. The program calls for account validation. The account stack runs.
5. If the account stack came back saying the token has expired, the password stack runs to change it, right there in the middle of the login.
6. The program opens a session. The session stack runs.
7. At logout, the session stack runs again, closing.

Step 5 is the one that surprises people. “You are required to change your password immediately” is not passwd running; it is the same login process running a different stack, because the account stack said so.

And the safety rule that governs everything below. Most of those programs share a file, so a stack that refuses everybody refuses the console, SSH, su, and sudo at once, including the session you would fix it from. Full procedure in the panel after the control flags.

A file for every service

The directory is small and nearly every file in it is named for a program:

# AlmaLinux 10.2, x86_64
$ ls /etc/pam.d
chfn
chsh
config-util
fingerprint-auth
login
other
passwd
password-auth
postlogin
remote
runuser
runuser-l
smartcard-auth
su
su-l
switchable-auth
system-auth

The name is the interface. There is no registry and no build step, which is why writing /etc/pam.d/myapp is all it takes to give your own program a PAM configuration, and why a typo in a filename produces a service with no configuration rather than an error. (The older single /etc/pam.conf is ignored whenever /etc/pam.d exists.) other is the fallback for a service name with no matching file, and on the RHEL family it denies all four module types with pam_deny.so, so an unknown service fails closed.

The files arrive with the packages that need them. That listing is an AlmaLinux container with no SSH server and no sudo installed. The same directory on a Fedora CoreOS machine that runs both:

# Fedora CoreOS 44.20260707.3.1 on a virtual machine, aarch64
$ ls /etc/pam.d/ | head -20; echo "--- how many ---"; ls /etc/pam.d/ | wc -l
chfn
chsh
config-util
fingerprint-auth
login
other
passwd
password-auth
postlogin
remote
runuser
runuser-l
smartcard-auth
sshd
sssd-shadowutils
su
su-l
sudo
sudo-i
switchable-auth
--- how many ---
22

sshd, sudo, and sudo-i are here and absent there, because openssh-server ships /etc/pam.d/sshd and sudo ships /etc/pam.d/sudo. Removing a package removes its stack file, and reinstalling one quietly restores a file somebody had customised.

The four module types

Every line begins with one of four words, and that word says which question is being answered:

The four are independent stacks that happen to live in one file. pam_unix checks the hash in the auth stack, checks expiry in the account stack, writes a new hash in the password stack, and logs session open and close in the session stack: one shared object, four questions, and it may answer one with success and another with failure.

# AlmaLinux 10.2, x86_64
$ cat /etc/pam.d/passwd
#%PAM-1.0
# This tool only uses the password stack.
password   substack	system-auth
-password   optional	pam_gnome_keyring.so use_authtok
password   substack	postlogin

Only password lines, and the file says so in a comment. A program that never authenticates anybody needs no auth stack. The - on the middle line is not a typo; it is covered with the flags.

Modules are shared objects in a directory

A module is a .so file, and there are a lot of them:

# AlmaLinux 10.2, x86_64
$ ls /usr/lib64/security | head -20
pam_access.so
pam_canonicalize_user.so
pam_cap.so
pam_chroot.so
pam_debug.so
pam_deny.so
pam_echo.so
pam_env.so
pam_exec.so
pam_faildelay.so
pam_faillock.so
pam_filter
pam_filter.so
pam_ftp.so
pam_group.so
pam_issue.so
pam_keyinit.so
pam_lastlog.so
pam_limits.so
pam_listfile.so

The library dlopens the file named on the line, calls the entry point for the module type, and takes back a return code. A module returns success or failure and nothing else: no partial credit, no explanation to the stack, and anything it wants to tell a human goes to the log. Debian keeps the same shared objects under a multiarch path, /usr/lib/x86_64-linux-gnu/security, which is why a stack line names pam_unix.so and never a path. The ones worth recognising:

pam_deny and pam_permit look like jokes and are neither. They are how a stack says “and otherwise, no” and “and otherwise, yes”, which matters once the flags below turn a stack into something with control flow.

getent passwd alice

The control flags

Here is the file nearly every service on a RHEL-family machine ends up using. Thirteen module lines, and between them every control flag you need:

# AlmaLinux 10.2, x86_64
$ cat /etc/pam.d/system-auth
# Generated by authselect
# Do not modify this file manually, use authselect instead. Any user changes will be overwritten.
# You can stop authselect from managing your configuration by calling 'authselect opt-out'.
# See authselect(8) for more details.

auth        required                                     pam_env.so
auth        required                                     pam_faildelay.so delay=2000000
auth        sufficient                                   pam_unix.so nullok
auth        required                                     pam_deny.so

account     required                                     pam_unix.so

password    requisite                                    pam_pwquality.so
password    sufficient                                   pam_unix.so yescrypt shadow nullok use_authtok
password    required                                     pam_deny.so

session     optional                                     pam_keyinit.so revoke
session     required                                     pam_limits.so
-session    optional                                     pam_systemd.so
session     [success=1 default=ignore]                   pam_succeed_if.so service in crond quiet use_uid
session     required                                     pam_unix.so

The columns are type, control flag, module, then arguments. The flag decides what a module’s result does to everything below it:

required and requisite differ in when the failure is reported, not whether it is. required keeps going, so the user cannot tell from the prompts or the timing which check refused them, and so modules further down still run, which matters when one of them is what records the failed attempt. requisite stops dead, which is what you want when continuing would hand a secret to something that should not receive it.

sufficient is the one that changes program flow. Its success ends the stack there and then. That is how “any one of these will do” is expressed, and it is the single most common way a configuration comes to contain a restriction that restricts nothing. optional is weaker than it sounds: its result counts only when no other module returned a definite success or failure, so it is for modules that do work rather than modules that decide.

Two more pieces of syntax are on that page. The leading - on -session optional pam_systemd.so attaches to the type, not the flag, and means: if this module is not installed, skip the line silently instead of logging an error. It is how one stack ships to machines with and without a component.

The bracket form on the pam_succeed_if line is the general case the named flags are shorthand for: returncode=action pairs, with default= catching everything unnamed. The actions are ignore, ok, bad, die, done, reset, and a number, meaning “skip the next N modules”. So that line says if the service running this stack is crond, jump over one module, and the module jumped over is session required pam_unix.so, which writes a session record, so cron does not add a login record every minute. The named flags are defined in terms of it, which is the clearest way to see what they do:

bad marks the stack failed and keeps going. die marks it failed and returns at once. That one word is the whole difference between required and requisite.

# Fedora CoreOS 44.20260707.3.1 on a virtual machine, aarch64
$ grep -E "^(auth|account|password|session)" /etc/authselect/system-auth
auth        required                                     pam_env.so
auth        required                                     pam_faildelay.so delay=2000000
auth        sufficient                                   pam_unix.so nullok
auth        required                                     pam_deny.so
account     required                                     pam_unix.so
password    requisite                                    pam_pwquality.so
password    sufficient                                   pam_unix.so yescrypt shadow nullok use_authtok
password    required                                     pam_deny.so
session     optional                                     pam_keyinit.so revoke
session     required                                     pam_limits.so
session     [success=1 default=ignore]                   pam_succeed_if.so service in crond quiet use_uid
session     required                                     pam_unix.so

-session optional pam_systemd.so is missing, because the pattern anchors on ^session and that line begins with a hyphen, so the output cannot tell you whether the line is in the file. A pattern that looks like it matches “every module line” misses every optional-if-absent line, and those are exactly the lines that differ between distributions and releases: a naive regular expression under-reports, and what it under-reports is what the vendor changed.

auth  sufficient  pam_unix.so
auth  required    pam_wheel.so use_uid

Tracing a stack top to bottom

The whole skill is reading a stack the way you would read a small program. Take the four auth lines from the shared file above:

auth        required     pam_env.so
auth        required     pam_faildelay.so delay=2000000
auth        sufficient   pam_unix.so nullok
auth        required     pam_deny.so

With the right password: the first two succeed. pam_faildelay only registered that a failure should be reported late: delay=2000000 is microseconds, so two seconds, jittered by up to a quarter either way. pam_unix hashes what was typed with the stored salt from lesson 28 and matches, and because it is sufficient the stack returns success immediately and pam_deny never runs. With the wrong password: pam_unix fails, sufficient discards the failure, and evaluation falls through to pam_deny, which always fails and is required. The stack returns failure, two seconds late.

Both traces on a real machine, an ordinary user running su with the wrong password and then the right one. The plumbing exists only because su insists on reading a password from a terminal rather than a pipe:

# AlmaLinux 10.2, x86_64
$ (sleep 2; echo hunter2) | runuser -u tux -- script -qec "su - root -c id" /dev/null; echo "rc=$?"
Password: 
su: Authentication failure
rc=1

# AlmaLinux 10.2, x86_64
$ (sleep 2; echo correcthorse) | runuser -u tux -- script -qec "su - root -c id" /dev/null; echo "rc=$?"
Password: 
uid=0(root) gid=0(root) groups=0(root)
rc=0

Note what su does not say when it fails. It received one return code and has no idea whether the password was wrong, the account was locked, or a module failed to load. That distinction exists in /var/log/secure and nowhere else, which is why the log window is part of the testing procedure rather than an afterthought.

pam_deny at the foot of a sufficient chain is a deliberate idiom. The chain reads “try local users, or the directory, or the smart card”; pam_deny is the else that makes the refusal explicit instead of depending on what a stack does when it runs off the end. Every generated stack on a RHEL machine ends this way.

Who decides your password is good enough

Back to the question at the top. The password stack from the same file:

password    requisite    pam_pwquality.so
password    sufficient   pam_unix.so yescrypt shadow nullok use_authtok
password    required     pam_deny.so

pam_pwquality is the module with the opinions, and BAD PASSWORD is its message. It reads /etc/security/pwquality.conf, which ships with almost everything commented out so the built-in defaults apply:

enforce_for_root is off by default, which explains a confusing observation: root sets a three-character password, is told it is a BAD PASSWORD, and proceeds anyway. The check ran and the complaint is real; the module simply does not return an error for root unless you ask it to.

The requisite on that line is doing security work. With required instead, the bad password fails pam_pwquality, the failure is remembered, and evaluation continues, so pam_unix runs, takes the token, and writes it to /etc/shadow. The stack then reports failure, the user sees an error, and the password has already been changed to the bad one.

Each argument on the pam_unix line carries weight. yescrypt is the hashing algorithm, the same one behind the $y$ prefix in lesson 28. shadow writes to /etc/shadow rather than /etc/passwd. use_authtok means “use the password the previous module already collected rather than prompting again”, which is why pam_pwquality has to sit above it. nullok permits a change from an empty existing password, and on an auth line the same word permits logging in to an account whose password field is empty, which is a finding in any audit and worth grepping for on a machine you inherit.

include, substack, and the shared stack

No service file repeats those thirteen lines. They pull them in. su is the most instructive file in the directory:

# AlmaLinux 10.2, x86_64
$ cat /etc/pam.d/su
#%PAM-1.0
auth		required	pam_env.so
auth		sufficient	pam_rootok.so
# Uncomment the following line to implicitly trust users in the "wheel" group.
#auth		sufficient	pam_wheel.so trust use_uid
# Uncomment the following line to require a user to be in the "wheel" group.
#auth		required	pam_wheel.so use_uid
auth		substack	system-auth
auth		include		postlogin
account		sufficient	pam_succeed_if.so uid = 0 use_uid quiet
account		include		system-auth
password	include		system-auth
session		include		system-auth
session		include		postlogin
session		optional	pam_xauth.so

auth sufficient pam_rootok.so is why root is never asked for a password when running su: the module succeeds for uid 0 and sufficient ends the stack before any password is collected. It is sufficient and not required on purpose, as required it would mean only uid 0 may use su at all.

The two commented lines are the classic exercise, and their flags differ on purpose. Uncommenting the second restricts su to wheel: a non-member fails a required module and is refused, and a member returns a neutral result so the stack carries on and still asks for the password. Uncommenting the first does something else entirely: trust makes the module return outright success for a member, which with sufficient ends the stack and lets wheel members su with no password at all. One word and one flag apart, and one of them is a significant loosening. use_uid judges by the process’s current uid rather than the login name, which is the reliable choice when su is reached from a script or a nested session. Both sit above auth substack system-auth so the group check happens before the shared stack asks for a password; below it they are unreachable.

include and substack both pull in another file, and they are not the same.

Look at what that buys su. auth substack system-auth runs the shared stack, and when pam_unix inside it succeeds (a sufficient, which means done) the substack ends but su’s own stack does not, so auth include postlogin on the next line still runs. Written as include system-auth, that done would have ended su’s auth stack outright and skipped postlogin. That is why the file uses one keyword on one line and the other on the next.

# AlmaLinux 10.2, x86_64
$ ls -l /etc/pam.d/system-auth /etc/pam.d/password-auth
lrwxrwxrwx. 1 root root 29 Aug  8 17:04 /etc/pam.d/password-auth -> /etc/authselect/password-auth
lrwxrwxrwx. 1 root root 27 Aug  8 17:04 /etc/pam.d/system-auth -> /etc/authselect/system-auth

They are symlinks out of /etc/pam.d entirely. The real files live in /etc/authselect, next to a generated nsswitch.conf:

# AlmaLinux 10.2, x86_64
$ readlink -f /etc/pam.d/system-auth; ls /etc/authselect
/etc/authselect/system-auth
authselect.conf
custom
dconf-db
dconf-locks
fingerprint-auth
nsswitch.conf
password-auth
postlogin
smartcard-auth
switchable-auth
system-auth

Two shared stacks rather than one, and the split matters: system-auth is for local and console services, password-auth for services that authenticate over the network, sshd chief among them, so a policy can differ between somebody at the physical console and somebody arriving from the internet. Editing only system-auth and wondering why SSH behaves differently is a recurring afternoon. fingerprint-auth, smartcard-auth, and postlogin are the same idea for other routes in.

# Fedora CoreOS 44.20260707.3.1 on a virtual machine, aarch64
$ ls -l /etc/pam.d/system-auth /etc/pam.d/password-auth; echo "--- what authselect is doing ---"; sudo authselect current 2>&1
lrwxrwxrwx. 1 root root 29 Aug  7 14:14 /etc/pam.d/password-auth -> /etc/authselect/password-auth
lrwxrwxrwx. 1 root root 27 Aug  7 14:14 /etc/pam.d/system-auth -> /etc/authselect/system-auth
--- what authselect is doing ---
Profile ID: local
Enabled features:
- with-silent-lastlog

# AlmaLinux 10.2, x86_64
$ authselect list
- local  	 Local users only
- sssd   	 Enable SSSD for system authentication (also for local users only)
- winbind	 Enable winbind for system authentication

sudo authselect create-profile ourpolicy --base-on sssd
sudo authselect select custom/ourpolicy

Locking an account after failed attempts

Nothing in the stacks above counts anything: a wrong password costs two seconds and nothing else, forever. pam_faillock changes that, and its command-line half is present on any machine with PAM installed:

# AlmaLinux 10.2, x86_64
$ faillock --user root
root:
When                Type  Source                                           Valid

An empty table is the answer, not a missing feature. The columns are there, root has no recorded failures, and the module is not in this machine’s stack at all. That is the default state everywhere: the tooling ships, the enforcement does not.

Settings live in /etc/security/faillock.conf, which beats repeating module arguments in three places:

unlock_time = 0 is a decision, not a default to inherit. An account that never unlocks itself turns password guessing against a service account into a denial of service that needs a human; a few hundred seconds stops guessing at any rate that matters while healing on its own.

faillock --user alice inspects and sudo faillock --user alice --reset clears. On the RHEL family, the way to put the modules into the stacks is not to type them in:

# AlmaLinux 10.2, x86_64
$ authselect enable-feature with-faillock; grep faillock /etc/pam.d/system-auth
auth        required                                     pam_faillock.so preauth silent
auth        required                                     pam_faillock.so authfail
account     required                                     pam_faillock.so

Three lines across two stacks, and not a deny= or unlock_time= among them. One command inserted them into every generated stack and left the numbers in faillock.conf, so one file governs every service on the machine. With those lines in place the empty table fills up. An ordinary user attempts su twice with the wrong password:

# AlmaLinux 10.2, x86_64
$ for i in 1 2; do (sleep 2; echo hunter2) | runuser -u tux -- script -qec "su - root -c id" /dev/null; done; faillock --user root
Password: 
su: Authentication failure
Password: 
su: Authentication failure
root:
When                Type  Source                                           Valid
2026-08-08 18:15:11 TTY   /dev/pts/0                                           V
2026-08-08 18:15:16 TTY   /dev/pts/0                                           V

Read the Valid column. V means the record still counts toward deny. Records older than fail_interval stay in the listing and stop counting, so a table with rows in it is not by itself a locked account.

auth     required    pam_faillock.so preauth silent
auth     sufficient  pam_unix.so nullok
auth     required    pam_faillock.so authfail
auth     required    pam_deny.so
account  required    pam_faillock.so

polkit, the other authorisation engine

PAM decides whether you may become a session. polkit decides whether a session you already have may perform one specific privileged action. It is the desktop half of the same problem, and it is present on servers too.

• Actions are named strings such as org.freedesktop.systemd1.manage-units, declared by packages in /usr/share/polkit-1/actions/.
• Rules are JavaScript files in /etc/polkit-1/rules.d/, evaluated in filename order, that answer yes, no, or ask for a password.
• pkexec is polkit’s answer to sudo, and it is setuid root, it appeared in the setuid inventory in lesson 45. pkaction lists actions and pkcheck tests one.

The two compose rather than compete: when a rule says “ask for a password”, polkit authenticates that password through PAM. So a PAM change can alter how a polkit prompt behaves, and a polkit rule can grant something sudoers never mentions. On a headless server that matters more than it looks. An ordinary user running systemctl restart over D-Bus is authorised by polkit, not by sudoers, so a permissive rule file dropped in by a package is a grant that appears in no sudo audit; pkaction --verbose is where that inventory lives. What is examinable is what polkit is and how it differs from PAM. Writing rules is beyond it.

Across distributions

The mechanism is identical everywhere. What differs is who writes the shared files and what they are called:

# Debian 13 (trixie), x86_64
$ ls /etc/pam.d
chfn
chpasswd
chsh
common-account
common-auth
common-password
common-session
common-session-noninteractive
login
newusers
other
passwd
runuser
runuser-l
su
su-l

No system-auth and no password-auth. Four common- files instead, split by module type rather than by local-versus-network, plus a fifth for non-interactive sessions. A guide that tells you to edit system-auth here is describing a file that does not exist:

# Debian 13 (trixie), x86_64
$ ls -l /etc/pam.d/common-auth /etc/pam.d/system-auth
ls: cannot access '/etc/pam.d/system-auth': No such file or directory
-rw-r--r--. 1 root root 1214 Aug  3 00:00 /etc/pam.d/common-auth

Debian’s su pulls those in with a different keyword:

# Debian 13 (trixie), x86_64
$ grep -vE "^\s*(#|$)" /etc/pam.d/su
auth       sufficient pam_rootok.so
session       required   pam_env.so readenv=1
session       required   pam_env.so readenv=1 envfile=/etc/default/locale
session    optional   pam_mail.so nopen
session    required   pam_limits.so
@include common-auth
@include common-account
@include common-session

@include is a real syntax difference, not a spelling. It takes no module type and pulls in the entire named file, every stack in it at once. The RHEL-family include takes a type and pulls only the lines of that type, which is why the RHEL su above names system-auth on four separate lines, one per stack.

And the shared stack itself is the same logic written a different way:

# Debian 13 (trixie), x86_64
$ cat /etc/pam.d/common-auth
#
# /etc/pam.d/common-auth - authentication settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authentication modules that define
# the central authentication scheme for use on the system
# (e.g., /etc/shadow, LDAP, Kerberos, etc.).  The default is to use the
# traditional Unix authentication mechanisms.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules.  See
# pam-auth-update(8) for details.

# here are the per-package modules (the "Primary" block)
auth	[success=1 default=ignore]	pam_unix.so nullok
# here's the fallback if no module succeeds
auth	requisite			pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
auth	required			pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config

Trace it: the bracket form is doing the work of sufficient. pam_unix succeeds, success=1 jumps over one module, pam_deny, and lands on pam_permit, which returns success. pam_unix fails, default=ignore carries on to pam_deny, which is requisite and returns failure at once. Identical behaviour to the RHEL stack you traced, expressed as a jump rather than a short circuit, and the file’s own comment says why: modules are added and removed here by a program, and a jump computed from a known number of lines composes more predictably than a chain of sufficient lines whose meaning depends on what a package inserted above them. That comment is also the same warning in different words. Both families generate their shared files and both will overwrite your edit; here the tool is pam-auth-update, driven by files in /usr/share/pam-configs/.

The password-quality row is the one that catches people. A stock Debian machine has no quality module at all: obscure turns on pam_unix’s own small checks (palindrome, case-only change, too similar to the old one, too short) and that is the entire policy until libpam-pwquality is installed. Auditing a Debian host for minlen finds nothing because there is nothing there to find.

Prove it

# Which file will this service use, and does it exist at all
ls -l /etc/pam.d/sshd

# Where does the shared stack really live, and who owns it
readlink -f /etc/pam.d/system-auth
authselect current
authselect check

# Before blaming PAM: is the user even visible
getent passwd alice
id alice

# What PAM actually decided, with the module that decided it
sudo journalctl -t sshd -t su -t sudo --since "10 min ago"
sudo tail -n 50 /var/log/secure

# Lockout state, and clearing it
faillock --user alice
sudo faillock --user alice --reset

getent before anything else. It goes through the name service and never touches PAM, so it splits “this user does not exist here” from “this user cannot authenticate” in one command, and those two arrive as the same sentence from the same user.

What trips people up

1. A restriction placed below a sufficient line

auth sufficient pam_unix.so followed by auth required pam_wheel.so restricts nobody: the sufficient returns success for anyone with a valid password and the line below never executes. Read a stack as a program with early returns, and put a control above every line that could return before it.

2. Editing the generated shared stack by hand

system-auth and password-auth are symlinks into /etc/authselect, and the real files say in their first two lines that they are generated. The change works, survives a reboot, and vanishes weeks later during patching. Use a feature, or a custom profile, or authselect opt-out and accept ownership.

3. Authentication token manipulation error

The generic failure from the password stack, with several causes behind identical text: pam_pwquality rejected the new password and said why only in the log; the current password was wrong; /etc/shadow is not writable, whether immutable from lesson 45, a full filesystem, or a read-only mount; or SELinux refused the write, from lesson 44, leaving an AVC and no other clue. journalctl -t passwd or /var/log/secure names the module. The terminal never will.

4. One pam_faillock line instead of three

preauth above the authenticating module, authfail below it, and an account line as well. Miss the account line and the lock is counted but inconsistently enforced; put preauth below pam_unix and it never runs. authselect enable-feature with-faillock does all three correctly.

5. Testing a change with only one session open

The shared stack serves the console, SSH, su, and sudo at once, so breaking it closes every way in and the recovery is a rescue boot. Copy the file, keep an authenticated root shell open, test from a second session, and watch the log while you do. A session that already exists is not re-authenticated, which is the only reason the safety shell works.

Work it through

A security review lands with two requirements for a fleet of RHEL 10 machines: su is to be restricted to members of wheel, and accounts are to lock after five failed passwords with an automatic unlock after fifteen minutes. Reason it out before reading on.

Decide which files are yours to edit, because the two requirements do not have the same answer. ls -l /etc/pam.d/su /etc/pam.d/system-auth returns a regular file and a symlink into /etc/authselect, so the su requirement is a legitimate hand edit and the lockout requirement is not. Getting this backwards costs you either a control that evaporates at the next update, or a hunt for an authselect template that does not exist because the tool does not own /etc/pam.d/su.

Second, the su restriction. The line is already in the file, commented, and the right one is the second of the two:

auth		required	pam_wheel.so use_uid

Not the trust variant, which would let wheel members become root with no password at all. And it stays where it is, above auth substack system-auth.

The lockout. sudo authselect enable-feature with-faillock, then deny = 5 and unlock_time = 900 in /etc/security/faillock.conf, once, rather than as module arguments repeated across three lines in several files.

Fourth, and this is the step that is not on the review. Open a second root session before touching anything, copy /etc/pam.d/su, and test from a third: as a wheel member, as a non-member, and as a non-member typing a wrong password five times. Confirm with faillock --user testuser, clear it with --reset, and read /var/log/secure to see which module refused each attempt.

Now change one detail and watch the answer change. Had the requirement been to restrict SSH, system-auth would be the wrong file: network services use password-auth, and sshd has its own service file besides. The better answer might not be PAM at all, since AllowGroups wheel in sshd_config is simpler, more visible, and does not risk the shared stack. And if these machines are joined to a directory, a pam_sss.so line exists in the auth stack, and where lockout sits relative to it decides whether directory accounts are counted at all.

The point worth extracting: a PAM stack is a small program with early returns, and the two questions that answer almost everything are “what runs before this line” and “who writes this file”. Order decides whether a control exists. Ownership decides whether it is still there next month.

Try it

Optional, on a machine you can break, with a second root session already open.

1. ls /etc/pam.d/ and name the program each of five files belongs to.
2. ldd $(which su) | grep pam and confirm the program is linked against the library.
3. cat /etc/pam.d/su. Find the sufficient line and say what it does for root.
4. readlink -f /etc/pam.d/system-auth, then authselect current. Say who owns that file.
5. cat /etc/pam.d/system-auth and trace the auth stack twice out loud, once for a correct password and once for a wrong one. Name the line that runs last in each case.
6. Uncomment auth required pam_wheel.so use_uid in /etc/pam.d/su, then try su from an account that is not in wheel, from your second session. Read /var/log/secure.
7. Move that line below auth substack system-auth and try again. Explain what changed.
8. faillock --user root, then authselect enable-feature with-faillock, then look at the generated stack again.

Verification step. You have it when you can be handed an unfamiliar /etc/pam.d/<service> file and say, without running anything, which line a correct password stops at, which line a wrong password stops at, and which lines in the file can never execute.

Check yourself

auth        required     pam_env.so
auth        required     pam_faildelay.so delay=2000000
auth        sufficient   pam_unix.so nullok
auth        required     pam_deny.so

password    requisite    pam_pwquality.so
password    sufficient   pam_unix.so ... use_authtok

#auth		sufficient	pam_wheel.so trust use_uid
#auth		required	pam_wheel.so use_uid

References

• pam(8) - Linux man-pages project. Accessed 2026-08-08.
• pam.conf(5) - Linux man-pages project. Accessed 2026-08-08.
• pam_unix(8) - Linux man-pages project. Accessed 2026-08-08.
• pam_faillock(8) - Linux man-pages project. Accessed 2026-08-08.
• pam_wheel(8) - Linux man-pages project. Accessed 2026-08-08.
• pam_pwquality(8) - Debian Project. Accessed 2026-08-08.
• nsswitch.conf(5) - Linux man-pages project. Accessed 2026-08-08.
• polkit(8) - Debian manpages. Accessed 2026-08-08.
• Configuring authentication and authorization in RHEL - Red Hat. Accessed 2026-08-08.

Captured output came from three machines: an AlmaLinux 10.2 container with no SSH server and no sudo installed, a Debian 13 container, and a Fedora CoreOS virtual machine that runs both. None ships pam_faillock in its stacks by default, which is why the faillock table is empty until authselect enable-feature puts the modules there. The su transcripts are real logins and real refusals driven through a pseudo-terminal, because su will not take a password from a pipe. Blocks without a distribution and architecture header are illustrative: the interleaved pam_faillock stack, the pwquality settings, and excerpts quoted back from files shown in full elsewhere come from the module documentation rather than from a capture.