Previous     Contents     Index          Next     
iPlanet Messaging Server 5.0 Reference Manual



Chapter 5   MTA Configuration


The following topics are covered in this chapter:



The MTA Configuration Files

This section explains the structure and layout of the MTA configuration files. Some configuration modifications can be done using the command-line interface, as described in Chapter 2 "Message Transfer Agent Command-line Utilities." Modifications not possible through the command line can be done by editing the configuration files. We recommend that only experienced administrators edit and modify 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 MTA 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.

Table 5-1 lists the MTA configuration files with a short description.

Table 5-1    MTA Configuration files 

File

Description

Autoreply Option File  

Options used by the autoreply program. server_root/msg-instance/imta/config/autoreply.opt  

Alias File (mandatory)  

Implements aliases not present in the directory. server_root/msg-instance/imta/config/aliases  

SMTP Channel Option Files  

Many channels use channel options files to set channel specific options. server_root/msg-instance/imta/config/channel_option  

Conversion File  

Used by conversion channel to control message body part conversions. server_root/msg-instance/imta/config/conversions  

Dirsync Option File (mandatory)  

Options used by the dirsync program. server_root/msg-instance/imta/config/dirsync.opt  

Dispatcher Configuration File (mandatory)  

Configuration file for service dispatcher. server_root/msg-instance/imta/config/dispatcher.cnf  

imta.cnf File (mandatory)  

Used for address rewriting and routing as well as channel definition. server_root/msg-instance/imta/config/imta.cnf  

Mapping File (mandatory)  

Repository of mapping tables. server_root/msg-instance/imta/config/mappings  

Option Files  

File of global MTA options. server_root/msg-instance/imta/config/option.dat  

Tailor File (mandatory)  

File to specify locations. server_root/msg-instance/imta/config/imta_tailor  

Job Controller Configuration File (mandatory)  

Configuration file used by the Job Controller. server_root/msg-instance/imta/config/job_controller.cnf  

Table 5-2 lists the MTA database files with a short description.

Table 5-2    MTA Database Files 

File

Description

Address Reversal Database)  

Used to change addresses in outgoing mail. This database is created using the imsimta dirsync command and is not editable directly. DO NOT EDIT. server_root/msg-instance/imta/db/reversedb.db  

Alias Database (mandatory)  

Implements aliases, mail forwarding, and mailing lists. Changes should be made to the directory and running imsimta dirsync. DO NOT EDIT. server_root/msg-instance/imta/db/aliasesdb.db  

Domain Database  

Used for Storing additional rewriting rules. DO NOT EDIT. server_root/msg-instance/imta/db/domaindb.db  

General Database  

Used with domain rewriting rules or in mapping rules, for site-specific purposes. server_root/msg-instance/imta/db/generaldb.db  

Profile Database

(mandatory)  

Database to store program delivery, file delivery, and other special delivery mechanism information. This database is also created from information in the directory during imsimta dirsync. DO NOT EDIT. server_root/msg-instance/imta/db/profiledb.db  



imta.cnf File


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


Structure of the imta.cnf File

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.


Comments in the File

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.
! Part I: Rewrite rules
!
ims-ms.my_server.siroe.com $E$U@ims-ms-daemon
!
! Part II: Channel definitions

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.


Including Other Files

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 /usr/iplanet/server5/msg-tango/table/internet.rules file.
</usr/iplanet/server5/msg-tango/table/internet.rules

Note Any files included in the configuration file must be world-readable just as the configuration file is world-readable.




Channel Definitions


The second part of an MTA 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 the MTA 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 5-3 for more information.

The following imta.cnf file fragment displays a sample channel block:
[blank line]
! sample channel block
channelname keyword1 keyword2
routing_system
[blank line]

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



Channel Configuration Keywords


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 5-3; 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 which will be required from a process in order to enqueue mail to the channel. The imsimta test -rewrite utility tells you whether you have any keywords in your configuration file that don't match any known rights list identifier.

Table 5-3    Channel Keywords 

Keyword

Usage

addrsperfile  

Number of addresses per message file.  

addrsperjob  

Number of addresses to be processed by a single job.  

allowetrn  

Honor all ETRN commands.  

allowswitchchannel  

Allow switching to this channel from an allowswitchchannel channel.  

authrewrite  

Use SMTP AUTH information in header.  

bangoverpercent  

Group A!B%C as A!(B%C).  

bidirectional  

Channel is served by both a master and slave program.  

blocketrn  

Do not honor ETRN commands.  

blocklimit  

Maximum number of MTA blocks allowed per message.  

cacheeverything  

Cache all connection information.  

cachefailures  

Cache only connection failure information.  

cachesuccesses  

Cache only connection success information.  

charset7  

Default character set to associate with 7-bit text messages.  

charset8  

Default character set to associate with 8-bit text messages.  

charsetesc  

Default character set to associate with text containing the escape character.  

checkehlo  

Check the SMTP response banner for whether to use EHLO.  

commentinc  

Leave comments in message header lines intact.  

commentomit  

Remove comments from message header lines.  

commentstrip  

Remove problematic characters from comment fields in message header lines.  

commenttotal  

Strip comments (material in parentheses) everywhere.  

connectalias  

Does not rewrite addresses upon message dequeue.  

connectcanonical  

Rewrite addresses upon message dequeue.  

copysendpost  

Send copies of failures to the postmaster unless the originator address is blank.  

copywarnpost  

Send copies of warnings to the postmaster unless the originator address is blank.  

daemon  

Specify the name of a gateway through which to route mail.  

datefour  

Convert date/time specifications to four-digit years.  

datetwo  

Convert date/time specifications to two-digit years.  

dayofweek  

Include day of week in date and time specifications.  

defaultmx  

Channel determines whether or not to do MX lookups from network.  

deferred  

Honor deferred delivery dates.  

defragment  

Reassemble any MIME-compliant message/partial parts queued to this channel.  

destinationfilter  

Specifies the location of channel filter file that applies to outgoing messages.  

domainetrn  

Tell the MTA to honor only those ETRN commands that specify a domain.  

domainvrfy  

Issue SMTP VRFY commands using full address.  

ehlo  

Use EHLO on all initial SMTP connections.  

eightbit  

Channel supports 8-bit characters.  

eightnegotiate  

Channel should negotiate use of eight bit transmission, if possible.  

eightstrict  

Channel should reject messages that contain unnegotiated 8-bit data.  

errsendpost  

Send copies of failures to the postmaster if the originator address is illegal.  

errwarnpost  

Send copies of warnings to the postmaster if the originator address is illegal.  

expandchannel  

Channel in which to perform deferred expansion due to application of expandlimit.  

expandlimit  

Process an incoming message "offline" when the number of addressees exceeds this limit.  

exproute  

Explicit routing for this channel's addresses.  

fileinto  

Specify effect on address when a mailbox filter fileinto operation is applied.  

filesperjob  

Number of queue entries to be processed by a single job.  

filter  

Specify the location of user filter files.  

forwardcheckdelete  

Effects verification of source IP address.  

forwardchecknone  

No forward lookup is done  

forwardchecktag  

Tell the MTA to do a forward lookup after each reverse lookup.  

headerinc  

Place the message header at the top of the message.  

headerlabelalign  

Align header lines.  

headerlinelength  

Fold long header lines.  

headerread  

Apply header trimming rules from an options file to the message headers upon message enqueue (use with caution).  

headertrim  

Applies header trimming rules from an options file to the message headers (use with caution).  

identnone  

Disable IDENT lookups; 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.  

identnonenumeric  

Disable IDENT lookups and IP-to-hostname translation.  

identnonesymbolic  

Disable this IDENT lookup; perform IP to host name translation. Only the host name will be included in the Received: header for the message.  

identtcp  

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

identtcpnumeric  

Perform IDENT lookups on incoming SMTP connections; disable IP to hostname translation.  

identtcpsymbolic  

Enable IDENT protocol (RFC 1413).  

ignoreencoding  

Ignore Encoding: header on incoming messages.  

immnonurgent  

Start delivery immediately after submission, even for messages with lower-than-normal priority.  

improute  

Implicit routing for this channel's addresses.  

includefinal  

Include final form of address in delivery notifications.  

inner  

Rewrite inner message headers.  

innertrim  

Apply header trimming rules from an options file to inner message headers (use with caution).  

interpretencoding  

Interpret Encoding: header on incoming messages.  

lastresort  

Specify a last-resort host.  

linelength  

Message lines exceeding this length limit are wrapped.  

linelimit  

Maximum number of lines allowed per message.  

localvrfy  

Issue SMTP VRFY command using local address.  

logging  

Log message enqueues and dequeues into the log file.  

mailfromdnsverify  

Setting on an incoming TCP/IP channel causes the MTA 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  

Channel is served only by a master program.  

master_debug  

Generate debugging output in the channel's master program output.  

maxblocks  

Maximum number of MTA blocks per message; longer messages are broken into multiple messages.  

maxheaderaddrs  

Maximum number of addresses per message header line; longer header lines are broken into multiple header lines.  

maxheaderchars  

Maximum number of characters per message header line; longer header lines are broken into multiple header lines.  

maxjobs  

Maximum number of jobs that can be created at one time.  

maxlines  

Maximum number of message lines per message; longer messages are broken into multiple messages.  

maxprocchars  

Specifies maximum length of headers to process.  

maysaslserver  

Cause the SMTP server to permit clients to attempt to use SASL authentication.  

maytls  

SMTP client and server allow TLS use.  

maytlsclient  

SMTP client will attempt TLS use.  

maytlsserver  

SMTP server allows TLS use.  

missingrecipientpolicy  

Controls handling of messages missing recipient header lines.  

multiple  

Accept multiple destination hosts in a single message copy.  

mustsaslserver  

Cause the SMTP server to insist that clients use SASL authentication; the SMTP server will not accept messages unless the remote client successfully authenticates.  

musttls  

SMTP client and server insist upon TLS use and will not transfer messages with remote sides that do not support TLS.  

musttlsclient  

SMTP client insists upon TLS use and will not send messages to any remote SMTP server that does not support TLS use.  

musttlsserver  

SMTP server insists upon TLS user and will not accept messages from any remote SMTP client that does not support TLS use.  

mx  

TCP/IP network and software supports MX record lookups.  

nobangoverpercent  

Group A!B%C as (A!B)%C (default).  

nocache  

Do not cache any connection information.  

nodayofweek  

Remove day of week from date/time specifications.  

nodeferred  

Do not honor deferred delivery dates.  

nodefragment  

Do not perform special processing for message/partial messages.  

nodestinationfilter  

Do not perform channel filtering for outgoing messages.  

noehlo  

Never use the SMTP EHLO command.  

noexproute  

No explicit routing for this channel's addresses.  

nofileinto  

Mailbox filter fileinto operator has no effect.  

nofilter  

Do not perform user mailbox filtering.  

noheaderread  

Do not apply header trimming rules from option file upon message enqueue.  

noheadertrim  

Do not apply header trimming rules from options file.  

noimproute  

No implicit routing for this channel's addresses.  

noinner  

Do not rewrite inner message headers.  

noinnertrim  

Do not apply header trimming to inner message headers.  

nologging  

Do not log message enqueues and dequeues into the log file.  

nomailfromdnsverify  

The MTA does not verify that an entry in the DNS exists for the domain used.  

nomaster_debug  

Do not generate debugging output in the channel's master program output.  

nomx  

TCP/IP network does not support MX lookups.  

nonrandommx  

Perform MX lookups; does not randomize returned entries of equal precedence.  

nonurgentblocklimit  

Force messages above this size to wait unconditionally for a periodic job.  

noreceivedfor  

Do not include Envelope to address in Received: header line.  

noreceivedfrom  

Construct Received: header lines without including the original envelope From: address.  

noremotehost  

Use local host's domain name as the default domain name to complete addresses.  

norestricted  

Do not apply RFC 1137 restricted encoding to addresses.  

noreverse  

Do not apply reverse database to addresses.  

normalblocklimit  

Force messages above this size to nonurgent priority.  

nosasl  

SASL authentication will not be permitted or attempted.  

nosaslserver  

SASL authentication will not be permitted.  

nosendetrn  

Do not send an ETRN command.  

nosendpost  

Do not send copies of failures to the postmaster.  

noserviceall  

Master programs should only process the messages that were queued to process after its inception.  

noslave_debug  

Do not generate slave debugging output.  

nosmtp  

Channel does not use SMTP.  

nosourcefilter  

Do not perform channel filtering for incoming messages.  

noswitchchannel  

Do not switch to the channel associated with the originating host; does not permit being switched to.  

notices  

Specifies the amount of time that may elapse before notices are sent and messages returned.  

notls  

SMTP client and server neither attempt nor allow TLS use.  

notlsclient  

SMTP client does not attempt TLS use when sending messages.  

notlsserver  

SMTP server does not offer or allow TLS use when receiving messages.  

novrfy  

Do not issue SMTP VRFY commands.  

nowarnpost  

Do not send copies of warnings to the postmaster.  

nox_env_to  

Do not add X-Envelope-to header lines while enqueuing.  

personalinc  

Leave personal name fields in message header lines intact.  

personalomit  

Remove personal name fields from message header lines.  

personalstrip  

Strip problematic characters from personal name fields in message header lines.  

pool  

Specifies processing pool master channel programs run in.  

port  

Connect to the specified TCP/IP port.  

postheadbody  

Both the message's header and body are sent to the postmaster when a delivery failure occurs.  

postheadonly  

Only the message's header is sent to the postmaster when a delivery failure occurs.  

randommx  

Perform MX lookups; randomizes returned entries with equal precedence.  

receivedfor  

Includes envelope to address in Received header.  

receivedfrom  

Include the original envelope From: address when constructing Received: header lines.  

remotehost  

Use remote host's name as the default domain name to complete addresses.  

restricted  

Apply RFC 1137 restricted encoding to addresses.  

returnenvelope  

Control use of blank envelope return addresses.  

reverse  

Apply reverse database to addresses.  

saslswitchchannel  

Cause incoming connections to be switched to a specified channel upon a client's successful use of SASL.  

sendpost  

Sends copies of failures to the postmaster.  

sendetrn  

Send an ETRN command, if the remote SMTP server says it supports ETRN.  

sensitivity*  

Set an upper limit on the sensitivity of messages that can be accepted by a channel.  

serviceall  

Specifies that the master program should attempt to process all messages queued to the channel each time it runs.  

sevenbit  

Channel does not support 8-bit characters; 8-bit characters must be encoded.  

silentetrn  

Honor all ETRN commands, but without echoing the name of the channel that the domain matched.  

single  

Only one envelope To: address per message copy.  

single_sys  

Each message copy must be for a single destination system.  

slave  

Channel is serviced only by a slave program.  

slave_debug  

Generate slave debug output.  

smtp  

Channel uses SMTP.  

smtp_cr  

Accept CR as an SMTP line terminator.  

smtp_crlf  

Require CRLF as the SMTP line terminator.  

smtp_lf  

Accept LF as an SMTP line terminator.  

sourceroute  

Use source routes in the message envelope; synonymous with 822.  

sourcefilter  

Specify the location of channel filter file for incoming messages.  

subdirs  

Use multiple subdirectories.  

submit  

Marks the channel as a submit-only channel.  

suppressfinal  

Suppress the final address form from notification messages.  

switchchannel  

Switch from the server channel to the channel associated with the originating host.  

threaddepth  

Number of messages per thread.  

tlsswitchchannel  

Switch to specified channel upon successful TLS negotiation.  

unrestricted  

Do not apply RFC 1137 restricted encoding to addresses.  

urgentblocklimit  

Force messages above this size to normal priority.  

usereplyto  

Specifies mapping of Reply-to header.  

useresent  

Specifies mapping of Resent- headers for non-RFC 822 environments.  

vrfyallow  

Issue a detailed, informative response.  

vrfydefault  

Provide a detailed, informative response, unless the channel option HIDE_VERIFY=1 has been specified.  

vrfyhide  

Issue only a vague, ambiguous response.  

warnpost  

Send copies of warnings to the postmaster.  

x_env_to  

Add X-Envelope-to header lines while enqueuing.  


Address Interpretation (bangoverpercent, nobangoverpercent)

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.



Routing Information in Addresses (exproute, noexproute, improute, noimproute)

The addressing model that the MTA 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 the MTA that the associated channel requires explicit routing when its addresses are passed on to remote systems. If this keyword is specified on a channel, the MTA 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 the MTA 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. The MTA 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. They make 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.


Address Rewriting Upon Message Dequeue (connectalias, connectcanonical)

The MTA 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 the MTA to deliver to whatever host is listed in the recipient address. This is the default. The keyword connectcanonical forces the MTA to run the address through the rewrite rules one additional time and use the resulting host.


Channel Directionality (master, slave, bidirectional)

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 the MTA 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 the MTA supports indicate when and where these keywords should be used.


Channel Service Periodicity (immnonurgent)

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. immnonurgent enables immediate delivery for urgent, normal, and nonurgent messages.


Message Size Affecting Priority (urgentblocklimit, normalblocklimit, nonurgentblocklimit)

The urgentblocklimit, normalblocklimit, and nonurgentblocklimit keywords may be used to downgrade the priority of messages based on their size. This priority, in turn, may affect whether a message is processed immediately, or whether it is left to wait for processing until the next periodic job runs.

The urgentblocklimit keyword instructs the MTA to downgrade messages larger than the specified size to normal priority. The normalblocklimit keyword instructs the MTA to downgrade messages larger than the specified size to nonurgent priority. The nonurgentblocklimit keyword instructs the MTA 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.


Channel Connection Information Caching (cacheeverything, cachesuccesses, cachefailures, nocache)

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 channel that is used to connect to a single unpredictable host does not benefit from caching. Therefore, channel keywords are provided to adjust the MTA'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.


Number of Addresses or Message Files to Handle per Service Job or File (addrsperjob, filesperjob, maxjobs)

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.

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 no such channels are provided with iPlanet Messaging Server 5.0. However, the functionality is provided for third party or site-supplied channels which might be able to make use of such granularity.


Multiple Addresses (multiple, addrsperfile, single, single_sys)

The MTA 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, the MTA 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.)


Expansion of Multiple Addresses (expandlimit)

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.

the MTA provides a special facility to force deferred ("offline") processing if more than a given number of recipient 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.

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 MTA configuration utility, then you should already have such a channel.


Multiple Subdirectories (subdirs)

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


Service Job Queue Usage and Job Deferral (pool)

The MTA creates service jobs (channel master programs) to deliver messages. The Job Controller, which launches these jobs, associates them with pools. Pool types are defined in the job_controller.cnf file. The pool with which each channel's master program is associated can be selected on a channel-by-channel basis, using the pool keyword. The pool keyword must be followed by the name of the pool to which delivery jobs for the current channel should be queued. The name of the pool should not contain more than 12 characters. If the pool keyword is omitted, then the pool used is the default queue, the first queue listed in the Job Controller configuration file.


Deferred Delivery Dates (deferred, nodeferred)

The deferred channel keyword implements recognition and honoring of the Deferred-delivery: header line. 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 line.

The keyword nodeferred is the default. It is important to realize that while support for deferred message processing is mandated by RFC 1327, actual implementation of it effectively lets people use the mail system as an extension of their disk quota.


Undeliverable Message Notification Times (notices)

The notices keyword controls the amount of time an undeliverable message is silently retained in a given channel queue. The MTA is capable of returning a series of warning messages to the originator and, if the message remains undeliverable, the MTA 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.
tcp_local charset7 us-ascii charset8 iso-8853-1 notices 1 2 3 mail.alpha.com

The defaults channel appears immediately after the first blank line in the configuration file. It is important that a blank line appear before and after the line defaults notices....


Returned Messages (sendpost, nosendpost, copysendpost, errsendpost)

A channel program may be unable to deliver a message because of long-term service failures or invalid addresses. When this failure occurs, the MTA channel program returns the message to the sender with an accompanying explanation of why the message was not delivered. Optionally, a copy of all failed messages is sent to the local postmaster. This is useful for monitoring message failures, but it can result in 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 the MTA to send a copy of all failed messages to the postmaster unconditionally. copysendpost instructs the MTA 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 the MTA 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 line or a blank envelope From: address.This default behavior does not correspond to any of the keyword settings.


Warning Messages (warnpost, nowarnpost, copywarnpost, errwarnpost)

In addition to returning messages, the MTA 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 the MTA to send a copy of all warning messages to the postmaster unconditionally.

  • copywarnpost-Instructs the MTA 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 the MTA 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 line or a blank envelope From: address. This default behavior does not correspond to any of the keyword settings.


Postmaster Returned Message Content (postheadonly, postheadbody)

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

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.


Including Altered Addresses in Notification Messages (includefinal, suppressfinal)

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

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


Triggering New Threads in Multithreaded Channels (threaddepth)

The multithreaded SMTP client sorts outgoing messages to different destinations to different threads. The threaddepth keyword may be used to instruct the MTA'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).


Channel Protocol Selection (smtp, nosmtp)

These options specify whether or not a channel supports the SMTP protocol and what type of SMTP line terminator the MTA 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 the MTA always generates; this option affects only the handling of incoming material.


SMTP EHLO Command (ehlo, checkehlo, noehlo)

RFC 1651 extends SMTP to allow for the 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 the MTA 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.



Receiving an SMTP ETRN Command (allowetrn, blocketrn, domainetrn, silentetrn)

The allowetrn, blocketrn, domainetrn, and silentetrn keywords control the the MTA response when a sending SMTP client issues the SMTP ETRN command, requesting that the MTA attempt to deliver messages in the MTA queues. allowetrn is the default; the MTA will attempt to honor all ETRN commands. silentetrn tells the MTA to honor all ETRN commands, but without echoing the name of the channel that the domain matched and that the MTA will be attempting to run. blocketrn tells the MTA not to honor ETRN commands. domainetrn tells the MTA to honor only ETRN commands that specify a domain; it also causes the MTA not to echo back the name of the channel that the domain matched and that the MTA will be attempting to run.


Sending an SMTP ETRN Command (sendetrn, nosendetrn)

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 MTA SMTP client sends an ETRN command at the beginning of an SMTP connection. The default is nosendetrn, meaning that the MTA will not send an ETRN command. The sendetrn keyword tells the MTA 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.


SMTP VRFY Commands (domainvrfy, localvrfy, novrfy)

These keywords control the MTA'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 MTA 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 the MTA to issue a VRFY command with just the local part of the address (user). novrfy is the default.


Responding to SMTP VRFY commands (vrfyallow, vrfydefault, vrfyhide)

These keywords control the MTA SMTP server's response when a sending SMTP client issues an SMTP VRFY command. The vrfyallow keyword tells the MTA to issue a detailed, informative response. The vrfydefault tells the MTA to provide a detailed, informative response, unless the channel option HIDE_VERIFY=1 has been specified. The vrfyhide keyword tells the MTA 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.


TCP/IP Port Number (port)

The SMTP over TCP/IP channels normally connect 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.


TCP/IP MX Record Support (mx, nomx, defaultmx, randommx, nonrandommx)

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


Specifying a Last Resort Host (lastresort)

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.


Reverse DNS and IDENT Lookups on Incoming SMTP Connections (identtcp, identtcplimited, identtcpnumeric, identtcpsymbolic, identnone, identnonelimited, identnonenumeric, identnonesymbolic, forwardchecknone, forwardchecktag, forwardcheckdelete)

The identtcp keyword tells the MTA 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 lines 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 MTA 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 lines 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 MTA 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 lines 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 MTA 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 lines 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 lines 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 lines. 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 MTA does a forward lookup of an IP name found using a DNS reverse lookup, and if such forward lookups are requested what the MTA 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 MTA 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 MTA 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.


Selecting an Alternate Channel for Incoming Mail (switchchannel, allowswitchchannel, noswitchchannel)

When an SMTP 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.



Host Name to Use When Correcting Incomplete Addresses (remotehost, noremotehost)

The MTA often receives from misconfigured or incompliant mailers and SMTP clients addresses that do not contain a domain name. The MTA attempts to make such addresses legal before allowing them to pass further. The MTA does this by appending a domain name to the address (for example, appends @siroe.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 the MTA 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 MTA hosts.


Legalizing Messages Without Recipient Header Lines (missingrecipientpolicy)

RFC 822 (Internet) messages are required to contain recipient header lines: To:, Cc:, or Bcc: header lines. A message without such header lines 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.

Table 5-4    missingrecipientpolicy Values

Value

Action

0  

Place envelope To: recipients in a To: header line.  

1  

Pass the illegal message through unchanged.  

2  

Place envelope To: recipients in a To: header line.  

3  

Place all envelope To: recipients in a single Bcc: header line.  

4  

Generate a group construct (for example, ;) To: header line, To: Recipients not specified.  

5  

Generate a blank Bcc: header line.  

6  

Reject the message.  

Note that the MISSING_RECIPIENT_POLICY option can be used to set an MTA system default for this behavior.


Eight-Bit Capability (eightbit, eightnegotiate, eightstrict, sevenbit)

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. The MTA 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 the MTA to reject any messages that contain unnegotiated eight-bit data.


Automatic Character Set Labeling (charset7, charset8, charsetesc)

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, charset8, and charsetesc 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 MTA table directory. 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; charsetesc will be used if a message containing only seven bit data happens to contain the escape character. 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 MTA local channels as follows:
l ... charset7 US-ASCII charset8 ISO-8859-1 ...
hostname

If there is no Content-type header in the message, it is added. This keyword also adds the MIME-version: header line if it is missing.


Message Line Length Restrictions (linelength)

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



Channel-Specific Use of the Reverse Database (reverse, noreverse)

The reverse keyword tells the MTA 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.


Inner Header Rewriting (noinner, inner)

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). The MTA normally only interprets and rewrites the outermost set of message headers. The MTA 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 the MTA not to rewrite inner message header lines. It is the default. The keyword inner tells the MTA to parse messages and rewrite inner headers. These keywords can be applied to any channel.


Restricted Mailbox Encoding (restricted, unrestricted)

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 the MTA that the channel connects to mail systems that require this encoding. The MTA 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 the MTA 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.)



Trimming Message Header Lines (headertrim, noheadertrim, headerread, noheaderread, innertrim, noinnertrim)

The MTA 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 MTA 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 MTA to perform header trimming on inner message parts, for example, embedded MESSAGE/RFC822 parts. The noinnertrim keyword, which is the default, tells the MTA not to perform any header trimming on inner message parts.

The headerread keyword instructs the MTA 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 MTA. 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 MTA configuration directory, server_root/msg-instance/imta/config/.


Encoding: Header Line (ignoreencoding, interpretencoding)

The MTA can convert various nonstandard message formats to MIME using the Yes CHARSET-CONVERSION. In particular, the RFC 1154 format uses a nonstandard Encoding: header line. However, some gateways emit incorrect information on this header line, with the result that sometimes it is desirable to ignore this header line. The ignoreencoding keyword instructs the MTA to ignore any Encoding: header line.

Note Unless the MTA has a CHARSET-CONVERSION enabled, such headers are ignored in any case. The interpretencoding keyword instructs the MTA to pay attention to any Encoding: header line, if otherwise configured to do so, and is the default.



Generation of X-Envelope-to: Header Lines (x_env_to, nox_env_to)

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 header lines while the nox_env_to will remove such headers from enqueued messages. The default is nox_env_to.


Envelope to Address in Received: Header Lines (receivedfor, noreceivedfor, receivedfrom, noreceivedfrom)

The receivedfor keyword instructs the MTA that if a message is addressed to just one envelope recipient, to include that envelope to the address in the Received: header line it constructs. The keyword receivedfor is the default. The noreceivedfor keyword instructs the MTA to construct Received header lines without including any envelope addressee information.

The receivedfrom keyword instructs the MTA to include the original envelope From: address when constructing a Received: header line for an incoming message if the MTA 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 MTA to construct Received: header lines without including the original envelope From: address.


Blank Envelope Return Addresses (returnenvelope)

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

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


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


Mapping Reply-to: Header Lines (usereplyto)

The usereplyto keyword controls the mapping of the Reply-to: header line.The default is usereplyto 0, which means to use the channel default behavior, which varies from channel to channel. Table 5-5 indicates the mapping specifications for the Reply-to: header line.

Table 5-5    Reply-to: Header Mapping Options

Value

Action

-1  

Never map Reply-to: addresses to anything.  

0  

Use the channel default mapping of Reply-to: addresses; (varies from channel to channel). This is the default.  

1  

Map Reply-to: to From: if no usable From: address exists.  

2  

If there is a usable Reply-to: address, then map it to From:; otherwise, fall back to the From: address.  


Mapping Resent- Header Lines Using a Gateway to Non-RFC 822 Environments (useresent)

The useresent keyword controls the use of Resent- header lines when using a gateway to environments that do not support RFC 822 header lines. This keyword takes a single integer-valued argument. Table 5-6 lists the values used for mapping the Resent- headers.

Table 5-6    Resent- Header Lines Mapping Options 

Value

Action

+2  

Use any Resent- header lines that are present to generate address information.  

+1  

Use only Resent-From header lines to generate address information; all other Resent- header lines are ignored.  

0  

Do not use Resent- header lines to generate address information. This is the default.  


Comments in Address Header Lines (commentinc, commentomit, commentstrip, commenttotal)

The MTA interprets the contents of header lines only when necessary. However, all registered header lines 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 the MTA to retain comments in header lines. It is the default. The keyword commentomit tells the MTA to remove any comments from addressing headers, for example, To, From, or Cc headers lines.

The keyword commenttotal tells the MTA to remove any comments from all header lines, including Received: header lines; this keyword is not normally useful or recommended. commentstrip tells the MTA to strip any nonatomic characters from all comment fields. These keywords can be applied to any channel.


Personal Names in Address Header Lines (personalinc, personalomit, personalstrip)

During the rewriting process, all header lines 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 the MTA to retain personal names in the headers. It is the default. The keyword personalomit tells the MTA to remove all personal names.The keyword personalstrip tells the MTA to strip any nonatomic characters from all personal name fields. These keywords can be applied to any channel.


Two- or Four-Digit Date Conversion (datefour, datetwo)

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 the MTA's processing of the year field in message header dates. The keyword datefour, the default, instructs the MTA 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 the MTA 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.



Day of Week in Date Specifications (dayofweek, nodayofweek)

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 the MTA's processing of day of the week information. The keyword dayofweek, the default, instructs the MTA 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 the MTA 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.



Automatic Splitting of Long Header Lines (maxheaderaddrs, maxheaderchars)

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.

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


Header Alignment and Folding (headerlabelalign, headerlinelength)

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 header lines with an alignment point of 10 might look like this:
To: joe@siroe.com
From: mary@siroe.com
Subject: Alignment test

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


Automatic Defragmentation of Message/Partial Messages (defragment, nodefragment)

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 the MTA. 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 MTA configuration file in order for the defragment keyword to have any effect. If your configuration was built by the MTA configuration utility, then you should already have such a channel.


Automatic Fragmentation of Large Messages (maxblocks, maxlines)

Some email systems or network transfers cannot handle messages that exceed certain size limits. The MTA 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 MTA block is normally 1024 bytes; this can be changed with the BLOCK_SIZE option in the MTA 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 MTA 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, the MTA 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.


Absolute Message Size Limits (blocklimit, linelimit)

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. The MTA rejects attempts to queue messages containing more blocks than this to the channel. An MTA block is normally 1024 bytes; this can be changed with the BLOCK_SIZE option in the MTA option file.

The keyword linelimit specifies the maximum number of lines allowed in a message. The MTA 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.

The MTA 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, the MTA servers can make them known to mail clients prior to obtaining message recipient information. This simplifies the process of message rejection in some protocols.


Specify Maximum Length Header (maxprocchars)

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


Message Logging (logging, nologging)

The MTA 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 server_root/msg-instance/log/imta/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.


Debugging Channel Master and Slave Programs (master_debug, nomaster_debug, slave_debug, noslave_debug)

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 MTA 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 server_root/msg-instance/log/imta/l_master.log.


Delivery of Deferred Messages (serviceall, noserviceall)

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.


Sensitivity checking (sensitivitynormal, sensitivitypersonal, sensitivityprivate, sensitivitycompanyconfidential)

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 used

Note that the MTA 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.


SMTP AUTH (maysaslserver, mustsaslserver, nosasl, nosaslserver, saslswitchchannel)

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.


Verify the Domain on MAIL FROM: Is In the DNS (mailfromdnsverify, nomailfromdnsverify)

Setting mailfromdnsverify on an incoming TCP/IP channel causes the MTA 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.


Channel Operation Type (submit)

The submit keyword may be used to mark a channel as a submit-only channel. This is normally useful on TCP/IP channels, such as an SMTP server run on a special port used solely for submitting messages.


Filter File Location (filter, nofilter, destinationfilter, nodestinationfilter, sourcefilter, nosourcefilter, fileinto, nofileinto)

The filter keyword may be used on the l and ims-ms channels to specify the location of user filter files for that channel. It takes a required URL argument describing the filter file location. nofilter is the default and means that a user mailbox filters are not enabled of the channel.

The sourcefilter and destinationfilter keywords may be used on general MTA channels to specify a channel-level filter to apply to incoming and outgoing messages, respectively. These keywords take a required URL argument describing the channel filter file location. nosourcefilter and nodestinationfilter are the defaults and mean that no channel mailbox filter is enabled for either direction of the channel.

The fileinto keyword, currently supported only for ims-ms channels when delivering to the Message Store, specifies how to alter an address when a mailbox filter fileinto operator is applied. For ims-ms channels, the usual usage is:

fileinto $U+$S@$D

The folder name should be inserted as a sub-address into the original address, replacing any originally present sub-address.


Use authenticated address from SMTP AUTH in header (authrewrite)

The authrewrite channel keyword may be used on a source channel to have the MTA propagate authenticated originator information, if available, into the headers. Normally the SMTP AUTH information is used, though this may be overridden via the FROM_ACCESS mapping.


Transport Layer Security (maytls, maytlsclient, maytlsserver, musttls, musttlsclient, musttlsserver, notlsclient, notlsserver, tlsswitchchannel)

The maytls, maytlsclient, maytlsserver, musttls, musttlsclient, musttlsserver, notls, notlsclient, notlsserver, and tlsswitchchannel channel keywords are used to configure TLS use during the SMTP protocol by SMTP based channels such as TCP/IP channels. notls is the default, and means that TLS will not be permitted or attempted. It assumes the notlsclient keyword, which means that TLS use will not be attempted by the MTA SMTP client on outgoing connections and the notlsserver keyword, which means that TLS use will not be permitted by the MTA SMTP server on incoming connections. Specifying maytls causes the MTA to offer TLS to incoming connections and to attempt TLS upon outgoing connections. It assumes maytlsclient, which means that the MTA SMTP client will attempt TLS use when sending outgoing messages, if sending to an SMTP server that supports TLS, and maytlsserver, which means that the MTA SMTP server will advertise support for the STARTTLS extension and will allow TLS use when receiving messages. Specifying musttls will cause the MTA to insist upon TLS in both outgoing and incoming connections; email will not be exchanged with remote systems that fail to successfully negotiate TLS use. It assumes musttlsclient, which means that the MTA SMTP client will insist on TLS use when sending outgoing messages and will not send to SMTP servers that do not successfully negotiate TLS use (the MTA will issue the STARTTLS command and that command must succeed), and musttlsserver, which means that the MTA SMTP server will advertise support for the STARTTLS extension and will insist upon TLS use when receiving incoming messages and will not accept messages from clients that do not successfully negotiate TLS use. The tlsswitchchannel keyword is used to cause incoming connections to be switched to a specified channel upon a client's successful TLS negotiation. It takes a required value, specifying the channel to which to switch.



Alias File


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 MTA 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:
user@domain: <address>

user@domain: <address>

The following is an example aliases file:
! A /var/mail user
mailsrv@siroe.com: mailsrv@native-daemon

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


Including Other Files in the Alias File

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

The file specification must be a complete file path specification and the file must have the same protections as the primary 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.



/var/mail Channel Option File


An option file may be used to control various characteristics of the native channel. This local channel option file must be stored in the MTA configuration directory and named native_option (for example, server_root/msg-instance/imta/config/native_option).

Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
option=value

The value may be either a string or an integer, depending on the option's requirements.

Table 5-7    Local Channel Options

Options

Descriptions

FORCE_CONTENT_LENGTH

(0 or 1; UNIX only)  

If FORCE_CONTENT_LENGTH=1, then the MTA adds a Content-length: header line to messages delivered to the native channel, and causes the channel not to use the ">From" syntax when "From" is at the beginning of the line. This makes local UNIX mail compatible with Sun's newer mail tools, but potentially incompatible with other UNIX mail tools.  

REPEAT_COUNT (integer)
SLEEP_TIME (integer)  

In case the user's new mail file is locked by another process when the MTA tries to deliver the new mail, these options provide a way to control the number and frequency of retries the local channel program should attempt. If the file can not be opened after the number of retries specified, the messages will remain in the local queue and the next run of the local channel will attempt to deliver the new messages again.

The REPEAT_COUNT option controls how many times the channel programs will attempt to open the mail file before giving up. REPEAT_COUNT defaults to 30, (30 attempts).

The SLEEP_TIME option controls how many seconds the channel program waits between attempts. SLEEP_TIME defaults to 2 (two seconds between retries).  



SMTP Channel Option Files


An option file may be used to control various characteristics of TCP/IP channels. Such an option file must be stored in the MTA configuration directory (server_root/msg-instance/imta/config) and named x_option, where x is the name of the channel.


Format of the File

Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
option=value

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.


Available SMTP Channel Options

The available options are listed in Table 5-8.

Table 5-8    SMTP Channel Options  

Option

Description

ALLOW_ETRNS_PER_SESSION (integer)  

Limits the number of ETRN commands accepted per session. The default is 1.  

ALLOW_REJECTIONS_BEFORE_DEFERRAL (integer)  

Set a limit on the number of bad RCPT TO: addresses that will be allowed during a single session. That is, after the specified number of To: addresses have been rejected, all subsequent recipients, good or bad, will be rejected with a 4xx error.  

ALLOW_TRANSACTIONS_PER_SESSION (Integer)  

Limits the number of messages allowed per connection. The default is no limit.  

ALLOW_RECIPIENTS_PER_TRANSACTION (Integer)  

Limits the number of recipients allowed per message. The default is no limit.  

ATTEMPT_TRANSACTIONS_PER_SESSION (Integer)  

Limits the number of messages the MTA will attempt to transfer during any one connection session.  

COMMAND_RECEIVE_TIME (Integer)  

Specifies, in minutes, how long to wait to receive general SMTP commands (commands other than those with explicitly specified time-out values set using other specifically named options).  

COMMAND_TRANSMIT_TIME (Integer)  

Specifies, in minutes, how long to spend transmitting general SMTP commands (commands other than those with explicitly specified time-out values set using other specifically named options).  

DATA_RECEIVE_TIME (Integer)  

Specifies, in minutes, how long to wait to receive data during an SMTP dialogue. The default is 60.  

DATA_TRANSMIT_TIME (Integer)  

Specifies, in minutes, how long to spend transmitting data during an SMTP dialogue. The default is 10.  

DISABLE_ADDRESS (0 or 1)  

The MTA SMTP server implements a private command XADR. This command returns information about how an address is routed internally by the MTA as well as general channel information. Releasing such information may constitute a breach of security for some sites. Setting the DISABLE_ADDRESS option to 1 disables the XADR command. The default is 0, which enables the XADR command.  

DISABLE_EXPAND (0 or 1)  

The SMTP EXPN command is used to expand mailing lists. Exposing the contents of mailing lists to outside scrutiny may constitute a breach of security for some sites. The DISABLE_EXPAND option, when set to 1, disables the EXPN command completely. The default value is 0, which causes the EXPN command to work normally.

Note that mailing list expansion can also be blocked on a list-by-list basis by setting the expandable attribute to False in the list's directory entry.  

DISABLE_STATUS (0 or 1)  

The MTA SMTP server implements a private command XSTA. This command returns status information about the number of messages processed and currently in the MTA channel queues. Releasing such information may consisted a breach of security for some sites. Setting the DISABLE_STATUS option to 1 disables the XSTA command. The default is 0, which enables the XSTA command.  

DOT_TRANSMIT_TIME (Integer)  

Specifies, in minutes, how long to spend transmitting the dot (.) terminating the data in an SMTP dialogue. The default is 10.  

HIDE_VERIFY (0 or 1)  

The SMTP VRFY command can be used to establish the legality of an address before using it. This command has been abused by automated query engines in some cases. The HIDE_VERIFY option, when set to 1, tells the MTA not to return any useful information in the VRFY command result. The default value is 0, which causes VRFY to act normally.  

LOG_BANNER (0 or 1)  

The LOG_BANNER option controls whether the remote SMTP server banner line is included in mail.log* file entries when the logging channel keyword is enabled for the channel. A value of 1 (the default) enables logging of the remote SMTP server banner line; a value of 0 disables it.  

LOG_CONNECTION (integer)  

The LOG_CONNECTION option controls whether or not connection information, e.g., the domain name of the SMTP client sending the message, is saved in mail.log file entries and the writing of connection records when the logging channel keyword is enabled for the channel. This value is a decimal integer representing a bit-encoded integer, the interpretation of which is given below:

Bit-0 Value-1: When set, connection information is included in E
   and D log records.

Bit-1 Value-2: When set, connection open/close/fail records are
   logged by message enqueue and dequeue agents such as

   the SMTP and X.400 clients and servers.

Bit-2 Value-4: When set, I records are logged recording ETRN
   events.

Where Bit 0 is the least significant bit.

This channel option defaults to the setting of the global MTA option LOG_CONNECTION as set in the MTA option file. This channel option may be set explicitly to override on a per-channel basis the behavior requested by the global option.  

LOG_TRANSPORTINFO (0 or 1)  

The LOG_TRANSPORTINFO controls whether transport information, such as the sending and receiving side IP addresses and TCP ports, is included in mail.log file entries when the logging channel keyword is enabled for the channel. A value of 1 enables transport information logging. A value of 0 disables it. This channel option defaults to the setting of the global MTA option LOG_CONNECTION as set in the MTA option file.  

MAIL_TRANSMIT_TIME (Integer)  

Specifies, in minutes, how long to spend transmitting the SMTP command MAIL FROM. The default is 10.  

MAX_CLIENT_THREADS  

An integer number indicating the maximum number of simultaneous outbound connections that the client channel program will allow. Note that multiple processes may be used for outbound connections, depending on how you have channel-processing queues set up. This option controls the number of threads per process. The default if this option is not specified is 10.  

RCPT_TRANSMIT_TIME (Integer)  

Specifies, in minutes, how long to spend transmitting the SMTP command RCPT TO. The default is 10.  

STATUS_DATA_RECEIVE_TIME (Integer)  

Specifies, in minutes, how long to wait to receive the SMTP response to your sent data; that is, how long to wait to receive a 550 (or other) response to the dot-terminating-sent data. The default value is 10. See also the STATUS_DATA_RECV_PER_ADDR_TIME, STATUS_DATA_RECV_PER_BLOCK_TIME, and STATUS_DATA_RECV_PER_ADDR_PER_BLOCK_TIME options.  

STATUS_DATA_RECV_PER_ADDR_TIME
(Floating Point Value)  

Specifies an adjustment factor for how long to wait to receive the SMTP response to your sent data based on the number of addresses in the MAIL TO command. This value is multiplied by the number of addresses and added to the base wait time (specified with the STATUS_DATA_RECV_TIME option). The default is 0.083333.  

STATUS_DATA_RECV_PER_BLOCK_TIME (Floating Point Value)  

Specifies an adjustment factor for how long to wait to receive the SMTP response to your sent data based on the number of blocks sent. This value is multiplied by the number of blocks and added to the base wait time (specified with the STATUS_DATA_RECV_TIME option). The default is 0.001666.  

STATUS_DATA_RECV_PER_ADDR_PER_BLOCK_TIME (Floating Point Value)  

Specifies an adjustment factor for how long to wait to receive the SMTP response to your sent data based on the number of addresses (in the MAIL TO command) per number of blocks sent. This value is multiplied by the number of addresses per block and added to the base wait time (specified with the STATUS_DATA_RECV_TIME option). The default is 0.003333.  

STATUS_MAIL_RECEIVE_TIME (Integer)  

Specifies, in minutes, how long to wait to receive the SMTP response to a sent MAIL FROM command. (Also corresponds to the time we wait for the greetings.) The default is 10.  

STATUS_RCPT_RECEIVE_TIME (Integer)  

Specifies, in minutes, how long to wait to receive the SMTP response to a sent RCPT TO command. The default value is 10.  

STATUS_RECEIVE_TIME (Integer)  

Specifies, in minutes, how long to wait to receive the SMTP response to general SMTP commands, (commands other than those with specified time out values set using other specifically named options). The default value is 10.  

STATUS_TRANSMIT_TIME (Integer)  

Specifies, in minutes, how long to spend transmitting the SMTP response to an SMTP command.  

TRACE_LEVEL (0, 1, or 2)  

This option controls whether TCP/IP level trace is included in debug log files. The default value is 0, meaning that no TCP/IP packet traces are included; a value of 1 tells the MTA to include TCP/IP packet traces in any debug log files; a value of 2 tells the MTA to include DNS lookup information as well as TCP/IP packet traces.  



Conversions


There are two broad categories of conversions in the MTA, controlled by two corresponding mapping tables and the MTA conversions file.

The first category is that of character set, formatting, and labelling conversions performed internally by the MTA. The application of such conversions is controlled by the CHARSET-CONVERSION mapping table.

The second category is that of conversions of message attachments using external, third-party programs and site-supplied procedures, such as document convertors. The application of such conversions is controlled by the CONVERSIONS mapping table, and messages requiring such conversions are thereby routed through the MTA conversion channel; the conversion channel executes the site-specified external conversion procedure.

The MTA conversions file is used to specify the details of external CONVERSION table triggered conversions and to specify the details of some internal CHARSET-CONVERSION table triggered conversions.


Character Set Conversion and Message Reformatting Mapping

One very basic mapping table in the MTA is the character set conversion table. The name of this table is CHARSET-CONVERSION. It is used to specify what sorts of channel-to-channel character set conversions and message reformatting should be done.

On many systems there is no need to do character set conversions or message reformatting and therefore this table is not needed. Situations arise, however, where character conversions must be done.

The CHARSET-CONVERSION mapping can also be used to alter the format of messages. Facilities are provided to convert a number of non-MIME formats into MIME. Changes to MIME encodings and structure are also possible. These options are used when messages are being relayed to systems that only support MIME or some subset of MIME. And finally, conversion from MIME into non-MIME formats is provided in a small number of cases.

The MTA will probe the CHARSET-CONVERSION mapping table in two different ways. The first probe is used to determine whether or not the MTA should reformat the message and if so, what formatting options should be used. (If no reformatting is specified the MTA does not bother to check for specific character set conversions.) The input string for this first probe has the general form:
IN-CHAN=in-channel;OUT-CHAN=out-channel;CONVERT

Here in-channel is the name of the source channel (where the message comes from) and out-channel is the name of the destination channel (where the message is going). If a match occurs the resulting string should be a comma-separated list of keywords. The keywords provided are listed in Table 5-9.

Table 5-9    Character set Conversion Keywords 

Keyword

Action

Always  

Force conversion even when conversion channel is an intermediate destination.  

Appledouble  

Convert other MacMIME formats to Appledouble format.  

Applesingle  

Convert other MacMIME formats to Applesingle format.  

BASE64  

Switch MIME encodings to BASE64.  

Binhex  

Convert other MacMIME formats, or parts including Macintosh type and Mac creator information, to Binhex format.  

Block  

Extract just the data fork from MacMIME format parts.  

Bottom  

"Flatten" any message/rfc822 body part (forwarded message) into a message content part and a header part.  

Delete  

"Flatten" any message/rfc822 body part (forwarded message) into a message content part, deleting the forwarded headers.  

Level  

Remove redundant multipart levels from message.  

Macbinary  

Convert other MacMIME formats, or parts including Macintosh type and Macintosh creator information, to Macbinary format.  

No  

Disable conversion.  

QUOTED-PRINTABLE  

Switch MIME encodings to QUOTED-PRINTABLE.  

Record,Text  

Line wrap text/plain parts at 80 characters.  

Record,Text=n  

Line wrap text/plain parts at n characters.  

RFC1154  

Convert message to RFC 1154 format.  

Top  

"Flatten" any message/rfc822 body party (forwarded message) into a header part and a message content part.  

UUENCODE  

Switch MIME encodings to X-UUENCODE.  

Yes  

Enable conversion.  

For more information on character set conversion and message reformatting mapping, see the iPlanet Messaging Server 5.0 Administration Guide.


Conversion File

Configuration of the conversion channel in the MTA 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 MTA conversion file. This is the file specified by the IMT_CONVERSION_FILE option in the MTA tailor file. By default, this is the file server_root/msg-instance/imta/conversions.

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

The rule parameters currently provided are shown in Table 5-10. Parameters not listed in the table are ignored.

Table 5-10    Conversion Parameters  

Parameter

Description

COMMAND  

Command to execute to perform conversion. This parameter is required; if no command is specified, the entry is ignored.  

DELETE  

0 or 1. If this flag is set, the message part will be deleted. (If this is the only part in a message, then a single empty text part will be substituted.)  

DPARAMETER-COPY-n  

A list of the Content-Disposition: parameters to copy from the input body part's Content-Disposition: parameter list to the output body part's Content-Disposition: parameter list; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to copy, as matched by an IN-PARAMETER-NAME-m clause. Wildcards may be used in the argument. In particular, an argument of * means to copy all the original Content-Disposition: parameters.  

DPARAMETER-SYMBOL-n  

Content-disposition parameters to convert to environment variables if present; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to convert, as matched by an IN-DPARAMETER-NAME-m clause. Each DPARAMETER-SYMBOL-n is extracted from the Content-Disposition: parameter list and placed in an environment variable prior to executing the converter.  

IN-A1-FORMAT  

Input A1-format from enclosing message/rfc822 part.  

IN-A1-TYPE  

Input A1-type from enclosing message/rfc822 part.  

IN-CHAN  

Inputs channel to match for conversion (wildcards allowed). The conversion specified by this entry will only be performed if the message is coming from the specified channel.  

IN-CHANNEL  

Synonym for IN-CHAN.  

IN-DESCRIPTION  

Inputs MIME Content-Description.  

IN-DISPOSITION  

Inputs MIME Content-Disposition.  

IN-DPARAMETER-DEFAULT-n  

Inputs MIME Content-Disposition parameter value default if parameter is not present. This value is used as a default for the IN-DPARAMETER-VALUE-n test when no such parameter is specified in the body part.  

IN-DPARAMETER-NAME-n  

Inputs MIME Content-Disposition parameter name whose value is to be checked; n = 0, 1, 2....  

IN-DPARAMETER-VALUE-n  

Inputs MIME Content-Disposition parameter value that must match corresponding IN-DPARAMETER-NAME (wildcards allowed). The conversion specified by this entry is performed only if this field matches the corresponding parameter in the body part's Content-Disposition: parameter list.  

IN-PARAMETER-DEFAULT-n  

Inputs MIME Content-Type parameter value default if parameter is not present. This value is used as a default for the IN-PARAMETER-VALUE-n test when no such parameter is specified in the body part.  

IN-PARAMETER-NAME-n  

Inputs MIME Content-Type parameter name whose value is to be checked; n = 0, 1, 2....  

IN-PARAMETER-VALUE-n  

Inputs MIME Content-Type parameter value that must match corresponding IN-PARAMETER-NAME (wildcards allowed). The conversion specified by this entry is performed only if this field matches the corresponding parameter in the body part's Content-Type parameter list.  

IN-SUBJECT  

Inputs Subject from enclosing MESSAGE/RFC822 part.  

IN-SUBTYPE  

Inputs MIME subtype to match for conversion (wildcards allowed). The conversion specified by this entry is performed only if this field matches the MIME subtype of the body part.  

IN-TYPE  

Inputs MIME type to match for conversion (wildcards allowed). The conversion specified is performed only if this field matches the MIME type of the body part.  

MESSAGE-HEADER-FILE  

 

ORIGINAL-HEADER-FILE  

0 or 1. If set to 1, the original headers or the enclosing MESSAGE/RFC822 part are written to the file represented by the OUTPUT_HEADERS symbol.  

OUT-A1-FORMAT  

Output A1-format.  

OUT-A1-TYPE  

Output A1-type.  

OUT-CHAN  

Outputs channel to match for conversion (wildcards allowed). The conversion specified by this entry will be performed only if the message is destined for the specified channel.  

OUT-CHANNEL  

Synonym for OUT-CHAN.  

OUT-DESCRIPTION  

Outputs MIME Content-Description if it is different than the input MIME Content-Description.  

OUT-DISPOSITION  

Outputs MIME Content-Disposition if it is different than the input MIME Content-Disposition.  

OUT-DPARAMETER-NAME-n  

Outputs MIME Content-Disposition parameter name; n=0, 1, 2...  

OUT-DPARAMETER-VALUE-n  

Outputs MIME Content-Disposition parameter value corresponding to OUT-DPARAMETER-NAME-n.  

OUT-MODE  

Mode in which to read the converted file. This should be one of: BLOCK, RECORD, RECORD-ATTRIBUTE, TEXT.  

OUT-ENCODING  

Encoding to apply to the converted file.  

OUT-PARAMETER-NAME-n  

Outputs MIME Content-Type parameter name; n = 0, 1, 2...  

OUT-PARAMETER-VALUE-n  

Outputs MIME Content-Type parameter value corresponding to OUT-PARAMETER-NAME-n.  

OUT-SUBTYPE  

Outputs MIME type if it is different than the input MIME type.  

OUT-TYPE  

Outputs MIME type if it is different than the input type.  

OVERRIDE-HEADER-FILE  

0 or 1. If set, then headers are read from the OUTPUT_HEADERS symbol, overriding the original headers in the enclosing MESSAGE/RFC822 part.  

OVERRIDE-OPTION-FILE  

If set, the conversion channel reads options from the OUTPUT_OPTIONS symbol.  

PARAMETER-COPY-n  

A list of the Content-Type parameters to copy from the input body part's Content-Type parameter list to the output body part's Content-Type: parameter list; n=0, 1, 2... Takes as argument the name of the MIME parameter to copy, as matched by an IN-PARAMETER-NAME-n clause.  

PARAMETER-SYMBOL-n  

Content-Type parameters to convert to environment variables if present; n = 0, 1, 2... Takes as argument the name of the MIME parameter to convert, as matched by an IN-PARAMETER-NAME-n clause. Each PARAMETER-SYMBOL-n is extracted from the Content-Type: parameter list and placed in an environment variable of the same name prior to executing the converter.  

PART-NUMBER  

Dotted integers: a. b. c... The part number of the MIME body part.  

RELABEL  

0 or 1. This flag is ignored during conversion channel processing.  

SERVICE-COMMAND  

The command to execute to perform service conversion. This parameter is required; if no command is specified, the entry is ignored. Note that this flag causes an entry to be ignored during conversion channel processing; SERVICE-COMMAND entries are instead performed during character set conversion processing.  

TAG  

Input tag, as set by a mail list CONVERSION_TAG parameter.  


Predefined Environment Variables

Table 5-11 shows the basic set of environment variables available for use by the conversion command.

Table 5-11    Environment Variables used by the Conversion Channel 

Environment Variable

Description

INPUT_FILE  

Name of the file containing the original body part. The converter should read this file.  

INPUT_HEADERS  

Name of the file containing the original headers for the enclosing part. The converter should read this file.  

INPUT_TYPE  

Content type of the input message part.  

INPUT_SUBTYPE  

Content subtype of the input message part.  

INPUT_DESCRIPTION  

Content description of the input message part.  

INPUT_DISPOSITION  

Content disposition of the input message part.  

MESSAGE_HEADERS  

Name of the file containing the original headers for an enclosing message. The converter should read this file.  

OUTPUT_FILE  

Name of the file where the converter should store its output. The converter should create and write this file.  

OUTPUT_HEADERS  

Name of the file where the converter should store headers for an enclosing MESSAGE/RFC822 part. The converter should create and write this file.  

OUTPUT_OPTIONS  

Name of the file from which the converter should read options.  

Table 5-12 displays additional override options available for use by the conversion channel. The converter procedure may use these to pass information back to the conversion channel. To set these options, set OVERRIDE-OPTION-FILE=1 in the desired conversion entry and then have the converter procedure set the desired options in the OUTPUT_OPTIONS file.

Table 5-12    Options for passing information back to the conversion channel 

Option

Description

OUTPUT_TYPE  

Content type of the output message part.  

OUTPUT_SUBTYPE  

Content subtype of the output message part.  

OUTPUT_DESCRIPTION  

Content description of the output message part.  

OUTPUT_DIAGNOSTIC  

Text to include in the error text returned to the message sender if a message is forcibly bounced by the conversion channel.  

OUTPUT_DISPOSITION  

Content disposition of the output message part.  

OUTPUT_ENCODING  

Content transfer encoding to use on the output message part.  

OUTPUT_MODE  

Mode with which the conversion channel should write the output message part, hence the mode with which recipients should read the output message part.  

STATUS  

Exit status for the converter.  

Additional environment variables containing Content-Type information can be created as they are needed using the PARAMETER-SYMBOL-n facility.



Mapping File


Many components of the MTA employ table lookup-oriented information. Generally speaking, this sort of table is used to transform (that is, map) an input string into an output string. Such tables, called mapping tables, are usually presented as two columns, the first (or left-hand) column giving the possible input strings and the second (or right-hand) column giving the resulting output string for the input it is associated with. Most of the MTA databases are instances of just this sort of mapping table. The MTA database files, however, do not provide wildcard-lookup facilities, owing to inherent inefficiencies in having to scan the entire database for wildcard matches.

The mapping file provides the MTA 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.


Locating and Loading the Mapping File

All mappings are kept in the MTA mapping file. (This is the file specified with the IMTA_MAPPING_FILE option in the MTA tailor file; by default, this is server_root/msg-instance/imta/config/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.


File Format in the Mapping File

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:
TABLE-1-NAME

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

TABLE-2-NAME

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

.
.
.

TABLE-m-NAME

.
.
.

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.


Including Other Files in the Mapping File

Other files may be included in the mapping file. This is done with a line of the form:
<file-spec

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.


Mapping Operations

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.


Mapping Entry Patterns

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.

Table 5-13    Mapping Pattern Wildcards 

Wildcard  

Description  

%  

Match exactly one character.  

*  

Match zero or more characters, with maximal or "greedy" left-to-right matching  

Back match  

Description  

$ n*  

Match the nth wildcard or glob.  

$_  

Use minimal or "lazy" left-to-right matching.  

$@  

Turn off "saving" of the succeeding wildcard or glob.  

$^  

Turn on "saving" of the succeeding wildcard or glob; this is the default.  

Global wildcard  

Description  

$A%  

Match one alphabetic character, A--Z or a--z.  

$A*  

Match zero or more alphabetic characters, A--Z or a--z.  

$B%  

Match one binary digit (0 or 1).  

$B*  

Match zero or more binary digits (0 or 1).  

$D%  

Match one decimal digit 0--9.  

$D*  

Match zero or more decimal digits 0--9.  

$H%  

Match one hexadecimal digit 0--9 or A--F.  

$H*  

Match zero or more hexadecimal digits 0--9 or A--F.  

$O%  

Match one octal digit 0--7.  

$O*  

Match zero or more octal digits 0--7.  

$S%  

Match one symbol set character, for example, 0--9, A--Z, a--z, _, $.  

$S*  

Match zero or more symbol set characters, for example, 0--9, A--Z, a--z, _, $.  

$T%  

Match one tab or vertical tab or space character.  

$T*  

Match zero or more tab or vertical tab or space characters.  

$X%  

A synonym for $H%.  

$X*  

A synonym for $H*.  

$[ c]%  

Match character c.  

$[ c]*  

Match arbitrary occurrences of character c.  

$[ c 1 c 2 ... c n ]%  

Match exactly one occurrence of character c 1, c 2, or c n.  

$[ c 1 c 2 ... c n ]*  

Match arbitrary occurrences of any characters c 1, c 2, or c n.  

$[ c 1 -c n ]%  

Match any one character in the range c 1 to c n.  

$[ c 1 -c n ]*  

Match arbitrary occurrences of characters in the range c 1 to c n.  

$< IPv4>  

Match an IPv4 address.  

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

All other characters in a pattern just represent and match themselves. In particular, single and double quote characters as well as parentheses have no special meaning in either mapping patterns or templates; they are just ordinary characters. This makes it easy to write entries that correspond to illegal addresses or partial addresses.

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

Note that the imsimta test -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.


IPv4 Matching

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.


Mapping Entry Templates

If the comparison of the pattern in a given entry fails, no action is taken; the scan proceeds to the next entry. If the comparison succeeds, the right side of the entry is used as a template to produce an output string. The template effectively causes the replacement of the input string with the output string that is constructed from the instructions given by the template.

Almost all characters in the template simply produce themselves in the output. The one exception is a dollar sign ($).

A dollar sign followed by a dollar sign, space, or tab produces a dollar sign, space, or tab in the output string. Note that all these characters must be quoted in order to be inserted into the output string.

A dollar sign followed by a digit n calls for a substitution; a dollar sign followed by an alphabetic character is referred to as a "metacharacter." Metacharacters themselves will not appear in the output string produced by a template. See Table 5-14 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.

Table 5-14    Mapping Template Substitutions and Metacharacters  

Substitution sequence

Substitutes

$n  

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

$#...#  

Sequence number substitution.  

$|...|  

Applies specified mapping table to supplied string.  

${...}  

General database substitution.  

$[...]  

Invokes site-supplied routine; substitute in result.  

Metacharacter  

Description  

$C  

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

$E  

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

$L  

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

$R  

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

$?x?  

Mapping entry succeeds x percent of the time.  

$\  

Forces subsequent text to lowercase.  

$^  

Forces subsequent text to uppercase.  

$_  

Leaves subsequent text in its original case.  


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:
PSI$%*::* $1@$0.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 the MTA to continue the mapping from the next entry, which causes the connection attempt to be rejected with an SMTP error and the message: Try again later.
PORT_ACCESS

TCP|*|25|123.45.6.78|* $C$?25?$Y
TCP|*|25|123.45.6.78|* $NTry$ again$ later


Sequence Number Substitutions ($#...#)
A $#...# substitution increments the value stored in an MTA sequence file and substitutes that value into the template. This can be used to generate unique, increasing strings in cases where it is desirable to have a unique qualifier in the mapping table output; for instance, when using a mapping table to generate file names.

Permitted syntax is any one of the following:
$#seq-file-spec|radix|width#
$#seq-file-spec|radix#
$#seq-file-spec#

The required seq-file-spec argument is a full file specification for an already existing MTA sequence file, 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 MTA sequence file referred to in a mapping must already exist. To create an MTA sequence file, use the following command:
touch seq-file-spec

or
cat >seq-file-spec

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


Mapping Table Substitutions ($|...|)
A substitution of the form $|mapping,argument| is handled specially. The MTA looks for an auxiliary mapping table named mapping in the MTA 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 imsimta 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, the MTA uses dlopen and dlsym to dynamically load and call the routine routine from the shared library image. The routine routine is then called as a function with the following argument list:
status = routine (argument, arglength, result, reslength)

The argument and result are 252-byte long character string buffers. The argument and result are passed as a pointer to a character string (for example, in C, as char*). The arglength and reslength are signed, long integers passed by reference. On input, argument contains the argument string from the mapping table template, and arglength the length of that string. On return, the resultant string should be placed in result and its length in reslength. This resultant string 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 the MTA's mapping process to be extended in all sorts of complex ways. For example, in a PORT_ACCESS or ORIG_SEND_ACCESS mapping table, a call to some type of load monitoring service could be performed and the result used to decide whether or not to accept a connection or message.

The site-supplied shared library image image should be world readable.


Address-Reversal Database, REVERSE Mapping and FORWARD Mapping

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

The reverse database is created each time you run the imsimta dirsync command.

The reverse database is generally located in the MTA database directory. The database is the files whose names are specified with the IMTA_REVERSE_DATABASE option in the server_root/msg-instance/imta/config/imta_tailor file, which by default are the files server_root/msg-instance/imta/db/reversedb.*.

If an address is found in the database, the corresponding right side from the database is substituted for the address. If the address is not found, an attempt is made to locate a mapping table named REVERSE in the 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|*@*.siroe.com and $|@siroe.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).

Table 5-15    REVERSE mapping table flags 

Flags

Description

$Y  

Use output as new address.  

$N  

Address remains unchanged.  

$D  

Run output through the reversal database.  

$A  

Add pattern as reverse database entry.  

$F  

Add pattern as forward database entry.  

Flag comparison  

Description  

$:B  

Match only header (body) addresses.  

$:E  

Match only envelope addresses.  

$:F  

Match only forward pointing addresses.  

$:R  

Match only backwards pointing addresses.  

$:I  

Match only message-ids.  

As an example, suppose that the internal addresses at siroe.com are actually of the form user@host.siroe.com, but, unfortunately, the user name space is such that user@hosta.siroe.com and user@hostb.siroe.com specify the same person for all hosts at siroe.com. Then the following, very simple REVERSE mapping may be used in conjunction with the address-reversal database:
REVERSE
* @ *.siroe.com $0@host.siroe.com$Y$D

This mapping maps addresses of the form user@anyhost.siroe.com to user@host.siroe.com. The $D metacharacter causes the address-reversal database to be consulted. The address-reversal database should contain entries of the form:
user@host.siroe.com first.last@siroe.com

The reverse and noreverse channel keywords, and the MTA 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.


FORWARD Address Mapping

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.siroe.com associated with the native channel produces RFC 822 addresses of the general form:
"lastname, firstname"@am.sigurd.siroe.com

or
"lastname,firstname"@am.sigurd.siroe.com

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:
firstname.lastname@am.sigurd.siroe.com

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 MTA option USE_REVERSE_DATABASE is set.
REVERSE

*|mr_gateway|"*,$ *"@am.sigurd.siroe.com $Y"$1,$ $2"@am.sigurd.nocompany.com
*|mr_gateway|"*,*"@am.sigurd.siroe.com $Y"$1,$ $2"@am.sigurd.nocompany.com
*|*|"*,$ *"@am.sigurd.siroe.com $Y$3.$2@am.sigurd.nocompany.com
*|*|"*,*"@am.sigurd.siroe.com $Y$3.$2@am.sigurd.nocompany.com
*|mr_gateway|*.*@am.sigurd.siroe.com $Y"$2,$ $1"@am.sigurd.nocompany.com
*|*|*.*@am.sigurd.siroe.com $Y$2.$3@am.sigurd.nocompany.com

FORWARD

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



Option Files


Global MTA options, as opposed to channel options, are specified in the MTA option file.

The MTA uses an option file to provide a means of overriding the default values of various parameters that apply to the MTA as a whole. In particular, the option file is used to establish sizes of the various tables into which the configuration and alias files are read.


Locating and Loading the MTA Option File

The option file is the file specified with the IMTA_OPTION_FILE option in the IMTA tailor file (server_root/msg-instance/imta/config/imta_tailor). By default, this is server_root/msg-instance/imta//config/option.dat.


Option File Format and Available Options

Option files consist of several lines. Each line contains the setting for one option. An option setting has the form:
option=value

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

Table 5-16    Option File Options  

Options

Description

ACCESS_ERRORS (Integer 0 or 1)  

The MTA 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 the MTA 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 the MTA. Any message exceeding this size will be rejected. By default, the MTA 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)  

The MTA uses the concept of a "block" in several ways. For example, the MTA 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 MTA 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.  

CHANNEL_TABLE_SIZE

(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 the MTA configuration files.  

CONVERSION_SIZE

(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 the MTA'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.  

DOMAIN_HASH_SIZE

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

EXPROUTE_FORWARD

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

HOST_HASH_SIZE

(Integer <= 32,767)  

Controls the size of the channel hosts hash table. Each channel host specified on a channel definition in the MTA 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.  

IMPROUTE_FORWARD

(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 the MTA. Any message exceeding this limit will be rejected. By default, the MTA 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 the MTA 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 MTA 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 MTA 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:

To: MAXIMUM=1

From: MAXIMUM=1

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 the MTA 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 the MTA's log entries.  

LOG_SNDOPR  

Controls the production of syslog messages by the MTA message logging facility.  

LOG_SIZE_BINS  

Specifies the bin sizes 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.  

MAP_NAMES_SIZE

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

MAX_HEADER_BLOCK_USE

(Real Number Between
0 and 1)  

Controls what fraction of the available message blocks can be used by message headers.  

MAX_HEADER_LINE_USE

(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 MTA blocks) a message the MTA 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 the MTA 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 the MTA 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 MTA 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 the MTA should process MIME messages. The default is 100, which means that the MTA will process up to 100 levels of message nesting.  

MAX_MIME_PARTS  

Specify the maximum number of MIME parts that the MTA should process in a MIME message.  

MAX_RECEIVED_LINES (Integer)  

As the MTA 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 MTA 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 the MTA 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 the MTA 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 MTA 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 the MTA'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.  

RETURN_DELIVERY_HISTORY

(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 the MTA are written with a blank envelope address or with the address of the local postmaster. Setting the bit forces the use of the local postmaster address; clearing the bit forces the use of a blank 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 the MTA 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 the MTA generates postmaster messages (for example, bounce messages). By default, the MTA uses the string, Internet Mail Delivery.  

REVERSE_ENVELOPE (0 or 1)  

Controls whether the MTA 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 the MTA will attempt to apply the database to envelope From addresses. A value of 0 will disable this use of the address reversal database.  

SEPARATE_CONNECTION_LOG

(0 or 1)  

Controls whether the connection log information generated by setting LOG_CONNECTION =1 is stored in the usual the MTA 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.  

STRING_POOL_SIZE

(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 the MTA 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 the MTA 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 the MTA uses the alias database as a source of system aliases for local addresses. The default (1), means that the MTA 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 the MTA will check the database if it exists. 0  

USE_ERRORS_TO (0 or 1)  

Controls whether the MTA uses the information contained in Errors-to header lines when returning messages. Setting this option to 1 directs the MTA 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 the MTA 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 5-17.  

USE_WARNINGS_TO (0 or 1)  

Controls whether the MTA uses the information contained in Warnings-to header lines when returning messages. Setting this option to 1 directs the MTA 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.  


Table 5-17    USE_REVERSE_DATABASE Bit Values  

Bit

Value

Usage

0  

1  

When set, address reversal is applied to addresses after they have been rewritten by the MTA address rewriting process.  

1  

2  

When set, address reversal is applied before addresses have had the MTA address rewriting applied to them.  

2  

4  

When set, address reversal will be applied to all addresses, not just to backward pointing addresses.  

3  

8  

When set, channel-level granularity is used with REVERSE mapping. REVERSE mapping table (pattern) entries must have the form (note the vertical bars [|]).

source-channel| destination-channel| address  

4  

16  

When set, channel-level granularity is used with address reversal database entries. Reversal database entries must have the form (note the vertical bars [|]).

source-channel| destination-channel| address

Note that bit 0 is the least significant bit.

The default value for USE_REVERSE_DATABASE is 5, which means that the MTA will reverse envelope From addresses and both backward and forward pointing addresses after they have passed through the normal address rewriting process. Simple address strings are presented to both REVERSE mapping and the reverse database. A value of 0 disables the use of the address reversal completely.  


Header Option Files

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. 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 MTA option files.


Header Option File Location

For header trimming to be applied upon message dequeue, the MTA looks in the config directory (server_root/msg-instance/config/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, the MTA looks in the config directory (server_root/msg-instance/config/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.


Header Option File Format

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: OPTION=VALUE, OPTION=VALUE, OPTION=VALUE, ...

Header-name is the name of a header line that the MTA 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 the MTA 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 the MTA'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 5-18.

Table 5-18    Header options 

Option

Description

ADD (Quoted String)  

Creates a new header line of the given type. The new header line contains the specified string. The header line created by ADD will appear after any existing header lines of the same type. The ADD option cannot be used in conjunction with the header line type; it will be ignored if it is specified as part of an Other option list.  

FILL

(Quoted String)  

Creates a new header line of the given type only if there are no existing header lines of the same type. The new header line contains the specified string. The FILL option cannot be used in conjunction with the header line type; it will be ignored if it is specified as part of an Other option list.  

GROUP

(Integer 0 or 1)  

Controls grouping of header lines of the same type at a particular precedence level. A GROUP value of 0 is the default, and indicates that all header lines of a particular type should appear together. A value of 1 indicates that only one header line of the respective type should be output and the scan over all header lines at the associated level should resume, leaving any header lines of the same type unprocessed. Once the scan is complete it is then repeated in order to pick up any remaining header lines. This header option is primarily intended to accommodate Privacy Enhanced Mail (PEM) header processing.  

MAXCHARS (Integer)  

Controls the maximum number of characters that can appear in a single header line of the specified type. Any header line exceeding that length is truncated to a length of MAXCHARS. This option pays no attention to the syntax of the header line and should never be applied to header lines containing addresses and other sorts of structured information. The length of structured header lines should be controlled with the maxheaderchars and maxheaderaddrs channel keywords.  

MAXIMUM (Integer)  

Controls the maximum number of header lines of this type that may appear. This has no effect on the number of lines; after wrapping, each individual header line can consume. A value of -1 is interpreted as a request to suppress this header line type completely.  

MAXLINES (Integer)  

Controls the maximum number of lines all header lines of a given type may occupy. It complements the MAXIMUM option in that it pays no attention to how many header lines are involved, only to how many lines of text they collectively occupy. As with the MAXIMUM option, headers are trimmed from the bottom to meet the specified requirement.  

PRECEDENCE (Integer)  

Controls the order in which header lines are output. All header lines have a default precedence of zero. The smaller the value, the higher the precedence. Positive PRECEDENCE values will push header lines toward the bottom of the header while negative values will push them toward the top. Equal precedence ties are broken using the MTA's internal rules for header line output ordering.  

RELABEL
(header name)  

Changes a header line to another header line; that is, the name of the header is changed, but the value remains the same. For instance,

X-MSMail-Priority: RELABEL="Priority"

X-Priority: RELABEL="Importance"  



Tailor File


The MTA tailor file (imta_tailor) is an option file in which the location of various MTA components are set. This file must always exist in the server_root/msg-instance/config/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 MTA should be restarted after making any changes to the file. It is preferable to make the changes while the MTA is down.

An option setting has the form:
option=value

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

Table 5-19    tailor File Options 

Option

Description

IMTA_ADMIN_PROPERTY  

Location of the adminserver properties file. The imsimta dirsync utility reads this file to find the domains the MTA is responsible for. The default value is adminserver.properties.  

IMTA_ALIAS_DATABASE  

The alias database. The default is aliasesdb.  

IMTA_ALIAS_FILE  

The MTA aliases file. Aliases not set in the directory, for example, postmaster, are set in this file. The default is aliases.  

IMTA_CHARSET_DATA  

Specifies where the MTA compiled character set data is located. The default is charset_data.  

IMTA_CHARSET_OPTION_FILE  

File used for charset conversion options. The default is option_charset.dat.  

IMTA_COM  

Specifies where the MTA shell scripts are located. The default is server_root/bin/msg-instance/imta/bin/.  

IMTA_CONFIG_DATA  

Compiled configuration for the MTA. The default is server_root/msg-instance/imta/lib/config_data.  

IMTA_CONFIG_FILE  

The MTA configuration file. Rewrite rules and per-channel options are set in this file. The default is server_root/msg-instance/imta/imta.cnf.  

IMTA_CONVERSION_FILE  

File to set rules for the conversion channel. The default is server_root/msg-instance/imta/conversions.  

IMTA_DISPATCHER_CONFIG  

The MTA dispatcher's configuration file. The default is server_root/msg-instance/imta/dispatcher.cnf.  

IMTA_DOMAIN_DATABASE  

Database used to store additional rewrite rules. The default is server_root/msg-instance/imta/db/domaindb  

IMTA_DNSRULES  

The MTA DNS configuration library. The default is server_root/msg-instance/imta/lib/imdnsrules.so.  

IMTA_FORWARD_DATABASE  

Not used.  

IMTA_GENERAL_DATABASE  

Provided for each site's customer usage. Generally, lookups can be embedded in mappings and rewrite rules. The default is server_root/msg-instance/imta/generaldb.  

IMTA_HELP  

Location of the help files for the MTA utility. The default is server_root/msg-instance/imta/lib.  

IMTA_JBC_CONFIG_FILE  

The MTA job_controller's configuration file. The default is server_root/msg-instance/imta/job_controller.cnf.  

IMTA_JBC_SERVICE  

Specifies the host and port for the Job Controller.

Do not edit this option.  

IMTA_LANG  

Locale of the MTA's notary messages. By default it is server_root/msg-instance/imta/locale/C/LC_MESSAGES.  

IMTA_LDAP_SERVER  

Specifies the location of the LDAP directory, searched by the MTA dirsync, autoreply and other programs. The list consists of one or more ldaphost port pairs separated by commas. Each program reads this list and connects to the first directory that it is able to connect to. It connects to port 389, if the port is not specified. The default is just localhostname:389.  

IMTA_LIB  

Directory where the MTA libraries and executables are stored. The default is server_root/msg-instance/imta/lib/.  

IMTA_LIBUTIL  

The MTA utility library. By default it is server_root/msg-instance/lib/libimtautil.so.1.  

IMTA_LOG  

Location of the MTA log files. The default is server_root/msg-instance/imta/log/.  

IMTA_MAPPING_FILE  

File used for setting access control rules, reverse mapping rules, forward mapping rules, and so forth. The default value is server_root/msg-instance/imta/mappings.  

IMTA_NAME_CONTENT_FILE  

Location of file used by the MTA for content-type conversions. The default is server_root/msg-instance/imta/name_content.dat.  

IMTA_OPTION_FILE  

Name of the MTA's option file. The default is server_root/msg-instance/imta/option.dat.  

IMTA_QUEUE  

The MTA message queue directory. The default is server_root/msg-instance/imta/queue.  

IMTA_RETURN_PERIOD  

Controls the return of expired messages and the generation of warnings.The default value for this option is 1. If this options is set to an integer value N, then the associated action will only be performed every N times the return job runs. By default, the return job runs once every day.  

IMTA_RETURN_SPLIT_PERIOD  

Controls splitting of the mail.log file. The default value for this option is 1. If this options is set to an integer value N, then the associated action will only be performed every N times the return job runs. By default, the return job runs once every day.  

IMTA_RETURN_SYNCH_PERIOD  

Controls queue synchronization.The default value for this option is 1. If this options is set to an integer value N, then the associated action will only be performed every N times the return job runs. By default, the return job runs once every day.  

IMTA_REVERSE_DATABASE  

The MTA reverse database. This database is used for rewriting From addresses. The default is server_root/msg-instance/imta/db/reversedb.  

IMTA_ROOT  

Base directory for the MTA installation. The default is server_root/msg-instance/imta/.  

IMTA_SCRATCH  

Directory where the MTA stores its backup configuration files. During a full dirsync temporary database files are also created under this directory.The default is server_root/msg-instance/imta/tmp/.  

IMTA_SYNCH_CACHE_PERIOD  

Controls the queue synchronization by the post program.The default value for this option is 1. If this option is set to an integer value N, then the associated action will only be performed every N times the post job runs. By default the post job runs once every four hours.  

IMTA_TABLE  

The MTA configuration directory. The default is server_root/msg-instance/imta/.  

IMTA_USER  

Name of the postmaster. The default is inetmail. If this is changed be sure to edit the server_root/msg-instance/imta/aliases file to reflect the change to the postmaster address.  

IMTA_USER_PROFILE_DATABASE  

Database used for storing user's vacation, forwarding, and program delivery information. The default is server_root/msg-instance/imta/profiledb.  

IMTA_USER_USERNAME  

Specifies the userid of the subsidiary account the MTA uses for certain "non-privileged" operations—operations which it doesn't want to perform under the usual MTA account. The default is nobody.  

IMTA_VERSION_LIMIT  

Maximum versions of log files to be preserved while purging old log files. The default value is 5.  

IMTA_VERSION_LIMIT_PERIOD  

Controls the frequency of purging of log files by the post job. The default value for this option is 1. If this options is set to an integer value N, then the associated action will only be performed every N times the post job runs. By default the post job runs once every four hours  

IMTA_WORLD_GROUP  

Can perform certain privileged operations as a member of this group. The default is mail.  



Dirsync Option File


This file is used to set options for the dirsync program that cannot be set through the command line. This file (dirsync.opt) should be located in the MTA configuration directory. 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:
option=value

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:

Table 5-20    dirsync File Options

Option

Description

IMTA_DL_DIR  

Directory where the distribution lists member's list files are stored. Default value is server_root/msg-instance/imta/dl/.  

IMTA_DL_HASHSIZE  

Maximum number of subdirectories under the dl directory. This number must be a prime number. Default value is 211.  

IMTA_PROGRAM_CONFIG  

File where information about delivery programs are stored. The default is server_root/msg-instance/imta/config/program.opt.  

IMTA_PROGRAM_DIR  

Location of the programs used for program delivery. The default is server_root/msg-instance/imta/programs/.  

USER_SPEC_INTERNAL  

Used to create aliases and domain rewrite rules for hosted domains (%u?%d is the default). Where %u is replaced by the user part and %d is replaced by the domain part.  

USER_SPEC  

Used to create addresses for a channel for which no spec has been specified in the channel option file. (This does not apply to the default channels.)  



Autoreply Option File


This file is used for setting options for the autoreply or vacation program. This file should be located in the MTA configuration directory. 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:
option=value

The value may be either a string or an integer, depending on the option's requirements.

The available options are:

Table 5-21    autoreply File Options

Option

Description

DEBUG  

Determines whether a trace file is created for each autoreply. The default is 0 and this facility is off. A value of 1 creates an autoreply trace file for each autoreply sent in the MTA log directory. A value of 3 puts more information in the trace file.  

RESEND_TIMEOUT  

If mail arrives for a recipient with autoreply on, an autoreply is not sent if a certain period has not elapsed since the last autoreply was sent from this recipient to this specific sender. This option sets the time in hours, after which an autoreply is sent to the same sender again. The default, if this option is not set, is 168 (for example, once a week).  



Job Controller


The Job Controller ensures that there is a channel job running to deliver the message each time a message is enqueued to a channel. This might involve starting a new job process, adding a thread, or simply noting that a job is already running. If a job cannot be started because the job limit for the channel or pool (i.e., the maxjobs keyword value for the channel or the Job Controller JOB_LIMIT option for the pool, respectively) has been reached, the Job Controller waits until another job has exited, then, when the job limit is no longer exceeded, starts another job.

If a message cannot be delivered on the first attempt, the message is delayed for a period of time determined by the appropriate back-off keyword. As soon as the time specified in the back-off has elapsed, the delayed message is available for delivery, and if necessary, a channel job is started to process the message.

Internally, the Job Controller maintains a set of processing pools. Various channels may be configured to "share resources" by running within the same pool; other channels may be configured to each run in an individual pool dedicated to a particular channel. Within each pool, messages are automatically sorted into different processing queues according to the message priority; higher priority messages in a pool are processed before lower priority messages in that pool.

The Job Controller's in-memory data structure of messages currently being processed and awaiting processing typically reflects the full set of message files stored on disk in the MTA queue area. However, if a backlog of message files on disk builds up large enough to exceed the Job Controller's in-memory data structure size limit (see the MAX_MESSAGES option), then the Job Controller tracks in-memory only a subset of the total number of message files on disk, and works for awhile only on those messages it is tracking in-memory; once a sufficient number of messages have been delivered to free up in-memory storage space, the Job Controller will automatically refresh its in-memory store (that is, scan the MTA queue area) to update its list of messages and begin processing the additional message files that meantime have been waiting patiently on disk. Such automatic rescans of the MTA queue area are not normally apparent to sites; they are automatically performed as needed. However, sites that routinely experience extremely heavy message backlogs may wish to tune the Job Controller's behavior in this respect by using the MAX_MESSAGES option. By increasing the MAX_MESSAGES option value to allow the Job Controller to use more memory, sites can reduce the occasions when message backlogs overflow the Job Controller's in-memory cache, thereby reducing the overhead involved when the Job Controller must rescan the MTA queue directory; on the other hand, when the Job Controller does need to rescan the rebuilding of the in-memory cache will take longer (the in-memory cache being bigger). Note also that, since the Job Controller must rescan the MTA queue directory every time it is started or restarted, large message backlogs (especially if a site has increased MAX_MESSAGES beyond its default size), mean that starts or restarts of the Job Controller will incur more overhead than starts or restarts when no such backlog exists.


Job Controller Configuration

At startup, the job controller reads a configuration file that specifies parameters, pools, and channel processing information. This configuration information is specified in the file job_controller.cnf in the server_root/msg-instance/imta/config/ directory.


Job Controller Configuration File

In accordance with the format of the MTA option files, the job controller configuration file contains lines of the form:
option=value

In addition to option settings, the file may contain a line consisting of a section and value enclosed in square-brackets ([ ]) in the form:
[section-type=value]

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 POOL, to define pools and their parameters, and CHANNEL, to define channel processing information.

Table 5-22 shows the available options.

Table 5-22    Job Controller Configuration File Options 

Option

Description

ANON_HOST=0 or 1  

Specifies whether or not the destination host name is useful for job scheduling. The default is 1. ANON_HOST=0 should be specified for TCP channels.  

DEBUG=integer  

If DEBUG is set to a value other than zero, the MTA writes debugging information to a file in the server_root/msg-instance/imta/log directory named job_controller.uniqueid, where uniqueid is a unique ID string that distinctively identifies the file name. The imsimta purge utility recognizes the uniqueids and can be used to remove older log files. The value for DEBUG is a bit mask specifying what sort of debugging information is requested:

  • 1—Trace protocol messages between the job controller and other MTA components.

  • 2—More detailed analysis of the messages and interactions.

  • 4—State change events.

  • 8—Trace rebuild decisions.

  • 16—Dump each pools on every pools action.

  • 32—Be cautious about deleting items from pools.

Specifying bit 16 can cause log files to grow very quickly. Specifying 32 does not generate any more output, and should only be used in extreme cases. If DEBUG is not specified, it defaults to 0.  

JOB_LIMIT=integer  

Specifies the maximum number of processes that the pool can use simultaneously (in parallel). The JOB_LIMIT applies to each pool individually; the maximum total number of jobs is the sum of the JOB_LIMIT parameters for all pools. If set outside of a section, it is used as the default by any [POOL] section that doesn't specify JOB_LIMIT. This option is ignored inside of a [CHANNEL] section.  

MASTER_COMMAND=file specification  

Specifies the full path to the command to be executed by the UNIX system process created by the job controller to run the channel and dequeue messages outbound on that channel. If set outside of a section, it is used as the default by any [CHANNEL] section that doesn't specify a MASTER_COMMAND. This option is ignored inside of a [POOL] section.  

MAX_LIFE_AGE=integer  

Specifies the maximum life time for a master program in seconds. If this parameter is not specified for a channel, then the global default value is used. If no default value is specified, 1800 (30 minutes) is used.  

MAX_LIFE_CONNS=integer  

In addition to the maximum life age parameter, the life expectancy of a master channel is limited by the number of times it can ask the Job Controller if there are any messages. If this parameter is not specified for a channel, then the global default value is used. If no default value is specified, 300 is used.  

MAX_MESSAGES=integer  

The Job Controller keeps information about messages in an in-memory structure. In the event that a large backlog builds, it may need to limit the size of this structure. If the number of messages in the backlog exceeds the parameter specified here, information about subsequent messages is not kept in memory. Mail messages are not lost because they are always written to disk, but they will not be considered for delivery until the number of messages known by the Job Controller drops to half this number. At this point, the Job Controller scans the pool directory mimicking an imsimta cache -sync command.  

PURGE_ARGV=string  

The parameter that is passed to the job specified by PURGE_JOB.  

PURGE_JOB=file_spec  

Cleans up old log files.  

PURGE_TIME=time_spec  

Specifies when and how often the purge job is run. By default, this is /04:00 or every four hours from when the Job Controller started.  

RETURN_ARGV=string  

The parameter passed to the job specified by RETURN_JOB.  

RETURN_JOB=file_spec  

A periodic job that is started by the Job Controller.  

RETURN_TIME=time_spec  

Specifies when and how often the return job is run. By default, this is 00:30/24:00 or every day at 12:30 AM.  

SECRET=file_spec  

Shared secret used to protect requests sent to the Job Controller.  

SLAVE_COMMAND=file_spec  

Specifies the full path to the command to be executed by the UNIX system process created by the job controller in order to run the channel and poll for any messages inbound on the channel. Most MTA channels do not have a SLAVE_COMMAND. If that is the case, the reserved value NULL should be specified. If set outside of a section, it is used as the default by any [CHANNEL] section that doesn't specify a SLAVE_COMMAND. This option is ignored inside of a [POOL] section.  

SYNCH_TIME=time_spec  

The Job Controller occasionally scans the pool files on disk to check for missing files. By default, this takes place every four hours, starting four hours after the Job Controller is started. The format of the time_spec is HH:MM/hh:mm or /hh:mm. hh.mm is the interval between the events in hours and minutes. HH:MM is the first time in a day the even should take place. For example specifying, 15:45/7:15 starts the event at 15:45 and every seven hours and fifteen minutes from then.  

TCP_PORT=integer  

Specifies the TCP port on which the job controller should listen for request packets. Do not change this unless the default conflicts with another TCP application on your system. If you do change this option, change the corresponding IMTA_JBC_SERVICE option in the MTA tailor file, server_root/msg-instance/imta/config/imta_tailor, so that it matches. The TCP_PORT option applies globally and is ignored if it appears in a [CHANNEL] or [POOL] section.  



Dispatcher


The MTA multithreaded Dispatcher is a multithreaded connection dispatching agent that permits multiple multithreaded servers to share responsibility for a given service. When using the Dispatcher, it is possible to have several multithreaded SMTP, POP3, and IMAP servers running concurrently. In addition to having multiple servers for a single service, each server may handle simultaneously one or more active connections.


Dispatcher Configuration File

The Dispatcher configuration information is specified in the server_root/msg-instance/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.


Configuration File Format

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

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

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

The following is a sample Dispatcher configuration file (dispatcher.cnf).
! The first set of options, listed without a [SERVICE=xxx]
! header, are the default options that will be applied to all
! services.
!
MIN_PROCS=0
MAX_PROCS=5
MIN_CONNS=5
MAX_CONNS=20
MAX_LIFE_TIME=86400
MAX_LIFE_CONNS=100
MAX_SHUTDOWN=2
!
! Define the services available to Dispatcher
!
[SERVICE=SMTP]
PORT=25
IMAGE=server_root/msg-instance/imta/lib/tcp_smtp_server
LOGFILE=server_root/msg-instance/imta/log/tcp_smtp_server.log

Table 5-23 shows the available options.

Table 5-23    Dispatcher configuration file options 

Option

Description

BACKLOG=integer  

Controls the depth of the TCP backlog queue for the socket. The default value for each service is MAX_CONNS*MAX_PROCS (with a minimum value of 5). This option should not be set higher than the underlying TCP/IP kernel supports.  

DEBUG  

Enables debugging output. 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 5-24.  

ENABLE_RBL=0 or 1  

Specifying ENABLE_RBL=1 causes the Dispatcher to compare incoming connections to the "Black Hole" list at maps.vix.com. For instance, if the Dispatcher receives a connection from 192.168.51.32, then it will attempt to obtain the IP address for the hostname 32.51.168.192.rbl.maps.vix.com. If the query is successful, the connection will be closed rather than handed off to a worker process. If this option is enabled on a well-known port (25, 110, or 143), then a standard message such as the one below will be sent before the connection is closed:

5.7.1 Mail from 192.168.51.32 refused, see http://maps.vix.com/rbl/

If you want the MTA to log such rejections, set the 24th bit of the Dispatcher debugging DEBUG option, DEBUG=16%1000000, to cause logging of the rejections to the dispatcher.log file; entries will take the form:

access_control: host a.b.c.d found on RBL list and rejected  

HISTORICAL_TIME=integer  

Controls how long the expired connections (those that have been closed) and processes (those that have exited) remain listed for statistical purposes.  

INTERFACE_ADDRESS=IP address  

The INTERFACE_ADDRESS option can be used to specify the IP address interface to which the Dispatcher service should bind. By default, the Dispatcher binds to all IP addresses. But for systems having multiple network interfaces each with its own IP address, it may be useful to bind different services to the different interfaces. Note that if INTERFACE_ADDRESS is specified for a service, then that is the only interface IP address to which that Dispatcher service will bind. Only one such explicit interface IP address may be specified for a particular service (though other similar Dispatcher services may be defined for other interface IP addresses).  

IDENT=0 or 1  

If IDENT=1 is set for a service, it causes the Dispatcher to try an IDENT query on incoming connections for that service, and to note the remote username (if available) as part of the Dispatcher statistics. The default is IDENT=0, meaning that no such query is made.  

IMAGE=file specification  

Specifies the image that is run by server processes when created by the Dispatcher. The specified image should be one designed to be controlled by the Dispatcher.  

LOGFILE=file specification  

Causes the Dispatcher to direct output for corresponding server processes to the specified file. LOGFILE can include a %s which includes the local system's hostname in the file specification. For example, LOGFILE=tcp_smtp_server_%s.log on node freddy will result in log files with the name tcp_smtp_server_freddy.log-*.  

MAX_CONNS=integer  

Affects the Dispatcher's management of connections. This value specifies a maximum number of connections that may be active on any server process.  

MAX_HANDOFFS=integer  

Specifies the maximum number of concurrent asynchronous hand-offs in progress that the Dispatcher will allow for newly established TCP/IP connections to a service port. The default value is 5.  

MAX_IDLE_TIME=integer  

Specifies the maximum idle time for a server process. When an server process has had no active connections for this period, it becomes eligible for shutdown. This option is only effective if there are more than the value of MIN_PROCS server processes currently in the Dispatcher's pool for this service.  

MAX_LIFE_CONNS  

Specifies the maximum number of connections an server process can handle in its lifetime. Its purpose is to perform worker-process housekeeping.  

MAX_LIFE_TIME=integer  

Requests that server processes be kept only for the specified number of seconds. This is part of the Dispatcher's ability to perform worker-process housekeeping. When an server process is created, a countdown timer is set to the specified number of seconds. When the countdown time has expired, the SMTP server process is subject to shutdown.  

MAX_PROCS=integer  

Controls the maximum number of server processes that are created for this service.  

MAX_SHUTDOWN=integer  

Specifies the maximum number of server processes available before the Dispatcher shuts down. In order to provide a minimum availability for the service, the Dispatcher does not shut down server processes that might otherwise be eligible for shutdown if shutting them down results in having fewer than MAX_SHUTDOWN server processes for the service. This means that processes that are eligible for shutdown can continue running until a shutdown "slot" is available.  

MIN_CONNS=integer  

Determines the minimum number of connections that each server process must have before considering the addition of a new server process to the pool of currently available server processes. The Dispatcher attempts to distribute connections evenly across this pool.  

MIN_PROCS=integer  

Determines the minimum number of server processes that are created by the Dispatcher for the current service. Upon initialization, the Dispatcher creates this many detached processes to start its pool. When a process is shut down, the Dispatcher ensures that there are at least this many available processes in the pool for this service.  

PARAMETER  

The interpretation and allowed values for the PARAMETER option are service specific. In the case of an service, the PARAMETER option may be set to CHANNEL=channelname, to associate a default TCP/IP channel with the port for that service. For instance:

[SERVICE=SMTP_SUBMIT]

PORT=587

...

PARAMETER=CHANNEL=tcp_incoming

This can be useful if you want to run servers on multiple ports—perhaps because your internal POP and IMAP clients have been configured to use a port other than the normal port 25, thus separating their message traffic from incoming SMTP messages from external hosts—and if you want to associate different TCP/IP channels with the different port numbers.  

PORT=integer...  

Specifies the TCP port(s) to which the Dispatcher listens for incoming connections for the current service. Connections made to this port are transferred to one of the SMTP server processes created for this service. Specifying PORT=0 disables the current service.  

STACKSIZE  

Specifies the thread stack size of the server. The purpose of this option is to reduce the chances of the server running out of stack when processing deeply nested MIME messages (several hundreds of levels of nesting). Note that these messages are in all likelihood spam messages destined to break mail handlers. Having the server fail will protect other mail handlers farther down the road.  


Debugging and Log Files

Dispatcher error and debugging output (if enabled) are written to the file dispatcher.log in the MTA 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 5-24.

Table 5-24    Dispatcher Debugging Bits 

Bit

Hexadecimal
value

Decimal
value

Usage

0  

x 00001  

1  

Basic Service Dispatcher main module debugging.  

1  

x 00002  

2  

Extra Service Dispatcher main module debugging.  

2  

x 00004  

4  

Service Dispatcher configuration file logging.  

3  

x 00008  

8  

Basic Service Dispatcher miscellaneous debugging.  

4  

x 00010  

16  

Basic service debugging.  

5  

x 00020  

32  

Extra service debugging.  

6  

x 00040  

64  

Process related service debugging.  

7  

x 00080  

128  

Not used.  

8  

x 00100  

256  

Basic Service Dispatcher and process communication debugging.  

9  

x 00200  

512  

Extra Service Dispatcher and process communication debugging.  

10  

x 00400  

1024  

Packet level communication debugging.  

11  

x 00800  

2048  

Not used.  

12  

x 01000  

4096  

Basic Worker Process debugging.  

13  

x 02000  

8192  

Extra Worker Process debugging.  

14  

x 04000  

16384  

Additional Worker Process debugging, particularly connection hand-offs.  

15  

x 08000  

32768  

Not used.  

16  

x 10000  

65536  

Basic Worker Process to Service Dispatcher I/O debugging.  

17  

x 20000  

131072  

Extra Worker Process to Service Dispatcher I/O debugging.  

20  

x 100000  

1048576  

Basic statistics debugging.  

21  

x 200000  

2097152  

Extra statistics debugging.  

24  

x 1000000  

16777216  

Log PORT_ACCESS denials to the dispatcher.log file.  


System Parameters on Solaris

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


Previous     Contents     Index          Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated August 15, 2002