contrib/libpam/doc/man/pam.8

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\" $Id: pam.8,v 1.2 1997/02/15 18:37:27 morgan Exp $
   3 .\" $FreeBSD: src/contrib/libpam/doc/man/pam.8,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
   4 .\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam.8,v 1.2 2003/06/17 04:24:02 dillon Exp $
   5 .\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org>
   6 .TH PAM 8 "1997 Feb 9" "PAM 0.56" "PAM Manual"
   7 .SH NAME
   8
   9 PAM \- Pluggable Authentication Modules
  10
  11 .SH SYNOPSIS
  12 .B /etc/pam.conf
  13 .sp 2
  14 .SH DESCRIPTION
  15
  16 This manual is intended to offer a quick introduction to
  17 .BR PAM ". "
  18 For more information the reader is directed to the
  19 .BR "Linux-PAM system administrators' guide".
  20
  21 .sp
  22 .BR PAM
  23 Is a system of libraries that handle the authentication tasks of
  24 applications (services) on the system.  The library provides a stable
  25 general interface (Application Programming Interface - API) that
  26 privilege granting programs (such as
  27 .BR login "(1) "
  28 and
  29 .BR su "(1)) "
  30 defer to to perform standard authentication tasks.
  31
  32 .sp
  33 The principal feature of the PAM approach is that the nature of the
  34 authentication is dynamically configurable.  In other words, the
  35 system administrator is free to choose how individual
  36 service-providing applications will authenticate users. This dynamic
  37 configuration is set by the contents of the single
  38 .BR PAM
  39 configuration file
  40 .BR /etc/pam.conf "."
  41 Alternatively, the configuration can be set by individual
  42 configuration files located in the
  43 .B /etc/pam.d/
  44 directory.
  45 .IB "The presence of this directory will cause " PAM " to ignore"
  46 .BI /etc/pam.conf "."
  47
  48 .sp
  49 From the point of view of the system administrator, for whom this
  50 manual is provided, it is not of primary importance to understand the
  51 internal behavior of the
  52 .BR PAM
  53 library.  The important point to recognize is that the configuration
  54 file(s)
  55 .I define
  56 the connection between applications
  57 .BR "" "(" services ")"
  58 and the pluggable authentication modules
  59 .BR "" "(" PAM "s)"
  60 that perform the actual authentication tasks.
  61
  62 .sp
  63 .BR PAM
  64 separates the tasks of
  65 .I authentication
  66 into four independent management groups:
  67 .BR "account" " management; "
  68 .BR "auth" "entication management; "
  69 .BR "password" " management; "
  70 and
  71 .BR "session" " management."
  72 (We highlight the abbreviations used for these groups in the
  73 configuration file.)
  74
  75 .sp
  76 Simply put, these groups take care of different aspects of a typical
  77 user's request for a restricted service:
  78
  79 .sp
  80 .BR account " - "
  81 provide account verification types of service: has the user's password
  82 expired?; is this user permitted access to the requested service?
  83
  84 .br
  85 .BR auth "entication - "
  86 establish the user is who they claim to be. Typically this is via some
  87 challenge-response request that the user must satisfy: if you are who
  88 you claim to be please enter your password.  Not all authentications
  89 are of this type, there exist hardware based authentication schemes
  90 (such as the use of smart-cards and biometric devices), with suitable
  91 modules, these may be substituted seamlessly for more standard
  92 approaches to authentication - such is the flexibility of
  93 .BR PAM "."
  94
  95 .br
  96 .BR password " - "
  97 this group's responsibility is the task of updating authentication
  98 mechanisms. Typically, such services are strongly coupled to those of
  99 the
 100 .BR auth
 101 group. Some authentication mechanisms lend themselves well to being
 102 updated with such a function. Standard UN*X password-based access is
 103 the obvious example: please enter a replacement password.
 104
 105 .br
 106 .BR session " - "
 107 this group of tasks cover things that should be done prior to a
 108 service being given and after it is withdrawn. Such tasks include the
 109 maintenance of audit trails and the mounting of the user's home
 110 directory. The
 111 .BR session
 112 management group is important as it provides both an opening and
 113 closing hook for modules to affect the services available to a user.
 114
 115 .SH The configuration file(s)
 116
 117 When a
 118 .BR PAM
 119 aware privilege granting application is started, it activates its
 120 attachment to the PAM-API.  This activation performs a number of
 121 tasks, the most important being the reading of the configuration file(s):
 122 .BR /etc/pam.conf "."
 123 Alternatively, this may be the contents of the
 124 .BR /etc/pam.d/
 125 directory.
 126
 127 These files list the
 128 .BR PAM "s"
 129 that will do the authentication tasks required by this service, and
 130 the appropriate behavior of the PAM-API in the event that individual
 131 .BR PAM "s "
 132 fail.
 133
 134 .sp
 135 The syntax of the
 136 .B /etc/pam.conf
 137 configuration file is as follows. The file is made
 138 up of a list of rules, each rule is typically placed on a single line,
 139 but may be extended with an escaped end of line: `\\<LF>'. Comments
 140 are preceded with `#' marks and extend to the next end of line.
 141
 142 .sp
 143 The format of each rule is a space separated collection of tokens, the
 144 first three being case-insensitive:
 145
 146 .sp
 147 .br
 148 .BR "   service  type  control  module-path  module-arguments"
 149
 150 .sp
 151 The syntax of files contained in the
 152 .B /etc/pam.d/
 153 directory, are identical except for the absence of any
 154 .I service
 155 field. In this case, the
 156 .I service
 157 is the name of the file in the
 158 .B /etc/pam.d/
 159 directory. This filename must be in lower case.
 160
 161 .sp
 162 An important feature of
 163 .BR PAM ", "
 164 is that a number of rules may be
 165 .I stacked
 166 to combine the services of a number of PAMs for a given authentication
 167 task.
 168
 169 .sp
 170 The
 171 .BR service
 172 is typically the familiar name of the corresponding application:
 173 .BR login
 174 and
 175 .BR su
 176 are good examples. The
 177 .BR service "-name, " other ", "
 178 is reserved for giving
 179 .I default
 180 rules.  Only lines that mention the current service (or in the absence
 181 of such, the
 182 .BR other
 183 entries) will be associated with the given service-application.
 184
 185 .sp
 186 The
 187 .BR type
 188 is the management group that the rule corresponds to. It is used to
 189 specify which of the management groups the subsequent module is to
 190 be associated with. Valid entries are:
 191 .BR account "; "
 192 .BR auth "; "
 193 .BR password "; "
 194 and
 195 .BR session "."
 196 The meaning of each of these tokens was explained above.
 197
 198 .sp
 199 The third field,
 200 .BR control ", "
 201 indicates the behavior of the PAM-API should the module fail to
 202 succeed in its authentication task. Valid
 203 .BR control
 204 values are:
 205 .BR requisite
 206 - failure of such a PAM results in the immediate termination of the
 207 authentication process;
 208 .BR required
 209 - failure of such a PAM will ultimately lead to the PAM-API returning
 210 failure but only after the remaining
 211 .I stacked
 212 modules (for this
 213 .BR service
 214 and
 215 .BR type ")"
 216 have been invoked;
 217 .BR sufficient
 218 - success of such a module is enough to satisfy the authentication
 219 requirements of the stack of modules (if a prior
 220 .BR required
 221 module has failed the success of this one is
 222 .IR ignored "); "
 223 .BR optional
 224 - the success or failure of this module is only important if it is the
 225 only module in the stack associated with this
 226 .BR service "+" type "."
 227
 228 .sp
 229 .BR module-path
 230 - this is the full filename of the PAM to be used by the application
 231
 232 .sp
 233 .BR module-arguments
 234 - these are a space separated list of tokens that can be used to
 235 modify the specific behavior of the given PAM. Such arguments will be
 236 documented for each individual module.
 237
 238 .SH "FILES"
 239 .BR /etc/pam.conf " - the configuration file"
 240 .br
 241 .BR /etc/pam.d/ " - the"
 242 .BR PAM
 243 configuration directory. If this directory is present, the
 244 .B /etc/pam.conf
 245 file is ignored.
 246 .br
 247 .BR /usr/lib/libpam.so.X " - the dynamic library"
 248 .br
 249 .BR /usr/lib/pam_*.so " - the PAMs
 250
 251 .SH ERRORS
 252 Typically errors generated by the
 253 .BR PAM
 254 system of libraries, will be written to
 255 .BR syslog "(3)."
 256
 257 .SH "CONFORMING TO"
 258 DCE-RFC 86.0, October 1995.
 259 .br
 260 Contains additional features, currently under consideration by the
 261 DCE-RFC committee.
 262
 263 .SH BUGS
 264 .sp 2
 265 None known.
 266
 267 .SH "SEE ALSO"
 268
 269 The three
 270 .BR Linux-PAM
 271 Guides, for
 272 .BR "System administrators" ", "
 273 .BR "module developers" ", "
 274 and
 275 .BR "application developers" ". "