The popstore and MessageStore have a few options controlled through the use of option files. The popstore option file contains popstore specific options as well as options shared by both the popstore and MessageStore. Use of this option file is optional for the popstore but mandatory for the MessageStore. The MessageStore option file contains options specific to the MessageStore. Both of these option files are described in the following sections.

Initial option files are created by the configuration utility described in the PMDF Installation Guide manual.

3.1 Location of the Option Files

/pmdf/table/popstore_option /pmdf/table/msgstore_option

On OpenVMS platforms, they are the files

PMDF_TABLE:popstore_option. PMDF_TABLE:msgstore_option.

The option files are ordinary text files and can be created and edited with a normal text editor. Like many PMDF option files, the option files must be world readable.

3.2 Option File Formats

option-name=option-value

where option-value can be either a string or an integer, depending on the option's requirements. If the option accepts an integer value, option-value, a base can 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.

Comments are allowed in option files. Any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored in any option file.

3.3 Options for Both the popstore and the MessageStore

AVOID_LOGIN_NAMES (0, 1, or 2)

Under some circumstances, sites using a password database shared between login and popstore or MessageStore accounts may want to ensure that no popstore or MessageStore accounts are created which have the same name as a login account. By setting AVOID_LOGIN_NAMES=1, popstore and MessageStore accounts cannot be created which have the same name as a login account. When AVOID_LOGIN_NAMES is set to the value 2, popstore and MessageStore accounts cannot be created which have the same name as a privileged login account. On UNIX platforms, a privileged login account is considered to be any account with a UID of 0 or which is in the root group. On OpenVMS platforms, a privileged account is deemed to be any account with a group UIC number less than or equal to the SYSGEN MAXSYSGROUP parameter or which has any default or authorized privileges other than TMPMBX and NETMBX. On NT platforms, AVOID_LOGIN_NAMES only prevents an account named Administrator from being created when a value of either 1 or 2 is used. The default value of AVOID_LOGIN_NAMES is 0 which allows accounts of any name to be created. Note that the AVOID_LOGIN_NAMES option only influences accounts created through the management interfaces and the POPSTORE_command and POPSTORE_command_d subroutines. The option does not influence accounts created through other popstore API routines such as POPSTORE_user_create.

COMPUTE_CONNECT (UNIX or NT file specification; OpenVMS exec-mode logical name)

This option is used to supply the name of a site-developed, shared library which the popstore will then use to compute elapsed connect time for client connections. The shared library must contain an entry point for a subroutine named compute_connect as described in Section 14.1. On UNIX and NT systems, the value of the option must be a full file path --- the path to the file containing the shared library. On OpenVMS systems, the value of the option must be the name of a system-wide, executive mode logical whose translation value is the full file specification for the shared library. Any logical referenced by the logical must also be a system-wide, executive mode logical. Moreover, on OpenVMS systems, the shared library must be installed as a known image with the OpenVMS INSTALL utility.

DEBUG (bit mask)

When set to a value of -1, enables debugging in the popstore. When debugging is enabled, the output is appended to the file /pmdf/log/popstore.log (UNIX and NT) or PMDF_LOG:popstore.log (OpenVMS). The default value is 0 which disables all debug output. Note that use of this option will impact performance of the popstore. Moreover, the format of the debug output is intentionally not documented as it is subject to change. Sites wanting to generate similar output should provide their own logging subroutine; see Chapter 13 for details.

HTTP_REALM (string)

Use the HTTP_REALM option to override the name of the HTTP authentication realm used by the popstore and MessageStore HTTP CGIs.

LOG_ACTIVITY (UNIX or NT file specification; OpenVMS exec-mode logical name)

This option is used to supply the name of a site-developed, shared library which the popstore will then use to log activity. The shared library must contain an entry point for a subroutine named log_activity as described in Section 13.2. On UNIX and NT systems, the value of the option must be a full file path --- the path to the file containing the shared library. On OpenVMS systems, the value of the option must be the name of a system-wide, executive mode logical whose translation value is the full file specification for the shared library. Any logical referenced by the logical must also be a system-wide, executive mode logical. Moreover, on OpenVMS systems, the shared library must be installed as a known image with the OpenVMS INSTALL utility.

LOG_ACTIVITY_MASK (bit mask)

This option can be used in conjunction with the LOG_ACTIVITY option to control for which events the site supplied logging routine is called. By default, the logging routine is called for all events. See Section 13.2.2 for further details.

MAP_PROFILE_FILENAME (UNIX or NT file specification; OpenVMS exec-mode logical name)

This option is used to supply the name of a site-developed, shared library which the popstore will then use to map message filenames to disk devices and directory trees. The shared library must contain an entry point for a subroutine named map_profile_filename as described in Chapter 14. On UNIX and NT systems, the value of the option must be a full file path --- the path to the file containing the shared library. On OpenVMS systems, the value of the option must be the name of a system-wide, executive mode logical whose translation value is the full file specification for the shared library. Any logical referenced by the logical must also be a system-wide, executive mode logical. Moreover, on OpenVMS systems, the shared library must be installed as a known image with the OpenVMS INSTALL utility.

MESSAGE_PROFILE_VERSION (non-negative integer)

The value of this option is passed to the site supplied map_profile_filename subroutine; see Section 14.2 for details. When not specified in the option file, this option assumes the default value of 0.

PASSWORD_LIFETIME (non-negative integer)

Non-negative integer value specifying in units of days, how long a password's lifetime should be before it expires and the user must change their password. To disable password expiration, specify a value of zero, PASSWORD_LIFETIME=0, meaning that passwords never expire. When no PASSWORD_LIFETIME value is specified, password expiration is disabled. Units other than days can be selected by immediately following the numeric value with a single character unit specifier chosen from the table below:

M, m	Units of minutes
H, h	Units of hours
D, d	Units of days
W, w	Units of weeks

For instance, a value of 14 days might be specified as

PASSWORD_LIFETIME=2w

where the value 2w indicates two weeks.

PASSWORD_MINIMUM_LENGTH (0 <= integer <= 32)

This option is used to specify a minimum acceptable length for a password. If the password specified is shorter than PASSWORD_MINIMUM_LENGTH, then it is rejected. If a value of 0 is specified, or this option is not specified at all, there is no minimum length required (this is the default).

PASSWORD_REASONABLENESS (0, 1, or 2)

This option is used to specify what level of "reasonableness" checks that a password must go through to be acceptable. If the password specified does not pass the reasonableness checks, it is rejected. A value of 0 (the default) causes no reasonableness checks to be made. A value of 1 causes PMDF to check and make sure that the password is not the same as the username. A value of 2 causes PMDF to check and make sure both that the password is not the same as the username, and it is not a substring of the "Owner" field (usually used to contain the real name of the user).

REJECT_OVER_QUOTA (0 or 1)

By default, PMDF will accept incoming messages for users who have exceeded their storage quota. This corresponds to the option setting REJECT_OVER_QUOTA=0. To have PMDF reject incoming messages for over quota users, specify REJECT_OVER_QUOTA=1. The rejections will take the form of a temporary error (e.g., an SMTP 4yz response). Note that when this option is specified, local users can experience difficulty sending mail to over quota users. For instance, a local POP user when sending mail to an over quota user will be met with a temporary error and their client will be unable to send the message. This option is, in general, only useful when all incoming messages are coming from remote store-and-forward mail systems and not from local user agents.

USERNAME_STYLE (1, 2, or 3)

Selects the name space used for usernames. A value of 3 selects the preferred name space described in Section 1.3.1.1. A value of 2 selects the default name space described in Section 1.3.1.2. Finally, a value of 1 selects the name space described in Section 1.3.1.3. Note that the MessageStore requires that USERNAME_STYLE=3 be used.

Note After creating popstore accounts, you cannot simply change the value of the USERNAME_STYLE option. The value of this option influences the file names used to store profile files. Should you change this option after creating accounts, accounts created before the change can become inaccessible. Contact Process Software for assistance in changing this option with an existing popstore installation. As such, sites which have been using the popstore prior to PMDF V6.0 and now want to use the MessageStore should contact Process Software for assistance.

VALIDATE_PASSWORD (UNIX or NT file specification; OpenVMS exec-mode logical name)

This option is used to supply the name of a site-developed, shared library which PMDF will call to perform additional validation (reasonableness) checks when a user's password is changed. The shared library must contain an entry point for a subroutine named validate_password as described in Section 14.3. On UNIX and NT systems, the value of the option must be a full file path --- the path to the file containing the shared library. On OpenVMS systems, the value of the option must be the name of a system-wide, executive mode logical whose translation value is the full file specification for the shared library. Any logical referenced by the logical must also be a system-wide, executive mode logical. Moreover, on OpenVMS systems, the shared library must be installed as a known image with the OpenVMS INSTALL utility.

3.4 popstore Specific Options

COMPUTE_BLOCK_DAYS (UNIX or NT file specification; OpenVMS exec-mode logical name)

This option is used to supply the name of a site-developed, shared library which the popstore will then use to compute elapsed block days of storage for message files. The shared library must contain an entry point for a subroutine named compute_block_days as described in Section 14.1. On UNIX and NT systems, the value of the option must be a full file path --- the path to the file containing the shared library. On OpenVMS systems, the value of the option must be the name of a system-wide, executive mode logical whose translation value is the full file specification for the shared library. Any logical referenced by the logical must also be a system-wide, executive mode logical. Moreover, on OpenVMS systems, the shared library must be installed as a known image with the OpenVMS INSTALL utility.

MAP_MESSAGE_FILENAME (UNIX or NT file specification; OpenVMS exec-mode logical name)

This option is used to supply the name of a site-developed, shared library which the popstore will then use to map message filenames to disk devices and directory trees. The shared library must contain an entry point for a subroutine named map_message_filename as described in Chapter 14. On UNIX and NT systems, the value of the option must be a full file path --- the path to the file containing the shared library. On OpenVMS systems, the value of the option must be the name of a system-wide, executive mode logical whose translation value is the full file specification for the shared library. Any logical referenced by the logical must also be a system-wide, executive mode logical. Moreover, on OpenVMS systems, the shared library must be installed as a known image with the OpenVMS INSTALL utility.

MESSAGE_FILENAME_VERSION (non-negative integer)

This option is intended for use with a site-supplied map_message_filename subroutine as described in Section 14.2. The value of this option modulo 36 is used to generate the last character appearing in the names of the files used to store messages. The value of the option is also passed to the site supplied map_message_filename subroutine. When not specified in the option file, this option assumes the default value of 0.

QUOTA_WARNING (0 <= integer <= 100)

The POP3 server can optionally generate quota warnings when a user's current storage exceeds a given percentage of their primary storage quota. The warning takes the effect of a virtual e-mail message. That is, the user appears to have a new e-mail message in their inbox which warns about their quota usage. However, this message does not actually exist: the POP server dynamically generates it. By default, these quota warnings are not generated. This corresponds to the option setting QUOTA_WARNING=0. To warn users when they have reached 90% of their allowed primary quota, specify QUOTA_WARNING=90. Note that the POP server OVER_QUOTA_MSG_FILE option may be used to specify a file containing customized warning message text. This option is specified in the PMDF_POP3_CONFIG_FILE configuration file for the legacy POP server and in the PMDF_IMAPPOP_CONFIG_FILE configuration file for the MessageStore POP server. See the PMDF System Manager's Guide for details.

RETURN_AFTER (non-negative integer)

Non-negative integer value specifying in units of days, how long to retain messages in the store. Any message exceeding the specified age will be silently deleted from the message store. A non-delivery notice is sent back to the message's originator, if one or more of the message's recipients had not read the message. To retain messages indefinitely, specify a value of zero, RETURN_AFTER=0. When no RETURN_AFTER value is specified, a maximum message age of 14 days is assumed, RETURN_AFTER=14. Units other than days can be selected by immediately following the numeric value with a single character unit specifier chosen from the table below:

M, m	Units of minutes
H, h	Units of hours
D, d	Units of days
W, w	Units of weeks

For instance, the default value of 14 days might be specified as

RETURN_AFTER=2w

where the value 2w indicates two weeks.

USER_DOMAINS (0 or 1)

By default, all popstore accounts are considered to be part of the same user domain called the default domain. This is true regardless of the e-mail address used to reach the account's mailbox. This default behavior corresponds to the setting USER_DOMAINS=0. By setting USER_DOMAINS=1, the use of user domains is enabled. This allows distinct domains of users to be established, each domain distinguished by the host name associated with the e-mail address used for the accounts in that domain. Note that if you are using USER_DOMAINS=0 and have more than one host listed in the delivery channel's definition,

popstore defragment holdexquota official-host-name second-host-name third-host-name fourth-host-name ...

then setting USER_DOMAIN=1 will cause the mailboxes for the second, third, fourth, etc. hosts to appear to disappear. Specifically, with the above channel definition and USER_DOMAINS=0, all the mailboxes for all those hosts are stored in the same user domain: the default user domain. For example, the e-mail addresses sue@official-host-name and bob@third-host-name correspond, respectively, the the accounts sue and bob in the default user domain. When USER_DOMAINS=1 is set, only the mailboxes for the first host, official-host-name, are associated with the default domain. Mail for bob@third-host-name will be for the account bob in the user domain named third-host-name. That mail will bounce until such time that the bob account is moved from the default user domain to the third-host-name domain, or a new bob account is added to the third-host-name domain.

Note You must not use the filter channel keyword on the popstore or MessageStore delivery channel if USER_DOMAINS=1 is set. So doing will cause the wrong filters to be used for users in domains other than the default domain.

Note The legacy POP3 server does not support user domains.

USERNAME_CHARSET (0-9)

The USERNAME_CHARSET option specifies the character set used for popstore account usernames and is only used when USERNAME_STYLE=1 is set.¹ This character set information is in turn used by the popstore to perform upper case to lower case conversions on usernames presented to the popstore. The valid values for this option are

Value	Character Set	Value	Character Set
0	ASCII, DEC-MCS	5	Latin 5 (ISO-8859-5)
1	Latin 1 (ISO-8859-1)	6	Latin 6 (ISO-8859-6)
2	Latin 2 (ISO-8859-2)	7	Latin 7 (ISO-8859-7)
3	Latin 3 (ISO-8859-3)	8	Latin 8 (ISO-8859-8)
4	Latin 4 (ISO-8859-4)	9	Latin 9 (ISO-8859-9)

The default character set, when no USERNAME_CHARSET option is specified, is Latin 1 and corresponds to USERNAME_CHARSET=1.

3.5 MessageStore Specific Options

The following options are specific to the MessageStore and are specified in the MesageStore option file.

DEFAULT_ACL (Access Control List)

This option sets the default Access Control List ACL used when creating top-level, public folders. An ACL is a list of pairs, each pair containing an identifier and a set of rights represented as single letters. The identifier can be anyone to represent all users, group:groupname to represent all users in a management group, or a user name to represent just that user. The rights are shown in Table 3-1.

Table 3-1 MessageStore ACL Rights

Letter	Rights	Usage
a	Administrative	Permits ACLs to be changed
c	Create	Permit the creation of sub-folders
d	Delete	Permit the deletion of messages and folders
i	Insert	Permit messages to be directly appended to a folder
l	Lookup	Permit the folder to be seen in listings
p	Post	Permit sending e-mail messages to the folder (currently only implemented for anyone)
r	Read	Permit reading of messages in the folder
s	Seen	Permit saving seen information between sessions
w	Write	Permit shared IMAP flags to be set

The default setting is

DEFAULT_ACL=anyone lrs

The value

DEFAULT_ACL=anyone lrsp

will simplify administration as it allows messages to be delivered directly to all newly created top-level, public folders. You can also want to use a value like

DEFAULT_ACL=anyone lrsp manager lrspicdwa

to allow the user manager to manage all folders. See RFC 2086 for technical details about IMAP access control lists.

FILE_DEBUG (bit encoded integer value)

A value of -1 sets full debugging on the low-level file operations used by the MessageStore. The debugging output goes to the server thread log file with the IMAP, POP and HTTP servers, to the channel log file for the msgstore channel, and to the display with the command-line management utility.

POST_USER (string)

This option sets the reserved account name which will be used for delivery to public folders. By default, mail addressed to

post+folder@host

will be delivered to the public folder named folder if the ACL on the folder has the p right for the anyone identifier.