About MTA Services and Configuration

Skip to end of metadata
Go to start of metadata

About MTA Services and Configuration

This information describes general MTA services and configuration.

Topics:

Compiling the MTA Configuration

Whenever an MTA configuration file such as imta.cnf, mappings, aliases, or option.dat is modified, you must recompile the configuration. This compiles the configuration files into a single image in shared memory (on UNIX) or a dynamic link library (NT).

The compiled configuration has a static and dynamic reloadable part. If the dynamic part is changed, and you run an imsimta reload, a running program reloads the dynamic data. The dynamic parts are mapping tables, aliases, and lookup tables.

The main reason for compiling configuration information is performance. Another feature of using a compiled configuration is that configuration changes can be tested more conveniently since the configuration files themselves are not "live" when a compiled configuration is in use.

Whenever a component of the MTA (such as a channel program) must read the configuration file, it first checks to see if a compiled configuration exists. If it does, the image is attached to the running program. If the image attach operation fails, the MTA falls back on the old method of reading the text files instead.

If you make changes to the reverse, forward, or general databases, then issue the command imsimta reload to get the changes to take effect. If you make changes to the imta.cnf, mappings file, aliases, conversions, or option.dat files that do not affect the job controller, then you should issue an imsimta cnbuild followed by an imsimta restart smtp. If you make changes to dispatcher.cnf you need to do an imsimta restart dispatcher. If you make changes to the configuration files that are included in the compiled configuration that affect the job controller, but not the SMTP server, in many cases you should issue the following commands: imsimta cnbuild and imsimta restart job_controller.

If you make changes to the configuration files that are included in the compiled configuration that affect both the SMTP server and the job controller, you should issue the following commands:

(See MTA Commands for details on these commands.)

Other instances where you must restart the job controller:

  • Changing the controller configuration files, job_controller.cnf or job_controller.site, or any files included into job_controller.cnf.
  • Adding or changing use of the channel keywords pool, maxjobs, master, slave, single, single_sys, or multiple in the imta.cnf file. Adding or changing a threaddepth channel keyword in the imta.cnf can be dealt with instead by running imsimta cache -change -thread_depth=....
  • If you want changes to master channel jobs to take effect immediately (rather than waiting for the controller to time-out existing channel jobs), then any relevant (which means almost all) changes to the MTA configuration or channel option files. (Changes to the mappings file or to MTA databases: (1) aren't usually relevant for outbound channel jobs, though they can matter to "intermediate" channels such as conversion, process, reprocess, and (2) if those intermediate channels are a concern, changes to the mappings file or to databases can often be handled by running imsimta reload, avoiding a restart of the Job Controller.) The desire to have changes take effect immediately needs to be balanced against the damage that restarting the Job Controller does. Also consider just how much longer a particular sort of job is going to run anyhow.

The MTA configuration includes imta.cnf and all files it includes (such as internet.rules), the alias file, the mappings file, the conversions file, the option.dat file (and any files any of the preceding include), and imta.filter, and the reverse, forward, and general data files, and potentially some configutil parameters.

Any changes (such as additions or changes to keywords on channel definitions) to imta.cnf also require running imsimta cnbuild. That's a basic, regardless of whether a Job Controller restart is needed.

Try to avoid restarting the Job Controller, especially at times of large numbers of messages in the queues, unless one of the preceding conditions necessitates a restart.

Do not use the imsimta refresh command on production systems because it is often not necessary to restart the job controller, and restarting the job controller resets message retries, delayed notification messages, bounced messages, and so on.

The MTA Configuration File

The primary MTA configuration file is imta.cnf. By default, this file is found at msg-svr-base/config/imta.cnf. This file contains MTA channel definitions as well as the channel rewrite rules. The channel associated with a rewritten destination address becomes the destination channel. The system will typically work well using the default imta.cnf.

This section provides a brief introduction to the MTA configuration file. For details about configuring the rewrite rules and channel definitions that make up the MTA configuration file, see Configuring Rewrite Rules and Configuring Channel Definitions.

By modifying the MTA configuration file, you establish the channels in use at a site and establish which channels are responsible for which sorts of addresses by using rewrite rules. The configuration file establishes the layout of the email system by specifying the transport methods available (channels) and the transport routes (rewrite rules) associating types of addresses with appropriate channels.

The configuration file consists of two parts: domain rewriting rules and channel definitions. The domain rewriting rules appear first in the file and are separated from the channel definitions by a blank line. The channel definitions are collectively referred to as the channel table. An individual channel definition forms a channel block.

The following example of an imta.cnf configuration file shows how rewrite rules are used to route messages to the proper channel. No domain names are used to keep things as simple as possible. The rewrite rules appear in the upper half of the configuration file followed by the channel definitions in the lower half of the configuration file.

The key items (labeled with numbers, enclosed in parentheses) in the preceding configuration file are explained in the following list:

  1. Exclamation points (!) are used to include comment lines. The exclamation point must appear in the first column. An exclamation point appearing anywhere else is interpreted as a literal exclamation point.
  2. The rewrite rules appear in the first half of the configuration file. No blank lines can appear among the lines of rewrite rules. Lines with comments (beginning with an exclamation point in the first column) are permitted.
  3. The first blank line to appear in the file signifies the end of the rewrite rules section and the start of the channel blocks. These definitions are collectively referred to as the_channel host table_, which defines the channels that the MTA can use and the names associated with each channel.
  4. The first channel block to appear is usually the local or l channel. Blank lines then separate each channel block from one another. (An exception is the defaults channel, which can appear before the l channel).
  5. A typical channel definition consists of a channel name (a_channel), some keywords which define the configuration of a channel (defragment charset7 usascii), and a routing system (a-daemon), which is also called a channel tag.
  6. The contents of other files can be included in the configuration file. If a line is encountered with a less than sign (<) in column one, the rest of the line is treated as a file name. The file name should always be an absolute and full file path. The file is opened and its contents are spliced into the configuration file at that point. Include files may be nested up to three levels deep. Any files included in the configuration file must be world-readable just as the configuration file is world-readable.

The following table shows how some example addresses would be routed by the preceding configuration.

Addresses and Associated Channels
Address Queued to channel
u@a a_channel
u@b b_channel
u@c b_channel
u@d a_channel

Refer to Rewrite Rules, Channel Definitions, and Configuring Rewrite Rules for more information on the MTA configuration file.

Note
Whenever changes are made to the imta.cnf file, the MTA configuration must be recompiled. See Compiling the MTA Configuration.

Mappings File

Many components of the MTA employ table lookup-oriented information. This type of table is used to transform, that is map, an input string into an output string. Such mapping tables are represented as two columns. The first (left-hand) column provides patterns to which an input strings is compared. The second (right-hand) column supplies the template by which the input string is mapped to an output string. For details about which MTA processes use which tables and when, see Messaging Server Mapping Tables.

Most of the MTA databases that contain different types of MTA data, and which should not be confused with mapping tables, are instances of just this type of 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 MTA mappings file supports multiple mapping tables. Wildcard capabilities are provided, as well as multistep and iterative mapping methods. 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.

Mapping tables are kept in the MTA mappings file in the msg-svr-base/config/ directory. The contents of the mappings file are incorporated into the compiled configuration as part of the reloadable section (see Compiling the MTA Configuration). Failure to allow world-read access leads to erratic behavior. Whenever changes are made to the mappings file, the MTA configuration must be recompiled.

The following table lists the mapping tables.

Messaging Server Mapping Tables
Mapping Table Description
AUTH_REWRITE Used with the authrewrite keyword to modify header and envelope addresses using addressing information obtained from authentication operations (SASL). See TCP/IP Connection and DNS Lookup Support.
CHARSET-CONVERSION Used to specify what sorts of channel-to-channel character set conversions and message reformatting should be done. See Character Set Conversion and Message Reformatting.
COMMENT_STRINGS Used to modify address header comments (strings enclosed in parentheses). See Handling Comments in Address Header Lines.
CONVERSIONS Used to select message traffic for the conversion channel. See Selecting Traffic for Conversion Processing.
FORWARD Used to perform forwarding similar to that performed using the alias file or alias database. See The Forward Lookup Table and FORWARD Address Mapping.
FROM_ACCESS Filter based on envelope From addresses. Used by tcp_smtp_server when MAIL FROM is received. Use this table if the To address is irrelevant. See Controlling Access with Mapping Tables.
INTERNAL_IP Used to recognize systems and subnets that are internal. Called by entries in the PORT_ACCESS table. See To Add SMTP Relaying.
IP_ACCESS Block incoming connections based on source channel, IP address count for remote server, index of current IP address being tried. See Controlling Access with Mapping Tables.
MAIL_ACCESS Filter based on combination of information available in SEND_ACCESS and PORT_ACCESS tables. Used by tcp_smtp_server when RCPT TO is received. See Controlling Access with Mapping Tables.
NOTIFICATION_LANGUAGE Used to customize or localize notification messages. See Controlling Delivery Status Notification Messages.
ORIG_MAIL_ACCESS Same as MAIL_ACCESS except using the value of the original To address after rewriting but before alias expansion. See Controlling Access with Mapping Tables.
ORIG_SEND_ACCESS Same as SEND_ACCESS except using the value of the original To address after rewriting but before alias expansion. See Controlling Access with Mapping Tables.
PERSONAL_NAMES Used to modify personal names (strings preceding angle-bracket-delimited addresses). See Handling Personal Names in Address Header Lines.
PORT_ACCESS Block incoming connections based on source and destination IP address and TCP port number. Used by dispatcher immediately after accepting the TCP connection. Used by tcp_smtp_server when connection is handed off from dispatcher. See Controlling Access with Mapping Tables.
REVERSE Used to convert addresses from an internal form to a public, advertised form. To Convert Addresses from an Internal Form to a Public Form.
SEND_ACCESS Filter based on envelope From address, envelope To address, and source and destination channels. Used by tcp_smtp_server when RCPT TO is received. See Controlling Access with Mapping Tables.
SMS_Channel_TEXT Used for site-defined text conversions. See Site-defined Text Conversions.
X-ATT-NAMES Used to retrieve a parameter value from a mapping table. See To Call Out to a Mapping Table from a Conversion Entry.
X-REWRITE-SMS-ADDRESS Used for local SMS address validity checks. See Site-defined Address Validity Checks and Translations.

File Format in the Mappings File

The mappings 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 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:

An application using the mapping table TABLE2_NAME would map the input string which matched pattern2-2 into whatever is specified by template2-2. Each pattern or template can contain up to 256 and 1024 characters respectively. The maximum size of a line in the mapping file is 4096 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 (over 252 characters) 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 mappings file.

Including Other Files in the Mappings File

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

This effectively substitutes the contents of the file file-spec into the mappings 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 mappings file. Includes can be nested up to three levels deep. Include files are loaded at the same time the mappings file is loaded – when it is compiled. Includes are not loaded on demand, so there is no performance or memory savings involved in using include files.

Mapping Operations

Mapping tables can be thought of like programming subroutines or functions. They take an input string and input flags. They return an output string and output flags. All mapping tables follow the same rules, but the format of the input and output strings, and which input and output flags apply, varies depending on the purpose of the table, which is determined by the MTA process or function which uses the table. For details about which MTA processes use which tables and when, see Messaging Server Mapping Tables.

A mapping operation starts off with an input string (and possibly input flags). 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 input string is compared to the left side, the pattern, of the entry in a case-blind fashion. If the input string matches the pattern, the right side, the template, is processed. In the simplest form, the mapping table will return the result of processing that template.

The pattern can contain a variety of wildcard characters as well as characters which must be matched exactly.

The template can contain characters which will be output exactly as provided, as well as substitution sequences, which will be replaced with the result of performing another table lookup, or other callout, and metacharacters which can be used to test input flags or other conditions and set output flags. Such tests, call-outs, or lookups can result in success or failure as well as returning an output string or setting output flags. Other metacharacters can specify that if a subsequent test, call-out, or lookup fails, the mapping operation should continue scanning down the table for other entries that match the input string rather than returning immediately. Some output flags are simply set or clear. Other output flags require an argument which is passed back to the calling process as the value of that output flag. For more information about the significance of the ordering of output flag arguments, see the sections about the specific mapping tables.

For more information on patterns and templates, see the following subsections:

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.

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.
Glob wildcard Description
$A% Match one alphabetic character, A-Z or a-z.
$A* Match zero or more alphabetic characters, A-Z or a-z.
$B% Match one binary digit (0 or 1).
$B* Match zero or more binary digits (0 or 1).
$D% Match one decimal digit 0-9.
$D* Match zero or more decimal digits 0-9.
$H% Match one hexadecimal digit 0-9 or A-F.
$H* Match zero or more hexadecimal digits 0-9 or A-F.
$O% Match one octal digit 0-7.
$O* Match zero or more octal digits 0--7.
$S% Match one symbol set character, for example, 0-9, A-Z, a-z, _, $.
$S* Match zero or more symbol set characters, that is, 0-9, A-Z, a-z, _, $.
$T% Match one tab or vertical tab or space character.
$T* Match zero or more tab or vertical tab or space characters.
$X% A synonym for $H%.
$X* 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.
$(IPv4) Match an IPv4 address, keeping prefix bits.
${IPv6} Match an IPv6 address. Note that IPv6 connection handling is not currently supported in Messaging Server.

Within globs, that is, within a $[...] construct, the backslash character, (\) is the quote character. To represent a literal hyphen, -, or right bracket, ], within a glob the hyphen or right bracket must be quoted with a backslash.

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.

To specify multiple modifiers, or to specify modifiers and a back match, the syntax uses just one dollar character. For instance, to back match the initial wild card, without saving the back match itself, one would use $@0, not $@$0.

You can use imsimta test -match to test mapping patterns and specifically to test wildcard behavior in patterns.

Asterisk wildcards maximize what they match by working from left to right across the input string. For instance, when the input string a/b/c is compared to the pattern */*, the left asterisk matches a/b and the right asterisk matches the remainder, c.

The $_ modifier causes wildcard matching to be minimized, where the least possible match is considered the match, working from left to right across the pattern. For instance, when the string a/b/c is compared to the pattern $_*/$_*, the left $_* matches a and the right $_* matches b/c.

IP Matching

With IPv4 prefix matching, an IP address or subnet is specified, optionally followed by a slash and the number of bits from the prefix that are significant when comparing for a match. For example, the following matches anything in the 123.45.67.0 subnet:

With IPv4 ignore bits matching, an IP address or subnet is specified, optionally followed by a slash and the number of bits to ignore when checking for a match. For example, the following matches anything in the 123.45.67.0 subnet:

The following example matches anything in the range 123.45.67.4 through 123.45.67.7:

IPv6 matching matches an IPv6 address or subnet.

Phase 1 of IPv6 support was introduced in Messaging Server 7 Update 2.

Mapping Entry Templates

If the input string does not match the pattern in a given entry, no action is taken, and the scan proceeds to the next entry. If the input string matches the pattern, the right 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 do not appear in the output string produced by a template, but produce some special substitution or processing. See the following table for a list of the special substitution and standard processing metacharacters. Any other metacharacters are listed in the sections about specific mappings tables. See Access Control Mapping Tables.

Mapping Template Substitutions and Metacharacters
Substitution sequence Substitutes
$n The _n_th wildcarded field as counted from left to right starting from 0.
$#...# Sequence number substitution.
$]...[ 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. See Processing Control ($C, $L, $R, $E).
$E Ends the mapping process now; uses the output string from this entry as the final result of the mapping process. $+1E exits immediately without interpreting the rest of the template. See Processing Control ($C, $L, $R, $E).
$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. See Processing Control ($C, $L, $R, $E).
$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. See Processing Control ($C, $L, $R, $E).
$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 if n is omitted.
$?x? 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.
$= Forces subsequent substituted characters to undergo quoting appropriate for insertion into LDAP search filters.
$:x Match only if the specified flag is set.
$;x Match only if the specified flag is clear.

This section consists of the following subsections:

Wildcard Field Substitutions ($n)

A dollar sign followed by a digit n is replaced with the material that matched the _n_th 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.siroe.com:

The input string PSI%1234::USER would also match producing USER@1234.psi.siroe.com 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 ($\, $^, $_)

The metacharacter $\ 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 control whether and when the mapping process terminates. As described in Mapping Operations, the mapping process normally consists of a single pass, from top to bottom, ending at the first entry with a pattern matching the input string, with the result specified by the template of that entry. Even if the processing of a metacharacter in the template fails, the mapping process would normally terminate because the input string matched the pattern of that entry. The metacharacters $C, $L, and $R cause the mapping process to continue instead of terminate. The metacharacter $E explicitly terminates the mapping process, thus overriding a previous $C on the same line.

The metacharacters $C, $L, and $R can be used to change the input string and continue the mapping process. If the template modifies the output string and $C, $L, or $R are used, the mapping process continues with the output string of the current entry used as the input string for further operations. $C continues with the next entry. $L continues with the next entry, but if no matching entry is found before the end of the table, one more pass will be made starting again at the top of the table. $R continues from the top of the table.

Templates are processed from left to right. When the intention is that an entry should succeed and terminate the mapping process if the template succeeds, but that the mapping process should continue if the template fails, then the entry should use the $C (or $R or $L) metacharacter to the left of the part that may fail and $E to the right of that part.

For example, see the PORT_ACCESS table where the $|...| callout is used in To Use DNS Lookups Including RBL Checking for SMTP Relay Blocking to check the client IP address against the INTERNAL_IP table. If the lookup succeeds, the template processing ends with $Y and the mapping process is terminated by the $E. But if the lookup fails, the template processing ends with the failure, but the $C causes the mapping process to continue. Because this template generated no output string, the original input string remains unmodified.

Because metacharacters $L and $R reiterate the mapping process, 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 new input string that is the same length or longer than the previous pass. If the resulting output string has a shorter length than the input string, the counter is reset to zero. A request to reiterate a mapping is ignored after the counter has exceeded 10.

Note that any of the metacharacters $C, $E, $L, or $R, when present in the template, influences the mapping process and control 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.

Check for Special Flags ($:x, $;x)

Some mapping probes have special flags set. You can test their presence or absence using the general mapping table facility of the $: or $; tests. $:x causes an entry to match only if the flag x is set. $;x causes an entry to match only if the flag x is clear. See specific mapping table descriptions Messaging Server Mapping Tables for any special flags that apply for that table.

When the intention is that an entry should succeed and terminate if the flag check succeeds, but that the mapping process should continue if the flag check fails, then the entry should use the $C metacharacter to the left of the flag check and use the $E flag to the right of the flag check.

Entry Randomly Succeeds or Fails ($?x?)

The metacharacters $?x? in a mapping table entry cause 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. (Depending upon the mapping, the effect of the entry failing is not necessarily the same as the entry not matching in the first place.) The 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 SMTP email and you'd like to slow it down. You can use a PORT_ACCESS mapping table in the following way. Suppose want 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 the MTA 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 MTA 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 MTA sequence file. 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 is padded with 0s on the left to obtain the correct number of digits. If a width is explicitly specified, then the radix must be explicitly specified also.

The optional m argument is a modulus. If this fourth argument is specified, the value inserted is the sequence number retrieved from the file mod m. The default is not to perform any modulus operation.

As stated previously, the MTA sequence file referred to in a mapping must already exist. To create an MTA sequence file, use the following UNIX command:

or

A sequence number file accessed using a mapping table must be world readable in order to operate properly. You must also have an MTA user account (configured to be nobody in the imta_tailor file) in order to use such sequence number files.

URL substitutions, $]...[

A substitution of the form $]url[ is specially handled. url can be any supported URL type including file: and data:. Standard LDAP URLs can also be used, with the host and port omitted. The host and port are instead specified with the LDAP_HOST and LDAP_PORT options. That is, the LDAP URL should be specified as:

where the square bracket characters [ and ] shown previously indicate optional portions of the URL. The dn is required and is a distinguished name specifying the search base. The optional attributes, scope, and filter portions of the URL further refine the information to return. That is, attributes specifies the attribute or attributes to be returned from LDAP directory entries matching this LDAP query. The scope can be any of base, (the default), one, or sub. filter describes the characteristics of matching entries.

Certain LDAP URL substitution sequences are available for use within the LDAP query URL. The length of URLs can be 1024 characters. This also applies to expressions created by mappings and mapping calls to other mappings.

Mapping Table Substitutions ($|...|)

A substitution of the form $|mapping;argument| is handled specially. The MTA looks for an auxiliary mapping table named mapping in the MTA mappings 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 is used as the output string.

When you want 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 means that the processing control metacharacter is not seen.

General Lookup Table or Database Substitutions (${...})

A substitution of the form ${text} is handled specially. The text part is used as a key to access the general lookup table or database (see MTA Text Databases for more information). If text is found in the table, the corresponding template from the table is substituted. If text does not match an entry in the table, the input string is used unchanged as the output string.

If you are using the general lookup table you need to set the low order bit of the MTA option use_text_databases. That is, set it to an odd number. Changes to the general.txt need to be compiled into the MTA configuration using the imsimta cnbuild to compile and imsimta reload to reload the reloadable data.

If you are using a general database, it should be world readable to insure that it operates properly.

When you want to use processing control metacharacters such as $C, $R, or $L in a mapping table entry that does a general table substitution, the processing control metacharacter should be placed to the left of the general table substitution in the mapping table template. Otherwise, the "failure" of a general table substitution means that the processing control metacharacter is not seen.

Expression Substitutions ($`..')

A substitution of the form:

$`n>>x<<y'

where n is some value (for example, a $n value from the pattern), and x and y are the number of bits to shift the value. Consider the following substitution:

$`255>>4<<4'

This example results in 240; that is, shift right 4 bits causes 1111111111 to become 1111, then shift left 4 bits becomes 11110000.

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 on UNIX, the MTA 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:

The argument and result are 252-byte long character string buffers. The argument and result are passed as a pointer to a character string (for example, in C, as char*). The 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 then replaces 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 is used unchanged as the output string.

If you want to use processing control metacharacters such as $C, $R, or $L in a mapping table entry that does a site-supplied routine substitution, you place the processing control metacharacter to the left of the site-supplied routine substitution in the mapping table template. Otherwise, the "failure" of a mapping table substitution means that the processing control metacharacter is not seen.

The site-supplied routine callout mechanism enables the MTA'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.

Generate UTF-8 Strings

You can generate UTF-8 strings from Unicode character values in the general mapping table facility. A Unicode metacharacter sequence of the form:

produces a UTF-8 string containing the characters at position A0A0, 20, and A1A1 in it.

Other MTA Configuration Files

In addition to the imta.cnf file, Messaging Server provides several other configuration files to help you configure MTA services. These files are summarized in MTA Configuration Files.

This section consists of the following subsections:

If you make changes to the reverse, forward, or general databases, then issue the command imsimta reload to get the changes to take effect (see MTA Text Databases). If you make changes to the imta.cnf, mappings file, aliases, conversions, or option.dat files that do not affect the job_controller, then you should issue an imsimta cnbuild followed by an imsimta restart smtp. If you make changes to dispatcher.cnf you need to do an imsimta restart dispatcher. If you make changes to the configuration files that are included in the compiled configuration that affect the job controller, but not the SMTP server, in many cases you should issue the following commands: imsimta cnbuild and imsimta restart job_controller.

See MTA Commands for details on these commands.

MTA Configuration Files
File Description
Alias File (mandatory) Implements aliases not present in the directory. msg-svr-base/config/aliases
TCP/IP (SMTP) Channel Option Files SMTP Option Files) Sets channel-specific options. msg-svr-base/config/channel_option
Conversion File Used by the conversion channel to control message body part conversions.msg-svr-base/config/conversions
Dispatcher Configuration File (mandatory) Configuration file for the Dispatcher. msg-svr-base/config/dispatcher.cnf
Job Controller File (mandatory) Configuration file used by the Job Controller. msg-svr-base/config/job_controller.cnf
MTA Configuration File (mandatory) Used for address rewriting and routing as well as channel definition. msg-svr-base/config/imta.cnf
Mappings File (mandatory) Repository of mapping tables./msg-svr-base/config/mappings
Option File File of global MTA options. msg-svr-base/config/option.dat
Tailor File (mandatory) File to specify locations and some tuning parameters. msg-svr-base/config/imta_tailor
General Lookup Table (optional) General lookup facility is equivalent to the general database. Part of reloadable compiled configuration.File to specify locations and some tuning parameters. msg-svr-base/config/general.txt
Forward Lookup Table (optional) Lookup facility for To: addresses. Equivalent to forward database. Part of reloadable compiled configuration. msg-svr-base/config/forward.txt
Reverse Lookup Table (optional) Reverse lookup facility for From: addresses. Equivalent to reverse database. Part of reloadable compiled configuration msg-svr-base/config/reverse.txt

Alias File

The alias file, aliases, sets aliases not set in the directory. In particular, the address for root is a good example. Aliases set in this file will be ignored if the same aliases exist in the directory. For more information about aliases and the aliases file, see Aliases.

After making changes to the aliases file, you must restart the MTA for the changes to take effect.

TCP/IP (SMTP) Channel Option Files

TCP/IP channel option files control various characteristics of TCP/IP channels. Channel option files must be stored in the MTA configuration directory and named xoption, where _x is the name of the channel. For example, msg-svr-base/config/tcp_local_option. For more information refer to Configuring SMTP Channel Options. For complete information on all channel option keywords and syntax, see the Messaging Server Administration Reference.

Conversion File

The conversion file, conversions, specifies how the conversion channel performs conversions on messages flowing through the MTA. Any subset of MTA traffic can be selected for conversion and any set of programs or command procedures can be used to perform conversion processing. The MTA looks at the conversion file to choose an appropriate conversion for each body part.

For more information about the syntax of this file, see The Conversion Channel.

Dispatcher Configuration File

The Dispatcher configuration file, dispatcher.cnf, specifies Dispatcher configuration information. A default configuration file is created at installation time and can be used without any changes made. However, if you want to modify the default configuration file for security or performance reasons, you can do so by editing the dispatcher.cnf file. (For conceptual information, see The Dispatcher).

The Dispatcher configuration file format is similar to the format of other MTA configuration files. Lines specifying options have the following form:

option=value

The option is the name of an option and value is the string or integer to which the options is set. If the option accepts an integer value, a base may be specified using notation of the form b%v, where b is the base expressed in base 10 and v is the actual value expressed in base b. Such option specifications are grouped into sections corresponding to the service to which the following option settings apply, using lines of the following form:

[SERVICE=service-name]

The service-name is the name of a service. Initial option specifications that appear before any such section tag apply globally to all sections.

The following is a sample Dispatcher configuration file (dispatcher.cnf).

! The first set of options, listed without a [SERVICE=xxx]
! header, are the default options that will be applied to all
! services.
!
MIN_PROCS=0
MAX_PROCS=5
MIN_CONNS=5
MAX_CONNS=20
MAX_LIFE_TIME=86400
MAX_LIFE_CONNS=100
MAX_SHUTDOWN=2
!
! Define the services available to Dispatcher
!
[SERVICE=SMTP]
PORT=25
IMAGE=<msg-svr-base>/lib/tcp_smtp_server
LOGFILE=<msg-svr-base>/log/tcp_smtp_server.log

For more information about the parameters for this file, see the Messaging Server Administration Reference.

Mappings File

The mappings file defines how the MTA maps input strings to output strings.

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 this type 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 mappings file provides the MTA with facilities for supporting multiple mapping tables. Full wildcard facilities are provided, and multi-step 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 actually serve to eliminate the need for most of the entries in an equivalent database, and this may actually result in lower overhead overall.

You can test mapping tables with the imsimta test -mapping command. For more information about the syntax of the mappings file and the test -mapping command, see Mappings File and the Messaging Server Administration Reference.

After making changes to the mappings file, you must restart the MTA or issue the command imsimta reload.

Option File

The options file, option.dat, specifies global MTA options as opposed to channel-specific options.

You can use the options file to override the default values of various parameters that apply to the MTA as a whole. In particular, the option file is used to establish sizes of the various tables into which the configuration and alias files are read. You can also use the options file to limit the size of messages accepted by the MTA, specify the number of channels allowed in the MTA configuration, set the number of rewrite rules allowed, and so on.

In option.dat, lines starting with #, ! or ; are treated as comment lines, even if the preceding line has a trailing \ meaning that it is being continued. This means that long options that may contain these characters, in particular delivery options, care has to be taken.

For delivery options, where a natural layout would lead to continuation lines starting with a # or !, there is a safe and neat work around.

For more information about the syntax of the options file, see the Messaging Server Administration Reference.

Tailor File

The tailor file, imta_tailor, sets the location of various MTA components. For the MTA to function properly, the imta_tailor file must always reside in the msg-svr-base/config directory.

Although you can edit this file to reflect the changes in a particular installation, you must do so with caution. After making any changes to this file, you must restart the MTA. Make the changes while the MTA is shut down.

Note
Do not edit this file unless absolutely necessary.

For complete information on this file, see the Messaging Server Administration Reference.

Job Controller File

The Job Controller creates and manages channel jobs for delivering messages. These channel jobs run inside processing pools within the Job Controller. Think of a processing pool as a "place" where the channel jobs are run. The pool provides a computing area where a set of jobs can operate without vying for resources with jobs outside of the pool. For information on Job Controller concepts and channel keyword configuration, see to The Job Controller, Processing Pools for Channel Execution Jobs, and Service Job Limits.

The Job Controller file, job_controller.cnf, specifies the following channel processing information:

  • Defines various pools
  • Specifies for all channels, the master program name and the slave program name, if applicable

In the imta.cnf file, you can specify the name of a process pool (that was defined in the job_controller.cnf file) by using the pool keyword. For example, the following fragment from a sample job_controller.cnf file defines the pool MY_POOL:

The following fragment from a sample imta.cnf file specifies the pool MY_POOL in a channel block:

If you want to modify the parameters associated with the default pool configuration or add additional pools, you can do so by editing the job_controller.cnf file, then stopping and restarting the Job Controller.

The first pool in the Job Controller configuration file is used for any requests that do not specify the name of a pool. The MTA channels defined in the MTA configuration file (imta.cnf) can have their processing requests directed to a specific pool by using the pool channel keyword followed by the name of the pool. The pool name must match the name of a pool in the Job Controller configuration. If the Job Controller does not recognize the requested pool name, the request is ignored.

In the initial configuration, the following pools are defined: DEFAULT, LOCAL_POOL, IMS_POOL, SMTP_POOL

Examples of Use

Typically, you would add additional pool definitions to the Job Controller configuration if you wanted to differentiate processing of some channels from that of other channels. You might also choose to use pools with different characteristics. For example, you might need to control the number of simultaneous requests that some channels are allowed to process. You can do this by creating a new pool with the job limit, then use the pool channel keyword to direct those channels to the new, more appropriate pool.

In addition to the definition of pools, the Job Controller configuration file also contains a table of the MTA channels and the commands that the Job Controller must use to process requests for each channel. The two types of requests are termed "master" and "slave." Typically, a channel master program is invoked when there is a message stored in an MTA message queue for the channel. The master program dequeues the message.

A slave program is invoked to poll a channel and pick up any messages inbound on that channel. While nearly all MTA channels have a master program, many do not have or need a slave program. For example, a channel that handles SMTP over TCP/IP does not use a slave program because a network service, the SMTP server, receives incoming SMTP messages upon request by any SMTP server. The SMTP channel's master program is the MTA's SMTP client.

If the destination system associated with the channel cannot handle more than one message at a time, you need to create a new type of pool whose job limit is one:

On the other hand, if the destination system has enough parallelism, you can set the job limit to a higher value.

The following example shows a sample Job Controller configuration file. Job Controller Configuration File Options shows the available options.

Sample Job Controller Configuration File in UNIX

The key items in the preceding example (numbered and enclosed in parentheses) are:

  1. This global option defines the TCP port number on which the Job Controller listens for requests.
  2. Sets a default SLAVE_COMMAND for subsequent [CHANNEL] sections.
  3. Sets a default MAX_LIFE_AGE for subsequent [CHANNEL] sections.
  4. This [POOL] section defines a pool named DEFAULT.
  5. Set the JOB_LIMIT for this pool to 10.
  6. This [CHANNEL] section applies to a channel named l, the UNIX local channel. The only definition required in this section is the master_command, which the Job Controller issues to run this channel. Since no wildcard appears in the channel name, the channel must match exactly.
  7. This [CHANNEL] section applies to any channel whose name begins with tcp_*. Since this channel name includes a wildcard, it will match any channel whose name begins with tcp_.
Example of Adding Additional Pools
Note
The job limit that is set in the job_controller is per pool. So, for example, if you have your SMTP_POOL defined with a job_limit of 10, then only 10 tcp_smtp client processes can run in that pool at any given time.

There are situations where you might want to create additional tcp_* channels (say, for example, a tcp channel for particularly slow mail sites). It is a good idea to have these channels run in different pools. The reason for this is if you created ten different tcp_* channels and they were all running in SMTP_POOL, it is possible to only have one tcp_smtp client running per tcp_* channel at any given time (depending on whether or not there is mail destined for all the tcp_* channels and given that SMTP_POOL is defined with a job_limit of 10). Assuming there is heavy load on the system and that all queues have messages waiting to go out the various tcp_* channels, this would not be efficient. It is much more likely that one would want to define additional pools for the additional tcp_* channels so that there is no contention for slots.

For example, suppose you set up the following tcp_* channels:

To have ten tcp_smtp_client processes for each of the new channels you would add the following in the job_controller.cnf file:

For more information about pools, see Processing Pools for Channel Execution Jobs.

Job Controller Configuration File Options
Option Description
General Options Description
INTERFACE_ADDRESS=adapter Specifies the IP address interface to which the Job Controller should bind. The value specified (adapter) can be one of ANY, ALL, LOCALHOST, or an IP address. By default the Job Controller binds to all addresses (equivalent to specifying ALL or ANY). Specifying INTERFACE_ADDRESS=LOCALHOST means that the Job Controller only accepts connections from within the local machine. This does not affect normal operation, since no inter-machine operation is supported by the Job Controller. However, this may be inappropriate in an HA environment where an HA agent may be checking if the Job Controller is responding. If the machine on which the Messaging Server is running is in an HA environment, has an "internal network" adapter and an "external network" adapter, and you are not confident of your firewall's ability to block connections to high port numbers, consider specifying the IP address of the "internal network" adapter.
MAX_MESSAGES=integer The Job Controller keeps information about messages in an in-memory structure. In the event that a large backlog builds, it may need to limit the size of this structure. If the number of messages in the backlog exceeds the parameter specified here, information about subsequent messages is not kept in memory. Mail messages are not lost because they are always written to disk, but they are not considered for delivery until the number of messages known by the Job Controller drops to half this number. At this point, the Job Controller scans the queue directory mimicking an imsimta cache -sync command. The minimum value is 10. See The Job Controller for more information. The default is 100000.
SECRET=file_spec Shared secret used to protect requests sent to the Job Controller.
SYNCH_TIME=time_spec The Job Controller occasionally scans the queue files on disk to check for missing files. By default, this takes place every four hours, starting four hours after the Job Controller is started. The format of the time_spec is HH:MM/hh:mm or /hh:mm. The variable hh.mm is the interval between the events in hours (h) and minutes (m). The variable HH:MM is the first time in a day the even should take place. For example specifying, 15:45/7:15 starts the event at 15:45 and every seven hours and fifteen minutes from then.
TCP_PORT=integer Specifies the TCP port on which the Job Controller should listen for request packets. Do not change this unless the default conflicts with another TCP application on your system. If you do change this option, change the corresponding IMTA_JBC_SERVICE option in the MTA tailor file, msg-svr-base/config/imta_tailor, so that it matches. The TCP_PORT option applies globally and is ignored if it appears in a [CHANNEL] or [POOL] section.
Pool Option Description
JOB_LIMIT=integer Specifies the maximum number of processes that the pool can use simultaneously (in parallel). The JOB_LIMIT applies to each pool individually. The maximum total number of jobs is the sum of the JOB_LIMIT parameters for all pools. If set outside of a section, it is used as the default by any [POOL] section that does not specify JOB_LIMIT. This option is ignored inside of a [CHANNEL] section.
Channel Option Description
MASTER_COMMAND=file_spec Specifies the full path to the command to be executed by the UNIX system process created by the Job Controller to run the channel and dequeue messages outbound on that channel. If set outside of a section, it is used as the default by any [CHANNEL] section that doesn’t specify a MASTER_COMMAND. This option is ignored inside of a [POOL] section.
MAX_LIFE_AGE=integer Specifies the maximum life time for a channel master job in seconds. If this parameter is not specified for a channel, then the global default value is used. If no default value is specified, 14400 (240 minutes) is used.
MAX_LIFE_CONNS=integer In addition to the maximum life age parameter, the life expectancy of a channel master job is limited by the number of times it can ask the Job Controller if there are any messages. If this parameter is not specified for a channel, then the global default value is used. If no default value is specified, 300 is used.
SLAVE_COMMAND=file_spec Specifies the full path to the command to be executed by the UNIX system process created by the Job Controller in order to run the channel and poll for any messages inbound on the channel. Most MTA channels do not have a SLAVE_COMMAND. If that is the case, the reserved value NULL should be specified. If set outside of a section, it is used as the default by any [CHANNEL] section that does not specify a SLAVE_COMMAND. This option is ignored inside of a [POOL] section.

Aliases

The MTA provides a facility to support mailbox names associated with the local system that do not necessarily correspond to actual users: aliases. Aliases are useful for constructing mailing lists, forwarding mail, and providing synonyms for user names. For a discussion on how alias resolution is handled see The $V Metacharacter.

Old-style mailing lists defined in the aliases file or aliases database now accept a nonpositional [capture] parameter. If used, the [capture] parameter specifies a capture address with the same semantics as capture addresses specified by the LDAP_CAPTURE attribute applied to a user or group in LDAP.

A value "\" given as an [envelope_from] nonpositional alias parameter, as an error to positional alias parameter, or as a value of the mgrpErrorsTo LDAP attribute, is now interpreted as a request to revert to using the original envelope From: address for the incoming message while retaining mailing list semantics. This can be useful for setting up mailing lists that report all forms of list errors to the original sender.

The Alias Database

Use of the Alias Database is discouraged. Use the aliases file instead, especially since it can be dynamically reloaded using the imsimta reload command.

The MTA uses the information in the directory and creates the alias database. The alias database is consulted once each time the regular alias files is consulted. However, the alias database is checked before the regular alias file is used. In effect, the database acts as a sort of address rewriter that is invoked prior to using the alias file.

Note
The format of the database itself is private. Do not try to edit the database directly. Make all required changes in the directory.

The Alias File

The aliases file is used to set aliases not set in the directory. In particular, the postmaster alias is a good example. Aliases set in this file will be ignored, if the same aliases exist in the directory. Changes can be activated by issuing the imsimta reload command (or restarting the MTA). Any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored.

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

A physical line in this file is limited to 1024 characters. You can split a logical line into multiple physical lines using the backslash (\) continuation character.

The format of the file is as follows:

For example:

Including Other Files in the Alias File

Other files can be included in the primary aliases file. A line of the following form directs the MTA to read the file-spec file:

The file specification must be a complete file path specification and the file must have the same protections as the primary aliases file. For example, it must be world readable.

The contents of the included file are inserted into the aliases file at its point of reference. The same effect can be achieved by replacing the reference to the included file with the file's actual contents. The format of include files is identical to that of the primary aliases file itself. Indeed, include files may themselves include other files. Up to three levels of include file nesting are allowed.

Command-Line Utilities

Messaging Server provides several command-line utilities that enable you to perform various maintenance, testing, and management tasks for the MTA. For example, you use the imsimta cnbuild command to compile the MTA configuration, alias, mapping, security, system wide filter, and option files. For complete information on the MTA command-line utilities, see the Messaging Server Administration Reference.

SMTP Security and Access Control

For information about SMTP security and access control, see Mail Filtering and Access Control.

Log Files

All MTA specific log files are kept in the log directory, (msg-svr-base/log). This directory contains log files that describe message traffic through the MTA and log files that describe information about specific master or slave programs.

For more information about MTA log files, see Managing Logging.

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 uid@mailhost.siroe.com might be a valid address within the siroe.com domain, it might not be an appropriate address to expose to the outside world. You might prefer a public address like firstname.lastname@siroe.com.

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 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 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.

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

The following table shows REVERSE mapping table flags.

REVERSE mapping table flags
Flags Description
$Y Use output as new address.
$N Address remains unchanged.
$D Run output through the reversal database.
$A Add pattern as reverse database entry.
$F Add pattern as forward database entry.
Flag comparison Description
$:B Match only header (body) addresses.
$:E Match only envelope addresses.
$:F Match only forward pointing addresses.
$:R Match only backwards pointing addresses.
$:I Match only message-ids.

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_DATA options 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 database
    reverse.txt - reverse database
    forward.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.
    For example, USE_REVERSE_DATABASE, USE_FORWARD_DATABASE, or whatever
  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 are 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 want 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 is not), you're back to replacing the entire database when updating, which in this case, makes text databases preferable.

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 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.

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 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 siroe.com are of the form user@mailhost.siroe.com. However, the user name space is such that user@host1.siroe.com and user@host2.siroe.com specify the same person for all hosts at siroe.com. The following REVERSE mapping may be used in conjunction with the address-reversal text database:

In this example, addresses of the form name@anyhost.siroe.com would be changed to name@siroe.com. 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:

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 binky@macho.siroe.com to Rebecca.Woods@siroe.com

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

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 the following table for a list of additional flags.

FORWARD Output Mapping Table Flags Description
Flag Description
$D Run output through the rewriting process again
$G Run output through the forward lookup table, if forward lookup table use has been enabled
$H Disable further forward lookup table or FORWARD mapping lookups
$I Hold the message as a .HELD file
$N Address remains unchanged
$Y 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. (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. Previously they were only available to the various *_ACCESS mappings.

FORWARD Input Mapping Table Flags Description
Flag Description
$A SASL used to authenticate connection.
$D NOTIFY=DELAYS active for this recipient.
$E Incoming connection used ESMTP/EHLO.
$F NOTIFY=FAILURES active for this recipient.
$L Incoming connection used LMTP/LHLO.
$S NOTIFY=SUCCESSES active for this recipient.
$T SSL/TLS used to secure connection.

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

"lastname, firstname"@am.sigurd.example.com

or

"lastname,firstname"@am.sigurd.example.com

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

firstname.lastname@am.sigurd.example.com

Example of a complex FORWARD and REVERSE mapping:

So the goals of the sample mapping tables in this 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. 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 by using 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 the msg-svr-base/configure/forward.txt file, 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:

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

will map the To: address helen@red.com to "helen of troy"@siroe.com if and only if the message is coming from bob@blue.com and the enqueuing channel is tcp_limited.

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

Controlling Delivery Status Notification Messages

Delivery status notifications or status notifications are email status messages sent by the MTA to the sender and, optionally, the postmaster. Messaging Server enables you to customize notification messages by content and language. You can also create different messages for each type of delivery status (for example, FAILED, BOUNCED, TIMEDOUT, and so on.). In addition, you can create status notifications for messages originating from specific channels.

By default, status notifications are stored in the msg-svr-base/config/locale/C directory (specified by the IMTA_LANG setting in the msg-svr-base/config/imta_tailor file). The filenames are as follows:

return_bounced.txt, return_delivered.txt return_header.opt, return_timedout.txt, return_deferred.txt, return_failed.txt, return_prefix.txt, return_delayed.txt, return_forwarded.txt, return_suffix.txt

Message text for *.txt files should be limited to 78 characters per line. You should not change these files directly since they will be overwritten when the current version of Messaging Server is upgraded. If you want to modify these files and use them as your only set of notification message template files (return_*.txt), copy the files to a new directory and edit them there. Then, set the IMTA_LANG option in the imta_tailor file to point to the new directory containing those templates. If you want to have multiple sets of notification files (for example, a set for each language) then you will need to set up a NOTIFICATION_LANGUAGE mapping table.

This section consists of the following subsections:

To Construct and Modify Status Notifications

A single notification message is constructed from a set of three files: return_prefix.txt + return_ActionStatus.txt + return_suffix.txt

To customize or localize notifications, you would create a complete set of return_*.txt files for each locale and/or customization and store it in a separate directory. For example, you could have French notification files stored in one directory, Spanish for another, and notifications for a special unsolicited bulk email channel stored in a third.

Note
Sample files for French, German, and Spanish are included in this release. These files can be modified to suit your specific needs.

For double-byte languages such as Japanese, be sure to construct your text in Japanese, then view the text as if it was ASCII to check for % characters. If there are accidental % characters, then replace them with %%.

The following information describes the format and structure of status notification message sets.

  1. return_prefix.txt provides appropriate header text as well as introductory material for the body. The default for US-english locale is as follows:

    Non-US-ASCII status notification messages should change the charset parameter and Content-Language header value appropriately (for example, for French localized files the values would be ISO-8859-1 and fr). %H is a header substitution sequence defined in Notification Message Substitution Sequences.

  1. return_ActionStatus>.txt contains status-specific text. ActionStatus refers to a message's MTA status type. For example, the default text for return_failed.txt is as follows:
    Your message cannot be delivered to the following recipients:%R
    The default text for return_bounced.txt is:
    Your message is being returned. It was forced to return bythe postmaster.
    The recipient list for this message was:%R
  2. return_suffix.txt contains concluding text. By default this file is blank.
Notification Message Substitution Sequences
Substitutions Definition
%H Expands into the message's headers.
%C Expands into the number of units 1 the message has been queued.
%L Expands into the number of units 1 the message has left in the queue before it is returned.
%F Expands into the number of units 1 a message is allowed to stay in the queue.
%S [%s] Expands to the letter S or s if the previously expanded numeric value was not equal to one. Example: "%C day%s" can expand to "1 day" or "2 days" depending on how many days the message has been queued.
%U [%u] Expands into the time units Hour [hour] or Day [day], in use. Example: "%C %U%s" can expand to "2 days" or "1 hour" depending on how many days or hours the message has been queued, and the value of the MTA option RETURN_UNITS. If you have set RETURN_UNITS=1 (hours) and your site is using localized status notification messages, you will need to edit return_delayed.txt and return_timedout.txt and replace the word "days" with the word hours for all languages other than English. French, replace jour(s) with heure(s). German, replace Tag(e) with Stunde(n). Spanish, replace día(s) with hora(s).
%R Expands into the list of the message's recipients.
%% % (The text is scanned byte by byte for substitutions sequences regardless of character set. Check for unintended % signs if you are using a double byte character set.)
1 Units is defined by the RETURN_UNITS option in the MTA Options file and can be hours or days (default).

To Customize and Localize Delivery Status Notification Messages

Delivery Status Notification Messages can be localized such that messages will be returned to different users in different languages. For example, French notifications could be returned to users who have expressed a preference for French.

Localizing or customizing status notification messages consists of two steps:

  1. Create a set of localized/customized return_*.txt message files and store each set in a separate directory. This is described in To Construct and Modify Status Notifications.
  2. Set up a NOTIFICATION_LANGUAGE mapping table.

The NOTIFICATION_LANGUAGE mapping table (located in msg-svr-base/config/mappings) specifies the set of localized or customized notification message files to use depending upon attributes (for example: language, country, domain, or address) of the originating message (the message causing the notification to be sent).

The original sender's message is parsed to determine status notification type, source channel, preferred language, return address and first recipient. Depending on how the table is constructed, a set of notification files is selected depending on one or more of these attributes.

The format of the NOTIFICATION_LANGUAGE mapping table is as follows. The sample entry line has been wrapped for typographic reasons. The actual entry should appear on one physical line.

  • dsn-type-list is a comma-separated list of delivery status notification types. If multiple types are specified, they must be separated by commas and without spaces (a space will terminate the pattern of the mapping table entry). The types are as follows:
    • failed - Generic permanent failure messages (for example, no such user). Uses the return_failed.txt file.
    • bounced - Notification message used in conjunction with manual "bounces." Done by the postmaster. Uses the return_bounced.txt file.
    • timedout - The MTA has been unable to deliver the message within the time allowed for delivery. The message is now being returned. Uses the return_timedout.txt file.
    • delayed - The MTA has been unable to deliver the message, but will continue to try to deliver it. Uses the return_delayed.txt file.
    • deferred - Non-delivery notification similar to "delayed" but without an indication of how much longer the MTA will continue to try to deliver. Uses the return_deferred.txt file.
    • forwarded - A delivery receipt was requested for this message, however, this message has now been forwarded to a system that does not support such receipts. Uses the return_forwarded.txt file.
  • source-channel is the channel generating the notification message, that is, the channel at which the message is currently queued. For example, ims-ms for the message store's delivery queue, tcp_local for outbound SMTP queues, etc.
  • preferred-language is the language expressed in the message being processed (the message for which the notification is being generated). The sources for this information are first the accept_language field. If that does not exist, the Preferred-language: header field and X-Accept-Language: header field are used. For a list of standard language code values, refer to the file msg-svr-base/config/languages.txt.
    This field, if not empty, will be whatever the originator of the message specified for the Preferred-language: or X-Accept-language: header line. As such, you may find nonsense characters in this field.
  • return-address is the envelope From: address of the originating message. This is the envelope address to which the notification message will be sent and hence a possible indicator of what language to use.
  • first-recipient is the envelope To: address (the first one, if the message is failing to more than one recipient) to which the original message was addressed. For example, in the notification, dan@siroe.com is the envelope To: address being reported on: "your message to dan@siroe.com could not be delivered"
  • directory-spec is the directory containing the return_*.txt files to use if the mapping table probe matches. Note that a $I must precede the directory specification.
    For instance, a site that stores French notification files (return_*.txt) in a directory /lc_messages/table/notify_french/ and Spanish notification files in return_*.txt files in a directory /lc_messages/table/notify_spanish/ might use a table similar to the following one. Each entry must start with one or more spaces, and that there can be no blank lines between entries.
    Note
    A default mappings.locale file is provided with the installation and will be included in the mappings file to enable notification language mapping. To disable notification language mapping, comment out the include line as follows:

    (Read the comments in the file and modify to suit your needs.)

Internationalization of Generated Notices

Two option files can be used for both the delivery status and message disposition notification. These are intended to make internationalization of generated notices more flexible. They are as follows:

The following table describes the available options for these files.

Delivery Status and Message Disposition Notification Options
Option Description
DAY (DSN) The text to insert for a %U or %u substitution when RETURN_UNITS=0 (the default) is set. Note that no distinction is made between %U and %u (unlike the default case where English “Day” or “day”, respectively, would be substituted).
DIAGNOSTIC_CODE (DSN) Override for the “Diagnostic code:“ text used in the construction of the per-recipient section of the first part of a DSN. This field should be specified in the same charset that’s used for the first part of the DSN.
HOUR (DSN) The text to insert for a %U or %u substitution when RETURN_UNITS=1 is set. Note that no distinction is made between %U and %u (unlike the default case where English “Hour” or “hour”, respectively, would be substituted).
n.n.n (DSN) When constructing the per-recipient part of a DSN a check will be made to see if there’s an option whose name matches the numeric per-recipient status. If there is the corresponding text will be inserted into the DSN. Additionally, if the REASON option specified above produces a zero length result the REASON field will not be inserted.
ORIGINAL_ADDRESS (DSN) Override for the “Original address:” text used in the construction of the per-recipient section of the first part of a DSN. This field should be specified in the same charset that’s used for the first part of the DSN.
REASON (DSN) Override for the “Reason:” text used in the construction of the per-recipient section of the first part of a DSN. This field should be specified in the same charset that’s used for the first part of the DSN.
RECIPIENT_ADDRESS (DSN) Override for the “Recipient address:” text used in the construction of the per-recipient section of the first part of a DSN. This field should be specified in the same charset that’s used for the first part of the DSN.
RETURN_PERSONAL (DSN and MDN) Override personal name field to be used in conjunction with the From: field. This field should be RFC 2047 encoded. The value set by the RETURN_PERSONAL MTA option is used if this option is not specified.
SUBJECT (DSN and MDN) Override Subject: field. This value will only be used if the notification didn’t provide a subject field of its own. This field should be RFC 2047 encoded. An appropriate subject will be constructed if this option is not used and the notification did not provide one.
TEXT_CHARSET (MDN) Charset text for the first part and subject of the MDN should be converted to. The default is not to perform any conversion.

Additional Status Notification Message Features

The essential procedures for setting up status notification messages is describe in the previous sections. The following sections describe additional functionality:

To Block Content Return on Large Messages

Typically, when a message is bounced or blocked, the content of the message is returned to sender and to the local domain postmaster in the notification message. This can be a strain on resources if a number of very large messages are returned in their entirety. To block the return of content for messages over a certain size, set the CONTENT_RETURN_BLOCK_LIMIT option in the MTA options file.

The MTA fetches the block limit associated with the envelope return address and will set RET=HDRS if no return policy is specified and the message size exceeds the block limit. This prevents nondelivery reports for large messages from being undeliverable themselves. No new options or settings are associated with this change.

To Remove non-US-ASCII Characters from Included Headers in the Status Notification Messages

The raw format for Internet message headers does not permit non-US-ASCII characters. If non-US-ASCII characters are used in a message header they are encoded using "MIME header encoding" described in RFC 2047. Thus, a Chinese "Subject" line in an email message looks like the following:

Subject: =?big5?Q?=A4j=AB=AC=A8=B1=AD=B1=B0=D3=F5=A5X=AF=B2?=

and it is the responsibility of email clients to remove the encoding when displaying headers.

Because the %H template copies headers into the body of the notification message, the encoded header text will normally appear. However, Messaging Server will remove the encoding if the character set in the subject (in this case "big5") matches the character set in the Content-Type header character set parameter in return_prefix.txt. If it does not match, the Messaging Server will leave the encoding intact.

To Set Notification Message Delivery Intervals

Keywords: notices, nonurgentnotices, normalnotices, urgentnotices

Undeliverable messages are held in a given channel queue for specified amount of time before being returned to sender. In addition, a series of status/warning messages can be returned to the sender while Messaging Server attempts delivery. The amount of time and intervals between messages can be specified with the notices, nonurgentnotices, normalnotices, or urgentnotices keywords. Examples:

notices 1 2 3

Transient failure status notification messages are sent after 1 and 2 days for all messages. If the message is still not delivered after 3 days, it is returned to its originator.

urgentnotices 2,4,6,8

Transient failure notifications are sent after 2, 4, and 6 days for messages of urgent priority. If the message is still not delivered after 8 days, it is returned to its originator.

The RETURN_UNITS option in the MTA Options file enables you to specify the units in either hours (1) or days (0). The default is days (0). If you set RETURN_UNITS=1, then you need to schedule the return job to run hourly as well to get hourly notices. When the return job runs every hour it will also roll over the mail.log* files every hour. To prevent the hourly rollover of the mail.log file, set the IMTA_RETURN_SPLIT_PERIOD tailor file option in the imta.tailor file to 24. Return job scheduling is controlled by the local.schedule.return_job configutil parameter. However, by default this command is run on a regular basis (see Pre-defined Automatic Tasks).

If no notices keyword is specified, the default is to use the notices setting for the local, l, channel. If no setting has been made for the local channel, then the default is to use notices 3, 6, 9, 12.

To Include Altered Addresses in Status Notification Messages

Keywords: includefinal, suppressfinal, useintermediate

When the MTA generates a notification message (bounce message, delivery receipt message, and so on), there may be both an "original" form of a recipient address and an altered "final" form of that recipient address available to the MTA. The MTA always includes the original form (assuming it is present) in the notification message, because that is the form that the recipient of the notification message (the sender of the original message, which the notification message concerns) is most likely to recognize.

The includefinal and suppressfinal channel keywords control whether the MTA also includes the final form of the address. Suppressing the inclusion of the final form of the address may be of interest to sites that are "hiding" their internal mailbox names from external view. Such sites may prefer that only the original, "external" form of address be included in status notification messages. includefinal is the default and includes the final form of the recipient address. suppressfinal causes the MTA to suppress the final address form, if an original address form is present, from status notification messages.

The useintermediate keyword uses an intermediate form of the address produced after list expansion, but prior to user mailbox name generation. If this information isn’t available, the final form is used.

To Send, Block and Specify Status Notification Messages to the Postmaster

By default, a copy of failure and warning status notification messages are sent to the postmaster unless error returns and warnings are completely suppressed with a blank Errors-to: header line or a blank envelope From: address. Further granularity of notification message delivery to the postmaster can be controlled by a number of channel keywords described in the following sections and in Keywords for Sending Notification Messages to the Postmaster and Sender.

Returned Failed Messages

Keywords: sendpost, nosendpost, copysendpost, errsendpost

A channel program might be unable to deliver a message because of long-term service failures or invalid addresses. When this occurs, the MTA channel program returns the message to the sender with an accompanying explanation of why the message was not delivered. Optionally, a copy of all failed messages is sent to the local postmaster. This is useful for monitoring message failures, but it can result in an excessive amount of traffic with which the postmaster must deal. (See Keywords for Sending Notification Messages to the Postmaster and Sender.)

Warning Messages

Keywords: warnpost, nowarnpost, copywarnpost, errwarnpost

In addition to returning messages, the MTA can send detailed warnings for undelivered messages. This is generally due to time-outs based on the setting of the notices channel keyword, although in some cases channel programs may produce warning messages after failed delivery attempts. The warning messages contain a description of what’s wrong and how long delivery attempts continue. In most cases they also contain the headers and the first few lines of the message in question.

Optionally, a copy of all warning messages can be sent to the local postmaster. This can be somewhat useful for monitoring the state of the various queues, although it does result in lots of traffic for the postmaster to deal with. The keywords warnpost, copywarnpost, errwarnpost, and nowarnpost are used to control the sending of warning messages to the postmaster. (See Keywords for Sending Notification Messages to the Postmaster and Sender.)

Blank Envelope Return Addresses

Keywords: returnenvelope

The returnenvelope keyword takes a single integer value, which is interpreted as a set of bit flags. Bit 0 (value = 1) controls whether or not return notifications generated by the MTA are written with a blank envelope address or with the address of the local postmaster. Setting the bit forces the use of the local postmaster address; clearing the bit forces the use of a blank address.

Note
The use of a blank address is mandated by RFC 1123. However, some systems do not properly handle blank envelope From: addresses and may require the use of this option.

Bit 1 (value = 2) controls whether or not the MTA replaces all blank envelope addresses with the address of the local postmaster. This is used to accommodate noncompliant systems that do not conform to RFC 821, RFC 822, or RFC 1123.

Bit 2 (value = 4) prohibits syntactically invalid return addresses.

Bit 3 (value = 8) same as mailfromdnsverify keyword.

Postmaster Returned Message Content

Keywords: postheadonly, postheadbody

When a channel program or the periodic message return job returns messages to both the postmaster and the original sender, the postmaster copy can either be the entire message or just the headers. Restricting the postmaster copy to just the headers adds an additional level of privacy to user mail. However, this by itself does not guarantee message security; postmasters and system managers are typically in a position where the contents of messages can be read using root system privileges, if they so choose. (See Keywords for Sending Notification Messages to the Postmaster and Sender.)

Setting Per Channel Postmaster Addresses

Keywords: aliaspostmaster, returnaddress, noreturnaddress, returnpersonal, noreturnpersonal

By default, the Postmaster's return address that is used when the MTA constructs bounce or status notification messages is postmaster@local-host, where local-host is the official local host name (the name on the local channel), and the Postmaster personal name is "MTA e-Mail Interconnect." Care should be taken in the selection of the Postmaster address. An illegal selection can cause rapid message looping and a great number of error messages.

The RETURN_ADDRESS and RETURN_PERSONAL options can be used to set an MTA system default for the Postmaster address and personal name. Or, if per channel controls are desired, the returnaddress and returnpersonal channel keywords may be used. returnaddress and returnpersonal each take a required argument specifying the Postmaster address and Postmaster personal name, respectively. noreturnaddress and noreturnpersonal are the defaults and signify that the default values should be used. The defaults are established via the RETURN_ADDRESS and RETURN_PERSONAL options or the normal default values if such options are not set.

If the aliaspostmaster keyword is placed on a channel, then any messages addressed to the user name postmaster (lowercase, uppercase, or mixed case) at the official channel name is redirected to postmaster@local-host, where local-host is the official local host name (the name on the local channel). Note that Internet standards require that any domain in the DNS that accepts mail have a valid postmaster account that receives mail. So this keyword can be useful when it is desired to centralize postmaster responsibilities, rather than setting separate postmaster accounts for separate domains. That is, whereas returnaddress controls what return postmaster address is used when the MTA generates a notification message from the postmaster, aliaspostmaster affects what the MTA does with messages addressed to the postmaster.

Keywords for Sending Notification Messages to the Postmaster and Sender
Keyword Description
Returned Message Content Specifies Addresses on Notifications
notices Specifies the time that may elapse before notices are sent and messages returned.
nonurgentnotices Specifies the time that may elapse before notices are sent and messages returned for messages of non-urgent priority.
normalnotices Specifies the time that may elapse before notices are sent and messages returned for messages of normal priority.
urgentnotices Specify the time which may elapse before notices are sent and messages returned for messages of urgent priority.
Returned Messages How to handle failure notices for returned messages.
sendpost Enables sending a copy of all failed messages to the postmaster.
copysendpost Sends a copy of the failure notice to the postmaster unless the originator address on the failing message is blank, in which case, the postmaster gets copies of all failed messages except those messages that are actually themselves bounces or notifications.
errsendpost Sends a copy of the failure notice to the postmaster only when the notice cannot be returned to the originator. If nosendpost is specified, failed messages are never sent to the postmaster.
nosendpost Disables sending a copy of all failed messages to the postmaster.
Warning Messages How to handle warning messages.
warnpost Enables sending a copy of warning messages to the postmaster. The default is to send a copy of warnings to the postmaster unless warnings are completely suppressed with a blank Warnings-to: header or a blank envelope From: address.
copywarnpost Sends a copy of the warning message to the postmaster unless the originator address on the undelivered message is blank.
errwarnpost Sends a copy of the warning message to the postmaster when the notice cannot be returned to the originator.
nowarnpost Disables sending a copy of warning messages to the postmaster.
Returned Message Content Specifies whether to send entire message or just headers to the postmaster.
postheadonly Returns only headers to the postmaster. Restricting the postmaster copy to just the headers adds an additional level of privacy to user mail. However, this does not guarantee message security as postmasters and system managers are able to read the contents of messages using root system privileges, if they choose.
postheadbody Returns both the headers and the contents of the message.
Returned Message Content Specifies Addresses on Notifications
includefinal Include final form of address in delivery notifications (recipient address).
returnenvelope Control use of blank envelope return addresses. The returnenvelope keyword takes a single integer value, which is interpreted as a set of bit flags.Bit 0 (value = 1) controls whether or not return notifications generated by the MTA are written with a blank envelope address or with the address of the local postmaster. Setting the bit forces the use of the local postmaster address; clearing the bit forces the use of a blank address.Bit 1 (value = 2) controls whether or not the MTA replaces all blank envelope addresses with the address of the local postmaster. This is used to accommodate noncompliant systems that do not conform to RFC 821, RFC 822, or RFC 1123.Bit 2 (value = 4) prohibits syntactically invalid return addresses.Bit 3 (value = 8) same as mailfromdnsverify keyword.
suppressfinal Suppress the final address form from notification messages, if an original address form is present, from notification messages.
useintermediate Uses an intermediate form of the address produced after list expansion, but prior to user mailbox name generation. If this information isn’t available, the final form is used.
Returned Message Content Specifies Addresses on Notifications
aliaspostmaster Messages addressed to the user name postmaster at the official channel name is redirected to postmaster@local-host, where local-host is the local host name (the name on the local channel).
returnaddress Specifies the return address for the local postmaster.
noreturnaddress Use RETURN_ADDRESS option value as postmaster address name.
returnpersonal Set the personal name for the local postmaster.
noreturnpersonal Use RETURN_PERSONAL option value as postmaster personal name.

Controlling Message Disposition Notifications

Message Disposition Notifications (MDN) are email reports sent by the MTA to a sender and/or postmaster reporting on a message's delivery disposition. For example, if a message is rejected by a Sieve filter, an MDN will be sent to the sender. MDNs are also known as read receipts, acknowledgements, receipt notifications, or delivery receipts. The Sieve scripting language is typically used for messaging filtering and vacation messages.

To Customize and Localize Message Disposition Notification Messages

The instructions for modifying and localizing MDNs parallel those described in customizing and localizing delivery status notification messages with some minor differences as described here. (See To Customize and Localize Delivery Status Notification Messages and Internationalization of Generated Notices.

The mapping (called the DISPOSITION_LANGUAGE mapping) parallels the notification_language mapping table (see To Customize and Localize Delivery Status Notification Messages) used to internationalize status notifications.

However, probes for MDNs to this mapping take the following form:

type|modifiers|source-channel|header-language|return|recipient

Where:

type is disposition type, which can be one of the following: displayed, dispatched, processed, deleted, denied, or failed.

modifiers is a comma-separate list of disposition modifiers. The current list is: error, warning, superseded, and expired.

source-channel is the source channel producing the MDN.

header-language is the language specified in one of the following: accept-language, preferred-language, or x-accept-language. (MTA uses the first of these options that is present.)

return is the address to which the notification is being returned.

recipient is the address that the disposition is about.

The result of the disposition mapping consists of two or three pieces of information separated by vertical bars (|). The first piece of information is the directory where the template files for the disposition notification can be found. The second piece of information is the character set into which the standalone disposition text should be forced. (This information is required because some dispositions. notably the dispositions produced by autoreply echo or the use of the :mime parameter to the vacation Sieve action, do not employ template files and consequently cannot inherit the character set from those files.) Finally, the third piece of information is an override subject line for the notification. This information is only used if the $T flag is also set by the mapping.

The following additional template files are used to construct MDNs:

disposition_deleted.txt disposition_failed.txtdisposition_denied.txt disposition_prefix.txtdisposition_dispatched.txt disposition_processed.txtdisposition_displayed.txt disposition_suffix.txtdisposition_option.opt

The use of these template files parallels that of the various return_*.txt files for status notification messages. Message text for *.txt files should be limited to 78 characters per line.

Optimizing MTA Performance

This section describes miscellaneous optimizations for the MTA. It consists of the following section:

Optimizing Authorization Checks to the LDAP Directory for Messages Addressed to Mailing Lists

You can use metacharacter character substitutions to reduce authorization checks to the LDAP directory for Messages addressed to a mailing list.

Metacharacter substitutions can now be specified in mgrpModerator, mgrpAllowedBroadcaster and mgrpDisallowedBroadcaster attributes. In particular, the various address-related metacharacter sequences ($A for the entire address, $U for the mailbox part, $D for the domain part) refer to the current envelope From: address and can in some cases be used to limit the results returned by the URL to entries that are likely (or guaranteed) to match. This may make authorization checks much more efficient.

The new MTA option PROCESS_SUBSTITUTIONS controls whether or not substitutions are performed in various LDAP attributes that specify a URL. This is a bit-encoded value, with the bits defined as shown in the following table:

Bit Value Description
0 1 Enables substitutions in mgrpDisallowedBroadcaster if set
1 2 Enables substitutions in mgrpAllowedBroadcaster if set
2 4 Enables substitutions in mgrpModerator if set
3 8 Enables substitutions in mgrpDeliverTo if set
4 16 Enables substitutions in memberURL

The PROCESS_SUBSTITUTIONS MTA option defaults to 0, meaning that all of these substitutions are disabled by default.

An example would be a dynamic list defined through an LDAP lookup where anyone on the list is allowed to post. In such cases you typically define the list with attributes like:

The effect of such a definition, however, is to expand the list twice, once for the authorization check and once to build the actual recipient list,. This is a very server intensive operation. If, on the other hand, you add a restriction so only entries containing the current envelope From: address are returned in the authorization check, things may be much more efficient. First change the PROCESS_SUBSTITUTION setting to 2, and then you can set the following entries:

In this example, only the sender's entry is checked for broadcast authorization as opposed to all the user entries in Sesta US. This reduces the work the directory server has to do to a single (hopefully indexed) match and a single return value. The alternative is to return the entire list and have the MTA perform the match.

Note that the information available for substitution varies depending on whether the attribute is used for authorization checks or for actual list expansion. For authorization attributes, the whole address ($A), domain ($D), host ($H), and local-part ($L) are all derived from the authenticated sender address. In the case of list expansion attributes all of these substitution values are derived from the envelope recipient address that specified the list. In both cases, however, the subaddress substitution ($S) is derived from the current envelope recipient address.

The ability to access subaddress information in list expansion URLs makes it possible to define metagroups, that is, a single group entry that creates an entire collection of different groups. For example, a group with a mgrpDeliverTo value of:

mgrpDeliverTo: ldap:///o=usergroup?mail?sub?(department=$S)

and the corresponding PROCESS_SUBSTITUTIONS value being 8. It is possible to send mail to every member of a given department with an address of the form group+department@domain.com. Note that a mechanism like a forward mapping could be used to alter the syntax if subaddresses are seen as too difficult.

Labels:
messagingserver messagingserver Delete
administering administering Delete
mappings mappings Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. May 28, 2010

    The returnenvelope section is missing one additional value that I am aware of. (Are there more? I thought I remember reading about bit 5 in an Info-iMS message, but can't find it.)

    • Bit 4 (value = 16) If the envelope from address is in a domain that the system is authoritative for, it must be valid. (That is my wording...get something better from the developers.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.