Chapter 11 Using Pre-defined Channels

When you first install Messaging Server, several channels are already defined (see Table 11-1). This chapter describes how to use pre-defined channel definitions in the MTA.

Table 11-1 Predefined Channels
Channel	Definition
defaults	Used to specify which keywords are defaults for various channels. See "Configuring Channel Defaults".
l	UNIX only. Used to make routing decisions and for submitting mail using UNIX mail tools.
ims-ms	Delivers mail to the local store.
native	UNIX only. Delivers mail to /var/mail. (Note that Messaging Server does not support /var/mail access. User must use UNIX tools to access mail from the /var/mail store.)
pipe	Used to perform delivery via a site-supplied program or script. Commands executed by the pipe channel are controlled by the administrator via the imsimta program interface.
reprocess process	These channels are used for deferred, offline message processing. The reprocess channel is normally invisible as a source or destination channel; the process channel is visible like other MTA channels.
defragment	Provides the means to reassemble MIME fragmented messages.
conversion	Performs body-part-by-body-part conversions on messages flowing through the MTA.
bitbucket	Used for messages that need to be discarded.
inactive/deleted	Used to process messages for users who have been marked as inactive/deleted in the directory. Typically, bounces the message and returns custom bounce message to the sender of the message.
hold	Used to hold messages for users. For example, when a user is migrated from one mail server to another.
sms	Provides support for one-way email to an SMS gateway.
tcp_local tcp_intranet tcp_auth tcp_submit tcp_tas	Implements SMTP over TCP/IP. The multithreaded TCP SMTP channel includes a multithreaded SMTP server that runs under the control of the Dispatcher. Outgoing SMTP mail is processed by the channel program tcp_smtp_client, and runs as needed under the control of the Job Controller. tcp_local receives inbound messages from remote SMTP hosts. Depending on whether you use a smarthost/firewall configuration, either sends outbound messages directly to remote SMTP hosts or sends outbound messages to the smarthost/firewall system. tcp_intranet receives and sends messages within the intranet. tcp_auth is used as a switch channel for tcp_local; authenticated users switch to the tcp_auth channel to avoid realy-blocking restrictions. tcp_submit accepts message submissions—usually from user agents—on the reserved submission port 587 (see RFC 2476). tcp_tas is a special channel used by sites doing Unified Messaging.

To Deliver Messages to Programs Using the Pipe Channel

Users might want incoming mail passed to a program instead of to their mailbox. For example, users might want their incoming mail sent to a mail sorting program. The pipe channel performs delivery of messages using per-user, site-supplied programs.

To facilitate program delivery, you must first register programs as able to be invoked by the pipe channel. Do this by using the imsimta program utility. This utility gives a unique name to each command that you register as able to be invoked by the pipe channel. End users can then specify the method name as a value of their mailprogramdeliveryinfo LDAP attribute.

For example, to add a UNIX command myprocmail as a program that can be invoked by a user, you would first register the command by using the imsimta program utility as shown in the following example. This example registers a program called myprocmail that executes the program procmail with the arguments -d username and executes as the user:

Make sure the executable exists in the programs directory msg_svr_base/data/site-programs. Make sure also that the execute permissions are set to “others.”

To enable a user to access the program, the user’s LDAP entry must contain the following attributes and values:

For more information about the imsimta program utility, see the Messaging Server Reference Manual.

Alternative delivery programs must conform to the following exit code and command-line argument restrictions:

Exit Code Restrictions. Delivery programs invoked by the pipe channel must return meaningful error codes so that the channel knows whether to dequeue the message, deliver for later processing, or return the message.

If the subprocess exits with an exit code of 0 (EX_OK), the message is presumed to have been delivered successfully and is removed from the MTA queues. If it exits with an exit code of 71, 74, 75, or 79 (EX_OSERR, EX_IOERR, EX_TEMPFAIL, or EX_DB), a temporary error is presumed to have occurred and delivery of the message is deferred. If any other exit code is returned, then the message will be returned to its originator as undeliverable. These exit codes are defined in the system header file sysexits.h.

Command Line Arguments. Delivery programs can have any number of fixed arguments as well as the variable argument, %s, representing the user name for programs executed by the user or username+domain for programs executed by the postmaster, “inetmail.” For example, the following command line delivers a recipient’s mail using the program procmail:

To Configure the Native (/var/mail) Channel

An option file may be used to control various characteristics of the native channel. This native channel option file must be stored in the MTA configuration directory and named native_option (for example, msg_svr_base/config/native_option).

Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:

The value may be either a string or an integer, depending on the option's requirements.

Table 11-2 Local Channel Options
Options	Descriptions
FORCE_CONTENT_LENGTH (0 or 1; UNIX only)	If FORCE_CONTENT_LENGTH=1, then the MTA adds a Content-length: header line to messages delivered to the native channel, and causes the channel not to use the “>From” syntax when “From” is at the beginning of the line. This makes local UNIX mail compatible with Sun’s newer mail tools, but potentially incompatible with other UNIX mail tools.
FORWARD_FORMAT (string)	Specifies the location of the users’ .forward files. The string %u indicates that it is substituted in each user id. The string %h indicates that it is substituted in each user’s home directory. The default behavior, if this option is not explicitly specified, corresponds to: FORWARD_FORMAT=%h/.forward
REPEAT_COUNT (integer) SLEEP_TIME (integer)	In case the user’s new mail file is locked by another process when the MTA tries to deliver the new mail, these options provide a way to control the number and frequency of retries the native channel program should attempt. If the file can not be opened after the number of retries specified, the messages remain in the native queue and the next run of the native channel attempts to deliver the new messages again. The REPEAT_COUNT option controls how many times the channel programs attempt to open the mail file before giving up. REPEAT_COUNT defaults to 30, (30 attempts). The SLEEP_TIME option controls how many seconds the channel program waits between attempts. SLEEP_TIME defaults to 2 (two seconds between retries).
SHELL_TIMEOUT (integer)	Controls the length of time in seconds the channel waits for a user’s shell command in a .forward to complete. Upon such time-outs, the message are returned to the original sender with an error message resembling “Time-out waiting for user’s shell command command to complete.” The default is 600 (10 minutes).
SHELL_TMPDIR (directory-specific)	Controls the location where the local channel creates its temporary files when delivering to a shell command. By default, such temporary files are created in users’ home directories. Using this option, the administrator may instead choose the temporary files to be created in another (single) directory. For example: SHELL_TMPDIR=/tmp

To Temporarily Hold Messages Using the Hold Channel

The hold channel is used to hold the messages of a recipient temporarily prevented from receiving new messages. Messages may be held because a user’s name is being changed or their mailbox is being moved from one mailhost or domain to another. There may also be other reasons to temporarily hold messages.

When messages are to be held, they are directed to the hold channel, in the msg_svr_base/queue/hold directory, using the same mechanism used to direct messages to the reprocess channel. In this way, the envelope To: addresses are unchanged. The messages are written to the hold channel queue, in the msg-server/queue/hold directory, as ZZxxx.HELD files. This prevents them from being seen by the job controller, and thus they are “held.” Use the imsimta qm dir -held command to view a list of .HELD files. These messages can be selected and released using the imsimta qm -release command. Releasing them changes their name to ZZxxx.00 and informs the job controller. The messages are then processed by the master program associated with the hold channel, reprocess.exe. Thus the message (and the To: addresses) are processed using the normal rewriting machinery.

For more information on the imsimta qm command, see the Sun ONE Messaging Server Reference Guide.

The Conversion Channel

The conversion channel allows you to perform arbitrary body part-by-body part processing on specified messages flowing through the MTA. (Note that a body part is different than a message in that a message can contain multiple body parts as, for instance, in an attachment. Also, body parts are specified and delineated by MIME headers.) This processing can be done by any site-supplied programs or command procedures and may do such things such as convert text or images from one format to another, virus scanning, language translation and so forth. Various message types of the MTA traffic are selected for conversion, and specific processes and programs can be specified for each type of message body part.

The prerequisite for using this chapter is understanding the concept of channels (see "Channels"). For supplemental information on virus scanning using the conversion channel, refer to the Messaging Server Technical Notes at the bottom of the Messaging Server Documentation website.

Implementing the conversion channel consists of A) selecting message traffic for processing, and B) specifying how different messages will be processed. These procedures will discussed in further detail.

MIME Overview


Note	A default conversion channel is automatically created in the MTA configuration file (imta.cnf). This channel can be used as is and requires no modification.

The conversion channel makes extensive use of the MIME (Multipurpose Internet Mail Extensions) header lines. Knowledge of message construction and MIME header fields is required. For complete information on MIME, refer to RFCs 1806, 2045 through 2049, and 2183. A short overview of MIME is presented here for convenience.

Message Construction

A simple message consists of a header and a body. The header is at the top of the message and contains certain control information such as date, subject, sender, and recipient. The body is everything after the first blank line after the header. MIME specifies a way to construct more complex messages which can contain multiple body parts, and even body parts nested within body parts. Messages like these are called multi-part messages, and, as mentioned earlier, the conversion channel performs body part-by-body part processing of messages.

MIME Headers

The MIME specification defines a set of header lines for body parts. These include MIME-Version, Content-type, Content-Transfer-Encoding, Content-ID, and Content-disposition. The conversion channel uses the Content-type and Content-disposition headers most frequently. An example of some MIME header lines is shown below:

Content-type Header


Note	MIME header lines are not the same as general, non-MIME header lines such as To:, Subject: and From:. Basically, for Conversion channel discussion, MIME header lines start with the string Content-.

The MIME Content-Type header describes the content of the body-part. The Content-Type header format (with an example) is shown below:

type describes the type of content of the body part. Examples of type are Text, Multipart, Message, Application, Image, Audio, and Video.

subtype further describes content type. Each Content-type has its own set of subtypes. For examples: text/plain, application/octet-stream, and image/jpeg. Content Subtypes for MIME mail are assigned and listed by the IANA (Internet Assigned Numbers Authority). A copy of the list is at http://www.isi.edu/in-notes/iana/assignments/media-types/media-types

parameter is specific to Content-type/subtype pairs. For example, the charset and the name parameters are shown below:

The charset parameter specifies a character set for a textual message. The name parameter gives a suggested file name to be used if the data were to be written to a file.

Content-disposition Header


Note	Content-Type values, subtypes, and parameter names are case-insensitive.

The MIME Content-disposition header provides presentation information for the body-part. It is often added to attachments specifying whether the attachment body part should be displayed (inline) or presented as a file name to be copied (attachment). The Content-disposition header has the following format:

disposition_type is usually inline (display the body part) or attachment (present as file to save.) Attachment usually has the parameter filename with a value specifying the suggested name for the saved file.

Selecting Traffic for Conversion Processing

Unlike other MTA channels, the conversion channel is not normally specified in an address or MTA rewrite rule. Instead, messages are sent to the conversion channel using the CONVERSIONS mapping table (specified by the parameter IMTA_MAPPING_FILE in the imta_tailor file). Entries to the table have the following format:

As the MTA processes each message it probes the CONVERSIONS mapping table (if one is present). If the source-channel is the channel from which the message is coming and destination-channel is the channel to which the message is going, then the action following CONVERT is taken (Yes means the MTA diverts the message from its destination-channel to the conversion channel; if no match is found, the message will be queued to the regular destination channel).

The following example routes all non-internal messages—messages originating from, or destined to, the Internet—to the conversion channel.


Note	An address of the form user@conversion.localhostname or user@conversion will be routed through the conversion channel, regardless of the CONVERSIONS mapping table.

The first line specifies that messages coming from the tcp_local channel will be processed. The second line specifies that messages going to the tcp_local channel will also be processed. The tcp_local channel handles all messages going to and coming from the Internet. Since the default is to not go through the conversion channel, any other messages won’t go through the conversion channel.

Note that this is a very basic table, and that it might not be sufficient for a site with a more customized configuration, for example, one using multiple outbound-to-the-Internet tcp_* channels, or using multiple inbound-from-the-Internet tcp_* channels.

To Control Conversion Processing

When a message is sent to the conversion channel, it is processed body part-by-body part. Processing is controlled by the MTA conversions file, which is specified by the IMTA_CONVERSION_FILE option in the imta_tailor file (default: msg_svr_base/conversions). The conversions file consists of entries that control which types of body parts will be processed, and how they will be processed.

Each entry consists of one or more lines containing one or more name=value parameter clauses. The values in the parameter clauses conform to MIME conventions. Every line except the last must end with a semicolon (;). A physical line in this file is limited to 252 characters. You can split a logical line into multiple physical lines using the back slash (\) continuation character. Entries are terminated either by a line that does not end in a semicolon, one or more blank lines, or both.

The clauses out-chan=ims-ms; in-type=application; in-subtype=wordperfect5.1 qualify the body part. That is, they specify the type of part to be converted. The header of each part is read and its Content-Type: and other header information is extracted. The entries in the conversion file are then scanned in order from first to last; any in-* parameters present, and the OUT-CHAN parameter, if present, are checked. If all of these parameters match the corresponding information for the body part being processed, then the conversion specified by the command= or delete= clause is performed, and the out-* parameters are set.

If no match occurs, then the part is matched against the next conversions file entry. Once all body parts have been scanned and processed (assuming there is a qualifying match), then the message is sent onwards to the next channel. If there are no matches, no processing occurs, and the message is sent to the next channel.

out-chan=ims-ms specifies that only message parts destined for the ims-ms channel will be converted. in-type=application and in-subtype=wordperfect5.1 specifies that the MIME Content-type header for the message part must be application/wordperfect5.1.

Message parts can be further qualified with additional in-* parameters. (See Table 11-6.) The entry above will trigger conversion actions on a message part which has the following MIME header lines:

After the three conversion file qualifying parameters in Code Example 11-1, the next two parameters, out-type=application and out-subtype=msword, specify replacement MIME header lines to be attached to the “processed” body part. out-type=application and out-subtype=msword specify that the MIME Content-type/subtype of the outgoing message be application/msword.

Note that since the in-type and out-type parameters are the same, out-type=application is not necessary since the conversion channel defaults to the original MIME labels for outgoing body parts. Additional MIME labels for outgoing body parts can be specified with additional output parameters.

out-mode=block (Code Example 11-1) specifies the file type that the site-supplied program will return. In other words, it specifies how the file will be stored and how the conversion channel should be read back in the returned file. For example, an html file is stored in text mode, while an .exe program or a zip file is stored in block/binary mode. Mode is a way of describing that the file being read is in a certain storage format.

command="/usr/bin/convert -in=wordp -out=msword ‘INPUT_FILE’ ‘OUTPUT_FILE’"

The command= parameter specifies that a program will execute on the body part. /usr/bin/convert is the hypothetical command name; -in=wordp and -out=msword are hypothetical command line arguments specifying the format of the input text and output text; INPUT_FILE and OUTPUT_FILE are conversion channel environmental parameters (see "To Use Conversion Channel Environmental Variables") specifying a file containing the original body part and a file where the program should store its converted body part.

Instead of executing a command on the body part, the message part can simply be deleted by substituting DELETE=1 in place of the command parameter.

Conversion Channel Information Flow


Note	Whenever the conversions file is modified, you must recompile the configuration (see the imsimta refresh command in the Sun ONE Messaging Server Reference Manual).

The flow of information is as follows: a message containing body parts comes into the conversion channel. The conversion channel parses the message, and processes the parts one by one. The conversion channel then qualifies the body part, that is, it determines if it should be processed or not by comparing its MIME header lines to the qualifying parameters. If the body part qualifies, the conversion processing commences. If MIME or body part information is to be passed to the conversion script, it is stored in an environmental variable (Table 11-3) as specified by information passing parameters.

At this point, an action specified by an action parameter, is taken on the body part. Typically the action is that the body part be deleted or that it be passed to a program wrapped in a script. The script processes the body part and then sends it back to the conversion channel for reassembling into the post-processed message. The script can also send information to the conversion channel by using the conversion channel output options. This can be information such as new MIME header lines to add to the output body part, error text to be returned to the message sender, or special directives instructing the MTA to initiate some action such as bounce, delete, or hold a message.

Finally, the conversion channel replaces the header lines for the output body part as specified by the output parameters.

To Use Conversion Channel Environmental Variables

When operating on message body parts, it is often useful to pass MIME header line information, or entire body parts, to and from the site-supplied program. For example, a program may require Content-type and Content-disposition header line information as well as a message body part. Typically a site-supplied program’s main input is a message body part which is read from a file. After processing the body part, the program will need to write it to a file from which the conversion channel can read it. This type of information passing is done by using conversion channel environmental variables.

Environmental variables can be created in the conversions file using the parameter-symbol-* parameter or by using a set of pre-defined conversion channel environmental variables (see Table 11-4).

The following conversions file entry and incoming header show how to pass MIME information to the site-supplied program using environment variables.

in-channel=*; in-type=application; in-subtype=* specify that a message body part from any input channel of type application will be processed.

parameter-symbol-0=NAME specifies that the first Content-type parameter value (Draft1.doc in our example) be stored in an environment variable called NAME.

parameter-copy-0=* specifies that all Content-type parameters of the input body part be copied to the output body part.

dparameter-symbol-0=FILENAME specifies that the first Content-disposition parameter value (Draft1.doc in our example) be stored in an environment variable called FILENAME.

dparameter-copy-0=* specifies that all Content-disposition parameters of the input body part be copied to the output body part.

message-header-file=2 specifies that the original header of the message as a whole (the outermost message header) be written to the file specified by the environment variable MESSAGE_HEADERS.

original-header-file=1 specifies that the original header of the enclosing MESSAGE/RFC822 part are written to the file specified by the environment variable INPUT_HEADERS.

override-header-file=1 specifies that MIME headers are read from the file specified by environmental variable OUTPUT_HEADERS, overriding the original MIME header lines in the enclosing MIME part. $OUTPUT_HEADERS is an on-the-fly temporary file created at the time conversion runs. A site-supplied program would use this file to store MIME header lines changed during the conversion process. The conversion channel would then read the MIME header lines from this file when it re-assembles the body part. Note that only MIME header lines can be modified. Other general, non-MIME header lines cannot be cannot be altered by the conversion channel.

override-option-file=1 specifies that the conversion channel read conversion channel options from the file named by the OUTPUT_OPTIONS environmental variable. See "To Use Conversion Channel Output Options".

command="msg_svr_base/bin/viro-scan500.sh" specifies the command to execute on the message body part.

Table 11-3 Conversion Channel Environment Variables
Environment Variable	Description
INPUT_ENCODING	Encoding originally present on the body part.
INPUT_FILE	Name of the file containing the original body part. The site-supplied program should read this file.
INPUT_HEADERS	Name of the file containing the original header lines for the body part. The site-supplied program should read this file.
INPUT_TYPE	MIME Content-type of the input message part.
INPUT_SUBTYPE	MIME content subtype of the input message part.
INPUT_DESCRIPTION	MIME content-description of the input message part.
INPUT_DISPOSITION	MIME content-disposition of the input message part.
MESSAGE_HEADERS	Name of the file containing the original outermost header for an enclosing message (not just the body part) or the header for the part’s most immediately enclosing MESSAGE/RFC822 part. The site-supplied program should read this file.
OUTPUT_FILE	Name of the file where the site-supplied program should store its output. The site-supplied program should create and write this file.
OUTPUT_HEADERS	Name of the file where the site-supplied program should store MIME header lines for an enclosing part. The site-supplied program should create and write this file. Note that file should contain actual MIME header lines (not option=value lines) followed by a blank line as its final line. Note also that only MIME header lines can be modified. Other general, non-MIME header lines cannot be cannot be altered by the conversion channel.
OUTPUT_OPTIONS	Name of the file from which the site-supplied program should read conversion channel options. See "To Use Conversion Channel Output Options".”

To Use Conversion Channel Output Options

Conversion channel output options (Table 11-4) are dynamic variables used to pass information and special directives from the conversion script to the conversion channel. For example, during body part processing the script may want to send a special directive asking the conversion channel to bounce the message and to add some error text to the returned message stating that the message contained a virus.

The output options are initiated by setting OVERRIDE-OPTION-FILE=1 in the desired conversion entry. Output options are then set by the script as needed and stored in the environmental variable file, OUTPUT_OPTIONS. When the script is finished processing the body part, the conversion channel reads the options from the OUTPUT_OPTIONS file.

The OUTPUT_OPTION variable is the name of the file from which the conversion channel reads options. Typically it is used as an on-the-fly temporary file to pass information. The example below shows a script that uses output options to return an error message to a sender who mailed a virus.

In this example, the system diagnostic message and status code are added to the file defined by $OUTPUT_OPTIONS. If you read the $OUTPUT_OPTIONS temporary file out you would see something like:

The line OUTPUT_DIAGNOSTIC='Virus found and deleted’ tells the conversion channel to add the text Virus found and deleted to the message.

178029946 is the PMDF__FORCERETURN status per the pmdf_err.h file which is found in the msg_svr_base/include/deprecated/pmdf_err.h. This status code directs the conversion channel to bounce the message back to the sender. (For more information on using special directives refer to "To Bounce, Delete, or Hold Messages Using the Conversion Channel Output".)

Headers in an Enclosing MESSAGE/RFC822 Part

Table 11-4 Conversion Channel Output Options
Option	Description
OUTPUT_TYPE	MIME content type of the output message part.
OUTPUT_SUBTYPE	MIME content subtype of the output message part.
OUTPUT_DESCRIPTION	MIME content description of the output message part.
OUTPUT_DIAGNOSTIC	Text to include as part of the message sent to the sender if a message is forcibly bounced by the conversion channel.
OUTPUT_DISPOSITION	MIME content-disposition of the output message part.
OUTPUT_ENCODING	MIME content transfer encoding to use on the output message part.
OUTPUT_MODE	MIME Mode with which the conversion channel should write the output message part, hence the mode with which recipients should read the output message part.
STATUS	Exit status for the converter. This is typically a special directive initiating some action by the conversion channel. A complete list of directives can be viewed in msg_svr_base/include/deprecated/pmdf_err.h

When performing conversions on a message part, the conversion channel has access to the header in an enclosing MESSAGE/RFC822 part, or to the message header if there is no enclosing MESSAGE/RFC822 part. Information in the header may be useful for the site-supplied program.

If an entry is selected that has ORIGINAL-HEADER-FILE=1, then all the original header lines of the enclosing MESSAGE/RFC822 part are written to the file represented by the OUTPUT_HEADERS environment variable. If OVERRIDE-HEADER-FILE=1, then the conversion channel will read and use as the header on that enclosing part the contents of the file represented by the OUTPUT_HEADERS environment variable.

To Call Out to a Mapping Table from a Conversion Entry

out-parameter-* values may be stored and retrieved in an arbitrarily named mapping table. This feature is useful for renaming attachments sent by clients that send all attachments with a generic name like att.dat regardless of whether they are postscript, msword, text or whatever. This is a generic way to relabel the part so that other clients (Outlook for example) will be able to open the part by reading the extension.

$Y returns a parameter value. If there is no match found or the match returns $N, then that parameter in the conversions file entry is ignored or treated as a blank string. Lack of a match or a $N does not cause the conversion entry itself to be aborted.

The following conversion entry for the above mapping table results in substituting generic file names in place of specific file names on attachments:

In the example above, out-chan=tcp_local; in-type=application; in-subtype=* specifies that a message to be processed must come from the tcp_local channel with the content-type header of application/* (* specifies that any subtype would do).

in-parameter-name-0=name; in-parameter-value-0=* additionally specifies that the message must have a paramater type name=* (again, * specifies that any parameter value would do.)

out-type=application; specifies that the MIME Content-type parameter for the post-processing message be application.

out-subtype=’INPUT-SUBTYPE’; specifies that the MIME subtype parameter for the post-processing body part be the INPUT-SUBTYPE environmental variable, which is the original value of the input subtype. Thus, if you wanted change

out-parameter-name-0=name; specifies that the first MIME Content-type parameter of the output body part be of type name= .

out-parameter-value-0=’X-ATT-NAMES:\\’INPUT_SUBTYPE\\’’; says to take the first MIME subtype parameter value and search the mapping table X-ATT-NAMES for a subtype match. If a match is found, the name parameter receives the new value specified in the X-ATT-NAMES mapping table. Thus, if the parameter is of type msword, the name parameter will be temp.DOC.

To Bounce, Delete, or Hold Messages Using the Conversion Channel Output

This section describes how to use the conversion channel options to bounce, delete, or hold messages. The basic procedure is as follows:

A complete listing of special directives can be found in msg_svr_base/include/deprecated/pmdf_err.h. The ones commonly used by the conversion channel are:

To Bounce Messages

Table 11-5 Special Directives Commonly Used By the Conversion Channel
NAME	Hex Value	Decimal Value
PMDF__FORCEHOLD	0x0A9C86AA	178030250
PMDF__FORCERETURN	0x0A9C857A	178029946
PMDF__FORCEDELETE	0x0A9C8662	178030178

To bounce a message using the conversion channel set OVERRIDE-OPTION-FILE=1 in the appropriate conversions file entry and add the following line to your conversion script:

If you wish to add a short text string to the bounced message add the following line to the conversion script:

where text string is something like: “The message sent from your machine contained a virus which has been removed. Be careful about executing email attachments.”

To Conditionally Delete Message Parts

It may be useful to delete parts conditionally, depending on what they contain. This can be done using the output options. By contrast, the DELETE=1 conversion parameter clause unconditionally deletes a message part.

To delete a message part using the output options, set OVERRIDE-OPTION-FILE=1 in the appropriate conversions file entry and add the following line to your conversion script:

To Hold a Message

It may be useful to hold messages conditionally, depending on what they contain. To delete a message part using the output options, set OVERRIDE-OPTION-FILE=1 in the appropriate conversions file entry and add the following line to your conversion script:

This requests that the conversion channel hold the message as a .HELD file in the conversion channel queue.

Conversion Channel Example

The CONVERSIONS mapping and set of conversion rules seen in examples below cause GIF, JPEG, and BITMAP files sent to the hypothetical channel tcp_docuprint to be converted into PostScript automatically. Several of these conversions use the hypothetical /usr/bin/ps-converter.sh to make that transformation. An additional rule that converts WordPerfect 5.1 files into Microsoft Word files is included.

Table 11-6 Conversion Parameters
Parameter	Description
Qualifying Parameters (Specifies the parameters for which the message must match before it will be converted.)
OUT-CHAN, OUT-CHANNEL	Output channel to match for conversion (wildcards allowed). The conversion specified by this entry is performed only if the message is destined for this specified channel.
IN-CHAN, IN-CHANNEL	Input channel to match for conversion (wildcards allowed). The conversion specified by this entry is only performed if the message is coming from the specified channel.
IN-TYPE	Input MIME type to match for conversion (wildcards allowed). The conversion specified is performed only if this field matches the MIME type of the body part.
IN-SUBTYPE	Input MIME subtype to match for conversion (wildcards allowed). The conversion specified by this entry is performed only if this field matches the MIME subtype of the body part.
IN-PARAMETER-NAME-n	Input MIME Content-Type parameter name that must match for conversion; n = 0, 1, 2.... This parameter can be used with IN-PARAMETER-VALUE-n to distinctly identify a parameter by its name and the value that it holds.
IN-PARAMETER-VALUE-n	Input MIME Content-Type parameter value of corresponding IN-PARAMETER-NAME that must match for conversion. The conversion specified by this entry is performed only if this field matches the corresponding parameter in the body part's Content-Type parameter list. Wildcards allowed.
IN-PARAMETER-DEFAULT-n	Input MIME Content-Type parameter value default if parameter is not present. This value is used as a default for the IN-PARAMETER-VALUE-n test when no such parameter is specified in the body part.
IN-DISPOSITION	Input MIME Content-Disposition to match for conversion.
IN-DPARAMETER-NAME-n	Input MIME Content-Disposition parameter name that must match for conversion; n = 0, 1, 2.... This parameter can be used with IN-DPARAMETER-VALUE-n to distinctly identify a parameter by its name and the value that it holds.
IN-DPARAMETER-VALUE-n	Input MIME Content-Disposition parameter value of corresponding IN-DPARAMETER-NAME that must match for conversion. The conversion specified by this entry is performed only if this field matches the corresponding parameter in the body part's Content-Disposition: parameter list. Wildcards allowed.
IN-DPARAMETER-DEFAULT-n	Input MIME Content-Disposition parameter value default if parameter is not present. This value is used as a default for the IN-DPARAMETER-VALUE-n test when no such parameter is specified in the body part.
IN-DESCRIPTION	Input MIME Content-Description to match for conversion.
IN-SUBJECT	Input Subject from enclosing MESSAGE/RFC822 part.
Output Parameters (Specify the body part’s post-conversion output settings.)
OUT-TYPE	Output MIME type if it is different than the input type.
OUT-SUBTYPE	Output MIME subtype if it is different than the input subtype.
OUT-PARAMETER-NAME-n	Output MIME Content-Type parameter name; n = 0, 1, 2...
OUT-PARAMETER-VALUE-n	Output MIME Content-Type parameter value corresponding to OUT-PARAMETER-NAME-n.
PARAMETER-COPY-n	A list of the Content-Type parameters to copy from the input body part's Content-Type parameter list to the output body part's Content-Type: parameter list; n=0, 1, 2... Uses the same name of the MIME parameter to copy, as matched by an IN-PARAMETER-NAME-n clause.
OUT-DISPOSITION	Output MIME Content-Disposition if it is different than the input MIME Content-Disposition.
OUT-DPARAMETER-NAME-n	Output MIME Content-Disposition parameter name; n=0, 1, 2...
OUT-DPARAMETER-VALUE-n	Output MIME Content-Disposition parameter value corresponding to OUT-DPARAMETER-NAME-n.
DPARAMETER-COPY-n	A list of the Content-Disposition: parameters to copy from the input body part’s Content-Disposition: parameter list to the output body part’s Content-Disposition: parameter list; n = 0, 1, 2,... Takes as argument the name of the MIME parameter to copy, as matched by an IN-PARAMETER-NAME-n clause. Wildcards may be used in the argument. In particular, an argument of * means to copy all the original Content-Disposition: parameters.
OUT-DESCRIPTION	Output MIME Content-Description if it is different than the input MIME Content-Description.
OUT-MODE	Mode in which to read and store the converted file. This should be BLOCK (binaries and executables) or TEXT.
OUT-ENCODING	Encoding to apply to the converted file when the message is reassembled.
Action Parameters (Specify an action to take on a message part.)
COMMAND	Command to execute to perform conversion. Command to execute to perform conversion. This parameter is required; if no command is specified, the entry is ignored. Use / to specify paths, not \. Example: command="D:/tmp/mybat.bat"
DELETE	0 or 1. If this flag is set, the message part is deleted. (If this is the only part in a message, then a single empty text part is substituted.)
RELABEL	RELABEL=1 will relabel the MIME label to whatever is specified by the Output parameters. Relabel=0 does nothing. Usually relabelling is done on mislabeled parts (example: from Content-type: application/octet-stream to Content-type: application/msword) so users can “doubleclick” to open a part, rather than having to save the part to a file and open it with a program.
SERVICE-COMMAND	SERVICE-COMMAND=command will execute a site-supplied procedure that will operate on entire MIME message (MIME headers and content body part). Also, unlike other CHARSET-CONVERSION operations or conversion channel operations, the service-command are expected to do their own MIME disassembly, decoding, re-encoding, and reassembly. Note that this flag causes an entry to be ignored during conversion channel processing; SERVICE-COMMAND entries are instead performed during character set conversion processing. Use / to specify paths, not \. Example: command="D:/tmp/mybat.bat"
TAG	Input tag, as set by a mail list CONVERSION_TAG parameter.
Information Passing Parameters (Used to pass information to and from the site-supplied program.)
DPARAMETER-SYMBOL-n	Environment variable into which the Content-disposition parameter value, if present, will be stored; n = 0, 1, 2,... Each DPARAMETER-SYMBOL-n is extracted from the Content-Disposition: parameter list in order (n=0 is first parameter, n=2 second, etc.) and placed in the specified environment variable prior to executing the site-supplied program.
PARAMETER-SYMBOL-n	Environment variable into which the Content-Type parameter value, if present, will be stored; n = 0, 1, 2... Each PARAMETER-SYMBOL-n is extracted from the Content-Type: parameter list in order (n=0 is first parameter, n=2 second, etc.) and placed in an environment variable of the same name prior to executing the site-supplied program. Takes as argument the variable name into which the MIME parameter to convert, as matched by an IN-PARAMETER-NAME-n clause.
MESSAGE-HEADER-FILE	Writes all, part, or none of the original header of a message to the file specified by the environmental variable MESSAGE_HEADERS. If set to 1, the original header of the immediately enclosing body part are written to the file specified by the environmental variable MESSAGE_HEADERS. If set to 2, the original header of the message as a whole (the outermost message header) are written to the file.
ORIGINAL-HEADER-FILE	0 or 1. If set to 1, the original header of the enclosing MESSAGE/RFC822 part (not just the body part) are written to the file represented by the environmental variable OUTPUT_HEADERS.
OVERRIDE-HEADER-FILE	0 or 1. If set to 1, then MIME header lines are read by the conversion channel from the environmental variable OUTPUT_HEADERS, overriding the original header lines in the enclosing MIME part.
OVERRIDE-OPTION-FILE	If OVERRIDE-OPTION-FILE=1, the conversion channel reads options from the OUTPUT_OPTIONS environmental variable.
PART-NUMBER	Dotted integers: a. b. c... The part number of the MIME body part.

Character Set Conversion and Message Reformatting

One very basic mapping table in Messaging Server is the character set conversion table. The name of this table is CHARSET-CONVERSION. It is used to specify what sorts of channel-to-channel character set conversions and message reformatting should be done.

On many systems there is no need to do character set conversions or message reformatting and therefore this table is not needed. Situations arise, however, where character conversions must be done.

The CHARSET-CONVERSION mapping table can also be used to alter the format of messages. Facilities are provided to convert a number of non-MIME formats into MIME. Changes to MIME encodings and structure are also possible. These options are used when messages are being relayed to systems that only support MIME or some subset of MIME. And finally, conversion from MIME into non-MIME formats is provided in a small number of cases.

The MTA will probe the CHARSET-CONVERSION mapping table in two different ways. The first probe is used to determine whether or not the MTA should reformat the message and if so, what formatting options should be used. (If no reformatting is specified, the MTA does not bother to check for specific character set conversions.) The input string for this first probe has the general form:

Here in-channel is the name of the source channel (where the message comes from) and out-channel is the name of the destination channel (where the message is going). If a match occurs the resulting string should be a comma-separated list of keywords. Table 11-7 lists the keywords.

Table 11-7 CHARSET-CONVERSION Mapping Table Keywords
Keyword	Description
Always	Force conversion even the message is going to be passed through the conversion channel before going to out-channel.
Appledouble	Convert other MacMIME formats to Appledouble format.
Applesingle	Convert other MacMIME formats to Applesingle format.
BASE64	Switch MIME encodings to BASE64. This keyword only applies to message parts that are already encoded. Messages with Content-transfer-encoding: 7BIT or 8bit do not require any special encoding and therefore this BASE64 option will have no effect on them.
Binhex	Convert other MacMIME formats, or parts including Macintosh type and Mac creator information, to Binhex format.
Block	Extract just the data fork from MacMIME format parts.
Bottom	“Flatten” any message/rfc822 body part (forwarded message) into a message content part and a header part.
Delete	“Flatten” any message/rfc822 body part (forwarded message) into a message content part, deleting the forwarded headers.
Level	Remove redundant multipart levels from message.
Macbinary	Convert other MacMIME formats, or parts including Macintosh type and Macintosh creator information, to Macbinary format.
No	Disable conversion.
QUOTED-PRINTABLE	Switch MIME encodings to QUOTED-PRINTABLE.
Record,Text	Line wrap text/plain parts at 80 characters.
Record,Text= n	Line wrap text/plain parts at n characters.
RFC1154	Convert message to RFC 1154 format.
Top	“Flatten” any message/rfc822 body part (forwarded message) into a header part and a message content part.
UUENCODE	Switch MIME encodings to X-UUENCODE.
Yes	Enable conversion.

Character Set Conversion

If the MTA probes and finds that the message is to be reformatted, it will proceed to check each part of the message. Any text parts are found and their character set parameters are used to generate the second probe. Only when the MTA has checked and found that conversions may be needed does it ever perform the second probe. The input string in this second case looks like this:

The in-channel and out-channel are the same as before, and the in-char-set is the name of the character set associated with the particular part in question. If no match occurs for this second probe, no character set conversion is performed (although message reformatting, for example, changes to MIME structure, may be performed in accordance with the keyword matched on the first probe). If a match does occur it should produce a string of the form:

Here out-char-set specifies the name of the character set to which the in-char-set should be converted. Note that both of these character sets must be defined in the character set definition table, charsets.txt, located in the MTA table directory. No conversion will be done if the character sets are not properly defined in this file. This is not usually a problem since this file defines several hundred character sets; most of the character sets in use today are defined in this file. See the description of the imsimta chbuild (UNIX and NT) utility for further information on the charsets.txt file.

If all the conditions are met, the MTA will proceed to build the character set mapping and do the conversion. The converted message part will be relabelled with the name of the character set to which it was converted.

Message Reformatting

As described above, the CHARSET-CONVERSION mapping table is also used to effect the conversion of attachments between MIME and several proprietary mail formats.

The following sections give examples of some of the other sorts of message reformatting which can be affected with the CHARSET-CONVERSION mapping table.

Non-MIME Binary Attachment Conversion

Mail in certain non-standard (non-MIME) formats; for example, mail in certain proprietary formats or mail from the Microsoft Mail (MSMAIL) SMTP gateway is automatically converted into MIME format if CHARSET-CONVERSION is enabled for any of the channels involved in handling the message. If you have a tcp_local channel then it is normally the incoming channel for messages from a Microsoft Mail SMTP gateway, and the following will enable the conversion of messages delivered to your local users:

Alternatively, to cover every channel you can simply specify OUT-CHAN=* instead of OUT-CHAN=ims-ms. However, this may bring about an increase in message processing overhead as all messages coming in the tcp_local channel will now be scrutinized instead of just those bound to specific channels.

More importantly, such indiscriminate conversions might place your system in the dubious and frowned upon position of converting messages—not necessarily your own site’s—which are merely passing through your system, a situation in which you should merely be acting as a transport and not necessarily altering anything beyond the message envelope and related transport information.

To convert MIME into the format Microsoft Mail SMTP gateway understands, use a separate channel in your MTA configuration for the Microsoft Mail SMTP gateway; for example, tcp_msmail, and put the following in the mappings. file:

Relabelling MIME Headers

Some user agents or gateways may emit messages with MIME headers that are less informative than they might be, but that nevertheless contain enough information to construct more precise MIME headers. Although the best solution is to properly configure such user agents or gateways, if they are not under your control, you can instead ask the MTA to try to reconstruct more useful MIME headers.

If the first probe of the CHARSET-CONVERSION mapping table yields a Yes or Always keyword, then the MTA will check for the presence of a conversions file. If a conversions file exists, then the MTA will look in it for an entry with RELABEL=1 and if it finds such an entry, the MTA will then perform any MIME relabelling specified in the entry.

For example, the combination of a CHARSET-CONVERSION table and MTA conversions file entries such as the following will result in messages that arrive on the tcp_local channel and are routed to the ims-ms channel, and that arrive originally with MIME labelling of application/octet-stream but have a filename parameter with the extension ps or msw, being relabelled as application/postscript or application/msword, respectively. (Note that this more precise labelling is what the original user agent or gateway should have performed itself.)

MacMIME Format Conversions

Macintosh files have two parts, a resource fork that contains Macintosh specific information, and a data fork that contains data usable on other platforms. This introduces an additional complexity when transporting Macintosh files, as there are four different formats in common use for transporting the Macintosh file parts. Three of the formats, Applesingle, Binhex, and Macbinary, consist of the Macintosh resource fork and Macintosh data fork encoded together in one piece. The fourth format, Appledouble, is a multipart format with the resource fork and data fork in separate parts. Appledouble is hence the format most likely to be useful on non-Macintosh platforms, as in this case the resource fork part may be ignored and the data fork part is available for use by non-Macintosh applications. But the other formats may be useful when sending specifically to Macintoshes.

The MTA can convert between these various Macintosh formats. The CHARSET-CONVERSION keywords Appledouble, Applesingle, Binhex, or Macbinary tell the MTA to convert other MacMIME structured parts to a MIME structure of multipart/appledouble, application/applefile, application/mac-binhex40, or application/macbinary, respectively. Further, the Binhex or Macbinary keywords also request conversion to the specified format of non-MacMIME format parts that do nevertheless contain X-MAC-TYPE and X-MAC-CREATOR parameters on the MIME Content-type: header. The CHARSET-CONVERSION keyword Block tells the MTA to extract just the data fork from MacMIME format parts, discarding the resource fork; (since this loses information, use of Appledouble instead is generally preferable).

For example, the following CHARSET-CONVERSION table would tell the MTA to convert to Appledouble format when delivering to the ims-ms channel.

The conversion to Appledouble format would only be applied to parts already in one of the MacMIME formats.

When doing conversion to Appledouble or Block format, the MAC-TO-MIME-CONTENT-TYPES mapping table may be used to indicate what specific MIME label to put on the data fork of the Appledouble part, or the Block part, depending on what the Macintosh creator and Macintosh type information in the original Macintosh file were. Probes for this table have the form format|type|creator|filename where format is one of SINGLE, BINHEX or MACBINARY, where type and creator are the Macintosh type and Macintosh creator information in hex, respectively, and where filename is the filename.

For example, to convert to Appledouble when sending to the ims-ms channel and when doing so to use specific MIME labels for any MS Word or PostScript documents converted from MACBINARY or BINHEX parts, appropriate tables might be:

Note that the template (right hand side) of the mapping entry must have the $Y flag set in order for the specified labelling to be performed. Sample entries for additional types of attachments may be found in the file mac_mappings.sample in the MTA table directory.

If you wish to convert non-MacMIME format parts to Binhex or Macbinary format, such parts need to have X-MAC-TYPE and X-MAC-CREATOR MIME Content-type: parameter values provided. Note that MIME relabelling can be used to force such parameters onto parts that would not otherwise have them.

Service Conversions

The MTA’s conversion service facility may be used to process with site-supplied procedures a message so as to produce a new form of the message. Unlike either the sorts of CHARSET-CONVERSION operations discussed above or the conversion channel, which operate on the content of individual MIME message parts, conversion services operate on entire MIME message parts (MIME headers and content) as well as entire MIME messages. Also, unlike other CHARSET-CONVERSION operations or conversion channel operations, conversion services are expected to do their own MIME disassembly, decoding, re-encoding, and reassembly.

Like other CHARSET-CONVERSION operations, conversion services are enabled through the CHARSET-CONVERSION mapping table. If the first probe of the CHARSET-CONVESION mapping table yields a Yes or Always keyword, then the MTA will check for the presence of an MTA conversions file. If a conversions file exists, then the MTA will look in it for an entry specifying a SERVICE-COMMAND, and if it finds such an entry, execute it. The conversions file entries should have the form:

Of key interest is the command string. This is the command that should be executed to perform a service conversion (for example, invoke a document converter). The command must process an input file containing the message text to be serviced and produce as output a file containing the new message text. On UNIX, the command must exit with a 0 if successful and a non-zero value otherwise.

Environment variables are used to pass the names of the input and output files as well as the name of a file containing the list of the message's envelope recipient addresses. The names of these environment variables are:

The values of these three environment variables may be substituted into the command line by using standard command line substitution: that is, preceding the variable's name with a dollar character on UNIX.

Using Brightmail

Brightmail Inc. is a company that provides an anti-spam and anti-virus software solution for email servers. The Brightmail solution consists of the Brightmail server along with realtime anti-spam and anti-virus rule updates downloaded to email servers. See "The Conversion Channel" for another method of integrating anti-virus software into your system.

How Brightmail Works

The Brightmail server is deployed at a customer site. Brightmail has email probes set around the internet for detection of new spam. Brightmail technicians create custom rules to block this spam in realtime. These rules are downloaded to Brightmail servers, also in realtime. The Brightmail database is updated and Brightmail server runs this database filter against the email for the specified users or domains.

Brightmail Architecture

When the Brightmail Logistics and Operations Center (BLOC) receives spam from email probes, operators immediately create appropriate anti-spam rules, which are downloaded to Brightmail customer machines. Similarly, the Symantec Security Response realtime virus rules are also sent from Brightmail. These rules are used by customer’s Brightmail servers to catch spam and viruses.

The MTA uses the Brightmail SDK to communicate with the Brightmail Server. The MTA dispatches messages based on the response back from Brightmail. After the mail (1a) or (1b) is received by the MTA, the MTA sends the message to the Brightmail server (2). The Brightmail server uses its rules and data to determine if the message is a spam or virus (3), and returns a verdict back to the MTA. Based on the verdict, the MTA either (4a) discards the message or files the message into a folder, or (4b) delivers it normally to the destination.

Since the Brightmail SDK is third party software, we do not include it in our installation kit. The Brightmail SDK and server software must be obtained from Brightmail Inc. The MTA has configuration settings to tell it whether and where to load the Brightmail SDK to enable Brightmail integration.

Once the SDK is loaded, Brightmail message processing is determined by several factors and levels of granularity (the term used by Brightmail to specify active processing is optin). This is specified by the following criteria:

For any particular message recipient, the optins and defaults above are combined, which means, if the channel default is already specified for both spam and virus, then there is no reason to bother with per-user optin. That is, if the system administrator decides to do spam and virus filtering for everyone, then there is no reason to expose to the user the ability to optin for spam or virus. There is no way to opt out of processing, that is, you can not say you do not want the service if a user is already optin. This also means that if you are optin for a service, and you have forwarded your mail to another address, that address would get the mail after the filtering has been performed on your behalf.

There are only two services offered, virus or spam detection. Brightmail also provides “content-filtering” service, but this functionality is provided using Sieve, so there is no added value to have Brightmail do the Sieve filtering.

When a message is determined to contain a virus, the Brightmail server can be configured to clean the virus and resubmit the cleaned message back to the MTA. (Due to some undesirable side effects caused by loss of information about the original message in a resubmitted cleaned message, we recommend you do not configure Brightmail to resubmit the cleaned message back to the MTA.) When the message is spam, the verdict back from the Brightmail along with the configuration in Brightmail allows the MTA to determine what happens to the message. Basically, three things can happen, either the message is discarded, it is filed into a folder, or it is delivered normally in the INBOX.

The Brightmail servers can be located on the same system as the MTA, or it can be on a separate system. In fact, you can have a farm of Brightmail servers serving one or more MTAs. The Brightmail SDK uses the Brightmail configuration file to determine which Brightmail server to use. It is not something with which the MTA must handle.

Brightmail Requirements and Performance Considerations

Deploying Brightmail

This section describes how to deploy Brightmail for the following configurations:

Brightmail filtering is enabled in Messaging Server using the keywords or an LDAP attribute. The method of filtering on the system is additive. That is, it is the combination of both keywords and the attribute.

To Activate Brightmail Processing for All Users on a Destination or Source Channel

Examples

Example 1 - mail going into the tcp_siroemail channel will be filtered by Brightmail for spam and viruses:

Example 2, mail coming from the tcp_local channel will be filtered by the Brightmail for spam:

To Activate Brightmail Processing for Selected Users

Example

Assume that LDAP_OPTIN was set to mailAntiUBEService in the option.dat file. If the user, Otis Fanning, has the mailAntiUBEService attribute set to spam and virus in his user entry, then his mail will be filtered by Brightmail for spam and viruses. Code Example 11-2 shows the Brightmail enabled user entry for Otis Fanning.

To Activate Brightmail Processing for Selected Domains on a System

Example

Assume that LDAP_DOMAIN_ATTR_OPTIN was set to mailAntiUBEService in the option.dat file. The mailAntiUBEService attribute is set to spam and virus in the example.com domain entry in the DC tree. Code Example 11-3 shows the Brightmail-enabled domain entry.

Brightmail Options and Keywords

Table 11-8and Table 11-9 show the Messaging Server’s Brightmail options and keywords. Selected Brightmail configuration file options are shown in Table 11-10. The latest and complete listing of Brightmail configuration file options can be obtained from Brightmail.

Table 11-8 Brightmail MTA Options (option.dat)
Option	Description and Default
Brightmail_library	Required to activate Brightmail. Full file path and name of the Brightmail SDK shared library. When specified along with Brightmail_config_file, this library is loaded by the MTA at run time. Can also be used with SpamAssassin. Example: /opt/mailwall/lib/libbmiclient.so Default: None
Brightmail_config_file	Required to activate Brightmail. Full file path and name of the Brightmail configuration file. When specified along with Brightmail_library, the MTA is enabled for Brightmail integration. Can also be used with SpamAssassin. Example: /opt/mailwall/config Default: None
LDAP_optin (used to be LDAP_SPARE_2 in previous release)	The name of the LDAP attribute used to activate Brightmail on a per-user basis. This should be an attribute in the inetMailUser objectclass. If you do not have another predefined attribute, use mailAntiUBEService. The attribute itself (example: mailAntiUBEService) is multi-valued, case-sensitive. Its value could be either spam or virus in lowercase. If the user is opting for both, then he would have two such attributes, one containing spam, one containing virus. Default: none
LDAP_domain_attr_optin	The name of the LDAP attribute used to activate Brightmail on a per-domain basis. It applies to the destination domain. It is just like LDAP_optin above except it should be in the objectclass mailDomain. Default: none
Brightmail_verdict_n	Brightmail_verdict_n and Brightmail_action_n are matched pairs, where n is a number from 0 to 9. These options are not normally specified if you take the default interpretation of Brightmail verdicts. The possible values for this option are specified by the values on the right of the \| in the Brightmail configuration file options blSWClientDestinationLocal (for local domains) or blSWClientDesintationForeign (for domains that are not local). Using the example: blSWClientDestinationLocal=spam\|spamfolder you would want to have Brightmail_verdict_0=spamfolder (not spam, which is to the left of \|. This may seem non-intuitive, but that is indeed how it works. Default: none
Brightmail_null_action	Specifies a Sieve command with optional if-then-else statement* to execute when the verdict from Brightmail matches the Null action in the Brightmail configuration file. For example, if the Brightmail configuration file has: blSWClientDestinationLocal: spam\| where the null or nothing after the \| means the null action. If the verdict for the message is spam, matching the word spam before the \|, then the null action will be taken by the MTA. There is usually no reason to specify this option, since the default action is discard, matching what Brightmail means by the null action. The template for the Sieve command is: data:,[require “command”;] command; Where the require statement is needed for reject and fileinto. Default: data:,discard;
Brightmail_action_n	As a pair with the matching Brightmail_verdict_n option, this can specify a Sieve command with optional if-then-else statement* to execute. For example, if you want to reject spam, then you may have the pair: Brightmail_verdict_0=spamfolder Brightmail_action_0=data:,require "reject"; reject "Rejected by Brightmail"; The template for the Sieve command is: data:,[require “command”;] command; Where the require statement is needed for reject and fileinto. Another example: Brightmail_verdict_1=spam-folder Brightmail_action_1_=data;,require "fileinto";fileinto "Junk"; This files the spam (assuming spam-folder is the verdict returned by Brightmail for spam) into a folder called Junk. Without Junk, spam will be filed into the folder called spam-folder. Default: none
Brightmail_optional	If set to 1, when the MTA calls an initialization routine to load the Brightmail SDK, but fails, the MTA continues as if Brightmail was not enabled. This setting has no effect if the MTA is already in a dialogue with Brightmail and Brightmail dies. In this case the MTA returns a temporary error to the SMTP client. Default: 0
Brightmail_string_action	Specifies a Sieve command with optional if-then-else statement* to execute when the Brightmail verdict matches an action which is a string in the Brightmail configuration file. For example, if in the Brightmail configuration file you have blSWClientDestinationLocal: spam\|spam-folder then spam-folder is a string. If the verdict is spam, then we have a string which matches the verdict. This option is rarely used, since the default action when a string is specified is to file the message into that folder. The template for the Sieve command is: data:,[require “command”;] command; Where the require statement is needed for reject and fileinto. Default: data:,require "fileinto"; fileinto "$U”; $U is the string to the right of \| in the blSWClientDestinationLocal value (in the example above it would be spam-folder)

* Here is a Sieve example of an optional if-then-else statement in option.dat. Note that this can be used for Brightmail_action_n, Brightmail_null_action, or Brightmail_string_action.

Table 11-9 MTA Channel Keywords for Brightmail
Channel Keyword	Description
sourcebrightmail	Specifies that all messages originating from this channel receive Brightmail processing. All recipient addresses will be made known to Brightmail regardless of destination channel if the recipient or the recipient’s domain has opted in via the LDAP attribute. Looks at recipient’s LDAP attribute mailAntiUBEService (or equivalent) to determine whether spam, virus or both or none are filtered. If mailAntiUBEService doesn’t specify either spam or virus, then mail is not sent to the Brightmail server for filtering. This should be placed on the switched-to channel, if switchchannel is in effect. Syntax: sourcebrightmail
destinationbrightmail	Specifies that all messages destined to this channel be subject to Brightmail processing if the recipient has opted in via the LDAP attribute mailAntiUBEService (or equivalent). Syntax: destinationbrightmail
destinationbrightmailoptin	Specifies that all messages destined to this channel will be subject to the specified brightmail processing (either spam or virus or both) even if those services have not been opted in by the user or domain via the LDAP attribute. The filter list follows the keyword. The list following must be either spam or virus or spam,virus or virus,spam. Example 1: ims-ms destinationbrightmailoptin spam,virus. . . All mail destined for the message store is scanned for both spam and virus by Brightmail
sourcebrightmailoptin	Specifies that all messages originating from this channel will be subject to the specified brightmail processing (either spam or virus or both) even if those services have not been opted in by the user or domain via the LDAP attribute.The system-wide default filter list follows the keyword. The list following must be either spam or virus or spam,virus or virus,spam. This should be placed on the switched-to channel, if switchchannel is in effect. Example 1: tcp_local sourcebrightmailoptin spam,virus . . . Specifies that mail be scanned for both spam and virus by Brightmail regardless of the user’s LDAP attribute. Example 2: tcp_local sourcebrightmailoptin virus . . . Specifies that mail will default to only virus scanning. In this case, spam filtering can be enabled on a per user basis, or by destination domain via the LDAP attributes.

Table 11-10 Selected Brightmail Configuration File Options
Brightmail Option (Not Case-sensitive)	Description (value of the attributes are case-sensitive)
blSWPrecedence	A given message can have multiple verdicts. This specifies the precedence order. So if a message is processed for virus first, then for spam if you specified this option as virus-spam the verdicts are separated by hyphens (-). This is the recommended setting when using Brightmail with Sun ONE Messaging Server.
blSWClientDestinationDefault	Specifies how to deliver normal messages, that is, not a spam or virus, and thus have no verdict. Usually you want to deliver this message normally, so you would specify inbox as the value. There is no default.
blSWLocalDomain	This attribute specifies what domain(s) are considered to be local. There can be multiple lines of this attribute specifying several domains which are all considered local. Local versus foreign domain is used to specify two different handling for a verdict. See below blSWClientDestinationLocal and blSWClientDestinationForeign. For example, you can specify blSWLocalDomain=siroe.com
blSWClientDestinationLocal	This specifies the verdict and action pair for the local domain. You would normally have two lines for this, one for spam and one for virus. The value is of the form verdict\|action, For example, blSWClientDestinationLocal=spam\|spambox blSWClientDestinationLocal=virus\| The default Brightmail interpretation for the “null” action, meaning nothing to the right of the \|, is to discard the message. So the example above discards the message if it has a verdict of virus. And if the verdict is spam, the above example files the message into the folder called spambox. If the message is not spam or virus, then the verdicts do not match, and the mail is delivered normally based on what’s set in the blSWClientDestinationDefault setting above. When using a separate Brightmail server or servers from the MTA, you can customize the actions taken by each MTA by using the Brightmail_verdict_n/Brightmail_action_n/Brightmail_null_action/Brightmail_string_action MTA options to override the actions and verdicts returned by the Brightmail server. In this example, you can use different Brightmail_null_action on the MTA to override the Virus action (which would be to discard it) or to use Brightmail_verdict_0=spambox, and Brightmail_action_0=data:,require "fileinto";fileinto "Junk"; to file into a folder called Junk instead of spambox.
blSWClientDesintationForeign	Same format and interpretation as blSWClientDestinationLocal above, except this applies to users in the domain which are NOT local.
blSWUseClientOptin	Always set this to TRUE when used with Sun ONE Messaging Server.
blswcServerAddress	Is of the form ip:port[,ip:port,...] to specify one or more Brightmail server’s IP address and port numbers

Common Brightmail Deployment Scenarios

There are several common deployment Brightmail scenarios that are discussed in this section. These are:

Brightmail Processing on Local Incoming Messages

You may wish to configure your system so that all mail delivered locally is screened for spam and viruses. To set up Brightmail processing of all incoming messages to the local message store (that is, to the ims-ms channel in imta.cnf), add the destinationbrightmailoptin keyword to the ims-ms channel definition. Example:

ims-ms defragment subdirs 20 backoff “pt5m” “pt10” “pt30” “pt1h” \
“pt2h” “pt4h” maxjobs 1 pool IMS_POOL fileinto $U+$S@$D filter \
ssrd:$A ims-ms-daemon destinationbrightmailoptin spam,virus
ims-ms-daemon

Brightmail Processing on Incoming Messages from the Internet

You may wish to configure your system so that all mail coming from the internet is screened for spam. To set up Brightmail processing of all incoming messages from the internet, add the sourcebrightmailoptin keyword to the tcp-local channel definition. Example:

tcp_local smtp mx single_sys remotehost inner switchchannel \
identnonelimited subdirs 20 maxjobs 7 pool SMTP_POOL maytlsserver \
maysaslserver saslswitchchannel tcp_auth sourcebrightmailoptin spam
tcp-daemon

Brightmail Processing on Outgoing Messages to the Internet

You may wish to configure your system so that all mail going to the internet is screened for spam. To set up Brightmail processing of all outgoing messages to the internet, add the destinationbrightmailoptin keyword to the tcp-local channel definition on the outgoing MTA. Example:

Brightmail Processing on Incoming Messages to a Specific Backend Message Store Host

To configure your system so that all mail coming into a specific backend message store host is screened for virus and spam, do the following:

Adding a Header to Spam Messages

You can add an arbitrary header to a spam message. To add the header spam-result: Brightmail says this is spam to a message caught by Brightmail software, add the following to option.dat:

brightmail_string_action=data:,require ["addheader" "spamtest"];addheader "spam-result: Brightmail says this is spam";

Using SpamAssassin

Messaging Server supports the use of SpamAssassin, a freeware mail filter used to identify spam. SpamAssassin consists of a library written in Perl and a set of applications and utilities that can be used to integrate SpamAssassin into messaging systems.

SpamAssassin calculates a score for every message. Scores are calculated by performing a series of tests on message header and body information. Each test either succeeds or fails, and the score is adjusted accordingly. Scores are real numbers and may be positive or negative. Scores that exceed a certain threshold (typically 5.0) are considered to be spam.

SpamAssassin is highly configurable. Tests may be added or removed at any time and the scores of existing tests may be adjusted. This is all done through various configuration files. Further information on SpamAssassin can be found on the SpamAssassin Web site.

The same mechanism used for calling out to the Brightmail spam and virus scanning library can be used to connect to the SpamAssassin spamd server. The module provided in Sun ONE Messaging Server is called libspamass.so.

SpamAssassin Requirements and Performance Considerations

Deploying SpamAssassin

This section provides step-by step instructions for deploying SpamAssassin on Messaging Server.

spamd -d

spamd defaults to only accepting connections from the local system. If SpamAssassin and Messaging Server are running on different systems you will require a command of the form:

spamd -d -i <listen_ip_address> -A <allowed_hosts>

where listen_ip_address is the address on which to listen and allowed_hosts is a list of authorized hosts or networks (using IP addresses) which can connect to this spamd instance.

Table 11-11 SpamAssassin Options
Spam Assassin Options	Description	Default
host	The name of the system where spamd is running	localhost
port	Port number where spamd listens for incoming requests.	783
debug	0 or 1. Specifies whether to turn on debugging in the libspamass.so. Debugging of spamd itself is controlled by the command line invoking spamd.	0
mode	Controls the translation of SpamAssassin results to Brightmail verdict information. Three different modes are available: 0 - Return the verdict string specified by the verdict option if the message is found to be spam; return a default SpamAssassin verdict if it is not. A null verdict is returned if the verdict option is empty or unspecified. 1 - Return the SpamAssassin result as a verdict if the message is found to be spam. 2- Same as mode 1 except that the verdict is returned regardless of whether or not the message is seen as spam.	0
verdict	A string, specifying the verdict string used for MODE 0	“”
field	A string specifying the SpamAssasin result string prefix. SpamAssassin result strings generally look like: Spam-Test: False ; 0.0 / 5.0 or Spam-Test: True ; 27.7 / 5.0 The field option provides the means for changing the “Spam-Test” part of the result. Note that the “: “ will also be removed if an empty field value is specified.	“Spam-test”


Note	Brightmail allows you to either discard spam messages, or save them in a designated spam folder. If the ability to designate a spam folder is not available for the receiving system, then the address syntax for the spam folder will be meaningless to that system.

MTA Options for Spam Assassin	Description	Default
Brightmail_library	Full file path and name of the SpamAssassin shared library.	None
Brightmail_config_file	Full file path and name of the SpamAssassin configuration file.	None
Brightmail_null_action	SIEVE rule specifying what to do with the message when the SpamAssassin verdict returns as null.	data:,discard;
Brightmail_string_action	SIEVE rule specifying what to do with the message if the verdict is a string. Default: data:,require "fileinto"; fileinto "$U; $U is the string verdict returned.	See description