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 741 2013-09-07 13:34:02Z des $ 30.\" 31.Dd September 7, 2013 32.Dt PAM.CONF 5 33.Os 34.Sh NAME 35.Nm pam.conf 36.Nd PAM policy file format 37.Sh DESCRIPTION 38The PAM library searches for policies in the following files, in 39decreasing 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 51If none of these locations contains a policy for the given service, 52the 53.Dq Dv other 54policy is used instead, if it exists. 55.Pp 56Entries in per-service policy files must be of one of the two forms 57below: 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 63Entries in 64.Pa pam.conf Ns -style 65policy files are of the same form, but are prefixed by an additional 66field specifying the name of the service they apply to. 67.Pp 68In both cases, blank lines and comments introduced by a 69.Ql # 70sign are ignored, and the normal shell quoting rules apply. 71The precise details of how the file is tokenized are described in 72.Xr openpam_readword 3 . 73.Pp 74The 75.Ar facility 76field specifies the facility the entry applies to, and is one of: 77.Bl -tag -width 12n 78.It Cm auth 79Authentication functions 80.Po 81.Xr pam_authenticate 3 , 82.Xr pam_setcred 3 83.Pc 84.It Cm account 85Account management functions 86.Pq Xr pam_acct_mgmt 3 87.It Cm session 88Session handling functions 89.Po 90.Xr pam_open_session 3 , 91.Xr pam_close_session 3 92.Pc 93.It Cm password 94Password management functions 95.Pq Xr pam_chauthtok 3 96.El 97.Pp 98The 99.Ar control-flag 100field determines how the result returned by the module affects the 101flow of control through (and the final result of) the rest of the 102chain, and is one of: 103.Bl -tag -width 12n 104.It Cm required 105If this module succeeds, the result of the chain will be success 106unless a later module fails. 107If it fails, the rest of the chain still runs, but the final result 108will be failure regardless of the success of later modules. 109.It Cm requisite 110If this module succeeds, the result of the chain will be success 111unless a later module fails. 112If the module fails, the chain is broken and the result is failure. 113.It Cm sufficient 114If this module succeeds, the chain is broken and the result is 115success. 116If it fails, the rest of the chain still runs, but the final result 117will be failure unless a later module succeeds. 118.It Cm binding 119If this module succeeds, the chain is broken and the result is 120success. 121If it fails, the rest of the chain still runs, but the final result 122will be failure regardless of the success of later modules. 123.It Cm optional 124If this module succeeds, the result of the chain will be success 125unless a later module fails. 126If this module fails, the result of the chain will be failure unless a 127later module succeeds. 128.El 129.Pp 130There are two exceptions to the above: 131.Cm sufficient 132and 133.Cm binding 134modules are treated as 135.Cm optional 136by 137.Xr pam_setcred 3 , 138and in the 139.Dv PAM_PRELIM_CHECK 140phase of 141.Xr pam_chauthtok 3 . 142.Pp 143The 144.Ar module-path 145field specifies the name or full path of the module to call. 146If only the name is specified, the PAM library will search for it in 147the following locations: 148.Bl -enum 149.It 150.Pa /usr/lib 151.It 152.Pa /usr/local/lib 153.El 154.Pp 155The remaining fields, if any, are passed unmodified to the module if 156and when it is invoked. 157.Pp 158The 159.Cm include 160form of entry causes entries from a different chain (specified by 161.Ar other-system-name ) 162to be included in the current one. 163This allows one to define system-wide policies which are then included 164into service-specific policies. 165The system-wide policy can then be modified without having to also 166modify each and every service-specific policy. 167.Pp 168.Bf -symbolic 169Take care not to introduce loops when using 170.Cm include 171rules, as there is currently no loop detection in place. 172.Ef 173.Sh MODULE OPTIONS 174Some PAM library functions may alter their behavior when called by a 175service module if certain module options were specified, regardless of 176whether the module itself accords them any importance. 177One such option is 178.Cm debug , 179which causes the dispatcher to enable debugging messages before 180calling each service function, and disable them afterwards (unless 181they were already enabled). 182Other special options include: 183.Bl -tag -width 12n 184.It Cm authtok_prompt Ns = Ns Ar prompt , Cm oldauthtok_prompt Ns = Ns Ar prompt , Cm user_prompt Ns = Ns Ar prompt 185These options can be used to override the prompts used by 186.Xr pam_get_authtok 3 187and 188.Xr pam_get_user 3 . 189.It Cm echo_pass 190This option controls whether 191.Xr pam_get_authtok 3 192will allow the user to see what they are typing. 193.It Cm try_first_pass , Cm use_first_pass 194These options control 195.Xr pam_get_authtok 3 Ns 's 196use of cached authentication tokens. 197.El 198.Sh SEE ALSO 199.Xr pam 3 200.Sh STANDARDS 201.Rs 202.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" 203.%D "June 1997" 204.Re 205.Sh AUTHORS 206The OpenPAM library was developed for the 207.Fx 208Project by ThinkSec AS and Network Associates Laboratories, the 209Security Research Division of Network Associates, Inc.\& under 210DARPA/SPAWAR contract N66001-01-C-8035 211.Pq Dq CBOSS , 212as part of the DARPA CHATS research program. 213.Pp 214The OpenPAM library is maintained by 215.An Dag-Erling Sm\(/orgrav Aq des@des.no . 216