Sun Java System Messaging Server 6.3 Administration Guide

10.9.3 The Forward Lookup Table and FORWARD Address Mapping

Address reversals are not applied to envelope To: addresses. The reasons for this omission are fairly obvious—envelope To: addresses are continuously rewritten and modified as messages proceed through the mail system. The entire goal of routing is to convert envelope To: addresses to increasingly system and mailbox-specific formats. The canonicalization functions of address reversal are entirely inappropriate for envelope To: addresses.

In any case, plenty of machinery is available in the MTA to perform substitutions on envelope To: addresses. The alias file, alias database and general lookup table, provide precisely this functionality.

The MTA also provides the forward lookup table and FORWARD mapping, used for special sorts of forwarding purposes, such as pattern-based forwarding, source-specific forwarding, or auto-registration of addresses. Note that the forward lookup table and FORWARD mapping are intended for use primarily for certain special sorts of address forwarding; most sorts of address forwarding, however, are better performed using one of the MTA’s other forwarding mechanisms.

The various substitution mechanisms for envelope To: addresses provide functionality equivalent to the reversal lookup table, but none yet discussed provide functionality equivalent to the reverse mapping. And circumstances do arise where mapping functionality for envelope To: addresses is useful and desirable. The FORWARD Mapping Table

The FORWARD mapping table provides this functionality of pattern based forwarding, and also provides a mechanism for source specific forwarding. If a FORWARD mapping table exists in the mapping file, it is applied to each envelope To: address. No changes are made if this mapping does not exist or no entries in the mapping match.

If the address matches a mapping entry, the result of the mapping is tested. The resulting string will replace the envelope To: address if the entry specifies a $Y; a $N will discard the result of the mapping. See Table 10–8 for a list of additional flags.

Table 10–8 FORWARD Output Mapping Table Flags Description




Run output through the rewriting process again 


Run output through the forward lookup table, if forward lookup table use has been enabled 


Disable further forward lookup table or FORWARD mapping lookups 


Hold the message as a .HELD file


Address remains unchanged 


Use output as new address 

The FORWARD mapping, if present, is consulted before any forward lookup table lookup. If a FORWARD mapping matches and has the flag $G, then the result of the FORWARD mapping will be checked against the forward lookup table, if forward lookup table use has been enabled via the appropriate setting of USE_FORWARD_DATABASE. (Note that if channel specific forward lookup table use has been specified, then the source address and source channel will be prefixed to the result of the FORWARD mapping before looking up in the forward lookup table.) If a matching FORWARD mapping entry specifies $D, then the result of the FORWARD mapping (and optional forward table lookup) will be run through the MTA address rewriting process again. If a matching FORWARD mapping entry specifies $H, then no further FORWARD mapping or database lookups will be performed during that subsequent address rewriting (that resulting from the use of $D).

The following input flags are now available in the FORWARD mapping. In the past they were only available to the various *_ACCESS mappings.

Table 10–9 FORWARD Input Mapping Table Flags Description




SASL used to authenticate connection.  


NOTIFY=DELAYS active for this recipient. 


Incoming connection used ESMTP/EHLO. 


NOTIFY=FAILURES active for this recipient. 


Incoming connection used LMTP/LHLO. 


NOTIFY=SUCCESSES active for this recipient. 


SSL/TLS used to secure connection. 

The example below illustrates the use of a complex REVERSE and FORWARD mapping. Suppose that a system or pseudo domain named associated with the mr_local channel produces RFC 822 addresses of the general form:

"lastname, firstname"



Although these addresses are perfectly legal they often confuse other mailers which do not fully comply with RFC 822 syntax rules—mailers which do not handle quoted addresses properly, for instance. Consequently, an address format which does not require quoting tends to operate with more mailers. One such format is

Example of a complex FORWARD and REVERSE mapping:


 *|mr_local|"*,$ *" $Y"$1,$ $2"
 *|mr_local|"*,*"   $Y"$1,$ $2"
 *|*|"*,$ *"        $Y$3.$
 *|*|"*,*"          $Y$3.$
 *|mr_local|*.*     $Y"$2,$ $1"
 *|*|*.*            $Y$2.$


 "*,$ *"            $Y"$0,$ $1"
 "*,*"              $Y"$0,$ $1"
 *.*                $Y"$1,$ $0"

So the goals of the sample mapping tables in the above example are threefold. (1) Allow any of these three address formats above to be used. (2) Present only addresses in the original format to the mr_local channel, converting formats as necessary. (3) Present only addresses in the new unquoted format to all other channels, converting formats as necessary. (The REVERSE mapping shown assumes that bit 3 in the MTA option USE_REVERSE_DATABASE is set. The Forward Lookup Table

In cases where address forwardings need to be auto-registered or source specific, the forward lookup table is available. Note that use of the Forward lookup table for simple forwarding of messages is generally not appropriate; the aliases file or alias lookup table is a more efficient way to perform such forwarding. By default, the forward lookup table is not used at all; its use must be explicitly enabled via the USE_FORWARD_DATABASE option. Forward table lookups are performed after address rewriting and after alias expansion is performed, and after any FORWARD mapping is checked. If a forward table lookup succeeds, the resulting substituted address is then run through the MTA address rewriting process all over again.

There are two mechanisms available for the forward lookup table, an in-memory hash table or conventional text database. Unless the size of the table is prohibitively large then hash table is recommended. (1,000 is not prohibitively large, 100,000 is). The hash table is enabled by setting bit 2 (value 4) in the use_text_databaseS option as well as setting use_forward_database. The hash table is read from msg-svr-base/configure/forward.txt, compiled into the reloadable part of the configuration, and can be forced to be reloaded into the active MTA processes by the imsimta reload command.

The format of the source text file by default is expected to be:

user1@domain1 changedmailbox1@changeddomain1
user2@domain2 changedmailbox@changeddomain2

But if source specific use of the forward text database has been enabled by setting bit 2 of the USE_FORWARD_DATABASE option, then the source text file format expected is:

source-channel|source-address|original-address changed-address

For instance, an entry such as

tcp_limited||  “helen of troy”

will map the To: address to “helen of troy” if and only if the message is coming from and the enqueuing channel is tcp_limited.

See 10.9.1 MTA Text Databases for more information on the Forward Text database.