1.\" $NetBSD: pam.conf.5,v 1.10 2019/12/15 17:08:21 christos Exp $ 2.\" 3.\"- 4.\" Copyright (c) 2005-2017 Dag-Erling Smørgrav 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote 16.\" products derived from this software without specific prior written 17.\" permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $OpenPAM: pam.conf.5 947 2019-02-24 20:18:17Z des $ 32.\" 33.Dd February 24, 2019 34.Dt PAM.CONF 5 35.Os 36.Sh NAME 37.Nm pam.conf 38.Nd PAM policy file format 39.Sh DESCRIPTION 40The PAM library searches for policies in the following files, in 41decreasing order of preference: 42.Bl -enum 43.It 44.Pa /etc/pam.d/ Ns Ar service-name 45.It 46.Pa /etc/pam.conf 47.\" .It 48.\" .Pa /usr/local/etc/pam.d/ Ns Ar service-name 49.\" .It 50.\" .Pa /usr/local/etc/pam.conf 51.El 52.Pp 53If none of these locations contains a policy for the given service, 54the 55.Dq Dv other 56policy is used instead, if it exists. 57.Pp 58Entries in per-service policy files must be of one of the two forms 59below: 60.Bd -unfilled -offset indent 61.Ar facility control-flag module-path Op Ar arguments ... 62.Ar facility Cm include Ar other-service-name 63.Ed 64.Pp 65Entries in 66.Pa pam.conf Ns -style 67policy files are of the same form, but are prefixed by an additional 68field specifying the name of the service they apply to. 69.Pp 70In both cases, blank lines and comments introduced by a 71.Ql # 72sign are ignored, and the normal shell quoting rules apply. 73The precise details of how the file is tokenized are described in 74.Xr openpam_readword 3 . 75.Pp 76The 77.Ar facility 78field specifies the facility the entry applies to, and is one of: 79.Bl -tag -width 12n 80.It Cm auth 81Authentication functions 82.Po 83.Xr pam_authenticate 3 , 84.Xr pam_setcred 3 85.Pc 86.It Cm account 87Account management functions 88.Pq Xr pam_acct_mgmt 3 89.It Cm session 90Session handling functions 91.Po 92.Xr pam_open_session 3 , 93.Xr pam_close_session 3 94.Pc 95.It Cm password 96Password management functions 97.Pq Xr pam_chauthtok 3 98.El 99.Pp 100The 101.Ar control-flag 102field determines how the result returned by the module affects the 103flow of control through (and the final result of) the rest of the 104chain, and is one of: 105.Bl -tag -width 12n 106.It Cm required 107If this module succeeds, the result of the chain will be success 108unless a later module fails. 109If it fails, the rest of the chain still runs, but the final result 110will be failure regardless of the success of later modules. 111.It Cm requisite 112If this module succeeds, the result of the chain will be success 113unless a later module fails. 114If the module fails, the chain is broken and the result is failure. 115.It Cm sufficient 116If this module succeeds, the chain is broken and the result is 117success. 118If it fails, the rest of the chain still runs, but the final result 119will be failure unless a later module succeeds. 120.It Cm binding 121If this module succeeds, the chain is broken and the result is 122success. 123If it fails, the rest of the chain still runs, but the final result 124will be failure regardless of the success of later modules. 125.It Cm optional 126If this module succeeds, the result of the chain will be success 127unless a later module fails. 128If this module fails, the result of the chain will be failure unless a 129later module succeeds. 130.El 131.Pp 132There are two exceptions to the above: 133.Cm sufficient 134and 135.Cm binding 136modules are treated as 137.Cm optional 138by 139.Xr pam_setcred 3 , 140and in the 141.Dv PAM_PRELIM_CHECK 142phase of 143.Xr pam_chauthtok 3 . 144.Pp 145The 146.Ar module-path 147field specifies the name or full path of the module to call. 148If only the name is specified, the PAM library will search for it in 149the following location: 150.Bl -enum 151.It 152.\" .Pa /usr/lib 153.Pa /usr/lib/security 154.\" .It 155.\" .Pa /usr/local/lib 156.El 157.Pp 158The remaining fields, if any, are passed unmodified to the module if 159and when it is invoked. 160.Pp 161The 162.Cm include 163form of entry causes entries from a different chain (specified by 164.Ar other-system-name ) 165to be included in the current one. 166This allows one to define system-wide policies which are then included 167into service-specific policies. 168The system-wide policy can then be modified without having to also 169modify each and every service-specific policy. 170.Pp 171.Bf -symbolic 172Take care not to introduce loops when using 173.Cm include 174rules, as there is currently no loop detection in place. 175.Ef 176.Sh MODULE OPTIONS 177Some PAM library functions may alter their behavior when called by a 178service module if certain module options were specified, regardless of 179whether the module itself accords them any importance. 180One such option is 181.Cm debug , 182which causes the dispatcher to enable debugging messages before 183calling each service function, and disable them afterwards (unless 184they were already enabled). 185Other special options include: 186.Bl -tag -width 12n 187.It Cm authtok_prompt Ns = Ns Ar prompt , Cm oldauthtok_prompt Ns = Ns Ar prompt , Cm user_prompt Ns = Ns Ar prompt 188These options can be used to override the prompts used by 189.Xr pam_get_authtok 3 190and 191.Xr pam_get_user 3 . 192.It Cm echo_pass 193This option controls whether 194.Xr pam_get_authtok 3 195will allow the user to see what they are typing. 196.It Cm try_first_pass , Cm use_first_pass 197These options control 198.Xr pam_get_authtok 3 Ns 's 199use of cached authentication tokens. 200.El 201.Sh SEE ALSO 202.Xr pam 3 203.Sh STANDARDS 204.Rs 205.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" 206.%D "June 1997" 207.Re 208.Sh AUTHORS 209The OpenPAM library was developed for the 210.Fx 211Project by ThinkSec AS and Network Associates Laboratories, the 212Security Research Division of Network Associates, Inc.\& under 213DARPA/SPAWAR contract N66001-01-C-8035 214.Pq Dq CBOSS , 215as part of the DARPA CHATS research program. 216.Pp 217The OpenPAM library is maintained by 218.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 219