\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename anubis.info
@settitle GNU Anubis Manual
@setchapternewpage odd
@finalout
@c %**end of header
@include version.texi
@include rendition.texi
@smallbook

@defcodeindex op
@defcodeindex cm
@syncodeindex fn cp

@copying
Copyright @copyright{} 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2011, 2014
Wojciech Polak and Sergey Poznyakoff.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying

@ifinfo
@dircategory Email
@direntry
* Anubis: (anubis).                   The GNU SMTP message submission daemon.
* anubis: (anubis) Invoking Anubis.   Anubis command line summary.
* anubisadm: (anubis) Administrators. Administration of the Anubis User Database. 
* anubisusr: (anubis) Users.          User interface to the Anubis User Database.
@end direntry
@end ifinfo

@titlepage
@title GNU Anubis
@subtitle An SMTP message submission daemon.
@subtitle GNU Anubis Version @value{VERSION}
@subtitle @value{UPDATED}
@author Wojciech Polak and Sergey Poznyakoff

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@page
@contents
@end ifnothtml

@ifnottex
@node Top
@top GNU Anubis
This edition of the @cite{GNU Anubis Manual}, last updated @value{UPDATED},
documents GNU Anubis Version @value{VERSION}.
@end ifnottex

@menu
* Overview::                        Program Overview.
* Glossary::                        Frequently Used Terms Explained.
* Authentication::                  Authenticating Incoming Connections.
* Configuration::                   Writing your Configuration Files.
* Rule System::                     How to Use the Rule System.
* Invoking Anubis::                 How to Invoke the GNU @command{anubis}.
* Quick Start::                     A Quick Start Example.
* TLS/SSL::                         Using TLS/SSL Encryption.
* S/MIME::                          Using S/MIME Signatures.
* MDA Mode::                        Processing Incoming Mail.
* Mutt::                            Using Anubis with Mutt.
* Problems::                        Reporting Bugs.

Appendices

* Pixie-Dixie::                     Original description of the new
                                    GNU Anubis operation mode.
* Multi-Part Message Processing::   New Method of Processing
                                    Multi-Part messages.
* GNU Free Documentation License::  This manual is under the GNU Free
                                    Documentation License.
Indices

* Concept Index::                   Index of concepts.

@detailmenu
 --- The Detailed Node Listing ---

Auth mode.

* User Database::
* Database URL::
* Managing the Database::

Database URL

* text::        Plain text databases
* gdbm::        Databases in GDBM format
* sql::         MySQL and PostgreSQL databases

Managing the Database

* Administrators::      Administrator's View
* Users::               User's View

Administrators

* Create::              Creating the Database
* List::                Listing Database Records
* Add::                 Adding New Records
* Remove::              Removing Existing Records       
* Modify::              Modifying Existing Records
* anubisadm summary::   Summary of All Administrative Commands

Logical Structure

* AUTH Section::
* CONTROL Section::
* TRANSLATION Section::
* GUILE Section::

CONTROL Section

* Basic Settings::
* Output and Debugging Settings::
* SOCKS Proxy::
* ESMTP Authentication Settings::
* Encryption Settings::
* Security Settings::

The Rule System

* Actions::
* Conditional Statements::
* Triggers::
* Boolean Operators::
* Regular Expressions::
* Action List::
* Using Guile Actions::

Conditional Statements

* Concatenations::

Action List

* Stop Action::            Stopping Processing
* Call Action::            Invoking Another Section
* Adding Headers or Text:: How to add a new header or body line(s).
* Removing Headers::       How to remove a message header line(s).
* Modifying Messages::     How to modify a message contents on-the-fly.
* Modifying SMTP Commands::
* Inserting Files::        How to append text files to an outgoing message.
* Mail Encryption::        How to encrypt a message on-the-fly.
* External Processor::     How to process a message body using an external tool.
* Quick Example::          A quick example of using an action list.

Using Guile Actions

* Defining Guile Actions::
* Invoking Guile Actions::

Predefined Guile Actions
* Rot-13::
* Remailers::
* Entire Message Filters::

Using Mutt with Anubis

* mutt-smtp::            Using @acronym{SMTP}
* maidag::               Using GNU Mailutils
* msg2smtp.pl::          Using @command{msg2smtp.pl}

@end detailmenu
@end menu

@node Overview
@chapter Overview
@cindex overview
@cindex Simple Mail Transport Protocol, SMTP
@cindex daemon
@cindex client
@cindex tunnel
@cindex proxy
@cindex server
@cindex message submission daemon
@cindex outgoing mail processor
@cindex MUA, Mail User Agent
@cindex MTA, Mail Transport Agent

GNU Anubis is an @acronym{SMTP} message submission daemon. Its purpose
is to receive outgoing messages, optionally perform some manipulations
over their content, and to forward altered messages to the mail
transport agent. 

A usual mail sending scheme looks as follows: the user composes
his message using @dfn{mail user agent} (@dfn{MUA} for short). Once
the message is composed, the user sends it. While sending, the
@acronym{MUA} connects to the @dfn{mail transport agent}
(@dfn{MTA} for short) and passes it the message for delivery. The
figure below illustrates this interaction:

@smallexample
+-------+                 +-------+               
|  MUA  | ---[outmsg]---> |  MTA  | ... [outmsg]
+-------+                 +-------+         |     
                                            |
                                            V
                                     +--------------+
                                     |  Recipient's |
                                     |   Mailbox    |  
                                     +--------------+
                                                        
@end smallexample

As shown in this figure, outgoing message (@dfn{outmsg}) reaches
the recipient's mailbox unaltered.

However, there are situations where it may be necessary to modify
the outgoing message before it reaches @acronym{MTA}. For example,
the user might wish to sign outgoing messages with his PGP
key, because his @acronym{MUA} does not support this operation.

In such cases, installing GNU Anubis between the @acronym{MUA} and @acronym{MTA}
allows the user to perform additional processing on the
sent message. The figure below illustrates this concept:

@smallexample
+-------+                 +--------+                 +-------+               
|  MUA  | ---[outmsg]---> | Anubis | ---[modmsg]---> |  MTA  | 
+-------+                 +--------+                 +-------+     
                                                         |
                                                      [modmsg]
                                                         .
                                                         .
                                                         V
                                                  +--------------+
                                                  |  Recipient's |
                                                  |   Mailbox    |  
                                                  +--------------+
@end smallexample

The outgoing message is modified by GNU Anubis, and it is
the resulting message (@dfn{modmsg}) that reaches the @acronym{MTA}.

GNU Anubis is able to perform a wide set of operations on messages,
such as modifying headers or body, encrypting or signing 
messages with GPG (GNU Privacy Guard) keys, installing secure tunnels
to @acronym{MTA} using @acronym{TLS/SSL} encryption, tunneling messages through
SOCKS proxies, etc.

When the set of built-in operations is not enough, administrators can
define new ones using Guile, a @dfn{GNU's Ubiquitous
Intelligent Language for Extensions}.

@cindex SMTP normalization
Apart from configurable operations, GNU Anubis always performs
@dfn{SMTP session normalization}, a process that ensures that the
@acronym{SMTP} stream coming out of Anubis complies with the RFC
2821, even if the incoming stream does not. In particular, Anubis
removes any extra whitespace appearing between @samp{MAIL FROM:} or
@samp{SMTP TO} command and its argument.

Message processing is controlled by two configuration files: a
system-wide one that affects functionality of the system as
a whole, and user configuration files, which modify Anubis
behaviour on a per-user basis.

@node Glossary
@chapter Glossary of Frequently Used Terms

@table @dfn
@item Authentication
A process whereby Anubis determines authenticity of the connecting
party, its user name and configuration settings.

@item Protocol
A standard for information exchange. Protocol
defines specific wording and control flow for communications between
two or more programs, devices or systems.

@item SMTP
Simple Mail Transport Protocol is a common mechanism for exchanging
mail across a network. This was described initially in @acronym{RFC}
821, and subsequently extended by more documents, the most recent one
being @acronym{RFC} 5321.

@item Daemon
A process that runs in the background, doing automated processing.

@item Server
A server provides information or other services for its
clients. Most network protocols are client--server based. This term often
refers to hardware, but it can also refer (and we're using it that way)
to a particular program or process, on that machine, which provides the
service.

@item Proxy
A program, which goes between @acronym{MUA} and @acronym{MTA}. It can
be used as a gateway to the outside world, while using a firewall. In
this case a host under the firewall sends data to the proxy server,
which in turn forwards it to a server outside, receives its
replies, and passes them back to the internal host.

@item Guile
GNU's Ubiquitous Intelligent Language for Extensions. It provides a
Scheme interpreter conforming to the R5RS language specification. GNU
Anubis uses Guile as its extension language.
For more information about Guile,
@ref{Top,,Overview,guile,The Guile Reference Manual}.

@item GPG
GNU Privacy Guard, a tool compatible with @dfn{PGP} (@dfn{Pretty Good
Privacy}).
@end table

@node Authentication
@chapter Authentication
@cindex authentication

When GNU Anubis accepts incoming connection, it first has to identify
the remote party, i.e. to determine whether it is authorised to use
Anubis resources and, if so, what configuration settings to use 
during the session. We call this process @dfn{authentication}.
The exact method of authentication depends on Anubis @dfn{operation
mode}. Currently there are three modes:

@table @asis
@item proxy
No authentication is performed.  Anubis switches to the unprivileged
user (@pxref{Security Settings,,user-unprivileged}) and acts as an
@dfn{@acronym{SMTP} proxy}.

@item transparent
Anubis relies on AUTH service (@command{identd}) to authenticate users.
This is the default mode. It is compatible with versions of GNU Anubis
up to 3.6.2.

@item auth
This mode uses @acronym{SMTP} AUTH mechanism to authenticate incoming
connections. @xref{Pixie-Dixie}, original description of this mode.
@end table

Both modes have their advantages and deficiencies, which you need
to weigh carefully before choosing which one to use. They are
discussed below:

@heading Transparent (@samp{traditional}) mode.

Deficiencies:
@enumerate
@item The user must have @command{identd} installed on his machine.
@item The user must have a system account on the machine running
GNU Anubis (though the system administrator may relax
this limitation by using user name translation, @pxref{TRANSLATION
Section}).
@end enumerate

@noindent
Advantages:
@enumerate
@item Relative simplicity. No user database is necessary.
@item Authentication is performed immediately after connecting.
@end enumerate

@heading Auth mode.

Deficiencies:
@enumerate
@item A user database is needed
@item @acronym{MUA}s of the users must be able to perform ESMTP AUTH.@footnote{It is
not a serious restriction, however. Users may install Anubis on their
machines for the sole purpose of @acronym{SMTP} authentication, as Pixie-Dixie suggests.}
@end enumerate

@noindent
Advantages:
@enumerate
@item Improved reliability.
@item Users do not have to run @command{identd} on their machines.
@item Users are not required to have accounts on the machine where
Anubis runs.
@item Users can remotely modify their configuration files.
@end enumerate

@menu
* User Database::
* Database URL::
* Managing the Database::
@end menu

@node User Database
@section User Database

A @dfn{User Database} is a storage system where GNU Anubis keeps @dfn{user
credentials}, i.e. data necessary for authenticating and authorizing
users. The exact way of storing these data is described further in
this manual. In this section we treat user database as an abstraction
layer.

The user database consists of @dfn{records}. Each record keeps
information about a particular @dfn{user}. A record consists
of four @dfn{fields}. A field may contain some value, or be
empty, in which case we say that it has @dfn{null}
value.

The fields are:

@table @code
@item SMTP AUTHID
@acronym{SMTP} authentication @acronym{ID} of the user.

@item AUTH PASSWORD
@acronym{SMTP} password.

@item ACCOUNT
System user name.

@item CONFIG
Path to the configuration file.
@end table

The first two fields are mandatory and must always have non-null values.
No two records in the database may have the same value of
@code{SMTP AUTHID} field. When @command{anubis} is trying to
authenticate a user, it first looks up in the database a record
with the value of @code{SMTP AUTHID} field matching AUTHID given
by the user. If no such entry is found, authentication fails.
Otherwise, @command{anubis} goes on and compares the password
supplied by the user with that from @code{AUTH PASSWORD} field.
If they match, authentication succeeds and @command{anubis}
passes to authorization state.

In this state, it first determines the user @acronym{ID}
(@acronym{UID}) to switch to. If the @code{ACCOUNT} field
is not null, its value is used as account login name. If it is null,
@command{anubis} uses the privileges of the @dfn{default not
privileged user}, 
specified by @code{user-notprivileged} statement in the global
configuration file (@pxref{Security Settings, user-notprivileged}).

The final step is to parse the @dfn{user configuration file}. If
@code{CONFIG} field is not null, its value is used as absolute
path to the configuration file. Otherwise, @command{anubis} searches
for file @file{~/.anubisrc} (where @samp{~} denotes home directory
for the system account obtained on the previous step) and if such
a file exists, loads it.

@node Database URL
@section Database URL

Anubis database is identified by its @dfn{URL}, or @dfn{Universal
Resource Locator}. A @code{URL} consists of following elements
(square brackets enclose optional elements):

@smallexample
@var{proto}://[[@var{user}[:@var{password}]@@]@var{host}]/@var{path}[@var{params}]
@end smallexample

@noindent
where:

@table @var
@item proto
Specifies the database @dfn{protocol}. The protocol describes how
the database is to be accessed. In a way, it may be regarded as
specifying the database @dfn{type}. Currently, GNU Anubis supports
the following database protocols:

@multitable @columnfractions .20 .80
@item @samp{text} @tab A plain text file with users' credentials.
@item @samp{gdbm} @tab @acronym{GDBM} database
@item @samp{mysql} @tab @acronym{MySQL} database
@item @samp{pgsql} @tab @acronym{PostgreSQL} database
@item @samp{postgres} @tab Alias for @samp{pgsql}.
@end multitable

These protocols are described in detail below.

@item user
The name of the user authorized to access the database. 

@item password
Password for the above user.

@item host
Domain name or @acronym{IP} address of a machine running the database.

@item path
A @dfn{path} to the database. The exact meaning of this element
depends on the database protocol. It is described in detail when
discussing particular protocols.

@item params
A list of protocol-dependent parameters. Each parameter consists
of the @dfn{parameter name}, or @dfn{keyword} and its @dfn{value}
separated by a equals sign:

@smallexample
@var{keyword}=@var{name}
@end smallexample

Multiple parameters are separated by semicolons.
@end table

@menu
* text::        Plain text databases
* gdbm::        Databases in GDBM format
* sql::         MySQL and PostgreSQL databases
@end menu

@node text
@subsection Plain text databases

A simplest database is a plain text file, with lines representing
@dfn{records}. Empty lines and lines beginning with @samp{#}
(@dfn{comments}) sign are ignored. A record consists of
@dfn{fields}, separated by colons (@samp{:}, @acronym{ASCII} 58).
If @samp{:} character occurs as a part of a field, it must be escaped
by a single  backslash character (@samp{\\}, @acronym{ASCII} 92).
Each record must contain at least two and no more than four fields:

@enumerate 1
@item @acronym{SMTP} @samp{AUTHID}.
@item @acronym{SMTP} password.
@item Account name. 
@item Pathname of the user configuration file.
@end enumerate 

@subsubheading URL syntax

The @acronym{URL} syntax for this type of databases is quite simple:

@smallexample
text:@var{path}
@end smallexample

@noindent
where @var{path} specifies absolute file name of the database file.

@node gdbm
@subsection Databases in GDBM format

The protocol value @samp{gdbm} specifies a @dfn{GDBM database}. For
the detailed description of @acronym{GDBM} system
@ref{Top,,Introduction,gdbm,The GNU DBM Manual}.

Technically speaking, each @acronym{GDBM} record consists of
a @dfn{key} and @dfn{content}. Its @code{key} holds the value of
@acronym{SMTP} @samp{AUTHID}, whereas its @code{content} holds
@acronym{SMTP} password, system account name and path to user
configuration file, separated by commas. As it was with @samp{text}
databases, the two last fields are optional. 

The @acronym{URL} syntax for @acronym{GDBM} databases is: 

@smallexample
gdbm:@var{path}
@end smallexample

@noindent
where @var{path} specifies absolute file name of the database file.

@node sql
@subsection MySQL and PostgreSQL

This is the most flexible database format. GNU Anubis @value{VERSION}
supports MySQL@footnote{See @url{http://www.mysql.com}.} and
PostgreSQL@footnote{See @url{http://www.postgres.org}.} interfaces.
No matter which of them you use, the implementation details are hidden
behind a single consistent Anubis interface.

GNU Anubis supposes that all user data are kept in a single database
table. This table must have at least four columns for storing
@acronym{SMTP} @samp{AUTHID}, @acronym{SMTP} password, system account name and path to
user configuration file. Among those, only the last two may have
NULL values. There is no restriction on the name of the database or
the authentication table, nor on its column names. This information
may be specified in @acronym{URL} as discussed below.

@subsubheading URL syntax

@smallexample
@var{proto}://[[@var{user}[:@var{password}]@@]@var{host}/]@var{dbname}[@var{params}]
@end smallexample

@var{Proto} describes the database type to use. Use @samp{mysql}
for MySQL databases and @samp{pgsql} or @samp{postgres} for PostgreSQL
databases.

Optional @var{user} and @var{password} specify authentication
credentials for accessing the database. 

@var{Host} sets the domain name or @acronym{IP} address of the machine running
the database. It may be omitted if the database resides on 
@samp{localhost}.

The database name is specified by the @var{dbname} element.

Further details needed for connecting to the database are
given by @acronym{URL} parameters. All of them have reasonable
default values, so you'll have to specify only those parameters that
differ from the default. The following parameters are defined:

@table @option
@item port=@var{number}
Specifies port number the database server is listening on.
If it is not given, the behavior depends on the value of the
@option{socket} parameter (see below). If @option{socket} is not present, the
program will use the default port number for the given protocol
(i.e. 3306 for @samp{mysql} and 5432 for @samp{pgsql}.

@item socket=@var{string}
Specifies the UNIX file name of the socket to connect to. This
parameter cannot be used together with @option{port} (see above).

@item bufsize=@var{number}
Sets length of the buffer for storing SQL queries. Default is
1024 bytes.

@item table=@var{string}
Specifies name of the database table with the authentication
data. Default is @samp{users}.

@item authid=@var{string}
Specifies the name of a column in @option{table} which holds 
@samp{AUTHID} value. Default is @samp{authid}.

@item passwd=@var{string}
Specifies the name of a column in @option{table} which holds 
the user password. Default is @samp{passwd}.

@item account=@var{string}
Specifies the name of a column in @option{table} which holds
the name of system account to be used for this @samp{AUTHID}. Default
is @samp{account}.

@item rcfile=@var{string}
Specifies the name of a column in @option{table} which holds
the path to the user's configuration file. Default is @samp{rcfile}.

@FIXME{An example, please.}
@end table

@cindex options file, MySQL
@findex my.cnf
@findex /etc/my.cnf
When using a MySQL database (@samp{mysql://}), database parameters and
access credentials are first read from the file @file{/etc/my.cnf}, if
it exists.  This file called @dfn{option file} in @samp{MySQL} parlance
@ifhtml
(see @uref{http://dev.mysql.com/doc/refman/5.0/en/option-files.html,
option files}).
@end ifhtml
@ifnothtml
(@pxref{option-files, Using Option Files,,mysql,MySQL Manual})
@end ifnothtml
is organized in groups, each group beginning with the group name in
square brackets on a separate line.  Within a group, each non-empty
line consists of a MySQL option name, optionally followed by an equals
sign and the value.  By default, the values from the @samp{anubis}
group are read.

Two additional parameters are provided to fine-tune this behavior:

@table @option
@item options-file=@var{file}
Read options from @var{file} instead of @file{/etc/my.cnf}.  An
empty value (@samp{options-file=}), disables using the options file.

@item options-group=@var{name}
Set the name of the group in the MySQL configuration file, from
which to read configuration options.     
@end table

@node Managing the Database
@section Managing the Database

Managing the user database is a complex task, which looks differently
from administrator's and user's point of view. Administrators have
all privileges on the database, they can add new records and delete or
modify existing ones. Users, of course, do not have such ample
rights. The only thing a user is able to do is to maintain his own
record in the database, provided that he already has one. 

@menu
* Administrators::      Administrator's View
* Users::               User's View
@end menu

@node Administrators
@subsection Administrators

All administrative tasks are done via the @command{anubisadm} command ---
a multipurpose tool for Anubis administrators.

The command usage syntax is:

@smallexample
anubisadm @var{command} [@var{options}] @var{database-url}
@end smallexample

@noindent
where @var{command} specifies the operation to be performed on the
database, @var{options} give additional operation-specific parameters,
and @var{database-url} specifies the database to operate upon.

All administrative tasks can be subdivided into the following
five categories:

@itemize
@item Creating the Database
@item Listing Database Records
@item Adding New Records
@item Removing Existing Records       
@item Modifying Existing Records
@end itemize

@menu
* Create::              Creating the Database
* List::                Listing Database Records
* Add::                 Adding New Records
* Remove::              Removing Existing Records       
* Modify::              Modifying Existing Records
* anubisadm summary::   Summary of All Administrative Commands
@end menu

@node Create
@subsubsection Creating the Database

To create a database, use @kbd{anubisadm --create} (or
@kbd{anubisadm -c}). @command{Anubisadm} will read database
entries from the standard input and write them to the database.
The standard input is supposed to be formatted as a @code{text} database
(@pxref{text}).

For example, to create a @acronym{GDBM} database from plain text file
@file{userlist}, use the following command

@smallexample
anubisadm --create gdbm:/etc/anubis.db < userlist
@end smallexample

@noindent
Similarly, to create an initially empty database, type

@smallexample
anubisadm --create gdbm:/etc/anubis.db < /dev/null
@end smallexample

@emph{Notice}, that if you use @acronym{SQL} database format,
@option{--create} command does not imply creating the database
structure! So, before running

@smallexample
anubisadm --create mysql://localhost/dbname < userlist
@end smallexample 

@noindent
make sure you create the underlying database structure (including
granting privileges to the @command{anubis} user), via the
usual procedure. Please refer to corresponding database manual
for the detailed instructions on this.

It is sometimes necessary to convert an existing user database
from one format (protocol) to another. For example, suppose you
have been running @acronym{GDBM} database (@code{text:/etc/anubis.db})
for some time, but now it has grown so big that you decided to
switch to PostgreSQL database to improve performance. To do so,
first create the database using postgres utilities. Then run

@smallexample
anubisadm --list text:/etc/anubis.db | \
 anubisadm --create pgsql://localhost/dbname
@end smallexample

@noindent 
That's all there is to it!

@node List
@subsubsection Listing Database Records

The @option{--list} (or @option{-l}) option lists the existing
database:

@smallexample
anubisadm --list gdbm:/etc/anubis.db
@end smallexample

By default it displays all records from the database.

Among its other uses, such invocation is handy for converting
user database to another format (@pxref{Create}).

If you wish to list only a particular record, specify the 
@code{AUTHID} using @option{--authid} (@option{-i}) option. For example,
to list the record for @code{AUTHID} @samp{test},
type:

@smallexample
example$ anubisadm --list --authid test gdbm:/etc/anubis.db
@end smallexample


@node Add
@subsubsection Adding New Records

To add a new record use the @option{--add} (@option{-a}) option.
Additional data are specified via the following options:

@table @option
@item -i @var{string}
@itemx --authid=@var{string}
Specify the user @code{SMTP AUTHID}. 

@item -p @var{string}
@itemx --password=@var{string}
Specify the user password. 

@item -u @var{string}
@itemx --user=@var{string}
Specify the system user name for this @code{AUTHID}.

@item -f @var{string}
@itemx --rcfile=@var{string}
Specify configuration file to be used for this user.
@end table

For example, the following command adds a record with @code{SMTP
AUTHID} @samp{test}, password @samp{guessme} and maps it
to the system account @samp{gray}:

@smallexample
anubisadm --add --authid test --password guessme \
          --user gray gdbm:/etc/anubis.db
@end smallexample

@node Remove
@subsubsection Removing Existing Records

Removing a record is quite straightforward: use the @option{--remove}
(@option{-r}) option and supply the @code{AUTHID} to delete via the
@option{--authid} option. For example, to remove the record created
in the previous subsection, run:

@smallexample
anubisadm --remove --authid test gdbm:/etc/anubis.db
@end smallexample

@node Modify
@subsubsection Modifying Existing Records

To modify an existing record use the @option{--modify}
(@option{-m}) option. The record is identified via the
@option{--authid} option. The following options supply
the changed values:

@table @option
@item -p @var{string}
@itemx --password=@var{string}
Specify new user password. 

@item -u @var{string}
@itemx --user=@var{string}
Specify new system user name for this @code{AUTHID}.

@item -f @var{string}
@itemx --rcfile=@var{string}
Specify the user's configuration file.
@end table

For example, the following command changes the name of configuration file
for the user @samp{smith}:

@smallexample
anubisadm --authid smith \
          --rcfile=/var/spool/anubis/common gdbm:/etc/anubis.db
@end smallexample

@node anubisadm summary
@subsubsection Summary of All Administrative Commands

@itemize @bullet
@item Usage
@smallexample
anubisadm @var{command} [@var{options}] @var{database-url}
@end smallexample

@item Commands:
@table @option
@item -c
@itemx --create
Create the database.

@item -l
@item --list
List the contents of an existing database.

@item -a
@item --add
Add a new record.

@item -m
@itemx --modify
Modify an existing record.

@item -r
@item --remove
Remove an existing record.

@item --version
Display program version number and exit.

@item --help
Display short usage summary and exit.
@end table

@item Options:
@table @option
@item -i @var{string}
@itemx --authid=@var{string}
Specify the authid to operate upon. This option is mandatory for
@option{--add}, @option{--modify} and @option{--remove} commands.
It may also be used with @option{--list} command.

@item -p @var{string}
@itemx --password=@var{string}
Specify the password for the authid. This option is mandatory for
@option{--add}, @option{--modify} and @option{--remove} commands.

@item -u @var{string}
@itemx --user=@var{string}
Specify the system user name corresponding to the given authid. It may
be used with @option{--add}, @option{--modify}, and @option{--remove}
commands.

@item -f @var{string}
@itemx --rcfile=@var{string}
Specify the rc file to be used for this authid. The option may
be used with @option{--add}, @option{--modify}, and @option{--remove}
commands.
@end table
@end itemize

@node Users
@subsection Users

Users maintain their database records via the @command{anubisusr}
command. We suggest invoking
@command{anubisusr} from your @file{~/.profile}, which will make
sure that your configuration file is up to date when you log in.
@footnote{Make sure to run @command{anubisusr} in background, so
it does not slow down your normal login sequence.}.
@FIXME{anubisusr should also allow to modify user
password. This is the only database field, apart from @code{CONFIG}
that the user may be allowed to change}

@subsubheading Usage

@smallexample
anubisusr [@var{options}] [@var{smtp-url}]
@end smallexample

@noindent
where @var{smtp-url} is a @acronym{URL} of your GNU Anubis server.
Notice that if it lacks user name and password, then
@command{anubisusr} will first try to retrieve them from your
@file{~/.netrc} file (@pxref{netrc,,,netrc(5), netrc manual page}), and if not
found, it will prompt you to supply them.

@subsubheading Options

@table @option
@item -m @var{mech}
@itemx --mechanism @var{mech}
Use the SASL mechanism @var{mech}. Give this option several times
to set a list of allowed mechanisms.

@item --file=@var{file}
@itemx -f @var{file}
Sets the user configuration file name (default is @file{.anubisrc}).

@item --netrc+@var{file}
@itemx -n @var{file}
Sets the name of the automatic login configuration file (default is
@file{.netrc}).

@item -v
@itemx --verbose
Verbose output. Multiple options increase verbosity. Maximum verbosity
level is 3.
@end table

Options controlling encryption:
  
@table @option  
@item --disable-tls
@itemx -d
Disable the use of TLS encryption.

@item --tls-cafile=@var{file}
@itemx -C @var{file}
Sets the name of certificate authority file to use when verifying the
server certificate.

@item --tls-priorities=@var{list}
Sets cipher suite preferences to use.  The @var{list} argument may
contain a single initial keyword or be a colon-separated list of TLS
keywords.  The description of TLS keywords is well beyond the scope of
this document.  Please refer to @ref{Priority Strings,Priority
Strings,,gnutls,GnuTLS Manual}, for a detailed discussion.

Default priority list is @samp{NORMAL}.
@end table
  
Informational options:  

@table @option
@item --version
Display program version number and exit.

@item --help
Display short usage summary and exit.
@end table

@node Configuration
@chapter Configuration
@cindex configuration
@cindex settings
@cindex system configuration file
@cindex user configuration file

The behavior of GNU Anubis is controlled by two configuration files.
The @dfn{system configuration file}, @file{/etc/anubisrc},
supplies system-wide settings that affect all users. This file is usually
owned by root. The @dfn{user configuration file} specifies what GNU
Anubis should do for a particular user. By default it is located
in @file{~/.anubisrc}. This location can be changed if
@command{anubis} operates in auth mode. The permissions of
a user configuration file must be set to 0600 (u=rw,g=,o=),
otherwise GNU Anubis won't accept the file.

@subheading Lexical Structure

Both configuration files use simple line-oriented syntax. Each
line introduces a single statement. A statement consists of
@dfn{words}, each word being defined as a contiguous sequence of
non-whitespace symbols. The word may be composed of alphanumeric
characters and any of the following punctuation symbols:
@samp{_}, @samp{.}, @samp{/}, @samp{-}. Any arbitrary sequence
of characters enclosed in a pair of double quotes is also recognized
as a word. Such a sequence is called @dfn{quoted string}.

@cindex Quoted Strings
@cindex Escape Sequences
Quoted strings follow the same syntax rules as in the C language.
A backslash character @samp{\} alters the meaning of the character
following it. This special construct is called @dfn{escape sequence}.
When processing an escape sequence, Anubis removes it from the string
and replaces it with a single character as described in the following
table:

@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@item Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \e @tab Escape (@acronym{ASCII} (@acronym{ASCII} 27)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
@end multitable
@end float

A backslash followed by any character not listed above is replaced by
the character alone. This can be used, in particular, for inserting
@samp{"} character within a string, as in the example below:

@smallexample
"This string contains \"quoted string\"."
@end smallexample

Similarly, a backslash followed by a newline is replaced by the newline
itself. Thus, the following two strings are equivalent:

@smallexample
"This string is split\nover two lines"

"This string is split\
over two lines"
@end smallexample

@FIXME{Should we support \ooo (o is an octal digit) and \\xHH (H is a
hex digit) syntax? I'd say yes, but then a special exception should be
made for back references \1 - \9.}

The familiar shell @dfn{here document} syntax can be used to produce
a word containing several lines of text. The syntax is:

@smallexample
<<[-]delimiter
    text
delimiter
@end smallexample                                                  

If ``here document'' starts with @samp{<<-}, then all leading tab
characters are stripped from input lines and the line containing
@dfn{delimiter}. This allows to indent here-document in a natural
fashion.

To summarize all the above, let's consider an example:

@smallexample
@group
first-word "second word" <<-EOT
                            Third word
                            containing several
                            lines of text
                            EOT
@end group
@end smallexample

@noindent
This line contains three words: @samp{first-word}, @samp{second word}
and the third one composed of the three lines between the @samp{EOT}
markers.

If a statement is very long, it may be split among several lines
of text. To do so, end each line with a backslash (@samp{\}),
immediately before the newline, as in:

@smallexample
@group
a very long statement\
  occupying several lines\
  of text
@end group  
@end smallexample

A @samp{#} in a line starts a @dfn{comment}. The @samp{#} character
and the rest of the line following it are ignored. Comments may appear
anywhere in the configuration file, except within a command line or
a ``here-document'' construct. A line containing just a
comment (with optional whitespace before it) is effectively blank, and
is ignored. For example:

@smallexample
@group
# This is a comment
if header[Subject] :re "No.*"  # This is also a comment
  guile-process action-name This # is not a comment!!!
fi
@end group
@end smallexample

@subheading Logical Structure

Statements in a configuration file are grouped into
@dfn{sections}. Each section has its name. A section begins with
one of the following constructs:

@smallexample
BEGIN @var{name}
---BEGIN @var{name}---
@end smallexample

@noindent

and ends with one of the following constructs:

@smallexample
END
---END---
@end smallexample

Notice, that both @samp{BEGIN} and @samp{END} must be uppercase.
When using the second form, any amount of whitespace is allowed
between the three dashes and the word.

Sections cannot be nested.

There are five predefined sections, whose names are in uppercase.
The user may define his own sections, which may then be referred
to from the @code{RULE} section as subroutines (@pxref{Call Action}).

The predefined section names are:

@table @dfn
@item AUTH
Defines authentication mechanisms. 
@item CONTROL
This section specifies the basic GNU Anubis behavior. Its presence
is required in the system configuration file. It may be used in
the user configuration file to override the system-wide settings.
@item TRANSLATION
This section specifies a translation map for mapping
remote user names to local ones. It may be used only in the system-wide
configuration file.
@item GUILE
Configures the Guile interpreter. This section is allowed in both
configuration files.
@item RULE
Defines rules that for altering the message contents.
@end table

@menu
* AUTH Section::
* CONTROL Section::
* TRANSLATION Section::
* GUILE Section::
@end menu

@node AUTH Section
@section AUTH Section
@cindex AUTH section

The @code{AUTH} session controls various aspects of authentication mode.

@deffn Option smtp-greeting-message @var{text}
Configures the greeting message issued by GNU Anubis upon accepting
SMTP connection.
@end deffn

@deffn Option smtp-help-message @var{help-text}
Defines the message issued in response to @acronym{SMTP}
@code{HELP} command. @var{Help-text} is a list of strings. Each string
from the list will be displayed on a separate response line.
@end deffn

@deffn Option sasl-password-db @var{url}
Sets @acronym{URL} of the user database (@pxref{User Database}).
@end deffn

@deffn Option sasl-allowed-mech @var{mech-list}
Defines the list of allowed authentication methods.
@end deffn

@deffn Option sasl-service @var{name}
Sets the SASL @dfn{service name}. It is used, among others, with GSSAPI
authentication method. Default is @samp{anubis}.
@end deffn

@deffn Option sasl-hostname @var{name}
Sets the SASL hostname. By default, the server determines it
automatically. If it happens to make a wrong guess, you can fix it
using this directive.
@end deffn

@deffn Option sasl-realm @var{name}
Sets the SASL realm. By default, the local domain is used as SASL realm
(@pxref{Basic Settings, local-domain}).
@end deffn

@node CONTROL Section
@section CONTROL Section
@cindex CONTROL section

The @samp{CONTROL} section defines basic GNU Anubis behavior.
If used in the system-wide configuration file, it applies to all users in
the system. Each user can have a @samp{CONTROL} section in his
configuration file, to customize his personal settings. Of course, not
all options can be set or changed by the user. Some options can only be
set in the system configuration file, and some only in the user
configuration file. By default, options specified in the user
configuration file have a @strong{higher} priority than those
specified in system configuration file.

All option names are case insensitive, so that
@code{bind} or @code{BIND} or @code{BiNd} all refer to the same option.

@menu
* Basic Settings::
* Output and Debugging Settings::
* SOCKS Proxy::
* ESMTP Authentication Settings::
* Encryption Settings::
* Security Settings::
@end menu


@node Basic Settings
@subsection Basic Settings
@UNREVISED{}

@deffn Option bind [@var{host}:]@var{port}
Specify the @acronym{TCP} port on which GNU Anubis listens for connections.
The default @var{host} value is @w{@samp{INADDR_ANY}}, which means
that anyone can connect to GNU Anubis. The default @var{port} number
is 24 (private mail system). This option is available only in the
system configuration file.

For example, to bind GNU Anubis to port 25 (@acronym{SMTP}) and limit
its clients only to those from @samp{localhost}, set the following in
your system configuration file:

@smallexample
bind localhost:25
@end smallexample
@end deffn

@deffn Option remote-mta @var{host}[:@var{port}]
Specify a host name or @acronym{IP} address of the remote
@acronym{SMTP}. GNU Anubis will forward mails to that server. The
default @var{port} number is 25. This option is available in both
configuration files.
@end deffn

@deffn Option local-mta @var{file-name} [@var{args}]
Execute a local @acronym{SMTP} server, which works on standard input and output
(inetd-type program). For example:

@smallexample
local-mta /usr/sbin/sendmail -bs
@end smallexample

The @samp{CONTROL} section must contain either @code{local-mta} or
@code{remote-mta}, but not both.
@end deffn

@deffn Option mode @var{mode-name}
Selects Anubis operation mode. Allowed values for @var{mode-name}
are:

@table @asis
@item proxy
@item transparent
@item auth
@end table

@xref{Authentication}, for the detailed discussion of GNU Anubis
operation modes.
@end deffn

@deffn Option read-entire-body @var{yes-or-no}
Normally, when processing a multi-part message with external
filter (@pxref{External Processor}), Anubis feeds
only the first part to the filter. The rest of the message is copied
verbatim. To alter this behavior so that your external program
sees the entire message body, set @code{read-entire-body yes}
in your control  section.
@end deffn

@deffn Option incoming-mail-rule @var{string} 
Declares the name of command section for incoming mail. Default is
@samp{INCOMING}. This option is available only for system
configuration file. @xref{MDA Mode}, for detailed description of
incoming mail processing.
@FIXME{More info?}
@end deffn

@deffn Option outgoing-mail-rule @var{string}
Declares the name of command section for outgoing mail. Default is
@samp{RULE}. This option is available only for system
configuration file.
@end deffn

@deffn Option smtp-command-rule @var{string}
Declares the name of command section for rewriting @acronym{SMTP}
commands. Default is @samp{SMTP}. This option is available only
for system configuration file. @xref{Modifying SMTP Commands}.
@end deffn

@deffn Option log-tag @var{string}
Tag syslog messages with @var{string}. Default is @samp{anubis}.
@end deffn

@deffn Option log-facility @var{string}
Use syslog facility @var{string} for logging. Valid argument values
are: @samp{user}, @samp{daemon}, @samp{auth}, @samp{authpriv},
@samp{mail}, @samp{cron}, @samp{local0} through @samp{local7} (all
names case-insensitive, optionally prefixed by @samp{log_}), or a
decimal facility number.  Default is @samp{mail}.
@end deffn

@deffn Option local-domain @var{string}
Set local domain name.  By default, the domain name is defined as the
part of the local host name following the first dot.

Local domain name is used as @acronym{SASL} realm, unless overridden
by @samp{sasl-realm} statement (@pxref{AUTH Section, sasl-realm}).
@end deffn

@node Output and Debugging Settings
@subsection Output Settings

@deffn Option termlevel @var{level}
Defines logging verbosity level. Allowed values are:

@table @asis
@item normal
Only errors are logged. This is the default level.

@item verbose
Produce more diagnostic output.

@item debug
Produce debugging output.

@item silent
Do not log anything.

@end table
This command is allowed only in the system configuration file.
@end deffn

@deffn Option logfile @var{file-name}
This command sets the name of additional log file. GNU Anubis logs
there messages about user's @acronym{SMTP} session, as defined by
the @samp{loglevel} statement (see below). For example:

@smallexample
logfile "anubis.log"
@end smallexample

This will direct additional logging to the @file{~/anubis.log} file in
the user's home directory.
@end deffn

@deffn Option loglevel @var{level}
This option defines verbosity level for the additional log
file. It may be used only in user configuration file. Allowed
values for @var{level} are:

@table @asis
@item none
@item fails
Log only failure messages.

@item all
Log all relevant messages.
@end table
@end deffn

@deffn Option tracefile @var{yes-or-no}
@deffnx Option tracefile @var{file-name}
This option instructs @command{anubis} to log the execution of
tests and actions from the RULE sections. This is useful
for debugging configuration files.

When this option is used in the system-wide configuration file,
only boolean argument is allowed. Using @samp{tracefile yes} enables
logging of actions and tests to the default syslog channel.
Using @samp{tracefile no} disables it.

When used in the user configuration file, a filename is allowed
as an argument to this option. This allows you to explicitly
specify to which file the tracing output should go. Otherwise,
using @samp{tracefile yes} enables logging to the same file
as @samp{logfile} (if possible).
@end deffn

@deffn Option HANG @var{delay}
@emph{Do not use this option, unless you are developing or debugging
Anubis!}

This option instructs each child process to hang for the given number
of seconds. Before hanging, the process issues the following
diagnostic message:

@smallexample
Child process suspended for @var{delay} seconds
@end smallexample

This option is useful for Anubis developers who wish to
attach to a child process with debugger. After attaching, set the
variable @code{_anubis_hang} to zero to continue processing. You may
wish to add the following statement to your @file{.gdbinit} file:

@smallexample
set variable _anubis_hang=0
@end smallexample

@end deffn

@node SOCKS Proxy
@subsection SOCKS Proxy
@cindex @acronym{SOCKS} proxy

@deffn Option socks-proxy @var{host}[:@var{port}]
Enables tunneling incoming connections through a @acronym{SOCKS} proxy server,
specified as an argument @var{host}. The default value for @var{port} is
1080, which is a common port number for @acronym{SOCKS} proxies.
@end deffn

@deffn Option socks-v4 @var{yes-or-no}
Use @acronym{SOCKS} protocol version 4. By default it is turned off,
and version 5 of the @acronym{SOCKS} protocol is used.
@end deffn

@deffn Option socks-auth @var{username}:@var{password}
Sets user name and password for the @acronym{SOCKS} proxy server.
@end deffn

@node ESMTP Authentication Settings
@subsection ESMTP Authentication Settings
@cindex ESMTP authentication

The following options set authentication credentials for @acronym{ESMTP}
authentication. They are useful, for example, if your @acronym{MTA}
requires such an authentication, but your @acronym{MUA} does not support it.

You can also use these statements in a @samp{SMTP} section. 
@xref{Modifying SMTP Commands}, for a detailed description of this feature.

@deffn Option esmtp-allowed-mech @var{mech-list}
Defines the list of allowed authentication mechanisms. @var{Mech-list}
is a list of valid authentication mechanism names separated by
whitespace.

Anubis selects the authentication method using the following algorithm:
@acronym{MTA} presents a list of authentication methods it supports.
For each element in @var{mech-list}, Anubis tests whether it is
available in the list presented by @acronym{MTA}. If found, this method is
selected. For example, suppose that the @acronym{MTA} reports the following
supported mechanisms:

@smallexample
PLAIN LOGIN CRAM-MD5 ANONYMOUS
@end smallexample

@noindent
and in your configuration file you have:

@smallexample
esmtp-allowed-mech DIGEST-MD5 CRAM-MD5 LOGIN
@end smallexample

@noindent
Then, Anubis will select @samp{CRAM-MD5}.

@end deffn

@deffn Option esmtp-require-encryption @var{mech-list}
Declares the list of mechanisms that can be used only over
a TLS encrypted channel. By default Anubis uses

@smallexample
esmtp-require-encryption LOGIN PLAIN
@end smallexample

@noindent
This prevents sending user password over an unencrypted connection.

@end deffn

@deffn Option esmtp-auth-delayed @var{yes-or-no}
By default, ESMTP authentication is attempted as early as
possible, normally while handling the client @samp{EHLO} command.

When this statement is set to @samp{yes}, authentication is delayed
until the client issued the @samp{MAIL} command. This will allow
@command{anubis} to select authentication credentials depending on the
sender email. For a detailed description of this feature, see
@ref{Modifying SMTP Commands}.
@end deffn

@deffn Option esmtp-auth-id @var{authentication-id}
Sets authentication @acronym{ID} (user name).
@end deffn

@deffn Option esmtp-authz-id @var{authorization-id}
Sets authorization @acronym{ID} (user name).
@end deffn

@deffn Option esmtp-password @var{password}
Sets @acronym{ESTMP AUTH} password.
@end deffn

@deffn Option esmtp-auth @var{username}:@var{password}
This is a shortcut to set both authentication and authorization
@acronym{ID}s and the password. It is equivalent to

@smallexample
esmtp-auth-id @var{username}
esmtp-authz-id @var{username}
esmtp-password @var{password}
@end smallexample

@end deffn

The following options specify authentication credentials for GSSAPI,
DIGEST-MD5 and KERBEROS_V5 authentication mechanisms:

@deffn Option esmtp-service @var{service-name}
Sets the name of GSSAPI service.
@end deffn

@deffn Option esmtp-hostname @var{hostname}
Sets hostname of the machine.
@end deffn

@deffn Option esmtp-generic-service @var{servise-name}
Sets generic service name.
@end deffn

@deffn Option esmtp-passcode @var{passcode}
Sets passcode.
@end deffn

@deffn Option esmtp-realm @var{realm-name}
Sets GSSAPI realm.
@end deffn

The following option is useful with the @samp{ANONYMOUS}
authentication mechanism:

@deffn Option esmtp-anonymous-token @var{token}
Sets the token to be used with the @samp{ANONYMOUS} authentication mechanism
@end deffn

@node Encryption Settings
@subsection Encryption Settings

@deffn Option ssl @var{yes-or-no}
Enable or disable the @acronym{TLS/SSL} encryption between the
@acronym{MUA} and the @acronym{MTA}. The default is @samp{no}, but
using the @acronym{TLS/SSL} encryption is recommended. You should also
set your private key and certificate using the @samp{ssl-key} and
@samp{ssl-cert} keywords (defined below).

@xref{TLS/SSL}, for details.
@end deffn

@deffn Option ssl-oneway @var{yes-or-no}
Enable the @dfn{ONEWAY} encryption. Set @code{ssl-oneway yes},
if you want to use the @acronym{TLS/SSL}, but your @acronym{MUA}
doesn't support @acronym{ESMTP} @acronym{TLS/SSL}. Using
this option does not require setting the @samp{ssl-key} and
@samp{ssl-cert} options. 
@end deffn

@deffn Option ssl-priorities @var{list}
Sets cipher suite preferences to use.  The @var{list} argument is
either a single initial keyword or a colon-separated list of TLS
keywords.  The description of TLS keywords is well beyond the scope of
this document.  Please refer to @ref{Priority Strings,Priority
Strings,,gnutls,GnuTLS Manual}, for a detailed discussion.

The default priority list is @samp{NORMAL}.
@end deffn

@deffn Option ssl-cert @var{file-name}
Specify the certificate for the @acronym{TLS/SSL} encryption.

Default for @var{file-name} is @file{anubis.pem}.
@end deffn

@deffn Option ssl-key @var{file-name}
Set the private key for the @acronym{TLS/SSL} encryption.

The default @var{file-name} is @file{anubis.pem}.
@end deffn

@deffn Option ssl-cafile @var{file-name}
Specify CA certificate file (supported only by GnuTLS).
@end deffn


@node Security Settings
@subsection Security Settings

The following options control various security settings. 

@deffn Option drop-unknown-user @var{yes-or-no}
If this option is set to @samp{yes}, @command{anubis} drops
sessions which failed verification by the @acronym{IDENT} service.

This option is in effect only in @samp{transparent} mode.

Default is @samp{no}.
@end deffn

@deffn Option user-notprivileged @var{username}
Defines the @dfn{unprivileged} user, i.e. the user with whose
privileges @command{anubis} runs most of the time. This option is
available only in the system configuration file. For example: 

@smallexample
user-notprivileged "anubis"
@end smallexample

@strong{Caution:} This user must exist in the system user database
(@file{/etc/passwd}).
@end deffn

@deffn Option rule-priority @var{value}
This statement defines the order of execution of the system and user
@code{RULE} sections (@xref{Rule System}, for a detailed description).
It is available only in system configuration file.

Allowed values are:

@table @code
@item system
First execute the system section, then the user one.

@item user
First execute the user section, then the system one.

@item system-only
Execute only the system @code{RULE} section.

@item user-only
Execute only the user @code{RULE} section.
@end table
@end deffn

@deffn Option control-priority @var{value}
Sets the order of processing @code{CONTROL} sections. This option is
available only in system configuration file.

Allowed values are:

@table @code
@item system
The system @code{CONTROL} section is processed first. Notice, that
this means that the user may override the system settings in his
configuration file. This is the default setting.

@item user
The user @code{CONTROL} section is processed first. Thus, the
system-wide settings always override users' private settings.
@end table
@end deffn

@node TRANSLATION Section
@section TRANSLATION Section
@cindex TRANSLATION section

The @samp{TRANSLATION} section specifies how to translate remote or local
user names, or host names or addresses, to local user names.
The @samp{TRANSLATION} section is available only in the system
configuration file. The syntax is:

@smallexample
@group
---BEGIN TRANSLATION---
translate  [@var{user}@@]@var{address} into  @var{username}
...
---END---
@end group
@end smallexample

@var{address} means host name or @acronym{IP} address. You can also specify
@samp{0.0.0.0}, and it means any address (@samp{INADDR_ANY}).

For example:

@smallexample
@group
BEGIN TRANSLATION
translate jack@@example.net into john
END
@end group
@end smallexample

@noindent
This rule will allows the remote user @samp{jack} at @samp{example.net}
to use the configuration file of the local user @samp{john}.

In the contrast, this statement:
@smallexample
translate example.net into john
@end smallexample
@noindent
means that @emph{all} users at @samp{example.net} are allowed to use
the local john's configuration file.

@node GUILE Section
@section GUILE Section
@cindex GUILE section
@cindex Guile
@cindex extension language
@cindex Scheme

@deffn Command guile-output @var{file}
Specifies the name of the file to bind to the Scheme standard error
and output ports.

By default both ports are redirected to syslog. The standard error port
uses the @samp{err} priority, and the standard output port writes to the
@samp{warning} priority.

This option has no effect if GNU Anubis is started
with either @option{--foreground} or @option{--stdio} command line
option. 
@end deffn

@deffn Command guile-debug @var{yes-or-no}
When set to @samp{yes}, enables Guile stack traces and debugging output.
@end deffn

@deffn Command guile-load-path-append @var{path}
Appends the given @var{path} to the list of Guile load paths
(@pxref{Build Config, %load-path,,guile,The Guile Reference Manual}).
@end deffn

@deffn Command guile-load-program @var{file}
Reads the given Scheme program.
@end deffn


@node Rule System
@chapter The Rule System
@cindex rule system

The rule system is a core part of GNU Anubis. It can be regarded
as a program that is executed for every outgoing message. 

Throughout this chapter, when showing syntax definitions, their
optional parts will be enclosed in a pair of square
brackets, e.g.:

@smallexample
keyword [@var{optional-part}] @var{mandatory-part}
@end smallexample

@noindent
When the square braces are required symbols, they will be marked
as such, e.g.:

@smallexample
remove @samp{[}@var{key}@samp{]}
@end smallexample

The rule system is defined in the @dfn{RULE} section.
The statements within this section are executed sequentially.
Each statement is either an @dfn{action} or a @dfn{conditional
statement}.

@menu
* Actions::
* Conditional Statements::
* Triggers::
* Boolean Operators::
* Regular Expressions::
* Action List::
* Using Guile Actions::
@end menu


@node Actions
@section Actions
@cindex actions defined

An @dfn{action} is a statement defining an operation 
over the message. Syntactically, each action is

@smallexample
@var{command} [=] @var{right-hand-side}
@end smallexample

@noindent
Where @var{command} specifies the operation and
@var{right-hand-side} specifies its arguments. The equal sign
is optional.


@node Conditional Statements
@section Conditional Statements
@cindex Conditional statements
@cindex @code{if}, conditional statements
@cindex @code{else}, conditional statements
@cindex @code{fi}, conditional statements

A @dfn{conditional statement} defines control flow within the section.
It allows to execute arbitrary actions depending on whether a certain
condition is met. The conditional statement in its simplest form is:

@smallexample
if @var{condition}
  @var{action-list-1}
fi
@end smallexample

If @var{condition} evaluates to true, then the list of statements
@var{action-list-1} is executed.

A simple @var{condition} has the following syntax:

@smallexample
@var{part} [@var{sep}] [@var{op}] [@var{pattern-match-flags}] @var{regex}
@end smallexample

@noindent
(square brackets denoting optional parts).  Its parts are:

@table @var
@item part
Specifies which part of the input should be considered
when evaluating the condition. It is either @samp{command}, meaning
the text of the @acronym{SMTP} command issued while sending the message, or
@samp{header}, meaning the value of an @acronym{RFC}822 header. Either
of the two may be followed by the name of the corresponding command or
header enclosed in square brackets. If this part is missing, all
command or headers will be searched. 

@item sep
Optional @dfn{concatenation separator}.  @xref{Concatenations},
for its meaning.

@item op
Either @samp{=}, meaning ``match'', or @samp{!=}, meaning ``does not
match''.  Missing @var{op} is equivalent to @samp{=}.

@item pattern-match-flags
Optional @var{pattern-match-flags} alter the pattern matching
type used in subsequent conditional expression. It
will be described in detail in the section @ref{Regular Expressions}.

@item regex
Regular expression enclosed in double quotes.
@end table

The condition yields true if @var{regex} matches
the @var{part} (if @var{op} is @samp{=}), or does not
match it (if @var{op} is @samp{!=}).

For example:

@smallexample
@group
if header [Subject] "^ *Re:"
  ...
fi
@end group
@end smallexample

The actions represented by @dots{} will be executed only if the
@samp{Subject:} header of the message starts with @samp{Re:} optionally
preceded by any amount of whitespace.

A more elaborate form of the conditional allows you to choose among
the two different action sets depending on a given condition. The
syntax is:

@smallexample
if @var{condition}
  @var{action-list-1}  
else
  @var{action-list-2}
fi
@end smallexample

Here, @var{action-list-1} is executed if the 
@var{condition} is met. Otherwise, @var{action-list-2} is
executed.

Note, that both @var{action-list-1} and @var{action-list-2} can in
turn contain conditionals, so that the conditional
statements may be nested. This allows for creating very sophisticated
rule sets. As an example, consider the following statement:

@smallexample
if [List-Id] :re ".*<anubis-commit@@gnu.org>"
  modify [Subject] "[Anubis Commit Notice] &"
else
  if [List-Id] :re ".*<bug-anubis@@gnu.org>"
    modify [Subject] "[Anubis Bug Notice] &"
  else
    add [X-Passed] "Subject checking"
  fi
fi  
@end smallexample

The effect of this statement is: depending on the value of
@code{List-Id} header, prepend the @code{Subject} header with an
identification string, or add an @code{X-Passed} header if no known
@code{List-Id} was found.

To simplify writing such nested conditional statements, the
@samp{elif} keyword is provided:

@smallexample
if @var{condition-1}
  @var{action-list-1}
elif @var{condition-2}  
  @var{action-list-2}
else
  @var{action-list-3}
fi
@end smallexample

This statement is equivalent to:

@smallexample
if @var{condition}
  @var{action-list-1}
else
  if @var{condition-2}  
    @var{action-list-2}
  else
    @var{action-list-3}
  fi
fi
@end smallexample

Any number of @samp{elif} branches may appear in a conditional
statement, the only requirement being that they appear before
the @samp{else} statement, if it is used.

@menu
* Concatenations::
@end menu


@node Concatenations
@subsection Concatenations
@cindex Concatenation
It is important to understand that conditional expressions choose
the first match.  To illustrate this, lets suppose you wish to store
all recipient emails from the envelope in the
@samp{X-Also-Delivered-To} header.  A naive way to do so is:

@smallexample
if command [rcpt to:] = "(.*)"
  add header [X-Also-Delivered-To] "\1"
fi
@end smallexample

However, this will store only the very first @code{RCPT TO} value, so
you will not achieve your goal.

To help you in this case, @command{anubis} offers a
@dfn{concatenation} operator, whose effect is to concatenate the
values of all requested keys prior to matching them against the
regular expression.  Syntactically, the concatenation operator is a
string enclosed in parentheses, placed right after the key part of a
condition.  This string is used as a separator when concatenating
values.  For example:

@smallexample
if command [rcpt to:] (",") = "(.*)"
  add header [X-Also-Delivered-To] "\1"
fi
@end smallexample

This fragment will first create a string containing all @code{RCPT
TO} addresses, separated by commas, and then match it against
the regular expression on the right hand side.  Since this expression
matches any string, the @samp{\1} will contain a comma-separated list
of addresses.

@node Triggers
@section Triggers
@cindex Triggers

Triggers are conditional statements that use the value of the
@samp{Subject} header to alter the control flow. Syntactically, a
trigger is:

@smallexample
@group
trigger [@var{flags}] @var{pattern}
  @var{action-list}
done
@end group
@end smallexample

@noindent
Here, @var{pattern} is the pattern against which the @samp{Subject}
header is checked, @var{flags} are optional flags controlling the
type of regular expression used (@pxref{Regular Expressions}). For
backward compatibility, the keyword @code{rule} may be used instead
of @code{trigger}.

The trigger acts as follows: First, the value of the @samp{Subject} header is
matched against the pattern @samp{@@@@}@var{pattern}. If it matches,
then the matched part is removed from the @samp{Subject}, and the
@var{action-list} is executed.

Basically, putting aside the possibility to use different flavors of
regular expressions, a trigger is equivalent to the following statement:

@smallexample
@group
if header[Subject] :posix "(.*)@@@@@var{pattern}"
  modify header [Subject] "\1"
  @var{action-list}
fi
@end group
@end smallexample

Thus, adding the @samp{@@@@@var{rule-name}} code to the @samp{Subject}
header of your message, triggers a rule named @var{rule-name},
specified in a user configuration file. For example:

@smallexample
@group
BEGIN RULE
trigger :basic "^gpg-encrypt-john"
   gpg-encrypt "john's_gpg_key"
done
END
@end group
@end smallexample

@noindent
Now, if you send an email with the subject ending on
@samp{@@@@gpg-encrypt-john} (e.g.: @samp{Subject: hello
John!@@@@gpg-encrypt-john}), it will be encrypted with John's public
key. The trigger will remove the @samp{@@@@} and the characters
following it, so John will only receive a message with @samp{hello
John!} as a subject.

Another example shows an even more dynamic trigger, that is using
a substitution and back-references:

@smallexample
@group
---BEGIN RULE---
trigger :extended "^gpg-encrypt:(.*)"
   gpg-encrypt "\1"
   add [X-GPG-Comment] "Encrypted for \1"
done
---END---
@end group
@end smallexample

@noindent
To encrypt a message to user e.g. @samp{John}, simply send an email with
a subject @w{@samp{hello John!@@@@gpg-encrypt:john's_gpg_key}}.
This way, you decide at a run time which public key should be used,
without creating separate rules for each user.


@node Boolean Operators
@section Boolean Operators

The following table lists the boolean operators that can be used
in Anubis conditional expressions in the order of increasing binding
strength:

@itemize @bullet
@item @samp{OR}
@item @samp{AND}
@item @samp{NOT}
@end itemize

As an example, let's consider the following statement:

@smallexample
@group
if header[X-Mailer] "mutt" or header[X-Mailer] "mail" \
   and not header[Content-Type] "^multipart/mixed;.*"
   @var{action}
fi
@end group
@end smallexample

In this case the @var{action} will be executed if the @code{X-Mailer}
header contains the word @samp{mutt}. The same @var{action} will also
be executed if the @code{X-Mailer} header contains the word @samp{mail}
@emph{and} the value of the @code{Content-Type} header does not begin
with the string @samp{multipart/mixed}.

Now, if we wished to execute the @var{action} for any message sent
using @command{mail} or @command{mutt} whose @code{Content-Type}
header does not begin with the string @samp{multipart/mixed}, we would
write the following:

@smallexample
@group
if (header[X-Mailer] "mutt" or header[X-Mailer] "mail") \
   and not header[Content-Type] "^multipart/mixed;.*"
   @var{action}
fi
@end group
@end smallexample

@noindent
Notice the use of parentheses to change the binding strength of the
boolean operators.


@node Regular Expressions
@section Regular Expressions
@cindex regex, flag
@cindex re, flag
@cindex perl, flag
@cindex perlre, flag
@cindex exact, flag
@cindex ex, flag
@cindex scase, flag
@cindex icase, flag
@cindex basic, flag
@cindex extended, flag

GNU Anubis supports two types of regular expressions: POSIX (both
basic and extended), and Perl-style regular expressions. The former
are always supported, whereas the support for the latter 
depends on the configuration settings at compile time. By default
POSIX extended regexps are assumed.

Regular expressions often contain characters, prefixed
with a backslash (e.g. @samp{\(} in basic POSIX or @samp{\s} in
perl-style regexp). Due to escape substitution
(@pxref{backslash-interpretation}), you will have to escape the
backslash character, e.g. write:

@smallexample
modify :perl body ["\\stext"] "text"
@end smallexample

@noindent
instead of

@smallexample
# WRONG!
modify :perl body ["\stext"] "text"
@end smallexample

However, this rule does not apply to back references, i.e. @code{"\1"}
is OK. @FIXME{This is clearly a special case. When we support \ooo and
\xHH escapes, this will have to be handled separately...}

A number of modifiers is provided to change the type of regular
expressions. These are described in the following table.

@table @code
@item :regex
@itemx :re
Indicates that the following pattern should be considered a regular
expression. The default type for this expression is assumed.

@item :perl
@itemx :perlre
The regular expression is a Perl-style one. 

@item :exact
@itemx :ex
Disables regular expression matching, all patterns will be matched
as exact strings.

@item :scase
Enables case-sensitive comparison.

@item :icase
Enables case-insensitive comparison.

@item :basic
Switches to the POSIX Basic regular expression matching.

@item :extended
Switches to the POSIX Extended regular expression matching.
@end table

The special statement @code{regex} allows you to alter the default
regular expression type. For example, the following statement

@smallexample
regex :perl :scase
@end smallexample

sets the default regular expression types to Perl-style, case-sensitive.
The settings of @code{regex} statement regard only those patterns that
appear after it in the configuration file and have force until the
next occurrence of the @code{regex} statement. 

A couple of examples:

@smallexample
@group
if header[Subject] :perlre "(?<=(?<!foo)bar)baz"
 ...
fi
@end group
@end smallexample

@noindent
This will match any @code{Subject} header whose value
matches an occurrence of @samp{baz} that is preceded by @samp{bar}
which in turn is not preceded by @samp{foo}.
              
@smallexample
if header[Subject] :scase "^Re"
@end smallexample

@noindent
will match a @code{Subject} header whose value starts with @samp{Re},
but will not match it if it starts with @samp{RE} or @samp{re}.

When using POSIX regular expressions, the extended syntax is enabled
by default. If you wish to use a basic regular expression, precede
it with the @code{:basic} flag.

For the detailed description of POSIX regular expressions,
@xref{Top,,Regular Expression Library,regex,Regular Expression Library}.
For information about Perl-style regular expressions, refer to the
Perl documentation.


@node Action List
@section Action List
@cindex Action List

An @dfn{action list} is a list of action commands, which control processing
of messages. All action command names are case insensitive, so you
can use for instance: @samp{add} or @samp{ADD} or @samp{AdD}, and so on.

@menu
* Stop Action::            Stopping Processing
* Call Action::            Invoking Another Section
* Adding Headers or Text:: How to add a new header or body line(s).
* Removing Headers::       How to remove a message header line(s).
* Modifying Messages::     How to modify a message contents on-the-fly.
* Modifying SMTP Commands::
* Inserting Files::        How to append text files to an outgoing message.
* Mail Encryption::        How to encrypt a message on-the-fly.
* External Processor::     How to process a message body using an external tool.
* Quick Example::          A quick example of using an action list.
@end menu


@node Stop Action
@subsection Stop Action
@cindex @code{stop}

The @code{stop} command stops processing of the
section immediately. It can be used in the main @code{RULE} section as well as
in any user-defined section. For example:

@smallexample
if not header[Content-Type] "text/plain; .*"
  stop
fi
@end smallexample


@node Call Action
@subsection Call Action
@cindex @code{call}

The @code{call} command invokes a user-defined section much
in the same manner as a subroutine in a programming language. The
invoked section continues to execute until its end or the @code{stop}
statement is encountered, whichever the first.

@smallexample
BEGIN myproc
if header[Subject] "Re: .*"
  stop
fi
trigger "pgp"
  gpg-encrypt "my_gpg_key"
done
END

BEGIN RULE
call myproc
END
@end smallexample


@node Adding Headers or Text
@subsection Adding Headers or Text
@cindex @code{add}

The @code{add} command adds arbitrary headers or text
to the message. To add a header, use the following syntax:

@deffn Command add header @samp{[}@var{name}@samp{]} @var{string}
@deffnx Command add @samp{[}@var{name}@samp{]} @var{string}
For example:

@smallexample
add header[X-Comment-1] "GNU's Not Unix!"
add [X-Comment-2] "Support FSF!"
@end smallexample
@end deffn

To add text to the body of the message, use:

@deffn Command add body @var{text}
Adds the @var{text} to the message body. Use of this command with
@samp{here document} syntax allows to append multi-line text to the
message, e.g.:

@smallexample
@group
add body <<-EOT
    Regards,
    Hostmaster
    EOT
@end group
@end smallexample
@end deffn


@node Removing Headers
@subsection Removing Headers
@cindex @code{remove}

The @code{remove} command removes headers from the
message. The syntax is:

@deffn Command remove [@var{flags}] header @samp{[}@var{string}@samp{]}
@deffnx Command remove [@var{flags}] @samp{[}@var{string}@samp{]}

The name of the header to delete is given by @var{string} parameter.
By default only those headers are removed whose names match it exactly.
Optional @var{flags} allow to change this behavior. @xref{Regular Expressions},
for the detailed description of these.

An example:

@smallexample
remove ["X-Mailer"]
remove :regex ["^X-.*"]
@end smallexample

The first example will remove the @samp{X-Mailer:} header from
an outgoing message, and the second one will remove all "X-*"
headers.
@end deffn


@node Modifying Messages
@subsection Modifying Messages
@cindex @code{modify}

The @code{modify} command alters headers or body of the message. 

@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]}
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]}

@cindex Back References
For each header whose name matches @var{key}, replaces its name
with @var{new-key}. If @var{key} is a regular expressions, @var{new-key}
can contain back references. For example, the following statement
selects all headers whose names start with @samp{X-} and changes their
names to begin with @samp{X-Old-}:

@smallexample
modify header :re ["X-\(.*\)"] ["X-Old-\1"]
@end smallexample
@end deffn

@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @var{value}
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @var{value}

For each header whose name matches @var{key}, changes its value to
@var{value}. For example:

@smallexample
modify [Subject] "New subject"
@end smallexample

Every occurrence of unescaped @samp{&} in the new value will be replaced
by the old header value. To enter the @samp{&} character itself,
escape it with two backslash characters (@samp{\\}). For example, the
following statement

@smallexample
modify [Subject] "[Anubis \\& others] &"
@end smallexample

@noindent
prepends the @code{Subject} header with the string @samp{[Anubis &
others]}. Thus, the header line

@smallexample
Subject: Test subject
@end smallexample

@noindent

after having been processed by Anubis, will contain:

@smallexample
Subject: [Anubis & others] Test subject
@end smallexample

@end deffn

@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value}
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value}

Combines the previous two cases, i.e. changes both the header
name and its value, as shown in the following example:

@smallexample
modify header [X-Mailer] [X-X-Mailer] "GNU Anubis"
@end smallexample
@end deffn

@deffn Command modify [@var{flags}] body @samp{[}@var{key}@samp{]}
Removes all occurrences of @var{key} from the message body.
For example, this statement will remove every occurrence of
the word @samp{old}:

@smallexample
modify body ["old"]
@end smallexample
@end deffn

@deffn Command modify [@var{flags}] body @samp{[}@var{key}@samp{]} @var{string}
Replaces all occurrences of @var{key} with @var{string}. For example:

@smallexample
modify body :extended ["the old \([[:alnum:]]+\)"] "the new \1"
@end smallexample
@end deffn

@node Modifying SMTP Commands
@subsection Modifying SMTP Commands

GNU Anubis is able to modify arguments of @acronym{SMTP} commands.
To instruct it to do so, define a section named @samp{SMTP}.
Anubis will call this section each time
it receives an @acronym{SMTP} command. This section can contain
any statements allowed for @samp{RULE} section, plus the
following special flavor of the @samp{modify} statement:

@deffn Command modify [@var{flags}] command @samp{[}@var{cmd}@samp{]} @var{value}
If the current @acronym{SMTP} command matches @var{cmd}, rewrite it by
using @var{value} as its argument.
@end deffn

For example, this is how to force using @samp{my.host.org} as the
@samp{EHLO} argument:

@smallexample
@group
BEGIN SMTP
modify command [ehlo] "my.host.org"
END
@end group
@end smallexample

Additionally, the ESMTP authentication settings (@pxref{ESMTP
Authentication Settings}) can be used as actions in this section.
To do so, you must first set @code{esmtp-auth-delayed} to @samp{yes}
in the @samp{CONTROL} section (@pxref{ESMTP Authentication Settings,
esmtp-auth-delayed}).  Changes in the settings take effect if they
occur either before the @samp{MAIL} @acronym{SMTP} command, or while
handling this command.  

Consider, for example, the following configuration:

@smallexample
BEGIN CONTROL
 mode transparent
 bind 25
 remote-mta mail.example.com
 esmtp-auth-delayed yes
END

BEGIN SMTP
if command ["mail from:"] "<smith(\+.*)?@@example.net>"
  esmtp-auth-id smith
  esmtp-password guessme
else
  esmtp-auth no
fi
END
@end smallexample

It delays ESMTP authentication until the receipt of the @code{MAIL}
command from the client. Authentication is used only if the mail
is being sent from @email{smith@@example.net} or any additional mailbox
of that user (e.g. @email{smith+mbox@@example.net}). Otherwise,
authentication is disabled.

The following points are worth mentioning:

@enumerate 1
@item As usual, you may use conditional expressions to decide what
to modify and how. For example, the code below replaces the domain
part of each @samp{MAIL FROM} command with @samp{gnu.org}:

@smallexample
BEGIN SMTP
if command ["mail from:"] "<(.*)@@(.*)>(.*)"
  modify command ["mail from:"] "<\1@@gnu.org>\2"
fi
END
@end smallexample

@item Each @samp{modify command} statement applies only if
the current command matches its @var{cmd} argument. In particular,
this means that you cannot modify already transferred @acronym{SMTP}
commands nor the commands to be transferred. For example, the
following code will not work:

@smallexample
@group
BEGIN SMTP
# @r{Wrong!}
if command ["mail from:"] "<>(.*)"
  modify command [ehlo] "domain.net"
fi
END
@end group
@end smallexample

It is because by the time @samp{MAIL FROM} is received, the
@samp{EHLO} command has already been processed and sent to
the server.
@end enumerate

The final point to notice is that you may use an alternative name for
that section (if you really want to). To do so, define the new name
via the @samp{smtp-command-rule} option in the @samp{CONTROL} section
(@pxref{Basic Settings,,smtp-command-rule}).

@node Inserting Files
@subsection Inserting Files

@deffn Command signature-file-append @var{yes-or-no}
@cmindex signature-file-append @var{yes-or-no}
This action command adds at the end of a message body the
@samp{-- } line, and includes a client's
@file{~/.signature} file.

Default is @samp{no}.
@end deffn

@deffn Command body-append @var{file-name}
@cmindex body-append @var{file-name}
This action command includes at the end of the message body
the contents of the given file. Unless @file{@var{file-name}}
starts with a @samp{/} character, it is taken relative to
the current user home directory.
@end deffn

@deffn Command body-clear
@cmindex body-clear
Removes the body of the message.
@end deffn

@deffn Command body-clear-append @var{file-name}
@cmindex body-clear-append @var{file-name}
Replaces the message body with the contents of the specified
file. The action is equivalent to the following command sequence:

@smallexample
body-clear
body-append @var{file-name}
@end smallexample
@end deffn


@node Mail Encryption
@subsection Mail Encryption
@cindex GNU Privacy Guard, GnuPG
@cindex Pretty Good Privacy, PGP
@cindex GPG/PGP private key
@cindex GPG/PGP public key

@deffn Command gpg-passphrase @var{passphrase}
@cmindex gpg-passphrase @var{passphrase}
Specifies your private key's pass phrase for signing messages
using the GNU Privacy Guard. To protect your passwords from
being compromised, use the 0600 (u=rw,g=,o=) permissions for the
configuration file, otherwise GNU Anubis won't accept them.

We recommend setting the @samp{gpg-passphrase} once in your
configuration file, e.g. at the start of @code{RULE} section.

GNU Anubis support for the GNU Privacy Guard is based on the
@dfn{GnuPG Made Easy} library, available from
@w{@uref{http://www.gnupg.org/gpgme.html}}.
@end deffn

@deffn Command gpg-encrypt @var{gpg-keys}
@cmindex gpg-encrypt @var{gpg-keys}
This command enables encrypting messages with the
GNU Privacy Guard (Pretty Good Privacy) public key(s).
@var{gpg-keys} is a comma separated list of keys (with no space
between commas and keys).

@smallexample
gpg-encrypt "John's public key"
@end smallexample
@end deffn

@deffn Command gpg-sign @var{gpg-signer-key}
@deffnx Command gpg-sign @samp{yes-or-default}
@cmindex gpg-sign @var{gpg-signer-key}
This command signs the message with your
GNU Privacy Guard private key. Specify a @var{passphrase} with
@code{gpg-passphrase}. Value @samp{default} means your default
private key, but you can change it if you have more than one
private key.

For example:

@smallexample
gpg-sign default
@end smallexample

or

@smallexample
@group
gpg-passphrase "my office key passphrase"
gpg-sign office@@example.key
@end group
@end smallexample
@end deffn

@deffn Command gpg-sign-encrypt @var{gpg-keys}[:@var{gpg-signer-key}]
@deffnx Command gpg-se @var{gpg-keys}[:@var{gpg-signer-key}]
@cmindex gpg-sign-encrypt @var{gpg-keys}[:@var{gpg-signer-key}]
This command simultaneously signs and encrypts the message.
It has the same effect as @command{gpg} command line switch
@option{-se}. The argument before the colon is a comma-separated list
of PGP keys to encrypt the message with. This argument is mandatory.
The @var{gpg-signer-key} part is optional. In the absence of it,
your default private key is used.

For example:

@smallexample
gpg-sign-encrypt John@@example.key
@end smallexample

or

@smallexample
gpg-se John@@example.key:office@@example.key
@end smallexample
@end deffn


@node External Processor
@subsection Using an External Processor

@deffn Command external-body-processor @var{program} [@var{args}]
@cmindex external-body-processor @var{program} [@var{args}]
Pipes the message body through @var{program}. The @var{program} must
be a filter that reads the text from the standard input
and prints the transformed text on the standard output. The output
from it replaces the original body of the message.
@var{args} are any additional arguments the program may require.
@end deffn

@cindex read-entire-body
@cindex Multi-part Messages, Processing with External Programs
The amount of data fed to the external program depends on the
message. For plain messages, the entire body is passed. For
multi-part messages, only the first part is passed by default.
This is based on the assumption that in most multi-part messages
the first part contains textual data, while the rest contains
various (mostly non-textual) attachments. There is a special
configuration variable @code{read-entire-body} that controls this
behavior (@pxref{Basic Settings}). Setting @code{read-entire-body yes}
in @code{CONTROL} section of your configuration file instructs
Anubis to pass the entire body of multi-part messages to
your external processor.

There is a substantial difference between operating in
@code{read-entire-body no} (the default) and @code{read-entire-body
yes} modes. When operating in @code{read-entire-body no}, the first
part of the message is decoded and then passed to the external
program. In contrast, when @code{read-entire-body} is set to
@code{yes}, the message is not decoded. Thus, your external processor
must be able to cope with MIME messages.

@node Quick Example
@subsection Quick Example

Here is a quick example of an action list:

@smallexample
@group
---BEGIN RULE---
if header [X-Mailer] :re ".*"
   remove [X-Mailer]
   add [X-Comment] "GNU's Not Unix!"
   gpg-sign "my password"
   signature-file-append yes
fi
---END---
@end group
@end smallexample

@noindent
The example above removes the @samp{X-Mailer:} header from the
message, adds the @samp{X-Comment:} header, then signs the
message with your private key, and finally adds a signature from
the file in your home directory.


@node Using Guile Actions
@section Using Guile Actions
@cindex Guile

@dfn{Guile} is the @dfn{GNU's Ubiquitous Intelligent Language for
Extensions}. It provides a Scheme interpreter conforming to the R5RS
language specification. GNU Anubis uses Guile as its extension language.

This section describes how to write GNU Anubis actions in Scheme.
It assumes that the reader is sufficiently familiar with the
Scheme language. For information about the language, refer to
@ref{Top,,,r5rs,Revised(5) Report on the Algorithmic Language Scheme}.
For more information about Guile,
@xref{Top,,Overview,guile,The Guile Reference Manual}.

@menu
* Defining Guile Actions::
* Invoking Guile Actions::

Predefined Guile Actions
* Rot-13::
* Remailers::
* Entire Message Filters::
@end menu


@node Defining Guile Actions
@subsection Defining Guile Actions
@cindex Guile Actions, defining

A Guile action is defined as follows:

@smalllisp
(define (@var{function-name} @var{header} @var{body} . @var{rest})
 ...)
@end smalllisp

@noindent
Its arguments are:

@table @var
@item header
List of message headers. Each list element is a cons

@smallexample
(@var{name} . @var{value})
@end smallexample

@noindent
where @var{name} is the name of the header field, and @var{value} is
its value with final CRLF stripped off. Both @var{name} and
@var{value} are strings.

@item body
A string containing the message body.

@item rest
Any additional arguments passed to the function from the configuration
file (@pxref{Invoking Guile Actions}). This argument may be absent if
the function is not expected to take optional arguments.
@end table

The function must return a cons whose car contains the new message
headers, and cdr contains the new message body. If the car is
@code{#t}, it means that no headers are changed. If the cdr is
@code{#t}, it means that the body has not changed. If the cdr is
@code{#f}, Anubis will delete the entire message body.

As the first example, let's consider a @dfn{no-operation} action,
i.e. an action that does not alter the message in any way. It can
be written in two ways:

@smalllisp
(define (noop-1 header body)
  (cons header body))
  
(define (noop-2 header body)
  (cons #t #t))
@end smalllisp

The following example is a function that deletes the message body
and adds an additional header:

@smalllisp
(define (proc header body)
  (cons (append header
                (cons "X-Body-Deleted" "yes"))
        #f))
@end smalllisp        

Let's consider a more constructive example. The following function
checks if the @code{Subject} header starts with string @samp{ODP:}
(a Polish equivalent to @samp{Re:}), and if it does, 
replaces it with @samp{Re:}. It also adds the header

@smallexample
X-Processed-By: GNU Anubis
@end smallexample

@noindent
Additionally, an optional argument can be used.  If it is given, it will
be appended to the body of the message.

@smalllisp
(define (fix-subject hdr body . rest)
  "If the Subject: field starts with characters \"ODP:\", replace
them with \"Re:\".
If REST is not empty, append its car to BODY"
  (cons (append
         (map (lambda (x)
                (if (and (string-ci=? (car x) "subject")
                         (string-ci=? (substring (cdr x) 0 4) "ODP:"))
                    (cons (car x)
                          (string-append "Re:"
                                         (substring (cdr x) 4)))
                    x))
              hdr)
         (list (cons "X-Processed-By" "GNU Anubis")))
        (if (null? rest)
            #t
            (string-append body "\n" (car rest)))))
@end smalllisp


@node Invoking Guile Actions
@subsection Invoking Guile Actions
@cindex @code{guile-process}

Guile actions are invoked from the @code{RULE} section using the
@code{guile-process} command. Its syntax is:

@deffn {Scheme Function} @var{function} @var{args}
Arguments:

@table @var
@item function
The name of the Guile function to be invoked.

@item args
Additional arguments. These are passed to the @var{function} as
its third argument (@var{rest}).
@end table
@end deffn

To pass keyword arguments to the function, use the usual Scheme
notation: @samp{#:key}.

As an example, let's consider the invocation of the @code{fix-subject}
function, defined in the previous subsection:

@smallexample
guile-process fix-subject <<-EOT
                                ----------
                                Kind regards,
                                Antonius Block
                          EOT
@end smallexample

@noindent
In this example, the additional argument (a string of three lines) is
passed to the function, which will add it to the message of the body.


@node Rot-13
@subsection Support for @sc{rot-13}
@cindex rot-13

The @sc{rot-13} transformation is a simple form of encryption where the
letters A-M are transposed with the letters L-Z. It is often used in
Usenet postings/mailing lists to prevent people from accidentally
reading a disturbing message.

GNU Anubis supports @sc{rot}-13 via a loadable Guile function. To enable
this support, add the following to your @code{GUILE}
section:

@smallexample
guile-load-program rot-13.scm
@end smallexample

Then, in your @code{RULE} section use:

@deffn {Scheme Function} rot-13 @var{keyword-arguments}
@fnindex rot-13, Scheme function
The command accepts the following @var{keyword-arguments}:

@table @code
@item #:body
Encrypt the entire body of the message

@item #:subject
Encrypt the @samp{Subject} header.
@end table

For example:

@smallexample
@group
trigger "rot-13.*body"
 guile-process rot-13 #:body
done

trigger "rot-13.*subj"
 guile-process rot-13 #:subject
done
@end group
@end smallexample  
@end deffn

@node Remailers
@subsection Remailers Type-I
@cindex remailer

GNU Anubis supports remailers of type I. The support is written
entirely in Scheme. To enable it, you need to specify the following
in the @code{GUILE} section of your configuration file:

@smallexample
@group
guile-load-program remailer.scm
@end group
@end smallexample

To send the message via a remailer, use the following command
in the @code{RULE} section:

@deffn {Scheme Function} remailer-I @var{keyword-arguments}
@fnindex remailer-I, Scheme function
@cmindex guile-process remailer-I @var{keyword-arguments}
The @var{keyword-arguments} specify the various parameters for
the remailer. These are:

@table @code
@item #:rrt @var{string}
This is the only required keyword argument. It sets the value for the
@dfn{Request Remailing To} line. @var{string} should be your actual
recipient's email address.

@item #:post @var{news-group}
Adds the @samp{Anon-Post-To: @var{news-group}} line,
and prepares the message for sending it to the Usenet
via a remailer. Note, that this is only possible with remailers
that support @samp{Anon-Post-To:} header.

@item #:latent @var{time}
Adds the @samp{Latent-Time:} line, that causes a remailer to keep
your message for specified @var{time} before forwarding it. 

@item #:random
Adds random suffix to the latent time.

@item #:header @var{string}
Adds an extra header line to the remailed message.
@end table

Example:

@smallexample
@group
trigger "remail:(.*)/(.*)"
 guile-process remailer-I \
             #:rrt antonius_block@@helsingor.net \
             #:post \1 \
             #:latent \2 \
             #:header "X-Processed-By: GNU Anubis & Remailer-I"
done
@end group
@end smallexample
@end deffn

Some remailers require the message to be GPG encrypted or signed.
You can do so by placing @code{gpg-encrypt} or @code{gpg-sign}
statement right after the invocation of @code{remailer-I}, for
example:

@smallexample
@group
trigger "remail:(.*)/(.*)"
 guile-process remailer-I \
             #:rrt antonius_block@@helsingor.net \
             #:post \1 \
             #:latent \2 \
             #:header "X-Processed-By: GNU Anubis & Remailer-I"
 gpg-sign mykey
done
@end group
@end smallexample

@xref{Mail Encryption}, for more information on mail encryption in
GNU Anubis.

@node Entire Message Filters
@subsection Entire Message Filters
@cindex entire-msg.scm
@fnindex entire-msg-filter, Scheme function
@fnindex openssl-filter, Scheme function
@cindex entire message, filtering

There may be cases when you need to use an external filter that
processes entire message (including headers). You cannot use
@code{external-body-processor}, since it feeds only the
message body to the program. To overcome this difficulty, GNU Anubis
is shipped with @file{entire-msg.scm} module. This module provides
Scheme function @code{entire-msg-filter}, which is to be used in
such cases.

@deffn {Scheme Function} entire-msg-filter @var{program} [@var{args}]
Feeds entire message to the given program. The output from the program
replaces message headers and body.

@table @var
@item progname
Full pathname of the program to be executed.

@item args
Any additional arguments it may require.
@end table
@end deffn

Suppose you have a program @code{/usr/libexec/myfilter}, that accepts
entire message as its input and produces on standard output a
modified version of this message. The program takes the name of a
directory for temporary files as its argument. The following example
illustrates how to invoke this program:

@smallexample
BEGIN GUILE
guile-load-program entire-msg.scm
END

BEGIN RULE
guile-process entire-msg-filter /usr/libexec/myfilter /tmp
END
@end smallexample

Another function defined in this module is @code{openssl-filter}:

@deffn {Scheme Function} openssl-filter @var{program} [@var{args}]

This function is provided for use with @code{openssl}
program. @code{Openssl} binary attempts to rewind its input and
fails if the latter is a pipe, so @code{openssl} cannot be used
with @code{entire-msg-filter}. Instead, you should use 
@code{openssl-filter}. Its arguments are:

@table @var
@item program
Path to @code{openssl} binary.

@item args
Its arguments
@end table

@xref{S/MIME}, for an example of use of this function.
@end deffn

@node Invoking Anubis
@chapter Invoking GNU Anubis
@cindex command line

The @command{anubis} executable acts like a daemon, i.e. after
a successful startup it disconnects itself from the controlling
terminal@footnote{Unless given the @option{--foreground} command line
option.} and continues its work in the background. The program reads
its initial settings from the @samp{CONTROL} section of the site-wide
configuration file (@pxref{CONTROL Section}) and from the command
line options.

Command line options have higher priority than configuration file
settings and can be used to temporarily override them.

The following command line options are understood:

@table @samp
@item --altrc @var{file}
Specify alternate system configuration file.

@item --bind [@var{host}:]@var{port}
@itemx -b
Specify the @acronym{TCP} port on which GNU Anubis listens for connections.
The default @var{host} value is @w{@samp{INADDR_ANY}}, and default
@var{port} number is 24 (private mail system).

@item --check-config[=@var{level}]
@itemx -c[@var{level}]
Run the configuration file syntax checker. Optional @var{level}
specifies the verbosity level. The following levels are allowed:

@table @asis
@item 0
Display only errors. This is the default.

@item 1
Print the syntax tree after parsing the file.

@item 2
As @samp{1}, but also prints the parser traces.

@item 3
As @samp{2}, but also prints the lexical analyzer traces.
@end table

@item --debug
@itemx -D
Debug mode.

@item --foreground
@itemx -f
Foreground mode.

@item --help
Print short usage summary and exit.

@item --local-mta @var{file}
@itemx -l
Execute a local @acronym{SMTP} server, which works on standard input and output
(inetd-type program). This option excludes the @samp{--remote-mta} option.

@item --mode @var{mode-name}
@itemx -m @var{mode-name}
Selects Anubis operation mode. Allowed values for @var{mode-name}
are @samp{proxy}, @samp{transparent} (the default), @samp{auth} and
@samp{mda}. @xref{Authentication}, for the detailed discussion of
Anubis operation modes.

@item --norc
Ignore system configuration file.

@item --relax-perm-check
Do not check a user config file permissions.

@item --remote-mta @var{host}[:@var{port}]
@itemx -r
Specify a remote @acronym{SMTP} host name or @acronym{IP} address, which GNU Anubis will
connect and forward mail to.
The default @var{port} number is 25.

@item --silent
@itemx -s
Work silently.

@item --show-config-options
Print the list of configuration options used to build GNU Anubis.

@item --stdio
@itemx -i
Use the @acronym{SMTP} protocol (OMP/Tunnel) as described in @acronym{RFC} 821 on standard
input and output.

@item --verbose
@itemx -v
Work noisily.

@item --version
Print version number and copyright.
@end table

Examples:

@smallexample
$ anubis --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Run GNU Anubis on port number 24 (private mail system). Note that
you must have root privileges to use port number lower than 1024.
Make the tunnel between your localhost:24 and @var{smtp-host}:25.

@smallexample
$ anubis -f --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Same as above, but run GNU Anubis in a foreground mode.

@smallexample
$ anubis -f --local-mta /usr/sbin/sendmail -- sendmail -bs
@end smallexample

@noindent
Same as above, but create a tunnel between localhost:24
and a local program (local @acronym{MTA}). In this example local program
is @command{sendmail} with @samp{-bs} command line option.
The @samp{-bs} option forces @command{sendmail} to work on standard
input and output.

@smallexample
$ anubis --norc --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Do not read the system configuration file, make the tunnel between
localhost:24 and @var{smtp-host}:25.

@smallexample
$ anubis --bind localhost:1111 --remote-mta @var{smtp-host}:25
@end smallexample

@noindent
Create the tunnel between localhost:1111 and @var{smtp-host}:25.

@smallexample
$ anubis -i
@end smallexample

@noindent
Use the @acronym{SMTP} protocol (OMP/Tunnel) as described in @acronym{RFC} 821
on standard input and output.


@node Quick Start
@chapter Quick Start

By default, GNU Anubis binds to port number 24 (private mail system),
so there shouldn't be any conflict with your local @acronym{MTA} (Mail
Transport Agent). You only have to reconfigure your @acronym{MUA} (Mail User
Agent) to talk to GNU Anubis directly on port number 24. All
@acronym{MUA}s are normally set up to talk directly to the
@acronym{MTA}, so you must change their settings and specify GNU
Anubis' port number as their target. This makes GNU Anubis act as
an outgoing mail processor between your @acronym{MUA} and the
@acronym{MTA}. Read your @acronym{MUA}'s documentation for more
information. 

Then you need to choose whether you want to connect GNU Anubis to a remote
or local @acronym{SMTP} host via @acronym{TCP/IP} or a local
@acronym{SMTP} program, which works on standard input and output. In
the former case, specify the following option: 

@smallexample
REMOTE-MTA @var{smtp-host}:25
@end smallexample

@noindent
In the latter case (local @acronym{SMTP} program), use this:

@smallexample
LOCAL-MTA @var{/path/to/your/mta/mta-executable} -bs
@end smallexample

Please note that the @samp{-bs} command line option is a common way
to run @acronym{MTA}s on standard input and output, but it is not a rule.
Refer to your @acronym{MTA}'s documentation, for instructions on how
to get it working on standard input and output.

If you would like to run GNU Anubis on port number 25 (which is a
default value for the @acronym{SMTP}) or any other port number, then
use the @samp{bind} keyword. For instance, the following code will
bind GNU Anubis to @samp{localhost:25}:

@smallexample
bind localhost:25
@end smallexample

This can make a conflict between GNU Anubis and your local
@acronym{MTA}, which usually listens on port number 25. To solve this,
disable the @acronym{MTA} and specify the
@samp{local-mta} keyword, or run @acronym{MTA} on port number
different than GNU Anubis' port number (e.g. 1111). For example:

@smallexample
@group
bind localhost:25
remote-mta localhost:1111
@end group
@end smallexample

@strong{Caution:} Make sure that your local machine doesn't accept any
incoming mail (i.e. it is @emph{not} a POP or IMAP server), otherwise
you cannot disable your @acronym{MTA} or change its port number!

@node TLS/SSL
@chapter Using the TLS/SSL Encryption
@cindex Transport Layer Security, TLS
@cindex Secure Socket Layer, SSL
@cindex GnuTLS
@cindex encryption

The @acronym{TLS} (Transport Layer Security) protocol provides
communications privacy over the Internet. It is described in
@acronym{RFC} 2246 document. The protocol allows client/server
applications to communicate in a way that prevents
eavesdropping, tampering, or message forgery. The primary goal of the
protocol is to provide privacy and data integrity between two
communicating applications. The @acronym{TLS} protocol itself is based on the
@acronym{SSL} 3.0 (Secure Socket Layer) protocol specification.

GNU Anubis supports the @acronym{TLS/SSL} (via the GnuTLS, a Transport
Layer Security Library available from @w{@uref{http://www.gnutls.org/}}),
but your @acronym{MTA} must provide the @samp{STARTTLS} command
first. This can be checked by:

@smallexample
@group
$ telnet @var{your-smtp-host} 25
  ehlo @var{your-domain-name}
@end group
@end smallexample

@noindent
@cindex oneway TLS encryption
The server will response with all its available commands.
If you see the word @samp{STARTTLS}, then you can use the
@acronym{TLS/SSL} encryption. If your @acronym{MUA} doesn't support
the @acronym{TLS/SSL} encryption, but your @acronym{MTA} does, then
you should use the @samp{oneway-ssl} keyword in your configuration
file. Before using the @acronym{TLS/SSL} encryption, generate
a proper private key and a certificate. GNU @command{anubis} provides
a scrypt @file{keygen.sh} which can be used for this, e.g.:

@smallexample
@group
$ cd anubis-directory
$ ./build/keygen.sh
@end group
@end smallexample

@noindent
This will create the @file{anubis.pem} file.
Copy it to the directory of your choice, e.g. @w{@file{/usr/share/ssl/certs/}}.
Next, edit your configuration file by adding:

@smallexample
@group
ssl yes
ssl-key @var{path-to-the-private-key}
ssl-cert @var{path-to-the-certificate}
@end group
@end smallexample

For example:

@smallexample
@group
ssl-key /usr/share/ssl/certs/anubis.pem
ssl-cert /usr/share/ssl/certs/anubis.pem
@end group
@end smallexample

@noindent
@strong{Caution:} Each client can specify its own private key
and a certificate by adding the @samp{ssl-key} and @samp{ssl-cert}
keywords in its own user configuration file.

@noindent
@xref{Encryption Settings}, for details.

@node S/MIME
@chapter Using S/MIME Signatures
@cindex smime
@cindex openssl

Anubis version @value{VERSION} does not yet provide built-in support
for @acronym{S/MIME} encryption or signing. To encrypt or sign messages using
@acronym{S/MIME}, you will have to use external programs. Usually such programs
require the whole message as their input, so simply using
@code{external-body-processor} will not work. GNU Anubis distribution
includes a special Guile program, @file{entire-msg.scm}, designed for
use with such programs. For its detailed description, please refer to
@ref{Entire Message Filters}. This chapter addresses a special case of
using it with @code{openssl} to sign outgoing messages.

To use @code{openssl} for @acronym{S/MIME} signing, invoke it using
@code{openssl-filter} function defined in @file{entire-msg.scm}. Give
it at least @code{-sign} and @code{-signer} arguments. Notice, that
you should not specify any input or output files.

The following example illustrates this approach:

@smallexample
BEGIN GUILE
guile-load-program entire-msg.scm
END

BEGIN RULE
guile-process openssl-filter /usr/local/ssl/bin/openssl \
              smime -sign -signer FILE
END
@end smallexample

@node MDA Mode
@chapter Using Anubis to Process Incoming Mail
@cindex MDA mode
@cindex incoming mail, processing

Historically Anubis was designed to process outgoing mail. Support for
processing incoming mail was added in version 4.1.

To process incoming mail, Anubis must be started as @dfn{mail
delivery agent} from your @acronym{MTA} configuration file. The invocation
line must contain @option{--mode=mda} option, that tells Anubis
to act in @dfn{mail delivery mode}. In this mode, Anubis receives
the message from standard input, processes it using configuration
file sections named @code{incoming-mail-rule} (@pxref{Basic Settings,,
incoming-mail-rule}) and finally calls local mailer to actually
deliver the modified message. The local mailer must be given using
@option{--local-mta} option.


Let's summarize the special features of mail delivery mode:
@FIXME{This is basically a reminder for me to provide a detailed
description of MDA mode}

@enumerate 1
@item
The mode is triggered by @option{--mode=mda} in the command line.
It cannot be specified in configuration file. @FIXME{Why?}

@item
Anubis uses local mailer to actually deliver messages. The invocation
line of the local mailer must be given via @option{--local-mta}
command line option. The @option{local-mta} settings (if any) (@pxref{Basic
Settings}) are ignored. @FIXME{Is it really so? And, again: why?}

The local mailer invocation line can contain meta-variables
@code{%sender} and @code{%recipient}, which will be replaced by
the actual sender and recipient email addresses before starting
the mailer.

@item
A special option @option{--from} may be used in Anubis command line.
This option sets sender email address (see @code{%sender} meta
variable above). It implies @option{--mode=mda}. If the option is
not given, GNU Anubis will deduce sender address from UNIX
@samp{From } header or, if it is not present, from the value of
@code{From} @acronym{SMTP} header.

@item
In MDA mode, Anubis takes recipient email addresses from the command line.

@item
Anubis uses a separate rule section for processing incoming mails. The
default section name is @samp{INCOMING}. It may be overridden in 
system configuration file using @option{incoming-mail-rule}
(@pxref{Basic Settings,,incoming-mail-rule}).
@end enumerate

The following discussion explains how to configure Anubis in MDA mode with
different mail transport agents.

@itemize @bullet
@item Sendmail

If you use @code{mc} file to generate @file{sendmail.cf}, use
@code{LOCAL_MAILER_PATH} and @code{LOCAL_MAILER_ARGS} as shown
in the following example:

@smallexample
@group
define(`LOCAL_MAILER_PATH', `/usr/local/sbin/anubis')
define(`LOCAL_MAILER_ARGS',
       `mail --mode=mda -l '/libexec/mail.local -f %sender %recipient')
@end group
@end smallexample

@noindent
If you prefer to directly edit @file{sendmail.cf}, use @code{M}
macro to declare Anubis as a local mailer. For example:
          
@smallexample
@group
Mlocal, P=/usr/local/sbin/anubis,
        F=lsDFMAw5:/|@@qSPfhn9,
        S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
        T=DNS/RFC822/X-Unix,
        A=mail --mode=mda -l '/libexec/mail.local -f %sender %recipient' $u
@end group        
@end smallexample
                                
@item Exim

With @command{exim}, you will need to declare appropriate transport
and director in @file{exim.conf}:

@smallexample
@group
# transport
mail_local_pipe:
  driver = pipe
  command = /usr/local/sbin/anubis --mode=mda \
             -l '/libexec/mail.local -f %sender %recipient' $local_part
  return_path_add
  delivery_date_add
  envelope_to_add

# director
mail_local:
  driver = localuser
  transport = mail_local_pipe
@end group   
@end smallexample
              
@end itemize
@FIXME{More mailers, anybody?}

@node Mutt
@chapter Using Mutt with Anubis
@cindex mutt

Newer versions of @command{mutt} (1.5.20) are able to
send mail directly via @acronym{SMTP} channel.  Older ones
(1.4.1 and 1.5.3) can only use an external program to send
messages.

The following sections describe the recommended ways of
configuring @command{mutt}.

@menu
* mutt-smtp::            Using @acronym{SMTP}
* maidag::               Using GNU Mailutils
* msg2smtp.pl::          Using @command{msg2smtp.pl}
@end menu

@node mutt-smtp
@section Configure Mutt @acronym{SMTP}

@command{Mutt} version 1.5.20 supports @acronym{SMTP} if compiled
with the @option{--enable-smtp} option. You can verify if it is so
by running the following command:

@smallexample
mutt -v | fgrep '+USE_SMTP'
@end smallexample

If the output contains @samp{+USE_SMTP}, then @command{mutt} is
compiled properly and you can use further instructions from this
section.

@table @code
@item set smtp_url = "@var{url}"
Sets @acronym{URL} of the Anubis server. The format of @var{url} is

@smallexample
smtp://[@var{user}[:@var{pass}]@@]host[:@var{port}]
@end smallexample

@noindent
where square brackets denote optional parts.  If Anubis is running
in @samp{auth} mode, @var{user} and @var{pass} become mandatory.
The latter can also be set using the following statement.

@item set smtp_pass = "@var{pass}"
Sets @acronym{SMTP} password.

@item set smtp_authenticators="@var{auth-list}"
Sets the list of the authentication methods to try when
attempting to perform @acronym{SMTP AUTH}.  The argument
is a colon-delimited list of method names.
@end table

For example, if Anubis runs on the server @samp{anubis.domain.org},
port 24, your @file{.muttrc} could contain:

@smallexample
set smtp_url = "smtp://anubis.domain.org:24"
@end smallexample

@node maidag
@section Using GNU mailutils as an interface to mutt
@cindex maidag
@cindex mailutils
@cindex GNU mailutils

GNU Mailutils is a collection of utilities for handling electronic
mail. It includes lots of programs necessary for dealing with
e-mail messages. One of them is @command{maidag} --- a general-purpose
mail delivery agent (@pxref{maidag,,, mailutils, GNU Mailutils
Manual}).

The package can be downloaded from
@url{ftp://ftp.gnu.org/@/gnu/@/mailutils} or any of the mirrors 
(See @url{http://www.gnu.org/@/order/@/ftp.html} for a complete
list of these. Please, select the mirror closest too you). The
complete information about the package is available from its
home page at @url{http://www.gnu.org/@/software/@/mailutils/} 

To use @command{maidag}, first download and install GNU mailutils
(as usual the package is shipped with files @file{README} and
@file{INSTALL} which provide the necessary guidelines). Then
add to your @file{.muttrc} file the following line:

@smallexample
set sendmail="@var{maidag} --url smtp://@var{hostname}[:@var{port}]"
@end smallexample

@noindent
where @var{maidag} stands for the full file name of
@command{maidag} utility, @var{hostname} and optional
@var{port} specify the host name (or @acronym{IP} address) of the machine
running @command{anubis} and the port it listens on. Notice, that
the default port value for @samp{smtp} is 25, which means
that in most cases you will have to specify it explicitly.

For example, suppose you run @command{anubis} on machine
@samp{anubis.example.org} and that it listens on port 24.
Let's also assume you have installed mailutils in the default
location, so that full file name of the @command{maidag} utility is
@file{/usr/local/sbin/maidag}. Then, your @file{.muttrc}
will contain:

@smallexample
set sendmail="/usr/local/sbin/maidag \
              --url smtp://anubis.example.org:24"
@end smallexample

@noindent
(the line being split for readability).

@node msg2smtp.pl
@section Using msg2smtp.pl as an interface to mutt
@cindex msg2smtp.pl

GNU Anubis is shipped with @code{msg2smtp.pl} --- a perl script
designed as an interface between it and @command{mutt}. The script
is kindly contributed by Michael de Beer. 

The script is located in the subdirectory @file{contrib} of 
GNU Anubis distribution. Copy it to any convenient location, e.g.:

@smallexample
cp anubis-@value{VERSION}/contrib/msg2smtp.pl /usr/local/libexec
@end smallexample

@noindent
and add the following line to your @file{.muttrc}:

@smallexample
set sendmail="/usr/local/libexec/msg2smtp.pl -h @var{hostname} -p @var{port}"
@end smallexample

@noindent
where @var{hostname} and @var{port} specify the host name (or @acronym{IP}
address) of the machine running @command{anubis} and the port it
listens on, respectively.

A complete description of @command{msg2smtp.pl} and a discussion of
its command line switches can be found in file @file{contrib/msg2smtp.txt}.

@node Problems
@chapter Reporting Bugs
@cindex bugs
@cindex problems

Please send any bug reports, improvements, comments,
suggestions, or questions to @email{bug-anubis@@gnu.org}.

Before reporting a bug, make sure you have actually found
a real bug. Carefully reread the documentation and see if it
really says you can do what you are trying to do. If it is
not clear whether you should be able to do something or not,
report that too; it's a bug in the documentation!

@node Pixie-Dixie
@appendix Pixie & Dixie
@include pixie-dixie.texi

@node Multi-Part Message Processing
@appendix Multi-Part Message Processing
@include mime.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@unnumbered Concept Index
@printindex cp
@shortcontents
@contents

@bye

@c anubis.texi ends here
