GNU Anubis Manual: 4.2 CONTROL Section

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.

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