<reference>
    <title>@PACKAGE@ Sendmail milter - Version @VERSION@</title>
    <partintro>
        <title>Packages</title>

        <para>The various source and binary packages are available at <ulink
        url="http://www.five-ten-sg.com/@PACKAGE@/packages/">http://www.five-ten-sg.com/@PACKAGE@/packages/</ulink>
        The most recent documentation is available at <ulink
        url="http://www.five-ten-sg.com/@PACKAGE@/">http://www.five-ten-sg.com/@PACKAGE@/</ulink>
        </para>

        <para>A <ulink
        url="http://www.selenic.com/mercurial/wiki/">Mercurial</ulink> source
        code repository for this project is available at <ulink
        url="http://hg.five-ten-sg.com/@PACKAGE@/">http://hg.five-ten-sg.com/@PACKAGE@/</ulink>.
        </para>

    </partintro>

    <refentry id="@PACKAGE@.1">
        <refentryinfo>
            <date>2008-03-21</date>
        </refentryinfo>

        <refmeta>
            <refentrytitle>@PACKAGE@</refentrytitle>
            <manvolnum>1</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.1'>
            <refname>@PACKAGE@</refname>
            <refpurpose>a sendmail milter to add recipients to messages</refpurpose>
        </refnamediv>

        <refsynopsisdiv id='synopsis.1'>
            <title>Synopsis</title>
            <cmdsynopsis>
                <command>@PACKAGE@</command>
                <arg><option>-c</option></arg>
                <arg><option>-d <replaceable class="parameter">n</replaceable></option></arg>
                <arg><option>-p <replaceable class="parameter">sendmail-socket</replaceable></option></arg>
                <arg><option>-t <replaceable class="parameter">timeout</replaceable></option></arg>
            </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1 id='options.1'>
            <title>Options</title>
            <variablelist>
                <varlistentry>
                    <term>-c</term>
                    <listitem><para>
                        Load the configuration file, print a cannonical form
                        of the configuration on stdout, and exit.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term>-d <replaceable class="parameter">n</replaceable></term>
                    <listitem><para>
                        Set the debug level to <replaceable class="parameter">n</replaceable>.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term>-p <replaceable class="parameter">sendmail-socket</replaceable></term>
                    <listitem><para>
                        Set the socket used for the milter connection to sendmail. This is either
                        "inet:port@ip-address" or "local:local-domain-socket-file-name".
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term>-t <replaceable class="parameter">timeout</replaceable></term>
                    <listitem><para>
                        Set the timeout in seconds used for communication with sendmail.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </refsect1>

        <refsect1 id='usage.1'>
            <title>Usage</title>
            <para><command>@PACKAGE@</command> -c</para>
            <para><command>@PACKAGE@</command> -d 10 -p local:sm-archive.sock</para>
        </refsect1>

        <refsect1 id='installation.1'>
            <title>Installation</title>
            <para>
                This is now a standard GNU autoconf/automake installation, so the normal
                "./configure; make; su; make install" works.  "make chkconfig" will
                setup the init.d runlevel scripts.  Alternatively, you can use the
                source or binary RPMs at <ulink
                url="http://www.five-ten-sg.com/@PACKAGE@/packages">http://www.five-ten-sg.com/@PACKAGE@/packages</ulink>.
            </para>
            <para>
                Note that this has ONLY been tested on Linux, specifically RedHat Linux.
                You will need at a minimum a C++ compiler with a
                minimally thread safe STL implementation.  The distribution includes a
                test.cpp program.  If it fails this milter won't work.  If it passes,
                this milter might work.
            </para>
            <para>
                Modify your sendmail.mc by adding
                the following line in your sendmail.mc and rebuild the .cf file
            </para>
            <para><screen>INPUT_MAIL_FILTER(`sm-archive', `S=local:/var/run/sm-archive/sm-archive.sock, F=T, T=C:30s;S:5m;R:5m;E:5m')</screen></para>
            <para>
                Modify the default <citerefentry>
                <refentrytitle>@PACKAGE@.conf</refentrytitle> <manvolnum>5</manvolnum>
                </citerefentry> configuration.
            </para>
        </refsect1>

        <refsect1 id='configuration.1'>
            <title>Configuration</title>
            <para>
                The configuration file is documented in <citerefentry>
                <refentrytitle>@PACKAGE@.conf</refentrytitle> <manvolnum>5</manvolnum>
                </citerefentry>.  Any change to the config file, or any file included
                from that config file, will cause it to be reloaded within three
                minutes.
            </para>
        </refsect1>

        <refsect1 id='introduction.1'>
            <title>Introduction</title>
            <para>
                Consider the problem of archiving all the mail sent to or from particular
                email addresses or domains. This milter allows you to configure archive
                mailboxes for each address or domain. It will add the address of the archive
                mailbox to messages that pass thru this milter.
            </para>
            <para>
                The archive milter reads a text configuration file (sm-archive.conf) on
                startup, and whenever the config file (or any of the referenced include
                files) is changed.  The entire configuration file is case insensitive.
                If the configuration cannot be loaded due to a syntax error, the milter
                will log the error and quit.  If the configuration cannot be reloaded
                after being modified, the milter will log the error and send an email to
                root from sm-archive@$hostname.  You probably want to added sm-archive@$hostname
                to your /etc/mail/virtusertable since otherwise sendmail will reject
                that message.
            </para>
        </refsect1>

        <refsect1 id='todo.1'>
            <title>TODO</title>
            <para>
                Placeholder for future ideas.
            </para>
        </refsect1>

        <refsect1 id='copyright.1'>
            <title>Copyright</title>
            <para>
                Copyright (C) 2007 by 510 Software Group &lt;carl@five-ten-sg.com&gt;
            </para>
            <para>
                This program is free software; you can redistribute it and/or modify it
                under the terms of the GNU General Public License as published by the
                Free Software Foundation; either version 3, or (at your option) any
                later version.
            </para>
            <para>
                You should have received a copy of the GNU General Public License along
                with this program; see the file COPYING.  If not, please write to the
                Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
            </para>
        </refsect1>

        <refsect1 id='version.1'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>
    </refentry>


    <refentry id="@PACKAGE@.conf.5">
        <refentryinfo>
            <date>2008-03-21</date>
        </refentryinfo>

        <refmeta>
            <refentrytitle>@PACKAGE@.conf</refentrytitle>
            <manvolnum>5</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.5'>
            <refname>@PACKAGE@.conf</refname>
            <refpurpose>configuration file for @PACKAGE@ sendmail milter</refpurpose>
        </refnamediv>

        <refsynopsisdiv id='synopsis.5'>
            <title>Synopsis</title>
            <cmdsynopsis>
                <command>@PACKAGE@.conf</command>
            </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1 id='description.5'>
            <title>Description</title>
            <para>The <command>@PACKAGE@.conf</command> configuration file is
            specified by this partial bnf description.</para>

            <literallayout class="monospaced"><![CDATA[
CONFIG     = {ENV-FROM ENV-TO}+
ENV-FROM   = env_from "{" LIST "}" ";"
ENV-TO     = rcpt_to  "{" LIST "}" ";"
LIST       = ELEMENT {LIST}+
ELEMENT    = ADDRESS TARGET ["remove"] ";"
ADDRESS    = (USER@ | DOMAIN | USER@DOMAIN)
TARGET     = ("" | USER@DOMAIN)]]></literallayout>
        </refsect1>

        <refsect1 id='sample.5'>
            <title>Sample</title>
            <literallayout class="monospaced"><![CDATA[
env_from {
    fred@example.com    manager@example.com;
    example.com         archive@example.com;

    # suppress archiving for joe
    joe@example.com     "";
};

rcpt_to {
    fred@example.com    manager@example.com;

    # sam does not get a copy
    sam@example.com     manager@example.com remove;
};]]></literallayout>
        </refsect1>

        <refsect1 id='version.5'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>

    </refentry>
</reference>