contrib/openpam/doc/man/pam.conf.5

   1 .\"-
   2 .\" Copyright (c) 2005-2017 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 .\" $OpenPAM: pam.conf.5 939 2017-04-30 21:36:50Z des $
  30 .\"
  31 .Dd April 30, 2017
  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 cases, blank lines and comments introduced by a
  69 .Ql #
  70 sign are ignored, and the normal shell quoting rules apply.
  71 The precise details of how the file is tokenized are described in
  72 .Xr openpam_readword 3 .
  73 .Pp
  74 The
  75 .Ar facility
  76 field specifies the facility the entry applies to, and is one of:
  77 .Bl -tag -width 12n
  78 .It Cm auth
  79 Authentication functions
  80 .Po
  81 .Xr pam_authenticate 3 ,
  82 .Xr pam_setcred 3
  83 .Pc
  84 .It Cm account
  85 Account management functions
  86 .Pq Xr pam_acct_mgmt 3
  87 .It Cm session
  88 Session handling functions
  89 .Po
  90 .Xr pam_open_session 3 ,
  91 .Xr pam_close_session 3
  92 .Pc
  93 .It Cm password
  94 Password management functions
  95 .Pq Xr pam_chauthtok 3
  96 .El
  97 .Pp
  98 The
  99 .Ar control-flag
 100 field determines how the result returned by the module affects the
 101 flow of control through (and the final result of) the rest of the
 102 chain, and is one of:
 103 .Bl -tag -width 12n
 104 .It Cm required
 105 If this module succeeds, the result of the chain will be success
 106 unless a later module fails.
 107 If it fails, the rest of the chain still runs, but the final result
 108 will be failure regardless of the success of later modules.
 109 .It Cm requisite
 110 If this module succeeds, the result of the chain will be success
 111 unless a later module fails.
 112 If the module fails, the chain is broken and the result is failure.
 113 .It Cm sufficient
 114 If this module succeeds, the chain is broken and the result is
 115 success.
 116 If it fails, the rest of the chain still runs, but the final result
 117 will be failure unless a later module succeeds.
 118 .It Cm binding
 119 If this module succeeds, the chain is broken and the result is
 120 success.
 121 If it fails, the rest of the chain still runs, but the final result
 122 will be failure regardless of the success of later modules.
 123 .It Cm optional
 124 If this module succeeds, the result of the chain will be success
 125 unless a later module fails.
 126 If this module fails, the result of the chain will be failure unless a
 127 later module succeeds.
 128 .El
 129 .Pp
 130 There are two exceptions to the above:
 131 .Cm sufficient
 132 and
 133 .Cm binding
 134 modules are treated as
 135 .Cm optional
 136 by
 137 .Xr pam_setcred 3 ,
 138 and in the
 139 .Dv PAM_PRELIM_CHECK
 140 phase of
 141 .Xr pam_chauthtok 3 .
 142 .Pp
 143 The
 144 .Ar module-path
 145 field specifies the name or full path of the module to call.
 146 If only the name is specified, the PAM library will search for it in
 147 the following locations:
 148 .Bl -enum
 149 .It
 150 .Pa /usr/lib
 151 .It
 152 .Pa /usr/local/lib
 153 .El
 154 .Pp
 155 The remaining fields, if any, are passed unmodified to the module if
 156 and when it is invoked.
 157 .Pp
 158 The
 159 .Cm include
 160 form of entry causes entries from a different chain (specified by
 161 .Ar other-system-name )
 162 to be included in the current one.
 163 This allows one to define system-wide policies which are then included
 164 into service-specific policies.
 165 The system-wide policy can then be modified without having to also
 166 modify each and every service-specific policy.
 167 .Pp
 168 .Bf -symbolic
 169 Take care not to introduce loops when using
 170 .Cm include
 171 rules, as there is currently no loop detection in place.
 172 .Ef
 173 .Sh MODULE OPTIONS
 174 Some PAM library functions may alter their behavior when called by a
 175 service module if certain module options were specified, regardless of
 176 whether the module itself accords them any importance.
 177 One such option is
 178 .Cm debug ,
 179 which causes the dispatcher to enable debugging messages before
 180 calling each service function, and disable them afterwards (unless
 181 they were already enabled).
 182 Other 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
 185 These options can be used to override the prompts used by
 186 .Xr pam_get_authtok 3
 187 and
 188 .Xr pam_get_user 3 .
 189 .It Cm echo_pass
 190 This option controls whether
 191 .Xr pam_get_authtok 3
 192 will allow the user to see what they are typing.
 193 .It Cm try_first_pass , Cm use_first_pass
 194 These options control
 195 .Xr pam_get_authtok 3 Ns 's
 196 use 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
 206 The OpenPAM library was developed for the
 207 .Fx
 208 Project by ThinkSec AS and Network Associates Laboratories, the
 209 Security Research Division of Network Associates, Inc.\& under
 210 DARPA/SPAWAR contract N66001-01-C-8035
 211 .Pq Dq CBOSS ,
 212 as part of the DARPA CHATS research program.
 213 .Pp
 214 The OpenPAM library is maintained by
 215 .An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .