[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Configuration

The behavior of GNU Anubis is controlled by two configuration files. The system configuration file, ‘/etc/anubisrc’, specifies system-wide options that affect all users. This file is usually owned by root. The user configuration file specifies what GNU Anubis should do for a particular user. By default it is located in ‘~/.anubisrc’. This location can be changed in auth mode. To protect your passwords in the configuration files, use the 0600 (u=rw,g=,o=) permissions, otherwise GNU Anubis won't accept them.

Lexical Structure

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

Quoted strings follow the same syntax rules as in C language. A backslash character ‘\’ alters the meaning of the character following it. This special construct is called 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:

\a

Audible bell character (ASCII 7)

\b

Backspace (ASCII 8)(5)

\e

Escape character (ASCII 27)

\f

Form feed (ASCII 12)

\n

Newline (ASCII 10)

\r

Carriage return (ASCII 13)

\t

Horizontal tab (ASCII 9)

\d

(where ‘d’ represents a single decimal digit) Reproduced verbatim.

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

 
"This string contains \"quoted string\"."

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

 
"This string is split\nover two lines"

"This string is split\
over two lines"

The familiar shell here document syntax may be used to produce a word containing several lines of text. The syntax is:

 
<<[-]delimiter
    text
delimiter

If “here document” starts with ‘<<-’, then all leading tab characters are stripped from input lines and the line containing delimiter. This allows to indent here-document in a natural fashion.

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

 
first-word "second word" <<-EOT
                            Third word
                            containing several
                            lines of text
                            EOT

This line contains three words: ‘first-word’, ‘second word’ and the third one composed of the three lines between the ‘EOT’ markers.

If a statement is very long, it may be split among several lines of text. To do so, precede the newline characters with a backslash ‘\’, e.g.:

 
a very long statement\
  occupying several lines\
  of text
 

A ‘#’ in a line starts a comment. It and the rest of the line are ignored. Comments may appear on any of the lines in the configuration file, except on a commands and within a “here-document” construction. A line containing just a comment (with perhaps spaces before it) is effectively blank, and is ignored. For example:

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

Logical Structure

The statements within a configuration file are grouped into sections. Each section has its name. A section begins with one of the following constructs:

 
BEGIN name
---BEGIN name---

and ends with one of the following constructs:

 
END
---END---

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

The sections cannot be nested.

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

The predefined section names are:

AUTH

Controls authentication mechanisms.

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.

TRANSLATION

This section specifies a translation map for remapping remote or local users. It may be used only in the system-wide configuration file.

GUILE

Contains the settings of the Guile interpreter. The section is allowed in both configuration files.

RULE

Defines the rules that are used to alter the contents of the messages (conditional and unconditional rules).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 AUTH Section

AUTH session controls various aspects of authentication mode.

Option: smtp-greeting-message text

Configures the greeting message issued by GNU Anubis upon accepting the connection.

Option: smtp-help-message help-text

Sets the test of the message issued by Anubis in response to SMTP HELP command. Help-text is a list of strings. Each string from the list will be displayed at a separate response line.

Option: sasl-password-db url

Sets the user database URL (see section User Database).

Option: sasl-allowed-mech mech-list

Defines the list of allowed authentication methods.

Option: sasl-service name

Set SASL service name. It is used, among others, with GSSAPI authentication method. Default is ‘anubis’.

Option: sasl-hostname name

Set SASL hostname. By default, the server determines it automatically. If, however, it makes a wrong guess, you can fix it using this directive.

Option: sasl-realm name

Set SASL realm. By default, the domain part of the current hostname is used as SASL realm.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 CONTROL Section

The ‘CONTROL’ section specifies the basic GNU Anubis behavior. Specified in the system configuration file, it applies to all users on the machine, but each user can specify its own ‘CONTROL’ section, to customize own settings. Of course, not all options can be set or changed by user. Some options can only be set in the system configuration file, and some only in user configuration file. By default, options specified in user configuration file have a higher priority that those specified in system configuration file.

All option names are case insensitive, so you can use for instance: bind or BIND or BiNd, and so on.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.1 Basic Settings

(This message will disappear, once this node revised.)

Option: bind [host:]port

Specify the TCP port on which GNU Anubis listens for connections. The default host value is ‘INADDR_ANY’, which means that anyone can connect to GNU Anubis. The default port number is 24 (private mail system). This option is available only in the system configuration file. If you would like, for instance, to bind GNU Anubis to port 25 (SMTP) and limit its clients only to those from ‘localhost’, then set the following in your system configuration file:

 
bind localhost:25
Option: remote-mta host[:port]

Specify a remote SMTP host name or IP address, which GNU Anubis will connect and forward mail to (after processing). The default port number is 25. This option is available in both configuration files.

Option: local-mta file-name [args]

Execute a local SMTP server, which works on standard input and output (inetd-type program). This option excludes the ‘remote-mta’ keyword (or ‘--remote-mta’ command line option). For example:

 
local-mta /usr/sbin/sendmail -bs
Option: mode mode-name

Selects Anubis operation mode. Allowed values for mode-name are:

transparent
auth

See section Authentication, for the detailed discussion of GNU Anubis operation modes.

Option: read-entire-body yes-or-no

When processing a multi-part message using an external filter (see section Using an External Processor) Anubis normally feeds to it only the first part. The rest of the message is copied verbatim. To alter this behavior so that your external program sees the entire message body, set read-entire-body yes in your control section.

Option: incoming-mail-rule string

Declares name of processing sections for incoming mail. Default is ‘INCOMING’. This option is available only for system configuration file. See section Using Anubis to Process Incoming Mail, for detailed description of incoming mail processing.

Option: outgoing-mail-rule string

Declares name of processing sections for outgoing mail. Default is ‘RULE’. This option is available only for system configuration file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.2 Output Settings

Option: termlevel level

This is a logging level for syslogd or a terminal (if using the ‘--foreground’ command line option). level can be one of the following:

normal

Only errors are logged. This is the default level.

verbose

Produce more diagnostic output.

debug

Produce debugging output.

silent

Do not log anything.

This command may be used only in system configuration file.

Option: logfile file-name

This command specifies an additional file, where GNU Anubis can log its information, but only those information available for a client. Only in user configuration file. For example:

 
logfile "anubis.log"

This will log to the ‘~/anubis.log’ file in a client's home directory.

Option: loglevel level

This option specifies an output level for an additional file (‘logfile’). It can be used only in user configuration file. level is one of the following:

none
fails
all
Option: tracefile yes-or-no
Option: tracefile file-name

This option instructs anubis to log the execution of tests and actions from the RULE sections. This is useful for debugging the configuration files.

When this option is used in the system-wide configuration file, only its first form is allowed. Using ‘tracefile yes’ enables logging of the actions and tests to the default syslog channel. Using ‘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 ‘tracefile yes’ enables logging to the same file as ‘logfile’ (if possible).

Option: HANG delay

Do not use this option, unless you are developing or debugging Anubis! This option instructs a child process to hang for the given number of seconds. Before hanging, the process will issue the following diagnostic message, no matter what the settings of termlevel variable were:

 
Child process suspended for delay seconds

This option is useful for Anubis developers who wish to attach to a child process with debugger. After attaching, set the variable _anubis_hang to zero to continue processing. It is useful to add the following statement to your ‘.gdbinit’ file:

 
set variable _anubis_hang=0

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.3 Proxy Settings

Option: socks-proxy host[:port]

This option enables tunneling the connections through a SOCKS proxy server, specified as an argument host. The port default value is 1080, which is a common port number for SOCKS proxies.

Option: socks-v4 yes-or-no

This specifies a SOCKS protocol version 4. By default it is turned off, and a default mode is SOCKS protocol version 5.

Option: socks-auth username:password

Specify a user name and a password, if a SOCKS proxy server requires them. A username and a password are separated with a colon (‘:’).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.4 ESMTP Authentication Settings

The following options set authentication credentials for ESMTP authentication. You may use this option, for example, if your MTA requires such an authentication, but your MUA does not support it.

Option: esmtp-allowed-mech mech-list

Defines the list of allowed authentication mechanisms. Mech-list is a list of valid authentication mechanism names separated by whitespace.

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

 
PLAIN LOGIN CRAM-MD5 ANONYMOUS

and you have following statement in your configuration file

 
esmtp-allowed-mech DIGEST-MD5 CRAM-MD5 LOGIN

In this case Anubis will select CRAM-MD5.

Option: esmtp-require-encryption mech-list

This statement declares the list of mechanisms that can be used only over a TLS encrypted channel. By default Anubis uses

 
esmtp-require-encryption LOGIN PLAIN

This prevents sending user password over an unencrypted connection.

Option: esmtp-auth-id authentication-id

Sets authentication ID (user name).

Option: esmtp-authz-id authorization-id

Sets authorization ID (user name).

Option: esmtp-password password

Sets password to be used in authentication.

Option: esmtp-auth username:password

This option sets both authentication and authorization IDs and the password. It is equivalent to

 
esmtp-auth-id username
esmtp-authz-id username
esmtp-password password

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

Option: esmtp-service service-name

Sets the name of GSSAPI service.

Option: esmtp-hostname hostname

Sets hostname of the machine.

Option: esmtp-generic-service servise-name

Sets generic service name.

Option: esmtp-passcode passcode

Sets passcode.

Option: esmtp-realm realm-name

Sets GSSAPI realm.

Following option is useful with ANONYMOUS authentication mechanism:

Option: esmtp-anonymous-token token

Sets the token to be used with ANONYMOUS authentication mechanism


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.5 Encryption Settings

Option: ssl yes-or-no

This option enables the TLS/SSL encryption between the MUA and the MTA. Value ‘no’ is the default, but using the TLS/SSL encryption is recommended. You should also specify a private key and a certificate using the ‘ssl-key’ and ‘ssl-cert’ keywords (defined below). See section Using the TLS/SSL Encryption, for details.

Option: ssl-oneway yes-or-no

This option enables the ONEWAY encryption. Use this mode, when you want to use the TLS/SSL, but your MUA doesn't provide a support for ESMTP TLS/SSL. Using this option doesn't require using the ‘ssl-key’ and ‘ssl-cert’ keywords.

Option: ssl-cert file-name

Specify a certificate for the TLS/SSL encryption. Value ‘anubis.pem’ is the default.

Option: ssl-key file-name

Specify a private key for the TLS/SSL encryption. Value ‘anubis.pem’ is the default.

Option: ssl-cafile file-name

Specify a CA certificate file (supported only by GnuTLS).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.6 Security Settings

The following options control various security settings.

Option: allow-local-mta yes-or-no

For security reasons, this option is set to ‘no’, but the ‘yes’ value enables the ‘local-mta’ keyword (or ‘--local-mta’ command line option), so if you want to use a local mail server, which works on standard input and output, a supervisor must set this option to ‘yes’. The option is available only in system configuration file.

Option: drop-unknown-user yes-or-no

This option drops an unknown user, i.e. a client which has not been verified by IDENT service. Value ‘no’ is the default.

Option: user-notprivileged username

For security reasons, it is recommended to create an unprivileged user, which the server runs as most of the time, when doing unprivileged operations. The option is available only in system configuration file. For example:

 
user-notprivileged "anubis.unprivileged"

Caution: Create a user account named ‘anubis.unprivileged’ in the ‘/etc/passwd’, if necessary. Add this user name also to the ‘/etc/anubis.allow’, if using GNU Anubis with PAM support.

Option: rule-priority value

This statement defines the order of execution of the system and user RULE sections (See section The Rule System, for detailed description). It is available only in system configuration file.

system

The system section is executed first, then the user section is executed.

user

The user section is executed first, next the system section is executed.

system-only

Only the system RULE section is executed.

user-only

Only the user RULE section is executed.

Option: control-priority value

Sets the order of processing the CONTROL sections. The option is available only in system configuration file. Its possible values are:

system

The system 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.

user

The user CONTROL section is processed first. Thus, the system-wide settings always override the user private settings.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 TRANSLATION Section

The ‘TRANSLATION’ section specifies how to translate remote or local user names, or host names or addresses, to local user names. The ‘TRANSLATION’ section is available only in the system configuration file. Syntax:

 
---BEGIN TRANSLATION---
translate  [user@]address into  username
...
---END---

address means host name or IP address. You can also specify ‘0.0.0.0’, and it means any address (‘INADDR_ANY’).

An example:

 
---BEGIN TRANSLATION---
translate jack@somewhere.net into john
---END---

The rule above will allow a remote user ‘jack’ at ‘somewhere.net’ to use the configuration file of the local user ‘john’. Or you can write: ‘translate somewhere.net into john’, and this means that all users at ‘somewhere.net’ are allowed to use the local john's configuration file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 GUILE Section

Command: guile-output file

Specifies the name of the file to bind to the Scheme standard error and output ports. This option has no effect if GNU Anubis is started with either of ‘--foreground’ or ‘--stdio’ command line options.

Command: guile-debug yes-or-no

When set to ‘yes’ enables Guile stack traces and debugging output.

Command: guile-load-path-append path

Appends the given path to the list of Guile load paths (see %load-path: (guile)Build Config section `Build Config' in The Guile Reference Manual).

Command: guile-load-program file

Reads the given Scheme program.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Sergey Poznyakoff on December, 20 2008 using texi2html 1.78.