Complete Contents
Chapter 1 Getting Started With Netscape Messaging Server
Chapter 2 Configuring IMAP and POP Services
Chapter 3 Configuring SMTP Services
Chapter 4 Managing Mail Users and Mailing Lists
Chapter 5 Managing the Message Store
Chapter 6 Security and Access Control
Chapter 7 Working With SMTP Plugins
Chapter 8 Filtering Unsolicited Bulk Email
Chapter 9 Message Routing
Chapter 10 Monitoring and Maintaining Your Server
Chapter 11 Logging and Log Analysis
Appendix A Command Line Utilities
Appendix B Program Delivery
Appendix C sendmail Migration and Compatibility
Appendix D SNMP MIB
Glossary
Messaging Server Administrator's Guide: Filtering Unsolicited Bulk Email
Previous Next Contents Index Bookshelf


Chapter 8 Filtering Unsolicited Bulk Email

This chapter describes the unsolicited bulk email (UBE) plug-in and the filters it uses to help you screen out unsolicited email. For information on Messaging Server plug-ins in general, see Chapter 7, Working With SMTP Plug-Ins.

This chapter contains the following sections:


About the UBE Plug-In
The UBE plug-in is an SMTP plug-in that works as an extension to Netscape Messaging Server. You can use it to design and implement filters that can block unsolicited bulk email from reaching your users.

 What Is UBE?

Unsolicited bulk mail is email sent to large numbers of recipients without their knowledge or consent, often advertising commercial products or services. It is the electronic equivalent of paper junk mail. For a full definition, see the Web-based document Unsolicited Bulk Email: Definitions and Problems.

Users of email services are sometimes inundated with unsolicited bulk mail and may expect their service providers to address the problem. One approach that providers can follow is to use filters that selectively eliminate email whose characteristics mark it as UBE. Netscape Messaging Server provides both a plug-in architecture and a scriptable plug-in module that can be used to cut down on (though probably never completely eliminate) UBE.

 UBE Filters and the UBE Plug-In

The UBE plug-in is an SMTP plug-in to Netscape Messaging Server. SMTP plug-ins are dynamically loaded software modules that access the Messaging Server Plug-in API, an application programming interface. The plug-ins function by intercepting incoming and outgoing messages, analyzing them for certain characteristics, and taking appropriate action before possibly passing them on. SMTP Plug-ins are described in general in Chapter 7, Working With SMTP Plug-Ins.

The UBE plug-in is provided as part of Messaging Server 4.0. It is a customizable plug-in that works by examining all incoming mail before it is routed throughout the system (to users' mailboxes or to other email servers). The UBE plug-in uses a set of rules (called filters), contained in a configuration file, to decide how to handle each piece of mail. Any mail not affected by any of the filters continues on its normal course, untouched by the plug-in.

 The UBE plug-in supports a simple scripting language that is useful for processing and directing the flow of messages. You use the language to create the filters that intercept and block or otherwise handle UBE messages. You can use the Netscape Console interface to create and edit filters, or you can perform those tasks manually by editing the UBE configuration file directly.

 How UBE Filters Work

A UBE filter is a line in a text file (default name = UBEfilter.cfg). When you create a filter, you define a criterion to which email messages are compared. Whenever an email message meets the criterion defined in the filter definition, the filter triggers the action that you designated in the filter definition.

For example, if you don't want to get any messages from uglymail.com, you can create a UBE filter that identifies any email message from uglymail.com. You can then designate REJECT as the action to be performed by the UBE plug-in.

 In using the UBE plug-in, you can create many different types of UBE filters and activate or deactivate them individually. You can manipulate your set of UBE filters through the Netscape Console interface, or through direct editing of the configuration file in which they are stored. This chapter describes both methods.
UBE Filter Format
A UBE filter is a single text line containing 3 to 5 parts, in this order:

 
[:label] messageField matchCriterion action [argument]
Here is an example filter that includes all five parts: 

:DontSend Subject "Bad mail" REJECT "Do not send mail"
The following subsections use this example to describe, in order, the parts that make up a filter.

 Label

The label is an identifying name for the filter. This part is optional and is used only if this filter is the destination of another filter's JUMP action. (See Table 8.1 for a description of the JUMP action.)

The label is always preceded by a colon (:).

 Example: :DontSend

 Message Field

The message field is the portion of the message header or envelope that the filter analyzes. Each arriving message has header fields that hold information about that message. The filter can use any of the fields in deciding how to handle the mail. There is no complete list of possible header fields since the format is open (see Internet Draft RFC 822 for a list of the defined standard fields), but common fields include To, From, Sender, Reply-To, Content-type, and so on. See Table 8.3 for descriptions of some of the most common fields.

Example: Subject

 After the message field name you can place a colon (:) followed by special tags that affect how the message field is processed. Currently, two special tags are supported: case and envonly.

 case Tag

The case tag causes the matching criterion (which follows the message field in the filter) to be treated as case sensitive. By default, filters are not case sensitive. Here's an example of two filters, identical except for the case tag:

Subject:case "Bad mail" REJECT "Do not send mail"
Subject "Bad mail" REJECT "Do not send mail"
The first filter would intercept only those messages whose subject is Bad mail; the second filter would intercept messages whose subject is either Bad mail or bad mail (or even bAd mAiL).

envonly Tag

The envonly tag instructs the filter to consider only envelope information, rather than all message-header information, for the message field. Because header information is more easily altered by a mail sender than is envelope information, you can use this tag to help resist spoofing attacks based on header information.

For example, Auth-Sender is an envelope field, added by a server sending a message by authenticated SMTP, that identifies the sender of the message.You might design a filter that examines that field to ensure that only authenticated mail gets through. A tricky user could, however, add a phony Auth-Sender field to the header information in a message, possibly defeating your filter. If you restrict the message field to envonly, only those fields that are created by the server, and thus are harder to tamper with, will be considered.

Note: Using the envonly tag makes sense only if your UBE plug-in has been configured to include header fields by default; see Envelope Fields and Header Fields for an explanation.

Match Criterion

The match criterion is the string (or regular expression) that the filter looks for in the contents of the message field to see whether a match is achieved. The combination of message field and match criterion is called the filter's predicate; the state of the predicate (matched or unmatched) determines whether or not the filter is to be applied.

Predicate example: Subject "Bad mail"

 In this example, if the Subject field of the message being analyzed is Bad mail, the filter is applied; otherwise, the filter is not applied. Note that, in the absence of a case tag, the match criterion is not case sensitive.

 The match criterion is a regular expression, so you can use it to match a wide variety of strings. For example, to match any Subject field containing the phrase "Get Rich Quick", you can specify ".*Get Rich Quick.*" as the match criterion. See Regular Expressions for Match Criterion for more information.

Action

The action field defines the action that the UBE plug-in performs if a match occurs. As soon as a match occurs with any filter predicate, the action associated with that filter is taken. Filter processing stops when a terminal action (one that stops processing) is taken, or when the end of the filter file is reached. See Table 8.1 for descriptions of the actions.

Example: REJECT

 This action causes the message to be returned to the sender.

 You can also apply the negation modifier to reverse the conditions under which an action occurs; see Negation Modifier.

Argument

The argument field contains any additional information that may be needed to perform the specified action. Some actions do not take an argument, whereas others do. See Table 8.1 for descriptions of the arguments used by each of the actions.

Example: "Do not send mail"

 In this case, "Do not send mail" is the argument to the REJECT action; it is a message that accompanies the returned mail.

 Available Actions for UBE Filters

Table 8.1 lists the actions that you can specify in a UBE filter. Each action is classified either as terminal (filter processing stops as soon as it is taken) or non-terminal (processing continues after it is taken).

Table 8.1 UBE filter actions

Action
Argument
Description
COPY
Comma-separated list of addresses
Adds these recipients to the original set of recipients, then continues processing the next filter. (Non-terminal action.)

Example:
Channel-To "user1@domain1\.com" COPY "postmaster, user2"

In this case, any mail sent to user1@domain1.com is also sent to postmaster and to user2.

DROP
One address
Replaces original set of recipients with this one and sends the message on. (Terminal action.)


Example:
User-From ".*@bulk\.com" DROP "postmaster"

In this case, any mail from any account at bulk.com is sent to postmaster but no one else.

EXIT
(none)
Immediately stops filter processing and sends the message on. Subsequent filters in the configuration file are not applied to this message. (Terminal action.)


Example:
User-From "CEO@.*" EXIT

In this case, any mail from a user named CEO is sent through.

HOLDCOPY
Comma-separated list of addresses, followed by a vertical bar (|) and a message string
Holds the message. Sends a notification--containing the original message and the message string in the argument--to the recipients listed in the argument. (Terminal action.)


Example:
Subject "Free stuff!" HOLDCOPY "postmaster | please handle"
In this case, any mail containing the subject "Free stuff!" is held, with a copy sent to postmaster.

HOLDONLY
Comma-separated list of addresses, followed by vertical bar (|) and a message string
(Same as HOLDCOPY, except that it does not copy the original message.) Sends a notification containing the message string in the argument--but without including the original message--to the recipients listed in the argument. (Terminal action.)


Example:
Subject "Free stuff!" HOLDCOPY "postmaster | please handle"

In this case, any mail containing the subject "Free stuff!" is held, with a notification sent to postmaster.

JUMP
Label (filter name)
Shifts filter processing to the named filter, skipping any intervening filters. The named filter must exist in the configuration file. (Non-terminal action.)


Example:
Subject "Easy $$$" JUMP "MoneyReject"
subject".*$$$.*" HOLDCOPY "postmaster | evaluate
for $$$"
:MoneyReject Subject "Easy $$$" REJECT
"No commercials, please"

In this case, mail with the specific subject "Easy $$$" is rejected, whereas other mail with triple dollar signs in the subject is held for the postmaster to evaluate.

REJECT
Reject reason (message string)
Returns the mail to the sender and includes the reject reason in the message. (Terminal action.)


Example:
User-from "Pitchman@cheapstuff\.com" REJECT
"Do not advertise to our users"

In this case, any mail from Pitchman@cheapstuff.com is automatically returned along with the message "Do not advertise to our users".

RUN
Command line to execute
Executes the specified program, passing the message header and body to the program. The program must be located in the directory
INSTANCEDIR/smtp-bin/plugins
where INSTANCEDIR is the instance directory (name = msg-instancename). You can use the special field name $& in the subsequent filter to match the return value of the program. (Non-terminal action.)


Example:
Subject "May contain a virus" RUN "VirusScan.exe"
$& "1" REJECT "Message rejected due to presence
of virus!"

In this case, any mail with the subject "May contain a virus" is sent to the program VirusScan.exe for analysis. If the return value from the program is 1, the message is returned along with the message "Message rejected due to presence of virus!".

Regular Expressions for Match Criterion

The UBE filter supports extended regular expressions compliant with POSIX 1003.2. There are many sources of information on regular expressions; this document is not intended as a reference.

Table 8.2 lists some of the common regular-expression special characters and constructions that you can use in creating match criteria for UBE filters.

Table 8.2 Regular-expression special characters

Characters
Usage
.
(Dot). Matches any single character.
[]
(Brackets). Matches any single character from the set of characters specified within the brackets. The brackets may enclose the entire set of permissible characters ([2468]), or they may specify an ASCII range, using end points and a hyphen ([a-z]).

For example, r[eo]d matches red and rod, but not rid or reed.
x[0-9] matches x0, x1, x2, and so on, but not x11.
[^]
(Caret in brackets). Matches any single character that is not one of those specified within the brackets following the caret. (The caret must be the first character in the brackets.)

For example, r[^eo]d matches rid but not red or rod.
x[^0-9] matches xa, xb, xc, and so on, but not x2.
*
(Asterisk). Matches zero or more of the immediately preceding character or expression.

For example, ba*c matches bc, bac, baac, and so on.
The expression .* matches any string.
+
(Plus) Matches one or more of the immediately preceding character or expression.

For example, ba+c matches bac, baac, and so on.
r[eo]+d matches red, rod, reed and rood, but not reod or roed.
\
(Backslash) The Escape character. It removes the pattern-matching significance of the character it precedes, so that special characters (like those in this table) can be matched as regular ASCII characters.

For example, . matches any character, but \. matches only the dot character. (To match the backslash character itself, you must precede it with another backslash: \\.)
\~
(Escaped tilde) Matches any character but the subsequent character.

For example, b\~ad matches bbd, bcd, b3d, but not bad.
\{\}
(Escaped braces) Matches any number of occurrences of the exact sequence of characters between the escaped braces.

For example, \{ju\}+fruit matches jufruit, jujufruit, jujujufruit, and so on. It does not match jfruit, ufruit, or ujfruit. You can use the expression \{ \} to match any number of spaces between words.
\{x\!x\}
(Escaped bang in escaped braces) Matches any one of the characters x separated by the alternation symbol (\!).

For example, \{j\!u\}+fruit matches jfruit, jjfruit, ufruit, ujfruit, uufruit, uuufruit, and so on.
^
(Caret) Matches the beginning of a line.
$
(Dollar sign) Matches the end of a line.
()
(Parentheses) Delimits arguments. You can explicitly limit the extent of a regular expression by enclosing it in parentheses.

For example, uuufruit is a single regular expression, but you can force it to be considered two separate expressions by applying parentheses, as in (uuu)(fruit). For an example of the use of parentheses, see the example filter following Table 8.4.

Many other rules define, for example, what a character is and how characters in regular expressions may be juxtaposed for various purposes. Please consult any POSIX 1003.2-compliant regular-expression documentation for more information.

 Envelope Fields and Header Fields

Every message has two types of fields that you can include in the message-field part of your filters. Header fields are created by a mail client when it sends a message. Envelope fields are created by mail servers that send or resend the message during its transit from sender to receiver. By default, the UBE plug-in examines envelope fields only. This restriction exists for performance reasons, because the header can contain any number of fields.

The envelope fields most useful for filter purposes include those listed in Table 8.3.

Table 8.3 Common envelope fields for UBE filters

Envelope field
Description
Submitted-Date
The date on which the server received the message.
Host-From
The IP address of the machine that directly connected to and transferred the message to this Messaging Server. You can use this field to, for example, separate external mail from mail of local origin.
User-From
The value of the SMTP mail-from command. The value in this field is not validated unless you have enabled the "Verify each recipient's address when accepting messages" setting. (See Verifying Recipient Addresses for instructions.) You can use this field to, for example, ensure that you accept (or perhaps reject) messages only from specific known users.
Auth-Sender
If authenticated SMTP is being used for this message, this field contains the email address of the authenticated user that sent the message. (Note that this field contains the email address of the user, not the user name or password used to authenticate the user.) You can use this field to, for example, accept mail only from authenticated users.
MAIL-Exts
A list of any extensions to SMTP (such as delivery notification) that were passed to the SMTP daemon through the mail-from SMTP command. Extensions are listed exactly as entered in the command.
Channel-To
The list of recipients for this message, as listed in the rcpt-to SMTP command. Each recipient is listed on a separate line, with this format:
<user@xyzcorp.com>
RCPT-Exts
A list of any extensions to SMTP (such as delivery notification) that were passed to the SMTP daemon through the rcpt-to SMTP command. Extensions are listed exactly as entered in the command.
Message-Size
The total size, in bytes, of the header plus body of the received message. You can use the value in this field to, for example, drop messages that are too large.
MTA-Hops
The number of SMTP servers (not including this one) that the received message has passed through. You can use the value in this field to, for example, drop messages that have been relayed through too many machines.

If you want to include header fields as well as envelope fields in your filter predicates, you can use the Netscape Console interface (see Unsolicited Bulk Email Configuration Tab). You can also accomplish this manually, by adding the following line to your filter options file (UBEfilter.opt): 

parseheader: 1
This instruction tells the UBE plug-in to look at both envelope and header fields when comparing a message to a filter.

If you have set the default to include header fields, you can then, on a filter-by-filter basis, force the plug-in to look only at the envelope fields by using the envonly flag in the message field of your filter; see envonly Tag for a description of the flag.

Note: If you are designing your filters to operate on header fields as well as envelope fields, you can use your mail client to help decide which header fields to analyze. With the Netscape Messenger mail client in Netscape Communicator, you can view the complete set of header fields in a received message by choosing All from the Headers menu (accessed from the View menu).

Special Message-Field Names

You can use special field names to combine filters and narrow your criteria. Table 8.4 describes these names, using the following filter as an example:

Subject "This is ."   REJECT "This is bad mail"
(Note that this example includes a dot wildcard, which matches any single character, in the match criterion.)

Table 8.4 Special message-field names for UBE filters

Special name
Explanation
$0
Represents the complete message field content that was last matched. Assume that the message just compared against the above example filter had the subject "This is a test". Then the current value of $0 would be "This is a test".
$1
Represents the exact matching portion of the message field content that was last compared. In the above example, again assuming that the message subject was "This is a test", the value of $1 after the comparison would be "This is a". An example of the use of $1 follows this table.
$2..$9
Represent the values, in order, of any parenthetical matches you may have specified in your match criterion. If, in the above example, your match criterion had been "(This) (is) (a) (test)", and again assuming that the message subject was "This is a test", the comparison would yield the results $2=this, $3=is, $4=a, and $5=test.
$&
Represents the numerical result code of the last action. You can use this special field name in conjunction with the RUN action (see Table 8.1).
$#
Represents the number of recipients in the current message. A comparison of this value and a number is considered true if this value is equal to or greater than the given number. You can use this field name to, for example, block all messages with more than a maximum permitted number of recipients.
$ANY
Represents any field. Using this special name causes the plug-in to compare your match criterion with all fields. For example, you can use it to search all header fields for a specific phrase, as in this predicate:

$ANY "get free stuff"

You can also use it to match all messages, with a predicate such as

$ANY ".*"

which will match any field containing any string.

The following example uses both a special field name and parenthesized expression parsing:

 
:handleFrom   User-From   (.*)@airius.com   !JUMP   handleregular   
              $1          "postmaster"       JUMP   handleAIRIUSpost   
              ""          ""                 JUMP   handleregular
Negation Modifier

You can modify an action by applying the negation operator to it. Normally, the action specified in a filter is taken if the match criterion is matched. If, however, the negation operator is applied to the action, the action is not taken if the criterion is matched; conversely, the action is taken if the criterion is not matched.

For example, the following filter accepts all messages originating from within Airius Corporation:

 
Sender ".*airius\.com" EXIT
A complementary filter might reject all messages that are not local:

 
Sender ".*airius\.com" !REJECT "local mail only"
If you are using the Netscape Console interface to create filters, you click a button to apply the negation modifier; if you are creating filters manually, you apply the modifier as a prefix to the action, as shown in the example.
Managing UBE Filters With Netscape Console
The UBE plug-in is installed automatically when you install Messaging Server 4.0; see Installing Messaging Server 4.0 for more information. This section explains how to use Netscape Console to activate the UBE plugin and to create, edit, activate, and change the order of individual filters.

 Details of filter format and instructions for designing filters using Netscape Console are given in UBE Filter Format. Note that you can also create and manipulate filters manually; see Creating Filters Manually for details.

Activating the UBE Plug-In

To make the UBE plug-in available for use, use Netscape Console to access the SMTP Plugins form (see Activating and Deactivating Plug-Ins). Turn on the UBE plug-in in the Plugin Configuration table. (Its name is libUBEfilter.so or libUBEfilter.sl for Unix; libUBEfilter.dll for Windows NT.)

As with all SMTP plug-ins, basic configuration of the UBE plug-in is controlled by the contents of the configuration file plugins.cfg. Individual filter characteristics and other aspects of UBE plug-in execution are controlled by the files UBEfilter.cfg and UBEfilter.opt. See Plug-In File and Configuration Files for more information.

Creating a New Filter

Follow these steps to create a new UBE filter from Netscape Console:

  1. In Netscape Console, open the Messaging Server whose UBE plug-in you want to add a new filter to.

  2. Follow either of these steps to access the UBE Configuration form:

  3. Click "Add a filter." The "Add a UBE Filter" window opens.

  4. (Optional) Assign a label to the new filter. The label is needed only in certain circumstances; see Label.

  5. Specify a message field to use for matching. Either select a field from the popup menu in the "If" field or enter the field name directly into the "If" field. The field names in the popup menu correspond to the parts of the header or envelope information attached to an email message. See Message Field.

  6. Choose equals (=) or does not equal (!=). If you choose =, the UBE plug-in acts only when a match between a message and this filter occurs. If you choose !=, the plug-in acts only when a match between a message and this filter does not occur. See Negation Modifier.

  7. Type a value (the match criterion) in the Value field. This is the value (generally a string or regular expression) that the UBE plug-in compares with the contents of the message field you specified above. See Match Criterion.

  8. Select an action from the popup menu in the "Then" field. This is the action the UBE plug-in will perform on any email that matches this filter (or does not match, if you chose (!=) in Step 4). See Action.

  9. If required by the action you selected, enter an argument for that action in the Argument field. Some actions require arguments, such as addresses to forward mail to. See Argument.

  10. When you have finished creating the UBE filter, click OK. The new UBE filter appears in the list of UBE filters in the UBE Configuration form.

  11. Back in the UBE Configuration form, click Save to save the new UBE filter.
See Add/Edit UBE Filter Window for a complete description of the contents of the Add UBE Filter window.

IMPORTANT: Newly created filters are not saved until you click Save, even though they may appear in the UBE Configuration form.

Note: New filters are automatically saved as active. If you want to deactivate your new filter, follow the instructions in Activating and Deactivating Filters.

You can also create a new UBE filter by directly editing the filter configuration file. See Creating Filters Manually.

Editing an Existing Filter

Follow these steps to edit an existing UBE filter from Netscape Console:

  1. Access the UBE Configuration form, as described in Creating a New Filter.

  2. In the Filters field, click to highlight the UBE filter that you want to edit.

  3. Click the Edit button. The "Edit a UBE Filter" window opens, displaying the parts of the UBE filter you're editing.

  4. Make any desired changes to the filter, specifying the contents of the fields, as described in Creating a New Filter.

  5. When you have finished editing the filter, click OK. The revised filter appears in the same place it previously occupied in the UBE configuration form.
    6. IMPORTANT: When you edit a UBE filter, the edited filter replaces the original one. You cannot create a new filter by editing an existing filter and, for example, saving it with a new name (label). To create a new filter, see Creating a New Filter.

  6. Back in the UBE Configuration form, click Save to save the edited filter.
See Add/Edit UBE Filter Window for a complete description of the contents of the Edit UBE Filter window.

IMPORTANT: Changes made to filters are not saved until you click Save, even though they may appear changed in the UBE Configuration form.

You can also modify an existing UBE filter by directly editing the filter configuration file. See Creating Filters Manually.

Activating and Deactivating Filters

Active filters are designated with a check in the Active box next to the filter definition in the UBE Configuration form. You can activate or deactivate filters individually, and you can activate or deactivate all filters at once. Follow these steps:

  1. Access the UBE Configuration form, as described in Creating a New Filter.

  2. Do any of the following:

  3. When you have finished activating or deactivating filters, click Save.

    4. IMPORTANT: The changes you make to the active state of filters are not saved until you click Save.

You can also activate and deactivate UBE filters by directly editing the filter configuration file. See Creating Filters Manually.

Changing the Order of Filters

Incoming email messages are compared to UBE filters in the order in which the filters appear in the UBE Configuration form. Depending on how you design your filters, the order in which they are applied to incoming email messages may be important. Follow these steps to change the order of the filters in the UBE Configuration form:

  1. Access the UBE Configuration form, as described in Creating a New Filter.

  2. Click the up or down arrow next to the filter you want to move. If necessary, continue clicking the appropriate arrow until the filter you are moving is in the desired position relative to the other UBE filters in the list.

  3. Repeat step 2 for each filter you want to move.

  4. When you have finished changing the order of your UBE filters, click Save.

    5. IMPORTANT: The changes you make in the order of your UBE filters are not saved until you click Save, even though they may appear reordered in the UBE Configuration form.

You can also reorder UBE filters by directly editing the filter configuration file. See the section Creating Filters Manually.

Parsing Header Fields

You can specify that the UBE plug-in examine header fields as well as envelope fields when applying the filters to a message. (By default, the plug-in looks only at envelope fields.) Follow these steps:

  1. Access the UBE Configuration form, as described in Creating a New Filter.

  2. Check the "Parse message header" box to specify that the UBE plug-in should parse message headers as well as envelopes. See Envelope Fields and Header Fields for more information.
You can also set this option manually. See Plug-In File and Configuration Files for more information.


Creating Filters Manually
If you are designing a lengthy and complex set of UBE filters, it may be more efficient to create and edit them manually, rather than through the Netscape Console interface. This section describes how to create, delete, modify, activate, and deactivate UBE filters without using Netscape Console. To do this, you must understand the configuration files used by the UBE plug-in and how to edit them.

Plug-In File and Configuration Files

The UBE plug-in is an SMTP plug-in that operates at the postSmtpAccept point of message handling. Messaging Server uses the file plugins.cfg to configure the UBE plug-in. A typical UBE configuration in plugins.cfg (for a Windows NT installation) might look like this (see Chapter 7, Working With SMTP Plug-Ins, for more information about plugins.cfg):

PostSmtpAccept i:\Netscape\Server4\msg-Airius1\
   smtp-bin\libUBEfilter.dll
funcs=filter_msg_plugin config=i:\Netscape\
   Server4\msg-Airius1\smtp-bin\plugins\UBEfilter.opt
option=i:\Netscape\Server4\msg-Airius1\smtp-bin\plugins\UBEfilter.opt
These command lines tells the server to

 (A Unix version would be similar, except that the paths would be in Unix format and the command line would specify the shared object libUBEfilter.so.)

Note: If a plug-in is installed but has been deactivated through the Netscape Console interface, its line in the plugins.cfg file is commented out; that is, it starts with a number sign (#) character.

The most important files to note from this plugins.cfg example are the filter configuration file and the filter options file. These two files drive the functioning of the UBE plug-in.

Editing the Filter Configuration File

To create and manipulate UBE filters without using Netscape Console, you need to manipulating several configuration files.

  1. Start by ensuring that the UBE plug-in is activated.
    2. Examine the file plugins.cfg (see previous section) to make sure the proper configuration lines are in place to activate the plug-in.

  2. If necessary, edit the file UBEfilter.opt or its equivalent to specify message-header parsing.

  3. Create your set of UBE filters by editing the file UBEfilter.cfg or its equivalent. You can use any text editor (Notepad for Windows NT or vi for Unix, for example).
    4. Enter your filters in order, one per line, in the configuration file. To enter a comment use the # symbol at the beginning of the line. (See Entering Comments for more information on comments.)

  4. When you are satisfied with your edits, save the file in its proper location as defined in plugins.cfg.

  5. To make changes later, open, edit, and resave the configuration file.
During execution, the UBE plug-in processes your filters, in order, from the top to the bottom of the file (except when it encounters a JUMP action; see Table 8.1) and applies all rules that match, until it reaches a terminal action or the end of the file.

Note: When you change the configuration file, its new filters automatically take effect immediately.

Omitting Parts of a Filter

All parts of each filter line (other than the optional label) must be present, but you can use empty quotes ("") as a place holder, if you wish to. For example, you can replace the action part of a filter if you want filter processing to continue on the next line, rather than taking action immediately:

           Channel-To  (.*)@airius.com  ""      
  :ceo     $1           ceo             COPY    postmaster@airius.com 
  :cfo     $1           cfo             COPY    finance@airius.com
In this case, all mail for Airius Corporation is analyzed by subsequent lines to see whether it should be copied to the postmaster or the finance administrator.

For the message field or match-criterion parts of a filter, empty quotes have the effect of matching everything:

 
 :cfo     $1           cfo           COPY    finance@airius.com    
          ""           ""            JUMP     othermail
In this case, once a message has been analyzed to see whether a copy should go to finance, its processing continues with a jump to another location.

 Entering Comments

Any line that starts with the number sign (#) or tilde (~) (leading spaces or tabs are ignored) is considered a comment and is ignored during execution by the UBE plug-in.

Keep these points in mind when using comment markers:

 Examples

Filter examples are shown throughout this chapter as illustrations of filter format. This section provides additional illustrations, including an example of a complexly interacting set of filters that performs many functions.

Example Configuration File

This sample filter configuration file for the fictional XYZ Corporation illustrates filter usage and the interactions among filters. Following the sample are several scenarios illustrating how the UBE plug-in would use this file to handle several kinds of mail.

        Channel-To   "louisr@xyzcorp\.com" COPY     "watch@domain.com"
        Subject      "weapons for sale"    DROP     "weap@xxx.gov"
        Channel-To   "CEO.*"               JUMP     "DoCEO"
:xCEO   $#           "50"                  REJECT   "No bulk mail"
        Subject      "May contain a virus" RUN      "VirusScan.exe"
        $&           "1"                   REJECT   "This had a virus"
        Content-Type "multipart/mixed"     JUMP     "DoMime"
        Client       "Netscape.*"         !JUMP     "TstCli"
:xCli   Subject      ".*"                  EXIT
:DoCEO  Subject      "Postmaster Eval"     HOLDCOPY "postmaster eval"
        $ANY         ".*"                  JUMP     "xCEO"
:DoMime Channel-To   ".*_.*@xyzcorp\.com"  REJECT   "Can't read MIME "
        $ANY         ".*"                  EXIT
:TstCli Host-From    ".*\.xyzcorp\.com"    COPY     "IS_department"
        $ANY         ".*"                  JUMP     "xCli"
Scenario 1: Message to the CEO for the postmaster to evaluate

 These are the received message's Channel-to and Subject fields:

 
Channel-To: CEO@domain.com
Subject "Postmaster Eval"

  1. This message is matched by the Channel-To "CEO.*" filter (line 3).

  2. Processing therefore jumps to the filter labeled :DoCEO (line 10). The filter on that line again matches the message (because the subject is "Postmaster Eval") and so this message is copied to the postmaster, who can then decide whether or not the CEO should see it.
Scenario 2: Message to the CEO about the shareholders' meeting

 These are the received message's Channel-to and Subject fields:

 
Channel-To: CEO@domain.com
Subject "Shareholders meeting"

  1. As in the previous case, this message is matched by the Channel-To "CEO.*" filter (line 3), so processing then jumps to the filter labeled :DoCEO (line 10).

  2. But this time the filter on line 10 doesn't match the message (the subject is not "Postmaster Eval"), so processing passes to the next line (11).

  3. The filter on line 11 matches the message (because its predicate can match any string in any field), so processing jumps back to the label :xCEO (line 4).

  4. At this point the rest of the filters can be applied to this message. If none of lines 4 through 8 match the message, processing will halt with the EXIT action at line 9, because the Subject fields will match. The mail will then be forwarded to its addressee.
Scenario 3: Message sent to a monitored account:

 The account of Louis R. is being monitored for illegal activity. These are the received message's Channel-to and Subject fields:

 
Channel-To "louisr@xyzcorp.com"
Subject "illegal stock trade"
This message is matched by the first filter. A copy of this message is sent to the watch account.

 Scenario 4: A message arrives addressed to all 3000 employees:

 This message is matched by the filter on line 4. That filter automatically rejects any message with 50 or more recipients, regardless of the content of any of its header fields.

 Scenario 5: IS requires that all local mail be sent using a Netscape client:

  1. If the Client field of the message doesn't start with "Netscape", the filter on line 8 transfers processing to the filter labeled :TstCli (line 14).

  2. That filter tests whether the message was sent from any host in the domain xyzcorp.com. If it was, the sender did not use a Netscape client to send the mail, so the plug-in notifies the IS department of that fact by sending them a copy of the message.

  3. If the message was not sent locally, processing passes to the last line (15), where it jumps back up to line 9 and continues.
Scenario 6: The account nomime can't read MIME messages:

 At XYZ Corporation, mail accounts with underscores are reserved for clients that cannot handle MIME attachments. These are the received message's Channel-to and Content-Type fields:

 
Channel-To r_francisco 
Content-Type "multipart/mixed"

  1. The filter on line 7 matches the content type of the message, so processing jumps to the filter labeled :DoMime (line 12).

  2. That filter checks the account name. Because the name contains an underscore, the plug-in rejects the mail.
Anti-Relay Example

You can create a set of UBE filters to hinder the practice of relaying, the intentional sending of email from an outside domain into your domain when its destination is another outside domain. Mail sent this way is often UBE that is using relaying to hide its original source.

If your installation has a separate external mail server, outside your firewall, that receives external mail but does not forward outbound internal mail, it can effectively stop relaying by examining the Channel-To envelope field, like this: 

Channel-To ".*@xyzcorp\.com" EXIT
$ANY ".*" REJECT "We accept mail for XYZ Corporation only"
The first filter passes through any mail destined for the internal domain of XYZ Corporation and then exits. The second filter rejects any mail that does not match the first filter.

If your installation uses the same mail server for both internal and external mail, the filtering requires an extra preliminary step. Add a filter that first checks the source of the message, by looking at the Host-From field:

 
Host-From "123.45.67.*" EXIT 
Channel-To ".*@xyzcorp\.com" EXIT 
$ANY ".*" REJECT "We accept mail for XYZ Corporation only"
In this case, the first filter passes through any mail that originates from the subnet belonging to XYZ Corporation and then exits. The second filter passes through any mail that does not match the first filter but is destined for the internal domain of XYZ Corporation. The third filter rejects any mail that does not match either of the first two filters.

Note: Using the same mail server for both internal and external mail is not a recommended configuration. It makes your messaging system more open to external attacks.


Extending the UBE Plug-In
You can extend the UBE plug-in to give it capabilities beyond those delivered with the Messaging Server. Examples in this chapter have already demonstrated one extension method: the use of programs executed by the RUN action. Another method of extension involves use of an extension library. This section gives brief overviews of how to implement both methods.

 Using the RUN Action

The RUN action is built into the UBE plug-in. You can use this action to invoke an external program that can process messages in conjunction with the UBE filters. External programs called in this way can perform tasks such as scanning for viruses, matching message-field content against DNS or other databases of names, matching message-body text, and gathering statistics.

Your external program is executed through a command line that is the argument of the RUN action in a filter.The program provides a return value that a subsequent filter in the configuration file can make use of.

 Your program is passed two parameters: the pathname to a file containing the envelope of the message that triggered the RUN action, and the pathname to a file containing the combined header and body of the message. Your program must return a numerical value.

 The RUN action is described in Available Actions for UBE Filters.

Implementing a program executed through the RUN action can be very simple. In many cases, you may be able to use an existing text- manipulation utility, either directly or by writing a simple wrapper that is executed by the RUN action and that in turn calls the text utility. IMPORTANT: For security purposes, the external program must be located in the same directory of your Messaging Server as the UBE plugin configuration file (instanceDirectory/smtp-bin/plugins/).

Using an Extension Library

The UBE plug-in supports use of an extension library that is separate from the plug-in itself. You can write extensions to verify host name, reject relaying, perform DNS lookup, and perform virus checking, and any other task required. An extension library may be more appropriate than a program executed by the RUN action in situations where you want to alter the fundamental nature of a UBE plug-in action, or where you need to add a new kind of action to it.

In Unix environments, the extension library is defined as a shared object or shared library (extension .so or .sl), and in an NT environment it is referred to as a dynamically linked library (extension .dll). In the filter options file you can use the extension_so option to define the path to your shared library. For example, the line

 extension_so:/lib/HostNameChecker.so

 instructs the plug-in to load the library HostNameChecker.so into memory.

 Basically, an extension library can override existing UBE plug-in actions (such as COPY or EJECT), and it can also add new actions. If an extension library is present at the time the UBE plug-in reads an action in a filter configuration file, the plug-in takes these steps:

  1. It tries to locate the action name in the extension library. If an entry point with that action name is found, the plug-in calls it.

  2. If the plug-in finds no entry point with that action name in the extension library, the plug-in executes its own built-in default action.

  3. If the plug-in has no built in default action of that name, it does nothing and continues processing the filter configuration file.
Each entry point in the extension library is a function that must use the following prototype:

 
int (*ExtpFuncAct) (
      const char *arg, 
      char *control_file, 
      char *msg_file, 
      int * result
     );
where ExtpFuncAct, the name of the entry point, is the name of the action implemented by this entry point. (That is, COPY, DROP, EXIT, HOLDCOPY, HOLDONLY, JUMP, REJECT, RUN, or a new action defined by this library.)

The parameters to the function have the following meanings:
arg
(input) A pointer to a string that is the argument to the filter action. (The pointer is null if this action takes no argument.)
control_file
(input) A pointer to the pathname of a file containing the message's envelope fields.
msg_file
(input) A pointer to the pathname of a file containing the message's header fields and body text.
result
(output) A pointer to a result code. A return value of 0 indicates that the UBE plug-in should continue processing the filter configuration file; a nonzero return value stops processing filters.

This return value is stored in the variable $&, which can appear as the message-field name in the subsequent filter in the file. See Special Message-Field Names for more information.

IMPORTANT: When you write an extension library for Unix, be sure to put extern "C" {} around your function declaration. (The function name must be text symbols, not C++ symbols. You can verify that fact on most platforms by displaying the library's symbol table with nm shared_obj.so, and making sure it's of type T.)


Interface Reference: UBE Filters
This section describes the Netscape Console interface elements that allow you to manipulate UBE filters. See Managing Servers With Netscape Console for information on using Netscape Console to manage Messaging Server and other servers.
Unsolicited Bulk Email Configuration Tab
You use the form accessed through this tab to configure the UBE plug-in. For more information, see also

 The Unsolicited Bulk Email Configuration form has these elements:

 Filters. This field lists, in processing order, all current UBE filters, active and inactive. To edit the content of a filter or to alter its position in the filter list, first select it in this field.

Active. Check this box to make the filter displayed beside it active. If the box is unchecked, the filter is inactive.

 Add. Click this button to open the "Add a UBE Filter" window (see Add/Edit UBE Filter Window), which you can use to add a new UBE filter to the current set of filters.

Edit. After selecting a filter in the Filters field, click this button to open the "Edit a UBE Filter" window (see Add/Edit UBE Filter Window), which you can use to edit the characteristics of the selected UBE filter.

Delete. After selecting a filter in the Filters field, click this button to delete the selected filter from the set of UBE filters.

 Move up. After selecting a filter in the Filters field, click this button to reposition the selected filter by moving it up one position in the list of UBE filters. This move changes the order in which the filter is processed; when the UBE plug-in runs, it applies filters in sequence from top to bottom.

 Move down. After selecting a filter in the Filters field, click this button to reposition the selected filter by moving it down one position in the list of UBE filters. This move changes the order in which the filter is processed; when the UBE plug-in runs, it applies filters in sequence from top to bottom.

 Parse message header. Check this box to specify that the UBE plug-in is to analyze the header fields as well as the envelope fields of incoming messages. If this box in unchecked, only envelope fields are matched against the filter criteria. See Envelope Fields and Header Fields for more information.

Action Buttons

Save. Click this button to commit any settings you have made in the Unsolicited Bulk Email form.

Reset. Click this button to return the form to the settings it displayed when you opened it (unless you have previously clicked Save, in which case the form returns the settings it had when you last clicked Save).

 Help. Click this button to display online help (this document) describing the Unsolicited Bulk Email form.
Add/Edit UBE Filter Window
You use this window to edit the content of a UBE filter or to add a new filter to your set of UBE filters. For more information, see also

 The Add/Edit UBE Filter window has these elements:

 Name (optional). Use this field to enter a label for the filter you are creating or editing. A label is necessary only if this filter is the destination of another filter's JUMP action. For more information, see Label.

If. Use this field to select or enter the name of the envelope or header field whose contents this filter is to apply to. You can select one of the common fields from the list, or enter the name of another field. For more information, see Message Field.

=/!=. Click either the "equals" (=) or "does not equal" (!=) radio button. If you click =, the filter action is applied only if the message field matches the criterion; if you click !=, the filter action is applied only if the message field does not match the criterion. For more information, see Negation Modifier.

Value. Use this field to enter the match criterion--a string or regular expression that the filter seeks to match against the contents of the envelope or header field selected in the "If" field. For more information, see Match Criterion.

Case Sensitive. Check this box if you want the matching to be case sensitive. If this box is unchecked, case is ignored. For more information, see case Tag.

Envonly. Check this box if you want this filter to look only at envelope fields. The state of this box matters only if you have checked the Parse header fields checkbox in the UBE Configuration form (see Unsolicited Bulk Email Configuration Tab); if that box is unchecked, all filters look only at envelope fields. For more information, see envonly Tag.

then. Use this field to select the action that this filter is to perform if a match occurs (or if it does not occur, if you have selected the "does not equal" radio button). For more information, see Action.

Argument. Use this field to add any string argument that may be required by the filter action selected in the "then" field. For more information, see Argument.

Action Buttons

OK. Click this button to commit the entries you have made. If you have been creating a new filter, the filter is added to the end of the list of filters. If you have been editing an existing filter, the edited filter replaces the existing version at its current location in the list of filters.

Cancel. Click this button to close the window without making any changes or additions to the UBE filters.

 Help. Click this button to display online Help (this document) describing the Add/Edit UBE Filter window.

 

© Copyright 1998 Netscape Communications Corporation