contrib/libpam/doc/modules/pam_tally.sgml

   1 <!--
   2
   3    $Id: pam_tally.sgml,v 1.1 2001/02/11 07:52:56 agmorgan Exp $
   4
   5    This template file was written by Andrew G. Morgan <morgan@kernel.org>
   6    adapted from text provided by Tim Baverstock.
   7 -->
   8
   9 <sect1>The login counter (tallying) module
  10
  11 <sect2>Synopsis
  12
  13 <p>
  14 <descrip>
  15
  16 <tag><bf>Module Name:</bf></tag>
  17 pam_tally
  18
  19 <tag><bf>Author[s]:</bf></tag>
  20 Tim Baverstock
  21
  22 <tag><bf>Maintainer:</bf></tag>
  23
  24 <tag><bf>Management groups provided:</bf></tag>
  25 auth; account
  26
  27 <tag><bf>Cryptographically sensitive:</bf></tag>
  28
  29 <tag><bf>Security rating:</bf></tag>
  30
  31 <tag><bf>Clean code base:</bf></tag>
  32
  33 <tag><bf>System dependencies:</bf></tag>
  34 A faillog file (default location /var/log/faillog)
  35
  36 <tag><bf>Network aware:</bf></tag>
  37
  38 </descrip>
  39
  40 <sect2>Overview of module
  41
  42 <p>
  43 This module maintains a count of attempted accesses, can reset count
  44 on success, can deny access if too many attempts fail.
  45
  46 <p>
  47 pam_tally comes in two parts: <tt>pam_tally.so</tt> and
  48 <tt>pam_tally</tt>. The former is the PAM module and the latter, a
  49 stand-alone program. <tt>pam_tally</tt> is an (optional) application
  50 which can be used to interrogate and manipulate the counter file. It
  51 can display users' counts, set individual counts, or clear all
  52 counts. Setting artificially high counts may be useful for blocking
  53 users without changing their passwords. For example, one might find it
  54 useful to clear all counts every midnight from a cron job.
  55
  56 <p>
  57 The counts file is organized as a binary-word array, indexed by
  58 uid. You can probably make sense of it with <tt>od</tt>, if you don't
  59 want to use the supplied appliction.
  60
  61 <p>
  62 Note, there are some outstanding issues with this module:
  63 <tt>pam_tally</tt> is very dependant on <tt>getpw*()</tt> - a database
  64 of usernames would be much more flexible; the `keep a count of current
  65 logins' bit has been <tt>#ifdef</tt>'d out and you can only reset the
  66 counter on successful authentication, for now.
  67
  68 <sect3>Generic options accepted by both components
  69 <p>
  70 <itemize>
  71 <item> <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>):
  72    if something weird happens, such as unable to open the file, how
  73    should the module react?
  74 <item> <tt>file=</tt><em>/where/to/keep/counts</em>:
  75    specify the file location for the counts.
  76    The default location is <tt>/var/log/faillog</tt>.
  77 </itemize>
  78
  79 <sect2>Authentication component
  80
  81 <p>
  82 <descrip>
  83
  84 <tag><bf>Recognized arguments:</bf></tag>
  85 <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
  86 <tt>file=</tt>/where/to/keep/counts;
  87 <tt>no_magic_root</tt>
  88
  89 <tag><bf>Description:</bf></tag>
  90
  91 <p>
  92 The authentication component of this module increments the attempted
  93 login counter.
  94
  95 <p>
  96 <tag><bf>Examples/suggested usage:</bf></tag>
  97
  98 <p>
  99 The module argument <tt>no_magic_root</tt> is used to indicate that if
 100 the module is invoked by a user with uid=0, then the counter is
 101 incremented. The sys-admin should use this for daemon-launched
 102 services, like <tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>. For user
 103 launched services, like <tt>su</tt>, this argument should be omitted.
 104
 105 <p>
 106 By way of more explanation, when a process already running as root
 107 tries to access some service, the access is <em>magic</em>, and
 108 bypasses <tt>pam_tally</tt>'s checks: this is handy for <tt>su</tt>ing
 109 from root into an account otherwise blocked. However, for services
 110 like <tt>telnet</tt> or <tt>login</tt>, which always effectively run
 111 from the root account, root (ie everyone) shouldn't be granted this
 112 magic status, and the flag `no_magic_root' should be set in this
 113 situation, as noted in the summary above.
 114
 115 </descrip>
 116
 117 <sect2>Account component
 118
 119 <p>
 120 <descrip>
 121
 122 <tag><bf>Recognized arguments:</bf></tag>
 123 <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
 124 <tt>file=</tt>/where/to/keep/counts;
 125 <tt>deny=</tt><em>n</em>;
 126 <tt>no_magic_root</tt>;
 127 <tt>even_deny_root_account</tt>;
 128 <tt>reset</tt>;
 129 <tt>no_reset</tt>;
 130 <tt>per_user</tt>;
 131 <tt>no_lock_time</tt>
 132
 133 <tag><bf>Description:</bf></tag>
 134
 135 <p>
 136 The account component can deny access and/or reset the attempts
 137 counter. It also checks to make sure that the counts file is a plain
 138 file and not world writable.
 139
 140 <tag><bf>Examples/suggested usage:</bf></tag>
 141
 142 <p>
 143 The <tt>deny=</tt><em>n</em> option is used to deny access if tally
 144 for this user exceeds <em>n</em>. The presence of
 145 <tt>deny=</tt><em>n</em> changes the default for
 146 <tt>reset</tt>/<tt>no_reset</tt> to <tt>reset</tt>, unless the user
 147 trying to gain access is root and the <tt>no_magic_root</tt> option
 148 has NOT been specified.
 149
 150 <p>
 151 The <tt>no_magic_root</tt> option ensures that access attempts by root
 152 DON'T ignore deny.  Use this for daemon-based stuff, like
 153 <tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>.
 154
 155 <p>
 156 The <tt>even_deny_root_account</tt> option is used to ensure that the
 157 root account can become unavailable. <bf>Note</bf> that magic root
 158 trying to gain root bypasses this, but normal users can be locked out.
 159
 160 <p>
 161 The <tt>reset</tt> option instructs the module to reset count to 0 on
 162 successful entry, even for magic root. The <tt>no_reset</tt> option is
 163 used to instruct the module to not reset the count on successful
 164 entry.  This is the default unless <tt>deny</tt> exists and the user
 165 attempting access is NOT magic root.
 166
 167 <p>
 168 If <tt>/var/log/faillog</tt> contains a non-zero <tt>.fail_max</tt>
 169 field for this user then the <tt>per_user</tt> module argument will
 170 ensure that the module uses this value and not the global
 171 <tt>deny=</tt><em>n</em> parameter.
 172
 173 <p>
 174 The <tt>no_lock_time</tt> option is for ensuring that the module does
 175 not use the <tt>.fail_locktime</tt> field in /var/log/faillog for this
 176 user.
 177
 178 <p>
 179 Normally, failed attempts to access root will <bf>NOT</bf> cause the
 180 root account to become blocked, to prevent denial-of-service: if your
 181 users aren't given shell accounts and root may only login via
 182 <tt>su</tt> or at the machine console (not
 183 <tt>telnet</tt>/<tt>rsh</tt>, etc), this is safe. If you really want
 184 root to be blocked for some given service, use
 185 <tt>even_deny_root_account</tt>.
 186
 187 </descrip>
 188
 189 <!--
 190 End of sgml insert for this module.
 191 -->