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_tally">
8 <refentrytitle>pam_tally</refentrytitle>
9 <manvolnum>8</manvolnum>
10 <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
13 <refnamediv id="pam_tally-name">
14 <refname>pam_tally</refname>
15 <refpurpose>The login counter (tallying) module</refpurpose>
19 <cmdsynopsis id="pam_tally-cmdsynopsis1">
20 <command>pam_tally.so</command>
22 file=<replaceable>/path/to/counter</replaceable>
25 onerr=[<replaceable>fail</replaceable>|<replaceable>succeed</replaceable>]
31 even_deny_root_account
34 deny=<replaceable>n</replaceable>
37 lock_time=<replaceable>n</replaceable>
40 unlock_time=<replaceable>n</replaceable>
61 <cmdsynopsis id="pam_tally-cmdsynopsis2">
62 <command>pam_tally</command>
64 --file <replaceable>/path/to/counter</replaceable>
67 --user <replaceable>username</replaceable>
70 --reset[=<replaceable>n</replaceable>]
78 <refsect1 id="pam_tally-description">
80 <title>DESCRIPTION</title>
83 This module maintains a count of attempted accesses, can
84 reset count on success, can deny access if too many attempts fail.
87 pam_tally comes in two parts:
88 <emphasis remap='B'>pam_tally.so</emphasis> and
89 <command>pam_tally</command>. The former is the PAM module and
90 the latter, a stand-alone program. <command>pam_tally</command>
91 is an (optional) application which can be used to interrogate and
92 manipulate the counter file. It can display users' counts, set
93 individual counts, or clear all counts. Setting artificially high
94 counts may be useful for blocking users without changing their
95 passwords. For example, one might find it useful to clear all counts
96 every midnight from a cron job. The
98 <refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
99 </citerefentry> command can be used instead of pam_tally to to
100 maintain the counter file.
103 Normally, failed attempts to access <emphasis>root</emphasis> will
104 <emphasis remap='B'>not</emphasis> cause the root account to become
105 blocked, to prevent denial-of-service: if your users aren't given
106 shell accounts and root may only login via <command>su</command> or
107 at the machine console (not telnet/rsh, etc), this is safe.
111 <refsect1 id="pam_tally-options">
113 <title>OPTIONS</title>
121 This can be used for <emphasis>auth</emphasis> and
122 <emphasis>account</emphasis> module types.
127 <option>onerr=[<replaceable>fail</replaceable>|<replaceable>succeed</replaceable>]</option>
131 If something weird happens (like unable to open the file),
132 return with <errorcode>PAM_SUCCESS</errorcode> if
133 <option>onerr=<replaceable>succeed</replaceable></option>
134 is given, else with the corresponding PAM error code.
140 <option>file=<replaceable>/path/to/counter</replaceable></option>
144 File where to keep counts. Default is
145 <filename>/var/log/faillog</filename>.
151 <option>audit</option>
155 Will log the user name into the system log if the user is not found.
161 <option>silent</option>
165 Don't print informative messages.
171 <option>no_log_info</option>
175 Don't log informative messages via <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
189 Authentication phase first checks if user should be denied
190 access and if not it increments attempted login counter. Then
191 on call to <citerefentry>
192 <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
193 </citerefentry> it resets the attempts counter.
198 <option>deny=<replaceable>n</replaceable></option>
202 Deny access if tally for this user exceeds
203 <replaceable>n</replaceable>.
209 <option>lock_time=<replaceable>n</replaceable></option>
213 Always deny for <replaceable>n</replaceable> seconds
214 after failed attempt.
220 <option>unlock_time=<replaceable>n</replaceable></option>
224 Allow access after <replaceable>n</replaceable> seconds
225 after failed attempt. If this option is used the user will
226 be locked out for the specified amount of time after he
227 exceeded his maximum allowed attempts. Otherwise the
228 account is locked until the lock is removed by a manual
229 intervention of the system administrator.
235 <option>magic_root</option>
239 If the module is invoked by a user with uid=0 the
240 counter is not incremented. The sysadmin should use this
241 for user launched services, like <command>su</command>,
242 otherwise this argument should be omitted.
248 <option>no_lock_time</option>
252 Do not use the .fail_locktime field in
253 <filename>/var/log/faillog</filename> for this user.
259 <option>no_reset</option>
263 Don't reset count on successful entry, only decrement.
269 <option>even_deny_root_account</option>
273 Root account can become unavailable.
279 <option>per_user</option>
283 If <filename>/var/log/faillog</filename> contains a non-zero
284 .fail_max/.fail_locktime field for this user then use it
285 instead of <option>deny=<replaceable>n</replaceable></option>/
286 <option>lock_time=<replaceable>n</replaceable></option> parameter.
292 <option>no_lock_time</option>
296 Don't use .fail_locktime filed in
297 <filename>/var/log/faillog</filename> for this user.
313 Account phase resets attempts counter if the user is
314 <emphasis remap='B'>not</emphasis> magic root.
315 This phase can be used optionally for services which don't call
317 <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
318 </citerefentry> correctly or if the reset should be done regardless
319 of the failure of the account phase of other modules.
324 <option>magic_root</option>
328 If the module is invoked by a user with uid=0 the
329 counter is not incremented. The sysadmin should use this
330 for user launched services, like <command>su</command>,
331 otherwise this argument should be omitted.
337 <option>no_reset</option>
341 Don't reset count on successful entry, only decrement.
351 <refsect1 id="pam_tally-types">
352 <title>MODULE TYPES PROVIDED</title>
354 The <option>auth</option> and <option>account</option>
355 module types are provided.
359 <refsect1 id='pam_tally-return_values'>
360 <title>RETURN VALUES</title>
363 <term>PAM_AUTH_ERR</term>
366 A invalid option was given, the module was not able
367 to retrieve the user name, no valid counter file
368 was found, or too many failed logins.
373 <term>PAM_SUCCESS</term>
376 Everything was successful.
381 <term>PAM_USER_UNKNOWN</term>
391 <refsect1 id='pam_tally-examples'>
392 <title>EXAMPLES</title>
394 Add the following line to <filename>/etc/pam.d/login</filename> to
395 lock the account after too many failed logins. The number of
396 allowed fails is specified by <filename>/var/log/faillog</filename>
397 and needs to be set with pam_tally or <citerefentry>
398 <refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
399 </citerefentry> before.
402 auth required pam_securetty.so
403 auth required pam_tally.so per_user
404 auth required pam_env.so
405 auth required pam_unix.so
406 auth required pam_nologin.so
407 account required pam_unix.so
408 password required pam_unix.so
409 session required pam_limits.so
410 session required pam_unix.so
411 session required pam_lastlog.so nowtmp
412 session optional pam_mail.so standard
416 <refsect1 id="pam_tally-files">
420 <term><filename>/var/log/faillog</filename></term>
422 <para>failure logging file</para>
428 <refsect1 id='pam_tally-see_also'>
429 <title>SEE ALSO</title>
432 <refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
435 <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
438 <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
441 <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
446 <refsect1 id='pam_tally-author'>
447 <title>AUTHOR</title>
449 pam_tally was written by Tim Baverstock and Tomas Mraz.