Sun Java System Messaging Server 6 2005Q4 Administration Reference


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:


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:


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

Table 4–26 shows the available options.

Table 4–26 Dispatcher configuration file options




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.


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.


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:



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: 

500 5.7.1 access_control: host found on DNS list and rejected

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


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


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. 


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


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.


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.


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.


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


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


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


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.


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. 


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. 


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:





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. 


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.


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.

Table 4–27 Dispatcher Debugging Bits







x 00001 

Basic Service Dispatcher main module debugging. 

x 00002 

Extra Service Dispatcher main module debugging. 

x 00004 

Service Dispatcher configuration file logging. 

x 00008 

Basic Service Dispatcher miscellaneous debugging. 

x 00010 


Basic service debugging. 

x 00020 


Extra service debugging. 

x 00040 


Process related service debugging. 

x 00080 


Not used. 

x 00100 


Basic Service Dispatcher and process communication debugging. 

x 00200 


Extra Service Dispatcher and process communication debugging. 


x 00400 


Packet level communication debugging. 


x 00800 


Not used. 


x 01000 


Basic Worker Process debugging. 


x 02000 


Extra Worker Process debugging. 


x 04000 


Additional Worker Process debugging, particularly connection hand-offs. 


x 08000 


Not used. 


x 10000 


Basic Worker Process to Service Dispatcher I/O debugging. 


x 20000 


Extra Worker Process to Service Dispatcher I/O debugging. 


x 100000 


Basic statistics debugging. 


x 200000 


Extra statistics debugging. 


x 1000000 


Log PORT_ACCESS denials to the dispatcher.log file.