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

   1 SUMMARY:
   2   pam_tally:
   3
   4         Maintains a count of attempted accesses, can reset count on success,
   5                 can deny access if too many attempts fail.
   6
   7         Options:
   8
   9                 * onerr=[succeed|fail] (if something weird happens
  10                         such as unable to open the file, what to do?)
  11                 * file=/where/to/keep/counts (default /var/log/faillog)
  12
  13         (auth)
  14             Authentication phase increments attempted login counter.
  15                 * no_magic_root (root DOES increment counter. Use for
  16                         daemon-based stuff, like telnet/rsh/login)
  17
  18         (account)
  19             Account phase can deny access and/or reset attempts counter.
  20                 * deny=n (deny access if tally for this user exceeds n;
  21                         The presence of deny=n changes the default for
  22                         reset/no_reset to reset, unless the user trying to
  23                         gain access is root and the no_magic_root option
  24                         has NOT been specified.)
  25
  26                 * no_magic_root (access attempts by root DON'T ignore deny.
  27                         Use this for daemon-based stuff, like telnet/rsh/login)
  28                 * even_deny_root_account (Root can become unavailable. BEWARE.
  29                         Note that magic root trying to gain root bypasses this,
  30                         but normal users can be locked out.)
  31
  32                 * reset (reset count to 0 on successful entry, even for
  33                         magic root)
  34                 * no_reset (don't reset count on successful entry)
  35                         This is the default unless deny exists and the
  36                         user attempting access is NOT magic root.
  37
  38                 * per_user (If /var/log/faillog contains a non-zero
  39                         .fail_max field for this user then use it
  40                         instead of deny=n parameter)
  41
  42                 * no_lock_time (Don't use .fail_locktime filed in
  43                         /var/log/faillog for this user)
  44
  45         Also checks to make sure that the counts file is a plain
  46         file and not world writable.
  47
  48         - Tim Baverstock <warwick@sable.demon.co.uk>, v0.1 5 March 1997
  49
  50 LONGER:
  51
  52 pam_tally comes in two parts: pam_tally.so and pam_tally.
  53
  54 pam_tally.so sits in a pam config file, in the auth and account sections.
  55
  56 In the auth section, it increments a per-uid counter for each attempted
  57 login, in the account section, it denies access if attempted logins
  58 exceed some threashold and/or resets that counter to zero on successful
  59 login.
  60
  61 Root is treated specially:
  62
  63 1. When a process already running as root tries to access some service, the
  64 access is `magic', and bypasses pam_tally's checks: handy for `su'ing from
  65 root into an account otherwise blocked. However, for services like telnet or
  66 login which always effectively run from the root account, root (ie everyone)
  67 shouldn't be granted this magic status, and the flag `no_magic_root' should
  68 be set in this situation, as noted in the summary above.  [This option may
  69 be obsolete, with `sufficient root' processing.]
  70
  71 2. Normally, failed attempts to access root will NOT cause the root
  72 account to become blocked, to prevent denial-of-service: if your users aren't
  73 given shell accounts and root may only login via `su' or at the machine
  74 console (not telnet/rsh, etc), this is safe. If you really want root to be
  75 blocked for some given service, use even_deny_root_account.
  76
  77 pam_tally is an (optional) application which can be used to interrogate and
  78 manipulate the counter file. It can display users' counts, set individual
  79 counts, or clear all counts. Setting artificially high counts may be useful
  80 for blocking users without changing their passwords. I found it useful to
  81 clear all counts every midnight from a cron..
  82
  83 The counts file is organised as a binary-word array, indexed by uid. You
  84 can probably make sense of it with `od', if you don't want to use the
  85 supplied application.
  86
  87 BUGS:
  88
  89 pam_tally is very dependant on getpw*(): a database of usernames
  90 would be much more flexible.
  91
  92 The (4.0 Redhat) utilities seem to do funny things with uid, and I'm
  93 not wholly sure I understood what I should have been doing anyway so
  94 the `keep a count of current logins' bit has been #ifdef'd out and you
  95 can only reset the counter on successful authentication, for now.