1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5 <section id='pam.conf-syntax'>
7 The syntax of the <filename>/etc/pam.conf</filename>
8 configuration file is as follows. The file is made up of a list
9 of rules, each rule is typically placed on a single line,
10 but may be extended with an escaped end of line: `\<LF>'.
11 Comments are preceded with `#' marks and extend to the next end of
16 The format of each rule is a space separated collection of tokens,
17 the first three being case-insensitive:
21 <emphasis remap='B'> service type control module-path module-arguments</emphasis>
25 The syntax of files contained in the <filename>/etc/pam.d/</filename>
26 directory, are identical except for the absence of any
27 <emphasis>service</emphasis> field. In this case, the
28 <emphasis>service</emphasis> is the name of the file in the
29 <filename>/etc/pam.d/</filename> directory. This filename must be
34 An important feature of <emphasis>PAM</emphasis>, is that a
35 number of rules may be <emphasis>stacked</emphasis> to combine
36 the services of a number of PAMs for a given authentication task.
40 The <emphasis>service</emphasis> is typically the familiar name of
41 the corresponding application: <emphasis>login</emphasis> and
42 <emphasis>su</emphasis> are good examples. The
43 <emphasis>service</emphasis>-name, <emphasis>other</emphasis>,
44 is reserved for giving <emphasis>default</emphasis> rules.
45 Only lines that mention the current service (or in the absence
46 of such, the <emphasis>other</emphasis> entries) will be associated
47 with the given service-application.
51 The <emphasis>type</emphasis> is the management group that the rule
52 corresponds to. It is used to specify which of the management groups
53 the subsequent module is to be associated with. Valid entries are:
60 this module type performs non-authentication based account
61 management. It is typically used to restrict/permit access
62 to a service based on the time of day, currently available
63 system resources (maximum number of users) or perhaps the
64 location of the applicant user -- 'root' login only on the
73 this module type provides two aspects of authenticating
74 the user. Firstly, it establishes that the user is who they
75 claim to be, by instructing the application to prompt the user
76 for a password or other means of identification. Secondly, the
77 module can grant group membership or other privileges through
78 its credential granting properties.
86 this module type is required for updating the authentication
87 token associated with the user. Typically, there is one module
88 for each 'challenge/response' based authentication (auth) type.
96 this module type is associated with doing things that need to
97 be done for the user before/after they can be given service.
98 Such things include the logging of information concerning the
99 opening/closing of some data exchange with a user, mounting
107 The third field, <emphasis>control</emphasis>, indicates the
108 behavior of the PAM-API should the module fail to succeed in its
109 authentication task. There are two types of syntax for this control
110 field: the simple one has a single simple keyword; the more
111 complicated one involves a square-bracketed selection of
112 <emphasis>value=action</emphasis> pairs.
116 For the simple (historical) syntax valid <emphasis>control</emphasis>
121 <term>required</term>
124 failure of such a PAM will ultimately lead to the PAM-API
125 returning failure but only after the remaining
126 <emphasis>stacked</emphasis> modules (for this
127 <emphasis>service</emphasis> and <emphasis>type</emphasis>)
133 <term>requisite</term>
136 like <emphasis>required</emphasis>, however, in the case that
137 such a module returns a failure, control is directly returned
138 to the application. The return value is that associated with
139 the first required or requisite module to fail. Note, this flag
140 can be used to protect against the possibility of a user getting
141 the opportunity to enter a password over an unsafe medium. It is
142 conceivable that such behavior might inform an attacker of valid
143 accounts on a system. This possibility should be weighed against
144 the not insignificant concerns of exposing a sensitive password
145 in a hostile environment.
150 <term>sufficient</term>
153 success of such a module is enough to satisfy the
154 authentication requirements of the stack of modules (if a
155 prior <emphasis>required</emphasis> module has failed the
156 success of this one is <emphasis>ignored</emphasis>). A failure
157 of this module is not deemed as fatal to satisfying the
158 application that this type has succeeded.
163 <term>optional</term>
166 the success or failure of this module is only important if
167 it is the only module in the stack associated with this
168 <emphasis>service</emphasis>+<emphasis>type</emphasis>.
176 include all lines of given type from the configuration
177 file specified as an argument to this control.
184 For the more complicated syntax valid <emphasis>control</emphasis>
185 values have the following form:
188 [value1=action1 value2=action2 ...]
192 Where <emphasis>valueN</emphasis> corresponds to the return code
193 from the function invoked in the module for which the line is
194 defined. It is selected from one of these:
195 <emphasis>success</emphasis>, <emphasis>open_err</emphasis>,
196 <emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>,
197 <emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>,
198 <emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>,
199 <emphasis>cred_insufficient</emphasis>,
200 <emphasis>authinfo_unavail</emphasis>,
201 <emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>,
202 <emphasis>new_authtok_reqd</emphasis>,
203 <emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>,
204 <emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>,
205 <emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>,
206 <emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>,
207 <emphasis>authtok_recover_err</emphasis>,
208 <emphasis>authtok_lock_busy</emphasis>,
209 <emphasis>authtok_disable_aging</emphasis>,
210 <emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>,
211 <emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>,
212 <emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis>
213 and <emphasis>default</emphasis>.
216 The last of these, <emphasis>default</emphasis>, implies 'all
217 <emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the
218 full list of PAM errors is available in
219 <filename>/usr/include/security/_pam_types.h</filename>. The
220 <emphasis>actionN</emphasis> can be: an unsigned integer,
221 <emphasis>n</emphasis>, signifying an action of 'jump over the
222 next <emphasis>n</emphasis> modules in the stack', or take one
223 of the following forms:
230 when used with a stack of modules, the module's return
231 status will not contribute to the return code the application
240 this action indicates that the return code should be thought
241 of as indicative of the module failing. If this module is the
242 first in the stack to fail, its status value will be used for
243 that of the whole stack.
251 equivalent to bad with the side effect of terminating the
252 module stack and PAM immediately returning to the application.
260 this tells PAM that the administrator thinks this return code
261 should contribute directly to the return code of the full
262 stack of modules. In other words, if the former state of the
263 stack would lead to a return of <emphasis>PAM_SUCCESS</emphasis>,
264 the module's return code will override this value. Note, if
265 the former state of the stack holds some value that is
266 indicative of a modules failure, this 'ok' value will not be
267 used to override that value.
275 equivalent to ok with the side effect of terminating the module
276 stack and PAM immediately returning to the application.
284 clear all memory of the state of the module stack and
285 start again with the next stacked module.
292 Each of the four keywords: required; requisite; sufficient; and
293 optional, have an equivalent expression in terms of the [...]
294 syntax. They are as follows:
298 <term>required</term>
301 [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
306 <term>requisite</term>
309 [success=ok new_authtok_reqd=ok ignore=ignore default=die]
314 <term>sufficient</term>
317 [success=done new_authtok_reqd=done default=ignore]
322 <term>optional</term>
325 [success=ok new_authtok_reqd=ok default=ignore]
332 <emphasis>module-path</emphasis> is either the full filename
333 of the PAM to be used by the application (it begins with a '/'),
334 or a relative pathname from the default module location:
335 <filename>/lib/security/</filename> or
336 <filename>/lib64/security/</filename>, depending on the architecture.
340 <emphasis>module-arguments</emphasis> are a space separated list
341 of tokens that can be used to modify the specific behavior of the
342 given PAM. Such arguments will be documented for each individual
343 module. Note, if you wish to include spaces in an argument, you
344 should surround that argument with square brackets.
347 squid auth required pam_mysql.so user=passwd_query passwd=mada \
348 db=eminence [query=select user_name from internet_service \
349 where user_name='%u' and password=PASSWORD('%p') and \
353 When using this convention, you can include `[' characters
354 inside the string, and if you wish to include a `]' character
355 inside the string that will survive the argument parsing, you
356 should use `\['. In other words:
359 [..[..\]..] --> ..[..]..
363 Any line in (one of) the configuration file(s), that is not formatted
364 correctly, will generally tend (erring on the side of caution) to make
365 the authentication process fail. A corresponding error is written to
366 the system log files with a call to
368 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>