SUMMARY:
  pam_tally.so:

        Maintains a count of attempted accesses, can reset count on success,
                can deny access if too many attempts fail.

        Options:

                * onerr=[succeed|fail] (if something weird happens
                        such as unable to open the file, what to do?)
                * file=/where/to/keep/counts (default /var/log/faillog)
		* audit (will display the username typed if the user is not found)

        (auth)
            Authentication phase first checks if user should be denied access
	    and if not it increments attempted login counter. Then on call to
	    pam_setcred it resets the attempts counter if the user is NOT
	    magic root.
                * deny=n (deny access if tally for this user exceeds n)
		
		* lock_time=n (always deny for n seconds after failed attempt)
		
		* unlock_time=n (allow access after n seconds after the last
		        failed attempt with exceeded tally)
                
                * magic_root (access attempts by root as requesting user ignore
			deny and don't change counter.
                        Use this for su and similar services.)

                * even_deny_root_account (Root can become unavailable. BEWARE.
                        Note that magic root trying to gain root bypasses this,
                        but normal users can be locked out.)
                
		* per_user (If /var/log/faillog contains a non-zero
			.fail_max/.fail_locktime field for this user then use it
			instead of deny=n/lock_time=n parameter.)

		* no_lock_time (Don't use .fail_locktime filed in
			/var/log/faillog for this user)

                * no_reset (don't reset count on successful entry,
		        only decrement)

                
        (account)
            Account phase resets attempts counter if the user is NOT magic root.
	    This phase can be used optionaly for services which don't call
	    pam_setcred correctly or if the reset should be done regardless
	    of the failure of the account phase of other modules.
	    
                * magic_root (access attempts by root as requesting user 
			don't change counter.
                        Use this for su and similar services.)

                * no_reset (don't reset count on successful entry,
		        only decrement)

        Also checks to make sure that the counts file is a plain
        file and not world writable.

        - Tim Baverstock <warwick@sable.demon.co.uk>, v0.1 5 March 1997
	- Tomas Mraz <tmraz@redhat.com>, v0.2 5 January 2005

LONGER:

pam_tally comes in two parts: pam_tally.so and pam_tally.

pam_tally.so sits in a pam config file, in the auth and account sections.

In the auth section, it denies access if attempted logins exceed some
threshold and it increments a per-uid counter for each attempted login,
in the account section, it resets that counter to zero on successful
login. If the module isn't used in the account section it resets the counter
to zero on call to pam_setcred.

Root is treated specially:

1. When a process already running as root tries to access some service and the
'magic_root' flag is set, the access is `magic', and bypasses pam_tally's 
checks: handy for `su'ing from root into an account otherwise blocked.
NOTE: This was changed from the previous version of pam_tally where the default
was to treat root as magic and there were the 'no_magic_root' flag. However
for most of services the current default make sense.

2. Normally, failed attempts to access root will NOT cause the root 
account to become blocked, to prevent denial-of-service: if your users aren't 
given shell accounts and root may only login via `su' or at the machine 
console (not telnet/rsh, etc), this is safe. If you really want root to be
blocked for some given service, use even_deny_root_account.

pam_tally is an (optional) application which can be used to interrogate and 
manipulate the counter file. It can display users' counts, set individual 
counts, or clear all counts. Setting artificially high counts may be useful 
for blocking users without changing their passwords. I found it useful to 
clear all counts every midnight from a cron..

The counts file is organised as a binary-word array, indexed by uid. You
can probably make sense of it with `od', if you don't want to use the
supplied application.

BUGS:

pam_tally is very dependant on getpw*(): a database of usernames
would be much more flexible.

The (4.0 Redhat) utilities seem to do funny things with uid, and I'm
not wholly sure I understood what I should have been doing anyway so
the `keep a count of current logins' bit has been #ifdef'd out and you
can only reset the counter on successful authentication, for now.

IMPORTANT NOTICE:
In the original version of pam_tally there was a bug where the information
if the password was correct or not was leaked by returning error from
different pam management phases. This was solved by moving the denying
functionality to the auth phase. However it's necessary to update the pam
configuration by moving the required options (as deny=N) to the auth phase.