Sun Java System Messaging Server 6 2005Q4 Administration Reference

Conversions

There are two broad categories of conversions in the MTA, controlled by two corresponding mapping tables and the MTA conversions file.

The first category is that of character set, formatting, and labelling conversions performed internally by the MTA. The application of such conversions is controlled by the CHARSET-CONVERSION mapping table.

The second category is that of conversions of message attachments using external, third-party programs and site-supplied procedures, such as document converters and virus scanners. The application of such conversions is controlled by the CONVERSIONS mapping table, and messages requiring such conversions are thereby routed through the MTA conversion channel, which in turn executes the site-specified external conversion procedure.

The MTA conversions file is used to specify the details of external CONVERSION table triggered conversions and to specify the details of some internal CHARSET-CONVERSION table triggered conversions.

Character Set Conversion and Message Reformatting Mapping

One very basic mapping table in the MTA 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 performed.

The MTA probes 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:

IN-CHAN=in-channel;OUT-CHAN=out-channel;CONVERT

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. The keywords provided are listed in Table 4–10.

Table 4–10 CHARSET-CONVERSION Mapping Table Keywords


Keyword	Description
`Always`	Force conversion even when 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.
`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.

For more information on character set conversion and message reformatting mapping, see the Sun Java System Messaging Server 6 2005Q4 Administration Guide.

Conversion File

Configuration of the conversion channel in the MTA configuration file (imta.cnf) is performed by default. With the rewrite rules from the default configuration, an address of the form user@conversion.localhostname or user@conversion is routed through the conversion channel, regardless of what the CONVERSIONS mapping states.

The actual conversions performed by the conversion channel are controlled by rules specified in the MTA conversion file. This is the file specified by the IMTA_CONVERSION_FILE option in the MTA tailor file. By default, this is the file msg_svr_base/imta/conversions.

The MTA conversion file is a text file containing entries in a format that is modeled after MIME Content-Type parameters. Each entry consists of one or more lines grouped together; each line contains one or more name=value; parameter clauses. Quoting rules conform to MIME conventions for Content-Type header line parameters. Every line except the last must end with a semicolon (;). A physical line in this file is limited to 1024 characters. You can split a logical line into multiple physical lines using the backslash (\) continuation character. Entries are terminated either by a line that does not end in a semicolon, one or more blank lines, or both.

The rule parameters currently provided are shown in Table 4–11. Parameters not listed in the table are ignored.

Table 4–11 Conversion Parameters


Parameter	Description
`COMMAND`	Command to execute to perform conversion. This parameter is required; if no command is specified, the entry is ignored.
`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.)
`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.
`DPARAMETER-SYMBOL-n`	Content-disposition parameters to convert to environment variables if present; `n` = 0, 1, 2, .... Takes as argument the name of the MIME parameter to convert, as matched by an `IN-DPARAMETER-NAME-m` clause. Each `DPARAMETER-SYMBOL-n` is extracted from the Content-Disposition: parameter list and placed in an environment variable prior to executing the site-supplied program.
`IN-A1-FORMAT`	Input A1-format from enclosing message/rfc822 part.
`IN-A1-TYPE`	Input A1-type from enclosing message/rfc822 part.
`IN-CHAN`	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-CHANNEL`	Synonym for `IN-CHAN`.
`IN-DESCRIPTION`	Input MIME Content-Description to match for conversion.
`IN-DISPOSITION`	Input MIME Content-Disposition to match for conversion.
`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-DPARAMETER-NAME-n`	Input MIME Content-Disposition parameter name whose value is to be checked; `n` = 0, 1, 2....
`IN-DPARAMETER-VALUE-n`	Input MIME Content-Disposition parameter value that must match corresponding `IN-DPARAMETER-NAME` (wildcards allowed). 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.
`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-PARAMETER-NAME-n`	Input MIME Content-Type parameter name whose value is to be checked; `n` = 0, 1, 2....
`IN-PARAMETER-VALUE-n`	Input MIME Content-Type parameter value that must match corresponding `IN-PARAMETER-NAME` (wildcards allowed). 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.
`IN-SUBJECT`	Input Subject from enclosing `MESSAGE/RFC822` 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-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.
`MESSAGE-HEADER-FILE`	Writes all, part, or none of the original headers of a message to the file specified by `MESSAGE_HEADERS`. If set to 1, the original headers of the immediately enclosing message part are written to the file specified by `MESSAGE_HEADER`. If set to 2, the original headers of the message as a whole (the outermost message headers) are written to the file.
`ORIGINAL-HEADER-FILE`	0 or 1. If set to 1, the original headers of the enclosing `MESSAGE/RFC822` part are written to the file represented by the `OUTPUT_HEADERS` symbol.
`OUT-CHAN`	Output channel to match for conversion (wildcards allowed). The conversion specified by this entry is performed only if the message is destined for the specified channel.
`OUT-CHANNEL`	Synonym for `OUT-CHAN`.
`OUT-DESCRIPTION`	Output MIME Content-Description if it is different than the input MIME Content-Description.
`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`.
`OUT-MODE`	Mode in which to read and store the converted file. This should be one of: `BLOCK` (binaries and executables) or `TEXT`.
`OUT-ENCODING`	Encoding to apply to the converted file when the message is reassembled.
`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`.
`OUT-SUBTYPE`	Output MIME type if it is different than the input MIME type.
`OUT-TYPE`	Output MIME type if it is different than the input type.
`OVERRIDE-HEADER-FILE`	0 or 1. If set, then MIME headers are read from the `OUTPUT_HEADERS` symbol, overriding the original headers in the enclosing MIME part.
`OVERRIDE-OPTION-FILE`	If set, the conversion channel reads options from the `OUTPUT_OPTIONS` environment variable.
`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... Takes as argument the name of the MIME parameter to copy, as matched by an `IN-PARAMETER-NAME-n` clause.
`PARAMETER-SYMBOL-n`	Content-Type parameters to convert to environment variables if present; `n` = 0, 1, 2... Takes as argument the name of the MIME parameter to convert, as matched by an `IN-PARAMETER-NAME-n` clause. Each `PARAMETER-SYMBOL-n` is extracted from the Content-Type: parameter list and placed in an environment variable of the same name prior to executing the site-supplied program. Takes as the argument the variable name into which the MIME parameter to convert, as matched by an `IN-PARAMETER-NAME-n` clause.
`PART-NUMBER`	Dotted integers: `a. b. c`... The part number of the MIME body part.
`RELABEL`	0 or 1. This flag causes an entry to be ignored during conversion channel processing. However, if this flag is 1, then MIME header enabling is performed during character set conversions.
`SERVICE-COMMAND`	The command to execute to perform service conversion. The COMMAND parameter is required for conversion channel processing while SERVICE-COMMAND is an optional feature of charset conversion processing; if no command is specified, the entry is ignored. 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.
`TAG`	Input tag, as set by a mail list `CONVERSION_TAG` parameter.

Predefined Environment Variables

Table 4–12 shows the basic set of environment variables available for use by the conversion command.

Table 4–12 Environment Variables used by the Conversion Channel


Environment Variable	Description
`ATTACHMENT_NUMBER`	Attachment number for the current part. This has the same format as the `ATTACHMENT-NUMBER` conversion match parameter.
`CONVERSION_TAG`	Current list of active conversion tags. This variable corresponds to the `TAG` conversion parameter.
`INPUT_CHANNEL`	Channel that enqueued the message to the conversion channel. This variable corresponds to the `IN-CHANNEL` conversion parameter.
`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 headers for the enclosing 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 headers 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_CHANNEL`	Channel to which the message is headed. This variable corresponds to the `IN-CHANNEL` conversion parameter.
`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 header lines (not `option=value` lines) followed by a blank line as its final line.
`OUTPUT_OPTIONS`	Name of the file from which the site-supplied program should read conversion channel options. Note that file should include header lines, followed by a blank line as its final line.
`PART_NUMBER`	Part number for the current part. This has the same format as the `PART-NUMBER` conversion match parameter.
`PART_SIZE`	Size in bytes of the part being processed.

Additional environment variables containing Content-type: parameter information or Content-disposition: parameter information can be created as needed using the PARAMETER-SYMBOL-n or DPARAMETER-SYMBOL-n parameters respectively.

Table 4–13 displays additional override options available for use by the conversion channel. The converter procedure may use these to pass information back to the conversion channel. To set these options, set OVERRIDE-OPTION-FILE=1 in the desired conversion entry and then have the converter procedure set the desired options in the OUTPUT_OPTIONS file.

Table 4–13 Options for passing information back to the conversion channel


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 in the error text returned to the message 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/bin/msg/imtasdk/include/pmdf_err.h`