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

*: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: