path: root/doc/man/pam.conf.5

.\"     Title: pam.conf
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
.\"      Date: 03/02/2009
.\"    Manual: Linux-PAM Manual
.\"    Source: Linux-PAM Manual
.\"  Language: English
.\"
.TH "PAM\&.CONF" "5" "03/02/2009" "Linux-PAM Manual" "Linux-PAM Manual"
.\" -----------------------------------------------------------------
.\" * (re)Define some macros
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" toupper - uppercase a string (locale-aware)
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de toupper
.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
\\$*
.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SH-xref - format a cross-reference to an SH section
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de SH-xref
.ie n \{\
.\}
.toupper \\$*
.el \{\
\\$*
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SH - level-one heading that works better for non-TTY output
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de1 SH
.\" put an extra blank line of space above the head in non-TTY output
.if t \{\
.sp 1
.\}
.sp \\n[PD]u
.nr an-level 1
.set-an-margin
.nr an-prevailing-indent \\n[IN]
.fi
.in \\n[an-margin]u
.ti 0
.HTML-TAG ".NH \\n[an-level]"
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
\." make the size of the head bigger
.ps +3
.ft B
.ne (2v + 1u)
.ie n \{\
.\" if n (TTY output), use uppercase
.toupper \\$*
.\}
.el \{\
.nr an-break-flag 0
.\" if not n (not TTY), use normal case (not uppercase)
\\$1
.in \\n[an-margin]u
.ti 0
.\" if not n (not TTY), put a border/line under subheading
.sp -.6
\l'\n(.lu'
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SS - level-two heading that works better for non-TTY output
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de1 SS
.sp \\n[PD]u
.nr an-level 1
.set-an-margin
.nr an-prevailing-indent \\n[IN]
.fi
.in \\n[IN]u
.ti \\n[SN]u
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.ps \\n[PS-SS]u
\." make the size of the head bigger
.ps +2
.ft B
.ne (2v + 1u)
.if \\n[.$] \&\\$*
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" BB/BE - put background/screen (filled box) around block of text
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de BB
.if t \{\
.sp -.5
.br
.in +2n
.ll -2n
.gcolor red
.di BX
.\}
..
.de EB
.if t \{\
.if "\\$2"adjust-for-leading-newline" \{\
.sp -1
.\}
.br
.di
.in
.ll
.gcolor
.nr BW \\n(.lu-\\n(.i
.nr BH \\n(dn+.5v
.ne \\n(BHu+.5v
.ie "\\$2"adjust-for-leading-newline" \{\
\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
.\}
.el \{\
\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
.\}
.in 0
.sp -.5v
.nf
.BX
.in
.sp .5v
.fi
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" BM/EM - put colored marker in margin next to block of text
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de BM
.if t \{\
.br
.ll -2n
.gcolor red
.di BX
.\}
..
.de EM
.if t \{\
.br
.di
.ll
.gcolor
.nr BH \\n(dn
.ne \\n(BHu
\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
.in 0
.nf
.BX
.in
.fi
.\}
..
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "Name"
pam.conf, pam.d \- PAM configuration files
.SH "DESCRIPTION"
.PP
When a
\fIPAM\fR
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):
\FC/etc/pam\&.conf\F[]\&. Alternatively, this may be the contents of the
\FC/etc/pam\&.d/\F[]
directory\&. The presence of this directory will cause Linux\-PAM to ignore
\FC/etc/pam\&.conf\F[]\&.
.PP
These files list the
\fIPAM\fRs that will do the authentication tasks required by this service, and the appropriate behavior of the PAM\-API in the event that individual
\fIPAM\fRs fail\&.
.PP
The syntax of the
\FC/etc/pam\&.conf\F[]
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: `\e<LF>\'\&. Comments are preceded with `#\' marks and extend to the next end of line\&.
.PP
The format of each rule is a space separated collection of tokens, the first three being case\-insensitive:
.PP

\fB service type control module\-path module\-arguments\fR
.PP
The syntax of files contained in the
\FC/etc/pam\&.d/\F[]
directory, are identical except for the absence of any
\fIservice\fR
field\&. In this case, the
\fIservice\fR
is the name of the file in the
\FC/etc/pam\&.d/\F[]
directory\&. This filename must be in lower case\&.
.PP
An important feature of
\fIPAM\fR, is that a number of rules may be
\fIstacked\fR
to combine the services of a number of PAMs for a given authentication task\&.
.PP
The
\fIservice\fR
is typically the familiar name of the corresponding application:
\fIlogin\fR
and
\fIsu\fR
are good examples\&. The
\fIservice\fR\-name,
\fIother\fR, is reserved for giving
\fIdefault\fR
rules\&. Only lines that mention the current service (or in the absence of such, the
\fIother\fR
entries) will be associated with the given service\-application\&.
.PP
The
\fItype\fR
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:
.PP
account
.RS 4
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\&.
.RE
.PP
auth
.RS 4
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\&.
.RE
.PP
password
.RS 4
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\&.
.RE
.PP
session
.RS 4
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\&.
.RE
.PP
If the
\fItype\fR
value from the list above is prepended with a
\fI\-\fR
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\&.
.PP
The third field,
\fIcontrol\fR, 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
\fIvalue=action\fR
pairs\&.
.PP
For the simple (historical) syntax valid
\fIcontrol\fR
values are:
.PP
required
.RS 4
failure of such a PAM will ultimately lead to the PAM\-API returning failure but only after the remaining
\fIstacked\fR
modules (for this
\fIservice\fR
and
\fItype\fR) have been invoked\&.
.RE
.PP
requisite
.RS 4
like
\fIrequired\fR, however, in the case that such a module returns a failure, control is directly returned to the application\&. The return value is that associated with the first required or requisite module to fail\&. Note, this flag can be used to protect against the possibility of a user getting the opportunity to enter a password over an unsafe medium\&. It is conceivable that such behavior might inform an attacker of valid accounts on a system\&. This possibility should be weighed against the not insignificant concerns of exposing a sensitive password in a hostile environment\&.
.RE
.PP
sufficient
.RS 4
success of such a module is enough to satisfy the authentication requirements of the stack of modules (if a prior
\fIrequired\fR
module has failed the success of this one is
\fIignored\fR)\&. A failure of this module is not deemed as fatal to satisfying the application that this type has succeeded\&. If the module succeeds the PAM framework returns success to the application immediately without trying any other modules\&.
.RE
.PP
optional
.RS 4
the success or failure of this module is only important if it is the only module in the stack associated with this
\fIservice\fR+\fItype\fR\&.
.RE
.PP
include
.RS 4
include all lines of given type from the configuration file specified as an argument to this control\&.
.RE
.PP
substack
.RS 4
include all lines of given type from the configuration file specified as an argument to this control\&. This differs from
\fIinclude\fR
in that evaluation of the
\fIdone\fR
and
\fIdie\fR
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
\fIreset\fR
action will reset the state of a module stack to the state it was in as of beginning of the substack evaluation\&.
.RE
.PP
For the more complicated syntax valid
\fIcontrol\fR
values have the following form:
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

      [value1=action1 value2=action2 \&.\&.\&.]
    
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.PP
Where
\fIvalueN\fR
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:
\fIsuccess\fR,
\fIopen_err\fR,
\fIsymbol_err\fR,
\fIservice_err\fR,
\fIsystem_err\fR,
\fIbuf_err\fR,
\fIperm_denied\fR,
\fIauth_err\fR,
\fIcred_insufficient\fR,
\fIauthinfo_unavail\fR,
\fIuser_unknown\fR,
\fImaxtries\fR,
\fInew_authtok_reqd\fR,
\fIacct_expired\fR,
\fIsession_err\fR,
\fIcred_unavail\fR,
\fIcred_expired\fR,
\fIcred_err\fR,
\fIno_module_data\fR,
\fIconv_err\fR,
\fIauthtok_err\fR,
\fIauthtok_recover_err\fR,
\fIauthtok_lock_busy\fR,
\fIauthtok_disable_aging\fR,
\fItry_again\fR,
\fIignore\fR,
\fIabort\fR,
\fIauthtok_expired\fR,
\fImodule_unknown\fR,
\fIbad_item\fR,
\fIconv_again\fR,
\fIincomplete\fR, and
\fIdefault\fR\&.
.PP
The last of these,
\fIdefault\fR, implies \'all
\fIvalueN\fR\'s not mentioned explicitly\&. Note, the full list of PAM errors is available in
\FC/usr/include/security/_pam_types\&.h\F[]\&. The
\fIactionN\fR
can be: an unsigned integer,
\fIn\fR, signifying an action of \'jump over the next
\fIn\fR
modules in the stack\'; or take one of the following forms:
.PP
ignore
.RS 4
when used with a stack of modules, the module\'s return status will not contribute to the return code the application obtains\&.
.RE
.PP
bad
.RS 4
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\&.
.RE
.PP
die
.RS 4
equivalent to bad with the side effect of terminating the module stack and PAM immediately returning to the application\&.
.RE
.PP
ok
.RS 4
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
\fIPAM_SUCCESS\fR, 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\&.
.RE
.PP
done
.RS 4
equivalent to ok with the side effect of terminating the module stack and PAM immediately returning to the application\&.
.RE
.PP
reset
.RS 4
clear all memory of the state of the module stack and start again with the next stacked module\&.
.RE
.PP
Each of the four keywords: required; requisite; sufficient; and optional, have an equivalent expression in terms of the [\&.\&.\&.] syntax\&. They are as follows:
.PP
required
.RS 4
[success=ok new_authtok_reqd=ok ignore=ignore default=bad]
.RE
.PP
requisite
.RS 4
[success=ok new_authtok_reqd=ok ignore=ignore default=die]
.RE
.PP
sufficient
.RS 4
[success=done new_authtok_reqd=done default=ignore]
.RE
.PP
optional
.RS 4
[success=ok new_authtok_reqd=ok default=ignore]
.RE
.PP

\fImodule\-path\fR
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:
\FC/lib/security/\F[]
or
\FC/lib64/security/\F[], depending on the architecture\&.
.PP

\fImodule\-arguments\fR
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\&.
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

    squid auth required pam_mysql\&.so user=passwd_query passwd=mada \e
          db=eminence [query=select user_name from internet_service \e
          where user_name=\'%u\' and password=PASSWORD(\'%p\') and \e
        service=\'web_proxy\']
    
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.PP
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 `\e]\'\&. In other words:
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

    [\&.\&.[\&.\&.\e]\&.\&.]    \-\->   \&.\&.[\&.\&.]\&.\&.
    
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.PP
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
\fBsyslog\fR(3)\&.
.PP
More flexible than the single configuration file is it to configure libpam via the contents of the
\FC/etc/pam\&.d/\F[]
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\&.
.PP
The syntax of each file in /etc/pam\&.d/ is similar to that of the
\FC/etc/pam\&.conf\F[]
file and is made up of lines of the following form:
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

type  control  module\-path  module\-arguments
    
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.PP
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,
\FC/etc/pam\&.d/login\F[]
contains the configuration for the
\fBlogin\fR
service\&.
.SH "SEE ALSO"
.PP

\fBpam\fR(3),
\fBPAM\fR(8),
\fBpam_start\fR(3)