The Job Controller configuration file contains lines of the form

option=value

in accordance with the format of PMDF option files.

In addition to option settings, the file can contain a line consisting of a section and value enclosed in square-brackets in the form

[section-type=value]

Such a line indicates that option settings following this line are to apply only to the section named by value. Initial option settings that appear before any such section tags apply globally to all sections.

Per section option settings override global defaults for that section.

Recognized section types for the Job Controller configuration file are [QUEUE] to define queues and their parameters, and [CHANNEL] to define channel processing information.

A sample Job Controller configuration file on UNIX is shown in Figure 10-1; a sample Job Controller configuration file on NT is shown in Figure 10-2.

Figure 10-1 Sample Job Controller Configuration File on UNIX

! ! Global parameters and defaults for all queues ! and channels. ! TCP_PORT=27442 (1) SLAVE_COMMAND=NULL (2) ! ! The DEFAULT queue, which is used for channels that don't ! specify a queue. ! [QUEUE=DEFAULT] (3) JOB_LIMIT=8 (4) ! ! Another queue for some channels to use. ! [QUEUE=BIGQUEUE] JOB_LIMIT=16 ! ! Definitions for channel processing; each section ! corresponding to a PMDF channel. ! [CHANNEL=l] (5) MASTER_COMMAND=/pmdf/bin/l_master ! [CHANNEL=tcp_*] MASTER_COMMAND=/pmdf/bin/tcp_smtp_client ANON_HOST=0 ! [CHANNEL=cc_*] (6) MASTER_COMMAND=/pmdf/bin/lan_master SLAVE_COMMAND=/pmdf/bin/lan_slave

Figure 10-2 Sample Job Controller Configuration File on NT

! ! Global parameters and defaults for all queues ! and channels. ! TCP_PORT=27442 (1) SLAVE_COMMAND=NULL (2) ! ! The DEFAULT queue, which is used for channels that don't ! specify a queue. ! [QUEUE=DEFAULT] (3) JOB_LIMIT=8 (4) ! ! Another queue for some channels to use. ! [QUEUE=BIGQUEUE] JOB_LIMIT=16 ! ! Definitions for channel processing; each section ! corresponding to a PMDF channel. ! [CHANNEL=l] (5) MASTER_COMMAND=pmdf_exe:msgstore_master ! [CHANNEL=tcp_*] MASTER_COMMAND=pmdf_exe:tcp_smtp_client ANON_HOST=0 ! [CHANNEL=cc_*] (6) MASTER_COMMAND=pmdf_exe:lan_master SLAVE_COMMAND=pmdf_exe:lan_slave

The key items in the above examples are:

1. This global option defines the TCP port number on which the Job Controller listens for requests.
2. Set a default SLAVE_COMMAND for subsequent [CHANNEL] sections.
3. This [QUEUE] section defines a queue named "DEFAULT". This queue is used by all channels that do not specify a queue name using the queue channel keyword.
4. Set the JOB_LIMIT for this queue to 8.
5. This [CHANNEL] section applies to a channel named "l", the PMDF local channel. The only definition required in this section is the MASTER_COMMAND that the Job Controller issues to run this channel. Since no wildcard appears in the channel name, the channel must match exactly.
6. This [CHANNEL] section applies to any channel whose name begins with "cc_*", i.e., to any PMDF-LAN cc:Mail channel. For this channel, both a MASTER_COMMAND and a SLAVE_COMMAND are necessary. Since this channel name includes a wildcard, it matches any channel whose name begins with "cc_".

The general Job Controller options are:

DEBUG (integer)

An integer value specifying the level of debugging information written to the Job Controller log file in the PMDF log directory. The value of DEBUG is a bit mask specifying what sort of debugging information is requested:

1	Protocol messages between the Job Controller and other PMDF components.
2	Detailed analysis of protocol messages and interactions.
4	Host, queue, and job information.
8	Queue cache database rebuild decisions.
16	Detailed process tracing.
32	Dump each queue on every queue-related action.

Specifying bits 16 or 32 can cause log files to grow very rapidly. Specifying bit 32 will have a noticeable negative impact on PMDF performance.

MAX_MESSAGES (integer)

An integer specifying the number of messages that the Job Controller should provide space for in the in-memory queue cache database. The default value is 100,000, which is sufficient for most sites. If your site regularly experiences large message backlogs, you may wish to increase the value of this option. In the case of a message backlog overflowing the queue cache database, PMDF automatically scans the on-disk queue areas and updates the database as soon as space is available. Note that messages are not lost when the queue cache database fills - they are simply left in the on-disk queue area.

SECRET (integer)

An integer number containing a shared secret to be used for checksum functions, with a default value of 0. The Job Controller requires all incoming requests to be authenticated with a checksum code. This prevents a malicious site from sending malformed requests to the Job Controller.

TCP_PORT (integer)

An integer number indicating the TCP port on which the Job Controller should listen for incoming requests. The default is port 27442. This option shouldn't be changed unless it conflicts with another application on your system.

The options valid in a [QUEUE] section are:

JOB_LIMIT (integer)

The maximum number of jobs (processes) that a queue may run in parallel to handle requests. If there are more requests in the queue than there are available jobs, they are held until a job becomes available to process them. The JOB_LIMIT applies to each queue individually - the maximum total number of jobs is the sum of the JOB_LIMIT parameters for all queues. If this parameter is set outside of a [QUEUE] section, it is used as the default by any queue that doesn't specify a JOB_LIMIT. The default value is 1.

The options valid in a [CHANNEL] section are:

ANON_HOST (0 or 1)

This option is only useful for tcp_* channels. For all other channels, it should be left to the default value of 1.

For TCP channels, when anon_host is set to the default value of 0, this causes the Job Controller to group together messages that are going to be sent to the same remote host (based on the domain name in the envelope TO address), and then treat them as a group. This is the most efficient processing method for the standard tcp_local or tcp_internal channels, which are expected to be sending mail to lots of different remote domain names, with a small number going to each domain name.

Setting the anon_host option to 1 for TCP channels is recommended for specialty channels (that can be configured by the system manager on a site-specific basis) which are set up to send all of its messages to a single remote system. Because this setting allows all of the threads in all of the SMTP client jobs for that channel to be used simultaneously to handle all of the messages. (With anon_host=0, one thread is dedicated to each remote domain name.)

MASTER_COMMAND (file specification)

Specifies the full path to the command to be executed by the Job Controller to run the channel and dequeue outbound messages in the channel. Some PMDF channels do not have a MASTER_COMMAND. If that is the case, the reserved value NULL should be specified. If this parameter is set outside of a [CHANNEL] section, it is used as the default by any channel that doesn't specify a MASTER_COMMAND.

MAX_AGE (integer)

Specifies the maximum lifetime for a channel master job in seconds. When a channel master job has been running for this period of time, it is shut down. This prevents master jobs for heavily used channels from monopolizing the available job slots, and gives lesser-used channels a chance to run. If no value is specified, the default value of 1800 (30 minutes) is used.

MAX_CONNS (integer)

For TCP channels only, in addition to the MAX_AGE parameter, the lifetime of a tcp_xxx channel master job is limited by the number of times it can check with the Job Controller to see if there are any queued requests. If this parameter is not specified for a channel, the default value of 300 is used.

QUEUE (queue name)

By default, all channels use the DEFAULT queue. If you have defined additional queues, use the QUEUE option to direct certain channels to run in certain queues.

SLAVE_COMMAND (file specification)

Specifies the full path to the command to be executed by the Job Controller to run the channel and poll for any messages inbound on the channel. Most PMDF channels do not have a SLAVE_COMMAND. If that is the case, the reserved value NULL should be specified. If this parameter is set outside of a [CHANNEL] section, it is used as the default by any channel that doesn't specify a SLAVE_COMMAND.