1 files changed, 151 insertions, 0 deletions
diff --git a/doc/INSTRUCTION b/doc/INSTRUCTION
new file mode 100644
index 0000000..d4ffc69
--- /dev/null
+++ b/doc/INSTRUCTION
@@ -0,0 +1,151 @@
+
+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>		Log information to the given file (note the file is 
+    			appended to).
+			If not used, or is an illegal path, logging is to
+			stdout.
+
+    delete_log <path>	Logs deleted messages to the given file, which is
+    			appended to.
+			If not used, or is an illegal path, logging is to
+			$HOME/.kbs-deletelog.
+
+    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 delete_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.1.1.1 2003-12-04 01:54:55 ianc Exp $