=pod

=head1 NAME

B<ungrey-robins> - pf spamd auto-whitelister of round-robin SMTP clients

=head1 SYNOPSIS

B<ungrey-robins> [B<-d>] [B<-g> I<grace threshold>]

=head1 DESCRIPTION

B<ungrey-robins> assists postmasters by automatically whitelisting round robin
SMTP clients (which often fail to pass greylisting), without resorting to manual
maintenance of whitelists.

=head2 Normal Usage

Running B<ungrey-robins> at the same frequency as spamd(8)'s B<-G> I<greyexp>
period (4 hours by default) is entirely adequate. There is no benefit in
consuming CPU, I/O & network resources in running it more often.

=head2 Scheduling

Intermittent runs of the lightweight korn(1) shell script via cron(8) has proved
to be effective simplicity.

=head1 OPTIONS

=head2 -d

Run in debug mode.

=head2 -g I<grace threshold>

The threshold at which grace is granted to whitelist a spamdb(8) greylisted IP
address, which defaults to 7.

=head1 ENVIRONMENT

=over

=item DEBUG

Enable debugging when set to anything.

=back

=over

=item TMPDIR

Directory in which to place temporary files made with mktemp(1).
If unset, F</tmp> is used.

=back

=head1 FILES

F</etc/mail/ungrey-robins.ptrn> mandatory domains pattern file.

=head1 SECURITY

For unprivileged, non-root usage:

To both read and write to spamd(8)'s database file F</var/db/spamd>
via the spamdb(8) tool, it is suggested to run B<ungrey-robins> from the
C<_spamd> user's crontab(5).

The source code distribution contains an example F<crontab> file.

=head1 SEE ALSO

ungrey-robins.ptrn(5), spamd(8), spamdb(8), crontab(5), crontab(1), mktemp(1)

=head1 AVAILABILITY

For your convenience, the project offers:

=over

=item *

anonymous CVS source code access

=item *

anonymous HTTP access from L<http://web.Britvault.Co.UK/products/ungrey-robins/>

=item *

a mailing list for discussion & diffs

=back

The source code distribution F<README> file contains specifics.

While designed specifically for OpenBSD, it might function on Unix-like
pf spamd enabled OSs, such as NetBSD, FreeBSD, DragonFly BSD, etc.

=head1 LICENCE

B<ungrey-robins> has an ISC, or 'two-term BSD' styled open source copyright.
Refer to the F<LICENCE> file within the source distribution.

=head1 HISTORY

Craig Skinner developed B<ungrey-robins>, mostly in 2016.
The F<ChangeLog> file in the source distribution contains more information.

=cut