lib/libpam/modules/pam_unix/pam_unix.8

   1 .\" Copyright (c) 2001 Mark R V Murray
   2 .\" All rights reserved.
   3 .\" Copyright (c) 2001 Networks Associates Technology, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
   7 .\" NAI Labs, the Security Research Division of Network Associates, Inc.
   8 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
   9 .\" DARPA CHATS research program.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. The name of the author may not be used to endorse or promote
  20 .\"    products derived from this software without specific prior written
  21 .\"    permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd November 26, 2001
  38 .Dt PAM_UNIX 8
  39 .Os
  40 .Sh NAME
  41 .Nm pam_unix
  42 .Nd UNIX PAM module
  43 .Sh SYNOPSIS
  44 .Op Ar service-name
  45 .Ar module-type
  46 .Ar control-flag
  47 .Pa pam_unix
  48 .Op Ar options
  49 .Sh DESCRIPTION
  50 The
  51 .Ux
  52 authentication service module for PAM,
  53 .Nm
  54 provides functionality for two PAM categories:
  55 authentication
  56 and account management.
  57 In terms of the
  58 .Ar module-type
  59 parameter, they are the
  60 .Dq Li auth
  61 and
  62 .Dq Li account
  63 features.
  64 It also provides a null function for session management.
  65 .Ss Ux Ss Authentication Module
  66 The
  67 .Ux
  68 authentication component
  69 provides functions to verify the identity of a user
  70 .Pq Fn pam_sm_authenticate ,
  71 which obtains the relevant
  72 .Xr passwd 5
  73 entry.
  74 It prompts the user for a password
  75 and verifies that this is correct with
  76 .Xr crypt 3 .
  77 .Pp
  78 The following options may be passed to the authentication module:
  79 .Bl -tag -width ".Cm use_first_pass"
  80 .It Cm debug
  81 .Xr syslog 3
  82 debugging information at
  83 .Dv LOG_DEBUG
  84 level.
  85 .It Cm use_first_pass
  86 If the authentication module
  87 is not the first in the stack,
  88 and a previous module
  89 obtained the user's password,
  90 that password is used
  91 to authenticate the user.
  92 If this fails,
  93 the authentication module returns failure
  94 without prompting the user for a password.
  95 This option has no effect
  96 if the authentication module
  97 is the first in the stack,
  98 or if no previous modules
  99 obtained the user's password.
 100 .It Cm try_first_pass
 101 This option is similar to the
 102 .Cm use_first_pass
 103 option,
 104 except that if the previously obtained password fails,
 105 the user is prompted for another password.
 106 .It Cm auth_as_self
 107 This option will require the user
 108 to authenticate himself as the user
 109 given by
 110 .Xr getlogin 2 ,
 111 not as the account they are attempting to access.
 112 This is primarily for services like
 113 .Xr su 1 ,
 114 where the user's ability to retype
 115 their own password
 116 might be deemed sufficient.
 117 .It Cm nullok
 118 If the password database
 119 has no password
 120 for the entity being authenticated,
 121 then this option
 122 will forgo password prompting,
 123 and silently allow authentication to succeed.
 124 .It Cm local_pass
 125 Use only the local password database,
 126 even if NIS is in use.
 127 This will cause an authentication failure
 128 if the system is configured
 129 to only use NIS.
 130 .It Cm nis_pass
 131 Use only the NIS password database.
 132 This will cause an authentication failure
 133 if the system is not configured
 134 to use NIS.
 135 .El
 136 .Ss Ux Ss Account Management Module
 137 The
 138 .Ux
 139 account management component
 140 provides a function to perform account management,
 141 .Fn pam_sm_acct_mgmt .
 142 The function verifies
 143 that the authenticated user
 144 is allowed to login to the local user account
 145 by checking the password expiry date.
 146 .Pp
 147 The following options may be passed to the management module:
 148 .Bl -tag -width ".Cm use_first_pass"
 149 .It Cm debug
 150 .Xr syslog 3
 151 debugging information at
 152 .Dv LOG_DEBUG
 153 level.
 154 .El
 155 .Ss Ux Ss Password Management Module
 156 The
 157 .Ux
 158 password management component
 159 provides a function to perform account management,
 160 .Fn pam_sm_chauthtok .
 161 The function changes
 162 the user's password.
 163 .Pp
 164 The following options may be passed to the password module:
 165 .Bl -tag -width ".Cm use_first_pass"
 166 .It Cm debug
 167 .Xr syslog 3
 168 debugging information at
 169 .Dv LOG_DEBUG
 170 level.
 171 .It Cm no_warn
 172 suppress warning messages to the user.
 173 These messages include
 174 reasons why the user's
 175 authentication attempt was declined.
 176 .It Cm local_pass
 177 forces the password module
 178 to change a local password
 179 in favour of a NIS one.
 180 .It Cm nis_pass
 181 forces the password module
 182 to change a NIS password
 183 in favour of a local one.
 184 .El
 185 .Sh FILES
 186 .Bl -tag -width ".Pa /etc/master.passwd" -compact
 187 .It Pa /etc/master.passwd
 188 default
 189 .Ux
 190 password database.
 191 .El
 192 .Sh SEE ALSO
 193 .Xr passwd 1 ,
 194 .Xr getlogin 2 ,
 195 .Xr crypt 3 ,
 196 .Xr getpwent 3 ,
 197 .Xr syslog 3 ,
 198 .Xr nsswitch.conf 5 ,
 199 .Xr passwd 5 ,
 200 .Xr pam 8 ,
 201 .Xr yp 8