bf663cc26b
responsible for repeated failed authentication attempts. WWW: http://www.hexten.net/pam_abl/ PR: ports/100635 Submitted by: Petr Rehor <prehor@gmail.com>
270 lines
8 KiB
Groff
270 lines
8 KiB
Groff
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd January 14, 2006
|
|
.Dt pam_abl 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pam_abl
|
|
.Nd auto blacklist PAM module
|
|
.Sh SYNOPSIS
|
|
.Ss Auto Blacklist PAM module
|
|
.Op Ar service-name
|
|
.Ar module-name
|
|
.Ar control-flag
|
|
.Pa pam_abl
|
|
.Op Ar options
|
|
.Ss Blacklist maintenance tool
|
|
.Nm
|
|
.Op Fl h | Fl -help
|
|
.Op Fl p | Fl -purge
|
|
.Op Fl r | Fl -relative
|
|
.Op Fl v | Fl -verbose
|
|
.Op Fl -okhost Ns No = Ns Ar host
|
|
.Op Fl -okuser Ns No = Ns Ar user
|
|
.Op Ar config-file
|
|
.Sh DESCRIPTION
|
|
The Auto Blacklist module for PAM,
|
|
.Nm
|
|
provides functionality for only one PAM category: authentication.
|
|
In terms of the
|
|
.Ar module-type
|
|
parameter, this is the
|
|
.Dq Li auth
|
|
feature.
|
|
.Ss Auto Blacklist PAM Authentication Module
|
|
.Nm
|
|
provides auto blacklisting of hosts and users responsible for repeated
|
|
failed authentication attempts. Generally configured so that blacklisted
|
|
users still see normal login prompts but are guaranteed to fail to
|
|
authenticate. This functionality is only available to services which call
|
|
PAM as root. If
|
|
.Nm
|
|
is called for uid != 0 it will silently succeed.
|
|
|
|
The following options may be passed to the authentication module:
|
|
.Bl -tag -width indent
|
|
.It Cm debug
|
|
.Xr syslog 3
|
|
debugging information at
|
|
.Dv LOG_DEBUG
|
|
level.
|
|
.It Cm expose_account
|
|
Ignored.
|
|
.It Cm no_warn
|
|
suppress warning messages to the user.
|
|
These messages include reasons why the user's authentication attempt was
|
|
declined.
|
|
.It Cm try_first_pass
|
|
Ignored.
|
|
.It Cm use_first_pass
|
|
Ignored.
|
|
.It Cm use_mapped_pass
|
|
Ignored.
|
|
.It Cm config Ns No = Ns Ar config-file
|
|
The configuration file contains additional arguments. In order for the
|
|
.Nm
|
|
blacklist maintenance tool to work correctly most of the configuration
|
|
should be placed in the config file rather than being provided by arguments.
|
|
The format of the config file is described below.
|
|
.It Cm host_db Ns No = Ns Ar host-database-file
|
|
Path to the Berkeley DB which is used to log the host responsible for failed
|
|
authentication attempts.
|
|
If host_db is omitted the corresponding auto blacklisting will be disabled.
|
|
.It Cm host_purge Ns No = Ns Ar time
|
|
Defines how long failed hosts are retained in the host database.
|
|
Defaults to 1 day.
|
|
.It Cm host_rule Ns No = Ns Ar host-rule
|
|
The rule (see below for format) which defines the conditions under which a
|
|
failed hosts will be blackisted.
|
|
.It Cm user_db Ns No = Ns Ar user-database-file
|
|
Path to the Berkeley DB which is used to log the user responsible for failed
|
|
authentication attempts.
|
|
If user_db is omitted the corresponding auto blacklisting will be disabled.
|
|
.It Cm user_purge Ns No = Ns Ar time
|
|
Defines how long failed users are retained in the user database.
|
|
Defaults to 1 day.
|
|
.It Cm user_rule Ns No = Ns Ar user-rule
|
|
The rule (see below for format) which defines the conditions under which a
|
|
failed users will be blackisted.
|
|
.El
|
|
.Ss Rules syntax
|
|
.Cm host_rule No Cm user_rule
|
|
are the rules which determine the circumstances under which accounts ares
|
|
auto blacklisted.
|
|
The
|
|
.Cm host_rule
|
|
is used to block access to hosts that are responsible for excessive
|
|
authentication failures and the
|
|
.Cm user_rule
|
|
is used to disable accounts for which there have been excessive
|
|
authentication failures.
|
|
Each rule consists of a number of space separated
|
|
.Sy user clauses Ns No .
|
|
A
|
|
.Sy user clause
|
|
specifies the user names and services to match and a set of triggers.
|
|
A simple example would be:
|
|
.Bd -literal -offset indent
|
|
*:10/1h
|
|
.Ed
|
|
.Pp
|
|
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:
|
|
.Bd -literal -offset indent
|
|
root|dba|admin:10/1h
|
|
.Ed
|
|
.Pp
|
|
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:
|
|
.Bd -literal -offset indent
|
|
root/sshd|dba/*:3/1d
|
|
.Ed
|
|
.Pp
|
|
which means 'block the users root for service sshd and user 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:
|
|
.Bd -literal -offset indent
|
|
root:10/1h,20/1d
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Multiple rules can be provided separated by spaces like this:
|
|
.Bd -literal -offset indent
|
|
*:10/1h root:5/1h,10/1d
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The sense of the user matching can be inverted by placing a '!' in front
|
|
of the rule so that:
|
|
.Bd -literal -offset indent
|
|
!root:20/1d
|
|
.Ed
|
|
.Pp
|
|
is a rule which would match for all users apart from root.
|
|
.Pp
|
|
It is important to treat root as a special case in the
|
|
.Cm 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.
|
|
.Pp
|
|
Here is the full syntax for rules:
|
|
.Bd -literal -offset indent
|
|
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
|
|
.Ed
|
|
.Pp
|
|
For rules to work correctly
|
|
.Cm host_purge No and Cm user_purge
|
|
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
|
|
.Nm
|
|
blacklist maintenance tool can report information over a longer period of
|
|
time.
|
|
The format for this items 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
|
|
.Nm
|
|
PAM module 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
|
|
.Nm
|
|
blacklist maintenance tool should be used.
|
|
.Ss Blacklist maintenance tool
|
|
Blacklist maintenance tool
|
|
.Nm
|
|
perform maintenance on the databases used by the
|
|
.Nm
|
|
PAM module.
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl h | Fl -help
|
|
Print help page and exit.
|
|
.It Fl p | Fl -purge
|
|
Purge databases according to purge rules in config.
|
|
.It Fl r | Fl -relative
|
|
Display times relative to now otherwise absolute times will be displayed.
|
|
.It Fl v | Fl -verbose
|
|
Verbose output.
|
|
.It Fl -okhost Ns No = Ns Ar host-name
|
|
Unblock host.
|
|
.It Fl -okuser Ns No = Ns Ar user-name
|
|
Unblock user.
|
|
.It Ar config-file
|
|
Name of the
|
|
.Nm
|
|
configuration file (default: %%ETCPREFIX%%/etc/pam_abl.conf).
|
|
The config file is read to discover the names of the
|
|
.Nm
|
|
databases and the rules that control purging of old data from them.
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Ss Auto Blacklist PAM module
|
|
Typically
|
|
.Nm
|
|
PAM module is added to the auth stack as a required module just before
|
|
whatever modules actually peform authentication.
|
|
Here's a fragment of the PAM config:
|
|
.Bd -literal -offset indent
|
|
auth required pam_env
|
|
auth required pam_abl config=%%ETCPREFIX%%/etc/pam_abl.conf
|
|
auth sufficient pam_unix likeauth nullok
|
|
auth required pam_deny
|
|
.Ed
|
|
.Ss Blacklist maintenance tool
|
|
Obtain a list of failed hosts and users:
|
|
.Bd -literal -offset indent
|
|
$ pam_abl
|
|
.Ed
|
|
.Pp
|
|
Obtain a full list of failures listing times relative to now:
|
|
.Bd -literal -offset indent
|
|
$ pam_abl -rv
|
|
.Ed
|
|
.Pp
|
|
Purge old data:
|
|
.Bd -literal -offset indent
|
|
$ pam_abl -p
|
|
.Ed
|
|
.Pp
|
|
Unblock all example.com hosts and all users:
|
|
.Bd -literal -offset indent
|
|
$ pam_abl -v --okhost='*.example.com' --okuser='*'
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr pam.conf 5 ,
|
|
.Xr pam 8
|
|
.Bd -literal
|
|
http://www.hexten.net/pam_abl/
|
|
http://sourceforge.net/project/showfiles.php?group_id=148927
|
|
.Ed
|
|
.Sh AUTHORS
|
|
Written by Andy Armstrong <andy@hexten.net>.
|
|
.Sh BUGS
|
|
Report bugs to Andy Armstrong <andy@hexten.net>.
|