diff options
| -rw-r--r-- | CHANGELOG | 8 | ||||
| -rw-r--r-- | doc/modules/module.sgml-template | 2 | ||||
| -rw-r--r-- | doc/modules/pam_tally.sgml | 191 |
3 files changed, 197 insertions, 4 deletions
@@ -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). diff --git a/doc/modules/module.sgml-template b/doc/modules/module.sgml-template index d0b0e3c6..16a93c79 100644 --- a/doc/modules/module.sgml-template +++ b/doc/modules/module.sgml-template @@ -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 diff --git a/doc/modules/pam_tally.sgml b/doc/modules/pam_tally.sgml new file mode 100644 index 00000000..eeb05518 --- /dev/null +++ b/doc/modules/pam_tally.sgml @@ -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. +--> |