| Linux System Administration |
| Home | Tech | Linux | Links | Consulting |
|
PAM configuration guide for Debian
In the past, programs for logging into a console, or the X Window System, had to be modified to support every new authentication method that was introduced. To remedy this situation, a framework was developed in the 1990s by Sun Microsystems' SunSoft development group, called Pluggable Authentication Modules (PAM). Basically a suite of shared libraries, it provides an abstraction layer between, on the one hand the various methods available that provide authentication, such as passwords, smartcards and biometrics, and on the other hand the applications that require authentication and would otherwise have to support those methods directly. With PAM, all that is necessary for these components to cooperate is that a specific PAM module be available for each of them. This page explains how Linux-PAM is configured on systems running Debian GNU/Linux, although most all of it will apply to other distributions as well. It is meant to support other pages on this site that cover subjects such as OpenLDAP and Kerberos. 1. Service type PAM is configured by defining a set of rules that can be stacked to combine the functions of various modules in order to complete a given authentication task. Originally, all PAM rules were defined in a single configuration file, /etc/pam.conf. This file can still be used, in which case each rule has up to five fields: service-type module-type control module-path arguments The service type usually matches the name of the service (see /etc/services) or application making the call to PAM, thus allowing certain modules to be applied to them. Valid service types can be, for example, login, su, sshd, or xdm, although other is used as a default. Later it became possible to use a directory instead. Now, if /etc/pam.d/ is present, which is the default for Debian lenny, PAM will ignore /etc/pam.conf and instead search the directory for a filename that matches the name of the service or application making the call. Usually, these configuration files have almost the same syntax as before: module-type control module-path arguments 2. Module type The module type, or task, is the management group that the rule corresponds to. Any particular PAM module will support up to four different types:
3. Control The control field determines how PAM will behave when a module fails. There are two different syntaxes available for it: a simple one that uses a single directive, and a more complex one that uses a set of value=action pairs. The simple syntax includes four possible directives:
The more complex syntax uses a square-bracketed selection of value=action pairs: [value1=action1 value2=action2 ...] The values are module return codes, possible valid choices for which are:
The actions can either be unsigned integers, indicating the number of modules in the stack to jump over next, or be one of the following keywords:
To illustrate how this syntax is used, each of the four simple control directives mentioned above can be replaced with an equivalent complex expression:
4. Module path The module path is either the full filename of the module, beginning with a "/", or a pathname that is relative to the default module directory, which is /lib/security/ on a Debian lenny system. In practice, this usually means that only the names of the modules are mentioned. The modules themselves are all named as pam_<name>.so. See the Linux-PAM System Administrator's Guide (linked below) for a list of all standard modules, their descriptions and possible arguments. 5. Arguments The last field is a space-separated list of tokens that can be used to modify the behavior of a module. Any arguments are usually found in the documentation for the module (e.g. man pam_unix). If an argument includes one or more spaces, it should surrounded by square brackets. Some modules go further and even have their own dedicated configuration files. 6. Include statements Linux-PAM also includes two relatively new keywords that are usually described as control directives − even in the Linux-PAM System Administrator's Guide − but are actually quite different:
As might be expected, the syntax for their use is a little different as well: module-type keyword file-path Here, the file path is either the full name of the file, beginning with a "/", or a pathname that is relative to the /etc/pam.d/ directory. Previously, Linux-PAM did not provide any include methods. To compensate for this lack of basic functionality, some distributions followed a solution adopted by RedHat, which was to use a module, called pam_stack.so. A complicated patch, it was basically a kludge that hijacked PAM's internals to obtain a pass over an additional configuration file. At first, Debian used pam_stack.so also, but later switched to a more elegant patch that achieves essentially the same result. The syntax for it is: @include file-path These statements are still used in Debian lenny, even though it is now possible to replaced them with native PAM include statements that are both more efficient and more flexible. Therefore, one might expect that this Debian patch will eventually be phased out. 7. Debian 5.0 defaults On Debian 5.0 (lenny) systems, every PAM service configuration file contains between one and four @include statements. This is because Debian lenny uses four configuration files − one for each of the four module types − to apply the same system defaults to all service types. It is a much more efficient solution than having to edit all of the individual service configuration files every time a general change is required. The five system default configuration files are:
System administrators are expected to edit only these four files. When configuring certain network applications, doing so is mandatory. In such cases, it is good to know what the default configurations are for these files. Here is an overview, followed by a few explanations: /etc/pam.d/common-auth: auth required pam_unix.so nullok_secure /etc/pam.d/common-account: account required pam_unix.so /etc/pam.d/common-password: password required pam_unix.so nullok obscure md5 /etc/pam.d/common-session: session required pam_unix.so The default employs only a single PAM module, pam_unix.so, which is used for standard Unix authentication, retrieving and setting account information, and changing passwords. This module has many possible arguments, four of which are used here:
The last two arguments are not mentioned in the Linux-PAM System Administrator's Guide, but are described in the Debian man page for pam_unix, along with many other options. 8. Debian 6.0 defaults On Debian 6.0 (squeeze) systems, every PAM service configuration file contains between one and five @include statements. This is because Debian squeeze uses five configuration files: one for each of the first three module types and two files for the fourth. This is to apply the same system defaults to all service types. It is a much more efficient solution than having to edit all of the individual service configuration files every time a general change is required. The five system default configuration files are:
The last file is new with Debian squeeze, its purpose being to allow those session modules that do not provide shell-like interactive capabilities for users (e.g. cron, cups, samba, ppp) to be separated from those that do (e.g. login, ssh, gdm). This way, it can be avoided that certain modules are called unnecessarily for certain services in certain contexts. All of these files now include a structure that is a bit more complex than it was previously with Debian lenny:
The primary block consists of one or more PAM modules associated with various applications. The fallback is a module that always denys access in case none of the primary block modules succeed. The stack is then primed to permit access with a module that always results in a positive return value. This is to avoid an error code being returned in case a success code has not already been set. Finally, an additional block of one or more modules may follow. System administrators are expected to alter only these five files. However, as of PAM v1.0.1-6, the default is to manage these files with pam-auth-update. This Perl script is used to configure PAM using the pre-defined profiles that come with PAM module packages. Nevertheless, it is good to know what the default configurations are for these files in case manual intervention is needed anyway. Here is an overview, followed by a few explanations: /etc/pam.d/common-auth: auth [success=1 default=ignore] pam_unix.so nullok_secure auth requisite pam_deny.so auth required pam_permit.so /etc/pam.d/common-account: account [success=1 new_authtok_reqd=done default=ignore] pam_unix.so account requisite pam_deny.so account required pam_permit.so /etc/pam.d/common-password: password [success=1 default=ignore] pam_unix.so obscure sha512 password requisite pam_deny.so password required pam_permit.so /etc/pam.d/common-session: session [default=1] pam_permit.so session requisite pam_deny.so session required pam_permit.so session required pam_unix.so /etc/pam.d/common-session-noninteractive: session [default=1] pam_permit.so session requisite pam_deny.so session required pam_permit.so session required pam_unix.so As opposed to the PAM configuration files in Debian 5.0 (lenny), here the first three files are configured so that the correct return values are more likely to be given, rather than when this is left up to the pam_unix.so module alone, or any other module(s) that might be used along with it or in its place. In each of these three cases, depending on the response from the pam_unix.so module, the second module, pam_deny.so, will either be skipped or not. If it is, the next and last module to be processed will be pam_permit.so, which always permits access. If it is not skipped, pam_deny.so will not only deny access, but because of the requisite directive, control will immediately be returned to the application before pam_permit.so is ever reached. The default configuration employs three different PAM modules. The first, pam_unix.so, is used for standard Unix authentication, retrieving and setting account information, and changing passwords. This module has many possible arguments, three of which are used here:
The last two arguments are not mentioned in the Linux-PAM System Administrator's Guide, but are described in the Debian man page for pam_unix, along with many other options. 9. See also
10. Further reading
11. Sources
Last modified: 2017-08-02, 17:32
©2003-2020 RJ Systems. Permission is granted to copy, distribute and/or modify the content of this page under the terms of the OpenContent License, version 1.0. |
