diff options
Diffstat (limited to 'doc/man/pam.conf.5')
-rw-r--r-- | doc/man/pam.conf.5 | 553 |
1 files changed, 553 insertions, 0 deletions
diff --git a/doc/man/pam.conf.5 b/doc/man/pam.conf.5 new file mode 100644 index 00000000..4673e40b --- /dev/null +++ b/doc/man/pam.conf.5 @@ -0,0 +1,553 @@ +.\" 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: 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<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 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) |