Dispatcher

The MTA multithreaded Dispatcher is a multithreaded connection dispatching agent that permits multiple
multithreaded servers to share responsibility for a given service. When using
the Dispatcher, it is possible to have several multithreaded SMTP servers
running concurrently. In addition to having multiple servers for a single
service, each server may handle simultaneously one or more active connections.

Dispatcher Configuration File

The Dispatcher configuration information is specified in the msg_svr_base/imta/dispatcher.cnf file. A default configuration
file is created at installation time and can be used without any changes made.
However, if you want to modify the default configuration file for security
or performance reasons, you can do so by editing the dispatcher.cnf file.

Configuration File Format

The Dispatcher configuration file format is similar to the format of
other MTA configuration files. Lines specifying options have the following
form:

option=value

The option is the name of an option and value is the string or integer to which the options is set.
If the option accepts an integer value, a base
may be specified using notation of the form b%v, where b is the base expressed
in base 10 and v is the actual value expressed
in base b. Such option specifications are grouped
into sections corresponding to the service to which the following option settings
apply, using lines of the following form:

[SERVICE=service-name]

The service-name is the name of a service.
Initial option specifications that appear before any such section tag apply
globally to all sections.

Controls the depth of the TCP backlog queue for the socket. The default
value for each service is MAX_CONNS*MAX_PROCS (with a minimum
value of 5). This option should not be set higher than the underlying TCP/IP
kernel supports.

DEBUG

Enables debugging output. Enabling all debugging is done by setting
the option to -1. The actual meaning of each bit is described in Table 4–27.

DNS_VERIFY_DOMAIN

Specifies the host name or IP address of source against which to check
incoming connections. Various groups maintain information about unsolicited
email sources or open relay sites. Some sites check incoming IP connections
against the lists maintained by such groups. Up to five DNS_VERIFY_DOMAIN options can be specified for each service. Note that SMTP is typically
the only service for which such checks make sense. For example:

[SERVICE=SMTP]

PORT=25

DNS_VERIFY_DOMAIN=rbl.maps.siroe.com

DNS_VERIFY_DOMAIN=dul.maps.siroe.com

If this options is enabled on a well known port (25, 110, or 143), then
a standard message such as the one below is sent before the connection is
closed:

If you wish the MTA to log such rejections, the 24th bit of the Dispatcher
debugging DEBUG option can be set (DEBUG=16%1000000) to
cause logging of the rejections to the dispatcher.log file.
Log entries take the following form:

access_control: host a.b.c.d found on DNS list and rejected

ENABLE_RBL=0 or 1

This option is deprecated. You should use the DNS_VERIFY_DOMAIN option or the dns_verify callout from the PORT_ACCESS mapping table instead.

HISTORICAL_TIME=integer

Controls how long the expired connections (those that have been closed)
and processes (those that have exited) remain listed for statistical purpose
in the Dispatcher statistics.

INTERFACE_ADDRESS=IP address

The INTERFACE_ADDRESS option can be used to specify
the IP address interface to which the Dispatcher service should bind. By default,
the Dispatcher binds to all IP addresses. But for systems having multiple
network interfaces each with its own IP address, it may be useful to bind
different services to the different interfaces. Note that if INTERFACE_ADDRESS is specified for a service, then that is the only interface IP
address to which that Dispatcher service bind. Only one such explicit interface
IP address may be specified for a particular service (though other similar
Dispatcher services may be defined for other interface IP addresses).

IDENT=0 or 1

If IDENT=1 is set for a service, it causes the Dispatcher
to try an IDENT query on incoming connections for that
service, and to note the remote username (if available) as part of the Dispatcher
statistics. The default is IDENT=0, meaning that no such
query is made.

IMAGE=file specification

Specifies the image that is run by server processes when created by
the Dispatcher. The specified image should be one designed to be controlled
by the Dispatcher.

LOGFILE=file specification

Causes the Dispatcher to direct output for corresponding server processes
to the specified file. LOGFILE can include a %s which includes the local system’s hostname in the file
specification. For example, LOGFILE=tcp_smtp_server_%s.log on
node freddy results in log files with the name tcp_smtp_server_freddy.log-*.

MAX_CONNS=integer

Specifies a maximum number of connections that may be active on any
server process. The MAX_CONNS option affects the Dispatcher’s
management of connections. The default value for MAX_CONNS is
10. The maximum possible value for MAX_CONNS is 50.

The choice of setting this option is mainly a performance issue relating
to the number of processes and the size of the process virtual address space.

Setting MAX_CONNS to higher values allows more connections,
but at the potential cost of decreased performance for each individual connection.
If it is set to 1, then for every incoming client connection, only one server
process is used. Note that the value of MAX_CONNS multiplied
by the value of MAX_PROCS controls the maximum number of
simultaneous connections that can be accepted.

MAX_HANDOFFS=integer

Specifies the maximum number of concurrent asynchronous hand-offs in
progress that the Dispatcher allows for newly established TCP/IP connections
to a service port. The default value is 5.

MAX_IDLE_TIME=integer

Specifies the maximum idle time for a server process. When an server
process has had no active connections for this period, it becomes eligible
for shutdown. This option is only effective if there are more than the value
of MIN_PROCS server processes currently in the Dispatcher’s
pool for this service.

MAX_LIFE_CONNS

Specifies the maximum number of connections an server process can handle
in its lifetime. Its purpose is to perform worker-process housekeeping.

MAX_LIFE_TIME=integer

Requests that server processes be kept only for the specified number
of seconds. This is part of the Dispatcher’s ability to perform worker-process
housekeeping. When an server process is created, a countdown timer is set
to the specified number of seconds. When the countdown time has expired, the
SMTP server process is subject to shutdown. Default value is 86400 (one day).

MAX_PROCS=integer

Controls the maximum number of server processes that are created for
this service.

MAX_SHUTDOWN=integer

Specifies the maximum number of server processes which can be in the
shutdown state. In order to provide a minimum availability for the service,
the Dispatcher does not shut down server processes that might otherwise be
eligible for shutdown if shutting them down results in having more than MAX_SHUTDOWN server processes for the service in the shutdown statue.
This means that processes that are eligible for shutdown can continue running
until a shutdown “slot” is available.

MIN_CONNS=integer

Determines the minimum number of connections that each Worker Process
must have before considering the addition of a new server process to the pool
of currently available server processes. The Dispatcher attempts to distribute
connections evenly across this pool.

MIN_PROCS=integer

Determines the minimum number of server processes that are created by
the Dispatcher for the current service. Upon initialization, the Dispatcher
creates this many detached processes to start its pool. When a process is
shut down, the Dispatcher ensures that there are at least this many available
processes in the pool for this service.

PARAMETER

The interpretation and allowed values for the PARAMETER option
are service specific. In the case of an SMTP service, the PARAMETER option may be set to CHANNEL=channelname, to
associate a default TCP/IP channel with the port for that service. For instance:

[SERVICE=SMTP_SUBMIT]

PORT=587

...

PARAMETER=CHANNEL=tcp_incoming

This can be useful if you want to run servers on multiple ports—if
your internal POP and IMAP clients have been configured to use a port other
than the normal port 25 for message submission, separating their message traffic
from incoming SMTP messages from external hosts—and if you want to associate
different TCP/IP channels with the different port numbers.

PORT=integer...

Specifies the TCP port(s) to which the Dispatcher listens for incoming
connections for the current service. Connections made to this port are transferred
to one of the SMTP server processes created for this service. Specifying PORT=0 disables the current service.

STACKSIZE

Specifies the thread stack size of the server. The purpose of this option
is to reduce the chances of the server running out of stack when processing
deeply nested MIME messages (several hundreds of levels of nesting). Note
that these messages are in all likelihood spam messages destined to break
mail handlers. Having the server fail protects other mail handlers farther
down the road.

Debugging and Log Files

Dispatcher error and debugging output (if enabled) are written to the
file dispatcher.log in the MTA log directory.

Debugging output may be enabled using the option DEBUG in
the Dispatcher configuration file, or on a per-process level, using the IMTA_DISPATCHER_DEBUG environment variable (UNIX).

The DEBUG option or IMTA_DISPATCHER_DEBUG environment variable (UNIX) defines a 32-bit debug mask in hexadecimal.
Enabling all debugging is done by setting the option to -1,
or by defining the logical or environment variable system-wide to the value FFFFFFFF. The actual meaning of each bit is described in Table 4–27.