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:

*db_home*::
Specify the directory where the Berkeley db
can store it's lock and log files. Make sure
this dir exists and is writable.

*limits*::
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".

*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*::
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. 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 '[', ']' or '\', you need to escape them with a '\'.

*host_whitelist, user_whitelist*::
;-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 (1.1.1.1) or using a netmask (1.1.1.1/24)

EXAMPLE
-------

----------------------------
# /etc/security/pam_abl.conf  
debug                         
host_db=/var/lib/abl/hosts.db 
host_purge=2d                 
host_rule=*:10/1h,30/1d       
host_block_cmd=[/sbin/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_clear_cmd=[/usr/bin/logger] [block] [user] [%u]
----------------------------

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>
