PMDF System Manager's Guide

The available Dispatcher configuration file options are:

ASTLM, BIOLM, BYTLM, CPULM, DIOLM, ENQLM, FILLM, JTQUOTA, PGFLQUOTA,

PRCLM, TQELM, WSDEFAULT, WSEXTENT, WSQUOTA (integer; OpenVMS only)

On OpenVMS, use the specified process quota. The default values are:

Option	Default value
ASTLM	500
BIOLM	100
BYTLM	200000
CPULM	0
DIOLM	100
ENQLM	0
FILLM	0
JTQUOTA	0
PGFLQUOTA	81920
PRCLM	0
TQELM	500
WSDEFAULT	0
WSEXTENT	0
WSQUOTA	0

A default value of 0 means to use the corresponding PQL_D*SYSGEN parameter value. For POP and IMAP services, the BYTLM, ENQLM, FILLM, and PGFLQUOTA options are particularly relevant. A general recommendation for sites using a POP or IMAP server is to set the Dispatcher option BYTLM in the POP or IMAP service section, respectively, of the Dispatcher configuration file according to the formula:
BYTLM>5120 * Sum_servicesMAX_PROCS + 1024 * Sum_services(MAX_PROCS*MAX_CONNS).

Or if UCX_HOLD=0 is set, the need for BYTLM is instead only
BYTLM>5120 * Sum_servicesMAX_PROCS.

BACKLOG (integer)

This option controls the depth of the TCP backlog queue for the socket. The default value for each service is MAX_CONNS*MAX_PROCS for that service (with a minimum value of 5). On OpenVMS, the maximum value is 255; attempts to set higher values will be treated as a value of 255. This option should not be set higher than the underlying TCP/IP kernel supports.

DNS_VERIFY_DOMAIN (host name or IP address)

Various groups maintain information about spam sources or open relay sites and some sites like to check incoming IP connections against the lists maintained by such groups. This option specifies the host name or IP address of source against which to check incoming connections. You can have up to five DNS_VERIFY_DOMAIN options 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=relays.mail-abuse.org DNS_VERIFY_DOMAIN=dialups.mail-abuse.org

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

500 5.7.1 access_control: host 192.168.51.32 found on DNS list and rejected

If you want PMDF to log such rejections, you can set the 24th bit of the Dispatcher debugging DEBUG option, DEBUG=16%1000000, to cause logging of the rejections to the dispatcher.log file; see Section 11.6. Such dispatcher.log entries will take the form:

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

ENABLE_RBL (0 or 1)

Specifying ENABLE_RBL=1 causes the Dispatcher to compare incoming connections to the "Black Hole" list at mail-abuse.org.

Note Setting ENABLE_RBL to 1 is the same as using the option DNS_VERIFY_DOMAIN set to blackholes.mail-abuse.org. The ENABLE_RBL option has been obsoleted by the DNS_VERIFY_DOMAIN option.

For example, if the Dispatcher receives a connection from 192.168.51.32, then it will attempt to obtain the IP address for the hostname 32.51.168.192.blackholes.mail-abuse.org. If the query is successful, the connection will be closed rather than handed off to a worker process.

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

500 5.7.1 access_control: host 192.168.51.32 found on DNS list and rejected

If you want PMDF to log such rejections, you can set the 24th bit of the Dispatcher debugging DEBUG option, DEBUG=16%1000000, to cause logging of the rejections to the dispatcher.log file; see Section 11.6. Such dispatcher.log entries will take the form:

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

GROUP (string; UNIX only)

USER (string; UNIX only)

These options control under what user id and group id the service runs. Via these options, the Dispatcher can give services the access they need to function properly. The IMAP, POP3, and POPPASSD servers should be set

USER=root

These options should not be set except to those values and for those services where Process Software specifically directs their use.

HISTORICAL_TIME (integer)

The HISTORICAL_TIME option controls how long (in seconds) expired connections (those that have been closed) and processes (those that have exited) remain listed for statistical purposes. The default value is 120 seconds; i.e., two minutes. Note that the setting of this option affects the amount of virtual memory that the Dispatcher requires; for instance, on OpenVMS, busy sites that want to increase the HISTORICAL_TIME setting can also need to increase the PGFLQUOTA option setting for the Dispatcher service itself in a [SERVICE=DISPATCHER] section.

IMAGE (file specification)

This is the image that will be run by Worker Processes when created by the Service Dispatcher. Note that the specified image should be one designed to be controlled by the Service Dispatcher.

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 can 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 will bind. Only one such explicit interface IP address can be specified for a particular service (though other similar Dispatcher services can be defined for other interface IP addresses). Note that the interfaceaddress channel keyword, Section 2.3.4.37, provides the complementary capability for specifying which interface address a TCP/IP channel uses for outgoing connections and messages.

LOGFILE (file specification)

Specifying this option for a service causes the Service Dispatcher to direct output for corresponding Worker Processes to the specified file. The log file can include the system's name (SCSNODE on VMS, if available, or the first part of the Internet hostname) by including the %s token. For instance,

[SERVICE=DISPATCHER] LOGFILE=PMDF_LOG:dispatcher-%s.log

MAX_CONNS (integer)

This option specifies the maximum number of concurrent connections handled by a single server process (Worker Process). When the maximum number of concurrent sessions is reached, the server process stops listening for new connections. When all currently open connections are closed the original server will exit. The default value for this option is 10. On OpenVMS, the maximum possible value for this option is 31, where here the limit is the number of threads supported by OpenVMS's callable MAIL. On other platforms, the maximum possible value for this option is 50. For services where the server image is not multithreaded, this option must be set to 1. In contrast, servers such as the PMDF SMTP server, POP3 server, or IMAP server are multi-threaded, and therefore capable of handling multiple clients. For such multithreaded servers, the choice of setting for 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 will be used. When the client shuts down, the server process will also exit. Note that this value times the MAX_PROCS value controls the maximum number of simultaneous connections that can be accepted.

MAX_HANDOFFS (integer)

This option specifies the maximum number of concurrent asynchronous handoffs in progress that the Dispatcher will allow for newly established TCP/IP connections to a service port. The default value is 5.

MAX_IDLE_TIME (integer)

When a Worker Process has had no active connections for this period, it will be eligible for being shut down. Note that this option is only effective if there are more than the value of MIN_PROCS Worker Processes currently in the Service Dispatcher's pool for this service.

MAX_LIFE_CONNS (integer)

As part of the Service Dispatcher's ability to perform Worker Process housekeeping, this option requests that Worker Processes only be kept around for the specified number of connections. After a Worker Process has handled the specified number of connections, it is subject to being shut down. The global default value is 300. For instance, when specified in a POP or IMAP service section, this is the number of total connections the POP3 or IMAP server is able to accept before being restarted. This is different from the MAX_CONNS option, which limits the number of concurrent connections. On OpenVMS when serving out the native VMS MAIL mailbox it is recommended to set this to no more than 100; otherwise problems due to memory leaks in callable MAIL can be encountered.

MAX_LIFE_TIME (integer)

As part of the Service Dispatcher's ability to perform Worker Process housekeeping, this option requests that Worker Processes only be kept around for the specified number of seconds. When a Worker Process is created, a countdown timer is set to the specified number of seconds. When the countdown time has expired, the Worker Process is subject to being shut down.

MAX_PROCS (integer)

This option controls the maximum number of Worker Processes that will be created for this service. Thus this value times MAX_CONNS thus specifies the maximum number of simultaneous connections that can be handled.

MAX_SHUTDOWN (integer)

In order to provide a minimum availability for the service, the Service Dispatcher will not shut down Worker Processes that might otherwise be eligible to be shut down if shutting them down would result in having more than MAX_SHUTDOWN Worker Processes for the service in the shutting down state. This means that processes that can be eligible to be shut down can continue running until a shutdown "slot" is available. Having this option set to about half of the value of the MAX_PROCS option is usually appropriate.

MIN_CONNS (integer)

The Service Dispatcher attempts to distribute connections evenly across its pool of currently available Worker Processes. The Service Dispatcher uses this value to determine the minimum number of connections that each Worker Process must have before there will be any consideration of adding new Worker Processes to the pool.

MIN_PROCS (integer)

This option determines the minimum number of Worker Processes that will be created by the Service Dispatcher for the current service. Upon initialization, the Service Dispatcher will create this many detached processes to start its pool. When a process is shut down, the Service Dispatcher will ensure 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 can be set to CHANNEL=channelname, to associate a default TCP/IP channel with the port for that SMTP service. For instance,

[SERVICE=SMTP] PORT=25 ... PARAMETER=CHANNEL=tcp_incoming

Note that this can be useful if you want to run SMTP servers on multiple ports -- perhaps because your internal POP and IMAP clients have been configured to use a port other than the normal port 25, thus separating their message traffic from incoming SMTP messages from external SMTP hosts---and if you want to associate different TCP/IP channels with the different port numbers. For an IMAP server or Web500 server, the PARAMETER option can be set to CONFIG_FILE=filename, to tell the server to use the specified file as its configuration file. Note that this can be useful if you want to run such servers on multiple ports with the different servers having different configuration files.

PORT (integer or comma separated list of integers)

Specifies the TCP port(s) on which the Service Dispatcher will listen for incoming connections for the current service. Connections made to this port or these ports will be transferred to one of the Worker Processes created for this service. The default is 25 for SMTP, 110 for POP3, and 143 for IMAP. Specifying PORT=0 has the effect of disabling the current service.

PRIORITY (integer; OpenVMS only)

On OpenVMS, the PRIORITY option can be used to control the priority at which the Worker Processes will run.

STACKSIZE (integer > 0)

Specifies a minimum per-thread stack size. Various components can have their own minimum values; the larger of an explicitly specified STACKSIZE option value and the component's own internal minimum will be used.

TLS_CERTIFICATE (comma separated list of file-specs)

This option specifies a pair of files in which a TLS certificate can be found. The default, if this option is not specified, is to look for a certificate in the server-pub.pem and server-priv.pem files stored in the PMDF table directory. Up to five instances of this option can be specified, which can be particularly useful for sites that want to have and use multiple certificates; for instance:

TLS_CERTIFICATE=/pmdf/table/server-pub.pem,/pmdf/table/server-priv.pem TLS_CERTIFICATE=/pmdf/table/server-smtp-pub.pem,/pmdf/table/server-smtp-priv.pem

Note The TLS_CERTIFICATE option is only available for PMDF-TLS sites.

TLS_PORT (integer or comma separated list of integers)

Specifies the TCP port(s) on which the Service Dispatcher will listen for incoming TLS connections for the current service. Connections made to this port or these ports will automatically negotiate TLS use and be transferred to one of the Worker Processes created for this service. See also Section 15.2.2.1.

Note The TLS_PORT option is only available for PMDF-TLS sites.

UCX_HOLD (0 or 1; OpenVMS only)

On OpenVMS, the UCX_HOLD option controls whether the Dispatcher continues to hold an assigned I/O channel for each connection for that service while the connnection is being handled by a worker process. The default value, UCX_HOLD=1, is required for some TCP/IP packages, such as DEC TCP/IP Services for OpenVMS (UCX). Keeping such connections open requires that your system have a sufficient CHANNELCNT SYSGEN parameter. With some TCP/IP packages, e.g., MultiNet or TCPware, you can want to set this option to 0, allowing the Dispatcher to deassign the I/O channel after the connection has been handed off to a worker process, and thereby mitigating the need to increase the CHANNELCNT value.

WP_TIMEOUT (integer)

This option specifies how many seconds the Dispatcher should wait for a Worker Process to start, before deciding that the Worker Process must be dead and trying to start another one. The default is 30. The value should not be set higher than 60.