pam_abl.conf - Configuration file for pam_abl PAM module.
Configuration file for both the pam_abl(8) PAM module, and the pam_abl(1)
command line tool.
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
Each rule consists of a number of space separated user clauses
. A user
clause specifies the user (and service) names to match and a set of triggers.
A simple example would be
which means block any user () if they are responsible for ten
or more failed authentication attempts in the last hour . In place of
which matches any user a list of usernames can be supplied
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
which means block the users root for service 'sshd
and 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
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
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 !
of the rule so that
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. The config file can contain any arguments
that would be supplied via PAM config. In the config file arguments are placed
on separate lines. Comments may be included after a #
continuation is possible by placing a back slash at the end of the line to be
continued. Here is a sample /etc/security/pam_abl.conf:
All of the standard PAM arguments (debug, expose_account, no_warn,
try_first_pass, use_first_pass, use_mapped_pass) are accepted; with the
exception of debug and no_warn these are ignored.
The arguments that are specific to the PAM module are as follows:
Specify the directory where the Berkeley db
can store it’s lock and log files. Make sure this dir exists and is
It’s value should have the 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 for this user/host 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".
Specify the name of the databases that will be
used to log failed authentication attempts. The host database is used to log
the hostname responsible for a failed auth and the user database is used to
log the requested username. If host_db or user_db is omitted the corresponding
auto blacklisting will be disabled.
Specify the length of time for which failed
attempts should be kept in the databases. For rules to work correctly this
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 command line tool can report information over a
longer period of time. The format for this item 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 pam_abl 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 command line tool should be used.
These are the rules which determine the
circumstances under which accounts are 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. The rule syntax is described in full
host_clr_cmd, host_blk_cmd, user_clr_cmd, user_blk_cmd
Deprecated for security reasons. Please use
the corresponding safer option: host_clear_cmd, host_block_cmd,
host_clear_cmd, host_block_cmd, user_clear_cmd, user_block_cmd
These specify commands that will run during a
check when an item switches state since its last check.
host_clear_cmd and user_clear_cmd will run if the host or user is currently
allowed access. host_block_cmd and user_block_cmd are run if the host or user
is currently being blocked by their respective rules.
Within the commands, you can specify substitutions with %h, %u and %s, which
will be replace with the host name, user name and service currently being
checked. For security reasons we do not run the command using the system call.
We use the more secure fork/exec solution. This means that you can’t
specify input and output redirections.
Note that this also means that no escaping is done, so if you call a shell here,
you might introduce a security problem.
The commands should follow a special syntax (you can use the command line tool
with the -d option to test the parsing of your commands) where the command and
it’s different arguments need to be enclosed in  and all text not
enclosed in  is simply ignored. For example: "[/usr/bin/logger] ignored
[block] [user] [%u]" will run the command "/usr/bin/logger block
user <current user>". If you want to specify a [
, you need to escape them with a \
;-seperated list of hosts/users whose attempts
will not be recorded. So if an attempt is made from "10.10.10.10"
for user "root" and "root" is in the whitelist, only an
attempt for his machine is recorded. If a user is whitelisted, this does not
prevent his machine from being blocked. Hosts can be specified using their IP
(184.108.40.206) or using a netmask (220.127.116.11/24)
host_block_cmd=[/sbin/iptables] [-I] [INPUT] [-s] [%h] [-j] [DROP]
user_clear_cmd=[/usr/bin/logger] [block] [user] [%u]
Lode Mertens <email@example.com>
Andy Armstrong <firstname.lastname@example.org>
Chris Tasma <email@example.com>