Print this page
2947 prelim manpage changes, packaging manifests
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man4/pam.conf.4
+++ new/usr/src/man/man4/pam.conf.4
1 1 '\" te
2 2 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved.
3 +.\" Copyright 2012 Joshua M. Clulow <josh@sysmgr.org>
3 4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH PAM.CONF 4 "Jun 19, 2006"
7 +.TH PAM.CONF 4 "Jun 30, 2012"
7 8 .SH NAME
8 -pam.conf \- configuration file for pluggable authentication modules
9 +pam.d, pam.conf \- configuration for pluggable authentication modules
9 10 .SH SYNOPSIS
10 11 .LP
11 12 .nf
13 +\fB/etc/pam.d\fR
14 +.fi
15 +.nf
12 16 \fB/etc/pam.conf\fR
13 17 .fi
14 18
15 19 .SH DESCRIPTION
16 20 .sp
17 21 .LP
18 -\fBpam.conf\fR is the configuration file for the Pluggable Authentication
19 -Module architecture, or \fBPAM\fR. A \fBPAM\fR module provides functionality
22 +
23 +\fB/etc/pam.d\fR is the configuration directory for the Pluggable Authentication
24 +Module architecture, or \fBPAM\fR. A \fBPAM\fR module provides functionality
20 25 for one or more of four possible services: authentication, account management,
21 -session management, and password management.
26 +session management, and password management. The configuration directory
27 +contains per-service 'shards' of the legacy, monolithic \fBpam.conf\fR file.
22 28 .sp
23 29 .ne 2
24 30 .na
25 31 \fBauthentication service module\fR
26 32 .ad
27 33 .sp .6
28 34 .RS 4n
29 35 Provides functionality to authenticate a user and set up user credentials.
30 36 .RE
31 37
32 38 .sp
33 39 .ne 2
34 40 .na
35 41 \fBaccount management module\fR
36 42 .ad
37 43 .sp .6
38 44 .RS 4n
39 45 Provides functionality to determine if the current user's account is valid.
40 46 This includes checking for password and account expiration, as well as
41 47 verifying access hour restrictions.
42 48 .RE
43 49
44 50 .sp
45 51 .ne 2
46 52 .na
47 53 \fBsession management module\fR
48 54 .ad
49 55 .sp .6
50 56 .RS 4n
51 57 Provides functionality to set up and terminate login sessions.
52 58 .RE
53 59
54 60 .sp
55 61 .ne 2
56 62 .na
57 63 \fBpassword management module\fR
58 64 .ad
59 65 .sp .6
60 66 .RS 4n
61 67 Provides functionality to change a user's authentication token or password.
62 68 .RE
63 69
64 70 .sp
65 71 .LP
66 72 Each of the four service modules can be implemented as a shared library object
67 73 which can be referenced in the \fBpam.conf\fR configuration file.
68 74 .SS "Simplified pam.conf Configuration File"
69 75 .sp
70 76 .LP
71 77 The \fBpam.conf\fR file contains a listing of services. Each service is paired
72 78 with a corresponding service module. When a service is requested, its
73 79 associated module is invoked. Each entry may be a maximum of 256 characters,
74 80 including the end of line, and has the following format:
|
↓ open down ↓ |
43 lines elided |
↑ open up ↑ |
75 81 .sp
76 82 .in +2
77 83 .nf
78 84 \fIservice_name module_type control_flag module_path options\fR
79 85 .fi
80 86 .in -2
81 87 .sp
82 88
83 89 .sp
84 90 .LP
91 +If shard files are used in \fB/etc/pam.d\fR instead of the monolithic
92 +\fBpam.conf\fR file, then the \fIservice_name\fR column is not present in
93 +those files. The \fIservice_name\fR is, instead, derived from the
94 +filename of the shard. As an example, for the service 'login' the configuration
95 +would now be in \fB/etc/pam.d/login\fR and would omit the first column
96 +(previously containing 'login').
97 +.sp
98 +.LP
85 99 The following is an example of a \fBpam.conf\fR configuration file with support
86 100 for authentication, account management, session management and password
87 101 management modules (See the \fBpam.conf\fR file that is shipped with your
88 102 system for the contents of this file):
89 103 .sp
90 104 .in +2
91 105 .nf
92 106 login auth requisite pam_authtok_get.so.1
93 107 login auth required pam_dhkeys.so.1
94 108 login auth required pam_unix_auth.so.1
95 109 login auth required pam_dial_auth.so.1
96 110
97 111 other account requisite pam_roles.so.1
98 112 other account required pam_unix_account.so.1
99 113
100 114 other session required pam_unix_session.so.1
101 115
102 116 other password required pam_dhkeys.so.1
103 117 other password requisite pam_authtok_get.so.1
104 118 other password requisite pam_authtok_check.so.1
105 119 other password required pam_authtok_store.so.1
106 120 .fi
107 121 .in -2
108 122
109 123 .sp
110 124 .LP
111 125 \fIservice_name\fR denotes the service (for example, \fBlogin\fR,
112 126 \fBdtlogin\fR, or \fBrlogin\fR).
113 127 .sp
114 128 .LP
115 129 The keyword, "\fBother\fR," indicates the module that all other applications
116 130 which have not been specified should use. The "\fBother\fR" keyword can also be
117 131 used if all services of the same \fImodule_type\fR have the same requirements.
118 132 .sp
119 133 .LP
120 134 In the example, since all of the services use the same session module, they
121 135 could have been replaced by a single \fBother\fR line.
122 136 .sp
123 137 .LP
124 138 \fImodule_type\fR denotes the service module type: authentication (\fBauth\fR),
|
↓ open down ↓ |
30 lines elided |
↑ open up ↑ |
125 139 account management (\fBaccount\fR), session management (\fBsession\fR), or
126 140 password management (\fBpassword\fR).
127 141 .sp
128 142 .LP
129 143 The \fIcontrol_flag\fR field determines the behavior of stacking.
130 144 .sp
131 145 .LP
132 146 The \fImodule_path\fR field specifies the relative pathname to a shared library
133 147 object, or an included \fBPAM\fR configuration file, which implements the
134 148 service functionality. If the pathname is not absolute, shared library objects
135 -are assumed to be relative to \fB/usr/lib/security/$ISA/\fR, and included
136 -\fBPAM\fR configuration files are assumed to be relative to
137 -\fB/usr/lib/security/\fR.
149 +are assumed to be relative to \fB/usr/lib/security/$ISA/\fR, and \fBPAM\fR
150 +configuration files included in shards are assumed to be relative to
151 +\fB/etc/pam.d/\fR, or \fB/usr/lib/security/\fB if included in the legacy
152 +\fBpam.conf\fR.
138 153 .sp
139 154 .LP
140 155 The \fBISA\fR token is replaced by an implementation defined directory name
141 156 which defines the path relative to the calling program's instruction set
142 157 architecture.
143 158 .sp
144 159 .LP
145 160 The \fIoptions\fR field is used by the \fBPAM\fR framework layer to pass module
146 161 specific options to the modules. It is up to the module to parse and interpret
147 162 the options.
148 163 .sp
149 164 .LP
150 165 This field can be used by the modules to turn on debugging or to pass any
151 166 module specific parameters such as a \fBTIMEOUT\fR value. The options supported
152 167 by the modules are documented in their respective manual pages.
153 168 .SS "Integrating Multiple Authentication Services With Stacking"
154 169 .sp
155 170 .LP
156 171 When a \fIservice_name\fR of the same \fImodule_type\fR is defined more than
157 172 once, the service is said to be stacked. Each module referenced in the
158 173 \fImodule_path\fR for that service is then processed in the order that it
159 174 occurs in the configuration file. The \fIcontrol_flag\fR field specifies the
160 175 continuation and failure semantics of the modules, and can contain one of the
161 176 following values:
162 177 .sp
163 178 .ne 2
164 179 .na
165 180 \fB\fBbinding\fR\fR
166 181 .ad
167 182 .RS 14n
168 183 If the service module returns success and no preceding \fBrequired\fR modules
169 184 returned failures, immediately return success without calling any subsequent
170 185 modules. If a failure is returned, treat the failure as a \fBrequired\fR module
171 186 failure, and continue to process the \fBPAM\fR stack.
172 187 .RE
173 188
174 189 .sp
175 190 .ne 2
176 191 .na
177 192 \fB\fBinclude\fR\fR
178 193 .ad
179 194 .RS 14n
180 195 Process the lines from the \fBPAM\fR configuration file that is specified in
181 196 the \fImodule_path\fR at this point in the \fBPAM\fR stack. The ``\fBother\fR''
182 197 keyword is used if the specified service_name is not found. 32 levels of
183 198 included \fBPAM\fR configuration files are supported. Any options are ignored.
184 199 .RE
185 200
186 201 .sp
187 202 .ne 2
188 203 .na
189 204 \fB\fBoptional\fR\fR
190 205 .ad
191 206 .RS 14n
192 207 If the service module returns success, record the success, and continue to
193 208 process the \fBPAM\fR stack. If a failure is returned, and it is the first
194 209 \fBoptional\fR module failure, save the failure code as an \fBoptional\fR
195 210 failure. Continue to process the \fBPAM\fR stack.
196 211 .RE
197 212
198 213 .sp
199 214 .ne 2
200 215 .na
201 216 \fB\fBrequired\fR\fR
202 217 .ad
203 218 .RS 14n
204 219 If the service module returns success, record the success, and continue to
205 220 process the \fBPAM\fR stack. If a failure is returned, and it is the first
206 221 \fBrequired\fR failure, save the failure code as a \fBrequired\fR failure.
207 222 Continue to process the \fBPAM\fR stack.
208 223 .RE
209 224
210 225 .sp
211 226 .ne 2
212 227 .na
213 228 \fB\fBrequisite\fR\fR
214 229 .ad
215 230 .RS 14n
216 231 If the service module returns success, record the success, and continue to
217 232 process the \fBPAM\fR stack. If a failure is returned, immediately return the
218 233 first non-optional failure value recorded without calling any subsequent
219 234 modules. That is, return this failure unless a previous required service module
220 235 failed. If a previous required service module failed, then return the first of
221 236 those values.
222 237 .RE
223 238
224 239 .sp
225 240 .ne 2
226 241 .na
227 242 \fB\fBsufficient\fR\fR
228 243 .ad
229 244 .RS 14n
230 245 If the service module return success and no preceding required modules returned
231 246 failures, immediately return success without calling any subsequent modules. If
232 247 a failure is returned, treat the failure as an optional module failure, and
233 248 continue to process the \fBPAM\fR stack.
234 249 .RE
235 250
236 251 .sp
237 252 .LP
238 253 If the \fBPAM\fR stack runs to completion, that is, neither a \fBrequisite\fR
239 254 module failed, nor a \fBbinding\fR or \fBsufficient\fR module success stops it,
240 255 success is returned if no required modules failed and at least one required,
241 256 requisite, optional module succeeded. If no module succeeded and a required or
242 257 binding module failed, the first of those errors is returned. If no required or
243 258 binding module failed and an optional module failed, the first of the option
244 259 module errors is returned. If no module in the stack succeeded or failed, that
245 260 is, all modules returned an ignore status, a default error based on module
246 261 type, for example, "User account expired," is returned.
247 262 .sp
248 263 .LP
249 264 All errors in \fBpam.conf\fR entries are logged to \fBsyslog\fR as
250 265 \fBLOG_AUTH\fR | \fBLOG_ERR\fR errors. The use of a service with an error noted
251 266 in the \fBpam.conf\fR entry for that service will fail. The system
252 267 administrator will need to correct the noted errors before that service may be
253 268 used. If no services are available or the \fBpam.conf\fR file is missing, the
254 269 system administrator may enter system maintenance mode to correct or restore
255 270 the file.
256 271 .sp
257 272 .LP
258 273 The following is a sample configuration file that stacks the \fBsu\fR,
259 274 \fBlogin\fR, and \fBrlogin\fR services.
260 275 .sp
261 276 .in +2
262 277 .nf
263 278 su auth required pam_inhouse.so.1
264 279 su auth requisite pam_authtok_get.so.1
265 280 su auth required pam_dhkeys.so.1
266 281 su auth required pam_unix_auth.so.1
267 282
268 283 login auth requisite pam_authtok_get.so.1
269 284 login auth required pam_dhkeys.so.1
270 285 login auth required pam_unix_auth.so.1
271 286 login auth required pam_dial_auth.so.1
272 287 login auth optional pam_inhouse.so.1
273 288
274 289 rlogin auth sufficient pam_rhosts_auth.so.1
275 290 rlogin auth requisite pam_authtok_get.so.1
276 291 rlogin auth required pam_dhkeys.so.1
277 292 rlogin auth required pam_unix_auth.so.1
278 293 .fi
279 294 .in -2
280 295
281 296 .sp
282 297 .LP
283 298 In the case of \fBsu\fR, the user is authenticated by the \fBinhouse\fR and
284 299 \fBauthtok_get\fR, \fBdhkeys\fR, and \fBunix_auth\fR authentication modules.
285 300 Because the \fBinhouse\fR and the other authentication modules are
286 301 \fBrequired\fR and \fBrequisite\fR, respectively, an error is returned back to
287 302 the application if any module fails. In addition, if the \fBrequisite\fR
288 303 authentication (\fBpam_authtok_get\fR authentication) fails, the other
289 304 authentication modules are never invoked, and the error is returned immediately
290 305 back to the application.
291 306 .sp
292 307 .LP
293 308 In the case of \fBlogin\fR, the \fBrequired\fR keyword for \fIcontrol_flag\fR
294 309 requires that the user be allowed to login only if the user is authenticated by
295 310 all the service modules. If \fBpam_unix_auth\fR authentication fails, control
296 311 continues to proceed down the stack, and the \fBinhouse\fR authentication
297 312 module is invoked. \fBinhouse\fR authentication is optional by virtue of the
298 313 optional keyword in the \fIcontrol_flag\fR field. The user can still log in
299 314 even if \fBinhouse\fR authentication fails, assuming the modules stacked above
300 315 succeeded.
301 316 .sp
302 317 .LP
303 318 In the case of \fBrlogin\fR, the \fBsufficient\fR keyword for
304 319 \fIcontrol_flag\fR specifies that if the \fBrhosts\fR authentication check
305 320 succeeds, then \fBPAM\fR should return success to \fBrlogin\fR and \fBrlogin\fR
306 321 should not prompt the user for a password. The other authentication modules,
307 322 which are in the stack, will only be invoked if the \fBrhosts\fR check fails.
308 323 This gives the system administrator the flexibility to determine if
309 324 \fBrhosts\fR alone is sufficient enough to authenticate a remote user.
310 325 .sp
311 326 .LP
312 327 Some modules return \fBPAM_IGNORE\fR in certain situations. In these cases the
313 328 \fBPAM\fR framework ignores the entire entry in \fBpam.conf\fR regardless of
314 329 whether or not it is \fBbinding\fR, \fBrequisite\fR, \fBrequired\fR,
315 330 \fBoptional\fR, or \fBsufficient\fR.
316 331 .SS "Utilities and Files"
317 332 .sp
318 333 .LP
319 334 The specific service names and module types for each service should be
320 335 documented in the man page for that service. For instance, the \fBsshd\fR(1M)
321 336 man page lists all of the \fBPAM\fR service names and module types for the
322 337 \fBsshd\fR command.
323 338 .sp
324 339 .LP
325 340 The \fBPAM\fR configuration file does not dictate either the name or the
326 341 location of the service specific modules. The convention, however, is the
327 342 following:
328 343 .sp
329 344 .ne 2
330 345 .na
331 346 \fB\fBpam_module_name.so.x\fR\fR
332 347 .ad
333 348 .RS 29n
334 349 File that implements various function of specific authentication services. As
335 350 the relative pathname specified, \fB/usr/lib/security/$ISA\fR is prepended to
336 351 it.
337 352 .RE
|
↓ open down ↓ |
190 lines elided |
↑ open up ↑ |
338 353
339 354 .sp
340 355 .ne 2
341 356 .na
342 357 \fB\fB/etc/pam.conf\fR\fR
343 358 .ad
344 359 .RS 29n
345 360 Configuration file
346 361 .RE
347 362
363 +.sp
364 +.ne 2
365 +.na
366 +\fB\fB/etc/pam.d\fR\fR
367 +.ad
368 +.RS 29n
369 +Configuration directory
370 +.RE
371 +
348 372 .sp
349 373 .ne 2
350 374 .na
351 375 \fB\fB/usr/lib/$ISA/libpam.so.1\fR\fR
352 376 .ad
353 377 .RS 29n
354 378 File that implements the \fBPAM\fR framework library
355 379 .RE
356 380
357 381 .SH EXAMPLES
358 382 .LP
359 383 \fBExample 1 \fRUsing the include control flag
360 384 .sp
361 385 .LP
362 386 The following example collects the common Unix modules into a single file to be
363 387 included as needed in the example of a \fBpam.conf\fR file. The common Unix
364 388 module file is named \fBunix_common\fR and consists of:
365 389
366 390 .sp
367 391 .in +2
368 392 .nf
369 393 OTHER auth requisite pam_authtok_get.so.1
370 394 OTHER auth required pam_dhkeys.so.1
371 395 OTHER auth required pam_unix_auth.so.1
372 396 OTHER auth required pam_unix_cred.so.1
373 397 OTHER account requisite pam_roles.so.1
374 398 OTHER account required pam_unix_account.so.1
375 399 OTHER session required pam_unix_session.so.1
376 400 OTHER password required pam_dhkeys.so.1
377 401 OTHER password requisite pam_authtok_get.so.1
378 402 OTHER password requisite pam_authtok_check.so.1
379 403 OTHER password required pam_authtok_store.so.1
380 404 .fi
381 405 .in -2
382 406 .sp
383 407
384 408 .sp
385 409 .LP
386 410 The \fBpam.conf\fR file and consists of:
387 411
388 412 .sp
389 413 .in +2
390 414 .nf
391 415 # Authentication management
392 416 #
393 417 # login service (explicit because of pam_dial_auth)
394 418 #
395 419 login auth include unix_common
396 420 login auth required pam_dial_auth.so.1
397 421 #
398 422 # rlogin service (explicit because of pam_rhost_auth)
399 423 #
400 424 rlogin auth sufficient pam_rhosts_auth.so.1
401 425 rlogin auth include unix_common
402 426 #
403 427 # Default definitions for Authentication management
404 428 # Used when service name is not explicitly mentioned
405 429 #
406 430 OTHER auth include unix_common
407 431 #
408 432 # Default definition for Account management
409 433 # Used when service name is not explicitly mentioned
410 434 #
411 435 OTHER account include unix_common
412 436 #
413 437 # Default definition for Session management
414 438 # Used when service name is not explicitly mentioned
415 439 #
416 440 OTHER session include unix_common
417 441 #
418 442 # Default definition for Password management
419 443 # Used when service name is not explicitly mentioned
420 444 #
421 445 OTHER password include unix_common
422 446 .fi
423 447 .in -2
424 448 .sp
425 449
426 450 .SH ATTRIBUTES
427 451 .sp
428 452 .LP
429 453 See \fBattributes\fR(5) for descriptions of the following attributes:
430 454 .sp
431 455
432 456 .sp
433 457 .TS
434 458 box;
435 459 c | c
436 460 l | l .
437 461 ATTRIBUTE TYPE ATTRIBUTE VALUE
438 462 _
439 463 Interface Stability See Below.
440 464 .TE
441 465
442 466 .sp
443 467 .LP
444 468 The format is Stable. The contents has no stability attributes.
445 469 .SH SEE ALSO
446 470 .sp
447 471 .LP
448 472 \fBlogin\fR(1), \fBpasswd\fR(1), \fBin.ftpd\fR(1M), \fBin.rlogind\fR(1M),
449 473 \fBin.rshd\fR(1M), \fBin.telnetd\fR(1M), \fBin.uucpd\fR(1M), \fBinit\fR(1M),
450 474 \fBrpc.rexd\fR(1M), \fBsac\fR(1M), \fBttymon\fR(1M), \fBsu\fR(1M),
451 475 \fBpam\fR(3PAM), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBattributes\fR(5),
452 476 \fBenviron\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
453 477 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_krb5\fR(5),
454 478 \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5),
455 479 \fBpam_unix_session\fR(5)
456 480 .SH NOTES
457 481 .sp
458 482 .LP
459 483 The \fBpam_unix\fR module is no longer supported. Similar functionality is
460 484 provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
461 485 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5),
462 486 \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and
463 487 \fBpam_unix_session\fR(5).
464 488 .sp
465 489 .LP
466 490 With the removal of the \fBpam_unix\fR module, the SunOS delivered PAM service
467 491 modules no longer need or support the "\fBuse_first_pass\fR" or
468 492 "\fBtry_first_pass\fR" options. This functionality is provided by stacking
469 493 \fBpam_authtok_get\fR(5) above a module that requires a password.
|
↓ open down ↓ |
112 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX