Setting up a Milter (optional)

To describe where filters are located, you need to add reference to the filters in the sendmail configuration file (sendmail.cf). Filters declaration in the sendmail configuration file are made in the following form:

X name field =value |*

Filters are specified with a key letter (X for external), and name is the name of the filter (used internally only). The field=value pairs, or equates, define attributes of the filter.

The fields and their values are:

Socket

The socket specification is in one of the following forms:

S = inet: port @ host | [IP address]
S = inet6: port @ host | [IP address]
S = local: path

The first two describe an IPv4 (inet) and IPv6 (inet6) socket listening on a certain port at a given host or IP address. The final form describes a named socket on the file system at the given path.

Flags

Special flags for a filter are:

F=R           Reject connection if filter unavailable
F=T             Temporary fail connection if filter unavailable

Timeouts

To override the default timeouts used by sendmail when talking to the filters, use T = timeout, where timeout includes four fields as follows:

C        Timeout for connecting to a filter (if 0, use system timeout)
S        Timeout for sending information from the MTA to a filter
R        Timeout for reading reply from the filter
E        Overall timeout between sending end-of-message to filter and
         waiting for the final acknowledgment

The separator between each timeout field is a semicolon (;). The default timeout values, if not set in the configuration file, are as follows, where s is seconds and m is minutes:

T=C:5m;S:10s;R:10s;E:5m

A comma (,) separates equates, as shown in the following example filters:

Xfilter1, S=local:/var/run/f1.sock, F=R
Xfilter2, S=inet6:999@localhost, F=T, T=C:10m;S:1s;R:1s;E:5m
Xfilter3, S=inet:3333@localhost

Assuming the filters are stored in /var/spool/milter, the following commands would start the above three mail filters. Note that S= is replaced by -p, and the flags are dropped.

/var/spool/milter/filter1 -p local:/var/run/f1.sock &
/var/spool/milter/filter2 -p inet6:999@localhost &
/var/spool/milter/filter3 -p inet:3333@localhost &

Which filters are invoked, and their sequencing, is handled by the InputMailFilters option as follows, where fnamex are the names of the filters:

O InputMailFilters=fname1, fname2, fname3

If InputMailFilters is not defined, no filters are used. However, there is a special case. Because sendmail can run multiple daemons, you can assign different filters to different daemons. For example:

O DaemonPortOptions=Port=6666,Name=mmta,I=filter
.
.
.
Xfilter, S=inet:3333@localhost

DaemonPortOptions is used to define multiple clients and daemons, and the I field is used to assign a specific filter to the daemon. If a daemon is assigned a specific filter, it connects to that filter only. In the previous example, the daemon using port 6666 connects to the filter defined by [Xfilter, S=inet:3333@localhost]. If a daemon is not assigned a specific filter, it connects to filters defined by [InputMailFilters].

There are two suboptions for Milter:

LogLevel: Log level for input mail filter actions, the default is LogLevel
Macros: Specifies list of macros to transmit to filters

The macros option has the following suboptions, which specify the list of macros to transmit to milters after a certain event has occurred. By default, the lists of macros are empty.

Option: After this event
Connect: Session connection start
Helo: HELO command
Envfrom: MAIL FROM command
Envrcpt: RCPT TO command

Examples:

O Milter.LogLevel=12
O Milter.macros.connect=j, _, {daemon_name}

These filters can easily be configured in your mc file using the following commands:

MAIL_FILTER(`name', `equates')
INPUT_MAIL_FILTER(`name', `equates')

The first command, MAIL_FILTER(), defines a filter with the given name and equates. For example:

MAIL_FILTER(`archive', `S=local:/var/run/archivesock, F=R')

This creates the following equivalent sendmail.cf entry:

Xarchive, S=local:/var/run/archivesock, F=R

The INPUT_MAIL_FILTER() command performs the same actions as MAIL_FILTER, but also populates the m4 variable `confINPUT_MAIL_FILTERS' with the name of the filter such that the filter will actually be called by sendmail. For example:

INPUT_MAIL_FILTER(`archive', `S=local:/var/run/archivesock, F=R')
INPUT_MAIL_FILTER(`spamcheck', `S=inet:2525@localhost, F=T')

The two commands above are equivalent to the following three commands:

MAIL_FILTER(`archive', `S=local:/var/run/archivesock, F=R')
MAIL_FILTER(`spamcheck', `S=inet:2525@localhost, F=T')
define(`confINPUT_MAIL_FILTERS', `archive, spamcheck')

In general, INPUT_MAIL_FILTER() should be used, unless you need to define more filters than you want to use for `confINPUT_MAIL_FILTERS'. Note that setting `confINPUT_MAIL_FILTERS' after any INPUT_MAIL_FILTER() commands clears the list created by the prior INPUT_MAIL_FILTER() commands.

The following table shows M4 variables:

Table 1. M4 variables
M4 variable	Configuration variable	Description
confINPUT_MAIL_FILTERS	InputMailFilters	A list of filters, separated by commas, that determines which filters are contacted for incoming SMTP messages, as well as the invocation sequence. If none are set, no filters are contacted.
confMILTER_LOG_LEVEL	Milter.LogLevel	Log level for input mail filter actions. The default is LogLevel.
confMILTER_MACROS_CONNECT	Milter.macros.connect	Macros to transmit to milters when a session connection starts. The default is [j, _, {daemon_name}, {if_name}, {if_addr}].
confMILTER_MACROS_HELO	Milter.macros.helo	Macros to transmit to milters after HELO command. The default is [{tls_version}, {cipher}, {cipher_bits}, {cert_subject}, {cert_issuer}].
confMILTER_MACROS_ENVFROM	Milter.macros.envfrom	Macros to transmit to milters MAIL FROM command. The default is [i, {auth_type}, {auth_authen}, {auth_ssf}, {auth_author}, {mail_mailer}, {mail_host}, {mail_addr}].
confMILTER_MACROS_ENVRCPT	Milter.macros.envrcpt	Macros to transmit to milters after RCPT TO command. The default is [{rcpt_mailer}, {rcpt_host}, {rcpt_addr}].

For instructions on how to compile and link a mail filter program, see z/OS Communications Server: IP Programmer's Guide and Reference.