PMDF System Manager's Guide

There are two (three on OpenVMS) sorts of configuration options relating to the mailbox servers:

• PMDF Service Dispatcher configuration options, controlling things such as the existence of the POP and IMAP servers, and the number of connections handled per server process;
• mailbox server specific options, controlling things such as timeouts, debugging, and logging; and
• (OpenVMS only) the PMDF_SYSTEM_FLAGS logical, controlling handling of DECnet format node::user addresses.

These options are discussed in Section 13.2.3.1, Section 13.2.3.2, and Section 13.2.3.3, respectively, below.

13.2.3.1 Service Dispatcher Configuration for Mailbox Servers

Samples of service definitions for the legacy mailbox servers to be included in the Dispatcher configuration file, dispatcher.cnf , are shown in Example 13-1 for OpenVMS, and similarly in Example 13-3 for UNIX. The PMDF mailbox servers configuration utility, if told you want to run only the legacy mailbox servers, would generate similar definitions as the file dispatcher_mailbox_servers.cnf in the PMDF table directory. Sample of service definitions for the PMDF MessageStore mailbox servers to be included in the Dispatcher configuration file are shown in Example 13-2, Example 13-4, and Example 13-5, for OpenVMS, UNIX, and NT, respectively. See Chapter 11 for details on the format and meaning of options in this file.

In particular, on OpenVMS and UNIX where two alternate POP servers and two alternate IMAP servers are available, note that the IMAGE Dispatcher option is used to select the desired server image: compare Example 13-1 vs. Example 13-2, or Example 13-3 vs. Example 13-4. Also note that sites can run both legacy mailbox servers and PMDF MessageStore mailbox servers on the same system by running them on different ports, as selected by the PORT option.

Example 13-1 Sample dispatcher_mailbox_servers.cnf File on OpenVMS for Legacy Mailbox Servers---Dispatcher Definitions for POP and IMAP Servers

! ! POP3 server for both POPSTORE and regular mail ! [SERVICE=POP3] PORT=110 IMAGE=PMDF_EXE:POP3D.EXE LOGFILE=PMDF_LOG:POP3D.LOG MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=4 MIN_CONNS=3 MAX_CONNS=5 MAX_LIFE_CONNS=400 PGFLQUOTA=110000 ENQLM=1000 FILLM=450 ! ! IMAP server ! [SERVICE=IMAP] PORT=143 IMAGE=PMDF_EXE:IMAPD.EXE LOGFILE=PMDF_LOG:IMAPD.LOG MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=4 MIN_CONNS=2 MAX_CONNS=5 MAX_LIFE_CONNS=100 PGFLQUOTA=125000 ENQLM=1000 FILLM=450

Example 13-2 Sample dispatcher_mailbox_servers.cnf File on OpenVMS for PMDF MessageStore Mailbox Servers---Dispatcher Definitions for POP and IMAP Servers

! ! POP3 server for downloading mail ! [SERVICE=POP_SERVER] PORT=110 IMAGE=PMDF_EXE:POP_SERVER.EXE LOGFILE=PMDF_LOG:POP_SERVER_%s.LOG MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=4 MIN_CONNS=3 MAX_CONNS=5 PGFLQUOTA=100500 ENQLM=146 FILLM=187 ! ! IMAP4rev1 server for accessing mail on server ! [SERVICE=IMAP_SERVER] PORT=143 IMAGE=PMDF_EXE:IMAP_SERVER.EXE LOGFILE=PMDF_LOG:IMAP_SERVER_%s.LOG MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=4 MIN_CONNS=3 MAX_CONNS=5 PGFLQUOTA=100500 ENQLM=146 FILLM=187

Example 13-3 Sample dispatcher_mailbox_servers.cnf File on UNIX for Legacy Mailbox Servers---Dispatcher Definitions for POP and IMAP Servers

! ! POP3 server for both POPSTORE and regular mail ! [SERVICE=POP3] PORT=110 IMAGE=PMDF_EXE:pop3d_dispatcher LOGFILE=PMDF_LOG:pop3d_dispatcher.log MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=3 MIN_CONNS=3 MAX_CONNS=5 USER=root ! ! IMAP server ! [SERVICE=IMAP] PORT=143 IMAGE=PMDF_EXE:imapd_dispatcher LOGFILE=PMDF_LOG:imapd_dispatcher.log MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=3 MIN_CONNS=2 MAX_CONNS=5 USER=root

Example 13-4 Sample dispatcher_mailbox_servers.cnf File on UNIX for PMDF MessageStore Mailbox Servers---Dispatcher Definitions for POP and IMAP Servers

! ! POP3 server for downloading mail ! [SERVICE=POP_SERVER] PORT=110 IMAGE=pmdf_exe:pop_server LOGFILE=pmdf_log:pop_server.log MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=4 MIN_CONNS=3 MAX_CONNS=5 ! ! IMAP4rev1 server for accessing mail on server ! [SERVICE=IMAP_SERVER] PORT=143 IMAGE=pmdf_exe:imap_server LOGFILE=pmdf_log:imap_server.log MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=4 MIN_CONNS=3 MAX_CONNS=5

Example 13-5 Sample dispatcher_mailbox_servers.cnf File on NT for MessageStore Mailbox Servers---Dispatcher Definitions for POP and IMAP Servers

! ! POP3 server for both POPSTORE and MessageStore mail ! [SERVICE=POP3] PORT=110 IMAGE=C:\pmdf\bin\pop_server LOGFILE=C:\pmdf\log\pop_server.log MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=3 MIN_CONNS=3 MAX_CONNS=5 ! ! IMAP server ! [SERVICE=IMAP] PORT=143 IMAGE=C:\pmdf\bin\imap_server LOGFILE=C:\pmdf\log\imap_server.log MIN_PROCS=1 MAX_PROCS=6 MAX_SHUTDOWN=3 MIN_CONNS=2 MAX_CONNS=5

13.2.3.2 Mailbox Server Specific Options

Note that after a server has started running, it will not see changes made to the configuration option files. Use the PMDF RESTART (OpenVMS) or pmdf restart command (UNIX or NT) to restart your servers after making changes to these options. Note that if the server is not running, then the Dispatcher itself must be restarted (or started up if not already running) in order to start the server, via the PMDF RESTART DISPATCHER (OpenVMS) or pmdf restart dispatcher (UNIX or NT) command, or the PMDF STARTUP DISPATCHER (OpenVMS) or pmdf startup dispatcher (UNIX or NT) command.

13.2.3.2.1 IMAP Server Configuration Options

In either case, the IMAP server option file follows the format of PMDF option files; see, for instance, Section 7.2 for a description of this format.

Note that any changes to an IMAP server configuration file will not take effect until the IMAP server is restarted via the OpenVMS command

$ PMDF RESTART/CLUSTER IMAP

or the UNIX command

# pmdf restart imap

or the NT command

C:\> pmdf restart dispatcher

DEBUG (integer)

For both the PMDF legacy mailbox server and the MessageStore mailbox server, this option takes a value where each bit corresponds to a different subcomponent or set of debugging information. This option should only be specified when debugging is needed. Performance of the server is negatively impacted when debugging is enabled. For the legacy mailbox server, when this option is set to 1 or higher, the POP or IMAP protocol dialogue between the client and server, on a per thread basis, is written to files in the PMDF log directory named imap_thread.log . For the MessageStore mailbox server, if the option is set to 1 or higher, per thread debug logging is written to files in the PMDF log directory named imaps_thread.log . The POP or IMAP protocol dialogue output is turned on for the MessageStore servers by setting this option to a value of 7. If you are having a problem that needs debug logging turned on, Process Software's technical support department will instruct you to set this option's value as needed to capture debug logging for the components that are related to the problem. Be sure to specify this option in the appropriate IMAP server configuration file, imapd.cnf for the legacy mailbox server or imappop.cnf for the PMDF MessageStore mailbox server, if you want to enable debugging for the IMAP server, not in the Dispatcher configuration file, which enables entirely different debugging! The default is 0.

Caution Since all input from the client is logged, this means that passwords are also written to the debugging file.

DEBUG_USER_username (integer)

For the legacy mailbox server, when this option is set to 1, the POP or IMAP protocol dialogue between the client and server, on a per thread basis, is written to files in the PMDF log directory named imapd_thread.log , showing all transactions involving only user username. For the PMDF MessageStore mailbox server, if this option is set to 7, the POP or IMAP protocol dialogue between the client and server, on a per thread basis, is written to files in the PMDF log directory named imaps_thread.log showing all transactions involving user username. Note that the additional debug logging in the MessageStore mailbox server cannot be turned on by this user-specific debug option, only by the global DEBUG option. This option can only turn on the POP/IMAP protocol exchange between the client and server. The debugging output includes all dialog between the server and the user's client, therefore this should only be used when debugging is needed. Performance of the server will suffer when this is enabled. Be sure to put this in the appropriate IMAP server configuration file, imapd.cnf for legacy mailbox server or imappop.cnf for the PMDF MessageStore mailbox server, if you want to enable debugging for the IMAP server, not in the Dispatcher configuration file, which enables entirely different debugging! The default is 0.

Caution Since all input from the client is logged, this means that the user's password is also written to the debugging file.

FORCE_CHECK_TIME (integer; OpenVMS legacy mailbox server only)

This option is an integer value in seconds. On OpenVMS, the server will reopen the NEWMAIL folder and get the current new mail count on a CHECK command if this many seconds have passed since the last CHECK command. This is a way to trade off accuracy versus server overhead because opening a folder is an expensive operation for the VMS MAIL mailbox. The default is 600. A zero value means the server will not automatically reopen the folder.

FORCE_COPY_TO_APPEND (0 or 1; OpenVMS legacy mailbox server only)

On OpenVMS, this option can be used to select OpenVMS mailbox style movement of messages---whereby messages are inserted in original delivery date order into folders when moved---rather than the standard IMAP style movement whereby messages are always inserted at the end of a folder when moved (getting a new date in the process). The default is 1, meaning that standard IMAP style moves are performed. Setting FORCE_COPY_TO_APPEND=0 selects OpenVMS mailbox style movement. Note that using FORCE_COPY_TO_APPEND=0 is not safe unless the IMAP client properly pays attention to UID validity, since the movement of messages into the middle of a folder invalidates UIDs; note that it will also require the client to perform more work, since the client will need to update UIDs after such a message move is performed and UIDs are invalidated.

FORCE_KILL_TIMEOUT (integer)

In the IMAP protocol, a client can connect and stay connected essentially indefinitely, with the client issuing periodic commands keeping the connection alive---typically the frequency of such commands being specified by the IMAP client as an option along the lines of "how often to check for new mail". Unless the user says never to check for new mail, the connection will stay alive indefinitely. Even restarting the PMDF IMAP server won't affect this, because "live" connections must terminate before the IMAP server itself can shut down. This can be undesirable because it means system resources are wasted. The FORCE_KILL_TIMEOUT option allows the IMAP server to force a disconnect after the specified time if it goes into the shutdown state, (as when its Dispatcher configured MAX_LIFE_CONNS value is reached, or if the PMDF IMAP server or the Dispatcher in general has been instructed to restart). The value for this option specifies the number of seconds to wait before shutting down the connection, when in a shutdown state. For instance, if FORCE_KILL_TIMEOUT=300 is set, then the users connected to the server shutting down will be disconnected after 300 seconds. Warnings are issued to the client, and the client program should display them. The user then has to "Connect" or just open a message, and the client should then reconnect automatically. However, note that the appearance of the warnings ("dialogue boxes") can cause confusion to the users, since the underlying issue (that the server needs to restart) is outside their frame of reference. A different option that can be preferable for limiting the resources used by IMAP users is SESSION_LIFETIME , as its timing depends instead upon a user's own connection lifetime and hence its impact will be more predictable from the user point of view. The default is that the FORCE_KILL_TIMEOUT option is not set. See the related options SEND_KILL_WARNING , KILL_WARNING_TEXT , and KILL_FINAL_TEXT .

LOGGING (0, 1, or 2)

When this option is set to 1, user login/logout events will be logged to a PMDF log file. By default, such connection log records are written to the PMDF mail log file mail.log_current in the PMDF log directory, but if the SEPARATE_CONNECTION_LOG PMDF option has been set, then they will instead be written to the PMDF connection log file, connection.log_current . Connection activity is logged with both a time stamp and client host information when each connection is opened, closed, etc. When this option is set to 2, only login authentication failures (A records) will be logged to the PMDF log file. The default is 0, meaning that no such logging is performed. The types of entry records written are:

Entry	Description
A	Authentication attempt failed
O	Login phase completed (either successful login or aborted connection)
C	Connection closed cleanly
X	Connection aborted (by either end)+

KILL_FINAL_TEXT (string)

KILL_WARNING_TEXT (string)

SEND_KILL_WARNING (0 or 1)

SESSION_LIFETIME (integer)

TIMEOUT (integer)

UPDATE_LOGIN_TIME (0 or 1) (OpenVMS legacy mailbox server only)

13.2.3.2.2 POP3 Server Configuration Options

In either case, the POP server option file follows the format of PMDF option files; see, for instance, Section 7.2 for a description of this format.

Note that any changes to a POP server configuration file will not take effect until the POP server is restarted via the OpenVMS command

$ PMDF RESTART/CLUSTER POP

or the UNIX command

# pmdf restart pop

or the NT command

C:\> pmdf restart dispatcher

DEBUG (0 or 1)

When this option is set to 1, per thread debugging output will be written to pop3d_thread.log files for the legacy mailbox server or pop3s_thread.log files for the PMDF MessageStore mailbox server; these files will be located in the PMDF log directory. The debugging output includes all dialog between the server and the client, therefore this should only be used when debugging is needed. Performance of the server will suffer when this is enabled. Be sure to put this in the appropriate POP3 server configuration file, pop3d.cnf file for the legacy mailbox server or the imappop.cnf file for the PMDF MessageStore server, if you want to enable debugging for the POP3 server, not in the Dispatcher configuration file, which enables entirely different debugging! The default is 0.

DEBUG_USER_username (0 or 1)

When this option is set to 1, per thread debugging output will be written to files in the PMDF log directory named pop3d_thread.log for the legacy mailbox server or pop3s_thread.log for the PMDF MessageStore mailbox server; such files will show each transaction involving user user. The debugging output includes all dialog between the server and the user's client, therefore this should only be used when debugging is needed. Performance of the server will suffer when this is enabled. Be sure to put this in the appropriate POP3 server configuration file, pop3d.cnf for the legacy mailbox server or imappop.cnf for the PMDF MessageStore mailbox server, if you want to enable debugging for the POP3 server, not in the Dispatcher configuration file, which enables entirely different debugging! The default is 0.

DISABLE_UIDL(0 or 1)

When this option is set to 1, the POP3 server will not honor the UIDL command. The default is 0. This option is used for the MessageStore POP server. The legacy POP server uses the option NO_UIDL .

FUDGE_SIZE (integer) (OpenVMS only)

On OpenVMS, when this option is set to a non-zero value, the POP3 server will not read the entire message to determine its size in bytes, instead it will multiply the number of records with this number to get an approximate size of the message. Then the value is returned in the LIST and STAT commands, this makes the POP3 server respond faster when there are a lot of messages in the NEWMAIL folder. This option is only used with the VMS MAIL message store. If the message is actually retrieved with the RETR command, then the actual message size is used in future responses. The default is 0. Recommended non-zero values range from 80 to 256. 80 is assuming each record is about 80 characters long, 256 is the maximum record size.

LOGGING (0, 1, or 2)

When this option is set to 1, user login/logout events will be logged to a PMDF log file. By default, such connection log records are written to the PMDF mail log file mail.log_current in the PMDF log directory, but if the SEPARATE_CONNECTION_LOG PMDF option has been set then they will instead be written to the PMDF connection log file, connection.log_current . Connection activity is logged with both a time stamp and client host information when each connection is opened, closed, etc. When this option is set to 2, only login authentication failures (A records) will be logged to the PMDF log file. The default is 0, meaning that no such logging is performed. The types of etnry records written are:

Entry	Description
A	Authentication attempt failed
O	Login phase completed (either successful login or aborted connection)
C	Connection closed cleanly
X	Connection aborted (by either end)+

MAX_MESSAGES (integer)

MIN_LOGIN_INTERVAL (integer)

MOVE_READ_MAIL (OpenVMS legacy mailbox server only)

NO_UIDL (0 or 1)

OVER_QUOTA_MSG_FILE (string)

TIMEOUT (integer)

UPDATE_LOGIN_TIME (0 or 1) (OpenVMS legacy mailbox server only)

13.2.3.3 The PMDF_SYSTEM_FLAGS Logical and DECnet Style Addresses on OpenVMS

PMDF_SYSTEM_FLAGS (OpenVMS only)

This option is similar to the MAIL$SYSTEM_FLAGS logical name, but currently only bit 0 is used by the mail servers. If bit 0 is set (i.e., the value of PMDF_SYSTEM_FLAGS is 1), then the node is treated as part of a homogeneous cluster. This is only of impact when a mail message to be read lacks an RFC 822 header. In this case the VMS MAIL From: and To: addresses are converted from the DECnet format node::user to user%node@servernode if bit 0 is clear, or to user@servernode if bit 0 is set. If PMDF_SYSTEM_FLAGS is not set, then the value of MAIL$SYSTEM_FLAGS is used. If MAIL$SYSTEM_FLAGS is not defined either, then the node is not treated as part of a homogeneous cluster, and the address would appear as user%node@servernode. This logical name should be entered in the SYSTEM logical name table as an EXECUTIVE mode logical.