The Linux-PAM System Administrators' Guide

Andrew G. Morgan

<morgan@kernel.org>

Thorsten Kukuk

<kukuk@thkukuk.de>

Version 0.99.6.0, 5. August 2006

Abstract

This manual documents what a system-administrator needs to know about the
Linux-PAM library. It covers the correct syntax of the PAM configuration file
and discusses strategies for maintaining a secure system.

-------------------------------------------------------------------------------

1. Introduction
2. Some comments on the text
3. Overview
4. The Linux-PAM configuration file

    4.1. Configuration file syntax
    4.2. Directory based configuration
    4.3. Example configuration file entries

5. Security issues

    5.1. If something goes wrong
    5.2. Avoid having a weak `other' configuration

6. A reference guide for available modules

    6.1. pam_access - logdaemon style login access control
    6.2. pam_cracklib - checks the password against dictionary words
    6.3. pam_debug - debug the PAM stack
    6.4. pam_deny - locking-out PAM module
    6.5. pam_echo - print text messages
    6.6. pam_env - set/unset environment variables
    6.7. pam_exec - call an external command
    6.8. pam_filter - filter module
    6.9. pam_ftp - module for anonymous access
    6.10. pam_group - module to modify group access
    6.11. pam_issue - add issue file to user prompt
    6.12. pam_keyinit - display the keyinit file
    6.13. pam_lastlog - display date of last login
    6.14. pam_limits - limit resources
    6.15. pam_listfile - deny or allow services based on an arbitrary file
    6.16. pam_localuser - require users to be listed in /etc/passwd
    6.17. pam_mail - inform about available mail
    6.18. pam_mkhomedir - create users home directory
    6.19. pam_motd - display the motd file
    6.20. pam_namespace - setup a private namespace
    6.21. pam_nologin - prevent non-root users from login
    6.22. pam_permit - the promiscuous module
    6.23. pam_rhosts - grant access using .rhosts file
    6.24. pam_rootok - gain only root access
    6.25. pam_securetty - limit root login to special devices
    6.26. pam_selinux - set the default security context
    6.27. pam_shells - check for valid login shell
    6.28. pam_succeed_if - test account characteristics
    6.29. pam_tally - login counter (tallying) module
    6.30. pam_time - time controled access
    6.31. pam_umask - set the file mode creation mask
    6.32. pam_userdb - authenticate against a db database
    6.33. pam_warn - logs all PAM items
    6.34. pam_wheel - only permit root access to members of group wheel
    6.35. pam_xauth - forward xauth keys between users

7. See also
8. Author/acknowledgments
9. Copyright information for this document

Chapter 1. Introduction

Linux-PAM (Pluggable Authentication Modules for Linux) is a suite of shared
libraries that enable the local system administrator to choose how applications
authenticate users.

In other words, without (rewriting and) recompiling a PAM-aware application, it
is possible to switch between the authentication mechanism(s) it uses. Indeed,
one may entirely upgrade the local authentication system without touching the
applications themselves.

Historically an application that has required a given user to be authenticated,
has had to be compiled to use a specific authentication mechanism. For example,
in the case of traditional UN*X systems, the identity of the user is verified
by the user entering a correct password. This password, after being prefixed by
a two character ``salt'', is encrypted (with crypt(3)). The user is then
authenticated if this encrypted password is identical to the second field of
the user's entry in the system password database (the /etc/passwd file). On
such systems, most if not all forms of privileges are granted based on this
single authentication scheme. Privilege comes in the form of a personal
user-identifier (UID) and membership of various groups. Services and
applications are available based on the personal and group identity of the
user. Traditionally, group membership has been assigned based on entries in the
/etc/group file.

It is the purpose of the Linux-PAM project to separate the development of
privilege granting software from the development of secure and appropriate
authentication schemes. This is accomplished by providing a library of
functions that an application may use to request that a user be authenticated.
This PAM library is configured locally with a system file, /etc/pam.conf (or a
series of configuration files located in /etc/pam.d/) to authenticate a user
request via the locally available authentication modules. The modules
themselves will usually be located in the directory /lib/security or /lib64/
security and take the form of dynamically loadable object files (see dlopen
(3)).

Chapter 2. Some comments on the text

Before proceeding to read the rest of this document, it should be noted that
the text assumes that certain files are placed in certain directories. Where
they have been specified, the conventions we adopt here for locating these
files are those of the relevant RFC (RFC-86.0, see bibliography"). If you are
using a distribution of Linux (or some other operating system) that supports
PAM but chooses to distribute these files in a diferent way you should be
careful when copying examples directly from the text.

As an example of the above, where it is explicit, the text assumes that PAM
loadable object files (the modules) are to be located in the following
directory: /lib/security/ or /lib64/security depending on the architecture.
This is generally the location that seems to be compatible with the Filesystem
Hierarchy Standard (FHS). On Solaris, which has its own licensed version of
PAM, and some other implementations of UN*X, these files can be found in /usr/
lib/security. Please be careful to perform the necessary transcription when
using the examples from the text.

Chapter 3. Overview

For the uninitiated, we begin by considering an example. We take an application
that grants some service to users; login is one such program. Login does two
things, it first establishes that the requesting user is whom they claim to be
and second provides them with the requested service: in the case of login the
service is a command shell (bash, tcsh, zsh, etc.) running with the identity of
the user.

Traditionally, the former step is achieved by the login application prompting
the user for a password and then verifying that it agrees with that located on
the system; hence verifying that as far as the system is concerned the user is
who they claim to be. This is the task that is delegated to Linux-PAM.

From the perspective of the application programmer (in this case the person
that wrote the login application), Linux-PAM takes care of this authentication
task -- verifying the identity of the user.

The flexibility of Linux-PAM is that you, the system administrator, have the
freedom to stipulate which authentication scheme is to be used. You have the
freedom to set the scheme for any/all PAM-aware applications on your Linux
system. That is, you can authenticate from anything as naive as simple trust (
pam_permit) to something as paranoid as a combination of a retinal scan, a
voice print and a one-time password!

To illustrate the flexibility you face, consider the following situation: a
system administrator (parent) wishes to improve the mathematical ability of her
users (children). She can configure their favorite ``Shoot 'em up game''
(PAM-aware of course) to authenticate them with a request for the product of a
couple of random numbers less than 12. It is clear that if the game is any good
they will soon learn their multiplication tables. As they mature, the
authentication can be upgraded to include (long) division!

Linux-PAM deals with four separate types of (management) task. These are:
authentication management; account management; session management; and password
management. The association of the preferred management scheme with the
behavior of an application is made with entries in the relevant Linux-PAM
configuration file. The management functions are performed by modules specified
in the configuration file. The syntax for this file is discussed in the section
below.

Here is a figure that describes the overall organization of Linux-PAM:

  +----------------+
  | application: X |
  +----------------+       /  +----------+     +================+
  | authentication-[---->--\--] Linux-   |--<--| PAM config file|
  |       +        [----<--/--]   PAM    |     |================|
  |[conversation()][--+    \  |          |     | X auth .. a.so |
  +----------------+  |    /  +-n--n-----+     | X auth .. b.so |
  |                |  |       __|  |           |           _____/
  |  service user  |  A      |     |           |____,-----'
  |                |  |      V     A
  +----------------+  +------|-----|---------+ -----+------+
                         +---u-----u----+    |      |      |
                         |   auth....   |--[ a ]--[ b ]--[ c ]
                         +--------------+
                         |   acct....   |--[ b ]--[ d ]
                         +--------------+
                         |   password   |--[ b ]--[ c ]
                         +--------------+
                         |   session    |--[ e ]--[ c ]
                         +--------------+


By way of explanation, the left of the figure represents the application;
application X. Such an application interfaces with the Linux-PAM library and
knows none of the specifics of its configured authentication method. The
Linux-PAM library (in the center) consults the contents of the PAM
configuration file and loads the modules that are appropriate for
application-X. These modules fall into one of four management groups
(lower-center) and are stacked in the order they appear in the configuration
file. These modules, when called by Linux-PAM, perform the various
authentication tasks for the application. Textual information, required from/or
offered to the user, can be exchanged through the use of the
application-supplied conversation function.

If a program is going to use PAM, then it has to have PAM functions explicitly
coded into the program. If you have access to the source code you can add the
appropriate PAM functions. If you do not have accessto the source code, and the
binary does not have the PAM functions included, then it is not possible to use
PAM.

Chapter 4. The Linux-PAM configuration file

When a PAM aware privilege granting application is started, it activates its
attachment to the PAM-API. This activation performs a number of tasks, the most
important being the reading of the configuration file(s): /etc/pam.conf.
Alternatively, this may be the contents of the /etc/pam.d/ directory. The
presence of this directory will cause Linux-PAM to ignore /etc/pam.conf.

These files list the PAMs that will do the authentication tasks required by
this service, and the appropriate behavior of the PAM-API in the event that
individual PAMs fail.

4.1. Configuration file syntax

The syntax of the /etc/pam.conf configuration file is as follows. The file is
made up of a list of rules, each rule is typically placed on a single line, but
may be extended with an escaped end of line: `\<LF>'. Comments are preceded
with `#' marks and extend to the next end of line.

The format of each rule is a space separated collection of tokens, the first
three being case-insensitive:

service type control module-path module-arguments

The syntax of files contained in the /etc/pam.d/ directory, are identical
except for the absence of any service field. In this case, the service is the
name of the file in the /etc/pam.d/ directory. This filename must be in lower
case.

An important feature of PAM, is that a number of rules may be stacked to
combine the services of a number of PAMs for a given authentication task.

The service is typically the familiar name of the corresponding application:
login and su are good examples. The service-name, other, is reserved for giving
default rules. Only lines that mention the current service (or in the absence
of such, the other entries) will be associated with the given
service-application.

The type is the management group that the rule corresponds to. It is used to
specify which of the management groups the subsequent module is to be
associated with. Valid entries are:

account

    this module type performs non-authentication based account management. It
    is typically used to restrict/permit access to a service based on the time
    of day, currently available system resources (maximum number of users) or
    perhaps the location of the applicant user -- 'root' login only on the
    console.

auth

    this module type provides two aspects of authenticating the user. Firstly,
    it establishes that the user is who they claim to be, by instructing the
    application to prompt the user for a password or other means of
    identification. Secondly, the module can grant group membership or other
    privileges through its credential granting properties.

password

    this module type is required for updating the authentication token
    associated with the user. Typically, there is one module for each
    'challenge/response' based authentication (auth) type.

session

    this module type is associated with doing things that need to be done for
    the user before/after they can be given service. Such things include the
    logging of information concerning the opening/closing of some data exchange
    with a user, mounting directories, etc.

The third field, control, indicates the behavior of the PAM-API should the
module fail to succeed in its authentication task. There are two types of
syntax for this control field: the simple one has a single simple keyword; the
more complicated one involves a square-bracketed selection of value=action
pairs.

For the simple (historical) syntax valid control values are:

required

    failure of such a PAM will ultimately lead to the PAM-API returning failure
    but only after the remaining stacked modules (for this service and type)
    have been invoked.

requisite

    like required, however, in the case that such a module returns a failure,
    control is directly returned to the application. The return value is that
    associated with the first required or requisite module to fail. Note, this
    flag can be used to protect against the possibility of a user getting the
    opportunity to enter a password over an unsafe medium. It is conceivable
    that such behavior might inform an attacker of valid accounts on a system.
    This possibility should be weighed against the not insignificant concerns
    of exposing a sensitive password in a hostile environment.

sufficient

    success of such a module is enough to satisfy the authentication
    requirements of the stack of modules (if a prior required module has failed
    the success of this one is ignored). A failure of this module is not deemed
    as fatal to satisfying the application that this type has succeeded.

optional

    the success or failure of this module is only important if it is the only
    module in the stack associated with this service+type.

include

    include all lines of given type from the configuration file specified as an
    argument to this control.

For the more complicated syntax valid control values have the following form:

      [value1=action1 value2=action2 ...]


Where valueN corresponds to the return code from the function invoked in the
module for which the line is defined. It is selected from one of these: 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 and default.

The last of these, default, implies 'all valueN's not mentioned explicitly.
Note, the full list of PAM errors is available in /usr/include/security/
_pam_types.h. The actionN can be: an unsigned integer, n, signifying an action
of 'jump over the next n modules in the stack', or take one of the following
forms:

ignore

    when used with a stack of modules, the module's return status will not
    contribute to the return code the application obtains.

bad

    this action indicates that the return code should be thought of as
    indicative of the module failing. If this module is the first in the stack
    to fail, its status value will be used for that of the whole stack.

die

    equivalent to bad with the side effect of terminating the module stack and
    PAM immediately returning to the application.

ok

    this tells PAM that the administrator thinks this return code should
    contribute directly to the return code of the full stack of modules. In
    other words, if the former state of the stack would lead to a return of
    PAM_SUCCESS, the module's return code will override this value. Note, if
    the former state of the stack holds some value that is indicative of a
    modules failure, this 'ok' value will not be used to override that value.

done

    equivalent to ok with the side effect of terminating the module stack and
    PAM immediately returning to the application.

reset

    clear all memory of the state of the module stack and start again with the
    next stacked module.

Each of the four keywords: required; requisite; sufficient; and optional, have
an equivalent expression in terms of the [...] syntax. They are as follows:

required

    [success=ok new_authtok_reqd=ok ignore=ignore default=bad]

requisite

    [success=ok new_authtok_reqd=ok ignore=ignore default=die]

sufficient

    [success=done new_authtok_reqd=done default=ignore]

optional

    [success=ok new_authtok_reqd=ok default=ignore]

module-path is either the full filename of the PAM to be used by the
application (it begins with a '/'), or a relative pathname from the default
module location: /lib/security/ or /lib64/security/, depending on the
architecture.

module-arguments are a space separated list of tokens that can be used to
modify the specific behavior of the given PAM. Such arguments will be
documented for each individual module. Note, if you wish to include spaces in
an argument, you should surround that argument with square brackets.

    squid auth required pam_mysql.so user=passwd_query passwd=mada \
          db=eminence [query=select user_name from internet_service \
          where user_name='%u' and password=PASSWORD('%p') and \
        service='web_proxy']


When using this convention, you can include `[' characters inside the string,
and if you wish to include a `]' character inside the string that will survive
the argument parsing, you should use `\['. In other words:

    [..[..\]..]    -->   ..[..]..


Any line in (one of) the configuration file(s), that is not formatted
correctly, will generally tend (erring on the side of caution) to make the
authentication process fail. A corresponding error is written to the system log
files with a call to syslog(3).

4.2. Directory based configuration

More flexible than the single configuration file is it to configure libpam via
the contents of the /etc/pam.d/ directory. In this case the directory is filled
with files each of which has a filename equal to a service-name (in
lower-case): it is the personal configuration file for the named service.

The syntax of each file in /etc/pam.d/ is similar to that of the /etc/pam.conf
file and is made up of lines of the following form:

type  control  module-path  module-arguments


The only difference being that the service-name is not present. The
service-name is of course the name of the given configuration file. For
example, /etc/pam.d/login contains the configuration for the login service.

4.3. Example configuration file entries

In this section, we give some examples of entries that can be present in the
Linux-PAM configuration file. As a first attempt at configuring your system you
could do worse than to implement these.

If a system is to be considered secure, it had better have a reasonably secure
'other entry. The following is a paranoid setting (which is not a bad place to
start!):

#
# default; deny access
#
other   auth     required       pam_deny.so
other   account  required       pam_deny.so
other   password required       pam_deny.so
other   session  required       pam_deny.so


Whilst fundamentally a secure default, this is not very sympathetic to a
misconfigured system. For example, such a system is vulnerable to locking
everyone out should the rest of the file become badly written.

The module pam_deny (documented in a later section) is not very sophisticated.
For example, it logs no information when it is invoked so unless the users of a
system contact the administrator when failing to execute a service application,
the administrator may go for a long while in ignorance of the fact that his
system is misconfigured.

The addition of the following line before those in the above example would
provide a suitable warning to the administrator.

#
# default; wake up! This application is not configured
#
other   auth     required       pam_warn.so
other   password required       pam_warn.so


Having two 'other auth' lines is an example of stacking.

On a system that uses the /etc/pam.d/ configuration, the corresponding default
setup would be achieved with the following file:

#
# default configuration: /etc/pam.d/other
#
auth     required       pam_warn.so
auth     required       pam_deny.so
account  required       pam_deny.so
password required       pam_warn.so
password required       pam_deny.so
session  required       pam_deny.so


This is the only explicit example we give for an /etc/pam.d/ file. In general,
it should be clear how to transpose the remaining examples to this
configuration scheme.

On a less sensitive computer, one on which the system administrator wishes to
remain ignorant of much of the power of Linux-PAM, the following selection of
lines (in /etc/pam.d/other) is likely to mimic the historically familiar Linux
setup.

#
# default; standard UN*X access
#
auth     required       pam_unix.so
account  required       pam_unix.so
password required       pam_unix.so
session  required       pam_unix.so


In general this will provide a starting place for most applications.

Chapter 5. Security issues

5.1. If something goes wrong

Linux-PAM has the potential to seriously change the security of your system.
You can choose to have no security or absolute security (no access permitted).
In general, Linux-PAM errs towards the latter. Any number of configuration
errors can dissable access to your system partially, or completely.

The most dramatic problem that is likely to be encountered when configuring
Linux-PAM is that of deleting the configuration file(s): /etc/pam.d/* and/or /
etc/pam.conf. This will lock you out of your own system!

To recover, your best bet is to restore the system from a backup or boot the
system into a rescue system and correct things from there.

5.2. Avoid having a weak `other' configuration

It is not a good thing to have a weak default (other) entry. This service is
the default configuration for all PAM aware applications and if it is weak,
your system is likely to be vulnerable to attack.

Here is a sample "other" configuration file. The pam_deny module will deny
access and the pam_warn module will send a syslog message to auth.notice:

#
# The PAM configuration file for the `other' service
#
auth      required   pam_deny.so
auth      required   pam_warn.so
account   required   pam_deny.so
account   required   pam_warn.so
password  required   pam_deny.so
password  required   pam_warn.so
session   required   pam_deny.so
session   required   pam_warn.so


Chapter 6. A reference guide for available modules

Here, we collect together the descriptions of the various modules coming with
Linux-PAM.

6.1. pam_access - logdaemon style login access control

pam_access.so [ debug ] [ accessfile=file ] [ fieldsep=sep ] [ listsep=sep ]

6.1.1. DESCRIPTION

The pam_access PAM module is mainly for access management. It provides
logdaemon style login access control based on login names, host or domain
names, internet addresses or network numbers, or on terminal line names in case
of non-networked logins.

By default rules for access management are taken from config file /etc/security
/access.conf if you don't specify another file.

6.1.2. DESCRIPTION

The /etc/security/access.conf file specifies (user, host), (user, network/
netmask) or (user, tty) combinations for which a login will be either accepted
or refused.

When someone logs in, the file access.conf is scanned for the first entry that
matches the (user, host) or (user, network/netmask) combination, or, in case of
non-networked logins, the first entry that matches the (user, tty) combination.
The permissions field of that table entry determines whether the login will be
accepted or refused.

Each line of the login access control table has three fields separated by a ":"
character (colon):

permission:users:origins

The first field, the permission field, can be either a "+" character (plus) for
access granted or a "-" character (minus) for access denied.

The second field, the users field, should be a list of one or more login names,
group names, or ALL (which always matches).

The third field, the origins field, should be a list of one or more tty names
(for non-networked logins), host names, domain names (begin with "."), host
addresses, internet network numbers (end with "."), internet network addresses
with network mask (where network mask can be a decimal number or an internet
address also), ALL (which always matches) or LOCAL (which matches any string
that does not contain a "." character). If supported by the system you can use
@netgroupname in host or user patterns.

The except operator makes it possible to write very compact rules.

The group file is searched only when a name does not match that of the
logged-in user. Only groups are matched in which users are explicitly listed.
However the PAM module does not look at the primary group id of a user.

The "#" character at start of line (no space at front) can be used to mark this
line as a comment line.

6.1.3. OPTIONS

accessfile=/path/to/access.conf

    Indicate an alternative access.conf style configuration file to override
    the default. This can be useful when different services need different
    access lists.

debug

    A lot of debug informations are printed with syslog(3).

fieldsep=separators

    This option modifies the field separator character that pam_access will
    recognize when parsing the access configuration file. For example: fieldsep
    =| will cause the default `:' character to be treated as part of a field
    value and `|' becomes the field separator. Doing this may be useful in
    conjuction with a system that wants to use pam_access with X based
    applications, since the PAM_TTY item is likely to be of the form
    "hostname:0" which includes a `:' character in its value. But you should
    not need this.

listsep=separators

    This option modifies the list separator character that pam_access will
    recognize when parsing the access configuration file. For example: listsep
    =, will cause the default ` ' (space) and `\t' (tab) characters to be
    treated as part of a list element value and `,' becomes the only list
    element separator. Doing this may be useful on a system with group
    information obtained from a Windows domain, where the default built-in
    groups "Domain Users", "Domain Admins" contain a space.

6.1.4. MODULE SERVICES PROVIDED

All services are supported.

6.1.5. RETURN VALUES

PAM_SUCCESS

    Access was granted.

PAM_PERM_DENIED

    Access was not granted.

PAM_IGNORE

    pam_setcred was called which does nothing.

PAM_ABORT

    Not all relevant data or options could be gotten.

PAM_USER_UNKNOWN

    The user is not known to the system.

6.1.6. FILES

/etc/security/access.conf

    Default configuration file

6.1.7. EXAMPLES

These are some example lines which might be specified in /etc/security/
access.conf.

User root should be allowed to get access via cron, X11 terminal :0, tty1, ...,
tty5, tty6.

+ : root : crond :0 tty1 tty2 tty3 tty4 tty5 tty6

User root should be allowed to get access from hosts which own the IPv4
addresses. This does not mean that the connection have to be a IPv4 one, a IPv6
connection from a host with one of this IPv4 addresses does work, too.

+ : root : 192.168.200.1 192.168.200.4 192.168.200.9

+ : root : 127.0.0.1

User root should get access from network 192.168.201. where the term will be
evaluated by string matching. But it might be better to use network/netmask
instead. The same meaning of 192.168.201. is 192.168.201.0/24 or 192.168.201.0/
255.255.255.0.

+ : root : 192.168.201.

User root should be able to have access from hosts foo1.bar.org and
foo2.bar.org (uses string matching also).

+ : root : foo1.bar.org foo2.bar.org

User root should be able to have access from domain foo.bar.org (uses string
matching also).

+ : root : .foo.bar.org

User root should be denied to get access from all other sources.

- : root : ALL

User foo and members of netgroup admins should be allowed to get access from
all sources. This will only work if netgroup service is available.

+ : @admins foo : ALL

User john and foo should get access from IPv6 host address.

+ : john foo : 2001:4ca0:0:101::1

User john should get access from IPv6 net/mask.

+ : john : 2001:4ca0:0:101::/64

All other users should be denied to get access from all sources.

- : ALL : ALL

6.1.8. AUTHORS

The logdaemon style login access control scheme was designed and implemented by
Wietse Venema. The pam_access PAM module was developed by Alexei Nogin
<alexei@nogin.dnttm.ru>. The IPv6 support and the network(address) / netmask
feature was developed and provided by Mike Becher
<mike.becher@lrz-muenchen.de>.

6.2. pam_cracklib - checks the password against dictionary words

pam_cracklib.so [ ... ]

6.2.1. DESCRIPTION

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

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 first 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 strength checks works in the following manner: at first the Cracklib
routine is called to check if the password is part of a dictionary; if this is
not the case an additional set of strength checks is done. These checks are:

Palindrome

    Is the new password a palindrome of the old one?

Case Change Only

    Is the new password the the old one with only a change of case?

Similar

    Is the new password too much like the old one? This is primarily controlled
    by one argument, difok which is a number of characters that if different
    between the old and new are enough to accept the new password, this
    defaults to 10 or 1/2 the size of the new password whichever is smaller.

    To avoid the lockup associated with trying to change a long and complicated
    password, difignore is available. This argument can be used to specify the
    minimum length a new password needs to be before the difok value is
    ignored. The default value for difignore is 23.

Simple

    Is the new password too small? This is controlled by 5 arguments minlen,
    dcredit, ucredit, lcredit, and ocredit. See the section on the arguments
    for the details of how these work and there defaults.

Rotated

    Is the new password a rotated version of the old password?

Already used

    Was the password used in the past? Previously used passwords are to be
    found in /etc/security/opasswd.

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.

6.2.2. OPTIONS

debug

    This option makes the module write information to syslog(3) indicating the
    behavior of the module (this option does not write password information to
    the log file).

type=XXX

    The default action is for the module to use the following prompts when
    requesting passwords: "New UNIX password: " and "Retype UNIX password: ".
    The default word UNIX can be replaced with this option.

retry=N

    Prompt user at most N times before returning with error. The default is 1

difok=N

    This argument will change the default of 5 for the number of characters in
    the new password that must not be present in the old password. In addition,
    if 1/2 of the characters in the new password are different then the new
    password will be accepted anyway.

difignore=N

    How many characters should the password have before difok will be ignored.
    The default is 23.

minlen=N

    The minimum acceptable size for the new password (plus one if credits are
    not disabled which is the default). In addition to the number of characters
    in the new password, credit (of +1 in length) is given for each different
    kind of character (other, upper, lower and digit). The default for this
    parameter is 9 which is good for a old style UNIX password all of the same
    type of character but may be too low to exploit the added security of a md5
    system. Note that there is a pair of length limits in Cracklib itself, a
    "way too short" limit of 4 which is hard coded in and a defined limit (6)
    that will be checked without reference to minlen. If you want to allow
    passwords as short as 5 characters you should not use this module.

dcredit=N

    (N >= 0) This is the maximum credit for having digits in the new password.
    If you have less than or N digits, each digit will count +1 towards meeting
    the current minlen value. The default for dcredit is 1 which is the
    recommended value for minlen less than 10.

    (N < 0) This is the minimum number of digits that must be met for a new
    password.

ucredit=N

    (N >= 0) This is the maximum credit for having upper case letters in the
    new password. If you have less than or N upper case letters each letter
    will count +1 towards meeting the current minlen value. The default for
    ucredit is 1 which is the recommended value for minlen less than 10.

    (N > 0) This is the minimum number of upper case letters that must be met
    for a new password.

lcredit=N

    (N >= 0) This is the maximum credit for having lower case letters in the
    new password. If you have less than or N lower case letters, each letter
    will count +1 towards meeting the current minlen value. The default for
    lcredit is 1 which is the recommended value for minlen less than 10.

    (N < 0) This is the minimum number of lower case letters that must be met
    for a new password.

ocredit=N

    (N >= 0) This is the maximum credit for having other characters in the new
    password. If you have less than or N other characters, each character will
    count +1 towards meeting the current minlen value. The default for ocredit
    is 1 which is the recommended value for minlen less than 10.

    (N < 0) This is the minimum number of other characters that must be met for
    a new password.

use_authtok

    This argument is used to force the module to not prompt the user for a new
    password but use the one provided by the previously stacked password
    module.

dictpath=/path/to/dict

    Path to the cracklib dictionaries.

6.2.3. MODULE SERVICES PROVIDED

Only he password service is supported.

6.2.4. RETURN VALUES

PAM_SUCCESS

    The new password passes all checks.

PAM_AUTHTOK_ERR

    No new password was entered, the username could not be determined or the
    new password fails the strength checks.

PAM_AUTHTOK_RECOVERY_ERR

    The old password was not supplied by a previous stackked module or got not
    requested from the user. The first error can happen if use_authtok is
    specified.

PAM_SERVICE_ERR

    A internal error occured.

6.2.5. EXAMPLES

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

#
# 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_unix.so use_authtok nullok md5


6.2.6. AUTHOR

pam_cracklib was written by Cristian Gafton <gafton@redhat.com>

6.3. pam_debug - debug the PAM stack

pam_debug.so [ auth=value ] [ cred=value ] [ acct=value ] [ prechauthtok=value
] [ chauthtok=value ] [ auth=value ] [ open_session=value ] [ close_session=
value ]

6.3.1. DESCRIPTION

The pam_debug PAM module is intended as a debugging aide for determining how
the PAM stack is operating. This module returns what its module arguments tell
it to return.

6.3.2. OPTIONS

auth=value

    The pam_sm_authenticate(3) function will return value.

cred=value

    The pam_sm_setcred(3) function will return value.

acct=value

    The pam_sm_acct_mgmt(3) function will return value.

prechauthtok=value

    The pam_sm_chauthtok(3) function will return value if the PAM_PRELIM_CHECK
    flag is set.

chauthtok=value

    The pam_sm_chauthtok(3) function will return value if the PAM_PRELIM_CHECK
    flag is not set.

open_session=value

    The pam_sm_open_session(3) function will return value.

close_session=value

    The pam_sm_close_session(3) function will return value.

Where value can be one of: 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.

6.3.3. MODULE SERVICES PROVIDED

The services auth, account, password and session are supported.

6.3.4. RETURN VALUES

PAM_SUCCESS

    Default return code if no other value was specified, else specified return
    value.

6.3.5. EXAMPLES

auth    requisite       pam_permit.so
auth    [success=2 default=ok]  pam_debug.so auth=perm_denied cred=success
auth    [default=reset]         pam_debug.so auth=success cred=perm_denied
auth    [success=done default=die] pam_debug.so
auth    optional        pam_debug.so auth=perm_denied cred=perm_denied
auth    sufficient      pam_debug.so auth=success cred=success


6.3.6. AUTHOR

pam_debug was written by Andrew G. Morgan <morgan@kernel.org>.

6.4. pam_deny - locking-out PAM module

pam_deny.so

6.4.1. DESCRIPTION

This module can be used to deny access. It always indicates a failure to the
application through the PAM framework. It might be suitable for using for
default (the OTHER) entries.

6.4.2. OPTIONS

This module does not recognice any options.

6.4.3. MODULE SERVICES PROVIDED

All services (account, auth, password and session) are supported.

6.4.4. RETURN VALUES

PAM_AUTH_ERR

    This is returned by the account and auth services.

PAM_CRED_ERR

    This is returned by the setcred function.

PAM_AUTHTOK_ERR

    This is returned by the password service.

PAM_SESSION_ERR

    This is returned by the session service.

6.4.5. EXAMPLES

#%PAM-1.0
#
# If we don't have config entries for a service, the
# OTHER entries are used. To be secure, warn and deny
# access to everything.
other auth     required       pam_warn.so
other auth     required       pam_deny.so
other account  required       pam_warn.so
other account  required       pam_deny.so
other password required       pam_warn.so
other password required       pam_deny.so
other session  required       pam_warn.so
other session  required       pam_deny.so


6.4.6. AUTHOR

pam_deny was written by Andrew G. Morgan <morgan@kernel.org>

6.5. pam_echo - print text messages

pam_echo.so [ file=/path/message ]

6.5.1. DESCRIPTION

The pam_echo PAM module is for printing text messages to inform user about
special things. Sequences starting with the % character are interpreted in the
following way:

%H

    The name of the remote host (PAM_RHOST).

%h

    The name of the local host.

%s

    The service name (PAM_SERVICE).

%t

    The name of the controlling terminal (PAM_TTY).

%U

    The remote user name (PAM_RUSER).

%u

    The local user name (PAM_USER).

All other sequences beginning with % expands to the characters following the %
character.

6.5.2. OPTIONS

file=/path/message

    The content of the file /path/message will be printed with the PAM
    conversion function as PAM_TEXT_INFO.

6.5.3. MODULE SERVICES PROVIDED

All services are supported.

6.5.4. RETURN VALUES

PAM_BUF_ERR

    Memory buffer error.

PAM_SUCCESS

    Message was successful printed.

PAM_IGNORE

    PAM_SILENT flag was given or message file does not exist, no message
    printed.

6.5.5. EXAMPLES

For an example of the use of this module, we show how it may be used to print
informations about good passwords:

password optional pam_echo.so file=/usr/share/doc/good-password.txt
password required pam_unix.so


6.5.6. AUTHOR

Thorsten Kukuk <kukuk@thkukuk.de>

6.6. pam_env - set/unset environment variables

pam_env.so [ debug ] [ conffile=conf-file ] [ envfile=env-file ] [ readenv=0|1
]

6.6.1. DESCRIPTION

The pam_env PAM 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.

By default rules for (un)setting of variables is taken from the config file /
etc/security/pam_env.conf if no other file is specified.

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.

6.6.2. DESCRIPTION

The /etc/security/pam_env.conf file specifies the environment variables to be
set, unset or modified by pam_env(8). When someone logs in, this file is read
and the environment variables are set according.

Each line starts with the variable name, there are then two possible options
for each variable DEFAULT and OVERRIDE. DEFAULT allows and 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 values can be delimited with "", escaped "
not supported. Note that many environment variables that you would like to use
may not be set by the time the module is called. For example, HOME is used
below several times, but many PAM applications don't make it available by the
time you need it.

The "#" character at start of line (no space at front) can be used to mark this
line as a comment line.

6.6.3. OPTIONS

conffile=/path/to/pam_env.conf

    Indicate an alternative pam_env.conf style configuration file to override
    the default. This can be useful when different services need different
    environments.

debug

    A lot of debug informations are printed with syslog(3).

envfile=/path/to/environment

    Indicate an alternative environment file to override the default. This can
    be useful when different services need different environments.

readenv=0|1

    Turns on or off the reading of the file specified by envfile (0 is off, 1
    is on). By default this option is on.

6.6.4. MODULE SERVICES PROVIDED

The auth and session services are supported.

6.6.5. RETURN VALUES

PAM_ABORT

    Not all relevant data or options could be gotten.

PAM_BUF_ERR

    Memory buffer error.

PAM_IGNORE

    No pam_env.conf and environment file was found.

PAM_SUCCESS

    Environment variables were set.

6.6.6. FILES

/etc/security/pam_env.conf

    Default configuration file

/etc/environment

    Default environment file

6.6.7. EXAMPLES

These are some example lines which might be specified in /etc/security/
pam_env.conf.

Set the REMOTEHOST variable for any hosts that are remote, default to
"localhost" rather than not being set at all

      REMOTEHOST     DEFAULT=localhost OVERRIDE=@{PAM_RHOST}


Set the DISPLAY variable if it seems reasonable

      DISPLAY        DEFAULT=${REMOTEHOST}:0.0 OVERRIDE=${DISPLAY}


Now some simple variables

      PAGER          DEFAULT=less
      MANPAGER       DEFAULT=less
      LESS           DEFAULT="M q e h15 z23 b80"
      NNTPSERVER     DEFAULT=localhost
      PATH           DEFAULT=${HOME}/bin:/usr/local/bin:/bin\
      :/usr/bin:/usr/local/bin/X11:/usr/bin/X11


Silly examples of escaped variables, just to show how they work.

      DOLLAR         DEFAULT=\$
      DOLLARDOLLAR   DEFAULT=        OVERRIDE=\$${DOLLAR}
      DOLLARPLUS     DEFAULT=\${REMOTEHOST}${REMOTEHOST}
      ATSIGN         DEFAULT=""      OVERRIDE=\@


6.6.8. AUTHOR

pam_env was written by Dave Kinchlea <kinch@kinch.ark.com>.

6.7. pam_exec - call an external command

pam_exec.so [ debug ] [ seteuid ] [ log=file ] command [ ... ]

6.7.1. DESCRIPTION

pam_exec is a PAM module that can be used to run an external command.

6.7.2. OPTIONS

debug

    Print debug information.

log=file

    The output of the command is appended to file

seteuid

    Per default pam_exec.so will execute the external command with the real
    user ID of the calling process. Specifying this option means the command is
    run with the effective user ID.

6.7.3. MODULE SERVICES PROVIDED

The services auth, account, password and session are supported.

6.7.4. RETURN VALUES

PAM_SUCCESS

    The external command runs successfull.

PAM_SERVICE_ERR

    No argument or a wrong number of arguments were given.

PAM_SYSTEM_ERR

    A system error occured or the command to execute failed.

PAM_IGNORE

    pam_setcred was called, which does not execute the command.

6.7.5. EXAMPLES

Add the following line to /etc/pam.d/passwd to rebuild the NIS database after
each local password change:

        passwd optional pam_exec.so seteuid make -C /var/yp


This will execute the command

make -C /var/yp

with effective user ID.

6.7.6. AUTHOR

pam_exec was written by Thorsten Kukuk <kukuk@thkukuk.de>.

6.8. pam_filter - filter module

pam_filter.so [ debug ] [ new_term ] [ non_term ] run1|run2 filter [ ... ]

6.8.1. DESCRIPTION

This module is intended to be a platform for providing access to all of the
input/output that passes between the user and the application. It is only
suitable for tty-based and (stdin/stdout) applications.

To function this module requires filters to be installed on the system. 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).

Each component of the module has the potential to invoke the desired filter.
The filter is always execv(2) 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.

6.8.2. OPTIONS

debug

    Print debug information.

new_term

    The default action of the filter is to set the PAM_TTY item to indicate the
    terminal that the user is using to connect to the application. This
    argument indicates that the filter should set PAM_TTY to the filtered
    pseudo-terminal.

non_term

    don't try to set the PAM_TTY item.

runX

    In order that the module can invoke a filter it should know when to invoke
    it. This argument is required to tell the filter when to do this.

    Permitted values for X are 1 and 2. These indicate the precise time that
    the filter is to be run. To understand this concept it will be useful to
    have read the pam(3) manual page. Basically, for each management group
    there are up to two ways of calling the module's functions. In the case of
    the authentication and session components there are actually two separate
    functions. For the case of authentication, these functions are
    pam_authenticate(3) and pam_setcred(3), here run1 means run the filter from
    the pam_authenticate function and run2 means run the filter from
    pam_setcred. In the case of the session modules, run1 implies that the
    filter is invoked at the pam_open_session(3) stage, and run2 for
    pam_close_session(3).

    For the case of the account component. Either run1 or run2 may be used.

    For the case of the password component, run1 is used to indicate that the
    filter is run on the first occasion of pam_chauthtok(3) (the
    PAM_PRELIM_CHECK phase) and run2 is used to indicate that the filter is run
    on the second occasion (the PAM_UPDATE_AUTHTOK phase).

filter

    The full pathname of the filter to be run and any command line arguments
    that the filter might expect.

6.8.3. MODULE SERVICES PROVIDED

The services auth, account, password and session are supported.

6.8.4. RETURN VALUES

PAM_SUCCESS

    The new filter was set successfull.

PAM_ABORT

    Critical error, immediate abort.

6.8.5. EXAMPLES

Add the following line to /etc/pam.d/login to see how to configure login to
transpose upper and lower case letters once the user has logged in:

        session required pam_filter.so run1 /lib/security/pam_filter/upperLOWER


6.8.6. AUTHOR

pam_filter was written by Andrew G. Morgan <morgan@kernel.org>.

6.9. pam_ftp - module for anonymous access

pam_ftp.so [ debug ] [ ignore ] [ users=XXX,YYY, ...]

6.9.1. DESCRIPTION

pam_ftp is a PAM module which provides a pluggable anonymous ftp mode of
access.

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.

This module is not safe and easily spoofable.

6.9.2. OPTIONS

debug

    Print debug information.

ignore

    Pay no attention to the email address of the user (if supplied).

ftp=XXX,YYY,...

    Instead of ftp or anonymous, provide anonymous login to the comma separated
    list of users: XXX,YYY,.... Should the applicant enter one of these
    usernames the returned username is set to the first in the list: XXX.

6.9.3. MODULE SERVICES PROVIDED

Only the auth service is supported.

6.9.4. RETURN VALUES

PAM_SUCCESS

    The authentication was successfull.

PAM_USER_UNKNOWN

    User not known.

6.9.5. EXAMPLES

Add the following line to /etc/pam.d/ftpd to handle ftp style anonymous login:

#
# ftpd; add ftp-specifics. These lines enable anonymous ftp over
#       standard UN*X access (the listfile entry blocks access to
#       users listed in /etc/ftpusers)
#
auth    sufficient  pam_ftp.so
auth    required    pam_unix.so use_first_pass
auth    required    pam_listfile.so \
           onerr=succeed item=user sense=deny file=/etc/ftpusers


6.9.6. AUTHOR

pam_ftp was written by Andrew G. Morgan <morgan@kernel.org>.

6.10. pam_group - module to modify group access

pam_group.so

6.10.1. DESCRIPTION

The pam_group PAM 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.

By default rules for group memberships are taken from config file /etc/security
/group.conf.

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.10.2. DESCRIPTION

The pam_group PAM 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.

For this module to function correctly there must be a correctly formatted /etc/
security/group.conf file present. White spaces are ignored and lines maybe
extended with '\' (escaped newlines). Text following a '#' is ignored to the
end of the line.

The syntax of the lines is as follows:

services;ttys;users;times;groups

The first field, the services field, is a logic list of PAM service names that
the rule applies to.

The second field, the tty field, is a logic list of terminal names that this
rule applies to.

The third field, the users field, is a logic list of users or a netgroup of
users to whom this rule applies.

For these items the simple wildcard '*' may be used only once. With netgroups
no wildcards or logic operators are allowed.

The times field is used to indicate "when" these groups are to be given to the
user. The format here is a logic list of day/time-range entries. The days are
specified by a sequence of two character entries, MoTuSa for example is Monday
Tuesday and Saturday. Note that repeated days are unset MoMo = no day, and MoWk
= all weekdays bar Monday. The two character combinations accepted are Mo Tu We
Th Fr Sa Su Wk Wd Al, the last two being week-end days and all 7 days of the
week respectively. As a final example, AlFr means all days except Friday.

Each day/time-range can be prefixed with a '!' to indicate "anything but". The
time-range part is two 24-hour times HHMM, separated by a hyphen, indicating
the start and finish time (if the finish time is smaller than the start time it
is deemed to apply on the following day).

The groups field is a comma or space separated list of groups that the user
inherits membership of. These groups are added if the previous fields are
satisfied by the user's request.

For a rule to be active, ALL of service+ttys+users must be satisfied by the
applying process.

6.10.3. OPTIONS

This module does not recognice any options.

6.10.4. MODULE SERVICES PROVIDED

Only the auth service is supported.

6.10.5. RETURN VALUES

PAM_SUCCESS

    group membership was granted.

PAM_ABORT

    Not all relevant data could be gotten.

PAM_BUF_ERR

    Memory buffer error.

PAM_CRED_ERR

    Group membership was not granted.

PAM_IGNORE

    pam_sm_authenticate was called which does nothing.

PAM_USER_UNKNOWN

    The user is not known to the system.

6.10.6. FILES

/etc/security/group.conf

    Default configuration file

6.10.7. EXAMPLES

These are some example lines which might be specified in /etc/security/
group.conf.

Running 'xsh' on tty* (any ttyXXX device), the user 'us' is given access to the
floppy (through membership of the floppy group)

xsh;tty*&!ttyp*;us;Al0000-2400;floppy

Running 'xsh' on tty* (any ttyXXX device), the user 'sword' is given access to
games (through membership of the floppy group) after work hours.

xsh; tty* ;sword;!Wk0900-1800;games, sound
xsh; tty* ;*;Al0900-1800;floppy


6.10.8. AUTHORS

pam_group was written by Andrew G. Morgan <morgan@kernel.org>.

6.11. pam_issue - add issue file to user prompt

pam_issue.so [ noesc ] [ issue=issue-file-name ]

6.11.1. DESCRIPTION

pam_issue is a PAM module 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:

\d

    current day

\l

    name of this tty

\m

    machine architecture (uname -m)

\n

    machine's network node hostname (uname -n)

\o

    domain name of this system

\r

    release number of operating system (uname -r)

\t

    current time

\s

    operating system name (uname -s)

\u

    number of users currently logged in

\U

    same as \u except it is suffixed with "user" or "users" (eg. "1 user" or
    "10 users")

\v

    operating system version and build date (uname -v)

6.11.2. OPTIONS

noesc

    Turns off escape code parsing.

issue=issue-file-name

    The file to output if not using the default.

6.11.3. MODULE SERVICES PROVIDED

Only the auth service is supported.

6.11.4. RETURN VALUES

PAM_BUF_ERR

    Memory buffer error.

PAM_IGNORE

    The prompt was already changed.

PAM_SERVICE_ERR

    A service module error occured.

PAM_SUCCESS

    The new prompt was set successfull.

6.11.5. EXAMPLES

Add the following line to /etc/pam.d/login to set the user specific issue at
login:

        auth optional pam_issue.so issue=/etc/issue


6.11.6. AUTHOR

pam_issue was written by Ben Collins <bcollins@debian.org>.

6.12. pam_keyinit - display the keyinit file

pam_keyinit.so [ debug ] [ force ] [ revoke ]

6.12.1. DESCRIPTION

The pam_keyinit PAM module ensures that the invoking process has a session
keyring other than the user default session keyring.

The session component of the module checks to see if the process's session
keyring is the user default, and, if it is, creates a new anonymous session
keyring with which to replace it.

If a new session keyring is created, it will install a link to the user common
keyring in the session keyring so that keys common to the user will be
automatically accessible through it.

The session keyring of the invoking process will thenceforth be inherited by
all its children unless they override it.

This module is intended primarily for use by login processes. Be aware that
after the session keyring has been replaced, the old session keyring and the
keys it contains will no longer be accessible.

This module should not, generally, be invoked by programs like su, since it is
usually desirable for the key set to percolate through to the alternate
context. The keys have their own permissions system to manage this.

This module should be included as early as possible in a PAM configuration, so
that other PAM modules can attach tokens to the keyring.

The keyutils package is used to manipulate keys more directly. This can be
obtained from:

Keyutils

6.12.2. OPTIONS

debug

    Log debug information with syslog(3).

force

    Causes the session keyring of the invoking process to be replaced
    unconditionally.

revoke

    Causes the session keyring of the invoking process to be revoked when the
    invoking process exits if the session keyring was created for this process
    in the first place.

6.12.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.12.4. RETURN VALUES

PAM_SUCCESS

    This module will usually return this value

PAM_AUTH_ERR

    Authentication failure.

PAM_BUF_ERR

    Memory buffer error.

PAM_IGNORE

    The return value should be ignored by PAM dispatch.

PAM_SERVICE_ERR

    Cannot determine the user name.

PAM_SESSION_ERR

    This module will return this value if its arguments are invalid or if a
    system error such as ENOMEM occurs.

PAM_USER_UNKNOWN

    User not known.

6.12.5. EXAMPLES

Add this line to your login entries to start each login session with its own
session keyring:

session  required  pam_keyinit.so


This will prevent keys from one session leaking into another session for the
same user.

6.12.6. AUTHOR

pam_keyinit was written by David Howells, <dhowells@redhat.com>.

6.13. pam_lastlog - display date of last login

pam_lastlog.so [ debug ] [ silent ] [ never ] [ nodate ] [ nohost ] [ noterm ]
[ nowtmp ]

6.13.1. DESCRIPTION

pam_lastlog is a PAM module to display a line of information about the last
login of the user. In addition, the module maintains the /var/log/lastlog file.

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

6.13.2. OPTIONS

debug

    Print debug information.

silent

    Don't inform the user about any previous login, just upate the /var/log/
    lastlog file.

never

    If the /var/log/lastlog file does not contain any old entries for the user,
    indicate that the user has never previously logged in with a welcome
    message.

nodate

    Don't display the date of the last login.

noterm

    Don't display the terminal name on which the last login was attempted.

nohost

    Don't indicate from which host the last login was attempted.

nowtmp

    Don't update the wtmp entry.

6.13.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.13.4. RETURN VALUES

PAM_SUCCESS

    Everything was successfull.

PAM_SERVICE_ERR

    Internal service module error.

PAM_USER_UNKNOWN

    User not known.

6.13.5. EXAMPLES

Add the following line to /etc/pam.d/login to display the last login time of an
user:

    session  required  pam_lastlog.so nowtmp


6.13.6. AUTHOR

pam_lastlog was written by Andrew G. Morgan <morgan@kernel.org>.

6.14. pam_limits - limit resources

pam_limits.so [ change_uid ] [ conf=/path/to/limits.conf ] [ debug ] [
utmp_early ]

6.14.1. DESCRIPTION

The pam_limits PAM module sets limits on the system resources that can be
obtained in a user-session. Users of uid=0 are affected by this limits, too.

By default limits are taken from the /etc/security/limits.conf config file.

6.14.2. DESCRIPTION

The syntax of the lines is as follows:

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

The fields listed above should be filled as follows:

<domain>
      * a username

      * a groupname, with @group syntax. This should not be confused with
        netgroups.

      * the wildcard *, for default entry.

      * the wildcard %, for maxlogins limit only, can also be used with %group
        syntax.

<type>

    hard

        for enforcing hard resource limits. These limits are set by the
        superuser and enforced by the Kernel. The user cannot raise his
        requirement of system resources above such values.

    soft

        for enforcing soft resource limits. These limits are ones that the user
        can move up or down within the permitted range by any pre-exisiting
        hard limits. The values specified with this token can be thought of as
        default values, for normal system usage.

    -

        for enforcing both soft and hard resource limits together.

        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
        specified user/group etc. .

<item>

    core

        limits the core file size (KB)

    data

        maximum data size (KB)

    fsize

        maximum filesize (KB)

    memlock

        maximum locked-in-memory address space (KB)

    nofile

        maximum number of open files

    rss

        maximum resident set size (KB)

    stack

        maximum stack size (KB)

    cpu

        maximum CPU time (minutes)

    nproc

        maximum number of processes

    as

        address space limit

    maxlogins

        maximum number of logins for this user

    maxsyslogins

        maximum number of logins on system

    priority

        the priority to run user process with (negative values boost process
        priority)

    locks

        maximum locked files (Linux 2.4 and higher)

    sigpending

        maximum number of pending signals (Linux 2.6 and higher)

    msqqueue

        maximum memory used by POSIX message queues (bytes) (Linux 2.6 and
        higher)

    nice

        maximum nice priority allowed to raise to (Linux 2.6.12 and higher)

    rtprio

        maximum realtime priority allowed for non-privileged processes (Linux
        2.6.12 and higher)

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).

6.14.3. OPTIONS

change_uid

    Change real uid to the user for who the limits are set up. Use this option
    if you have problems like login not forking a shell for user who has no
    processes. Be warned that something else may break when you do this.

conf=/path/to/limits.conf

    Indicate an alternative limits.conf style configuration file to override
    the default.

debug

    Print debug information.

utmp_early

    Some broken applications actually allocate a utmp entry for the user before
    the user is admitted to the system. If some of the services you are
    configuring PAM for do this, you can selectively use this module argument
    to compensate for this behavior and at the same time maintain system-wide
    consistency with a single limits.conf file.

6.14.4. MODULE SERVICES PROVIDED

Only the session service is supported.

6.14.5. RETURN VALUES

PAM_ABORT

    Cannot get current limits.

PAM_IGNORE

    No limits found for this user.

PAM_PERM_DENIED

    New limits could not be set.

PAM_SERVICE_ERR

    Cannot read config file.

PAM_SESSEION_ERR

    Error recovering account name.

PAM_SUCCESS

    Limits were changed.

PAM_USER_UNKNOWN

    The user is not known to the system.

6.14.6. FILES

/etc/security/limits.conf

    Default configuration file

6.14.7. EXAMPLES

These are some example lines which might be specified in /etc/security/
limits.conf.

*               soft    core            0
*               hard    rss             10000
@student        hard    nproc           20
@faculty        soft    nproc           20
@faculty        hard    nproc           50
ftp             hard    nproc           0
@student        -       maxlogins       4


6.14.8. AUTHORS

pam_limits was initially written by Cristian Gafton <gafton@redhat.com>

6.15. pam_listfile - deny or allow services based on an arbitrary file

pam_listfile.so item=[tty|user|rhost|ruser|group|shell] sense=[allow|deny] file
=/path/filename onerr=[succeed|fail] [ apply=[user|@group] ]

6.15.1. DESCRIPTION

pam_listfile is a PAM module which provides a way to deny or allow services
based on an arbitrary file.

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.

No credentials are awarded by this module.

6.15.2. OPTIONS

item=[tty|user|rhost|ruser|group|shell]

    What is listed in the file and should be checked for.

sense=[allow|deny]

    Action to take if found in file, if the item is NOT found in the file, then
    the opposite action is requested.

file=/path/filename

    File containing one item per line. The file needs to be a plain file and
    not world writeable.

onerr=[succeed|fail]

    What to do if something weird happens like being unable to open the file.

apply=[user|@group]

    Restrict the user class for which the restriction apply. Note that with
    item=[user|ruser|group] this oes not make sense, but for item=[tty|rhost|
    shell] it have a meaning.

6.15.3. MODULE SERVICES PROVIDED

The services auth, account, password and session are supported.

6.15.4. RETURN VALUES

PAM_AUTH_ERR

    Authentication failure.

PAM_BUF_ERR

    Memory buffer error.

PAM_IGNORE

    The rule does not apply to the apply option.

PAM_SERVICE_ERR

    Error in service module.

PAM_SUCCESS

    Success.

6.15.5. EXAMPLES

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

#
# deny ftp-access to users listed in the /etc/ftpusers file
#
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 /etc/pam.d/login
entry like this:

#
# permit login to users listed in /etc/loginusers
#
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.15.6. AUTHOR

pam_listfile was written by Michael K. Johnson <johnsonm@redhat.com> and Elliot
Lee <sopwith@cuc.edu>.

6.16. pam_localuser - require users to be listed in /etc/passwd

pam_localuser.so [ debug ] [ file=/path/passwd ]

6.16.1. DESCRIPTION

pam_localuser is a PAM module to help implementing site-wide login policies,
where they typically include a subset of the network's users and a few accounts
that are local to a particular workstation. Using pam_localuser and pam_wheel
or pam_listfile is an effective way to restrict access to either local users
and/or a subset of the network's users.

This could also be implemented using pam_listfile.so and a very short awk
script invoked by cron, but it's common enough to have been separated out.

6.16.2. OPTIONS

debug

    Print debug information.

file=/path/passwd

    Use a file other than /etc/passwd.

6.16.3. MODULE SERVICES PROVIDED

The auth and account services are supported.

6.16.4. RETURN VALUES

PAM_SUCCESS

    The new localuser was set successfull.

PAM_SERVICE_ERR

    No username was given.

PAM_USER_UNKNOWN

    User not known.

6.16.5. EXAMPLES

Add the following line to /etc/pam.d/su to allow only local users in group
wheel to use su.

account sufficient pam_localuser.so
account required pam_wheel.so


6.16.6. AUTHOR

pam_localuser was written by Nalin Dahyabhai <nalin@redhat.com>.

6.17. pam_mail - inform about available mail

pam_mail.so [ close ] [ debug ] [ dir=maildir ] [ empty ] [ hash=count ] [
noenv ] [ nopen ] [ quit ] [ standard ]

6.17.1. DESCRIPTION

The pam_mail PAM module provides the "you have new mail" service to the user.
It can be plugged into any application that has credential or session 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 PAM environment variable, MAIL,
to the user's mail directory.

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

6.17.2. OPTIONS

close

    Indicate if the user has any mail also on logout.

debug

    Print debug information.

dir=maildir

    Look for the users' mail in an alternative location defined by maildir/
    <login>. The default location for mail is /var/mail/<login>. Note, if the
    supplied maildir is prefixed by a '~', the directory is interpreted as
    indicating a file in the user's home directory.

empty

    Also print message if user has no mail.

hash=count

    Mail directory hash depth. For example, a hashcount of 2 would make the
    mail file be /var/spool/mail/u/s/user.

noenv

    Do not set the MAIL environment variable.

nopen

    Don't print any mail information on login. This flag is useful to get the
    MAIL environment variable set, but to not display any information about it.

quiet

    Only report when there is new mail.

standard

    Old style "You have..." format which doesn't show the mail spool being
    used. This also implies "empty".

6.17.3. MODULE SERVICES PROVIDED

The auth and account services are supported.

6.17.4. RETURN VALUES

PAM_BUF_ERR

    Memory buffer error.

PAM_SERVICE_ERR

    Badly formed arguments.

PAM_SUCCESS

    Success.

PAM_USER_UNKNOWN

    User not known.

6.17.5. EXAMPLES

Add the following line to /etc/pam.d/login to indicate that the user has new
mail when they login to the system.

session  optional  pam_mail.so standard


6.17.6. AUTHOR

pam_mail was written by Andrew G. Morgan <morgan@kernel.org>.

6.18. pam_mkhomedir - create users home directory

pam_mkhomedir.so [ silent ] [ umask=mode ] [ skel=skeldir ]

6.18.1. DESCRIPTION

The pam_mkhomedir PAM module will create a users home directory if it does not
exist when the session begins. This allows users to be present in central
database (such as NIS, kerberos or LDAP) without using a distributed file
system or pre-creating a large number of directories. The skeleton directory
(usually /etc/skel/) is used to copy default files and also set's a umask for
the creation.

The new users home directory will not be removed after logout of the user.

6.18.2. OPTIONS

silent

    Don't print informative messages.

umask=mask

    The user file-creation mask is set to mask. The default value of mask is
    0022.

skel=/path/to/skel/directory

    Indicate an alternative skel directory to override the default /etc/skel.

6.18.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.18.4. RETURN VALUES

PAM_BUF_ERR

    Memory buffer error.

PAM_CRED_INSUFFICIENT

    Insufficient credentials to access authentication data.

PAM_PERM_DENIED

    Not enough permissions to create the new directory or read the skel
    directory.

PAM_USER_UNKNOWN

    User not known to the underlying authentication module.

PAM_SUCCESS

    Environment variables were set.

6.18.5. EXAMPLES

A sample /etc/pam.d/login file:

  auth       requisite   pam_securetty.so
  auth       sufficient  pam_ldap.so
  auth       required    pam_unix.so
  auth       required    pam_nologin.so
  account    sufficient  pam_ldap.so
  account    required    pam_unix.so
  password   required    pam_unix.so
  session    required    pam_mkhomedir.so skel=/etc/skel/ umask=0022
  session    required    pam_unix.so
  session    optional    pam_lastlog.so
  session    optional    pam_mail.so standard


6.18.6. AUTHOR

pam_mkhomedir was written by Jason Gunthorpe <jgg@debian.org>.

6.19. pam_motd - display the motd file

pam_motd.so [ motd=/path/filename ]

6.19.1. DESCRIPTION

pam_motd is a PAM module that can be used to display arbitrary motd (message of
the day) files after a succesful login. By default the /etc/motd file is shown.
The message size is limited to 64KB.

6.19.2. OPTIONS

motd=/path/filename

    The /path/filename file is displayed as message of the day.

6.19.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.19.4. RETURN VALUES

PAM_IGNORE

    This is the only return value of this module.

6.19.5. EXAMPLES

The suggested usage for /etc/pam.d/login is:

session  optoinal  pam_motd.so  motd=/etc/motd


6.19.6. AUTHOR

pam_motd was written by Ben Collins <bcollins@debian.org>.

6.20. pam_namespace - setup a private namespace

pam_namespace.so [ debug ] [ unmnt_remnt ] [ unmnt_only ] [ require_selinux ] [
gen_hash ] [ ignore_config_error ] [ ignore_instance_parent_mode ] [
no_unmount_on_close ]

6.20.1. DESCRIPTION

The pam_namespace PAM module sets up a private namespace for a session with
polyinstantiated directories. A polyinstantiated directory provides a different
instance of itself based on user name, or when using SELinux, user name,
security context or both. If an executable script /etc/security/namespace.init
exists, it is used to initialize the namespace every time a new instance
directory is setup. The script receives the polyinstantiated directory path and
the instance directory path as its arguments.

The pam_namespace module disassociates the session namespace from the parent
namespace. Any mounts/unmounts performed in the parent namespace, such as
mounting of devices, are not reflected in the session namespace. To propagate
selected mount/unmount events from the parent namespace into the disassociated
session namespace, an administrator may use the special shared-subtree feature.
For additional information on shared-subtree feature, please refer to the mount
(8) man page and the shared-subtree description at http://lwn.net/Articles/
159077 and http://lwn.net/Articles/159092.

6.20.2. DESCRIPTION

This module allows setup of private namespaces with polyinstantiated
directories. Directories can be polyinstantiated based on user name or, in the
case of SELinux, user name, sensitivity level or complete security context. If
an executable script /etc/security/namespace.init exists, it is used to
initialize the namespace every time a new instance directory is setup. The
script receives the polyinstantiated directory path and the instance directory
path as its arguments.

The /etc/security/namespace.conf file specifies which directories are
polyinstantiated, how they are polyinstantiated, how instance directories would
be named, and any users for whom polyinstantiation would not be performed.

When someone logs in, the file namespace.conf is scanned where each non comment
line represents one polyinstantiated directory with space separated fields as
follows:

polydir instance_prefix method list_of_uids

The first field, polydir, is the absolute pathname of the directory to
polyinstantiate. Special entry $HOME is supported to designate user's home
directory. This field cannot be blank.

The second field, instance_prefix is the string prefix used to build the
pathname for the instantiation of <polydir>. The directory security context, or
optionally its md5sum string (32 hex characters), is appended to the prefix to
generate the final instance directory path. This directory is created if it did
not exist already, and is then bind mounted on the <polydir> to provide an
instance of <polydir> based on the <method> column. The special string $HOME is
replaced with the user's home directory, and $USER with the username. This
field cannot be blank. The directory where polyinstantiated instances are to be
created, must exist and must have, by default, the mode of 000. The requirement
that the instance parent be of mode 000 can be overridden with the command line
option <ignore_instance_parent_mode>

The third field, method, is the method used for polyinstantiation. It can take
3 different values; "user" for polyinstantiation based on user name, "level"
for polyinstantiation based on process MLS level and user name, and "context"
for polyinstantiation based on process security context and user name Methods
"context" and "level" are only available with SELinux. This field cannot be
blank.

The fourth field, list_of_uids, is a comma separated list of user names for
whom the polyinstantiation is not performed. If left blank, polyinstantiation
will be performed for all users.

6.20.3. OPTIONS

debug

    A lot of debug information is logged using syslog

unmnt_remnt

    For programs such as su and newrole, the login session has already setup a
    polyinstantiated namespace. For these programs, polyinstantiation is
    performed based on new user id or security context, however the command
    first needs to undo the polyinstantiation performed by login. This argument
    instructs the command to first undo previous polyinstantiation before
    proceeding with new polyinstantiation based on new id/context

unmnt_only

    For trusted programs that want to undo any existing bind mounts and process
    instance directories on their own, this argument allows them to unmount
    currently mounted instance directories

require_selinux

    If selinux is not enabled, return failure

gen_hash

    Instead of using the security context string for the instance name,
    generate and use its md5 hash.

ignore_config_error

    If a line in the configuration file corresponding to a polyinstantiated
    directory contains format error, skip that line process the next line.
    Without this option, pam will return an error to the calling program
    resulting in termination of the session.

ignore_instance_parent_mode

    Instance parent directories by default are expected to have the restrictive
    mode of 000. Using this option, an administrator can choose to ignore the
    mode of the instance parent. This option should be used with caution as it
    will reduce security and isolation goals of the polyinstantiation
    mechanism.

no_unmount_on_close

    For certain trusted programs such as newrole, open session is called from a
    child process while the parent perfoms close session and pam end functions.
    For these commands use this option to instruct pam_close_session to not
    unmount the bind mounted polyinstantiated directory in the parent.

6.20.4. MODULE SERVICES PROVIDED

The session service is supported.

6.20.5. RETURN VALUES

PAM_SUCCESS

    Namespace setup was successful.

PAM_SERVICE_ERR

    Unexpected system error occurred while setting up namespace.

PAM_SESSION_ERR

    Unexpected namespace configuration error occurred.

6.20.6. FILES

/etc/security/namespace.conf

    Configuration file

6.20.7. EXAMPLES

These are some example lines which might be specified in /etc/security/
namespace.conf.


      # The following three lines will polyinstantiate /tmp,
      # /var/tmp and user's home directories. /tmp and /var/tmp
      # will be polyinstantiated based on the security level
      # as well as user name, whereas home directory will be
      # polyinstantiated based on the full security context and user name.
      # Polyinstantiation will not be performed for user root
      # and adm for directories /tmp and /var/tmp, whereas home
      # directories will be polyinstantiated for all users.
      #
      # Note that instance directories do not have to reside inside
      # the polyinstantiated directory. In the examples below,
      # instances of /tmp will be created in /tmp-inst directory,
      # where as instances of /var/tmp and users home directories
      # will reside within the directories that are being
      # polyinstantiated.
      #
      /tmp     /tmp-inst/               level      root,adm
      /var/tmp /var/tmp/tmp-inst/    level      root,adm
      $HOME    $HOME/$USER.inst/inst- context
    

For the <service>s you need polyinstantiation (login for example) put the
following line in /etc/pam.d/<service> as the last line for session group:

session required pam_namespace.so [arguments]

This module also depends on pam_selinux.so setting the context.

6.20.8. AUTHORS

The namespace setup scheme was designed by Stephen Smalley, Janak Desai and
Chad Sellers. The pam_namespace PAM module was developed by Janak Desai
<janak@us.ibm.com>, Chad Sellers <csellers@tresys.com> and Steve Grubb
<sgrubb@redhat.com>.

6.21. pam_nologin - prevent non-root users from login

pam_nologin.so [ file=/path/nologin ] [ successok ]

6.21.1. DESCRIPTION

pam_nologin is a PAM module that prevents users from logging into the system
when /etc/nologin exists. The contents of the /etc/nologin file are displayed
to the user. The pam_nologin module has no effect on the root user's ability to
log in.

6.21.2. OPTIONS

file=/path/nologin

    Use this file instead the default /etc/nologin.

successok

    Return PAM_SUCCESS if no file exists, the default is PAM_IGNORE.

6.21.3. MODULE SERVICES PROVIDED

The auth and acct services are supported.

6.21.4. RETURN VALUES

PAM_AUTH_ERR

    The user is not root and /etc/nologin exists, so the user is not permitted
    to log in.

PAM_BUF_ERR

    Memory buffer error.

PAM_IGNORE

    This is the default return value.

PAM_SUCCESS

    Success: either the user is root or the /etc/nologin file does not exist.

PAM_USER_UNKNOWN

    User not known to the underlying authentication module.

6.21.5. EXAMPLES

The suggested usage for /etc/pam.d/login is:

auth  required  pam_nologin.so


6.21.6. AUTHOR

pam_nologin was written by Michael K. Johnson <johnsonm@redhat.com>.

6.22. pam_permit - the promiscuous module

pam_permit.so

6.22.1. DESCRIPTION

pam_permit is a PAM module that always permit access. It does nothing else.

In the case of authentication, the user's name will be set to nobody if the
application didn't set one. Many applications and PAM modules become confused
if this name is unknown.

This module is very dangerous. It should be used with extreme caution.

6.22.2. OPTIONS

This module does not recognice any options.

6.22.3. MODULE SERVICES PROVIDED

The services auth, account, password and session are supported.

6.22.4. RETURN VALUES

PAM_SUCCESS

    This module always returns this value.

6.22.5. EXAMPLES

Add this line to your other login entries to disable account management, but
continue to permit users to log in.

account  required  pam_permit.so


6.22.6. AUTHOR

pam_permit was written by Andrew G. Morgan, <morgan@kernel.org>.

6.23. pam_rhosts - grant access using .rhosts file

pam_rhosts.so

6.23.1. DESCRIPTION

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

The authentication mechanism of this module is based on the contents of two
files; /etc/hosts.equiv (or 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.

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.

6.23.2. OPTIONS

debug

    Print debug information.

silent

    Don't print informative messages.

superuser=account

    Handle account as root.

6.23.3. MODULE SERVICES PROVIDED

Only the auth service is supported.

6.23.4. RETURN VALUES

PAM_AUTH_ERR

    The remote host, remote user name or the local user name couldn't be
    determined or access was denied by .rhosts file.

PAM_USER_UNKNOWN

    User is not known to system.

6.23.5. EXAMPLES

To grant a remote user access by /etc/hosts.equiv or .rhosts for rsh add the
following lines to /etc/pam.d/rsh:

#%PAM-1.0
#
auth     required       pam_rhosts.so
auth     required       pam_nologin.so
auth     required       pam_env.so
auth     required       pam_unix.so


6.23.6. AUTHOR

pam_rhosts was written by Thorsten Kukuk <kukuk@thkukuk.de>

6.24. pam_rootok - gain only root access

pam_rootok.so [ debug ]

6.24.1. DESCRIPTION

pam_rootok is a PAM module that 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.

6.24.2. OPTIONS

debug

    Print debug information.

6.24.3. MODULE SERVICES PROVIDED

Only the auth service is supported.

6.24.4. RETURN VALUES

PAM_SUCCESS

    The UID is 0.

PAM_AUTH_ERR

    The UID is not 0.

6.24.5. EXAMPLES

In the case of the su(1) 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 with PAM the following pair of lines are needed for the
corresponding entry in the /etc/pam.d/su configuration file:

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


6.24.6. AUTHOR

pam_rootok was written by Andrew G. Morgan, <morgan@kernel.org>.

6.25. pam_securetty - limit root login to special devices

pam_securetty.so [ debug ]

6.25.1. DESCRIPTION

pam_securetty is a PAM module that allows root logins only if the user is
logging in on a "secure" tty, as defined by the listing in /etc/securetty.
pam_securetty also checks to make sure that /etc/securetty is a plain file and
not world writable.

This module has no effect on non-root users and requires that the application
fills in the PAM_TTY item correctly.

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

6.25.2. OPTIONS

debug

    Print debug information.

6.25.3. MODULE SERVICES PROVIDED

Only the auth service is supported.

6.25.4. RETURN VALUES

PAM_SUCCESS

    The user is allowed to continue authentication. Either the user is not
    root, or the root user is trying to log in on an acceptable device.

PAM_AUTH_ERR

    Authentication is rejected. Either root is attempting to log in via an
    unacceptable device, or the /etc/securetty file is world writable or not a
    normal file.

PAM_INCOMPLETE

    An application error occurred. pam_securetty was not able to get
    information it required from the application that called it.

PAM_SERVICE_ERR

    An error occurred while the module was determining the user's name or tty,
    or the module could not open /etc/securetty.

PAM_IGNORE

    The module could not find the user name in the /etc/passwd file to verify
    whether the user had a UID of 0. Therefore, the results of running this
    module are ignored.

6.25.5. EXAMPLES

auth  required  pam_securetty.so
auth  required  pam_unix.so


6.25.6. AUTHOR

pam_securetty was written by Elliot Lee <sopwith@cuc.edu>.

6.26. pam_selinux - set the default security context

pam_selinux.so [ close ] [ debug ] [ open ] [ nottys ] [ verbose ] [
select_context ] [ use_current_range ]

6.26.1. DESCRIPTION

In a nutshell, pam_selinux sets up the default security context for the next
execed shell.

When an application opens a session using pam_selinux, the shell that gets
executed will be run in the default security context, or if the user chooses
and the pam file allows the selected security context. Also the controlling tty
will have it's security context modified to match the users.

Adding pam_selinux into a pam file could cause other pam modules to change
their behavior if the exec another application. The close and open option help
mitigate this problem. close option will only cause the close portion of the
pam_selinux to execute, and open will only cause the open portion to run. You
can add pam_selinux to the config file twice. Add the pam_selinux close as the
executes the open pass through the modules, pam_selinux open_session will
happen last. When PAM executes the close pass through the modules pam_selinux
close_session will happen first.

6.26.2. OPTIONS

close

    Only execute the close_session portion of the module.

debug

    Turns on debugging via syslog(3).

open

    Only execute the open_session portion of the module.

nottys

    Do not try to setup the ttys security context.

verbose

    attempt to inform the user when security context is set.

select_context

    Attempt to ask the user for a custom security context role. If MLS is on
    ask also for sensitivity level.

use_current_range

    Use the sensitivity range of the process for the user context. This option
    and the select_context option are mutually exclusive.

6.26.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.26.4. RETURN VALUES

PAM_AUTH_ERR

    Unable to get or set a valid context.

PAM_SUCCESS

    The security context was set successfull.

PAM_USER_UNKNOWN

    The user is not known to the system.

6.26.5. EXAMPLES

auth     required  pam_unix.so
session  required  pam_permit.so
session  optional  pam_selinux.so


6.26.6. AUTHOR

pam_selinux was written by Dan Walsh <dwalsh@redhat.com>.

6.27. pam_shells - check for valid login shell

pam_shells.so

6.27.1. DESCRIPTION

pam_shells is a PAM module that only allows access to the system if the users
shell is listed in /etc/shells.

It also checks if /etc/shells is a plain file and not world writable.

6.27.2. OPTIONS

This module does not recognice any options.

6.27.3. MODULE SERVICES PROVIDED

The services auth and account are supported.

6.27.4. RETURN VALUES

PAM_AUTH_ERR

    Access to the system was denied.

PAM_SUCCESS

    The users login shell was listed as valid shell in /etc/shells.

PAM_SERVICE_ERR

    The module was not able to get the name of the user.

6.27.5. EXAMPLES

auth  required  pam_shells.so


6.27.6. AUTHOR

pam_shells was written by Erik Troan <ewt@redhat.com>.

6.28. pam_succeed_if - test account characteristics

pam_succeed_if.so [flag...] [condition...]

6.28.1. DESCRIPTION

pam_succeed_if.so is designed to succeed or fail authentication based on
characteristics of the account belonging to the user being authenticated. One
use is to select whether to load other modules based on this test.

The module should be given one or more conditions as module arguments, and
authentication will succeed only if all of the conditions are met.

6.28.2. OPTIONS

The following flags are supported:

debug

    Turns on debugging messages sent to syslog.

use_uid

    Evaluate conditions using the account of the user whose UID the application
    is running under instead of the user being authenticated.

quiet

    Don't log failure or success to the system log.

quiet_fail

    Don't log failure to the system log.

quiet_success

    Don't log success to the system log.

Conditions are three words: a field, a test, and a value to test for.

Available fields are user, uid, gid, shell, home and service:

field < number

    Field has a value numerically less than number.

field <= number

    Field has a value numerically less than or equal to number.

field eq number

    Field has a value numerically less equal to number.

field >= number

    Field has a value numerically greater than or equal to number.

field > number

    Field has a value numerically greater than number.

field ne number

    Field has a value numerically different from number.

field = string

    Field exactly matches the given string.

field != string

    Field does not match the given string.

field =~ glob

    Field matches the given glob.

field !~ glob

    Field does not match the given glob.

field in item:item:...

    Field is contained in the list of items separated by colons.

field notin item:item:...

    Field is not contained in the list of items separated by colons.

user ingroup group

    User is in given group.

user notingroup group

    User is not in given group.

user innetgr netgroup

    (user,host) is in given netgroup.

user notinnetgr group

    (user,host) is not in given netgroup.

6.28.3. MODULE SERVICES PROVIDED

All services are supported.

6.28.4. RETURN VALUES

PAM_SUCCESS

    The condition was true.

PAM_AUTH_ERR

    The condition was false.

PAM_SERVICE_ERR

    A service error occured or the arguments can't be parsed as numbers.

6.28.5. EXAMPLES

To emulate the behaviour of pam_wheel, except there is no fallback to group 0:

auth required pam_succeed_if.so quiet user ingroup wheel


Given that the type matches, only loads the othermodule rule if the UID is over
500. Adjust the number after default to skip several rules.

type [default=1 success=ignore] pam_succeed_if.so quiet uid > 500
type required othermodule.so arguments...


6.28.6. AUTHOR

Nalin Dahyabhai <nalin@redhat.com>

6.29. pam_tally - login counter (tallying) module

pam_tally.so [ file=/path/to/counter ] [ onerr=[fail|succeed] ] [ magic_root ]
[ even_deny_root_account ] [ deny=n ] [ lock_time=n ] [ unlock_time=n ] [
per_user ] [ no_lock_time ] [ no_reset ] [ audit ]

pam_tally [ --file /path/to/counter ] [ --user username ] [ --reset[=n] ] [
--quiet ]

6.29.1. DESCRIPTION

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 faillog(8) command can be used
instead of pam_tally to to maintain the counter file.

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.

6.29.2. OPTIONS

GLOBAL OPTIONS

    This can be used for auth and account services.

    onerr=[fail|succeed]

        If something weird happens (like unable to open the file), return with
        PAM_SUCESS if onerr=succeed is given, else with the corresponding PAM
        error code.

    file=/path/to/counter

        File where to keep counts. Default is /var/log/faillog.

    audit

        Will display the username typed if the user is not found.

AUTH OPTIONS

    Authentication phase first checks if user should be denied access and if
    not it increments attempted login counter. Then on call to pam_setcred(3)
    it resets the attempts counter.

    deny=n

        Deny access if tally for this user exceeds n.

    lock_time=n

        Always deny for n seconds after failed attempt.

    unlock_time=n

        Allow access after n seconds after failed attempt. If this option is
        used the user will be locked out for the specified amount of time after
        he exceeded his maximum allowed attempts. Otherwise the account is
        locked until the lock is removed by a manual intervention of the system
        administrator.

    magic_root

        If the module is invoked by a user with uid=0 the counter is not
        incremented. The sys-admin should use this for user launched services,
        like su, otherwise this argument should be omitted.

    no_lock_time

        Do not use the .fail_locktime field in /var/log/faillog for this user.

    no_reset

        Don't reset count on successful entry, only decrement.

    even_deny_root_account

        Root account can become unavailable.

    even_deny_root_account

        Root account can become unavailable.

    per_user

        If /var/log/faillog contains a non-zero .fail_max/.fail_locktime field
        for this user then use it instead of deny=n/ lock_time=n parameter.

    no_lock_time

        Don't use .fail_locktime filed in /var/log/faillog for this user.

ACCOUNT OPTIONS

    Account phase resets attempts counter if the user is not magic root. This
    phase can be used optionaly for services which don't call pam_setcred(3)
    correctly or if the reset should be done regardless of the failure of the
    account phase of other modules.

    magic_root

        If the module is invoked by a user with uid=0 the counter is not
        incremented. The sys-admin should use this for user launched services,
        like su, otherwise this argument should be omitted.

    no_reset

        Don't reset count on successful entry, only decrement.

6.29.3. MODULE SERVICES PROVIDED

The auth and account services are supported.

6.29.4. RETURN VALUES

PAM_AUTH_ERR

    A invalid option was given, the module was not able to retrive the user
    name, no valid counter file was found, or too many failed logins.

PAM_SUCCESS

    Everything was successfull.

PAM_USER_UNKNOWN

    User not known.

6.29.5. EXAMPLES

Add the following line to /etc/pam.d/login to lock the account after too many
failed logins. The number of allowed fails is specified by /var/log/faillog and
needs to be set with pam_tally or faillog(8) before.

auth     required       pam_securetty.so
auth     required       pam_tally.so per_user
auth     required       pam_env.so
auth     required       pam_unix.so
auth     required       pam_nologin.so
account  required       pam_unix.so
password required       pam_unix.so
session  required       pam_limits.so
session  required       pam_unix.so
session  required       pam_lastlog.so nowtmp
session  optional       pam_mail.so standard


6.29.6. AUTHOR

pam_tally was written by Tim Baverstock and Tomas Mraz.

6.30. pam_time - time controled access

pam_time.so

6.30.1. DESCRIPTION

The pam_time PAM module does not authenticate the user, but instead it
restricts access to a system and or specific applications at various times of
the day and on specific days or over various terminal lines. 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.

By default rules for time/port access are taken from config file /etc/security/
time.conf.

6.30.2. DESCRIPTION

The pam_time PAM module does not authenticate the user, but instead it
restricts access to a system and or specific applications at various times of
the day and on specific days or over various terminal lines. 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.

For this module to function correctly there must be a correctly formatted /etc/
security/time.conf file present. White spaces are ignored and lines maybe
extended with '\' (escaped newlines). Text following a '#' is ignored to the
end of the line.

The syntax of the lines is as follows:

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 first field, the services field, is a logic list of PAM service names that
the rule applies to.

The second field, the tty field, is a logic list of terminal names that this
rule applies to.

The third field, the users field, is a logic list of users or a netgroup of
users to whom this rule applies.

For these items the simple wildcard '*' may be used only once. With netgroups
no wildcards or logic operators are allowed.

The times field is used to indicate the times at which this rule applies. The
format here is a logic list of day/time-range entries. The days are specified
by a sequence of two character entries, MoTuSa for example is Monday Tuesday
and Saturday. Note that repeated days are unset MoMo = no day, and MoWk = all
weekdays bar Monday. The two character combinations accepted are Mo Tu We Th Fr
Sa Su Wk Wd Al, the last two being week-end days and all 7 days of the week
respectively. As a final example, AlFr means all days except Friday.

Each day/time-range can be prefixed with a '!' to indicate "anything but". The
time-range part is two 24-hour times HHMM, separated by a hyphen, indicating
the start and finish time (if the finish time is smaller than the start time it
is deemed to apply on the following day).

For a rule to be active, ALL of service+ttys+users must be satisfied by the
applying process.

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.30.3. OPTIONS

This module does not recognice any options.

6.30.4. MODULE SERVICES PROVIDED

Only the account service is supported.

6.30.5. RETURN VALUES

PAM_SUCCESS

    Access was granted.

PAM_ABORT

    Not all relevant data could be gotten.

PAM_BUF_ERR

    Memory buffer error.

PAM_PERM_DENIED

    Access was not granted.

PAM_USER_UNKNOWN

    The user is not known to the system.

6.30.6. FILES

/etc/security/time.conf

    Default configuration file

6.30.7. EXAMPLES

These are some example lines which might be specified in /etc/security/
time.conf.

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

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


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


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


6.30.8. AUTHOR

pam_time was written by Andrew G. Morgan <morgan@kernel.org>.

6.31. pam_umask - set the file mode creation mask

pam_umask.so [ debug ] [ silent ] [ usergroups ] [ umask=mask ]

6.31.1. DESCRIPTION

pam_umask is a PAM module to set the file mode creation mask of the current
environment. The umask affects the default permissions assigned to newly
created files.

The PAM module tries to get the umask value from the following places in the
following order:

  * umask= argument

  * umask= entry of the users GECOS field

  * pri= entry of the users GECOS field

  * ulimit= entry of the users GECOS field

  * UMASK= entry from /etc/default/login

  * UMASK entry from /etc/login.defs

6.31.2. OPTIONS

debug

    Print debug information.

silent

    Don't print informative messages.

usergroups

    If the user is not root, and the user ID is equal to the group ID, and the
    username is the same as primary group name, the umask group bits are set to
    be the same as owner bits (examples: 022 -> 002, 077 -> 007).

umask=mask

    Sets the calling process's file mode creation mask (umask) to mask & 0777.
    The value is interpreted as Octal.

6.31.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.31.4. RETURN VALUES

PAM_SUCCESS

    The new umask was set successfull.

PAM_SERVICE_ERR

    No username was given.

PAM_USER_UNKNOWN

    User not known.

6.31.5. EXAMPLES

Add the following line to /etc/pam.d/login to set the user specific umask at
login:

        session optional pam_umask.so umask=0022


6.31.6. AUTHOR

pam_umask was written by Thorsten Kukuk <kukuk@thkukuk.de>.

6.32. pam_userdb - authenticate against a db database

pam_userdb.so db=/path/database [ debug ] [ crypt=[crypt|none] ] [ icase ] [
dump ] [ try_first_pass ] [ use_first_pass ] [ unknown_ok ] [ key_only ]

6.32.1. DESCRIPTION

The pam_userdb 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.

6.32.2. OPTIONS

crypt=[crypt|none]

    Indicates whether encrypted or plaintext passwords are stored in the
    database. If it is crypt, passwords should be stored in the database in
    crypt(3) form. If none is selected, passwords should be stored in the
    database as plaintext.

db=/path/database

    Use the /path/database database for performing lookup. There is no default;
    the module will return PAM_IGNORE if no database is provided.

debug

    Print debug information.

dump

    Dump all the entries in the database to the log. Don't do this by default!

icase

    Make the password verification to be case insensitive (ie when working with
    registration numbers and such). Only works with plaintext password storage.

try_first_pass

    Use the authentication token previously obtained by another module that did
    the conversation with the application. If this token can not be obtained
    then the module will try to converse. This option can be used for stacking
    different modules that need to deal with the authentication tokens.

use_first_pass

    Use the authentication token previously obtained by another module that did
    the conversation with the application. If this token can not be obtained
    then the module will fail. This option can be used for stacking different
    modules that need to deal with the authentication tokens.

unknown_ok

    Do not return error when checking for a user that is not in the database.
    This can be used to stack more than one pam_userdb module that will check a
    username/password pair in more than a database.

key_only

    The username and password are concatenated together in the database hash as
    'username-password' with a random value. if the concatenation of the
    username and password with a dash in the middle returns any result, the
    user is valid. this is useful in cases where the username may not be unique
    but the username and password pair are.

6.32.3. MODULE SERVICES PROVIDED

The services auth and account are supported.

6.32.4. RETURN VALUES

PAM_AUTH_ERR

    Authentication failure.

PAM_AUTHTOK_RECOVERY_ERR

    Authentication information cannot be recovered.

PAM_BUF_ERR

    Memory buffer error.

PAM_CONV_ERR

    Conversation failure.

PAM_SERVICE_ERR

    Error in service module.

PAM_SUCCESS

    Success.

PAM_USER_UNKNOWN

    User not known to the underlying authentication module.

6.32.5. EXAMPLES

auth  sufficient pam_userdb.so icase db=/etc/dbtest.db


6.32.6. AUTHOR

pam_userdb was written by Cristian Gafton >gafton@redhat.com<.

6.33. pam_warn - logs all PAM items

pam_warn.so

6.33.1. DESCRIPTION

pam_warn is a PAM module that logs 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. The module always returns PAM_IGNORE, indicating
that it does not want to affect the authentication process.

6.33.2. OPTIONS

This module does not recognice any options.

6.33.3. MODULE SERVICES PROVIDED

The services auth, account, password and session are supported.

6.33.4. RETURN VALUES

PAM_IGNORE

    This module always returns PAM_IGNORE.

6.33.5. EXAMPLES

#%PAM-1.0
#
# If we don't have config entries for a service, the
# OTHER entries are used. To be secure, warn and deny
# access to everything.
other auth     required       pam_warn.so
other auth     required       pam_deny.so
other account  required       pam_warn.so
other account  required       pam_deny.so
other password required       pam_warn.so
other password required       pam_deny.so
other session  required       pam_warn.so
other session  required       pam_deny.so


6.33.6. AUTHOR

pam_warn was written by Andrew G. Morgan <morgan@kernel.org>.

6.34. pam_wheel - only permit root access to members of group wheel

pam_wheel.so [ debug ] [ deny ] [ group=name ] [ root_only ] [ trust ] [
use_uid ]

6.34.1. DESCRIPTION

The pam_wheel PAM 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. If no group with this name exist, the module is using the
group with the group-ID 0.

6.34.2. OPTIONS

debug

    Print debug information.

deny

    Reverse the sense of the auth operation: if the user is trying to get UID 0
    access and is a member of the wheel group (or the group of the group
    option), deny access. Conversely, if the user is not in the group, return
    PAM_IGNORE (unless trust was also specified, in which case we return
    PAM_SUCCESS).

group=name

    Instead of checking the wheel or GID 0 groups, use the name group to
    perform the authentification.

root_only

    The check for wheel membership is done only.

trust

    The pam_wheel module will return PAM_SUCCESS instead of PAM_IGNORE if the
    user is a member of the wheel group (thus with a little play stacking the
    modules the wheel members may be able to su to root without being prompted
    for a passwd).

use_uid

    The check for wheel membership will be done against the current uid instead
    of the original one (useful when jumping with su from one account to
    another for example).

6.34.3. MODULE SERVICES PROVIDED

The auth and account services are supported.

6.34.4. RETURN VALUES

PAM_AUTH_ERR

    Authentication failure.

PAM_BUF_ERR

    Memory buffer error.

PAM_IGNORE

    The return value should be ignored by PAM dispatch.

PAM_PERM_DENY

    Permission denied.

PAM_SERVICE_ERR

    Cannot determine the user name.

PAM_SUCCESS

    Success.

PAM_USER_UNKNOWN

    User not known.

6.34.5. EXAMPLES

The root account 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.so


6.34.6. AUTHOR

pam_wheel was written by Cristian Gafton <gafton@redhat.com>.

6.35. pam_xauth - forward xauth keys between users

pam_xauth.so [ debug ] [ xauthpath=/path/to/xauth ] [ systemuser=UID ] [
targetuser=UID ]

6.35.1. DESCRIPTION

The pam_xauth PAM module is designed to forward xauth keys (sometimes referred
to as "cookies") between users.

Without pam_xauth, when xauth is enabled and a user uses the su(1) command to
assume another user's priviledges, that user is no longer able to access the
original user's X display because the new user does not have the key needed to
access the display. pam_xauth solves the problem by forwarding the key from the
user running su (the source user) to the user whose identity the source user is
assuming (the target user) when the session is created, and destroying the key
when the session is torn down.

This means, for example, that when you run su(1) from an xterm sesssion, you
will be able to run X programs without explicitly dealing with the xauth(1)
xauth command or ~/.Xauthority files.

pam_xauth will only forward keys if xauth can list a key connected to the
$DISPLAY environment variable.

Primitive access control is provided by ~/.xauth/export in the invoking user's
home directory and ~/.xauth/import in the target user's home directory.

If a user has a ~/.xauth/import file, the user will only receive cookies from
users listed in the file. If there is no ~/.xauth/import file, the user will
accept cookies from any other user.

If a user has a .xauth/export file, the user will only forward cookies to users
listed in the file. If there is no ~/.xauth/export file, and the invoking user
is not root, the user will forward cookies to any other user. If there is no ~
/.xauth/export file, and the invoking user is root, the user will not forward
cookies to other users.

Both the import and export files support wildcards (such as *). Both the import
and export files can be empty, signifying that no users are allowed.

6.35.2. OPTIONS

debug

    Print debug information.

xauthpath=/path/to/xauth

    Specify the path the xauth program (it is expected in /usr/X11R6/bin/xauth,
    /usr/bin/xauth, or /usr/bin/X11/xauth by default).

systemuser=UID

    Specify the highest UID which will be assumed to belong to a "system" user.
    pam_xauth will refuse to forward credentials to users with UID less than or
    equal to this number, except for root and the "targetuser", if specified.

targetuser=UID

    Specify a single target UID which is exempt from the systemuser check.

6.35.3. MODULE SERVICES PROVIDED

Only the session service is supported.

6.35.4. RETURN VALUES

PAM_BUF_ERR

    Memory buffer error.

PAM_PERM_DENIED

    Permission denied by import/export file.

PAM_SESSION_ERR

    Cannot determine user name, UID or access users home directory.

PAM_SUCCESS

    Success.

PAM_USER_UNKNOWN

    User not known.

6.35.5. EXAMPLES

Add the following line to /etc/pam.d/su to forward xauth keys between users
when calling su:

session  optional  pam_xauth.so


6.35.6. AUTHOR

pam_xauth was written by Nalin Dahyabhai <nalin@redhat.com>, based on original
version by Michael K. Johnson <johnsonm@redhat.com>.

Chapter 7. See also

  * The Linux-PAM Application Writers' Guide.

  * The Linux-PAM Module Writers' Guide.

  * The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE
    AUTHENTICATION MODULES'', Open Software Foundation Request For Comments
    86.0, October 1995.

Chapter 8. Author/acknowledgments

This document was written by Andrew G. Morgan (morgan@kernel.org) with many
contributions from Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger,
Craig S. Bell, Derrick J. Brashear, Ben Buxton, Seth Chaiklin, Oliver Crow,
Chris Dent, Marc Ewing, Cristian Gafton, Emmanuel Galanos, Brad M. Garcia, Eric
Hester, Michel D'Hooge, Roger Hu, Eric Jacksch, Michael K. Johnson, David
Kinchlea, Olaf Kirch, Marcin Korzonek, Thorsten Kukuk, Stephen Langasek,
Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton, Al Longyear, Ingo
Luetkebohle, Marek Michalkiewicz, Robert Milkowski, Aleph One, Martin Pool,
Sean Reifschneider, Jan Rekorajski, Erik Troan, Theodore Ts'o, Jeff Uphoff,
Myles Uyema, Savochkin Andrey Vladimirovich, Ronald Wahl, David Wood, John
Wilmes, Joseph S. D. Yao and Alex O. Yuriev.

Thanks are also due to Sun Microsystems, especially to Vipin Samar and Charlie
Lai for their advice. At an early stage in the development of Linux-PAM, Sun
graciously made the documentation for their implementation of PAM available.
This act greatly accelerated the development of Linux-PAM.

Chapter 9. Copyright information for this document

Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de>
Copyright (c) 1996-2002 Andrew G. Morgan <morgan@kernel.org>


Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, and the entire permission notice in its entirety,
   including the disclaimer of warranties.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. The name of the author may not be used to endorse or promote
   products derived from this software without specific prior
   written permission.


Alternatively, this product may be distributed under the terms of the GNU
General Public License (GPL), in which case the provisions of the GNU GPL are
required instead of the above restrictions. (This clause is necessary due to a
potential bad interaction between the GNU GPL and the restrictions contained in
a BSD-style copyright.)

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH


