PMDF System Manager's Guide

PMDF mailbox filters implement the SIEVE RFC (3028), plus the vacation draft (DRAFT-SHOWALTER-SIEVE-VACATION-04.TXT), and a couple of other extensions.

RFC 3028 and the vacation draft are available in the PMDF RFC directory, if you chose to install them. The PMDF RFC directory is PMDF_ROOT:[DOC.RFC] on VMS, /pmdf/doc/rfc on UNIX, and C:\pmdf\doc\rfc on NT.

16.2.7.1 Standard SIEVE Commands

The SIEVE commands are standardized in RFC 3028. This section gives a summary of the SIEVE commands, including any related PMDF-specific information. Refer to RFC 3028 for more information about the SIEVE commands.

Note that for list types, such as the list of strings to search for in a header, there is a limit on the number of entries that can be in a single list. This limit is specified by the MAX_LIST_SIZE option (see Section 7.3.3).

16.2.7.1.1 Comments

PMDF supports the two comment delimiters defined in RFC 3028.

The first kind are hash comments, these begin with the hash sign (#). These comments usually start at the beginning of the line. They always cause the rest of the line to be considered a comment.

The second kind are bracketed comments. They begin with the two-character string "/*" and end with the two-character string "*/".

16.2.7.1.2 Control structures

if <test1: test> <block1: block>
elsif <test2: test> <block2: block> else <block3: block>

Standard 'if' control structure similar to other languages.

require <capabilities: string-list>

Some commands in the filter file are optional or are extensions to RFC 3028. If any of these are used, they must be specified in a require command at the beginning of the file. The capabilities that PMDF supports are: envelope, fileinto, reject, vacation.

stop

Ends all processing of the filter file.

ADDRESS-PART: ":localpart" / ":domain" / ":all"

ADDRESS-PART is used in comparisons against addresses to indicate which parts of the address to look at. :localpart refers to the left side of the @, :domain refers to the right side of the @, and :all refers to the entire address. The default is :all.

COMPARATOR: ":comparator" <comparator-name: string>

COMPARATOR indicates what kind of character comparison to do. The possible values for comparator-name are: i;octet for case-sensitive matching, and i;ascii-casemap for case-insensitive matching. The default is i;ascii-casemap.

MATCH-TYPE: ":is" / ":contains" / ":matches"

MATCH-TYPE indicates what kind of comparison to do for tests that compare one string to another. The :is match-type requires an exact string match. The :contains match-type requires a substring match. The :matches match-type is for wildcard matching. Using :matches enables the wildcard characters "*" (0 or more characters) and "?" (single character). The default is :is.

address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE] <header-names: string-list> <key-list: string-list>

The address test returns true if any header in the header-names list contains any key in the key-list in the specified part of the address, doing the comparison as indicated by the comparator and match keywords. Similar to the header test, but only applies to headers with addresses as values.

allof <tests: test-list>

The allof test performs a logical AND on the tests supplied to it.

anyof <tests: test-list>

The anyof test performs a logical OR on the tests supplied to it.

envelope [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE] <envelope-part: string-list> <key-list: string-list>

The envelope test returns true if any of the envelope headers in the envelope-part list contains any key in the key-list in the specified part of the address, doing the comparison as indicated by the comparator and match keywords. The possible values for envelope-part are "to" and "from".

exists <header-names: string-list>

The exists test returns true if all of the headers in the header-names list exist within the message.

false

The false test always evaluates to false.

header [COMPARATOR] [MATCH-TYPE] <header-names: string-list> <key-list: string-list>

The header test returns true if any header in the header-names list contains any key in the key-list, doing the comparison as indicated by the comparator and match keywords.

not <test>

Evaluates the specified test, and reverses the result.

size <":over" / ":under"> <limit: number>

The size test compares the size of the message to the specified limit. If :over is specified, it returns true if the size is larger than the limit. If :under is specified, it returns true if the size is smaller than the limit. It never returns true if the size is equal to the limit.

true

The true test always evaluates to true.

discard

Throws the message away. If the FILTER_DISCARD option (see Section 7.3.3) is set to 2 or 3, the message is placed on the filter_discard channel, othewise it is immediately deleted by the bitbucket channel.

fileinto <folder: string>

Supported for MessageStore only. Delivers the message to the specified folder instead of the INBOX. The maximum number of fileinto commands allowed is specified by the MAX_FILEINTOS option (see Section 7.3.3). The fileinto channel keyword must be specified on the channel (see Section 16.2.1.2).

keep

This is the default action. Delivers the message to the INBOX.

redirect <address-list: string-list>

Forwards the message to all of the addresses listed in address-list. Put each address in double quotes and separate them with commas. The maximum number of redirect commands allowed is specified by the MAX_FORWARDS option (see Section 7.3.3).

The addresses in address-list may contain any of the substitution strings listed in Table 16-2.

reject <reason: string>

Rejects the message and sends a rejection notice back to the sender containing the reason for the rejection.

The SIEVE vacation command is described in DRAFT-SHOWALTER-SIEVE-VACATION-04.TXT and summarized here.

The syntax for the vacation command is:

require "vacation"; vacation [":days" number] [":addresses" string-list] [":subject" string] [":mime"] <reason: string>;

The optional :days parameter is used to specify the period in which addresses are kept and are not responded to. The valid range is 1 to 30 days. The default is 7.

Only messages that are addressed directly to the user are responded to with a vacation notice. The optional :addresses parameter is used to allow the user to specify other addresses that PMDF should consider to belong to the user.

The optional :subject parameter is used to specify the subject of the vacation notice message. If it is not specified, the subject is Re: followed by the original message's subject.

The optional :mime parameter is for advanced users only. It tells PMDF that the reason argument text is formatted as a valid MIME part, including the MIME headers.

The reason argument is the text of the vacation notice. Formatting using multiple lines, blank lines, and tab characters is supported.

The vacation command is only supported in users' personal filter files. For more information on vacation notices, see Section 16.2.8.

16.2.7.3 PMDF SIEVE Extensions

PMDF also implements the following commands, which are not standard. They are listed here using the format used in RFC 3028, and using keywords (such as COMPARATOR) defined in RFC 3028.

body [:contains] [COMPARATOR] <key-list: string-list>

The body test searches the body of the message for strings in key-list. The body test is case-insensitive by default. COMPARATOR can be specified to make it case-sensitive.

debug <message: string>

The debug command prints out the message in the currently active debug log file.

hold

The hold command causes PMDF to hold the message as a .HELD file. The hold command is allowed in the system filter file and channel level filters only.

The following is a simple example of a filter file:

require ["fileinto","vacation"]; if body :contains "free stuff" { discard; } elsif address :localpart "to" "info-pmdf" { fileinto "info-pmdf"; } else { vacation :days 5 :subject "I'm on vacation" "see you next week"; }

16.2.8 Vacation Notices

Users can establish a vacation notice using the vacation SIEVE command (see Section 16.2.7.2) or using the web-based interface (see Section 16.2.6). A vacation notice sends an automatic reply to mail messages received by the user. See the appropriate edition of the PMDF User's Guide for more information.

Note that the vacation SIEVE command is only supported for users' personal mailbox filters. If it appears in a channel filter or system filter file, it will not cause a syntax error, but no vacation notices will be sent out.

Vacation notices are always sent to the envelope From: address. Vacation notices are never sent to mailing lists or other addresses which are most likely from automated mailers (see vacation exceptions option file, Section 16.2.8.1).

The vacation notice itself is formatted as a multipart/report message, where the report type is delivery-status. The text of the notice (the reason argument to the vacation command) is included in the first part of the multipart message.

PMDF keeps track of all of the addresses which have been responded to, per vacation message, in the vacation notice history file. This file is in the same directory as the mailbox filter file. Its name is the name of the filter file with -vnhf appended to it. This is a text file, but it should not be edited by users or system managers.

As required by the SIEVE vacation command draft document (DRAFT-SHOWALTER-SIEVE-VACATION-04.TXT), PMDF has a list of addresses that vacation notices are not sent to (because they are most likely from automated mailers). PMDF also has a list of headers that indicate a mailing list, since vacation notices must not be sent to mailing lists. These lists of addresses and headers are specified in the vacation exceptions option file, vacation_exceptions.opt, located in the PMDF table directory. PMDF supplies a default list during installation. System managers may edit this file to add new headers and addresses, or remove ones already there. Note that this file is replaced upon installation (except on VMS), so any changes must be saved by the system manager so they are not lost.

The vacation exceptions file contains a list of headers and optional values. Note that only headers recognized by PMDF are supported in the file; all others are ignored. Any of the header lines described in this manual may be specified, plus any of the header lines standardized in RFC 822, RFC 987, RFC 1049, RFC 1421, RFC 1422, RFC 1423, RFC 1424, RFC 2156, and RFC 2045.

When PMDF is about to send a vacation notice in response to a mail message, it searches the mail message first for each header in the file. If any of the headers is present with the specified value, the vacation notice is not sent.

A header can be included with no value (make sure to include the colon ":" after the header name), indicating that the header's presence alone is sufficient to suppress the vacation notice. Wildcards are supported in the value part ("*" and "?"), but not in the header name. Use the backslash character ("\") to quote the wildcards.

16.2.9 Checking Your Changes

The syntax of filter files can be partially verified using the following command:

# pmdf test -rewrite -filter mailbox (UNIX and NT)

or

$ pmdf test/rewrite/filter mailbox (VMS)

This command only checks some elements of the filter file. The best way to check a filter file is to send mail through it.

Note that the web-based interface always generates syntactically valid filter files.