modules/pam_tally2/README

   1 pam_tally2 — The login counter (tallying) module
   2
   3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   4
   5 DESCRIPTION
   6
   7 This module maintains a count of attempted accesses, can reset count on
   8 success, can deny access if too many attempts fail.
   9
  10 pam_tally2 comes in two parts: pam_tally2.so and pam_tally2. The former is the
  11 PAM module and the latter, a stand-alone program. pam_tally2 is an (optional)
  12 application which can be used to interrogate and manipulate the counter file.
  13 It can display users' counts, set individual counts, or clear all counts.
  14 Setting artificially high counts may be useful for blocking users without
  15 changing their passwords. For example, one might find it useful to clear all
  16 counts every midnight from a cron job.
  17
  18 Normally, failed attempts to access root will not cause the root account to
  19 become blocked, to prevent denial-of-service: if your users aren't given shell
  20 accounts and root may only login via su or at the machine console (not telnet/
  21 rsh, etc), this is safe.
  22
  23 OPTIONS
  24
  25 GLOBAL OPTIONS
  26
  27     This can be used for auth and account module types.
  28
  29     onerr=[fail|succeed]
  30
  31         If something weird happens (like unable to open the file), return with
  32         PAM_SUCCESS if onerr=succeed is given, else with the corresponding PAM
  33         error code.
  34
  35     file=/path/to/counter
  36
  37         File where to keep counts. Default is /var/log/tallylog.
  38
  39     audit
  40
  41         Will log the user name into the system log if the user is not found.
  42
  43     silent
  44
  45         Don't print informative messages.
  46
  47     no_log_info
  48
  49         Don't log informative messages via syslog(3).
  50
  51 AUTH OPTIONS
  52
  53     Authentication phase first increments attempted login counter and checks if
  54     user should be denied access. If the user is authenticated and the login
  55     process continues on call to pam_setcred(3) it resets the attempts counter.
  56
  57     deny=n
  58
  59         Deny access if tally for this user exceeds n.
  60
  61     lock_time=n
  62
  63         Always deny for n seconds after failed attempt.
  64
  65     unlock_time=n
  66
  67         Allow access after n seconds after failed attempt. If this option is
  68         used the user will be locked out for the specified amount of time after
  69         he exceeded his maximum allowed attempts. Otherwise the account is
  70         locked until the lock is removed by a manual intervention of the system
  71         administrator.
  72
  73     magic_root
  74
  75         If the module is invoked by a user with uid=0 the counter is not
  76         incremented. The sysadmin should use this for user launched services,
  77         like su, otherwise this argument should be omitted.
  78
  79     even_deny_root
  80
  81         Root account can become unavailable.
  82
  83     root_unlock_time=n
  84
  85         This option implies even_deny_root option. Allow access after n seconds
  86         to root account after failed attempt. If this option is used the root
  87         user will be locked out for the specified amount of time after he
  88         exceeded his maximum allowed attempts.
  89
  90     serialize
  91
  92         Serialize access to the tally file using locks. This option might be
  93         used only for non-multithreaded services because it depends on the
  94         fcntl locking of the tally file. Also it is a good idea to use this
  95         option only in such configurations where the time between auth phase
  96         and account or setcred phase is not dependent on the authenticating
  97         client. Otherwise the authenticating client will be able to prevent
  98         simultaneous authentications by the same user by simply artificially
  99         prolonging the time the file record lock is held.
 100
 101 ACCOUNT OPTIONS
 102
 103     Account phase resets attempts counter if the user is not magic root. This
 104     phase can be used optionally for services which don't call pam_setcred(3)
 105     correctly or if the reset should be done regardless of the failure of the
 106     account phase of other modules.
 107
 108     magic_root
 109
 110         If the module is invoked by a user with uid=0 the counter is not
 111         changed. The sysadmin should use this for user launched services, like
 112         su, otherwise this argument should be omitted.
 113
 114 NOTES
 115
 116 pam_tally2 is not compatible with the old pam_tally faillog file format. This
 117 is caused by requirement of compatibility of the tallylog file format between
 118 32bit and 64bit architectures on multiarch systems.
 119
 120 There is no setuid wrapper for access to the data file such as when the
 121 pam_tally2.so module is called from xscreensaver. As this would make it
 122 impossible to share PAM configuration with such services the following
 123 workaround is used: If the data file cannot be opened because of insufficient
 124 permissions (EACCES) the module returns PAM_IGNORE.
 125
 126 EXAMPLES
 127
 128 Add the following line to /etc/pam.d/login to lock the account after 4 failed
 129 logins. Root account will be locked as well. The accounts will be automatically
 130 unlocked after 20 minutes. The module does not have to be called in the account
 131 phase because the login calls pam_setcred(3) correctly.
 132
 133 auth     required       pam_securetty.so
 134 auth     required       pam_tally2.so deny=4 even_deny_root unlock_time=1200
 135 auth     required       pam_env.so
 136 auth     required       pam_unix.so
 137 auth     required       pam_nologin.so
 138 account  required       pam_unix.so
 139 password required       pam_unix.so
 140 session  required       pam_limits.so
 141 session  required       pam_unix.so
 142 session  required       pam_lastlog.so nowtmp
 143 session  optional       pam_mail.so standard
 144
 145
 146 AUTHOR
 147
 148 pam_tally2 was written by Tim Baverstock and Tomas Mraz.
 149