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
*: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 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.
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 #, and line
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:
# /etc/security/pam_abl.conf
debug
host_db=/var/lib/abl/hosts.db
host_purge=2d
host_rule=*:10/1h,30/1d
user_db=/var/lib/abl/users.db
user_purge=2d
user_rule=!root:10/1h,30/1d
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:
-
db_home
-
Specify the directory where the Berkeley db
can store its lock and log files. Make sure
this directory exists and is writable.
-
limits
-
Its value should have the following syntax
"<minimum>-<maximum>". If you do not block
hosts (with iptables for example) 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
than any rule specified. We recommend a value
of "1000-1200".
-
host_db, user_db
-
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.
-
host_purge, user_purge
-
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.
-
host_rule, user_rule
-
These are the rules used to 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 below.
-
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, user_clear_cmd, user_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, but was blocked during the previous attempt. Obviously this
will not work if you previously blocked them with iptables, since they will
never be able to trigger this command. In this case, you can’t rely on pam_abl
to unblock them. One possibility would be to use special firewall chains which
can be cleared automatically with a script and a cron job.
host_block_cmd and user_block_cmd are run if the current attempt causes a
previously allowed host or user to be blocked.
Within the commands, you can specify substitutions with %h, %u and %s, which
will be replaced 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
its 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 [, ] or \, you need to escape them with a \.
-
host_whitelist, user_whitelist
-
A semi-colon separated list of hosts or 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 (1.1.1.1) or using a netmask (1.1.1.1/24)