share/man/man5/pam.conf.5

   1 .\"     $NetBSD: pam.conf.5,v 1.8 2005/03/17 12:55:26 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Jason R. Thorpe.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 17, 2005
  31 .Dt PAM.CONF 5
  32 .Os
  33 .Sh NAME
  34 .Nm pam.conf
  35 .Nd Pluggable Authentication Modules configuration file
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 file specifies how Pluggable Authentication Modules
  40 .Pq PAM
  41 should operate.
  42 For an overview of the Pluggable Authentication Modules framework, see
  43 .Xr pam 8 .
  44 .Pp
  45 PAM may be configured using a single
  46 .Pa /etc/pam.conf
  47 configuration file or by using multiple configuration files, one for each
  48 PAM-aware service, located in the
  49 .Pa /etc/pam.d/
  50 directory.
  51 If
  52 .Pa /etc/pam.d/
  53 exists,
  54 .Pa /etc/pam.conf
  55 will be ignored.
  56 .Pa /etc/pam.d/
  57 is the preferred method for configuring PAM.
  58 .Pp
  59 PAM's configuration is based on
  60 .Dq stacking
  61 different modules together to form a processing chain for the task.
  62 A standard PAM configuration stanza is structured as follows:
  63 .Bd -filled -offset indent
  64 .Op Ar service-name
  65 .Ar module-type
  66 .Ar control-flag
  67 .Ar module-name
  68 .Op Ar options
  69 .Ed
  70 .Pp
  71 .Ar service-name
  72 is used only
  73 .Pq and is mandatory
  74 in
  75 .Pa /etc/pam.conf .
  76 It specifies the PAM-aware service whose PAM behavior is being configured.
  77 When
  78 .Pa /etc/pam.d/
  79 is used, the name of the configuration file specifies the service.
  80 .Pp
  81 .Ar module-type
  82 specifies which of the four classes of PAM module functionality is being
  83 configured.
  84 These four classes are
  85 .Em account
  86 .Pq account management ,
  87 .Em auth
  88 .Pq authentication ,
  89 .Em password
  90 .Pq password management ,
  91 and
  92 .Em session
  93 .Pq session management .
  94 .Pp
  95 .Ar control-flag
  96 specifies the behavior of the processing chain upon success or failure
  97 of the PAM module's authentication task.
  98 The following are valid values for
  99 .Ar control-flag :
 100 .Bl -tag -width sufficient
 101 .It binding
 102 If the module succeeds and no earlier module in the chain
 103 has failed, the chain is immediately terminated and the
 104 request is granted.
 105 If the module fails, the rest of the chain is executed,
 106 but the request is ultimately denied.
 107 .It requisite
 108 If the module returns success, continue to execute the processing chain.
 109 If the module fails, immediately return the error code from the first
 110 .Sq required
 111 failure.
 112 .It required
 113 If the module returns success, continue to execute the processing chain.
 114 If the module fails, record as a
 115 .Sq required
 116 failure and continue to execute the processing chain.
 117 If there are any
 118 .Sq required
 119 failures in the processing chain, the chain will ultimately return
 120 failure.
 121 .It optional
 122 If the module returns success, continue to execute the processing chain.
 123 If the module fails, record as an
 124 .Sq optional
 125 failure and continue to execute the processing chain.
 126 .It sufficient
 127 If the module returns success and there have been no recorded
 128 .Sq required
 129 failures, immediately return success without calling any subsequent
 130 modules in the processing chain.
 131 If the module fails, return as an
 132 .Sq optional
 133 failure and continue to execute the processing chain.
 134 .El
 135 .Pp
 136 .Ar module-name
 137 specifies the module to execute for this stanza.
 138 This is either an absolute path name or a path name relative to the
 139 default module location:
 140 .Pa /usr/lib/security .
 141 .Pp
 142 .Ar options
 143 are additional options that may be specified for the module.
 144 Refer to the individual modules' documentation for more information
 145 on available options.
 146 .Pp
 147 In addition to the standard configuration stanza format, there is
 148 an additional stanza format available when
 149 .Pa /etc/pam.d/
 150 is used:
 151 .Bd -filled -offset indent
 152 .Ar module-type
 153 include
 154 .Ar service-name
 155 .Ed
 156 .Pp
 157 This stanza format provides a simple inheritance model for processing
 158 chains.
 159 .Sh FILES
 160 .Bl -tag -width /etc/pam.conf -compact
 161 .It Pa /etc/pam.conf
 162 monolithic PAM configuration file
 163 .It Pa /etc/pam.d/
 164 PAM service configuration file directory
 165 .El
 166 .Sh EXAMPLES
 167 The following
 168 .Em auth
 169 processing chain for the
 170 .Dq login
 171 service
 172 .Po
 173 located in
 174 .Pa /etc/pam.d/login
 175 .Pc
 176 performs the following tasks: allows the login if the old user
 177 and new user are the same, verifies that logins are not disabled using
 178 the
 179 .Pa /var/run/nologin
 180 file, allows Kerberos 5 password authentication, and requires standard
 181 .Ux
 182 password authentication if Kerberos 5 failed:
 183 .Bd -literal -offset indent
 184 auth    sufficient      pam_self.so
 185 auth    required        pam_nologin.so
 186 auth    sufficient      pam_krb5.so
 187 auth    required        pam_unix.so
 188 .Ed
 189 .Sh NOTES
 190 It is important to note that loading a chain will fail if any of the
 191 components of the chain fail to load or are not available.
 192 A common situation when this can happen is on a system that where
 193 components such as
 194 .Xr kerberos 1
 195 or
 196 .Xr crypto 3
 197 have not been installed.
 198 In that situation
 199 .Xr pam_krb5 8 ,
 200 .Xr pam_ksu 8 ,
 201 or
 202 .Xr pam_ssh 8
 203 might not be present in the system.
 204 In order for a chain to load properly all non-present components must
 205 be removed from the chain.
 206 .Sh SEE ALSO
 207 .Xr login 1 ,
 208 .Xr passwd 1 ,
 209 .Xr su 1 ,
 210 .Xr pam 3 ,
 211 .Xr pam 8
 212 .Sh HISTORY
 213 The
 214 .Nm
 215 file format first appeared in
 216 .Nx 3.0 .