Provided by: libpam-abl_0.6.0-5_amd64 
NAME
pam_abl - PAM Auto Blacklist Module
SYNOPSIS
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.
DESCRIPTION
Brute force password discovery attacks involve repeated attempts to authenticate against a service using
a dictionary of common passwords. While it is desirable to enforce strong passwords for users this is not
always possible and in cases where a weak password has been used brute force attacks can be effective.
The pam_abl module monitors failed authentication attempts and automatically blacklists those hosts (and
accounts) that are responsible for large numbers of failed attempts. Once a host is blacklisted it is
guaranteed to fail authentication even if the correct credentials are provided.
Blacklisting is triggered when the number of failed authentication attempts in a particular period of
time exceeds a predefined limit. Hosts which stop attempting to authenticate will, after a period of
time, be un-blacklisted.
Commands can be specified which will be run when a host or user switches state from being blocked to
clear or clear to blocked. See below or the pam_abl.conf(5) manpage for the details.
If pam_abl is called for uid != 0 it will silently succeed. If this was not the case it would be possible
for a malicious local user to poison the pam_abl data by, for example, discovering the names of the hosts
from which root typically logs in and then constructing PAM authentication code to lock out root login
attempts from those hosts.
OPTIONS
Name Arguments Description
debug None Enable debug output to
syslog.
expose_account None Ignored
no_warn None Disable warnings which are
otherwise output to syslog.
try_first_pass None Ignored
use_first_pass None Ignored
use_mapped_pass None Ignored
config Path to the configuration The configuration file
file. contains additional
arguments. In order for the
pam_abl command line 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.
limits Minimum and maximum number It’s value should have the
of attempts to keep. following syntax
"<minimum>-<maximum>". If
you do not block machines
that do too many attempts,
the db can easily become
bloated. To prevent this we
introduced this setting. As
soon as there are a
<maximum> number of attempts
for a user/host, the number
of stored attempts is
reduced to <minimum>. A
<maximum> of 0 means no
limits. Make sure that
<minimum> is larger then any
rule specified. We recommend
a value of "1000-1200".
db_home Directory for db locking and Path to a directory where
logging files. Berkeley DB can place it’s
locking and logging files.
Make sure this dir is
writable.
host_db Path to host database file. Path to the Berkeley DB
which is used to log the
host responsible for failed
authentication attempts.
host_purge Purge time for the host Defines how long failed
database. hosts are retained in the
host database. Defaults to 1
day.
host_rule Rule for host blacklisting. The rule (see below for
format) which defines the
conditions under which a
failed hosts will be
blackisted.
host_whitelist Host that do not need to be ;-seperated list of host
tracked. that do not need to be
tracked. You can specify
single IP addresses here or
use subnets. For example
1.1.1.1 or 1.1.1.1/24
host_blk_cmd Host block command Deprecated for security
reasons. Please use
host_block_cmd
host_clr_cmd Host clear command Deprecated for security
reasons. Please use
host_clear_cmd
host_block_cmd Host block command Command that should be run
when a host is checked, and
is currently blocked. Within
the command, the strings %u,
%h and %s are substituted
with username, host and
service. Not all need to be
used. Please see the manpage
of pam_abl.conf for the
correct syntax.
host_clear_cmd Host clear command Command that should be run
when a host is checked, and
is currently clear. Within
the command, the strings %u,
%h and %s are substituted
with username, host and
service. Not all need to be
used. Please see the manpage
of pam_abl.conf for the
correct syntax.
user_db Path to user database file. Path to the Berkeley DB
which is used to log the
user responsible for failed
authentication attempts.
user_purge Purge time for the user Defines how long failed
database. users are retained in the
user database. Defaults to 1
day.
user_rule Rule for user blacklisting. The rule (see below for
format) which defines the
conditions under which a
failed users will be
blackisted.
user_whitelist Users that do not need to be ;-seperated list of users
tracked. whose attempts do not need
to be recorded. This does
not prevent the machine they
are using from being
blocked.
user_blk_cmd User block command Deprecated for security
reasons. Please use
user_block_cmd
user_clr_cmd User clear command Deprecated for security
reasons. Please use
clear_block_cmd
user_blk_cmd User block command Command that should be run
when a user is checked, and
is currently blocked. Within
the command, the strings %u,
%h and %s are substituted
with username, host and
service. Not all need to be
used.
user_clr_cmd User block command Command that should be run
when a user is checked, and
is currently clear. Within
the command, the strings %u,
%h and %s are substituted
with username, host and
service. Not all need to be
used.
USAGE
Typically pam_abl.so is added to the auth stack as a required module just before whatever modules
actually perform authentication. Here’s a fragment of the PAM config for a production server that is
running pam_abl:
auth required /lib/security/pam_env.so
auth required /lib/security/pam_abl.so
config=/etc/security/pam_abl.conf
auth sufficient /lib/security/pam_unix.so likeauth nullok
auth required /lib/security/pam_deny.so
Although all of accepted arguments can be supplied here they will usually be placed in a separate config
file and linked to using the config argument as in the above example. The pam_abl command line tool reads
the external config file (/etc/security/pam_abl.conf in this case) to find the databases so in order for
it work correctly an external config should be used.
EXAMPLES
auth required /lib/security/pam_env.so
auth required /lib/security/pam_abl.so config=/etc/security/pam_abl.conf
auth sufficient /lib/security/pam_unix.so likeauth nullok
auth required /lib/security/pam_deny.so
SEE ALSO
pam_abl.conf(5), pam_abl(1)
AUTHORS
Lode Mertens <pam-abl@danta.be>
Andy Armstrong <andy@hexten.net>
Chris Tasma <pam-abl@deksai.com>
AUTHOR
Chris Tasma
Author.
GNU 05/19/2016 PAM_ABL(8)