Rewrite rules

Domain rewriting rules, or, as they are more frequently called, rewrite rules, play two important roles for the MTA: rewrite rules are used to convert addresses into true domain addresses, and to determine their corresponding channels. These rules are used to rewrite addresses appearing in both the transport layer and the message header. The transport layer is the message&#x27;s "envelope", which contains routing information and is invisible to the user. The determination of to which channels a message should be enqueued results from rewriting its envelope To addresses.

The rewrite rules and the table of channels cooperate to determine the disposition of each address. Each address detected in a message is rewritten, startinga with the envelope To address(es). The result of the rewrite process is a rewritten address and a "routing system" (as determined from rewriting the envelope To address); i.e., the system to which the message is to be sent. Depending upon the topology of the network, the routing system may only be the first step along the path the message takes to reach its destination or it may be the final destination system itself.

After the rewrite process has finished, a search is made for the routing system among the MTA&#x27;s channels. Each channel will have one or more host names associated with it. The routing system name is compared against each of these names to determine to which channel to enqueue the message.

Note that the MTA provides (many) other means of manipulating addresses for the purposes of changing them for varied purposes, such as cosmetic changes, message forwarding, mailing list processing, etc.   See for instance Aliases. Rewrite rules are appropriate for global, unconditional transformations of domain names to be controlled purely by the MTA (as opposed to provisioning of domain name handling in, for instance, an LDAP directory), and are required for configuring MTA routing of messages based on envelope To address.

Every rewrite rule consists of two parts: a pattern (left hand side) followed by an equivalence string or  template (right hand side). The two parts must be separated by one or more spaces. Spaces are not allowed in the parts themselves. In general, the template specifies a mailbox name (e.g., username), a host/domain specification, and the name of a system attached to an existing MTA channel to which messages to this address should be enqueued. The total length of a line in the configuration file is limited to 1024 characters; the pattern is limited to 256 characters, and template (prior to substitutions) is also limited to 256 characters.

In legacy configuration, note that each rewrite rule would appear on a single line in the upper half of the MTA configuration file. Comment lines (lines beginning with a  comment character such as exclamation point in the first column) but not blank lines could be placed between rules. Rewrite rules could also, optionally, be stored in an auxiliary database called the domain database.

In Unified Configuration, rewrite rules are stored under the  XML element. But they are most conveniently viewed and editted "as if" they were in the legacy configuration  file, by using the   command.

The syntax of rewrite rules is discussed in further detail in Rewrite rule patterns and tags and Rewrite rule templates. First, however, Application of rewrite rules to addresses gives an overview of the action of rewrite rules in operation.

aTechnically, rewriting begins with a preliminary rewrite of the envelope From address, for access control and source channel determination purposes. After that, the envelope To address is rewritten (possibly sensitive to the source channel), and then with destination channel(s) determined (due to the rewriting of the envelope To address) the envelope From address receives  another, "real" rewriting now that the destination channels are known.

See also:
 * Channels
 * official_host_name Option
 * local_host_alias Option
 * Rewrite rule patterns and tags
 * Rewrite rule templates
 * Domain database
 * The rewrite group
 * Application of rewrite rules to addresses
 * The MTA