.\" .\" $FreeBSD$ .\" .Dd January 14, 2006 .Dt pam_abl 8 .Os .Sh NAME .Nm pam_abl .Nd auto blacklist PAM module .Sh SYNOPSIS .Ss Auto Blacklist PAM module .Op Ar service-name .Ar module-name .Ar control-flag .Pa pam_abl .Op Ar options .Ss Blacklist maintenance tool .Nm .Op Fl h | Fl -help .Op Fl p | Fl -purge .Op Fl r | Fl -relative .Op Fl v | Fl -verbose .Op Fl -okhost Ns No = Ns Ar host .Op Fl -okuser Ns No = Ns Ar user .Op Ar config-file .Sh DESCRIPTION The Auto Blacklist module for PAM, .Nm provides functionality for only one PAM category: authentication. In terms of the .Ar module-type parameter, this is the .Dq Li auth feature. .Ss Auto Blacklist PAM Authentication Module .Nm provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts. Generally configured so that blacklisted users still see normal login prompts but are guaranteed to fail to authenticate. This functionality is only available to services which call PAM as root. If .Nm is called for uid != 0 it will silently succeed. The following options may be passed to the authentication module: .Bl -tag -width indent .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm expose_account Ignored. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined. .It Cm try_first_pass Ignored. .It Cm use_first_pass Ignored. .It Cm use_mapped_pass Ignored. .It Cm config Ns No = Ns Ar config-file The configuration file contains additional arguments. In order for the .Nm blacklist maintenance tool to work correctly most of the configuration should be placed in the config file rather than being provided by arguments. The format of the config file is described below. .It Cm host_db Ns No = Ns Ar host-database-file Path to the Berkeley DB which is used to log the host responsible for failed authentication attempts. If host_db is omitted the corresponding auto blacklisting will be disabled. .It Cm host_purge Ns No = Ns Ar time Defines how long failed hosts are retained in the host database. Defaults to 1 day. .It Cm host_rule Ns No = Ns Ar host-rule The rule (see below for format) which defines the conditions under which a failed hosts will be blackisted. .It Cm user_db Ns No = Ns Ar user-database-file Path to the Berkeley DB which is used to log the user responsible for failed authentication attempts. If user_db is omitted the corresponding auto blacklisting will be disabled. .It Cm user_purge Ns No = Ns Ar time Defines how long failed users are retained in the user database. Defaults to 1 day. .It Cm user_rule Ns No = Ns Ar user-rule The rule (see below for format) which defines the conditions under which a failed users will be blackisted. .El .Ss Rules syntax .Cm host_rule No Cm user_rule are the rules which determine the circumstances under which accounts ares auto blacklisted. The .Cm host_rule is used to block access to hosts that are responsible for excessive authentication failures and the .Cm user_rule is used to disable accounts for which there have been excessive authentication failures. Each rule consists of a number of space separated .Sy user clauses Ns No . A .Sy user clause specifies the user names and services to match and a set of triggers. A simple example would be: .Bd -literal -offset indent *:10/1h .Ed .Pp which means 'block any user (*) if they are responsible for ten or more failed authentication attempts in the last hour'. In place of the '*' which matches any user a list of usernames can be supplied like this: .Bd -literal -offset indent root|dba|admin:10/1h .Ed .Pp which means 'block the users root, dba and admin if they are responsible for ten or more failed authentication attempts in the last hour'. You can also specify a service name to match against like this: .Bd -literal -offset indent root/sshd|dba/*:3/1d .Ed .Pp which means 'block the users root for service sshd and user dba for any service if they are responsible for three or more failed authentication attempts in the last day'. Finally you can specify multiple triggers like this: .Bd -literal -offset indent root:10/1h,20/1d .Ed .Pp which means 'block the user root if they are responsible for ten or more failed attempts in the last hour or twenty or more failed attempts in the last day. .Pp Multiple rules can be provided separated by spaces like this: .Bd -literal -offset indent *:10/1h root:5/1h,10/1d .Ed .Pp in which case all rules that match a particular user and service will be checked. The user or host will be blocked if any of the rule triggers matches. .Pp The sense of the user matching can be inverted by placing a '!' in front of the rule so that: .Bd -literal -offset indent !root:20/1d .Ed .Pp is a rule which would match for all users apart from root. .Pp It is important to treat root as a special case in the .Cm user_rule otherwise excessive attempts to authenticate as root will result in the root account being locked out even for valid holders of root credentials. .Pp Here is the full syntax for rules: .Bd -literal -offset indent word ::= /[^\\s\\|\\/\\*]+/ name ::= word | '*' username ::= name servicename ::= name userservice ::= username | username '/' servicename namelist ::= userservice | userservice '|' namelist userspec ::= namelist | '!' namelist multiplier ::= 's' | 'm' | 'h' | 'd' number ::= /\d+/ period ::= number | number multiplier trigger ::= number '/' period triglist ::= trigger | trigger ',' triglist userclause ::= userspec ':' triglist rule ::= userclause | userclause /\s+/ rule .Ed .Pp For rules to work correctly .Cm host_purge No and Cm user_purge must be at least as long as the longest period specified in a corresponding rule. You may wish to retain information about failed attempts for longer than this so that the .Nm blacklist maintenance tool can report information over a longer period of time. The format for this items is a number with an optional multiplier suffix, 's', 'm', 'h' or 'd' which correspond with seconds, minutes, hours and days. To specify seven days for example one would use '7d'. Note that in normal operation .Nm PAM module will only purge the logged data for a particular host or user if it happens to be updating it, i.e. if that host or user makes another failed attempt. To purge all old entries the .Nm blacklist maintenance tool should be used. .Ss Blacklist maintenance tool Blacklist maintenance tool .Nm perform maintenance on the databases used by the .Nm PAM module. The options are as follows: .Bl -tag -width indent .It Fl h | Fl -help Print help page and exit. .It Fl p | Fl -purge Purge databases according to purge rules in config. .It Fl r | Fl -relative Display times relative to now otherwise absolute times will be displayed. .It Fl v | Fl -verbose Verbose output. .It Fl -okhost Ns No = Ns Ar host-name Unblock host. .It Fl -okuser Ns No = Ns Ar user-name Unblock user. .It Ar config-file Name of the .Nm configuration file (default: %%ETCPREFIX%%/etc/pam_abl.conf). The config file is read to discover the names of the .Nm databases and the rules that control purging of old data from them. .El .Sh EXAMPLES .Ss Auto Blacklist PAM module Typically .Nm PAM module is added to the auth stack as a required module just before whatever modules actually peform authentication. Here's a fragment of the PAM config: .Bd -literal -offset indent auth required pam_env auth required pam_abl config=%%ETCPREFIX%%/etc/pam_abl.conf auth sufficient pam_unix likeauth nullok auth required pam_deny .Ed .Ss Blacklist maintenance tool Obtain a list of failed hosts and users: .Bd -literal -offset indent $ pam_abl .Ed .Pp Obtain a full list of failures listing times relative to now: .Bd -literal -offset indent $ pam_abl -rv .Ed .Pp Purge old data: .Bd -literal -offset indent $ pam_abl -p .Ed .Pp Unblock all example.com hosts and all users: .Bd -literal -offset indent $ pam_abl -v --okhost='*.example.com' --okuser='*' .Ed .Sh SEE ALSO .Xr pam.conf 5 , .Xr pam 8 .Bd -literal http://www.hexten.net/pam_abl/ http://sourceforge.net/project/showfiles.php?group_id=148927 .Ed .Sh AUTHORS Written by Andy Armstrong . .Sh BUGS Report bugs to Andy Armstrong .