.\" Title: pam.conf .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.74.0 .\" Date: 10/27/2010 .\" Manual: Linux-PAM Manual .\" Source: Linux-PAM Manual .\" Language: English .\" .TH "PAM\&.CONF" "5" "10/27/2010" "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\'\&. 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 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 N (an unsigned integer) .RS 4 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)\&. .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)