7 Configuring mailfromd

Upon startup, mailfromd checks if the file /etc/mailfromd.conf exists.²⁹ If it does, the program attempts to retrieve its configuration settings from that file.

The mailfromd.conf file must be written in the GNU mailutils configuration format, as described in Configuration File Syntax in GNU Mailutils Manual. This format can be summarized as follows:

Comments

Inline comments begin with ‘//’ or ‘#’ and end at the end of the line. Multiline comments are delimited by ‘/*’ and ‘*/’. Multiline comments cannot be nested, but can contain inline comment markers.

Empty lines and whitespace

Empty lines are ignored. Whitespace characters (i.e. horizontal, vertical space, and newline) are ignored, except as they serve to separate tokens.

Statements

A statement consists of a keyword and a value, separated by whitespace. Statements terminate with a semicolon. E.g.

pidfile /var/run/mailfromd.pid;

Block statements

A block statement consists of a keyword and a list of statements enclosed in ‘{’ and ‘}’ characters. Optional label can appear between the keyword and opening curly brace. E.g.:

logging {
  syslog on;
  facility mail;
}

Block statement is not required to terminate with a semicolon, although it is allowed to.

File Inclusion

The include statement causes inclusion of the file listed as its value:

include /usr/share/mailfromd/config.inc;

The mailfromd.conf file is used by all programs that form the ‘mailfromd’ package, i.e. mailfromd, calloutd, mfdbtool, and pmult. Since the sets of statements understood by each of them differ, special syntactic means are provided to separate program-specific configurations from each other.

First of all, if the argument to include is a directory, then the program will search that directory for a file with the same name as the base name of the program itself. If found, this file will be loaded after finishing parsing the mailfromd.conf file. Otherwise, this statement is ignored.

Secondly, the special block statement program tag is processed only if tag matches the base name of the program being run. Again, it is processed after the main mailfromd.conf file.

Thus, if you need to provide configuration for the calloutd component, there are two ways of doing so. First, you can place it to a file named calloutd placed in a separate directory (say, /etc/mailfromd.d), and use the name of that directory in a include statement in the main configuration file:

include /etc/mailfromd.d;

Secondly, you can use the program statement as follows:

program calloutd {
  ...
}

7.1 Special Configuration Data Types

In addition to the usual data types (see Statements in GNU Mailutils Manual), mailfromd configuration introduces the following two special ones:

time interval specification

The time interval specification is a string that defines an interval, much the same way we do this in English: it consists of one or more pairs ‘number’-‘time unit’. For example, the following are valid interval specifications:

1 hour
2 hours 35 seconds
1 year 7 months 2 weeks 2 days 11 hours 12 seconds

The pairs can occur in any order, however unusual it may sound to a human ear, e.g. ‘2 days 1 year’. If the ‘time unit’ is omitted, seconds are supposed.

Connection URL

unix://file

unix:file

local://file

local:file

A named pipe (socket).

inet://address:port

inet:port@address

An IPv4 connection to host address at port port. Port must be specified either as a decimal number or as a string representing the port name in /etc/services.

inet6:port@address

An IPv6 connection to host address at port port. This port type is not yet supported.

7.2 Base Mailfromd Configuration

Mailfromd Conf: script-file file

Read filter script from file. By default it is sysconfdir/mailfromd.mfl.

Mailfromd Conf: setvar name value

Initialize MFL variable name to value.

Mailfromd Conf: include-path path

Add directories to the list of directories to be searched for include files. See include search path.

Argument is a list of directory names separated by colons. These names are added to the search path before the default search path directories, but after any directories added by the previous include-path statements, if any.

See --include-path

Mailfromd Conf: module-path path

Add directories to the module search path See module search path.

Argument is a list of directory names separated by colons. These names are added to the search path before the default search path directories, but after any directories added by the previous module-path statements, if any.

See --module-path

Mailfromd Conf: state-directory dir

Set program state directory. See statedir.

Mailfromd Conf: relayed-domain-file file

Append domain names from the named file to the list of relayed domains. This list can be inspected from MFL script using the ‘relayed’ function (see relayed).

The file argument is either a single file name or a list of file names, e.g.:

relayed-domain-file /etc/mail/sendmail.cw;
relayed-domain-file (/etc/mail/sendmail.cw, /etc/mail/relay-domains);

Mailfromd Conf: source-ip ipaddr

Set source IP address for outgoing TCP connections.

Mailfromd Conf: pidfile file

Set the name of the file to store PID value in. The file must be writable for the user or group mailfromd runs as (see conf-priv).

7.3 Preprocessor Configuration

MFL preprocessor is configured using the preprocessor statement (default values shown):

preprocessor {
  # Enable preprocessor
  enable yes;
  # Preprocessor command line stub.
  command "m4 -s";
  # Pass current include path to the preprocessor via -I options.
  pass-includes false;
  # Pass to the preprocessor the feature definitions via -D options
  # as well as any -D/-U options from the command line
  pass-defines true;
  # Name of the preprocessor setup file.  Unless absolute, it is
  # looked up in the include path.
  setup-file "pp-setup";
}

Its substatements are:

preprocessor: enable bool

Enable or disable preprocessor. If disabled in configuration file, preprocessor can be forcefully enabled in the command line by using the --preprocessor option.

preprocessor: command string

The stub for the preprocessor command line. Before use, it will be eventually augmented by -I and -D options, depending on the pass-includes and pass-defines settings in this section. This is described in detail in Configuring Preprocessor.

preprocessor: pass-includes bool

If true the directories from include search path (see include search path will be passed to the preprocessor via the -I options.

preprocessor: pass-defines bool

If true, the -D options defining optional features will be passed to the preprocessor (e.g. -DWITH_DKIM), as well as any -D and -U options from the mailfromd command line.

preprocessor: setup-file string

Name of the preprocessor setup file (see Preprocessor). Unless string begins with a slash, the file with this name is looked up in the current include search path (see include search path). If found, its absolute name is passed to the preprocessor as its first argument.

If string begins with a slash, it is passed to the preprocessor as is.

7.4 DNS Resolver Configuration

DNS resolver settings are configured using the resolver compound statement:

resolver {
  config filename;
  max-cname-chain num;
}

resolver: config filename

Name of the resolver configuration file to use, instead of the default /etc/resolv.conf.

resolver: max-cname-chain num

Maximum allowed length of a DNS CNAME chain that will be followed. A CNAME chain is a sequence of CNAME records pointing to another CNAMEs. Although CNAME chains are not considered a good practice, many sites still use them. By default the mailfromd resolver allows at most one CNAME record pointing to a CNAME (this corresponds to max-cname-chain 2). If you need to follow longer chains, raise this value. Note however, that using values greater than 5 is not a good idea, anyway.

7.5 Server Configuration

A single mailfromd daemon can run several servers. These are configured in the following statement:

server type {
  id name;
  listen url;
  backlog num;
  max-instances num;
  single-process bool;
  reuseaddr bool;
  option list;
  default bool;
  callout url;
  acl { … }
}

Mailfromd Conf: server type

Define a server. The type is either ‘milter’ or ‘callout’. See SMTP Timeouts, for a description of various types of servers.

The substatements in the server block provide parameters for configuring this server.

server: id name

Assign an identifier to this server. This identifier is used as a suffix to syslog tag (see syslog tag) in messages related to this server. For example, if a server block had the following statement in it:

id main;

then all messages related to this server will be marked with tag ‘mailfromd#main’.

The part before the ‘#’ is set using the tag statement in logging block (see Mailutils Configuration File in GNU Mailutils Manual).

This identifier can be inspected from the MFL code using the milter_server_id variable (see milter_server_id).

server: listen url

Listen for connections on the given URL. See milter port specification, for a description of allowed url formats.

Example:

listen inet://10.10.10.1:3331;

The MFL code can access its address using the milter_server_address and milter_server_family variables.

server: backlog num

Configures the size of the queue of pending connections. Default value is 8.

server: max-instances number

Sets the maximum number of instances allowed for this server.

server: single-process bool

When set to ‘yes’, this server will run in single-process mode, i.e. it will not fork sub-processes to serve requests. This option is meant exclusively to assist in debugging mailfromd. Don’t use it for anything else but for debugging!

server: reuseaddr bool

When set to ‘yes’, mailfromd will attempt to reuse existing socket addresses. This is the default behavior.

If the server type is ‘callout’, the following statement is also allowed:

server: option list

Configures server options. As of version 9.0 only one option is defined:

default

Mark this server as the default one. This means it will be used by every milter server that doesn’t define the callout-url statement.

server: default bool

When set to ‘yes’, this server is marked as a default callout server for all milter servers declared in the configuration. This is equivalent to option default.

if the server type is ‘milter’, you can use the following statement to query a remote callout server:

server: callout url

Use a callout server at url (see milter port specification).

You can also set a global callout server, which will be used by all milter servers that do not set the callout statement:

Mailfromd Conf: callout-url url

Set global callout server. See milter port specification, for allowed url formats.

7.6 Milter Connection Configuration

Mailfromd Conf: milter-timeout time

Sets the timeout value for connection between the filter and the MTA. Default value is 7210 seconds. You normally do not need to change this value.

Mailfromd Conf: acl

This block statement configures access control list for incoming Milter connections. See Mailutils Configuration File in GNU Mailutils Manual, for a description of its syntax. E.g.:

acl {
  allow from 10.10.10.0/24;
  deny from any;
}

7.7 Logging and Debugging configuration

Mailfromd Conf: logger mech

Set default logger mechanism. Allowed values for mech are:

stderr

Log everything to the standard error.

syslog

Log to syslog.

syslog:async

Log to syslog using the asynchronous syslog implementation.

See Logging and Debugging, for a detailed discussion. See also Using non-blocking syslog, for information on how to set default syslog implementation at compile time.

Mailfromd Conf: debug spec

Set mailfromd debug verbosity level. The spec must be a valid debugging level specification (see debugging level specification).

Mailfromd Conf: stack-trace bool

Enables stack trace dumps on runtime errors. This feature is useful for locating the source of an error, especially in complex scripts. See tracing runtime errors, for a detailed description.

Mailfromd Conf: trace-actions bool

Enable action tracing. If bool is ‘true’, mailfromd will log all executed actions. See Logging and Debugging, for a detailed description of action tracing.

Mailfromd Conf: trace-program modlist

Enable program instruction tracing for modules in modlist, a comma-separated list of source code modules, e.g.:

trace-program (bi_io,bi_db);

This statement enables tracing for functions from modules bi_io.c and bi_db.c (notice, that you need not give file suffixes).

This tracing is useful for debugging mailfromd, but is not advised to use otherwise, since it is very time-costly.

Mailfromd Conf: transcript bool

Enable transcripts of call-out SMTP sessions. See SMTP transcript, for a detailed description of SMTP transcripts.

7.8 Timeout Configuration

The SMTP timeouts used in callout sessions are configured via smtp-timeout statement:

Syntax

smtp-timeout type {
  connection interval;
  initial-response interval;
  helo interval;
  mail interval;
  rcpt interval;
  rset interval;
  quit interval;
}

Mailfromd Conf: smtp-timeout type

Declare SMTP timeouts of the given type, which may be ‘soft’ or ‘hard’.

Callout SMTP sessions initiated by polling functions, are controlled by two sets of timeouts: ‘soft’ and ‘hard’. Soft timeouts are used by the mailfromd milter servers. Hard timeouts are used by callout servers (see callout server). When a soft timeout is exceeded, the calling procedure is delivered an ‘e_temp_failure’ exception and the session is scheduled for processing by a callout server. The latter re-runs the session using hard timeouts. If a hard timeout is exceeded, the address is marked as ‘not_found’ and is stored in the cache database with that status.

Normally, soft timeouts are set to shorter values, suitable for use in MFL scripts without causing excessive delays. Hard timeouts are set to large values, as requested by RFC 2822 and guarantee obtaining a definite answer (see below for the default values).

Statements

The time argument for all smtp-timeout sub-statements is expressed in time interval units, as described in time interval specification.

smtp-timeout: connection time

Sets initial connection timeout for callout tests. If the connection is not established within this time, the corresponding callout function returns temporary failure.

smtp-timeout: initial-response time

Sets the time to wait for the initial SMTP response.

smtp-timeout: helo time

Timeout for a response to ‘HELO’ (or ‘EHLO’) command.

smtp-timeout: mail time

Timeout for a response to ‘MAIL’ command.

smtp-timeout: rcpt time

Timeout for a response to ‘RCPT’ command.

smtp-timeout: rset time

Timeout for a response to ‘RSET’ command.

smtp-timeout: quit time

Timeout for a response to ‘QUIT’ command.

Default Values

The default timeout settings are:

Mailfromd Conf: io-timeout time

Sets a general SMTP I/O operation timeout. This timeout is used as the default for entries marked with ‘I/O’ in the above table. The default is 3 seconds.

7.9 Call-out Configuration

Mailfromd Conf: ehlo-domain string

Sets default domain used in ‘EHLO’ (or ‘HELO’) SMTP command when probing the remote host. This value can be overridden by ‘from’ parameter to poll command (see poll).

This statement assigns the value string to the ‘ehlo_domain’ variable (see ehlo_domain), and is therefore equivalent to

setvar ehlo_domain string;

Mailfromd Conf: mail-from-address string

Sets default email addresses used in ‘MAIL FROM:’ SMTP command when probing the remote host. This value can be overridden by ‘as’ parameter to poll command (see poll).

This statement assigns the value string to the ‘mailfrom_address’ variable (see mailfrom_address), and is therefore equivalent to

setvar mailfrom_address string;

Mailfromd Conf: enable-vrfy bool

Enables the use of SMTP VRFY statement prior to normal callout sequence. If VRFY is supported by the remote server, mailfromd relies on its reply and does not perform normal callout.

The use of this statement is not recommended, because many existing VRFY implementations always return affirmative result, no matter is the requested email handled by the server or not.

The default is enable-vrfy no, i.e. VRFY is disabled.

Mailfromd Conf: smtp-starttls string

Configures whether to issue the STARTTLS command if the mail server offers such capability. Allowed values are:

smtp-starttls value: never

Never use STARTTLS.

smtp-starttls value: always

Always use STARTTLS if supported by the server.

smtp-starttls value: ondemand

Use STARTTLS only if MAIL FROM: command failed with the code 530 (Authorization required).

Default is ‘ondemand’.

Notice, that the smtp-starttls feature depends on whether GnuTLS support is available in libmailutils. You can check whether it is available by inspecting the output of mailfromd --show-defaults (see Examining Defaults): if so, the ‘optional features’ line will contain the word ‘STARTTLS’.

Mailfromd Conf: tls { ... }

Configures TLS settings for the callout. This is a compound statement. The two most important statements in this compound are:

Mailfromd TLS: ssl-priorities string

Configures the TLS session’s handshake algorithms and options in a compact, easy-to-use format. See Priority strings in GnuTLS, for a detailed description of the priority string format.

Default value is ‘NORMAL:%COMPAT’. You may need to adjust it in order to work with older or misconfigured servers, e.g.:

tls {
  ssl-priorities "LEGACY:%COMPAT";
}

Mailfromd TLS: handshake-timeout n

Sets the timeout for TLS handshake to n seconds.

The remaining three statements are not of much importance for callout. They are described here for completeness sake:

Mailfromd TLS: ssl-ca-file file

Specifies the pathname of the certificate authority file.

Mailfromd TLS: ssl-certificate-file file

Specifies the pathname of the certificate file.

Mailfromd TLS: ssl-key-file file

Specifies the pathname of the certificate key file.

7.10 Privilege Configuration

Mailfromd Conf: user name

Switch to this user’s privileges after startup. See Starting and Stopping, for a discussion of the privileges mailfromd runs under and the options that affect them. See also group below.

Mailfromd Conf: group name

Retain the supplementary group name when switching to user privileges. By default mailfromd clears the list of supplementary groups when switching to user privileges, but this statement allows to retain the given group. It can be specified multiple times to retain several groups. This option may be necessary to maintain proper access rights for various files. See Starting and Stopping.

7.11 Database Configuration

Syntax

database dbname {
  file name;
  enable bool;
  expire-interval interval;
  positive-expire-interval interval;
  negative-expire-interval interval;
}

Mailfromd Conf: database dbname

The database statement controls run-time parameters of the DBM database identified by dbname. Allowed values for the latter are:

cache

Callout cache database.

rate

Sending rate database. See Sending Rate.

tbf

Token-bucket filter database. See TBF.

greylist

Greylisting database. See Greylisting.

Statements

database: file name

Set the database file name. The file name can be prefixed with the DBM scheme, which indicates the desired DBM implementation to use. The scheme consists of DBM type name followed by a colon and two slashes. To obtain the list of available DBM types, run mailfromd --show-defaults (see Examining Defaults) and examine the ‘supported database types:’ line, e.g.:

$ mailfromd --show-defaults | grep '^supported database types:'
supported database types:gdbm, bdb

If no DBM scheme is supplied, the default DBM implementation will be used. The default implementation is set up on compile time and can be inspected using the following command:

mailfromd --show-defaults | grep '^default database type:'

The part that follows DBM scheme can be either absolute or relative file name. Absolute file name (begining with ‘/’) is used verbatim. Relative file name (i.e. the name that begins with any character except ‘/’) is modified by prepending it with the mailfromd local state directory (see statedir).

To illustrate the above, suppose that the local state directory is /var/mailfromd and default DBM implementation is gdbm. Then:

Value of file	Resulting filename	DBM type
tbf.db	/var/mailfromd/tbf.db	GDBM
bdb://tbf.db	/var/mailfromd/tbf.db	Berkeley DB
/run/tbf.db	/run/tbf.db	GDBM
bdb:///run/tbf.db	/run/tbf.db	Berkeley DB

database: enable bool

Enable or disable this database.

database: expire-interval time

Set the expiration interval for this database dbname. See time interval specification, for a description of time format.

database: positive-expire-interval time

This statement is valid only for ‘cache’ database. It sets the expiration interval for positive (‘success’) cache entries.

database: negative-expire-interval time

This statement is valid only for ‘cache’ database, where it sets expiration interval for negative (‘not_found’) cache entries.

Additional Statements

Mailfromd Conf: database-type type

Set default database type. type is one of the database types supported by mailutils (i.e., for Mailutils 3.0: ‘gdbm’, ‘ndbm’, ‘bdb’, ‘kc’, and ‘tc’). Run

mailfromd --show-defaults | grep 'supported databases:'

to get a list of type names supported by your build of mailfromd (see Examining Defaults).

Mailfromd Conf: database-mode mode

Defines file mode for newly created database files. mode must be a valid file mode in octal.

7.12 Runtime Constants Configuration

Mailfromd Conf: runtime { statements }

The statements in the runtime section configure various values used by MFL builtin functions.

runtime: max-streams number

Sets the maximum number of stream descriptors that can be opened simultaneously. Default is 1024. See I/O functions.

runtime: max-open-mailboxes number

Sets the maximum number of available mailbox descriptors. This value is used by MFL mailbox functions (see Mailbox functions).

runtime: max-open-messages number

Sets the maximum number of messages that can be opened simultaneously using the mailbox_get_message function. See Message functions, for details.

runtime: max-mfmods number

Maximum number of dynamically loaded modules (mfmods) that can be used simultaneously. See mfmod.

runtime: mfmod-path string

Search path for dynamically loaded modules – a colon-delimited list of directories where to look for libraries loaded using the dlopen function (see dlopen). Default mfmod-path value is prefix/mailfromd/lib, where prefix is the installation prefix directory. See mfmod, for details.

7.13 Standard Mailutils Statements

The following standard Mailutils statements are understood: