1 <?xml version="1.0" encoding='UTF-8'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
5 <refentry id="pam_unix">
8 <refentrytitle>pam_unix</refentrytitle>
9 <manvolnum>8</manvolnum>
10 <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
13 <refnamediv id="pam_unix-name">
14 <refname>pam_unix</refname>
15 <refpurpose>Module for traditional password authentication</refpurpose>
19 <cmdsynopsis id="pam_unix-cmdsynopsis">
20 <command>pam_unix.so</command>
27 <refsect1 id="pam_unix-description">
29 <title>DESCRIPTION</title>
32 This is the standard Unix authentication module. It uses standard
33 calls from the system's libraries to retrieve and set account
34 information as well as authentication. Usually this is obtained
35 from the /etc/passwd and the /etc/shadow file as well if shadow is
40 The account component performs the task of establishing the status
41 of the user's account and password based on the following
42 <emphasis>shadow</emphasis> elements: expire, last_change, max_change,
43 min_change, warn_change. In the case of the latter, it may offer advice
44 to the user on changing their password or, through the
45 <emphasis remap='B'>PAM_AUTHTOKEN_REQD</emphasis> return, delay
46 giving service to the user until they have established a new password.
47 The entries listed above are documented in the <citerefentry>
48 <refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum>
49 </citerefentry> manual page. Should the user's record not contain
50 one or more of these entries, the corresponding
51 <emphasis>shadow</emphasis> check is not performed.
55 The authentication component performs the task of checking the
56 users credentials (password). The default action of this module
57 is to not permit the user access to a service if their official
62 A helper binary, <citerefentry>
63 <refentrytitle>unix_chkpwd</refentrytitle><manvolnum>8</manvolnum>
64 </citerefentry>, is provided
65 to check the user's password when it is stored in a read
66 protected database. This binary is very simple and will only
67 check the password of the user invoking it. It is called
68 transparently on behalf of the user by the authenticating
69 component of this module. In this way it is possible
70 for applications like <citerefentry>
71 <refentrytitle>xlock</refentrytitle><manvolnum>1</manvolnum>
72 </citerefentry> to work without
73 being setuid-root. The module, by default, will temporarily turn
74 off SIGCHLD handling for the duration of execution of the helper
75 binary. This is generally the right thing to do, as many applications
76 are not prepared to handle this signal from a child they didn't know
77 was <function>fork()</function>d. The <option>noreap</option> module
78 argument can be used to suppress this temporary shielding and may be
79 needed for use with certain applications.
83 The password component of this module performs the task of updating
88 The session component of this module logs when a user logins
93 Remaining arguments, supported by others functions of this
94 module, are silently ignored. Other arguments are logged as
95 errors through <citerefentry>
96 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
101 <refsect1 id="pam_unix-options">
103 <title>OPTIONS</title>
107 <option>debug</option>
111 Turns on debugging via
113 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
121 <option>audit</option>
125 A little more extreme than debug.
132 <option>nullok</option>
136 The default action of this module is to not permit the
137 user access to a service if their official password is blank.
138 The <option>nullok</option> argument overrides this default.
144 <option>try_first_pass</option>
148 Before prompting the user for their password, the module first
149 tries the previous stacked module's password in case that
150 satisfies this module as well.
156 <option>use_first_pass</option>
160 The argument <option>use_first_pass</option> forces the module
161 to use a previous stacked modules password and will never prompt
162 the user - if no password is available or the password is not
163 appropriate, the user will be denied access.
169 <option>nodelay</option>
173 This argument can be used to discourage the authentication
174 component from requesting a delay should the authentication
175 as a whole fail. The default action is for the module to
176 request a delay-on-failure of the order of two second.
182 <option>use_authtok</option>
186 When password changing enforce the module to set the new
187 password to the one provided by a previously stacked
188 <option>password</option> module (this is used in the
189 example of the stacking of the <command>pam_cracklib</command>
190 module documented below).
196 <option>not_set_pass</option>
200 This argument is used to inform the module that it is not to
201 pay attention to/make available the old or new passwords from/to
202 other (stacked) password modules.
212 NIS RPC is used for setting new passwords.
218 <option>remember=<replaceable>n</replaceable></option>
222 The last <replaceable>n</replaceable> passwords for each
223 user are saved in <filename>/etc/security/opasswd</filename>
224 in order to force password change history and keep the user
225 from alternating between the same password too frequently.
231 <option>shadow</option>
235 Try to maintain a shadow based system.
245 When a user changes their password next, encrypt
246 it with the MD5 algorithm.
252 <option>bigcrypt</option>
256 When a user changes their password next,
257 encrypt it with the DEC C2 algorithm.
263 <option>sha256</option>
267 When a user changes their password next,
268 encrypt it with the SHA256 algorithm. If the
269 SHA256 algorithm is not known to the <citerefentry>
270 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
271 </citerefentry> function,
278 <option>sha512</option>
282 When a user changes their password next,
283 encrypt it with the SHA512 algorithm. If the
284 SHA512 algorithm is not known to the <citerefentry>
285 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
286 </citerefentry> function,
293 <option>blowfish</option>
297 When a user changes their password next,
298 encrypt it with the blowfish algorithm. If the
299 SHA512 algorithm is not known to the <citerefentry>
300 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
301 </citerefentry> function,
308 <option>rounds=<replaceable>n</replaceable></option>
312 Set the optional number of rounds of the SHA256, SHA512
313 and blowfish password hashing algorithms to
314 <replaceable>n</replaceable>.
320 <option>broken_shadow</option>
324 Ignore errors reading shadow inforation for
325 users in the account management module.
331 Invalid arguments are logged with <citerefentry>
332 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
337 <refsect1 id="pam_unix-types">
338 <title>MODULE TYPES PROVIDED</title>
340 All module types (<option>account</option>, <option>auth</option>,
341 <option>password</option> and <option>session</option>) are provided.
345 <refsect1 id='pam_unix-return_values'>
346 <title>RETURN VALUES</title>
349 <term>PAM_IGNORE</term>
359 <refsect1 id='pam_unix-examples'>
360 <title>EXAMPLES</title>
362 An example usage for <filename>/etc/pam.d/login</filename>
365 # Authenticate the user
366 auth required pam_unix.so
367 # Ensure users account and password are still active
368 account required pam_unix.so
369 # Change the users password, but at first check the strength
370 # with pam_cracklib(8)
371 password required pam_cracklib.so retry=3 minlen=6 difok=3
372 password required pam_unix.so use_authtok nullok md5
373 session required pam_unix.so
378 <refsect1 id='pam_unix-see_also'>
379 <title>SEE ALSO</title>
382 <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
385 <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
388 <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
393 <refsect1 id='pam_unix-author'>
394 <title>AUTHOR</title>
396 pam_unix was written by various people.