Working with server plugins

• Plugin Configuration
• Unsolicited Bullk Email (UBE)

Configuring server plugins

Turning plugins on and off

1. From the Messaging Server's Administration page, click Plugins.
2. Click Plugin Configuration.
3. Locate in the table the name of the plugin you want to turn on or off.
4. Click the ON or OFF radio button to the right of the plugin name.
5. Click OK.

Configuring plugins in detail

1. From the Messaging Server's Administration page, click Plugins.
2. Click Plugin Configuration.
3. Click the Edit Config File button at the bottom of the form.

This displays a window showing the contents of the configuration file.
4. Edit the configuration file in the window.

The specific syntax varies from plugin to plugin--consult the documentation for the plugins you are configuring or contact your Netscape technical support representative.
5. When you are finished editing the file, click OK.

Controlling unsolicited bulk email (UBE)

• How UBE filters work
• Creating a UBE filter
• Editing an existing UBE filter
• Activating and deactivating UBE filters
• Changing the order of UBE filters

How UBE filters work

For example, if you want to delete all messages from uglymail.com, you would create a UBE filter that identifies any email message from uglymail.com.  You would designate "delete" as the action to be performed by the filter.

You can create a variety of types of UBE filters, store them, and activate or deactivate them from the UBE Filters form.

Creating a UBE filter

1. From the Messaging Server's Administration page, click Plugins.
2. Click Unsolicited Bulk Email (UBE).
3. Click Add a filter.

The Add a UBE Filter window appears.
4. (Optional) Assign a name to the new filter.
5. Select a field from the Field list or enter the field name in the text field.

The fields in the Field list correspond to the parts of the header or envelope information attached to an email message.
6. Choose equals (=) or does not equal (!=).
7. Type a value in the Value field.

This is the value that the filter uses as a triggering criterion.
8. Select an action from the Action list.

This is the action the filter will perform to any email that meets the triggering criterion you indicated in the Value field. For an explanation of the available actions listed in the Action list, see the table below.
9. If necessary, type an argument in the Argument field.

Some actions require arguments.  For example, if you choose Forward in the Action list, you need to add an email address to which the email message will be forwarded.
10. When you have finished creating the UBE filter, click OK.

The new UBE filter appears in the list of UBE filters.
11. Click Commit Changes to save the new UBE filter.

Important:  New filters are not saved until you click Commit Changes, even if they appear in the list of UBE filters.
Note:  New filters are automatically activated.  If you want to deactivate your new filter, follow the instructions in Activating and deactivating UBE filters.
 

Editing an existing UBE filter

1. From the Messaging Server's Administration page, click Plugins.
2. Click Unsolicited Bulk Email (UBE).
3. Click the UBE filter that you want to edit.

The Edit a UBE filter window appears, displaying the components of the UBE filter you're editing.
4. Make any changes to the filter.
5. When you have finished editing the filter, click OK.

The edit filter appears in the UBE filters list, with the changes you made to it.
6. Important: When you edit a UBE filter, the edited filter replaces the original filter.  You cannot edit create a new filter by editing an existing filter and saving it with a new name.
7. Click Commit Changes to save the edited UBE filter.

Activating and deactivating UBE filters

To activate or deactive filters:

1. Do one of the following:
• To activate all filters, click Activate all filters.
• To deactivate all filters, click Deactivate all filters.
• To activate an individual filter, check the Active box next to the filter that you want to activate.
• To deactivate an individual filter, uncheck the Active box next to the filter that you want to deactivate.
2. When you have finished activating or deactivating filters, click Commit Changes.

Important:  The changes you make in activating or deactivating filter are not saved until you click Commit Changes.

Changing the order of UBE filters

To change the order of UBE filters:

1. Click the up or down arrow next to the filter that you want to move.
2. If necessary, continue clicking the arrow until the filter that you are moving is in its appropriate position relative to other listed UBE filters.
3. Repeat steps 1 and 2 for each filter that you want to move.
4. When you have finished changing the order of your UBE filters, click Commit Changes.

Important:  The changes you make in the order of your UBE filters are not saved until you click Commit Changes, even if they appear reordered in the list of UBE filters.

More about UBE filters

This section describes the functionality of the General Scriptable Plugin, and how it interacts with the Netscape Messaging Server. This section assumes that you are using the Messaging Server Plugin API 2.x or 3.0. This API is available on the Solaris, HP-UX, and Windows NT platforms only.

One subsystem is implemented using this facility - the Unsolicited Bulk Email (UBE) filter.

The General Scriptable Plugin and its subsystems are designed for ISP administrators who want to extend the functionality of the Netscape Messaging Server for site-specific reasons.

Where to Find the General Scriptable Plugin

The General Scriptable Plugin is installed when you run a regular install of the Messaging Server. To use the General Scriptable Plugin, go to Plugins|Plugin Config and enable the plugin.

Where to Find Developer Information

For Netscape developer information, see the Netscape DevEdge site.

For more information about server Plugin APIs, see these Netscape documents:

Messaging Server Plugin API Guide

Overview and Installation

This section describes the General Scriptable Plugin and how to install it.

Overview
Installation

Overview

The General Scriptable Plugin is a dynamically loaded module designed to interact with Netscape Messaging Server 2.x and 3.x. It uses the existing Plugin API to hook into the "PostSmtpAccept" and "PreSmtpDelivery" stages of the MTA (Message Transfer Agent) operation, and contains a simple scripting language useful for processing and directing the flow of messages.

Installation

The General Scriptable Plugin is installed when you run a regular install of the Messaging Server. To use the General Scriptable Plugin, go to the Plugin Configuration menu and enable it. 

Unsolicited Bulk Email (UBE) filter

This section describes how the filtering functionality of the General Scriptable Plugin works.

What is UBE?

Unsolicited Bulk Email (UBE) 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 http://www.imc.org/uce-def.html Unsolicited Bulk Email: Definitions and Problems.

What is the UBE filter?

The UBE filter is a plugin for Netscape Messaging Server (version 3.0 and above). It works by examining all incoming mail before it is routed throughout the system (to users mailboxes or to other email servers). The UBE filter uses a set of rules (also known as filters) to decide what to do with each piece of mail. Any mail not handled by one of these filters continues on its normal course, untouched by the filter.

How do I use the UBE filter?

To use the filters in Messaging Server 3.5 simply turn on the nsfilter.dll (or nsfilter.so for UNIX) line from the Plugin Config screen in the admin server interface. Once turned on you can then go the Unsolicited Bulk Email page and use the UI to create filters. For Messaging Server 3.0, please see the documentation for instructions on how to install a plugin for your operating system.  In 3.0 you must manually create the filters you wish to use.  For 3.5 you can use the UI or manually create them.  This document describes how to manually create rules. The online help for the UI describes how to use the UI method.

The Messaging Server looks at the file plugin.conf to determine how the UBE filter is configured.  A typical line for an NT install would look like this:

PostSmtpAccept i:\Netscape\SuiteSpot\bin\mail\Server\etc\NSfilter.dll
funcs=filter_msg_plugin config=i:\Netscape\SuiteSpot\bin\mail\Server\etc\filter.cfg
option=i:\Netscape\SuiteSpot\bin\mail\Server\etc\filter.opt

This command line tells the server to:

• Use the NSfilter.dll file (which contains the UBE filter)
• Call the function filter_msg_plugin (which start the filters processing)
• Use the config file named filter.cfg
• Use the option file named filter.opt

For Unix, the command line would be very similar except that it would use the shared object NSfilter.so and the paths would be in a Unix format.

The important part of this statement is the config and option definitions. These two files drive the UBE filter. The config file (filter.cfg by default) contains the list of filters to apply to any incoming mail. The option file (filter.opt) tells the UBE filter how to behave. It describes such things as whether or not to parse the message header file and which file to use a template reply message.

Once you have the UBE filter installed and the line entered in the plugin.conf file, you can start creating filters. To write filters you can use any text editor (notepad for NT or vi for Unix, for example) and edit the file listed in the config line from the last section.

Enter your filters one per line in the file.  To enter a comment use the '#' symbol at the beginning of the line. The UBE filter will then check these filters in order from the top to the bottom (see the JUMP action for exceptions) and will apply the first rule that matches.

Filters contain from 3 to 5 parts depending on type. These parts are described below using the following example:

filter.cfg
:Testlabel Subject "Bad mail" REJECT "Do not send mail"

1. A name or label. This is optional and is used only by the JUMP action (explained below).  It is always preceded with a colon (:). In this case the label is  TestLabel.



2. The field in the message to base your filter on. When a message arrives, it has header information about that message. The UBE filter is capable of using any of these fields for determining what to do with a given piece of mail. There is no full list of possible fields since it is an open format, but common fields include Subject, Channel-To, From, and so on. This example examines the Subject line in the header.
   
   Note: After the field name you can place a colon (:) followed by special tags that affect how the rule is processed. Currently there are 2 tags supported: case and envonly. The case tag causes the matching criteria to be treated as case sensitive. By default the rules are case insenstive. Here's an example:
   
   

   Subject:case "test" REJECT "Hit rule 1" Subject "test" REJECT "Hit rule 2"

   Now if a message arrives with a header of "Subject: Test" it won't be caught by the first rule since it's been modified to be case sensitive. The second rule, however, is not case sensitive and thus will catch this message and reject it with a reason of "Hit rule 2".

   The envonly tag tells the filter to only look at the envelope information for this field. This can prevent fake envelope information.  Auth-Sender is a good example.  If a user sends mail via authenticated SMTP, then the envelope will contain an Auth-Sender field you could use to assure yourself that only authenticated mail gets through.  A tricky user could, however, add an Auth-Sender to the header information (remember that header information can be any field name) and then your filter would become confused.  By using the envonly flag you can tell the filter that you want to consider only those fields in the envelope that is created by the server and thus cannot be tampered with.




3. The matching criteria. This is combined with the field to form the Predicate and it decides whether or not to apply the filter. In this example the criteria is "Bad mail". If the Subject line is "Bad mail", the filter is applied. Otherwise, it is not applied. The matching criteria is a regular expression, which means you can enter regular expressions to fine tune your matching. For example, if you wanted to match on any Subject containing the phrase "Get Rich Quick", enter ".*Get Rich Quick.*" which says the line contains any character (.), any amount of times (*), then the phrase "Get Rich Quick" followed by any amount of any other characters. Note that the matching critierion is treated as case insensitive unless the rule has been given the case tag (see point 2 above). For more information about regular expressions, see Using Regular Expressions.



4. The action. This is the action that will be performed if the message matches the predicate.  For information on the various actions you can perform, see Actions.



5. The argument. This argument is used by the action to perform its task and is different for each action.  For details on what kind of argument the actions expect, see The Actions.

1. Comments. Any line that starts with the '#' character (or spaces and or tabs followed by the '#' character) is treated as a comment and is ignored by the filter. The '~' character is a special comment used by the UBE filters form in the Messaging Server 3.5 administration pages. If a line starts with '~', it will be treated as a comment by the filter when it is running, but the form will show this rule as being disabled and will treat the remainder of the line as a valid rule. This differs from '#' which is ignored by both the running filter and the form.
   
   You should use the '#' character only to create comments in the filter file.
   
   The '~' character should be inserted only by the form.
   
   Using the comment symbols anywhere but the beginning of a line is invalid syntax. You can include either of these characters in any of the fields by enclosing the character in quotes. For example, if you want to filter based on a field called X-Accept# then your filter line would be:

   :Label "X-Accept#" "Free stuff" REJECT "Please don't send this mail"

   The following example is invalid:

   :Label X-Accept# "Free stuff" REJECT "Please don't send this mail"
   
   

2. When you change the configuration file, the filters automatically take effect.



3. When you receive mail that you want to add a filter for you can view all the headers by choosing View, Headers, All in Netscape Communicator.  This will give you some clues as to what kind of predicate you will want to use to filter out any more mail like this.



4. The fields are broken up into two types: envelope fields and general header fields. Envelope fields are created by the Messaging Server; the header fields are created by the mail client that sent the message.  By default the UBE filter will only look at envelope fields.  This is to increase performance because the header can contain any number of fields.  However, if you wish to use the header fields in your predicate then you must add the following line to your option file (filter.opt):
   
   parseheader: 1

   This tells the UBE filter to look at both the control and header fields.  The control fields include:
   
   

   • Submitted-Date
   • Host-From
   • User-From
   • Auth-Sender
   • MAIL-Exts
   • Channel-To
   • RCPT-Exts
   • Message-Size
   • MTA-Hops
   
   You can force a filter to look only at the envelope fields on a filter-by-filter basis by using the envonly flag.  See the description of the field attribute above for more information on using flags.
   
   
5. There are some special field names you can use to combine filters and narrow your criteria. The following example filter illustrates this practice:

Subject "This is ."   REJECT "This is bad mail"

• $0 - Gives you the last line compared. In this example let's assume that the message had the subject:
  
  "Subject: This is a test"
  
  Then $0 is "This is a test".



• $1 -  Gives you whatever you matched with. In this example $1 becomes "This is a" without the test part.



• $2..$9 - These will return any parenthetical matches you have entered in order. For example, if you do a search for Subject (This) (is) (a) (test) would give $2=this $3=is $4=a and $5=test.



• $& - Gives you the result code of the last action. This is useful in conjunction with the RUN action (see below).



• $#- Gives you the number of recipients in the message.  A comparison of this and a number is considered true if the number of recipients is equal to or greater than the given number.



• $ANY - This will cause the filter to match your criteria with any field. You can use this property to create "always true" cases by creating a filter like:



$ANY ".*" REJECT ("I don't want this mail")

This rule says that if any field contains any string (.*) then execute the command REJECT. You could also use this to search all the headers for a specific phrase. For example:


$ANY "get free stuff" REJECT ("I don't want free stuff")

The following is a list of all the possible actions and how to use them:

COPY
Argument: a comma separated list of recipients.
Description: Copy adds its argument to the existing list of recipients for the incoming message and then sends the list on its way.
Example: Channel-To "user1@domain\.com" COPY "postmaster, user2"

Any mail sent to user1@domain.com is also sent to the postmaster and user2. DROP
Argument: one address.
Description: sends this mail to the address in the argument only.
Example: User-From  ".*@bulk\.com"   DROP "postmaster"

Any mail from any account at bulk.com will be dropped in the postmasters inbox but nowhere else.

Any mail containing the subject "Free hamburgers!" will not be sent to any account starting with vegetarian or green. EXIT
Argument: No argument.
Description: This action tells the UBE filter to stop looking at this mail and just let it through.  This prevents any filters further down the file from trapping a message though any actions already taken still take effect.
Example: User-From  "CEO@.*" EXIT

If the mail is from the CEO send it through all the time.

Any mail with the subject "Free Stuff" will be given to the postmaster. HOLDONLY
Argument: Comma separated list of recipients followed by | followed by a text description.
Description: This is the same as HOLDCOPY except that a copy of the original message is not included in the notification.
Example: See HOLDCOPY

JUMP
Argument: A label that exists somewhere else in the filter config file.
Description: When a JUMP action is initiated the flow of control in the list of filters is changed so that the next line interpreted is the one that starts with the given label. Using !JUMP can be very helpful, allowing the script to skip lines if criteria isn't met.
Example:

Subject  "Test"    JUMP   "JumpHere"
Subject  "Test"    REJECT "This is line 2"
:JumpHere  Subject "Test"   REJECT  "This is line 3"

If a message with the subject "Test" arrives, it will cause the filter to skip the second rule and start at the line beginning with :JumpHere and thus the message will be rejected with the following reason: "This is line 3" REJECT
Argument: A message that will be included in the rejected mail.
Description: This action will send the mail back to its recipient as if it had bounced but the reason for the bounced mail will be the given argument.
Example:
User-From "annoying@domain\.com" REJECT "Your mail is annoying; nobody wants it"

Any mail from annoying@domain.com will automatically be sent back to annoying@domain.com with the following reason: "Your mail is annoying; nobody wants it". RUN
Argument: A command line to execute.
Description: You can extend the actions by having the filter run another program.  This program must exist in the postoffice (spool) directory for security reasons.  Once the program is started the UBE filter will pipe the header and body of the message so that you can do whatever you want to it.  You can use the special field name $& in the next filter to match the return value of your program.
Example:

Subject "May contain a virus"  RUN     "VirusScan.exe"
$&      "1"                    REJECT  "This had a virus"

If mail arrives with the subject "May contain a virus" then run the program VirusScan.exe. If the return value is 1, reject the message with the reason "This had a virus".

Example Script:

Following is a sample script to show the interactions that the filters can have. Following the sample script is a description of how several kinds of mail would be handled by this script.

            Channel-To   "monitor@domain\.com" COPY     "watcher@domain.com"
            Subject      "weapons for sale"    DROP     "weap@xxx.gov"
            Channel-To   "CEO.*"               JUMP     "HandleCEO"
:DoneCEO    $#           "50"                  REJECT   "Don't send mail 50 or more"
            Subject      "May contain a virus" RUN      "VirusScan.exe"
            $&           "1"                   REJECT   "This had a virus"
            Content-Type "multipart/mixed"     JUMP     "HandleMime"
            Client       "Netscape.*"          !JUMP    "TestClient"
:DoneClient Subject      ".*"                  EXIT
:HandleCEO  Subject      "Postmaster Eval"     HOLDCOPY "postmaster | This is your eval"
            $ANY         ".*"                  JUMP     "DoneCEO"
:HandleMime Channel-To   "nomime@domain\.com"  REJECT   "Can't read mime messages"
            $ANY         ".*"                  EXIT
:TestClient Host-From    "local\.domain\.com"  COPY     "IS_department"
            $ANY         ".*"                  JUMP     "DoneClient"

Case 1:
Message for the CEO about the postmasters evaluation:

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

This message will be caught by the Channel-To "CEO.*" message which will then jump to the label :HandleCEO. The lines rule will also match because of the subject and so this message will be copied to the postmaster who can decide whether or not the CEO should see it.

Case 2:
Message for the CEO about the shareholders meeting:

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

This message will be caught by the Channel-To "CEO.*" rule but won't match the first line (Subject "Postmaster Eval") but will match the next line since .* means match anything. Thus, the script will jump back up to the line starting with :DoneCEO so that the rest of the filters can still be applied to the message.

Case 3:
Message sent to an account being monitored for some reason:

Channel-To "monitor@domain.com"
Subject "illegal stock trade"

A copy of this message will be mailed to the watcher account.

Case 4:
A message arrives with all 3000 employees listed:

This will be caught by the 4th line which says that any message with 50 or more recipients regardless of any other criteria will be reject automatically.

Case 5:
The IS department has said that all mail sent from local.domain.com must be sent using a Netscape client:

If the client doesn't start with Netscape, the filter will jump to TestClient and then check if the host the message was sent from is local.domain.com. If it is, they didn't use a Netscape product to send mail from local.domain.com so the script sends a copy to the IS department so they can handle it. Otherwise, the script jumps back up and continues.

Case 6:
The account nomime can't read mime messages:

The filter will look at the content-type; if it is a mime message, the script jumps to :HandleMime, which checks the account--if it is nomime, the script rejects the mail.

Using Regular Expressions

The UBE filter supports extended regular expressions compliant with POSIX 1003.2.  There are several good sources of information on regular expressions, a simple internet search will provide you with all the detail you could want.

Extensibility

This section provides an overview on how to extend the functionality of the General Scriptable Plugin, using the Run action and the Extension library.

Using the Run Action
Using the Extension Library

Using the Run Action

The Run action allows you to invoke external programs, enabling you to perform different tasks such as virus scanning with Virus Scanner . Please see the description of the Run action in the section Pre-Defined Actions in "Unsolicited Bulk Email (UBE) filter" above for details. 

Using the Extension Library

The General Scriptable Plugin filter supports an extension library. In a UNIX environment, the extension library is defined as a shared object (so), and in an NT environment it is referred to as a Dynamically Linked Library (DLL).

Specifying an extension_so option in the option file, extension_so:/etc/HostNameChecker.so, enables the filter to load the shared object /etc/HostNameChecker.so into memory.

If an extension library is present at the time that an action is to be executed, the Plugin will try to locate the action name in the extension library. If an entry point with the action name is found, the entry point is invoked. If no entry point with the action name is found, the built-in default action is invoked. If no built in default action is available for that action name, the nothing action is invoked and execution of the script continues.

Each entry point in the extension library should use the following prototype:

int (*ExtpFuncAct) (
    const char  *arg,
    char *control_file,
    char *header_file,
    char *body_file,
    int * result
    );

You can write an extension to verify hostname, to reject relaying, to perform DNS lookup, and to perform virus checking, or any other task required.

IMPORTANT: When writing an extension library for UNIX, make sure that you put extern "C" {} around your function declaration. The function name must be text symbols, not C++ symbols. Verify that with nm shared_obj.so and see if it's of type  T.