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 using the imsimta refresh command (see the Sun Java System Messaging Server Administration Reference). This command 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 will reload 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.

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 default imta.cnf.

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

! test.cnf - An example configuration file. (1)!
! This is only an example of a configuration file. It serves
! no useful purpose and should not be used in a real system.
!
! Part I: Rewrite rules
a $U@a-daemon (2)b $U@b-daemon
c $U%c@b-daemon
d $U%d@a-daemon(3)! Part II: Channel definitions
l (4)local-host

a_channel defragment charset7 usascii (5)a-daemon

b_channel noreverse notices 1 2 3
b-daemon

</opt/SUNWmsgsr/msg-tango/table/internet.rules (6)

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

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.

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.

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.

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

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.

The contents of other files may 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.

Table 10-1 shows how some example addresses would be routed by the preceding 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 tables, called mapping tables, are usually presented as two columns. The first (left-hand) column provides possible input strings against which to match (pattern), and the second (right-hand) column gives the resulting output string for which the input string is mapped (template).

Most of the MTA databases—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. This is the file specified with the IMTA_MAPPING_FILE option in the MTA tailor file; by default, this is msg_svr_base/config/mappings. The contents of the mappings file is incorporated into the compiled configuration as part of the reloadable section (seeCompiling the MTA Configuration). The mappings file should be world readable. Failure to allow world-read access leads to erratic behavior. Whenever changes are made to the mappings file, the MTA configuration must be recompiled. See Compiling the MTA Configuration

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.

An application using the mapping table TABLE2_NAME would map the string pattern2-2 into whatever is specified by template2-2. Each pattern or template can contain up to 252 characters. There is no limit to the number of entries that can appear in a mapping (although excessive numbers of entries may consume huge amounts of CPU and can consume excessive amounts of memory). Long lines (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:

<file-spec

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—they are not loaded on demand, so there is no performance or memory savings involved in using include files.

Mapping Operations

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

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

Mapping Entry Patterns

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

Table 10-3 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.

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.

Note that the imsimta test -match utility may be used 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 pattern. For instance, when the 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:

$(123.45.67.0/24)

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:

$<123.45.67.0/8>

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

$<123.45.67.4/2>

IPv6 matching matches an IPv6 address or subnet.

Mapping Entry Templates

If the comparison of the pattern in a given entry fails, no action is taken; the scan proceeds to the next entry. If the comparison succeeds, the right 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 Table 10-4 for a list of the special substitution and standard processing metacharacters. Any other metacharacters are reserved for mapping-specific applications.

Note that any of the metacharacters $C, $E, $L, or $R, when present in the template of a matching pattern, 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.

Table 10-4 Mapping Template Substitutions and Metacharacters

Substitution sequence

Substitutes

$n

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

$#...#

Sequence number substitution.

$]...[

LDAP search URL lookup; substitute in result.

$|...|

Applies specified mapping table to supplied string.

${...}

General database substitution.

$}domain,attribute{

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

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

_base_dn_ - The base DN for user entries in the domain

_domain_dn_ - The DN of the domain entry itself

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

_canonical_name_ - The canonical name associated with the domain

$[...]

Invokes site-supplied routine; substitute in result.

Metacharacter

Description

$C

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

$E

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

$L

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

$R

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

$nA

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

$nX

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

Wildcard Field Substitutions ($n)

A dollar sign followed by a digit n is replaced with the material that matched the nth wildcard in the pattern. The wildcards are numbered starting with 0. For example, the following entry would match the input string PSI%A::B and produce the resultant output string b@a.psi.siroe.com:

PSI$%*::* $1@$0.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 influence the mapping process, controlling whether and when the mapping process terminates. The metacharacter:

$C causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process.

$L causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process, and, if no matching entry is found, making one more pass through the table starting with the first table entry; a subsequent matching entry with a $C, $E, or $R metacharacter overrides this condition.

$R causes the mapping process to continue from the first entry of the table, using the output string of the current entry as the new input string for the mapping process.

$E causes the mapping process to terminate; the output string of this entry is the final output. $E is the default.

Mapping table templates are scanned left to right. To set a $C, $L, or $R flag for entries that may “succeed” or “fail” (for example, general database substitutions or random-value controlled entries), put the $C, $L, or $R metacharacter to the left of the part of the entry that may succeed or fail; otherwise, if the remainder of the entry fails, the flag is not seen.

Check for Special Flags

Some mapping probes have special flags set. These are flags that can be set, and then their presence/absence tested-for using the general mapping table facility of $:, $; 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 for any special flags that may apply for that table. (See $A, $T, $S, $F, and $D in Table 17-2.)

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. (Note that, depending upon the mapping, the effect of the entry failing is not necessarily the same as the entry not matching in the first place.) 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 you'd like to allow through only 25 percent of its connection attempts and reject the other 75 percent of its connection attempts. The following PORT_ACCESS mapping table uses $?25? to cause the entry with the $Y (accept the connection) to succeed only 25 percent of the time; the other 75 percent of the time, when this entry fails, the initial $C on that entry causes 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:

$#seq-file-spec|radix|width|m#

$#seq-file-spec|radix|width#

$#seq-file-spec|radix#

$#seq-file-spec#

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 0's on the left to obtain the correct number of digits. Note that 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 noted above, the MTA sequence file referred to in a mapping must already exist. To create an MTA sequence file, use the following UNXI command:

touch seq-file-spec

or

cat >seq-file-spec

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.

LDAP query URL substitutions, $]...[

A substitution of the form $]ldap-url[ is specially handled. ldap-url is interpreted as an LDAP query URL and the result of the LDAP query is substituted. Standard LDAP URLs are used, with the host and port omitted; the host and part are instead specified with the LDAP_HOST and LDAP_PORT options. That is, the LDAP URL should be specified as:

ldap:///dn[?attributes[?scope?filter]]

where the square bracket characters [ and ] shown above 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 may 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.

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.

Note that 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. The database is generated with the imsimta crdb utility. 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.

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:

status = routine (argument, arglength, result, reslength)

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 allows 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:

$&A0A0,20,A1A1&

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 Table 10-5. Note that whenever an MTA configuration file such as imta.cnf, mappings, aliases, or option.dat is modified, you must recompile the configuration (see the imsimta refresh command in the Sun Java System Messaging Server Administration Reference).

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 or issue the command imsimta reload.

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 x_option, where x is the name of the channel. For example, msg_svr_base/config/imta/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 Reference Manual.

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.

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

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 the Mappings File and the Messaging Server Reference Manual.

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

Option File

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

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. It is preferable to make the changes while the MTA is down.

Note

Do not edit this file unless absolutely necessary.

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

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. A pool can be thought of 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, refer to The Job Controller, Processing Pools for Channel Execution Jobs, and Service Job Limits.)

Specifies for all channels, the master program name and the slave program name, if applicable

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

[POOL=MY_POOL]
job_limit = 12

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

channel_x pool MY_POOL
channel_x-daemon

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 doesn’t 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:

[POOL=single_job]
job_limit=1

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

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

This global option defines the TCP port number on which the Job Controller listens for requests.

Sets a default SLAVE_COMMAND for subsequent [CHANNEL] sections.

Sets a default MAX_LIFE_AGE for subsequent [CHANNEL] sections.

This [POOL] section defines a pool named DEFAULT.

Set the JOB_LIMIT for this pool to 10.

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.

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

The Job Controller creates and manages channel jobs for delivering messages. These channel jobs run inside processing pools within the Job Controller. A pool can be thought of 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. Note that 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 one may 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 we 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 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.

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, you should 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 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 doesn’t 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, 1800 (30 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 doesn’t 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.

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 Chapter 11, "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.

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:

<file-spec

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

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

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 database (also called the reverse 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 may prefer a public address like firstname.lastname@siroe.com.

Note

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

In the reverse database, the public address for each user is specified by the mail attribute of the user entry in the directory. The private or internal address is specified by the mailAlternativeAddress attribute. The same is true for distribution lists.

The reverse database contains a mapping between any valid address and this public address. The reverse database is generally located in the MTA database directory. The database is the files whose names are specified with the IMTA_REVERSE_DATABASE option in the msg_svr_base/config/imta_tailor file, which by default are the files msg_svr_base/data/db/reversedb.*

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.

REVERSE

OldAddress $Y[Flags]NewAddress

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

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 Sun Java System Messaging Server Administration Reference for details.

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

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

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

General Reverse Mapping Example

An example of a general REVERSE Mapping is as follows: suppose that the internal addresses at 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 database:

REVERSE

*@*.siroe.com $0@siroe.com$Y$D

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 database should contain entries of the form:

user@mailhost.siroe.com first.last@siroe.com

Channel-Specific Reverse Mapping Example

By default, the address reversal 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:

REVERSE

tcp_*|tcp_local|binky@macho.siroe.com $D$YRebecca.Woods@siroe.com

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 Table 10-8 for a list of additional flags.

Table 10-8 FORWARD mapping table flags 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. (Note that if channel specific forward lookup table use has been specified, then the source address and source channel will be prefixed to the result of the FORWARD mapping before looking up in the forward lookup table.) If a matching FORWARD mapping entry specifies $D, then the result of the FORWARD mapping (and optional forward table lookup) will be run through the MTA address rewriting process again. If a matching FORWARD mapping entry specifies $H, then no further FORWARD mapping or database lookups will be performed during that subsequent address rewriting (that resulting from the use of $D).

The example below 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 which do not fully comply with RFC 822 syntax rules—mailers which do not handle quoted addresses properly, for instance. Consequently, an address format which does not require quoting tends to operate with more mailers. One such format is

So the goals of the sample mapping tables in the above example are threefold. (1) Allow any of these three address formats above to be used. (2) Present only addresses in the original format to the mr_local channel, converting formats as necessary. (3) Present only addresses in the new unquoted format to all other channels, converting formats as necessary. (The REVERSE mapping shown assumes that bit 3 in the MTA option USE_REVERSE_DATABASE is set.

The Forward Lookup Table

In cases where address forwardings need to be auto-registered or source specific, the forward lookup table is available. Note that use of the Forward lookup table for simple forwarding of messages is generally not appropriate; the aliases file or alias lookup table is a more efficient way to perform such forwarding. By default, the forward lookup table is not used at all; its use must be explicitly enabled via the USE_FORWARD_DATABASE option. Forward table lookups are performed after address rewriting and after alias expansion is performed, and after any FORWARD mapping is checked. If a forward table lookup succeeds, the resulting substituted address is then run through the MTA address rewriting process all over again.

There are two mechanisms available for the forward lookup table, an in-memory hash table or conventional 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 3 (value 34) in the use_text_database option as well as setting use_forward_database. The hash table is read from msg_svr_base/configure/forward.txt, compiled into the reloadable part of the configuration, and can be forced to be reloaded into the active MTA processes by the imsimta reload command.

The forward database is an MTA crdb database, created using the crdb utility from a source text file. The format of the source text file by default is expected to be:

But if source specific use of the forward database has been enabled by setting bit 3 of the USE_FORWARD_DATABASE option, then the source text file format expected is:

source-channel|source-address|original-address changed-address

For instance, an entry such as

tcp_limited|bob@blue.com|helen@red.com “helen of troy”@siroe.com

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.

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 allows 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, etc.). 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:

Message text for *.txt files should be limited to 78 characters per line. Note that you shouldn’t change these files directly since they’ll be overwritten when the Messaging Server is upgraded. If you wish 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 wish 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.

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 format and structure of status notification message sets is described below.

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

Content-type: text/plain; charset=us-asciContent-language: EN-US

This report relates to a message you sent with the followingheader fields: %H

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 Table 10-9.

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

return_suffix.txt contains concluding text. By default this file is blank.

Table 10-9 Notification Message Substitution Sequences

Substitutions

Definition

%H

Expands into the message’s headers.

%C

Expands into the number of units1 the message has been queued.

%L

Expands into the number of units1 the message has left in the queue before it is returned.

%F

Expands into the number of units1 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 units1 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.

%%

% (Note that 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:

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.

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:

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 doesn’t 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 “your message to dan@siroe.com could not be delivered”—in this case dan@siroe.com is the envelope To: address being reported on.

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 as shown below. Note that each entry must start with one or more spaces, and that there can be no blank lines between entries.

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:

! <IMTA_TABLE:mappings.locale

(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 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 isn’t used and the notification didn’t 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.

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 will actually look like this:

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 doesn’t 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.

Note that the RETURN_UNITS option in the MTA Options file allows 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 will 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_jobconfigutil parameter.

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 sections below and in Table 10-11.

Returned Failed Messages

Keywords: sendpost, nosendpost, copysendpost, errsendpost

A channel program may 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 Table 10-11.)

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 Table 10-11.)

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 Table 10-11.)

Setting Per Channel Postmaster Addresses

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

Table 10-11 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.

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.