Skip to content

PAM configuration

Synopsis

/etc/pam.d/<SERVICE>:
TYPE    CONTROL    MODULE-PATH    [MODULE-ARGUMENTS]
-TYPE   CONTROL    MODULE-PATH    [MODULE-ARGUMENTS]
@include <FILE>                                    (Debian and Ubuntu)

Description

Linux-PAM reads one file per service from /etc/pam.d/, named after the service name the application passes to pam_start(). If the file doesn't exist, /etc/pam.d/other is used. Each non-comment line adds one module to the stack of one management group; within a group, lines run in file order. The legacy single file /etc/pam.conf, with the service name as an extra first field, is read only if /etc/pam.d/ doesn't exist. Where Linux-PAM is built with a vendor directory, /usr/lib/pam.d/, a file in /etc/pam.d/ overrides the file of the same name there. Changes take effect at the next PAM transaction; no service needs reloading.

Many modules also read a configuration file of their own under /etc/security/. Arguments given on the PAM line take precedence over that file.

Checked against Linux-PAM 1.7.0 on Debian 13 and Ubuntu 26.04, 1.6.1 on AlmaLinux 10 and Rocky Linux 10, 1.7.3 on Arch Linux and 1.7.2 on Gentoo; libpwquality 1.4.5; passwdqc 2.1.0 and pambase 20251104 on Gentoo (November 2026).

Files per distribution

Family Shared stacks Generated by Password quality module Module directory
Debian, Ubuntu common-auth, common-account, common-password, common-session, common-session-noninteractive pam-auth-update, from profiles in /usr/share/pam-configs/ None by default; pam_pwquality from libpam-pwquality /usr/lib/x86_64-linux-gnu/security/
AlmaLinux, Rocky Linux, RHEL system-auth, password-auth, fingerprint-auth, smartcard-auth, postlogin authselect; the files are symbolic links into /etc/authselect/ pam_pwquality, enabled /usr/lib64/security/
Arch Linux system-auth, system-login, system-local-login, system-remote-login, system-services Not generated; shipped by pambase None by default; pam_pwquality from libpwquality /usr/lib/security/
Gentoo system-auth, system-login, system-local-login, system-remote-login, system-services Not generated; shipped by sys-auth/pambase, contents chosen by its USE flags pam_passwdqc, enabled (USE flag passwdqc); pam_pwquality with USE flag pwquality /usr/lib64/security/

/etc/pam.d/other, used for services without a file of their own, denies everything on the RHEL family, Arch Linux and Gentoo (Arch also logs with pam_warn). On Debian and Ubuntu it includes the four common-* files.

File Read by Purpose
/etc/security/faillock.conf pam_faillock, faillock Failed-login lockout settings
/etc/security/pwquality.conf, /etc/security/pwquality.conf.d/*.conf pam_pwquality, pwscore, pwmake Password quality rules
/etc/security/passwdqc.conf pam_passwdqc (when passed config=) Password quality rules (Gentoo)
/etc/security/limits.conf, /etc/security/limits.d/*.conf pam_limits Resource limits for sessions
/etc/security/access.conf pam_access Login access by user, group and origin
/etc/security/time.conf pam_time Login access by time
/etc/security/pwhistory.conf pam_pwhistory Password reuse history
/etc/login.defs shadow tools (useradd, passwd and others) Defaults for new accounts, password ageing, hash method; not read by most PAM modules

Line syntax

Field Values
Type auth, account, password, session. A leading - (for example -session) makes a missing module file silently ignored instead of failing the line.
Control A keyword (required, requisite, sufficient, optional, include, substack) or a bracketed list of value=action pairs
Module path A file name, looked up in the module directory, or an absolute path
Arguments Space-separated, module-specific. An argument containing spaces is written in square brackets, with \] for a literal ].

A line can be continued on the next one with a trailing \. On Debian and Ubuntu, @include <FILE> inserts every line of /etc/pam.d/<FILE>, for all four types.

Control keywords

Keyword Equivalent bracketed form Meaning
required [success=ok new_authtok_reqd=ok ignore=ignore default=bad] Failure makes the stack fail, after the remaining modules have run
requisite [success=ok new_authtok_reqd=ok ignore=ignore default=die] Failure makes the stack fail immediately
sufficient [success=done new_authtok_reqd=done default=ignore] Success ends the stack successfully, unless an earlier required module failed; failure is ignored
optional [success=ok new_authtok_reqd=ok default=ignore] The result matters only if it's the only module of that type in the stack
include Insert the lines of the same type from the named file in /etc/pam.d/
substack As include, but done and die in the included file end only the included stack, not the calling stack

Actions

Action Effect
ignore The result doesn't contribute to the stack's outcome
ok Use this result as the outcome if no earlier module failed; continue
done As ok, then end the stack and return
bad Record failure as the outcome; continue
die As bad, then end the stack and return
reset Forget the outcome recorded so far; continue
N (a positive integer) As ok, then skip the next N lines of the same type

Return values that can appear before =, in addition to default (every value not listed):

success open_err symbol_err service_err system_err buf_err perm_denied auth_err
cred_insufficient authinfo_unavail user_unknown maxtries new_authtok_reqd
acct_expired session_err cred_unavail cred_expired cred_err no_module_data
conv_err authtok_err authtok_recover_err authtok_lock_busy
authtok_disable_aging try_again ignore abort authtok_expired module_unknown
bad_item conv_again incomplete

Common modules

pam_unix

Traditional authentication against /etc/passwd and /etc/shadow. Provides all four types.

Argument Type Effect
nullok auth, password Allow accounts with an empty password
try_first_pass auth, password Use a password already collected by an earlier module; prompt if there is none
use_first_pass auth, password Use a password already collected by an earlier module; fail if there is none
use_authtok password Use the new password set by an earlier module (such as pam_pwquality) instead of prompting
yescrypt, sha512, sha256, blowfish, md5 password Hash method for new passwords; without one, ENCRYPT_METHOD from login.defs is used
rounds=N password Cost factor for the hash method
shadow password Store the hash in /etc/shadow
remember=N password Refuse the last N passwords, kept in /etc/security/opasswd (pam_pwhistory is the dedicated module)
obscure password Basic checks on a new password (palindrome, case change only, too similar, too short)
minlen=N password Minimum length of a new password
audit all Log the user name, even when unknown
quiet session Don't log session open and close

pam_faillock

Counts failed authentication attempts per user and locks the account for a time after too many. Replaces pam_tally and pam_tally2, which were removed in Linux-PAM 1.5.0. Used in auth (twice: preauth before the password module and authfail after it, optionally authsucc) and in account. Settings come from /etc/security/faillock.conf, or from arguments with the same names.

Option Default Effect
dir=PATH /var/run/faillock Directory with one tally file per user
deny=N 3 Lock after N consecutive failures
fail_interval=SECONDS 900 Only failures within this interval count
unlock_time=SECONDS 600 Unlock automatically after this time; 0 or never means only an administrator can unlock
even_deny_root not set Also lock root
root_unlock_time=SECONDS as unlock_time Unlock time for root, with even_deny_root
admin_group=NAME not set Treat members of this group like root
audit not set Log the user name of unknown users
silent not set Don't tell the user the account is locked
local_users_only not set Track only users in /etc/passwd
nodelay not set Don't add the delay that normally follows a failure

The faillock command shows and resets the tallies: faillock --user <USER> lists failures, faillock --user <USER> --reset unlocks. On the RHEL family, pam_faillock is enabled with authselect enable-feature with-faillock. Arch Linux enables it in system-auth by default; Gentoo enables it in system-auth with the pambase defaults in the lab image.

pam_pwquality

Checks the strength of a new password in the password group, usually as requisite before pam_unix, which then needs use_authtok. Settings come from /etc/security/pwquality.conf and the files in /etc/security/pwquality.conf.d/, or from arguments with the same names.

Option Default Effect
minlen=N 8 Minimum score: length, plus one per character class present when the corresponding credit is positive
minclass=N 0 Minimum number of character classes (digits, upper case, lower case, others)
dcredit, ucredit, lcredit, ocredit 0 Positive: credit towards minlen per character of that class, up to this number. Negative: at least that many characters of the class are required
difok=N 1 Characters in the new password that must not appear in the old one
maxrepeat=N 0 (off) Maximum run of identical characters
maxsequence=N 0 (off) Maximum length of a monotonic sequence such as abcd or 1234
maxclassrepeat=N 0 (off) Maximum run of characters of the same class
dictcheck=N 1 Non-zero: refuse words from the cracklib dictionary
usercheck=N 1 Non-zero: refuse passwords containing the user name
usersubstr=N 0 If greater than 3, also refuse passwords containing a substring of the user name of at least N characters
gecoscheck=N 0 Non-zero: refuse words from the user's GECOS field
badwords=LIST empty Space-separated words that must not appear
retry=N 1 Prompts before giving up
enforcing=N 1 Zero: only warn
enforce_for_root not set Also refuse weak passwords set by root (by default root only gets a warning)
local_users_only not set Skip users not in /etc/passwd

pwscore (in libpwquality-tools on Debian and Ubuntu, libpwquality elsewhere) scores a password read from standard input against the same settings.

pam_passwdqc

Gentoo's default password quality module (sys-auth/passwdqc), used in the password group before pam_unix. Gentoo passes config=/etc/security/passwdqc.conf.

Option Gentoo default Effect
min=N0,N1,N2,N3,N4 disabled,24,11,8,7 Minimum length for passwords with one character class, two classes, passphrases, three classes and four classes; disabled refuses that kind
max=N 72 Maximum length
passphrase=N 3 Words required for a passphrase
match=N 4 Length of common substrings looked for in the old password and in dictionaries
similar=permit\|deny deny Whether a new password may be similar to the old one
random=N 47 Bits of randomness in the suggested random passphrase
enforce=none\|users\|everyone none Who gets refused: no one (only warnings), non-root users, or everyone including root
retry=N 3 Prompts before giving up

An upper-case letter at the start and a digit at the end of a password don't count towards its number of classes.

pam_limits

Applies resource limits (setrlimit), process priority and login counts at session start (session group). Reads /etc/security/limits.conf, then every file in /etc/security/limits.d/ ending in .conf, in name order.

<DOMAIN>  <TYPE>  <ITEM>  <VALUE>
Field Values
Domain A user name, @group, %group (for maxlogins), * (default entry), a UID or GID range such as 1000:
Type soft (the value applied), hard (the ceiling users can raise the soft value to), - (both)
Item core, data, fsize, memlock, nofile, rss, stack, cpu, nproc, as, maxlogins, maxsyslogins, nonewprivs, priority, locks, sigpending, msgqueue, nice, rtprio
Value A number, or unlimited/infinity

Limits apply only to sessions opened through PAM. Services started by systemd don't pass through PAM; their limits are set with LimitNOFILE= and similar unit directives.

Tools that manage the files

Command Family Effect
pam-auth-update Debian, Ubuntu Regenerate the common-* files from the profiles in /usr/share/pam-configs/; with no option, choose profiles interactively; --enable/--disable NAME; --package (used by package scripts)
authselect current RHEL family Show the selected profile and features
authselect select <PROFILE> [FEATURES] RHEL family Select a profile (local, sssd, winbind) and features, and regenerate the files
authselect enable-feature <FEATURE> RHEL family Turn on a feature such as with-faillock, with-pwhistory, with-mkhomedir
authselect create-profile <NAME> -b <BASE> RHEL family Create a custom profile under /etc/authselect/custom/ for local changes
authselect check RHEL family Report whether the files were changed outside authselect

Examples

Lock an account for 15 minutes after five failures within 15 minutes, in /etc/security/faillock.conf:

deny = 5
fail_interval = 900
unlock_time = 900

Require 12 characters from at least three classes, in /etc/security/pwquality.conf.d/50-local.conf:

minlen = 12
minclass = 3

A password stack with pam_pwquality, as used on the RHEL family:

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

Raise the open-files limit for members of the group builders, in /etc/security/limits.d/50-builders.conf:

@builders  soft  nofile  8192
@builders  hard  nofile  65536

See also

  • pam(8), pam.conf(5), pam.d(5), pam_unix(8), pam_faillock(8), faillock.conf(5), pam_pwquality(8), pwquality.conf(5), pam_passwdqc(8), passwdqc.conf(5), pam_limits(8), limits.conf(5), login.defs(5), pam-auth-update(8), authselect(8)
  • Linux-PAM, libpwquality, passwdqc, authselect