pam_abl(8)

NAME
pam_abl - auto blacklist PAM module

SYNOPSIS

  Auto Blacklist PAM module
[service-name] module-name control-flag pam_abl [options]

  Blacklist maintenance tool
pam_abl [-h | --help] [-p | --purge] [-r | --relative] [-v | --verbose] [--okhost=host] [--okuser=user] [config-file]

DESCRIPTION
The Auto Blacklist module for PAM, pam_abl provides functionality for only one PAM category: authentication. In terms of the module-type parameter, this is the “auth” feature.

  Auto Blacklist PAM Authentication Module
pam_abl 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 pam_abl is called for uid != 0 it will silently succeed. The following options may be passed to the authentication module:

debug
    syslog(3) debugging information at LOG_DEBUG level.

expose_account
    Ignored.

no_warn
    suppress warning messages to the user. These messages include reasons why the user's authentication attempt was declined.

try_first_pass
    Ignored.

use_first_pass
    Ignored.

use_mapped_pass
    Ignored.

config=config-file
    The configuration file contains additional arguments. In order for the pam_abl 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.

host_db=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.

host_purge=time
    Defines how long failed hosts are retained in the host database. Defaults to 1 day.

host_rule=host-rule
    The rule (see below for format) which defines the conditions under which a failed hosts will be blackisted.

user_db=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.

user_purge=time
    Defines how long failed users are retained in the user database. Defaults to 1 day.

user_rule=user-rule
    The rule (see below for format) which defines the conditions under which a failed users will be blackisted.

  Rules syntax
host_rule user_rule are the rules which determine the circumstances under which accounts ares auto blacklisted. The host_rule is used to block access to hosts that are responsible for excessive authentication failures and the user_rule is used to disable accounts for which there have been excessive authentication failures. Each rule consists of a number of space separated user clauses. A user clause specifies the user names and services to match and a set of triggers. A simple example would be:

    *:10/1h

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:

    root|dba|admin:10/1h

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:

    root/sshd|dba/*:3/1d

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:

    root:10/1h,20/1d

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.

Multiple rules can be provided separated by spaces like this:

    *:10/1h root:5/1h,10/1d

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.

The sense of the user matching can be inverted by placing a '!' in front of the rule so that:

    !root:20/1d

is a rule which would match for all users apart from root.

It is important to treat root as a special case in the 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.

Here is the full syntax for rules:

    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 ::= /+/
    period ::= number | number multiplier
    trigger ::= number '/' period
    triglist ::= trigger | trigger ',' triglist
    userclause ::= userspec ':' triglist
    rule ::= userclause | userclause // rule

For rules to work correctly host_purge and 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 pam_abl 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, To specify seven days for example one would use '7d'. Note that in normal operation pam_abl 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 pam_abl blacklist maintenance tool should be used.

  Blacklist maintenance tool
Blacklist maintenance tool pam_abl perform maintenance on the databases used by the pam_abl PAM module. The options are as follows:

-h | --help
    Print help page and exit.

-p | --purge
    Purge databases according to purge rules in config.

-r | --relative
    Display times relative to now otherwise absolute times will be displayed.

-v | --verbose
    Verbose output.

--okhost=host-name
    Unblock host.

--okuser=user-name
    Unblock user.

config-file
    Name of the pam_abl configuration file (default: %%ETCPREFIX%%/etc/pam_abl.conf). The config file is read to discover the names of the pam_abl databases and the rules that control purging of old data from them.

EXAMPLES

  Auto Blacklist PAM module
Typically pam_abl 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:

    auth required   pam_env
    auth required   pam_abl  config=%%ETCPREFIX%%/etc/pam_abl.conf
    auth sufficient pam_unix likeauth nullok
    auth required   pam_deny

  Blacklist maintenance tool
Obtain a list of failed hosts and users:

    $ pam_abl

Obtain a full list of failures listing times relative to now:

    $ pam_abl -rv

Purge old data:

    $ pam_abl -p

Unblock all example.com hosts and all users:

    $ pam_abl -v --okhost='*.example.com' --okuser='*'

SEE ALSO
pam.conf(5), pam(8)

    http://www.hexten.net/pam_abl/
    http://sourceforge.net/project/showfiles.php?group_id=148927

AUTHORS
Written by Andy Armstrong <andy@hexten.net>.

BUGS
Report bugs to Andy Armstrong <andy@hexten.net>.