4 Configuration

The behavior of GNU Anubis is controlled by two configuration files. The system configuration file, ‘/etc/anubisrc’, supplies system-wide settings 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 if 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.

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. The 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 the 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:

Table 4.1: Backslash escapes

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

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

Similarly, a 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 can 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 an 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, end each line with a backslash (‘\’), immediately before the newline, as in:

a very long statement\
  occupying several lines\
  of text

A ‘#’ in a line starts a comment. The ‘#’ 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:

# 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

Statements in 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.

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 RULE section as subroutines (see section Call Action).

The predefined section names are:

AUTH

Defines 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 mapping remote user names to local ones. It may be used only in the system-wide configuration file.

GUILE

Configures the Guile interpreter. This section is allowed in both configuration files.

RULE

Defines rules that for altering the message contents.

4.1 AUTH Section

The AUTH session controls various aspects of authentication mode.

Option: smtp-greeting-message text

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

Option: smtp-help-message help-text

Defines the message issued in response to SMTP HELP command. Help-text is a list of strings. Each string from the list will be displayed on a separate response line.

Option: sasl-password-db url

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

Option: sasl-allowed-mech mech-list

Defines the list of allowed authentication methods.

Option: sasl-service name

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

Option: sasl-hostname 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.

Option: sasl-realm name

Sets the SASL realm. By default, the local domain is used as SASL realm (see section local-domain).

4.2 CONTROL Section

The ‘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 ‘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 higher priority than those specified in system configuration file.

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

4.2.1 Basic Settings

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.

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

bind localhost:25

Option: remote-mta host[:port]

Specify a host name or IP address of the remote SMTP. GNU Anubis will forward mails to that server. 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). For example:

local-mta /usr/sbin/sendmail -bs

The ‘CONTROL’ section must contain either local-mta or remote-mta, but not both.

Option: mode mode-name

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

proxy

transparent

auth

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

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

Normally, when processing a multi-part message with external filter (see section Using an 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 read-entire-body yes in your control section.

Option: identd-keyfile filename

Sets the file name of the file that contains DES keys to use when decoding responses from the auth (ident) server. This file is used if auth server encrypts its responses. See section Auth Service, for details.

Option: incoming-mail-rule string

Declares the name of command section 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 the name of command section for outgoing mail. Default is ‘RULE’. This option is available only for system configuration file.

Option: smtp-command-rule string

Declares the name of command section for rewriting SMTP commands. Default is ‘SMTP’. This option is available only for system configuration file. See section Modifying SMTP Commands.

Option: log-tag string

Tag syslog messages with string. Default is ‘anubis’.

Option: log-facility string

Use syslog facility string for logging. Valid argument values are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, ‘local0’ through ‘local7’ (all names case-insensitive, optionally prefixed by ‘log_’), or a decimal facility number. Default is ‘mail’.

Option: local-domain 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 SASL realm, unless overridden by ‘sasl-realm’ statement (see section sasl-realm).

Option: use-pam bool

Enable the Pluggable Authentication Module interface. If set to yes, anubis will uses PAM for accounting and session management (service name ‘anubis’).

The default is yes if PAM support is compiled in.

4.2.2 Output Settings

Option: termlevel level

Defines logging verbosity level. Allowed values are:

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 is allowed only in the system configuration file.

Option: logfile file-name

This command sets the name of additional log file. GNU Anubis logs there messages about user’s SMTP session, as defined by the ‘loglevel’ statement (see below). For example:

logfile "anubis.log"

This will direct additional logging to the ‘~/anubis.log’ file in the user’s home directory.

Option: loglevel level

This option defines verbosity level for the additional log file. It may be used only in user configuration file. Allowed values for level are:

none

fails

Log only failure messages.

all

Log all relevant messages.

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 configuration files.

When this option is used in the system-wide configuration file, only boolean argument is allowed. Using ‘tracefile yes’ enables logging of 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 each child process to hang for the given number of seconds. Before hanging, the process issues the following diagnostic message:

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. You may wish to add the following statement to your ‘.gdbinit’ file:

set variable _anubis_hang=0

4.2.3 SOCKS Proxy

Option: socks-proxy host[:port]

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

Option: socks-v4 yes-or-no

Use SOCKS protocol version 4. By default it is turned off, and version 5 of the SOCKS protocol is used.

Option: socks-auth username:password

Sets user name and password for the SOCKS proxy server.

4.2.4 ESMTP Authentication Settings

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

You can also use these statements in a ‘SMTP’ section. See section Modifying SMTP Commands, for a detailed description of this feature.

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 the following algorithm: MTA presents a 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 reports the following supported mechanisms:

PLAIN LOGIN CRAM-MD5 ANONYMOUS

and in your configuration file you have:

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

Then, Anubis will select ‘CRAM-MD5’.

Option: esmtp-require-encryption mech-list

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-delayed yes-or-no

By default, ESMTP authentication is attempted as early as possible, normally while handling the client ‘EHLO’ command.

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

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 ESTMP AUTH password.

Option: esmtp-auth username:password

This is a shortcut to set 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.

The following option is useful with the ‘ANONYMOUS’ authentication mechanism:

Option: esmtp-anonymous-token token

Sets the token to be used with the ‘ANONYMOUS’ authentication mechanism

4.2.5 Encryption Settings

Option: ssl yes-or-no

Enable or disable the TLS/SSL encryption between the MUA and the MTA. The default is ‘no’, but using the TLS/SSL encryption is recommended. You should also set your private key and 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

Enable the ONEWAY encryption. Set ssl-oneway yes, if you want to use the TLS/SSL, but your MUA doesn’t support ESMTP TLS/SSL. Using this option does not require setting the ‘ssl-key’ and ‘ssl-cert’ options.

Option: ssl-priorities list

Sets cipher suite preferences to use. The 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 Priority Strings in GnuTLS Manual, for a detailed discussion.

The default priority list is ‘NORMAL’.

Option: ssl-cert file-name

Specify the certificate for the TLS/SSL encryption.

Default for file-name is ‘anubis.pem’.

Option: ssl-key file-name

Set the private key for the TLS/SSL encryption.

The default file-name is ‘anubis.pem’.

Option: ssl-cafile file-name

Specify CA certificate file (supported only by GnuTLS).

4.2.6 Security Settings

The following options control various security settings.

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

If this option is set to ‘yes’, anubis drops sessions which failed verification by the IDENT service.

This option is in effect only in ‘transparent’ mode.

Default is ‘no’.

Option: user-notprivileged username

Defines the unprivileged user, i.e. the user with whose privileges anubis runs most of the time. This option is available only in the system configuration file. For example:

user-notprivileged "anubis"

Caution: This user must exist in the system user database (‘/etc/passwd’).

Option: rule-priority value

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

Allowed values are:

system

First execute the system section, then the user one.

user

First execute the user section, then the system one.

system-only

Execute only the system RULE section.

user-only

Execute only the user RULE section.

Option: control-priority value

Sets the order of processing CONTROL sections. This option is available only in system configuration file.

Allowed 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 users’ private settings.

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. The syntax is:

---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’).

For example:

BEGIN TRANSLATION
translate jack@example.net into john
END

This rule will allows the remote user ‘jack’ at ‘example.net’ to use the configuration file of the local user ‘john’.

In the contrast, this statement:

translate example.net into john

means that all users at ‘example.net’ are allowed to use the local john’s configuration file.

4.4 GUILE Section

Command: guile-output 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 ‘err’ priority, and the standard output port writes to the ‘warning’ priority.

This option has no effect if GNU Anubis is started with either ‘--foreground’ or ‘--stdio’ command line option.

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 in The Guile Reference Manual).

Command: guile-load-program file

Reads the given Scheme program.

This document was generated on January 6, 2024 using texi2html 5.0.