Usage
=====

    kbs


Description
===========

kbs works on the simple premise that most people know who will be sending them
email, or at least have a few trusted domains.  It also makes it easy for
a special keyword in a subject header to be used.


Config file format
==================

The kbs config file is read from $HOME/.kbsrc and is in the form:

[config settings]

[trusted settings]

[domain settings]

Note it is *highly* recommended to set .kbsrc to be only readable by the
user - this is as passwords are stored in there.

Blank lines and text proceeded with a hash (#) are ignored.

Each token is delimited with white space - if the value you want to use
includes spaces, simple quote them (with either single or double quotes).

Note that escapes aren't used (to make regular expression writing easier), so
if you want to include a quote in a string, simply use the other sort of quote.
If you want both, you're stuck!

To see and example kbsrc file, see kbsrc in the src directory.


Config settings
===============

The config settings are in the general form:

    set variable=value

And understand the following variables:


    hostname <FQDN>	The Fully Qualified Domain Name of the POP3 server.
			Defaults to localhost.

    port <port number>	The port number to connect to.
			Defaults to 110.

    username <username>	The username to give to the server.
			Defaults to guest.

    password <username>	The password to give to the server.
			Defaults to an empty string.

    log <path>		Logs deleted messages to the given file, which is
    			appended to.  Note that non-deletion diagnostics go to
			stderr.
			If not used, or is an illegal path, logging is to
			$HOME/.kbs-deletelog unless the variable is set to
			a dash (-), in which case logging is disabled.

    verbose <on|off>	Whether logging is verbose.  If it's verbose then
    			the username, subject and a tailing report is generated.
			If logging is not verbose, then just usernames are
			logged.
			Defaults to verbose (on).

    timeout <seconds>	Number of seconds to allow for no response from the
    			server.
			Defaults to 60 seconds.

    casesense <on|off>	Whether regular expressions are case sensitive.
			Defaults to case insensitive (off).

    dejunk <on|off>	Whether subjects are dejunked before checking.
    			Dejunking here means that anything an alphanumeric
			character is stripped, and all contiguos white space
			is reduced to one space.
			Defaults to off.

    blockhtml <on|off>	Whether messages that are pure HTML (content part just
    			reported as "text/html" are blocked.
			Defaults to off.

    testmode <on|off>	Whether things will be really deleted, or just
    			the actions logged.  Note that the log is still
			filled out as if the deletion occured.
			Defaults to off, though it is recommended to use this
			for early runs to ensure your rules are not too harsh
			(or too easy for that matter).


Trusted settings
================

These define users and domains for which mail is let thorugh, regardless of
other tests.

    trusted_users
    {
    	username
	[username]
    }

    trusted_domains
    {
    	domain
	[domain]
    }


Domain settings
===============

These define the rules applied to a certain domain.  Note the order these
appear in is important, as the first match when checking domain names will
be used.

    domain <regular expression>
    {
	[default block|allow]
    	[block_user <username>]
    	[allow_subject <regular expression>]
	[block_subject <regular expression>]
    }

The default says what to do if neither the allow_subject or block_subject are
matched.  If not specified, the default is to allow.

The block user allows a specific username to be blocked.  For instance, I've
noticed that spammers have a great love of emailing from your username at
a different domain.

The allow_subject means that subjects that match that regular expression are
always let through.

The block_subject means that subjects that match that regular expression are
always blocked and deleted.

Note that multiple allow_subject and block_subject commands can be in one
domain.


-------------------------------------------------------------------------------
$Id: INSTRUCTION,v 1.2 2003-12-05 02:33:05 ianc Exp $