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.

                                                 +-----------------+
                                          +----->| Milter Client 1 |
                                          |      +-----------------+
                                          |
        +-----------+       +---------+   |      +-----------------+
        |   MeTA1   |<=====>|  Pmult  |<--+----->| Milter Client 1 |
        +-----------+       +---------+   |      +-----------------+
                                          |
                                          +--------->    //
                                          |
                                          |      +-----------------+
                                          +----->| Milter Client N |
                                                 +-----------------+

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 (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 (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 (Pies Manual).

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.

The following standard Mailutils statements are understood:

Statement   Reference
debug   see Mailutils Configuration File (GNU Mailutils Manual).
logging   see Mailutils Configuration File (GNU Mailutils Manual).
include   see Mailutils Configuration File (GNU Mailutils Manual).

Multiplexer Configuration.
--------------------------

Pmult listens for Pmilter requests on a socket, configured using listen statement:

 -- Pmult Conf: listen URL
     Listen on the given URL.  Argument is a valid Mailutils URL.  See milter port specification, for a description of URL.

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: pidfile FILE
     Store PID of the pmult process in FILE.

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

 -- Pmult Conf: max-threads-soft N
     ``Soft'' limit on the number of pmilter threads.  Default is 2.

 -- Pmult Conf: max-threads-hard N
     ``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-fd N
     Maximum number of file descriptors pmilter library is allowed to open simultaneously.  Default is 10.

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 VERSION, only IPv4 addresses are supported.  Defined in all handlers.

client_port
     The port number of the SMTP client.  Defined in all handlers.

i
     MeTA1 session ID.  Defined in all handlers.

f
     The envelope sender (from) address.  Defined in envfrom and subsequent handlers.

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

ntries
     The number of delivery attempts.  As of version VERSION 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-macros HANDLER MACROS
     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:

      1. taid cannot be requested before mail stage.

      2. msgid can be requested only in dot stage.

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

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

 -- Pmult Conf: auth-macros BOOL
     If BOOL is true (see boolean (GNU Mailutils Manual)), pass auth macros to mailfromd mail handler.  It is equivalent to:

          define-macros mail (auth_type, auth_authen, auth_author);

Pmult Client Configuration.
---------------------------

In pmult terminology, remote Milters are clients. The number of clients pmult is able to handle is not limited.  Each client is declared using client statement:

     client [IDENT] {
       # Set remote protocol type.
       type PROTOCOL-TYPE;
       # Set remote client URL.
       url ARG;
       # Set write timeout.
       write-timeout DURATION;
       # Set read timeout.
       read-timeout DURATION;
       # Set timeout for EOM.
       eom-timeout DURATION;
       # Set connect timeout.
       connect-timeout DURATION;
       # Set log verbosity level.
       log-level LEVEL;
     };

 -- Pmult Conf: client [IDENT] { STATEMENTS }
     Declare a Milter client.  Optional IDENT gives the identifier of this client, which will be used in diagnostics messages.

     STATEMENTS are described below.

 -- Pmult Conf: type TYPESTR
     This statement is reserved for future use.  In version VERSION it is a no-op.

     If given, the value of TYPESTR must be milter.

     In future versions this statement will declare the protocol to be used to interact with this client.  The syntax for TYPESTR is

            TYPE [VERSION]

     where TYPE is either milter or pmilter, and optional VERSION is minimal protocol version.

 -- Pmult Conf: url ARG
     Set remote client URL.  See milter port specification, for a description of URL.

 -- Pmult Conf: connect-timeout INTERVAL
     Configure Milter initial connection timeout.  Default is GACOPYZ_CONNECT_TIMEOUT.

     See time interval specification, for information on INTERVAL format.

 -- Pmult Conf: write-timeout INTERVAL
     Configure Milter write timeout.  Default is GACOPYZ_WRITE_TIMEOUT.

     See time interval specification, for information on INTERVAL format.

 -- Pmult Conf: read-timeout INTERVAL
     Configure Milter read timeout.  Default is GACOPYZ_READ_TIMEOUT.

     See time interval specification, for information on INTERVAL format.

 -- Pmult Conf: eom-timeout INTERVAL
     Configure Milter end of message timeout.  Default is GACOPYZ_EOM_TIMEOUT.

     See time interval specification, for information on INTERVAL format.

 -- Pmult Conf: log-level ARG
     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.

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 (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: debug SPEC
     Set debugging level for the pmult code.  See Mailutils Configuration File (GNU Mailutils Manual), for a description of SPEC syntax.  Multiplexor-specific debugging is enabled by the pmult category.  The following levels are used:

     pmult.trace1
          Prints the following information:

            * opening and closing incoming connections;

            * entering particular Pmilter stage handlers;

            * received requests with unknown command code;

            * header modification requests that does not match any headers.

     pmult.trace2
          Information about milter to Pmilter request translation.

     pmult.trace7
          Detailed dump of message body chunks received during Pmilter DATA stage.

     pmult.error
          Logs bad recipient addresses.

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

 -- Pmult Conf: pmilter-debug LEVEL
     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 pies stderr statement to capture this stream and redirect it to the syslog or file (see Output Redirectors (Pies Manual)).

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.

     listen inet://127.0.0.1:3333;

     logging {
        facility local2;
     };

     debug {
        level "pmult.trace7";
     }

     define-macros envmail (auth_type, auth_authen, auth_author, tls_vrfy);
     define-macros envrcpt (auth_type, auth_authen, auth_author);

     client {
        type milter;
        url /usr/local/var/mailfromd/mailfrom;
        log-level ">info";
        # Set write timeout.
        write-timeout 30 seconds;
        # Set read timeout.
        read-timeout 5 minutes;
        # Set timeout for EOM.
        eom-timeout 5 minutes;
     }

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