granicus.if.org Git - linux-pam/blob - modules/pam_tally/pam_tally.8.xml

   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">
   4
   5 <refentry id="pam_tally">
   6
   7   <refmeta>
   8     <refentrytitle>pam_tally</refentrytitle>
   9     <manvolnum>8</manvolnum>
  10     <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_tally-name">
  14     <refname>pam_tally</refname>
  15     <refpurpose>The login counter (tallying) module</refpurpose>
  16   </refnamediv>
  17
  18   <refsynopsisdiv>
  19     <cmdsynopsis id="pam_tally-cmdsynopsis1">
  20       <command>pam_tally.so</command>
  21       <arg choice="opt">
  22         file=<replaceable>/path/to/counter</replaceable>
  23       </arg>
  24       <arg choice="opt">
  25         onerr=[<replaceable>fail</replaceable>|<replaceable>succeed</replaceable>]
  26       </arg>
  27       <arg choice="opt">
  28         magic_root
  29       </arg>
  30       <arg choice="opt">
  31         even_deny_root_account
  32       </arg>
  33       <arg choice="opt">
  34         deny=<replaceable>n</replaceable>
  35       </arg>
  36       <arg choice="opt">
  37         lock_time=<replaceable>n</replaceable>
  38       </arg>
  39       <arg choice="opt">
  40         unlock_time=<replaceable>n</replaceable>
  41       </arg>
  42       <arg choice="opt">
  43         per_user
  44       </arg>
  45       <arg choice="opt">
  46         no_lock_time
  47       </arg>
  48       <arg choice="opt">
  49         no_reset
  50       </arg>
  51       <arg choice="opt">
  52         audit
  53       </arg>
  54       <arg choice="opt">
  55         silent
  56       </arg>
  57       <arg choice="opt">
  58         no_log_info
  59       </arg>
  60     </cmdsynopsis>
  61     <cmdsynopsis id="pam_tally-cmdsynopsis2">
  62       <command>pam_tally</command>
  63       <arg choice="opt">
  64         --file <replaceable>/path/to/counter</replaceable>
  65       </arg>
  66       <arg choice="opt">
  67         --user <replaceable>username</replaceable>
  68       </arg>
  69       <arg choice="opt">
  70         --reset[=<replaceable>n</replaceable>]
  71       </arg>
  72       <arg choice="opt">
  73         --quiet
  74       </arg>
  75     </cmdsynopsis>
  76   </refsynopsisdiv>
  77
  78   <refsect1 id="pam_tally-description">
  79
  80     <title>DESCRIPTION</title>
  81
  82     <para>
  83       This module maintains a count of attempted accesses, can
  84       reset count on success, can deny access if too many attempts
  85       fail.
  86     </para>
  87     <para>
  88       pam_tally has several limitations, which are solved with
  89       pam_tally2. For this reason pam_tally is deprecated and
  90       will be removed in a future release.
  91     </para>
  92     <para>
  93       pam_tally comes in two parts:
  94       <emphasis remap='B'>pam_tally.so</emphasis> and
  95       <command>pam_tally</command>. The former is the PAM module and
  96       the latter, a stand-alone program. <command>pam_tally</command>
  97       is an (optional) application which can be used to interrogate and
  98       manipulate the counter file. It can display users' counts, set
  99       individual counts, or clear all counts. Setting artificially high
 100       counts may be useful for blocking users without changing their
 101       passwords. For example, one might find it useful to clear all counts
 102       every midnight from a cron job. The
 103       <citerefentry>
 104         <refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
 105       </citerefentry> command can be used instead of pam_tally to to
 106       maintain the counter file.
 107     </para>
 108     <para>
 109       Normally, failed attempts to access <emphasis>root</emphasis> will
 110       <emphasis remap='B'>not</emphasis> cause the root account to become
 111       blocked, to prevent denial-of-service: if your users aren't given
 112       shell accounts and root may only login via <command>su</command> or
 113       at the machine console (not telnet/rsh, etc), this is safe.
 114     </para>
 115   </refsect1>
 116
 117   <refsect1 id="pam_tally-options">
 118
 119     <title>OPTIONS</title>
 120     <variablelist>
 121       <varlistentry>
 122         <term>
 123           GLOBAL OPTIONS
 124         </term>
 125         <listitem>
 126           <para>
 127             This can be used for <emphasis>auth</emphasis> and
 128             <emphasis>account</emphasis> module types.
 129           </para>
 130           <variablelist>
 131             <varlistentry>
 132               <term>
 133                 <option>onerr=[<replaceable>fail</replaceable>|<replaceable>succeed</replaceable>]</option>
 134               </term>
 135               <listitem>
 136                 <para>
 137                   If something weird happens (like unable to open the file),
 138                   return with <errorcode>PAM_SUCCESS</errorcode> if
 139                   <option>onerr=<replaceable>succeed</replaceable></option>
 140                   is given, else with the corresponding PAM error code.
 141                 </para>
 142               </listitem>
 143             </varlistentry>
 144             <varlistentry>
 145               <term>
 146                 <option>file=<replaceable>/path/to/counter</replaceable></option>
 147               </term>
 148               <listitem>
 149                 <para>
 150                   File where to keep counts. Default is
 151                   <filename>/var/log/faillog</filename>.
 152                 </para>
 153               </listitem>
 154             </varlistentry>
 155             <varlistentry>
 156               <term>
 157                 <option>audit</option>
 158               </term>
 159               <listitem>
 160                 <para>
 161                   Will log the user name into the system log if the user is not found.
 162                 </para>
 163               </listitem>
 164             </varlistentry>
 165             <varlistentry>
 166               <term>
 167                 <option>silent</option>
 168               </term>
 169               <listitem>
 170                 <para>
 171                   Don't print informative messages.
 172                 </para>
 173               </listitem>
 174             </varlistentry>
 175             <varlistentry>
 176               <term>
 177                 <option>no_log_info</option>
 178               </term>
 179               <listitem>
 180                 <para>
 181                   Don't log informative messages via <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 182                 </para>
 183               </listitem>
 184             </varlistentry>
 185           </variablelist>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term>
 191           AUTH OPTIONS
 192         </term>
 193         <listitem>
 194           <para>
 195             Authentication phase first checks if user should be denied
 196             access and if not it increments attempted login counter. Then
 197             on call to <citerefentry>
 198               <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
 199             </citerefentry> it resets the attempts counter.
 200           </para>
 201           <variablelist>
 202             <varlistentry>
 203               <term>
 204                 <option>deny=<replaceable>n</replaceable></option>
 205               </term>
 206               <listitem>
 207                 <para>
 208                   Deny access if tally for this user exceeds
 209                   <replaceable>n</replaceable>.
 210                 </para>
 211               </listitem>
 212             </varlistentry>
 213             <varlistentry>
 214               <term>
 215                 <option>lock_time=<replaceable>n</replaceable></option>
 216               </term>
 217               <listitem>
 218                 <para>
 219                   Always deny for <replaceable>n</replaceable> seconds
 220                   after failed attempt.
 221                 </para>
 222               </listitem>
 223             </varlistentry>
 224             <varlistentry>
 225               <term>
 226                 <option>unlock_time=<replaceable>n</replaceable></option>
 227               </term>
 228               <listitem>
 229                 <para>
 230                   Allow access after <replaceable>n</replaceable> seconds
 231                   after failed attempt. If this option is used the user will
 232                   be locked out for the specified amount of time after he
 233                   exceeded his maximum allowed attempts. Otherwise the
 234                   account is locked until the lock is removed by a manual
 235                   intervention of the system administrator.
 236                 </para>
 237               </listitem>
 238             </varlistentry>
 239             <varlistentry>
 240               <term>
 241                 <option>magic_root</option>
 242               </term>
 243               <listitem>
 244                 <para>
 245                   If the module is invoked by a user with uid=0 the
 246                   counter is not incremented. The sysadmin should use this
 247                   for user launched services, like <command>su</command>,
 248                   otherwise this argument should be omitted.
 249                 </para>
 250               </listitem>
 251             </varlistentry>
 252             <varlistentry>
 253               <term>
 254                 <option>no_lock_time</option>
 255               </term>
 256               <listitem>
 257                 <para>
 258                   Do not use the .fail_locktime field in
 259                   <filename>/var/log/faillog</filename> for this user.
 260                 </para>
 261               </listitem>
 262             </varlistentry>
 263             <varlistentry>
 264               <term>
 265                 <option>no_reset</option>
 266               </term>
 267               <listitem>
 268                 <para>
 269                   Don't reset count on successful entry, only decrement.
 270                 </para>
 271               </listitem>
 272             </varlistentry>
 273             <varlistentry>
 274               <term>
 275                 <option>even_deny_root_account</option>
 276               </term>
 277               <listitem>
 278                 <para>
 279                   Root account can become unavailable.
 280                 </para>
 281               </listitem>
 282             </varlistentry>
 283             <varlistentry>
 284               <term>
 285                 <option>per_user</option>
 286               </term>
 287               <listitem>
 288                 <para>
 289                   If <filename>/var/log/faillog</filename> contains a non-zero
 290                   .fail_max/.fail_locktime field for this user then use it
 291                   instead of <option>deny=<replaceable>n</replaceable></option>/
 292                   <option>lock_time=<replaceable>n</replaceable></option> parameter.
 293                 </para>
 294               </listitem>
 295             </varlistentry>
 296             <varlistentry>
 297               <term>
 298                 <option>no_lock_time</option>
 299               </term>
 300               <listitem>
 301                 <para>
 302                   Don't use .fail_locktime filed in
 303                   <filename>/var/log/faillog</filename> for this user.
 304                 </para>
 305               </listitem>
 306             </varlistentry>
 307
 308           </variablelist>
 309         </listitem>
 310       </varlistentry>
 311
 312
 313       <varlistentry>
 314         <term>
 315           ACCOUNT OPTIONS
 316         </term>
 317         <listitem>
 318           <para>
 319             Account phase resets attempts counter if the user is
 320             <emphasis remap='B'>not</emphasis> magic root.
 321             This phase can be used optionally for services which don't call
 322             <citerefentry>
 323               <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
 324             </citerefentry> correctly or if the reset should be done regardless
 325             of the failure of the account phase of other modules.
 326           </para>
 327           <variablelist>
 328             <varlistentry>
 329               <term>
 330                 <option>magic_root</option>
 331               </term>
 332               <listitem>
 333                 <para>
 334                   If the module is invoked by a user with uid=0 the
 335                   counter is not incremented. The sysadmin should use this
 336                   for user launched services, like <command>su</command>,
 337                   otherwise this argument should be omitted.
 338                 </para>
 339               </listitem>
 340             </varlistentry>
 341             <varlistentry>
 342               <term>
 343                 <option>no_reset</option>
 344               </term>
 345               <listitem>
 346                 <para>
 347                   Don't reset count on successful entry, only decrement.
 348                 </para>
 349               </listitem>
 350             </varlistentry>
 351           </variablelist>
 352         </listitem>
 353       </varlistentry>
 354     </variablelist>
 355   </refsect1>
 356
 357   <refsect1 id="pam_tally-types">
 358     <title>MODULE TYPES PROVIDED</title>
 359     <para>
 360       The <option>auth</option> and <option>account</option>
 361       module types are provided.
 362     </para>
 363   </refsect1>
 364
 365   <refsect1 id='pam_tally-return_values'>
 366     <title>RETURN VALUES</title>
 367     <variablelist>
 368       <varlistentry>
 369         <term>PAM_AUTH_ERR</term>
 370         <listitem>
 371           <para>
 372             A invalid option was given, the module was not able
 373             to retrieve the user name, no valid counter file
 374             was found, or too many failed logins.
 375           </para>
 376         </listitem>
 377       </varlistentry>
 378       <varlistentry>
 379         <term>PAM_SUCCESS</term>
 380         <listitem>
 381           <para>
 382             Everything was successful.
 383           </para>
 384         </listitem>
 385       </varlistentry>
 386       <varlistentry>
 387         <term>PAM_USER_UNKNOWN</term>
 388         <listitem>
 389           <para>
 390             User not known.
 391           </para>
 392         </listitem>
 393       </varlistentry>
 394     </variablelist>
 395   </refsect1>
 396
 397   <refsect1 id='pam_tally-examples'>
 398     <title>EXAMPLES</title>
 399     <para>
 400       Add the following line to <filename>/etc/pam.d/login</filename> to
 401       lock the account after too many failed logins. The number of
 402       allowed fails is specified by <filename>/var/log/faillog</filename>
 403       and needs to be set with pam_tally or <citerefentry>
 404         <refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
 405       </citerefentry> before.
 406     </para>
 407     <programlisting>
 408 auth     required       pam_securetty.so
 409 auth     required       pam_tally.so per_user
 410 auth     required       pam_env.so
 411 auth     required       pam_unix.so
 412 auth     required       pam_nologin.so
 413 account  required       pam_unix.so
 414 password required       pam_unix.so
 415 session  required       pam_limits.so
 416 session  required       pam_unix.so
 417 session  required       pam_lastlog.so nowtmp
 418 session  optional       pam_mail.so standard
 419     </programlisting>
 420   </refsect1>
 421
 422   <refsect1 id="pam_tally-files">
 423     <title>FILES</title>
 424     <variablelist>
 425       <varlistentry>
 426         <term><filename>/var/log/faillog</filename></term>
 427         <listitem>
 428           <para>failure logging file</para>
 429         </listitem>
 430       </varlistentry>
 431     </variablelist>
 432   </refsect1>
 433
 434   <refsect1 id='pam_tally-see_also'>
 435     <title>SEE ALSO</title>
 436     <para>
 437       <citerefentry>
 438         <refentrytitle>faillog</refentrytitle><manvolnum>8</manvolnum>
 439       </citerefentry>,
 440       <citerefentry>
 441         <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
 442       </citerefentry>,
 443       <citerefentry>
 444         <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
 445       </citerefentry>,
 446       <citerefentry>
 447         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 448       </citerefentry>
 449     </para>
 450   </refsect1>
 451
 452   <refsect1 id='pam_tally-author'>
 453     <title>AUTHOR</title>
 454       <para>
 455         pam_tally was written by Tim Baverstock and Tomas Mraz.
 456       </para>
 457   </refsect1>
 458
 459 </refentry>