PMDF System Manager's Guide

The named-parameters appearing in

alias: <file-spec, named-parameters, error-return-address, \ reply-to-address, errors-to-address, \ warnings-to-address, comments

are used to specify optional modifiers to the list expansion process. There can be zero or more named parameters, separated by commas, and they must appear before any positional parameters (e.g., error-return-address, reply-to-address, etc.). The general syntax of a named parameter is:

[name] value

Here name is the name of the parameter and value is its corresponding value. The square brackets are a mandatory part of the syntax: they do not indicate an optional field.

See Table 4-1 for a description of controls on the effect of named parameters relating to the addition of headers, such as specifying whether a header is to be added only if not originally present, or added unconditionally, and whether the header supplements or substitutes for an originally present header.

The available named parameters are:

AUTH_CHANNEL

CANT_CHANNEL

AUTH_CHANNEL is used to specify a source channel that can submit messages to the mailing list. CANT_CHANNEL is used to specify a source channel that can not submit messages to the mailing list. The argument should be a (possibly wildcarded) channel name. AUTH_CHANNEL also accepts a space-separated list of channel names.

AUTH_LIST

CANT_LIST

USERNAME_AUTH_LIST

USERNAME_CANT_LIST

AUTH_LIST is used to specify a list of addresses that are allowed to post to the mailing list. The value item must be either the full file path specification for a world readable file containing the list of addresses allowed to post to the list, or an LDAP URL that returns the list of addresses allowed to post to the list. PMDF will match the envelope From: address against the addresses in the list; if no match occurs, the attempted posting fails and an error is returned to the would be postings originator. USERNAME_AUTH_LIST is analogous to AUTH_LIST, but for (possibly wildcarded) usernames rather than addresses; note that usernames are generally only useful for messages submitted from the L channel or submitted with SASL authentication via SMTP (SMTP AUTH) since for messages submitted from other sources the username will simply be that of the account under which the submitting PMDF process is running. Note that for messages submitted via SMTP with authentication (SMTP AUTH), the username that authenticated will be prefixed with the asterisk, *, character. For instance, to specify that only the user JDOE can submit to a list, whether submitting from the L channel or via SMTP (e.g., from a POP or IMAP client that performs SASL SMTP authentication), the USERNAME_AUTH_LIST file would need to contain the entries:

JDOE $*JDOE

where the first entry would match for messages submitted from the L channel and the second entry would match for messages submitted via SMTP AUTH. Note that as asterisk is normally a wildcard character, matching of only the exact literal asterisk character is specified by using the dollar character to quote the asterisk.

CANT_LIST has the opposite effect as AUTH_LIST: it supplies the full file path specification of a world readable file containing a list of addresses, or an LDAP URL returning a list of addresses, specifying which addresses can not post to the list. USERNAME_CANT_LIST is analogous to CANT_LIST, but for (possibly wildcarded) usernames rather than addresses; note that usernames are generally only useful for messages submitted from the L channel or submitted with SASL authentication via SMTP (SMTP AUTH) since for messages submitted from other sources the username will simply be that of the account under which the submitting PMDF process is running.

One common use of this facility is to restrict a list so that only list members can post. This can be done by specifying the same file as both the list file and the AUTH_LIST file. For example, assuming that the list is named test-list and the list file is PMDF_TABLE:test-list.dis, the alias file entry would be:

test-list: <pmdf_table:test-list.dis, \ [auth_list] pmdf_table:test-list.dis

AUTH_MAPPING

CANT_MAPPING

AUTH_MAPPING and CANT_MAPPING are similar to AUTH_LIST and CANT_LIST except that they use mappings rather than explicit files of addresses. The value item associated with these named parameters is the name of a mapping table to use. By default, the mapping is given the envelope From: address as input. The transport and application connection information can be added to the input by specifying the INCLUDE_CONNECTIONINFO option in the PMDF option file.

If AUTH_MAPPING is used at least one mapping entry must match or the posting is rejected. If an entry does match the resulting string is checked; if it begins with an F, f, N, or n the posting is rejected. The mailing list will expand normally if the resulting string begins with any other character.

If CANT_MAPPING is used, the posting is accepted if no entry matches. If an entry does match the resulting string is checked; if it begins with a T, t, Y, or y the posting is accepted. The posting is rejected if the resulting string begins with any other character.

The most common use of AUTH_MAPPING is to restrict postings to all users of a given (usually local) host. For example, if the local host name is ymir.claremont.edu, the following mailing list definition could be used for the gripes-list:

gripes: <pmdf_table:gripes-list.dis, [auth_mapping] x-gripes

The corresponding mapping file entries would be:

X-GRIPES *@ymir.claremont.edu Y

Using a mapping table name beginning X- is recommended, so that this private mapping table name will not collide with a standard Process Software mapping table name.

AUTH_USERNAME

CANT_USERNAME

AUTH_USERNAME is used to specify a username or wildcarded username pattern for an account or accounts allowed to post to the list. Note that this is generally only useful for senders submitting from the L channel or via SMTP SASL; for messages submitted from other sources, the messages are considered to be submitted under the username of the PMDF process that received and enqueued the message, e.g., the account under which the PMDF SMTP server is running. Attempted postings from any other sender will be rejected.

CANT_USERNAME can be used to specify a username or wildcarded username pattern for an account or accounts whose postings should be rejected.

Note that for messages submitted via SMTP with authentication (SMTP AUTH), the username that authenticated will be prefixed with the asterisk, *, character. Also note that the asterisk character is normally a wildcard, and must be quoted with the dollar character in order to be interpreted as a literal asterisk character. For instance, to specify that the only sender who can post to a list is user JDOE who will be submitted solely via SMTP with SMTP AUTH, you would use:

[AUTH_USERNAME] $*JDOE

Without the dollar sign, specifying just *JDOE would allow postings not only from user JDOE but also from any users AJDOE, BOBJDOE, etc.

For specifying more than one username (or wildcarded username pattern), see the USERNAME_AUTH_LIST and USERNAME_CANT_LIST parameters described below.

BLOCKLIMIT

LINELIMIT

The BLOCKLIMIT and LINELIMIT parameters can be used to limit the size of messages that can be posted to the list. The value item must be an integer number of blocks for [BLOCKLIMIT], or an integer number of lines for [LINELIMIT]. The number of bytes in a block is specified via the BLOCK_SIZE PMDF option; see Section 7.3.5. The default value is 0, meaning that no limit is imposed on the size of message that can be posted to the list (apart, that is, from any channel or system wide limits).

CONVERSION_TAG

The CONVERSION_TAG named parameter can be used to set a tag which conversion file entries can match upon. The value item should be the string to use as the tag. For instance, if a list is defined

listname: </pmdf/table/listname.dis, [CONVERSION_TAG] listtag

then conversion file entries could include a tag=listtag; clause to match. For instance, if for some mailing list it was desired to convert any text/html parts in posted messages to text/plain, and if a site had an HTML to TEXT convertor called htmltotextconvert and had set up the conversion channel and a CONVERSIONS mapping table to apply to list postings, then a conversion file entry could be

in-chan=*; out-chan=*; in-type=text; in-subtype=html; tag=listtag; out-type=text; out-subtype=plain; parameter-copy-0=*; command="htmltotextconvert 'INPUT_FILE' 'OUTPUT_FILE'"

DEFERRED

The DEFERRED named parameter can be used to add a Deferred-delivery: header line. The value should be a date and time, in ISO 8601 P format. Note that by default PMDF does not honor Deferred-delivery: headers; see Section 2.3.4.19 for a discussion. ISO 8601 P format is, e.g.,

PyearYmonthMweekWdayDThourHminuteMsecondS

where the values year, month, etc., are integer values specifying an offset (delta) from the current time. The initial P is required; other fields can be omitted, though the T is required if any time values are specified.

DELAY_NOTIFICATIONS

NODELAY_NOTIFICATIONS

The DELAY_NOTIFICATIONS named parameter requests that NOTARY delay notifications be sent for mailing list postings; the NODELAY_NOTIFICATIONS named parameter requests that NOTARY delay notifications not be sent for mailing list postings. The value specification is currently ignored and should always be NONE.

ENVELOPE_FROM

This parameter takes a required value specifying an address to replace the message's original envelope From: address. This sets only the envelope From: address, unlike the error-return-address positional parameter which also sets an Errors-to: address.

EXPIRY

The EXPIRY named parameter is used to add an Expiry-Date: header line. The value should be a date and time, in ISO 8601 P format (as described for the DEFERRED parameter above). The PMDF periodic return job will return messages whose Expiry-Date: has passed.

EXPANDABLE

NONEXPANDABLE

The EXPANDABLE named parameter is used to specify that the associated list can be expanded (and hence its contents seen) by various protocols which can attempt such an operation. It does not mean, or imply, that the contents of the list will be expanded into message headers. The value specification is currently ignored and should always be NONE. The NONEXPANDABLE named parameter specifies that the associated list can not be expanded. Again, the value specified is currently ignored and should always be NONE. EXPANDABLE is the default. NONEXPANDABLE is useful in blocking the expansion of mailing lists via SMTP's EXPN command.

FILTER

The FILTER parameter can be used to specify a filter file to apply on attempted message postings. The argument must be a URL specifying the path to the filter file to apply.

HEADER_ADDITION

HEADER_ADDITION can be used to specify a file of headers to be added to posted messages. The argument must be a full file specification for the file containing headers to be added. In particular this facility can be used to add the standard mailing list headers defined in RFC 2369. For instance, a site domain.com that has set up a list named listname, using the MAILSERV channel to manage subscription and unsubscription requests, and with certain list information and archives available at an FTP site, might use a header addition file along the lines of the following:

List-Help: <ftp://ftp.domain.com/pub/listname-help.txt> (FTP), <mailto:mailserv@domain.com?body=send%20/pub/listname-help.txt>, <mailto:mailserv@domain.com?body=help> (MAILSERV Instructions), <mailto:listname-owner@domain.com?subject=help> (List Manager) List-Subscribe: <mailto:mailserv@domain.com?body=subscribe%20listname> List-Unsubscribe: <mailto:mailserv@domain.com?body=unsubscribe%20listname> List-Post: <mailto:listname@domain.com> List-Owner: <mailto:listname-owner@domain.com?Subject=listname> List-Archive: <ftp://ftp.domain.com/pub/listname/archive/>, <mailto:mailserv@domain.com?body=send%20/pub/listname/archive/*>

HEADER_ALIAS

HEADER_EXPANSION

The HEADER_ALIAS named parameter forces the use of the original alias in any original headers constructed using this alias. HEADER_EXPANSION forces the alias to expand into its component addresses in any constructed header lines. The value specification is currently ignored and should always be NONE. These named parameters correspond to the expand and no-expand options for entries in personal alias databases. HEADER_ALIAS is the default for entries in the system alias file and database. Note that these parameters are only valid when headers are originally being constructed, as for instance for messages submitted via the L channel. These parameters are not relevant for incoming messages (such as incoming SMTP messages) for which the headers are already present in one form or another.

HOLD_LIST

NOHOLD_LIST

HOLD_MAPPING

NOHOLD_MAPPING

The HOLD_LIST named parameter can be used to specify a list of originator addresses whose attempts to post to the list should be sidelined as .HELD messages. The NOHOLD_LIST named parameter can be used to specify the list of originator addresses whose postings should not be so sidelined, while all other postings will be sidelined. The value must be a full file specification for a file of addresses, or an LDAP URL returning a list of addresses. The HOLD_MAPPING and NOHOLD_MAPPING named parameters are used analogously, but via mapping tables rather than via lists. The value should be the name of a PMDF mapping table. By default, the mapping tables are given the envelope From: address as input. The transport and application connection information can be added to the input by specifying the INCLUDE_CONNECTIONINFO option in the PMDF option file.

IMPORTANCE

PRECEDENCE

PRIORITY

SENSITIVITY

The IMPORTANCE, PRECEDENCE, PRIORITY, and SENSITIVITY named parameters are used to generate respective headers; the value specification is inserted on the respective header line.

KEEP_DELIVERY

KEEP_READ

By default, PMDF strips delivery receipt and read receipt requests from messages posted to mailing lists. The KEEP_DELIVERY and KEEP_READ named parameters can be used to override this behavior, causing PMDF to retain any delivery receipt or read receipt requests, respectively, on messages posted to the list. The value specification is currently ignored and should always be NONE. Note that passing receipt requests through to mailing lists is quite dangerous; the default behavior of stripping such requests is strongly recommended.

MODERATOR_ADDRESS

MODERATOR_LIST

MODERATOR_MAPPING

USERNAME_MODERATOR_LIST

The MODERATOR_ named parameters are used to establish a moderated mailing list. All postings to the list not originating from a moderator are sent to the list's moderator. The address of the moderator must be specified with the MODERATOR_ADDRESS named parameter. The moderator address determines where moderator mail is sent when someone other than the moderator posts. The value of that named parameter is the moderator's address. For example,

test-list: <d1:[bob]test.dis, \ [MODERATOR_ADDRESS] bob@example.com

When there can be multiple moderator addresses (for instance, both robert@a1.example.com and bob@example.com), use MODERATOR_LIST, USERNAME_MODERATOR_LIST, or MODERATOR_MAPPING to specify all addresses from which postings should be passed directly to the list and not sent to the list's moderator. MODERATOR_LIST specifies either the name of a file containing a list of moderator addresses, or an LDAP URL returning a list of moderator addresses. USERNAME_MODERATOR_LIST specifies either the name of a file containing a list of (possibly wildcarded) moderator usernames, or an LDAP URL returning a list of (possibly wildcarded) moderator usernames; note that usernames are generally only useful for messages submitted from the L channel or submitted with SASL authentication via SMTP (SMTP AUTH) since for messages submitted from other sources the username will simply be that of the account under which the submitting PMDF process is running. Note that for messages submitted via SMTP with authentication (SMTP AUTH), the username that authenticated will be prefixed with the asterisk, *, character. For instance, to specify that only the user JDOE is the list moderator, whether submitting from the L channel or via SMTP (e.g., from a POP or IMAP client that performs SASL SMTP authentication), the USERNAME_MODERATOR_LIST file would need to contain the entries:

JDOE $*JDOE

where the first entry would match for messages submitted from the L channel and the second entry would match for messages submitted via SMTP AUTH. Note that as asterisk is normally a wildcard character, matching of only the exact literal asterisk character is specified by using the dollar character to quote the asterisk.

MODERATOR_MAPPING specifies the name of a mapping table used to verify whether or not an address is a moderator address. By default, the mapping is given the envelope From: address as input. The transport and application connection information can be added to the input by specifying the INCLUDE_CONNECTIONINFO option in the PMDF option file.

If a MODERATOR_LIST or MODERATOR_MAPPING parameter is used, thereby specifying who can post directly to the list, then a MODERATOR_ADDRESS parameter should also be present to specify the address to which to send postings not from any moderator.

The use of the MODERATOR_ADDRESS parameter alone, without the MODERATOR_LIST parameter, is equivalent to using MODERATOR_ADDRESS and a MODERATOR_LIST consisting of just the one moderator address.

ORIGINATOR_REPLY

NOORIGINATOR_REPLY

ORIGINATOR_REPLY is used to control whether or not the originator's address is added to any generated Reply-to: header. The value item should be the full file path specification for a world readable file containing the list of addresses that should never be added. (This is usually the mailing list itself.) PMDF will match the envelope From: address against the addresses in the list; if no match occurs, the originator's address will be added to any generated Reply-to: header.

NOORIGINATOR_REPLY specifies that any generated Reply-to: header should contain only explicitly specified addresses. The value item is ignored. NOORIGINATOR_REPLY is the default.

PUBLIC

PRIVATE

The PUBLIC named parameter specifies that the associated alias is public and hence can appear in any constructed header lines. The value specification is currently ignored and should always be NONE. The PRIVATE named parameter specifies that the alias is private and should appear as an empty group construct in message headers. The value specification is optional and if specified is used as the name for the group. Neither PUBLIC nor PRIVATE have any effect if the HEADER_EXPANSION named parameter is also specified. These named parameters correspond to the public and private options for entries in personal alias databases. PUBLIC is the default for entries in the system alias file and database.

Note that these parameters are only valid when headers are originally being constructed, as for instance for messages submitted via the L channel. These parameters are not relevant for incoming messages (such as incoming SMTP messages) for which the headers are already present in one form or another.

RECEIVEDFOR

NORECEIVEDFOR

RECEIVEDFROM

NORECEIVEDFROM

These named parameters control features of what appears in the Received: header constructed when expanding the alias, and override normal channel receivedfor, noreceivedfor, receivedfrom, or noreceivedfrom keyword settings; see Section 2.3.4.62 for a discussion of the channel keywords. The value specification is currently ignored and should always be NONE.

REPROCESS

The REPROCESS named parameter is used to request deferred expansion of the mailing list, where rather than expanding the mailing list "on line", the message should instead be enqueued to the reprocess channel; the reprocess channel can then performing the mailing list processing in a separate step. The value specification is currently ignored and should always be reprocess.

Use of this parameter defers much of the processing overhead of handling the message to the later step when the reprocess channel runs, rather than doing the processing as the message is initially accepted. This deferred processing can be especially helpful in cases such as incoming SMTP messages addressed to large mailing lists, where "on line" delays could lead to connection time outs.

Use of this parameter as in:

listname: </pmdf/table/listname.dis, [REPROCESS] reprocess

thus provides essentially identical functionality as defining a mailing list in two stages through the reprocess channel to obtain deferred expansion (the mailing list addresses aren't even expanded until the reprocess channel runs) such as:

listname: listname-expand@reprocess listname-expand: </pmdf/table/listname.dis

SEQUENCE_PREFIX

SEQUENCE_SUFFIX

SEQUENCE_STRIP

The SEQUENCE_PREFIX and SEQUENCE_SUFFIX named parameters request that a sequence number be prepended or appended to the Subject: lines of messages posted to the list. The value item gives the full file path specification of a sequence number file. This file is read, incremented, and updated each time a message is posted to the list. The number read from the file is prepended, in the case of SEQUENCE_PREFIX, or appended, in the case of SEQUENCE_SUFFIX, to the message's Subject: header line. This mechanism provides a way of uniquely sequencing each message posted to a list so that recipients can more easily track postings and determine whether or not they have missed any.

By default, a response to a previously posted message (with a previous sequence number) retains the previous sequence number as well as adding a new sequence number to the subject line; the build up of sequence numbers shows the entire "thread" of the message in question. However, the SEQUENCE_STRIP named parameter can be used to request that only the highest numbered, i.e., most recent, sequence number be retained on the subject line. The value item is currently ignored and should always be NONE.

Important note To ensure that sequence numbers are only incremented for successful postings, a SEQUENCE_PREFIX or SEQUENCE_SUFFIX named parameter should always appear as the last named parameter; that is, if other named parameters are also being used, the SEQUENCE_* named parameter should appear at the end of the list of named parameters.

Sequence number files are binary files and must have the proper file attributes and access permissions in order to function correctly. PMDF will create an appropriate initial sequence number file automatically if sequence numbers are requested for a mailing list created via an alias in the PMDF_ALIAS_FILE or PMDF_ALIAS_DATABASE.² This initial sequence number file will be empty (but have the right file attributes and access permissions); the first sequence number based on this file will be "[1]".

TAG

The TAG named parameter can be used to prefix specified text to the Subject: header of posted messages. The value item should be the string to be added. (Note that multiple tags may be specified, separated by a vertical bar.) For instance,

schedule-list: <d1:[adam]schedule-list.dis, [TAG] Schedule posting -- , \ [AUTH_LIST] d1:[adam]schedule-list.dis

will cause any postings to the list schedule-list to have a Subject: header that begins "Schedule posting --" followed by whatever the original subject of the posting might have been.

USERNAME

The USERNAME named parameter can be used to set the username that PMDF will consider to "own" these mailing list messages. The pmdf qm utility will allow that username to inspect and bounce messages in the queue resulting from expansion of this mailing list. The value item should be the username of the account to "own" the mailing list postings. On OpenVMS, note that the username specified will be forced to uppercase.

4.1.1.1 Specifying Multiple Access Control Parameters

Note also that the [AUTH_LIST], [AUTH_MAPPING], [CANT_LIST], and [CANT_MAPPING] parameters provide a separate sort of control from [MODERATOR_LIST] and [MODERATOR_MAPPING]; they do different things and can be used effectively in conjunction. The [AUTH_*] and [CANT_*] parameters control who can post at all; only addresses that make it through those access filters then get checked for the next question, the [MODERATOR_*] access filter, of whether the sender can post directly vs. whether their attempted posting is referred to [MODERATOR_ADDRESS].