5 This template file was written by Andrew G. Morgan <morgan@kernel.org>
6 adapted from text provided by Tim Baverstock.
9 <sect1>The login counter (tallying) module
16 <tag><bf>Module Name:</bf></tag>
19 <tag><bf>Author[s]:</bf></tag>
23 <tag><bf>Maintainer:</bf></tag>
25 <tag><bf>Management groups provided:</bf></tag>
28 <tag><bf>Cryptographically sensitive:</bf></tag>
30 <tag><bf>Security rating:</bf></tag>
32 <tag><bf>Clean code base:</bf></tag>
34 <tag><bf>System dependencies:</bf></tag>
35 A faillog file (default location /var/log/faillog)
37 <tag><bf>Network aware:</bf></tag>
41 <sect2>Overview of module
44 This module maintains a count of attempted accesses, can reset count
45 on success, can deny access if too many attempts fail.
48 pam_tally comes in two parts: <tt>pam_tally.so</tt> and
49 <tt>pam_tally</tt>. The former is the PAM module and the latter, a
50 stand-alone program. <tt>pam_tally</tt> is an (optional) application
51 which can be used to interrogate and manipulate the counter file. It
52 can display users' counts, set individual counts, or clear all
53 counts. Setting artificially high counts may be useful for blocking
54 users without changing their passwords. For example, one might find it
55 useful to clear all counts every midnight from a cron job.
58 The counts file is organized as a binary-word array, indexed by
59 uid. You can probably make sense of it with <tt>od</tt>, if you don't
60 want to use the supplied appliction.
63 Note, there are some outstanding issues with this module:
64 <tt>pam_tally</tt> is very dependant on <tt>getpw*()</tt> - a database
65 of usernames would be much more flexible
67 <sect3>Generic options accepted by both components
70 <item> <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>):
71 if something weird happens, such as unable to open the file, how
72 should the module react?
73 <item> <tt>file=</tt><em>/where/to/keep/counts</em>:
74 specify the file location for the counts.
75 The default location is <tt>/var/log/faillog</tt>.
76 <item> <tt>audit</tt>:
77 display the username typed if the user is not found. It may be
78 useful for scripts, but you should know users often type their
79 password instead making your system weaker. Activate it only if you
80 know what you are doing.
83 <sect2>Authentication component
88 <tag><bf>Recognized arguments:</bf></tag>
89 <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
90 <tt>file=</tt>/where/to/keep/counts;
91 <tt>deny=</tt><em>n</em>;
92 <tt>lock_time=</tt><em>n</em>;
93 <tt>unlock_time=</tt><em>n</em>;
95 <tt>even_deny_root_account</tt>;
100 <tag><bf>Description:</bf></tag>
103 The authentication component first checks if the user should be denied
104 access and if not it increments attempted login counter.
105 Then on call to <tt>pam_setcred</tt> it resets the attempts counter
106 if the user is NOT magic root.
109 <tag><bf>Examples/suggested usage:</bf></tag>
112 The <tt>deny=</tt><em>n</em> option is used to deny access if tally
113 for this user exceeds <em>n</em>.
116 The <tt>lock_time=</tt><em>n</em> option is used to always deny access
117 for at least <em>n</em> seconds after a failed attempt.
120 The <tt>unlock_time=</tt><em>n</em> option is used to allow access after
121 <em>n</em> seconds after the last failed attempt with exceeded tally.
122 If this option is used the user will be locked out only for the specified
123 amount of time after he exceeded his maximum allowed attempts. Otherwise
124 the lock is removed only by a manual intervention of the system administrator.
127 The <tt>magic_root</tt> option is used to indicate that if
128 the module is invoked by a user with uid=0, then the counter is not
129 incremented. The sys-admin should use this for user launched services,
130 like <tt>su</tt>, otherwise this argument should be omitted.
133 By way of more explanation, when a process already running as root
134 tries to access some service, the access is <em>magic</em>, and
135 bypasses <tt>pam_tally</tt>'s checks: this is handy for <tt>su</tt>ing
136 from root into an account otherwise blocked. However, for services
137 like <tt>telnet</tt> or <tt>login</tt>, which always effectively run
138 from the root account, root (ie everyone) shouldn't be granted this
139 magic status, and the flag `magic_root' should not be set in this
140 situation, as noted in the summary above.
143 Normally, failed attempts to access root will <bf>NOT</bf> cause the
144 root account to become blocked, to prevent denial-of-service: if your
145 users aren't given shell accounts and root may only login via
146 <tt>su</tt> or at the machine console (not
147 <tt>telnet</tt>/<tt>rsh</tt>, etc), this is safe. If you really want
148 root to be blocked for some given service, use
149 <tt>even_deny_root_account</tt>.
152 If <tt>/var/log/faillog</tt> contains a non-zero <tt>.fail_max/.fail_locktime</tt>
153 field for this user then the <tt>per_user</tt> module argument will
154 ensure that the module uses this value and not the global
155 <tt>deny/lock_time=</tt><em>n</em> parameter.
158 The <tt>no_lock_time</tt> option is for ensuring that the module does
159 not use the <tt>.fail_locktime</tt> field in /var/log/faillog for this
163 The <tt>no_reset</tt> option is used to instruct the module to not reset
164 the count on successful entry.
168 <sect2>Account component
173 <tag><bf>Recognized arguments:</bf></tag>
174 <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
175 <tt>file=</tt>/where/to/keep/counts;
179 <tag><bf>Description:</bf></tag>
182 The account component resets attempts counter if the user is NOT
183 magic root. This phase can be used optionaly for services which don't call
184 pam_setcred correctly or if the reset should be done regardless
185 of the failure of the account phase of other modules.
187 <tag><bf>Examples/suggested usage:</bf></tag>
190 The <tt>magic_root</tt> option is used to indicate that if
191 the module is invoked by a user with uid=0, then the counter is not
192 decremented/reset. The sys-admin should use this for user launched services,
193 like <tt>su</tt>, otherwise this argument should be omitted.
196 The <tt>no_reset</tt> option is used to instruct the module to not reset
197 the count on successful entry.
202 End of sgml insert for this module.