Chapter 11 Configuring Rewrite Rules

This chapter describes how to configure rewrite rules in the imta.cnf file. If you have not already read Chapter 10, About MTA Services and Configuration,” you should do so before reading this chapter.

This chapter contains the following sections:

• 11.1 Before You Begin

• 11.2 Rewrite Rule Structure

• 11.3 Rewrite Rule Patterns and Tags

• 11.4 Rewrite Rule Templates

• 11.5 How the MTA Applies Rewrite Rules to an Address

• 11.6 Template Substitutions and Rewrite Rule Control Sequences

• 11.7 Handling Large Numbers of Rewrite Rules

• 11.8 Testing Rewrite Rules

• 11.9 Rewrite Rules Example

Messaging Server’s address rewriting facility is the primary facility for manipulating and changing the host or domain portion of addresses. Messaging Server provides other facilities for address manipulation, such as aliases, the address reversal database, and specialized mapping tables. For best performance, however, rewrite rules should be used whenever possible to perform address manipulations.

11.1 Before You Begin

When you make changes to rewrite rules in the imta.cnf file, you must restart any programs or channels that load the configuration data only once when they start up, for example, the SMTP server, by using the imsimta restart command. If you are using a compiled configuration, you must recompile and then restart.

For more information about compiling configuration information and starting programs, see the Sun Java System Messaging Server 6.3 Administration Reference.

11.2 Rewrite Rule Structure

Rewrite rules appear in the upper-half of the MTA configuration file, imta.cnf. Each rule in the configuration file appears on a single line. Comments, but not blank lines, are allowed between the rules. The rewrite rules end with a blank line, after which the channel definitions follow. The example below shows the rewrite rule section of a partial configuration file.

! test.cnf - An example configuration file.
!
! This is only an example of a configuration file. It serves
! no useful purpose and should not be used in a real system.
!
a.com   $U@a-host
b.org   $U@b-host
c.edu   $U%c@b-daemon
d.com   $U%d@a-daemon

! Begin channel definitions

Rewrite rules consist of two parts: a pattern, followed by an equivalence string or template. The two parts must be separated by spaces, although spaces are not allowed within the parts themselves. The structure for rewrite rules is as follows:

pattern template

pattern

Indicates the string to search for in the domain name. In Table 11–3 the patterns are a.com, b.org, c.edu, and d.com.

If the pattern matches the domain part of the address, the rewrite rule is applied to the address. A blank space must separate the pattern from the template. For more information about pattern syntax, see 11.3 Rewrite Rule Patterns and Tags

template

is one of the following:

UserTemplate%DomainTemplate@ChannelTag[controls]
UserTemplate@ChannelTag[controls]
UserTemplate%DomainTemplate[controls]
UserTemplate@DomainTemplate@ChannelTag[controls]
UserTemplate@DomainTemplate@SourceRoute@ChannelTag[controls]

where

UserTemplate specifies how the user part of the address is rewritten. Substitution sequences can be used to represent parts of the original address or the results of a database lookup. The substitution sequences are replaced with what they represent to construct the rewritten address. In Table 11–4, the $U substitution sequence is used. For more information, see 11.6 Template Substitutions and Rewrite Rule Control Sequences

DomainTemplate specifies how the domain part of the address is rewritten. Like the UserTemplate, the DomainTemplate can contain substitution sequences.

ChannelTag indicates the channel to which this message is sent. (All channel definitions must include a channel tag as well as a channel name. The channel tag typically appears in rewrite rules, as well as in its channel definition.)

controls. The applicability of a rule can be limited using controls. Some control sequences must appear at the beginning of the rule; other controls must appear at the end of the rule. For more information about controls, see 11.6 Template Substitutions and Rewrite Rule Control Sequences

For more information about template syntax, see 11.4 Rewrite Rule Templates

11.3 Rewrite Rule Patterns and Tags

This section consists of the following subsections:

• 11.3.1 A Rule to Match Percent Hacks

• 11.3.2 A Rule to Match Bang-Style (UUCP) Addresses

• 11.3.3 A Rule to Match Any Address

• 11.3.4 Tagged Rewrite Rule Sets

Most rewrite rule patterns consist either of a specific host name that will match only that host or of a subdomain pattern that will match any host/domain in the entire subdomain.

For example, the following rewrite rule pattern contains a specific host name that will match the specified host only:

host.siroe.com

The next rewrite rule pattern contains a subdomain pattern that will match any host or domain in the entire subdomain:

.siroe.com

This pattern will not, however, match the exact host name siroe.com; to match the exact host name siroe.com, a separate siroe.com pattern would be needed.

The MTA attempts to rewrite host/domain names starting from the specific host name and then incrementally generalizing the name to make it less specific. This means that a more specific rewrite rule pattern will be preferentially used over more general rewrite rule patterns. For example, assume the following rewrite rule patterns are present in the configuration file:

hosta.subnet.siroe.com
.subnet.siroe.com
.siroe.com

Based on the rewrite rule patterns, an address of jdoe@hosta.subnet.siroe.com will match the hosta.subnet.siroe.com rewrite rule pattern; an address of jdoe@hostb.subnet.siroe.com will match the .subnet.siroe.com rewrite rule pattern; and an address of jdoe@hostc.siroe.com will match the .siroe.com rewrite rule pattern.

In particular, the use of rewrite rules incorporating subdomain rewrite rule patterns is common for sites on the Internet. Such a site will typically have a number of rewrite rules for their own internal hosts and subnets, and then will include rewrite rules for the top-level Internet domains into their configuration from the file internet.rules (msg-svr-base/config/internet.rules).

To ensure that messages to Internet destinations (other than to the internal host destinations handled via more specific rewrite rules) will be properly rewritten and routed to an outgoing TCP/IP channel, ensure that the imta.cnf file contains:

• Rewrite rules with patterns that match the top level Internet domains

• Templates that rewrite addresses matching such patterns to an outgoing TCP/IP channel

!    Ascension Island
 .AC                      $U%$H$D@TCP-DAEMON
. [text
.     removed for
.             brevity]
!      Zimbabwe
 .ZW                      $U%$H$D@TCP-DAEMON

      

IP domain literals follow a similar hierarchical matching pattern, though with right-to-left (rather than left-to-right) matching. For example, the following pattern matches only and exactly the IP literal [1.2.3.4]:

[1.2.3.4]

The next pattern matches anything in the 1.2.3.0 subnet:

[1.2.3.]

In addition to the more common sorts of host or subdomain rewrite rule patterns already discussed, rewrite rules may also make use of several special patterns, summarized in Table 11–1, and discussed in the following subsections.

In addition to these special patterns, Messaging Server also has the concept of tags, which may appear in rewrite rule patterns. These tags are used in situations where an address may be rewritten several times and, based upon previous rewrites, distinctions must be made in subsequent rewrites by controlling which rewrite rules match the address. For more information, see 11.3.4 Tagged Rewrite Rule Sets

11.3.1 A Rule to Match Percent Hacks

If the MTA tries to rewrite an address of the form A%B and fails, it tries one extra rule before falling through and treating this address form as A%B@localhost. (For more information about these address forms, see 11.4 Rewrite Rule Templates.) This rule is only activated when a local part containing a percent sign has failed to rewrite any other way (including the match all rule described below).

The percent hack rule is useful for assigning some special, internal meaning to percent hack addresses.

11.3.2 A Rule to Match Bang-Style (UUCP) Addresses

If the MTA tries to rewrite an address of the form B!A and fails, it tries one extra rule before falling through and treating this address form as B!A@localhost. This extra rule is the bang-style rule. The pattern is $!. The pattern never changes. This rule is only activated when a local part containing an exclamation point has failed to rewrite any other way (including the default rule described below).

The bang-style rule can be used to force UUCP style addresses to be routed to a system with comprehensive knowledge of UUCP systems and routing.

11.3.3 A Rule to Match Any Address

The special pattern “.” (a single period) will match any host/domain specification if no other rule matches and the host/domain specification cannot be found anywhere in the channel table. In other words, the “.” rule is used as a last resort when address rewriting would fail otherwise.

Regarding substitution sequences, when the match-all rule matches and its template is expanded, $H expands to the full host name and $D expands to a single dot “.”. Thus, $D is of limited use in a match-all rule template!

11.3.4 Tagged Rewrite Rule Sets

As the rewrite process proceeds it may be appropriate to bring different sets of rules into play. This is accomplished by the use of the rewrite rule tag. The current tag is prepended to each pattern before looking it up in the configuration file or domain database. The tag can be changed by any rewrite rule that matches by using the $T substitution string in the rewrite rule template (described below).

Tags are somewhat sticky; once set they will continue to apply to all hosts that are extracted from a single address. This means that care must be taken to provide alternate rules that begin with the proper tag values once any tags are used. In practice this is rarely a problem since tags are usually used in only very specialized applications. Once the rewriting of the address is finished the tag is reset to the default tag—an empty string.

By convention all tag values end in a vertical bar |. This character is not used in normal addresses and thus is free to delineate tags from the rest of the pattern.

11.4 Rewrite Rule Templates

The following sections describe in more detail template formats for rewrite rules. Table 11–2 summarizes the template formats.

11.4.1 Ordinary Rewriting Templates, A%B@C or A@B

The following template is the most common form of template. The rule is applied to the user part of the address and to the domain part of the address. The new address is then used to route the message to a specific channel (indicated by ChannelTag).

UserTemplate%DomainTemplate@ChannelTag[controls]

The next form of template is identical in application to the most common form of template. However, this form of template is possible only if DomainTemplate and ChannelTag are identical.

UserTemplate@ChannelTag[controls]

11.4.2 Repeated Rewrites Template, A%B

The following template format is used for meta-rules that require additional rewriting after application of the rule. After the rule is applied, the entire rewriting process is repeated on the resulting new address. (All other rewrite rule formats cause the rewriting process to terminate after the rule has been applied.)

UserTemplate%DomainTemplate[controls]

Note, however, that while the special A%B form does cause rewriting of the current domain to restart, it is actually just a continuation of the current rewriting process. It does not rewrite the entire process from the beginning. It does not perform the $* pattern when it goes through the second time.

For example, the following rule has the effect of removing all occurrences of the .removable domain from the ends of addresses:

.removable $U%$H

Extreme care must be taken when using these repeating rules; careless use can create a “rules loop.” For this reason meta-rules should only be used when absolutely necessary. Be sure to test meta-rules with the imsimta test -rewrite command. For more information on the test -rewrite command, see the Sun Java System Messaging Server 6.3 Administration Reference.

11.4.3 Specified Route Rewriting Templates, A@B@C@D or A@B@C

The following template format works in the same way as the more common template UserTemplate%DomainTemplate@ChannelTag (note the difference in the first separator character), except that ChannelTag is inserted into the address as a source route. The message is then routed to ChannelTag:

UserTemplate@DomainTemplate@Source-Route
    @ChannelTag[controls]

The rewritten address becomes @route:user@domain. The following template is also valid:

UserTemplate@DomainTemplate@ChannelTag[controls]

For example, the following rule rewrites the address jdoe@com1 into the source-routed address @siroe.com:jdoe@com1. The channel tag becomes siroe.com:

com1 $U@com1@siroe.com

11.4.4 Case Sensitivity in Rewrite Rule Templates

Unlike the patterns in rewrite rules, character case in templates is preserved. This is necessary when using rewrite rules to provide an interface to a mail system that is sensitive to character case. Note that substitution sequences like $U and $D that substitute material extracted from addresses also preserve the original case of characters.

When it is desirable to force substituted material to use a particular case, for example, to force mailboxes to lowercase on UNIX systems, special substitution sequences can be used in templates to force substituted material to the desired case. Specifically, $\ forces subsequent substituted material into lower case, $^ forces subsequent substituted material into upper case, and $_ says to use the original case.

For example, you can use the following rule to force mailboxes to lowercase for unix.siroe.com addresses:

unix.siroe.com    $\$U$_%unix.siroe.com

11.5 How the MTA Applies Rewrite Rules to an Address

The following steps describe how the MTA applies rewrite rules to a given address:

1. The MTA extracts the first host or domain specification from an address.

   An address can specify more than one host or domain name as in the case:

   jdoe%hostname@siroe.com.

2. After identifying the first host or domain name, the MTA conducts a search that scans for a rewrite rule whose pattern matches the host or domain name.

3. When the matching rewrite rule is found, the MTA rewrites the address according to the template portion of that rule.

4. Finally, the MTA compares the channel tag with the host names that are associated with each channel.

   If a match is found, the MTA enqueues the message to the associated channel; otherwise, the rewrite process fails. If the matching channel is the local channel, some additional rewriting of the address may take place by looking up the alias database and alias file.

These steps are described in more detail in the subsections that follow.

Using a channel tag that does not belong to any existing channel will cause messages whose addresses match this rule to be bounced. That is, it makes the matching messages nonroutable.

This section consists of the following subsections:

• 11.5.1 Step 1. Extract the First Host or Domain Specification

• 11.5.2 Step 2. Scan the Rewrite Rules

• 11.5.3 Step 3. Rewrite Address According to Template

• 11.5.4 Step 4. Finish the Rewrite Process

• 11.5.5 Rewrite Rule Failure

• 11.5.6 Syntax Checks After Rewrite

• 11.5.7 Handling Domain Literals

11.5.1 Step 1. Extract the First Host or Domain Specification

The process of rewriting an address starts by extracting the first host or domain specification from the address. (Readers not familiar with RFC 822 address conventions are advised to read that standard to understand the following discussion.) The order in which host/domain specifications in the address are scanned is as follows:

1. Hosts in source routes (read from left to right)

2. Hosts appearing to the right of the “at” sign (@)

3. Hosts appearing to the right of the last single percent sign (%)

4. Hosts appearing to the left of the first exclamation point (!)

The order of the last two items is switched if the bangoverpercent keyword is in effect on the channel that is doing the address rewriting. That is, if the channel attempting to enqueue the message is, itself, marked with the bangoverpercent channel keyword.

Some examples of addresses and the host names that could be extracted first are shown in Table 11–3.

RFC 822 does not address the interpretation of exclamation points (!) and percent signs (%) in addresses. Percent signs are customarily interpreted in the same manner as at signs (@) if no at sign is present, so this convention is adopted by the Messaging Server MTA.

The special interpretation of repeated percent signs is used to allow percent signs as part of local user names; this might be useful in handling some foreign mail system addresses. The interpretation of exclamation points conforms to RFC 976’s “bang-style” address conventions and makes it possible to use UUCP addresses with the Messaging Server MTA.

The order of these interpretations is not specified by either RFC 822 or RFC 976, so the bangoverpercent and nobangoverpercent keywords can be used to control the order in which they are applied by the channel doing the rewriting. The default is more “standard,” although the alternate setting may be useful under some circumstances.

The use of exclamation points (!) or percent signs (%) in addresses is not recommended.

11.5.2 Step 2. Scan the Rewrite Rules

Once the first host or domain specification has been extracted from the address, the MTA consults the rewrite rules to find out what to do with it. The host/domain specification is compared with the pattern part of each rule (that is, the left side of each rule). The comparison is case insensitive. Case insensitivity is mandated by RFC 822. The MTA is insensitive to case but preserves it whenever possible.

If the host or domain specification does not match any pattern, in which case it is said to “not match any rule,” the first part of the host or domain specification—the part before the first period, usually the host name—is removed and replaced with an asterisk (*) and another attempt is made to locate the resulting host or domain specification, but only in the configuration file rewrite rules (the domain database is not consulted).

If this fails, the first part is removed and the process is repeated. If this also fails the next part is removed (usually a subdomain) and the rewriter tries again, first with asterisks and then without. All probes that contain asterisks are done only in the configuration file rewrite rules table; the domain database is not checked. This process proceeds until either a match is found or the entire host or domain specification is exhausted. The effect of this procedure is to try to match the most specific domain first, working outward to less specific and more general domains.

A more algorithmic view of this matching procedure is:

• The host/domain specification is used as the initial value for the comparison strings spec_1 and spec_2. (For example, spec_1 = spec_2 = a.b.c).

• The comparison string spec_1 is compared with the pattern part of each rewrite rule in the configuration file and then the domain database until a match is found. The matching procedure is exited if a match is found.

• If no match is found, then the left-most, nonasterisk part of spec_2 is converted to an asterisk. For example, if spec_2 is a.b.c then it is changed to *.b.c; if spec_2 is *.b.c, then it is changed to *.*.c. The matching procedure is exited if a match is found.

• If no match is found then the first part, including any leading period, of the comparison string spec_1 is removed. Where spec_1 has only one part (for example, .c or c), the string is replaced with a single period, “.”. If the resulting string spec_1 is of nonzero length, then you return to step 1. If the resulting string has zero length (for example, was previously “.”), then the lookup process has failed and you exit the matching procedure.

For example, suppose the address dan@sc.cs.siroe.edu is to be rewritten. This causes the MTA to look for the following patterns in the given order:

sc.cs.siroe.edu
*.cs.siroe.edu
.cs.siroe.edu
*.*.siroe.edu
.siroe.edu
*.*.*.edu
.edu
*.*.*.*
.
 

11.5.3 Step 3. Rewrite Address According to Template

Once the host/domain specification matches a rewrite rule, it is rewritten using the template part of the rule. The template specifies three things:

1. A new user name for the address.

2. A new host/domain specification for the address.

3. A channel tag that identifies an existing MTA channel to which messages to this address should be sent.

11.5.4 Step 4. Finish the Rewrite Process

One of two things can happen once the host/domain specification is rewritten.

• If the channel tag is associated neither with the local channel nor a channel marked with the routelocal channel keyword, or there are no additional host/domain specifications in the address, the rewritten specification is substituted into the address replacing the original specification that was extracted for rewriting, and the rewriting process terminates.

• If the channel tag matches the local channel or a channel marked routelocal and there are additional host/domain specifications that appear in the address, the rewritten address is discarded, the original (initial) host/domain specification is removed from the address, a new host/domain specification is extracted from the address, and the entire process is repeated. Rewriting will continue until either all the host/domain specifications are gone or a route through a non-local, non-routelocal channel is found. This iterative mechanism is how the MTA provides support for source routing. In effect, superfluous routes through the local system and routelocal systems are removed from addresses by this process.

11.5.5 Rewrite Rule Failure

If a host/domain specification fails to match any rewrite rule and no default rule is present, the MTA uses the specification “as-is”; for example, the original specification becomes both the new specification and the routing system. If the address has a nonsensical host/domain specification it will be detected when the routing system does not match any system name associated with any channel and the message will be bounced.

11.5.6 Syntax Checks After Rewrite

No additional syntax checking is done after the rewrite rules have been applied to an address. This is deliberate—it makes it possible for rewrite rules to be used to convert addresses into formats that do not conform to RFC 822. However, this also means that mistakes in the configuration file may result in messages leaving the MTA with incorrect or illegal addresses.

11.5.7 Handling Domain Literals

Ddomain literals are handled specially during the rewriting process. If a domain literal appearing in the domain portion of an address does not match a rewrite rule pattern as is, the literal is interpreted as a group of strings separated by periods and surrounded by square brackets. The right-most string is removed and the search is repeated. If this does not work, the next string is removed, and so on until only empty brackets are left. If the search for empty brackets fails, the entire domain literal is removed and rewriting proceeds with the next section of the domain address, if there is one. No asterisks are used in the internal processing of domain literals; when an entire domain literal is replaced by an asterisk, the number of asterisks corresponds to the number of elements in the domain literal.

Like normal domain or host specifications, domain literals are also tried in most specific to least specific order. The first rule whose pattern matches will be the one used to rewrite the host or domain specification. If there are two identical patterns in the rules list, the one which appears first will be used.

As an example, suppose the address dan@[128.6.3.40] is to be rewritten. The rewriter looks for [128.6.3.40], then [128.6.3.], then [128.6.], then [128.], then [], then [*.*.*.*], and finally the match-all rule “.”.

11.6 Template Substitutions and Rewrite Rule Control Sequences

Substitutions are used to rewrite user names or addresses by inserting a character string into the rewritten address, the value of which is determined by the particular substitution sequence used. This section consists of the following subsections:

• 11.6.1 Username and Subaddress Substitution, $U, $0U, $1U

• 11.6.2 Host/Domain and IP Literal Substitutions, $D, $H, $nD, $nH, $L

• 11.6.3 Literal Character Substitutions, $$, $%, $@

• 11.6.4 LDAP Query URL Substitutions, $]...[

• 11.6.5 General Database Substitutions, $(...)

• 11.6.6 Apply Specified Mapping, ${...}

• 11.6.7 Customer-supplied Routine Substitutions, $[...]

• 11.6.8 Single Field Substitutions, $&, $!, $*, $#

• 11.6.9 Unique String Substitutions

• 11.6.10 Source-Channel-Specific Rewrite Rules ($M, $N)

• 11.6.11 Destination-Channel-Specific Rewrite Rules ($C, $Q)

• 11.6.12 Direction-and-Location-Specific Rewrite Rules ($B, $E, $F, $R)

• 11.6.13 Host-Location-Specific Rewrites ($A, $P, $S, $X)

• 11.6.14 Changing the Current Tag Value, $T

• 11.6.15 Controlling Error Messages Associated with Rewriting ($?)

For example, in the following template, the $U is a substitution sequence. It causes the username portion of the address being rewritten to be substituted into the output of the template. Thus, if jdoe@mailhost.siroe.com was being rewritten by this template, the resulting output would be jdoe@siroe.com, the $U substituting in the username portion, jdoe, of the original address:

$U@siroe.com

Control sequences impose additional conditions to the applicability of a given rewrite rule. Not only must the pattern portion of the rewrite rule match the host or domain specification being examined, but other aspects of the address being rewritten must meet conditions set by the control sequence or sequences. For example, the $E control sequence requires that the address being rewritten be an envelope address, while the $F control sequence requires that it be a forward pointing address. The following rewrite rule only applies to (rewrite) envelope To: addresses of the form user@siroe.com:

siroe.com $U@mail.siroe.com$E$F

If a domain or host specification matches the pattern portion of a rewrite rule but doesn’t meet all of the criteria imposed by a control sequences in the rule’s template, then the rewrite rule fails and the rewriter continues to look for other applicable rules.

Table 11–4 summarizes the template substitutions and control sequences.

11.6.1 Username and Subaddress Substitution, $U, $0U, $1U

Any occurrences of $U in the template are replaced with the username (RFC 822 “local-part”) from the original address. Note that user names of the form a.“b” will be replaced by “a.b” as RFC2822 deprecates the former syntax from RFC 822 and it is expected that the latter usage will become mandatory in the future.

Any occurrences of $0U in the template are replaced with the username from the original address, minus any subaddress and subaddress indication character (+). Any occurrences of $1U in the template are replaced with the subaddress and subaddress indication character, if any, from the original address. So note that $0U and $1U are complementary pieces of the username, with $0U$1U being equivalent to a simple $U.

11.6.2 Host/Domain and IP Literal Substitutions, $D, $H, $nD, $nH, $L

Any occurrences of $H are replaced with the portion of the host/domain specification that was not matched by the rule. Any occurrences of $D are replaced by the portion of the host/domain specification that was matched by the rewrite rule. The $nH and $nD characters are variants that preserve the normal $H or $D portion from the nth leftmost part starting counting from 0. That is, $nH and $nD omit the leftmost n parts (starting counting from 1) of what would normally be a $H or $D, substitution, respectively. In particular, $0H is equivalent to $H and $0D is equivalent to $D.

For example, assume the address jdoe@host.siroe.com matches the following rewrite rule:

host.siroe.com    $U%$1D@TCP-DAEMON

The resulting address is jdoe@siroe.com with TCP-DAEMON used as the outgoing channel. Here where $D would have substituted in the entire domain that matched, host.siroe.com, the $1D instead substitutes in the portions of the match starting from part 1 (part 1 being siroe), so substitutes in siroe.com.

$L substitutes the portion of a domain literal that was not matched by the rewrite rule.

11.6.3 Literal Character Substitutions, $$, $%, $@

The $, %, and @ characters are normally metacharacters in rewrite rule templates. To perform a literal insertion of such a character, quote it with a dollar character, $. That is, $$ expands to a single dollar sign, $; $% expands to a single percent, % (the percent is not interpreted as a template field separator in this case); and $@ expands to a single at sign, @ (also not interpreted as a field separator).

11.6.4 LDAP Query URL Substitutions, $]...[

A substitution of the form $]ldap-url[ is interpreted as an LDAP query URL and the result of the LDAP query is substituted. Standard LDAP URLs are used with the host and port omitted. The host and port are instead specified in the msg.conf file (local.ldaphost and local.ldapport attributes).

That is, the LDAP URL should be specified as follows where the square bracket characters, [ ], indicate optional portions of the URL:

ldap:///dn[?attributes[?scope?filter]]

The dn is required and is a distinguished name specifying the search base. The optional attributes, scope, and filter portions of the URL further refine what information to return. For a rewrite rule, the desired attributes to specify returning might be a mailRoutingSystem attribute (or some similar attribute). The scope may be any of base (the default), one, or sub. And the desired filter might be to request the return of the object whose mailDomain value matches the domain being rewritten.

If the LDAP directory schema includes attributes mailRoutingSystem and mailDomain, then a possible rewrite rule to determine to which system to route a given sort of address might appear as the following where here the LDAP URL substitution sequence $D is used to substitute in the current domain name into the LDAP query constructed:

.siroe.com \
  $U%$H$D@$]ldap:///o=siroe.com?mailRoutingSystem?sub? \
  (mailDomain=$D)

For ease in reading, the backslash character is used to continue the single logical rewrite rule line onto a second physical line. Table 11–5 lists the LDAP URL Substitution Sequences.

The MTA now caches URL results from lookups done in rewrite rules and mappings. This new URL result cache is controlled by two new MTA options, URL_RESULT_CACHE_SIZE (default 10000 entries) and URL_RESULT_CACHE_TIMEOUT (default 600 seconds).

11.6.5 General Database Substitutions, $(...)

A substitution of the form $(text) is handled specially. The text part is used as a key to access the special general text database. This database consists of the file specified with the IMTA_GENERAL_DATABASE option in the msg-svr-base/config/imta_tailor file, which is usually the file msg-svr-base/db/generaldb.db.

If “text-string” is found in the database, the corresponding template from the database is substituted. If “text-string” does not match an entry in the database, the rewrite process fails; it is as if the rewrite rule never matched in the first place. If the substitution is successful, the template extracted from the database is re-scanned for additional substitutions. However, additional $(text) substitutions from the extracted template are prohibited in order to prevent endless recursive references.

As an example, suppose that the address jdoe@siroe.siroenet matches the following rewrite rule:

.SIROENET $($H)

Then, the text string siroe will be looked up in the general database and the result of the look up, if any, is used for the rewrite rule’s template. Suppose that the result of looking up siroe is $u%eng.siroe.com@siroenet. Then the output of the template will be jdoe@eng.siroe.com (i.e., username = jdoe, host/domain specification = eng.siroe.com), and the routing system will be siroenet.

If a general text database exists it should be world readable to insure that it operates properly. See 10.9.1 MTA Text Databases for more information.

11.6.6 Apply Specified Mapping, ${...}

A substitution of the form.SIROENET $($H) ${mapping,argument} is used to find and apply a mapping from the MTA mapping file. The mapping field specifies the name of the mapping table to use while argument specifies the string to pass to the mapping. The mapping must exist and must set the $Y flag in its output if it is successful; if it doesn’t exist or doesn’t set $Y the rewrite will fail. If successful the result of the mapping is merged into the template at the current location and re-expanded.

This mechanism allows the MTA rewriting process to be extended in various complex ways. For example, the username part of an address can be selectively analyzed and modified, which normally isn’t a feature the MTA rewriting process is capable of.

11.6.7 Customer-supplied Routine Substitutions, $[...]

A substitution of the form $[image,routine,argument] is used to find and call a customer-supplied routine. At run-time on UNIX, the MTA uses dlopen and dlsym to dynamically load and call the specified routine from the shared library image. The routine is then called as a function with the following argument list:

status := routine (argument, arglength, result, reslength)

argument and result are 252 byte long character string buffers. On UNIX, argument and result are passed as a pointer to a character string, (for example, in C, as char*.) arglength and reslength are signed, long integers passed by reference. On input, argument contains the argument string from the rewrite rule template, and arglength the length of that string. On return, the resultant string should be placed in result and its length in reslength. This resultant string will then replace the “$[image,routine,argument]” in the rewrite rule template. The routine should return 0 if the rewrite rule should fail and -1 if the rewrite rule should succeed.

This mechanism allows the rewriting process to be extended in all sorts of complex ways. For example, a call to some type of name service could be performed and the result used to alter the address in some fashion. Directory service lookups for forward pointing addresses (e.g., To: addresses) to the host siroe.com might be performed as follows with the following rewrite rule. The $F, described in 11.6.12 Direction-and-Location-Specific Rewrite Rules ($B, $E, $F, $R) causes this rule to be used only for forward pointing addresses:

siroe.com $F$[LOOKUP_IMAGE,LOOKUP,$U]

A forward pointing address jdoe@siroe.com will, when it matches this rewrite rule, cause LOOKUP_IMAGE (which is a shared library on UNIX) to be loaded into memory, and then cause the routine LOOKUP called with jdoe as the argument parameter. The routine LOOKUP might then return a different address, say, John.Doe%eng.siroe.com in the result parameter and the value -1 to indicate that the rewrite rule succeeded. The percent sign in the result string (see 11.4.2 Repeated Rewrites Template, A%B John.Doe@eng.siroe.com as the address to be rewritten.

On UNIX systems, the site-supplied shared library image should be world readable.

11.6.8 Single Field Substitutions, $&, $!, $*, $#

Single field substitutions extract a single subdomain part from the host/domain specification being rewritten. The available single field substitutions are shown in Table 11–6.

Suppose the address jdoe@eng.siroe.com matches the following rewrite rule:

*.SIROE.COM     $U%$&0.siroe.com@mailhub.siroe.com

Then the result from the template will be jdoe@eng.siroe.com with mailhub.siroe.com used as the routing system.

11.6.9 Unique String Substitutions

Each use of the $W control sequence inserts a text string composed of upper case letters and numbers that is designed to be unique and not repeatable. $W is useful in situation where non-repeating address information must be constructed.

11.6.10 Source-Channel-Specific Rewrite Rules ($M, $N)

It is possible to have rewrite rules that act only in conjunction with specific source channels. This is useful when a short-form name has two meanings:

1. When it appears in a message arriving on one channel.

2. When it appears in a message arriving on a different channel.

Source-channel-specific rewriting is associated with the channel program in use and the channel keywords rules and norules. If norules is specified on the channel associated with an MTA component that is doing the rewriting, no channel-specific rewrite checking is done. If rules is specified on the channel, then channel-specific rule checks are enforced. The keyword rules is the default.

Source-channel-specific rewriting is not associated with the channel that matches a given address. It depends only on the MTA component doing the rewriting and that component’s channel table entry.

Channel-specific rewrite checking is triggered by the presence of a $N or $M control sequence in the template part of a rule. The characters following the $N or $M, up until either an at sign (@), percent sign (%), or subsequent $N, $M, $Q, $C, $T, or $? are interpreted as a channel name.

For example, $Mchannel causes the rule to fail if channel is not currently doing the rewriting. $Nchannel causes the rule to fail if channel is doing the rewriting. Multiple $M and $N clauses may be specified. If any one of multiple $M clauses matches, the rule succeeds. If any of multiple $N clauses matches, the rules will fail.

11.6.11 Destination-Channel-Specific Rewrite Rules ($C, $Q)

It is possible to have rewrite rules whose application is dependent upon the channel to which a message is being enqueued. This is useful when there are two names for some host, one known to one group of hosts and one known to another. By using different channels to send mail to each group, addresses can be rewritten to refer to the host under the name known to each group.

Destination channel-specific rewriting is associated with the channel to which the message is to be dequeued and processed by, and the channel keywords rules and norules on that channel. If norules is specified on the destination channel, no channel-specific rewrite checking is done. If rules is specified on the destination channel, channel-specific rule checks are enforced. The keyword rules is the default.

Destination channel-specific rewriting is not associated with the channel matched by a given address. It depends only on the message’s envelope To: address. When a message is enqueued, its envelope To: address is first rewritten to determine to which channel the message is enqueued. During the rewriting of the envelope To: address, any $C and $Q control sequences are ignored. After the envelope To: address is rewritten and the destination channel determined, then the $C and $Q control sequences are honored, as other addresses associated with the message are rewritten.

Destination-channel-specific rewrite checking is triggered by the presence of a $C or $Q control sequence in the template part of a rule. The characters following the $C or $Q, up until either an at sign (@), percent sign (%), or subsequent $N, $M, $C, $Q, $T, or $? are interpreted as a channel name.

For example, $Qchannel causes the rule to fail if channel is not the destination. For another example, $Cchannel causes the rule to fail if channel is the destination. Multiple $Q and $C clauses may be specified. If any one of multiple $Q clauses matches, the rule succeeds. If any of multiple $C clauses matches, the rule fails.

11.6.12 Direction-and-Location-Specific Rewrite Rules ($B, $E, $F, $R)

Sometimes you need to specify rewrite rules that apply only to envelope addresses or, alternately, only to header addresses. The control sequence $E forces a rewrite to fail if the address being rewritten is not an envelope address. The control sequence $B forces a rewrite to fail if the address being rewritten is not from the message header or body. These sequences have no other effects on the rewrite and may appear anywhere in the rewrite rule template.

Addresses may also be categorized by direction. A forward pointing address is one that originates on a To:, Cc:, Resent-to:, or other header or envelope line that refers to a destination. A backward pointing address is something like a From:, Sender:, or Resent-From:, that refers to a source. The control sequence $F causes the rewrite to be applied if the address is forward pointing. The control sequence $R causes the rewrite to be applied if the address is reverse pointing.

11.6.13 Host-Location-Specific Rewrites ($A, $P, $S, $X)

Circumstances occasionally require rewriting that is sensitive to the location where a host name appears in an address. Host names can appear in several different contexts in an address:

• In a source route

• To the right of the at sign (@)

• To the right of a percent sign (%) in the local-part

• To the left of an exclamation point in the local-part

Under normal circumstances, a host name should be handled in the same way, regardless of where it appears. Some situations might require specialized handling.

Four control sequences are used to control matching on the basis of the host’s location in the address.

• $S specifies that the rule can match a host extracted from a source route.

• $A specifies that the rule can match a host found to the right of the @ sign.

• $P specifies that the rule can match a host found to the right of a % sign.

• $X specifies that the rule can match a host found to the left of an exclamation point (!).

The rule fails if the host is from a location other than the one specified. These sequences can be combined in a single rewrite rule. For example, if $S and $A are specified, the rule matches hosts specified in either a source route or to the right of the at sign. Specifying none of these sequences is equivalent to specifying all of them; the rule can match regardless of location.

11.6.14 Changing the Current Tag Value, $T

The $T control sequence is used to change the current rewrite rule tag. The rewrite rule tag is prepended to all rewrite rule patterns before they are looked up in the configuration file and domain database. Text following the $T, up until either an at sign, percent sign, $N, $M, $Q, $C, $T, or $? is taken to be the new tag.

Tags are useful in handling special addressing forms where the entire nature of an address is changed when a certain component is encountered. For example, suppose that the special host name internet, when found in a source route, should be removed from the address and the resulting address forcibly matched against the TCP-DAEMON channel.

This could be implemented with rules like the following (localhost is assumed to be the official name of the local host):

internet               $S$U@localhost$Tmtcp-force|

mtcp-force|.           $U%$H@TCP-DAEMON

The first rule will match the special host name internet if it appears in the source route. It forcibly matches internet against the local channel, which insures that it will be removed from the address. A rewrite tag is then set. Rewriting proceeds, but no regular rule will match because of the tag. Finally, the default rule is tried with the tag, and the second rule of this set fires, forcibly matching the address against the TCP-DAEMON channel regardless of any other criteria.

11.6.15 Controlling Error Messages Associated with Rewriting ($?)

The MTA provides default error messages when rewriting and channel matching fail. The ability to change these messages can be useful under certain circumstances. For example, if someone tries to send mail to an Ethernet router box, it may be considered more informative to say something like “our routers cannot accept mail” rather than the usual “illegal host/domain specified.”

A special control sequence can be used to change the error message that is printed if the rule fails. The sequence $? is used to specify an error message. Text following the $?, up to either an at sign (@), percent sign (%), $N, $M, $Q, $C, $T, or $? is taken to be the text of the error message to print if the result of this rewrite fails to match any channel. The setting of an error message is “sticky” and lasts through the rewriting process.

A rule that contains a $? operates just like any other rule. The special case of a rule containing only a $? and nothing else receives special attention --- the rewriting process is terminated without changing the mailbox or host portions of the address and the host is looked up as-is in the channel table. This lookup is expected to fail and the error message will be returned as a result.

For example, assume the final rewrite rule in the MTA configuration file is as follows:

. $?Unrecognized address; contact postmaster@siroe.com

In this example, any unrecognized host or domain specifications that can fail will, in the process of failing, generate the error message: Unrecognized address; contact postmaster@siroe.com.

11.7 Handling Large Numbers of Rewrite Rules

The MTA always reads in all the rewrite rules from the imta.cnf file and stores them in memory in a hash table. Use of a compiled configuration bypasses the overhead associated with reading the configuration file each and every time the information is needed; a hash table is still used to store all of the rewrite rules in memory. This scheme is adequate for small to medium numbers of rewrite rules. However, some sites may require as many as 10,000 rewrite rules or more, which can consume prohibitive amounts of memory.

The MTA solves this problem by providing an optional facility for storing large numbers of rewrite rules in an ancillary indexed data file. Whenever the regular configuration file is read, the MTA checks for the existence of the domain database. If this database exists, it is opened and consulted whenever an attempted match fails on the rules found in the configuration file. The domain database is only checked if a given rule is not found in the configuration file, so rules can always be added to the configuration file to override those in the database. By default, the domain database is used to store rewrite rules associated with hosted domains. The IMTA_DOMAIN_DATABASE attribute is stored in the imta_tailor file. The default location for the database is msg-svr-base/data/db/domaindb.db.

DO NOT EDIT THIS FILE BY HAND.

11.8 Testing Rewrite Rules

You can test rewrite rules with the imsimta test -rewrite command. The -noimage qualifier will allow you to test changes made to the configuration file prior to recompiling the new configuration.

You may find it helpful to rewrite a few addresses using this utility with the -debug qualifier. This will show you step-by-step how the address is rewritten. For example, issue the following command:

% imsimta test -rewrite -debug joe@siroe.com

For a detailed description of the imsimta test -rewrite utility, see the Sun Java System Messaging Server 6.3 Administration Reference.

11.9 Rewrite Rules Example

The following example provides sample rewrite rules and how sample addresses would be rewritten by the rules.

Suppose the configuration file for the system SC.CS.SIROE.EDU contained the rewrite rules shown in the following example:

sc                     $U@sc.cs.siroe.edu
sc1                    $U@sc1.cs.siroe.edu
sc2                    $U@sc2.cs.siroe.edu
*                      $U%$&0.cs.siroe.edu
*.cs                   $U%$&0.cs.siroe.edu
*.cs.siroe             $U%$&0.cs.siroe.edu
*.cs.siroe.edu         $U%$&0.cs.siroe.edu@ds.adm.siroe.edu
sc.cs.siroe.edu        $U@$D
sc1.cs.siroe.edu       $U@$D
sc2.cs.siroe.edu       $U@$D
sd.cs.siroe.edu        $U@sd.cs.siroe.edu
.siroe.edu             $U%$H.siroe.edu@cds.adm.siroe.edu
.edu                   $U@$H$D@gate.adm.siroe.edu
[]                     $U@[$L]@gate.adm.siroe.edu

Table 11–7 shows some sample addresses and how they would be rewritten and routed according to the rewrite rules.

Basically, what these rewrite rules say is: If the host name is one of our short-form names (sc, sc1 or sc2) or if it is one of our full names (sc.cs.siroe.edu, and so on), expand it to our full name and route it to us. Append cs.cmu.edu to one part short-form names and try again. Convert one part followed by .cs to one part followed by .cs.siroe.edu and try again. Also convert .cs.siroe to .cs.siroe.edu and try again.

If the name is sd.cs.siroe.edu (some system we connect to directly, perhaps) rewrite and route it there. If the host name is anything else in the .cs.siroe.edu subdomain, route it to ds.cs.siroe.edu (the gateway for the .cs.siroe.edu subdomain). If the host name is anything else in the .siroe.edu subdomain route it to cds.adm.siroe.edu (the gateway for the .siroe.edu subdomain). If the host name is anything else in the .edu top-level domain route it to gate.adm.siroe.edu (which is presumably capable of routing the message to its proper destination). If a domain literal is used send it to gate.adm.siroe.edu as well.

Most applications of rewrite rules (like the previous example) will not change the username (or mailbox) part of the address in any way. The ability to change the username part of the address is used when the MTA is used to interface to mailers that do not conform to RFC 822—mailers where it is necessary to stuff portions of the host/domain specification into the username part of the address. This capability should be used with great care if it is used at all.