## 7 Configuring `mailfromd` ¶

Upon startup, `mailfromd` checks if the file `/etc/mailfromd.conf` exists.29 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 Privilege Configuration).

### 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 Preprocessor Configuration.

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 MFL 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 `CNAME`s. 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.1 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:

Timeout | Soft | Hard
--- | --- | ---
connection | 10s | 5m
initial-response | 30s | 5m
helo | I/O | 5m
mail | I/O | 10m
rcpt | I/O | 5m
rset | I/O | 5m
quit | I/O | 2m

Table 7.1: Default SMTP timeouts

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 Default Values): 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 Default Values) 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 Default Values).

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 Dynamically Loaded Modules.

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 Dynamically Loaded Modules, for details.

### 7.13 Standard Mailutils Statements ¶

The following standard Mailutils statements are understood:

Statement | Reference
--- | ---
auth | See Mailutils Configuration File in GNU Mailutils Manual.
debug | See Mailutils Configuration File in GNU Mailutils Manual.
include | See Mailutils Configuration File in GNU Mailutils Manual.
logging | See Mailutils Configuration File in GNU Mailutils Manual.
mailer | See Mailutils Configuration File in GNU Mailutils Manual.
locking | See Mailutils Configuration File in GNU Mailutils Manual.

#### Footnotes

##### (29)

The exact location is determined at compile time: the `/etc` directory is the system configuration directory set when building `mailfromd` (see Building the Package).