lib/pam_module/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: src/lib/libpam/modules/pam_unix/pam_unix.8,v 1.13 2007/03/27 09:59:15 yar Exp $
  36 .\" $DragonFly: src/lib/pam_module/pam_unix/pam_unix.8,v 1.1 2005/08/01 16:15:19 joerg Exp $
  37 .\"
  38 .Dd March 27, 2007
  39 .Dt PAM_UNIX 8
  40 .Os
  41 .Sh NAME
  42 .Nm pam_unix
  43 .Nd UNIX PAM module
  44 .Sh SYNOPSIS
  45 .Op Ar service-name
  46 .Ar module-type
  47 .Ar control-flag
  48 .Pa pam_unix
  49 .Op Ar options
  50 .Sh DESCRIPTION
  51 The
  52 .Ux
  53 authentication service module for PAM,
  54 .Nm
  55 provides functionality for three PAM categories:
  56 authentication,
  57 account management, and password management.
  58 In terms of the
  59 .Ar module-type
  60 parameter, they are the
  61 .Dq Li auth ,
  62 .Dq Li account ,
  63 and
  64 .Dq Li password
  65 features.
  66 It also provides a null function for session management.
  67 .Ss Ux Ss Authentication Module
  68 The
  69 .Ux
  70 authentication component
  71 provides functions to verify the identity of a user
  72 .Pq Fn pam_sm_authenticate ,
  73 which obtains the relevant
  74 .Xr passwd 5
  75 entry.
  76 It prompts the user for a password
  77 and verifies that this is correct with
  78 .Xr crypt 3 .
  79 .Pp
  80 The following options may be passed to the authentication module:
  81 .Bl -tag -width ".Cm use_first_pass"
  82 .It Cm debug
  83 .Xr syslog 3
  84 debugging information at
  85 .Dv LOG_DEBUG
  86 level.
  87 .It Cm use_first_pass
  88 If the authentication module
  89 is not the first in the stack,
  90 and a previous module
  91 obtained the user's password,
  92 that password is used
  93 to authenticate the user.
  94 If this fails,
  95 the authentication module returns failure
  96 without prompting the user for a password.
  97 This option has no effect
  98 if the authentication module
  99 is the first in the stack,
 100 or if no previous modules
 101 obtained the user's password.
 102 .It Cm try_first_pass
 103 This option is similar to the
 104 .Cm use_first_pass
 105 option,
 106 except that if the previously obtained password fails,
 107 the user is prompted for another password.
 108 .It Cm auth_as_self
 109 This option will require the user
 110 to authenticate himself as the user
 111 given by
 112 .Xr getlogin 2 ,
 113 not as the account they are attempting to access.
 114 This is primarily for services like
 115 .Xr su 1 ,
 116 where the user's ability to retype
 117 their own password
 118 might be deemed sufficient.
 119 .It Cm nullok
 120 If the password database
 121 has no password
 122 for the entity being authenticated,
 123 then this option
 124 will forgo password prompting,
 125 and silently allow authentication to succeed.
 126 .It Cm local_pass
 127 Use only the local password database,
 128 even if NIS is in use.
 129 This will cause an authentication failure
 130 if the system is configured
 131 to only use NIS.
 132 .It Cm nis_pass
 133 Use only the NIS password database.
 134 This will cause an authentication failure
 135 if the system is not configured
 136 to use NIS.
 137 .El
 138 .Ss Ux Ss Account Management Module
 139 The
 140 .Ux
 141 account management component
 142 provides a function to perform account management,
 143 .Fn pam_sm_acct_mgmt .
 144 The function verifies
 145 that the authenticated user
 146 is allowed to log into the local user account
 147 by checking the following criteria:
 148 .Bl -dash -offset indent
 149 .It
 150 locked status of the account compatible with
 151 .Xr pw 8
 152 .Cm lock ;
 153 .It
 154 the password expiry date from
 155 .Xr passwd 5 ;
 156 .It
 157 .Xr login.conf 5
 158 restrictions on the remote host, login time, and tty.
 159 .El
 160 .Pp
 161 The following options may be passed to the management module:
 162 .Bl -tag -width ".Cm use_first_pass"
 163 .It Cm debug
 164 .Xr syslog 3
 165 debugging information at
 166 .Dv LOG_DEBUG
 167 level.
 168 .El
 169 .Ss Ux Ss Password Management Module
 170 The
 171 .Ux
 172 password management component
 173 provides a function to perform password management,
 174 .Fn pam_sm_chauthtok .
 175 The function changes
 176 the user's password.
 177 .Pp
 178 The following options may be passed to the password module:
 179 .Bl -tag -width ".Cm use_first_pass"
 180 .It Cm debug
 181 .Xr syslog 3
 182 debugging information at
 183 .Dv LOG_DEBUG
 184 level.
 185 .It Cm no_warn
 186 suppress warning messages to the user.
 187 These messages include
 188 reasons why the user's
 189 authentication attempt was declined.
 190 .It Cm local_pass
 191 forces the password module
 192 to change a local password
 193 in favour of a NIS one.
 194 .It Cm nis_pass
 195 forces the password module
 196 to change a NIS password
 197 in favour of a local one.
 198 .El
 199 .Sh FILES
 200 .Bl -tag -width ".Pa /etc/master.passwd" -compact
 201 .It Pa /etc/master.passwd
 202 default
 203 .Ux
 204 password database.
 205 .El
 206 .Sh SEE ALSO
 207 .Xr passwd 1 ,
 208 .Xr getlogin 2 ,
 209 .Xr crypt 3 ,
 210 .Xr getpwent 3 ,
 211 .Xr syslog 3 ,
 212 .Xr nsswitch.conf 5 ,
 213 .Xr passwd 5 ,
 214 .Xr pam 8 ,
 215 .Xr pw 8 ,
 216 .Xr yp 8