Mailfromd Manual (split by chapter):   Section:   Chapter:FastBack: Using MFL Mode   Up: Top   FastForward: Invocation   Contents: Table of ContentsIndex: Concept Index

7 Configuring mailfromd

Upon startup, mailfromd checks if the file /etc/mailfromd.conf exists.25 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 read from sysconfdir/mailfromd.mf.

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 header files. See include search path.

Argument is a list of directory names separated by colons.

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

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;
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 8.7 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.4 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.5 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.6 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:

TimeoutSoftHard
connection10s5m
initial-response30s5m
heloI/O5m
mailI/O10m
rcptI/O5m
rsetI/O5m
quitI/O2m

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

7.8 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.9 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 a DBM database identified by dbname. Allowed values for the latter are: ‘cache’, ‘rate’ and ‘greylist’ for main cache, DNS lookup, sending rate and greylisting databases, correspondingly.

Statements

database: file name

Set the database file name.

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.

Mailfromd Conf: database-mode mode

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

Mailfromd Conf: lock-retry-count number

Set maximum number of attempts to acquire the lock. The time between each two successive attempts is given by lock-retry-timeout statement (see below). After the number of failed attempts, mailfromd gives up.

Mailfromd Conf: lock-retry-timeout time

Set the time span between the two locking attempts. Any valid time interval specification (see time interval specification) is allowed as argument.

7.10 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.

7.11 Standard Mailutils Statements

The following standard Mailutils statements are understood:

StatementReference
authSee Mailutils Configuration File in GNU Mailutils Manual.
debugSee Mailutils Configuration File in GNU Mailutils Manual.
includeSee Mailutils Configuration File in GNU Mailutils Manual.
loggingSee Mailutils Configuration File in GNU Mailutils Manual.
mailerSee Mailutils Configuration File in GNU Mailutils Manual.
lockingSee Mailutils Configuration File in GNU Mailutils Manual.

Footnotes

(25)

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

Mailfromd Manual (split by chapter):   Section:   Chapter:FastBack: Mailfromd Configuration   Up: Mailfromd Configuration   FastForward: Invocation   Contents: Table of ContentsIndex: Concept Index