CHAPTER 2 |
IMTA Configuration |
The following topics are covered in this chapter:
|
|
"imta.cnf File" on page 68 |
|
|
"Domain Rewriting Rules" on page 70 |
|
|
"Template Substitutions" on page 77 |
|
|
"Handling Large Numbers of Rewrite Rules" on page 89 |
|
|
"Rewrite Rule Control Sequences" on page 88 |
|
|
"Channel Definitions" on page 92 |
|
|
"Channel Configuration Keywords" on page 93 |
|
|
"Aliases" on page 135 |
|
|
"Local Channel" on page 138 |
|
|
"SMTP Channel Option Files" on page 139 |
|
|
"The Pipe Channel" on page 144 |
|
|
"The Hold Channel" on page 145 |
|
|
"Conversion Channel" on page 145 |
|
|
"UUCP Channel" on page 153 |
|
|
"Mapping File" on page 156 |
|
|
"Option Files" on page 171 |
|
|
"Tailor File" on page 182 |
|
|
"Dirsync Option File" on page 186 |
|
|
"Autoreply Option File" on page 187 |
|
|
"Job Controller" on page 187 |
|
|
"SMTP Dispatcher" on page 193 |
This section explains the structure and layout of the IMTA configuration files. Some configuration modifications can be done using the command-line interface, as described in Chapter 1 in "Internet Message Transfer Agent" on page 43, or by using the accompanying SIMS Admin Console, as described in the SIMS Administrator's Guide. Modifications not possible through either can be done by editing the configuration files. We recommend that only experienced administrators edit and modify the configuration files. Many configuration settings can be defined using the GUI described in the Sun Internet Mail Server System Administrator's Guide.
Caution - Sun does not guarantee that the changes made by modifying configuration files will be recorded properly by the administration console. The administration console interfaces cannot recognize different types of information that the user might add to the configuration files.
All configuration files are ASCII text files that can be created or changed with any text editor. Permissions for the configuration file should be set to world-readable. Failure to make configuration files world-readable may cause unexpected IMTA failures. A physical line in most files is limited to 252 characters and you can split a logical line into multiple physical lines using the backslash (\) continuation character.
Note - If you change any of the files manually, restart your administration server after you make the changes. Then restart the administration console. This will ensure that the information that you changed in the imta.cnf configuration file is synchronized with the administration console.
By preprocessing these files and storing them in memory, the initialization time for IMTA is significantly reduced, thereby improving IMTA's performance.
TABLE 2-1 lists the IMTA configuration files with a short description.
TABLE 2-2 lists the IMTA database files with a short description.
The imta.cnf file contains the routing and address rewriting configuration. It defines all channels and their characteristics, the rules to route mail among those channels, and the method in which addresses are rewritten by the IMTA.
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.
Comment lines may appear anywhere in the configuration file. A comment is introduced with an exclamation point (!) in column one. Liberal use of comments to explain what is going on is strongly encouraged. The following imta.cnf file fragment displays the use of comment lines.
Distinguishing between blank lines and comment lines is important. Blank lines play an important role in delimiting sections of the configuration file. Comment lines are ignored by the configuration file reading routines--they are literally "not there" as far as the routines are concerned and do not count as blank lines.
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. The following imta.cnf file fragment includes the /etc/opt/SUNWmail/table/internet.rules file.
Note - Any files included in the configuration file must be world-readable just as the configuration file is world-readable.
Domain rewriting rules, or, as they are also called, "rewrite rules," play two important roles.
|
|
They are used to rewrite addresses into their proper form. |
|
|
They are used to determine to which channels a message should be enqueued. The determination of which channels to enqueue a message is made by rewriting its envelope To: addresses. |
Each rewrite rule appears on a single line in the upper half of the imta.cnf file.
For additional information about the domain configuring rules, refer to the Sun Internet Mail Server 4.0 Administrator's Guide.
The rewrite rules appear in the upper-half of the IMTA configuration file, imta.cnf (see the sample configuration file in "Configuration File Format" on page 195). Each rule in the configuration file appears on a single line. Comments, but not blank lines, are allowed between the rules. The rewrite rules end with a blank line, after which the channel definitions follow.
Rewrite rules consist of two parts: a pattern followed by an equivalence string or "template." The two parts must be separated by spaces, although spaces are not allowed within the parts themselves. The template specifies a usertemplate, any applicable options, a host/domain specification, and the name of a system attached to an existing IMTA channel (the routing system), to which messages to this address are sent. The structure for rewriting rules is:
TABLE 2-3 describes the parts of the rewriting rule structure.
TABLE 2-3 Rewriting Rule Structure Part
Description
pattern
The rule applies if the pattern matches the domain part of the address. Patterns can contain wildcards.
controls
The applicability of a rule can be limited using these control sequences. Control sequences can be located either before the user template or after the routing system. The selection criteria are described in TABLE 2-8. They include:
Envelope or header addresses
Direction (To or From)
Source or destination channel of the message [ userTemplate ]
Specifies how the user part of the address is rewritten. The template can be built using substitution sequences to represent certain parts of the original address or the results of a database lookup. The substitution sequences are replaced with what they represent in order to construct the rewritten address. See TABLE 2-5.
%
Separator used between userTemplate and domainTemplate (see preceding structure sample).
[ domainTemplate ]
Specifies how the domain part of the address is rewritten. Like the userTemplate, the domainTemplate can be built using substitution sequences.
@
Separator used between domainTemplate and routingSystem (see preceding structure sample).
[ routingSystem ]
Specifies the destination channel's routing system. Every channel is associated with a string (the routingSystem).
Refer to "Template Substitutions" on page 77 for additional information about rewrite rule structures and concepts.
The following steps apply to the application of the domain rewriting rules to a given address:
| 1. | The first host or domain specification is extracted from an address. |
| An address can specify more than one host or domain name as in the case: |
| jdoe%hostname@alpha.com. |
| 2. | After identifying the first host or domain name, a search is conducted that scans for a rewrite rule whose pattern matches the host/domain name. | |
| 3. | When the matching rewrite rule is found, the address is rewritten according to the template portion of that rule. |
| 4. | Finally, the routing system name is compared with the host names that are associated with each channel. |
Note - Using a routing system that does not belong to any existing channel will cause messages whose addresses match this rule to be bounced. That is, it makes matching messages nonroutable.
The process of rewriting an address starts by extracting the first host or domain specification from the address. (Readers not familiar with RFC 822 address conventions are advised to read that standard to understand the following discussion.) The order in which host/domain specifications in the address are scanned is as follows:
|
|
Hosts in source routes (read from left to right) |
|
|
Hosts appearing to the right of the "at" sign (@) |
|
|
Hosts appearing to the right of the last single percent sign (%) |
|
|
Hosts appearing to the left of the first exclamation point (!) |
The order of the last two items is switched if the bangoverpercent keyword is in effect on the channel that is doing the address rewriting. That is, if the channel attempting to enqueue the message is, itself, marked with the bangoverpercent channel keyword.
Some examples of addresses and the host names that could be extracted first are shown in TABLE 2-4.
RFC 822 does not address the interpretation of exclamation points (!) and percent signs (%) in addresses. Percent signs are customarily interpreted in the same manner as at signs (@) if no at sign is present, so this convention is adopted by IMTA.
The special interpretation of repeated percent signs is used to allow percent signs as part of local user names; thus is used in handling PSIMail and other foreign mail system addresses. The interpretation of exclamation points conforms to RFC 976's "bang-style" address conventions and makes it possible to use UUCP addresses with IMTA.
The order of these interpretations is not specified by either RFC 822 or RFC 976, so the bangoverpercent and nobangoverpercent keywords can be used to control the order in which they are applied by the channel doing the rewriting. The default is more "standard," although the alternate setting may be useful under some circumstances.
Note - The use of exclamation points (!) or percent signs (%) in addresses is not recommended. It is preferable to convert them into regular Internet addresses using the patterns $! or $%.
Once the first host or domain specification has been extracted from the address, the IMTA consults the rewrite rules to find out what to do with it. The host/domain specification is compared with the pattern part of each rule (that is, the left side of each rule). The comparison is case insensitive. Case insensitivity is mandated by RFC 822, UUCP addresses notwithstanding. The IMTA is insensitive to case but preserves it whenever possible.
If the host or domain specification does not match any pattern, in which case it is said to "not match any rule", the first part of the host or domain specification--the part before the first period, usually the host name--is removed and replaced with an asterisk (*) and another attempt is made to locate the resulting host or domain specification, but only in the configuration file rewrite rules (the domain database is not consulted).
If this fails, the first part is removed and the process is repeated. If this also fails the next part is removed (usually a subdomain) and the rewriter tries again, first with asterisks and then without. All probes that contain asterisks are done only in the configuration file rewrite rules table; the domain database is not checked. This process proceeds until either a match is found or the entire host or domain specification is exhausted. The effect of this procedure is to try to match the most specific domain first, working outward to less specific and more general domains.
A more algorithmic view of this matching procedure is:
|
|
The host/domain specification is used as the initial value for the comparison strings spec_1 and spec_2. (For example, spec_1 = spec_2 = a.b.c). |
|
|
The comparison string spec_1 is compared with the pattern part of each rewrite rule in the configuration file and then the domain database until a match is found. The matching procedure is exited if a match is found. |
|
|
If no match is found, then the left-most, nonasterisk part of spec_2 is converted to an asterisk. For example, if spec_2 is a.b.c then it is changed to *.b.c; if spec_2 is *.b.c, then it is changed to *.*.c. The matching procedure is exited if a match is found. |
|
|
If no match is found then the first part, including any leading period, of the comparison string spec_1 is removed. Where spec_1 has only one part (for example, .c or c), the string is replaced with a single period, ".". If the resulting string spec_1 is of nonzero length, then you return to step 1. If the resulting string has zero length (for example, was previously ".") then the lookup process has failed and you exit the matching procedure. |
For example, suppose the address dan@sc.cs.cmu.edu is to be rewritten. This causes the rewriter to look for the following patterns in the given order:
Once the host/domain specification matches a rewrite rule, it is rewritten using the template part of the rule. The template specifies three things:
| 1. | A new user name for the address, | |
| 2. | a new host/domain specification for the address, and | |
| 3. | the name of a system attached to an existing IMTA channel (the "routing system") to which messages to this address should actually be sent. |
The usual format for templates is A%B@C, where A is the new user name, B is the new host/domain specification, and C is the routing system. If B and C are identical, %B can be omitted; for example, you may use A@C when B and C are identical.
Substitution strings are allowed in the template. Any occurrences of $U in the template are replaced with the user name from the original address, any occurrences of $H are replaced with the portion of the host/domain specification that was not matched by the rule, and any occurrences of $D are replaced by the portion of the host/domain specification that was matched by the rewrite rule. $L substitutes the portion of a domain literal that was not matched by the rewrite rule.
Note - User names of the form a."b" will be replaced by "a.b" because current Internet standardization work is deprecating the former syntax from RFC 822. It is expected that the latter usage will become mandatory in future.
$$ expands to a single dollar sign, $; $% expands to a single percent, % (the percent is not interpreted as a template field separator in this case); and $@ expands to a single at sign, @ (also not interpreted as a field separator).
As an example, suppose that the host/domain specification jdoe@stream.com has matched the rewrite rule
stream.com $U@STREAM.COM
Then the template will produce the user name jdoe, the host/domain specification STREAM.COM, and the routing system STREAM.COM. In a slightly more complicated example, assume that the host/domain specification has matched the rewrite rule
.com $U%$H$D@TCP-DAEMON
In this case, $U = jdoe, $H = stream, and $D = .com. The template produces the username jdoe, the host/domain specification stream.com, and the routing system TCP-DAEMON.
TABLE 2-5 on page 78 contains a summary of these and other substitution strings, which are presented in "Template Substitutions" on page 77.
One of two things can happen once the host/domain specification is rewritten.
|
|
If the routing system is not associated with the local channel or there are no additional host/domain specifications in the address, the rewritten specification is substituted into the address replacing the original specification that was extracted for rewriting, and the rewriting process terminates. |
|
|
If the routing system matches the local channel and there are additional host/domain specifications that appear in the address, the rewritten address is discarded, the original (initial) host/domain specification is removed from the address, a new host/domain specification is extracted from the address and the entire process is repeated. Rewriting will continue until either all the host/domain specifications are gone or a route through a non-local channel is found. This iterative mechanism is IMTA's way of providing support for source routing. In effect, superfluous routes through the "local system" are removed from addresses by this process. |
If a host/domain specification fails to match any rewrite rule and no default rule is present, IMTA uses the specification "as-is"; for example, the original specification becomes both the new specification and the routing system. If the address has a nonsensical host/domain specification it will be detected when the routing system does not match any system name associated with any channel and the message will be bounced.
No additional syntax checking is done after the rewrite rules have been applied to an address. This is deliberate--it makes it possible for rewrite rules to be used to convert addresses into formats that do not conform to RFC 822. However, this also means that mistakes in the configuration file may result in messages leaving the IMTA with incorrect or illegal addresses.
Substitutions are used to abbreviate user names or addresses by inserting a character string into the rewritten address, the value of which is determined by the particular substitution sequence used. For example, in the template:
$U@stream.com
the $U is a substitution sequence. It causes the username portion of the address being rewritten to be substituted into the output of the template. Thus, if jdoe@mailhost.stream.com was being rewritten by this template, the resulting output would be jdoe@stream.com, the $U substituting in the username portion, jdoe, of the original address.
A summary of template substitutions appears in TABLE 2-5.
A substitution of the form $[image,routine,argument] is handled specially. The image,routine,argument part is used to find and call a customer-supplied routine. At runtime, IMTA uses dlopen and dlsym to dynamically load and call the routine routine from the shared library image. The routine routine is then called as a function, with the following argument list:
The argument and result are 252-byte long character string buffers. The routine routine returns a 0 if the rewrite rule fails, and -1 if the rewrite rule succeeds.
This mechanism allows the IMTA rewriting process to be extended in complex ways. For example, a call to a name service could be performed, and the result used to alter the address. For example, directory service lookups for forward-pointing addresses (To: addresses) to the host alpha.com might be performed as follows, with the rewrite rule, $F, described in TABLE 2-8 causing this rule to be used only for forward-pointing addresses):
jdoe@stream.com $F$[libxyz.so,mylookup,$U]
A forward-pointing address, jdoe@stream.com, when it matches this rewrite rule, causes libxyz.so to be loaded into memory, then causes the routine mylookup called with jdoe as the argument parameter. The routine mylookup might then return a different string, say, John.Doe%alpha.com in the result parameter and the value -1 to indicate that the rewrite rule succeeded. The percent sign (%) in the result string causes the rewriting process to start over again, using John.Doe@alpha.com as the address to be rewritten. The site-supplied shared library image image should be world readable.
Note - This facility is not designed for use by casual users; it is intended to be used to extend IMTA's capabilities system-wide.
Rewrite rules can possibly act only in conjunction with specific source channels. This is useful when a short-form name has two meanings:
| 1. | When it appears in a message arriving on one channel. | |
| 2. | When it appears in a message arriving on a different channel. |
Source channel-specific rewriting is associated with the channel program in use and the channel keywords rules and norules. If norules is specified on the channel associated with an IMTA component that is doing the rewriting, no channel-specific rewrite checking is done. If rules is specified on the channel, then channel-specific rule checks are enforced. The keyword rules is the default.
Source channel-specific rewriting is not associated with the channel that matches a given address. It depends only on the IMTA component doing the rewriting and that component's channel table entry. Channel-specific rewrite checking is triggered by the presence of a $N or $M control sequence in the template part of a rule. The characters following the $N or $M, up until either an at sign (@), percent sign (%), or subsequent $N, $M, $Q, $C, $T, or $? are interpreted as a channel name.
The $M channel causes the rule to fail if the channel channel is not currently doing the rewriting. The $N channel causes the rule to fail if the channel channel is doing the rewriting. Multiple $M and $N clauses may be specified. If any one of multiple $M clauses matches, the rule succeeds. If any of multiple $N clauses matches, the rules will fail.
Rewrite rules possibly can act only in conjunction with the channel to which the message is being queued. This is useful if a host has two names, one known to one group of hosts and one known to another. By using different channels to send mail to each group, addresses can be rewritten to refer to the host under the name known to each group.
Destination channel-specific rewriting is associated with the channel to which the message is to be dequeued and processed by, and the channel keywords rules and norules on that channel. If norules is specified on the destination channel, no channel-specific rewrite checking is done. If rules is specified on the destination channel, channel-specific rule checks are enforced. The keyword rules is the default.
Destination channel-specific rewriting is not associated with the channel matched by a given address. It depends only on the message's envelope To: address. When a message is enqueued, its envelope To: address is first rewritten to determine to which channel the message is enqueued. During the rewriting of the envelope To: address, any $C and $Q control sequences are ignored. After the envelope To: address is rewritten and the destination channel determined, then the $C and $Q control sequences are honored, as other addresses associated with the message are rewritten.
Destination channel-specific rewrite checking is triggered by the presence of a $C or $Q control sequence in the template part of a rule. The characters following the $C or $Q, up until either an at sign (@), percent sign (%), or subsequent $N, $M, $C, $Q, $T, or $? are interpreted as a channel name.
The $Q channel causes the rule to fail if the channel channel is not the destination. The $C channel causes the rule to fail if the channel channel is the destination. Multiple $Q and $C clauses may be specified. If any one of multiple $Q clauses matches, the rule succeeds. If any of multiple $C clauses matches, the rule fails.
Sometimes you need to specify rewrite rules that apply only to envelope addresses or, alternately, only to header addresses. The control sequence $E forces a rewrite to fail if the address being rewritten is not an envelope address. The control sequence $B forces a rewrite to fail if the address being rewritten is not from the message header or body. These sequences have no other effects on the rewrite and may appear anywhere in the rewrite rule template.
Addresses may also be categorized by direction. A forward pointing address is one that originates on a To:, Cc:, Resent-to:, or other header or envelope line that refers to a destination. A backward pointing address is something like a From:, Sender:, or Resent-From:, that refers to a source. The control sequence $F causes the rewrite to fail if the address is backward pointing. The control sequence $R causes the rewrite to fail if the address is forward-pointing.
Circumstances occasionally require rewriting that is sensitive to the location where a host name appears in an address. Host names can appear in several different contexts in an address:
|
|
In a source route |
|
|
To the right of the at sign (@) |
|
|
To the right of a percent sign (%) in the local-part |
|
|
To the left of an exclamation point in the local-part |
Under normal circumstances, a host name should be handled in the same way, regardless of where it appears. Situations might require specialized handling.
Four control sequences are used to control matching on the basis of the host's location in the address.
| 1. | $S specifies that the rule can match a host extracted from a source route. | |
| 2. | $A specifies that the rule can match a host found to the right of the @ sign. | |
| 3. | $P specifies that the rule can match a host found to the right of a % sign. | |
| 4. | $X specifies that the rule can match a host found to the left of an exclamation point (!). |
The rule fails if the host is from a location other than one specified. These sequences can be combined in a single rewrite rule. For example, if $S and $A are specified, the rule matches hosts specified in either a source route or to the right of the at sign. Specifying none of these sequences is equivalent to specifying all of them; the rule can match regardless of location.
Single field substitutions extract a single subdomain part from the host/domain specification being rewritten. The available single field substitutions are shown in TABLE 2-6.
Suppose the address jdoe@vaxa.stream.com matches the following rewrite rule:
Then the result from the template will be jdoe@vaxa.stream.com with mailhub.stream.com used as the routing system.
Domain literals are handled specially during the rewriting process. If a domain literal appearing in the left of an address does not match, the literal is interpreted as a group of strings separated by periods and surrounded by square brackets. The right-most string is removed and the search is repeated. If this does not work, the next string is removed, and so on until only empty brackets are left. If the search for empty brackets fails, the entire domain literal is removed and rewriting proceeds with the next section of the domain address, if there is one. No asterisks are used in the internal processing of domain literals; when an entire domain literal is replaced by an asterisk, the number of asterisks corresponds to the number of elements in the domain literal.
Like normal domain or host specifications, domain literals are also tried in most specific to least specific order. The first rule whose pattern matches will be the one used to rewrite the host or domain specification. If there are two identical patterns in the rules list, the one which appears first will be used.
As an example, suppose the address dan@[128.6.3.40] is to be rewritten. The rewriter looks for [128.6.3.40], then [128.6.3.], then [128.6.], then [128.], then [], then [*.*.*.*], and finally the match-all rule ".".
A substitution of the form $(text) is handled specially. This database is generated with the crdb utility. If text is found in the database the corresponding template from the database is substituted. If text does not match an entry in the database the rewrite process fails; it is as if the rewrite rule never matched in the first place. If the substitution is successful, the template extracted from the database is rescanned for additional substitutions. However, additional $(text) substitutions from the extracted template are prohibited in order to prevent endless recursive references.
As an example, suppose that the address jdoe@stream.decnet matches the following rewrite rule:
Then, the text string stream will be looked up in the general database and the result of the lookup, if any, used for the rewrite rule's template. Suppose that the result of looking up stream is $u%eng.stream.com@tcp-local. Then the output of the template will be jdoe@eng.stream.com (username = jdoe, host or domain specification = eng.stream.com), and the routing system will be tcp-local.
If a general database exists, it should be world readable to insure that it operates properly.
Note - This database consists of files specified with the IMTA_GENERAL_DATABASE option in the /etc/opt/SUNWmail/imta/imta/tailor file, which are usually the files /var/opt/SUNWmail/imta/db/generaldb.*.
A substitution of the form ${mapping,argument} is handled specially. The mapping,argument part is used to find and apply a mapping from the IMTA mapping file. The mapping field specifies the name of the mapping table to use while argument specifies the string to pass to the mapping. The mapping must exist and must set the $Y flag in its output if it is successful; if it doesn't exist or doesn't set $Y, the rewrite will fail. If successful the result of the mapping is merged into the template at the current location and re-expanded.
This mechanism allows the IMTA's rewriting process to be extended in various complex ways. For example, the user name part of an address can be selectively analyzed and modified, which normally isn't a feature that the IMTA's rewriting process is capable of.
Rewrite rules can make use of several special patterns, summarized in TABLE 2-7, and discussed in the following subsections.
In addition to these special patterns, IMTA also has the concept of tags, which may appear in rewrite rule patterns. These tags are used in situations where an address may be rewritten several times and, based upon previous rewritings, distinctions must be made in subsequent rewrites by controlling which rewrite rules match the address.
If IMTA tries to rewrite an address of the form A%B and fails, it tries one extra rule before falling through and treating this address form as A%B@localhost. This extra rule is the percent hack rule. The pattern is $%. The pattern never changes. This rule is only activated when a local part containing a percent sign has failed to rewrite any other way (including the match all rule described below).
The percent hack rule is useful for assigning some special, internal meaning to percent hack addresses.
If IMTA tries to rewrite an address of the form B!A and fails, it tries one extra rule before falling through and treating this address form as B!A@localhost. This extra rule is the bang-style rule. The pattern is $!. The pattern never changes. This rule is only activated when a local part containing an exclamation point has failed to rewrite any other way (including the default rule described below).
The bang-style rule can be used to force UUCP style addresses to be routed to a system with comprehensive knowledge of UUCP systems and routing.
The special pattern "." (a single period) will match any host/domain specification if no other rule matches and the host/domain specification cannot be found anywhere in the channel table. In other words, the "." rule is used as a last resort when address rewriting would fail otherwise.
Note - When the match-all rule matches and its template is expanded, $H expands to the full host name and $D expands to a single dot ".". Thus, $D is of limited use in a match-all rule template!
As the rewrite process proceeds it may be appropriate to bring different sets of rules into play. This is accomplished by the use of the rewrite rule tag. The current tag is prepended to each pattern before looking it up in the configuration file or domain database. The tag can be changed by any rewrite rule that matches by using the $T substitution string in the rewrite rule template (described below).
Tags are somewhat sticky; once set they will continue to apply to all hosts that are extracted from a single address. This means that care must be taken to provide alternate rules that begin with the proper tag values once any tags are used. In practice this is rarely a problem since tags are usually used in only very specialized applications. Once the rewriting of the address is finished the tag is reset to the default tag---an empty string.
By convention all tag values end in a vertical bar |. This character is not used in normal addresses and thus is free to delineate tags from the rest of the pattern.
Changing the Current Tag Value, $T
The $T control sequence is used to change the current rewrite rule tag. The rewrite rule tag is prepended to all rewrite rule patterns before they are looked up in the configuration file and domain database. Text following the $T, up until either an @ sign, percent sign, $N, $M, $Q, $C, $T, or $? is taken to be the new tag.
Tags are useful in handling special addressing forms where the entire nature of an address is changed when a certain component is encountered. For example, suppose that the special host name internet, when found in a source route, should be removed from the address and the resulting address forcibly matched against the TCP-DAEMON channel. This could be implemented with rules like the following (localhost is assumed to be the official name of the local host):
internet $S$U@localhost$Tmtcpforce |
mtcp-force|. $U%$H@TCP-DAEMONThe first rule will match the special host name internet if it appears in the source route. It forcibly matches internet against the local channel, which insures that it will be removed from the address. A rewrite tag is then set. Rewriting proceeds, but no regular rule will match because of the tag. Finally, the default rule is tried with the tag, and the second rule of this set fires, forcibly matching the address against the TCP- DAEMON channel regardless of any other criteria.
The IMTA provides default error messages when rewriting and channel matching fail. The ability to change these messages can be useful under certain circumstances. For example, if someone tries to send mail to an Ethernet router box, it may be considered more informative to say something like "our routers cannot accept mail" rather than the usual "illegal host/domain specified."
A special control sequence can be used to change the error message that is printed if the rule fails. The sequence $? is used to specify an error message. Text following the $?, up to either an at sign (@), percent sign (%), $N, $M, $Q, $C, $T, or $? is taken to be the text of the error message to print if the result of this rewrite fails to match any channel. The setting of an error message is "sticky" and lasts through the rewriting process.
A rule that contains a $? operates just like any other rule. The special case of a rule containing only a $? and nothing else receives special attention: The rewriting process is terminated without changing the mailbox or host portions of the address and the host is looked up as is in the channel table. This lookup is expected to fail and the error message is returned as a result. For example, if the final rewrite rule in the IMTA configuration file is:
$?Unrecognized address; contact postmaster@xyz.com
then any unrecognized host or domain specifications that can fail will, in the process of failing, generate the error message: Unrecognized address; contact postmaster@xyz.com.
Special control sequences can also appear in rewrite rule templates. These sequences impose additional conditions to the applicability of a given rewrite rule. Not only must the pattern portion of the rewrite rule match the host or domain specification being examined, but other aspects of the address being rewritten must meet conditions set by the control sequence or sequences. For instance, the $E control sequence requires that the address being rewritten be an envelope address, while the $F control sequence requires that it be a forward pointing address. Thus, the rewrite rule:
stream.com $U@mail.stream.com$E$F
only applies to (rewrite) envelope To: addresses of the form user@stream.com. If a domain or host specification matches the pattern portion of a rewrite rule but doesn't meet all of the criteria imposed by control sequences in the rule's template, then the rewrite rule fails and the rewriter continues to look for other applicable rules. This makes possible sets of rewrite rules such as:
stream.com $U@mail.stream.com$Nverify
stream.com $U%stream.com@verify-daemonwhich results in messages to user@stream.com being passed to the directory channel. However, should the verify channel rewrite a message with the address user@stream.com, that message does not again pass through the verify channel. This then allows all mail to user@stream.com to pass through the verify channel and for the verify channel to send mail to that address without causing a mail loop.
A summary of control sequences appears in TABLE 2-8.
IMTA always reads in all the rewrite rules from the configuration file and stores them in memory in a hash table. Use of a compiled configuration bypasses the overhead associated with reading the configuration file each and every time the information is needed; a hash table is still used to store all of the rewrite rules in memory. This scheme is adequate for small to medium numbers of rewrite rules. However, some sites may require as many as 10,000 rewrite rules or more, which can consume prohibitive amounts of memory.
The IMTA solves this problem by providing an optional facility for storing large numbers of rewrite rules in an ancillary indexed data file. Whenever the regular configuration file is read, IMTA checks for the existence of the domain database, IMTA_DOMAIN_DATABASE. If this database exists, it is opened and consulted whenever an attempted match fails on the rules found in the configuration file. The domain database is only checked if a given rule is not found in the configuration file, so rules can always be added to the configuration file to override those in the database. By default, the domain database is used to store rewrite rules associated with hosted domains. DO NOT EDIT BY HAND.
You can test rewrite rules with the imta test -rewrite command. The -noimage qualifier will allow you to test changes made to the configuration file prior to recompiling and reinstalling the new configuration.
You may find it helpful to rewrite a few addresses using this utility with the -debug qualifier. This will show you step-by-step how the address is rewritten. For example, issue the following command:
% imta test -rewrite joe@alpha.com
For a detailed description of the imta test -rewrite utility, refer to Chapter 1, "Commands Reference."
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 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. | |
| 4. | The first channel block to appear is always channel l (the local channel, designated with the lowercase letter "l"). Blank lines then separate each channel block from one another. An exception is a defaults channel, which can appear before channel l. |
TABLE 2-9 lists the routing and queuing of messages by the preceding configuration:
TABLE 2-9 Address Routing and Channel Queuing Address
Queued to channel
u@a
a_channel
u@b
b_channel
u@c
b_channel
u@d
a_channel
The second part of an IMTA configuration file contains the definitions for the channels themselves. These definitions are collectively referred to as the "channel or host table." Each individual channel definition forms a "channel block," which defines the channels that IMTA can use and the names associated with each channel. Blocks are separated by single blank lines. Comments, but no blank lines, may appear inside a channel block. A channel block contains a list of keywords which define the configuration of a channel. These keywords are referred to as "channel keywords." See TABLE 2-10 for more information.
The following imta.cnf file fragment displays a sample channel block:
The routing_system is an abstract label used to refer to this channel within the rewrite rules.
For detailed information about channel definitions and channel table keywords, refer to the section "Channel Configuration Keywords," and to TABLE 2-10.
The first line of each channel block is composed of the channel name, followed by a list of keywords defining the configuration of the specific channel. The following sections describe keywords and how they control the types of addresses the channel supports. A distinction is made between the addresses used in the transfer layer (the message envelope) and those used in message headers.
The keywords following the channel name are used to assign various attributes to the channel. Keywords are case-insensitive, and may be up to 32 characters long; any additional characters are ignored. The supported keywords are listed in TABLE 2-10; the keywords shown in boldface are defaults.
Specifying a keyword not on this list is not an error (although it may be incorrect). On UNIX systems, undefined keywords are interpreted as group IDs. The imta test -rewrite utility tells you whether you have any keywords in your configuration file that don't match a known rights list identifier.
TABLE 2-10 Channel Keywords Keyword
Usage
addrsperfile (page 106)
Number of addresses per message file.
addrsperjob (page 105)
Number of addresses to be processed by a single job.
after
Specifies time delay before master channel programs run.
allowetrn
The IMTA will attempt to honor all ETRN commands. (default)
allowswitchchannel (page 118)
Allows switching to this channel from an allowswitchchannel channel.
bangoverpercent (page 100)
Group A!B%C as A!(B%C).
bidirectional (page 102)
Channel is served by both a master and slave program.
blocketrn
Tells the IMTA not to honor ETRN commands.
blocklimit (page 131)
Maximum number of IMTA blocks allowed per message.
cacheeverything (page 103)
Caches all connection information.
cachefailures (page 155)
Caches only connection failure information.
cachesuccess (page 103)
Caches only connection success information.
charset7 (page 121)
Default character set to associate with 7-bit text messages.
charset8 (page 121)
Default character set to associate with 8-bit text messages.
checkehlo (page 113)
Checks the SMTP response banner for whether to use EHLO.
commentinc (page 127)
Leaves comments in message header lines intact.
commentomit (page 127)
Removes comments from message header lines.
commentstrip (page 127)
Removes problematic characters from comment field in message header lines.
commenttotal (page 127)
Strips comments (material in parentheses) everywhere.
connectalias (page 101)
Does not rewrite addresses upon message dequeue.
connectcanonical (page 101)
Rewrites addresses upon message dequeue.
copysendpost (page 109)
Sends copies of failures to the postmaster unless the originator address is blank.
copywarnpost (page 110)
Sends copies of warnings to the postmaster unless the originator address is blank.
daemon
Specifies the name of a gateway to which the daemon is routed.
datefour (page 128)
Converts date/time specifications to four-digit years.
datetwo (page 128)
Converts date/time specifications to two-digit years.
dayofweek (page 128)
Includes day of week in date and time specifications.
defaultmx (page 115)
Channel determines whether or not to do MX lookups from network.
deferred (page 108)
Honors deferred delivery dates.
defragment (page 130)
Reassembles any MIME-compliant message/partial parts queued to this channel.
domainetrn
Tells the IMTA to honor only those ETRN commands that specify a domain. It also causes the IMTA not to echo back the name of the channel that the domain matched and that the IMTA will be attempting to run.
domainvrfy (page 114)
Issues SMTP VRFY commands using full address.
ehlo (page 113)
Uses EHLO on all initial SMTP connections.
eightbit (page 120)
Channel supports 8-bit characters.
eightnegotiate (page 120)
Channel should negotiate use of eight bit transmission, if possible.
eightstrict (page 120)
Channel should reject messages that contain unnegotiated 8-bit data.
errsendpost (page 109)
Sends copies of failures to the postmaster if the originator address is illegal.
errwarnpost (page 110)
Sends copies of warnings to the postmaster if the originator address is illegal.
expandchannel
expandlimit (page 107)
Processes an incoming message "offline" when the number of addressees exceeds this limit.
exproute (page 100)
Explicit routing for this channel's addresses.
filesperjob (page 105)
Number of queue entries to be processed by a single job.
forwardcheckdelete
Tells the IMTA to do a forward lookup after each reverse lookup and to ignore (delete) the reverse lookup returned name if the forward lookup of that name does not match the original connection IP address. Use the original IP address instead.
forwardchecknone
No forward lookup is done
forwardchecktag
Tells the IMTA to do a forward lookup after each reverse lookup and to tag the IP name with an asterisk, *, if the number found using the forward lookup does not match that of the original connection.
headerinc
Places the message header at the top of the message.
headerlabelalign (page 129)
Aligns headers.
headerlinelength (page 129)
Folds long headers.
headerread (page 123)
Applies header trimming rules from an options file to the message headers upon message enqueue (use with caution).
headertrim (page 123)
Applies header trimming rules from an options file to the message headers (use with caution).
identnone (page 116)
Does not perform IDENT lookups; does perform IP-to-hostname translation.
identnonelimited
Has the same effect as identnone as far as IDENT lookups, reverse DNS lookups, and information displayed in Received: header. With identnonelimited the IP literal address is always used as the basis for any channel switching due to use of the switchchannel keyword, regardless of whether the DNS reverse lookup succeeds in determining a host name.
identnonenumeric (page 116)
Does not perform IDENT lookups or IP-to-hostname translation.
identnonesymbolic
Disables this IDENT lookup, but does do IP to host name translation; only the host name will be included in the Received: header for the message.
identtcp (page 116)
Performs IDENT lookups on incoming SMTP connections and IP to host name translation.
identtcplimited
Has the same effect as identtcp as far as IDENT lookups, reverse DNS lookups, and information displayed in Received: header. With identtcplimited the IP literal address is always used as the basis for any channel switching due to use of the switchchannel keyword, regardless of whether the DNS reverse lookup succeeds in determining a host name.
identtcpnumeric (page 116)
Performs IDENT lookups on incoming SMTP connections, but do not perform IP to hostname translation.
identtcpsymbolic
Tells the IMTA to perform a connection and lookup using the IDENT protocol (RFC 1413).
ignoreencoding (page 124)
Ignores Encoding: header on incoming messages.
immediate (page 102)
Delivery started immediately after submission for messages of second-class or higher priority.
immnonurgent (page 102)
Delivery started immediately after submission, even for messages with lower-than-normal priority.
immnormal (page 102)
Delivery started immediately after submission for messages of normal-or-higher priority.
immurgent (page 102)
Delivery started immediately after submission for urgent messages only.
improute (page 100)
Implicit routing for this channel's addresses.
includefinal
Include final form of address in delivery notifications.
inner (page 122)
Rewrites inner message headers.
innertrim (page 123)
Applies header trimming rules from an options file to inner message headers (use with caution).
interpretencoding (page 124)
Interprets Encoding: header on incoming messages.
lastresort (page 116)
Specifies a last-resort host.
linelength (page 121)
Message lines exceeding this length limit are wrapped.
linelimit (page 131)
Maximum number of lines allowed per message.
localvrfy (page 114)
Issues SMTP VRFY command using local address.
logging (page 132)
Log message enqueues and dequeues into the log file.
mailfromdnsverify
Setting on an incoming TCP/IP channel causes the IMTA to verify that an entry in the DNS exists for the domain used on the SMTP MAIL FROM: command, and to reject the message if no such entry exists.
master (page 102)
Channel is served only by a master program.
master_debug (page 132)
Generates debugging output in the channel's master program output.
maxblocks (page 130)
Maximum number of IMTA blocks per message; longer messages are broken into multiple messages.
maxheaderaddrs (page 129)
Maximum number of addresses per message header line; longer header lines are broken into multiple header lines.
maxheaderchars (page 129)
Maximum number of characters per message header line; longer header lines are broken into multiple header lines.
maxjobs (page 105)
Maximum number of jobs that can be created at one time.
maxlines (page 130)
Maximum number of message lines per message; longer messages are broken into multiple messages.
maxperiodic--
The maxperiodicnonurgent, maxperiodicnormal, or maxperiodicurgent keywords specify the maximum priority of message that a periodic job should try to deliver; the job will ignore messages of higher priority.
maxprocchars (page 132)
Specifies maximum length of headers to process.
maysaslserver
Causes the SMTP server to permit clients to attempt to use SASL authentication.
minperiodic--
The minperiodicnonurgent, minperiodicnormal, or minperiodicurgent keywords specify the minimum priority of message that a periodic job should try to deliver; the job will ignore messages of lower priority.
missingrecipientpolicy
Takes an integer value specifying the approach to use for such messages; the default value, if the keyword is not explicitly present, is 0, meaning that envelope To: addresses are placed in a To: header.
multiple (page 106)
Accepts multiple destination hosts in a single message copy.
mustsaslserver
Causes the SMTP server to insist that clients use SASL authentication; the SMTP server will not accept messages unless the remote client successfully authenticates.
mx (page 115)
TCP/IP network and software supports MX record lookups.
nobangoverpercent (page 100)
Group A!B%C as (A!B)%C (default).
nocache (page 155)
Does not cache any connection information.
nodayofweek (page 128)
Removes day of week from date/time specifications.
nodeferred (page 108)
Does not honor deferred delivery dates.
nodefragment (page 130)
Does not perform special processing for message/partial messages.
noehlo (page 113)
Never use the SMTP EHLO command.
noexproute (page 100)
No explicit routing for this channel's addresses.
noheaderread (page 123)
Does not apply header trimming rules from option file upon message enqueue.
noheadertrim (page 123)
Does not apply header trimming rules from options file.
noimproute (page 100)
No implicit routing for this channel's addresses.
noinner (page 122)
Does not rewrite inner message headers.
noinnertrim (page 123)
Does not apply header trimming to inner message headers.
nologging (page 132)
Does not log message enqueues and dequeues into the log file.
nomailfromdnsverify
Means that IMTA does not verify that an entry in the DNS exists for the domain used.
nomaster_debug (page 132)
Does not generate debugging output in the channel's master program output.
nomx (page 115)
TCP/IP network does not support MX lookups.
nonrandommx (page 115)
Does MX lookups; does not randomize returned entries with equal precedence.
nonurgentblocklimit (page 103)
Forces messages above this size to wait unconditionally for a periodic job.
noreceivedfor (page 125)
Does not include envelope to address in Received header.
noreceivedfrom
Instructs the IMTA to construct Received: headers without including the original envelope From: address.
noremotehost (page 119)
Uses local host's domain name as the default domain name to complete addresses.
norestricted
Does not apply RFC 1137 restricted encoding to addresses.
noreverse (page 122)
Does not apply reverse database to addresses.
normalblocklimit (page 103)
Forces messages above this size to nonurgent priority.
nosasl
SASL authentication will not be permitted or attempted.
nosaslserver
SASL authentication will not be permitted.
nosendpost (page 109)
Does not send copies of failures to the postmaster.
nosendetrn
The IMTA will not send an ETRN command.
noserviceall (page 133)
Indicates that the master program should only process the messages that were queued to process after its inception.
noslave_debug (page 132)
Does not generate debugging output in the channel's slave program output.
nosmtp (page 112)
Channel does not use SMTP.
noswitchchannel (page 118)
Stays with the server channel; do not switch to the channel associated with the originating host; does not permit being switched to.
notices (page 108)
Specifies the amount of time that may elapse before notices are sent and messages returned.
novrfy (page 114)
Does not issue SMTP VRFY commands.
nowarnpost (page 110)
Does not send copies of warnings to the postmaster.
nox_env_to (page 124)
Does not add X-Envelope-to header lines while enqueuing.
period (page 102)
Specifies periodicity of periodic channel service.
periodic (page 102)
Channel is serviced only periodically; immediate delivery processing is never done.
personalinc (page 127)
Leaves personal names in message header lines intact.
personalomit (page 127)
Removes personal name fields from message header lines.
personalstrip (page 127)
Strips problematic characters from personal name fields in message header lines.
port (page 115)
Sends to the specified TCP/IP port.
postheadbody (page 111)
Both the message's header and body are sent to the postmaster when a delivery failure occurs.
postheadonly (page 111)
Only the message's header is sent to the postmaster when a delivery failure occurs.
queue (page 108)
Specifies queue master channel programs run in.
randommx (page 115)
Does MX lookups; randomizes returned entries with equal precedence.
receivedfor (page 125)
Includes envelope to address in Received header.
receivedfrom
Instructs the IMTA to include the original envelope From: address when constructing a Received: header for an incoming message if the IMTA has changed the envelope From: address due to, for example, certain sorts of mailing list expansions. receivedfrom is the default.
remotehost (page 119)
Uses remote host's name as the default domain name to complete addresses.
restricted (page 122)
Applies RFC 1137 restricted encoding to addresses.
returnenvelope (page 125)
Controls use of blank envelope return addresses.
reverse (page 122)
Applies reverse database to addresses.
saslswitchchannel
Causes incoming connections to be switched to a specified channel upon a client's successful use of SASL. It takes a required value, specifying the channel to which to switch.
sendpost (page 109)
Sends copies of failures to the postmaster.
sendetrn
Tells the IMTA to send an ETRN command, if the remote SMTP server says it supports ETRN. The sendetrn keyword should be followed by the name of the system requesting that its messages receive a delivery attempt.
sensitivity--
The sensitivitynormal, sensitivitypersonal, sensitivityprivate, and sensitivitycompanyconfidential (messages of any sensitivity are allowed) keywords set an upper limit on the sensitivity of messages that can be accepted by a channel.
serviceall (page 133)
Specifies that the master program should attempt to process all messages queued to the channel each time it runs.
sevenbit (page 120)
Channel does not support 8-bit characters; 8-bit characters must be encoded.
silentetrn
Tells the IMTA to honor all ETRN commands, but without echoing the name of the channel that the domain matched and that the IMTA will be attempting to run.
single (page 106)
Only one envelope To address per message copy.
single_sys (page 106)
Each message copy must be for a single destination system.
slave (page 102)
Channel is serviced only by a slave program.
slave_debug (page 132)
Generates debugging output in the channel's slave program output.
smtp (page 112)
Channel uses SMTP.
smtp_cr (page 112)
Accepts CR as an SMTP line terminator.
smtp_crlf (page 112)
Requires CRLF as the SMTP line terminator.
smtp_lf (page 112)
Accepts LF as an SMTP line terminator.
sourceroute
Uses source routes in the message envelope; synonymous with 822.
subdirs (page 107)
Uses multiple subdirectories.
suppressfinal
Causes IMTA to suppress the final address form, if an original address form is present, from notification messages.
switchchannel (page 118)
Switches from the server channel to the channel associated with the originating host.
threaddepth (page 112)
Number of messages triggering new thread with multithreaded SMTP client.
unrestricted (page 122)
Does not apply RFC 1137 restricted encoding to addresses.
urgentblocklimit (page 103)
Forces messages above this size to normal priority.
usereplyto (page 126)
Specifies mapping of Reply-to header.
useresent (page 126)
Specifies mapping of Resent- headers for non-RFC 822 environments.
vrfyallow
Tells IMTA to issue a detailed, informative response.
vrfydefault
Tells IMTA to provide a detailed, informative response, unless the channel option HIDE_VERIFY=1 has been specified.
vrfyhide
Tells IMTA to issue only a vague, ambiguous response.
warnpost (page 110)
Sends copies of warnings to the postmaster.
x_env_to (page 124)
Adds X-Envelope-to header lines while enqueuing.
Addresses are always interpreted in accordance with RFC 822 and RFC 976. However, there are ambiguities in the treatment of certain composite addresses that are not addressed by these standards. In particular, an address of the form A!B%C can be interpreted as either:
|
|
A as the routing host and C as the final destination host |
or
|
|
C as the routing host and A as the final destination host |
While RFC 976 implies that mailers can interpret addresses using the latter set of conventions, it does not say that such an interpretation is required. Some situations may be better served by the former interpretation.
The bangoverpercent keyword forces the former A!(B%C) interpretation. The nobangoverpercent keyword forces the latter (A!B)%C interpretation. nobangoverpercent is the default.
Note - This keyword does not affect the treatment of addresses of the form A!B@C. These addresses are always treated as (A!B)@C. Such treatment is mandated by both RFC 822 and RFC 976.
The addressing model that IMTA deals with assumes that all systems are aware of the addresses of all other systems and how to get to them. Unfortunately, this ideal is not possible in all cases, such as when a channel connects to one or more systems that are not known to the rest of the world (for example, internal machines on a private TCP/IP network). Addresses for systems on this channel may not be legal on remote systems outside of the site. If you want to be able to reply to such addresses, they must contain a source route that tells remote systems to route messages through the local machine. The local machine can then (automatically) route the messages to these machines.
The exproute keyword (short for "explicit routing") tells IMTA that the associated channel requires explicit routing when its addresses are passed on to remote systems. If this keyword is specified on a channel, IMTA adds routing information containing the name of the local system (or the current alias for the local system) to all header addresses and all envelope From: addresses that match the channel. noexproute, the default, specifies that no routing information should be added.
The EXPROUTE_FORWARD option can be used to restrict the action of exproute to backward-pointing addresses. Another scenario occurs when IMTA connects to a system through a channel that cannot perform proper routing for itself. In this case, all addresses associated with other channels need to have routing indicated when they are used in mail sent to the channel that connects to the incapable system.
Implicit routing and the improute keyword is used to handle this situation. IMTA knows that all addresses matching other channels need routing when they are used in mail sent to a channel marked improute. The default, noimproute, specifies that no routing information should be added to addresses in messages going out on the specified channel. The IMPROUTE_FORWARD option can be used to restrict the action of improute to backward-pointing addresses.
The exproute and improute keywords should be used sparingly. It makes addresses longer, more complex, and may defeat intelligent routing schemes used by other systems. Explicit and implicit routing should not be confused with specified routes. Specified routes are used to insert routing information from rewrite rules into addresses. This is activated by the special A@B@C rewrite rule template.
Specified routes, when activated, apply to all addresses, both in the header and the envelope. Specified routes are activated by particular rewrite rules and as such are usually independent of the channel currently in use. Explicit and implicit routing, on the other hand, are controlled on a per-channel basis and the route address inserted is always the local system.
IMTA normally rewrites addresses as it enqueues messages to its channel queues. No additional rewriting is done during message dequeue. This presents a potential problem when host names change while there are messages in the channel queues still addressed to the old name.
|
|
The connectalias keyword tells IMTA to deliver to whatever host is listed in the recipient address. This is the default. The keyword connectcanonical forces IMTA to run the address through the rewrite rules one additional time and use the resulting host. |
Three keywords are used to specify whether a channel is served by a master program (master), a slave program (slave), or both (bidirectional). The default, if none of these keywords are specified, is bidirectional. These keywords determine whether IMTA initiates delivery activity when a message is queued to the channel.
The use of these keywords reflects certain fundamental characteristics of the corresponding channel program or programs. The descriptions of the various channels IMTA supports indicate when and where these keywords should be used.
If a channel is capable of master-mode operations (as specified with the master keyword), such operations may be initiated either by a periodic service job or on demand as delivery is needed:
|
|
immediate, which is the default, specifies that jobs should run on demand for messages of appropriate urgency. |
|
|
periodic inhibits initiation of delivery jobs on demand for the channel it is associated with, regardless of priority. |
| What appropriate urgency means is controlled by the keywords: |
|
|
immurgent enables immediate delivery processing on messages with a priority setting of urgent. Messages with a lower priority must wait for periodic processing. |
|
|
immnormal enables immediate delivery for messages with normal or urgent priority (immnormal is the default keyword with immediate). |
|
|
immnonurgent enables immediate delivery for urgent, normal, and nonurgent messages. |
The default behavior (immediate immnormal) enables immediate processing for all but nonurgent or lower priority messages.
Delivery by periodic service jobs is always possible unless the channel is marked with the slave keyword. Channels capable of master-mode operation are periodically checked for pending messages by periodic service jobs. These jobs run at fixed intervals, usually every four hours, although you can change this interval. On UNIX systems, the interval is determined in the crontab entry for the post job.
Not all channels need service at the same intervals. For example, a channel might see little traffic and be expensive to service. Servicing such a channel at longer intervals than that of a single period between periodic jobs can lower the cost of operation without significantly affecting the quality of service.
In another case, one particular channel may see very heavy traffic and require frequent service, while other channels need servicing much less often. In this situation it may be appropriate to service the heavily used channel more often than any other.
The period keyword can be used to control how often a channel is serviced. This keyword must be followed by an integer value N. The channel is then serviced by every Nth service job. The default value of the period keyword is 1, which means that every periodic service job checks the channel for pending messages.
The urgentblocklimit, normalblocklimit, and nonurgentblocklimit keywords may be used to downgrade the priority of messages based on size. This priority, in turn, may affect whether the message is processed immediately, or whether it is left to wait for processing until the next periodic job runs.
The urgentblocklimit keyword instructs IMTA to downgrade messages larger than the specified size to normal priority. The normalblocklimit keyword instructs IMTA to downgrade messages larger than the specified size to nonurgent priority. The nonurgentblocklimit keyword instructs IMTA to downgrade messages larger than the specified size to lower than nonurgent priority (second class priority), meaning that the messages always wait for the next periodic job for further processing.
SMTP channels maintain a cache containing a history of prior connection attempts. This cache is used to avoid reconnecting multiple times to inaccessible hosts, which can waste time and delay other messages. The cache normally records both connection successes and failures. (Successful connection attempts are recorded to offset subsequent failures; for example, a host that succeeded before but fails now doesn't warrant as long a delay before making another connection attempt as does one that has never been tried or one that has failed previously.)
However, this caching strategy is not necessarily appropriate for all situations. For example, an SMTP router channel that is used to connect to a single unpredictable host does not benefit from caching. Therefore, channel keywords are provided to adjust IMTA's cache.
The cacheeverything keyword enables all forms of caching and is the default. nocache disables all caching. The cachefailures enables caching of connection failures but not successes. Finally, cachesuccesses caches only successful connections. This last keyword is equivalent to nocache for channels.
When periodic delivery jobs are used they normally process all messages queued for the channel. However, on some channels you might want to limit normal periodic job processing to only messages of specified priorities. Other special site-supplied periodic jobs may then process the remaining messages. For instance, a site might choose to have normal IMTA periodic jobs pass over nonurgent messages, leaving the nonurgent messages to be delivered by a site-supplied job (perhaps scheduled to run at off-peak hours).
The minperiodicnonurgent, minperiodicnormal, or minperiodicurgent keywords specify the minimum priority of message that a periodic job should try to deliver; the job will ignore messages of lower priority.
The maxperiodicnonurgent, maxperiodicnormal, or maxperiodicurgent keywords specify the maximum priority of message that a periodic job should try to deliver; the job will ignore messages of higher priority.
When a message is enqueued to a channel the job controller normally starts one master process per channel. If the channel is processed on a periodic basis, one master process per channel is started.
A single master process might not be sufficient to ensure prompt delivery of all messages. In particular, fax messages may take a long time to deliver; if multiple fax modems are available, it is not efficient to use a single process and a single modem.
The addrsperjob and filesperjob keywords can be used to create additional master processes. Each of these keywords take a single positive integer parameter which specifies how many addresses or queue entries (files) must be sent to the associated channel before more than one master process is created to handle them. If a value less than or equal to zero is given, it is interpreted as a request to queue only one service job. Not specifying a keyword defaults to a value of 0. The effect of these keywords is maximized; the larger number computed is the number of service jobs that are actually created.
The addrsperjob keyword computes the number of service jobs to start by dividing the total number of To: addressees in all entries by the given value. The filesperjob keyword divides the number of actual queue entries or files by the given value. The number of queue entries resulting from a given message is controlled by a large number of factors, including but not limited to the use of the single and single_sys keywords and the specification of header modifying actions in mailing lists.
The maxjobs keyword places an upper limit on the total number of service jobs that can be created. This keyword must be followed by an integer value; if the computed number of service jobs is greater than this value, only maxjobs processes are actually created. If maxjobs is not specified, the default for this value is 100. Normally maxjobs is set to a value that is less than or equal to the total number of jobs that can run simultaneously in whatever service queue or queues the channel uses.
For example, if a message with four recipient addresses is queued to a channel marked addrsperjob 2 and maxjobs 5, a total of two service jobs are created. But if a message with 23 recipient addresses is queued to the same channel, only five jobs are created because of the maxjobs restriction.
Note - These keywords affect the creation of both periodic and immediate service jobs. In the case of periodic jobs, the number of jobs created is calculated from the total number of messages in the channel queue. In the case of immediate service jobs, the calculation is based only on the message being entered into the queue at the time.
The addrsperjob keyword is generally useful only on channels that provide per-address service granularity. Currently this is limited to fax channels.
The IMTA allows multiple destination addresses to appear in each queued message. Some channel programs may only be able to process messages with one recipient, or with a limited number of recipients, or with a single destination system per message copy. For example, the SMTP channels master program establishes a connection only to a single remote host in a given transaction, so only addresses to that host can be processed (this, despite the fact, that a single channel is typically used for all SMTP traffic).
Another example is that some SMTP servers may impose a limit on the number of recipients they can handle at one time, and they may not be able to handle this type of error.
The keywords multiple, addrsperfile, single, and single_sys can be used to control how multiple addresses are handled. The keyword single means that a separate copy of the message should be created for each destination address on the channel. The keyword single_sys creates a single copy of the message for each destination system used.The keyword multiple, the default, creates a single copy of the message for the entire channel.
Note - At least one copy of each message is created for each channel the message is queued to, regardless of the keywords used.
The addrsperfile keyword is used to put a limit on the maximum number of recipients that can be associated with a single message file in a channel queue, thus limiting the number of recipients that are processed in a single operation. This keyword requires a single-integer argument specifying the maximum number of recipient addresses allowed in a message file; if this number is reached, IMTA automatically creates additional message files to accommodate them. (The default multiple keyword corresponds to imposing no limit on the number of recipients in a message file.)
Most channels support the specification of multiple recipient addresses in the transfer of each inbound message. The specification of many recipient addresses in a single message may result in delays in message transfer processing ("online" delays). If the delays are long enough, network timeouts can occur, which in turn can lead to repeated message submission attempts and other problems.
IMTA provides a special facility to force deferred ("offline") processing if more than a given number of addresses are specified for a single message. Deferral of message processing can decrease online delays enormously. Note, however, that the processing overhead is only deferred, not avoided completely.
This special facility is activated by using a combination of the generic reprocessing channel and the expandlimit keyword. The expandlimit keyword takes an integer argument that specifies how many addresses should be accepted in messages coming from the channel before deferring processing. The default value is infinite if the expandlimit keyword is not specified. A value of 0 forces deferred processing on all incoming addresses from the channel.
The expandlimit keyword must not be specified on the local channel or the reprocessing channel itself; the results of such a specification are unpredictable. The reprocessing channel is used to perform the deferred processing and must be added to the configuration file in order for the expandlimit keyword to have any effect. If your configuration was built by the IMTA configuration utility, then you should already have such a channel.
By default, all messages queued to a channel are stored as files in the directory
/imta/queue/channel-name, where channel-name is the name of the channel. However, a channel that handles a large number of messages and tends to build up a large store of message files waiting for processing, for example, a TCP/IP channel, may get better performance out of the file system if those message files are spread across a number of subdirectories. The subdirs channel keyword provides this capability: it should be followed by an integer that specifies the number of subdirectories across which to spread messages for the channel, for example, tcp_local single_sys smtp subdirs 10.
IMTA creates service jobs (channel master programs) to deliver messages. The job controller, which launches these jobs, associates them with queues. Queue types are defined in the job_controller.cnf file. The queue type with which each channel's master program is associated can be selected on a channel-by-channel basis, using the queue keyword. The queue keyword must be followed by the name of the queue type to which delivery jobs for the current channel should be queued. The name of the queue type should not contain more than 12 characters. If the queue keyword is omitted, then the queue used is the default queue, the first queue listed in the job controller configuration file.
The deferred channel keyword implements recognition and honoring of the Deferred-delivery: header. Messages with a deferred delivery date in the future are held in the channel queue until they either expire and are returned or the deferred delivery date is reached. See RFC 1327 for details on the format and operation of the Deferred-delivery: header.
The keyword nodeferred is the default. It is important to realize that while support for deferred message processing is mandated by RFC 1327, actual implementing of it effectively lets people use the mail system as an extension of their disk quota.
The notices keyword controls the amount of time an undeliverable message is silently retained in a given channel queue. IMTA is capable of returning a series of warning messages to the originator and, if the message remains undeliverable, IMTA eventually returns the entire message.
The keyword is followed by a list of up to five monotonically increasing integer values. These values refer to the message ages at which warning messages are sent. The ages have units of days if the RETURN_UNITS option is 0 or not specified in the option file; or hours if the RETURN_UNITS option is 1. When an undeliverable message attains or exceeds the last listed age, it is returned (bounced).
When a message attains any of the other ages, a warning notice is sent. The default if no notices keyword is given is to use the notices setting for the local channel. If no setting has been made for the local channel, then the defaults 3, 6, 9, 12 are used, meaning that warning messages are sent when the message attains the ages 3, 6, and 9 days (or hours) and the message is returned after remaining in the channel queue for more than 12 days (or hours).
Note - The syntax for the notices keyword uses no punctuation. For example, the default return policy is expressed as: notices 3 6 9 12.
The following line specifies that if messages are enqueued to the tcp_local channel and deferred for later reprocessing, transient failure delivery status notifications will be generated after 1 and 2 days. If the message is still not delivered after 5 days, it will be returned to its originator.
The defaults channel appears immediately after the first blank line in the configuration file, usually /imta/table/imta.cnf. It is important that a blank line appear before and after the line defaults notices....
A channel program may be unable to deliver a message because of long-term service failures or invalid addresses. When this failure occurs, the IMTA 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 lots of traffic for the postmaster to deal with.
The keywords sendpost, copysendpost, errsendpost, and nosendpost control the sending of failed messages to the postmaster. The keyword sendpost tells IMTA to send a copy of all failed messages to the postmaster unconditionally. copysendpost instructs IMTA to send a copy of the failure notice to the postmaster unless the originator address on the failing message is blank, in which case, the postmaster gets copies of all failed messages except those messages that are actually themselves bounces or notifications.
The keyword errsendpost instructs IMTA to send a copy of the failure notice only to the postmaster when the notice cannot be returned to the originator. No failed messages are ever sent to the postmaster if nosendpost is specified. The default, if none of these keywords is specified, is to send a copy of failed mail messages to the postmaster, unless error returns are completely suppressed with a blank Errors-to: header or a blank envelope From: address.This default behavior does not correspond to any of the keyword settings.
In addition to returning messages, IMTA sometimes sends warnings detailing messages that it has been unable to deliver. This is generally due to timeouts 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 will 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 is 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.
|
|
warnpost-Tells IMTA to send a copy of all warning messages to the postmaster unconditionally. |
|
|
copywarnpost-Instructs IMTA to send a copy of the warning to the postmaster, unless the originator address on the undelivered message is blank. |
| In this case, the postmaster gets copies of all warnings of undelivered messages except for undelivered messages that are actually themselves bounces or notifications. |
|
|
errwarnpost-Instructs IMTA to send only a copy of the warning to the postmaster when the notice cannot be returned to the originator. |
No warning messages are ever sent to the postmaster if nowarnpost is specified. The default, if none of these keywords is specified, is to send a copy of warnings to the postmaster unless warnings are completely suppressed with a blank Warnings-to: header or a blank envelope From: address. This default behavior does not correspond to any of the keyword settings.
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.
The keywords postheadonly and postheadbody are used to control what gets sent to the postmaster. The keyword postheadbody returns both the headers and the contents of the message. It is the default.The keyword postheadonly causes only the headers to be sent to the postmaster.
When IMTA 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 IMTA. IMTA 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 IMTA also includes the final form of the address. Suppressing the inclusion of the final form of 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 notification messages. includefinal is the default and includes the final form of the recipient address. suppressfinal causes IMTA to suppress the final address form, if an original address form is present, from notification messages.
The multithreaded SMTP client sorts outgoing messages to different destinations to different threads. The threaddepth keyword may be used to instruct IMTA's multithreaded SMTP client to handle only the specified number of messages in any one thread, using additional threads even for messages all to the same destination (hence normally all handled in one thread).
These options specify whether or not a channel supports the SMTP protocol and what type of SMTP line terminator IMTA expects to see as part of that protocol. The keyword nosmtp means that the channel doesn't support SMTP; all the rest of these keywords imply SMTP support.
The selection of whether or not to use the SMTP protocol is implicit for most channels; the correct protocol is chosen by the use of the appropriate channel program or programs. Some gateway systems use the Simple Mail Transfer Protocol (SMTP) described in RFC 821 as a message envelope, while others might not use an envelope format. The result is that all envelope information is derived from the RFC 822 message header, which is present in all cases. The smtp keyword is used to tell the channel master programs to put a batch SMTP header on the message. The nosmtp keyword inhibits the generation of the batch SMTP header. The nosmtp is the default.
The keyword smtp is mandatory for all SMTP channels. The keywords smtp_cr, smtp_crlf, and smtp_lf can be used on SMTP channels to specify the character sequences to accept as line terminators. The keyword smtp_crlf means that lines must be terminated with a carriage return (CR) line feed (LF) sequence. The keyword smtp_lf or smtp means that an LF without a preceding CR is accepted. Finally, smtp_cr means that a CR is accepted without a following LF. It is normal to use CRLF sequences as the SMTP line terminator, and this is what IMTA always generates; this option affects only the handling of incoming material.
The SMTP protocol has recently been extended (RFC 1651) to allow for negotiation of additional commands. This is done using the new EHLO command, which replaces RFC 821's HELO command. Extended SMTP servers respond to EHLO by providing a list of the extensions they support. Unextended servers return an unknown command error, and the client then sends the old HELO command instead.
This fallback strategy normally works well with both extended and unextended servers. Problems can arise, however, with servers that do not implement SMTP according to RFC 821. In particular, some noncompliant servers are known to drop the connection on receipt of an unknown command.
The SMTP client implements a strategy whereby it attempts to reconnect and use HELO when any server drops the connection on receipt of an EHLO. However, this strategy may not work if the remote server not only drops the connection but also goes into a problematic state upon receipt of EHLO.
The channel keywords ehlo, noehlo, and checkehlo are provided to deal with such situations. EHLO tells IMTA to use the ehlo command on all initial connection attempts. The keyword noehlo disables all use of the EHLO command. The keyword checkehlo tests the response banner returned by the remote SMTP server for the string "ESMTP." If this string is found, EHLO is used; if not, HELO is used. The default behavior is to use EHLO on all initial connection attempts, unless the banner line contains the string "fire away," in which case HELO is used.
Note - There is no keyword corresponding to this default behavior, which lies between the behaviors resulting from the ehlo and checkehlo keywords.
The allowetrn, blocketrn, domainetrn, and silentetrn keywords control the IMTA response when a sending SMTP client issues the SMTP ETRN command, requesting that the IMTA attempt to deliver messages in the IMTA queues. allowetrn is the default; the IMTA will attempt to honor all ETRN commands. silentetrn tells the IMTA to honor all ETRN commands, but without echoing the name of the channel that the domain matched and that the IMTA will be attempting to run. blocketrn tells the IMTA not to honor ETRN commands. domainetrn tells the IMTA to honor only ETRN commands that specify a domain; it also causes the IMTA not to echo back the name of the channel that the domain matched and that the IMTA will be attempting to run.
The extended SMTP command ETRN (RFC 1985) allows an SMTP client to request that a remote SMTP server start up processing of the remote side's message queues destined for sending to the original SMTP client; that is, it allows an SMTP client and SMTP server to negotiate "switching roles", where the side originally the sender becomes the receiver, and the side originally the receiver becomes the sender. In other words, ETRN provides a way to implement "polling" of remote SMTP systems for messages incoming to one's own system. This can be useful for systems that have only transient connections between each other, for example, over dial-up lines. When the connection is brought up and one side sends to the other, using the ETRN command, the SMTP client can also tell the remote side that it should now try to deliver any messages that needs to travel in the reverse direction.
The SMTP client specifies on the SMTP ETRN command line the name of the system to which to send messages (generally the SMTP client system's own name). If the remote SMTP server supports the ETRN command, it will trigger execution of a separate process to connect back to the named system and send any messages awaiting delivery for that named system.
The sendetrn and nosendetrn channel keywords control whether the IMTA SMTP client sends an ETRN command at the beginning of an SMTP connection. The default is nosendetrn, meaning that the IMTA will not send an ETRN command. The sendetrn keyword tells the IMTA to send an ETRN command, if the remote SMTP server says it supports ETRN. The sendetrn keyword should be followed by the name of the system requesting that its messages receive a delivery attempt.
These keywords control IMTA's use of the VRFY command in its SMTP client. Under normal circumstances there is no reason to issue a VRFY command as part of an SMTP dialogue. The SMTP MAIL TO command should perform the same function that VRFY does and return an appropriate error. However, servers exist that can accept any address in a MAIL TO (and bounce it later), whereas these same servers perform more extensive checking as part of a VRFY command.
The IMTA can be configured to issue SMTP VRFY commands. The keyword domainvrfy causes a VRFY command to be issued with a full address (user@host) as its argument. The localvrfy keyword causes IMTA to issue a VRFY command with just the local part of the address (user). novrfy is the default.
These keywords control the IMTA SMTP server's response when a sending SMTP client issues an SMTP VRFY command. The vrfyallow keyword tells IMTA to issue a detailed, informative response. The vrfydefault tells IMTA to provide a detailed, informative response, unless the channel option HIDE_VERIFY=1 has been specified. The vrfyhide keyword tells IMTA to issue only a vague, ambiguous response. These keywords allow per-channel control of VRFY responses, as opposed to the HIDE_VERIFY option, which normally applies to all incoming TCP/IP channels handled through the same SMTP server.
The SMTP over TCP/IP channels normally connects to port 25 when sending messages. The port keyword can be used to instruct an SMTP over TCP/IP channel to connect to a nonstandard port.
Some TCP/IP networks support the use of MX (mail forwarding) records and some do not. Some TCP/IP channel programs can be configured not to use MX records if they are not provided by the network that the IMTA system is connected to. The keyword randommx specifies that MX lookups should be done and MX record values of equal precedence should be processed in random order. The keyword nonrandommx specifies that MX lookups should be done and MX values of equal precedence should be processed in the same order in which they were received.
The mx keyword is currently equivalent to nonrandommx; it might change to be equivalent to randommx in a future release. The nomx keyword disables MX lookups. The defaultmx keyword specifies that mx should be used if the network says that MX records are supported. The keyword defaultmx is the default on channels that support MX lookups in any form.
The lastresort keyword is used to specify a host to connect even when all other connection attempts fail. In effect this acts as an MX record of last resort. This is only useful on SMTP channels.
The identtcp keyword tells the IMTA to perform a connection and lookup using the IDENT protocol (RFC 1413). The information obtained from the IDENT protocol (usually the identity of the user making the SMTP connection) is then inserted into the Received: header of the message, with the host name corresponding to the incoming IP number, as reported from a DNS reverse lookup and the IP number itself.
The identtcpsymbolic keyword tells the IMTA to perform a connection and lookup using the IDENT protocol (RFC 1413). The information obtained from the IDENT protocol (usually the identity of the user making the SMTP connection) is then inserted into the Received: header of the message, with the actual incoming IP number, as reported from a DNS reverse lookup; the IP number itself is not included in the Received: header.
The identtcpnumeric keyword tells the IMTA to perform a connection and lookup using the IDENT protocol (RFC 1413). The information obtained from the IDENT protocol (usually the identity of the user making the SMTP connection) is then inserted into the Received: header of the message, with the actual incoming IP number --- no DNS reverse lookup on the IP number is performed.
Note - The remote system must be running an IDENT server for the IDENT lookup caused by identtcp or identtcpnumeric to be useful.
Be aware that IDENT query attempts may incur a performance hit. Increasingly routers will "black hole" attempted connections to ports that they don't recognize; if this happens on an IDENT query, then the IMTA does not hear back until the connection times out (a TCP/IP package controlled time-out, typically on the order of a minute or two).
A lesser performance factor occurs when comparing identtcp or identtcpsymbolic to identtcpnumeric. The DNS reverse lookup called for with identtcp or identtcpsymbolic incurs some additional overhead to obtain the more user-friendly host name.
The identnone keyword disables this IDENT lookup, but does do IP to host name translation, and both IP number and host name will be included in the Received: header for the message. The identnonesymbolic keyword disables this IDENT lookup, but does do IP to host name translation; only the host name will be included in the Received: header for the message. The identnonenumeric keyword disables this IDENT lookup and inhibits the usual DNS reverse lookup translation of IP number to host name, and might result in a performance improvement at the cost of less user-friendly information in the Received: header. identnone is the default.
The identtcplimited and identnonelimited keywords have the same effect as identtcp and identnone, respectively, as far as IDENT lookups, reverse DNS lookups, and information displayed in Received: header. Where they differ is that with identtcplimited or identnonelimited the IP literal address is always used as the basis for any channel switching due to use of the switchchannel keyword, regardless of whether the DNS reverse lookup succeeds in determining a host name.
The forwardchecknone, forwardchecktag, and forwardcheckdelete channel keywords can modify the effects of doing reverse lookups, controlling whether the IMTA does a forward lookup of an IP name found using a DNS reverse lookup, and if such forward lookups are requested what the IMTA does if the forward lookup of the IP name does not match the original IP number of the connection. The forwardchecknone keyword is the default, and means that no forward lookup is done. The forwardchecktag keyword tells the IMTA to do a forward lookup after each reverse lookup and to tag the IP name with an asterisk, *, if the number found using the forward lookup does not match that of the original connection. The forwardcheckdelete keyword tells the IMTA to do a forward lookup after each reverse lookup and to ignore (delete) the reverse lookup returned name if the forward lookup of that name does not match the original connection IP address. Use the original IP address instead.
Note - Having the forward lookup not match the original IP address is normal at many sites, where a more "generic" IP name is used for several different IP addresses.
These keywords are only useful on SMTP channels that run over TCP/IP.
When an IMTA server accepts an incoming connection from a remote system, it must choose a channel with which to associate the connection. Normally this decision is based on the transfer used; for example, an incoming TCP/IP connection is automatically associated with the tcp_local channel.
This convention breaks down, however, when multiple outgoing channels with different characteristics are used to handle different systems over the same transfer. When this happens, incoming connections are not associated with the same channel as outgoing connections, and the result is that the corresponding channel characteristics are not associated with the remote system.
The switchchannel keyword provides a way to eliminate this difficulty. If switchchannel is specified on the server's initial channel (tcp_local), the name of the originating host is matched against the channel table; if it matches, the source channel changes accordingly. The source channel may change to any channel marked switchchannel or allowswitchchannel (the default). The keyword noswitchchannel specifies that no channel switching should be done to or from the channel.
Specification of switchchannel on anything other than a channel that a server associates with by default has no effect. At present, switchchannel only affects SMTP channels, but there are actually no other channels where switchchannel would be reasonable.
Note - When the switchchannel is specified, the name of the originating host is obtained by a DNS reverse lookup translation of the IP address to host name. Consequently, this keyword is useful for setting up anti-spamming, but it may affect performance.
The IMTA often receives from misconfigured or incompliant mailers and SMTP clients addresses that do not contain a domain name. IMTA attempts to make such addresses legal before allowing them to pass further. IMTA does this by appending a domain name to the address (for example, appends @stream.com to mrochek). In the case of the SMTP server, however, the two logical choices for the domain name are:
|
|
Local host name |
|
|
Remote host name reported by the client SMTP |
Either of these two choices is likely to be correct, as both may occur operationally with some frequency. The use of the remote host's domain name is appropriate when dealing with improperly configured SMTP clients. The use of the local host's domain name is appropriate when dealing with a lightweight remote mail client such as a POP or IMAP client that uses SMTP to post messages.
The best that IMTA can do is to allow the choice to be made on a channel-by-channel basis. The remotehost channel keyword specifies that the remote host's name should be used. The noremotehost channel keyword specifies that the local host's name should be used. The keyword noremotehost is the default.
The switchchannel keyword as described, in the preceding section, Selecting an Alternate Channel for Incoming Mail (switchchannel, allowswitchchannel, noswitchchannel)" can be used to associate incoming SMTP connections with a particular channel. This facility can be used to group remote mail clients on a channel where they can receive proper treatment. Alternatively, it is simpler to deploy standards-compliant remote mail clients (even if a multitude of noncompliant clients are in use) rather than attempting to fix the network-wide problem on your IMTA hosts.
RFC 822 (Internet) messages are required to contain a recipient header: a To:, Cc:, or Bcc: header. A message without such a header is illegal. Nevertheless, some broken user agents and mailers (for example, many older versions of sendmail) will allow illegal messages.
The missingrecipientpolicy keyword takes an integer value specifying the approach to use for such messages; the default value, if the keyword is not explicitly present, is 0, meaning that envelope To: addresses are placed in a To: header.
Note that the MISSING_RECIPIENT_POLICY option can be used to set an IMTA system default for this behavior.
Some transfers restrict the use of characters with ordinal values greater than 127 (decimal). Most notably, some SMTP servers strip the high bit and thus garble messages that use characters in this eight-bit range. IMTA provides facilities to automatically encode such messages so that troublesome eight-bit characters do not appear directly in the message. This encoding can be applied to all messages on a given channel by specifying the sevenbit keyword. A channel should be marked eightbit if no such restriction exists.
Some transfers, such as extended SMTP, may actually support a form of negotiation to determine if eight-bit characters can be transmitted. The eightnegotiate keyword can be used to instruct the channel to encode messages when negotiation fails. This is the default for all channels; channels that do not support negotiation assume that the transfer is capable of handling eight-bit data. The eightstrict keyword tells IMTA to reject any messages that contain unnegotiated eight-bit data.
The MIME specification provides a mechanism to label the character set used in a plain text message. Specifically, a charset= parameter can be specified as part of the Content-type: header line. Various character set names are defined in MIME, including US-ASCII (the default), ISO-8859-1, ISO-8859-2, and so on.
Some existing systems and user agents do not provide a mechanism for generating these character set labels; as a result, some plain text messages may not be properly labeled. The charset7 and charset8 channel keywords provide a per-channel mechanism to specify character set names to be inserted into message headers. Each keyword requires a single argument giving the character set name. The names are not checked for validity.
Note - Character set conversion can be done only on character sets specified in the character set definition file charsets.txt found in the IMTA table directory,
/imta/table/charsets.txt. Use the names defined in this file, if possible.
The charset7 character set name is used if the message contains only seven-bit characters; charset8 is used if eight-bit data is found in the message. If the appropriate keyword is not specified, no character set name is inserted into the Content-type: header lines.
These character set specifications never override existing labels; that is, they have no effect if a message already has a character set label or is of a type other than text. It is usually appropriate to label IMTA local channels as follows:
If there is no Content-type header in the message, it is added. This keyword also adds the MIME-version: header if it is missing.
The SMTP specification allows for lines of text containing up to 1000 bytes. However, some transfers may impose more severe restrictions on line length. The linelength keyword provides a mechanism for limiting the maximum permissible message line length on a channel-by-channel basis. Messages queued to a given channel with lines longer than the limit specified for that channel are automatically encoded.
The various encodings available in the IMTA always result in a reduction of line length to fewer than 80 characters. The original message may be recovered after such encoding is done by applying an appropriating decoding filter.
Note - Encoding can only reduce line lengths to fewer than 80 characters. Specification of line length values less than 80 may not actually produce lines with lengths that comply with the stated restriction.
The reverse keyword tells IMTA that addresses in messages queued to the channel should be checked against, and possibly modified, by the address reversal database or REVERSE mapping, if either exists. noreverse exempts addresses in messages queued to the channel from address reversal processing. The reverse keyword is the default.
The contents of header lines are interpreted only when necessary. However, MIME messages can contain multiple sets of message headers as a result of the ability to imbed messages within messages (message/RFC822). IMTA normally only interprets and rewrites the outermost set of message headers. IMTA can optionally be told to apply header rewriting to inner headers within the message as well.
This behavior is controlled by the use of the noinner and inner keywords. The keyword noinner tells IMTA not to rewrite inner message header lines. It is the default. The keyword inner tells IMTA to parse messages and rewrite inner headers. These keywords can be applied to any channel.
Some mail systems have difficulty dealing with the full spectrum of addresses allowed by RFC 822. A particularly common example of this is sendmail-based mailers with incorrect configuration files. Quoted local-parts (or mailbox specifications) are a frequent source of trouble:
"smith, ned"@xyz.com
This is such a major source of difficulty that a methodology was laid out in RFC 1137 to work around the problem. The basic approach is to remove quoting from the address, then apply a translation that maps the characters requiring quoting into characters allowed in an atom (see RFC 822 for a definition of an atom as it is used here). For example, the preceding address would become:
smith#m#_ned@xyz.com
The restricted channel keyword tells IMTA that the channel connects to mail systems that require this encoding. IMTA then encodes quoted local-parts in both header and envelope addresses as messages are written to the channel. Incoming addresses on the channel are decoded automatically. The unrestricted keyword tells IMTA not to perform RFC 1137 encoding and decoding. The keyword unrestricted is the default.
Note - The restricted keyword should be applied to the channel that connects to systems unable to accept quoted local-parts. It should not be applied to the channels that actually generate the quoted local-parts. (It is assumed that a channel capable of generating such an address is also capable of handling such an address.)
The IMTA provides per-channel facilities for trimming or removing selected message header lines from messages. This is done through a combination of a channel keyword and an associated header option file or two. The headertrim keyword instructs the IMTA to consult a header option file associated with the channel and to trim the headers on messages queued to the channel accordingly, after the messages are processed. The noheadertrim keyword bypasses header trimming. The keyword noheadertrim is the default.
The innertrim keyword instructs the IMTA to perform header trimming on inner message parts, for example, embedded MESSAGE/RFC822 parts. The noinnertrim keyword, which is the default, tells the IMTA not to perform any header trimming on inner message parts.
The headerread keyword instructs the IMTA to consult a header option file associated with the channel and to trim the headers on messages queued to the channel accordingly, before the messages are processed. Note that headertrim header trimming, on the other hand, is applied after the messages have been processed. The noheaderread keyword bypasses message enqueue header trimming. noheaderread is the default.
Caution - Stripping away vital header information from messages may cause improper operation of the IMTA. Be extremely careful when selecting headers to remove or limit. This facility exists because there are occasional situations where selected header lines must be removed or otherwise limited. Before trimming or removing any header line, be sure that you understand the usage of that header line and have considered the possible implications of its removal.
Header options files for the headertrim and innertrim keywords have names of the form channel_headers.opt with channel, the name of the channel with which the header option file is associated. Similarly, header options files for the headerread keyword have names of the form channel_read_headers.opt. These files are stored in the IMTA configuration directory, /etc/opt/SUNWmail/imta/.
IMTA can convert various nonstandard message formats to MIME using the Yes CHARSET-CONVERSION. In particular, the RFC 1154 format uses a nonstandard Encoding: header. However, some gateways emit incorrect information on this header line, with the result that sometimes it is desirable to ignore this header. The ignoreencoding keyword instructs the IMTA to ignore any Encoding: header.
Note - Unless the IMTA has a CHARSET-CONVERSION enabled, such headers are ignored in any case. The interpretencoding keyword instructs the IMTA to pay attention to any Encoding: header, if otherwise configured to do so, and is the default.
The x_env_to and nox_env_to keywords control the generation or suppression of X-Envelope-to header lines on copies of messages queued to a specific channel. The x_env_to keyword enables generation of these headers while the nox_env_to will remove such headers from enqueued messages. The default is nox_env_to.
The receivedfor keyword instructs the IMTA that if a message is addressed to just one envelope recipient, to include that envelope to the address in the Received: header it constructs. The keyword receivedfor is the default. The noreceivedfor keyword instructs the IMTA to construct Received headers without including any envelope addressee information.
The receivedfrom keyword instructs the IMTA to include the original envelope From: address when constructing a Received: header for an incoming message if the IMTA has changed the envelope From: address due to, for example, certain sorts of mailing list expansions. receivedfrom is the default. The noreceivedfrom keyword instructs the IMTA to construct Received: headers without including the original envelope From: address.
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 IMTA are written with a blank envelope address or with the address of the local postmaster. Setting the bit forces the use of the local postmaster address; clearing the bit forces the use of a blank address.
Note - The use of a blank address is mandated by RFC 1123. However, some systems do not properly handle blank envelopes From: address and may require the use of this option.
Bit 1 (value = 2) controls whether or not IMTA replaces all blank envelope addresses with the address of the local postmaster. This is used to accommodate incompliant systems that don't conform to RFC 821, RFC 822, or RFC 1123.
The usereplyto keyword controls the mapping of the Reply-to header. The default is usereplyto 0, which means to use the channel default behavior, which varies from channel to channel. TABLE 2-12 indicates the mapping specifications for the Reply-to: header.
The useresent keyword controls the use of Resent- headers when using a gateway to environments that do not support RFC 822 headers. This keyword takes a single integer-valued argument. TABLE 2-13 lists the values used for mapping the Resent- headers.
IMTA interprets the contents of header lines only when necessary. However, all registered headers containing addresses must be parsed to rewrite and eliminate short form addresses and otherwise convert them to legal addresses. During this process, comments (strings enclosed in parentheses) are extracted and may be modified or excluded when the header line is rebuilt.
This behavior is controlled by the use of the commentinc, commentomit, commentstrip, and commenttotal keywords. The commentinc keyword tells IMTA to retain comments in header lines. It is the default. The keyword commentomit tells IMTA to remove any comments from addressing headers, for example, To, From, or Cc headers.
The keyword commenttotal tells IMTA to remove any comments from all headers, including Received: headers; this keyword is not normally useful or recommended. commentstrip tells IMTA to strip any nonatomic characters from all comment fields. These keywords can be applied to any channel.
During the rewriting process, all registered headers containing addresses must be parsed in order to rewrite and eliminate short form addresses and otherwise convert them to legal addresses. During this process personal names (strings preceding angle-bracket-delimited addresses) are extracted and can be optionally modified or excluded when the header line is rebuilt.
This behavior is controlled by the use of the personalinc, personalomit, and personalstrip keywords. The keyword personalinc tells IMTA to retain personal names in the headers. It is the default. The keyword personalomit tells IMTA to remove all personal names.The keyword personalstrip tells IMTA to strip any nonatomic characters from all personal name fields. These keywords can be applied to any channel.
The original RFC 822 specification called for two-digit years in the date fields in message headers. This was later changed to four digits by RFC 1123. However, some older mail systems cannot accommodate four-digit dates. In addition, some newer mail systems can no longer tolerate two-digit dates.
Note - Systems that cannot handle both formats are in violation of the standards.
The datefour and datetwo keywords control IMTA's processing of the year field in message header dates. The keyword datefour, the default, instructs IMTA to expand all year fields to four digits. Two- digit dates with a value less than 50 have 2000 added, while values greater than 50 have 1900 added.
Caution - The keyword datetwo instructs IMTA to remove the leading two digits from four-digit dates. This is intended to provide compatibility with incompliant mail systems that require two digit dates; it should never be used for any other purpose.
The RFC 822 specification allows for a leading day of the week specification in the date fields in message headers. However, some systems cannot accommodate day of the week information. This makes some systems reluctant to include this information, even though it is quite useful information to have in the headers.
The dayofweek and nodayofweek keywords control IMTA's processing of day of the week information. The keyword dayofweek, the default, instructs IMTA to retain any day of the week information and to add this information to date/time headers if it is missing.
Caution - The keyword nodayofweek instructs IMTA to remove any leading day of the week information from date/time headers. This is intended to provide compatibility with incompliant mail systems that cannot process this information properly; it should never be used for any other purpose.
Some message transfers, notably some sendmail implementations, cannot process long header lines properly. This often leads not just to damaged headers but to erroneous message rejection. Although this is a gross violation of standards, it is nevertheless a common problem.
IMTA provides per-channel facilities to split (break) long header lines into multiple, independent header lines. The maxheaderaddrs keyword controls how many addresses can appear on a single line. The maxheaderchars keyword controls how many characters can appear on a single line. Both keywords require a single integer parameter that specifies the associated limit. By default, no limit is imposed on the length of a header line nor on the number of addresses that can appear.
The headerlabelalign keyword controls the alignment point for message headers enqueued on this channel; it takes an integer-valued argument. The alignment point is the margin where the contents of headers are aligned. For example, sample headers with an alignment point of 10 might look like this:
To: joe@stream.com
From: mary@stream.com
Subject: Alignment testThe default headerlabelalign is 0, which causes headers not to be aligned. The headerlinelength keyword controls the length of message header lines enqueued on this channel. Lines longer than this are folded in accordance with RFC 822 folding rules.
These keywords only control the format of the headers of the message in the message queue; the actual display of headers is normally controlled by the user agent. In addition, headers are routinely reformatted as they are transferred across the Internet, so these keywords may have no visible effect even when used in conjunction with simple user agents that do not reformat message headers.
The MIME standard provides the message/partial content type for breaking up messages into smaller parts. This is useful when messages have to traverse networks with size limits. Information is included in each part so that the message can be automatically reassembled after it arrives at its destination.
The defragment channel keyword and the defragmentation channel provide the means to reassemble messages in IMTA. When a channel is marked defragment, any message or partial messages queued to the channel are placed in the defragmentation channel queue instead. After all the parts have arrived, the message is rebuilt and sent on its way. The nodefragment disables this special processing. The keyword nodefragment is the default.
A defragment channel must be added to the IMTA configuration file in order for the defragment keyword to have any effect. If your configuration was built by the IMTA configuration utility, then you should already have such a channel.
Some email systems or network transfers cannot handle messages that exceed certain size limits. IMTA provides facilities to impose such limits on a channel-by-channel basis. Messages larger than the set limits are automatically split (fragmented) into multiple, smaller messages. The Content-type: used for such fragments is message/partial, and a unique ID parameter is added so that parts of the same message can be associated with one another and, possibly, be automatically reassembled by the receiving mailer.
The maxblocks and maxlines keywords are used to impose size limits beyond which automatic fragmentation are activated. Both of these keywords must be followed by a single integer value. The keyword maxblocks specifies the maximum number of blocks allowed in a message. An IMTA block is normally 1024 bytes; this can be changed with the BLOCK_SIZE option in the IMTA option file. The keyword maxlines specifies the maximum number of lines allowed in a message. These two limits can be imposed simultaneously if necessary.
Message headers are, to a certain extent, included in the size of a message. Because message headers cannot be split into multiple messages, and yet they themselves can exceed the specified size limits, a rather complex mechanism is used to account for message header sizes. This logic is controlled by the MAX_HEADER_BLOCK_USE and MAX_HEADER_LINE_USE options in the IMTA option file.
MAX_HEADER_BLOCK_USE is used to specify a real number between 0 and 1. The default value is 0.5. A message's header is allowed to occupy this much of the total number of blocks a message can consume (specified by the maxblocks keyword). If the message header is larger, IMTA takes the product of MAX_HEADER_BLOCK_USE and maxblocks as the size of the header (the header size is taken to be the smaller of the actual header size and maxblocks) * MAX_HEADER_BLOCK_USE.
For example, if maxblocks is 10 and MAX_HEADER_BLOCK_USE is the default, 0.5, any message header larger than 5 blocks is treated as a 5-block header, and if the message is 5 or fewer blocks in size it is not fragmented. A value of 0 causes headers to be effectively ignored insofar as message-size limits are concerned.
A value of 1 allows headers to use up all of the size that's available. Each fragment always contains at least one message line, regardless of whether or not the limits are exceeded by this. MAX_HEADER_LINE_USE operates in a similar fashion in conjunction with the maxlines keyword.
Although fragmentation can automatically break messages into smaller pieces, it is appropriate in some cases to reject messages larger than some administratively defined limit, (for example, to avoid service denial attacks). The blocklimit and linelimit keywords are used to impose absolute size limits. Each of these keywords must be followed by a single integer value.
The keyword blocklimit specifies the maximum number of blocks allowed in a message. IMTA rejects attempts to queue messages containing more blocks than this to the channel. An IMTA block is normally 1024 bytes; this can be changed with the BLOCK_SIZE option in the IMTA option file.
The keyword linelimit specifies the maximum number of lines allowed in a message. IMTA rejects attempts to queue messages containing more than this number of lines to the channel. These two, blocklimit and linelimit, can be imposed simultaneously, if necessary.
IMTA options LINE_LIMIT and BLOCK_LIMIT can be used to impose similar limits on all channels. These limits have the advantage that they apply across all channels. Therefore, IMTA servers can make them known to mail clients prior to obtaining message recipient information. This simplifies the process of message rejection in some protocols.
Processing of long header lines containing lots of addresses can consume significant system resources. The maxprocchars keyword is used to specify the maximum length header that IMTA can process and rewrite. Messages with headers longer than this are still accepted and delivered; the only difference is that the long header lines are not rewritten in any way. A single integer argument is required. The default is processing headers of any length.
IMTA provides facilities for logging each message as it is enqueued and dequeued. All log entries are made to the file mail.log_current in the log directory /var/opt/SUNWmail/imta/log/mail.log_current. Logging is controlled on a per-channel basis. The logging keyword activates logging for a particular channel while the nologging keyword disables it.
Some channel programs include optional code to assist in debugging by producing additional diagnostic output. Two channel keywords are provided to enable generation of this debugging output on a per-channel basis. The keywords are master_debug, which enables debugging output in master programs, and slave_debug, which enables debugging output in slave programs. Both types of debugging output are disabled by default, corresponding to nomaster_debug and noslave_debug.
When activated, debugging output ends up in the log file associated with the channel program. The location of the log file may vary from program to program. Log files are usually kept in the IMTA log directory. Master programs usually have log file names of the form x_master.log, where x is the name of the channel; slave programs usually have log file names of the form x_slave.log. Also, some channel programs, notably TCP/IP and fax channel programs, may produce additional log files with names:
|
|
err_x_master.log |
|
|
err_x_slave.log |
|
|
di_x_master.log |
|
|
di_x_xlave.log |
|
|
ph_x_master.log |
|
|
ph_x_slave.log |
In the case of the local channel, master_debug enables debugging output when sending from the local channel, and slave_debug enables debugging output as messages are delivered to the local channel, with output usually appearing in the /var/opt/SUNWmail/imta/log/l_master.log.
Master programs normally process only a subset of the messages queued for the channel. There may be other messages that were queued to the channel at some prior time that will not be processed. However, on some channels, particularly those that only provide a link to a single mail component, this sort of operation may be inappropriate: if the immediate delivery job is successful in connecting to the mail component it may be able to easily process all the messages that are queued.
The serviceall and noserviceall keywords control this behavior. noserviceall, the default, indicates that the master program should only process the messages that were queued to process after its inception. serviceall specifies that the master program should attempt to process all messages queued to the channel each time it runs.
It may be tempting to indulge in use of serviceall on most or all channels. Be warned, however, that use of serviceall is probably not suitable for most channels that connect to multiple remote systems, or channels that entail lots of per-message overhead. If serviceall is used on such channels it may cause a dramatic increase in network and message processing overhead and the net result may be slower message processing overall.
Note that these keywords do not change the order in which message processing occurs. Immediate jobs always attempt to process the messages they were created to process prior to turning to other messages that are also in the channel queue.
The sensitivity checking keywords set an upper limit on the sensitivity of messages that can be accepted by a channel. The default is sensitivitycompanyconfidential; messages of any sensitivity are allowed through. A message with no Sensitivity: header is considered to be of normal, that is, the lowest, sensitivity. Messages with a higher sensitivity than that specified by such a keyword will be rejected when enqueued to the channel with an error message:
message too sensitive for one or more paths usedNote that IMTA does this sort of sensitivity checking at a per-message, not per-recipient, level: if a destination channel for one recipient fails the sensitivity check, then the message bounces for all recipients, not just for those recipients associated with the sensitive channel.
The maysaslserver, mustsaslserver, nosasl, nosaslserver, and saslswitchchannel channel keywords are used to configure SASL (SMTP AUTH) use during the SMTP protocol by SMTP channels such as TCP/IP channels.
nosasl is the default and means that SASL authentication will not be permitted or attempted. It subsumes nosaslserver, which means that SASL authentication will not be permitted. Specifying maysaslserver causes the SMTP server to permit clients to attempt to use SASL authentication. Specifying mustsaslserver causes the SMTP server to insist that clients use SASL authentication; the SMTP server will not accept messages unless the remote client successfully authenticates.
Use saslswitchchannel to cause incoming connections to be switched to a specified channel upon a client's successful use of SASL. It takes a required value, specifying the channel to which to switch.
Setting mailfromdnsverify on an incoming TCP/IP channel causes the IMTA to verify that an entry in the DNS exists for the domain used on the SMTP MAIL FROM: command, and to reject the message if no such entry exists. nomailfromdnsverify is the default and means that no such check is performed.
Note that performing DNS checks on the return address domain may result in rejecting some valid messages (for example, from legitimate sites that have not yet registered their domain name, or at times of bad information in the DNS); it is contrary to the spirit of being generous in what you accept and getting the e-mail through, expressed in RFC 1123, Requirements for Internet Hosts. However, some sites might want to perform such checks in cases where junk email (SPAM) is being sent with forged email addresses from non-existent domains.
The IMTA dirsync program creates in the domain database as well as in a file, /etc/opt/SUNWmail/imta/domains.rules. You can use this file instead of the domain database in case the number of domains is significantly fewer.
Note - Incremental dirsync does not update the domains.rules file. If you use the file instead of the database, the newly added domains would be recognized only after the next full dirsync. Also, if you make any changes to the domains.rules file manually, those changes will be overwritten by imta dirsync.
The IMTA 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. A second set of related facilities provides support for "centralized naming," whereby you establish, for instance, mail addresses of the form first.last@stream.com for all of your users. There are several advantages to such centralized naming systems. The addresses are simple; they provide added security in that they make no reference to internal account or system names; and, because they lack reference to account and system names, they are more stable.
Each time an address that matches the local channel is encountered by the IMTA's message submission logic, the mailbox (for example, username) specified in the address is compared against each entry in the alias database or alias file. If a match occurs the alias address is replaced by the translation value or values specified by the alias. An alias can translate into any combination and number of additional aliases or real addresses. The real addresses need not themselves be associated with the local channel and thus aliases can be used to forward mail to remote systems.
Aliases apply only to addresses mapped to the local channel. Since the only addresses truly considered to match a channel are Envelope To addresses, aliases can apply only to Envelope To addresses. The IMTA performs alias translation and expansion only after address parsing is completed. The translation values produced by an alias are treated as completely new addresses and are reprocessed from scratch.
The IMTA 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. Refer to the SIMS Provisioning Guide for information on what directory attributes are used to create user and distribution list entries in the alias database.
Note - The format of the database itself is private. Do not try to edit the database directly. Make all required changes in the directory.
The alias file 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. The IMTA has to be restarted for any changes to take effect. Any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored.
A physical line in this file is limited to 252 characters. You can split a logical line into multiple physical lines using the backslash (\) continuation character.
The format of the file is as follows:
For example:
Other files can be included in the primary alias file. A line of the following form directs the IMTA to read the file-spec file:
The file specification must be a complete file path specification and the file must have the same protections as the primary alias file; for example, it must be world readable.
The contents of the included file are inserted into the alias 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 alias file itself. Indeed, include files may themselves include other files. Up to three levels of include file nesting are allowed.
By default, the file /etc/opt/SUNWmail/imta/aliases/usr is included. This file is updated by the imta dirsync program. List of addresses too long to fit in the alias database are put in this file.
The local channel (l) is unique because addresses diverted to it are looked up in the alias table. In general, the result of the alias table lookup matches another channel, causing the message to be enqueued to this channel. In practice, no message is enqueued to the local channel.
When using a mail user agent on the local system to send mail (to anywhere), the sendmail utility (/opt/SUNWmail/imta/bin/sendmail) is invoked as the replacement for sendmail to queue the messages to the appropriate queues, and then the channel programs for those queues will process the messages.
The native channel is used to deliver messages to /var/mail mailboxes.
An option file may be used to control various characteristics of the local channel. This local channel option file must be stored in the IMTA configuration directory and named native_option (for example, /etc/opt/SUNWmail/imta/native_option).
Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
The value may be either a string or an integer, depending on the option's requirements.
An option file may be used to control various characteristics of TCP/IP channels. Such an option file must be stored in the IMTA configuration directory (/etc/opt/SUNWmail/imta) and named x_option, where x is the name of the channel.
Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
The value may be either a string or an integer, depending on the option's requirements. 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 vb.
The available options are listed in TABLE 2-15.
The pipe channel performs delivery of messages using per-user, site-supplied programs. It provides a similar functionality to sendmail's pipe (|). The following differences are designed so that they will not pose a security threat. First, delivery programs to be invoked by the pipe channel must be registered by the system administrator. This registration is done performed using the imta program utility. See "imta program" on page 51 for information about imta program.
Delivery programs invoked by the pipe channel must return meaningful error codes so that the channel knows whether to dequeue, deliver for later processing, or return messages.
If the subprocess exits with an exit code of 0 (EX_OK), the message is presumed to have been delivered successfully and is removed from IMTA's queues. If it exits with an exit code of 71, 74, 75, or 79 (EX_OSERR, EX_IOERR, EX_TEMPFAIL, or EX_DB), a temporary error is presumed to have occurred and delivery of the message is deferred. If any other exit code is returned, then the message will be returned to its originator as undeliverable. These exit codes are defined in the system header file sysexits.h.
The imta program utility gives a name to each UNIX command that the administrator registers as able to be invoked by the pipe channel. This name can then be used by the end user as a value of their mailprogramdeliveryinfo LDAP attribute in order to enable delivery using the command corresponding to this name. The attribute maildeliveryoption must have one value equal to program.
For example, to add a UNIX command myprocmail as a program that can be invoked by the users, the user's LDAP entry should contain the following attributes/values:
maildeliveryoption: program
mailprogramdeliveryinfo: myprocmailSee alternative delivery programs in the SIMS Administrator's Guide for more information.
The hold channel is used to hold the messages of a recipient temporarily halted from receiving new messages. Messages may be halted because a user's name is being changed, or their mailbox is being moved from one mailhost or domain to another. There may also be other reasons to temporarily halt a user from receiving messages, but these are the most common.
Messages are placed in the hold channel in two ways:
| 1. | Setting one of the maildeliveryoption values of a user to hold. All other maildeliveryoption values are ignored (maildeliveryoption is a multi-valued attribute), and messages to the user are routed to the hold channel. | |
| 2. | Executing the hold_slave program. This program steps through all other channels and moves the existing messages whose recipient(s) matches those specified by the arguments into the hold channel. (See the hold_slave man page.) |
Unlike most channels, the hold channel master program is not configured to run automatically. Messages queued in the hold channel will remain there until the hold_master program is invoked by the administrator. (See the hold_master man page.)
To migrate user, first mark the user as being moved (use imadmin modify user to set maildeliveryoption to hold). Then invoke hold_slave to move any messages already in the other queues to the hold queue. At this point, perform the remaining migration steps. Once you have completed these steps, remove maildeliveryoption=hold, and then invoke hold_master to reenqueue messages to their proper channels.
For more information, refer to the man pages for hold_master, hold_slave, and imadmin-modify-user.
The conversion channel performs arbitrary body-part-by-body-part conversions on messages flowing through IMTA. Any subset of IMTA traffic can be selected for conversion and any set of programs or command procedures can be used to perform conversion processing. (IMTA's native conversion facilities are fairly limited, so the ability to call external converters is crucial.) A special conversion channel configuration is consulted to choose an appropriate conversion for each body part.
Although conversion processing is done using a regular IMTA channel program, under normal circumstances this channel is never specified directly either in an address or in an IMTA rewrite rule. IMTA controls access to the conversion channel using the CONVERSIONS mapping table in the IMTA mappings file (/etc/opt/SUNWmail/imta/mappings).
As IMTA processes each message it probes the CONVERSIONS mapping (if one is present) with a string of the form:
The source-channel is the channel from which the message is coming and destination-channel is the channel to which the message is heading. If the mapping produces a result, it should either be the string Yes or No. If Yes is produced, IMTA will divert the message from its regular destination to the conversion channel. If No is produced or if no match is found, the message will be queued to the regular destination channel.
For example, if all messages that do not originate from the tcp_intranet channel and that are going require conversion processing, the following mapping would then be appropriate:
Configuration of the conversion channel in the IMTA configuration file (imta.cnf) is performed by default. An address of the form user@conversion.localhostname or user@conversion will be routed through the conversion channel, regardless of what the CONVERSIONS mapping states.
The actual conversions performed by the conversion channel are controlled by rules specified in the IMTA conversion file. This is the file specified by the IMTA_CONVERSION_FILE option in the IMTA tailor file. By default, this is the file /etc/opt/SUNWmail/imta/conversions.
The IMTA conversion file is a text file containing entries in a format that is modeled after MIME Content-Type parameters. Each entry consists of one or more lines grouped together; each line contains one or more name=value; parameter clauses. Quoting rules conform to MIME conventions for Content-Type header line parameters. Every line except the last must end with a semicolon (;). A physical line in this file is limited to 252 characters. You can split a logical line into multiple physical lines using the backslash (\) continuation character. Entries are terminated either by a line that does not end in a semicolon, one or more blank lines, or both. For example, the following entry specifies that application/wordperfect5.1 parts in messages sent to the local channel should be converted to DDIF:
The rule parameters currently provided are shown in TABLE 2-16. Parameters not listed in the table are ignored.
TABLE 2-17 shows the basic set of environment variables available for use by the conversion command.
Additional environment variables containing Content-Type information can be created as they are needed using the PARAMETER-SYMBOL-n facility.
The conversion channel processes each message part-by-part. The header of each part is read and its Content-Type and other header information is extracted. The entries in the conversion file are then scanned in order from first to last; any IN- parameters present and the OUT-CHAN parameter, if present, are checked. If all of these parameters match the corresponding information for the body part being processed, then the conversion specified by the remainder of the parameter is performed.
More specifically, the matching checks: if the IN-CHAN and OUT-CHAN parameters match the channels through which the message is passing; and if the PART-NUMBER matches the structured part number2 of the message part; and if all of the IN-CHAN, IN-PARAMETER-NAME, IN-PARAMETER-VALUE, IN-SUBTYPE, and IN-TYPE, parameters match the Content-Type of the message; and if all of the IN-DISPOSITION, IN-DPARAMETER-NAME, and IN-DPARAMETER-VALUE parameters match the Content-Disposition of the message; and if the IN-DESCRIPTION matches the Content-Description of the message; and if the IN-SUBJECT, IN-A1-TYPE, and IN-A1-FORMAT of the headers of the immediately enclosing message (MESSAGE/RFC822 part) match those immediately enclosing the message part. Only if all specified parameters match is the entry consider to match. Scanning terminates once a matching entry has been found or all entries have been exhausted. If no entry matches no conversion is performed.
If the matching entry specifies DELETE=1, then the message part is deleted. Otherwise, the command specified by the COMMAND parameter is executed.
Once an entry with a COMMAND parameter has been selected, the body part is extracted to a file. The converter execution environment is prepared as specified by the PARAMETER-SYMBOL-n parameters. Finally, a subprocess is created to run the command specified by the COMMAND parameter. The command should perform the necessary conversion operation, reading the file specified by the INPUT_FILE environment variable and producing the file specified by the OUTPUT_FILE environment variable.
Conversion operations are terminated and no conversion is performed if the forked command returns an error.
If the command succeeds, the resulting output file is read as specified by the OUT-MODE parameter and a new body part containing the converted material is constructed according to the OUT-ENCODING, OUT-PARAMETER-NAME-n, OUT-PARAMETER-VALUE-n, OUT-SUBTYPE, OUT-TYPE, OUT-DESCRIPTION, OUT-DISPOSITION, and OUT-DPARAMETER-VALUE-n parameters.
This process is repeated for each part of the message until all parts have been processed.
When performing conversions on a message part, the conversion channel has access to the headers in an enclosing MESSAGE/RFC822 part, or to the message headers if there is no enclosing MESSAGE/RFC822 part.
For instance, the IN-A1-TYPE and IN-A1-FORMAT parameters can be used to check the A1-Type and A1-Format headers of an enclosing part, and the OUT-A1-TYPE and OUT-A1-FORMAT parameters can be used to set those enclosing headers.
More generally, if an entry is selected that has ORIGINAL-HEADER-FILE=1, then all the original headers of the enclosing MESSAGE/RFC822 part are written to the file represented by the OUTPUT_HEADERS environment variable. If OVERRIDE-HEADER-FILE=1, then the conversion channel will read and use as the headers on that enclosing part the contents of the file represented by the OUTPUT_HEADERS environment variable.
Environment variable names may be substituted into a conversion entry by enclosing the name in single quotes. For instance, with a site supplied command procedure CONVERTER that attempts to perform various conversions and which defines OUTPUT_TYPE and OUTPUT_SYMBOL job logicals describing its output, one might use an entry along the lines of:
To obtain a literal single quote in a conversion entry, quote it with the backslash character, \'. To obtain a literal backslash in a conversion entry, use two backslashes, \\.
The value for a conversion parameter may be obtained by calling out a mapping table. The syntax for calling out a mapping table is as follows:
Consider the following mapping table:
The following conversion entry for the above mapping table results in substituting generic file names in place of specific file names on attachments:
UUCP (UNIX to UNIX Copy Program) is an asynchronous terminal, line-based system providing support for file transfer and remote execution between different computer systems. These primitive operations are then used to construct a mail system, which is also, confusingly, known as UUCP.
Solaris supports the HoneyDanBer version of UUCP. Refer to the book Configuring Your Network Software for information on setting up UUCP on your system.
The UUCP channel is not one of the default channels. It cannot be configured through the Administration Console. This section describes how to set up the UUCP channel by editing the IMTA configuration file, imta.cnf.
Two or more channels are needed for the IMTA to communicate using UUCP. A single common channel is used for all incoming messages, no matter from what system they originated. An additional outbound channel is needed for each system connected using UUCP. The incoming message channel is slave-only and should never have any messages queued to it. The outgoing message channels are master-only.
The entry for the incoming message channel should resemble the following (do not use a different channel name):
Entries for outgoing UUCP message channels will vary depending on the name of the system to which the channel connects. For example, suppose the remote system's official name is uuhost.bravo.com and its UUCP name is simply uuhost. A channel definition for this system might be:
In this case, the name of the remote host to which the channel connects is derived from the channel name. When a second channel connecting to the same remote host is needed, it can be defined as:
In this case, the daemon channel keyword has been used to explicitly specify the name of the remote system to which the channel connects.
If the official name and UUCP name are the same, ymir, the entry can be simplified:
Rewrite rules should be set up to point at the proper outgoing channel using the channel's official host name. For example
Once the UUCP channels have been added to the configuration file, the UUCP master program should be ready to use. No additional log, script, or option files are needed.
The IMTA uucp_slave program is used to replace the rmail program on UNIX. You should rename the original rmail program (for example, to rmail.org) and create a symbolic link that links rmail to /opt/SUNWmail/imta/lib/uucp_slave as follows:
Various log files are created during the operation of the UUCP channels. All IMTA-specific log files are kept in the IMTA log directory, (/var/opt/SUNWmail/imta/log).
While running, the uucp_master program creates a log file, x_master.logfile where x is the channel name. The x_master.logfile logs each message as it is queued to the UUCP system.
Operation of the uucp_slave program creates a log file called rmail.logfile.
The IMTA automatically returns undeliverable messages after a certain amount of time has elapsed. However, UUCP maintains its own queues for files, so it is possible for messages to get stuck in the UUCP queues where the IMTA's regular message return job cannot see them.
An additional periodic cron job is needed to return undeliverable UUCP messages. This job operates in the same way as the IMTA's regular message return job except that it scans the UUCP queues and not the IMTA queues. This job is scheduled by the cron daemon.
The UUCP message return job should be scheduled by cron. To submit commands to the cron daemon, first become administrator, inetmail:
To edit the crontab entries, issue the command:
Add an entry similar to the following:
Use the sample entry shown to run the UUCP return job at 1:30 am and create the log file /var/opt/SUNWmail/imta/log/return_uucp.log-uniqueid, where uniqueid will be a unique string disambiguifying the file name, allowing for multiple versions of the file. The first value specifies the minutes after the hour, and the second value specifies the hour--you can specify other values according to the needs of your site. Use the return_uucp shell script as shown above, which itself calls the program /var/opt/SUNWmail/imta/bin/return_uucp rather than the UUCP cleanup command, since return_uucp will honor the notices channel keyword and understand the MIME format of the messages.
Many components of IMTA 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 IMTA databases are instances of just this sort of mapping table. IMTA database files, however, do not provide wildcard-lookup facilities, owing to inherent inefficiencies in having to scan the entire database for wildcard matches.
The mapping file provides IMTA with facilities for supporting multiple mapping tables. Full wildcard facilities are provided, and multistep and iterative mapping methods can be accommodated as well. This approach is more compute-intensive than using a database, especially when the number of entries is large. However, the attendant gain in flexibility may serve to eliminate the need for most of the entries in an equivalent database, and this may result in lower overhead overall.
Note - The mapping file is used for reverse mapping, forward mapping, access control mapping, conversion mapping, and so forth. Additional mapping file information is available in Chapter 6, "IMTA Security and Unsolicited Bulk Email (UBE) Handling," of the SIMS Administrator's Guide.
All mappings are kept in the IMTA mapping file. (This is the file specified with the IMTA_MAPPING_FILE option in the IMTA tailor file; by default, this is /etc/opt/SUNWmail/imta/mappings.) The contents of the mapping file will be incorporated into the compiled configuration.
The mapping file should be world readable. Failure to allow world-read access will lead to erratic behavior.
The mapping file consists of a series of separate tables. Each table begins with its name. Names always have an alphabetic character in the first column. The table name is followed by a required blank line, and then by the entries in the table. Entries consist of zero or more indented lines. Each entry line consists of two columns separated by one or more spaces or tabs. Any spaces within an entry must be quoted. A blank line must appear after each mapping table name and between each mapping table; no blank lines can appear between entries in a single table. Comments are introduced by an exclamation mark (!) in the first column.
The resulting format looks like:
An application using the mapping table TABLE-2-NAME would map the string pattern2-2 into whatever is specified by template2-2. Each pattern or template can contain up to 252 characters. There is no limit to the number of entries that can appear in a mapping (although excessive numbers of entries may consume huge amounts of CPU and can consume excessive amounts of memory). Long lines (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 mapping file.
Other files may be included in the mapping file. This is done with a line of the form:
This will effectively substitute the contents of the file file-spec into the mapping file at the point where the include appears. The file specification should specify a full file path (directory, and so forth). All files included in this fashion must be world readable. Comments are also allowed in such included mapping files. Includes can be nested up to three levels deep. Include files are loaded at the same time the mapping file is loaded--they are not loaded on demand, so there is no performance or memory savings involved in using include files.
All mappings in the mapping file are applied in a consistent way. The only things that change from one mapping to the next is the source of input strings and what the output from the mapping is used for.
A mapping operation always starts off with an input string and a mapping table. The entries in the mapping table are scanned one at a time from top to bottom in the order in which they appear in the table. The left side of each entry is used as pattern, and the input string is compared in a case-blind fashion with that pattern.
Patterns can contain wildcard characters. In particular, the usual wildcard characters are allowed: an asterisk (*) will match zero or more characters, and each percent sign (%) will match a single character. Asterisks, percent signs, spaces, and tabs can be quoted by preceding them with a dollar sign ($). Quoting an asterisk or percent sign robs it of any special meaning. Spaces and tabs must be quoted to prevent them from ending prematurely a pattern or template. Literal dollar sign characters should be doubled ($$), the first dollar sign quoting the second one.
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 imta test -mapping utility may be used to test mapping patterns and specifically to test wildcard behavior in patterns.
Asterisk wildcards maximize what they match by working from left to right across the pattern. For instance, when the string a/b/c is compared to the pattern */*, the left asterisk will match "a/b" and the right asterisk will match the remainder, c.
With IPv4 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 instance,
$<123.45.67.0/8>
will match anything in the 123.45.67.0 subnet. Or another example is that
$<123.45.67.4/2>
will match anything in the range 123.45.67.4--123.45.67.7.
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 will not appear in the output string produced by a template. See TABLE 2-19 for a list of the special substitution and standard processing metacharacters. Any other metacharacters are reserved for mapping-specific applications.
Note that any of the metacharacters $C, $E, $L, or $R, when present in the template of a matching pattern, will influence the mapping process 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.
Wildcard Field Substitutions ($n)
A dollar sign followed by a digit n is replaced with the material that matched the nth wildcard in the pattern. The wildcards are numbered starting with 0. For example, the following entry would match the input string PSI%A::B and produce the resultant output string b@a.psi.network.org:
The input string PSI%1234::USER would also match producing USER@1234.psi.network.org as the output string. The input string PSIABC::DEF would not match the pattern in this entry and no action would be taken; that is, no output string would result from this entry.
Controlling Text Case ($\, $^, $_)
The metacharacter $\ forces subsequent text to lowercase, $^ forces subsequent text to uppercase, and $_ causes subsequent text to retain its original case. For instance, these metacharacters may be useful when using mappings to transform addresses for which case is significant.
Processing Control ($C, $L, $R, $E)
The $C, $L, $R, and $E metacharacters influence the mapping process, controlling whether and when the mapping process terminates. The metacharacter:
|
|
$C causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process. |
|
|
$L causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process, and, if no matching entry is found, making one more pass through the table starting with the first table entry; a subsequent matching entry with a $C, $E, or $R metacharacter overrides this condition. |
|
|
$R causes the mapping process to continue from the first entry of the table, using the output string of the current entry as the new input string for the mapping process. |
|
|
$E causes the mapping process to terminate; the output string of this entry is the final output. $E is the default. |
Mapping table templates are scanned left to right. To set a $C, $L, or $R flag for entries that may "succeed" or "fail" (for example, general database substitutions or random-value controlled entries), put the $C, $L, or $R metacharacter to the left of the part of the entry that may succeed or fail; otherwise, if the remainder of the entry fails, the flag will not be seen.
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 email and you'd like to slow it down; if you're using the multithreaded TCP SMTP channel, you can use a PORT_ACCESS mapping table in the following way. Suppose you'd like to allow through only 25 percent of its connection attempts and reject the other 75 percent of its connection attempts. The following PORT_ACCESS mapping table uses $?25? to cause the entry with the $Y (accept the connection) to succeed only 25 percent of the time; the other 75 percent of the time, when this entry fails, the initial $C on that entry causes IMTA to continue the mapping from the next entry, which causes the connection attempt to be rejected with an SMTP error and the message: Try again later.
Sequence Number Substitutions ($#...#)
A $#...# substitution increments the value stored in an IMTA sequence file and substitutes that value into the template. This can be used to generate unique, increasing strings in cases where it is desirable to have a unique qualifier in the mapping table output; for instance, when using a mapping table to generate file names.
Permitted syntax is any one of the following:
The required seq-file-spec argument is a full file specification for an already existing IMTA sequence file, where the optional radix and width arguments specify the radix (base) in which to output the sequence value, and the number of digits to output, respectively. The default radix is 10. Radices in the range -36 to 36 are also allowed; for instance, base 36 gives values expressed with digits 0,...,9,A,...,Z. By default, the sequence value is printed in its natural width, but if the specified width calls for a greater number of digits, then the output will be padded with 0's on the left to obtain the correct number of digits.
Note that if a width is explicitly specified, then the radix must be explicitly specified also.
As noted above, the IMTA sequence file referred to in a mapping must already exist. To create an IMTA sequence file, use the following command:
or
A sequence number file accessed using a mapping table must be world readable in order to operate properly. You must also have an IMTA user account in order to use such sequence number files.
Mapping Table Substitutions ($|...|)
A substitution of the form $|mapping,argument| is handled specially. IMTA looks for a auxiliary mapping table named mapping in the IMTA mapping file, and uses argument as the input to that named auxiliary mapping table. The named auxiliary mapping table must exist and must set the $Y flag in its output if it is successful; if the named auxiliary mapping table does not exist or doesn't set the $Y flag, then that auxiliary mapping table substitution fails and the original mapping entry is considered to fail: the original input string will be used as the output string.
Note that when you 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 will mean that the processing control metacharacter will not be seen.
General Database Substitutions (${...})
A substitution of the form ${text} is handled specially. The text part is used as a key to access the general database. This database is generated with the IMTA crdb utility. If text is found in the database, the corresponding template from the database is substituted. If text does not match an entry in the database, the input string is used unchanged as the output string.
If a general database exists, it should be world readable to insure that it operates properly.
When you want to use processing control metacharacters such as $C, $R, or $L in a mapping table entry that does a general database substitution, the processing control metacharacter should be placed to the left of the general database substitution in the mapping table template; otherwise the "failure" of a general database substitution will mean that the processing control metacharacter will not be seen.
Site-Supplied Routine Substitutions ($[...])
A substitution of the form $[image,routine,argument] is handled specially. The image,routine,argument part is used to find and call a customer-supplied routine. At runtime, IMTA uses dlopen and dlsym to dynamically load and call the routine routine from the shared library image. The routine routine is then called as a function with the following argument list:
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 will then replace the $[image,routine,argument] in the mapping table template. The routine routine should return 0 if the mapping table substitution should fail and -1 if the mapping table substitution should succeed. If the substitution fails, then normally the original input string will be used unchanged as the output string.
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 will mean that the processing control metacharacter will not be seen.
The site-supplied routine callout mechanism allows IMTA's mapping process to be extended in all sorts of complex ways. For example, in a PORT_ACCESS or ORIG_SEND_ACCESS mapping table, a call to some type of load monitoring service could be performed and the result used to decide whether or not to accept a connection or message.
The site-supplied shared library image image should be world readable.
Note - This facility is not designed for use by casual users; it is intended to be used to extend IMTA's capabilities system-wide.
Address reversal is the operation consisting of converting an address from an internal form to a public, advertised form. For example, while uid@mailhost.alpha.com might be a valid address within the alpha.com domain, it might not be an appropriate address for the outside world to see. first.last@alpha.com is a more likely public address.
The address reversal operation applies by default to envelop From and all header addresses. This can be changed by setting the value of the REVERSE_ENVELOPE and system options. Address reversal can be turned on or off on a per-channel basis using the reverse channel keyword.
The public address for each user is specified by the mail attribute of the user entry in the directory. The same is true for distribution lists.
The reverse database contains a mapping between any valid address and this public address. It is updated and created by imta dirsync.
The reverse database is created each time you run the imta dirsync command.
The reverse database is generally located in the IMTA database directory. The database is the files whose names are specified with the IMTA_REVERSE_DATABASE option in the /etc/opt/SUNWmail/imta/imta_tailor file, which by default are the files /var/opt/SUNWmail/imta/db/reversedb.*.
Note - Do not edit this database directly. Any required changes must be done in the directory.
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 mapping file. No substitution is made, and rewriting terminates normally if the table does not exist or no entries from the table match.
Reverse mapping can also be performed on a per-channel basis. The src_channel| destination and channel| internal addresses need to be mapped to *|tcp_local|*@*.stream.com and $|@stream.com$Y.
If the address matches a mapping entry, the result of the mapping is tested. The resulting string will replace the address if the entry specifies a $Y; a $N will discard the result of the mapping. If the mapping entry specifies $D in addition to $Y, the resulting string will be run through the reversal database once more; and if a match occurs, the template from the database will replace the mapping result (and hence the address).
As an example, suppose that the internal addresses at stream.com are actually of the form user@host.stream.com, but, unfortunately, the user name space is such that user@hosta.stream.com and user@hostb.stream.com specify the same person for all hosts at stream.com. Then the following, very simple REVERSE mapping may be used in conjunction with the address-reversal database:
This mapping maps addresses of the form user@anyhost.stream.com to user@host.stream.com. The $D metacharacter causes the address-reversal database to be consulted. The address-reversal database should contain entries of the form:
The reverse and noreverse channel keywords, and the IMTA options USE_REVERSE_DATABASE and REVERSE_ENVELOPE might be used to control the specifics of when and how address reversal is applied. In particular, address reversal will not be applied to addresses in messages when the destination channel is marked with the noreverse keyword. If USE_REVERSE_DATABASE is set to 0, address reversal will not be used with any channel. The REVERSE_ENVELOPE option controls whether or not address reversal is applied to envelope From addresses as well as message header addresses. See the descriptions of these options and keywords for additional information on their effects. By default, the address reversal database is used if the routability scope is set to the mail server domains.
Address reversals are not applied to envelope To addresses. These 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 canonization functions of address reversal are inappropriate for envelope To addresses.
The various substitution mechanisms for envelope To addresses provide functionality equivalent to the reversal database, but none of these things provides functionality equivalent to reverse mapping. Circumstances can arise where mapping functionality for envelope To addresses is useful and desirable.
The FORWARD mapping table provides this missing functionality. 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.
The following example illustrates the use of a complex REVERSE and FORWARD mapping. Suppose that a system or pseudo-domain named am.sigurd.stream.com associated with the native channel produces RFC 822 addresses of the general form:
or
Although these addresses are perfectly legal, they often confuse other mailers that do not fully comply with RFC 822 syntax rules--mailers that do not handle quoted addresses properly, for instance. Consequently, an address format that does not require quoting tends to operate with more mailers. One such format is:
The goals of this example mapping are to:
|
|
Allow any of these three address formats to be used |
|
|
Present only addresses in the original format to the mr_gateway channel, converting formats as necessary |
|
|
Present only addresses in the new unquoted format to all other channels, converting formats as necessary |
The following mapping file tables produce the results. The REVERSE mapping shown assumes that bit 3 in the IMTA option USE_REVERSE_DATABASE is set.
Global IMTA options, as opposed to channel options, are specified in the IMTA option file.
The IMTA uses an option file to provide a means of overriding the default values of various parameters that apply to the IMTA 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.
The option file is the file specified with the IMTA_OPTION_FILE option in the IMTA tailor file (/etc/opt/SUNWmail/imta/imta_tailor). By default, this is /etc/opt/SUNWmail/imta/option.dat.
Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
The value may be either a string or an integer, depending on the option's requirements. 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.
Comments are allowed. Any line that begins with an exclamation point (!) is considered to be a comment and is ignored. Blank lines are also ignored in any option file.
The available options are listed in TABLE 2-21.
TABLE 2-21 Option File Options Options
Description
ACCESS_ERRORS (Integer 0 or 1)
IMTA provides facilities to restrict access to channels on the basis of group IDs on the SunOS operating system. If ACCESS_ERRORS is set to 0 (the default), when an address causes an access failure IMTA will report it as an "illegal host or domain" error. This is the same error that would occur if the address were simply illegal. Although confusing, this usage provides an important element of security in circumstances where information about restricted channels should not be revealed. Setting ACCESS_ERRORS to 1 will override this default and provide a more descriptive error.
ALIAS_HASH_SIZE
(Integer <= 32,767)Sets the size of the alias hash table. This is an upper limit on the number of aliases that can be defined in the alias file. The default is 256; the maximum value is 32,767.
ALIAS_MEMBER_SIZE
(Integer <= 20,000)Controls the size of the index table that contains the list of alias translation value pointers. The total number of addresses on the right sides of all of the alias definitions in the alias file cannot exceed this value. The default is 320; the maximum value is 20,000.
BLOCK_LIMIT (Integer > 0)
Places an absolute limit on the size, in blocks, of any message that may be sent or received with IMTA. Any message exceeding this size will be rejected. By default, IMTA imposes no size limits. Note that the blocklimit channel keyword can be used to impose limits on a per-channel basis. The size in bytes of a block is specified with the BLOCK_SIZE option.
BLOCK_SIZE (Integer > 0)
IMTA uses the concept of a "block" in several ways. For example, the IMTA log files (resulting from placing the logging keyword on channels) record message sizes in terms of blocks. Message size limits specified using the maxblocks keyword are also in terms of blocks. Normally, an IMTA block is equivalent to 1024 characters. This option can be used to modify this sense of what a block is.
BOUNCE_BLOCK_LIMIT
Used to force bounces of messages over the specified size to return only the message headers, rather than the full message content.
(Integer <= 32,767)
Controls the size of the channel table. The total number of channels in the configuration file cannot exceed this value. The default is 256; the maximum is 32,767.
COMMENT_CHARS
Sets the comment characters in IMTA configuration files.
(Integer <= 2000)
Controls the size of the conversion entry table, and thus the total number of conversion file entries cannot exceed this number. The default is 32.
DEQUEUE_DEBUG (0 or 1)
Specifies whether debugging output from IMTA's dequeue facility (QU) is produced. If enabled with a value of 1, this output will be produced on all channels that use the QU routines. The default of 0 disables this output.
(Integer <= 32,767)
Controls the size of the domain rewrite rules hash table. Each rewrite rule in the configuration file consumes one slot in this hash table; thus the number of rewrite rules cannot exceed this option's value. The default is 512; the maximum number of rewrite rules is 32,767.
(Integer 0 or 1)
Controls the application of the exproute channel keyword to forward-pointing (To, Cc, and Bcc lines) addresses in the message header. A value of 1 is the default and specifies that exproute should affect forward pointing header addresses. A value of 0 disables the action of the exproute keyword on forward pointing addresses.
HISTORY_TO_RETURN (1-200)
Controls how many delivery attempt history records are included in returned messages. The delivery history provides an indication of how many delivery attempts were made and might indicate the reason the delivery attempts failed. The default value for this option is 20.
HELD_SND_OPR
Controls the production of operator messages when a message is forced into a held state because it has too many Received: header lines.
(Integer <= 32,767)
Controls the size of the channel hosts hash table. Each channel host specified on a channel definition in the IMTA configuration file (both official hosts and aliases) consumes one slot in this hash table, so the total number of channel hosts cannot exceed the value specified. The default is 512; the maximum value allowed is 32,767.
ID_DOMAIN (String)
Specifies the domain name to use when constructing message IDs. By default, the official host name of the local channel is used.
(Integer 0 or 1)
Controls the application of the improute channel keyword to forward-pointing (To, Cc, and Bcc lines) addresses in the message header. A value of 1 is the default and specifies that improute should affect forward-pointing header addresses. A value of 0 disables the action of the improute keyword on forward-pointing addresses.
LINE_LIMIT (Integer)
Places an absolute limit on the overall number of lines in any message that may be sent or received with IMTA. Any message exceeding this limit will be rejected. By default, IMTA imposes no line-count limits.The linelimit channel keyword can be used to impose limits on a per channel basis.
LINES_TO_RETURN (Integer)
Controls how many lines of message content IMTA includes when bouncing messages. The default is 20.
LOG_CONNECTION (0 or 1)
Controls whether connection information--for example, the domain name of the SMTP client sending the message--is saved in the mail.log file. A value of 1 enables connection logging. A value of 0 (the default) disables it.
LOG_DELAY_BUG
Specifies the bins for delivery delay range counters.
LOG_FILENAME (0 or 1)
Controls whether the names of the files in which messages are stored are saved in the mail.log file. A value of 1 enables file name logging. A value of 0 (the default) disables it.
LOG_FORMAT (1, 2, or 3)
Controls formatting options for the mail.log file. A value of 1 (the default) is the standard format. A value of 2 requests non-null formatting: empty address fields are converted to the string "<>." A value of 3 requests counted formatting: all variable length fields are preceded by N, where N is a count of the number of characters in the field.
LOG_HEADER (0 or 1)
Controls whether the IMTA writes message headers to the mail.log file. A value of 1 enables message header logging. The specific headers written to the log file are controlled by a site-supplied log_header.opt file. The format of this file is that of other IMTA header option files. For example, a log_header.opt file containing the following would result in writing the first To and the first From header per message to the log file. A value of 0 (the default) disables message header logging:
Defaults: MAXIMUM=-1
LOG_LOCAL (0 or 1)
Controls whether the domain name for the local host is appended to logged addresses that don't already contain a domain name. A value of 1 enables this feature, which is useful when logs from multiple systems running IMTA are concatenated and processed. A value of 0, the default, disables this feature.
LOG_MESSAGE_ID (0 or 1)
Controls whether message IDs are saved in the mail.log file. A value of 1 enables message ID logging. A value of 0 (the default) disables it.
LOG_PROCESS
Includes the enqueuing process ID in IMTA log entries.
LOG_SNDOPR
Controls the production of operator (OPCOM) messages or syslog messages by the IMTA message logging facility.
LOG_SIZE_BINS
Specifies the bins for message size range counters.
LOG_USERNAME (0 or 1)
Controls whether the user name associated with a process that enqueues mail is saved in the mail.log file. A value of 1 enables user name logging. A value of 0 (the default) disables it.
(Integer > 0)
Specifies the size of the mapping table name table, and thus the total number of mapping table cannot exceed this number. The default is 32.
MAX_ALIAS_LEVELS (Integer)
Controls the degree of indirection allowed in aliases; that is, how deeply aliases may be nested, with one alias referring to another alias, and so forth. The default value is 10.
(Real Number Between
0 and 1)Controls what fraction of the available message blocks can be used by message headers.
(Real Number Between
0 and 1)Controls what fraction of the available message lines can be used by message headers.
MAX_INTERNAL_BLOCKS (Integer)
Specifies how large (in IMTA blocks) a message IMTA will keep entirely in memory; messages larger than this size will be written to temporary files. The default is 10. For systems with lots of memory, increasing this value may provide a performance improvement.
MAX_LOCAL_RECEIVED_LINES (Integer)
As IMTA processes a message, it scans any Received: header lines attached to the message looking for references to the official local host name. (Any Received line that IMTA inserts will contain this name.) If the number of Received lines containing this name exceeds the MAX_LOCAL_RECEIVED_LINES value, the message is entered in the IMTA queue in a held state. The default for this value is 10 if no value is specified in the option file. This check blocks certain kinds of message forwarding loops. The message must be manually moved from the held state for processing to continue.
MAX_MIME_LEVELS
Specify the maximum depth to which IMTA should process MIME messages. The default is 100, which means that IMTA will process up to 100 levels of message nesting.
MAX_MIME_PARTS
Specify the maximum number of MIME parts that IMTA should process in a MIME message.
MAX_RECEIVED_LINES (Integer)
As IMTA processes a message, it counts the number of Received: header lines in the message's header. If the number of Received lines exceeds the MAX_RECEIVED_LINES value, the message is entered in the IMTA queue in a held state. The default for this value is 50 if no value is specified in the option file. This check blocks certain kinds of message forwarding loops. The message must be manually moved from the held state for processing to continue.
MISSING_RECIPIENT_POLICY
Legalizes messages that lack any recipient headers.
NORMAL_BLOCK_LIMIT (Integer)
Used to instruct IMTA to downgrade the priority of messages based on size: messages above the specified size will be downgraded to non-urgent priority. This priority, in turn, may affect whether the message is processed immediately, or whether it is left to wait for processing until the next periodic job runs.
NON_URGENT_BLOCK_LIMIT (Integer)
Used to instruct IMTA to downgrade the priority of messages based on size: Messages above the specified size will be downgraded to lower than nonurgent priority; they will not be processed immediately and will wait for processing until the next periodic job runs. The value is interpreted in terms of IMTA blocks, as specified by the BLOCK_SIZE option. Note also that the nonurgentblocklimit channel keyword may be used to impose such downgrade thresholds on a per channel basis.
POST_DEBUG (0 or 1)
Specifies whether debugging output is produced by IMTA's periodic delivery job. If enabled with a value of 1, this output will be produced in the post.log file. The default value of 0 disables this output.
RECEIVED_DOMAIN (String)
Sets the domain name to use when constructing Received headers. By default, the official host name of the local channel.
RETURN_ADDRESS (String)
Sets the return address for the local postmaster. The local postmaster's address is postmaster@localhost by default, but it can be overridden with the address of your choice. Care should be taken in the selection of this address--an illegal selection may cause rapid message looping and pileups of huge numbers of spurious error messages.
RETURN_DEBUG (0 or 1)
Enables or disables debugging output in the nightly message bouncer batch job. A value of 0 disables this output (the default), while a value of 1 enables it. Debugging output, if enabled, appears in the output log file, if such a log file is present. The presence of an output log file is controlled by the crontab entry for the return job.
(0 or 1)
Controls whether or not a history of delivery attempts is included in returned messages. The delivery history provides some indication of how many delivery attempts were made and, in some cases, indicates the reason the delivery attempts failed. A value of 1 enables the inclusion of this information and is the default. A value of 0 disables return of delivery history information. The HISTORY_TO_RETURN option controls how much history information is actually returned.
RETURN_ENVELOPE (Integer)
Takes a single integer value, which is interpreted as a set of bit flags. Bit 0 (value = 1) controls whether return notifications generated by IMTA 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 addresses. Note that the use of blank address is mandated by RFC 1123. However, some systems do not handle blank-envelope-from-address properly and may require the use of this option. Bit 1 (value = 2) controls whether IMTA replaces all blank envelope addresses with the address of the local postmaster. Again, this is used to accommodate noncompliant systems that don't conform to RFC 821, RFC 822, or RFC 1123. Note that the returnenvelope channel keyword can be used to impose this sort of control on a per-channel basis.
RETURN_PERSONAL (String)
Specifies the personal name to use when IMTA generates postmaster messages (for example, bounce messages). By default, IMTA uses the string, Internet Mail Delivery.
REVERSE_ENVELOPE (0 or 1)
Controls whether IMTA applies the address reversal to envelope From addresses as well as header addresses. This option will have no effect if the USE_REVERSE_DATABASE option is set to 0 or if the reverse database does not exist. The default is 1, which means that IMTA will attempt to apply the database to envelope From addresses. A value of 0 will disable this use of the address reversal database.
(0 or 1)
Controls whether the connection log information generated by setting LOG_CONNECTION =1 is stored in the usual IMTA message logging files, mail.log* or is stored separately in connection.log* files. The default (0) causes connection logging to be stored in the regular message log files; 1 causes the connection logging to be stored separately.
(Integer <= 10,000,000)
Controls the number of character slots allocated to the string pool used to hold rewrite rule templates and alias list members. A fatal error will occur if the total number of characters consumed by these parts of the configuration and alias files exceeds this limit. The default is 60,000; the maximum allowed value is 10,000,000.
URGENT_BLOCK_LIMIT (Integer)
Used to instruct IMTA to downgrade the priority of messages based on size: messages above the specified size will be downgraded to normal priority. This priority, in turn, may affect whether the message is processed immediately or left to wait for processing until the next periodic job runs. The value is interpreted in terms of IMTA blocks, as specified by the BLOCK_SIZE option. Note also that the urgentblocklimit channel keyword may be used to impose such downgrade thresholds on a per-channel basis.
USE_ALIAS_DATABASE (0 or 1)
Controls whether IMTA uses the alias database as a source of system aliases for local addresses. The default (1), means that IMTA will check the database if it exists. A value of 0 will disable this use of the alias database.
USE_DOMAIN_DATABASE
Controls the use of the domain database. The default (1) means that IMTA will check the database if it exists. 0
USE_ERRORS_TO (0 or 1)
Controls whether IMTA uses the information contained in Errors-to header lines when returning messages. Setting this option to 1 directs IMTA to make use of this header line. The default (0), disable uses of this header line.
USE_FORWARD_DATABASE
Control use of the forward database.
USE_REVERSE_DATABASE (0-31)
Controls whether IMTA uses the address reversal database and REVERSE mapping as a source of substitution addresses. This value is a decimal integer representing a bit-encoded integer, the interpretation of which is given in TABLE 2-22.
USE_WARNINGS_TO (0 or 1)
Controls whether IMTA uses the information contained in Warnings-to header lines when returning messages. Setting this option to 1 directs IMTA to make use of these header lines. The default is 0, which disables use of this header line.
WILD_POOL_SIZE (integer)
Controls the total number of patterns that appear throughout mapping tables. the default is 8000. The maximum allowed is 200,000.
Some special option files may be associated with a channel that describe how to trim the headers on messages queued to that channel. This facility is completely general and may be applied to any channel; it is controlled by the headertrim, noheadertrim, headerread, and noheaderread channel keywords.
An option file can be used in addition to the channel keywords to configure the behavior of a channel. This configuration tool is available for the Solaris /var/mail, the UUCP, the pipe, and the SMTP channels. In addition, any channel can use a header option file in order to create or remove channel-specific headers in messages processed by the channel's master program.
Header option files have a different format than other IMTA option files, and thus a header option file is always a separate file.
For header trimming to be applied upon message dequeue, IMTA looks in the config directory (/etc/opt/SUNWmail/imta) for header options files with names of the form channel_headers.opt, where channel is the name of the channel with which the header option file is associated. The headertrim keyword must be specified on the channel to enable the use of such a header option file.
For header trimming to be applied upon message enqueue, IMTA looks in the config directory (/etc/opt/SUNWmail/imta) for header options files with names of the form channel_read_headers.opt, where channel is the name of the channel with which the header option file is associated. The headerread keyword must be specified on the channel to enable the use of such a header option file.
Header option files should be world readable.
Simply put, the contents of a header option file are formatted as a set of message header lines. Note, however, that the bodies of the header lines do not conform to RFC 822.
The general structure of a line from a header options file is:
Header-name is the name of a header line that IMTA recognizes (any of the header lines described in this manual may be specified, plus any of the header lines standardized in RFC 822, RFC 987, RFC 1049, RFC 1421, RFC 1422, RFC 1423, RFC 1424, RFC 1327, and RFC 1521 (MIME).
Header lines not recognized by IMTA are controlled by the special header line name Other. A set of options to be applied to all header lines not named in the header option file can also be given on a special defaults line. The use of defaults guards against the inevitable expansion of IMTA's known header line table in future releases.
Various options can then be specified to control the retention of the corresponding header lines. The available options are listed in TABLE 2-23.
The IMTA tailor file (imta_tailor) is an option file in which the location of various IMTA components are set. Certain parameters for tuning the performance of the IMTA databases are also set in this file. This file must always exist in the /etc/opt/SUNWmail/imta directory for the MTA to function properly. The file may be edited to reflect the changes in a particular installation. Some options in the file should not be edited. The IMTA should be restarted after making any changes to the file. It is preferable to make the changes while the MTA is down. If the database tuning parameters are changed, all existing IMTA databases must be removed and reconstructed.
Note - Do not edit this file unless absolutely necessary.
An option setting has the form:
The value can be either a string or an integer, depending on the option's requirements. Comments are allowed. Any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored. Options that are available and can be edited are shown in TABLE 2-24.
This file is used to set options for the dirsync program that cannot be set through the command line. This file should be located in the IMTA configuration directory, which is specified by the value for IMTA_TABLE in the imta_tailor file. In this file, any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored. The format of this file is:
The value may be either a string or an integer, depending on the option's requirements. If any of the options in this file are changed, perform a full dirsync after the change. The available options are as follows:
This file is used for setting options for the autoreply or vacation program. This file should be located in the IMTA configuration directory, which is specified by the value for IMTA_TABLE in the imta_tailor file. In this file, any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored The format of this file is:
The value may be either a string or an integer, depending on the option's requirements.
The available options are:
The job controller is responsible for scheduling and executing the message delivery or message submission tasks upon request by various IMTA components. For example, upon receipt of an incoming message from any source, the IMTA channel that is handling the receipt of the message determines the destination, enqueues the message, and sends a request to the job controller to execute the next channel. The job controller schedules only the client tasks for IMTA.
Internally, the job controller maintains the set of channel queues. Requests are placed on specified queues by server processes as messages are processed. Each queue has a job limit that consists of the maximum number of concurrent jobs that can be processed and the maximum number of jobs that can be enqueued. Requests are executed as they are received until the job limit is exceeded, at which point they are queued to run when a currently executing request finishes. If the capacity of a queue is exceeded, requests directed at that queue are ignored by the job controller.
At startup, the job controller reads a configuration file that specifies parameters, queues, and channel processing information. This configuration information is specified in the file job_controller.cnf in the /etc/opt/SUNWmail/imta/ directory.
The job controller configuration file job_controller.cnf:
|
|
Defines various types of queues that differ by their capacity and job limit |
|
|
Specifies for all channels the master program name and the slave program name, if applicable |
In the imta.cnf file, you can specify a type of queue (that was defined in job_controller.cnf) by using the queue keyword. For example, the following fragment from a sample job_controller.cnf file defines the queue MY_QUEUE:
The following fragment from a sample imta.cnf file specifies the queue MY_QUEUE in a channel block:
If you want to modify the parameters associated with the default queue configuration or add additional queues, you can do so by editing the job_controller.cnf file, and stopping and then restarting the job controller with the command:
A new job controller process is created, using the new configuration, and receives subsequent requests. The old job controller process continues to execute any requests it has queued until they are all finished, at which time it exits.
To stop the job controller, execute the following command:
The first queue in the job controller configuration file, by default the only queue, is used for any requests that do not specify the name of a queue. IMTA channels defined in the IMTA configuration file (imta.cnf) can have their processing requests directed to a specific queue by using the queue channel keyword followed by the name of the queue. The queue name must match the name of a queue in the job controller configuration. If the job controller does not recognize the requested queue name, the request is ignored.
Typically, you would add additional types of queue characteristics 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 queues 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 queue with the job limit, then use the queue channel keyword to direct those channels to the new, more appropriate queue.
In addition to the definition of queues, the job controller configuration file also contains a table of IMTA channels and the commands that the job controller must use to process requests for each channel. These two types of requests are termed "master" and "slave." Typically, a channel master program is invoked when there is a message stored in an IMTA message queue for the channel. The master program dequeues the message and delivers it.
A slave program is invoked to poll a channel and pick up any messages inbound on that channel. While nearly all IMTA channels have a master program, many do not 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 IMTA'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 queue whose job limit is one:
On the other hand, if the destination system has enough parallelism, you can set the job limit to a higher value. The capacity defines the maximum number of requests which the job_controller will store at given time. Requests that are received after the limit has been reached are ignored.
In accordance with the format of IMTA option files, the job controller configuration file contains lines of the form:
In addition to option settings, the file may contain a line consisting of a section and value enclosed in square-brackets ([ ]) in the form:
Such a line indicates that option settings following this line apply only to the section named by value. Initial option settings that appear before any such section tags apply globally to all sections. Per section option settings override global defaults for that section. Recognized section types for the job controller configuration file are QUEUE, to define queues and their parameters, and CHANNEL, to define channel processing information.
The following is a sample job controller configuration file (job_controller.cnf).
The key items in the preceding example (numbered, enclosed in parentheses, and in bold font) are:
| 1. | This global option defines the UDP port number on which the job controller listens for requests. | |
| 2. | Sets a default SLAVE_COMMAND for subsequent [CHANNEL] sections. | |
| 3. | Sets a default CAPACITY for subsequent [QUEUE] sections. | |
| 4. | This [QUEUE] section defines a queue named DEFAULT. Since this is the first queue in the configuration file, it is used by all channels that do not specify a queue name using the queue channel keyword. | |
| 5. | Set the JOB_LIMIT for this queue to 10. | |
| 6. | This [CHANNEL] section applies to a channel named l, the IMTA 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_. |
TABLE 2-27 shows the available options.
A master_shutdown command may be associated with each channel that contains master programs. This is the command that stops the master program if the job controller is stopped. Such commands are useful for master programs which run like daemons. The format is:
The path is the full path name to the shutdown executable.
The IMTA multithreaded SMTP Dispatcher is a multithreaded connection dispatching agent that permits multiple multithreaded servers to share responsibility for a given service. When using the SMTP Dispatcher, it is possible to have several multithreaded SMTP servers running concurrently. In addition to having multiple servers for a single service, each server may handle simultaneously one or more active connections.
The SMTP Dispatcher works by acting as a central receiver for the TCP ports listed in its configuration. For each defined service, the IMTA SMTP Dispatcher may create one or more SMTP server processes that actually handle the connections after they've been established.
In general, when the SMTP Dispatcher receives a connection for a defined TCP port, it checks its pool of available SMTP server processes and chooses the best candidate for the new connection. If no suitable candidate is available and the configuration permits it, the SMTP Dispatcher creates a new SMTP server process to handle this and subsequent connections. The SMTP Dispatcher may also proactively create a new SMTP server process in expectation of future incoming connections. There are several configuration options that can tune the IMTA SMTP Dispatcher's control of its various services, and in particular, control the number of SMTP server processes and the number of connections each SMTP server process handles.
Automatic housekeeping facilities within the SMTP Dispatcher control the creation of new and expiration of old or idle SMTP server processes. The basic options that control the SMTP Dispatcher's behavior are MIN_PROCS and MAX_PROCS. MIN_PROCS provides a guaranteed level of service by having a number of SMTP server processes ready and waiting for incoming connections. MAX_PROCS, on the other hand, sets an upper limit on how many SMTP server processes may be concurrently active for the given service.
It is possible that a currently running SMTP server process might not be able to accept any connections because it is already handling the maximum number of connections of which it is capable, or because the process has been scheduled for termination. The SMTP Dispatcher may create additional processes to assist with future connections.
The MIN_CONNS and MAX_CONNS options provide a mechanism to help you distribute the connections among your SMTP server processes. MIN_CONNS specifies the number of connections that flags a SMTP server process as "busy enough" while MAX_CONNS specifies the "busiest" that a SMTP server process can be.
In general, the SMTP Dispatcher creates a new SMTP server process when the current number of SMTP server processes is less than MIN_PROCS or when all existing SMTP server processes are "busy enough" (the number of currently active connections each has is at least MIN_CONNS and at least 75 percent of MAX_CONNS).
If a SMTP server process is killed unexpectedly, for example, by the UNIX system kill command, the SMTP Dispatcher still creates new SMTP server processes as new connections come in.
The SMTP Dispatcher configuration information is specified in the
/etc/opt/SUNWmail/imta/dispatcher.cnf file. 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.
The SMTP Dispatcher configuration file format is similar to the format of other IMTA configuration files. Lines specifying options have the following form:
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:
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 SMTP Dispatcher configuration file (dispatcher.cnf).
TABLE 2-28 shows the available options.
The SMTP Dispatcher is a single resident process that starts and shuts down SMTP server processes for various services, as needed. The SMTP Dispatcher process is started using the command:
This command subsumes and makes obsolete any other imta start command that was used previously to start up a component of IMTA that the SMTP Dispatcher has been configured to manage. Specifically, you should no longer use imta start smtp. An attempt to execute any of the obsoleted commands causes IMTA to issue a warning.
To shut down the SMTP Dispatcher, execute the command:
What happens with the SMTP server processes when the SMTP Dispatcher is shut down depends upon the underlying TCP/IP package. If you modify your IMTA configuration or options that apply to the SMTP Dispatcher, you must restart the SMTP Dispatcher so that the new configuration or options take effect. To restart the SMTP Dispatcher, execute the command:
Restarting the SMTP Dispatcher has the effect of shutting down the currently running SMTP Dispatcher, then immediately starting a new one.
Service Dispatcher error and debugging output (if enabled) are written to the file dispatcher.log in the IMTA log directory.
Debugging output may be enabled using the option DEBUG in the Dispatcher configuration file, or on a per-process level, using the IMTA_DISPATCHER_DEBUG environment variable (UNIX).
The DEBUG option or IMTA_DISPATCHER_DEBUG environment variable (UNIX) defines a 32-bit debug mask in hexadecimal. Enabling all debugging is done by setting the option to -1, or by defining the logical or environment variable system-wide to the value FFFFFFFF. The actual meaning of each bit is described in TABLE 2-29.
The system's heap size (datasize) must be enough to accommodate the Dispatcher's thread stack usage. For each Dispatcher service compute STACKSIZE*MAX_CONNS, and then add up the values computed for each service. The system's heap size needs to be at least twice this number.
To display the heap size (that is, default datasize), use the csh command
# limit
or the ksh command
# ulimit -a
or the utility
# sysdef