After installation you will need to configure your MTA to use the milter. To do
this please consult your MTA documentation regarding milters.

We recommend you do NOT run ArchiveSMTP as root. You should create or select an
unprivileged user to run as and create a directory writable ONLY by that user
to store pidfile and socket (assuming using unix or local sockets). Sendmail
will NOT connect to a filter that uses a socket in a directory that is writable
by group or all.

A configuration file is required. The config file contains a list of rules. Each
rule has the following format:

{ TEST_LIST } ACTION_LIST;

Where TEST_LIST describes the tests a mail must pass and ACTION_LIST describes
the actions taken should it pass. Actions that produce output are in mbox format.
All tests may be negated using the exclaimation mark syntax, including brackets
(eg. !Sender, !(cond1 and cond2), etc).

A test follows the following format:

FIELD_TO_TEST LOCATION_IN_FIELD TEST_TEXT

So for example, a test might be:

Sender starts "Fred"

Valid values for FIELD_TO_TEST are:
    Sender - The username of the sender from SMTP Auth (or null if not auth'd).
    From   - The "From:" address in the mail header.
    To     - All recipient addresses, including "To:", "Cc:" and "Bcc:".
Note: Sender is CASE sensitive, the others are not.
	
Valid values for LOCATION_IN_FIELD are:
    Starts   - Test matches the start of the string.
    Ends     - Test matches the end of the string.
    Contains - Test matches any part of the string.
    Is       - Test and string must be exactly the same.

TEST_TEXT is a string. By default it is delineated by whitespace, but you can
use double quotes(") to prevent this and backslash(\) escapes are honoured.

There are also two special tests that require no location or test string:
    Not Matched - Will match if no previous rule has matched the mail.
    Match All   - Will match everything.

The ACTION_LIST is a list of comma(,) separated actions to take should the rule
match the input e-mail. The list is terminated by a semi-colon(;). Each rule
MUST have at least one action.

An action has the following format:

ACTION_TYPE ARGUMENTS

For example:

Store In "/path/to/file"

Valid values for ACTION_TYPE are:
    Store In   - On match the e-mail should be stored in the file given in ARG.
               * ARGUMENT must be a valid path including the file name.
    Add Header - On match the header given in ARG will be added to the e-mail.
               * ARGUMENT must be in the format "field:value".
    Pipe       - On match the e-mail data will be piped to the program in ARG.
               * ARGUMENT must be an executable program with required flags.
    Halt       - On match no further rules will be tested.
               * Has no arguments.

The action ARGUMENTS are a single case sensitive string, you can enclose them
in double quotes(") to include whitespace characters. Characters can also be
escaped by with backslash(\). Token substitution is provided for in all action
arguments, you may use as many tokens as you wish. Tokens must be in UPPERCASE
between percent(%) characters.

Supported tokens are:
    %%       - A literal % is inserted.
    %SENDER% - Username of the sender is inserted if set, otherwise nothing.
    %FROM%   - The from address is inserted.
    %TO%     - The FIRST matched to address is inserted. *Note: This token will
               be EMPTY unless at least one To test matches something.
	%ALLTO%  - This is a special case token and will cause the rule action that
               uses this token to be run once for every to address that can be
               matched by the rule, substituting a different address each pass.
               *Note: This token will be EMPTY unless at least one To test
               matches something.
Note: All tokens also support .USER and .DOMAIN specifiers which will cause them
to insert only the part before (user) or after (domain) the @ symbol (eg. if the
to address is foo@bar.com then %TO.DOMAIN% would insert 'bar.com' while 
%TO.USER% would insert 'foo').

You can use multiple conditions to create more complex expressions using the Or
and And keywords as well as bracket grouping. Multiple actions can specified
with comma separators. For example:

To starts "Fred" and From starts "Joe"

is valid. "and" and "or" both work. You can also use brackets:

{ Sender contains "Bloggs" and (To starts "Fred" or !From ends "Green") } store
in /maillogs/%SENDER.USER%.mbox, pipe "procmail", halt;

is a valid rule.

Please consult the man page (archivesmtp) for command line arguments and
invocations.
