PAM: login checks, password policy and lockout

PAM (Pluggable Authentication Modules) is the library that programs hand user checks to. login, su, sudo, sshd and passwd do not check passwords themselves: they call PAM, and PAM reads the file named after the program in /etc/pam.d/ and runs through its modules. To change the policy — password length, lockout after failures — you change the module stack and leave the programs alone. The files are read at every login, so an edit takes effect at once.

A program's file usually pulls in shared files with @include:

student@ubuntu:~$ grep -E '^(auth|@include)' /etc/pam.d/su
auth       sufficient pam_rootok.so
@include common-auth
@include common-account
@include common-session

sudo and sshd are built the same way: editing common-auth changes the password check for all of them at once.

Four stacks

Every line starts with a type — which stage of the login it belongs to:

Key login in sshd skips the auth stack: sshd checks the key itself. The account and session stacks run on key login too.

Reading a line

auth	[success=1 default=ignore]	pam_unix.so nullok

Type, control flag, module and its arguments. Modules run top to bottom, and the flag says what to do with their answer:

The auth stack on the machine:

student@ubuntu:~$ grep -v '^#' /etc/pam.d/common-auth | grep .
auth	[success=1 default=ignore]	pam_unix.so nullok
auth	requisite			pam_deny.so
auth	required			pam_permit.so
auth	optional			pam_cap.so

Right password: pam_unix jumps over one line — pam_deny — to pam_permit, and the login is allowed. Wrong password: the next line, pam_deny, refuses. Line order is part of the logic here: a line inserted between pam_unix and pam_deny changes where success=1 leads.

pam-auth-update

On Ubuntu the common-* files are assembled by pam-auth-update from the profiles in /usr/share/pam-configs/. The machine has five: capability, mkhomedir, pwquality, systemd, unix. A profile is the lines plus where to put them:

student@ubuntu:~$ cat /usr/share/pam-configs/pwquality
Name: Pwquality password strength checking
Default: yes
Priority: 1024
Conflicts: cracklib
Password-Type: Primary
Password:
	requisite			pam_pwquality.so retry=3

On the lab machine the profile is off. sudo pam-auth-update --enable pwquality turns it on and rebuilds common-password:

The first line is new. use_authtok tells pam_unix to take the password pam_pwquality has already checked instead of asking again.

If the common-* files were edited by hand, pam-auth-update first asks Override local changes to /etc/pam.d/common-*?. yes rebuilds the files from the profiles and wipes the manual lines; no leaves the files as they are — and the profile does not get enabled:

pam-auth-update: Local modifications to /etc/pam.d/common-*,
  not updating.
pam-auth-update: Run pam-auth-update --force to override.

pwquality: password quality

pam_pwquality checks a new password when it changes. The rules live in /etc/security/pwquality.conf or in files under /etc/security/pwquality.conf.d/*.conf (the directory does not exist on the machine; create it with mkdir). Everything in the machine's pwquality.conf is commented out, so the defaults apply:

A positive *credit value works differently: each such character, up to N of them, counts twice towards the length. retry=3 is an argument of the module in the pam.d line: how many times passwd asks again.

pwscore checks a password in advance. It reads the same pwquality.conf but does not look at PAM — a rule shows up in pwscore even before pam-auth-update. The answer is a score from 0 to 100 or the reason for refusal with exit code 1:

student@ubuntu:~$ echo 123 | pwscore
Password quality check failed:
 The password is shorter than 8 characters
student@ubuntu:~$ echo qwerty123 | pwscore
Password quality check failed:
 The password fails the dictionary check - it is based on a
 dictionary word
student@ubuntu:~$ echo 'Lab-Pass-2026' | pwscore
96

With minlen = 12, minclass = 3 and dcredit = -1 the refusals are:

passwd run by the user prints the same reasons after BAD PASSWORD: and gives up after three tries:

deploy@ubuntu:~$ passwd
Changing password for deploy.
Current password:
New password:
BAD PASSWORD: The password contains less than 3 character classes
New password:
BAD PASSWORD: The password is shorter than 12 characters
New password:
BAD PASSWORD: The password contains less than 1 digits
passwd: Have exhausted maximum number of retries for service
passwd: password unchanged

Root without enforce_for_root gets the same BAD PASSWORD, but the password changes: sudo passwd deploy prints the warning and password updated successfully, chpasswd prints only the warning and exits with 0. With enforce_for_root root is refused too — chpasswd exits with 1 and password not changed.

faillock: lockout after failures

pam_faillock counts failed logins. pam-configs has no profile for it — it is written into common-auth by hand, three lines around pam_unix:

auth	requisite			pam_faillock.so preauth
auth	[success=1 default=ignore]	pam_unix.so nullok
auth	[default=die]			pam_faillock.so authfail
auth	sufficient			pam_faillock.so authsucc
auth	requisite			pam_deny.so
auth	required			pam_permit.so
auth	optional			pam_cap.so

plus the line account required pam_faillock.so at the end of common-account.

The right password jumps over authfail (success=1) and lands on authsucc. There is a variant without authsucc: pam_unix has success=2, and the right password jumps over both authfail and pam_deny. Then only the account line resets the counter, so without it the counter keeps growing even after successful logins. Settings live in /etc/security/faillock.conf; on the machine everything there is commented out: deny = 3 failures, unlock_time = 600 seconds, fail_interval = 900 — the window in which failures are counted. Root is not locked until even_deny_root is on.

Three wrong su - deploy in a row, then the right password:

student@ubuntu:~$ su - deploy
Password:
su: Permission denied
student@ubuntu:~$ sudo faillock --user deploy
deploy:
When                Type  Source          Valid
2026-10-21 05:06:19 TTY   /dev/pts/0          V
2026-10-21 05:06:24 TTY   /dev/pts/0          V
2026-10-21 05:06:28 TTY   /dev/pts/0          V
student@ubuntu:~$ su - deploy
The account is locked due to 3 failed logins.
(10 minutes left to unlock)
su: Authentication failure

The password is not even asked for — preauth refused before it. The log says:

pam_faillock(su-l:auth): Consecutive login failures for user deploy
  account temporarily locked

The counters are files in /var/run/faillock/<user>. /run lives in memory, so a reboot wipes them. sudo faillock --user deploy --reset lifts the lockout earlier.

Key login through sshd lets the locked account in: the auth stack does not run, and the account line resets the counter.

• passwd — changing passwords and /etc/shadow.
• chage — password expiry.
• sudo — goes through PAM too.
• sshd — UsePAM, password and key login.
• fail2ban — banning an address after failed logins.
• users-groups — accounts.
• journalctl — su and sshd refusals in the log.