PORT_ACCESS mapping table

From Messaging Server Technical Reference Wiki
Jump to: navigation, search



The MTA Dispatcher is able to selectively accept or reject incoming connections to the services it manages such as SMTP, SMTP SUBMIT, or LMTP, based on IP address and port number. At Dispatcher startup time, the Dispatcher will look for a mapping table named PORT_ACCESS. If the mapping was present when the Dispatcher was started, then Dispatcher operation will include checking the mapping for each incoming connection. For each incoming connection the Dispatcher will format connection transport information in the form:


  TCP|server-address|server-port|client-address|client-port

and try to match against all PORT_ACCESS mapping entries. If the result of the mapping contains $N or $F, the connection will be immediately closed. Any other result of the mapping indicates that the connection is to be accepted. $N or $F may optionally be followed by a rejection message. If present, the message will be sent back down the connection just prior to closure.

As of MS 8.0.1.3, tildes (~) may be used as delimiters between multiplie lines in order to create a multiline response. Also note that a CRLF terminator will be appended to the string before it is sent back down the connection.

If no entry matched, then and only then will any dns_verify_domain lookups, as specified via a Dispatcher option (in particular in legacy configuration mode, in the Dispatcher configuration file), be performed, and the result of such a lookup is another way a connection may be refused. In particular, note that either an explicit rejection in PORT_ACCESS, or (as MS 6.0) a match without a rejection hence an "accept" effect will prevent dns_verify_domain lookups from occurring; this allows PORT_ACCESS to do initial filtering on connections, either "black listing" or "white listing" them, with dns_verify_domain taking effect only on any other source IP addresses.

The flag $< followed by an optional string causes the MTA to send the string to syslog (UNIX) if the mapping probe matches; the flag $> followed by an optional string causes the MTA to send the string to syslog (UNIX) if access is rejected.

If bit 1 (value 2) of the log_connection MTA option is set and the $N flag is set so that the connection is rejected, then also specifying the $T flag will cause a "T" entry to be written to the MTA connection log. Note that running processes do not notice the periodic "roll-over" of the mail.log_current file into the mail.log_yesterday file, and the creation of a new mail.log_current file; such changes are normally noticed merely because new processes come into existence and see the "new" file. But in the case of the Dispatcher, which is normally a very long running process (normally not restarted except at times of certain configuration changes), this means that the Dispatcher, which is writing the "T" records, will continue writing to the "old" log file. For instance, after a mail.log_current file has been renamed to mail.log_yesterday, the Dispatcher will keep writing its "T" records to the file it "knew" about, now named mail.log_yesterday; it will not know to start writing to mail.log_current unless and until the Dispatcher is restarted. (As of MS 6.2, the Dispatcher periodically (namely once an hour) forces a close and re-open of the connection log file.) So, if you are using "T" records, you may wish to restart your Dispatcher daily (at the time of log file rollover)---especially if you are running a version prior to MS 6.2.

The PORT_ACCESS mapping table, in addition to its normal use by the Dispatcher, is also optionally probed again by the SMTP server and LMTP server for the purpose of determining the appropriate SASL rule set (when SMTP AUTH has been used during message submission); as of 7.0, the SMTP server probe of the PORT_ACCESS mapping table is unconditional (always performed). (However, the LMTP server probe of PORT_ACCESS is still conditional.) Or enabling bit 4 of the log_connection MTA option also causes the SMTP server and LMTP server to probe the PORT_ACCESS mapping table; in this case site-supplied text may be provided in the PORT_ACCESS entry to include in the SMTP server's and LMTP server's application-info field---a field which is used in certain types of log entries (such as "C" connection log entries entries). To specify such text, include two vertical bar characters in the right hand side of the entry, followed by the desired text. New in MS 6.3-0.15, such SMTP server probes of PORT_ACCESS will respect the $N (in the case of SMTP AUTH usage), $>, and $< flags, whereas in prior versions the SMTP server probe results were only relevant for setting the SASL ruleset and the optional logging text; as of the fix for 12208860 (Sun 6590888) (MS 6.3-5.02), $N rejections will be respected in all cases. Thus new in MS 6.3-0.15 for the special case of SMTP AUTH use, and true in general subsequently, the SMTP server probes of PORT_ACCESS can be used to achieve connection rejections (in this case performed by the SMTP server processes, rather than by the main Dispatcher process); for "simple" rejections it is more efficient to perform such rejections from the main Dispatcher process, but for potentially complex or "slow" rejections (such as rejections determined by the results of DNS verification lookups), deferring the rejection until the individual SMTP server process stage can avoid "bottlenecking" the main Dispatcher process waiting for a result of a probe. (LMTP server probes of PORT_ACCESS remain, as previously, relevant only for setting the SASL ruleset and the optional logging text.)

PORT_ACCESS mapping flags
Flag Description
$U (New in 6.3-0.15) Enable channel debugging. As of 7.3-11.01, this includes consulting the mm_debug and os_debug MTA options and enabling any debugging they specify. This is only supported for SMTP server probes of the PORT_ACCESS mapping table; it is not supported for Dispatcher probes of the PORT_ACCESS mapping table.
$G (New in MS 7.0u5 for SMTP server; new in MS 8.1 for LMTP server) Enable TRACE_LEVEL=2 channel debug output. Only supported for SMTP or LMTP server probes; not supported for Dispatcher probes.
$V (New in MS 7.0) Enable the MTA's private SMTP extensions XADR, XCIR, XGEN, and XSTA, overriding any SMTP server DISABLE_* TCP/IP-channel-specific options. Only supported for SMTP server probes; not supported for LMTP server or Dispatcher probes.
$/ (New in 7.0-0.04) Set the "fast disconnect" flag for sessions that have not yet succeeded in starting a transaction; for such sessions, any subsequent disconnect is done with SO_LINGER enabled and a timeout of 0, which may clear slots quicker on intermediate firewalls and proxies. Only supported for SMTP server and Dispatcher probes; not supported for LMTP probes.
$Y Allow access.
$T If bit 1 of the log_connection MTA option is set, and if a connection is rejected ($N is also specified), then write a connection log file "T" record, including any of the optional text specified with $N. This is only supported for Dispatcher probes of the PORT_ACCESS mapping table; it is not supported for SMTP server or LMTP server probes of the PORT_ACCESS table.
  Flags with arguments, in argument reading order1
$Astring (New in Messaging Server 7.4-18.01; for LMTP server, new in MS 8.0.1.) Set the HULA debug flags specified by the argument string; comma-separated flags can be "perf", "connect", "authserv", and "hula"; see the AUTH_DEBUG TCP/IP-channel-specific option. This is only supported for SMTP server and LMTP server probes of the PORT_ACCESS mapping table; it is not supported for Dispatcher probes of the PORT_ACCESS mapping table.
$<string Send string to syslog (UNIX) if probe matches.
$>string Send string to syslog (UNIX) if access is rejected.
$Nstring Reject access with the optional error text string.
$Fstring Synonym for $Nstring, i.e., reject access with the optional error text string.
$Ddelay (New in 6.3-0.15) Delay the banner flush by the specified number of centiseconds, overriding the BANNER_PURGE_DELAY value. This is only supported for SMTP server probes of the PORT_ACCESS mapping table; not supported for LMTP server or Dispatcher probes of the PORT_ACCESS mapping table.
$Schannel-name (New in Messaging Server 7.0-0.04) Set the specified channel as the source channel for this SMTP session. This is only supported for SMTP server probes of the PORT_ACCESS mapping table; it is a no-op for the LMTP server or Dispatcher probes of the PORT_ACCESS mapping table.
$Bbanner-host (New in Messaging Server 8.1.0.7) Set the specified host as the banner host this SMTP/LMTP session. This is only supported for SMTP/LMTP server probes of the PORT_ACCESS mapping table; it is a no-op for the Dispatcher probes of the PORT_ACCESS mapping table.
$Ibanner-addition (New in Messaging Server 8.1.0.7) Set the specified string as the banner addition this SMTP/LMTP session. This is only supported for SMTP/LMTP server probes of the PORT_ACCESS mapping table; it is a no-op for the Dispatcher probes of the PORT_ACCESS mapping table.
Additional non-flagged fields Description
TLS-certificate-nicknames (New in Messaging Server 7.0-0.04) Comma-separated list of TLS certificate nicknames (which must appear subsequent to a vertical bar character). This is only supported for SMTP server probes of the PORT_ACCESS mapping table; not supported for LMTP server or Dispatcher probes of the PORT_ACCESS mapping table.
text If bit 4 of the log_connection MTA option is set, then the optional text text (which must appear subsequent to two vertical bar characters) may be included in the connection log "C" entry tm. This is only supported for SMTP server and LMTP server probes of the PORT_ACCESS mapping table; it is not supported for Dispatcher probes of the PORT_ACCESS mapping table.
Flag comparisons Description
$:A Match only when the probe is performed by the Dispatcher
$;A Match only when the Dispatcher is not performing the probe
$:S Match only when the probe is performed by an SMTP server or LMTP server
$;S Match only when neither an SMTP server nor an LMTP server is performing the probe

1To use multiple flags with arguments, or the non-flagged fields, separate the arguments with the vertical bar character, |, placing the arguments in the order listed in this table.

Note that prior to MS 6.3-0.15, Dispatcher probes of the PORT_ACCESS mapping table could not make use of LDAP callouts ($]...[ callouts).

The following example PORT_ACCESS mapping will only accept SMTP connections (to port 25, the normal SMTP port) from a single network, except for a particular host singled out for rejection without explanatory text:


PORT_ACCESS

  TCP|*|25|192.123.10.70|*     $N500
  TCP|*|25|192.123.10.*|*      $Y
  TCP|*|25|*|*                 $N500$ Bzzzzzzzzt$ thank$ you$ for$ playing.

Note that you will need to restart the Dispatche - or as of MS 6.3-0.15 use the imsimta reload utility to reload the changed mappings file into running processes such as the Dispatcher - after making any changes to the PORT_ACCESS mapping table so that the Dispatcher will see the changes. (Note that this requires a compiled MTA configuration and you'll first need to recompile before reloading.)

The PORT_ACCESS mapping table is specifically intended for performing IP number based rejections; for more general control at the email address level, the e-mail address access mappings such as SEND_ACCESS or MAIL_ACCESS may be more appropriate.


See also: