bionic (5) pam_abl.conf.5.gz

Provided by: libpam-abl_0.6.0-5_amd64 bug

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>

AUTHOR

       Chris Tasma
           Author.