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