PAM_ABL.CONF(5)
==============
:man source: GNU
:man manual: Linux-PAM Manual
:author: Chris Tasma

NAME
----

pam_abl.conf - Configuration file for pam_abl PAM module.

SYNOPSIS
--------

Configuration file for both the pam_abl(8) PAM module, and the pam_abl(1) command line tool.

DESCRIPTION
-----------

Syntax
~~~~~~

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

Rule syntax
~~~~~~~~~~~

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:

*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 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 below.                      

*host_clr_cmd, host_blk_cmd, user_clr_cmd, user_blk_cmd*::
These specify commands that will run during a check when an item switches
state since its last check. +
host_clr_cmd and user_clr_cmd will run if the host or user is currently allowed
access.  host_blk_cmd and user_blk_cmd are run if the host or user is
currentlybeing blocked by their respective rules.  If no command is specified,
no action is taken. +
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.  If there isn't enough information to fulfill the requested
substitutions (eg. running the pam_abl tool without specifying all the
necessary fields), the command will simply not run.

EXAMPLE
-------

----------------------------
# /etc/security/pam_abl.conf  
debug                         
host_db=/var/lib/abl/hosts.db 
host_purge=2d                 
host_rule=*:10/1h,30/1d       
host_blk_cmd=iptables -I INPUT -s %h -j DROP
user_db=/var/lib/abl/users.db 
user_purge=2d                 
user_rule=!root:10/1h,30/1d   
user_clr_cmd=logger This is a pointless command! user: %u host: %h service: %s
----------------------------

SEE ALSO
--------

pam_abl.conf(5), pam_abl(1)

AUTHORS
-------

Andy Armstrong <andy@hexten.net> +

Chris Tasma <pam-abl@deksai.com>
