The Linux-PAM System Administrators' Guide
Andrew G. Morgan, morgan@kernel.org
DRAFT v0.75 2001/03/18
This manual documents what a system-administrator needs to know about
the [1mLinux-PAM [22mlibrary. It covers the correct syntax of the PAM config-
uration file and discusses strategies for maintaining a secure system.
______________________________________________________________________
Table of Contents
1. Introduction
2. Some comments on the text
3. Overview
3.1 Getting started
4. The Linux-PAM configuration file
4.1 Configuration file syntax
4.2 Directory based configuration
4.3 Generic optional arguments
4.4 Example configuration file entries
4.4.1 Default policy
5. Security issues of Linux-PAM
5.1 If something goes wrong
5.2 Avoid having a weak `other' configuration
6. A reference guide for available modules
6.1 The access module
6.1.1 Synopsis
6.1.2 Overview of module
6.1.3 Account component
6.2 Chroot
6.2.1 Synopsis
6.2.2 Overview of module
6.2.3 Account component:
6.2.4 Authentication component:
6.2.5 Session component:
6.3 Cracklib pluggable password strength-checker
6.3.1 Synopsis
6.3.2 Overview of module
6.3.3 Password component
6.4 The locking-out module
6.4.1 Synopsis
6.4.2 Overview of module
6.4.3 Account component
6.4.4 Authentication component
6.4.5 Password component
6.4.6 Session component
6.5 Set/unset environment variables
6.5.1 Synopsis
6.5.2 Overview of module
6.5.3 Authentication component
6.6 The filter module
6.6.1 Synopsis
6.6.2 Overview of module
6.6.3 Account+Authentication+Password+Session components
6.7 Anonymous access module
6.7.1 Synopsis
6.7.2 Overview of module
6.7.3 Authentication component
6.8 The group access module
6.8.1 Synopsis
6.8.2 Overview of module
6.8.3 Authentication component
6.9 Add issue file to user prompt
6.9.1 Synopsis
6.9.2 Overview of module
6.9.3 Authentication component
6.10 The Kerberos 4 module.
6.10.1 Synopsis
6.10.2 Overview of module
6.10.3 Session component
6.10.4 Password component
6.10.5 Authentication component
6.11 The last login module
6.11.1 Synopsis
6.11.2 Overview of module
6.11.3 Session component
6.12 The resource limits module
6.12.1 Synopsis
6.12.2 Overview of module
6.12.3 Session component
6.13 The list-file module
6.13.1 Synopsis
6.13.2 Overview of module
6.13.3 Authentication component
6.14 The mail module
6.14.1 Synopsis
6.14.2 Overview of module
6.14.3 Session component
6.14.4 Authentication component
6.15 Create home directories on initial login
6.15.1 Synopsis
6.15.2 Overview of module
6.15.3 Session component
6.16 Output the motd file
6.16.1 Synopsis
6.16.2 Overview of module
6.16.3 Session component
6.17 The no-login module
6.17.1 Synopsis
6.17.2 Overview of module
6.17.3 Authentication component
6.18 The promiscuous module
6.18.1 Synopsis
6.18.2 Overview of module
6.18.3 Account+Authentication+Password+Session components
6.19 The Password-Database module
6.19.1 Synopsis
6.19.2 Overview of module
6.19.3 Account component
6.19.4 Authentication component
6.19.5 Password component
6.19.6 Session component
6.20 The RADIUS session module
6.20.1 Synopsis
6.20.2 Overview of module
6.20.3 Session component
6.21 The rhosts module
6.21.1 Synopsis
6.21.2 Overview of module
6.21.3 Authentication component
6.22 The root access module
6.22.1 Synopsis
6.22.2 Overview of module
6.22.3 Authentication component
6.23 The securetty module
6.23.1 Synopsis
6.23.2 Overview of module
6.23.3 Authentication component
6.24 The login counter (tallying) module
6.24.1 Synopsis
6.24.2 Overview of module
6.24.2.1 Generic options accepted by both components
6.24.3 Authentication component
6.24.4 Account component
6.25 Time control
6.25.1 Synopsis
6.25.2 Overview of module
6.25.3 Account component
6.26 The Unix Password module
6.26.1 Synopsis
6.26.2 Overview of module
6.26.3 Account component
6.26.4 Authentication component
6.26.5 Password component
6.26.6 Session component
6.27 The userdb module
6.27.1 Synopsis
6.27.2 Overview of module
6.27.3 Authentication component
6.28 Warning logger module
6.28.1 Synopsis
6.28.2 Overview of module
6.28.3 Authentication+Password component
6.29 The wheel module
6.29.1 Synopsis
6.29.2 Overview of module
6.29.3 Authentication component
7. Files
8. See also
9. Notes
10. Author/acknowledgments
11. Bugs/omissions
12. Copyright information for this document
______________________________________________________________________
[1m1. Introduction[0m
[1mLinux-PAM [22m(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.
Unfortunately, increases in the speed of computers and the widespread
introduction of network based computing, have made once secure
authentication mechanisms, such as this, vulnerable to attack. In the
light of such realities, new methods of authentication are
continuously being developed.
It is the purpose of the [1mLinux-PAM [22mproject 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 /usr/lib/security and take the form of
dynamically loadable object files (see dlopen(3)).
[1m2. Some comments on the text[0m
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 (Red Hat is one such
distribution), 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 [4mmodules[24m) are to be located in the
following directory: /usr/lib/security/. However, Red Hat Linux, in
agreement with the Linux File System Standard (the FSSTND), places
these files in /lib/security. Please be careful to perform the
necessary transcription when using the examples from the text.
[1m3. Overview[0m
For the uninitiated, we begin by considering an example. We take an
application that grants some service to users; [4mlogin[24m is one such
program. [4mLogin[24m 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 [4mlogin[24m the service is a command
shell ([4mbash,[24m [4mtcsh,[24m [4mzsh,[24m [4metc.[24m) running with the identity of the user.
Traditionally, the former step is achieved by the [4mlogin[24m 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 [1mLinux-PAM[22m.
From the perspective of the application programmer (in this case the
person that wrote the [4mlogin[24m application), [1mLinux-PAM [22mtakes care of this
authentication task -- verifying the identity of the user.
The flexibility of [1mLinux-PAM [22mis that [4myou[24m, 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 [4msimple[24m [4mtrust[24m (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 [4mmultiplication[24m [4mtables[24m. As they mature, the authentication can
be upgraded to include (long) division!
[1mLinux-PAM [22mdeals with four separate types of (management) task. These
are: [4mauthentication[24m [4mmanagement[24m; [4maccount[24m [4mmanagement[24m; [4msession[0m
[4mmanagement[24m; and [4mpassword[24m [4mmanagement[24m. The association of the preferred
management scheme with the behavior of an application is made with
entries in the relevant [1mLinux-PAM [22mconfiguration file. The management
functions are performed by [4mmodules[24m 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 [1mLinux-PAM[22m.
+----------------+
| 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 applica-
tion; application X. Such an application interfaces with the [1mLinux-[0m
[1mPAM [22mlibrary and knows none of the specifics of its configured authen-
tication method. The [1mLinux-PAM [22mlibrary (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 [1mLinux-[0m
[1mPAM[22m, 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 [4mconversation[0m
function.
[1m3.1. Getting started[0m
The following text was contributed by Seth Chaiklin:
To this point, we have described how PAM should work in an
ideal world, in which all applications are coded properly.
However, at the present time (October 1998), this is far
from the case. Therefore, here are some practical considerations
in trying to use PAM in your system.
Why bother, is it really worth all the trouble?
If you running Linux as a single user system, or in an
environment where all the users are trusted, then there
is no real advantage for using PAM.
[1mEd: [22mthere is actually an advantage since you can [4mdummy[24m [4mdown[24m the
authentication to the point where you don't have any... Almost like
Win95.
In a networked environment, it is clear that you need to think a
little more about how users etc., are authenticated:]
If you are running Linux as a server, where several different
services are being provided (e.g., WWW with areas restricted by
password control, PPP), then there can be some real and interesting
value for PAM. In particular, through the use of modules, PAM can
enable a program to search through several different password
databases, even if that program is not explicitly coded for
that particular database. Here are some examples of the possibilities
that this enables.
o Apache has a module that provides PAM services. Now
authentication
to use particular directories can be conducted by PAM, which
means that the range of modules that are available to PAM can
be used, including RADIUS, NIS, NCP (which means that Novell
password databases can be used).
o pppd has a PAMified version (available from Red Hat) Now it is
possible to use a series of databases to authenticate ppp users.
In addition to the normal Linux-based password databases (such
as /etc/passwd and /etc/shadow), you can use PAM modules to
authenticate against Novell password databases or NT-based
password databases.
o The preceding two examples can be combined. Imagaine that the
persons in your office/department are already registered with a
username and password in a Novell or NT LAN. If you wanted to
use this database on your Linux server (for PPP access, for
web access, or even for normal shell access), you can use PAM
to authenticate against this existing database, rather than
maintain a separate database on both Linux and the LAN server.
Can I use PAM for any program that requires authentication?
Yes and no. Yes, if you have access to the source code, and can
add the appropriate PAM functions. No, if you do not have access
to the source code, and the binary does not have the PAM functions
included.
In other words, if a program is going to use PAM, then it has to
have PAM functions explicitly coded into the program. If they
are not, then it is not possible to use PAM.
How can I tell whether a program has PAM coded into it or not?
A quick-and-dirty (but not always reliable) method is to ldd
<programname>
If libpam and libpam_misc are not among the libraries that the program
uses, then it is not going to work with PAM. However, it is possible
that the libraries are included, but there are still problems, because
the PAM coding in the program does not work as it should. So a
more reliable method is to make the follow tests.
In the /etc/pam.d directory, one needs to make a configuration file
for the program that one wants to run. The exact name of the
configuration
file is hard-coded into the program. Usually, it is the same name as
the
program, but not always. For sake of illustration, let's assume that
the program is named "pamprog" and the name of the configuration file
is /etc/pam.d/pamprog.
In the /etc/pam.d/pamprog but the following two lines:
auth required pam_permit.so
auth required pam_warn.so
Now try to use pamprog. The first line in the configuration file
says that all users are permitted. The second line will write a
warning to your syslog file (or whether you syslog is writing
messages). If this test succeeds, then you know that you have
a program that can understand pam, and you can start the more
interesting work of deciding how to stack modules in your
/etc/pam.d/pamprog file.
[1m4. The Linux-PAM configuration file[0m
[1mLinux-PAM [22mis designed to provide the system administrator with a great
deal of flexibility in configuring the privilege granting applications
of their system. The local configuration of those aspects of system
security controlled by Linux-PAM is contained in one of two places:
either the single system file, /etc/pam.conf; or the /etc/pam.d/
directory. In this section we discuss the correct syntax of and
generic options respected by entries to these files.
[1m4.1. Configuration file syntax[0m
The reader should note that the [1mLinux-PAM [22mspecific tokens in this file
are case [4minsensitive[24m. The module paths, however, are case sensitive
since they indicate a file's [4mname[24m and reflect the case dependence of
typical Linux file-systems. The case-sensitivity of the arguments to
any given module is defined for each module in turn.
In addition to the lines described below, there are two [4mspecial[0m
characters provided for the convenience of the system administrator:
comments are preceded by a `#' and extend to the next end-of-line;
also, module specification lines may be extended with a `\' escaped
newline.
A general configuration line of the /etc/pam.conf file has the
following form:
service-name module-type control-flag module-path arguments
Below, we explain the meaning of each of these tokens. The second (and
more recently adopted) way of configuring [1mLinux-PAM [22mis via the con-
tents of the /etc/pam.d/ directory. Once we have explained the meaning
of the above tokens, we will describe this method.
service-name
The name of the service associated with this entry. Frequently
the service name is the conventional name of the given
application. For example, `ftpd', `rlogind' and `su', [4metc.[24m .
There is a special service-name, reserved for defining a default
authentication mechanism. It has the name `OTHER' and may be
specified in either lower or upper case characters. Note, when
there is a module specified for a named service, the `OTHER'
entries are ignored.
module-type
One of (currently) four types of module. The four types are as
follows:
+o 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
(independently of the /etc/groups file discussed above) or
other privileges through its [4mcredential[24m granting properties.
+o account; this module 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.
+o session; primarily, this module 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. .
+o password; this last 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) module-type.
control-flag
The control-flag is used to indicate how the PAM library will
react to the success or failure of the module it is associated
with. Since modules can be [4mstacked[24m (modules of the same type
execute in series, one after another), the control-flags
determine the relative importance of each module. The
application is not made aware of the individual success or
failure of modules listed in the `/etc/pam.conf' file. Instead,
it receives a summary [4msuccess[24m or [4mfail[24m response from the [1mLinux-[0m
[1mPAM [22mlibrary. The order of execution of these modules is that of
the entries in the /etc/pam.conf file; earlier entries are
executed before later ones. As of Linux-PAM v0.60, this
[4mcontrol-flag[24m can be defined with one of two syntaxes.
The simpler (and historical) syntax for the control-flag is a
single keyword defined to indicate the severity of concern
associated with the success or failure of a specific module.
There are four such keywords: required, requisite, sufficient
and optional.
The Linux-PAM library interprets these keywords in the following
manner:
+o required; this indicates that the success of the module is
required for the module-type facility to succeed. Failure of
this module will not be apparent to the user until all of the
remaining modules (of the same module-type) have been
executed.
+o 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
[4mfirst[24m 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.
+o sufficient; the success of this module is deemed `[4msufficient[24m'
to satisfy the [1mLinux-PAM [22mlibrary that this module-type has
succeeded in its purpose. In the event that no previous
required module has failed, no more `[4mstacked[24m' modules of this
type are invoked. (Note, in this case subsequent required
modules are [1mnot [22minvoked.). A failure of this module is not
deemed as fatal to satisfying the application that this
module-type has succeeded.
+o optional; as its name suggests, this control-flag marks the
module as not being critical to the success or failure of the
user's application for service. In general, [1mLinux-PAM[0m
ignores such a module when determining if the module stack
will succeed or fail. However, in the absence of any
definite successes or failures of previous or subsequent
stacked modules this module will determine the nature of the
response to the application. One example of this latter
case, is when the other modules return something like
PAM_IGNORE.
The more elaborate (newer) syntax is much more specific and
gives the administrator a great deal of control over how the
user is authenticated. This form of the control flag is
delimeted with square brackets and consists of a series of
value=action tokens:
[value1=action1 value2=action2 ...]
Here, valueI is one of the following [4mreturn[24m [4mvalues[24m: 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)
can be used to set the action for those return values that are not
explicitly defined.
The actionI can be a positive integer or one of the following
tokens: ignore; ok; done; bad; die; and reset. A positive integer,
J, when specified as the action, can be used to indicate that the
next [4mJ[24m modules of the current type will be skipped. In this way,
the administrator can develop a moderately sophisticated stack of
modules with a number of different paths of execution. Which path
is taken can be determined by the reactions of individual modules.
+o ignore - when used with a stack of modules, the module's
return status will not contribute to the return code the
application obtains.
+o 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.
+o die - equivalent to bad with the side effect of terminating
the module stack and PAM immediately returning to the
application.
+o ok - this tells [1mPAM [22mthat 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.
+o done - equivalent to ok with the side effect of terminating
the module stack and PAM immediately returning to the
application.
+o reset - clear all memory of the state of the module stack and
start again with the next stacked module.
Just to get a feel for the power of this new syntax, here is a
taste of what you can do with it. With [1mLinux-PAM-0.63[22m, the notion
of client plug-in agents was introduced. This is something that
makes it possible for PAM to support machine-machine authentication
using the transport protocol inherent to the client/server
application. With the ``[ ... value=action ... ]'' control syntax,
it is possible for an application to be configured to support
binary prompts with compliant clients, but to gracefully fall over
into an alternative authentication mode for older, legacy,
applications. Flexible eh?
module-path
The path-name of the dynamically loadable object file; [4mthe[0m
[4mpluggable[24m [4mmodule[24m itself. If the first character of the module
path is `/', it is assumed to be a complete path. If this is not
the case, the given module path is appended to the default
module path: /usr/lib/security (but see the notes ``above'').
args
The args are a list of tokens that are passed to the module when
it is invoked. Much like arguments to a typical Linux shell
command. Generally, valid arguments are optional and are
specific to any given module. Invalid arguments are ignored by a
module, however, when encountering an invalid argument, the
module is required to write an error to syslog(3). For a list of
[4mgeneric[24m options see the next section.
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).
[1m4.2. Directory based configuration[0m
More flexible than the single configuration file, as of version 0.56,
it is possible 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.
[1mLinux-PAM [22mcan be compiled in one of two modes. The preferred mode
uses either /etc/pam.d/ or /etc/pam.conf configuration but not both.
That is to say, if there is a /etc/pam.d/ directory then libpam only
uses the files contained in this directory. However, in the absence
of the /etc/pam.d/ directory the /etc/pam.conf file is used. The
other mode (and the one currently supported by Red Hat Linux 4.2 and
higher) is to use both /etc/pam.d/ and /etc/pam.conf in sequence. In
this mode, entries in /etc/pam.d/ override those of /etc/pam.conf.
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:
module-type control-flag module-path 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 [4mlogin[0m
service.
This method of configuration has a number of advantages over the
single file approach. We list them here to assist the reader in
deciding which scheme to adopt:
+o A lower chance of misconfiguring an application. There is one less
field to mis-type when editing the configuration files by hand.
+o Easier to maintain. One application may be reconfigured without
risk of interfering with other applications on the system.
+o It is possible to symbolically link different services
configuration files to a single file. This makes it easier to keep
the system policy for access consistent across different
applications. (It should be noted, to conserve space, it is
equally possible to [4mhard[24m link a number of configuration files.
However, care should be taken when administering this arrangement
as editing a hard linked file is likely to break the link.)
+o A potential for quicker configuration file parsing. Only the
relevant entries are parsed when a service gets bound to its
modules.
+o It is possible to limit read access to individual [1mLinux-PAM[0m
configuration files using the file protections of the filesystem.
+o Package management becomes simpler. Every time a new application
is installed, it can be accompanied by an /etc/pam.d/[4mxxxxxx[24m file.
[1m4.3. Generic optional arguments[0m
The following are optional arguments which are likely to be understood
by any module. Arguments (including these) are in general [4moptional[24m.
debug
Use the syslog(3) call to log debugging information to the
system log files.
no_warn
Instruct module to not give warning messages to the application.
use_first_pass
The module should not prompt the user for a password. Instead,
it should obtain the previously typed password (from the
preceding auth module), and use that. If that doesn't work, then
the user will not be authenticated. (This option is intended for
auth and password modules only).
try_first_pass
The module should attempt authentication with the previously
typed password (from the preceding auth module). If that doesn't
work, then the user is prompted for a password. (This option is
intended for auth modules only).
use_mapped_pass
This argument is not currently supported by any of the modules
in the [1mLinux-PAM [22mdistribution because of possible consequences
associated with U.S. encryption exporting restrictions. Within
the U.S., module developers are, of course, free to implement it
(as are developers in other countries). For compatibility
reasons we describe its use as suggested in the [1mDCE-RFC 86.0[22m,
see section ``bibliography'' for a pointer to this document.
The use_mapped_pass argument instructs the module to take the
clear text authentication token entered by a previous module
(that requests such a token) and use it to generate an
encryption/decryption key with which to safely store/retrieve
the authentication token required for this module. In this way
the user can enter a single authentication token and be quietly
authenticated by a number of stacked modules. Obviously a
convenient feature that necessarily requires some reliably
strong encryption to make it secure. This argument is intended
for the auth and password module types only.
expose_account
In general the leakage of some information about user accounts
is not a secure policy for modules to adopt. Sometimes
information such as users names or home directories, or
preferred shell, can be used to attack a user's account. In some
circumstances, however, this sort of information is not deemed a
threat: displaying a user's full name when asking them for a
password in a secured environment could also be called being
'friendly'. The expose_account argument is a standard module
argument to encourage a module to be less discrete about account
information as it is deemed appropriate by the local
administrator.
[1m4.4. Example configuration file entries[0m
In this section, we give some examples of entries that can be present
in the [1mLinux-PAM [22mconfiguration file. As a first attempt at configuring
your system you could do worse than to implement these.
[1m4.4.1. Default policy[0m
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 /usr/lib/security/pam_deny.so
OTHER account required /usr/lib/security/pam_deny.so
OTHER password required /usr/lib/security/pam_deny.so
OTHER session required /usr/lib/security/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 /usr/lib/security/pam_warn.so
OTHER password required /usr/lib/security/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 /usr/lib/security/pam_warn.so
auth required /usr/lib/security/pam_deny.so
account required /usr/lib/security/pam_deny.so
password required /usr/lib/security/pam_warn.so
password required /usr/lib/security/pam_deny.so
session required /usr/lib/security/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.conf) is likely to mimic the
historically familiar Linux setup.
#
# default; standard UNIX access
#
OTHER auth required /usr/lib/security/pam_unix_auth.so
OTHER account required /usr/lib/security/pam_unix_acct.so
OTHER password required /usr/lib/security/pam_unix_passwd.so
OTHER session required /usr/lib/security/pam_unix_session.so
In general this will provide a starting place for most applications.
Unfortunately, most is not all. One application that might require
additional lines is [4mftpd[24m if you wish to enable [4manonymous-ftp[24m.
To enable anonymous-ftp, the following lines might be used to replace
the default (OTHER) ones. ([1m*WARNING* [22mas of 1996/12/28 this does not
work correctly with any ftpd. Consequently, this description may be
subject to change or the application will be fixed.)
#
# ftpd; add ftp-specifics. These lines enable anonymous ftp over
# standard UNIX access (the listfile entry blocks access to
# users listed in /etc/ftpusers)
#
ftpd auth sufficient /usr/lib/security/pam_ftp.so
ftpd auth required /usr/lib/security/pam_unix_auth.so use_first_pass
ftpd auth required /usr/lib/security/pam_listfile.so \
onerr=succeed item=user sense=deny file=/etc/ftpusers
Note, the second line is necessary since the default entries are
ignored by a service application (here [4mftpd[24m) if there are [4many[24m entries
in /etc/pam.conf for that specified service. Again, this is an exam-
ple of authentication module stacking. Note the use of the sufficient
control-flag. It says that ``if this module authenticates the user,
ignore the subsequent auth modules''. Also note the use of the
``use_first_pass'' module-argument, this instructs the UNIX
authentication module that it is not to prompt for a password but rely
one already having been obtained by the ftp module.
[1m5. Security issues of Linux-PAM[0m
This section will discuss good practices for using Linux-PAM in a
secure manner. [4mIt[24m [4mis[24m [4mcurrently[24m [4msadly[24m [4mlacking...suggestions[24m [4mare[0m
[4mwelcome![0m
[1m5.1. If something goes wrong[0m
[1mLinux-PAM [22mhas 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, [1mLinux-PAM [22merrs 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 [1mLinux-PAM [22mis that of [4mdeleting[24m 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 reboot the system in single user mode
and set about correcting things from there. The following has been
[4madapted[24m from a life-saving email on the subject from David Wood:
> What the hell do I do now?
OK, don't panic. The first thing you have to realize is that
this happens to 50% of users who ever do anything with PAM.
It happened here, not once, not twice, but three times, all
different, and in the end, the solution was the same every
time.
First, I hope you installed LILO with a delay. If you can,
reboot, hit shift or tab or something and type:
LILO boot: linux single
(Replace 'linux' with 'name-of-your-normal-linux-image').
This will let you in without logging in. Ever wondered how
easy it is to break into a linux machine from the console?
Now you know.
If you can't do that, then get yourself a bootkernel floppy
and a root disk a-la slackware's rescue.gz. (Red Hat's
installation disks can be used in this mode too.)
In either case, the point is to get back your root prompt.
Second, I'm going to assume that you haven't completely
nuked your pam installation - just your configuration files.
Here's how you make your configs nice again:
cd /etc
mv pam.conf pam.conf.orig
mv pam.d pam.d.orig
mkdir pam.d
cd pam.d
and then use vi to create a file called "other" in this
directory. It should contain the following four lines:
auth required pam_unix_auth.so
account required pam_unix_acct.so
password required pam_unix_passwd.so
session required pam_unix_session.so
Now you have the simplest possible PAM configuration that
will work the way you're used to. Everything should
magically start to work again. Try it out by hitting ALT-F2
and logging in on another virtual console. If it doesn't
work, you have bigger problems, or you've mistyped
something. One of the wonders of this system (seriously,
perhaps) is that if you mistype anything in the conf files,
you usually get no error reporting of any kind on the
console - just some entries in the log file. So look there!
(Try 'tail /var/log/messages'.)
From here you can go back and get a real configuration
going, hopefully after you've tested it first on a machine
you don't care about screwing up. :/
Some pointers (to make everything "right" with Red Hat...):
Install the newest pam, pamconfig, and pwdb from the
redhat current directory, and do it all on the same
command line with rpm...
rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-*
Then make sure you install (or reinstall) the newest
version of libc, util-linux, wuftp, and NetKit. For
kicks you might try installing the newest versions of
the affected x apps, like xlock, but I haven't gotten
those to work at all yet.
[1m5.2. Avoid having a weak `other' configuration[0m
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 [4mpam_deny[24m module will
deny access and the [4mpam_warn[24m 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
[1m6. A reference guide for available modules[0m
Here, we collect together some descriptions of the various modules
available for [1mLinux-PAM[22m. In general these modules should be freely
available. Where this is not the case, it will be indicated.
Also please note the comments contained in the section ``on text
conventions above'' when copying the examples listed below.
[1m6.1. The access module[0m
[1m6.1.1. Synopsis[0m
[1mModule Name:[0m
pam_access
[1mAuthor[s]:[0m
Alexei Nogin <alexei@nogin.dnttm.ru>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
account
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires a configuration file. By default
/etc/security/access.conf is used but this can be overridden.
[1mNetwork aware:[0m
Through PAM_TTY if set, otherwise attempts getting tty name of
the stdin file descriptor with ttyname(). Standard
gethostname(), yp_get_default_domain(), gethostbyname() calls.
[1mNIS [22mis used for netgroup support.
[1m6.1.2. Overview of module[0m
Provides logdaemon style login access control.
[1m6.1.3. Account component[0m
[1mRecognized arguments:[0m
accessfile=[4m/path/to/file.conf[0m
[1mDescription:[0m
This module provides logdaemon style login access control based
on login names and on host (or domain) names, internet addresses
(or network numbers), or on terminal line names in case of non-
networked logins. Diagnostics are reported through syslog(3).
Wietse Venema's login_access.c from [4mlogdaemon-5.6[24m is used with
several changes by A. Nogin.
The behavior of this module can be modified with the following
arguments:
+o accessfile=/path/to/file.conf - indicate an alternative
[4maccess[24m configuration file to override the default. This can
be useful when different services need different access
lists.
[1mExamples/suggested usage:[0m
Use of module is recommended, for example, on administrative
machines such as [1mNIS [22mservers and mail servers where you need
several accounts active but don't want them all to have login
capability.
For /etc/pam.d style configurations where your modules live in
/lib/security, start by adding the following line to
/etc/pam.d/login, /etc/pam.d/rlogin, /etc/pam.d/rsh and
/etc/pam.d/ftp:
account required /lib/security/pam_access.so
Note that use of this module is not effective unless your system
ignores .rhosts files. See the the pam_rhosts_auth documentation.
A sample access.conf configuration file is included with the
distribution.
[1m6.2. Chroot[0m
[1m6.2.1. Synopsis[0m
[1mModule Name:[0m
pam_chroot
[1mAuthor:[0m
Bruce Campbell <brucec@humbug.org.au>
[1mMaintainer:[0m
Author; proposed on 20/11/96 - email for status
[1mManagement groups provided:[0m
account; session; authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
Unwritten.
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
Expects localhost.
[1m6.2.2. Overview of module[0m
This module is intended to provide a transparent wrapper around the
average user, one that puts them in a fake file-system (eg, their
Useful if you have several classes of users, and are slightly paranoid
about security. Can be used to limit who else users can see on the
system, and to limit the selection of programs they can run.
[1m6.2.3. Account component:[0m
[4mNeed[24m [4mmore[24m [4minfo[24m [4mhere.[0m
[1m6.2.4. Authentication component:[0m
[4mNeed[24m [4mmore[24m [4minfo[24m [4mhere.[0m
[1m6.2.5. Session component:[0m
[4mNeed[24m [4mmore[24m [4minfo[24m [4mhere.[0m
[1mRecognized arguments:[0m
Arguments and logging levels for the PAM version are being
worked on.
[1mDescription:[0m
[1mExamples/suggested usage:[0m
Do provide a reasonable list of programs - just tossing 'cat',
'ls', 'rm',
Don't take it to extremes (eg, you can set up a separate
environment for each user, but its a big waste of your disk
space.)
[1m6.3. Cracklib pluggable password strength-checker[0m
[1m6.3.1. Synopsis[0m
[1mModule Name:[0m
pam_cracklib
[1mAuthor:[0m
Cristian Gafton <gafton@redhat.com>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
password
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires the system library libcrack and a system dictionary:
/usr/lib/cracklib_dict.
[1mNetwork aware:[0m
[1m6.3.2. Overview of module[0m
This module can be plugged into the password stack of a given
application to provide some plug-in strength-checking for passwords.
This module works in the following manner: it first calls the [4mCracklib[0m
routine to check the strength of the password; if crack likes the
password, the module does an additional set of strength checks. These
checks are:
+o [1mPalindrome [22m-
Is the new password a palindrome of the old one?
+o [1mCase Change Only [22m-
Is the new password the the old one with only a change of case?
+o [1mSimilar [22m-
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.
+o [1mSimple [22m-
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.
+o [1mRotated [22m-
Is the new password a rotated version of the old password?
+o [1mAlready used [22m-
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.
[1m6.3.3. Password component[0m
[1mRecognized arguments:[0m
debug; type=XXX; retry=N; difok=N; minlen=N; dcredit=N;
ucredit=N; lcredit=N; ocredit=N; use_authtok;
[1mDescription:[0m
The action of this module is to prompt the user for a password
and check its strength against a system dictionary and a set of
rules for identifying poor choices.
The default action is to prompt for a single password, check its
strength and then, if it is considered strong, prompt for the
password a second time (to verify that it was typed correctly on
the first occasion). All being well, the password is passed on
to subsequent modules to be installed as the new authentication
token.
The default action may be modified in a number of ways using the
arguments recognized by the module:
+o debug -
this option makes the module write information to syslog(3)
indicating the behavior of the module (this option does [1mnot[0m
write password information to the log file).
+o type=XXX -
the default action is for the module to use the following
prompts when requesting passwords: ``New UNIX password: ''
and ``Retype UNIX password: ''. Using this option you can
replace the word UNIX with XXX.
+o retry=N -
the default number of times this module will request a new
password (for strength-checking) from the user is 1. Using
this argument this can be increased to N.
+o difok=N -
This argument will change the default of 10 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.
+o minlen=N -
The minimum acceptable size for the new password plus one.
In addition to the number of characters in the new password,
credit (of +1 in length) is given for each different kind of
character ([4mother,[24m [4mupper,[24m [4mlower[24m and [4mdigit[24m). 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 [4mCracklib[24m 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 either not use this module or recompile the crack
library and then recompile this module.
+o dcredit=N -
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.
+o ucredit=N -
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.
+o lcredit=N -
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.
+o ocredit=N -
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.
+o use_authtok -
This argument is used to [4mforce[24m the module to not prompt the
user for a new password but use the one provided by the
previously stacked password module.
[1mExamples/suggested usage:[0m
For an example of the use of this module, we show how it may be
stacked with the password component of pam_pwdb:
#
# 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_pwdb 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_pwdb.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_pwdb.so use_authtok nullok md5
[1m6.4. The locking-out module[0m
[1m6.4.1. Synopsis[0m
[1mModule Name:[0m
pam_deny
[1mAuthor:[0m
Andrew G. Morgan <morgan@parc.power.net>
[1mMaintainer:[0m
current [1mLinux-PAM [22mmaintainer
[1mManagement groups provided:[0m
account; authentication; password; session
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
clean.
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.4.2. Overview of module[0m
This module can be used to deny access. It always indicates a failure
to the application through the PAM framework. As is commented in the
overview section ``above'', this module might be suitable for using
for default (the OTHER) entries.
[1m6.4.3. Account component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This component does nothing other than return a failure. The
failure type is PAM_ACCT_EXPIRED.
[1mExamples/suggested usage:[0m
Stacking this module with type account will prevent the user
from gaining access to the system via applications that refer to
[1mLinux-PAM[22m's account management function pam_acct_mgmt().
The following example would make it impossible to login:
#
# add this line to your other login entries to disable all accounts
#
login account required pam_deny.so
[1m6.4.4. Authentication component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This component does nothing other than return a failure. The
failure type is PAM_AUTH_ERR in the case that pam_authenticate()
is called (when the application tries to authenticate the user),
and is PAM_CRED_UNAVAIL when the application calls pam_setcred()
(to establish and set the credentials of the user -- it is
unlikely that this function will ever be called in practice).
[1mExamples/suggested usage:[0m
To deny access to default applications with this component of
the pam_deny module, you might include the following line in
your [1mLinux-PAM [22mconfiguration file:
#
# add this line to your existing OTHER entries to prevent
# authentication succeeding with default applications.
#
OTHER auth required pam_deny.so
[1m6.4.5. Password component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This component of the module denies the user the opportunity to
change their password. It always responds with PAM_AUTHTOK_ERR
when invoked.
[1mExamples/suggested usage:[0m
This module should be used to prevent an application from
updating the applicant user's password. For example, to prevent
login from automatically prompting for a new password when the
old one has expired you should include the following line in
your configuration file:
#
# add this line to your other login entries to prevent the login
# application from being able to change the user's password.
#
login password required pam_deny.so
[1m6.4.6. Session component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This aspect of the module prevents an application from starting
a session on the host computer.
[1mExamples/suggested usage:[0m
Together with another session module, that displays a message of
the day perhaps (XXX - such a module needs to be written), this
module can be used to block a user from starting a shell. Given
the presence of a pam_motd module, we might use the following
entries in the configuration file to inform the user it is
system time:
#
# An example to see how to configure login to refuse the user a
# session (politely)
#
login session required pam_motd.so \
file=/etc/system_time
login session required pam_deny.so
[1m6.5. Set/unset environment variables[0m
[1m6.5.1. Synopsis[0m
[1mModule Name:[0m
pam_env
[1mAuthor:[0m
Dave Kinchlea <kinch@kinch.ark.com>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
Authentication (setcred)
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
/etc/security/pam_env.conf
[1mNetwork aware:[0m
[1m6.5.2. Overview of module[0m
This module allows the (un)setting of environment variables. Supported
is the use of previously set environment variables as well as
[4mPAM_ITEM[24ms such as PAM_RHOST.
[1m6.5.3. Authentication component[0m
[1mRecognized arguments:[0m
debug; conffile=[4mconfiguration-file-name[24m; envfile=[4menv-file-name[24m;
readenv=[4m0|1[0m
[1mDescription:[0m
This module allows you to (un)set arbitrary environment
variables using fixed strings, the value of previously set
environment variables and/or [4mPAM_ITEM[24ms.
All is controlled via a configuration file (by default,
/etc/security/pam_env.conf but can be overriden with conffile
argument). Each line starts with the variable name, there are
then two possible options for each variable [1mDEFAULT [22mand
[1mOVERRIDE[22m. [1mDEFAULT [22mallows an administrator to set the value of
the variable to some default value, if none is supplied then the
empty string is assumed. The [1mOVERRIDE [22moption tells pam_env that
it should enter in its value (overriding the default value) if
there is one to use. [1mOVERRIDE [22mis 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) [4mPAM_ITEM[24ms
may be used in values using the @{string} syntax. Both the $ and @
characters can be backslash-escaped to be used as literal values
(as in \$. Double quotes may be used in values (but not
environment variable names) when white space is needed [1mthe full[0m
[1mvalue must be delimited by the quotes and embedded or escaped[0m
[1mquotes are not supported[22m.
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 [4menvfile[24m flag and turn it on or off
by setting the [4mreadenv[24m flag to 1 or 0 respectively.
The behavior of this module can be modified with one of the
following flags:
+o debug - write more information to syslog(3).
+o conffile=[4mfilename[24m - by default the file
/etc/security/pam_env.conf is used as the configuration file.
This option overrides the default. You must supply a complete
path + file name.
+o envfile=[4mfilename[24m - by default the file /etc/environment is
used to load KEY=VAL pairs directly into the env. This option
overrides the default. You must supply a complete path + file
name.
+o readenv=[4m0|1[24m - turns on or off the reading of the file
specified by envfile (0 is off, 1 is on). By default this
option is on.
[1mExamples/suggested usage:[0m
See sample pam_env.conf for more information and examples.
[1m6.6. The filter module[0m
[1m6.6.1. Synopsis[0m
[1mModule Name:[0m
pam_filter
[1mAuthor:[0m
Andrew G. Morgan <morgan@parc.power.net>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
account; authentication; password; session
[1mCryptographically sensitive:[0m
Not yet.
[1mSecurity rating:[0m
[1mClean code base:[0m
This module compiles cleanly on Linux based systems.
[1mSystem dependencies:[0m
To function it requires [4mfilters[24m to be installed on the system.
[1mNetwork aware:[0m
[1m6.6.2. Overview of module[0m
This module was written to offer a plug-in alternative to programs
like ttysnoop (XXX - need a reference). Since writing a filter that
performs this function has not occurred, it is currently only a toy.
The single filter provided with the module simply transposes upper and
lower case letters in the input and output streams. (This can be very
annoying and is not kind to termcap based editors).
[1m6.6.3. Account+Authentication+Password+Session components[0m
[1mRecognized arguments:[0m
debug; new_term; non_term; runX
[1mDescription:[0m
Each component of the module has the potential to invoke the
desired filter. The filter is always execv(2)d with the
privilege of the calling application and [1mnot [22mthat of the user.
For this reason it cannot usually be killed by the user without
closing their session.
The behavior of the module can be significantly altered by the
arguments passed to it in the [1mLinux-PAM [22mconfiguration file:
+o debug -
this option increases the amount of information logged to
syslog(3) as the module is executed.
+o 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.
+o non_term - don't try to set the PAM_TTY item.
+o 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. The arguments that follow this one
are respectively the full pathname of the filter to be run
and any command line arguments that the filter might expect.
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 Linux-PAM Module
developer's guide. Basically, for each management group there
are up to two ways of calling the module's functions.
In the case of the [4mauthentication[24m and [4msession[24m components
there are actually two separate functions. For the case of
authentication, these functions are _authenticate and
_setcred -- here run1 means run the filter from the
_authenticate function and run2 means run the filter from
_setcred. In the case of the session modules, run1 implies
that the filter is invoked at the _open_session stage, and
run2 for _close_session.
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
_chauthtok is run (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).
[1mExamples/suggested usage:[0m
At the time of writing there is little real use to be made of
this module. For fun you might try adding the following line to
your login's configuration entries
#
# An example to see how to configure login to transpose upper and
# lower case letters once the user has logged in(!)
#
login session required pam_filter.so \
run1 /usr/sbin/pam_filter/upperLOWER
[1m6.7. Anonymous access module[0m
[1m6.7.1. Synopsis[0m
[1mModule Name:[0m
pam_ftp.so
[1mAuthor:[0m
Andrew G. Morgan <morgan@linux.kernel.org>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
prompts for email address of user; easily spoofed (XXX - needs
work)
[1m6.7.2. Overview of module[0m
The purpose of this module is to provide a pluggable anonymous ftp
mode of access.
[1m6.7.3. Authentication component[0m
[1mRecognized arguments:[0m
debug; users=XXX,YYY,...; ignore
[1mDescription:[0m
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 is set to ``ftp''.
In this case the module succeeds. Alternatively, the module
sets the PAM_AUTHTOK item with the entered password and fails.
The behavior of the module can be modified with the following
flags:
+o debug - log more information to with syslog(3).
+o users=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''.
+o ignore - pay no attention to the email address of the user
(if supplied).
[1mExamples/suggested usage:[0m
An example of the use of this module is provided in the
configuration file section ``above''. With care, this module
could be used to provide new/temporary account anonymous login.
[1m6.8. The group access module[0m
[1m6.8.1. Synopsis[0m
[1mModule Name:[0m
pam_group
[1mAuthor:[0m
Andrew G. Morgan <morgan@parc.power.net>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
Sensitive to [4msetgid[24m status of file-systems accessible to users.
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires an /etc/security/group.conf file. Can be compiled with
or without libpwdb.
[1mNetwork aware:[0m
Only through correctly set PAM_TTY item.
[1m6.8.2. Overview of module[0m
This module provides group-settings based on the user's name and the
terminal they are requesting a given service from. It takes note of
the time of day.
[1m6.8.3. Authentication component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This module does not authenticate the user, but instead it
grants group memberships (in the credential setting phase of the
authentication module) to the user. Such memberships are based
on the service they are applying for. The group memberships are
listed in text form in the /etc/security/group.conf file.
[1mExamples/suggested usage:[0m
For this module to function correctly there must be a correctly
formatted /etc/security/groups.conf file present. The format of
this file is as follows. Group memberships are given based on
the service application satisfying any combination of lines in
the configuration file. Each line (barring comments which are
preceded by `#' marks) has the following syntax:
services ; ttys ; users ; times ; groups
Here the first four fields share the syntax of the pam_time config-
uration file; /etc/security/pam_time.conf, and the last field, the
groups field, is a comma (or space) separated list of the text-
names of a selection of groups. If the users application for ser-
vice satisfies the first four fields, the user is granted member-
ship of the listed groups.
As stated in above this module's usefulness relies on the file-
systems accessible to the user. The point being that once granted
the membership of a group, the user may attempt to create a [4msetgid[0m
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 [4mnosuid[24m 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 [4mnosuid[24m.
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 [4min[24m [4maddition[24m to those entries /etc/group
(or equivalent).
[1m6.9. Add issue file to user prompt[0m
[1m6.9.1. Synopsis[0m
[1mModule Name:[0m
pam_issue
[1mAuthor:[0m
Ben Collins <bcollins@debian.org>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
Authentication (pam_sm_authenticate)
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.9.2. Overview of module[0m
This module prepends the issue file ([4m/etc/issue[24m by default) when
prompting for a username.
[1m6.9.3. Authentication component[0m
[1mRecognized arguments:[0m
issue=issue-file-name; noesc;
[1mDescription:[0m
This module allows you to prepend an issue file to the username
prompt. It also by default parses escape codes in the issue file
similar to some common getty's (using \x format).
Recognized escapes:
+o d - current date
+o s - operating system name
+o l - name of this tty
+o m - architecture of this system (i686, sparc, powerpc, ...)
+o n - hostname of this system
+o o - domainname of this system
+o r - release number of the operation system (eg. 2.2.12)
+o t - current time
+o u - number of users currently logged in
+o U - same as u, except it is suffixed with "user" or "users"
(eg. "1 user" or "10 users"
+o v - version/build-date of the operating system (eg. "#3 Mon
Aug 23 14:38:16 EDT 1999" on Linux).
The behavior of this module can be modified with one of the
following flags:
+o issue - the file to output if not using the default
+o noesc - turns off escape code parsing
[1mExamples/suggested usage:[0m
login auth pam_issue.so issue=/etc/issue
[1m6.10. The Kerberos 4 module.[0m
[1m6.10.1. Synopsis[0m
[1mModule Name:[0m
pam_krb4
[1mAuthor:[0m
Derrick J. Brashear <shadow@dementia.org>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
authentication; password; session
[1mCryptographically sensitive:[0m
uses API
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
libraries - libkrb, libdes, libcom_err, libkadm; and a set of
Kerberos include files.
[1mNetwork aware:[0m
Gets Kerberos ticket granting ticket via a Kerberos key
distribution center reached via the network.
[1m6.10.2. Overview of module[0m
This module provides an interface for doing Kerberos verification of a
user's password, getting the user a Kerberos ticket granting ticket
for use with the Kerberos ticket granting service, destroying the
user's tickets at logout time, and changing a Kerberos password.
[1m6.10.3. Session component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This component of the module currently sets the user's KRBTKFILE
environment variable (although there is currently no way to
export this), as well as deleting the user's ticket file upon
logout (until PAM_CRED_DELETE is supported by [4mlogin[24m).
[1mExamples/suggested usage:[0m
This part of the module won't be terribly useful until we can
change the environment from within a Linux-PAM module.
[1m6.10.4. Password component[0m
[1mRecognized arguments:[0m
use_first_pass; try_first_pass
[1mDescription:[0m
This component of the module changes a user's Kerberos password
by first getting and using the user's old password to get a
session key for the password changing service, then sending a
new password to that service.
[1mExamples/suggested usage:[0m
This should only be used with a real Kerberos v4 kadmind. It
cannot be used with an AFS kaserver unless special provisions
are made. Contact the module author for more information.
[1m6.10.5. Authentication component[0m
[1mRecognized arguments:[0m
use_first_pass; try_first_pass
[1mDescription:[0m
This component of the module verifies a user's Kerberos password
by requesting a ticket granting ticket from the Kerberos server
and optionally using it to attempt to retrieve the local
computer's host key and verifying using the key file on the
local machine if one exists.
It also writes out a ticket file for the user to use later, and
deletes the ticket file upon logout (not until PAM_CRED_DELETE
is called from [4mlogin[24m).
[1mExamples/suggested usage:[0m
This module can be used with a real Kerberos server using MIT v4
Kerberos keys. The module or the system Kerberos libraries may
be modified to support AFS style Kerberos keys. Currently this
is not supported to avoid cryptography constraints.
[1m6.11. The last login module[0m
[1m6.11.1. Synopsis[0m
[1mModule Name:[0m
pam_lastlog
[1mAuthor:[0m
Andrew G. Morgan <morgan@kernel.org>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
auth
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
uses information contained in the /var/log/lastlog file.
[1mNetwork aware:[0m
[1m6.11.2. Overview of module[0m
This session module maintains the /var/log/lastlog file. Adding an
open entry when called via the pam_open_seesion() function and
completing it when pam_close_session() is called. This module can
also display a line of information about the last login of the user.
If an application already performs these tasks, it is not necessary to
use this module.
[1m6.11.3. Session component[0m
[1mRecognized arguments:[0m
debug; nodate; noterm; nohost; silent; never
[1mDescription:[0m
This module can be used to provide a ``Last login on ...''
message. when the user logs into the system from what ever
application uses the PAM libraries. In addition, the module
maintains the /var/log/lastlog file.
The behavior of this module can be modified with one of the
following flags:
+o debug - write more information to syslog(3).
+o nodate - neglect to give the date of the last login when
displaying information about the last login on the system.
+o noterm - neglect to diplay the terminal name on which the
last login was attempt.
+o nohost - neglect to indicate from which host the last login
was attempted.
+o silent - neglect to inform the user about any previous login:
just update the /var/log/lastlog file.
+o 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.
[1mExamples/suggested usage:[0m
This module can be used to indicate that the user has new mail
when they [4mlogin[24m to the system. Here is a sample entry for your
/etc/pam.d/XXX file:
#
# When were we last here?
#
session optional pam_lastlog.so
Note, some applications may perform this function themselves. In
such cases, this module is not necessary.
[1m6.12. The resource limits module[0m
[1m6.12.1. Synopsis[0m
[1mModule Name:[0m
pam_limits
[1mAuthors:[0m
Cristian Gafton <gafton@redhat.com>
Thanks are also due to Elliot Lee <sopwith@redhat.com> for his
comments on improving this module.
[1mMaintainer:[0m
Cristian Gafton - 1996/11/20
[1mManagement groups provided:[0m
session
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
requires an /etc/security/limits.conf file and kernel support
for resource limits. Also uses the library, libpwdb.
[1mNetwork aware:[0m
[1m6.12.2. Overview of module[0m
This module, through the [1mLinux-PAM [4m[22mopen[24m-session hook, sets limits on
the system resources that can be obtained in a user-session. Its
actions are dictated more explicitly through the configuration file
discussed below.
[1m6.12.3. Session component[0m
[1mRecognized arguments:[0m
debug; conf=/path/to/file.conf
[1mDescription:[0m
Through the contents of the configuration file,
/etc/security/limits.conf, resource limits are placed on users'
sessions. Users of uid=0 are not affected by this restriction.
The behavior of this module can be modified with the following
arguments:
+o debug - verbose logging to syslog(3).
+o conf=/path/to/file.conf - indicate an alternative [4mlimits[0m
configuration file to the default.
+o 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.
[1mExamples/suggested usage:[0m
In order to use this module the system administrator must first
create a [4mroot-only-readable[24m file (default is
/etc/security/limits.conf). This file describes the resource
limits the superuser wishes to impose on users and groups. No
limits are imposed on uid=0 accounts.
Each line of the configuration file describes a limit for a user
in the form:
<domain> <type> <item> <value>
The fields listed above should be filled as follows...
<domain> can be:
+o a username
+o a groupname, with @group syntax
+o the wild-card *, for default entry
<type> can have the three values:
+o hard for enforcing [4mhard[24m resource limits. These limits are set
by the superuser and enforced by the Linux Kernel. The user
cannot raise his requirement of system resources above such
values.
+o soft for enforcing [4msoft[24m resource limits. These limits are
ones that the user can move up or down within the permitted
range by any pre-exisiting [4mhard[24m limits. The values specified
with this token can be thought of as [4mdefault[24m values, for
normal system usage.
+o - for enforcing both [4msoft[24m and [4mhard[24m limits together.
<item> can be one of the following:
+o core - limits the core file size (KB)
+o data - max data size (KB)
+o fsize - maximum filesize (KB)
+o memlock - max locked-in-memory address space (KB)
+o nofile - max number of open files
+o rss - max resident set size (KB)
+o stack - max stack size (KB)
+o cpu - max CPU time (MIN)
+o nproc - max number of processes
+o as - address space limit
+o maxlogins - max number of logins for this user.
+o priority - the priority to run user process with
Note, if you specify a type of ``-'' but neglect to supply the item
and value fields then the module will never enforce any limits on
the corresponding user/group-members etc. . Note, the first entry
of the form which applies to the authenticating user will override
all other entries in the limits configuration file. In such cases,
the pam_limits module will always return PAM_SUCCESS.
In general, individual limits have priority over group limits, so
if you impose no limits for admin group, but one of the members in
this group have a limits line, the user will have its limits set
according to this line.
Also, please note that all limit settings are set [4mper[24m [4mlogin[24m. They
are not global, nor are they permanent; existing only for the
duration of the session.
In the [4mlimits[24m configuration file, the ``#'' character introduces a
comment - after which the rest of the line is ignored.
The pam_limits module does its best to report configuration
problems found in its configuration file via syslog(3).
The following is an example configuration file:
# EXAMPLE /etc/security/limits.conf file:
# =======================================
# <domain> <type> <item> <value>
* soft core 0
* hard rss 10000
@student hard nproc 20
@faculty soft nproc 20
@faculty hard nproc 50
ftp hard nproc 0
@student - maxlogins 4
Note, the use of soft and hard limits for the same resource (see
@faculty) -- this establishes the [4mdefault[24m and permitted [4mextreme[0m
level of resources that the user can obtain in a given service-ses-
sion.
For the services that need resources limits (login for example) put
the following line in /etc/pam.conf as the last line for that
service (usually after the pam_unix session line:
#
# Resource limits imposed on login sessions via pam_limits
#
login session required pam_limits.so
[1m6.13. The list-file module[0m
[1m6.13.1. Synopsis[0m
[1mModule Name:[0m
pam_listfile
[1mAuthor:[0m
Elliot Lee <sopwith@cuc.edu>
[1mMaintainer:[0m
Red Hat Software:
Michael K. Johnson <johnsonm@redhat.com> 1996/11/18
(if unavailable, contact Elliot Lee <sopwith@cuc.edu>).
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
clean
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.13.2. Overview of module[0m
The list-file module provides a way to deny or allow services based on
an arbitrary file.
[1m6.13.3. Authentication component[0m
[1mRecognized arguments:[0m
onerr=succeed|fail; sense=allow|deny; file=[4mfilename[24m;
item=user|tty|rhost|ruser|group|shell apply=user|@group
[1mDescription:[0m
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 [4mfilename[24m. [4mfilename[0m
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 [4mfilename[24m 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=[4musername[24m) or
a given group (apply=@[4mgroupname[24m). This added restriction is
only meaningful when used with the tty, rhost and shell [4mitems[24m.
Besides this last one, all arguments should be specified; do not
count on any default behavior, as it is subject to change.
No credentials are awarded by this module.
[1mExamples/suggested usage:[0m
Classic ``ftpusers'' authentication can be implemented with this
entry in /etc/pam.conf:
#
# deny ftp-access to users listed in the /etc/ftpusers file
#
ftp auth required pam_listfile.so \
onerr=succeed item=user sense=deny file=/etc/ftpusers
Note, users listed in /etc/ftpusers file are (counterintuitively)
[1mnot [22mallowed access to the ftp service.
To allow login access only for certain users, you can use a
pam.conf entry like this:
#
# permit login to users listed in /etc/loginusers
#
login auth required pam_listfile.so \
onerr=fail item=user sense=allow file=/etc/loginusers
For this example to work, all users who are allowed to use the
login service should be listed in the file /etc/loginusers. Unless
you are explicitly trying to lock out root, make sure that when you
do this, you leave a way for root to log in, either by listing root
in /etc/loginusers, or by listing a user who is able to [4msu[24m to the
root account.
[1m6.14. The mail module[0m
[1m6.14.1. Synopsis[0m
[1mModule Name:[0m
pam_mail
[1mAuthor:[0m
Andrew G. Morgan <morgan@linux.kernel.org>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
Authentication (credential) Session (open)
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Default mail directory /var/spool/mail/
[1mNetwork aware:[0m
[1m6.14.2. Overview of module[0m
This module looks at the user's mail directory and indicates whether
the user has any mail in it.
[1m6.14.3. Session component[0m
[1mRecognized arguments:[0m
debug; dir=[4mdirectory-name[24m; nopen; close; noenv; empty;
hash=[4mhashcount[24m; standard; quiet;
[1mDescription:[0m
This module provides the ``you have new mail'' service to the
user. It can be plugged into any application that has credential
hooks. It gives a single message indicating the [4mnewness[24m of any
mail it finds in the user's mail folder. This module also sets
the [1mLinux-PAM [22menvironment variable, MAIL, to the user's mail
directory.
The behavior of this module can be modified with one of the
following flags:
+o debug - write more information to syslog(3).
+o dir=[4mpathname[24m - look for the users' mail in an alternative
directory given by [4mpathname[24m. The default location for mail
is /var/spool/mail. Note, if the supplied [4mpathname[24m is
prefixed by a `~', the directory is interpreted as indicating
a file in the user's home directory.
+o nopen - instruct the module to [4mnot[24m print any mail information
when the user's credentials are acquired. This flag is useful
to get the MAIL environment variable set, but to not display
any information about it.
+o close - instruct the module to indicate if the user has any
mail at the as the user's credentials are revoked.
+o noenv - do not set the MAIL environment variable.
+o empty - indicate that the user's mail directory is empty if
this is found to be the case.
+o hash=[4mhashcount[24m - mail directory hash depth. For example, a
[4mhashcount[24m of 2 would make the mailfile be
/var/spool/mail/u/s/user.
+o standard - old style "You have..." format which doesn't show
the mail spool being used. this also implies "empty"
+o quiet - only report when there is new mail.
[1mExamples/suggested usage:[0m
This module can be used to indicate that the user has new mail
when they [4mlogin[24m to the system. Here is a sample entry for your
/etc/pam.conf file:
#
# do we have any mail?
#
login session optional pam_mail.so
Note, if the mail spool file (be it /var/spool/mail/$USER or a
pathname given with the dir= parameter) is a directory then
pam_mail assumes it is in the [4mQmail[24m [4mMaildir[24m format.
Note, some applications may perform this function themselves. In
such cases, this module is not necessary.
[1m6.14.4. Authentication component[0m
Then authentication companent works the same as the session component,
except that everything is done during the pam_setcred() phase.
[1m6.15. Create home directories on initial login[0m
[1m6.15.1. Synopsis[0m
[1mModule Name:[0m
pam_mkhomedir
[1mAuthor:[0m
Jason Gunthorpe <jgg@ualberta.ca>
[1mMaintainer:[0m
Ben Collins <bcollins@debian.org>
[1mManagement groups provided:[0m
Session
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.15.2. Overview of module[0m
Creates home directories on the fly for authenticated users.
[1m6.15.3. Session component[0m
[1mRecognized arguments:[0m
debug; skel=skeleton-dir; umask=octal-umask;
[1mDescription:[0m
This module is useful for distributed systems where the user
account is managed in a central database (such as NIS, NIS+, or
LDAP) and accessed through miltiple systems. It frees the
administrator from having to create a default home directory on
each of the systems by creating it upon the first succesfully
authenticated login of that user. The skeleton directory
(usually /etc/skel/) is used to copy default files and also
set's a umask for the creation.
The behavior of this module can be modified with one of the
following flags:
+o skel - The skeleton directory for default files to copy to
the new home directory.
+o umask - An octal for of the same format as you would pass to
the shells umask command.
[1mExamples/suggested usage:[0m
session required pam_mkhomedir.so skel=/etc/skel/
umask=0022
[1m6.16. Output the motd file[0m
[1m6.16.1. Synopsis[0m
[1mModule Name:[0m
pam_motd
[1mAuthor:[0m
Ben Collins <bcollins@debian.org>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
Session (open)
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.16.2. Overview of module[0m
This module outputs the motd file ([4m/etc/motd[24m by default) upon
successful login.
[1m6.16.3. Session component[0m
[1mRecognized arguments:[0m
debug; motd=motd-file-name;
[1mDescription:[0m
This module allows you to have arbitrary motd's (message of the
day) output after a succesful login. By default this file is
[4m/etc/motd[24m, but is configurable to any file.
The behavior of this module can be modified with one of the
following flags:
+o motd - the file to output if not using the default.
[1mExamples/suggested usage:[0m
login session pam_motd.so motd=/etc/motd
[1m6.17. The no-login module[0m
[1m6.17.1. Synopsis[0m
[1mModule Name:[0m
pam_nologin
[1mAuthor:[0m
Written by Michael K. Johnson <johnsonm@redhat.com>
(based on code taken from a module written by Andrew G. Morgan
<morgan@parc.power.net>).
[1mMaintainer:[0m
Michael K. Johnson <johnsonm@redhat.com>
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
1 warning about dropping const
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.17.2. Overview of module[0m
Provides standard Unix [4mnologin[24m authentication.
[1m6.17.3. Authentication component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
Provides standard Unix [4mnologin[24m authentication. If the file
/etc/nologin exists, only root is allowed to log in; other users
are turned away with an error message. All users (root or
otherwise) are shown the contents of /etc/nologin.
If the file /etc/nologin does not exist, this module succeeds
silently.
[1mExamples/suggested usage:[0m
In order to make this module effective, all login methods should
be secured by it. It should be used as a required method listed
before any sufficient methods in order to get standard Unix
nologin semantics.
[1m6.18. The promiscuous module[0m
[1m6.18.1. Synopsis[0m
[1mModule Name:[0m
pam_permit
[1mAuthor:[0m
Andrew G. Morgan, <morgan@parc.power.net>
[1mMaintainer:[0m
Linux-PAM maintainer.
[1mManagement groups provided:[0m
account; authentication; password; session
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
VERY LOW. Use with extreme caution.
[1mClean code base:[0m
Clean.
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.18.2. Overview of module[0m
This module is very dangerous. It should be used with extreme caution.
Its action is always to permit access. It does nothing else.
[1m6.18.3. Account+Authentication+Password+Session components[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
No matter what management group, the action of this module is to
simply return PAM_SUCCESS -- operation successful.
In the case of authentication, the user's name will be acquired.
Many applications become confused if this name is unknown.
[1mExamples/suggested usage:[0m
It is seldom a good idea to use this module. However, it does
have some legitimate uses. For example, if the system-
administrator wishes to turn off the account management on a
workstation, and at the same time continue to allow logins, then
she might use the following configuration file entry for login:
#
# add this line to your other login entries to disable account
# management, but continue to permit users to log in...
#
login account required pam_permit.so
[1m6.19. The Password-Database module[0m
[1m6.19.1. Synopsis[0m
[1mModule Name:[0m
pam_pwdb
[1mAuthor:[0m
Cristian Gafton <gafton@redhat.com>
and Andrew G. Morgan <morgan@kernel.org>
[1mMaintainer:[0m
Authors.
[1mManagement groups provided:[0m
account; authentication; password; session
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires properly configured libpwdb
[1mNetwork aware:[0m
[1m6.19.2. Overview of module[0m
This module is a pluggable replacement for the pam_unix_.. modules.
It uses the generic interface of the [4mPassword[24m [4mDatabase[24m library
http://linux.kernel.org/morgan/libpwdb/index.html.
[1m6.19.3. Account component[0m
[1mRecognized arguments:[0m
debug
[1mDescription:[0m
The debug argument makes the accounting functions of this module
syslog(3) more information on its actions. (Remaining arguments
supported by the other functions of this module are silently
ignored, but others are logged as errors through syslog(3)).
Based on the following pwdb_elements: expire; last_change;
max_change; defer_change; warn_change, this module performs the
task of establishing the status of the user's account and
password. In the case of the latter, it may offer advice to the
user on changing their password or, through the
PAM_AUTHTOKEN_REQD return, delay giving service to the user
until they have established a new password. The entries listed
above are documented in the [4mPassword[24m [4mDatabase[24m [4mLibrary[24m [4mGuide[24m (see
pointer above). Should the user's record not contain one or more
of these entries, the corresponding [4mshadow[24m check is not
performed.
[1mExamples/suggested usage:[0m
In its accounting mode, this module can be inserted as follows:
#
# Ensure users account and password are still active
#
login account required pam_pwdb.so
[1m6.19.4. Authentication component[0m
[1mRecognized arguments:[0m
debug; use_first_pass; try_first_pass; nullok; nodelay; likeauth
[1mDescription:[0m
The debug argument makes the authentication functions of this
module syslog(3) more information on its actions.
The default action of this module is to not permit the user
access to a service if their [4mofficial[24m password is blank. The
nullok argument overrides this default.
When given the argument try_first_pass, before prompting the
user for their password, the module first tries the previous
stacked auth-module's password in case that satisfies this
module as well. The argument use_first_pass forces the module to
use such a recalled password and will never prompt the user - if
no password is available or the password is not appropriate, the
user will be denied access.
The argument, nodelay, can be used to discourage the
authentication component from requesting a delay should the
authentication as a whole fail. The default action is for the
module to request a delay-on-failure of the order of one second.
Remaining arguments, supported by the other functions of this
module, are silently ignored. Other arguments are logged as
errors through syslog(3).
A helper binary, pwdb_chkpwd, is provided to check the user's
password when it is stored in a read protected database. This
binary is very simple and will only check the password of the
user invoking it. It is called transparently on behalf of the
user by the authenticating component of this module. In this
way it is possible for applications like [4mxlock[24m to work without
being setuid-root.
The likeauth argument makes the module return the same value
when called as a credential setting module and an authentication
module. This will help libpam take a sane path through the auth
component of your configuration file.
[1mExamples/suggested usage:[0m
The correct functionality of this module is dictated by having
an appropriate /etc/pwdb.conf file, the user databases specified
there dictate the source of the authenticated user's record.
[1m6.19.5. Password component[0m
[1mRecognized arguments:[0m
debug; nullok; not_set_pass; use_authtok; try_first_pass;
use_first_pass; md5; bigcrypt; shadow; radius; unix
[1mDescription:[0m
This part of the pam_pwdb module performs the task of updating
the user's password. Thanks to the flexibility of libpwdb this
module is able to move the user's password from one database to
another, perhaps securing the user's database entry in a dynamic
manner ([4mthis[24m [4mis[24m [4mvery[24m [4mALPHA[24m [4mcode[24m [4mat[24m [4mthe[24m [4mmoment![24m) - this is the
purpose of the shadow, radius and unix arguments.
In the case of conventional unix databases (which store the
password encrypted) the md5 argument is used to do the
encryption with the MD5 function as opposed to the [4mconventional[0m
crypt(3) call. As an alternative to this, the bigcrypt argument
can be used to encrypt more than the first 8 characters of a
password with DEC's (Digital Equipment Cooperation) `C2'
extension to the standard UNIX crypt() algorithm.
The nullok module is used to permit the changing of a password
[4mfrom[24m an empty one. Without this argument, empty passwords are
treated as account-locking ones.
The argument use_first_pass is used to lock the choice of old
and new passwords to that dictated by the previously stacked
password module. The try_first_pass argument is used to avoid
the user having to re-enter an old password when pam_pwdb
follows a module that possibly shared the user's old password -
if this old password is not correct the user will be prompted
for the correct one. The argument use_authtok is used to [4mforce[0m
this module to set the new password to the one provided by the
previously stacked password module (this is used in an example
of the stacking of the [4mCracklib[24m module documented above).
The not_set_pass argument is used to inform the module that it
is not to pay attention to/make available the old or new
passwords from/to other (stacked) password modules.
The debug argument makes the password functions of this module
syslog(3) more information on its actions. Other arguments may
be logged as erroneous to syslog(3).
[1mExamples/suggested usage:[0m
An example of the stacking of this module with respect to the
pluggable password checking module, pam_cracklib, is given in
that modules section above.
[1m6.19.6. Session component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
No arguments are recognized by this module component. Its action
is simply to log the username and the service-type to syslog(3).
Messages are logged at the beginning and end of the user's
session.
[1mExamples/suggested usage:[0m
The use of the session modules is straightforward:
#
# pwdb - unix like session opening and closing
#
login session required pam_pwdb.so
[1m6.20. The RADIUS session module[0m
[1m6.20.1. Synopsis[0m
[1mModule Name:[0m
pam_radius
[1mAuthor:[0m
Cristian Gafton <gafton@redhat.com>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
session
[1mCryptographically sensitive:[0m
This module does not deal with passwords
[1mSecurity rating:[0m
[1mClean code base:[0m
gcc reports 1 warning when compiling /usr/include/rpc/clnt.h.
Hey, is not my fault !
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
yes; this is a network module (independent of application).
[1m6.20.2. Overview of module[0m
This module is intended to provide the session service for users
authenticated with a RADIUS server. At the present stage, the only
option supported is the use of the RADIUS server as an accounting
server.
[1m6.20.3. Session component[0m
[1mRecognized arguments:[0m
debug - verbose logging to syslog(3).
[1mDescription:[0m
This module is intended to provide the session service for users
authenticated with a RADIUS server. At the present stage, the
only option supported is the use of the RADIUS server as an
[4maccounting[24m server.
(There are few things which needs to be cleared out first in the
PAM project until one will be able to use this module and expect
it to magically start pppd in response to a RADIUS server
command to use PPP for this user, or to initiate a telnet
connection to another host, or to hang and call back the user
using parameters provided in the RADIUS server response. Most of
these things are better suited for the radius login application.
I hope to make available Real Soon (tm) patches for the login
apps to make it work this way.)
When opening a session, this module sends an ``Accounting-
Start'' message to the RADIUS server, which will
log/update/whatever a database for this user. On close, an
``Accounting-Stop'' message is sent to the RADIUS server.
This module has no other prerequisites for making it work. One
can install a RADIUS server just for fun and use it as a
centralized accounting server and forget about wtmp/last/sac
etc. .
[1mExamples/suggested usage:[0m
For the services that need this module ([4mlogin[24m for example) put
the following line in /etc/pam.conf as the last line for that
service (usually after the pam_unix session line):
login session required pam_radius.so
Replace login for each service you are using this module.
This module make extensive use of the API provided in libpwdb
0.54preB or later. By default, it will read the radius server
configuration (hostname and secret) from /etc/raddb/server. This
is a default compiled into libpwdb, and curently there is no way to
modify this default without recompiling libpwdb. I am working on
extending the radius support from libpwdb to provide a possibility
to make this runtime-configurable.
Also please note that libpwdb will require also the RADIUS
dictionary to be present (/etc/raddb/dictionary).
[1m6.21. The rhosts module[0m
[1m6.21.1. Synopsis[0m
[1mModule Name:[0m
pam_rhosts_auth
[1mAuthor:[0m
Al Longyear <longyear@netcom.com>
[1mMaintainer:[0m
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
Clean.
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
Standard inet_addr(), gethostbyname() function calls.
[1m6.21.2. Overview of module[0m
This module performs the standard network authentication for services,
as used by traditional implementations of [4mrlogin[24m and [4mrsh[24m etc.
[1m6.21.3. Authentication component[0m
[1mRecognized arguments:[0m
no_hosts_equiv; no_rhosts; debug; no_warn; privategroup;
promiscuous; suppress
[1mDescription:[0m
The authentication mechanism of this module is based on the
contents of two files; /etc/hosts.equiv (or _PATH_HEQUIV in
#include <netdb.h>) and ~/.rhosts. Firstly, hosts listed in the
former file are treated as equivalent to the localhost.
Secondly, entries in the user's own copy of the latter file is
used to map "remote-host remote-user" pairs to that user's
account on the current host. Access is granted to the user if
their host is present in /etc/hosts.equiv and their remote
account is identical to their local one, or if their remote
account has an entry in their personal configuration file.
Some restrictions are applied to the attributes of the user's
personal configuration file: it must be a regular file (as
defined by S_ISREG(x) of POSIX.1); it must be owned by the
[4msuperuser[24m or the user; it must not be writable by any user
besides its owner.
The module authenticates a remote user (internally specified by
the item PAM_RUSER) connecting from the remote host (internally
specified by the item PAM_RHOST). Accordingly, for applications
to be compatible this authentication module they must set these
items prior to calling pam_authenticate(). The module is not
capable of independently probing the network connection for such
information.
In the case of root-access, the /etc/host.equiv file is [4mignored[0m
unless the hosts_equiv_rootok option should be used. Instead,
the superuser must have a correctly configured personal
configuration file.
The behavior of the module is modified by flags:
+o debug - log more information to syslog(3). (XXX - actually,
this module does not do any logging currently, please
volunteer to fix this!)
+o no_warn - do not give verbal warnings to the user about
failures etc. (XXX - this module currently does not issue any
warnings, please volunteer to fix this!)
+o no_hosts_equiv - ignore the contents of the /etc/hosts.equiv
file.
+o hosts_equiv_rootok - allow the use of /etc/hosts.equiv for
superuser. Without this option /etc/hosts.equiv is not
consulted for the superuser account. This option has no
effect if the no_hosts_equiv option is used.
+o no_rhosts - ignore the contents of all user's personal
configuration file ~/.rhosts.
+o privategroup - normally, the ~/.rhosts file must not be
writable by anyone other than its owner. This option
overlooks group write access in the case that the group owner
of this file has the same name as the user being
authenticated. To lessen the security problems associated
with this option, the module also checks that the user is the
only member of their private group.
+o promiscuous - A host entry of `+' will lead to all hosts
being granted access. Without this option, '+' entries will
be ignored. Note, that the debug option will syslog a warning
in this latter case.
+o suppress - This will prevent the module from syslog(3)ing a
warning message when this authentication fails. This option
is mostly for keeping logs free of meaningless errors, in
particular when the module is used with the sufficient
control flag.
[1mExamples/suggested usage:[0m
To allow users to login from trusted remote machines, you should
try adding the following line to your /etc/pam.conf file [4mbefore[0m
the line that would otherwise prompt the user for a password:
#
# No passwords required for users from hosts listed above.
#
login auth sufficient pam_rhosts_auth.so no_rhosts
Note, in this example, the system administrator has turned off all
[4mpersonal[24m [4mrhosts[24m configuration files. Also note, that this module
can be used to [4monly[24m allow remote login from hosts specified in the
/etc/host.equiv file, by replacing sufficient in the above example
with required.
[1m6.22. The root access module[0m
[1m6.22.1. Synopsis[0m
[1mModule Name:[0m
pam_rootok
[1mAuthor:[0m
Andrew G. Morgan <morgan@parc.power.net>
[1mMaintainer:[0m
[1mLinux-PAM [22mmaintainer
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
Clean.
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.22.2. Overview of module[0m
This module is for use in situations where the superuser wishes to
gain access to a service without having to enter a password.
[1m6.22.3. Authentication component[0m
[1mRecognized arguments:[0m
debug
[1mDescription:[0m
This module authenticates the user if their uid is 0.
Applications that are created [4msetuid[24m-root generally retain the
uid of the user but run with the authority of an enhanced
[4meffective-[24muid. It is the real uid that is checked.
[1mExamples/suggested usage:[0m
In the case of the su application the historical usage is to
permit the superuser to adopt the identity of a lesser user
without the use of a password. To obtain this behavior under
Linux-PAM the following pair of lines are needed for the
corresponding entry in the configuration file:
#
# su authentication. Root is granted access by default.
#
su auth sufficient pam_rootok.so
su auth required pam_unix_auth.so
Note. For programs that are run by the superuser (or started when
the system boots) this module should not be used to authenticate
users.
[1m6.23. The securetty module[0m
[1m6.23.1. Synopsis[0m
[1mModule Name:[0m
pam_securetty
[1mAuthor[s]:[0m
Elliot Lee <sopwith@cuc.edu>
[1mMaintainer:[0m
Red Hat Software:
[4mcurrently[24m Michael K. Johnson <johnsonm@redhat.com>
(if unavailable, contact Elliot Lee <sopwith@cuc.edu>).
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
/etc/securetty file
[1mNetwork aware:[0m
Requires the application to fill in the PAM_TTY item correctly
in order to act meaningfully.
[1m6.23.2. Overview of module[0m
Provides standard Unix securetty checking.
[1m6.23.3. Authentication component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
Provides standard Unix securetty checking, which causes
authentication for root to fail unless PAM_TTY is set to a
string listed in the /etc/securetty file. For all other users,
it succeeds.
[1mExamples/suggested usage:[0m
For canonical usage, should be listed as a required
authentication method before any sufficient authentication
methods.
[1m6.24. The login counter (tallying) module[0m
[1m6.24.1. Synopsis[0m
[1mModule Name:[0m
pam_tally
[1mAuthor[s]:[0m
Tim Baverstock
[1mMaintainer:[0m
[1mManagement groups provided:[0m
auth; account
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
A faillog file (default location /var/log/faillog)
[1mNetwork aware:[0m
[1m6.24.2. Overview of module[0m
This module maintains a count of attempted accesses, can reset count
on success, can deny access if too many attempts fail.
pam_tally comes in two parts: pam_tally.so and pam_tally. The former
is the PAM module and the latter, a stand-alone program. pam_tally is
an (optional) application which can be used to interrogate and
manipulate the counter file. It can display users' counts, set
individual counts, or clear all counts. Setting artificially high
counts may be useful for blocking users without changing their
passwords. For example, one might find it useful to clear all counts
every midnight from a cron job.
The counts file is organized as a binary-word array, indexed by uid.
You can probably make sense of it with od, if you don't want to use
the supplied appliction.
Note, there are some outstanding issues with this module: pam_tally is
very dependant on getpw*() - a database of usernames would be much
more flexible; the `keep a count of current logins' bit has been
#ifdef'd out and you can only reset the counter on successful
authentication, for now.
[1m6.24.2.1. Generic options accepted by both components[0m
+o onerr=(succeed|fail): if something weird happens, such as unable to
open the file, how should the module react?
+o file=[4m/where/to/keep/counts[24m: specify the file location for the
counts. The default location is /var/log/faillog.
[1m6.24.3. Authentication component[0m
[1mRecognized arguments:[0m
onerr=(succeed|fail); file=/where/to/keep/counts; no_magic_root
[1mDescription:[0m
The authentication component of this module increments the
attempted login counter.
[1mExamples/suggested usage:[0m
The module argument no_magic_root is used to indicate that if
the module is invoked by a user with uid=0, then the counter is
incremented. The sys-admin should use this for daemon-launched
services, like telnet/rsh/login. For user launched services,
like su, this argument should be omitted.
By way of more explanation, when a process already running as
root tries to access some service, the access is [4mmagic[24m, and
bypasses pam_tally's checks: this is handy for suing from root
into an account otherwise blocked. However, for services like
telnet or login, which always effectively run from the root
account, root (ie everyone) shouldn't be granted this magic
status, and the flag `no_magic_root' should be set in this
situation, as noted in the summary above.
[1m6.24.4. Account component[0m
[1mRecognized arguments:[0m
onerr=(succeed|fail); file=/where/to/keep/counts; deny=[4mn[24m;
no_magic_root; even_deny_root_account; reset; no_reset;
per_user; no_lock_time
[1mDescription:[0m
The account component can deny access and/or reset the attempts
counter. It also checks to make sure that the counts file is a
plain file and not world writable.
[1mExamples/suggested usage:[0m
The deny=[4mn[24m option is used to deny access if tally for this user
exceeds [4mn[24m. The presence of deny=[4mn[24m changes the default for
reset/no_reset to reset, unless the user trying to gain access
is root and the no_magic_root option has NOT been specified.
The no_magic_root option ensures that access attempts by root
DON'T ignore deny. Use this for daemon-based stuff, like
telnet/rsh/login.
The even_deny_root_account option is used to ensure that the
root account can become unavailable. [1mNote [22mthat magic root trying
to gain root bypasses this, but normal users can be locked out.
The reset option instructs the module to reset count to 0 on
successful entry, even for magic root. The no_reset option is
used to instruct the module to not reset the count on successful
entry. This is the default unless deny exists and the user
attempting access is NOT magic root.
If /var/log/faillog contains a non-zero .fail_max field for this
user then the per_user module argument will ensure that the
module uses this value and not the global deny=[4mn[24m parameter.
The no_lock_time option is for ensuring that the module does not
use the .fail_locktime field in /var/log/faillog for this user.
Normally, failed attempts to access root will [1mNOT [22mcause the root
account to become blocked, to prevent denial-of-service: if your
users aren't given shell accounts and root may only login via su
or at the machine console (not telnet/rsh, etc), this is safe.
If you really want root to be blocked for some given service,
use even_deny_root_account.
[1m6.25. Time control[0m
[1m6.25.1. Synopsis[0m
[1mModule Name:[0m
pam_time
[1mAuthor:[0m
Andrew G. Morgan <morgan@parc.power.net>
[1mMaintainer:[0m
Author
[1mManagement groups provided:[0m
account
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires a configuration file /etc/security/time.conf
[1mNetwork aware:[0m
Through the PAM_TTY item only
[1m6.25.2. Overview of module[0m
Running a well regulated system occasionally involves restricting
access to certain services in a selective manner. This module offers
some time control for access to services offered by a system. Its
actions are determined with a configuration file. This module can be
configured to deny access to (individual) users based on their name,
the time of day, the day of week, the service they are applying for
and their terminal from which they are making their request.
[1m6.25.3. Account component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
This module bases its actions on the rules listed in its
configuration file: /etc/security/pam.conf. Each rule has the
following form,
[4mservices[24m;[4mttys[24m;[4musers[24m;[4mtimes[0m
In words, each rule occupies a line, terminated with a newline or
the beginning of a comment; a `#'. It contains four fields sepa-
rated with semicolons, `;'. The fields are as follows:
+o [4mservices[24m - a logic list of service names that are affected by
this rule.
+o [4mttys[24m - a logic list of terminal names indicating those
terminals covered by the rule.
+o [4muser[24m - a logic list of usernames to which this rule applies
By a logic list we mean a sequence of tokens (associated with
the appropriate PAM_ item), containing no more than one
wildcard character; `*', and optionally prefixed with a
negation operator; `!'. Such a sequence is concatenated with
one of two logical operators: & (logical AND) and | (logical
OR). Two examples are: !morgan&!root, indicating that this
rule does not apply to the user morgan nor to root; and
tty*&!ttyp*, which indicates that the rule applies only to
console terminals but not pseudoterminals.
+o [4mtimes[24m - a logic list of times at which this rule applies. The
format of each element is a day/time-range. The days are
specified by a sequence of two character entries. For
example, MoTuSa, indicates Monday Tuesday and Saturday. Note
that repeated days are [4munset[24m; MoTuMo indicates Tuesday, and
MoWk means all weekdays bar Monday. The two character
combinations accepted are,
Mo Tu We Th Fr Sa Su Wk Wd Al
The last two of these being [4mweekend[24m days and [4mall[24m [4m7[24m [4mdays[24m of the
week respectively.
The time range part is a pair of 24-hour times, [4mHHMM[24m, separated
by a hyphen -- indicating the start and finish time for the
rule. If the finsish time is smaller than the start time, it is
assumed to apply on the following day. For an example,
Mo1800-0300 indicates that the permitted times are Monday night
from 6pm to 3am the following morning.
Note, that the given time restriction is only applied when the
first three fields are satisfied by a user's application for
service.
For convenience and readability a rule can be extended beyond a
single line with a `\[4mnewline[24m'.
[1mExamples/suggested usage:[0m
The use of this module is initiated with an entry in the [1mLinux-[0m
[1mPAM [22mconfiguration file of the following type:
#
# apply pam_time accounting to login requests
#
login account required pam_time.so
where, here we are applying the module to the [4mlogin[24m application.
Some examples of rules that can be placed in the
/etc/security/time.conf configuration file are the following:
login ; tty* & !ttyp* ; !root ; !Al0000-2400
all users except for root are denied access to console-login
at all times.
games ; * ; !waster ; Wd0000-2400 | Wk1800-0800
games (configured to use Linux-PAM) are only to be accessed
out of working hours. This rule does not apply to the user
waster.
Note, currently there is no daemon enforcing the end of a session.
This needs to be remedied.
Poorly formatted rules are logged as errors using syslog(3).
[1m6.26. The Unix Password module[0m
[1m6.26.1. Synopsis[0m
[1mModule Name:[0m
pam_unix
[1mAuthor:[0m
[1mMaintainer:[0m
[1mManagement groups provided:[0m
account; authentication; password; session
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
[1m6.26.2. Overview of module[0m
This is the standard Unix authentication module. It uses standard
calls from the system's libraries to retrieve and set account
information as well as authentication. Usually this is obtained from
the /etc/passwd and the /etc/shadow file as well if shadow is enabled.
[1m6.26.3. Account component[0m
[1mRecognized arguments:[0m
debug; audit
[1mDescription:[0m
The debug argument makes the accounting functions of this module
syslog(3) more information on its actions. (Remaining arguments
supported by the other functions of this module are silently
ignored, but others are logged as errors through syslog(3)). The
audit argument causes even more logging.
Based on the following shadow elements: expire; last_change;
max_change; min_change; warn_change, this module performs the
task of establishing the status of the user's account and
password. In the case of the latter, it may offer advice to the
user on changing their password or, through the
PAM_AUTHTOKEN_REQD return, delay giving service to the user
until they have established a new password. The entries listed
above are documented in the [4mGNU[24m [4mLibc[24m info documents. Should the
user's record not contain one or more of these entries, the
corresponding [4mshadow[24m check is not performed.
[1mExamples/suggested usage:[0m
In its accounting mode, this module can be inserted as follows:
#
# Ensure users account and password are still active
#
login account required pam_unix.so
[1m6.26.4. Authentication component[0m
[1mRecognized arguments:[0m
debug; audit; use_first_pass; try_first_pass; nullok; nodelay
[1mDescription:[0m
The debug argument makes the authentication functions of this
module syslog(3) more information on its actions. The audit
causes even more information to be logged.
The default action of this module is to not permit the user
access to a service if their [4mofficial[24m password is blank. The
nullok argument overrides this default.
When given the argument try_first_pass, before prompting the
user for their password, the module first tries the previous
stacked auth-module's password in case that satisfies this
module as well. The argument use_first_pass forces the module to
use such a recalled password and will never prompt the user - if
no password is available or the password is not appropriate, the
user will be denied access.
The argument, nodelay, can be used to discourage the
authentication component from requesting a delay should the
authentication as a whole fail. The default action is for the
module to request a delay-on-failure of the order of one second.
Remaining arguments, supported by the other functions of this
module, are silently ignored. Other arguments are logged as
errors through syslog(3).
A helper binary, unix_chkpwd, is provided to check the user's
password when it is stored in a read protected database. This
binary is very simple and will only check the password of the
user invoking it. It is called transparently on behalf of the
user by the authenticating component of this module. In this
way it is possible for applications like [4mxlock[24m to work without
being setuid-root.
[1mExamples/suggested usage:[0m
The correct functionality of this module is dictated by having
an appropriate /etc/nsswitch.conf file, the user databases
specified there dictate the source of the authenticated user's
record.
In its authentication mode, this module can be inserted as
follows:
#
# Authenticate the user
#
login auth required pam_unix.so
[1m6.26.5. Password component[0m
[1mRecognized arguments:[0m
debug; audit; nullok; not_set_pass; use_authtok; try_first_pass;
use_first_pass; md5; bigcrypt; shadow; nis; remember
[1mDescription:[0m
This part of the pam_unix module performs the task of updating
the user's password.
In the case of conventional unix databases (which store the
password encrypted) the md5 argument is used to do the
encryption with the MD5 function as opposed to the [4mconventional[0m
crypt(3) call. As an alternative to this, the bigcrypt argument
can be used to encrypt more than the first 8 characters of a
password with DEC's (Digital Equipment Cooperation) `C2'
extension to the standard UNIX crypt() algorithm.
The nullok argument is used to permit the changing of a password
[4mfrom[24m an empty one. Without this argument, empty passwords are
treated as account-locking ones.
The argument use_first_pass is used to lock the choice of old
and new passwords to that dictated by the previously stacked
password module. The try_first_pass argument is used to avoid
the user having to re-enter an old password when pam_unix
follows a module that possibly shared the user's old password -
if this old password is not correct the user will be prompted
for the correct one. The argument use_authtok is used to [4mforce[0m
this module to set the new password to the one provided by the
previously stacked password module (this is used in an example
of the stacking of the [4mCracklib[24m module documented above).
The not_set_pass argument is used to inform the module that it
is not to pay attention to/make available the old or new
passwords from/to other (stacked) password modules.
The debug argument makes the password functions of this module
syslog(3) more information on its actions. Other arguments may
be logged as erroneous to syslog(3). The audit argument causes
even more information to be logged.
With the nis argument, pam_unix will attempt to use NIS RPC for
setting new passwords.
The remember argument takes one value. This is the number of
most recent passwords to save for each user. These are saved in
/etc/security/opasswd in order to force password change history
and keep the user from alternating between the same password too
frequently.
[1mExamples/suggested usage:[0m
Standard usage:
#
# Change the users password
#
passwd password required pam_unix.so
An example of the stacking of this module with respect to the
pluggable password checking module, pam_cracklib:
#
# Change the users password
#
passwd password required pam_cracklib.so retry=3 minlen=6 difok=3
passwd password required pam_unix.so use_authtok nullok md5
[1m6.26.6. Session component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
No arguments are recognized by this module component. Its action
is simply to log the username and the service-type to syslog(3).
Messages are logged at the beginning and end of the user's
session.
[1mExamples/suggested usage:[0m
The use of the session modules is straightforward:
#
# session opening and closing
#
login session required pam_unix.so
[1m6.27. The userdb module[0m
[1m6.27.1. Synopsis[0m
[1mModule Name:[0m
pam_userdb
[1mAuthor:[0m
Cristian Gafton <gafton@redhat.com>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires Berkeley DB.
[1mNetwork aware:[0m
[1m6.27.2. Overview of module[0m
Look up users in a .db database and verify their password against what
is contained in that database.
[1m6.27.3. Authentication component[0m
[1mRecognized arguments:[0m
debug; icase; dump; db=XXXX; use_authtok; unknown_ok;
[1mDescription:[0m
This module is used to verify a username/password pair against
values stored in a Berkeley DB database. The database is indexed
by the username, and the data fields corresponding to the
username keys are the passwords, in unencrypted form, so caution
must be exercised over the access rights to the DB database
itself..
The module will read the password from the user using the
conversation mechanism. If you are using this module on top of
another authentication module (like pam_pwdb;) then you should
tell that module to read the entered password from the
PAM_AUTHTOK field, which is set by this module.
The action of the module may be modified from this default by
one or more of the following flags in the /etc/pam.d/<service>
file.
+o debug - Supply more debugging information to syslog(3).
+o icase - Perform the password comparisons case insensitive.
+o dump - dump all the entries in the database to the log (eek,
don't do this by default!)
+o db=XXXX - use the database found on pathname XXXX. Note that
Berkeley DB usually adds the needed filename extension for
you, so you should use something like /etc/foodata instead of
/etc/foodata.db.
+o use_authtok - use the authentication token previously
obtained by another that did the conversation with the
application. If this token can not be obtained then the
module will try to converse again. This option can be used
for stacking different modules that need to deal with the
authentication tokens.
+o 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.
[1mExamples/suggested usage:[0m
This is a normal ftp configuration file (usually placed as
/etc/pam.d/ftp on most systems) that will accept for login users
whose username/password pairs are provided in the /tmp/dbtest.db
file:
#%PAM-1.0
auth required pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
auth sufficient pam_userdb.so icase db=/tmp/dbtest
auth required pam_pwdb.so shadow nullok try_first_pass
auth required pam_shells.so
account required pam_pwdb.so
session required pam_pwdb.so
[1m6.28. Warning logger module[0m
[1m6.28.1. Synopsis[0m
[1mModule Name:[0m
pam_warn
[1mAuthor:[0m
Andrew G. Morgan <morgan@parc.power.net>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
authentication; password
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
[1mNetwork aware:[0m
logs information about the remote user and host (if pam-items
are known)
[1m6.28.2. Overview of module[0m
This module is principally for logging information about a proposed
authentication or application to update a password.
[1m6.28.3. Authentication+Password component[0m
[1mRecognized arguments:[0m
[1mDescription:[0m
Log the service, terminal, user, remote user and remote host to
syslog(3). The items are not probed for, but instead obtained
from the standard pam-items.
[1mExamples/suggested usage:[0m
an example is provided in the configuration file section
``above''.
[1m6.29. The wheel module[0m
[1m6.29.1. Synopsis[0m
[1mModule Name:[0m
pam_wheel
[1mAuthor:[0m
Cristian Gafton <gafton@redhat.com>
[1mMaintainer:[0m
Author.
[1mManagement groups provided:[0m
authentication
[1mCryptographically sensitive:[0m
[1mSecurity rating:[0m
[1mClean code base:[0m
[1mSystem dependencies:[0m
Requires libpwdb.
[1mNetwork aware:[0m
[1m6.29.2. Overview of module[0m
Only permit root access to members of the wheel (gid=0) group.
[1m6.29.3. Authentication component[0m
[1mRecognized arguments:[0m
debug; use_uid; trust; deny; group=XXXX
[1mDescription:[0m
This module is used to enforce the so-called [4mwheel[24m group. By
default, it permits root access to the system if the applicant
user is a member of the wheel group (first, the module checks
for the existence of a 'wheel' group. Otherwise the module
defines the group with group-id 0 to be the [4mwheel[24m group).
The action of the module may be modified from this default by
one or more of the following flags in the /etc/pam.conf file.
+o debug - Supply more debugging information to syslog(3).
+o use_uid - This option modifies the behavior of the module by
using the current uid of the process and not the getlogin(3)
name of the user. This option is useful for being able to
jump from one account to another, for example with 'su'.
+o trust - This option instructs the module to return
PAM_SUCCESS should it find the user applying for root
privilege is a member of the wheel group. The default action
is to return PAM_IGNORE in this situation. By using the trust
option it is possible to arrange for wheel-group members to
become root without typing a password. [1mUSE WITH CARE[22m.
+o deny - This is used to reverse the logic of the module's
behavior. If the user is trying to get uid=0 access and is a
member of the wheel group, deny access (for the wheel group,
this is perhaps nonsense!): it is intended for use in
conjunction with the group= argument...
+o group=XXXX - Instead of checking the gid=0 group, use the
user's XXXX group membership for the authentication. Here,
XXXX is the name of the group and [1mnot [22mits numeric identifier.
[1mExamples/suggested usage:[0m
To restrict access to superuser status to the members of the
wheel group, use the following entries in your configuration
file:
#
# root gains access by default (rootok), only wheel members can
# become root (wheel) but Unix authenticate non-root applicants.
#
su auth sufficient pam_rootok.so
su auth required pam_wheel.so
su auth required pam_unix_auth.so
[1m7. Files[0m
/usr/lib/libpam.so.*
the shared library providing applications with access to [1mLinux-[0m
[1mPAM[22m.
/etc/pam.conf
the [1mLinux-PAM [22mconfiguration file.
/usr/lib/security/pam_*.so
the primary location for [1mLinux-PAM [22mdynamically loadable object
files; the modules.
[1m8. See also[0m
+o The [1mLinux-PAM [22mApplication Writers' Guide.
+o The [1mLinux-PAM [22mModule Writers' Guide.
+o The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation
Request For Comments 86.0, October 1995. See this url:
http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz
[1m9. Notes[0m
I intend to put development comments here... like ``at the moment this
isn't actually supported''. At release time what ever is in this
section will be placed in the Bugs section below! :)
Are we going to be able to support the use_mapped_pass module
argument? Anyone know a cheap (free) good lawyer?!
+o This issue may go away, as Sun have investigated adding a new
management group for mappings. In this way, libpam would have
mapping modules that could securely store passwords using strong
cryptography and in such a way that they need not be distributed
with Linux-PAM.
[1m10. Author/acknowledgments[0m
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, 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
[1mLinux-PAM[22m, Sun graciously made the documentation for their
implementation of PAM available. This act greatly accelerated the
development of [1mLinux-PAM[22m.
[1m11. Bugs/omissions[0m
More PAM modules are being developed all the time. It is unlikely that
this document will ever be truely up to date!
This manual is unfinished. Only a partial list of people is credited
for all the good work they have done.
[1m12. Copyright information for this document[0m
Copyright (c) Andrew G. Morgan 1996-9. All rights reserved.
Email: <morgan@linux.kernel.org>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
+o 1. Redistributions of source code must retain the above copyright
notice, and the entire permission notice in its entirety, including
the disclaimer of warranties.
+o 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.
+o 3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior written
permission.
[1mAlternatively[22m, 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 [1minstead of [22mthe 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
DAMAGE.
$Id: pam_source.sgml,v 1.5 2001/03/19 01:46:41 agmorgan Exp $
