SUMMARY:
  pam_tally2.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? Default
			is to fail.)
			
                * file=/where/to/keep/counts (default /var/log/tallylog)
		
		* audit (Will put the username typed if the user is not
			found into the syslog entry.)

        (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 (Deny access for n seconds after every 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 (Root can become unavailable. BEWARE.
                        Note that magic root trying to gain root bypasses this,
                        but normal users can be locked out.)
                
                * root_unlock_time=n (Implies even_deny_root. Same as unlock_time,
			affects only root account.)
                
		* quiet (Don't tell user that the fail count was exceeded.)

		* serialize (Serialize access to the tally file using locks.
			This option might be used only for non-multithreaded
			services because it depends on the fcntl locking of
			the tally file. Also it is a good idea to use
			this option only in such configurations where the time
			between auth phase and account or setcred phase is not
			dependent on the authenticating client. Otherwise the
			authenticating client will be able to prevent
			simultaneous authentications by the same user by
			simply artificially prolonging the time the file
			record lock is held.)

        (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.)

        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 January 2005, v2 January 2006

LONGER:

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

pam_tally2.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 first 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_tally2 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. For example it may be
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_tally2 is not compatible with the old pam_tally faillog file format.

There is no setuid wrapper for access to the data file such as when the
pam_tally2 module is called from xscreensaver. As this would make it
impossible to share PAM configuration with such services the following
workaround is used: If the data file cannot be opened because of insufficient
permissions (EPERM) the module returns PAM_IGNORE.

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.

The pam_tally was also incompatible between 32bit and 64bit versions because
the faillog format was architecture dependent. The new pam_tally2 uses a new
data file format and thus the file was renamed to /var/log/tallylog.