Sun Java System Messaging Server 6.3 Administration Reference

Domain Rewrite Rules

Domain rewrite rules play two important roles:

Rewrite addresses into their proper form.
Determine to which channels a message should be enqueued. The determination of which channel to enqueue a message is made by rewriting its envelope To: address.

Each rewrite rule appears on a single line in the upper half of the imta.cnf file.

For additional information about configuring rewrite rules, refer to Chapter 11, Configuring Rewrite Rules, in Sun Java System Messaging Server 6.3 Administration Guide.

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. Example 4–1shows the rewrite rule section of a partial configuration file.

Example 4–1 Simple Configuration File—Rewrite Rules

! 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     $U@a-host
b     $U@b-host
c     $U%c@b-daemon
d     $U%d@a-daemon

! Begin channel definitions
Simple Configuration File - Rewrite Rules

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 Example 4–1, the patterns are a, b, c, and d.

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 Rewrite Rule Patterns and Tags.

template

Is one of the following. For more information about template syntax, see Rewrite Rule Templates.

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

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 Example 4–1, the $U substitution sequence is used. For more information, see 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. Some can appear almost anywhere in a rule. For more information about controls, see Template Substitutions and Rewrite Rule Control Sequences.

Rewrite Rule Patterns and Tags

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).

This file is required to contain the following:

Rewrite rules with patterns that match the top level Internet domains
Templates that rewrite addresses matching such patterns to an outgoing TCP/IP channel

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 4–3, and discussed in the following subsections.

Table 4–3 Summary of Special Patterns for Rewrite Rules


Pattern	Description/Usage
$*	Matches any address. This rule, if specified, is tried first regardless of its position in the file.
$%	Percent Hack Rule. Matches any host/domain specification of the form A%B.
$!	Bang-style Rule. Matches any host/domain specification of the form B!A.
[]	IP literal match-all rule. Matches any IP domain literal.
.	Matches any host/domain specification. For example, `joe@[129.165.12.11]`

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 the Sun Java System Messaging Server 6.3 Administration Guide.

Rewrite Rule Templates

Table 4–4 summarizes the template formats.

Table 4–4 Summary of Template Formats for Rewrite Rules


Template	Usage
A%B	A becomes the new user/mailbox name, B becomes the new host/domain specification, rewrite again.
A@B	Treated as A%B@B.
A%B@C	A becomes the new user/mailbox name, B becomes the new host/domain specification, route to the channel associated with the host C.
A@B@C	Treated as A@B@C@C.
A@B@C@D	A becomes the new user/mailbox name, B becomes the new host/domain specification, insert C as a source route, route to the channel associated with the host D.

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.

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.

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 4–5 summarizes the template substitutions and control sequences.

Table 4–5 Summary of Template Substitutions and Control Sequences


Substitution Sequence	Substitutes
`$D`	Portion of domain specification that matched.
`$H`	Unmatched portion of host/domain specification; left of dot in pattern.
`$L`	Unmatched portion of domain literal; right of dot in pattern literal.
`$U`	User name from original address.
`$0U`	Local part (username) from original address, minus any subaddress.
`$1U`	Subaddress, if any, from local part (username) of original address.
`$$`	Inserts a literal dollar sign ($).
`$%`	Inserts a literal percent sign (%).
`$@`	Inserts a literal at sign (@).
`$\`	Forces material to lowercase.
`$^`	Forces material to uppercase.
`$_`	Uses original case.
`$W`	Substitutes in a random, unique string.
`$]...[`	LDAP search URL lookup.
`$(text)`	General database substitution; rule fails if lookup fails.
`${...}`	Applies specified mapping to supplied string.
`$[...]`	Invoke customer supplied routine; substitute in result.
`$&n`	The nth part of unmatched (or wildcarded) host, counting from left to right, starting from 0.
`$!n`	The nth part of unmatched (or wildcarded) host, as counted from right to left, starting from 0.
`$*n`	The nth part of matching pattern, counting from left to right, starting from 0.
`$#n`	The nth part of matching pattern, counted from right to left, starting from 0.
`$nD`	Portion of domain specification that matched, preserving from the nth leftmost part starting from 0
`$nH`	Portion of host/domain specification that didn't match, preserving from the nth leftmost part starting from 0
Control Sequence	Effect on Rewrite Rule
`$1M`	Apply only if the channel is an internal reprocessing channel.
`$1N`	Apply only if the channel is not an internal reprocessing channel.
`$1~`	Perform any pending channel match checks. If the checks fail, successfully terminate processing of the current rewrite rule template.
`$A`	Apply if host is to the right of the at sign
`$B`	Apply only to header/body addresses
`$C` `channel`	Fail if sending to `channel`
`$E`	Apply only to envelope addresses
`$F`	Apply only to forward-directed (e.g., To:) addresses
`$M` `channel`	Apply only if `channel` is rewriting the address
`$Nchannel`	Fail if `channel` is rewriting the address
`$P`	Apply if host is to the right of a percent sign
`$Q` `channel`	Apply if sending to `channel`
`$R`	Apply only to backwards-directed (e.g., From:) addresses
`$S`	Apply if host is from a source route
`$Tnewtag`	Set the rewrite rule tag to newtag
`$Vhost`	Fail if the host name is not defined in the LDAP directory (either in the DC tree or as a virtual domain). If the LDAP search times out, the remainder of the rewrite pattern from directly after the character following the host name is replaced with the MTA option string `DOMAIN_FAILURE`.
`$X`	Apply if host is to the left of an exclamation point
`$Zhost`	Fail if the host name is defined in the LDAP directory (either in the DC tree or as a virtual domain). If the LDAP search times out, the remainder of the rewrite pattern from directly after the character following the host name is replaced with the MTA option string `DOMAIN_FAILURE`.
`$?errmsg`	If rewriting fails, return `errmsg` instead of the default error message. The error message must be in US ASCII.
$`number`?`errmsg`	If rewriting fails, return `errmsg` instead of the default error message, and set the SMTP extended error code to `a`.`b`.`c`: `a` is `number`/ 1000000 (the first digit) `b` is (`number`/1000) remainder 1000 (the value of the digits 2 through 4) `c` is `number` remainder 1000 (the value of the last three digits. The following example sets the error code to 3.45.89: `$3045089?the snark is a boojum`

For more information on substitutions, refer to the Sun Java System Messaging Server 6.3 Administration Guide.