TThhee LLiinnuuxx--PPAAMM SSyysstteemm AAddmmiinniissttrraattoorrss'' GGuuiiddee
******** AAnnddrreeww GG.. MMoorrggaann ********
<_m_o_r_g_a_n_@_k_e_r_n_e_l_._o_r_g>
******** TThhoorrsstteenn KKuukkuukk ********
<_k_u_k_u_k_@_t_h_k_u_k_u_k_._d_e>
Version 1.1.2, 31. August 2010
AAbbssttrraacctt
This manual documents what a system-administrator needs to know about the
LLiinnuuxx--PPAAMM library. It covers the correct syntax of the PAM configuration file
and discusses strategies for maintaining a secure system.
===============================================================================
  _1_._ _I_n_t_r_o_d_u_c_t_i_o_n
  _2_._ _S_o_m_e_ _c_o_m_m_e_n_t_s_ _o_n_ _t_h_e_ _t_e_x_t
  _3_._ _O_v_e_r_v_i_e_w
  _4_._ _T_h_e_ _L_i_n_u_x_-_P_A_M_ _c_o_n_f_i_g_u_r_a_t_i_o_n_ _f_i_l_e
        _4_._1_._ _C_o_n_f_i_g_u_r_a_t_i_o_n_ _f_i_l_e_ _s_y_n_t_a_x
        _4_._2_._ _D_i_r_e_c_t_o_r_y_ _b_a_s_e_d_ _c_o_n_f_i_g_u_r_a_t_i_o_n
        _4_._3_._ _E_x_a_m_p_l_e_ _c_o_n_f_i_g_u_r_a_t_i_o_n_ _f_i_l_e_ _e_n_t_r_i_e_s
  _5_._ _S_e_c_u_r_i_t_y_ _i_s_s_u_e_s
        _5_._1_._ _I_f_ _s_o_m_e_t_h_i_n_g_ _g_o_e_s_ _w_r_o_n_g
        _5_._2_._ _A_v_o_i_d_ _h_a_v_i_n_g_ _a_ _w_e_a_k_ _`_o_t_h_e_r_'_ _c_o_n_f_i_g_u_r_a_t_i_o_n
  _6_._ _A_ _r_e_f_e_r_e_n_c_e_ _g_u_i_d_e_ _f_o_r_ _a_v_a_i_l_a_b_l_e_ _m_o_d_u_l_e_s
        _6_._1_._ _p_a_m___a_c_c_e_s_s_ _-_ _l_o_g_d_a_e_m_o_n_ _s_t_y_l_e_ _l_o_g_i_n_ _a_c_c_e_s_s_ _c_o_n_t_r_o_l
        _6_._2_._ _p_a_m___c_r_a_c_k_l_i_b_ _-_ _c_h_e_c_k_s_ _t_h_e_ _p_a_s_s_w_o_r_d_ _a_g_a_i_n_s_t_ _d_i_c_t_i_o_n_a_r_y_ _w_o_r_d_s
        _6_._3_._ _p_a_m___d_e_b_u_g_ _-_ _d_e_b_u_g_ _t_h_e_ _P_A_M_ _s_t_a_c_k
        _6_._4_._ _p_a_m___d_e_n_y_ _-_ _l_o_c_k_i_n_g_-_o_u_t_ _P_A_M_ _m_o_d_u_l_e
        _6_._5_._ _p_a_m___e_c_h_o_ _-_ _p_r_i_n_t_ _t_e_x_t_ _m_e_s_s_a_g_e_s
        _6_._6_._ _p_a_m___e_n_v_ _-_ _s_e_t_/_u_n_s_e_t_ _e_n_v_i_r_o_n_m_e_n_t_ _v_a_r_i_a_b_l_e_s
        _6_._7_._ _p_a_m___e_x_e_c_ _-_ _c_a_l_l_ _a_n_ _e_x_t_e_r_n_a_l_ _c_o_m_m_a_n_d
        _6_._8_._ _p_a_m___f_a_i_l_d_e_l_a_y_ _-_ _c_h_a_n_g_e_ _t_h_e_ _d_e_l_a_y_ _o_n_ _f_a_i_l_u_r_e_ _p_e_r_-_a_p_p_l_i_c_a_t_i_o_n
        _6_._9_._ _p_a_m___f_i_l_t_e_r_ _-_ _f_i_l_t_e_r_ _m_o_d_u_l_e
        _6_._1_0_._ _p_a_m___f_t_p_ _-_ _m_o_d_u_l_e_ _f_o_r_ _a_n_o_n_y_m_o_u_s_ _a_c_c_e_s_s
        _6_._1_1_._ _p_a_m___g_r_o_u_p_ _-_ _m_o_d_u_l_e_ _t_o_ _m_o_d_i_f_y_ _g_r_o_u_p_ _a_c_c_e_s_s
        _6_._1_2_._ _p_a_m___i_s_s_u_e_ _-_ _a_d_d_ _i_s_s_u_e_ _f_i_l_e_ _t_o_ _u_s_e_r_ _p_r_o_m_p_t
        _6_._1_3_._ _p_a_m___k_e_y_i_n_i_t_ _-_ _d_i_s_p_l_a_y_ _t_h_e_ _k_e_y_i_n_i_t_ _f_i_l_e
        _6_._1_4_._ _p_a_m___l_a_s_t_l_o_g_ _-_ _d_i_s_p_l_a_y_ _d_a_t_e_ _o_f_ _l_a_s_t_ _l_o_g_i_n
        _6_._1_5_._ _p_a_m___l_i_m_i_t_s_ _-_ _l_i_m_i_t_ _r_e_s_o_u_r_c_e_s
        _6_._1_6_._ _p_a_m___l_i_s_t_f_i_l_e_ _-_ _d_e_n_y_ _o_r_ _a_l_l_o_w_ _s_e_r_v_i_c_e_s_ _b_a_s_e_d_ _o_n_ _a_n_ _a_r_b_i_t_r_a_r_y_ _f_i_l_e
        _6_._1_7_._ _p_a_m___l_o_c_a_l_u_s_e_r_ _-_ _r_e_q_u_i_r_e_ _u_s_e_r_s_ _t_o_ _b_e_ _l_i_s_t_e_d_ _i_n_ _/_e_t_c_/_p_a_s_s_w_d
        _6_._1_8_._ _p_a_m___l_o_g_i_n_u_i_d_ _-_ _r_e_c_o_r_d_ _u_s_e_r_'_s_ _l_o_g_i_n_ _u_i_d_ _t_o_ _t_h_e_ _p_r_o_c_e_s_s_ _a_t_t_r_i_b_u_t_e
        _6_._1_9_._ _p_a_m___m_a_i_l_ _-_ _i_n_f_o_r_m_ _a_b_o_u_t_ _a_v_a_i_l_a_b_l_e_ _m_a_i_l
        _6_._2_0_._ _p_a_m___m_k_h_o_m_e_d_i_r_ _-_ _c_r_e_a_t_e_ _u_s_e_r_s_ _h_o_m_e_ _d_i_r_e_c_t_o_r_y
        _6_._2_1_._ _p_a_m___m_o_t_d_ _-_ _d_i_s_p_l_a_y_ _t_h_e_ _m_o_t_d_ _f_i_l_e
        _6_._2_2_._ _p_a_m___n_a_m_e_s_p_a_c_e_ _-_ _s_e_t_u_p_ _a_ _p_r_i_v_a_t_e_ _n_a_m_e_s_p_a_c_e
        _6_._2_3_._ _p_a_m___n_o_l_o_g_i_n_ _-_ _p_r_e_v_e_n_t_ _n_o_n_-_r_o_o_t_ _u_s_e_r_s_ _f_r_o_m_ _l_o_g_i_n
        _6_._2_4_._ _p_a_m___p_e_r_m_i_t_ _-_ _t_h_e_ _p_r_o_m_i_s_c_u_o_u_s_ _m_o_d_u_l_e
        _6_._2_5_._ _p_a_m___p_w_h_i_s_t_o_r_y_ _-_ _g_r_a_n_t_ _a_c_c_e_s_s_ _u_s_i_n_g_ _._p_w_h_i_s_t_o_r_y_ _f_i_l_e
        _6_._2_6_._ _p_a_m___r_h_o_s_t_s_ _-_ _g_r_a_n_t_ _a_c_c_e_s_s_ _u_s_i_n_g_ _._r_h_o_s_t_s_ _f_i_l_e
        _6_._2_7_._ _p_a_m___r_o_o_t_o_k_ _-_ _g_a_i_n_ _o_n_l_y_ _r_o_o_t_ _a_c_c_e_s_s
        _6_._2_8_._ _p_a_m___s_e_c_u_r_e_t_t_y_ _-_ _l_i_m_i_t_ _r_o_o_t_ _l_o_g_i_n_ _t_o_ _s_p_e_c_i_a_l_ _d_e_v_i_c_e_s
        _6_._2_9_._ _p_a_m___s_e_l_i_n_u_x_ _-_ _s_e_t_ _t_h_e_ _d_e_f_a_u_l_t_ _s_e_c_u_r_i_t_y_ _c_o_n_t_e_x_t
        _6_._3_0_._ _p_a_m___s_h_e_l_l_s_ _-_ _c_h_e_c_k_ _f_o_r_ _v_a_l_i_d_ _l_o_g_i_n_ _s_h_e_l_l
        _6_._3_1_._ _p_a_m___s_u_c_c_e_e_d___i_f_ _-_ _t_e_s_t_ _a_c_c_o_u_n_t_ _c_h_a_r_a_c_t_e_r_i_s_t_i_c_s
        _6_._3_2_._ _p_a_m___t_a_l_l_y_ _-_ _l_o_g_i_n_ _c_o_u_n_t_e_r_ _(_t_a_l_l_y_i_n_g_)_ _m_o_d_u_l_e
        _6_._3_3_._ _p_a_m___t_a_l_l_y_2_ _-_ _l_o_g_i_n_ _c_o_u_n_t_e_r_ _(_t_a_l_l_y_i_n_g_)_ _m_o_d_u_l_e
        _6_._3_4_._ _p_a_m___t_i_m_e_ _-_ _t_i_m_e_ _c_o_n_t_r_o_l_e_d_ _a_c_c_e_s_s
        _6_._3_5_._ _p_a_m___t_i_m_e_s_t_a_m_p_ _-_ _a_u_t_h_e_n_t_i_c_a_t_e_ _u_s_i_n_g_ _c_a_c_h_e_d_ _s_u_c_c_e_s_s_f_u_l
        _a_u_t_h_e_n_t_i_c_a_t_i_o_n_ _a_t_t_e_m_p_t_s
        _6_._3_6_._ _p_a_m___u_m_a_s_k_ _-_ _s_e_t_ _t_h_e_ _f_i_l_e_ _m_o_d_e_ _c_r_e_a_t_i_o_n_ _m_a_s_k
        _6_._3_7_._ _p_a_m___u_n_i_x_ _-_ _t_r_a_d_i_t_i_o_n_a_l_ _p_a_s_s_w_o_r_d_ _a_u_t_h_e_n_t_i_c_a_t_i_o_n
        _6_._3_8_._ _p_a_m___u_s_e_r_d_b_ _-_ _a_u_t_h_e_n_t_i_c_a_t_e_ _a_g_a_i_n_s_t_ _a_ _d_b_ _d_a_t_a_b_a_s_e
        _6_._3_9_._ _p_a_m___w_a_r_n_ _-_ _l_o_g_s_ _a_l_l_ _P_A_M_ _i_t_e_m_s
        _6_._4_0_._ _p_a_m___w_h_e_e_l_ _-_ _o_n_l_y_ _p_e_r_m_i_t_ _r_o_o_t_ _a_c_c_e_s_s_ _t_o_ _m_e_m_b_e_r_s_ _o_f_ _g_r_o_u_p_ _w_h_e_e_l
        _6_._4_1_._ _p_a_m___x_a_u_t_h_ _-_ _f_o_r_w_a_r_d_ _x_a_u_t_h_ _k_e_y_s_ _b_e_t_w_e_e_n_ _u_s_e_r_s
  _7_._ _S_e_e_ _a_l_s_o
  _8_._ _A_u_t_h_o_r_/_a_c_k_n_o_w_l_e_d_g_m_e_n_t_s
  _9_._ _C_o_p_y_r_i_g_h_t_ _i_n_f_o_r_m_a_t_i_o_n_ _f_o_r_ _t_h_i_s_ _d_o_c_u_m_e_n_t
CChhaapptteerr 11.. IInnttrroodduuccttiioonn
LLiinnuuxx--PPAAMM (Pluggable Authentication Modules for Linux) is a suite of shared
libraries that enable the local system administrator to choose how applications
authenticate users.
In other words, without (rewriting and) recompiling a PAM-aware application, it
is possible to switch between the authentication mechanism(s) it uses. Indeed,
one may entirely upgrade the local authentication system without touching the
applications themselves.
Historically an application that has required a given user to be authenticated,
has had to be compiled to use a specific authentication mechanism. For example,
in the case of traditional UN*X systems, the identity of the user is verified
by the user entering a correct password. This password, after being prefixed by
a two character ``salt'', is encrypted (with crypt(3)). The user is then
authenticated if this encrypted password is identical to the second field of
the user's entry in the system password database (the /etc/passwd file). On
such systems, most if not all forms of privileges are granted based on this
single authentication scheme. Privilege comes in the form of a personal user-
identifier (UID) and membership of various groups. Services and applications
are available based on the personal and group identity of the user.
Traditionally, group membership has been assigned based on entries in the /etc/
group file.
It is the purpose of the LLiinnuuxx--PPAAMM project to separate the development of
privilege granting software from the development of secure and appropriate
authentication schemes. This is accomplished by providing a library of
functions that an application may use to request that a user be authenticated.
This PAM library is configured locally with a system file, /etc/pam.conf (or a
series of configuration files located in /etc/pam.d/) to authenticate a user
request via the locally available authentication modules. The modules
themselves will usually be located in the directory /lib/security or /lib64/
security and take the form of dynamically loadable object files (see dlopen
(3)).
CChhaapptteerr 22.. SSoommee ccoommmmeennttss oonn tthhee tteexxtt
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 _b_i_b_l_i_o_g_r_a_p_h_y_"). If you are
using a distribution of Linux (or some other operating system) that supports
PAM but chooses to distribute these files in a different way you should be
careful when copying examples directly from the text.
As an example of the above, where it is explicit, the text assumes that PAM
loadable object files (the mmoodduulleess) are to be located in the following
directory: /lib/security/ or /lib64/security depending on the architecture.
This is generally the location that seems to be compatible with the Filesystem
Hierarchy Standard (FHS). On Solaris, which has its own licensed version of
PAM, and some other implementations of UN*X, these files can be found in /usr/
lib/security. Please be careful to perform the necessary transcription when
using the examples from the text.
CChhaapptteerr 33.. OOvveerrvviieeww
For the uninitiated, we begin by considering an example. We take an application
that grants some service to users; llooggiinn is one such program. LLooggiinn 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 llooggiinn the
service is a command shell (bash, tcsh, zsh, etc.) running with the identity of
the user.
Traditionally, the former step is achieved by the llooggiinn 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 LLiinnuuxx--PPAAMM.
From the perspective of the application programmer (in this case the person
that wrote the llooggiinn application), LLiinnuuxx--PPAAMM takes care of this authentication
task -- verifying the identity of the user.
The flexibility of LLiinnuuxx--PPAAMM is that yyoouu, 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 ssiimmppllee ttrruusstt
(ppaamm__ppeerrmmiitt) 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 mmuullttiipplliiccaattiioonn ttaabblleess. As they mature, the
authentication can be upgraded to include (long) division!
LLiinnuuxx--PPAAMM deals with four separate types of (management) task. These are:
aauutthheennttiiccaattiioonn mmaannaaggeemmeenntt; aaccccoouunntt mmaannaaggeemmeenntt; sseessssiioonn mmaannaaggeemmeenntt; and ppaasssswwoorrdd
mmaannaaggeemmeenntt. The association of the preferred management scheme with the
behavior of an application is made with entries in the relevant LLiinnuuxx--PPAAMM
configuration file. The management functions are performed by mmoodduulleess specified
in the configuration file. The syntax for this file is discussed in the section
_b_e_l_o_w.
Here is a figure that describes the overall organization of LLiinnuuxx--PPAAMM:
  +----------------+
  | application: X |
  +----------------+       /  +----------+     +================+
  | authentication-[---->--\--] Linux-   |--<--| PAM config file|
  |       +        [----<--/--]   PAM    |     |================|
  |[conversation()][--+    \  |          |     | X auth .. a.so |
  +----------------+  |    /  +-n--n-----+     | X auth .. b.so |
  |                |  |       __|  |           |           _____/
  |  service user  |  A      |     |           |____,-----'
  |                |  |      V     A
  +----------------+  +------|-----|---------+ -----+------+
                         +---u-----u----+    |      |      |
                         |   auth....   |--[ a ]--[ b ]--[ c ]
                         +--------------+
                         |   acct....   |--[ b ]--[ d ]
                         +--------------+
                         |   password   |--[ b ]--[ c ]
                         +--------------+
                         |   session    |--[ e ]--[ c ]
                         +--------------+
By way of explanation, the left of the figure represents the application;
application X. Such an application interfaces with the LLiinnuuxx--PPAAMM library and
knows none of the specifics of its configured authentication method. The LLiinnuuxx--
PPAAMM library (in the center) consults the contents of the PAM configuration file
and loads the modules that are appropriate for application-X. These modules
fall into one of four management groups (lower-center) and are stacked in the
order they appear in the configuration file. These modules, when called by
LLiinnuuxx--PPAAMM, 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 ccoonnvveerrssaattiioonn function.
If a program is going to use PAM, then it has to have PAM functions explicitly
coded into the program. If you have access to the source code you can add the
appropriate PAM functions. If you do not have access to the source code, and
the binary does not have the PAM functions included, then it is not possible to
use PAM.
CChhaapptteerr 44.. TThhee LLiinnuuxx--PPAAMM ccoonnffiigguurraattiioonn ffiillee
When a PPAAMM aware privilege granting application is started, it activates its
attachment to the PAM-API. This activation performs a number of tasks, the most
important being the reading of the configuration file(s): /etc/pam.conf.
Alternatively, this may be the contents of the /etc/pam.d/ directory. The
presence of this directory will cause Linux-PAM to ignore /etc/pam.conf.
These files list the PPAAMMs that will do the authentication tasks required by
this service, and the appropriate behavior of the PAM-API in the event that
individual PPAAMMs fail.
44..11.. CCoonnffiigguurraattiioonn ffiillee ssyynnttaaxx
The syntax of the /etc/pam.conf configuration file is as follows. The file is
made up of a list of rules, each rule is typically placed on a single line, but
may be extended with an escaped end of line: `\<LF>'. Comments are preceded
with `#' marks and extend to the next end of line.
The format of each rule is a space separated collection of tokens, the first
three being case-insensitive:
sseerrvviiccee ttyyppee ccoonnttrrooll mmoodduullee--ppaatthh mmoodduullee--aarrgguummeennttss
The syntax of files contained in the /etc/pam.d/ directory, are identical
except for the absence of any sseerrvviiccee field. In this case, the sseerrvviiccee is the
name of the file in the /etc/pam.d/ directory. This filename must be in lower
case.
An important feature of PPAAMM, is that a number of rules may be ssttaacckkeedd to
combine the services of a number of PAMs for a given authentication task.
The sseerrvviiccee is typically the familiar name of the corresponding application:
llooggiinn and ssuu are good examples. The sseerrvviiccee-name, ootthheerr, is reserved for giving
ddeeffaauulltt rules. Only lines that mention the current service (or in the absence
of such, the ootthheerr entries) will be associated with the given service-
application.
The ttyyppee is the management group that the rule corresponds to. It is used to
specify which of the management groups the subsequent module is to be
associated with. Valid entries are:
  account
      this module type performs non-authentication based account management. It
      is typically used to restrict/permit access to a service based on the
      time of day, currently available system resources (maximum number of
      users) or perhaps the location of the applicant user -- 'root' login only
      on the console.
  auth
      this module type provides two aspects of authenticating the user.
      Firstly, it establishes that the user is who they claim to be, by
      instructing the application to prompt the user for a password or other
      means of identification. Secondly, the module can grant group membership
      or other privileges through its credential granting properties.
  password
      this module type is required for updating the authentication token
      associated with the user. Typically, there is one module for each
      'challenge/response' based authentication (auth) type.
  session
      this module type is associated with doing things that need to be done for
      the user before/after they can be given service. Such things include the
      logging of information concerning the opening/closing of some data
      exchange with a user, mounting directories, etc.
If the ttyyppee value from the list above is prepended with a -- character the PAM
library will not log to the system log if it is not possible to load the module
because it is missing in the system. This can be useful especially for modules
which are not always installed on the system and are not required for correct
authentication and authorization of the login session.
The third field, ccoonnttrrooll, indicates the behavior of the PAM-API should the
module fail to succeed in its authentication task. There are two types of
syntax for this control field: the simple one has a single simple keyword; the
more complicated one involves a square-bracketed selection of vvaalluuee==aaccttiioonn
pairs.
For the simple (historical) syntax valid ccoonnttrrooll values are:
  required
      failure of such a PAM will ultimately lead to the PAM-API returning
      failure but only after the remaining ssttaacckkeedd modules (for this sseerrvviiccee
      and ttyyppee) have been invoked.
  requisite
      like rreeqquuiirreedd, however, in the case that such a module returns a failure,
      control is directly returned to the application or to the superior PAM
      stack. The return value is that associated with the first required or
      requisite module to fail. Note, this flag can be used to protect against
      the possibility of a user getting the opportunity to enter a password
      over an unsafe medium. It is conceivable that such behavior might inform
      an attacker of valid accounts on a system. This possibility should be
      weighed against the not insignificant concerns of exposing a sensitive
      password in a hostile environment.
  sufficient
      if such a module succeeds and no prior rreeqquuiirreedd module has failed the PAM
      framework returns success to the application or to the superior PAM stack
      immediately without calling any further modules in the stack. A failure
      of a ssuuffffiicciieenntt module is ignored and processing of the PAM module stack
      continues unaffected.
  optional
      the success or failure of this module is only important if it is the only
      module in the stack associated with this sseerrvviiccee+ttyyppee.
  include
      include all lines of given type from the configuration file specified as
      an argument to this control.
  substack
      include all lines of given type from the configuration file specified as
      an argument to this control. This differs from iinncclluuddee in that evaluation
      of the ddoonnee and ddiiee actions in a substack does not cause skipping the
      rest of the complete module stack, but only of the substack. Jumps in a
      substack also can not make evaluation jump out of it, and the whole
      substack is counted as one module when the jump is done in a parent
      stack. The rreesseett action will reset the state of a module stack to the
      state it was in as of beginning of the substack evaluation.
For the more complicated syntax valid ccoonnttrrooll values have the following form:
      [value1=action1 value2=action2 ...]
Where vvaalluueeNN corresponds to the return code from the function invoked in the
module for which the line is defined. It is selected from one of these:
ssuucccceessss, ooppeenn__eerrrr, ssyymmbbooll__eerrrr, sseerrvviiccee__eerrrr, ssyysstteemm__eerrrr, bbuuff__eerrrr, ppeerrmm__ddeenniieedd,
aauutthh__eerrrr, ccrreedd__iinnssuuffffiicciieenntt, aauutthhiinnffoo__uunnaavvaaiill, uusseerr__uunnkknnoowwnn, mmaaxxttrriieess,
nneeww__aauutthhttookk__rreeqqdd, aacccctt__eexxppiirreedd, sseessssiioonn__eerrrr, ccrreedd__uunnaavvaaiill, ccrreedd__eexxppiirreedd,
ccrreedd__eerrrr, nnoo__mmoodduullee__ddaattaa, ccoonnvv__eerrrr, aauutthhttookk__eerrrr, aauutthhttookk__rreeccoovveerr__eerrrr,
aauutthhttookk__lloocckk__bbuussyy, aauutthhttookk__ddiissaabbllee__aaggiinngg, ttrryy__aaggaaiinn, iiggnnoorree, aabboorrtt,
aauutthhttookk__eexxppiirreedd, mmoodduullee__uunnkknnoowwnn, bbaadd__iitteemm, ccoonnvv__aaggaaiinn, iinnccoommpplleettee, and ddeeffaauulltt.
The last of these, ddeeffaauulltt, implies 'all vvaalluueeNN's not mentioned explicitly.
Note, the full list of PAM errors is available in /usr/include/security/
_pam_types.h. The aaccttiioonnNN can take one of the following forms:
  ignore
      when used with a stack of modules, the module's return status will not
      contribute to the return code the application obtains.
  bad
      this action indicates that the return code should be thought of as
      indicative of the module failing. If this module is the first in the
      stack to fail, its status value will be used for that of the whole stack.
  die
      equivalent to bad with the side effect of terminating the module stack
      and PAM immediately returning to the application.
  ok
      this tells PAM that the administrator thinks this return code should
      contribute directly to the return code of the full stack of modules. In
      other words, if the former state of the stack would lead to a return of
      PPAAMM__SSUUCCCCEESSSS, the module's return code will override this value. Note, if
      the former state of the stack holds some value that is indicative of a
      modules failure, this 'ok' value will not be used to override that value.
  done
      equivalent to ok with the side effect of terminating the module stack and
      PAM immediately returning to the application.
  N (an unsigned integer)
      equivalent to ok with the side effect of jumping over the next N modules
      in the stack. Note that N equal to 0 is not allowed (and it would be
      identical to ok in such case).
  reset
      clear all memory of the state of the module stack and start again with
      the next stacked module.
Each of the four keywords: required; requisite; sufficient; and optional, have
an equivalent expression in terms of the [...] syntax. They are as follows:
  required
      [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
  requisite
      [success=ok new_authtok_reqd=ok ignore=ignore default=die]
  sufficient
      [success=done new_authtok_reqd=done default=ignore]
  optional
      [success=ok new_authtok_reqd=ok default=ignore]
mmoodduullee--ppaatthh is either the full filename of the PAM to be used by the
application (it begins with a '/'), or a relative pathname from the default
module location: /lib/security/ or /lib64/security/, depending on the
architecture.
mmoodduullee--aarrgguummeennttss are a space separated list of tokens that can be used to
modify the specific behavior of the given PAM. Such arguments will be
documented for each individual module. Note, if you wish to include spaces in
an argument, you should surround that argument with square brackets.
    squid auth required pam_mysql.so user=passwd_query passwd=mada \
          db=eminence [query=select user_name from internet_service \
          where user_name='%u' and password=PASSWORD('%p') and \
        service='web_proxy']
When using this convention, you can include `[' characters inside the string,
and if you wish to include a `]' character inside the string that will survive
the argument parsing, you should use `\]'. In other words:
    [..[..\]..]    -->   ..[..]..
Any line in (one of) the configuration file(s), that is not formatted
correctly, will generally tend (erring on the side of caution) to make the
authentication process fail. A corresponding error is written to the system log
files with a call to syslog(3).
44..22.. DDiirreeccttoorryy bbaasseedd ccoonnffiigguurraattiioonn
More flexible than the single configuration file is it to configure libpam via
the contents of the /etc/pam.d/ directory. In this case the directory is filled
with files each of which has a filename equal to a service-name (in lower-
case): it is the personal configuration file for the named service.
The syntax of each file in /etc/pam.d/ is similar to that of the /etc/pam.conf
file and is made up of lines of the following form:
type  control  module-path  module-arguments
The only difference being that the service-name is not present. The service-
name is of course the name of the given configuration file. For example, /etc/
pam.d/login contains the configuration for the llooggiinn service.
44..33.. EExxaammppllee ccoonnffiigguurraattiioonn ffiillee eennttrriieess
In this section, we give some examples of entries that can be present in the
LLiinnuuxx--PPAAMM configuration file. As a first attempt at configuring your system you
could do worse than to implement these.
If a system is to be considered secure, it had better have a reasonably secure
'ootthheerr entry. The following is a paranoid setting (which is not a bad place to
start!):
#
# default; deny access
#
other   auth     required       pam_deny.so
other   account  required       pam_deny.so
other   password required       pam_deny.so
other   session  required       pam_deny.so
Whilst fundamentally a secure default, this is not very sympathetic to a
misconfigured system. For example, such a system is vulnerable to locking
everyone out should the rest of the file become badly written.
The module ppaamm__ddeennyy (documented in a _l_a_t_e_r_ _s_e_c_t_i_o_n) is not very sophisticated.
For example, it logs no information when it is invoked so unless the users of a
system contact the administrator when failing to execute a service application,
the administrator may go for a long while in ignorance of the fact that his
system is misconfigured.
The addition of the following line before those in the above example would
provide a suitable warning to the administrator.
#
# default; wake up! This application is not configured
#
other   auth     required       pam_warn.so
other   password required       pam_warn.so
Having two 'ootthheerr aauutthh' lines is an example of stacking.
On a system that uses the /etc/pam.d/ configuration, the corresponding default
setup would be achieved with the following file:
#
# default configuration: /etc/pam.d/other
#
auth     required       pam_warn.so
auth     required       pam_deny.so
account  required       pam_deny.so
password required       pam_warn.so
password required       pam_deny.so
session  required       pam_deny.so
This is the only explicit example we give for an /etc/pam.d/ file. In general,
it should be clear how to transpose the remaining examples to this
configuration scheme.
On a less sensitive computer, one on which the system administrator wishes to
remain ignorant of much of the power of LLiinnuuxx--PPAAMM, the following selection of
lines (in /etc/pam.d/other) is likely to mimic the historically familiar Linux
setup.
#
# default; standard UN*X access
#
auth     required       pam_unix.so
account  required       pam_unix.so
password required       pam_unix.so
session  required       pam_unix.so
In general this will provide a starting place for most applications.
CChhaapptteerr 55.. SSeeccuurriittyy iissssuueess
55..11.. IIff ssoommeetthhiinngg ggooeess wwrroonngg
LLiinnuuxx--PPAAMM has the potential to seriously change the security of your system.
You can choose to have no security or absolute security (no access permitted).
In general, LLiinnuuxx--PPAAMM errs towards the latter. Any number of configuration
errors can disable access to your system partially, or completely.
The most dramatic problem that is likely to be encountered when configuring
LLiinnuuxx--PPAAMM is that of ddeelleettiinngg the configuration file(s): /etc/pam.d/* and/or /
etc/pam.conf. This will lock you out of your own system!
To recover, your best bet is to restore the system from a backup or boot the
system into a rescue system and correct things from there.
55..22.. AAvvooiidd hhaavviinngg aa wweeaakk ``ootthheerr'' ccoonnffiigguurraattiioonn
It is not a good thing to have a weak default (ootthheerr) 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 ppaamm__ddeennyy module will deny
access and the ppaamm__wwaarrnn module will send a syslog message to aauutthh..nnoottiiccee:
#
# 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
CChhaapptteerr 66.. AA rreeffeerreennccee gguuiiddee ffoorr aavvaaiillaabbllee mmoodduulleess
Here, we collect together the descriptions of the various modules coming with
Linux-PAM.
66..11.. ppaamm__aacccceessss -- llooggddaaeemmoonn ssttyyllee llooggiinn aacccceessss ccoonnttrrooll
pam_access.so [ debug ] [ nodefgroup ] [ noaudit ] [ accessfile=ffiillee ]
[ fieldsep=sseepp ] [ listsep=sseepp ]
66..11..11.. DDEESSCCRRIIPPTTIIOONN
The pam_access PAM module is mainly for access management. It provides
logdaemon style login access control based on login names, host or domain
names, internet addresses or network numbers, or on terminal line names, X
$DISPLAY values, or PAM service names in case of non-networked logins.
By default rules for access management are taken from config file /etc/
security/access.conf if you don't specify another file.
If Linux PAM is compiled with audit support the module will report when it
denies access based on origin (host, tty, etc.).
66..11..22.. DDEESSCCRRIIPPTTIIOONN
The /etc/security/access.conf file specifies (uusseerr//ggrroouupp, hhoosstt), (uusseerr//ggrroouupp,
nneettwwoorrkk//nneettmmaasskk), (uusseerr//ggrroouupp, ttttyy), (uusseerr//ggrroouupp, XX--$$DDIISSPPLLAAYY--vvaalluuee), or (uusseerr//
ggrroouupp, ppaamm--sseerrvviiccee--nnaammee) combinations for which a login will be either accepted
or refused.
When someone logs in, the file access.conf is scanned for the first entry that
matches the (uusseerr//ggrroouupp, hhoosstt) or (uusseerr//ggrroouupp, nneettwwoorrkk//nneettmmaasskk) combination,
or, in case of non-networked logins, the first entry that matches the (uusseerr//
ggrroouupp, ttttyy) combination, or in the case of non-networked logins without a tty,
the first entry that matches the (uusseerr//ggrroouupp, XX--$$DDIISSPPLLAAYY--vvaalluuee) or (uusseerr//ggrroouupp,
ppaamm--sseerrvviiccee--nnaammee//) combination. The permissions field of that table entry
determines whether the login will be accepted or refused.
Each line of the login access control table has three fields separated by a ":
" character (colon):
ppeerrmmiissssiioonn:uusseerrss//ggrroouuppss:oorriiggiinnss
The first field, the ppeerrmmiissssiioonn field, can be either a "++" character (plus) for
access granted or a "--" character (minus) for access denied.
The second field, the uusseerrss/ggrroouupp field, should be a list of one or more login
names, group names, or AALLLL (which always matches). To differentiate user
entries from group entries, group entries should be written with brackets, e.g.
((ggrroouupp)).
The third field, the oorriiggiinnss field, should be a list of one or more tty names
(for non-networked logins), X $DISPLAY values or PAM service names (for non-
networked logins without a tty), host names, domain names (begin with "."),
host addresses, internet network numbers (end with "."), internet network
addresses with network mask (where network mask can be a decimal number or an
internet address also), AALLLL (which always matches) or LLOOCCAALL. The LLOOCCAALL keyword
matches if and only if pam_get_item(3), when called with an iitteemm__ttyyppee of
PPAAMM__RRHHOOSSTT, returns NULL or an empty string (and therefore the oorriiggiinnss field is
compared against the return value of pam_get_item(3) called with an iitteemm__ttyyppee
of PPAAMM__TTTTYY or, absent that, PPAAMM__SSEERRVVIICCEE).
If supported by the system you can use @@nneettggrroouuppnnaammee in host or user patterns.
The @@@@nneettggrroouuppnnaammee syntax is supported in the user pattern only and it makes
the local system hostname to be passed to the netgroup match call in addition
to the user name. This might not work correctly on some libc implementations
causing the match to always fail.
The EEXXCCEEPPTT operator makes it possible to write very compact rules.
If the nodefgroup is not set, the group file is searched when a name does not
match that of the logged-in user. Only groups are matched in which users are
explicitly listed. However the PAM module does not look at the primary group id
of a user.
The "##" character at start of line (no space at front) can be used to mark this
line as a comment line.
66..11..33.. OOPPTTIIOONNSS
  accessfile=//ppaatthh//ttoo//aacccceessss..ccoonnff
      Indicate an alternative access.conf style configuration file to override
      the default. This can be useful when different services need different
      access lists.
  debug
      A lot of debug information is printed with syslog(3).
  noaudit
      Do not report logins from disallowed hosts and ttys to the audit
      subsystem.
  fieldsep=sseeppaarraattoorrss
      This option modifies the field separator character that pam_access will
      recognize when parsing the access configuration file. For example:
      ffiieellddsseepp==|| will cause the default `:' character to be treated as part of
      a field value and `|' becomes the field separator. Doing this may be
      useful in conjunction with a system that wants to use pam_access with X
      based applications, since the PPAAMM__TTTTYY item is likely to be of the form
      "hostname:0" which includes a `:' character in its value. But you should
      not need this.
  listsep=sseeppaarraattoorrss
      This option modifies the list separator character that pam_access will
      recognize when parsing the access configuration file. For example:
      lliissttsseepp==,, will cause the default ` ' (space) and `\t' (tab) characters to
      be treated as part of a list element value and `,' becomes the only list
      element separator. Doing this may be useful on a system with group
      information obtained from a Windows domain, where the default built-in
      groups "Domain Users", "Domain Admins" contain a space.
  nodefgroup
      User tokens which are not enclosed in parentheses will not be matched
      against the group database. The backwards compatible default is to try
      the group database match even for tokens not enclosed in parentheses.
66..11..44.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (auth, account, password and session) are provided.
66..11..55.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      Access was granted.
  PAM_PERM_DENIED
      Access was not granted.
  PAM_IGNORE
      pam_setcred was called which does nothing.
  PAM_ABORT
      Not all relevant data or options could be gotten.
  PAM_USER_UNKNOWN
      The user is not known to the system.
66..11..66.. FFIILLEESS
  /etc/security/access.conf
      Default configuration file
66..11..77.. EEXXAAMMPPLLEESS
These are some example lines which might be specified in /etc/security/
access.conf.
User rroooott should be allowed to get access via ccrroonn, X11 terminal ::00, ttttyy11, ...,
ttttyy55, ttttyy66.
+ : root : crond :0 tty1 tty2 tty3 tty4 tty5 tty6
User rroooott should be allowed to get access from hosts which own the IPv4
addresses. This does not mean that the connection have to be a IPv4 one, a IPv6
connection from a host with one of this IPv4 addresses does work, too.
+ : root : 192.168.200.1 192.168.200.4 192.168.200.9
+ : root : 127.0.0.1
User rroooott should get access from network 192.168.201. where the term will be
evaluated by string matching. But it might be better to use network/netmask
instead. The same meaning of 192.168.201. is 119922..116688..220011..00//2244 or 119922..116688..220011..00//
225555..225555..225555..00.
+ : root : 192.168.201.
User rroooott should be able to have access from hosts ffoooo11..bbaarr..oorrgg and
ffoooo22..bbaarr..oorrgg (uses string matching also).
+ : root : foo1.bar.org foo2.bar.org
User rroooott should be able to have access from domain ffoooo..bbaarr..oorrgg (uses string
matching also).
+ : root : .foo.bar.org
User rroooott should be denied to get access from all other sources.
- : root : ALL
User ffoooo and members of netgroup aaddmmiinnss should be allowed to get access from
all sources. This will only work if netgroup service is available.
+ : @admins foo : ALL
User jjoohhnn and ffoooo should get access from IPv6 host address.
+ : john foo : 2001:db8:0:101::1
User jjoohhnn should get access from IPv6 net/mask.
+ : john : 2001:db8:0:101::/64
Disallow console logins to all but the shutdown, sync and all other accounts,
which are a member of the wheel group.
-:ALL EXCEPT (wheel) shutdown sync:LOCAL
All other users should be denied to get access from all sources.
- : ALL : ALL
66..11..88.. AAUUTTHHOORRSS
The logdaemon style login access control scheme was designed and implemented by
Wietse Venema. The pam_access PAM module was developed by Alexei Nogin
<alexei@nogin.dnttm.ru>. The IPv6 support and the network(address) / netmask
feature was developed and provided by Mike Becher <mike.becher@lrz-
muenchen.de>.
66..22.. ppaamm__ccrraacckklliibb -- cchheecckkss tthhee ppaasssswwoorrdd aaggaaiinnsstt ddiiccttiioonnaarryy wwoorrddss
pam_cracklib.so [ ...... ]
66..22..11.. DDEESSCCRRIIPPTTIIOONN
This module can be plugged into the ppaasssswwoorrdd stack of a given application to
provide some plug-in strength-checking for passwords.
The action of this module is to prompt the user for a password and check its
strength against a system dictionary and a set of rules for identifying poor
choices.
The first action is to prompt for a single password, check its strength and
then, if it is considered strong, prompt for the password a second time (to
verify that it was typed correctly on the first occasion). All being well, the
password is passed on to subsequent modules to be installed as the new
authentication token.
The strength checks works in the following manner: at first the Cracklib
routine is called to check if the password is part of a dictionary; if this is
not the case an additional set of strength checks is done. These checks are:
  Palindrome
      Is the new password a palindrome?
  Case Change Only
      Is the new password the the old one with only a change of case?
  Similar
      Is the new password too much like the old one? This is primarily
      controlled by one argument, difok which is a number of character changes
      (inserts, removals, or replacements) between the old and new password
      that are enough to accept the new password. This defaults to 5 changes.
  Simple
      Is the new password too small? This is controlled by 6 arguments minlen,
      maxclassrepeat, dcredit, ucredit, lcredit, and ocredit. See the section
      on the arguments for the details of how these work and there defaults.
  Rotated
      Is the new password a rotated version of the old password?
  Same consecutive characters
      Optional check for same consecutive characters.
  Too long monotonic character sequence
      Optional check for too long monotonic character sequence.
  Contains user name
      Optional check whether the password contains the user's name in some
      form.
This module with no arguments will work well for standard unix password
encryption. With md5 encryption, passwords can be longer than 8 characters and
the default settings for this module can make it hard for the user to choose a
satisfactory new password. Notably, the requirement that the new password
contain no more than 1/2 of the characters in the old password becomes a non-
trivial constraint. For example, an old password of the form "the quick brown
fox jumped over the lazy dogs" would be difficult to change... In addition, the
default action is to allow passwords as small as 5 characters in length. For a
md5 systems it can be a good idea to increase the required minimum size of a
password. One can then allow more credit for different kinds of characters but
accept that the new password may share most of these characters with the old
password.
66..22..22.. OOPPTTIIOONNSS
  debug
      This option makes the module write information to syslog(3) indicating
      the behavior of the module (this option does not write password
      information to the log file).
  authtok_type=XXXXXX
      The default action is for the module to use the following prompts when
      requesting passwords: "New UNIX password: " and "Retype UNIX password: ".
      The example word UUNNIIXX can be replaced with this option, by default it is
      empty.
  retry=NN
      Prompt user at most NN times before returning with error. The default is
      11.
  difok=NN
      This argument will change the default of 55 for the number of character
      changes in the new password that differentiate it from the old password.
  minlen=NN
      The minimum acceptable size for the new password (plus one if credits are
      not disabled which is the default). In addition to the number of
      characters in the new password, credit (of +1 in length) is given for
      each different kind of character (ootthheerr, uuppppeerr, lloowweerr and ddiiggiitt). The
      default for this parameter is 9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 CCrraacckklliibb itself, a "way too short" limit of 4 which is hard
      coded in and a defined limit (6) that will be checked without reference
      to minlen. If you want to allow passwords as short as 5 characters you
      should not use this module.
  dcredit=NN
      (N >= 0) This is the maximum credit for having digits in the new
      password. If you have less than or NN digits, each digit will count +1
      towards meeting the current minlen value. The default for dcredit is 1
      which is the recommended value for minlen less than 10.
      (N < 0) This is the minimum number of digits that must be met for a new
      password.
  ucredit=NN
      (N >= 0) This is the maximum credit for having upper case letters in the
      new password. If you have less than or NN upper case letters each letter
      will count +1 towards meeting the current minlen value. The default for
      ucredit is 11 which is the recommended value for minlen less than 10.
      (N < 0) This is the minimum number of upper case letters that must be met
      for a new password.
  lcredit=NN
      (N >= 0) This is the maximum credit for having lower case letters in the
      new password. If you have less than or NN lower case letters, each letter
      will count +1 towards meeting the current minlen value. The default for
      lcredit is 1 which is the recommended value for minlen less than 10.
      (N < 0) This is the minimum number of lower case letters that must be met
      for a new password.
  ocredit=NN
      (N >= 0) This is the maximum credit for having other characters in the
      new password. If you have less than or NN other characters, each character
      will count +1 towards meeting the current minlen value. The default for
      ocredit is 1 which is the recommended value for minlen less than 10.
      (N < 0) This is the minimum number of other characters that must be met
      for a new password.
  minclass=NN
      The minimum number of required classes of characters for the new
      password. The default number is zero. The four classes are digits, upper
      and lower letters and other characters. The difference to the credit
      check is that a specific class if of characters is not required. Instead
      NN out of four of the classes are required.
  maxrepeat=NN
      Reject passwords which contain more than N same consecutive characters.
      The default is 0 which means that this check is disabled.
  maxsequence=NN
      Reject passwords which contain monotonic character sequences longer than
      N. The default is 0 which means that this check is disabled. Examples of
      such sequence are '12345' or 'fedcb'. Note that most such passwords will
      not pass the simplicity check unless the sequence is only a minor part of
      the password.
  maxclassrepeat=NN
      Reject passwords which contain more than N consecutive characters of the
      same class. The default is 0 which means that this check is disabled.
  reject_username
      Check whether the name of the user in straight or reversed form is
      contained in the new password. If it is found the new password is
      rejected.
  gecoscheck
      Check whether the words from the GECOS field (usualy full name of the
      user) longer than 3 characters in straight or reversed form are contained
      in the new password. If any such word is found the new password is
      rejected.
  enforce_for_root
      The module will return error on failed check also if the user changing
      the password is root. This option is off by default which means that just
      the message about the failed check is printed but root can change the
      password anyway. Note that root is not asked for an old password so the
      checks that compare the old and new password are not performed.
  use_authtok
      This argument is used to ffoorrccee the module to not prompt the user for a
      new password but use the one provided by the previously stacked ppaasssswwoorrdd
      module.
  dictpath=//ppaatthh//ttoo//ddiicctt
      Path to the cracklib dictionaries.
66..22..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the password module type is provided.
66..22..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The new password passes all checks.
  PAM_AUTHTOK_ERR
      No new password was entered, the username could not be determined or the
      new password fails the strength checks.
  PAM_AUTHTOK_RECOVERY_ERR
      The old password was not supplied by a previous stacked module or got not
      requested from the user. The first error can happen if use_authtok is
      specified.
  PAM_SERVICE_ERR
      A internal error occurred.
66..22..55.. EEXXAAMMPPLLEESS
For an example of the use of this module, we show how it may be stacked with
the password component of pam_unix(8)
#
# These lines stack two password type modules. In this example the
# user is given 3 opportunities to enter a strong password. The
# "use_authtok" argument ensures that the pam_unix module does not
# prompt for a password, but instead uses the one provided by
# pam_cracklib.
#
passwd  password required       pam_cracklib.so retry=3
passwd  password required       pam_unix.so use_authtok
Another example (in the /etc/pam.d/passwd format) is for the case that you want
to use md5 password encryption:
#%PAM-1.0
#
# These lines allow a md5 systems to support passwords of at least 14
# bytes with extra credit of 2 for digits and 2 for others the new
# password must have at least three bytes that are not present in the
# old password
#
password  required pam_cracklib.so \
               difok=3 minlen=15 dcredit= 2 ocredit=2
password  required pam_unix.so use_authtok nullok md5
And here is another example in case you don't want to use credits:
#%PAM-1.0
#
# These lines require the user to select a password with a minimum
# length of 8 and with at least 1 digit number, 1 upper case letter,
# and 1 other character
#
password  required pam_cracklib.so \
               dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
password  required pam_unix.so use_authtok nullok md5
66..22..66.. AAUUTTHHOORR
pam_cracklib was written by Cristian Gafton <gafton@redhat.com>
66..33.. ppaamm__ddeebbuugg -- ddeebbuugg tthhee PPAAMM ssttaacckk
pam_debug.so [ auth=vvaalluuee ] [ cred=vvaalluuee ] [ acct=vvaalluuee ] [ prechauthtok=vvaalluuee
] [ chauthtok=vvaalluuee ] [ auth=vvaalluuee ] [ open_session=vvaalluuee ]
[ close_session=vvaalluuee ]
66..33..11.. DDEESSCCRRIIPPTTIIOONN
The pam_debug PAM module is intended as a debugging aide for determining how
the PAM stack is operating. This module returns what its module arguments tell
it to return.
66..33..22.. OOPPTTIIOONNSS
  auth=vvaalluuee
      The pam_sm_authenticate(3) function will return vvaalluuee.
  cred=vvaalluuee
      The pam_sm_setcred(3) function will return vvaalluuee.
  acct=vvaalluuee
      The pam_sm_acct_mgmt(3) function will return vvaalluuee.
  prechauthtok=vvaalluuee
      The pam_sm_chauthtok(3) function will return vvaalluuee if the
      PPAAMM__PPRREELLIIMM__CCHHEECCKK flag is set.
  chauthtok=vvaalluuee
      The pam_sm_chauthtok(3) function will return vvaalluuee if the
      PPAAMM__PPRREELLIIMM__CCHHEECCKK flag is nnoott set.
  open_session=vvaalluuee
      The pam_sm_open_session(3) function will return vvaalluuee.
  close_session=vvaalluuee
      The pam_sm_close_session(3) function will return vvaalluuee.
Where vvaalluuee can be one of: success, open_err, symbol_err, service_err,
system_err, buf_err, perm_denied, auth_err, cred_insufficient,
authinfo_unavail, user_unknown, maxtries, new_authtok_reqd, acct_expired,
session_err, cred_unavail, cred_expired, cred_err, no_module_data, conv_err,
authtok_err, authtok_recover_err, authtok_lock_busy, authtok_disable_aging,
try_again, ignore, abort, authtok_expired, module_unknown, bad_item,
conv_again, incomplete.
66..33..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (auth, account, password and session) are provided.
66..33..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      Default return code if no other value was specified, else specified
      return value.
66..33..55.. EEXXAAMMPPLLEESS
auth    requisite       pam_permit.so
auth    [success=2 default=ok]  pam_debug.so auth=perm_denied cred=success
auth    [default=reset]         pam_debug.so auth=success cred=perm_denied
auth    [success=done default=die] pam_debug.so
auth    optional        pam_debug.so auth=perm_denied cred=perm_denied
auth    sufficient      pam_debug.so auth=success cred=success
66..33..66.. AAUUTTHHOORR
pam_debug was written by Andrew G. Morgan <morgan@kernel.org>.
66..44.. ppaamm__ddeennyy -- lloocckkiinngg--oouutt PPAAMM mmoodduullee
pam_deny.so
66..44..11.. DDEESSCCRRIIPPTTIIOONN
This module can be used to deny access. It always indicates a failure to the
application through the PAM framework. It might be suitable for using for
default (the OOTTHHEERR) entries.
66..44..22.. OOPPTTIIOONNSS
This module does not recognise any options.
66..44..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (account, auth, password and session) are provided.
66..44..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      This is returned by the account and auth services.
  PAM_CRED_ERR
      This is returned by the setcred function.
  PAM_AUTHTOK_ERR
      This is returned by the password service.
  PAM_SESSION_ERR
      This is returned by the session service.
66..44..55.. EEXXAAMMPPLLEESS
#%PAM-1.0
#
# If we don't have config entries for a service, the
# OTHER entries are used. To be secure, warn and deny
# access to everything.
other auth     required       pam_warn.so
other auth     required       pam_deny.so
other account  required       pam_warn.so
other account  required       pam_deny.so
other password required       pam_warn.so
other password required       pam_deny.so
other session  required       pam_warn.so
other session  required       pam_deny.so
66..44..66.. AAUUTTHHOORR
pam_deny was written by Andrew G. Morgan <morgan@kernel.org>
66..55.. ppaamm__eecchhoo -- pprriinntt tteexxtt mmeessssaaggeess
pam_echo.so [ file=//ppaatthh//mmeessssaaggee ]
66..55..11.. DDEESSCCRRIIPPTTIIOONN
The ppaamm__eecchhoo PAM module is for printing text messages to inform user about
special things. Sequences starting with the %% character are interpreted in the
following way:
  %%HH
      The name of the remote host (PAM_RHOST).
  %%hh
      The name of the local host.
  %%ss
      The service name (PAM_SERVICE).
  %%tt
      The name of the controlling terminal (PAM_TTY).
  %%UU
      The remote user name (PAM_RUSER).
  %%uu
      The local user name (PAM_USER).
All other sequences beginning with %% expands to the characters following the %%
character.
66..55..22.. OOPPTTIIOONNSS
  file=//ppaatthh//mmeessssaaggee
      The content of the file /path/message will be printed with the PAM
      conversion function as PAM_TEXT_INFO.
66..55..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (auth, account, password and session) are provided.
66..55..44.. RREETTUURRNN VVAALLUUEESS
  PAM_BUF_ERR
      Memory buffer error.
  PAM_SUCCESS
      Message was successful printed.
  PAM_IGNORE
      PAM_SILENT flag was given or message file does not exist, no message
      printed.
66..55..55.. EEXXAAMMPPLLEESS
For an example of the use of this module, we show how it may be used to print
information about good passwords:
password optional pam_echo.so file=/usr/share/doc/good-password.txt
password required pam_unix.so
66..55..66.. AAUUTTHHOORR
Thorsten Kukuk <kukuk@thkukuk.de>
66..66.. ppaamm__eennvv -- sseett//uunnsseett eennvviirroonnmmeenntt vvaarriiaabblleess
pam_env.so [ debug ] [ conffile=ccoonnff--ffiillee ] [ envfile=eennvv--ffiillee ] [ readenv=00||11
] [ user_envfile=eennvv--ffiillee ] [ user_readenv=00||11 ]
66..66..11.. DDEESSCCRRIIPPTTIIOONN
The pam_env PAM module allows the (un)setting of environment variables.
Supported is the use of previously set environment variables as well as
PPAAMM__IITTEEMMs such as PPAAMM__RRHHOOSSTT.
By default rules for (un)setting of variables are taken from the config file /
etc/security/pam_env.conf. An alternate file can be specified with the ccoonnffffiillee
option.
Second a file (/etc/environment by default) with simple KKEEYY==VVAALL pairs on
separate lines will be read. With the eennvvffiillee option an alternate file can be
specified. And with the rreeaaddeennvv option this can be completly disabled.
Third it will read a user configuration file ($HOME/.pam_environment by
default). The default file file can be changed with the uusseerr__eennvvffiillee option and
it can be turned on and off with the uusseerr__rreeaaddeennvv option.
Since setting of PAM environment variables can have side effects to other
modules, this module should be the last one on the stack.
66..66..22.. DDEESSCCRRIIPPTTIIOONN
The /etc/security/pam_env.conf file specifies the environment variables to be
set, unset or modified by pam_env(8). When someone logs in, this file is read
and the environment variables are set according.
Each line starts with the variable name, there are then two possible options
for each variable DEFAULT and OVERRIDE. DEFAULT allows and administrator to set
the value of the variable to some default value, if none is supplied then the
empty string is assumed. The OVERRIDE option tells pam_env that it should enter
in its value (overriding the default value) if there is one to use. OVERRIDE is
not used, "" is assumed and no override will be done.
VVAARRIIAABBLLEE [DDEEFFAAUULLTT==[[vvaalluuee]]] [OOVVEERRRRIIDDEE==[[vvaalluuee]]]
(Possibly non-existent) environment variables may be used in values using the $
{string} syntax and (possibly non-existent) PAM_ITEMs as well as HOME and SHELL
may be used in values using the @{string} syntax. Both the $ and @ characters
can be backslash escaped to be used as literal values values can be delimited
with "", escaped " not supported. Note that many environment variables that you
would like to use may not be set by the time the module is called. For example,
${HOME} is used below several times, but many PAM applications don't make it
available by the time you need it. The special variables @{HOME} and @{SHELL}
are expanded to the values for the user from his ppaasssswwdd entry.
The "##" character at start of line (no space at front) can be used to mark this
line as a comment line.
The /etc/environment file specifies the environment variables to be set. The
file must consist of simple NNAAMMEE==VVAALLUUEE pairs on separate lines. The pam_env(8)
module will read the file after the pam_env.conf file.
66..66..33.. OOPPTTIIOONNSS
  conffile=//ppaatthh//ttoo//ppaamm__eennvv..ccoonnff
      Indicate an alternative pam_env.conf style configuration file to override
      the default. This can be useful when different services need different
      environments.
  debug
      A lot of debug information is printed with syslog(3).
  envfile=//ppaatthh//ttoo//eennvviirroonnmmeenntt
      Indicate an alternative environment file to override the default. The
      syntax are simple KKEEYY==VVAALL pairs on separate lines. The eexxppoorrtt instruction
      can be specified for bash compatibility, but will be ignored. This can be
      useful when different services need different environments.
  readenv=00||11
      Turns on or off the reading of the file specified by envfile (0 is off, 1
      is on). By default this option is on.
  user_envfile=ffiilleennaammee
      Indicate an alternative .pam_environment file to override the default.The
      syntax is the same as for //eettcc//eennvviirroonnmmeenntt. The filename is relative to
      the user home directory. This can be useful when different services need
      different environments.
  user_readenv=00||11
      Turns on or off the reading of the user specific environment file. 0 is
      off, 1 is on. By default this option is off as user supplied environment
      variables in the PAM environment could affect behavior of subsequent
      modules in the stack without the consent of the system administrator.
66..66..44.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and session module types are provided.
66..66..55.. RREETTUURRNN VVAALLUUEESS
  PAM_ABORT
      Not all relevant data or options could be gotten.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_IGNORE
      No pam_env.conf and environment file was found.
  PAM_SUCCESS
      Environment variables were set.
66..66..66.. FFIILLEESS
  /etc/security/pam_env.conf
      Default configuration file
  /etc/environment
      Default environment file
  $HOME/.pam_environment
      User specific environment file
66..66..77.. EEXXAAMMPPLLEESS
These are some example lines which might be specified in /etc/security/
pam_env.conf.
Set the REMOTEHOST variable for any hosts that are remote, default to
"localhost" rather than not being set at all
      REMOTEHOST     DEFAULT=localhost OVERRIDE=@{PAM_RHOST}
Set the DISPLAY variable if it seems reasonable
      DISPLAY        DEFAULT=${REMOTEHOST}:0.0 OVERRIDE=${DISPLAY}
Now some simple variables
      PAGER          DEFAULT=less
      MANPAGER       DEFAULT=less
      LESS           DEFAULT="M q e h15 z23 b80"
      NNTPSERVER     DEFAULT=localhost
      PATH           DEFAULT=${HOME}/bin:/usr/local/bin:/bin\
      :/usr/bin:/usr/local/bin/X11:/usr/bin/X11
      XDG_DATA_HOME  @{HOME}/share/
Silly examples of escaped variables, just to show how they work.
      DOLLAR         DEFAULT=\$
      DOLLARDOLLAR   DEFAULT=        OVERRIDE=\$${DOLLAR}
      DOLLARPLUS     DEFAULT=\${REMOTEHOST}${REMOTEHOST}
      ATSIGN         DEFAULT=""      OVERRIDE=\@
66..66..88.. AAUUTTHHOORR
pam_env was written by Dave Kinchlea <kinch@kinch.ark.com>.
66..77.. ppaamm__eexxeecc -- ccaallll aann eexxtteerrnnaall ccoommmmaanndd
pam_exec.so [ debug ] [ expose_authtok ] [ seteuid ] [ quiet ] [ stdout ]
[ log=ffiillee ] [ type=ttyyppee ] ccoommmmaanndd [ ...... ]
66..77..11.. DDEESSCCRRIIPPTTIIOONN
pam_exec is a PAM module that can be used to run an external command.
The child's environment is set to the current PAM environment list, as returned
by pam_getenvlist(3) In addition, the following PAM items are exported as
environment variables: PPAAMM__RRHHOOSSTT, PPAAMM__RRUUSSEERR, PPAAMM__SSEERRVVIICCEE, PPAAMM__TTTTYY, PPAAMM__UUSSEERR and
PPAAMM__TTYYPPEE, which contains one of the module types: account, auth, password,
open_session and close_session.
Commands called by pam_exec need to be aware of that the user can have controll
over the environment.
66..77..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  expose_authtok
      During authentication the calling command can read the password from
      stdin(3). Only first PPAAMM__MMAAXX__RREESSPP__SSIIZZEE bytes of a password are provided
      to the command.
  log=ffiillee
      The output of the command is appended to file
  type=ttyyppee
      Only run the command if the module type matches the given type.
  stdout
      Per default the output of the executed command is written to /dev/null.
      With this option, the stdout output of the executed command is redirected
      to the calling application. It's in the responsibility of this
      application what happens with the output. The log option is ignored.
  quiet
      Per default pam_exec.so will echo the exit status of the external command
      if it fails. Specifying this option will suppress the message.
  seteuid
      Per default pam_exec.so will execute the external command with the real
      user ID of the calling process. Specifying this option means the command
      is run with the effective user ID.
66..77..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (auth, account, password and session) are provided.
66..77..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The external command was run successfully.
  PAM_SERVICE_ERR
      No argument or a wrong number of arguments were given.
  PAM_SYSTEM_ERR
      A system error occurred or the command to execute failed.
  PAM_IGNORE
      pam_setcred was called, which does not execute the command. Or, the value
      given for the type= parameter did not match the module type.
66..77..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/passwd to rebuild the NIS database after
each local password change:
        password optional pam_exec.so seteuid /usr/bin/make -C /var/yp
This will execute the command
make -C /var/yp
with effective user ID.
66..77..66.. AAUUTTHHOORR
pam_exec was written by Thorsten Kukuk <kukuk@thkukuk.de> and Josh Triplett
<josh@joshtriplett.org>.
66..88.. ppaamm__ffaaiillddeellaayy -- cchhaannggee tthhee ddeellaayy oonn ffaaiilluurree ppeerr--aapppplliiccaattiioonn
pam_faildelay.so [ debug ] [ delay=mmiiccrroosseeccoonnddss ]
66..88..11.. DDEESSCCRRIIPPTTIIOONN
pam_faildelay is a PAM module that can be used to set the delay on failure per-
application.
If no delay is given, pam_faildelay will use the value of FAIL_DELAY from /etc/
login.defs.
66..88..22.. OOPPTTIIOONNSS
  debug
      Turns on debugging messages sent to syslog.
  delay=NN
      Set the delay on failure to N microseconds.
66..88..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the auth module type is provided.
66..88..44.. RREETTUURRNN VVAALLUUEESS
  PAM_IGNORE
      Delay was successful adjusted.
  PAM_SYSTEM_ERR
      The specified delay was not valid.
66..88..55.. EEXXAAMMPPLLEESS
The following example will set the delay on failure to 10 seconds:
auth  optional  pam_faildelay.so  delay=10000000
66..88..66.. AAUUTTHHOORR
pam_faildelay was written by Darren Tucker <dtucker@zip.com.au>.
66..99.. ppaamm__ffiilltteerr -- ffiilltteerr mmoodduullee
pam_filter.so [ debug ] [ new_term ] [ non_term ] run1|run2 ffiilltteerr [ ...... ]
66..99..11.. DDEESSCCRRIIPPTTIIOONN
This module is intended to be a platform for providing access to all of the
input/output that passes between the user and the application. It is only
suitable for tty-based and (stdin/stdout) applications.
To function this module requires ffiilltteerrss to be installed on the system. The
single filter provided with the module simply transposes upper and lower case
letters in the input and output streams. (This can be very annoying and is not
kind to termcap based editors).
Each component of the module has the potential to invoke the desired filter.
The filter is always execv(2) with the privilege of the calling application and
nnoott that of the user. For this reason it cannot usually be killed by the user
without closing their session.
66..99..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  new_term
      The default action of the filter is to set the PPAAMM__TTTTYY item to indicate
      the terminal that the user is using to connect to the application. This
      argument indicates that the filter should set PPAAMM__TTTTYY to the filtered
      pseudo-terminal.
  non_term
      don't try to set the PPAAMM__TTTTYY item.
  runX
      In order that the module can invoke a filter it should know when to
      invoke it. This argument is required to tell the filter when to do this.
      Permitted values for XX are 11 and 22. These indicate the precise time that
      the filter is to be run. To understand this concept it will be useful to
      have read the pam(3) manual page. Basically, for each management group
      there are up to two ways of calling the module's functions. In the case
      of the aauutthheennttiiccaattiioonn and sseessssiioonn components there are actually two
      separate functions. For the case of authentication, these functions are
      pam_authenticate(3) and pam_setcred(3), here run1 means run the filter
      from the pam_authenticate function and run2 means run the filter from
      pam_setcred. In the case of the session modules, rruunn11 implies that the
      filter is invoked at the pam_open_session(3) stage, and rruunn22 for
      pam_close_session(3).
      For the case of the account component. Either rruunn11 or rruunn22 may be used.
      For the case of the password component, rruunn11 is used to indicate that the
      filter is run on the first occasion of pam_chauthtok(3) (the
      PPAAMM__PPRREELLIIMM__CCHHEECCKK phase) and rruunn22 is used to indicate that the filter is
      run on the second occasion (the PPAAMM__UUPPDDAATTEE__AAUUTTHHTTOOKK phase).
  filter
      The full pathname of the filter to be run and any command line arguments
      that the filter might expect.
66..99..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (auth, account, password and session) are provided.
66..99..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The new filter was set successfully.
  PAM_ABORT
      Critical error, immediate abort.
66..99..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to see how to configure login to
transpose upper and lower case letters once the user has logged in:
        session required pam_filter.so run1 /lib/security/pam_filter/upperLOWER
66..99..66.. AAUUTTHHOORR
pam_filter was written by Andrew G. Morgan <morgan@kernel.org>.
66..1100.. ppaamm__ffttpp -- mmoodduullee ffoorr aannoonnyymmoouuss aacccceessss
pam_ftp.so [ debug ] [ ignore ] [ users=XXXXXX,,YYYYYY,, ...]
66..1100..11.. DDEESSCCRRIIPPTTIIOONN
pam_ftp is a PAM module which provides a pluggable anonymous ftp mode of
access.
This module intercepts the user's name and password. If the name is ffttpp or
aannoonnyymmoouuss, the user's password is broken up at the @@ delimiter into a PPAAMM__RRUUSSEERR
and a PPAAMM__RRHHOOSSTT part; these pam-items being set accordingly. The username
(PPAAMM__UUSSEERR) is set to ffttpp. In this case the module succeeds. Alternatively, the
module sets the PPAAMM__AAUUTTHHTTOOKK item with the entered password and fails.
This module is not safe and easily spoofable.
66..1100..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  ignore
      Pay no attention to the email address of the user (if supplied).
  ftp=XXXXXX,,YYYYYY,,......
      Instead of ffttpp or aannoonnyymmoouuss, provide anonymous login to the comma
      separated list of users: XXXXXX,,YYYYYY,,....... Should the applicant enter one of
      these usernames the returned username is set to the first in the list:
      XXXXXX.
66..1100..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the auth module type is provided.
66..1100..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The authentication was successful.
  PAM_USER_UNKNOWN
      User not known.
66..1100..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/ftpd to handle ftp style anonymous login:
#
# ftpd; add ftp-specifics. These lines enable anonymous ftp over
#       standard UN*X access (the listfile entry blocks access to
#       users listed in /etc/ftpusers)
#
auth    sufficient  pam_ftp.so
auth    required    pam_unix.so use_first_pass
auth    required    pam_listfile.so \
           onerr=succeed item=user sense=deny file=/etc/ftpusers
66..1100..66.. AAUUTTHHOORR
pam_ftp was written by Andrew G. Morgan <morgan@kernel.org>.
66..1111.. ppaamm__ggrroouupp -- mmoodduullee ttoo mmooddiiffyy ggrroouupp aacccceessss
pam_group.so
66..1111..11.. DDEESSCCRRIIPPTTIIOONN
The pam_group PAM module does not authenticate the user, but instead it grants
group memberships (in the credential setting phase of the authentication
module) to the user. Such memberships are based on the service they are
applying for.
By default rules for group memberships are taken from config file /etc/
security/group.conf.
This module's usefulness relies on the file-systems accessible to the user. The
point being that once granted the membership of a group, the user may attempt
to create a setgid binary with a restricted group ownership. Later, when the
user is not given membership to this group, they can recover group membership
with the precompiled binary. The reason that the file-systems that the user has
access to are so significant, is the fact that when a system is mounted nnoossuuiidd
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 nnoossuuiidd.
The pam_group module functions in parallel with the /etc/group file. If the
user is granted any groups based on the behavior of this module, they are
granted iinn aaddddiittiioonn to those entries /etc/group (or equivalent).
66..1111..22.. DDEESSCCRRIIPPTTIIOONN
The pam_group PAM module does not authenticate the user, but instead it grants
group memberships (in the credential setting phase of the authentication
module) to the user. Such memberships are based on the service they are
applying for.
For this module to function correctly there must be a correctly formatted /etc/
security/group.conf file present. White spaces are ignored and lines maybe
extended with '\' (escaped newlines). Text following a '#' is ignored to the
end of the line.
The syntax of the lines is as follows:
sseerrvviicceess;ttttyyss;uusseerrss;ttiimmeess;ggrroouuppss
The first field, the sseerrvviicceess field, is a logic list of PAM service names that
the rule applies to.
The second field, the ttttyy field, is a logic list of terminal names that this
rule applies to.
The third field, the uusseerrss field, is a logic list of users, or a UNIX group, or
a netgroup of users to whom this rule applies. Group names are preceded by a
'%' symbol, while netgroup names are preceded by a '@' symbol.
For these items the simple wildcard '*' may be used only once. With UNIX groups
or netgroups no wildcards or logic operators are allowed.
The ttiimmeess field is used to indicate "when" these groups are to be given to the
user. The format here is a logic list of day/time-range entries. The days are
specified by a sequence of two character entries, MoTuSa for example is Monday
Tuesday and Saturday. Note that repeated days are unset MoMo = no day, and MoWk
= all weekdays bar Monday. The two character combinations accepted are Mo Tu We
Th Fr Sa Su Wk Wd Al, the last two being week-end days and all 7 days of the
week respectively. As a final example, AlFr means all days except Friday.
Each day/time-range can be prefixed with a '!' to indicate "anything but". The
time-range part is two 24-hour times HHMM, separated by a hyphen, indicating
the start and finish time (if the finish time is smaller than the start time it
is deemed to apply on the following day).
The ggrroouuppss field is a comma or space separated list of groups that the user
inherits membership of. These groups are added if the previous fields are
satisfied by the user's request.
For a rule to be active, ALL of service+ttys+users must be satisfied by the
applying process.
66..1111..33.. OOPPTTIIOONNSS
This module does not recognise any options.
66..1111..44.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the auth module type is provided.
66..1111..55.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      group membership was granted.
  PAM_ABORT
      Not all relevant data could be gotten.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_CRED_ERR
      Group membership was not granted.
  PAM_IGNORE
      pam_sm_authenticate was called which does nothing.
  PAM_USER_UNKNOWN
      The user is not known to the system.
66..1111..66.. FFIILLEESS
  /etc/security/group.conf
      Default configuration file
66..1111..77.. EEXXAAMMPPLLEESS
These are some example lines which might be specified in /etc/security/
group.conf.
Running 'xsh' on tty* (any ttyXXX device), the user 'us' is given access to the
floppy (through membership of the floppy group)
xsh;tty*&!ttyp*;us;Al0000-2400;floppy
Running 'xsh' on tty* (any ttyXXX device), the users 'sword', 'pike' and
'shield' are given access to games (through membership of the floppy group)
after work hours.
xsh; tty* ;sword|pike|shield;!Wk0900-1800;games, sound
xsh; tty* ;*;Al0900-1800;floppy
Any member of the group 'admin' running 'xsh' on tty*, is granted access (at
any time) to the group 'plugdev'
xsh; tty* ;%admin;Al0000-2400;plugdev
66..1111..88.. AAUUTTHHOORRSS
pam_group was written by Andrew G. Morgan <morgan@kernel.org>.
66..1122.. ppaamm__iissssuuee -- aadddd iissssuuee ffiillee ttoo uusseerr pprroommpptt
pam_issue.so [ noesc ] [ issue=iissssuuee--ffiillee--nnaammee ]
66..1122..11.. DDEESSCCRRIIPPTTIIOONN
pam_issue is a PAM module to prepend an issue file to the username prompt. It
also by default parses escape codes in the issue file similar to some common
getty's (using \x format).
Recognized escapes:
  \\dd
      current day
  \\ll
      name of this tty
  \\mm
      machine architecture (uname -m)
  \\nn
      machine's network node hostname (uname -n)
  \\oo
      domain name of this system
  \\rr
      release number of operating system (uname -r)
  \\tt
      current time
  \\ss
      operating system name (uname -s)
  \\uu
      number of users currently logged in
  \\UU
      same as \u except it is suffixed with "user" or "users" (eg. "1 user" or
      "10 users")
  \\vv
      operating system version and build date (uname -v)
66..1122..22.. OOPPTTIIOONNSS
  noesc
      Turns off escape code parsing.
  issue=iissssuuee--ffiillee--nnaammee
      The file to output if not using the default.
66..1122..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the auth module type is provided.
66..1122..44.. RREETTUURRNN VVAALLUUEESS
  PAM_BUF_ERR
      Memory buffer error.
  PAM_IGNORE
      The prompt was already changed.
  PAM_SERVICE_ERR
      A service module error occurred.
  PAM_SUCCESS
      The new prompt was set successfully.
66..1122..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to set the user specific issue at
login:
        auth optional pam_issue.so issue=/etc/issue
66..1122..66.. AAUUTTHHOORR
pam_issue was written by Ben Collins <bcollins@debian.org>.
66..1133.. ppaamm__kkeeyyiinniitt -- ddiissppllaayy tthhee kkeeyyiinniitt ffiillee
pam_keyinit.so [ debug ] [ force ] [ revoke ]
66..1133..11.. DDEESSCCRRIIPPTTIIOONN
The pam_keyinit PAM module ensures that the invoking process has a session
keyring other than the user default session keyring.
The session component of the module checks to see if the process's session
keyring is the user default, and, if it is, creates a new anonymous session
keyring with which to replace it.
If a new session keyring is created, it will install a link to the user common
keyring in the session keyring so that keys common to the user will be
automatically accessible through it.
The session keyring of the invoking process will thenceforth be inherited by
all its children unless they override it.
This module is intended primarily for use by login processes. Be aware that
after the session keyring has been replaced, the old session keyring and the
keys it contains will no longer be accessible.
This module should not, generally, be invoked by programs like ssuu, since it is
usually desirable for the key set to percolate through to the alternate
context. The keys have their own permissions system to manage this.
This module should be included as early as possible in a PAM configuration, so
that other PAM modules can attach tokens to the keyring.
The keyutils package is used to manipulate keys more directly. This can be
obtained from:
_K_e_y_u_t_i_l_s
66..1133..22.. OOPPTTIIOONNSS
  debug
      Log debug information with syslog(3).
  force
      Causes the session keyring of the invoking process to be replaced
      unconditionally.
  revoke
      Causes the session keyring of the invoking process to be revoked when the
      invoking process exits if the session keyring was created for this
      process in the first place.
66..1133..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided.
66..1133..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      This module will usually return this value
  PAM_AUTH_ERR
      Authentication failure.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_IGNORE
      The return value should be ignored by PAM dispatch.
  PAM_SERVICE_ERR
      Cannot determine the user name.
  PAM_SESSION_ERR
      This module will return this value if its arguments are invalid or if a
      system error such as ENOMEM occurs.
  PAM_USER_UNKNOWN
      User not known.
66..1133..55.. EEXXAAMMPPLLEESS
Add this line to your login entries to start each login session with its own
session keyring:
session  required  pam_keyinit.so
This will prevent keys from one session leaking into another session for the
same user.
66..1133..66.. AAUUTTHHOORR
pam_keyinit was written by David Howells, <dhowells@redhat.com>.
66..1144.. ppaamm__llaassttlloogg -- ddiissppllaayy ddaattee ooff llaasstt llooggiinn
pam_lastlog.so [ debug ] [ silent ] [ never ] [ nodate ] [ nohost ] [ noterm ]
[ nowtmp ] [ noupdate ] [ showfailed ] [ inactive=<days> ]
66..1144..11.. DDEESSCCRRIIPPTTIIOONN
pam_lastlog is a PAM module to display a line of information about the last
login of the user. In addition, the module maintains the /var/log/lastlog file.
Some applications may perform this function themselves. In such cases, this
module is not necessary.
If the module is called in the auth or account phase, the accounts that were
not used recently enough will be disallowed to log in. The check is not
performed for the root account so the root is never locked out.
66..1144..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  silent
      Don't inform the user about any previous login, just update the /var/log/
      lastlog file.
  never
      If the /var/log/lastlog file does not contain any old entries for the
      user, indicate that the user has never previously logged in with a
      welcome message.
  nodate
      Don't display the date of the last login.
  noterm
      Don't display the terminal name on which the last login was attempted.
  nohost
      Don't indicate from which host the last login was attempted.
  nowtmp
      Don't update the wtmp entry.
  noupdate
      Don't update any file.
  showfailed
      Display number of failed login attempts and the date of the last failed
      attempt from btmp. The date is not displayed when nodate is specified.
  inactive=<days>
      This option is specific for the auth or account phase. It specifies the
      number of days after the last login of the user when the user will be
      locked out by the module. The default value is 90.
66..1144..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and account module type allows to lock out users which did not login
recently enough. The session module type is provided for displaying the
information about the last login and/or updating the lastlog and wtmp files.
66..1144..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      Everything was successful.
  PAM_SERVICE_ERR
      Internal service module error.
  PAM_USER_UNKNOWN
      User not known.
  PAM_AUTH_ERR
      User locked out in the auth or account phase due to inactivity.
  PAM_IGNORE
      There was an error during reading the lastlog file in the auth or account
      phase and thus inactivity of the user cannot be determined.
66..1144..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to display the last login time of an
user:
    session  required  pam_lastlog.so nowtmp
To reject the user if he did not login during the previous 50 days the
following line can be used:
    auth  required  pam_lastlog.so inactive=50
66..1144..66.. AAUUTTHHOORR
pam_lastlog was written by Andrew G. Morgan <morgan@kernel.org>.
Inactive account lock out added by Toma Mrz <tm@t8m.info>.
66..1155.. ppaamm__lliimmiittss -- lliimmiitt rreessoouurrcceess
pam_limits.so [ conf=//ppaatthh//ttoo//lliimmiittss..ccoonnff ] [ debug ] [ set_all ] [ utmp_early
] [ noaudit ]
66..1155..11.. DDEESSCCRRIIPPTTIIOONN
The pam_limits PAM module sets limits on the system resources that can be
obtained in a user-session. Users of uuiidd==00 are affected by this limits, too.
By default limits are taken from the /etc/security/limits.conf config file.
Then individual *.conf files from the /etc/security/limits.d/ directory are
read. The files are parsed one after another in the order of "C" locale. The
effect of the individual files is the same as if all the files were
concatenated together in the order of parsing. If a config file is explicitly
specified with a module option then the files in the above directory are not
parsed.
The module must not be called by a multithreaded application.
If Linux PAM is compiled with audit support the module will report when it
denies access based on limit of maximum number of concurrent login sessions.
66..1155..22.. DDEESSCCRRIIPPTTIIOONN
The ppaamm__lliimmiittss..ssoo module applies ulimit limits, nice priority and number of
simultaneous login sessions limit to user login sessions. This description of
the configuration file syntax applies to the /etc/security/limits.conf file and
*.conf files in the /etc/security/limits.d directory.
The syntax of the lines is as follows:
<<ddoommaaiinn>> <<ttyyppee>> <<iitteemm>> <<vvaalluuee>>
The fields listed above should be filled as follows:
  <domain>
          * a username
          * a groupname, with @@ggrroouupp syntax. This should not be confused with
            netgroups.
          * the wildcard **, for default entry.
          * the wildcard %%, for maxlogins limit only, can also be used with
            %%ggrroouupp syntax. If the %% wildcard is used alone it is identical to
            using ** with maxsyslogins limit. With a group specified after %% it
            limits the total number of logins of all users that are member of
            the group.
          * an uid range specified as <<mmiinn__uuiidd>>::<<mmaaxx__uuiidd>>. If min_uid is
            omitted, the match is exact for the max_uid. If max_uid is omitted,
            all uids greater than or equal min_uid match.
          * a gid range specified as @@<<mmiinn__ggiidd>>::<<mmaaxx__ggiidd>>. If min_gid is
            omitted, the match is exact for the max_gid. If max_gid is omitted,
            all gids greater than or equal min_gid match. For the exact match
            all groups including the user's supplementary groups are examined.
            For the range matches only the user's primary group is examined.
          * a gid specified as %%::<<ggiidd>> applicable to maxlogins limit only. It
            limits the total number of logins of all users that are member of
            the group with the specified gid.
  <type>
        hard
            for enforcing hhaarrdd resource limits. These limits are set by the
            superuser and enforced by the Kernel. The user cannot raise his
            requirement of system resources above such values.
        soft
            for enforcing ssoofftt resource limits. These limits are ones that the
            user can move up or down within the permitted range by any pre-
            existing hhaarrdd limits. The values specified with this token can be
            thought of as ddeeffaauulltt values, for normal system usage.
        -
            for enforcing both ssoofftt and hhaarrdd resource limits together.
            Note, if you specify a type of '-' but neglect to supply the item
            and value fields then the module will never enforce any limits on
            the specified user/group etc. .
  <item>
        core
            limits the core file size (KB)
        data
            maximum data size (KB)
        fsize
            maximum filesize (KB)
        memlock
            maximum locked-in-memory address space (KB)
        nofile
            maximum number of open file descriptors
        rss
            maximum resident set size (KB) (Ignored in Linux 2.4.30 and higher)
        stack
            maximum stack size (KB)
        cpu
            maximum CPU time (minutes)
        nproc
            maximum number of processes
        as
            address space limit (KB)
        maxlogins
            maximum number of logins for this user (this limit does not apply
            to user with uuiidd==00)
        maxsyslogins
            maximum number of all logins on system; user is not allowed to log-
            in if total number of all user logins is greater than specified
            number (this limit does not apply to user with uuiidd==00)
        priority
            the priority to run user process with (negative values boost
            process priority)
        locks
            maximum locked files (Linux 2.4 and higher)
        sigpending
            maximum number of pending signals (Linux 2.6 and higher)
        msgqueue
            maximum memory used by POSIX message queues (bytes) (Linux 2.6 and
            higher)
        nice
            maximum nice priority allowed to raise to (Linux 2.6.12 and higher)
            values: [-20,19]
        rtprio
            maximum realtime priority allowed for non-privileged processes
            (Linux 2.6.12 and higher)
All items support the values --11, uunnlliimmiitteedd or iinnffiinniittyy indicating no limit,
except for pprriioorriittyy and nniiccee.
If a hard limit or soft limit of a resource is set to a valid value, but
outside of the supported range of the local system, the system may reject the
new limit or unexpected behavior may occur. If the control value rreeqquuiirreedd is
used, the module will reject the login if a limit could not be set.
In general, individual limits have priority over group limits, so if you impose
no limits for aaddmmiinn 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 ppeerr llooggiinn. They are not
global, nor are they permanent; existing only for the duration of the session.
One exception is the mmaaxxllooggiinn option, this one is system wide. But there is a
race, concurrent logins at the same time will not always be detect as such but
only counted as one.
In the lliimmiittss configuration file, the '##' character introduces a comment -
after which the rest of the line is ignored.
The pam_limits module does report configuration problems found in its
configuration file and errors via syslog(3).
66..1155..33.. OOPPTTIIOONNSS
  conf=//ppaatthh//ttoo//lliimmiittss..ccoonnff
      Indicate an alternative limits.conf style configuration file to override
      the default.
  debug
      Print debug information.
  set_all
      Set the limits for which no value is specified in the configuration file
      to the one from the process with the PID 1.
  utmp_early
      Some broken applications actually allocate a utmp entry for the user
      before the user is admitted to the system. If some of the services you
      are configuring PAM for do this, you can selectively use this module
      argument to compensate for this behavior and at the same time maintain
      system-wide consistency with a single limits.conf file.
  noaudit
      Do not report exceeded maximum logins count to the audit subsystem.
66..1155..44.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided.
66..1155..55.. RREETTUURRNN VVAALLUUEESS
  PAM_ABORT
      Cannot get current limits.
  PAM_IGNORE
      No limits found for this user.
  PAM_PERM_DENIED
      New limits could not be set.
  PAM_SERVICE_ERR
      Cannot read config file.
  PAM_SESSION_ERR
      Error recovering account name.
  PAM_SUCCESS
      Limits were changed.
  PAM_USER_UNKNOWN
      The user is not known to the system.
66..1155..66.. FFIILLEESS
  /etc/security/limits.conf
      Default configuration file
66..1155..77.. EEXXAAMMPPLLEESS
These are some example lines which might be specified in /etc/security/
limits.conf.
*               soft    core            0
*               hard    nofile          512
@student        hard    nproc           20
@faculty        soft    nproc           20
@faculty        hard    nproc           50
ftp             hard    nproc           0
@student        -       maxlogins       4
:123            hard    cpu             5000
@500:           soft    cpu             10000
600:700         hard    locks           10
66..1155..88.. AAUUTTHHOORRSS
pam_limits was initially written by Cristian Gafton <gafton@redhat.com>
66..1166.. ppaamm__lliissttffiillee -- ddeennyy oorr aallllooww sseerrvviicceess bbaasseedd oonn aann aarrbbiittrraarryy ffiillee
pam_listfile.so item=[tty|user|rhost|ruser|group|shell] sense=[allow|deny]
file=//ppaatthh//ffiilleennaammee onerr=[succeed|fail] [ apply=[uusseerr|@@ggrroouupp] ] [ quiet ]
66..1166..11.. DDEESSCCRRIIPPTTIIOONN
pam_listfile is a PAM module which provides a way to deny or allow services
based on an arbitrary file.
The module gets the item of the type specified -- uusseerr specifies the username,
PPAAMM__UUSSEERR; tty specifies the name of the terminal over which the request has
been made, PPAAMM__TTTTYY; rhost specifies the name of the remote host (if any) from
which the request was made, PPAAMM__RRHHOOSSTT; and ruser specifies the name of the
remote user (if available) who made the request, PPAAMM__RRUUSSEERR -- and looks for an
instance of that item in the file=ffiilleennaammee. filename contains one line per item
listed. If the item is found, then if sense=aallllooww, PPAAMM__SSUUCCCCEESSSS is returned,
causing the authorization request to succeed; else if sense=ddeennyy, PPAAMM__AAUUTTHH__EERRRR
is returned, causing the authorization request to fail.
If an error is encountered (for instance, if filename does not exist, or a
poorly-constructed argument is encountered), then if oonneerrrr==ssuucccceeeedd, PPAAMM__SSUUCCCCEESSSS
is returned, otherwise if oonneerrrr==ffaaiill, PPAAMM__AAUUTTHH__EERRRR or PPAAMM__SSEERRVVIICCEE__EERRRR (as
appropriate) will be returned.
An additional argument, apply=, can be used to restrict the application of the
above to a specific user (apply=uusseerrnnaammee) or a given group (apply=@@ggrroouuppnnaammee).
This added restriction is only meaningful when used with the ttttyy, rrhhoosstt and
sshheellll items.
Besides this last one, all arguments should be specified; do not count on any
default behavior.
No credentials are awarded by this module.
66..1166..22.. OOPPTTIIOONNSS
  item=[tty|user|rhost|ruser|group|shell]
      What is listed in the file and should be checked for.
  sense=[allow|deny]
      Action to take if found in file, if the item is NOT found in the file,
      then the opposite action is requested.
  file=//ppaatthh//ffiilleennaammee
      File containing one item per line. The file needs to be a plain file and
      not world writable.
  onerr=[succeed|fail]
      What to do if something weird happens like being unable to open the file.
  apply=[uusseerr|@@ggrroouupp]
      Restrict the user class for which the restriction apply. Note that with
      item=[user|ruser|group] this does not make sense, but for item=
      [tty|rhost|shell] it have a meaning.
  quiet
      Do not treat service refusals or missing list files as errors that need
      to be logged.
66..1166..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (auth, account, password and session) are provided.
66..1166..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      Authentication failure.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_IGNORE
      The rule does not apply to the apply option.
  PAM_SERVICE_ERR
      Error in service module.
  PAM_SUCCESS
      Success.
66..1166..55.. EEXXAAMMPPLLEESS
Classic 'ftpusers' authentication can be implemented with this entry in /etc/
pam.d/ftpd:
#
# deny ftp-access to users listed in the /etc/ftpusers file
#
auth    required       pam_listfile.so \
        onerr=succeed item=user sense=deny file=/etc/ftpusers
Note, users listed in /etc/ftpusers file are (counterintuitively) nnoott allowed
access to the ftp service.
To allow login access only for certain users, you can use a /etc/pam.d/login
entry like this:
#
# permit login to users listed in /etc/loginusers
#
auth    required       pam_listfile.so \
        onerr=fail item=user sense=allow file=/etc/loginusers
For this example to work, all users who are allowed to use the login service
should be listed in the file /etc/loginusers. Unless you are explicitly trying
to lock out root, make sure that when you do this, you leave a way for root to
log in, either by listing root in /etc/loginusers, or by listing a user who is
able to ssuu to the root account.
66..1166..66.. AAUUTTHHOORR
pam_listfile was written by Michael K. Johnson <johnsonm@redhat.com> and Elliot
Lee <sopwith@cuc.edu>.
66..1177.. ppaamm__llooccaalluusseerr -- rreeqquuiirree uusseerrss ttoo bbee lliisstteedd iinn //eettcc//ppaasssswwdd
pam_localuser.so [ debug ] [ file=//ppaatthh//ppaasssswwdd ]
66..1177..11.. DDEESSCCRRIIPPTTIIOONN
pam_localuser is a PAM module to help implementing site-wide login policies,
where they typically include a subset of the network's users and a few accounts
that are local to a particular workstation. Using pam_localuser and pam_wheel
or pam_listfile is an effective way to restrict access to either local users
and/or a subset of the network's users.
This could also be implemented using pam_listfile.so and a very short awk
script invoked by cron, but it's common enough to have been separated out.
66..1177..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  file=//ppaatthh//ppaasssswwdd
      Use a file other than /etc/passwd.
66..1177..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (account, auth, password and session) are provided.
66..1177..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The new localuser was set successfully.
  PAM_SERVICE_ERR
      No username was given.
  PAM_USER_UNKNOWN
      User not known.
66..1177..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/su to allow only local users in group
wheel to use su.
account sufficient pam_localuser.so
account required pam_wheel.so
66..1177..66.. AAUUTTHHOORR
pam_localuser was written by Nalin Dahyabhai <nalin@redhat.com>.
66..1188.. ppaamm__llooggiinnuuiidd -- rreeccoorrdd uusseerr''ss llooggiinn uuiidd ttoo tthhee pprroocceessss aattttrriibbuuttee
pam_loginuid.so [ require_auditd ]
66..1188..11.. DDEESSCCRRIIPPTTIIOONN
The pam_loginuid module sets the loginuid process attribute for the process
that was authenticated. This is necessary for applications to be correctly
audited. This PAM module should only be used for entry point applications like:
login, sshd, gdm, vsftpd, crond and atd. There are probably other entry point
applications besides these. You should not use it for applications like sudo or
su as that defeats the purpose by changing the loginuid to the account they
just switched to.
66..1188..22.. OOPPTTIIOONNSS
  require_auditd
      This option, when given, will cause this module to query the audit daemon
      status and deny logins if it is not running.
66..1188..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided.
66..1188..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The loginuid value is set and auditd is running if check requested.
  PAM_IGNORE
      The /proc/self/loginuid file is not present on the system or the login
      process runs inside uid namespace and kernel does not support overwriting
      loginuid.
  PAM_SESSION_ERR
      Any other error prevented setting loginuid or auditd is not running.
66..1188..55.. EEXXAAMMPPLLEESS
#%PAM-1.0
auth       required     pam_unix.so
auth       required     pam_nologin.so
account    required     pam_unix.so
password   required     pam_unix.so
session    required     pam_unix.so
session    required     pam_loginuid.so
66..1188..66.. AAUUTTHHOORR
pam_loginuid was written by Steve Grubb <sgrubb@redhat.com>
66..1199.. ppaamm__mmaaiill -- iinnffoorrmm aabboouutt aavvaaiillaabbllee mmaaiill
pam_mail.so [ close ] [ debug ] [ dir=mmaaiillddiirr ] [ empty ] [ hash=ccoouunntt ]
[ noenv ] [ nopen ] [ quiet ] [ standard ]
66..1199..11.. DDEESSCCRRIIPPTTIIOONN
The pam_mail PAM module provides the "you have new mail" service to the user.
It can be plugged into any application that has credential or session hooks. It
gives a single message indicating the nneewwnneessss of any mail it finds in the
user's mail folder. This module also sets the PAM environment variable, MMAAIILL,
to the user's mail directory.
If the mail spool file (be it /var/mail/$USER or a pathname given with the dir=
parameter) is a directory then pam_mail assumes it is in the MMaaiillddiirr format.
66..1199..22.. OOPPTTIIOONNSS
  close
      Indicate if the user has any mail also on logout.
  debug
      Print debug information.
  dir=mmaaiillddiirr
      Look for the user's mail in an alternative location defined by maildir/
      <login>. The default location for mail is /var/mail/<login>. Note, if the
      supplied maildir is prefixed by a '~', the directory is interpreted as
      indicating a file in the user's home directory.
  empty
      Also print message if user has no mail.
  hash=ccoouunntt
      Mail directory hash depth. For example, a hhaasshhccoouunntt of 2 would make the
      mail file be /var/spool/mail/u/s/user.
  noenv
      Do not set the MMAAIILL environment variable.
  nopen
      Don't print any mail information on login. This flag is useful to get the
      MMAAIILL environment variable set, but to not display any information about
      it.
  quiet
      Only report when there is new mail.
  standard
      Old style "You have..." format which doesn't show the mail spool being
      used. This also implies "empty".
66..1199..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The session and auth (on establishment and deletion of credentials) module
types are provided.
66..1199..44.. RREETTUURRNN VVAALLUUEESS
  PAM_BUF_ERR
      Memory buffer error.
  PAM_SERVICE_ERR
      Badly formed arguments.
  PAM_SUCCESS
      Success.
  PAM_USER_UNKNOWN
      User not known.
66..1199..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to indicate that the user has new
mail when they login to the system.
session  optional  pam_mail.so standard
66..1199..66.. AAUUTTHHOORR
pam_mail was written by Andrew G. Morgan <morgan@kernel.org>.
66..2200.. ppaamm__mmkkhhoommeeddiirr -- ccrreeaattee uusseerrss hhoommee ddiirreeccttoorryy
pam_mkhomedir.so [ silent ] [ umask=mmooddee ] [ skel=sskkeellddiirr ]
66..2200..11.. DDEESSCCRRIIPPTTIIOONN
The pam_mkhomedir PAM module will create a users home directory if it does not
exist when the session begins. This allows users to be present in central
database (such as NIS, kerberos or LDAP) without using a distributed file
system or pre-creating a large number of directories. The skeleton directory
(usually /etc/skel/) is used to copy default files and also sets a umask for
the creation.
The new users home directory will not be removed after logout of the user.
66..2200..22.. OOPPTTIIOONNSS
  silent
      Don't print informative messages.
  umask=mmaasskk
      The user file-creation mask is set to mmaasskk. The default value of mask is
      0022.
  skel=//ppaatthh//ttoo//sskkeell//ddiirreeccttoorryy
      Indicate an alternative skel directory to override the default /etc/skel.
66..2200..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided.
66..2200..44.. RREETTUURRNN VVAALLUUEESS
  PAM_BUF_ERR
      Memory buffer error.
  PAM_CRED_INSUFFICIENT
      Insufficient credentials to access authentication data.
  PAM_PERM_DENIED
      Not enough permissions to create the new directory or read the skel
      directory.
  PAM_USER_UNKNOWN
      User not known to the underlying authentication module.
  PAM_SUCCESS
      Environment variables were set.
66..2200..55.. EEXXAAMMPPLLEESS
A sample /etc/pam.d/login file:
  auth       requisite   pam_securetty.so
  auth       sufficient  pam_ldap.so
  auth       required    pam_unix.so
  auth       required    pam_nologin.so
  account    sufficient  pam_ldap.so
  account    required    pam_unix.so
  password   required    pam_unix.so
  session    required    pam_mkhomedir.so skel=/etc/skel/ umask=0022
  session    required    pam_unix.so
  session    optional    pam_lastlog.so
  session    optional    pam_mail.so standard
66..2200..66.. AAUUTTHHOORR
pam_mkhomedir was written by Jason Gunthorpe <jgg@debian.org>.
66..2211.. ppaamm__mmoottdd -- ddiissppllaayy tthhee mmoottdd ffiillee
pam_motd.so [ motd=//ppaatthh//ffiilleennaammee ]
66..2211..11.. DDEESSCCRRIIPPTTIIOONN
pam_motd is a PAM module that can be used to display arbitrary motd (message of
the day) files after a successful login. By default the /etc/motd file is
shown. The message size is limited to 64KB.
66..2211..22.. OOPPTTIIOONNSS
  motd=//ppaatthh//ffiilleennaammee
      The /path/filename file is displayed as message of the day.
66..2211..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided.
66..2211..44.. RREETTUURRNN VVAALLUUEESS
  PAM_IGNORE
      This is the only return value of this module.
66..2211..55.. EEXXAAMMPPLLEESS
The suggested usage for /etc/pam.d/login is:
session  optional  pam_motd.so  motd=/etc/motd
66..2211..66.. AAUUTTHHOORR
pam_motd was written by Ben Collins <bcollins@debian.org>.
66..2222.. ppaamm__nnaammeessppaaccee -- sseettuupp aa pprriivvaattee nnaammeessppaaccee
pam_namespace.so [ debug ] [ unmnt_remnt ] [ unmnt_only ] [ require_selinux ]
[ gen_hash ] [ ignore_config_error ] [ ignore_instance_parent_mode ]
[ unmount_on_close ] [ use_current_context ] [ use_default_context ]
[ mount_private ]
66..2222..11.. DDEESSCCRRIIPPTTIIOONN
The pam_namespace PAM module sets up a private namespace for a session with
polyinstantiated directories. A polyinstantiated directory provides a different
instance of itself based on user name, or when using SELinux, user name,
security context or both. If an executable script /etc/security/namespace.init
exists, it is used to initialize the instance directory after it is set up and
mounted on the polyinstantiated directory. The script receives the
polyinstantiated directory path, the instance directory path, flag whether the
instance directory was newly created (0 for no, 1 for yes), and the user name
as its arguments.
The pam_namespace module disassociates the session namespace from the parent
namespace. Any mounts/unmounts performed in the parent namespace, such as
mounting of devices, are not reflected in the session namespace. To propagate
selected mount/unmount events from the parent namespace into the disassociated
session namespace, an administrator may use the special shared-subtree feature.
For additional information on shared-subtree feature, please refer to the mount
(8) man page and the shared-subtree description at http://lwn.net/Articles/
159077 and http://lwn.net/Articles/159092.
66..2222..22.. DDEESSCCRRIIPPTTIIOONN
The ppaamm__nnaammeessppaaccee..ssoo module allows setup of private namespaces with
polyinstantiated directories. Directories can be polyinstantiated based on user
name or, in the case of SELinux, user name, sensitivity level or complete
security context. If an executable script /etc/security/namespace.init exists,
it is used to initialize the namespace every time an instance directory is set
up and mounted. The script receives the polyinstantiated directory path and the
instance directory path as its arguments.
The /etc/security/namespace.conf file specifies which directories are
polyinstantiated, how they are polyinstantiated, how instance directories would
be named, and any users for whom polyinstantiation would not be performed.
When someone logs in, the file namespace.conf is scanned. Comments are marked
by ## characters. Each non comment line represents one polyinstantiated
directory. The fields are separated by spaces but can be quoted by "" characters
also escape sequences \\bb, \\nn, and \\tt are recognized. The fields are as follows:
ppoollyyddiirr iinnssttaannccee__pprreeffiixx mmeetthhoodd lliisstt__ooff__uuiiddss
The first field, ppoollyyddiirr, is the absolute pathname of the directory to
polyinstantiate. The special string $$HHOOMMEE is replaced with the user's home
directory, and $$UUSSEERR with the username. This field cannot be blank.
The second field, iinnssttaannccee__pprreeffiixx is the string prefix used to build the
pathname for the instantiation of <polydir>. Depending on the polyinstantiation
mmeetthhoodd it is then appended with "instance differentiation string" to generate
the final instance directory path. This directory is created if it did not
exist already, and is then bind mounted on the <polydir> to provide an instance
of <polydir> based on the <method> column. The special string $$HHOOMMEE is replaced
with the user's home directory, and $$UUSSEERR with the username. This field cannot
be blank.
The third field, mmeetthhoodd, is the method used for polyinstantiation. It can take
these values; "user" for polyinstantiation based on user name, "level" for
polyinstantiation based on process MLS level and user name, "context" for
polyinstantiation based on process security context and user name, "tmpfs" for
mounting tmpfs filesystem as an instance dir, and "tmpdir" for creating
temporary directory as an instance dir which is removed when the user's session
is closed. Methods "context" and "level" are only available with SELinux. This
field cannot be blank.
The fourth field, lliisstt__ooff__uuiiddss, is a comma separated list of user names for
whom the polyinstantiation is not performed. If left blank, polyinstantiation
will be performed for all users. If the list is preceded with a single "~"
character, polyinstantiation is performed only for users in the list.
The mmeetthhoodd field can contain also following optional flags separated by ::
characters.
ccrreeaattee=mmooddee,oowwnneerr,ggrroouupp - create the polyinstantiated directory. The mode,
owner and group parameters are optional. The default for mode is determined by
umask, the default owner is the user whose session is opened, the default group
is the primary group of the user.
iissccrriipptt=ppaatthh - path to the instance directory init script. The base directory
for relative paths is /etc/security/namespace.d.
nnooiinniitt - instance directory init script will not be executed.
sshhaarreedd - the instance directories for "context" and "level" methods will not
contain the user name and will be shared among all users.
mmnnttooppttss=vvaalluuee - value of this flag is passed to the mount call when the tmpfs
mount is done. It allows for example the specification of the maximum size of
the tmpfs instance that is created by the mount call. See mount(8) for details.
The directory where polyinstantiated instances are to be created, must exist
and must have, by default, the mode of 0000. The requirement that the instance
parent be of mode 0000 can be overridden with the command line option
iiggnnoorree__iinnssttaannccee__ppaarreenntt__mmooddee
In case of context or level polyinstantiation the SELinux context which is used
for polyinstantiation is the context used for executing a new process as
obtained by getexeccon. This context must be set by the calling application or
pam_selinux.so module. If this context is not set the polyinstatiation will be
based just on user name.
The "instance differentiation string" is <user name> for "user" method and
<user name>_<raw directory context> for "context" and "level" methods. If the
whole string is too long the end of it is replaced with md5sum of itself. Also
when command line option ggeenn__hhaasshh is used the whole string is replaced with
md5sum of itself.
66..2222..33.. OOPPTTIIOONNSS
  debug
      A lot of debug information is logged using syslog
  unmnt_remnt
      For programs such as su and newrole, the login session has already setup
      a polyinstantiated namespace. For these programs, polyinstantiation is
      performed based on new user id or security context, however the command
      first needs to undo the polyinstantiation performed by login. This
      argument instructs the command to first undo previous polyinstantiation
      before proceeding with new polyinstantiation based on new id/context
  unmnt_only
      For trusted programs that want to undo any existing bind mounts and
      process instance directories on their own, this argument allows them to
      unmount currently mounted instance directories
  require_selinux
      If selinux is not enabled, return failure
  gen_hash
      Instead of using the security context string for the instance name,
      generate and use its md5 hash.
  ignore_config_error
      If a line in the configuration file corresponding to a polyinstantiated
      directory contains format error, skip that line process the next line.
      Without this option, pam will return an error to the calling program
      resulting in termination of the session.
  ignore_instance_parent_mode
      Instance parent directories by default are expected to have the
      restrictive mode of 000. Using this option, an administrator can choose
      to ignore the mode of the instance parent. This option should be used
      with caution as it will reduce security and isolation goals of the
      polyinstantiation mechanism.
  unmount_on_close
      Explicitly unmount the polyinstantiated directories instead of relying on
      automatic namespace destruction after the last process in a namespace
      exits. This option should be used only in case it is ensured by other
      means that there cannot be any processes running in the private namespace
      left after the session close. It is also useful only in case there are
      multiple pam session calls in sequence from the same process.
  use_current_context
      Useful for services which do not change the SELinux context with
      setexeccon call. The module will use the current SELinux context of the
      calling process for the level and context polyinstantiation.
  use_default_context
      Useful for services which do not use pam_selinux for changing the SELinux
      context with setexeccon call. The module will use the default SELinux
      context of the user for the level and context polyinstantiation.
  mount_private
      This option can be used on systems where the / mount point or its
      submounts are made shared (for example with a mmoouunntt ----mmaakkee--rrsshhaarreedd //
      command). The module will mark the whole directory tree so any mount and
      unmount operations in the polyinstantiation namespace are private.
      Normally the pam_namespace will try to detect the shared / mount point
      and make the polyinstantiated directories private automatically. This
      option has to be used just when only a subtree is shared and / is not.
      Note that mounts and unmounts done in the private namespace will not
      affect the parent namespace if this option is used or when the shared /
      mount point is autodetected.
66..2222..44.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided. The module must not be called from
multithreaded processes.
66..2222..55.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      Namespace setup was successful.
  PAM_SERVICE_ERR
      Unexpected system error occurred while setting up namespace.
  PAM_SESSION_ERR
      Unexpected namespace configuration error occurred.
66..2222..66.. FFIILLEESS
  /etc/security/namespace.conf
      Main configuration file
  /etc/security/namespace.d
      Directory for additional configuration files
  /etc/security/namespace.init
      Init script for instance directories
66..2222..77.. EEXXAAMMPPLLEESS
These are some example lines which might be specified in /etc/security/
namespace.conf.

      # The following three lines will polyinstantiate /tmp,
      # /var/tmp and user's home directories. /tmp and /var/tmp
      # will be polyinstantiated based on the security level
      # as well as user name, whereas home directory will be
      # polyinstantiated based on the full security context and user name.
      # Polyinstantiation will not be performed for user root
      # and adm for directories /tmp and /var/tmp, whereas home
      # directories will be polyinstantiated for all users.
      #
      # Note that instance directories do not have to reside inside
      # the polyinstantiated directory. In the examples below,
      # instances of /tmp will be created in /tmp-inst directory,
      # where as instances of /var/tmp and users home directories
      # will reside within the directories that are being
      # polyinstantiated.
      #
      /tmp     /tmp-inst/               level      root,adm
      /var/tmp /var/tmp/tmp-inst/    level      root,adm
      $HOME    $HOME/$USER.inst/inst- context
    
For the <service>s you need polyinstantiation (login for example) put the
following line in /etc/pam.d/<service> as the last line for session group:
session required pam_namespace.so [arguments]
This module also depends on pam_selinux.so setting the context.
66..2222..88.. AAUUTTHHOORRSS
The namespace setup scheme was designed by Stephen Smalley, Janak Desai and
Chad Sellers. The pam_namespace PAM module was developed by Janak Desai
<janak@us.ibm.com>, Chad Sellers <csellers@tresys.com> and Steve Grubb
<sgrubb@redhat.com>. Additional improvements by Xavier Toth <txtoth@gmail.com>
and Tomas Mraz <tmraz@redhat.com>.
66..2233.. ppaamm__nnoollooggiinn -- pprreevveenntt nnoonn--rroooott uusseerrss ffrroomm llooggiinn
pam_nologin.so [ file=//ppaatthh//nnoollooggiinn ] [ successok ]
66..2233..11.. DDEESSCCRRIIPPTTIIOONN
pam_nologin is a PAM module that prevents users from logging into the system
when /var/run/nologin or /etc/nologin exists. The contents of the file are
displayed to the user. The pam_nologin module has no effect on the root user's
ability to log in.
66..2233..22.. OOPPTTIIOONNSS
  file=//ppaatthh//nnoollooggiinn
      Use this file instead the default /var/run/nologin or /etc/nologin.
  successok
      Return PAM_SUCCESS if no file exists, the default is PAM_IGNORE.
66..2233..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and acct module types are provided.
66..2233..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      The user is not root and /etc/nologin exists, so the user is not
      permitted to log in.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_IGNORE
      This is the default return value.
  PAM_SUCCESS
      Success: either the user is root or the nologin file does not exist.
  PAM_USER_UNKNOWN
      User not known to the underlying authentication module.
66..2233..55.. EEXXAAMMPPLLEESS
The suggested usage for /etc/pam.d/login is:
auth  required  pam_nologin.so
66..2233..66.. AAUUTTHHOORR
pam_nologin was written by Michael K. Johnson <johnsonm@redhat.com>.
66..2244.. ppaamm__ppeerrmmiitt -- tthhee pprroommiissccuuoouuss mmoodduullee
pam_permit.so
66..2244..11.. DDEESSCCRRIIPPTTIIOONN
pam_permit is a PAM module that always permit access. It does nothing else.
In the case of authentication, the user's name will be set to nnoobbooddyy if the
application didn't set one. Many applications and PAM modules become confused
if this name is unknown.
This module is very dangerous. It should be used with extreme caution.
66..2244..22.. OOPPTTIIOONNSS
This module does not recognise any options.
66..2244..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth, account, password and session module types are provided.
66..2244..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      This module always returns this value.
66..2244..55.. EEXXAAMMPPLLEESS
Add this line to your other login entries to disable account management, but
continue to permit users to log in.
account  required  pam_permit.so
66..2244..66.. AAUUTTHHOORR
pam_permit was written by Andrew G. Morgan, <morgan@kernel.org>.
66..2255.. ppaamm__ppwwhhiissttoorryy -- ggrraanntt aacccceessss uussiinngg ..ppwwhhiissttoorryy ffiillee
pam_pwhistory.so [ debug ] [ use_authtok ] [ enforce_for_root ] [ remember=NN ]
[ retry=NN ] [ authtok_type=SSTTRRIINNGG ]
66..2255..11.. DDEESSCCRRIIPPTTIIOONN
This module saves the last passwords for each user in order to force password
change history and keep the user from alternating between the same password too
frequently.
This module does not work together with kerberos. In general, it does not make
much sense to use this module in conjunction with NIS or LDAP, since the old
passwords are stored on the local machine and are not available on another
machine for password history checking.
66..2255..22.. OOPPTTIIOONNSS
  debug
      Turns on debugging via syslog(3).
  use_authtok
      When password changing enforce the module to use the new password
      provided by a previously stacked password module (this is used in the
      example of the stacking of the ppaamm__ccrraacckklliibb module documented below).
  enforce_for_root
      If this option is set, the check is enforced for root, too.
  remember=NN
      The last NN passwords for each user are saved in /etc/security/opasswd.
      The default is 1100. Value of 00 makes the module to keep the existing
      contents of the opasswd file unchanged.
  retry=NN
      Prompt user at most NN times before returning with error. The default is
      11.
  authtok_type=SSTTRRIINNGG
      See pam_get_authtok(3) for more details.
66..2255..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the password module type is provided.
66..2255..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTHTOK_ERR
      No new password was entered, the user aborted password change or new
      password couldn't be set.
  PAM_IGNORE
      Password history was disabled.
  PAM_MAXTRIES
      Password was rejected too often.
  PAM_USER_UNKNOWN
      User is not known to system.
66..2255..55.. FFIILLEESS
  /etc/security/opasswd
      File with password history
66..2255..66.. EEXXAAMMPPLLEESS
An example password section would be:
#%PAM-1.0
password     required       pam_pwhistory.so
password     required       pam_unix.so        use_authtok
In combination with ppaamm__ccrraacckklliibb:
#%PAM-1.0
password     required       pam_cracklib.so    retry=3
password     required       pam_pwhistory.so   use_authtok
password     required       pam_unix.so        use_authtok
66..2255..77.. AAUUTTHHOORR
pam_pwhistory was written by Thorsten Kukuk <kukuk@thkukuk.de>
66..2266.. ppaamm__rrhhoossttss -- ggrraanntt aacccceessss uussiinngg ..rrhhoossttss ffiillee
pam_rhosts.so
66..2266..11.. DDEESSCCRRIIPPTTIIOONN
This module performs the standard network authentication for services, as used
by traditional implementations of rrllooggiinn and rrsshh etc.
The authentication mechanism of this module is based on the contents of two
files; /etc/hosts.equiv (or and ~/.rhosts. Firstly, hosts listed in the former
file are treated as equivalent to the localhost. Secondly, entries in the
user's own copy of the latter file is used to map "rreemmoottee--hhoosstt rreemmoottee--uusseerr"
pairs to that user's account on the current host. Access is granted to the user
if their host is present in /etc/hosts.equiv and their remote account is
identical to their local one, or if their remote account has an entry in their
personal configuration file.
The module authenticates a remote user (internally specified by the item
PPAAMM__RRUUSSEERR connecting from the remote host (internally specified by the item
PPAAMM__RRHHOOSSTT). Accordingly, for applications to be compatible this authentication
module they must set these items prior to calling pam_authenticate(). The
module is not capable of independently probing the network connection for such
information.
66..2266..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  silent
      Don't print informative messages.
  superuser=aaccccoouunntt
      Handle aaccccoouunntt as root.
66..2266..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the auth module type is provided.
66..2266..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      The remote host, remote user name or the local user name couldn't be
      determined or access was denied by .rhosts file.
  PAM_USER_UNKNOWN
      User is not known to system.
66..2266..55.. EEXXAAMMPPLLEESS
To grant a remote user access by /etc/hosts.equiv or .rhosts for rrsshh add the
following lines to /etc/pam.d/rsh:
#%PAM-1.0
#
auth     required       pam_rhosts.so
auth     required       pam_nologin.so
auth     required       pam_env.so
auth     required       pam_unix.so
66..2266..66.. AAUUTTHHOORR
pam_rhosts was written by Thorsten Kukuk <kukuk@thkukuk.de>
66..2277.. ppaamm__rroooottookk -- ggaaiinn oonnllyy rroooott aacccceessss
pam_rootok.so [ debug ]
66..2277..11.. DDEESSCCRRIIPPTTIIOONN
pam_rootok is a PAM module that authenticates the user if their UUIIDD is 00.
Applications that are created setuid-root generally retain the UUIIDD of the user
but run with the authority of an enhanced effective-UID. It is the real UUIIDD
that is checked.
66..2277..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
66..2277..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth, acct and password module types are provided.
66..2277..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The UUIIDD is 00.
  PAM_AUTH_ERR
      The UUIIDD is nnoott 00.
66..2277..55.. EEXXAAMMPPLLEESS
In the case of the su(1) application the historical usage is to permit the
superuser to adopt the identity of a lesser user without the use of a password.
To obtain this behavior with PAM the following pair of lines are needed for the
corresponding entry in the /etc/pam.d/su configuration file:
# su authentication. Root is granted access by default.
auth  sufficient   pam_rootok.so
auth  required     pam_unix.so
66..2277..66.. AAUUTTHHOORR
pam_rootok was written by Andrew G. Morgan, <morgan@kernel.org>.
66..2288.. ppaamm__sseeccuurreettttyy -- lliimmiitt rroooott llooggiinn ttoo ssppeecciiaall ddeevviicceess
pam_securetty.so [ debug ]
66..2288..11.. DDEESSCCRRIIPPTTIIOONN
pam_securetty is a PAM module that allows root logins only if the user is
logging in on a "secure" tty, as defined by the listing in /etc/securetty.
pam_securetty also checks to make sure that /etc/securetty is a plain file and
not world writable. It will also allow root logins on the tty specified with
console= switch on the kernel command line and on ttys from the /sys/class/tty/
console/active.
This module has no effect on non-root users and requires that the application
fills in the PPAAMM__TTTTYY item correctly.
For canonical usage, should be listed as a rreeqquuiirreedd authentication method
before any ssuuffffiicciieenntt authentication methods.
66..2288..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  noconsole
      Do not automatically allow root logins on the kernel console device, as
      specified on the kernel command line or by the sys file, if it is not
      also specified in the /etc/securetty file.
66..2288..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the auth module type is provided.
66..2288..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The user is allowed to continue authentication. Either the user is not
      root, or the root user is trying to log in on an acceptable device.
  PAM_AUTH_ERR
      Authentication is rejected. Either root is attempting to log in via an
      unacceptable device, or the /etc/securetty file is world writable or not
      a normal file.
  PAM_INCOMPLETE
      An application error occurred. pam_securetty was not able to get
      information it required from the application that called it.
  PAM_SERVICE_ERR
      An error occurred while the module was determining the user's name or
      tty, or the module could not open /etc/securetty.
  PAM_USER_UNKNOWN
      The module could not find the user name in the /etc/passwd file to verify
      whether the user had a UID of 0. Therefore, the results of running this
      module are ignored.
66..2288..55.. EEXXAAMMPPLLEESS
auth  required  pam_securetty.so
auth  required  pam_unix.so
66..2288..66.. AAUUTTHHOORR
pam_securetty was written by Elliot Lee <sopwith@cuc.edu>.
66..2299.. ppaamm__sseelliinnuuxx -- sseett tthhee ddeeffaauulltt sseeccuurriittyy ccoonntteexxtt
pam_selinux.so [ open ] [ close ] [ restore ] [ nottys ] [ debug ] [ verbose ]
[ select_context ] [ env_params ] [ use_current_range ]
66..2299..11.. DDEESSCCRRIIPPTTIIOONN
pam_selinux is a PAM module that sets up the default SELinux security context
for the next executed process.
When a new session is started, the open_session part of the module computes and
sets up the execution security context used for the next execve(2) call, the
file security context for the controlling terminal, and the security context
used for creating a new kernel keyring.
When the session is ended, the close_session part of the module restores old
security contexts that were in effect before the change made by the
open_session part of the module.
Adding pam_selinux into the PAM stack might disrupt behavior of other PAM
modules which execute applications. To avoid that, ppaamm__sseelliinnuuxx..ssoo ooppeenn should
be placed after such modules in the PAM stack, and ppaamm__sseelliinnuuxx..ssoo cclloossee should
be placed before them. When such a placement is not feasible, ppaamm__sseelliinnuuxx..ssoo
rreessttoorree could be used to temporary restore original security contexts.
66..2299..22.. OOPPTTIIOONNSS
  open
      Only execute the open_session part of the module.
  close
      Only execute the close_session part of the module.
  restore
      In open_session part of the module, temporarily restore the security
      contexts as they were before the previous call of the module. Another
      call of this module without the restore option will set up the new
      security contexts again.
  nottys
      Do not setup security context of the controlling terminal.
  debug
      Turn on debug messages via syslog(3).
  verbose
      Attempt to inform the user when security context is set.
  select_context
      Attempt to ask the user for a custom security context role. If MLS is on,
      ask also for sensitivity level.
  env_params
      Attempt to obtain a custom security context role from PAM environment. If
      MLS is on, obtain also sensitivity level. This option and the
      select_context option are mutually exclusive. The respective PAM
      environment variables are SSEELLIINNUUXX__RROOLLEE__RREEQQUUEESSTTEEDD,
      SSEELLIINNUUXX__LLEEVVEELL__RREEQQUUEESSTTEEDD, and SSEELLIINNUUXX__UUSSEE__CCUURRRREENNTT__RRAANNGGEE. The first two
      variables are self describing and the last one if set to 1 makes the PAM
      module behave as if the use_current_range was specified on the command
      line of the module.
  use_current_range
      Use the sensitivity level of the current process for the user context
      instead of the default level. Also suppresses asking of the sensitivity
      level from the user or obtaining it from PAM environment.
66..2299..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session module type is provided.
66..2299..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The security context was set successfully.
  PAM_SESSION_ERR
      Unable to get or set a valid context.
  PAM_USER_UNKNOWN
      The user is not known to the system.
  PAM_BUF_ERR
      Memory allocation error.
66..2299..55.. EEXXAAMMPPLLEESS
auth     required  pam_unix.so
session  required  pam_permit.so
session  optional  pam_selinux.so
66..2299..66.. AAUUTTHHOORR
pam_selinux was written by Dan Walsh <dwalsh@redhat.com>.
66..3300.. ppaamm__sshheellllss -- cchheecckk ffoorr vvaalliidd llooggiinn sshheellll
pam_shells.so
66..3300..11.. DDEESSCCRRIIPPTTIIOONN
pam_shells is a PAM module that only allows access to the system if the user's
shell is listed in /etc/shells.
It also checks if /etc/shells is a plain file and not world writable.
66..3300..22.. OOPPTTIIOONNSS
This module does not recognise any options.
66..3300..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and account module types are provided.
66..3300..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      Access to the system was denied.
  PAM_SUCCESS
      The user's login shell was listed as valid shell in /etc/shells.
  PAM_SERVICE_ERR
      The module was not able to get the name of the user.
66..3300..55.. EEXXAAMMPPLLEESS
auth  required  pam_shells.so
66..3300..66.. AAUUTTHHOORR
pam_shells was written by Erik Troan <ewt@redhat.com>.
66..3311.. ppaamm__ssuucccceeeedd__iiff -- tteesstt aaccccoouunntt cchhaarraacctteerriissttiiccss
pam_succeed_if.so [ffllaagg...] [ccoonnddiittiioonn...]
66..3311..11.. DDEESSCCRRIIPPTTIIOONN
pam_succeed_if.so is designed to succeed or fail authentication based on
characteristics of the account belonging to the user being authenticated or
values of other PAM items. One use is to select whether to load other modules
based on this test.
The module should be given one or more conditions as module arguments, and
authentication will succeed only if all of the conditions are met.
66..3311..22.. OOPPTTIIOONNSS
The following ffllaaggs are supported:
  debug
      Turns on debugging messages sent to syslog.
  use_uid
      Evaluate conditions using the account of the user whose UID the
      application is running under instead of the user being authenticated.
  quiet
      Don't log failure or success to the system log.
  quiet_fail
      Don't log failure to the system log.
  quiet_success
      Don't log success to the system log.
  audit
      Log unknown users to the system log.
CCoonnddiittiioonns are three words: a field, a test, and a value to test for.
Available fields are uusseerr, uuiidd, ggiidd, sshheellll, hhoommee, rruusseerr, rrhhoosstt, ttttyy and
sseerrvviiccee:
  field < number
      Field has a value numerically less than number.
  field <= number
      Field has a value numerically less than or equal to number.
  field eq number
      Field has a value numerically equal to number.
  field >= number
      Field has a value numerically greater than or equal to number.
  field > number
      Field has a value numerically greater than number.
  field ne number
      Field has a value numerically different from number.
  field = string
      Field exactly matches the given string.
  field != string
      Field does not match the given string.
  field =~ glob
      Field matches the given glob.
  field !~ glob
      Field does not match the given glob.
  field in item:item:...
      Field is contained in the list of items separated by colons.
  field notin item:item:...
      Field is not contained in the list of items separated by colons.
  user ingroup group
      User is in given group.
  user notingroup group
      User is not in given group.
  user innetgr netgroup
      (user,host) is in given netgroup.
  user notinnetgr group
      (user,host) is not in given netgroup.
66..3311..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (account, auth, password and session) are provided.
66..3311..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The condition was true.
  PAM_AUTH_ERR
      The condition was false.
  PAM_SERVICE_ERR
      A service error occurred or the arguments can't be parsed correctly.
66..3311..55.. EEXXAAMMPPLLEESS
To emulate the behaviour of ppaamm__wwhheeeell, except there is no fallback to group 0:
auth required pam_succeed_if.so quiet user ingroup wheel
Given that the type matches, only loads the othermodule rule if the UID is over
500. Adjust the number after default to skip several rules.
type [default=1 success=ignore] pam_succeed_if.so quiet uid > 500
type required othermodule.so arguments...
66..3311..66.. AAUUTTHHOORR
Nalin Dahyabhai <nalin@redhat.com>
66..3322.. ppaamm__ttaallllyy -- llooggiinn ccoouunntteerr ((ttaallllyyiinngg)) mmoodduullee
pam_tally.so [ file=//ppaatthh//ttoo//ccoouunntteerr ] [ onerr=[ffaaiill|ssuucccceeeedd] ] [ magic_root ]
[ even_deny_root_account ] [ deny=nn ] [ lock_time=nn ] [ unlock_time=nn ]
[ per_user ] [ no_lock_time ] [ no_reset ] [ audit ] [ silent ] [ no_log_info ]
pam_tally [ --file //ppaatthh//ttoo//ccoouunntteerr ] [ --user uusseerrnnaammee ] [ --reset[=nn] ] [ --
quiet ]
66..3322..11.. DDEESSCCRRIIPPTTIIOONN
This module maintains a count of attempted accesses, can reset count on
success, can deny access if too many attempts fail.
pam_tally has several limitations, which are solved with pam_tally2. For this
reason pam_tally is deprecated and will be removed in a future release.
pam_tally comes in two parts: ppaamm__ttaallllyy..ssoo and ppaamm__ttaallllyy. The former is the PAM
module and the latter, a stand-alone program. ppaamm__ttaallllyy is an (optional)
application which can be used to interrogate and manipulate the counter file.
It can display user counts, set individual counts, or clear all counts. Setting
artificially high counts may be useful for blocking users without changing
their passwords. For example, one might find it useful to clear all counts
every midnight from a cron job. The faillog(8) command can be used instead of
pam_tally to to maintain the counter file.
Normally, failed attempts to access rroooott will nnoott cause the root account to
become blocked, to prevent denial-of-service: if your users aren't given shell
accounts and root may only login via ssuu or at the machine console (not telnet/
rsh, etc), this is safe.
66..3322..22.. OOPPTTIIOONNSS
  GLOBAL OPTIONS
      This can be used for aauutthh and aaccccoouunntt module types.
        onerr=[ffaaiill|ssuucccceeeedd]
            If something weird happens (like unable to open the file), return
            with PAM_SUCCESS if onerr=ssuucccceeeedd is given, else with the
            corresponding PAM error code.
        file=//ppaatthh//ttoo//ccoouunntteerr
            File where to keep counts. Default is /var/log/faillog.
        audit
            Will log the user name into the system log if the user is not
            found.
        silent
            Don't print informative messages.
        no_log_info
            Don't log informative messages via syslog(3).
  AUTH OPTIONS
      Authentication phase first checks if user should be denied access and if
      not it increments attempted login counter. Then on call to pam_setcred(3)
      it resets the attempts counter.
        deny=nn
            Deny access if tally for this user exceeds nn.
        lock_time=nn
            Always deny for nn seconds after failed attempt.
        unlock_time=nn
            Allow access after nn seconds after failed attempt. If this option
            is used the user will be locked out for the specified amount of
            time after he exceeded his maximum allowed attempts. Otherwise the
            account is locked until the lock is removed by a manual
            intervention of the system administrator.
        magic_root
            If the module is invoked by a user with uid=0 the counter is not
            incremented. The sysadmin should use this for user launched
            services, like ssuu, otherwise this argument should be omitted.
        no_lock_time
            Do not use the .fail_locktime field in /var/log/faillog for this
            user.
        no_reset
            Don't reset count on successful entry, only decrement.
        even_deny_root_account
            Root account can become unavailable.
        per_user
            If /var/log/faillog contains a non-zero .fail_max/.fail_locktime
            field for this user then use it instead of deny=nn/ lock_time=nn
            parameter.
        no_lock_time
            Don't use .fail_locktime filed in /var/log/faillog for this user.
  ACCOUNT OPTIONS
      Account phase resets attempts counter if the user is nnoott magic root. This
      phase can be used optionally for services which don't call pam_setcred(3)
      correctly or if the reset should be done regardless of the failure of the
      account phase of other modules.
        magic_root
            If the module is invoked by a user with uid=0 the counter is not
            incremented. The sysadmin should use this for user launched
            services, like ssuu, otherwise this argument should be omitted.
        no_reset
            Don't reset count on successful entry, only decrement.
66..3322..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and account module types are provided.
66..3322..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      A invalid option was given, the module was not able to retrieve the user
      name, no valid counter file was found, or too many failed logins.
  PAM_SUCCESS
      Everything was successful.
  PAM_USER_UNKNOWN
      User not known.
66..3322..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to lock the account after too many
failed logins. The number of allowed fails is specified by /var/log/faillog and
needs to be set with pam_tally or faillog(8) before.
auth     required       pam_securetty.so
auth     required       pam_tally.so per_user
auth     required       pam_env.so
auth     required       pam_unix.so
auth     required       pam_nologin.so
account  required       pam_unix.so
password required       pam_unix.so
session  required       pam_limits.so
session  required       pam_unix.so
session  required       pam_lastlog.so nowtmp
session  optional       pam_mail.so standard
66..3322..66.. AAUUTTHHOORR
pam_tally was written by Tim Baverstock and Tomas Mraz.
66..3333.. ppaamm__ttaallllyy22 -- llooggiinn ccoouunntteerr ((ttaallllyyiinngg)) mmoodduullee
pam_tally2.so [ file=//ppaatthh//ttoo//ccoouunntteerr ] [ onerr=[ffaaiill|ssuucccceeeedd] ] [ magic_root ]
[ even_deny_root ] [ deny=nn ] [ lock_time=nn ] [ unlock_time=nn ]
[ root_unlock_time=nn ] [ serialize ] [ audit ] [ silent ] [ no_log_info ]
[ debug ]
pam_tally2 [ --file //ppaatthh//ttoo//ccoouunntteerr ] [ --user uusseerrnnaammee ] [ --reset[=nn] ] [ --
quiet ]
66..3333..11.. DDEESSCCRRIIPPTTIIOONN
This module maintains a count of attempted accesses, can reset count on
success, can deny access if too many attempts fail.
pam_tally2 comes in two parts: ppaamm__ttaallllyy22..ssoo and ppaamm__ttaallllyy22. The former is the
PAM module and the latter, a stand-alone program. ppaamm__ttaallllyy22 is an (optional)
application which can be used to interrogate and manipulate the counter file.
It can display user 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.
Normally, failed attempts to access rroooott will nnoott cause the root account to
become blocked, to prevent denial-of-service: if your users aren't given shell
accounts and root may only login via ssuu or at the machine console (not telnet/
rsh, etc), this is safe.
66..3333..22.. OOPPTTIIOONNSS
  GLOBAL OPTIONS
      This can be used for aauutthh and aaccccoouunntt module types.
        onerr=[ffaaiill|ssuucccceeeedd]
            If something weird happens (like unable to open the file), return
            with PAM_SUCCESS if onerr=ssuucccceeeedd is given, else with the
            corresponding PAM error code.
        file=//ppaatthh//ttoo//ccoouunntteerr
            File where to keep counts. Default is /var/log/tallylog.
        audit
            Will log the user name into the system log if the user is not
            found.
        silent
            Don't print informative messages.
        no_log_info
            Don't log informative messages via syslog(3).
        debug
            Always log tally count when it is incremented as a debug level
            message to the system log.
  AUTH OPTIONS
      Authentication phase first increments attempted login counter and checks
      if user should be denied access. If the user is authenticated and the
      login process continues on call to pam_setcred(3) it resets the attempts
      counter.
        deny=nn
            Deny access if tally for this user exceeds nn.
        lock_time=nn
            Always deny for nn seconds after failed attempt.
        unlock_time=nn
            Allow access after nn seconds after failed attempt. If this option
            is used the user will be locked out for the specified amount of
            time after he exceeded his maximum allowed attempts. Otherwise the
            account is locked until the lock is removed by a manual
            intervention of the system administrator.
        magic_root
            If the module is invoked by a user with uid=0 the counter is not
            incremented. The sysadmin should use this for user launched
            services, like ssuu, otherwise this argument should be omitted.
        even_deny_root
            Root account can become unavailable.
        root_unlock_time=nn
            This option implies even_deny_root option. Allow access after nn
            seconds to root account after failed attempt. If this option is
            used the root user will be locked out for the specified amount of
            time after he exceeded his maximum allowed attempts.
        serialize
            Serialize access to the tally file using locks. This option might
            be used only for non-multithreaded services because it depends on
            the fcntl locking of the tally file. Also it is a good idea to use
            this option only in such configurations where the time between auth
            phase and account or setcred phase is not dependent on the
            authenticating client. Otherwise the authenticating client will be
            able to prevent simultaneous authentications by the same user by
            simply artificially prolonging the time the file record lock is
            held.
  ACCOUNT OPTIONS
      Account phase resets attempts counter if the user is nnoott magic root. This
      phase can be used optionally for services which don't call pam_setcred(3)
      correctly or if the reset should be done regardless of the failure of the
      account phase of other modules.
        magic_root
            If the module is invoked by a user with uid=0 the counter is not
            changed. The sysadmin should use this for user launched services,
            like ssuu, otherwise this argument should be omitted.
66..3333..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and account module types are provided.
66..3333..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      A invalid option was given, the module was not able to retrieve the user
      name, no valid counter file was found, or too many failed logins.
  PAM_SUCCESS
      Everything was successful.
  PAM_USER_UNKNOWN
      User not known.
66..3333..55.. NNOOTTEESS
pam_tally2 is not compatible with the old pam_tally faillog file format. This
is caused by requirement of compatibility of the tallylog file format between
32bit and 64bit architectures on multiarch systems.
There is no setuid wrapper for access to the data file such as when the
ppaamm__ttaallllyy22..ssoo module is called from xscreensaver. As this would make it
impossible to share PAM configuration with such services the following
workaround is used: If the data file cannot be opened because of insufficient
permissions (EACCES) the module returns PAM_IGNORE.
66..3333..66.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to lock the account after 4 failed
logins. Root account will be locked as well. The accounts will be automatically
unlocked after 20 minutes. The module does not have to be called in the account
phase because the llooggiinn calls pam_setcred(3) correctly.
auth     required       pam_securetty.so
auth     required       pam_tally2.so deny=4 even_deny_root unlock_time=1200
auth     required       pam_env.so
auth     required       pam_unix.so
auth     required       pam_nologin.so
account  required       pam_unix.so
password required       pam_unix.so
session  required       pam_limits.so
session  required       pam_unix.so
session  required       pam_lastlog.so nowtmp
session  optional       pam_mail.so standard
66..3333..77.. FFIILLEESS
  /var/log/tallylog
      failure count logging file
66..3333..88.. AAUUTTHHOORR
pam_tally2 was written by Tim Baverstock and Tomas Mraz.
66..3344.. ppaamm__ttiimmee -- ttiimmee ccoonnttrroolleedd aacccceessss
pam_time.so [ debug ] [ noaudit ]
66..3344..11.. DDEESSCCRRIIPPTTIIOONN
The pam_time PAM module does not authenticate the user, but instead it
restricts access to a system and or specific applications at various times of
the day and on specific days or over various terminal lines. This module can be
configured to deny access to (individual) users based on their name, the time
of day, the day of week, the service they are applying for and their terminal
from which they are making their request.
By default rules for time/port access are taken from config file /etc/security/
time.conf.
If Linux PAM is compiled with audit support the module will report when it
denies access.
66..3344..22.. DDEESSCCRRIIPPTTIIOONN
The pam_time PAM module does not authenticate the user, but instead it
restricts access to a system and or specific applications at various times of
the day and on specific days or over various terminal lines. This module can be
configured to deny access to (individual) users based on their name, the time
of day, the day of week, the service they are applying for and their terminal
from which they are making their request.
For this module to function correctly there must be a correctly formatted /etc/
security/time.conf file present. White spaces are ignored and lines maybe
extended with '\' (escaped newlines). Text following a '#' is ignored to the
end of the line.
The syntax of the lines is as follows:
sseerrvviicceess;ttttyyss;uusseerrss;ttiimmeess
In words, each rule occupies a line, terminated with a newline or the beginning
of a comment; a '##'. It contains four fields separated with semicolons, ';;'.
The first field, the sseerrvviicceess field, is a logic list of PAM service names that
the rule applies to.
The second field, the ttttyy field, is a logic list of terminal names that this
rule applies to.
The third field, the uusseerrss field, is a logic list of users or a netgroup of
users to whom this rule applies.
For these items the simple wildcard '*' may be used only once. With netgroups
no wildcards or logic operators are allowed.
The ttiimmeess field is used to indicate the times at which this rule applies. The
format here is a logic list of day/time-range entries. The days are specified
by a sequence of two character entries, MoTuSa for example is Monday Tuesday
and Saturday. Note that repeated days are unset MoMo = no day, and MoWk = all
weekdays bar Monday. The two character combinations accepted are Mo Tu We Th Fr
Sa Su Wk Wd Al, the last two being week-end days and all 7 days of the week
respectively. As a final example, AlFr means all days except Friday.
Each day/time-range can be prefixed with a '!' to indicate "anything but". The
time-range part is two 24-hour times HHMM, separated by a hyphen, indicating
the start and finish time (if the finish time is smaller than the start time it
is deemed to apply on the following day).
For a rule to be active, ALL of service+ttys+users must be satisfied by the
applying process.
Note, currently there is no daemon enforcing the end of a session. This needs
to be remedied.
Poorly formatted rules are logged as errors using syslog(3).
66..3344..33.. OOPPTTIIOONNSS
  debug
      Some debug information is printed with syslog(3).
  noaudit
      Do not report logins at disallowed time to the audit subsystem.
66..3344..44.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the account type is provided.
66..3344..55.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      Access was granted.
  PAM_ABORT
      Not all relevant data could be gotten.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_PERM_DENIED
      Access was not granted.
  PAM_USER_UNKNOWN
      The user is not known to the system.
66..3344..66.. FFIILLEESS
  /etc/security/time.conf
      Default configuration file
66..3344..77.. EEXXAAMMPPLLEESS
These are some example lines which might be specified in /etc/security/
time.conf.
All users except for rroooott are denied access to console-login at all times:
login ; tty* & !ttyp* ; !root ; !Al0000-2400
Games (configured to use PAM) are only to be accessed out of working hours.
This rule does not apply to the user wwaasstteerr:
games ; * ; !waster ; Wd0000-2400 | Wk1800-0800
66..3344..88.. AAUUTTHHOORR
pam_time was written by Andrew G. Morgan <morgan@kernel.org>.
66..3355.. ppaamm__ttiimmeessttaammpp -- aauutthheennttiiccaattee uussiinngg ccaacchheedd ssuucccceessssffuull aauutthheennttiiccaattiioonn
aatttteemmppttss
pam_timestamp.so [ timestampdir=ddiirreeccttoorryy ] [ timestamp_timeout=nnuummbbeerr ]
[ verbose ] [ debug ]
66..3355..11.. DDEESSCCRRIIPPTTIIOONN
In a nutshell, ppaamm__ttiimmeessttaammpp caches successful authentication attempts, and
allows you to use a recent successful attempt as the basis for authentication.
This is similar mechanism which is used in ssuuddoo.
When an application opens a session using ppaamm__ttiimmeessttaammpp, a timestamp file is
created in the ttiimmeessttaammppddiirr directory for the user. When an application
attempts to authenticate the user, a ppaamm__ttiimmeessttaammpp will treat a sufficiently
recent timestamp file as grounds for succeeding.
66..3355..22.. OOPPTTIIOONNSS
  timestampdir=ddiirreeccttoorryy
      Specify an alternate directory where ppaamm__ttiimmeessttaammpp creates timestamp
      files.
  timestamp_timeout=nnuummbbeerr
      How long should ppaamm__ttiimmeessttaammpp treat timestamp as valid after their last
      modification date (in seconds). Default is 300 seconds.
  verbose
      Attempt to inform the user when access is granted.
  debug
      Turns on debugging messages sent to syslog(3).
66..3355..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and session module types are provided.
66..3355..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      The module was not able to retrieve the user name or no valid timestamp
      file was found.
  PAM_SUCCESS
      Everything was successful.
  PAM_SESSION_ERR
      Timestamp file could not be created or updated.
66..3355..55.. NNOOTTEESS
Users can get confused when they are not always asked for passwords when
running a given program. Some users reflexively begin typing information before
noticing that it is not being asked for.
66..3355..66.. EEXXAAMMPPLLEESS
auth sufficient pam_timestamp.so verbose
auth required   pam_unix.so

session required pam_unix.so
session optional pam_timestamp.so
66..3355..77.. FFIILLEESS
  /var/run/pam_timestamp/...
      timestamp files and directories
66..3355..88.. AAUUTTHHOORR
pam_timestamp was written by Nalin Dahyabhai.
66..3366.. ppaamm__uummaasskk -- sseett tthhee ffiillee mmooddee ccrreeaattiioonn mmaasskk
pam_umask.so [ debug ] [ silent ] [ usergroups ] [ umask=mmaasskk ]
66..3366..11.. DDEESSCCRRIIPPTTIIOONN
pam_umask is a PAM module to set the file mode creation mask of the current
environment. The umask affects the default permissions assigned to newly
created files.
The PAM module tries to get the umask value from the following places in the
following order:
    * umask= argument
    * umask= entry in the user's GECOS field
    * UMASK= entry from /etc/default/login
    * UMASK entry from /etc/login.defs
The GECOS field is split on comma ',' characters. The module also in addition
to the umask= entry recognizes pri= entry, which sets the nice priority value
for the session, and ulimit= entry, which sets the maximum size of files the
processes in the session can create.
66..3366..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  silent
      Don't print informative messages.
  usergroups
      If the user is not root and the username is the same as primary group
      name, the umask group bits are set to be the same as owner bits
      (examples: 022 -> 002, 077 -> 007).
  umask=mmaasskk
      Sets the calling process's file mode creation mask (umask) to mask &
      0777. The value is interpreted as Octal.
66..3366..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the session type is provided.
66..3366..44.. RREETTUURRNN VVAALLUUEESS
  PAM_SUCCESS
      The new umask was set successfully.
  PAM_SERVICE_ERR
      No username was given.
  PAM_USER_UNKNOWN
      User not known.
66..3366..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/login to set the user specific umask at
login:
        session optional pam_umask.so umask=0022
66..3366..66.. AAUUTTHHOORR
pam_umask was written by Thorsten Kukuk <kukuk@thkukuk.de>.
66..3377.. ppaamm__uunniixx -- ttrraaddiittiioonnaall ppaasssswwoorrdd aauutthheennttiiccaattiioonn
pam_unix.so [ ... ]
66..3377..11.. DDEESSCCRRIIPPTTIIOONN
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.
The account component performs the task of establishing the status of the
user's account and password based on the following sshhaaddooww elements: expire,
last_change, max_change, min_change, warn_change. In the case of the latter, it
may offer advice to the user on changing their password or, through the
PPAAMM__AAUUTTHHTTOOKKEENN__RREEQQDD return, delay giving service to the user until they have
established a new password. The entries listed above are documented in the
shadow(5) manual page. Should the user's record not contain one or more of
these entries, the corresponding sshhaaddooww check is not performed.
The authentication component performs the task of checking the users
credentials (password). The default action of this module is to not permit the
user access to a service if their official password is blank.
A helper binary, unix_chkpwd(8), is provided to check the user's password when
it is stored in a read protected database. This binary is very simple and will
only check the password of the user invoking it. It is called transparently on
behalf of the user by the authenticating component of this module. In this way
it is possible for applications like xlock(1) to work without being setuid-
root. The module, by default, will temporarily turn off SIGCHLD handling for
the duration of execution of the helper binary. This is generally the right
thing to do, as many applications are not prepared to handle this signal from a
child they didn't know was fork()d. The noreap module argument can be used to
suppress this temporary shielding and may be needed for use with certain
applications.
The maximum length of a password supported by the pam_unix module via the
helper binary is PPAAMM__MMAAXX__RREESSPP__SSIIZZEE - currently 512 bytes. The rest of the
password provided by the conversation function to the module will be ignored.
The password component of this module performs the task of updating the user's
password. The default encryption hash is taken from the EENNCCRRYYPPTT__MMEETTHHOODD variable
from //eettcc//llooggiinn..ddeeffss
The session component of this module logs when a user logins or leave the
system.
Remaining arguments, supported by others functions of this module, are silently
ignored. Other arguments are logged as errors through syslog(3).
66..3377..22.. OOPPTTIIOONNSS
  debug
      Turns on debugging via syslog(3).
  audit
      A little more extreme than debug.
  quiet
      Turns off informational messages namely messages about session open and
      close via syslog(3).
  nullok
      The default action of this module is to not permit the user access to a
      service if their official password is blank. The nullok argument
      overrides this default.
  try_first_pass
      Before prompting the user for their password, the module first tries the
      previous stacked module's password in case that satisfies this module as
      well.
  use_first_pass
      The argument use_first_pass forces the module to use a previous stacked
      modules password and will never prompt the user - if no password is
      available or the password is not appropriate, the user will be denied
      access.
  nodelay
      This argument 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
      two second.
  use_authtok
      When password changing enforce the module to set the new password to the
      one provided by a previously stacked password module (this is used in the
      example of the stacking of the ppaamm__ccrraacckklliibb module documented below).
  authtok_type=ttyyppee
      This argument can be used to modify the password prompt when changing
      passwords to include the type of the password. Empty by default.
  nis
      NIS RPC is used for setting new passwords.
  remember=nn
      The last nn passwords for each user are saved in /etc/security/opasswd in
      order to force password change history and keep the user from alternating
      between the same password too frequently. The MD5 password hash algorithm
      is used for storing the old passwords. Instead of this option the
      ppaamm__ppwwhhiissttoorryy module should be used.
  shadow
      Try to maintain a shadow based system.
  md5
      When a user changes their password next, encrypt it with the MD5
      algorithm.
  bigcrypt
      When a user changes their password next, encrypt it with the DEC C2
      algorithm.
  sha256
      When a user changes their password next, encrypt it with the SHA256
      algorithm. The SHA256 algorithm must be supported by the crypt(3)
      function.
  sha512
      When a user changes their password next, encrypt it with the SHA512
      algorithm. The SHA512 algorithm must be supported by the crypt(3)
      function.
  blowfish
      When a user changes their password next, encrypt it with the blowfish
      algorithm. The blowfish algorithm must be supported by the crypt(3)
      function.
  rounds=nn
      Set the optional number of rounds of the SHA256, SHA512 and blowfish
      password hashing algorithms to nn.
  broken_shadow
      Ignore errors reading shadow information for users in the account
      management module.
  minlen=nn
      Set a minimum password length of nn characters. The max. for DES crypt
      based passwords are 8 characters.
  no_pass_expiry
      When set ignore password expiration as defined by the sshhaaddooww entry of the
      user. The option has an effect only in case ppaamm__uunniixx was not used for the
      authentication or it returned authentication failure meaning that other
      authentication source or method succeeded. The example can be public key
      authentication in sssshhdd. The module will return PPAAMM__SSUUCCCCEESSSS instead of
      eventual PPAAMM__NNEEWW__AAUUTTHHTTOOKK__RREEQQDD or PPAAMM__AAUUTTHHTTOOKK__EEXXPPIIRREEDD.
Invalid arguments are logged with syslog(3).
66..3377..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
All module types (account, auth, password and session) are provided.
66..3377..44.. RREETTUURRNN VVAALLUUEESS
  PAM_IGNORE
      Ignore this module.
66..3377..55.. EEXXAAMMPPLLEESS
An example usage for /etc/pam.d/login would be:
# Authenticate the user
auth       required   pam_unix.so
# Ensure users account and password are still active
account    required   pam_unix.so
# Change the user's password, but at first check the strength
# with pam_cracklib(8)
password   required   pam_cracklib.so retry=3 minlen=6 difok=3
password   required   pam_unix.so use_authtok nullok md5
session    required   pam_unix.so
66..3377..66.. AAUUTTHHOORR
pam_unix was written by various people.
66..3388.. ppaamm__uusseerrddbb -- aauutthheennttiiccaattee aaggaaiinnsstt aa ddbb ddaattaabbaassee
pam_userdb.so db=//ppaatthh//ddaattaabbaassee [ debug ] [ crypt=[crypt|none] ] [ icase ]
[ dump ] [ try_first_pass ] [ use_first_pass ] [ unknown_ok ] [ key_only ]
66..3388..11.. DDEESSCCRRIIPPTTIIOONN
The pam_userdb module is used to verify a username/password pair against values
stored in a Berkeley DB database. The database is indexed by the username, and
the data fields corresponding to the username keys are the passwords.
66..3388..22.. OOPPTTIIOONNSS
  crypt=[crypt|none]
      Indicates whether encrypted or plaintext passwords are stored in the
      database. If it is crypt, passwords should be stored in the database in
      crypt(3) form. If none is selected, passwords should be stored in the
      database as plaintext.
  db=//ppaatthh//ddaattaabbaassee
      Use the /path/database database for performing lookup. There is no
      default; the module will return PPAAMM__IIGGNNOORREE if no database is provided.
      Note that the path to the database file should be specified without the
      .db suffix.
  debug
      Print debug information.
  dump
      Dump all the entries in the database to the log. Don't do this by
      default!
  icase
      Make the password verification to be case insensitive (ie when working
      with registration numbers and such). Only works with plaintext password
      storage.
  try_first_pass
      Use the authentication token previously obtained by another module that
      did the conversation with the application. If this token can not be
      obtained then the module will try to converse. This option can be used
      for stacking different modules that need to deal with the authentication
      tokens.
  use_first_pass
      Use the authentication token previously obtained by another module that
      did the conversation with the application. If this token can not be
      obtained then the module will fail. This option can be used for stacking
      different modules that need to deal with the authentication tokens.
  unknown_ok
      Do not return error when checking for a user that is not in the database.
      This can be used to stack more than one pam_userdb module that will check
      a username/password pair in more than a database.
  key_only
      The username and password are concatenated together in the database hash
      as 'username-password' with a random value. if the concatenation of the
      username and password with a dash in the middle returns any result, the
      user is valid. this is useful in cases where the username may not be
      unique but the username and password pair are.
66..3388..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth and account module types are provided.
66..3388..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      Authentication failure.
  PAM_AUTHTOK_RECOVERY_ERR
      Authentication information cannot be recovered.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_CONV_ERR
      Conversation failure.
  PAM_SERVICE_ERR
      Error in service module.
  PAM_SUCCESS
      Success.
  PAM_USER_UNKNOWN
      User not known to the underlying authentication module.
66..3388..55.. EEXXAAMMPPLLEESS
auth  sufficient pam_userdb.so icase db=/etc/dbtest
66..3388..66.. AAUUTTHHOORR
pam_userdb was written by Cristian Gafton >gafton@redhat.com<.
66..3399.. ppaamm__wwaarrnn -- llooggss aallll PPAAMM iitteemmss
pam_warn.so
66..3399..11.. DDEESSCCRRIIPPTTIIOONN
pam_warn is a PAM module that logs the service, terminal, user, remote user and
remote host to syslog(3). The items are not probed for, but instead obtained
from the standard PAM items. The module always returns PPAAMM__IIGGNNOORREE, indicating
that it does not want to affect the authentication process.
66..3399..22.. OOPPTTIIOONNSS
This module does not recognise any options.
66..3399..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The auth, account, password and session module types are provided.
66..3399..44.. RREETTUURRNN VVAALLUUEESS
  PAM_IGNORE
      This module always returns PAM_IGNORE.
66..3399..55.. EEXXAAMMPPLLEESS
#%PAM-1.0
#
# If we don't have config entries for a service, the
# OTHER entries are used. To be secure, warn and deny
# access to everything.
other auth     required       pam_warn.so
other auth     required       pam_deny.so
other account  required       pam_warn.so
other account  required       pam_deny.so
other password required       pam_warn.so
other password required       pam_deny.so
other session  required       pam_warn.so
other session  required       pam_deny.so
66..3399..66.. AAUUTTHHOORR
pam_warn was written by Andrew G. Morgan <morgan@kernel.org>.
66..4400.. ppaamm__wwhheeeell -- oonnllyy ppeerrmmiitt rroooott aacccceessss ttoo mmeemmbbeerrss ooff ggrroouupp wwhheeeell
pam_wheel.so [ debug ] [ deny ] [ group=nnaammee ] [ root_only ] [ trust ]
[ use_uid ]
66..4400..11.. DDEESSCCRRIIPPTTIIOONN
The pam_wheel PAM module is used to enforce the so-called wwhheeeell group. By
default it permits root access to the system if the applicant user is a member
of the wwhheeeell group. If no group with this name exist, the module is using the
group with the group-ID 00.
66..4400..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  deny
      Reverse the sense of the auth operation: if the user is trying to get UID
      0 access and is a member of the wheel group (or the group of the group
      option), deny access. Conversely, if the user is not in the group, return
      PAM_IGNORE (unless trust was also specified, in which case we return
      PAM_SUCCESS).
  group=nnaammee
      Instead of checking the wheel or GID 0 groups, use the nnaammee group to
      perform the authentication.
  root_only
      The check for wheel membership is done only when the target user UID is
      0.
  trust
      The pam_wheel module will return PAM_SUCCESS instead of PAM_IGNORE if the
      user is a member of the wheel group (thus with a little play stacking the
      modules the wheel members may be able to su to root without being
      prompted for a passwd).
  use_uid
      The check for wheel membership will be done against the current uid
      instead of the original one (useful when jumping with su from one account
      to another for example).
66..4400..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
The aauutthh and aaccccoouunntt module types are provided.
66..4400..44.. RREETTUURRNN VVAALLUUEESS
  PAM_AUTH_ERR
      Authentication failure.
  PAM_BUF_ERR
      Memory buffer error.
  PAM_IGNORE
      The return value should be ignored by PAM dispatch.
  PAM_PERM_DENY
      Permission denied.
  PAM_SERVICE_ERR
      Cannot determine the user name.
  PAM_SUCCESS
      Success.
  PAM_USER_UNKNOWN
      User not known.
66..4400..55.. EEXXAAMMPPLLEESS
The root account gains access by default (rootok), only wheel members can
become root (wheel) but Unix authenticate non-root applicants.
su      auth     sufficient     pam_rootok.so
su      auth     required       pam_wheel.so
su      auth     required       pam_unix.so
66..4400..66.. AAUUTTHHOORR
pam_wheel was written by Cristian Gafton <gafton@redhat.com>.
66..4411.. ppaamm__xxaauutthh -- ffoorrwwaarrdd xxaauutthh kkeeyyss bbeettwweeeenn uusseerrss
pam_xauth.so [ debug ] [ xauthpath=//ppaatthh//ttoo//xxaauutthh ] [ systemuser=UUIIDD ]
[ targetuser=UUIIDD ]
66..4411..11.. DDEESSCCRRIIPPTTIIOONN
The pam_xauth PAM module is designed to forward xauth keys (sometimes referred
to as "cookies") between users.
Without pam_xauth, when xauth is enabled and a user uses the su(1) command to
assume another user's privileges, that user is no longer able to access the
original user's X display because the new user does not have the key needed to
access the display. pam_xauth solves the problem by forwarding the key from the
user running su (the source user) to the user whose identity the source user is
assuming (the target user) when the session is created, and destroying the key
when the session is torn down.
This means, for example, that when you run su(1) from an xterm session, you
will be able to run X programs without explicitly dealing with the xauth(1)
xauth command or ~/.Xauthority files.
pam_xauth will only forward keys if xauth can list a key connected to the
$DISPLAY environment variable.
Primitive access control is provided by ~/.xauth/export in the invoking user's
home directory and ~/.xauth/import in the target user's home directory.
If a user has a ~/.xauth/import file, the user will only receive cookies from
users listed in the file. If there is no ~/.xauth/import file, the user will
accept cookies from any other user.
If a user has a .xauth/export file, the user will only forward cookies to users
listed in the file. If there is no ~/.xauth/export file, and the invoking user
is not rroooott, the user will forward cookies to any other user. If there is no
~/.xauth/export file, and the invoking user is rroooott, the user will nnoott forward
cookies to other users.
Both the import and export files support wildcards (such as **). Both the import
and export files can be empty, signifying that no users are allowed.
66..4411..22.. OOPPTTIIOONNSS
  debug
      Print debug information.
  xauthpath=//ppaatthh//ttoo//xxaauutthh
      Specify the path the xauth program (it is expected in /usr/X11R6/bin/
      xauth, /usr/bin/xauth, or /usr/bin/X11/xauth by default).
  systemuser=UUIIDD
      Specify the highest UID which will be assumed to belong to a "system"
      user. pam_xauth will refuse to forward credentials to users with UID less
      than or equal to this number, except for root and the "targetuser", if
      specified.
  targetuser=UUIIDD
      Specify a single target UID which is exempt from the systemuser check.
66..4411..33.. MMOODDUULLEE TTYYPPEESS PPRROOVVIIDDEEDD
Only the sseessssiioonn type is provided.
66..4411..44.. RREETTUURRNN VVAALLUUEESS
  PAM_BUF_ERR
      Memory buffer error.
  PAM_PERM_DENIED
      Permission denied by import/export file.
  PAM_SESSION_ERR
      Cannot determine user name, UID or access users home directory.
  PAM_SUCCESS
      Success.
  PAM_USER_UNKNOWN
      User not known.
66..4411..55.. EEXXAAMMPPLLEESS
Add the following line to /etc/pam.d/su to forward xauth keys between users
when calling su:
session  optional  pam_xauth.so
66..4411..66.. AAUUTTHHOORR
pam_xauth was written by Nalin Dahyabhai <nalin@redhat.com>, based on original
version by Michael K. Johnson <johnsonm@redhat.com>.
CChhaapptteerr 77.. SSeeee aallssoo
    * The Linux-PAM Application Writers' Guide.
    * The Linux-PAM Module Writers' Guide.
    * The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE
      AUTHENTICATION MODULES'', Open Software Foundation Request For Comments
      86.0, October 1995.
CChhaapptteerr 88.. AAuutthhoorr//aacckknnoowwlleeddggmmeennttss
This document was written by Andrew G. Morgan (morgan@kernel.org) with many
contributions from Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger,
Craig S. Bell, Derrick J. Brashear, Ben Buxton, Seth Chaiklin, Oliver Crow,
Chris Dent, Marc Ewing, Cristian Gafton, Emmanuel Galanos, Brad M. Garcia, Eric
Hester, Michel D'Hooge, Roger Hu, Eric Jacksch, Michael K. Johnson, David
Kinchlea, Olaf Kirch, Marcin Korzonek, Thorsten Kukuk, Stephen Langasek,
Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton, Al Longyear, Ingo
Luetkebohle, Marek Michalkiewicz, Robert Milkowski, Aleph One, Martin Pool,
Sean Reifschneider, Jan Rekorajski, Erik Troan, Theodore Ts'o, Jeff Uphoff,
Myles Uyema, Savochkin Andrey Vladimirovich, Ronald Wahl, David Wood, John
Wilmes, Joseph S. D. Yao and Alex O. Yuriev.
Thanks are also due to Sun Microsystems, especially to Vipin Samar and Charlie
Lai for their advice. At an early stage in the development of LLiinnuuxx--PPAAMM, Sun
graciously made the documentation for their implementation of PAM available.
This act greatly accelerated the development of LLiinnuuxx--PPAAMM.
CChhaapptteerr 99.. CCooppyyrriigghhtt iinnffoorrmmaattiioonn ffoorr tthhiiss ddooccuummeenntt
Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de>
Copyright (c) 1996-2002 Andrew G. Morgan <morgan@kernel.org>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright
   notice, and the entire permission notice in its entirety,
   including the disclaimer of warranties.

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

3. The name of the author may not be used to endorse or promote
   products derived from this software without specific prior
   written permission.
Alternatively, this product may be distributed under the terms of the GNU
General Public License (GPL), in which case the provisions of the GNU GPL are
required instead of the above restrictions. (This clause is necessary due to a
potential bad interaction between the GNU GPL and the restrictions contained in
a BSD-style copyright.)
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
