From c9da49158d9007c8ae27114c8a44289854f777b1 Mon Sep 17 00:00:00 2001 From: "Andrew G. Morgan" Date: Sun, 11 Feb 2001 07:52:56 +0000 Subject: Relevant BUGIDs: 126210 Purpose of commit: documentation Commit summary: --------------- added some pam_tally documentation. --- doc/modules/module.sgml-template | 2 +- doc/modules/pam_tally.sgml | 191 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 192 insertions(+), 1 deletion(-) create mode 100644 doc/modules/pam_tally.sgml (limited to 'doc') 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 - + [ 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 @@ + + +The login counter (tallying) module + +Synopsis + +

+ + +Module Name: +pam_tally + +Author[s]: +Tim Baverstock + +Maintainer: + +Management groups provided: +auth; account + +Cryptographically sensitive: + +Security rating: + +Clean code base: + +System dependencies: +A faillog file (default location /var/log/faillog) + +Network aware: + + + +Overview of module + +

+This module maintains a count of attempted accesses, can reset count +on success, can deny access if too many attempts fail. + +

+pam_tally comes in two parts: pam_tally.so and +pam_tally. The former is the PAM module and the latter, a +stand-alone program. 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. For example, one might find it +useful to clear all counts every midnight from a cron job. + +

+The counts file is organized 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 appliction. + +

+Note, there are some outstanding issues with this module: +pam_tally is very dependant on getpw*() - a database +of usernames would be much more flexible; 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. + +Generic options accepted by both components +

+ + onerr=(succeed|fail): + if something weird happens, such as unable to open the file, how + should the module react? + file=/where/to/keep/counts: + specify the file location for the counts. + The default location is /var/log/faillog. + + +Authentication component + +

+ + +Recognized arguments: +onerr=(succeed|fail); +file=/where/to/keep/counts; +no_magic_root + +Description: + +

+The authentication component of this module increments the attempted +login counter. + +

+Examples/suggested usage: + +

+The module argument no_magic_root 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 telnet/rsh/login. For user +launched services, like su, this argument should be omitted. + +

+By way of more explanation, when a process already running as root +tries to access some service, the access is magic, and +bypasses pam_tally's checks: this is handy for suing +from root into an account otherwise blocked. However, for services +like telnet or login, 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. + + + +Account component + +

+ + +Recognized arguments: +onerr=(succeed|fail); +file=/where/to/keep/counts; +deny=n; +no_magic_root; +even_deny_root_account; +reset; +no_reset; +per_user; +no_lock_time + +Description: + +

+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. + +Examples/suggested usage: + +

+The deny=n option is used to deny access if tally +for this user exceeds n. The presence of +deny=n changes the default for +reset/no_reset to reset, unless the user +trying to gain access is root and the no_magic_root option +has NOT been specified. + +

+The no_magic_root option ensures that access attempts by root +DON'T ignore deny. Use this for daemon-based stuff, like +telnet/rsh/login. + +

+The even_deny_root_account option is used to ensure that the +root account can become unavailable. Note that magic root +trying to gain root bypasses this, but normal users can be locked out. + +

+The reset option instructs the module to reset count to 0 on +successful entry, even for magic root. The no_reset option is +used to instruct the module to not reset the count on successful +entry. This is the default unless deny exists and the user +attempting access is NOT magic root. + +

+If /var/log/faillog contains a non-zero .fail_max +field for this user then the per_user module argument will +ensure that the module uses this value and not the global +deny=n parameter. + +

+The no_lock_time option is for ensuring that the module does +not use the .fail_locktime field in /var/log/faillog for this +user. + +

+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. + + + + -- cgit v1.2.3