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.

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.

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:

<file-spec

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

Wildcard

Description

%

Match exactly one character.

*

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

Back match

Description

$ n*

Match the nth wildcard or glob.

Modifiers

Description

$_

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.

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.

$}domain,attribute{

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.

Metacharacter

Description

$C

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.

$E

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

$L

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.

$R

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.

$nA

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

$nX

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