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-hand side of each entry is used as pattern and the input string is compared in a case-blind fashion with that pattern.
Patterns can contain wildcard characters. In particular, the usual wildcard characters are allowed: an asterisk (*) will match zero or more characters and each percent sign (%) will match 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.
All other characters in a pattern just represent and match themselves. In particular, single and double quote characters as well as parentheses have no special meaning in either mapping patterns or templates; they are just ordinary characters. This makes it easy to write entries that correspond to illegal addresses or partial addresses.
Asterisk wildcards maximize what they match by working from left to right across the pattern. For instance, when the string "a/b/c" is compared to the pattern */*, the left asterisk will match "a/b" and the right asterisk will match the remainder, "c".
If the comparison of the pattern in a given entry fails, no action is taken; the scan proceeds to the next entry. If the comparison succeeds, the right-hand side of the entry is used as a template to produce an output string. The template effectively causes the replacement of the input string with the output string that is constructed from the instructions given by the template.
Almost all characters in the template simply produce themselves in the output. The one exception is a dollar sign ($).
A dollar sign followed by a dollar sign, space, or tab produces a dollar sign, space, or tab in the output string. Note that all these characters must be quoted in order to be inserted into the output string.
A dollar sign followed by a digit n calls for a substitution; a dollar sign followed by an alphabetic character is referred to as a "metacharacter". Metacharacters themselves will not appear in the output string produced by a template. See TABLE 3-13 for a list of the special substitution and standard processing metacharacters. Any other metacharacters are reserved for mapping-specific applications.
Note that any of the metacharacters $C, $E, $L, or $R, when present in the template of a matching pattern, will influence the mapping process, controlling whether it terminates or continues. That is, it is possible to set up iterative mapping table entries, where the output of one entry becomes the input of another entry. If the template of a matching pattern does not contain any of the metacharacters $C, $E, $L, or $R, then $E (immediate termination of the mapping process) is assumed.
The number of iterative passes through a mapping table is limited to prevent infinite loops. A counter is incremented each time a pass is restarted with a pattern that is the same length or longer than the previous pass. If the string has a shorter length than previously, the counter is reset to zero. A request to reiterate a mapping is not honored after the counter has exceeded 10.
TABLE 3-13 Mapping Template Substitutions and Metacharacters
Wildcard Field Substitutions ($n)
A dollar sign followed by a digit n is replaced with the material that matched the nth wildcard in the pattern. The wildcards are numbered starting with 0. For example, the following entry would match the input string PSI%A::B and produce the resultant output string b@a.psi.network.org:
The input string PSI%1234::USER would also match producing USER@1234.psi.network.org as the output string. The input string PSIABC::DEF would not match the pattern in this entry and no action would be taken; that is, no output string would result from this entry.
Controlling Text Case ($\, $^, $_)
$\ forces subsequent text to lowercase, $^ forces subsequent text to uppercase, and $_ causes subsequent text to retain its original case. For instance, these metacharacters may be useful when using mappings to transform addresses for which case is significant.
Processing Control ($C, $L, $R, $E)
The $C, $L, $R, and $E metacharacters influence the mapping process, controlling whether and when the mapping process terminates. $C causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process. $L causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process, and, if no matching entry is found, making one more pass through the table starting with the first table entry; a subsequent matching entry with a $C, $E, or $R metacharacter overrides this condition. $R causes the mapping process to continue from the first entry of the table, using the output string of the current entry as the new input string for the mapping process. $E causes the mapping process to terminate; the output string of this entry is the final output. $E is the default.
Mapping table templates are scanned left to right. So to set a $C, $L, or $R flag for entries that may "succeed" or "fail" (for example, general database substitutions or random-value controlled entries), put the $C, $L, or $R metacharacter to the left of the part of the entry that may succeed or fail; otherwise, if the remainder of the entry fails, the flag will not be seen.
Entry Randomly Succeeds or Fails ($?x?)
$?x? in a mapping table entry causes the entry to "succeed" x percent of the time; the rest of the time, the entry "fails" and the output of the mapping entry's input is taken unchanged as the output. (Note that, depending upon the mapping, the effect of the entry "failing" is not necessarily the same as the entry not matching in the first place.) x should be a real number specifying the success percentage.
For instance, suppose that a system with IP address 123.45.6.78 is sending your site just a little too much e-mail and you'd like to slow it down; if you're using the multithreaded TCP SMTP channel, you can use a PORT_ACCESS mapping table in the following way. Suppose you'd like to allow through only 25 percent of its connection attempts and reject the other 75 percent of its connection attempts. The following PORT_ACCESS mapping table uses $?25? to cause the entry with the $Y (accept the connection) to succeed only 25 percent of the time; the other 75 percent of the time, when this entry fails, the initial $C on that entry causes IMTA to continue the mapping from the next entry, which causes the connection attempt to be rejected with an SMTP error and the message "Try again later."
Sequence Number Substitutions ($#...#)
A $#...# substitution increments the value stored in an IMTA sequence file and substitutes that value into the template. This can be used to generate unique, increasing strings in cases where it is desirable to have a unique qualifier in the mapping table output; for instance, when using a mapping table to generate file names.
Permitted syntax is any one of the following:
The required seq-file-spec argument is a full file specification for an already existing IMTA sequence file, and where the optional radix and width arguments specify the radix (base) in which to output the sequence value, and the number of digits to output, respectively. The default radix is 10. Radices in the range -36 to 36 are also allowed; for instance, base 36 gives values expressed with digits 0,...,9,A,...,Z. By default, the sequence value is printed in its natural width, but if the specified width calls for a greater number of digits, then the output will be padded with 0's on the left to obtain the desired number of digits. Note that if a width is explicitly specified, then the radix must be explicitly specified also.
As noted above, the IMTA sequence file referred to in a mapping must already exist. To create an IMTA sequence file, use the following command:
or
A sequence number file accessed via a mapping table must be world readable in order to operate properly. You must also have an IMTA user account in order to use such sequence number files.
Mapping Table Substitutions ($|...|)
A substitution of the form $|mapping,argument| is handled specially. IMTA looks for a auxiliary mapping table named mapping in the IMTA mapping file, and uses argument as the input to that named auxiliary mapping table. The named auxiliary mapping table must exist and must set the $Y flag in its output if it is successful; if the named auxiliary mapping table does not exist or doesn't set the $Y flag, then that auxiliary mapping table substitution fails and the original mapping entry is considered to fail: the original input string will be used as the output string.
Note that when you wish to use processing control metacharacters such as $C, $R, or $L in a mapping table entry that does a mapping table substitution, the processing control metacharacter should be placed to the left of the mapping table substitution in the mapping table template; otherwise the "failure" of a mapping table substitution will mean that the processing control metacharacter will not be seen.
General database substitutions (${...})
A substitution of the form ${text} is handled specially. The text part is used as a key to access the general database. This database is generated with the IMTA crdb utility. If text is found in the database, the corresponding template from the database is substituted. If text does not match an entry in the database, the input string is used unchanged as the output string.
If a general database exists, it should be world readable to insure that it operates properly.
Note that when wishing to use processing control metacharacters such as $C, $R, or $L in a mapping table entry that does a general database substitution, the processing control metacharacter should be placed to the left of the general database substitution in the mapping table template; otherwise the "failure" of a general database substitution will mean that the processing control metacharacter will not be seen.
Site-supplied Routine Substitutions ($[...])
A substitution of the form $[image,routine,argument] is handled specially. The image,routine,argument part is used to find and call a customer-supplied routine. At runtime, IMTA uses dlopen and dlsym to dynamically load and call the routine routine from the shared library image. The routine routine is then called as a function with the following argument list:
argument and result are 252-byte long character string buffers. argument and result are passed as a pointer to a character string (for example, in C, as char*). arglength and reslength are signed, long integers passed by reference. On input, argument contains the argument string from the mapping table template, and arglength the length of that string. On return, the resultant string should be placed in result and its length in reslength. This resultant string will then replace the $[image,routine,argument] in the mapping table template. The routine routine should return 0 if the mapping table substitution should fail and -1 if the mapping table substitution should succeed. If the substitution fails, then normally the original input string will be used unchanged as the output string.
Note that when wishing to use processing control metacharacters such as $C, $R, or $L in a mapping table entry that does a site-supplied routine substitution, the processing control metacharacter should be placed to the left of the site-supplied routine substitution in the mapping table template; otherwise, the "failure" of a mapping table substitution will mean that the processing control metacharacter will not be seen.
The site-supplied routine callout mechanism allows IMTA's mapping process to be extended in all sorts of complex ways. For example, in a PORT_ACCESS or ORIG_SEND_ACCESS mapping table, a call to some type of load monitoring service could be performed and the result used to decide whether or not to accept a connection or message.
The site-supplied shared library image image should be world readable.
Note - This facility is not designed for use by casual users; it is intended to be used to extend IMTA's capabilities system-wide.