General-Purpose Mail Filter

13 Pmilter multiplexer program.

Pmult is a Pmilter–Milter multiplexer, i.e. a
program that acts as a mediator between the Pmilter server
and one or several Milter clients. Usually, the former is
an instance of smtps from MeTA1, and the latter are running
mailfromd instances. Pmult receives Pmilter
commands from the server, translates them into equivalent Milter
commands and passes the translated requests to a preconfigured set of
Milter filters. When the filters reply, the reverse operation is performed:
Milter responses are translated into their Pmilter equivalents and
are sent back to the server.

Due to the specifics nature of the threaded MeTA1 libraries,
pmult does not detach from the controlling terminal
(i.e. does not become a daemon). To run it as a background process,
we recommend to use pies daemon. ‘Pies’ is a powerful
utility that allows you to launch several foreground-designed programs
in the background and control their execution. See Pies in Pies Manual, for a detailed description of the program.
For a practical advice on how to use it with pmult, see
Using Pies to Run Pmult in Pies Manual. For
a description on how to start both pmult and MeTA1 from
the same pies configuration file, see Using
Pies to Run Pmult and MeTA1 in Pies Manual.

13.1 Pmult Configuration

Pmult reads its configuration from the main configuration
file /etc/mailfromd.conf. Unless it is the only component of
the ‘Mailfromd’ package that is being run, its configuration
should be explicitly marked as such by using either program or
include statement, as described in Mailfromd Configuration.

Since pmult runs as a foreground program, it does not write
its PID number to a file by default. If this behavior is required, it
can be enabled using the following statement:

Pmult Conf: pidfilefile

Store PID of the pmult process in file.

The following three limits require MeTA1 version ‘PreAlpha30.0’
or later.

Pmult Conf: max-threads-softn

“Soft” limit on the number of ‘pmilter’ threads. Default is 2.

Pmult Conf: max-threads-hardn

“Hard” limit on the number of ‘pmilter’ threads. This is
roughly equivalent to the number of emails pmult is able
to handle simultaneously. The default value is 6. Raise this limit
if you experience long delays when connecting to the SMTP port.

Pmult Conf: max-pmilter-fdn

Maximum number of file descriptors ‘pmilter’ library is allowed
to open simultaneously. Default is 10.

13.1.2 Translating MeTA1 macros.

MeTA1’s notion of macros differs considerably from that of Sendmail.
Macros in MeTA1 are identified by integer numbers and only a limited
number of macros can be provided for each Pmilter stage.
Pmilter stages mostly correspond to Milter states (see handler names), except that there are no distinct header and body stages,
instead these two are combined into a single ‘data’ stage. This
comes unnoticed to mailfromd scripts, because pmult takes
care to invoke right Milter handlers within the single ‘data’
Pmilter state. Therefore in the discussion that follows we will refer
to Mailfromd handlers, rather than to Pmilter stages.

The most important standard Milter macros are always provided by
pmult itself. These are:

client_addr

The IP address of the SMTP client. As of version 8.7,
only IPv4 addresses are supported. Defined in all handlers.

The number of bad recipients for a single message. Defined in
envfrom and envrcpt handlers.

ntries

The number of delivery attempts. As of version 8.7 it is
always ‘1’. Defined in envfrom and subsequent handlers.

nrcpts

The number of validated recipients for a single message. Defined in
envfrom and envrcpt handlers.

r

Protocol used to receive the message. The value of this macro is
always ‘SMTP’. Defined in all handlers.

rcpt_host

The host from the resolved triple of the address given for the SMTP
RCPT command. Defined in envrcpt handler.

rcpt_addr

The address part of the resolved triple of the address given for the
SMTP RCPT command. Defined in envrcpt handler.

s

Sender’s helo domain (parameter to EHLO or HELO
command).

Two additional macros are provided for all handlers that allow to
identify whether the message is processed via pmult:

multiplexer

Canonical name of the multiplexer program, i.e. ‘pmult’.

mult_version

Version of pmult.

These macros can be used in mailfromd filters to provide alternative
processing for messages coming from a MeTA1 server.

Macros defined in MeTA1 can be made available in Mailfromd handlers
using the define-macros statement.

Pmult Conf: define-macroshandlermacros

Define a set of Sendmail macros for the given Mailfromd handler.
Allowed values for handler are: ‘connect’, ‘helo’,
‘mail’ (or ‘envfrom’), ‘rcpt’ (or ‘envrcpt’),
‘data’ (or ‘header’ or ‘body’), ‘dot’
(‘eom’). A list of these values is also accepted, in which case
macros are defined for each handler from the list.

The second argument specifies a list of names of the macros that
should be defined in this handler. Allowed macro names are:

hostname

Hostname of SMTP server.

client_resolve

Result of client lookup.

tls_version

TLS/SSL version used.

tls_cipher_suite

TLS cipher suite used.

tls_cipher_bits

Effective key length of the symmetric encryption algorithm.

tls_cert_subject

The DN (distinguished name) of the presented certificate.

tls_cert_issuer

The DN (distinguished name) of the CA (certificate authority) that
signed the presented certificate (the cert issuer).

tls_alg_bits

Maximum key length of the symmetric encryption algorithm. This may be
less than the effective key length for export controlled algorithms.

tls_vrfy

The result of the verification of the presented cert.

tls_cn_subject

cn_subject

The CN (common name) of the presented certificate.

tls_cn_issuer

cn_issuer

The CN (common name) of the CA that signed the presented certificate.

auth_type

The mechanism used for SMTP authentication (only set if successful).

auth_authen

The client’s authentication credentials as determined by
authentication (only set if successful). The actual format depends on
the mechanism used, it might be just ‘user’, or
‘user@realm’, or something similar.

auth_author

The authorization identity, i.e. the ‘AUTH=’ parameter of the
SMTP MAIL command if supplied.

taid

MeTA1 transaction id.

msgid

Message-Id of the message.

c

The hop count. Basically, this is the number of ‘Received:’ headers.

Notice the following limitations:

‘taid’ cannot be requested before ‘mail’ stage.

‘msgid’ can be requested only in ‘dot’ stage.

All ‘tls_*’ macros are valid only after a STARTTLS
command.

The number of MeTA1 macros per stage is limited by
PM_MAX_MACROS define in include/sm/pmfdef.h. In MeTA1
versions up to and including 1.0.PreAlpha28.0, this number is 8. If
you need more macros, increase this number and recompile MeTA1.

Set Milter log verbosity level for this client. Argument is a list of
items separated by commas or whitespace. Each item is a log level
optionally prefixed with ‘!’ to indicate “any level except this”,
‘<’, meaning “all levels up to and including this”, or with
‘>’, meaning “all levels starting from this”.

Log levels in order of increasing priority are: ‘proto’, ‘debug’,
‘info’, ‘warn’, ‘err’, ‘fatal’. The first two
levels are needed for debugging libgacopyz and Milter protocol.
See Gacopyz, for the description of the libgacopyz library.
See also the following subsection.

13.1.4 Debugging Pmult

If needed, pmult can be instructed to provide additional
debugging information. The amount of this information is configured
by three configuration statements. First of all, the standard
debug block statement controls debugging of the underlying GNU
Mailutils libraries (see Mailutils Configuration
File in GNU Mailutils Manual). Secondly, the debug
statement controls debugging output of the pmult utility
itself. The pmilter-debug statement controls debugging output
of the underlying MeTA1 libraries, and, finally, the log-level
statement, described in the previous subsection, defines debugging
level for the Milter library (libgacopyz).

Pmult Conf: debugspec

Set debugging level for the pmult code. See Mailutils Configuration File in GNU Mailutils
Manual, for a description of spec syntax. Multiplexor-specific
debugging is enabled by the ‘pmult’ category. The following
levels are used:

This information is printed using the output channel defined in the
logging statement (see Mailutils Configuration File in GNU Mailutils Manual).

Pmult Conf: pmilter-debuglevel

Set debug verbosity level for the Pmilter library. Argument is a
positive integer between zero (no debugging, the default),
and 100 (maximum debugging).

Pmilter debugging information is printed on the standard error. Use
piesstderr statement to capture this stream and
redirect it to the syslog or file (see Output Redirectors in Pies Manual).

13.2 Pmult Example

The following is an example of a working pmult
configuration. The multiplexer listens on localhost, port
‘3333’. It prints its diagnostics using syslog facility
local2. A single Mailfromd client is declared, which
listens on UNIX socket
/usr/local/var/mailfromd/mailfrom. The log verbosity level
for this client is set to ‘info’ and higher, i.e.: ‘info’,
‘warn’, ‘err’ and ‘fatal’.

13.3 Pmult Invocation

Normally, pmult is invoked without command line
arguments. However, it does support several command line options.
First of all, the common GNU Mailutils options are understood, which
are useful for checking pmult configuration file for syntax
errors. See Common Options in GNU
Mailutils Manual, for a detailed description of these.

The rest of command line options supported by pmult is
useful mostly for debugging. These options are summarized in the
table below:

--log-tag=string

Set the identifier used in syslog messages to string. This
option mostly is for debugging purposes. We advise
to use logging configuration statement for this purpose
(see Logging Statement in GNU Mailutils Manual).

--no-signal-handler

Disable signal handling in the main thread. This is for debugging
purposes.

--syslog

Log to the syslog. This is the default. See Logging
Statement in GNU Mailutils Manual, for information on how
to configure syslog logging.

-s

--stderr

Log to the standard error stream.

--url=url

Listen on the given url. This overrides the url
configuration statement (see url).

-x

--debug=level

Set debug verbosity level. This overrides the debug
configuration statement. See pmult-debug, for more information.