lib/libpam/modules/pam_unix/pam_unix.8

   1 .\" $NetBSD: pam_unix.8,v 1.7 2005/02/26 15:39:50 wiz Exp $
   2 .\" Copyright (c) 2001 Mark R V Murray
   3 .\" All rights reserved.
   4 .\" Copyright (c) 2001 Networks Associates Technology, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
   8 .\" NAI Labs, the Security Research Division of Network Associates, Inc.
   9 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
  10 .\" DARPA CHATS research program.
  11 .\"
  12 .\" Redistribution and use in source and binary forms, with or without
  13 .\" modification, are permitted provided that the following conditions
  14 .\" are met:
  15 .\" 1. Redistributions of source code must retain the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer.
  17 .\" 2. Redistributions in binary form must reproduce the above copyright
  18 .\"    notice, this list of conditions and the following disclaimer in the
  19 .\"    documentation and/or other materials provided with the distribution.
  20 .\" 3. The name of the author may not be used to endorse or promote
  21 .\"    products derived from this software without specific prior written
  22 .\"    permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\" $FreeBSD: src/lib/libpam/modules/pam_unix/pam_unix.8,v 1.11 2005/01/21 10:44:10 ru Exp $
  37 .\"
  38 .Dd February 26, 2005
  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 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 .\" XXX This is not currently implemented.  It's debatable whether or not
 125 .\" XXX it should be.
 126 .\" .It Cm passwd_db Ns = Ns Ar name
 127 .\" Use only the specified password database.
 128 .\" Valid password database names are:
 129 .\" .Bl -tag -width files
 130 .\" .It files
 131 .\" local password file
 132 .\" .It nis
 133 .\" NIS password database
 134 .\" .El
 135 .\" .Pp
 136 .\" If the user does not exist in the specified password database or if the
 137 .\" system is not configured to use the specified password database, an
 138 .\" authentication failure will occur.
 139 .El
 140 .Ss Ux Ss Account Management Module
 141 The
 142 .Ux
 143 account management component
 144 provides a function to perform account management,
 145 .Fn pam_sm_acct_mgmt .
 146 The function verifies
 147 that the authenticated user
 148 is allowed to login to the local user account
 149 by checking the password expiry date.
 150 .Pp
 151 The following options may be passed to the management module:
 152 .Bl -tag -width ".Cm use_first_pass"
 153 .It Cm debug
 154 .Xr syslog 3
 155 debugging information at
 156 .Dv LOG_DEBUG
 157 level.
 158 .El
 159 .Ss Ux Ss Password Management Module
 160 The
 161 .Ux
 162 password management component
 163 provides a function to perform account management,
 164 .Fn pam_sm_chauthtok .
 165 The function changes
 166 the user's password.
 167 .Pp
 168 The following options may be passed to the password module:
 169 .Bl -tag -width ".Cm use_first_pass"
 170 .It Cm debug
 171 .Xr syslog 3
 172 debugging information at
 173 .Dv LOG_DEBUG
 174 level.
 175 .It Cm no_warn
 176 suppress warning messages to the user.
 177 These messages include
 178 reasons why the user's
 179 authentication attempt was declined.
 180 .It Cm passwd_db Ns = Ns Ar name
 181 Change the user's password only the specified password database.
 182 Valid password database names are:
 183 .Bl -tag -width files
 184 .It files
 185 local password file
 186 .It nis
 187 NIS password database
 188 .El
 189 .El
 190 .Sh FILES
 191 .Bl -tag -width ".Pa /etc/master.passwd" -compact
 192 .It Pa /etc/master.passwd
 193 default
 194 .Ux
 195 password database.
 196 .El
 197 .Sh SEE ALSO
 198 .Xr passwd 1 ,
 199 .Xr getlogin 2 ,
 200 .Xr crypt 3 ,
 201 .Xr getpwent 3 ,
 202 .Xr syslog 3 ,
 203 .Xr nsswitch.conf 5 ,
 204 .Xr passwd 5 ,
 205 .Xr nis 8 ,
 206 .Xr pam 8