Figure 8-1 Simple Configuration File - Channel Definitions
|
! test.cnf - An example configuration file.
!
! Rewrite Rules
.
.
.
! BEGIN CHANNEL DEFINITIONS
! FIRST CHANNEL BLOCK
l
local-host
! SECOND CHANNEL BLOCK
a_channel defragment charset7 usascii
a-daemon
! THIRD CHANNEL BLOCK
b_channel noreverse notices 1 2 3
b-daemon
|
|
The channel host table defines the channels Messaging Server can use and the names of the systems associated with each channel.
On UNIX systems, the first channel block in the file always describes the local channel, l. (An exception is a defaults channel, which can appear before the local channel.) The local channel is used to make routing decisions and for sending mail sent by UNIX mail tools.
Predefined Channels
When you first install iPlanet Messaging Server, several channels are already defined. These channels are described in Table 8-1.
Table 8-1 Predefined Channels
|
Channel
|
Definition
|
|
l
|
UNIX only. Used to make routing decisions and for sending mail using UNIX mail tools.
|
|
ims-ms
|
Delivers mail to the local store.
|
|
native
|
UNIX only. Delivers mail to /var/mail. (Note that Messaging Server does not support /var/mail access. User must use UNIX tools to access mail from the /var/mail store.)
|
|
pipe
|
Used to perform delivery via a site-supplied program or script. Commands executed by the pipe channel are controlled by the administrator via the imsimta program interface. For more information, see Setting Up Program Delivery.
|
|
tcp_local
tcp_intranet
tcp_auth
tcp_submit
tcp_tas
|
Implements SMTP over TCP/IP. The multithreaded TCP SMTP channel includes a multithreaded SMTP server that runs under the control of the Dispatcher. Outgoing SMTP mail is processed by the channel program tcp_smtp_client, and runs as needed under the control of the Job Controller.
tcp_local receives inbound messages from remote SMTP hosts. Depending on whether you use a smarhost/firewall configuration, either sends outbound messages directly to remote SMTP hosts or sends outbound messages to the smarthost/firewall system.
tcp_intranet receives and sends messages within the intranet.
tcp_auth is used as a switch channel for tcp_local; authenticated users switch to the tcp_auth channel to avoid realy-blocking restrictions.
tcp_submit accepts message submissions—usually from user agents—on the reserved submission port 587 (see RFC 2476).
tcp_tas is a special channel used by sites doing Unified Messaging.
|
|
reprocess
process
|
These channels are used for deferred, offline message processing. The reprocess channel is normally invisible as a source or destination channel; the process channel is visible like other MTA channels.
|
|
defragment
|
Provides the means to reassemble MIME fragmented messages.
|
|
conversion
|
Performs body-part-by-body-part conversions on messages flowing through the MTA.
|
|
bitbucket
|
Used for messages that need to be discarded.
|
|
inactive/deleted
|
Used to process messages for users who have been marked as inactive/deleted in the directory. Typically, bounces the message and returns custom bounce message to the sender of the message.
|
|
hold
|
Used to hold messages for users. For example, when a user is migrated from one mail server to another.
|
|
autoreply
|
Used to process autoreply and vacation notice requests.
|
Configuring SMTP Channels
Depending on the type of installation, Messaging Server provides several SMTP channels at installation time: tcp_local, tcp_intranet, tcp_submit, tcp_auth, tcp_tas. You can modify the definitions of these channels or create new channels.
This section is divided into the following subsections:
SMTP Command and Protocol Support
You can specify whether an SMTP channel supports certain SMTP commands, such as EHLO, ETRN, and VRFY. You can also specify whether the channel support DNS domain verification, which characters the channel accepts as line terminators, and so on. This section describes the following:
Table 8-2 summarizes the keywords described in this section.
Table 8-2 SMTP Command and Protocol Keywords
|
Channel Keyword(s)
|
Description
|
|
Protocol Selection and Line Terminators
|
Specifies whether the channel supports the SMTP protocol and specifies the character sequences accepted as line terminators.
|
|
smtp
|
Supports the SMTP protocol. The keyword smtp is mandatory for all SMTP channels. (This keyword is equivalent to smtp_crorlf.)
|
|
nosmtp
|
Does not support the SMTP protocol. This is the default.
|
|
smtp_cr
|
Accepts lines terminated with a carriage return (CR) without a following line feed (LF).
|
|
smtp_crlf
|
Lines must be terminated with a carriage return (CR) line feed (LF) sequence.
|
|
smtp_lf
|
Accepts lines terminated with a linefeed (LF) without a preceding CR.
|
|
smtp_crorlf
|
Lines may be terminated with any of a carriage return (CR), or a line feed (LF) sequence, or a full CRLF.
|
|
EHLO keywords
|
Specifies how the channel handles EHLO commands
|
|
ehlo
|
Uses the SMTP EHLO command on initial connections.
|
|
checkehlo
|
Checks the SMTP response banner to determine whether to use EHLO or HELO.
|
|
noehlo
|
Does not use the EHLO command.
|
|
ETRN keywords
|
Specifies how the channel handles ETRN commands (requests for queue processing)
|
|
allowetrn
|
Honors ETRN commands.
|
|
blocketrn
|
Blocks ETRN commands.
|
|
domainetrn
|
Honors only those ETRN commands that specify a domain.
|
|
silentetrn
|
Honors ETRN commands without echoing channel information.
|
|
sendetrn
|
Sends ETRN commands.
|
|
nosendetrn
|
Does not send ETRN commands.
|
|
VRFY keywords
|
Specifies how the channel handles VRFY commands
|
|
domainvrfy
|
Issues VRFY commands using a full address.
|
|
localvrfy
|
Issues VRFY commands using a local address.
|
|
novrfy
|
Does not issue VRFY commands.
|
|
vrfyallow
|
Provides informative responses to VRFY commands.
|
|
vrfydefault
|
Provides default responses to VRFY command, according to channel's HIDE_VERIFY option setting.
|
|
vrfyhide
|
Provides obfuscatory responses to SMTP VRFY command.
|
|
DNS Domain Verification
|
Specifies whether the channel performs DNS domain verification
|
|
mailfromdnsverify
|
Verifies that the domain used on the MAIL FROM: command exists in the DNS.
|
|
nomailfromdnsverify
|
Does not verify that the domain used on the MAIL FROM: command exists in the DNS.
|
|
Character Sets and Eight-bit data
|
Specifies how the channel handles eight-bit data
Note: Although these keywords are commonly used on SMTP channels, they are potentially relevant to any sort of channel.
|
|
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 7-bit text containing the escape character
|
|
eightbit
|
Channel supports eight-bit characters.
|
|
eightnegotiate
|
Channel should negotiate use of eight-bit transmission if possible.
|
|
eightstrict
|
Channel should reject messages that contain unnegotiated eight-bit data.
|
|
sevenbit
|
Channel does not support eight-bit characters; eight-bit characters must be encoded.
|
|
Protocol streaming
streaming
|
Specify degree of protocol streaming for channel to use
|
Channel Protocol Selection and Line Terminators
The smtp and nosmtp keywords specify whether or not a channel supports the SMTP protocol. The smtp keyword, or one of its variations, is mandatory for all SMTP channels.
The keywords smtp_crlf, smtp_cr, smtp_crorlf, and smtp_lf can be used on SMTP channels to specify the character sequences that the MTA will 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. These option affect only the handling of incoming material.
Because the SMTP standard requires CRLF as the line terminator, the MTA always generates the standard CRLF sequence. The various smtp keywords merely control whether the MTA will accept additional non-standard line terminators. For example, you can specify stmp_crlf if you want the MTA to accept only strictly legal SMTP messages and reject any messages with nonstandard line terminators.
EHLO Command Support
The SMTP protocol has been extended (RFC 1869) to allow for negotiation of additional commands. This is done by 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 might 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. The ehlo keyword tells the MTA to use the EHLO command on all initial connection attempts. The noehlo keyword disables all use of the EHLO command. The checkehlo keyword 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 that there is no keyword corresponding to this default behavior, which lies between the behaviors resulting from the ehlo and checkehlo keywords.
ETRN Command Support
The ETRN command, defined in RFC 1985, provides an extension to the SMTP service whereby an SMTP client and server can interact to give the server an opportunity to start the processing of its queues for messages to go to a given host.
Using ETRN, an SMTP client can request that a remote SMTP server start processing the message queues destined for sending to the SMTP client. Thus, 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, sites that are set up as secondary mail exchange (MX) hosts for other sites that only have a dial-up connection to the Internet. By enabling this command, you permit remote, possibly dial-up, servers to request delivery of their mail.
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.
Responding to ETRN Commands
The allowetrn, blocketrn, domainetrn, and silentetrn keywords control the MTA response when a sending SMTP client issues the ETRN command, requesting that the MTA attempt to deliver messages in the MTA queues.
By default, the MTA will attempt to honor all ETRN commands; that is, the allowetrn keyword is enabled. You can specify that the MTA not honor ETRN commands by including the blocketrn keyword in the channel definition.
You can specify that the MTA 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 by including the silentetrn keyword. The domainetrn keyword specifies that the MTA 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 ETRN Commands
The sendetrn and nosendetrn channel keywords control whether the MTA 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.
VRFY Command Support
The VRFY command enables SMTP clients to send a request to an SMTP server to verify that mail for a specific user name resides on the server. The VRFY command is defined in RFC 821.
The server sends a response indicating whether the user is local or not, whether mail will be forwarded, and so on. A response of 250 indicates that the user name is local; a response of 251 indicates that the user name is not local, but the server can forward the message. The server response includes the mailbox name.
Sending a VRFY Command
Under normal circumstances there is no reason to issue a VRFY command as part of an SMTP dialogue. The SMTP RCPT 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 RCPT TO (and bounce it later), whereas these same servers perform more extensive checking as part of a VRFY command.
By default, the MTA does not send a VRFY command (the novrfy keyword is enabled).
If necessary, the MTA can be configured to issue the SMTP VRFY command by including the domainvrfy or localvrfy keyword in the channel definition. 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).
Responding to a VRFY Command
The vrfyallow, vrfydefault, and vrfyhide keywords control the 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.
DNS Domain Verification
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. The default, nomailfromdnsverify, means that no such check is performed. Note that performing DNS checks on the return address domain may result in rejecting some desired valid messages (for instance, from legitimate sites that simply 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 may desire to perform such checks in cases where unsolicited bulk email (UBE) is being sent with forged e-mail addresses from non-existent domains.
Character Set Labeling and Eight-Bit Data
Character Set Labeling
The charset7, charset8, and charsetesc channel keywords provide a per-channel mechanism to specify character set names to be inserted into message headers which lack character set labelling. Each keyword requires a single argument giving the character set name. The names are not checked for validity. Note, however, that character set conversion can only be done on character sets specified in the character set definition file charsets.txt found in the MTA table directory. The names defined in this file should be used if possible.
The charset7 character set name is used if the message contains only seven bit characters; the charset8 character set name will be 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 escape characters also. If the appropriate keyword is not specified no character set name will be inserted into 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.
The charsetesc keyword tends to be particularly useful on channels that receive unlabeled messages using Japanese or Korean character sets that contain the escape character.
Eight-Bit Data
Some transports restrict the use of characters with ordinal values greater than 127 (decimal). Most notably, some SMTP servers will strip the high bit and thus garble messages that use characters in this eight-bit range.
Messaging Server 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 enqueued to a given channel by specifying the sevenbit keyword. A channel should be marked eightbit if no such restriction exists.
The SMTP protocol disallows eightbit "unless the remote SMTP server explicitly says it supports the SMTP extension allowing eightbit." Some transports such as extended SMTP may actually support a form of negotiation to determine if eight bit characters can be transmitted. Therefore, the use of the eightnegotiate keyword is strongly recommended to instruct the channel to encode messages when negotiation fails. This is the default for all channels; channels that do not support negotiation will simply assume that the transport is capable of handling eight bit data.
The eightstrict keyword tells Messaging Server to reject any incoming messages that contain unnegotiated eight bit data.
Protocol Streaming
Some mail protocols support streaming operations. This means that the MTA can issue more than one operation at a time and wait for replies to each operation to arrive in batches. The streaming keyword controls the degree of protocol streaming used in the protocol associated with a channel. This keyword requires an integer parameter; how the parameter is interpreted is specific to the protocol in use.
Currently the MTA only supports the experimental use of streaming on SMTP channels. Implementation of this feature is experimental; it may change in future releases.
The streaming values available range from 0 to 3. A value of 0 specifies no streaming, a value of 1 causes groups of RCPT TO commands to stream, a value of 2 causes MAIL FROM/RCPT TO to stream, and a value of 3 causes HELO/MAIL FROM/RCPT TO or RSET/MAIL FROM/RCPT TO streaming to be used. The default value is 0.
Some SMTP implementations are known to react badly to streaming. In particular, sendmail is known to be incapable of handling streaming levels greater than 1. The iPlanet Messaging Server implementation of SMTP should work properly at any streaming level.
TCP/IP Connection and DNS Lookup Support
You can specify information about how the server handles TCP/IP connections and address lookups. This section describes the following:
Table 8-3 lists the TCP/IP connection and DNS lookup keywords described in this section.
Table 8-3 TCP/IP Connection and DNS Lookup Keywords
|
Channel Keyword(s)
|
Description
|
|
Port Selection and Interface Address
|
Specifies the default port number and interface address for SMTP connections
|
|
port
|
Specifies the default port number for SMTP connections. The standard port is 25.
|
|
interfaceaddress
|
Binds to the specified TCP/IP interface address.
|
|
Cache Keywords
|
Specifies how connection information is cached
|
|
cacheeverything
|
Caches all connection information.
|
|
cachefailures
|
Caches only connection failure information.
|
|
cachesuccesses
|
Caches only connection success information.
|
|
nocache
|
Does not cache any connection information.
|
|
DNS Lookups
|
Specifies how to handle DNS lookups on incoming SMTP connections
|
|
forwardcheckdelete
|
If a reverse DNS lookup has been performed, next performs a forward lookup on the returned name to check that the returned IP number matches the original; if not, deletes the name and use the IP address.
|
|
forwardchecknone
|
Does not perform a forward lookup after a DNS reverse lookup.
|
|
forwardchecktag
|
If a reverse DNS lookup has been performed, next performs a forward lookup on the returned name to check that the returned IP number matches the original; if not, tags the name with *.
|
|
IDENT Lookups/DNS Reverse Lookups
|
Specifies how to handle IDENT lookups and DNS Reverse Lookups on incoming SMTP connections
|
|
identnone
|
Does not perform IDENT lookups; does perform IP to hostname translation; includes both hostname and IP address in Received: header.
|
|
identnonelimited
|
Does not perform IDENT lookups; does perform IP to hostname translation, but does not use the hostname during channel switching; includes both hostname and IP address in Received: header.
|
|
identnonenumeric
|
Does not perform IDENT lookups or IP to hostname translation.
|
|
identnonesymbolic
|
Does not perform IDENT lookups; does perform IP to hostname translation; includes only the hostname in Received: header.
|
|
identtcp
|
Performs IDENT lookups on incoming SMTP connections and IP to hostname translation; include both hostname and IP address in Received: header
|
|
identtcplimited
|
Performs IDENT lookups on incoming SMTP connections and IP to hostname translation, but do not use the hostname during channel switching. Includes both hostname and IP address in Received: header.
|
|
indenttcpnumeric
|
Performs IDENT lookups on incoming SMTP connections, but does not perform IP to hostname translation.
|
|
identtcpsymbolic
|
Performs IDENT lookups on incoming SMTP connections and IP to hostname translation; includes only hostname in Received: header.
|
|
MX Record Support and TCP/IP Nameserver
|
Specifies whether and how the channel supports MX record lookups
|
|
mx
|
TCP/IP network and software supports MX records lookup.
|
|
nomx
|
TCP/IP network does not support MX lookups.
|
|
defaultmx
|
Channel determines whether to do MX lookups from network.
|
|
randommx
|
Does MX lookups; randomizes returned entries with equal precedence.
|
|
nonrandomemx
|
Does MX lookups; does not randomize returned entries with equal precedence.
|
|
nameservers
|
Specifies a list of nameservers to consult rather than consulting the TCP/IP stack's own choice of nameservers; nameservers requires a space separated list of IP addresses for the nameservers.
|
|
defaultnameservers
|
Consults TCP/IP stack's choice of nameservers.
|
|
lastresort
|
Specifies a last resort host.
|
|
Switch keywords
|
Controls selection of alternate channels for incoming mail
|
|
allowswitchchannel
|
Allows switching to this channel from a switchchannel channel
|
|
noswitchchannel
|
Stays with the server channel; does not switch to the channel associated with the originating host; does not permit being switched to.
|
|
switchchannel
|
Switches from the server channel to the channel associated with the originating host.
|
|
tlsswitchchannel
|
Switches to another channel upon successful TLS negotiation.
|
|
saslswitchchannel
|
Switches to another channel when SASL authentication is successful.
|
|
Target Host Choice and Storage of Message Copies
|
Specifies a target host system and how message copies are stored.
|
|
daemon
|
Connects to a specific host system regardless of the envelope address.
|
|
single
|
Specifies that a separate copy of the message should be created for each destination address on the channel.
|
|
single_sys
|
Creates a single copy of the message for each destination system used.
|
TCP/IP Port Number and Interface Address
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. Note that this keyword complements the Dispatcher option PORT, which controls which ports the MTA listens on for accepting SMTP connections.
The interfaceaddress keyword controls the address to which a TCP/IP channel binds as the source address for outbound connections; that is, on a system with multiple interface addresses this keyword controls which address will be used as the source IP address when the MTA sends outgoing SMTP messages. Note that this keyword complements the Dispatcher option INTERFACE_ADDRESS, which controls which interface address a TCP/IP channel listens on for accepting incoming connections and messages.
Caching for Channel Connection Information
Channels using the SMTP protocol 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 lots of time and delay other messages. The cache is a per process cache and only persists during a single run of the outbound SMTP delivery channel.
The cache normally records both connection successes and failures. (Successful connection attempts are recorded in order to offset subsequent failures—a host that succeeded before but fails now doesn't warrant as long of a delay before making another connection attempt as does one that has never been tried or one that has failed previously.)
However, the caching strategy used by the MTA is not necessarily appropriate for all situations. Therefore channel keywords are provided to adjust the MTA cache.
The cacheeverything keyword enables all forms of caching and is the default. The nocache keyword disables all caching.
The cachefailures keyword enables caching of connection failures but not successes—this forces a somewhat more restricted retry than cacheeverything does. Finally, cachesuccesses caches only successes. This last keyword is effectively equivalent to nocache for SMTP channels.
DNS Lookups
The forwardchecknone, forwardchecktag, and forwardcheckdelete channel keywords can modify the effects of doing reverse DNS lookups. These keywords can control whether the MTA does a forward lookup of an IP name found using a DNS reverse lookup, and if such forward lookups are requested, specify 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; in this case, the MTA uses 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.
|
IDENT Lookups
The IDENT keywords control how the MTA handles connections and lookups using the IDENT protocol. The IDENT protocol is described in RFC 1413.
The identtcp, identtcpsymbolic, and identtcpnumeric keywords tell the MTA to perform a connection and lookup using the IDENT protocol. The information obtained from the IDENT protocol (usually the identity of the user making the SMTP connection) is inserted into the Received: header of the message as follows:
identtcp inserts the host name corresponding to the incoming IP number, as reported from a DNS reverse lookup and the IP number itself.
identtcpsymbolic inserts the host name corresponding to the incoming IP number, as reported from a DNS reverse lookup; the IP number itself is not included in the Received: header.
identtcpnumeric inserts 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, identtcpsymbolic, 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 stack controlled time-out, typically on the order of a minute or two).
Another performance factor occurs when comparing identtcp, indenttcplimited, or identtcpsymbolic to identtcpnumeric. The DNS reverse lookup called for with identtcp, identtcplimited, or identtcpsymbolic incurs some additional overhead to obtain the more user-friendly host name.
The identnone keyword disables IDENT lookup, but does specify IP to host name translation, and both IP number and host name will be included in the Received: header for the message. This is the default.
The identnonesymbolic keyword disables IDENT lookup, but does do IP to host name translation; only the host name will be included in the Received: header for the message.
The identnonenumeric keyword disables this IDENT lookup and inhibits the usual DNS reverse lookup translation of IP number to host name, and might result in a performance improvement at the cost of less user-friendly information in the Received: header.
The identtcplimited and identnonelimited keywords have the same effect as identtcp and identnone, respectively, as far as IDENT lookups, reverse DNS lookups, and information displayed in Received: header. Where they differ is that with identtcplimited or identnonelimited the IP literal address is always used as the basis for any channel switching due to use of the switchchannel keyword, regardless of whether the DNS reverse lookup succeeds in determining a host name.
TCP/IP MX Record Support
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 mx, nomx, defaultmx, randommx, nonrandommx keywords control MX record support.
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.
Nameserver Lookups
When nameserver lookups are being performed, the nameservers channel keyword may be used to specify a list of nameservers to consult rather than consulting the TCP/IP stack's own choice of nameservers. The nameservers keyword requires a space separated list of IP addresses for the nameservers, as shown in the following example:
nameservers 1.2.3.1 1.2.3.2
The default, defaultnameservers, means use the TCP/IP stack's own choice of nameservers.
To prevent nameserver lookups on UNIX, you can modify the nsswitch.conf file. On NT, modify the TCP/IP configuration.
Last Resort Host
The lastresort keyword is used to specify a host to connect to 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.
Alternate Channels for Incoming Mail
The following keywords control selection of an alternate channel for incoming mail: switchchannel, allowswitchchannel, noswitchchannel.
When the MTA 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 SMTP over 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 initial channel the server uses, the IP address of the connecting (originating) host will be matched against the channel table and if it matches the source channel will change accordingly. If no IP address match is found or if a match is found that matches the original default incoming channel, the MTA may optionally try matching using the host name found by doing a DNS reverse lookup. The source channel may change to any channel marked switchchannel or allowswitchchannel (the default). The noswitchchannel keyword 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.
Target Host Choice
The daemon keyword is used on SMTP channels to control the choice of a target host.
Normally, channels connect to whatever host is listed in the envelope address of the message being processed. The daemon keyword is used to tell the channel to instead connect to a specific remote system, generally a firewall or mailhub system, regardless of the envelope address. The actual remote system name should appear directly after the daemon keyword, as shown in the following example:
tcp_firewall smtp mx daemon firewall.acme.com
TCP-DAEMON
If the argument after the daemon keyword is not a fully qualified domain name, the argument will be ignored and the channel will connect to the channel's official host. When specifying the firewall or gateway system name as the official host name, the argument given to the daemon keyword is typically specified as router, as shown in the following example:
tcp_firewall smtp mx daemon router
firewall.acme.com
TCP-DAEMON
Other keywords of interest are single and single_sys. The single keyword specifies that a separate copy of the message should be created for each destination address on the channel. The single_sys keyword creates a single copy of the message for each destination system used. Note that at least one copy of each message is created for each channel the message is queued to, regardless of the keywords used.
SMTP Authentication and SASL
You can control whether the Messaging Server supports authentication to the SMTP server using SASL (Simple Authentication and Security Layer). SASL is defined in RFC 2222. For more information about SASL, SMTP authentication, and security, see Chapter 11 "Configuring Security and Access Control."
Table 8-4 lists the SASL keywords described in this section.
Table 8-4 SMTP Authentication with SASL
|
Keyword
|
Definition
|
|
maysaslserver
|
SMTP server supports SASL authentication. Clients can attempt to connect to the server using SASL authentication.
|
|
mustsaslserver
|
SMTP server supports SASL authentication. Clients must use SASL authentication; the SMTP server will not accept messages unless the remote client successfully authenticates.
|
|
nosasl
|
SASL authentication is not to be permitted or attempted. It subsumes nosaslserver, which means that SASL authentication will not be permitted. This is the default.
|
|
nosaslserver
|
SMTP server does not permit SASL authentication.
|
|
saslswitchchannel
|
Causes incoming connections to be switched to a specified channel upon a client's successful use of SASL. It takes a required value, specifying the channel to which to switch.
|
Transport Layer Security
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.
The default is notls, and means that TLS will not be permitted or attempted. It subsumes the notlsclient keyword, which means that TLS use will not be attempted by the MTA SMTP client on outgoing connections (the STARTTLS command will not be issued during outgoing connections) and the notlsserver keyword, which means that TLS use will not be permitted by the MTA SMTP server on incoming connections (the STARTTLS extension will not be advertised by the SMTP server nor the command itself accepted).
Specifying maytls causes the MTA to offer TLS to incoming connections and to attempt TLS upon outgoing connections. It subsumes 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 subsumes 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). It also subsumes 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.
Channel Operation Type
Messaging Server supports RFC 2476's Message Submission protocol. The submit keyword may be used to mark a channel as a submit-only channel. This is normally useful mostly on TCP/IP channels, such as an SMTP server run on a special port used solely for submitting messages; RFC 2476 establishes port 587 for such message submission use.
Configuring Message Processing and Delivery
You can configure when the server attempts to deliver messages based on certain criteria. You can also specify parameters for job processing, such as processing limits for service jobs, or when to spawn a new SMTP channel thread. This section describes the following:
Table 8-5 summarizes the keywords described in this section.
Table 8-5 Message Processing and Delivery Keywords
|
Keyword
|
Definition
|
|
Immediate Delivery
|
Defines specification for immediate delivery of messages.
|
|
immnonurgent
|
Starts delivery immediately after submission for urgent, normal, and non-urgent messages.
|
|
Deferred Delivery
|
Defines specification for delivery of deferred jobs.
|
|
backoff
|
Specifies the frequency for attempted delivery of deferred messages. This keyword specifies the value for normal, urgent, and nonurgent mail unless one of the other backoff keywords is used. By default, a message that cannot be delivered will be retried as follows: after 1 hour, after 2 hours, after another 2 hours, and then every 4 hours for three more tries, at which point the server tries every 8 hours.
|
|
nonurgentbackoff
|
Specifies the frequency for attempted delivery of nonurgent messages.
|
|
normalbackoff
|
Specifies the frequency for attempted delivery of normal messages.
|
|
urgentbackoff
|
Specifies the frequency for attempted delivery of urgent messages.
|
|
Message Priority Based on Size
|
Defines message priority based on message size.
|
|
nonurgentblocklimit
|
Forces messages above this size to lower than nonurgent priority (second class priority), meaning that the messages will always wait for the next periodic job for further processing.
|
|
normalblocklimit
|
Forces messages above this size to nonurgent priority.
|
|
urgentblocklimit
|
Forces messages above this size to normal priority.
|
|
Processing Pools for Channel Execution Jobs
|
Specifies the pools for processing messages of different urgencies and deferral of jobs
|
|
pool
|
Specifies the pool in which channels run.
|
|
after
|
Specifies a time delay before channels run.
|
|
Service Job Limits
|
Specifies the number of service jobs and the maximum number of message files to handle per job
|
|
maxjobs
|
Specifies the maximum number of jobs that can be running concurrently for the channel.
|
|
filesperjob
|
Specifies the number of queue entries to be processed by a single job.
|
|
SMTP Channel Threads
threaddepth
|
Number of messages triggering new thread with multithreaded SMTP client.
|
|
Multiple Address Expansion
|
Defines processing specification for messages with multiple recipient addresses
|
|
expandlimit
|
Processes an incoming message "off-line" when the number of addressees exceeds this limit.
|
|
expandchannel
|
Specifies channel in which to perform deferred expansion due to application of expandlimit.
|
|
holdlimit
|
Holds an incoming message when the number of addresses exceeds this limit.
|
|
Undeliverable Message Notifications
|
Specifies when undeliverable message notifications are sent.
|
|
notices
|
Specifies the amount of time that may elapse before notices are sent and messages returned.
|
|
nonurgentnotices
|
Specifies the amount of time that may elapse before notices are sent and messages returned for messages of non-urgent priority.
|
|
normalnotices
|
Specifies the amount of time that may elapse before notices are sent and messages returned for messages of normal priority.
|
|
urgentnotices
|
Specify the amount of time which may elapse before notices are sent and messages returned for messages of urgent priority.
|
Delivery of Messages
Each time a message is enqueued to a channel, the Job Controller ensures that there is a job running to deliver the message. 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 has been reached, the Job Controller waits until another job has exited, then, when the job limit is no longer exceeded, starts another job. (Job limits for the channel are determined by the maxjobs channel keyword. Job limits for the pool are determined by the JOB_LIMIT option for the pool.)
Messaging Server attempts immediate delivery of all messages. If a message cannot be delivered on the first attempt, however, the message is delayed for a period of time determined by the appropriate backoff keyword. As soon as the time specified in the backoff keyword has elapsed, the delayed message is available for delivery, and if necessary, a channel job is started to process the message.
The Job Controller creates and manages channel jobs for delivering messages. These channel jobs run inside processing pools within the Job Controller. For more information about these pools, see Processing Pools for Channel Execution Jobs.
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, then the Job Controller tracks in memory only a subset of the total number of messages files on disk. The Job Controller processes only those messages it is tracking in memory. After a sufficient number of messages have been delivered to free enough in-memory storage, the Job Controller automatically refreshes its in-memory store by scanning the MTA queue area to update its list of messages. The Job Controller then begins processing the additional message files it just retrieved from disk. The Job Controller performs these scans of the MTA queue area automatically.
If your site routinely experiences heavy message backlogs, you might want to tune the Job Controller by using the MAX_MESSAGES option. By increasing the MAX_MESSAGES option value to allow Job Controller to use more memory, you can reduce the number of occasions when message backlogs overflow the Job Controller's in-memory cache. This reduces the overhead involved when the Job Controller must scan the MTA queue directory. Keep in mind, however, that when the Job Controller does need to rebuild the in-memory cache, the process will take longer because the cache is larger. Note also that because the Job Controller must scan the MTA queue directory every time it is started or restarted, large message backlogs means that starts or restarts of the Job Controller will incur more overhead than starts or restarts when no such backlog exists.
Processing Pools for Channel Execution Jobs
You can configure various channels to share resources by running within the same pool. You might want to configure other channels to run in pools dedicated to a particular channel. Within each pool, messages are automatically sorted into different processing queues according to message priority. Higher priority messages in the pool are process before lower-priority messages. (See Message Priority Based on Size.)
The pools where the jobs are created can be selected on a channel by channel basis by 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 pooled. The name of the pool should not contain more than twelve characters.
Execution of service jobs can be deferred using the after keyword. The after keyword must be followed by a specification of the amount of time to delay. If the value following the keyword is an unsigned integer value, it is interpreted as a number of seconds by which to defer delivery of the message—a delta time value.
Service Job Limits
Each time a message is enqueued to a channel, the Job Controller ensures that there is a job running to deliver the message. This might involve starting a new job process, adding a thread, or simply noting that a job is already running. A single service job may not be sufficient to ensure prompt delivery of all messages, however.
For any given installation, there is a reasonable maximum number of processes and threads to be started for delivering messages. This maximum number depends on factors such as the number of processors, the speed of the disks, and the characteristics of the connections. In the MTA configuration, it is possible to control the following:
The maximum number of processes to start running for a given channel (the maxjobs channel keyword)
The maximum number of processes to start for a set of channels (the JOB_LIMIT parameter in the relevant pool section of the Job Controller configuration file)
The number of queued messages received before a new thread or process is started (the threaddepth channel keyword)
For some channels, the maximum number of threads that will run within a given delivery program (max_client_threads parameter in the channel option file)
The maximum number of processes to start running for a given channel is the minimum of the maxjobs set on the channel and the JOB_LIMIT set for the pool that the channel runs in.
Assume a message needs processing. In general, the Job Controller starts new processes as follows:
If no process is running for a channel and the pool job limit has not been reached, then the Job Controller starts a new process.
If a channel program is single-threaded or the thread limit has been reached and the backlog increases past a multiple of threads (specified with threaddepth) and neither the channel nor pool job limit has been reached, the Job Controller starts a new process
If a channel program is multithreaded and the thread limit has not been reached and the backlog of messages increase past a multiple of threaddepth, a new thread is started.
For SMTP channels in particular, new threads or processes are started as messages are enqueued for different hosts. Thus, for SMTP channels, the Job Controller starts new processes as follows. Assume a message needs processing:
If no process is running for an SMTP channel and the pool limit has not been reached, the Job Controller starts a new process.
If the thread limit (MAX_CLIENT_THREADS) has been reached, a message is enqueued for a host not yet being serviced, and neither the channel (maxjobs) nor pool job limit (JOB_LIMIT) has been reached then a new process is started.
If the thread limit has not been reached and a message is enqueued for a host not yet being serviced, then a new thread is started.
If the thread limit has not been reached and a message is enqueued that takes the backlog of messages for that host increase past a multiple of threaddepth, a new thread is started.
See also SMTP Channel Threads.
The filesperjob keyword can be used to cause the MTA to create additional service jobs. This keyword takes a single positive integer parameter which specifies how many queue entries (that is, files) must be sent to the associated channel before more than one service job 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 is equivalent to specifying a value of zero. The effect of this keyword is maximized; the larger number computed will be the number of service jobs that are actually created.
The filesperjob keyword divides the number of actual queue entries or files by the given value. Note that 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 bound on the total number of service jobs that can be running concurrently. This keyword must be followed by an integer value; if the computed number of service jobs is greater than this value only maxjobs jobs will actually be created. The default for this value if maxjobs is not specified 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 pool or pools the channel uses.
Message Priority Based on Size
The urgentblocklimit, normalblocklimit, and nonurgentblocklimit keywords may be used to instruct the MTA to downgrade the priority of messages based on size. These keywords affect the priority that the Job Controller applies when processing the message.
SMTP Channel Threads
The multithreaded SMTP client sorts outgoing messages to different destinations to different threads. The threaddepth keyword may be used to instruct the 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).
Use of threaddepth may be of particular interest for achieving multithreading on a daemon router TCP/IP channel—a TCP/IP channel that connects to a single specific SMTP server—when the SMTP server to which the channel connects can handle multiple simultaneous connections.
Each time the backlog for a channel increases past a multiple of threaddepth, the Job Controller tries to increase the amount of processing dedicated to processing messages queued for that channel. For multithreaded channels, the Job Controller advises any job processing messages for that channel to start a new thread, or if all jobs have the maximum threads allowed for the channel (MAX_CLIENT_THREADS in the option for the tcp_* channels) it will start a new process. For single-threaded channels it will start new process. Note that the Job Controller will not start a new job if the job limit for the channel (maxjobs) or the pool (JOB_LIMIT) has been reached.
Expansion of Multiple Addresses
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 addresses are specified for a single message. Deferral of message processing can decrease on-line delays enormously. Note, however, that the processing overhead is deferred, not avoided completely.
This special facility is activated by using a combination of, for instance, 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 will force 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 channel actually used to perform the deferred processing may be specified using the expandchannel keyword; the reprocessing channel is used by default, if expandchannel is not specified, but use of some other reprocessing or processing channel may be useful for special purposes. If a channel for deferred processing is specified via expandchannel, that channel should be a reprocessing or processing channel; specification of other sorts of channels may lead to unpredictable results.
The reprocessing channel, or whatever channel is used to perform the deferred processing, must be added to the MTA 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 a reprocessing channel.
Extraordinarily large lists of recipient addresses are often a characteristic of unsolicited bulk email. The holdlimit keyword tells the MTA that messages coming in the channel that result in more than the specified number of recipients should be marked as .HELD messages and enqueued to the reprocess channel (or to whatever channel is specified via the expandchannel keyword). The files will sit unprocessed in the reprocess queue awaiting manual intervention by the MTA postmaster.
Undeliverable Message Notification Times
The notices, nonurgentnotices, normalnotices, and urgentnotices keywords control the amount of time an undeliverable message is silently retained in a given channel queue. Messaging Server is capable of returning a series of warning messages to the originator and, if the message remains undeliverable, Messaging Server will eventually return the entire message.
Different return handling for messages of different priorities may be explicitly set using the nonurgentnotices, normalnotices, or urgentnotices keywords. Otherwise, the notices keyword values will be used for all messages.
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 MTA option RETURN_UNITS is 0 or not specified in the MTA option file, or hours if the MTA option RETURN_UNITS is 1.
When an undeliverable message attains or exceeds the last listed age, it is returned (bounced). When it 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. If no setting has been made, 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).
The syntax for the notices keyword uses no punctuation. For example, the default return policy would be expressed as follows:
notices 3 6 9 12
If you wish to change the notification ages for all of your channels, then the simplest thing to do is to add a defaults channel block to the start of the channel block section of your MTA configuration file or to add the notices setting to your local channel. For example, the following command adds a defaults channel that specifies notification ages for all channels:
defaults notices 1 3 6 9 12
The defaults channel would appear immediately after the first blank line in the MTA configuration file.
Configuring Messages Sent to the Postmaster
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.
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 failed messages and warning messages is sent to the local postmaster. This is useful for monitoring message failures and the state of the various queues, but it can result in lots of traffic for the postmaster.
You can control which messages are sent to the postmaster with the keywords described in Table 8-6.
Table 8-6 Messages Sent to the Postmaster Keywords
|
Keyword
|
Description
|
|
Returned Messages
|
How to handle failure notices for returned messages.
|
|
sendpost
|
Enables sending a copy of all failed messages to the postmaster.
|
|
copysendpost
|
Sends a copy of the failure notice to the postmaster unless the originator address on the failing message is blank, in which case, the postmaster gets copies of all failed messages except those messages that are actually themselves bounces or notifications.
|
|
errsendpost
|
Sends a copy of the failure notice to the postmaster only when the notice cannot be returned to the originator. If nosendpost is specified, failed messages are never sent to the postmaster.
|
|
nosendpost
|
Disables sending a copy of all failed messages to the postmaster.
|
|
Warning Messages
|
How to handle warning messages.
|
|
warnpost
|
Enables sending a copy of warning messages to the postmaster. The default, if no keyword is specified, is to send a copy of warnings to the postmaster unless warnings are completely suppressed with a blank Warnings-to: header or a blank envelope From: address.
|
|
copywarnpost
|
Sends a copy of the warning message to the postmaster unless the originator address on the undelivered message is blank.
|
|
errwarnpost
|
Sends a copy of the warning message to the postmaster when the notice cannot be returned to the originator.
|
|
nowarnpost
|
Disables sending a copy of warning messages to the postmaster.
|
|
Returned Message Content
|
Specifies whether to send entire message or just headers to the postmaster.
|
|
postheadonly
|
Returns only headers to the postmaster. Restricting the postmaster copy to just the headers adds an additional level of privacy to user mail. However, this 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.
|
|
postheadbody
|
Returns both the headers and the contents of the message.
|
Configuring Channel Options
TCP/IP channel option files control various characteristics of TCP/IP channels. Channel option files must be stored in the MTA configuration directory and named x_option, where x is the name of the channel. For example, /server-instance/imta/config/tcp_local_option.
The option file consists of one or more keywords and an associated value. For example you can disable mailing list expansion on your server by including the DISABLE_EXPAND keyword in the option file and setting the value to 1.
Other option file keywords allow you to:
Set a limit on the number of recipients allowed per message (ALLOW_RECIPIENTS_PER_TRANSACTION)
Set a limit on the number of messages allowed per connection (ALLOW_TRANSACTIONS_PER_SESSION)
Fine tune the type of information logged to the MTA log file (LOG_CONNECTION, LOG_TRANPORTINFO)
Specify the maximum number of simultaneous outbound connections that the client channel program allows (MAX_CLIENT_THREADS)
For information about all channel option keywords and syntax, see the Messaging Server Reference Manual.
Configuring Channel Defaults
Many configurations involve repetition of various channel keywords on all or nearly all channels. Maintaining such a configuration is both tedious and error-prone. To simplify some configurations, you can specify which keywords are defaults for various channels.
For example, the following line in a configuration file indicates that all channel blocks following the line will inherit the keywords specified in the line:
defaults keyword1 keyword2 keyword3 ...
The defaults line can be thought of as a special channel block that changes the keyword defaults without actually specifying a channel. The defaults line also does not require any additional lines of channel block information (if any are specified they will be ignored).
There is no limit on the number of defaults lines that can be specified—the effects of multiple defaults lines are cumulative with the most recently encountered (reading from top to bottom) line having precedence.
It may be useful to unconditionally eliminate the effects of any defaults lines starting at some point in the configuration file (at the start of a standalone section of channel blocks in an external file, for example). The nodefaults line is provided for this purpose. For example, inserting the following line in the configuration file nullifies all settings established by any previous defaults channel and returns the configuration to the state that would apply if no defaults had been specified:
nodefaults
Like regular channel blocks, a blank line must separate each defaults or nodefaults channel block from other channel blocks. The defaults and nodefaults channel blocks are the only channel blocks which may appear before the local channel in the configuration file. However, like any other channel block, they must appear after the last rewrite rule.
Configuring Logging for Channels
The MTA provides facilities for logging each message as it is enqueued and dequeued. The logging and nologging keywords control logging for messages on a per-channel basis. By default, the initial configuration turns on logging for all channels. You can disable logging for a particular channel by substituting the nologging keyword in the channel definition.
For more information about logging, see Chapter 12 "Logging and Log Analysis."
Configuring Debugging for Channels
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 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.
Setting Up Program Delivery
Users might want incoming mail passed to a program instead of to their mailbox. For example, users might want their incoming mail sent to a mail sorting program or to an autoreply agent like Vacation Notice. The pipe channel performs delivery of messages using per-user, site-supplied programs.
To facilitate program delivery, you must first register programs as invokable by the pipe channel. You do this by using the imsimta program utility. This utility gives a unique name to each command that you register as invokable by the pipe channel. End users can then specify the program name as a value of their mailprogramdeliveryinfo LDAP attribute.
For example, to add a UNIX command myprocmail as a program that can be invoked by a user, you would first register the command by using the imsimta program utility as shown in the following example. This example registers a program called myprocmail that executes the program procmail with the arguments -d username and executes as the user:
imsimta program -a -m myprocmail -p procmail -g "-d %s" -e user
Make sure the executable exists in the programs directory—server-instance/imta/programs—and that the execute permissions are set to "others."
To enable a user to access the program, the user's LDAP entry must contain the following attributes and values:
maildeliveryoption: program
mailprogramdeliveryinfo: myprocmail
For more information about the imsimta program utility, see the Messaging Server Reference Manual.
Alternative delivery programs must conform to the following exit code and command-line argument restrictions:
Exit Code Restrictions. Delivery programs invoked by the pipe channel must return meaningful error codes so that the channel knows whether to dequeue the message, deliver for later processing, or return the message.
If the subprocess exits with an exit code of 0 (EX_OK), the message is presumed to have been delivered successfully and is removed from the MTA queues. If it exits with an exit code of 71, 74, 75, or 79 (EX_OSERR, EX_IOERR, EX_TEMPFAIL, or EX_DB), a temporary error is presumed to have occurred and delivery of the message is deferred. If any other exit code is returned, then the message will be returned to its originator as undeliverable. These exit codes are defined in the system header file sysexits.h.
Command Line Arguments. Delivery programs can have any number of fixed arguments as well as the variable argument, %s, representing the user name for programs executed by the user or username+domain for programs executed by the postmaster, "inetmail." For example, the following command line delivers a recipient's mail using the program procmail:
/usr/lib/procmail -d %s
Using the Hold Channel
The hold channel is used to hold the messages of a recipient temporarily halted from receiving new messages. Messages may be halted because a user's name is being changed, or their mailbox is being moved from one mailhost or domain to another. There may also be other reasons to temporarily halt a user from receiving messages, but those are the most common.
Messages are placed in the hold channel in two ways:
Setting one of the maildeliveryoption values of a user to hold. All other maildeliveryoption values are ignored (maildeliveryoption is a multi-valued attribute), and messages to the user are routed to the hold channel.
Executing the hold_slave program. This program steps through all other channels and moves the existing messages whose recipient(s) matches those specified by the arguments into the hold channel.
Unlike most channels, the hold channel master program is not configured to run automatically. Messages queued in the hold channel will remain there until the hold_master program is invoked by the administrator.
To migrate user, first mark the user as being moved (use imadmin modify user to set maildeliveryoption to hold). Then invoke hold_slave to move any messages already in the other queues to the hold queue. At this point, perform the remaining migration steps. Once you have completed these steps, remove maildeliveryoption=hold, and then invoke hold_master to enqueue messages to their proper channels.
Using the Conversion Channel
The conversion channel performs arbitrary body-part-by-body-part conversions on messages flowing through the MTA. Any subset of the MTA traffic can be selected for conversion and any set of programs or command procedures can be used to perform conversion processing. (The MTA's native conversion facilities are fairly limited, so the ability to call external converters is crucial.) A special conversion channel configuration is consulted to choose an appropriate conversion for each body part.
Selecting Traffic for Conversion Processing
Although conversion processing is done using a regular MTA channel program, under normal circumstances this channel is never specified directly either in an address or in an MTA rewrite rule. The MTA controls access to the conversion channel using the CONVERSIONS mapping table in the MTA mappings file (server_root/msg-instance/imta/config/mappings).
As the MTA processes each message it probes the CONVERSIONS mapping (if one is present) with a string of the form:
IN-CHAN=source-channel;OUT-CHAN=destination-channel;CONVERT
The source-channel is the channel from which the message is coming and destination-channel is the channel to which the message is heading. If the mapping produces a result, it should either be the string Yes or No. If Yes is produced, the MTA will divert the message from its regular destination to the conversion channel. If No is produced or if no match is found, the message will be queued to the regular destination channel.
For example, for all messages that do not originate from the tcp_intranet channel and that are going to require conversion processing, the following mapping would then be appropriate:
|
CONVERSIONS
IN-CHAN=tcp_intranet;OUT-CHAN=tcp_intranet;CONVERT NO
IN-CHAN=*;OUT-CHAN=tcp_intranet;CONVERT YES
|
|
Configuration of the Conversion Channel
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.
Conversion Control
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 IMTA_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. For example, the following entry specifies that application/wordperfect5.1 parts in messages sent to the ims-ms channel should be converted to MS Word using a hypothetical converter called "convert":
|
out-chan=l; in-type=application; in-subtype=wordperfect5.1;
out-type=application; out-subtype=ddif; out-mode=block;
command="/usr/bin/convert -in=wordp -out=msword <$INPUT_FILE>$OUTPUT_FILE"
|
|
Understanding 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 Messaging Server 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 table 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. Table 8-7 lists the keywords.
Table 8-7 CHARSET-CONVERSION Mapping Table Keywords
|
Keyword
|
Description
|
|
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
|
"Flatten" any message/rfc822 body part (forwarded message) into a message content part and a header part.
|
|
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 part (forwarded message) into a header part and a message content part.
|
|
UUENCODE
|
Switch MIME encodings to X-UUENCODE.
|
|
Yes
|
Enable conversion.
|
Character Set Conversion
If the MTA probes and finds that the message is to be reformatted, it will proceed to check each part of the message. Any text parts are found and their character set parameters are used to generate the second probe. Only when the MTA has checked and found that conversions may be needed does it ever perform the second probe. The input string in this second case looks like this:
IN-CHAN=in-channel;OUT-CHAN=out-channel;IN-CHARSET=in-char-set
The in-channel and out-channel are the same as before, and the in-char-set is the name of the character set associated with the particular part in question. If no match occurs for this second probe, no character set conversion is performed (although message reformatting, for example, changes to MIME structure, may be performed in accordance with the keyword matched on the first probe). If a match does occur it should produce a string of the form:
OUT-CHARSET=out-char-set
Here out-char-set specifies the name of the character set to which the in-char-set should be converted. Note that both of these character sets must be defined in the character set definition table, charsets.txt, located in the MTA table directory. No conversion will be done if the character sets are not properly defined in this file. This is not usually a problem since this file defines several hundred character sets; most of the character sets in use today are defined in this file. See the description of the imsimta chbuild (UNIX and NT) utility for further information on the charsets.txt file.
If all the conditions are met, the MTA will proceed to build the character set mapping and do the conversion. The converted message part will be relabelled with the name of the character set to which it was converted.
Message Reformatting
As described above, the CHARSET-CONVERSION mapping table is also used to effect the conversion of attachments between MIME and several proprietary mail formats.
The following sections give examples of some of the other sorts of message reformatting which can be affected with the CHARSET-CONVERSION mapping table.
Non-MIME Binary Attachment Conversion
Mail in certain non-standard (non-MIME) formats; for example, mail in certain proprietary formats or mail from the Microsoft Mail (MSMAIL) SMTP gateway is automatically converted into MIME format if CHARSET-CONVERSION is enabled for any of the channels involved in handling the message. If you have a tcp_local channel then it is normally the incoming channel for messages from a Microsoft Mail SMTP gateway, and the following will enable the conversion of messages delivered to your local users:
CHARSET-CONVERSION
IN-CHAN=tcp_local;OUT-CHAN=ims-ms;CONVERT Yes
Alternatively, to cover every channel you can simply specify OUT-CHAN=* instead of OUT-CHAN=ims-ms. However, this may bring about an increase in message processing overhead as all messages coming in the tcp_local channel will now be scrutinized instead of just those bound to specific channels.
More importantly, such indiscriminate conversions might place your system in the dubious and frowned upon position of converting messages—not necessarily your own site's—which are merely passing through your system, a situation in which you should merely be acting as a transport and not necessarily altering anything beyond the message envelope and related transport information.
To convert MIME into the format Microsoft Mail SMTP gateway understands, use a separate channel in your MTA configuration for the Microsoft Mail SMTP gateway; for example, tcp_msmail, and put the following in the mappings. file:
CHARSET-CONVERSION
IN-CHAN=*;OUT-CHAN=tcp_msmail;CONVERT RFC1154
Relabelling MIME Headers
Some user agents or gateways may emit messages with MIME headers that are less informative than they might be, but that nevertheless contain enough information to construct more precise MIME headers. Although the best solution is to properly configure such user agents or gateways, if they are not under your control, you can instead ask the MTA to try to reconstruct more useful MIME headers.
If the first probe of the CHARSET-CONVERSION mapping table yields a Yes or Always keyword, then the MTA will check for the presence of a conversions file. If a conversions file exists, then the MTA will look in it for an entry with RELABEL=1 and if it finds such an entry, the MTA will then perform any MIME relabelling specified in the entry.
For example, the combination of a CHARSET-CONVERSION table and MTA conversions file entries such as the following will result in messages that arrive on the tcp_local channel and are routed to the ims-ms channel, and that arrive originally with MIME labelling of application/octet-stream but have a filename parameter with the extension ps or msw, being relabelled as application/postscript or application/msword, respectively. (Note that this more precise labelling is what the original user agent or gateway should have performed itself.)
|
CHARSET CONVERSION TABLE
CHARSET-CONVERSION
IN-CHAN=tcp_local;OUT-CHAN=mr_local;CONVERT Yes
MTA CONVERSIONS FILE ENTRIES
out-chan=ims-ms; in-type=application; in-subtype=octet-stream;
in-parameter-name-0=name; in-parameter-value-0=*.ps;
out-type=application; out-subtype=postscript;
parameter-copy-0=*; relabel=1
out-chan=ims-ms; in-type=application; in-subtype=octet-stream;
in-parameter-name-0=name; in-parameter-value-0=*.msw;
out-type=application; out-subtype=msword;
parameter-copy-0=* relabel=1
|
|
MacMIME Format Conversions
Macintosh files have two parts, a resource fork that contains Macintosh specific information, and a data fork that contains data usable on other platforms. This introduces an additional complexity when transporting Macintosh files, as there are four different formats in common use for transporting the Macintosh file parts. Three of the formats, Applesingle, Binhex, and Macbinary, consist of the Macintosh resource fork and Macintosh data fork encoded together in one piece. The fourth format, Appledouble, is a multipart format with the resource fork and data fork in separate parts. Appledouble is hence the format most likely to be useful on non-Macintosh platforms, as in this case the resource fork part may be ignored and the data fork part is available for use by non-Macintosh applications. But the other formats may be useful when sending specifically to Macintoshes.
The MTA can convert between these various Macintosh formats. The CHARSET-CONVERSION keywords Appledouble, Applesingle, Binhex, or Macbinary tell the MTA to convert other MacMIME structured parts to a MIME structure of multipart/appledouble, application/applefile, application/mac-binhex40, or application/macbinary, respectively. Further, the Binhex or Macbinary keywords also request conversion to the specified format of non-MacMIME format parts that do nevertheless contain X-MAC-TYPE and X-MAC-CREATOR parameters on the MIME Content-type: header. The CHARSET-CONVERSION keyword Block tells the MTA to extract just the data fork from MacMIME format parts, discarding the resource fork; (since this loses information, use of Appledouble instead is generally preferable).
For example, the following CHARSET-CONVERSION table would tell the MTA to convert to Appledouble format when delivering to the ims-ms channel.
CHARSET-CONVERSION
IN-CHAN=*;OUT-CHAN=l;CONVERT Appledouble
The conversion to Appledouble format would only be applied to parts already in one of the MacMIME formats.
When doing conversion to Appledouble or Block format, the MAC-TO-MIME-CONTENT-TYPES mapping table may be used to indicate what specific MIME label to put on the data fork of the Appledouble part, or the Block part, depending on what the Macintosh creator and Macintosh type information in the original Macintosh file were. Probes for this table have the form format|type|creator|filename where format is one of SINGLE, BINHEX or MACBINARY, where type and creator are the Macintosh type and Macintosh creator information in hex, respectively, and where filename is the filename.
For example, to convert to Appledouble when sending to the ims-ms channel and when doing so to use specific MIME labels for any MS Word or PostScript documents converted from MACBINARY or BINHEX parts, appropriate tables might be:
|
CHARSET-CONVERSION
IN-CHAN=*;OUT-CHAN=ims-ms;CONVERT Appledouble
MAC-TO-MIME-CONTENT-TYPES
! PostScript
MACBINARY|45505346|76677264|* APPLICATION/POSTSCRIPT$Y
BINHEX|45505346|76677264|* APPLICATION/POSTSCRIPT$Y
! Microsoft Word
MACBINARY|5744424E|4D535744|* APPLICATION/MSWORD$Y
BINHEX|5744424E|4D535744|* APPLICATION/MSWORD$Y
|
|
Note that the template (right hand side) of the mapping entry must have the $Y flag set in order for the specified labelling to be performed. Sample entries for additional types of attachments may be found in the file mac_mappings.sample in the MTA table directory.
If you wish to convert non-MacMIME format parts to Binhex or Macbinary format, such parts need to have X-MAC-TYPE and X-MAC-CREATOR MIME Content-type: parameter values provided. Note that MIME relabelling can be used to force such parameters onto parts that would not otherwise have them.
Service Conversions
The MTA's conversion service facility may be used to process with site-supplied procedures a message so as to produce a new form of the message. Unlike either the sorts of CHARSET-CONVERSION operations discussed above or the conversion channel, which operate on the content of individual MIME message parts, conversion services operate on entire MIME message parts (MIME headers and content) as well as entire MIME messages. Also, unlike other CHARSET-CONVERSION operations or conversion channel operations, conversion services are expected to do their own MIME disassembly, decoding, re-encoding, and reassembly.
Like other CHARSET-CONVERSION operations, conversion services are enabled through the CHARSET-CONVERSION mapping table. If the first probe of the CHARSET-CONVESION mapping table yields a Yes or Always keyword, then the MTA will check for the presence of an MTA conversions file. If a conversions file exists, then the MTA will look in it for an entry specifying a SERVICE-COMMAND, and if it finds such an entry, execute it. The conversions file entries should have the form:
|
in-chan=channel-pattern;
in-type=type-pattern; in-subtype=subtype-pattern;
service-command=command
|
|
Of key interest is the command string. This is the command that should be executed to perform a service conversion (for example, invoke a document converter). The command must process an input file containing the message text to be serviced and produce as output a file containing the new message text. On UNIX, the command must exit with a 0 if successful and a non-zero value otherwise.
Environment variables are used to pass the names of the input and output files as well as the name of a file containing the list of the message's envelope recipient addresses. The names of these environment variables are:
INPUT_FILE - Name of the input file to process
OUTPUT_FILE - Name of the output file to produce
INFO_FILE - Name of the file containing envelope recipient addresses
The values of these three environment variables may be substituted into the command line by using standard command line substitution: that is, preceding the variable's name with a dollar character on UNIX.