mirror of
https://github.com/linux-pam/linux-pam.git
synced 2024-11-24 10:22:47 +08:00
Relevant BUGIDs: 126210
Purpose of commit: documentation Commit summary: --------------- added some pam_tally documentation.
This commit is contained in:
Andrew G. Morgan
parent
7ca1d77e78
commit
c9da49158d
@ -50,6 +50,8 @@ libpam. Prior versions were buggy - see bugfix for Bug 129775.
|
||||
|
||||
** WARNING **
|
||||
|
||||
* added some sys-admin documentation for the pam_tally module (Bug
|
||||
126210 - agmorgan).
|
||||
* added a link to module examples from the module writers doc (Bug
|
||||
131192 - agmorgan).
|
||||
* fixed a small security hole (more of a user confusion issue) with
|
||||
@ -57,9 +59,9 @@ libpam. Prior versions were buggy - see bugfix for Bug 129775.
|
||||
the bug report, but no uid change was possible so no-one should
|
||||
think they need to issue a security bulletin over this one! (Bug
|
||||
112540 - agmorgan)
|
||||
* pam_lastlog needs to be linked with -lutil (Bug 131549 - agmorgan)
|
||||
* pam_lastlog needs to be linked with -lutil (Bug 131549 - agmorgan).
|
||||
* pam_cracklib needs to be linked with -lcrypt (old password checking)
|
||||
(Bug 131601 - agmorgan)
|
||||
(Bug 131601 - agmorgan).
|
||||
* fixes for static library builds and also the examples when linked
|
||||
with the debugging build of the libraries. (Bug 131783 - agmorgan)
|
||||
* fixed URL for original RFC to a cached kernel.org file. (Bug 131503
|
||||
@ -68,7 +70,7 @@ libpam. Prior versions were buggy - see bugfix for Bug 129775.
|
||||
agmorgan).
|
||||
* improved handling of the setcred/close_session and update chauthtok
|
||||
stack. *Warning* This is a backwardly incompatable change, but 'more
|
||||
sane' than before. (Bug 129775 - agmorgan).
|
||||
sane' than before. (Bug 129775 - agmorgan)
|
||||
* bumped the version number, and added some code to assist in making
|
||||
documentation releases (Bug 129644 - agmorgan).
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
$Id$
|
||||
|
||||
This template file was written by Andrew G. Morgan
|
||||
<morgan@parc.power.net>
|
||||
<morgan@kernel.org>
|
||||
|
||||
[
|
||||
Text that should be deleted/replaced, is enclosed within
|
||||
|
||||
191
doc/modules/pam_tally.sgml
Normal file
191
doc/modules/pam_tally.sgml
Normal file
@ -0,0 +1,191 @@
|
||||
<!--
|
||||
|
||||
$Id$
|
||||
|
||||
This template file was written by Andrew G. Morgan <morgan@kernel.org>
|
||||
adapted from text provided by Tim Baverstock.
|
||||
-->
|
||||
|
||||
<sect1>The login counter (tallying) module
|
||||
|
||||
<sect2>Synopsis
|
||||
|
||||
<p>
|
||||
<descrip>
|
||||
|
||||
<tag><bf>Module Name:</bf></tag>
|
||||
pam_tally
|
||||
|
||||
<tag><bf>Author[s]:</bf></tag>
|
||||
Tim Baverstock
|
||||
|
||||
<tag><bf>Maintainer:</bf></tag>
|
||||
|
||||
<tag><bf>Management groups provided:</bf></tag>
|
||||
auth; account
|
||||
|
||||
<tag><bf>Cryptographically sensitive:</bf></tag>
|
||||
|
||||
<tag><bf>Security rating:</bf></tag>
|
||||
|
||||
<tag><bf>Clean code base:</bf></tag>
|
||||
|
||||
<tag><bf>System dependencies:</bf></tag>
|
||||
A faillog file (default location /var/log/faillog)
|
||||
|
||||
<tag><bf>Network aware:</bf></tag>
|
||||
|
||||
</descrip>
|
||||
|
||||
<sect2>Overview of module
|
||||
|
||||
<p>
|
||||
This module maintains a count of attempted accesses, can reset count
|
||||
on success, can deny access if too many attempts fail.
|
||||
|
||||
<p>
|
||||
pam_tally comes in two parts: <tt>pam_tally.so</tt> and
|
||||
<tt>pam_tally</tt>. The former is the PAM module and the latter, a
|
||||
stand-alone program. <tt>pam_tally</tt> 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, one might find it
|
||||
useful to clear all counts every midnight from a cron job.
|
||||
|
||||
<p>
|
||||
The counts file is organized as a binary-word array, indexed by
|
||||
uid. You can probably make sense of it with <tt>od</tt>, if you don't
|
||||
want to use the supplied appliction.
|
||||
|
||||
<p>
|
||||
Note, there are some outstanding issues with this module:
|
||||
<tt>pam_tally</tt> is very dependant on <tt>getpw*()</tt> - a database
|
||||
of usernames would be much more flexible; the `keep a count of current
|
||||
logins' bit has been <tt>#ifdef</tt>'d out and you can only reset the
|
||||
counter on successful authentication, for now.
|
||||
|
||||
<sect3>Generic options accepted by both components
|
||||
<p>
|
||||
<itemize>
|
||||
<item> <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>):
|
||||
if something weird happens, such as unable to open the file, how
|
||||
should the module react?
|
||||
<item> <tt>file=</tt><em>/where/to/keep/counts</em>:
|
||||
specify the file location for the counts.
|
||||
The default location is <tt>/var/log/faillog</tt>.
|
||||
</itemize>
|
||||
|
||||
<sect2>Authentication component
|
||||
|
||||
<p>
|
||||
<descrip>
|
||||
|
||||
<tag><bf>Recognized arguments:</bf></tag>
|
||||
<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
|
||||
<tt>file=</tt>/where/to/keep/counts;
|
||||
<tt>no_magic_root</tt>
|
||||
|
||||
<tag><bf>Description:</bf></tag>
|
||||
|
||||
<p>
|
||||
The authentication component of this module increments the attempted
|
||||
login counter.
|
||||
|
||||
<p>
|
||||
<tag><bf>Examples/suggested usage:</bf></tag>
|
||||
|
||||
<p>
|
||||
The module argument <tt>no_magic_root</tt> is used to indicate that if
|
||||
the module is invoked by a user with uid=0, then the counter is
|
||||
incremented. The sys-admin should use this for daemon-launched
|
||||
services, like <tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>. For user
|
||||
launched services, like <tt>su</tt>, this argument should be omitted.
|
||||
|
||||
<p>
|
||||
By way of more explanation, when a process already running as root
|
||||
tries to access some service, the access is <em>magic</em>, and
|
||||
bypasses <tt>pam_tally</tt>'s checks: this is handy for <tt>su</tt>ing
|
||||
from root into an account otherwise blocked. However, for services
|
||||
like <tt>telnet</tt> or <tt>login</tt>, which always effectively run
|
||||
from the root account, root (ie everyone) shouldn't be granted this
|
||||
magic status, and the flag `no_magic_root' should be set in this
|
||||
situation, as noted in the summary above.
|
||||
|
||||
</descrip>
|
||||
|
||||
<sect2>Account component
|
||||
|
||||
<p>
|
||||
<descrip>
|
||||
|
||||
<tag><bf>Recognized arguments:</bf></tag>
|
||||
<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
|
||||
<tt>file=</tt>/where/to/keep/counts;
|
||||
<tt>deny=</tt><em>n</em>;
|
||||
<tt>no_magic_root</tt>;
|
||||
<tt>even_deny_root_account</tt>;
|
||||
<tt>reset</tt>;
|
||||
<tt>no_reset</tt>;
|
||||
<tt>per_user</tt>;
|
||||
<tt>no_lock_time</tt>
|
||||
|
||||
<tag><bf>Description:</bf></tag>
|
||||
|
||||
<p>
|
||||
The account component can deny access and/or reset the attempts
|
||||
counter. It also checks to make sure that the counts file is a plain
|
||||
file and not world writable.
|
||||
|
||||
<tag><bf>Examples/suggested usage:</bf></tag>
|
||||
|
||||
<p>
|
||||
The <tt>deny=</tt><em>n</em> option is used to deny access if tally
|
||||
for this user exceeds <em>n</em>. The presence of
|
||||
<tt>deny=</tt><em>n</em> changes the default for
|
||||
<tt>reset</tt>/<tt>no_reset</tt> to <tt>reset</tt>, unless the user
|
||||
trying to gain access is root and the <tt>no_magic_root</tt> option
|
||||
has NOT been specified.
|
||||
|
||||
<p>
|
||||
The <tt>no_magic_root</tt> option ensures that access attempts by root
|
||||
DON'T ignore deny. Use this for daemon-based stuff, like
|
||||
<tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>.
|
||||
|
||||
<p>
|
||||
The <tt>even_deny_root_account</tt> option is used to ensure that the
|
||||
root account can become unavailable. <bf>Note</bf> that magic root
|
||||
trying to gain root bypasses this, but normal users can be locked out.
|
||||
|
||||
<p>
|
||||
The <tt>reset</tt> option instructs the module to reset count to 0 on
|
||||
successful entry, even for magic root. The <tt>no_reset</tt> option is
|
||||
used to instruct the module to not reset the count on successful
|
||||
entry. This is the default unless <tt>deny</tt> exists and the user
|
||||
attempting access is NOT magic root.
|
||||
|
||||
<p>
|
||||
If <tt>/var/log/faillog</tt> contains a non-zero <tt>.fail_max</tt>
|
||||
field for this user then the <tt>per_user</tt> module argument will
|
||||
ensure that the module uses this value and not the global
|
||||
<tt>deny=</tt><em>n</em> parameter.
|
||||
|
||||
<p>
|
||||
The <tt>no_lock_time</tt> option is for ensuring that the module does
|
||||
not use the <tt>.fail_locktime</tt> field in /var/log/faillog for this
|
||||
user.
|
||||
|
||||
<p>
|
||||
Normally, failed attempts to access root will <bf>NOT</bf> 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
|
||||
<tt>su</tt> or at the machine console (not
|
||||
<tt>telnet</tt>/<tt>rsh</tt>, etc), this is safe. If you really want
|
||||
root to be blocked for some given service, use
|
||||
<tt>even_deny_root_account</tt>.
|
||||
|
||||
</descrip>
|
||||
|
||||
<!--
|
||||
End of sgml insert for this module.
|
||||
-->
|
||||
Loading…
Reference in New Issue
Block a user