Chapter 10 About MTA Services and Configuration

This chapter describes general MTA services and configuration. More specific and detailed explanations may be found in other chapters. It consists of the following sections:

• 10.1 Compiling the MTA Configuration

• 10.2 The MTA Configuration File

• 10.3 Mappings File

• 10.4 Other MTA Configuration Files

• 10.5 Aliases

• 10.6 Command Line Utilities

• 10.7 SMTP Security and Access Control

• 10.8 Log Files

• 10.9 To Convert Addresses from an Internal Form to a Public Form

• 10.10 Controlling Delivery Status Notification Messages

• 10.11 Controlling Message Disposition Notifications

• 10.12 Optimizing MTA Performance

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

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

imsimta cnbuild
imsimta restart smtp 
imsimta restart job_controller

(See MTA Commands in Sun Java System Messaging Server 6.3 Administration Reference for details on these commands.)

Other instances where you must restart the job controller:

• Changes to 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 imta.cnf can be dealt with instead via 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 may 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 via 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 will do--and 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.

Note that any changes above (such as additions/changes to keywords on channel definitions) to imta.cnf also require an 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 above conditions necessitates a restart.

We do not recommend use of the imsimta refresh command on production systems because it is often not necessary to restart the job controller and restarting the job controller will reset message retries, delayed notification messages, bounced messages, and so on.

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

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 Chapter 11, Configuring Rewrite Rules, and Chapter 12, 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 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:

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

Refer to 8.4 Rewrite Rules, 8.5.3 Channel Definitions, and Chapter 11, Configuring Rewrite Rules” for more information on the MTA configuration file.

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

10.3 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 to which the input string is mapped (template). For details about which MTA processes uses which tables and when, see Table 10–2.

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. 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 (see10.1 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. See 10.1 Compiling the MTA Configuration

Table 10–2 lists the mapping tables described in this book.

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

TABLE1_NAME

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

TABLE2_NAME

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


TABLE3_NAME

           .
          .
          .

         

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

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

10.3.2 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. For details about which MTA processes uses which tables and when, see Table 10–2. This section consists of the following subsections:

• 10.3.2.1 Mapping Entry Patterns

• 10.3.2.2 IP Matching

• 10.3.2.3 Mapping Entry Templates

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

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

10.3.2.2 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. Note that IPv6 connection handling is not currently supported in Messaging Server.

10.3.2.3 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 listed in the sections about specific mappings tables,. See Table 18–1.

This section consists of the following subsections:

• Wildcard Field Substitutions ($n)

• Controlling Text Case ($\, $^, $_)

• Processing Control ($C, $L, $R, $E)

• Check for Special Flags

• Entry Randomly Succeeds or Fails ($?x?)

• Sequence Number Substitutions ($#...#)

• URL substitutions, $]...[

• Mapping Table Substitutions ($|...|)

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

• Site-Supplied Routine Substitutions ($[...])

• Generate UTF-8 Strings

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 control whether and when the mapping process terminates. As described in 10.3.2 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 18.7.4 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

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 Table 10–2for any special flags that may 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. (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.

PORT_ACCESS

   TCP|*|25|123.45.6.78|*         $C$?25?$Y
   TCP|*|25|123.45.6.78|*         $N45s$ 4.40$ 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 0s 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 UNIX 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.

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

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 (see 10.9.1 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.

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.

10.4 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. This section consists of the following subsections:

• 10.4.1 Alias File

• 10.4.2 TCP/IP (SMTP) Channel Option Files

• 10.4.3 Conversion File

• 10.4.4 Dispatcher Configuration File

• 10.4.5 Mappings File

• 10.4.6 Option File

• 10.4.7 Tailor File

• 10.4.8 Job Controller File

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 10.9.1 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 in Sun Java System Messaging Server 6.3 Administration Reference for details on these commands.

10.4.1 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 10.5 Aliases.

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

10.4.2 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/tcp_local_option. For more information refer to 12.4.1 Configuring SMTP Channel Options. For complete information on all channel option keywords and syntax, see the Sun Java System Messaging Server 6.3 Administration Reference.

10.4.3 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 13.5 The Conversion Channel

10.4.4 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 8.3 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 Sun Java System Messaging Server 6.3 Administration Reference.

10.4.5 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 10.3 Mappings File and theSun Java System Messaging Server 6.3 Administration Reference

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

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

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

Do not edit this file unless absolutely necessary.

For complete information on this file, see the Sun Java System Messaging Server 6.3 Administration Reference.

10.4.8 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 8.7 The Job Controller, 12.5.4 Processing Pools for Channel Execution Jobs and 12.5.5 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 job_controller.cnf) by using the pool keyword. 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.

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

Example 10–1 shows a sample Job Controller configuration file. Table 10–6 shows the available options.

Example 10–1 Sample Job Controller Configuration File in UNIX

!MTA Job Controller configuration file
!
!Global defaults
tcp_port=27442         (1)
secret=never mind
slave_command=NULL     (2)
max_life_age=3600      (3)
!
!
!Pool definitions
!
[POOL=DEFAULT]         (4)
job_limit=10           (5)
!
[POOL=LOCAL_POOL]
job_limit=10
!
[POOL=IMS_POOL]
job_limit=1
!
[POOL=SMTP_POOL]
job_limit=1
!
!Channel definitions
!
!
[CHANNEL=l]             (6)
master_command=msg-svr-base/lib/l_master
!
[CHANNEL=ims-ms]
master_command=msg-svr-base/lib/ims_master
!
[CHANNEL=tcp_*]         (7)
master_command=msg-svr-base/lib/tcp_smtp_client

The key items in the preceding example (numbered, enclosed in parentheses, and in bold font) 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

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.

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

tcp_yahoo smtp mx pool yahoo_pool keyword keyword keyword
tcp-yahoo-daemon

tcp_aol smtp mx keyword keyword keyword pool aol_pool
tcp-aol-daemon

tcp_hotmail smtp mx pool hotmail_pool keyword keyword keyword 
tcp-hotmail-daemon
...
tcp_sun smtp mx pool sun_pool keyword keyword keyword
tcp-sun-daemon

In order to add have ten tcp_smtp_client processes for each of the new channels we would add the following in the job_controller.cnf file:

[POOL=yahoo_pool]
job_limit=10

[POOL=aol_pool]
job_limit=10

[POOL=hotmail_pool]
job_limit=10

 ...

[POOL=sun_pool]
job_limit=10

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

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

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

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

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

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.

The format of the file is as follows:

user@domain: address (for users in hosted domains)

user@domain: address (for users in non-hosted domains. Example: default-domain)

For example:

! A /var/mail/ user
inetmail@siroe.com: inetmail@native-daemon

! A message store user
ms_testuser@siroe.com: mstestuser@ims-ms-daemon
         

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

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

10.7 SMTP Security and Access Control

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

10.8 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 Chapter 25, Managing Logging.

10.9 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 may 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 Chapter 11, Configuring Rewrite Rules.

This section consists of the following subsections:

• 10.9.1 MTA Text Databases

• 10.9.2 To Set Address Reversal Controls

• 10.9.3 The Forward Lookup Table and FORWARD Address Mapping

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

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.

REVERSE

   source-channel|destination-channel|OldAddress  $Y[Flags]NewAddresS

      

REVERSE mapping table flags as shown in Table 10–7.

10.9.1 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_DATAoptions 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 databasereverse.txt - reverse databaseforward.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 may be 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 wish 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 isn't--you're back to replacing the entire database when updating, which in this case, makes text databases preferable.

10.9.2 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 12.6.9 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. See Option File Format and Available Options in Sun Java System Messaging Server 6.3 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.

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

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

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

            

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

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

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

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

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

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 following input flags are now available in the FORWARD mapping. In the past they were only available to the various *_ACCESS mappings.

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

firstname.lastname@am.sigurd.example.com

Example of a complex FORWARD and REVERSE mapping:

REVERSE

 *|mr_local|"*,$ *"@am.sigurd.example.com $Y"$1,$ $2"@am.sigurd.example.com
 *|mr_local|"*,*"@am.sigurd.example.com   $Y"$1,$ $2"@am.sigurd.example.com
 *|*|"*,$ *"@am.sigurd.example.com        $Y$3.$2@am.sigurd.example.com
 *|*|"*,*"@am.sigurd.example.com          $Y$3.$2@am.sigurd.example.com
 *|mr_local|*.*@am.sigurd.example.com     $Y"$2,$ $1"@am.sigurd.example.com
 *|*|*.*@am.sigurd.example.com            $Y$2.$3@am.sigurd.example.com

FORWARD

 "*,$ *"@am.sigurd.example.com            $Y"$0,$ $1"@am.sigurd.example.com
 "*,*"@am.sigurd.example.com              $Y"$0,$ $1"@am.sigurd.example.com
 *.*@am.sigurd.example.com                $Y"$1,$ $0"@am.sigurd.example.com

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.

10.9.3.2 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 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 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 format of the source text file by default is expected to be:

user1@domain1 changedmailbox1@changeddomain1
user2@domain2 changedmailbox@changeddomain2

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

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.

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

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

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. Note that you shouldn’t change these files directly since they’ll be overwritten when the current version of 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.

This section consists of the following subsections:

• 10.10.1 To Construct and Modify Status Notifications

• 10.10.2 To Customize and Localize Delivery Status Notification Messages

• 10.10.3 Internationalization of Generated Notices

• 10.10.4 Additional Status Notification Message Features

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

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.

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:

   Content-type: text/plain; charset=us-asci Content-language: EN-US This report relates to a message you sent with the following header 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–10.

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

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

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

NOTIFICATION_LANGUAGE

 dsn-type-list|source-channel|preferred-language|return-address \
|first-recipient $Idirectory-spec

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

NOTIFICATION_LANGUAGE
 
! Preferred-language: header value specified
!
    *|*|fr|*|*     $I/lc_messages/table/notify_french/
    *|*|es|*|*     $IIMTA_TABLE/notify_spanish/
    *|*|en|*|*     $I/imta/lang/
!
! If no Preferred-language value, then select notification based on the
! country code in the domain name. EX: PF=French Polynesia; BO=Bolivia
!
    *|*|*|*.fr|*   $I/imta/table/notify_french/
    *|*|*|*.fx|*   $I/imta/table/notify_french/
    *|*|*|*.pf|*   $I/imta/table/notify_french/
    *|*|*|*.tf|*   $I/imta/table/notify_french/
    *|*|*|*.ar|*   $I/imta/table/notify_spanish/
    *|*|*|*.bo|*   $I/imta/table/notify_spanish/
    *|*|*|*.cl|*   $I/imta/table/notify_spanish/
    *|*|*|*.co|*   $I/imta/table/notify_spanish/
    *|*|*|*.cr|*   $I/imta/table/notify_spanish/
    *|*|*|*.cu|*   $I/imta/table/notify_spanish/
    *|*|*|*.ec|*   $I/imta/table/notify_spanish/
    *|*|*|*.es|*   $I/imta/table/notify_spanish/
    *|*|*|*.gp|*   $I/imta/table/notify_spanish/
    *|*|*|*.gt|*   $I/imta/table/notify_spanish/
    *|*|*|*.gy|*   $I/imta/table/notify_spanish/
    *|*|*|*.mx|*   $I/imta/table/notify_spanish/
    *|*|*|*.ni|*   $I/imta/table/notify_spanish/
    *|*|*|*.pa|*   $I/imta/table/notify_spanish/
    *|*|*|*.ve|*   $I/imta/table/notify_spanish/
                  

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

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

IMTA_LANG:return_option.dat (DSN)IMTA_LANG:disposition_option.dat (MDN)

The options available for these files are described in Table 10–11.

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

• 10.10.4.1 To Block Content Return on Large Messages

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

• 10.10.4.3 To Set Notification Message Delivery Intervals

• 10.10.4.4 To Include Altered Addresses in Status Notification Messages

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

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

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

10.10.4.3 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_job configutil parameter. Note, however, that by default this command is run on a regular basis (see 4.6.2 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.

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

10.10.4.5 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–12. This section consists of the following subsections:

• Returned Failed Messages

• Warning Messages

• Blank Envelope Return Addresses

• Postmaster Returned Message Content

• Setting Per Channel Postmaster Addresses

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

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

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.

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

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

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

10.11.1 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 10.10.2 To Customize and Localize Delivery Status Notification Messages and 10.10.3 Internationalization of Generated Notices.

The mapping (called the DISPOSITION_LANGUAGE mapping) parallels the notification_language mapping table (see 10.10.2 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.

10.12 Optimizing MTA Performance

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

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

10.12.1 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 follows:

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:

mgrpAllowedBroadcaster:
ldap:///o=Sesta,c=US??sub?(&(objectClass=inetMailUser)(objectClass=inetOrgPerson))
mgrpDeliverTo:
ldap:///o=Sesta,c=US??sub?(&(objectClass=inetMailUser)(objectClass=inetOrgPerson)) 

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:

mgrpAllowedBroadcaster:
ldap:///o=Sesta,c=US??sub?(&(objectClass=inetMailUser)(objectClass=inetOrgPerson)
(mail=$A)
mgrpDeliverTo:
ldap:///o=Sesta,c=US??sub?(&(objectClass=inetMailUser)(objectClass=inetOrgPerson)) 

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.