d5f80d57a181db3d595f4d453b886fda4b4ca39c
[dragonfly.git] / contrib / openpam / doc / man / pam.conf.5
1 .\"-
2 .\" Copyright (c) 2005-2011 Dag-Erling Smørgrav
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\" 3. The name of the author may not be used to endorse or promote
14 .\"    products derived from this software without specific prior written
15 .\"    permission.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" SUCH DAMAGE.
28 .\"
29 .\" $Id: pam.conf.5 610 2012-05-26 14:03:45Z des $
30 .\"
31 .Dd May 26, 2012
32 .Dt PAM.CONF 5
33 .Os
34 .Sh NAME
35 .Nm pam.conf
36 .Nd PAM policy file format
37 .Sh DESCRIPTION
38 The PAM library searches for policies in the following files, in
39 decreasing order of preference:
40 .Bl -enum
41 .It
42 .Pa /etc/pam.d/ Ns Ar service-name
43 .It
44 .Pa /etc/pam.conf
45 .It
46 .Pa /usr/local/etc/pam.d/ Ns Ar service-name
47 .It
48 .Pa /usr/local/etc/pam.conf
49 .El
50 .Pp
51 If none of these locations contains a policy for the given service,
52 the
53 .Dq Dv other
54 policy is used instead, if it exists.
55 .Pp
56 Entries in per-service policy files must be of one of the two forms
57 below:
58 .Bd -unfilled -offset indent
59 .Ar facility control-flag module-path Op Ar arguments ...
60 .Ar facility Cm include Ar other-service-name
61 .Ed
62 .Pp
63 Entries in
64 .Pa pam.conf Ns -style
65 policy files are of the same form, but are prefixed by an additional
66 field specifying the name of the service they apply to.
67 .Pp
68 In both types of policy files, blank lines are ignored, as is anything
69 to the right of a
70 .Ql #
71 sign.
72 .Pp
73 The
74 .Ar facility
75 field specifies the facility the entry applies to, and is one of:
76 .Bl -tag -width ".Cm password"
77 .It Cm auth
78 Authentication functions
79 .Po
80 .Xr pam_authenticate 3 ,
81 .Xr pam_setcred 3
82 .Pc
83 .It Cm account
84 Account management functions
85 .Pq Xr pam_acct_mgmt 3
86 .It Cm session
87 Session handling functions
88 .Po
89 .Xr pam_open_session 3 ,
90 .Xr pam_close_session 3
91 .Pc
92 .It Cm password
93 Password management functions
94 .Pq Xr pam_chauthtok 3
95 .El
96 .Pp
97 The
98 .Ar control-flag
99 field determines how the result returned by the module affects the
100 flow of control through (and the final result of) the rest of the
101 chain, and is one of:
102 .Bl -tag -width ".Cm sufficient"
103 .It Cm required
104 If this module succeeds, the result of the chain will be success
105 unless a later module fails.
106 If it fails, the rest of the chain still runs, but the final result
107 will be failure regardless of the success of later modules.
108 .It Cm requisite
109 If this module succeeds, the result of the chain will be success
110 unless a later module fails.
111 If the module fails, the chain is broken and the result is failure.
112 .It Cm sufficient
113 If this module succeeds, the chain is broken and the result is
114 success.
115 If it fails, the rest of the chain still runs, but the final result
116 will be failure unless a later module succeeds.
117 .It Cm binding
118 If this module succeeds, the chain is broken and the result is
119 success.
120 If it fails, the rest of the chain still runs, but the final result
121 will be failure regardless of the success of later modules.
122 .It Cm optional
123 If this module succeeds, the result of the chain will be success
124 unless a later module fails.
125 If this module fails, the result of the chain will be failure unless a
126 later module succeeds.
127 .El
128 .Pp
129 There are two exceptions to the above:
130 .Cm sufficient
131 and
132 .Cm binding
133 modules are treated as
134 .Cm optional
135 by
136 .Xr pam_setcred 3 ,
137 and in the
138 .Dv PAM_PRELIM_CHECK
139 phase of
140 .Xr pam_chauthtok 3 .
141 .Pp
142 The
143 .Ar module-path
144 field specifies the name, or optionally the full path, of the module
145 to call.
146 .Pp
147 The remaining fields are passed as arguments to the module if and when
148 it is invoked.
149 As a special case, if an argument is of the form ``name=value'' and
150 the right-hand side is surrounded by single or double quotes, any
151 whitespace between the quote characters will be considered part of the
152 same argument rather than a separator between this argument and the
153 next.
154 .Pp
155 The
156 .Cm include
157 form of entry causes entries from a different chain (specified by
158 .Ar other-system-name )
159 to be included in the current one.
160 This allows one to define system-wide policies which are then included
161 into service-specific policies.
162 The system-wide policy can then be modified without having to also
163 modify each and every service-specific policy.
164 .Sh SEE ALSO
165 .Xr pam 3
166 .Sh STANDARDS
167 .Rs
168 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
169 .%D "June 1997"
170 .Re
171 .Sh AUTHORS
172 The OpenPAM library was developed for the
173 .Fx
174 Project by ThinkSec AS and Network Associates Laboratories, the
175 Security Research Division of Network Associates, Inc.\& under
176 DARPA/SPAWAR contract N66001-01-C-8035
177 .Pq Dq CBOSS ,
178 as part of the DARPA CHATS research program.
179 .Pp
180 The OpenPAM library is maintained by
181 .An Dag-Erling Sm\(/orgrav Aq des@des.no .