CONVERSIONS mapping table

From Messaging Server Technical Reference Wiki
Jump to: navigation, search


Although conversion processing is done using a regular MTA channel program, under normal circumstances this channel is never specified directly either in an address or in an MTA rewrite rule. Instead, the MTA controls routing to the conversion channel via the CONVERSIONS mapping table.

In legacy configuration, the CONVERSIONS mapping table (like all mapping tables), was stored in the mappings file. In Unified Configuration, the CONVERSIONS mapping table is stored as the settings under either a role.mapping:CONVERSIONS option or a instance.mapping:CONVERSIONS option. In Unified Configuration, most often creation or modification of such a CONVERSIONS mapping table is performed using the edit command of the msconfig utility, to edit any or all mapping tables in a format like the legacy mappings file; e.g.:


msconfig> edit mappings

Or from within msconfig the CONVERSIONS mapping table can be created line-by-line:


msconfig> set mapping:CONVERSIONS.rule "IN-CHAN=tcp_local;OUT-CHAN=ims-ms;CONVERT" Yes
msconfig# set mapping:CONVERSIONS.rule "IN-CHAN=ims-ms;OUT-CHAN=tcp_local;CONVERT" Yes
msconfig# set mapping:CONVERSIONS.rule * No

Note that CONVERSIONS mapping rules often include a special character such as the equal sign, =, in either or both of the pattern (left hand side of the rule) or template (right hand side of the rule), thus often require quoting of pattern and/or template when being set at the msconfig command line.

As the MTA processes each message it probes the CONVERSIONS mapping (if one is present) with a string of the default form


IN-CHAN=source-channel;OUT-CHAN=destination-channel;CONVERT 

where source-channel is the source channel from which the message is coming and destination-channel is the destination channel to which the message is heading. New in MS 6.3, setting bit 1 (value 2) of the include_conversiontag MTA option will cause the probe to instead have the form


IN-CHAN=source-channel;OUT-CHAN=destination-channel;TAG=tag-list;CONVERT 

where tag-list is a comma-separated list of any conversion tags present on the message. Note that multiple conversion tags may be present; multiple tags will be included as a comma-separated list. The total, combined length of such tags (that is, the length of the list, including the commas) is limited to 256 characters. (As with all mapping tables, the overall probe length is limited to 1024 characters.)

New in the 8.0 release, setting bit 6 (value 64) of the include_mtpriority MTA option will cause an additional, compound field to be appended to the CONVERSIONS mapping table probe, immediately after any "TAG=" clause.

New in the 8.0.2.3 release, setting bit 0 (value 1) of the include_domain MTA option will casue an additiona field to be appended to the CONVERSIONS mapping table probe containing the destination domain for the current set of recipients, immediately after any "MTPRIORITY=" and "BLOCKS=" clauses.

If the probe matches the pattern (left hand side) of a CONVERSIONS mapping table entry, then the resulting string (right hand side of the mapping entry) should be a comma-separated list of keywords. Usually either just the keyword "Yes" or "No" is specified. If "Yes" is produced, the MTA will divert the message from its regular destination to the conversion channel. (By also specifying Channel=channel-name, the message can be diverted to some alternate channel rather than to the regular conversion channel.) If the message has a conversion tag set, note that the "T" flag will be set, and this can be tested for (when a match on the pattern, i.e., left hand side, occurred) using a $:T test in the template (right hand side) output string. If either "No" is produced or no match is found, the message will be queued to the regular destination channel.

Some less commonly used, additional template keywords, similar to those available for the CHARSET-CONVERSION mapping table, are also available as shown below.

Additional CONVERSIONS mapping keywords
Keyword Action
Always Force conversion even when the "conversion" channel is the same as the source channel; while not desirable when the actual conversion channel (or any other "intermediate channel") is being used, "Always" can be useful when an "alternate conversion channel", specified via a "Channel=channel-name" clause, is used to select some other sort of channel, such as a tcp_* 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
Channel=channel-name Route through the alternate channel channel-name rather than the regular conversion channel
Delete "Flatten" any message/rfc822 body part (forwarded message) into a message content part, deleting the forwarded headers
dkimidentity-N=identity New in MS 8.0.2.3. Activate DKIM signing in slot N using using the specified identity. See the description of the destinationdkimidentityN channel option for additional information on the value's semantics. At present only two slots are available so N must be either 0 or 1. This template keyword also clears the corresponding selector value, which can subsequently be set with the dkimselector-N template keyword.
dkimselector-N=selector New in MS 8.0.2.3. Specifies the selector list for DKIM slot N. See the description of the destinationdselectorN channel option for additional information on the value's semantics. At present only two slots are available so N must be either 0 or 1. This template keyword must be specified after the corresponding dkimidentity-N template keyword.
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
Pathworks Convert message to Pathworks Mail format
Preprocess (New in MS 6.3) Perform any configured charset conversion  before routing to the conversion channel
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
Thurman Convert some non-standard "attachments" to MIME 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 example, suppose messages coming in from the Internet and destined to the Message Store via either an ims-ms or tcp_lmtpcs* channel require conversion processing. The following mapping would then be appropriate:


CONVERSIONS 
 
  IN-CHAN=tcp_local;OUT-CHAN=ims-ms;CONVERT          Yes 
  IN-CHAN=tcp_local;OUT-CHAN=tcp_lmtpcs*;CONVERT     Yes 
  IN-CHAN=*;OUT-CHAN=*;CONVERT                       No 

In Unified Configuration, msconfig's edit command could show the CONVERSIONS mapping as above. Alternatively,


msconfig> show mapping:CONVERSIONS.*
role.mapping:CONVERSIONS.rule = IN-CHAN=tcp_local;OUT-CHAN=ims-ms;CONVERT Yes 
role.mapping:CONVERSIONS.rule = IN-CHAN=tcp_local;OUT-CHAN=tcp_lmtpcs*;CONVERT Yes 
role.mapping:CONVERSIONS.rule = IN-CHAN=*;OUT-CHAN=*;CONVERT No 

See also: