Sun Java System Messaging Server 6.3 Administration Guide

10.9 To Convert Addresses from an Internal Form to a Public Form

Addresses can be converted from an internal form to a public, advertised form using the Address-Reversal text database (also called the reverse text database) and the REVERSE mapping table. For example, while might be a valid address within the domain, it might not be an appropriate address to expose to the outside world. You may prefer a public address like

Messaging Server provides other facilities for address manipulation, such as the aliases file and specialized mapping tables. For best performance, however, rewrite rules should be used whenever possible to perform address manipulations. See Chapter 11, Configuring Rewrite Rules.

This section consists of the following subsections:

In the reverse text database, the public address for each user is specified by the mail attribute of the user entry in the directory.

The reverse text database contains a mapping between a valid address and a public address. See 10.9.1 MTA Text Databases for more information.

If an address is found in the database, the corresponding right side from the database is substituted for the address. If the address is not found, an attempt is made to locate a mapping table named REVERSE in the mappings file. No substitution is made, and rewriting terminates normally if the table does not exist or no entries from the table match.

If a REVERSE mapping table is found in the mappings file, and if the address matches a mapping entry, the resulting string replaces the address if the entry specifies a $Y. A $N discards the result of the mapping. If the mapping entry specifies $D in addition to $Y, the resulting string runs through the reversal database once more; and if a match occurs, the template from the database replaces the mapping result (and hence the address). The form of general REVERSE mapping table entries (that is, entries that apply to all channels) is shown below. Note that flags can be either in front of the new address or at the end.


   OldAddress        $Y[Flags]NewAddress


The form of channel-specific entries (that is, mapping that only occurs only on messages passing through a specific channel) is shown below. Note that you must set use_reverse_database to 13 in the option.dat for channel-specific entries to work.


   source-channel|destination-channel|OldAddress  $Y[Flags]NewAddresS


REVERSE mapping table flags as shown in Table 10–7.

Table 10–7 REVERSE mapping table flags




Use output as new address. 


Address remains unchanged. 


Run output through the reversal database. 


Add pattern as reverse database entry. 


Add pattern as forward database entry. 

Flag comparison



Match only header (body) addresses. 


Match only envelope addresses. 


Match only forward pointing addresses. 


Match only backwards pointing addresses. 


Match only message-ids. 

10.9.1 MTA Text Databases

MTA use of sleepycat databases is being deprecated because of the instability it introduces in Messaging Server deployments. (Note that sleepycat will not be removed in the near future). As a result, MTA text databases for the reverse, forward and general databases should be used instead.

To set up text databases:

  1. Prepare a text file containing the data.

    This is in the same format that imsimta crdb uses: one entry per line with two fields separated by one or more spaces. The file names are specified by the IMTA_GENERAL_DATA, IMTA_REVERSE_DATA, and IMTA_FORWARD_DATAoptions in imta_tailor), which normally point, respectively, to IMTA_TABLE:general.txt, IMTA_TABLE:reverse.txt, and IMTA_TABLE:forward.txt in msg-svr-base/config/.

    general.txt - general databasereverse.txt - reverse databaseforward.txt - forward database

  2. Set the appropriate bit or bits in the USE_TEXT_DATABASES option:

    bit 0 (value 1) - use text file for general databasebit 1 (value 2) - use text file for reverse database bit 2 (value 4) - use text file for forward database

  3. Set whatever additional options are needed to enable the desired databases.


  4. Run imsimta cnbuild

  5. Run imsimta reload

The only case where USE_TEXT_DATABASES is not appropriate is for highly dynamic data. In those cases, you may be better served by writing your own MTA plug-ins rather than by relying on the built-in database support.

If the text database is not appropriate, and you wish to use the crdb (Sleepycat) database support, then it may be possible, by structuring your database usage style and updating process appropriately, to use either imsimta crdb or imsimta db to update the database without recompiling, reloading, or restarting. However, for this to work you either have to be in a situation where you can only add or update existing entries, in which case you can use imsimta crdb. Otherwise, you have to have your data structured as a series of add/delete/change operations. If your data isn't structured this way--and it usually isn't--you're back to replacing the entire database when updating, which in this case, makes text databases preferable.

10.9.2 To Set Address Reversal Controls

The reverse and noreverse channel keywords, and the MTA options USE_REVERSE_DATABASE and REVERSE_ENVELOPE are used to control the specifics of when and how address reversal is applied. By default, the address reversal operation applies to all addresses, not just to backward pointing addresses.

Address reversal can be enabled or disabled by setting the value of the REVERSE_ENVELOPE system option (Default: 1-on, 0-off).

noreverse on the destination channel specifies that address reversal is not applied to addresses in messages. reverse specifies that address reversal is applied. See 12.6.9 Enabling Channel-Specific Use of the Reverse Database for details.

USE_REVERSE_DATABASE controls whether the MTA uses the address reversal text database and REVERSE mapping as a source of substitution addresses. A value of 0 means address reversal is not used with any channel. A value of 5 (default) specifies that address reversal is applied to all addresses—not just to backward pointing addresses— after they have been rewritten by the MTA address rewriting process. A value of 13 specifies that address reversal is applied to addresses with the reverse channel keyword—not just to backward pointing addresses— after they have been rewritten by the MTA address rewriting process. Further granularity of address reversal operation can be specified by setting the bit values of the USE_REVERSE_DATABASE option. See Option File Format and Available Options in Sun Java System Messaging Server 6.3 Administration Reference for details.

The REVERSE_ENVELOPE option controls whether or not address reversal is applied to envelope From addresses as well as message header addresses.

See the detailed descriptions of these options and keywords in the Sun Java System Messaging Server Administration Reference for additional information on their effects. General Reverse Mapping Example

An example of a general REVERSE Mapping is as follows: suppose that the internal addresses at are of the form However, the user name space is such that and specify the same person for all hosts at The following REVERSE mapping may be used in conjunction with the address-reversal text database:


   *@*        $$Y$D

In this example, addresses of the form would be changed to The $D metacharacter causes the address-reversal database to be consulted. The address-reversal text database should contain entries of the form:

     Channel-Specific Reverse Mapping Example

By default, the address reversal text database is used if the routability scope is set to the mail server domains. An example of a channel-specific REVERSE mapping table entry would be as follows:


   tcp_*|tcp_local|    $D$

This entry tells the MTA that for any mail with source channel of tcp_* going out the destination channel of tcp_local to change addresses of the form to

Note –

To enable channel-specific reverse mapping, you must set USE_REVERSE_DATABASE option in option.dat to 13. (Default=5.)

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.