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 maximum length of a password supported by the pam_unix module
84 via the helper binary is <emphasis>PAM_MAX_RESP_SIZE</emphasis>
85 - currently 512 bytes. The rest of the password provided by the
86 conversation function to the module will be ignored.
90 The password component of this module performs the task of updating
91 the user's password. The default encryption hash is taken from the
92 <emphasis remap='B'>ENCRYPT_METHOD</emphasis> variable from
93 <emphasis>/etc/login.defs</emphasis>
97 The session component of this module logs when a user logins
102 Remaining arguments, supported by others functions of this
103 module, are silently ignored. Other arguments are logged as
104 errors through <citerefentry>
105 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
110 <refsect1 id="pam_unix-options">
112 <title>OPTIONS</title>
116 <option>debug</option>
120 Turns on debugging via
122 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
130 <option>audit</option>
134 A little more extreme than debug.
141 <option>quiet</option>
145 Turns off informational messages namely messages about
146 session open and close via
148 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
156 <option>nullok</option>
160 The default action of this module is to not permit the
161 user access to a service if their official password is blank.
162 The <option>nullok</option> argument overrides this default.
168 <option>try_first_pass</option>
172 Before prompting the user for their password, the module first
173 tries the previous stacked module's password in case that
174 satisfies this module as well.
180 <option>use_first_pass</option>
184 The argument <option>use_first_pass</option> forces the module
185 to use a previous stacked modules password and will never prompt
186 the user - if no password is available or the password is not
187 appropriate, the user will be denied access.
193 <option>nodelay</option>
197 This argument can be used to discourage the authentication
198 component from requesting a delay should the authentication
199 as a whole fail. The default action is for the module to
200 request a delay-on-failure of the order of two second.
206 <option>use_authtok</option>
210 When password changing enforce the module to set the new
211 password to the one provided by a previously stacked
212 <option>password</option> module (this is used in the
213 example of the stacking of the <command>pam_cracklib</command>
214 module documented below).
220 <option>authtok_type=<replaceable>type</replaceable></option>
224 This argument can be used to modify the password prompt
225 when changing passwords to include the type of the password.
236 NIS RPC is used for setting new passwords.
242 <option>remember=<replaceable>n</replaceable></option>
246 The last <replaceable>n</replaceable> passwords for each
247 user are saved in <filename>/etc/security/opasswd</filename>
248 in order to force password change history and keep the user
249 from alternating between the same password too frequently.
250 The MD5 password hash algorithm is used for storing the
252 Instead of this option the <command>pam_pwhistory</command>
253 module should be used.
259 <option>shadow</option>
263 Try to maintain a shadow based system.
273 When a user changes their password next, encrypt
274 it with the MD5 algorithm.
280 <option>bigcrypt</option>
284 When a user changes their password next,
285 encrypt it with the DEC C2 algorithm.
291 <option>sha256</option>
295 When a user changes their password next,
296 encrypt it with the SHA256 algorithm. If the
297 SHA256 algorithm is not known to the <citerefentry>
298 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
299 </citerefentry> function,
306 <option>sha512</option>
310 When a user changes their password next,
311 encrypt it with the SHA512 algorithm. If the
312 SHA512 algorithm is not known to the <citerefentry>
313 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
314 </citerefentry> function,
321 <option>blowfish</option>
325 When a user changes their password next,
326 encrypt it with the blowfish algorithm. If the
327 blowfish algorithm is not known to the <citerefentry>
328 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
329 </citerefentry> function,
336 <option>gost_yescrypt</option>
340 When a user changes their password next,
341 encrypt it with the gost-yescrypt algorithm. If the
342 gost-yescrypt algorithm is not known to the <citerefentry>
343 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
344 </citerefentry> function,
351 <option>yescrypt</option>
355 When a user changes their password next,
356 encrypt it with the yescrypt algorithm. If the
357 yescrypt algorithm is not known to the <citerefentry>
358 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
359 </citerefentry> function,
366 <option>crypt_default</option>
370 When a user changes their password next,
371 encrypt it with the default algorithm and the default
372 amount of rounds provided by the system configuration
373 of libcrypt. If this default algorithm is not known to
375 <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
376 </citerefentry> function,
383 <option>rounds=<replaceable>n</replaceable></option>
387 Set the optional number of rounds of the SHA256, SHA512,
388 blowfish, gost-yescrypt, and yescrypt password hashing
390 <replaceable>n</replaceable>.
391 This option will be ignored when the crypt_default option
392 is used, as the default algorithm always uses the value
393 from the system configuration of libcrypt.
399 <option>broken_shadow</option>
403 Ignore errors reading shadow information for
404 users in the account management module.
410 <option>minlen=<replaceable>n</replaceable></option>
414 Set a minimum password length of <replaceable>n</replaceable>
415 characters. The max. for DES crypt based passwords are 8
422 <option>no_pass_expiry</option>
426 When set ignore password expiration as defined by the
427 <emphasis>shadow</emphasis> entry of the user. The option has an
428 effect only in case <emphasis>pam_unix</emphasis> was not used
429 for the authentication or it returned authentication failure
430 meaning that other authentication source or method succeeded.
431 The example can be public key authentication in
432 <emphasis>sshd</emphasis>. The module will return
433 <emphasis remap='B'>PAM_SUCCESS</emphasis> instead of eventual
434 <emphasis remap='B'>PAM_NEW_AUTHTOK_REQD</emphasis> or
435 <emphasis remap='B'>PAM_AUTHTOK_EXPIRED</emphasis>.
441 Invalid arguments are logged with <citerefentry>
442 <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
447 <refsect1 id="pam_unix-types">
448 <title>MODULE TYPES PROVIDED</title>
450 All module types (<option>account</option>, <option>auth</option>,
451 <option>password</option> and <option>session</option>) are provided.
455 <refsect1 id='pam_unix-return_values'>
456 <title>RETURN VALUES</title>
459 <term>PAM_IGNORE</term>
469 <refsect1 id='pam_unix-examples'>
470 <title>EXAMPLES</title>
472 An example usage for <filename>/etc/pam.d/login</filename>
475 # Authenticate the user
476 auth required pam_unix.so
477 # Ensure users account and password are still active
478 account required pam_unix.so
479 # Change the user's password, but at first check the strength
480 # with pam_cracklib(8)
481 password required pam_cracklib.so retry=3 minlen=6 difok=3
482 password required pam_unix.so use_authtok nullok md5
483 session required pam_unix.so
488 <refsect1 id='pam_unix-see_also'>
489 <title>SEE ALSO</title>
492 <refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum>
495 <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
498 <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
501 <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
506 <refsect1 id='pam_unix-author'>
507 <title>AUTHOR</title>
509 pam_unix was written by various people.