.\" Title: pam_abl.conf
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.74.0
.\" Date: 01/13/2010
.\" Manual: Linux-PAM Manual
.\" Source: GNU
.\" Language: English
.\"
.TH "PAM_ABL\&.CONF" "5" "01/13/2010" "GNU" "Linux\-PAM Manual"
.\" -----------------------------------------------------------------
.\" * (re)Define some macros
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" toupper - uppercase a string (locale-aware)
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de toupper
.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
\\$*
.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SH-xref - format a cross-reference to an SH section
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de SH-xref
.ie n \{\
.\}
.toupper \\$*
.el \{\
\\$*
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SH - level-one heading that works better for non-TTY output
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de1 SH
.\" put an extra blank line of space above the head in non-TTY output
.if t \{\
.sp 1
.\}
.sp \\n[PD]u
.nr an-level 1
.set-an-margin
.nr an-prevailing-indent \\n[IN]
.fi
.in \\n[an-margin]u
.ti 0
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.\" make the size of the head bigger
.ps +3
.ft B
.ne (2v + 1u)
.ie n \{\
.\" if n (TTY output), use uppercase
.toupper \\$*
.\}
.el \{\
.nr an-break-flag 0
.\" if not n (not TTY), use normal case (not uppercase)
\\$1
.in \\n[an-margin]u
.ti 0
.\" if not n (not TTY), put a border/line under subheading
.sp -.6
\l'\n(.lu'
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SS - level-two heading that works better for non-TTY output
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de1 SS
.sp \\n[PD]u
.nr an-level 1
.set-an-margin
.nr an-prevailing-indent \\n[IN]
.fi
.in \\n[IN]u
.ti \\n[SN]u
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.ps \\n[PS-SS]u
.\" make the size of the head bigger
.ps +2
.ft B
.ne (2v + 1u)
.if \\n[.$] \&\\$*
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" BB/BE - put background/screen (filled box) around block of text
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de BB
.if t \{\
.sp -.5
.br
.in +2n
.ll -2n
.gcolor red
.di BX
.\}
..
.de EB
.if t \{\
.if "\\$2"adjust-for-leading-newline" \{\
.sp -1
.\}
.br
.di
.in
.ll
.gcolor
.nr BW \\n(.lu-\\n(.i
.nr BH \\n(dn+.5v
.ne \\n(BHu+.5v
.ie "\\$2"adjust-for-leading-newline" \{\
\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
.\}
.el \{\
\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
.\}
.in 0
.sp -.5v
.nf
.BX
.in
.sp .5v
.fi
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" BM/EM - put colored marker in margin next to block of text
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de BM
.if t \{\
.br
.ll -2n
.gcolor red
.di BX
.\}
..
.de EM
.if t \{\
.br
.di
.ll
.gcolor
.nr BH \\n(dn
.ne \\n(BHu
\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
.in 0
.nf
.BX
.in
.fi
.\}
..
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "Name"
pam_abl.conf \- Configuration file for pam_abl PAM module\&.
.SH "Synopsis"
.sp
Configuration file for both the pam_abl(8) PAM module, and the pam_abl(1) command line tool\&.
.SH "DESCRIPTION"
.SS "Syntax"
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
word ::= /[^\es\e|\e/\e*]+/
name ::= word | \'*\'
username ::= name
servicename ::= name
userservice ::= username
| username \'/\' servicename
namelist ::= userservice
| userservice \'|\' namelist
userspec ::= namelist
| \'!\' namelist
multiplier ::= \'s\' | \'m\' | \'h\' | \'d\'
number ::= /\ed+/
period ::= number
| number multiplier
trigger ::= number \'/\' period
triglist ::= trigger
| trigger \',\' triglist
userclause ::= userspec \':\' triglist
rule ::= userclause
| userclause /\es+/ rule
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.SS "Rule syntax"
.sp
Each rule consists of a number of space separated \fIuser clauses\fR\&. A user clause specifies the user (and service) names to match and a set of triggers\&. A simple example would be
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
*:10/1h
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
which means \fIblock any user (\fR\fI\fB) if they are responsible for ten or more failed authentication attempts in the last hour\fR\fR\fI\&. In place of the \fR\fI\fR which matches any user a list of usernames can be supplied like this
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
root|dba|admin:10/1h
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
which means \fIblock the users root, dba and admin if they are responsible for ten or more failed authentication attempts in the last hour\fR\&. You can also specify a service name to match against like this
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
root/sshd|dba/*:3/1d
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
which means \fIblock the users root for service \'sshd\fR 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
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
root:10/1h,20/1d
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
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\&.
.sp
Multiple rules can be provided separated by spaces like this
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
*:10/1h root:5/1h,10/1d
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
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 \fI!\fR in front of the rule so that
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
!root:20/1d
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
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 \fI#\fR 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:
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
# /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
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.sp
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\&.
.sp
The arguments that are specific to the PAM module are as follows:
.PP
\fBhost_db, user_db\fR
.RS 4
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\&.
.RE
.PP
\fBhost_purge, user_purge\fR
.RS 4
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,
\fIs\fR,
\fIm\fR,
\fIh\fR
or
\fId\fR
which correspond with seconds, minutes, hours and days\&. To specify seven days for example one would use
\fI7d\fR\&. 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\&.
.RE
.PP
\fBhost_rule, user_rule\fR
.RS 4
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\&.
.RE
.PP
\fBhost_clr_cmd, host_blk_cmd, user_clr_cmd, user_blk_cmd\fR
.RS 4
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\(cqt 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\&.
.RE
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.BB lightgray
# /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
.EB lightgray
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
pam_abl\&.conf(5), pam_abl(1)
.SH "AUTHORS"
.sp
Andy Armstrong
.sp
Chris Tasma