=pod

=head1 NAME

B<spamdba> - pf spamd database assistant

=head1 SYNOPSIS

B<spamdba> [-hv] (add|delete|dump|load) [-l] (-stw) [-p pattern] [-f F<file>]

=head1 DESCRIPTION

B<spamdba> assists postmasters to routinely manipulate the spamd(8) database.
This tool is a wrapper for spamdb(8), simplifying common tasks, such as:-

=over

=item *

Adding/deleting of all, or a pattern matched subset of entries.

=item *

Dumping & loading - for OS upgrades, database format changes,
sharing data between different architecture/OS machines, etc.

=back

=head1 OPTIONS

=head2 -h, -?

Show a help summary of options and exit.

=head2 -v

Show version and exit.

=head2 add

Add entries via spamdb(8).

=head2 delete

Delete entries via spamdb(8).

=head2 dump

Dump (export) the spamdb(8) database.

=head2 load

Load (import) entries from a B<dump>ed spamdb(8) database.

=head2 -l

Generate a log file.

=head2 -s 

Add or delete I<SPAMTRAP> entries.

=head2 -t

Add or delete I<TRAPPED> entries.

=head2 -w

Add or delete I<WHITE> entries.

=head2 -p

Pattern to match with grep(1)

=head2 -f F<file>

A F<file> containing a list of single IP addresses I<or> email addresses to
add or delete. Blank and comment lines beginning with C<#> are ignored.


=head1 FILES

F</etc/mail/spamd.trap-addresses> optional default trap address list

=head1 SECURITY

Suggestions for unprivileged, non-root usage:

=over

=item *

add a group, such as C<postmasters> or C<mailadmins>

=item *

add suitable members to that group

=item *

make F</var/db/spamd> writable by that group

=back

I<Example> commands could include:

	you$ ls -l /var/db/spamd
	you$ sudo cp -p /var/db/spamd /var/db/spamd~
	you$ sudo groupadd postmasters
	you$ sudo usermod -G postmasters you
	you$ sudo chgrp postmasters /var/db/spamd
	you$ sudo chmod g+w /var/db/spamd
	you$ sudo chmod o-r /var/db/spamd
	you$ ls -l /var/db/spamd*
	-rw-rw----  1 _spamd  postmasters  212992 Mar 31 15:07 /var/db/spamd
	-rw-r--r--  1 _spamd  _spamd       212992 Mar 31 15:07 /var/db/spamd~

You may also want to grant the same group write
privileges to F</etc/mail/spamd.trap-addresses>, e.g:

	-rw-rw----  1 postmaster  postmasters  16955 Mar 28 20:11 /etc/mail/spamd.trap-addresses

=head1 EXAMPLES

Delete spam trap addresses, limiting to a pattern, and with logging:

	you$ spamdba delete -l -s -p '@britvault.co.uk$'
	Processed: 257
	Log: /tmp/spamdba_delete_SPAMTRAP.log.53YIYA6

Add spam trap addresses not already loaded,
from the default file F</etc/mail/spamd.trap-addresses>:

	you$ spamdba add -s
	Processed: 257

Runs to delete all spam trap addresses,
and then add in those matching a pattern:

	you$ spamdba delete -s
	Processed: 515
	you$ spamdba add -l -s -p jun-2006
	Processed: 470
	Log: /tmp/spamdba_add_SPAMTRAP.log.Phpqt3Z

Delete whitelisted hosts in a net block pattern:

	you$ spamdba delete -l -w -p '^157.55.'
	Processed: 14
	Log: /tmp/spamdba_delete_WHITE.log.Ou7QbA7

Whoops! Re-whitelist those hosts again:
 
	you$ spamdba add -w -f /tmp/spamdba_delete_WHITE.log.Ou7QbA7
	Processed: 14

Dump on one host & load on another of a different architecture:

	you@primary-mx sparc64$ spamdba dump
	Dump: /tmp/spamdba.dump.a26SCL9

	you@mx-backup i386$ spamdba load -f ~/spamdba.dump
	Processed: 515
	Log: /tmp/spamdba_add_SPAMTRAP.log.JsieTX8
	Processed: 1100
	Log: /tmp/spamdba_add_TRAPPED.log.ej7gp1B
	Processed: 241
	Log: /tmp/spamdba_add_WHITE.log.Ru65NEp


=head1 SEE ALSO

spamdb(8), spamd(8)

=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/spamdba/>

=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 VERSION

This page documents B<spamdba> version I<1.0.3>

=head1 LICENCE

B<spamdba> 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 spamdba, mostly in 2013-2014.
He packaged it for OpenBSD in 2014. The F<ChangeLog> file in
the source distribution contains more information.

=cut