Sun Java System Messaging Server 6.3 Administration Reference

Mapping File

Many components of the MTA employ table lookup-oriented information. Generally speaking, this sort of table is used to transform (that is, map) an input string into an output string. Such tables, called mapping tables, are usually presented as two columns, the first (or left-hand) column giving the possible input strings and the second (or right-hand) column giving the resulting output string for the input it is associated with. Most of the MTA databases are instances of just this sort of mapping table. The MTA database files, however, do not provide wildcard-lookup facilities, owing to inherent inefficiencies in having to scan the entire database for wildcard matches.

The mapping file provides the MTA with facilities for supporting multiple mapping tables. Full wildcard facilities are provided, and multistep and iterative mapping methods can be accommodated as well. This approach is more compute-intensive than using a database, especially when the number of entries is large. However, the attendant gain in flexibility may serve to eliminate the need for most of the entries in an equivalent database, and this may result in lower overhead overall.

For discussion on REVERSE and FORWARD address mapping, see the Sun Java System Messaging Server 6.3 Administration Guide.

Locating and Loading the Mapping File

All mappings are kept in the MTA mapping file. (This is the file specified with the IMTA_MAPPING_FILE option in the MTA tailor file; by default, this is msg-svr-base/config/mappings.) The contents of the mapping file is incorporated into the compiled configuration.

The mapping file should be world readable. Failure to allow world-read access leads to erratic behavior.

File Format in the Mapping File

The mapping file consists of a series of separate tables. Each table begins with its name. Names always have an alphabetic character in the first column. The table name is followed by a required blank line, and then by the entries in the table. Entries consist of zero or more indented lines. Each entry must be preceded by at least one space. Each entry line consists of two columns separated by one or more spaces or tabs. Any spaces within an entry must be quoted using the $ character. A blank line must appear after each mapping table name and between each mapping table; no blank lines can appear between entries in a single table. Comments are introduced by an exclamation mark (!) in the first column.

The resulting format looks like:


  pattern1-1    template1-1
  pattern1-2    template1-2
  pattern1-3    template1-3
     .           .
     .           .
     .           .
  pattern1-n    template1-n


  pattern2-1    template2-1
  pattern2-2    template2-2
  pattern2-3    template2-3
     .           .
     .           .
     .           .
  pattern2-n    template2-n




An application using the mapping table TABLE-2-NAME would map the string pattern2-2 into whatever is specified by template2-2. Each pattern or template can contain up to 252 characters. There is no limit to the number of entries that can appear in a mapping (although excessive numbers of entries may consume huge amounts of CPU and can consume excessive amounts of memory). Long lines may be continued by ending them with a backslash (\). The white space between the two columns and before the first column may not be omitted.

Duplicate mapping table names are not allowed in the mapping file.

Including Other Files in the Mapping File

Other files may be included in the mapping file. This is done with a line of the form:


This effectively substitutes the contents of the file file-spec into the mapping file at the point where the include appears. The file specification should specify a full file path (directory, and so forth). All files included in this fashion must be world readable. Comments are also allowed in such included mapping files. Includes can be nested up to three levels deep. Include files are loaded at the same time the mapping file is loaded—they are not loaded on demand, so there is no performance or memory savings involved in using include files.

Mapping Operations

All mappings in the mapping file are applied in a consistent way. The only things that change from one mapping to the next is the source of input strings and what the output from the mapping is used for.

A mapping operation always starts off with an input string and a mapping table. The entries in the mapping table are scanned one at a time from top to bottom in the order in which they appear in the table. The left side of each entry is used as pattern, and the input string is compared in a case-blind fashion with that pattern.

Mapping Entry Patterns

Patterns can contain wildcard characters. In particular, the usual wildcard characters are allowed: an asterisk (*) matches zero or more characters, and each percent sign (%) matches a single character. Asterisks, percent signs, spaces, and tabs can be quoted by preceding them with a dollar sign ($). Quoting an asterisk or percent sign robs it of any special meaning. Spaces and tabs must be quoted to prevent them from ending prematurely a pattern or template. Literal dollar sign characters should be doubled ($$), the first dollar sign quoting the second one.

Table 4–14 Mapping Pattern Wildcards



Match exactly one character. 

Match zero or more characters, with maximal or “greedy” left-to-right matching 

Back match  


$ n* 

Match the nth wildcard or glob. 




Use minimal or “lazy” left-to-right matching. 


Turn off “saving” of the succeeding wildcard or glob. 


Turn on “saving” of the succeeding wildcard or glob; this is the default. 

Glob wildcard  



Match one alphabetic character, A-Z or a-z. 


Match zero or more alphabetic characters, A-Z or a-z. 


Match one binary digit (0 or 1). 


Match zero or more binary digits (0 or 1). 


Match one decimal digit 0-9. 


Match zero or more decimal digits 0-9. 


Match one hexadecimal digit 0-9 or A-F. 


Match zero or more hexadecimal digits 0-9 or A-F. 


Match one octal digit 0-7. 


Match zero or more octal digits 0-7. 


Match one symbol set character, that is, 0-9, A-Z, a-z, _, $. 


Match zero or more symbol set characters, that is, 0-9, A-Z, a-z, _, $. 


Match one tab or vertical tab or space character. 


Match zero or more tab or vertical tab or space characters. 


A synonym for $H%. 


A synonym for $H*. 

$[ c]% 

Match character c. 

$[ c]* 

Match arbitrary occurrences of character c. 

$[ c1 c2 ... cn ]%

Match exactly one occurrence of character c1, c2, or cn.

$[ c1 c2 ... cn ]*

Match arbitrary occurrences of any characters c1, c2, or cn.

$[ c1 -cn ]%

Match any one character in the range c1 to cn.

$[ c1 -cn ]*

Match arbitrary occurrences of characters in the range c1 to cn.

$< IPv4> 

Match an IPv4 address, ignoring bits. 


Match an IPv4 address, keeping prefix bits. 


Match an IPv6 address. 

For more information about mapping pattern wildcards, see Mappings File in Sun Java System Messaging Server 6.3 Administration Guide.

Mapping Entry Templates

Table 4–15 lists the special substitution and standard processing metacharacters. Any other metacharacters are reserved for mapping-specific applications.

See the Sun Java System Messaging Server 6.3 Administration Guide for more discussion on mapping entry templates.

Table 4–15 Mapping Template Substitutions and Metacharacters

Substitution sequence  



The nth wildcarded field as counted from left to right starting from 0.


Sequence number substitution. 


LDAP search URL lookup; substitute in result. 


Applies specified mapping table to supplied string. 


General database substitution. 


Adds the capability to access per-domain attributes. domain is the domain in question and attribute is the attribute associated with the domain. If the domain exists and has the attribute, its initial value is substituted into the mapping result; if either the attribute or the domain does not exist, the mapping entry fails. 

Attributes can be domain LDAP attributes or the special attributes defined below: 

_base_dn_ - The base DN for user entries in the domain 

_domain_dn_ - The DN of the domain entry itself 

_domain_name_ - The name of the domain (as opposed to an alias) 

_canonical_name_ - The canonical name associated with the domain 


Invokes site-supplied routine; substitute in result. 




Continues the mapping process starting with the next table entry; uses the output string of this entry as the new input string for the mapping process. 


Ends the mapping process now; uses the output string from this entry as the final result of the mapping process. 


Continues the mapping process starting with the next table entry; use the output string of this entry as the new input string; after all entries in the table are exhausted, makes one more pass, starting with the first table entry. A subsequent match may override this condition with a $C, $E, or $R metacharacter.


Continues the mapping process starting with the first entry of the mapping table; uses the output string of this entry as the new input string for the mapping process. 


Inserts the nth left character of the current address starting from position 0. The entire address is inserted if n is omitted. 


Inserts the nth left component of the mailhost starting from 0. The entire mailhost is inserted of n is omitted. 


Mapping entry succeeds x percent of the time. 


Forces subsequent text to lowercase. 


Forces subsequent text to uppercase. 


Leaves subsequent text in its original case. 


Specifies that substituted characters undergo quoting appropriate for insertion into LDAP search filters. 


Match only if the specified flag is set. 


Match only if the specified flag is clear. 

For more information on Processing Control, see Processing Control ($C, $L, $R, $E) in Sun Java System Messaging Server 6.3 Administration Guide.

For more information on the substitution sequences and metacharacters, see Chapter 10, About MTA Services and Configuration, in Sun Java System Messaging Server 6.3 Administration Guide.

For details about which MTA processes use which tables and when, see Mappings File in Sun Java System Messaging Server 6.3 Administration Guide.