PAM_AF_TOOL(8)

NAME
pam_af_tool - pam_af(8) module control utility

SYNOPSIS
pam_af_tool ruleadd -h host -a attempts -t time [-l -cmd] [-u -cmd] [-r -file] [-v]
pam_af_tool rulemod -h host [-a attempts] [-t time] [-l -cmd] [-u -cmd] [-r -file] [-v]
pam_af_tool ruledel -h host [-r -file] [-v]
pam_af_tool rulelist [-r -file]
pam_af_tool ruleflush [-r -file] [-v]
pam_af_tool statdel -h host [-s -file] [-v]
pam_af_tool statlist [-s -file]
pam_af_tool statflush [-s -file] [-v]
pam_af_tool lock [-h host] [-s -file] [-r -file] [-fv]
pam_af_tool unlock [-h host] [-s -file] [-r -file] [-fv]

DESCRIPTION
The pam_af_tool utility can be used to control different aspects of the pam_af(8) PAM module's logic. It can add/list/delete host-specific rules, list/delete the module's internal statistics, lock/unlock given hosts and so on. The following commands are available:

ruleadd
    Add rule for the given host to the configuration database. The maximal auth attempts count must be specified using the “-a” option. Use the “unlimited” keyword to allow unlimited number of attempts. You must also give the locking period with the “-t” option. The time must be in the form like “10y16H10M”, i.e. the sequence of expressions “#c”, where “#” - decimal integer and “c” - conversion specification. The list includes: y - for years, m - for mounts, d - days, H - hours, M - minutes and S for seconds. You may omit S specificator - it is the default conversion.

    The lock command can be specified with “-l” flag. Use “-u” to give the unlock command.

rulemod
    Modify the given parameters for the host's rule in the configuration database.

ruledel
    Delete rule from the configuration database.

rulelist
    List all rules.

ruleflush
    Flush all rules.

statdel
    Delete statistics on the given host.

statlist
    List the entire statistics.

statflush
    Flush statistics.

lock
    Lock the specified host. If the hostname isn't given the pam_af_tool utilty will lock all hosts with max attempts count exceeded. Specify the “-f” option to force the host locking.

unlock
    Unlock the specified host. If the hostname isn't given the pam_af_tool utilty will unlock all hosts that have bypassed locktime already. Specify the “-f” option to force the host unlocking.

Available options:

-r file
    use file as the configuration database.

-s file
    use file as the statistics database.

-f  force the operation to be completed.

-v  be more verbose.

EXIT STATUS
The pam_af_tool utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
Add rule to limit the maximail fail auth attempts to 5 with 15 minutes locktime:

    pam_af_tool ruleadd -h '*' -a 5 -t 15M

The following command can be used in FreeBSD to block “bad” hosts by firewall:

    pam_af_tool ruleadd -h 207.46.0.0/16 -a 5 -t 15H -l '/sbin/ipfw add 100 deny all from $PAM_RHOST to any'

Change attempts limit to 15 for default rule:

    pam_af_tool rulemod -h '*' -a 15M

Delete rule for “127.0.0.1”:

    pam_af_tool ruledel -h 127.0.0.1

List internal per-host statistics:

    pam_af_tool statlist

Delete staticstics for localhost:

    pam_af_tool statdel -h localhost

Unlock all hosts that must be unlocked:

    pam_af_tool unlock -f

This can be used, for example, in cron to periodicaly unlock hosts, that cannot be processed by the pam_af(8) module, e.g. when they are blocked by firewall.

SEE ALSO
pam_af(8), ipfw(8), dbm(3), syslog(3), pam.conf(5), pam(8)

BUGS
In lock and unlock commands of the pam_af_tool utility only the PAM_RHOST enviropment variable would be set when executing external program.

AUTHORS
The pam_af_tool utility and this manual page was written by Stanislav Sedov <stas@FreeBSD.org>.