Recipient access mapping tables

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


The ORIG_SEND_ACCESS, SEND_ACCESS, ORIG_MAIL_ACCESS, and MAIL_ACCESS mapping tables may be used to control who may or may not send mail, receive mail, or both. The access checks have available a message's envelope from address and envelope to addresses, and knowledge of what channel the message came in, and what channel it would attempt to go out; in additional, the ORIG_MAIL_ACCESS and MAIL_ACCESS mapping tables also have access to all the information available to the PORT_ACCESS mapping table. Note that when the envelope To addresses are irrelevant and only the envelope From address matters, then use of the FROM_ACCESS mapping table, described in FROM_ACCESS mapping table, may be more convenient and efficient.

If an ORIG_SEND_ACCESS or SEND_ACCESS mapping table exists, then by default for each recipient of every message passing through the MTA, the MTA will probe the ORIG_SEND_ACCESS and/or SEND_ACCESS mapping tables with a probe string of the form (note the use of the vertical bar character, |)

src-channel|from-address|dst-channel|to-address

where src-channel is the channel originating the message (i.e., enqueueing/submitting the message); from-address is the address of the message's originator; dst-channel is the channel to which the message will be enqueued/submitted; and to-address is the address to which the message is addressed. Use of an asterisk in any of these fields causes that field to match any channel or address, as appropriate; see Mapping table format for additional matching characters and sequences.

Note that the addresses here are envelope addresses, that is, envelope From address and envelope To address. The from-address used is by default the so-called mapped return address: the envelope From address after simple address reversal has been applied to it (but not including, for instance, destination-specific address reversal). However, the MTA options use_orig_return, and (new in MS 6.3) use_canonical_return, and (new in MS 7.0) use_auth_return, can be used to probe with a different form of the envelope From address. In the case of SEND_ACCESS, the envelope To address is checked after rewriting, alias expansion, etc., have been performed; in the case of ORIG_SEND_ACCESS the originally specified envelope to address is checked after rewriting, but before alias expansion.

The MTA options access_orcpt, access_counts, include_conversiontag, and include_spares1 (which in 8.0.2.2 replaced the previous include_spares MTA option) can cause inclusion of additional fields in the probes. If the relevant bits of all these options are set (the options take bit-encoded integer arguments with distinct bits controlling the inclusion of the fields in the distinct mapping tables), then the format of probes with all optional fields enabled becomes

src-channel|from-address|dst-channel|to-address|orcpt|access-counts|list-of-tags|s1|s2|s3|s4|s5|s6

The optional orcpt field is the SMTP ORCPT field; that is, it will contain the address type (typically "rfc822") followed by a semicolon, followed by the "original" to address, e.g., "rfc822;user@domain.com". The optional access-counts field contains a count of which recipient address (RCPT TO) this probe is for, followed by a forward slash, following by a count of the number of valid recipient addresses resulting from previous recipient address submissions (addresses resulting from previous RCPT TO commands), followed by a forward slash, potentially followed by additional counts expected to be added in future versions; so note that good practice is to always use an asterisk here, so that future additions will not cause old entries to stop working. The optional list-of-tags field contains a comma-separated list of conversion tags already present on this message. (Note that conversion tags apply to entire message copies, different recipient conversion tags causing message copy "split up". But these recipient address probes occur before final recipient determination and hence before application of recipient conversion tags occurs.) The optional s* fields contain the values of the LDAP attributes named by the ldap_spare_* MTA options.

The MAIL_ACCESS mapping table is a superset of the SEND_ACCESS and PORT_ACCESS mapping tables; that is, it combines both the channel and address information of SEND_ACCESS, with the IP address and port number information of PORT_ACCESS. (See PORT_ACCESS mapping table for discussion of the PORT_ACCESS mapping table.) Similarly, the ORIG_MAIL_ACCESS mapping table is a superset of the ORIG_SEND_ACCESS and PORT_ACCESS mapping tables. The format for the default probe string for MAIL_ACCESS is

port_access-probe-info|app-info|submit-type|send_access-probe-info

and similarly the format for the default probe string for ORIG_MAIL_ACCESS is

port_access-probe-info|app-info|submit-type|orig_send_access-probe-info

Here port_access-probe-info consists of all the information usually included in a PORT_ACCESS mapping table probe (see PORT_ACCESS mapping table) in the case of incoming SMTP messages (including originally-incoming-SMTP messages that have been deferred to the reprocess channel), or will be blank otherwise, and app-info will usually be SMTP/claimed-HELO-name in the case of messages submitted via SMTP or SMTP/claimed-HELO-name/TLS-crypto-info in the case of messages submitted via SMTP over TLS (including the case of originally-incoming-SMTP messages that have been deferred to the reprocess channel), and blank otherwise. submit-type may be one of MAIL, SEND, SAML, or SOML, corresponding to how the message was submitted into the MTA. Normally the value is MAIL, meaning it was submitted as a message; SEND, SAML, or SOML can occur in the case of broadcast requests (or combined broadcast/message requests) submitted to the SMTP server. And for the MAIL_ACCESS mapping table, send_access-probe-info consists of all the information usually included in a SEND_ACCESS mapping table probe (including, if the MTA options access_orcpt, access_counts, include_conversiontag, and/or include_spares1 are enabled, their respective additional fields). Similarly for the ORIG_MAIL_ACCESS mapping, orig_send_access-probe-info consists of all the information usually included in an ORIG_SEND_ACCESS mapping table probe (including, if the MTA options access_orcpt, access_counts, include_conversiontag, and/or include_spares1 are enabled, their respective additional fields). (See above for additional discussion of SEND_ACCESS and ORIG_SEND_ACCESS probes, as well as the access_orcpt, access_counts, include_conversiontag, include_spares1 MTA options.)

New in MS 7.0, the MTA option mapping_paranoia can cause vertical bars present within a field to be replaced by a different character, thereby ensuring that the only vertical bar characters in a probe are the field delimiter occurrences.

Now, if the probe string matches a pattern (i.e., the left hand side of an entry in the table), then the resulting output of the mapping is checked. If the output contains the flags $Y or $y, then the enqueue for that particular recipient (envelope To) address is permitted.

If the mapping output contains any of the flags $N, $n, $F, or $f, then the enqueue to that particular address is rejected. In the case of a rejection, optional rejection text may be supplied in the mapping output. This string will be included in the rejection error the MTA issues.+ (Unless an at-sign character, @, is part of the explicit rejection text, the MTA will append a colon and the recipient address to the end of the explicitly specified rejection text.) The specific enhanced status code, which in turn determines whether the error is temporary or permanent, can be specified through the use of $X; see the access mapping flags table below for details.

If no string is output (other than the $N, $n, $F, or $f flag), then some default rejection text will be used. As of 6.2, the exact default text depends upon the value of the access_errors option; by default, if that option is 0, then the full SMTP error, including text, is:


550 5.7.1 unknown host or domain: recipient-address

This default rejection text is rather intentionally misleading for reasons of security, as under some circumstances it may be desirable to avoid revealing the real reason for a rejection. When no such security concerns apply, it is often more user-friendly to take the option of specifing some explanatory rejection text, either your own choice of text, or set access_errors=1. If access_errors is 1, then the full SMTP error, including text, is: but if that option is 1, then the text is:


550 5.7.1 you are not allowed to use this address

Technical note:When the MTA generates a probe, it may also set various input flags specific to certain probe conditions: e.g., the A input flag is set if SMTP AUTH has been used. Though these input flags are not part of the string part of the probe, they may be detected (tested) in a mapping entry via flag comparison tests in the entry template (right hand side). See the "Input flag comparisons" section of Address access mapping table flags for a full list. Input flags are separate from output flags: even in an iterative mapping, a flag set as output on one line will not become an input flag for possible subsequent probes, as it is the original input flags which are the input flags for all the probes. Sophisticated uses of the *_ACCESS mapping tables may make use of such input flag tests to more precisely specify under which circumstances to apply mapping effects.

See Address access mapping table flags for descriptions of additional flags. Note that input flags (set by the MTA prior to probing) are the only flags that may be tested using the input flag comparisons. Output flags, those set in the template (right hand side) of a mapping entry, are separate and not subject to such testing.

Address access mapping table flags1
Output flag Description
$/ (New in MS 7.0) 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.3
$! Disable (Sieve requested) vacation messages regarding this message3
$* (New in MS 7.0 for FROM_ACCESS; new in MS 7.0u2 for the other address *_ACCESS mappings) If used with $N, force disconnect of the SMTP session.
$+L (New in MS 7.0.5) If used with $M in FROM_ACCESS, cause the captured message copy to be in journal format
$B Redirect the message to the bitbucket
$H Hold the message as a .HELD file
$J (New in MS 7.0u4) If used with $M, cause generation of envelope "journal" format rather than the default DSN encapsulated format for the "capture" message copy 5
$O Forces single-copy-per-recipient message copy "split up", as if the single channel option were set on the relevant destination channel(s).
$P Force to enqueue to the reprocess channel. (For instance, this might be useful as part of $.text. handling when attempting an LDAP lookup that encountered an LDAP directory temporary problem; that is, in case of an LDAP lookup problem, defer to the reprocess channel.)
$V Force Sieve filter discard behavior for all recipients of this message copy.
$v (New in MS 7.0u3) Force Sieve filter discard behavior for solely this recipient5. For FROM_ACCESS, $v remains equivalent to $V as meaning force Sieve filter discard for all recipients.
$Y Allow access.
$Z Force Sieve filter jettison behavior (non-overridable discard) for all recipients of this message copy.
$z (New in MS 7.0u3) Force Sieve filter jettison behavior (non-overridable discard) for solely this recipient5. For FROM_ACCESS, $z remains synonymous with $Z as meaning force Sieve filter jettison for all recipients.
Output flags with arguments, in argument reading order2
$Un Enable channel (slave) debugging; if the optional n argument is specified, it also sets the specified value for enqueue debugging.
$~channel-name (New in MS 7.0, as well as MS 6.3p1) Change source channel to channel-name -- this may be of especial interest for the case of incoming notification messages (incoming messages with empty envelope From). Note that when this feature is used and it actually changes the source channel, then the FROM_ACCESS check process is restarted; also, $~ can only be applied once.3
$Jaddress Replace original envelope From address with specified address3
$Kaddress Replace original Sender: address with specified address3 (Note that while $K sets the MTA's internal value for the sender, hence will affect various access checks, whether or not a new Sender: header line should be added to the message displaying the newly specified sender address is controlled by the authrewrite channel option; that is, use of $K does not, on its own, cause addition of a Sender: header line showing the new sender address.)
$Iuser|identifier Check specified user for specified groupid (UNIX) and if not in the group, reject access (effectively sets the $N output flag).
$<string Send string to syslog (UNIX) if probe matches; see also the sndopr_priority MTA options4
$>string Send string to syslog (UNIX) if access is rejected; see also the sndopr_priority MTA option4
$Ddelay Delay response for an interval of delay hundredths of seconds; a positive value causes the delay to be imposed on each command in the transaction; a negative value causes the delay to be imposed only on the address handover (SMTP MAIL FROM: command for the FROM_ACCESS table; SMTP RCPT TO: command for the recipient address access mapping tables).
$Tprobe-tag Prefix subsequent address *_ACCESS mapping table probes with the tag probe-tag. New in MS 7.0.5, the last such tag set may optionally be prepended to the AUTH_REWRITE mapping table probe.
$Aheader Add the header line header to the message; (see the spamfilter*_includeheaders MTA options if it is desired to have this added header line be visible to spam/virus filter packages).
$Gconv-tag (New in MS 6.0) Add the conversion tag (or comma-separated tags) conv-tag to the message.
$Maddress Capture a copy of the message, sending the captured and encapsulated copy to address. By default, this captured copy is DSN-encapsulated -- but see the no-argument, non-FROM_ACCESS  $J output flag above.
$Sx 
$Sx,y 
$Sx,y,z
FROM_ACCESS6: Set an effective blocklimit, and optionally recipientlimit, and optionally recipientcutoff for the transaction. Prior to MS 6.3, these values were minimized with whatever other such limits were already in effect; as of MS 6.3 these values override any global MTA option or source-based such limits that may already be effect (but destination-based limits will still be applied, later).3
$,x (New in 6.1) Set a spam level value x (between -10000 and 10000). If the message already had a spam level, this is a "spamadjust" effect (adds or subtracts the specified amount x from the prior spam level). Note that such a spam level/spamadjust effect applies to all recipients (even for the recipient-specific mapping tables such as SEND_ACCESS) in order for tests to see if one of the recipients is a "honeypot" address.
$Qlanguage 
$Qlanguage|country
(New in MS 6.3) Set a preferred language and optionally a preferred country3
$(postmaster-⁠address FROM_ACCESS6: (New in MS 6.3) Set an override postmaster address3
$)postmaster-⁠address (New in MS 6.3) Set an override postmaster address if none was previously set3
$+Ename|value (New in MS 7.0u2) Set the Sieve environment item  name to value
$+Rn|string (New in MS 7.0u2) FROM_ACCESS6: Opt-in to spam/virus filtering.7n specifies which spam/virus filter package; string is the opt-in string to pass to that spam/virus filter package.3 The string may be blank but the preceding vertical bar may not be omitted.
$+Rn1,s1,n2,s2,... (New in MS 8.0.2.3) FROM_ACCESS6: Opt-in to spam/virus filtering.7n1, n2 ... specifies the spam/virus filter packagew; s1, s2, ... specify the opt-in strings to pass to the associated spam/virus filter package.3 The opt-in strings may be blank but the commas may not be omitted.
$+^n1,n2,... (New in MS 8.0.1.3) FROM_ACCESS: Disable selected filters, overriding any source channel optins. The argument is a comma-separated list of integer values n1, n2, n3 ... specifying which spam filters to disable.
$+&n1,s1,n2,s2... (New in MS 8.0.2.2) FROM_ACCESS: Load sender spare attribute with specified value The argument is a comma-separated list of integer-string value pairs n1, s1, n2, s2 ... specifying the index of the attribute to load and the value to load into it.
$Wn (New in MS 8.0) FROM_ACCESS: Set the MT-PRIORITY level to n.
$Xerror-code Issue the specified error-code extended SMTP error code if rejecting the message; if the first digit of the extended SMTP error code x.y.z is a 4, then the rejection will be issued as a temporary rejection, 452 4.y.z, instead of the usual 550 5.y.z sort of permanent rejection
$Nstring Reject access with the optional error text string
$Fstring Synonym for $Nstring, i.e., reject access with the optional error text string
$(file-spec [ORIG_][SEND|MAIL]_ACCESS6: If rejecting a message to a mailing list (or other envelope-From-overridden sort of message) with other than a 4xx (temporary) error, override the usual error_text_* error text option values with values from the file file-spec; the values should be specified one per line in the file, in the order of the error_text_* options as shown in error_text_* MTA options.5
$Surl [ORIG_][SEND|MAIL]_ACCESS6: Apply the Sieve filter obtained from resolving url5
$+Rn|string (New in 7.0u2) [ORIG_][SEND|MAIL]_ACCESS6: Opt-in to spam filtering.7 Only applied if neither $N nor $F is set. n is which spam/virus filter package; string is the opt-in string to pass to that spam/virus filter package.5 The string may be blank but the preceding vertical bar may not be omitted.
$+Rn1,s1,n2,s2,... (New in MS 8.0.2.3) [ORIG_][SEND|MAIL]_ACCESS6: Opt-in to spam filtering.7 Only applied if neither $N nor $F is set. n1, n2, ... specify which the spam/virus filter packages to activate; s1, s2, ... specify the the opt-in strings to pass to the associated spam/virus filter package.5 The opt-in strings may be blank but the commas may not be omitted.
$+^n1,n2... (New in MS 8.0.1.3) [ORIG_][SEND|MAIL]_ACCESS6: Disable selected filters, overriding any active optins. The argument is a comma-separated list of integer values n1, n2 ... specifying which spam filters to disable. Note that this effect only extends to the current level of alias expansion - optins at inner levels will be honored.
Input flag comparisons Description
$:| (New in MS 7.0) Match only if external material (e.g., an envelope address) in the probe contained a vertical bar
$;| (New in MS 7.0) Match only if no vertical bars were present in any external material in the probe
$:A Match only if SMTP AUTH (authenticated submission) has been used
$;A Match only if SMTP AUTH (authenticated submission) has not been used
$:D Match only if DELAY delivery receipts have been requested (e.g., NOTIFY=DELAY)5
$;D Match only if DELAY delivery receipts have not been requested5
$:E (New in MS 6.3) Match only if ESMTP has been used
$;E (New in MS 6.3) Match only if ESMTP has not been used
$:F Match only if FAILURE delivery receipts have been requested (e.g., NOTIFY=FAILURE)5
$;F Match only if FAILURE delivery receipts have not been requested5
$:L (New in MS 6.3) Match only if LMTP has been used
$;L (New in MS 6.3) Match only if LMTP has not been used
$:P (New in MS 7.0) Match only if POP-before-SMTP was used
$;P (New in MS 7.0) Match only if POP-before-SMTP was not used
$:R (New in MS 8.0) Match if the current, enqueueing channel is an "internal" channel such as the reprocess channel
$;R (New in MS 8.0) Match if the current, enqueueing channel is something other than an "internal" channel
$:S Match only if SUCCESS delivery receipts have been requested (e.g., NOTIFY=SUCCESS)5
$;S Match only if SUCCESS delivery receipts have not been requested5
$:T Match only if TLS has been used
$;T Match only if TLS has not been used
$:V (New in MS 7.0u1) Match only if recipient address expanded via an alias5
$;V (New in MS 7.0u1) Match only if recipient address did not expand via an alias5
$:C (New in MS 8.0.1.3) Match only if message is the result of a capture/journal action.
$;C (New in MS 8.0.1.3) Match only if message is not the result of a capture/journal action.

1These flags are relevant for the SEND_ACCESS, ORIG_SEND_ACCESS, MAIL_ACCESS, ORIG_MAIL_ACCESS, and FROM_ACCESS mapping table, except where footnotes indicate special restrictions. Note that the PORT_ACCESS mapping table supports a somewhat different set of flags.

2To use multiple flags with arguments, separate the arguments with the vertical bar character, |, placing the arguments in the order listed in this table.

3Available for the FROM_ACCESS mapping table only.

4It is a good idea to use the $D flag when dealing with problem senders, to prevent a denial of service attack. In particular, it is a good idea to use $D in any $> entry or $< entry rejecting access.

5Not available for the FROM_ACCESS mapping table.

6This output flag has a different meaning and/or occurs in a different position, relative to other output flags, for FROM_ACCESS  vs. the other address *_ACCESS mapping tables. See the rest of this table for the other occurrence of this flag, describing its operation for the other type of mapping table.

7Only one $+R and corresponding value can be used in a single mapping result.

+ Note that it is up to whatever is attempting to send the message whether the MTA rejection error text is actually presented to the user who attempted to send the message. In particular, in the case when SEND_ACCESS is used to reject an incoming SMTP message, the MTA merely issues an SMTP rejection code including the optional rejection text; it is up to the sending SMTP client to use that information to construct a bounce message to send back to the original sender.

An example of an important use of the ORIG_SEND_ACCESS mapping table is discussed in Blocking SMTP relaying.


See also: