How Can We Help?

How To Configure PAM (Pluggable Authentication Modules)

You are here:
< All Topics

Linux-PAM (Pluggable Authentication Modules) is a suite of shared libraries which dynamically authenticate users and access to applications or services.




Accidental deletion or corruption of configuration files under /etc/pam.d/ or the /etc/pam.conf can lock you out of the system!



To deploy PAM an application needs to be “PAM aware“. This means it must be written and compiled to use PAM. To check whether a program is “PAM-aware”, run ldd.


Eg, for sshd:


root@intel:~# ldd /usr/sbin/sshd | grep => /lib/x86_64-linux-gnu/ (0x00007f18cab59000)


The main configuration file for PAM is located at /etc/pam.conf.


The /etc/pam.d/ directory contains PAM configuration files for PAM-aware applications and services.


IMPORTANT: PAM will ignore the file if the directory exists.




Syntax for the main pam.conf configuration file


service type control-flag module module-arguments




service: is the actual application name.
type: module type/context/interface.
control-flag: this defines the behaviour of the PAM-API if the module fails its authentication task.
module: the absolute or relative pathname of the PAM-API.
module-arguments: a space separated list of tokens used to control PAM module behavior.


Rules are written on a single line, with overflow onto the next line using the “\” escape character.


Comments are preceded with the hash sign “#” and apply to the next end of line.



Example of a RAM rule definition, defined in the /etc/pam.d/sshd file, to disallow non-root logins when /etc/nologin exists:


account required



PAM authentication tasks have four independent management groups.


These groups are responsible for different aspects of a user request for a service or application.


All modules are assigned to one of the following management group types:


account: this provides services for account verification. For example, it checks the validity of a user password
authentication: this service authenticates the user and defines user credentials.
password: the password service updates user passwords and works together with the authentication modules.
session: this service manages actions performed at the start and end of a login session.


The PAM loadable object files (the actual PAM modules) are located at /lib/security/ or /lib64/security depending on the Linux system architecture.


The supported control-flags are:


requisite: a failure instantly returns control back to the application and indicates the nature of the first module failure.
required: the module must return a positive successful result in order for libpam to return a success result back to the application.
sufficient: provided all preceding modules have succeeded, the success of this module results in an immediate and successful return back to the application (while failure of this module is ignored).
optional: success or failure of this module is not recorded or required.


There are also two control flag directives used for PAM:


include: this directive includes all lines of given type from the configuration file specified as an argument for this control.
substack: this directs PAM to include all lines of given type from the configuration file specified as an argument for this control.



A Practical Example of How To Deploy PAM


In this example, we will use PAM to restrict root access to the SSH service for certain users.


The following defined PAM rule will tell PAM to consult the /etc/ssh/deniedusers file and deny access to the SSH and login services for any user listed in this file.


For this we use the /lib/security/ module.


nano /etc/pam.d/sshd




nano /etc/pam.d/login



Add the following rule to both files:


auth required \
onerr=succeed item=user sense=deny file=/etc/ssh/deniedusers



auth: is the PAM module type (or context).


required: is the control-flag. This means that if the module is used, then it must succeed or else the overall result will be a fail, regardless of the status of any other modules. is the PAM module which enables services to be denied or permitted based on an arbitrary file list.


onerr=succeed: the module argument.


item=user: a module argument which specifies what is to be listed and checked for in the file.


sense=deny: this module argument specifies the action to take if it is found in the file. If the item is not found in the file, then the opposite action will result.


file=/etc/ssh/deniedusers: the module argument specifying the file to be referenced.


Following this we now create the file /etc/ssh/deniedusers and add the name (in this case root) to it:


nano /etc/ssh/deniedusers


Finally set the permissions:


chmod 600 /etc/ssh/deniedusers




An overview of PAM modules and PAM man pages



root@intel:/# apropos pam
PAM (7) – Pluggable Authentication Modules for Linux
capability.conf (5) – configuration file for the pam_cap module
faillock.conf (5) – pam_faillock configuration file
group.conf (5) – configuration file for the pam_group module
limits.conf (5) – configuration file for the pam_limits module
pam (5) – portable arbitrary map file format
pam (7) – Pluggable Authentication Modules for Linux
pam-auth-update (8) – manage PAM configuration using packaged profiles
pam.conf (5) – PAM configuration files
pam.d (5) – PAM configuration files
pam_access (8) – PAM module for logdaemon style login access control
pam_cap (8) – PAM module to set inheritable capabilities
pam_debug (8) – PAM module to debug the PAM stack
pam_deny (8) – The locking-out PAM module
pam_echo (8) – PAM module for printing text messages
pam_env (7) – PAM module to set/unset environment variables
pam_env.conf (5) – the environment variables config files
pam_exec (8) – PAM module which calls an external command
pam_extrausers (8) – Module for libnss-extrausers authentication
pam_faildelay (8) – Change the delay on failure per-application
pam_faillock (8) – Module counting authentication failures during a specified interval
pam_filter (8) – PAM filter module
pam_ftp (8) – PAM module for anonymous access module
pam_getenv (8) – get environment variables from /etc/environment
pam_group (8) – PAM module for group access
pam_issue (8) – PAM module to add issue file to user prompt
pam_keyinit (8) – Kernel session keyring initialiser module
pam_lastlog (8) – PAM module to display date of last login and perform inactive account lock out
pam_limits (8) – PAM module to limit resources
pam_listfile (8) – deny or allow services based on an arbitrary file
pam_localuser (8) – require users to be listed in /etc/passwd
pam_loginuid (8) – Record user’s login uid to the process attribute
pam_mail (8) – Inform about available mail
pam_mkhomedir (8) – PAM module to create users home directory
pam_motd (8) – Display the motd file
pam_namespace (8) – PAM module for configuring namespace for a session
pam_nologin (8) – Prevent non-root users from login
pam_permit (8) – The promiscuous module
pam_pwhistory (8) – PAM module to remember last passwords
pam_rhosts (8) – The rhosts PAM module
pam_rootok (8) – Gain only root access
pam_securetty (8) – Limit root login to special devices
pam_selinux (7) – PAM module to set the default security context
pam_sepermit (8) – PAM module to allow/deny login depending on SELinux enforcement state
pam_shells (8) – PAM module to check for valid login shell
pam_succeed_if (8) – test account characteristics
pam_systemd (8) – Register user sessions in the systemd login manager
pam_tally (8) – The login counter (tallying) module
pam_tally2 (8) – The login counter (tallying) module
pam_time (8) – PAM module for time control access
pam_timestamp (8) – Authenticate using cached successful authentication attempts
pam_timestamp_check (8) – Check to see if the default timestamp is valid
pam_tty_audit (8) – Enable or disable TTY auditing for specified users
pam_umask (8) – PAM module to set the file mode creation mask
pam_unix (8) – Module for traditional password authentication
pam_userdb (8) – PAM module to authenticate against a db database
pam_warn (8) – PAM module which logs all PAM items if called
pam_wheel (8) – Only permit root access to members of group wheel
pam_xauth (8) – PAM module to forward xauth keys between users
pamcut (1) – cut a rectangle out of a PAM, PBM, PGM, or PPM image
pamdeinterlace (1) – remove ever other row from a PAM/PNM image
pamdice (1) – slice a Netpbm image into many horizontally and/or vertically
pamfile (1) – describe a Netpbm (PAM or PNM) file
pamoil (1) – turn a PAM image into an oil painting
pamon (1) – Play back or record raw or encoded audio streams on a PulseAudio sound server
pamstack (1) – stack planes of multiple PAM images into one PAM image
pamstretch (1) – scale up a PNM or PAM image by interpolating between pixels
pamstretch-gen (1) – use pamstretch and pnmscale to scale by non-integer values
pgmoil (1) – turn a PAM image into an oil painting
pnminterp (1) – scale up a PNM or PAM image by interpolating between pixels
pnminterp-gen (1) – use pamstretch and pnmscale to scale by non-integer values
sepermit.conf (5) – configuration file for the pam_sepermit module
time.conf (5) – configuration file for the pam_time module





PAM Services


Applications that require authentication can use PAM for this by means of a service name.


Examples of the PAM services currently available on this machine:


root@intel:~# ls /etc/pam.d/
chfn common-account common-session cups lightdm-greeter newusers polkit-1 runuser su systemd-user
chpasswd common-auth common-session-noninteractive lightdm login other ppp runuser-l sudo xfce4-screensaver
chsh common-password cron lightdm-autologin monit passwd quagga sshd su-l


Each of the files at /etc/pam.d represents a PAM service. PAM will use a configuration file named as the service if
the /etc/pam.d directory exists.


Alternatively, if PAM is configured using the single file /etc/pam.conf then the service name is defined in the configuration file in the first column.





Table of Contents