Next Previous Contents

6. A reference guide for available modules

Here, we collect together some descriptions of the various modules available for Linux-PAM. In general these modules should be freely available. Where this is not the case, it will be indicated.

Also please note the comments contained in the section on text conventions above when copying the examples listed below.

6.1 The access module

Synopsis

Module Name:

pam_access

Author[s]:

Alexei Nogin <alexei@nogin.dnttm.ru>

Maintainer:
Management groups provided:

account

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

Requires a configuration file. By default /etc/security/access.conf is used but this can be overridden.

Network aware:

Through PAM_TTY if set, otherwise attempts getting tty name of the stdin file descriptor with ttyname(). Standard gethostname(), yp_get_default_domain(), gethostbyname() calls. NIS is used for netgroup support.

Overview of module

Provides logdaemon style login access control.

Account component

Recognized arguments:

accessfile=/path/to/file.conf; fieldsep=separators

Description:

This module provides logdaemon style login access control based on login names and on host (or domain) names, internet addresses (or network numbers), or on terminal line names in case of non-networked logins. Diagnostics are reported through syslog(3). Wietse Venema's login_access.c from logdaemon-5.6 is used with several changes by A. Nogin.

The behavior of this module can be modified with the following arguments:

Examples/suggested usage:

Use of module is recommended, for example, on administrative machines such as NIS servers and mail servers where you need several accounts active but don't want them all to have login capability.

For /etc/pam.d style configurations where your modules live in /lib/security, start by adding the following line to /etc/pam.d/login, /etc/pam.d/rlogin, /etc/pam.d/rsh and /etc/pam.d/ftp:

account  required       /lib/security/pam_access.so

Note that use of this module is not effective unless your system ignores .rhosts files. See the the pam_rhosts_auth documentation.

A sample access.conf configuration file is included with the distribution.

6.2 Chroot

Synopsis

Module Name:

pam_chroot

Author:

Bruce Campbell <brucec@humbug.org.au>

Maintainer:

Author; proposed on 20/11/96 - email for status

Management groups provided:

account; session; authentication

Cryptographically sensitive:
Security rating:
Clean code base:

Unwritten.

System dependencies:
Network aware:

Expects localhost.

Overview of module

This module is intended to provide a transparent wrapper around the average user, one that puts them in a fake file-system (eg, their '/' is really /some/where/else).

Useful if you have several classes of users, and are slightly paranoid about security. Can be used to limit who else users can see on the system, and to limit the selection of programs they can run.

Account component:

Need more info here.

Authentication component:

Need more info here.

Session component:

Need more info here.

Recognized arguments:

Arguments and logging levels for the PAM version are being worked on.

Description:
Examples/suggested usage:

Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm', 'cp' and 'ed' in there is a bit...

Don't take it to extremes (eg, you can set up a separate environment for each user, but its a big waste of your disk space.)

6.3 Cracklib pluggable password strength-checker

Synopsis

Module Name:

pam_cracklib

Author:

Cristian Gafton <gafton@redhat.com>

Maintainer:

Author.

Management groups provided:

password

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

Requires the system library libcrack and a system dictionary: /var/cache/cracklib/cracklib_dict.

Network aware:

Overview of module

This module can be plugged into the password stack of a given application to provide some plug-in strength-checking for passwords.

This module works in the following manner: it first calls the Cracklib routine to check the strength of the password; if crack likes the password, the module does an additional set of strength checks. These checks are:

This module with no arguments will work well for standard unix password encryption. With md5 encryption, passwords can be longer than 8 characters and the default settings for this module can make it hard for the user to choose a satisfactory new password. Notably, the requirement that the new password contain no more than 1/2 of the characters in the old password becomes a non-trivial constraint. For example, an old password of the form "the quick brown fox jumped over the lazy dogs" would be difficult to change... In addition, the default action is to allow passwords as small as 5 characters in length. For a md5 systems it can be a good idea to increase the required minimum size of a password. One can then allow more credit for different kinds of characters but accept that the new password may share most of these characters with the old password.

Password component

Recognized arguments:

debug; type=XXX; retry=N; difok=N; minlen=N; dcredit=N; ucredit=N; lcredit=N; ocredit=N; use_authtok;

Description:

The action of this module is to prompt the user for a password and check its strength against a system dictionary and a set of rules for identifying poor choices.

The default action is to prompt for a single password, check its strength and then, if it is considered strong, prompt for the password a second time (to verify that it was typed correctly on the first occasion). All being well, the password is passed on to subsequent modules to be installed as the new authentication token.

The default action may be modified in a number of ways using the arguments recognized by the module:

Examples/suggested usage:

For an example of the use of this module, we show how it may be stacked with the password component of pam_unix:

#
# These lines stack two password type modules. In this example the
# user is given 3 opportunities to enter a strong password. The
# "use_authtok" argument ensures that the pam_unix module does not
# prompt for a password, but instead uses the one provided by
# pam_cracklib.
#
passwd  password required       pam_cracklib.so retry=3
passwd  password required       pam_unix.so use_authtok

Another example (in the /etc/pam.d/passwd format) is for the case that you want to use md5 password encryption:

#%PAM-1.0
#
# These lines allow a md5 systems to support passwords of at least 14
# bytes with extra credit of 2 for digits and 2 for others the new
# password must have at least three bytes that are not present in the
# old password
#
password  required pam_cracklib.so \
               difok=3 minlen=15 dcredit= 2 ocredit=2
password  required pam_unix.so use_authtok nullok md5

And here is another example in case you don't want to use credits:

#%PAM-1.0
#
# These lines require the user to select a password with a minimum
# length of 8 and with at least 1 digit number, 1 upper case letter,
# and 1 other character
#
password  required pam_cracklib.so \
               dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
password  required pam_pwdb.so use_authtok nullok md5

In this example we simply say that the password must have a minimum length of 8:

#%PAM-1.0
#
# These lines require the user to select a password with a mimimum
# length of 8. He gets no credits and he is not forced to use
# digit numbers, upper case letters etc.
#
password  required pam_cracklib.so \
               dcredit=0 ucredit=0 ocredit=0 lcredit=0 minlen=8
password  required pam_pwdb.so use_authtok nullok md5

6.4 The locking-out module

Synopsis

Module Name:

pam_deny

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

current Linux-PAM maintainer

Management groups provided:

account; authentication; password; session

Cryptographically sensitive:
Security rating:
Clean code base:

clean.

System dependencies:
Network aware:

Overview of module

This module can be used to deny access. It always indicates a failure to the application through the PAM framework. As is commented in the overview section above, this module might be suitable for using for default (the OTHER) entries.

Account component

Recognized arguments:
Description:

This component does nothing other than return a failure. The failure type is PAM_ACCT_EXPIRED.

Examples/suggested usage:

Stacking this module with type account will prevent the user from gaining access to the system via applications that refer to Linux-PAM's account management function pam_acct_mgmt().

The following example would make it impossible to login:

#
# add this line to your other login entries to disable all accounts
#
login   account  required       pam_deny.so

Authentication component

Recognized arguments:
Description:

This component does nothing other than return a failure. The failure type is PAM_AUTH_ERR in the case that pam_authenticate() is called (when the application tries to authenticate the user), and is PAM_CRED_UNAVAIL when the application calls pam_setcred() (to establish and set the credentials of the user -- it is unlikely that this function will ever be called in practice).

Examples/suggested usage:

To deny access to default applications with this component of the pam_deny module, you might include the following line in your Linux-PAM configuration file:

#
# add this line to your existing OTHER entries to prevent
# authentication succeeding with default applications.
#
OTHER   auth     required       pam_deny.so

Password component

Recognized arguments:
Description:

This component of the module denies the user the opportunity to change their password. It always responds with PAM_AUTHTOK_ERR when invoked.

Examples/suggested usage:

This module should be used to prevent an application from updating the applicant user's password. For example, to prevent login from automatically prompting for a new password when the old one has expired you should include the following line in your configuration file:

#
# add this line to your other login entries to prevent the login
# application from being able to change the user's password.
#
login   password required       pam_deny.so

Session component

Recognized arguments:
Description:

This aspect of the module prevents an application from starting a session on the host computer.

Examples/suggested usage:

Together with another session module, that displays a message of the day perhaps (pam_motd for example), this module can be used to block a user from starting a shell. We might use the following entries in the configuration file to inform the user it is system time:

#
# An example to see how to configure login to refuse the user a
# session (politely)
#
login   session  required       pam_motd.so \
                        motd=/etc/system_time
login   session  required       pam_deny.so

6.5 Set/unset environment variables

Synopsis

Module Name:

pam_env

Author:

Dave Kinchlea <kinch@kinch.ark.com>

Maintainer:

Author

Management groups provided:

Authentication (setcred)

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

/etc/security/pam_env.conf

Network aware:

Overview of module

This module allows the (un)setting of environment variables. Supported is the use of previously set environment variables as well as PAM_ITEMs such as PAM_RHOST.

Authentication component

Recognized arguments:

debug; conffile=configuration-file-name; envfile=env-file-name; readenv=0|1

Description:

This module allows you to (un)set arbitrary environment variables using fixed strings, the value of previously set environment variables and/or PAM_ITEMs.

All is controlled via a configuration file (by default, /etc/security/pam_env.conf but can be overriden with conffile argument). Each line starts with the variable name, there are then two possible options for each variable DEFAULT and OVERRIDE. DEFAULT allows an administrator to set the value of the variable to some default value, if none is supplied then the empty string is assumed. The OVERRIDE option tells pam_env that it should enter in its value (overriding the default value) if there is one to use. OVERRIDE is not used, "" is assumed and no override will be done.

VARIABLE   [DEFAULT=[value]]  [OVERRIDE=[value]]

(Possibly non-existent) environment variables may be used in values using the ${string} syntax and (possibly non-existent) PAM_ITEMs may be used in values using the @{string} syntax. Both the $ and @ characters can be backslash-escaped to be used as literal values (as in \$. Double quotes may be used in values (but not environment variable names) when white space is needed the full value must be delimited by the quotes and embedded or escaped quotes are not supported.

This module can also parse a file with simple KEY=VAL pairs on seperate lines (/etc/environment by default). You can change the default file to parse, with the envfile flag and turn it on or off by setting the readenv flag to 1 or 0 respectively.

The behavior of this module can be modified with one of the following flags:

Examples/suggested usage:

See sample pam_env.conf for more information and examples.

6.6 The filter module

Synopsis

Module Name:

pam_filter

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author.

Management groups provided:

account; authentication; password; session

Cryptographically sensitive:

Not yet.

Security rating:
Clean code base:

This module compiles cleanly on Linux based systems.

System dependencies:

To function it requires filters to be installed on the system.

Network aware:

Overview of module

This module was written to offer a plug-in alternative to programs like ttysnoop (XXX - need a reference). Since writing a filter that performs this function has not occurred, it is currently only a toy. The single filter provided with the module simply transposes upper and lower case letters in the input and output streams. (This can be very annoying and is not kind to termcap based editors).

Account+Authentication+Password+Session components

Recognized arguments:

debug; new_term; non_term; runX

Description:

Each component of the module has the potential to invoke the desired filter. The filter is always execv(2)d with the privilege of the calling application and not that of the user. For this reason it cannot usually be killed by the user without closing their session.

The behavior of the module can be significantly altered by the arguments passed to it in the Linux-PAM configuration file:

Examples/suggested usage:

At the time of writing there is little real use to be made of this module. For fun you might try adding the following line to your login's configuration entries

#
# An example to see how to configure login to transpose upper and
# lower case letters once the user has logged in(!)
#
login   session  required       pam_filter.so \
                        run1 /usr/sbin/pam_filter/upperLOWER

6.7 Anonymous access module

Synopsis

Module Name:

pam_ftp.so

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author.

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

prompts for email address of user; easily spoofed (XXX - needs work)

Overview of module

The purpose of this module is to provide a pluggable anonymous ftp mode of access.

Authentication component

Recognized arguments:

debug; users=XXX,YYY,...; ignore

Description:

This module intercepts the user's name and password. If the name is ``ftp'' or ``anonymous'', the user's password is broken up at the `@' delimiter into a PAM_RUSER and a PAM_RHOST part; these pam-items being set accordingly. The username (PAM_USER) is set to ``ftp''. In this case the module succeeds. Alternatively, the module sets the PAM_AUTHTOK item with the entered password and fails.

The behavior of the module can be modified with the following flags:

Examples/suggested usage:

An example of the use of this module is provided in the configuration file section above. With care, this module could be used to provide new/temporary account anonymous login.

6.8 The group access module

Synopsis

Module Name:

pam_group

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author.

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:

Sensitive to setgid status of file-systems accessible to users.

Clean code base:
System dependencies:

Requires an /etc/security/group.conf file. Can be compiled with or without libpwdb.

Network aware:

Only through correctly set PAM_TTY item.

Overview of module

This module provides group-settings based on the user's name and the terminal they are requesting a given service from. It takes note of the time of day.

Authentication component

Recognized arguments:
Description:

This module does not authenticate the user, but instead it grants group memberships (in the credential setting phase of the authentication module) to the user. Such memberships are based on the service they are applying for. The group memberships are listed in text form in the /etc/security/group.conf file.

Examples/suggested usage:

For this module to function correctly there must be a correctly formatted /etc/security/groups.conf file present. The format of this file is as follows. Group memberships are given based on the service application satisfying any combination of lines in the configuration file. Each line (barring comments which are preceded by `#' marks) has the following syntax:

services   ;   ttys   ;   users   ;   times   ;   groups
Here the first four fields share the syntax of the pam_time configuration file; /etc/security/pam_time.conf, and the last field, the groups field, is a comma (or space) separated list of the text-names of a selection of groups. If the users application for service satisfies the first four fields, the user is granted membership of the listed groups.

As stated in above this module's usefulness relies on the file-systems accessible to the user. The point being that once granted the membership of a group, the user may attempt to create a setgid binary with a restricted group ownership. Later, when the user is not given membership to this group, they can recover group membership with the precompiled binary. The reason that the file-systems that the user has access to are so significant, is the fact that when a system is mounted nosuid the user is unable to create or execute such a binary file. For this module to provide any level of security, all file-systems that the user has write access to should be mounted nosuid.

The pam_group module fuctions in parallel with the /etc/group file. If the user is granted any groups based on the behavior of this module, they are granted in addition to those entries /etc/group (or equivalent).

6.9 Add issue file to user prompt

Synopsis

Module Name:

pam_issue

Author:

Ben Collins <bcollins@debian.org>

Maintainer:

Author

Management groups provided:

Authentication (pam_sm_authenticate)

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

Overview of module

This module prepends the issue file (/etc/issue by default) when prompting for a username.

Authentication component

Recognized arguments:

issue=issue-file-name; noesc;

Description:

This module allows you to prepend an issue file to the username prompt. It also by default parses escape codes in the issue file similar to some common getty's (using \x format).

Recognized escapes:

The behavior of this module can be modified with one of the following flags:

Examples/suggested usage:

login auth pam_issue.so issue=/etc/issue

6.10 The Kerberos 4 module.

Synopsis

Module Name:

pam_krb4

Author:

Derrick J. Brashear <shadow@dementia.org>

Maintainer:

Author.

Management groups provided:

authentication; password; session

Cryptographically sensitive:

uses API

Security rating:
Clean code base:
System dependencies:

libraries - libkrb, libdes, libcom_err, libkadm; and a set of Kerberos include files.

Network aware:

Gets Kerberos ticket granting ticket via a Kerberos key distribution center reached via the network.

Overview of module

This module provides an interface for doing Kerberos verification of a user's password, getting the user a Kerberos ticket granting ticket for use with the Kerberos ticket granting service, destroying the user's tickets at logout time, and changing a Kerberos password.

Session component

Recognized arguments:
Description:

This component of the module currently sets the user's KRBTKFILE environment variable (although there is currently no way to export this), as well as deleting the user's ticket file upon logout (until PAM_CRED_DELETE is supported by login).

Examples/suggested usage:

This part of the module won't be terribly useful until we can change the environment from within a Linux-PAM module.

Password component

Recognized arguments:

use_first_pass; try_first_pass

Description:

This component of the module changes a user's Kerberos password by first getting and using the user's old password to get a session key for the password changing service, then sending a new password to that service.

Examples/suggested usage:

This should only be used with a real Kerberos v4 kadmind. It cannot be used with an AFS kaserver unless special provisions are made. Contact the module author for more information.

Authentication component

Recognized arguments:

use_first_pass; try_first_pass

Description:

This component of the module verifies a user's Kerberos password by requesting a ticket granting ticket from the Kerberos server and optionally using it to attempt to retrieve the local computer's host key and verifying using the key file on the local machine if one exists.

It also writes out a ticket file for the user to use later, and deletes the ticket file upon logout (not until PAM_CRED_DELETE is called from login).

Examples/suggested usage:

This module can be used with a real Kerberos server using MIT v4 Kerberos keys. The module or the system Kerberos libraries may be modified to support AFS style Kerberos keys. Currently this is not supported to avoid cryptography constraints.

6.11 The last login module

Synopsis

Module Name:

pam_lastlog

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author

Management groups provided:

auth

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

uses information contained in the /var/log/lastlog file.

Network aware:

Overview of module

This session module maintains the /var/log/lastlog file. Adding an open entry when called via the pam_open_seesion() function and completing it when pam_close_session() is called. This module can also display a line of information about the last login of the user. If an application already performs these tasks, it is not necessary to use this module.

Session component

Recognized arguments:

debug; nodate; noterm; nohost; silent; never

Description:

This module can be used to provide a ``Last login on ...'' message. when the user logs into the system from what ever application uses the PAM libraries. In addition, the module maintains the /var/log/lastlog file.

The behavior of this module can be modified with one of the following flags:

Examples/suggested usage:

This module can be used to indicate that the user has new mail when they login to the system. Here is a sample entry for your /etc/pam.d/XXX file:

#
# When were we last here?
#
session  optional       pam_lastlog.so

Note, some applications may perform this function themselves. In such cases, this module is not necessary.

6.12 The resource limits module

Synopsis

Module Name:

pam_limits

Authors:

Cristian Gafton <gafton@redhat.com>
Thanks are also due to Elliot Lee <sopwith@redhat.com> for his comments on improving this module.

Maintainer:

Cristian Gafton - 1996/11/20

Management groups provided:

session

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

requires an /etc/security/limits.conf file and kernel support for resource limits. Also uses the library, libpwdb.

Network aware:

Overview of module

This module, through the Linux-PAM open-session hook, sets limits on the system resources that can be obtained in a user-session. Its actions are dictated more explicitly through the configuration file discussed below.

Session component

Recognized arguments:

debug; conf=/path/to/file.conf; change_uid; utmp_early

Description:

Through the contents of the configuration file, /etc/security/limits.conf, resource limits are placed on users' sessions. Users of uid=0 are not affected by this restriction.

The behavior of this module can be modified with the following arguments:

Examples/suggested usage:

In order to use this module the system administrator must first create a root-only-readable file (default is /etc/security/limits.conf). This file describes the resource limits the superuser wishes to impose on users and groups. No limits are imposed on uid=0 accounts.

Each line of the configuration file describes a limit for a user in the form:

<domain>     <type>       <item>               <value>

The fields listed above should be filled as follows...
<domain> can be:

<type> can have the three values:

<item> can be one of the following:

Note, if you specify a type of ``-'' but neglect to supply the item and value fields then the module will never enforce any limits on the corresponding user/group-members etc. . Note, the first entry of the form which applies to the authenticating user will override all other entries in the limits configuration file. In such cases, the pam_limits module will always return PAM_SUCCESS.

In general, individual limits have priority over group limits, so if you impose no limits for admin group, but one of the members in this group have a limits line, the user will have its limits set according to this line.

Also, please note that all limit settings are set per login. They are not global, nor are they permanent; existing only for the duration of the session.

In the limits configuration file, the ``#'' character introduces a comment - after which the rest of the line is ignored.

The pam_limits module does its best to report configuration problems found in its configuration file via syslog(3).

The following is an example configuration file:

# EXAMPLE /etc/security/limits.conf file:
# =======================================
# <domain>   <type>       <item>               <value>
*               soft    core            0
*               hard    rss             10000
@student        hard    nproc           20
@faculty        soft    nproc           20
@faculty        hard    nproc           50
ftp             hard    nproc           0
ftp             -       chroot          /ftp
@student        -       maxlogins       4
Note, the use of soft and hard limits for the same resource (see @faculty) -- this establishes the default and permitted extreme level of resources that the user can obtain in a given service-session.

Note, that wild-cards * and % have the following meaning when used for maxlogins limit

See the following examples:
# EXAMPLE /etc/security/limits.conf file:
# <domain>   <type>       <item>               <value>
*               -       maxlogins       2
@faculty        -       maxlogins       4
%               -       maxlogins       30
%student        -       maxlogins       10
Explanation: every user can login 2 times, members of the faculty group can login 4 times, there can be only 30 logins, only 10 from students group.

For the services that need resources limits (login for example) put the following line in /etc/pam.conf as the last line for that service (usually after the pam_unix session line:

#
# Resource limits imposed on login sessions via pam_limits
#
login   session    required     pam_limits.so

6.13 The list-file module

Synopsis

Module Name:

pam_listfile

Author:

Elliot Lee <sopwith@cuc.edu>

Maintainer:

Red Hat Software:
Michael K. Johnson <johnsonm@redhat.com> 1996/11/18
(if unavailable, contact Elliot Lee <sopwith@cuc.edu>).

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:

clean

System dependencies:
Network aware:

Overview of module

The list-file module provides a way to deny or allow services based on an arbitrary file.

Authentication component

Recognized arguments:

onerr=succeed|fail; sense=allow|deny; file=filename; item=user|tty|rhost|ruser|group|shell apply=user|@group

Description:

The module gets the item of the type specified -- user specifies the username, PAM_USER; tty specifies the name of the terminal over which the request has been made, PAM_TTY; rhost specifies the name of the remote host (if any) from which the request was made, PAM_RHOST; and ruser specifies the name of the remote user (if available) who made the request, PAM_RUSER -- and looks for an instance of that item in the file filename. filename contains one line per item listed. If the item is found, then if sense=allow, PAM_SUCCESS is returned, causing the authorization request to succeed; else if sense=deny, PAM_AUTH_ERR is returned, causing the authorization request to fail.

If an error is encountered (for instance, if filename does not exist, or a poorly-constructed argument is encountered), then if onerr=succeed, PAM_SUCCESS is returned, otherwise if onerr=fail, PAM_AUTH_ERR or PAM_SERVICE_ERR (as appropriate) will be returned.

An additional argument, apply=, can be used to restrict the application of the above to a specific user (apply=username) or a given group (apply=@groupname). This added restriction is only meaningful when used with the tty, rhost and shell items.

Besides this last one, all arguments should be specified; do not count on any default behavior, as it is subject to change.

No credentials are awarded by this module.

Examples/suggested usage:

Classic ``ftpusers'' authentication can be implemented with this entry in /etc/pam.conf:

#
# deny ftp-access to users listed in the /etc/ftpusers file
#
ftp     auth     required       pam_listfile.so \
        onerr=succeed item=user sense=deny file=/etc/ftpusers
Note, users listed in /etc/ftpusers file are (counterintuitively) not allowed access to the ftp service.

To allow login access only for certain users, you can use a pam.conf entry like this:

#
# permit login to users listed in /etc/loginusers
#
login   auth     required       pam_listfile.so \
        onerr=fail item=user sense=allow file=/etc/loginusers

For this example to work, all users who are allowed to use the login service should be listed in the file /etc/loginusers. Unless you are explicitly trying to lock out root, make sure that when you do this, you leave a way for root to log in, either by listing root in /etc/loginusers, or by listing a user who is able to su to the root account.

6.14 The mail module

Synopsis

Module Name:

pam_mail

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author

Management groups provided:

Authentication (credential) Session (open)

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

Default mail directory /var/spool/mail/

Network aware:

Overview of module

This module looks at the user's mail directory and indicates whether the user has any mail in it.

Session component

Recognized arguments:

debug; dir=directory-name; nopen; close; noenv; empty; hash=hashcount; standard; quiet;

Description:

This module provides the ``you have new mail'' service to the user. It can be plugged into any application that has credential hooks. It gives a single message indicating the newness of any mail it finds in the user's mail folder. This module also sets the Linux-PAM environment variable, MAIL, to the user's mail directory.

The behavior of this module can be modified with one of the following flags:

Examples/suggested usage:

This module can be used to indicate that the user has new mail when they login to the system. Here is a sample entry for your /etc/pam.conf file:

#
# do we have any mail?
#
login   session  optional       pam_mail.so

Note, if the mail spool file (be it /var/spool/mail/$USER or a pathname given with the dir= parameter) is a directory then pam_mail assumes it is in the Qmail Maildir format.

Note, some applications may perform this function themselves. In such cases, this module is not necessary.

Authentication component

Then authentication companent works the same as the session component, except that everything is done during the pam_setcred() phase.

6.15 Create home directories on initial login

Synopsis

Module Name:

pam_mkhomedir

Author:

Jason Gunthorpe <jgg@ualberta.ca>

Maintainer:

Ben Collins <bcollins@debian.org>

Management groups provided:

Session

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

Overview of module

Creates home directories on the fly for authenticated users.

Session component

Recognized arguments:

debug; skel=skeleton-dir; umask=octal-umask;

Description:

This module is useful for distributed systems where the user account is managed in a central database (such as NIS, NIS+, or LDAP) and accessed through miltiple systems. It frees the administrator from having to create a default home directory on each of the systems by creating it upon the first succesfully authenticated login of that user. The skeleton directory (usually /etc/skel/) is used to copy default files and also set's a umask for the creation.

The behavior of this module can be modified with one of the following flags:

Examples/suggested usage:

session required pam_mkhomedir.so skel=/etc/skel/ umask=0022

6.16 Output the motd file

Synopsis

Module Name:

pam_motd

Author:

Ben Collins <bcollins@debian.org>

Maintainer:

Author

Management groups provided:

Session (open)

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

Overview of module

This module outputs the motd file (/etc/motd by default) upon successful login.

Session component

Recognized arguments:

debug; motd=motd-file-name;

Description:

This module allows you to have arbitrary motd's (message of the day) output after a succesful login. By default this file is /etc/motd, but is configurable to any file.

The behavior of this module can be modified with one of the following flags:

Examples/suggested usage:

login session pam_motd.so motd=/etc/motd

6.17 The no-login module

Synopsis

Module Name:

pam_nologin

Author:

Written by Michael K. Johnson <johnsonm@redhat.com>

Maintainer:
Management groups provided:

account; authentication

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

Overview of module

Provides standard Unix nologin authentication.

Authentication component

Recognized arguments:

successok, file=<filename>

Description:

Provides standard Unix nologin authentication. If the file /etc/nologin exists, only root is allowed to log in; other users are turned away with an error message (and the module returns PAM_AUTH_ERR or PAM_USER_UNKNOWN). All users (root or otherwise) are shown the contents of /etc/nologin.

If the file /etc/nologin does not exist, this module defaults to returning PAM_IGNORE, but the successok module argument causes it to return PAM_SUCCESS in this case.

The administrator can override the default nologin file with the file=pathname module argument.

Examples/suggested usage:

In order to make this module effective, all login methods should be secured by it. It should be used as a required method listed before any sufficient methods in order to get standard Unix nologin semantics. Note, the use of successok module argument causes the module to return PAM_SUCCESS and as such would break such a configuration - failing sufficient modules would lead to a successful login because the nologin module succeeded.

6.18 The promiscuous module

Synopsis

Module Name:

pam_permit

Author:

Andrew G. Morgan, <morgan@kernel.org>

Maintainer:

Linux-PAM maintainer.

Management groups provided:

account; authentication; password; session

Cryptographically sensitive:
Security rating:

VERY LOW. Use with extreme caution.

Clean code base:

Clean.

System dependencies:
Network aware:

Overview of module

This module is very dangerous. It should be used with extreme caution. Its action is always to permit access. It does nothing else.

Account+Authentication+Password+Session components

Recognized arguments:
Description:

No matter what management group, the action of this module is to simply return PAM_SUCCESS -- operation successful.

In the case of authentication, the user's name will be acquired. Many applications become confused if this name is unknown.

Examples/suggested usage:

It is seldom a good idea to use this module. However, it does have some legitimate uses. For example, if the system-administrator wishes to turn off the account management on a workstation, and at the same time continue to allow logins, then she might use the following configuration file entry for login:

#
# add this line to your other login entries to disable account
# management, but continue to permit users to log in...
#
login   account  required       pam_permit.so

6.19 The Password-Database module

Synopsis

Module Name:

pam_pwdb

Author:

Cristian Gafton <gafton@redhat.com>
and Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Red Hat.

Management groups provided:

account; authentication; password; session

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

Requires properly configured libpwdb

Network aware:

Overview of module

This module is a pluggable replacement for the pam_unix_.. modules. It uses the generic interface of the Password Database library libpwdb.

Account component

Recognized arguments:

debug

Description:

The debug argument makes the accounting functions of this module syslog(3) more information on its actions. (Remaining arguments supported by the other functions of this module are silently ignored, but others are logged as errors through syslog(3)).

Based on the following pwdb_elements: expire; last_change; max_change; defer_change; warn_change, this module performs the task of establishing the status of the user's account and password. In the case of the latter, it may offer advice to the user on changing their password or, through the PAM_AUTHTOKEN_REQD return, delay giving service to the user until they have established a new password. The entries listed above are documented in the Password Database Library Guide (see pointer above). Should the user's record not contain one or more of these entries, the corresponding shadow check is not performed.

Examples/suggested usage:

In its accounting mode, this module can be inserted as follows:

#
# Ensure users account and password are still active
#
login   account  required       pam_pwdb.so

Authentication component

Recognized arguments:

debug; use_first_pass; try_first_pass; nullok; nodelay; likeauth

Description:

The debug argument makes the authentication functions of this module syslog(3) more information on its actions.

The default action of this module is to not permit the user access to a service if their official password is blank. The nullok argument overrides this default.

When given the argument try_first_pass, before prompting the user for their password, the module first tries the previous stacked auth-module's password in case that satisfies this module as well. The argument use_first_pass forces the module to use such a recalled password and will never prompt the user - if no password is available or the password is not appropriate, the user will be denied access.

The argument, nodelay, can be used to discourage the authentication component from requesting a delay should the authentication as a whole fail. The default action is for the module to request a delay-on-failure of the order of one second.

Remaining arguments, supported by the other functions of this module, are silently ignored. Other arguments are logged as errors through syslog(3).

A helper binary, pwdb_chkpwd, is provided to check the user's password when it is stored in a read protected database. This binary is very simple and will only check the password of the user invoking it. It is called transparently on behalf of the user by the authenticating component of this module. In this way it is possible for applications like xlock to work without being setuid-root.

The likeauth argument makes the module return the same value when called as a credential setting module and an authentication module. This will help libpam take a sane path through the auth component of your configuration file.

Examples/suggested usage:

The correct functionality of this module is dictated by having an appropriate /etc/pwdb.conf file, the user databases specified there dictate the source of the authenticated user's record.

Password component

Recognized arguments:

debug; nullok; not_set_pass; use_authtok; try_first_pass; use_first_pass; md5; bigcrypt; shadow; radius; unix

Description:

This part of the pam_pwdb module performs the task of updating the user's password. Thanks to the flexibility of libpwdb this module is able to move the user's password from one database to another, perhaps securing the user's database entry in a dynamic manner (this is very ALPHA code at the moment!) - this is the purpose of the shadow, radius and unix arguments.

In the case of conventional unix databases (which store the password encrypted) the md5 argument is used to do the encryption with the MD5 function as opposed to the conventional crypt(3) call. As an alternative to this, the bigcrypt argument can be used to encrypt more than the first 8 characters of a password with DEC's (Digital Equipment Cooperation) `C2' extension to the standard UNIX crypt() algorithm.

The nullok module is used to permit the changing of a password from an empty one. Without this argument, empty passwords are treated as account-locking ones.

The argument use_first_pass is used to lock the choice of old and new passwords to that dictated by the previously stacked password module. The try_first_pass argument is used to avoid the user having to re-enter an old password when pam_pwdb follows a module that possibly shared the user's old password - if this old password is not correct the user will be prompted for the correct one. The argument use_authtok is used to force this module to set the new password to the one provided by the previously stacked password module (this is used in an example of the stacking of the Cracklib module documented above).

The not_set_pass argument is used to inform the module that it is not to pay attention to/make available the old or new passwords from/to other (stacked) password modules.

The debug argument makes the password functions of this module syslog(3) more information on its actions. Other arguments may be logged as erroneous to syslog(3).

Examples/suggested usage:

An example of the stacking of this module with respect to the pluggable password checking module, pam_cracklib, is given in that modules section above.

Session component

Recognized arguments:
Description:

No arguments are recognized by this module component. Its action is simply to log the username and the service-type to syslog(3). Messages are logged at the beginning and end of the user's session.

Examples/suggested usage:

The use of the session modules is straightforward:

#
# pwdb - unix like session opening and closing
#
login   session  required       pam_pwdb.so

6.20 The RADIUS session module

Synopsis

Module Name:

pam_radius

Author:

Cristian Gafton <gafton@redhat.com>

Maintainer:

Author.

Management groups provided:

session

Cryptographically sensitive:

This module does not deal with passwords

Security rating:
Clean code base:

gcc reports 1 warning when compiling /usr/include/rpc/clnt.h. Hey, is not my fault !

System dependencies:
Network aware:

yes; this is a network module (independent of application).

Overview of module

This module is intended to provide the session service for users authenticated with a RADIUS server. At the present stage, the only option supported is the use of the RADIUS server as an accounting server.

Session component

Recognized arguments:

debug - verbose logging to syslog(3).

Description:

This module is intended to provide the session service for users authenticated with a RADIUS server. At the present stage, the only option supported is the use of the RADIUS server as an accounting server.

(There are few things which needs to be cleared out first in the PAM project until one will be able to use this module and expect it to magically start pppd in response to a RADIUS server command to use PPP for this user, or to initiate a telnet connection to another host, or to hang and call back the user using parameters provided in the RADIUS server response. Most of these things are better suited for the radius login application. I hope to make available Real Soon (tm) patches for the login apps to make it work this way.)

When opening a session, this module sends an ``Accounting-Start'' message to the RADIUS server, which will log/update/whatever a database for this user. On close, an ``Accounting-Stop'' message is sent to the RADIUS server.

This module has no other prerequisites for making it work. One can install a RADIUS server just for fun and use it as a centralized accounting server and forget about wtmp/last/sac etc. .

Examples/suggested usage:

For the services that need this module (login for example) put the following line in /etc/pam.conf as the last line for that service (usually after the pam_unix session line):

login   session  required       pam_radius.so
Replace login for each service you are using this module.

This module make extensive use of the API provided in libpwdb 0.54preB or later. By default, it will read the radius server configuration (hostname and secret) from /etc/raddb/server. This is a default compiled into libpwdb, and curently there is no way to modify this default without recompiling libpwdb. I am working on extending the radius support from libpwdb to provide a possibility to make this runtime-configurable.

Also please note that libpwdb will require also the RADIUS dictionary to be present (/etc/raddb/dictionary).

6.21 The rhosts module

Synopsis

Module Name:

pam_rhosts_auth

Author:

Al Longyear <longyear@netcom.com>

Maintainer:
Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:

Clean.

System dependencies:
Network aware:

Standard inet_addr(), gethostbyname() function calls.

Overview of module

This module performs the standard network authentication for services, as used by traditional implementations of rlogin and rsh etc.

Authentication component

Recognized arguments:

no_hosts_equiv; no_rhosts; debug; no_warn; privategroup; promiscuous; suppress

Description:

The authentication mechanism of this module is based on the contents of two files; /etc/hosts.equiv (or _PATH_HEQUIV in #include <netdb.h>) and ~/.rhosts. Firstly, hosts listed in the former file are treated as equivalent to the localhost. Secondly, entries in the user's own copy of the latter file is used to map "remote-host remote-user" pairs to that user's account on the current host. Access is granted to the user if their host is present in /etc/hosts.equiv and their remote account is identical to their local one, or if their remote account has an entry in their personal configuration file.

Some restrictions are applied to the attributes of the user's personal configuration file: it must be a regular file (as defined by S_ISREG(x) of POSIX.1); it must be owned by the superuser or the user; it must not be writable by any user besides its owner.

The module authenticates a remote user (internally specified by the item PAM_RUSER) connecting from the remote host (internally specified by the item PAM_RHOST). Accordingly, for applications to be compatible this authentication module they must set these items prior to calling pam_authenticate(). The module is not capable of independently probing the network connection for such information.

In the case of root-access, the /etc/host.equiv file is ignored unless the hosts_equiv_rootok option should be used. Instead, the superuser must have a correctly configured personal configuration file.

The behavior of the module is modified by flags:

Examples/suggested usage:

To allow users to login from trusted remote machines, you should try adding the following line to your /etc/pam.conf file before the line that would otherwise prompt the user for a password:

#
# No passwords required for users from hosts listed above.
#
login  auth  sufficient  pam_rhosts_auth.so no_rhosts
Note, in this example, the system administrator has turned off all personal rhosts configuration files. Also note, that this module can be used to only allow remote login from hosts specified in the /etc/host.equiv file, by replacing sufficient in the above example with required.

6.22 The root access module

Synopsis

Module Name:

pam_rootok

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Linux-PAM maintainer

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:

Clean.

System dependencies:
Network aware:

Overview of module

This module is for use in situations where the superuser wishes to gain access to a service without having to enter a password.

Authentication component

Recognized arguments:

debug

Description:

This module authenticates the user if their uid is 0. Applications that are created setuid-root generally retain the uid of the user but run with the authority of an enhanced effective-uid. It is the real uid that is checked.

Examples/suggested usage:

In the case of the su application the historical usage is to permit the superuser to adopt the identity of a lesser user without the use of a password. To obtain this behavior under Linux-PAM the following pair of lines are needed for the corresponding entry in the configuration file:

#
# su authentication. Root is granted access by default.
#
su      auth     sufficient     pam_rootok.so
su      auth     required       pam_unix_auth.so

Note. For programs that are run by the superuser (or started when the system boots) this module should not be used to authenticate users.

6.23 The securetty module

Synopsis

Module Name:

pam_securetty

Author[s]:

Elliot Lee <sopwith@cuc.edu>

Maintainer:

Red Hat Software:
currently Michael K. Johnson <johnsonm@redhat.com>
(if unavailable, contact Elliot Lee <sopwith@cuc.edu>).

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

/etc/securetty file

Network aware:

Requires the application to fill in the PAM_TTY item correctly in order to act meaningfully.

Overview of module

Provides standard Unix securetty checking.

Authentication component

Recognized arguments:
Description:

Provides standard Unix securetty checking, which causes authentication for root to fail unless PAM_TTY is set to a string listed in the /etc/securetty file. For all other users, it succeeds.

Examples/suggested usage:

For canonical usage, should be listed as a required authentication method before any sufficient authentication methods.

6.24 The login counter (tallying) module

Synopsis

Module Name:

pam_tally

Author[s]:

Tim Baverstock

Maintainer:
Management groups provided:

auth; account

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

A faillog file (default location /var/log/faillog)

Network aware:

Overview of module

This module maintains a count of attempted accesses, can reset count on success, can deny access if too many attempts fail.

pam_tally comes in two parts: pam_tally.so and pam_tally. The former is the PAM module and the latter, a stand-alone program. pam_tally is an (optional) application which can be used to interrogate and manipulate the counter file. It can display users' counts, set individual counts, or clear all counts. Setting artificially high counts may be useful for blocking users without changing their passwords. For example, one might find it useful to clear all counts every midnight from a cron job.

The counts file is organized as a binary-word array, indexed by uid. You can probably make sense of it with od, if you don't want to use the supplied appliction.

Note, there are some outstanding issues with this module: pam_tally is very dependant on getpw*() - a database of usernames would be much more flexible; the `keep a count of current logins' bit has been #ifdef'd out and you can only reset the counter on successful authentication, for now.

Generic options accepted by both components

Authentication component

Recognized arguments:

onerr=(succeed|fail); file=/where/to/keep/counts; no_magic_root

Description:

The authentication component of this module increments the attempted login counter.

Examples/suggested usage:

The module argument no_magic_root is used to indicate that if the module is invoked by a user with uid=0, then the counter is incremented. The sys-admin should use this for daemon-launched services, like telnet/rsh/login. For user launched services, like su, this argument should be omitted.

By way of more explanation, when a process already running as root tries to access some service, the access is magic, and bypasses pam_tally's checks: this is handy for suing from root into an account otherwise blocked. However, for services like telnet or login, which always effectively run from the root account, root (ie everyone) shouldn't be granted this magic status, and the flag `no_magic_root' should be set in this situation, as noted in the summary above.

Account component

Recognized arguments:

onerr=(succeed|fail); file=/where/to/keep/counts; deny=n; no_magic_root; even_deny_root_account; reset; no_reset; per_user; no_lock_time

Description:

The account component can deny access and/or reset the attempts counter. It also checks to make sure that the counts file is a plain file and not world writable.

Examples/suggested usage:

The deny=n option is used to deny access if tally for this user exceeds n. The presence of deny=n changes the default for reset/no_reset to reset, unless the user trying to gain access is root and the no_magic_root option has NOT been specified.

The no_magic_root option ensures that access attempts by root DON'T ignore deny. Use this for daemon-based stuff, like telnet/rsh/login.

The even_deny_root_account option is used to ensure that the root account can become unavailable. Note that magic root trying to gain root bypasses this, but normal users can be locked out.

The reset option instructs the module to reset count to 0 on successful entry, even for magic root. The no_reset option is used to instruct the module to not reset the count on successful entry. This is the default unless deny exists and the user attempting access is NOT magic root.

If /var/log/faillog contains a non-zero .fail_max field for this user then the per_user module argument will ensure that the module uses this value and not the global deny=n parameter.

The no_lock_time option is for ensuring that the module does not use the .fail_locktime field in /var/log/faillog for this user.

Normally, failed attempts to access root will NOT cause the root account to become blocked, to prevent denial-of-service: if your users aren't given shell accounts and root may only login via su or at the machine console (not telnet/rsh, etc), this is safe. If you really want root to be blocked for some given service, use even_deny_root_account.

6.25 Time control

Synopsis

Module Name:

pam_time

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author

Management groups provided:

account

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

Requires a configuration file /etc/security/time.conf

Network aware:

Through the PAM_TTY item only

Overview of module

Running a well regulated system occasionally involves restricting access to certain services in a selective manner. This module offers some time control for access to services offered by a system. Its actions are determined with a configuration file. This module can be configured to deny access to (individual) users based on their name, the time of day, the day of week, the service they are applying for and their terminal from which they are making their request.

Account component

Recognized arguments:
Description:

This module bases its actions on the rules listed in its configuration file: /etc/security/time.conf. Each rule has the following form,

services;ttys;users;times
In words, each rule occupies a line, terminated with a newline or the beginning of a comment; a `#'. It contains four fields separated with semicolons, `;'. The fields are as follows:

Note, that the given time restriction is only applied when the first three fields are satisfied by a user's application for service.

For convenience and readability a rule can be extended beyond a single line with a `\newline'.

Examples/suggested usage:

The use of this module is initiated with an entry in the Linux-PAM configuration file of the following type:

#
# apply pam_time accounting to login requests
#
login   account  required       pam_time.so
where, here we are applying the module to the login application.

Some examples of rules that can be placed in the /etc/security/time.conf configuration file are the following:

login ; tty* & !ttyp* ; !root ; !Al0000-2400

all users except for root are denied access to console-login at all times.

games ; * ; !waster ; Wd0000-2400 | Wk1800-0800

games (configured to use Linux-PAM) are only to be accessed out of working hours. This rule does not apply to the user waster.

Note, currently there is no daemon enforcing the end of a session. This needs to be remedied.

Poorly formatted rules are logged as errors using syslog(3).

6.26 The Unix Password module

Synopsis

Module Name:

pam_unix

Author:
Maintainer:
Management groups provided:

account; authentication; password; session

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

Overview of module

This is the standard Unix authentication module. It uses standard calls from the system's libraries to retrieve and set account information as well as authentication. Usually this is obtained from the /etc/passwd and the /etc/shadow file as well if shadow is enabled.

Account component

Recognized arguments:

debug; audit

Description:

The debug argument makes the accounting functions of this module syslog(3) more information on its actions. (Remaining arguments supported by the other functions of this module are silently ignored, but others are logged as errors through syslog(3)). The audit argument causes even more logging.

Based on the following shadow elements: expire; last_change; max_change; min_change; warn_change, this module performs the task of establishing the status of the user's account and password. In the case of the latter, it may offer advice to the user on changing their password or, through the PAM_AUTHTOKEN_REQD return, delay giving service to the user until they have established a new password. The entries listed above are documented in the GNU Libc info documents. Should the user's record not contain one or more of these entries, the corresponding shadow check is not performed.

Examples/suggested usage:

In its accounting mode, this module can be inserted as follows:

#
# Ensure users account and password are still active
#
login   account  required       pam_unix.so

Authentication component

Recognized arguments:

debug; audit; use_first_pass; try_first_pass; nullok; nodelay

Description:

The debug argument makes the authentication functions of this module syslog(3) more information on its actions. The audit causes even more information to be logged.

The default action of this module is to not permit the user access to a service if their official password is blank. The nullok argument overrides this default.

When given the argument try_first_pass, before prompting the user for their password, the module first tries the previous stacked auth-module's password in case that satisfies this module as well. The argument use_first_pass forces the module to use such a recalled password and will never prompt the user - if no password is available or the password is not appropriate, the user will be denied access.

The argument, nodelay, can be used to discourage the authentication component from requesting a delay should the authentication as a whole fail. The default action is for the module to request a delay-on-failure of the order of one second.

Remaining arguments, supported by the other functions of this module, are silently ignored. Other arguments are logged as errors through syslog(3).

A helper binary, unix_chkpwd, is provided to check the user's password when it is stored in a read protected database. This binary is very simple and will only check the password of the user invoking it. It is called transparently on behalf of the user by the authenticating component of this module. In this way it is possible for applications like xlock to work without being setuid-root.

Examples/suggested usage:

The correct functionality of this module is dictated by having an appropriate /etc/nsswitch.conf file, the user databases specified there dictate the source of the authenticated user's record.

In its authentication mode, this module can be inserted as follows:

#
# Authenticate the user
#
login   auth  required       pam_unix.so

Password component

Recognized arguments:

debug; audit; nullok; not_set_pass; use_authtok; try_first_pass; use_first_pass; md5; bigcrypt; shadow; nis; min; max; obscure; remember

Description:

This part of the pam_unix module performs the task of updating the user's password.

In the case of conventional unix databases (which store the password encrypted) the md5 argument is used to do the encryption with the MD5 function as opposed to the conventional crypt(3) call. As an alternative to this, the bigcrypt argument can be used to encrypt more than the first 8 characters of a password with DEC's (Digital Equipment Cooperation) `C2' extension to the standard UNIX crypt() algorithm.

The nullok argument is used to permit the changing of a password from an empty one. Without this argument, empty passwords are treated as account-locking ones.

The argument use_first_pass is used to lock the choice of old and new passwords to that dictated by the previously stacked password module. The try_first_pass argument is used to avoid the user having to re-enter an old password when pam_unix follows a module that possibly shared the user's old password - if this old password is not correct the user will be prompted for the correct one. The argument use_authtok is used to force this module to set the new password to the one provided by the previously stacked password module (this is used in an example of the stacking of the Cracklib module documented above).

The not_set_pass argument is used to inform the module that it is not to pay attention to/make available the old or new passwords from/to other (stacked) password modules.

The debug argument makes the password functions of this module syslog(3) more information on its actions. Other arguments may be logged as erroneous to syslog(3). The audit argument causes even more information to be logged.

With the nis argument, pam_unix will attempt to use NIS RPC for setting new passwords.

The remember argument takes one value. This is the number of most recent passwords to save for each user. These are saved in /etc/security/opasswd in order to force password change history and keep the user from alternating between the same password too frequently.

The min and max options allow control over the length of the password. These have a hard coded default of 1 and 8. The values are inclusive.

The obscure option enables some extra checks on the password. These is taken after the same obscure checks enabled in the original shadow package. This works very similar to the pam_cracklib module and implements these checks (it does not implement dictionary checks):

Examples/suggested usage:

Standard usage:

#
# Change the users password
#
passwd   password   required   pam_unix.so

An example of the stacking of this module with respect to the pluggable password checking module, pam_cracklib:

#
# Change the users password
#
passwd   password   required   pam_cracklib.so retry=3 minlen=6 difok=3
passwd   password   required   pam_unix.so use_authtok nullok md5

Session component

Recognized arguments:
Description:

No arguments are recognized by this module component. Its action is simply to log the username and the service-type to syslog(3). Messages are logged at the beginning and end of the user's session.

Examples/suggested usage:

The use of the session modules is straightforward:

#
# session opening and closing
#
login   session  required       pam_unix.so

6.27 The userdb module

Synopsis

Module Name:

pam_userdb

Author:

Cristian Gafton <gafton@redhat.com>

Maintainer:

Author.

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:

Requires Berkeley DB.

Network aware:

Overview of module

Look up users in a .db database and verify their password against what is contained in that database.

Authentication component

Recognized arguments:

debug; icase; dump; db=XXXX;

Description:

This module is used to verify a username/password pair against values stored in a Berkeley DB database. The database is indexed by the username, and the data fields corresponding to the username keys are the passwords, in unencrypted form, so caution must be exercised over the access rights to the DB database itself..

The module will read the password from the user using the conversation mechanism. If you are using this module on top of another authetication module (like pam_unix;) then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module.

The action of the module may be modified from this default by one or more of the following flags in the /etc/pam.d/<service> file.

Examples/suggested usage:

This is a normal ftp configuration file (usually placed as /etc/pam.d/ftp on most systems) that will accept for login users whose username/password pairs are provided in the /tmp/dbtest.db file:

#%PAM-1.0
auth       required     pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
auth       sufficient   pam_userdb.so icase db=/tmp/dbtest
auth       required     pam_unix.so shadow nullok try_first_pass
auth       required     pam_shells.so
account    required     pam_unix.so
session    required     pam_unix.so

6.28 Warning logger module

Synopsis

Module Name:

pam_warn

Author:

Andrew G. Morgan <morgan@kernel.org>

Maintainer:

Author.

Management groups provided:

authentication; password

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

logs information about the remote user and host (if pam-items are known)

Overview of module

This module is principally for logging information about a proposed authentication or application to update a password.

Authentication+Password component

Recognized arguments:
Description:

Log the service, terminal, user, remote user and remote host to syslog(3). The items are not probed for, but instead obtained from the standard pam-items.

Examples/suggested usage:

an example is provided in the configuration file section above.

6.29 The wheel module

Synopsis

Module Name:

pam_wheel

Author:

Cristian Gafton <gafton@redhat.com>

Maintainer:

Author.

Management groups provided:

authentication

Cryptographically sensitive:
Security rating:
Clean code base:
System dependencies:
Network aware:

Overview of module

Only permit root access to members of the wheel (gid=0) group.

Authentication component

Recognized arguments:

debug; trust; deny; group=XXXX

Description:

This module is used to enforce the so-called wheel group. By default, it permits root access to the system if the applicant user is a member of the wheel group (first, the module checks for the existence of a 'wheel' group. Otherwise the module defines the group with group-id 0 to be the wheel group).

The action of the module may be modified from this default by one or more of the following flags in the /etc/pam.conf file.

Examples/suggested usage:

To restrict access to superuser status to the members of the wheel group, use the following entries in your configuration file:

#
# root gains access by default (rootok), only wheel members can 
# become root (wheel) but Unix authenticate non-root applicants.
#
su      auth     sufficient     pam_rootok.so
su      auth     required       pam_wheel.so
su      auth     required       pam_unix_auth.so


Next Previous Contents