Chapter 7 Connecting to Other Internet MTAs
7.3 Using TLS with SMTP
7.6.2 Options affecting SMTP authentication
7.6.2.1 Options specific to LDAPDB plugin
LDAPDB is an auxiliary property (auxprop) plugin used for password verification by SASL plugins implementing the SASL authentication method. If you want to store usernames and passwords for SMTP AUTH in LDAP, you need to use LDAPDB. This plugin requires some configuration options, which are listed below.
The following internal variables affect LDAPDB:
ldapdb_uri[=<ldapurl>] [P]
This option specifies the LDAP server hostname and port number to connect to. If this option is not specified, the default value is going to be constructed from ldap_host
and ldap_port described below.
• If ldap_host is not specified, then the value localhost is used when constructing
ldapdb_uri
• If ldap_port is not specified, then the default LDAP port 389 is assumed when constructing ldapdb_uri
ldap_host[=<hostname>]
This option specifies the LDAP server hostname to connect to. LDAPDB ignores this option if ldapdb_uri is specified.
ldap_port[=<portnum>]
This option specifies the LDAP server port number to connect to. LDAPDB ignores this option if ldapdb_uri is specified.
sasl_ldapdb_dn=<Distinguished Name of target MTA> [P]
This is the Distinguished Name to be used in the LDAP bind. This DN must have the right to read the userPassword attribute for users stored in LDAP. If this option is not specified, the value of dap_user option (see below) is used instead. This value is only used if sasl_ldapdb_mech has the value SIMPLE.
sasl_ldapdb_id=<SASL username> [P]
This is the SASL username to be used in the LDAP SASL bind. This user must have the right to read the userPassword attribute for users stored in LDAP. If this option is not specified, the value of the ldap_sasl_user option is used instead. This value is only used if sasl_ldapdb_mech has any value other than SIMPLE.
sasl_ldapdb_pw=<password>
This is the password to be used in the LDAP bind. If this option is not specified, the value of dap_passwd option (see below) is used instead.
dap_user=<Distinguished Name of target MTA>
This is the Distinguished Name to be used in the LDAP bind. LDAPDB ignores this option if the sasl_ldapdb_dn option is specified.
dap_passwd=<password>
This is the password to be used in the LDAP bind. LDAPDB ignores this option if the
sasl_ldapdb_pw option is specified.
sasl_ldapdb_mech={SIMPLE|<SASL mechanism>} [P]
This option contains the name of the SASL mechanism to use in LDAP SASL bind, or the word SIMPLE, if LDAP Simple is to be used. If this option is not specified, the value of the ldap_sasl_mech option is used instead.
From this list the following options must be specified: • sasl_ldapdb_mech
• either sasl_ldapdb_dn or sasl_ldapdb_id, depending on the value of the
sasl_ldapdb_mech option • sasl_ldapdb_pw
The following channel variables affect LDAPDB (note that they need to be specified for each SMTP channel that allows SMTP AUTH):
sasl_saslMappingRule=<rule number>
This option specifies how M-Switch users will be located in the corresponding Directory. Valid values are
• 0 ("AD compatible" mapping), • 1 ("Domain Part search"), • 2 ("Two searches") or • 3 ("Single searche")
Other options listed below specify which options are used by which mapping rule.
sasl_saslUsernameAttribute=<attribute name> [P]
(only used for sasl_saslMappingRule=0|1|2)
This option specifies the attribute that contains the local part of a userid.
sasl_saslDCMappingSuffix=<base Distinguished Name> [P]
This option specifies the base DN for all user entries.
sasl_saslUserParent=<Relative Distinguished Name> [P]
This option specifies a Relative Distinguished Name (also called a ‘container’) for all user accounts in the same domain (with the same right hand side). The empty string is used when this option is not specified.
sasl_saslSearchSuffix=<base Distinguished Name> [P]
(only used for sasl_saslMappingRule=1|2|3)
This option specifies the base DN for LDAPDB searches for user entries.
sasl_saslDomainAttribute=<attribute name> [P]
(only used for sasl_saslMappingRule=1|2)
This option specifies the attribute that contains the domain (right hand side) part of a userid.
sasl_saslFullUsernameAttribute=<attribute name> [P]
(only used for sasl_saslMappingRule=3)
This option specifies the attribute that contains a complete userid.
sasl_saslDefaultDomain=<domain> [P]
(only used for sasl_saslMappingRule=1|2) This option specifies the default SASL domain.
sasl_saslUsernamePrefix=<string> [P]
(only used for sasl_saslMappingRule=3)
This option specifies an optional prefix to strip from a value of the
sasl_saslFullUsernameAttribute attribute.
7.6.2.2
How different mapping rules work
Each SASL mapping takes a userid (in <user>@<domain> format) and converts it to the corresponding DN in the LDAP Directory. Note that each mapping must be 1-to-1, i.e. if multiple entries end up satisfying an LDAP search used to find the corresponding user, M-Switch assumes that there is no match.
• AD compatible mapping
This mapping rule can be used to construct a DN that is compatible with DNs used in Active Directory. The mapping is a static algorithm.
• The user (left hand side) part of the SASL userid is used to form the least significant RDN,with an attribute type of sasl_saslUsernameAttribute option.
• An additional RDN sequence, specified in the sasl_saslUserParent option, is then optionally appended.
• The domain part of the SASL userid is split into multiple subdomains, and each subdomain is used to construct a DC-style RDN sequence which is then appended. • An additional RDN sequence, specified in sasl_saslDCMappingSuffix option,
is then optionally appended.
When this configuration is in force, the userid [email protected] will have a DN of:
<sasl_saslUsernameAttribute>=user, <sasl_saslUserParent>, dc=example, dc=com, <sasl_saslDCMappingSuffix>
• "Domain part search" mapping
This mapping supports holding users with multiple SASL domains in multiple separate subtrees.
• If the SASL userid has a domain that is different from the default domain, then: • search from Search base DN for entries matching Domain attribute=domain.
The DN of the matching entry is used for domainsuffix. Otherwise:
• set the domainsuffix to the Search base DN.
• The user part of the SASL userid is used to form the least significant RDN, with an attribute type of sasl_saslUsernameAttribute option.
• The domainsuffix is appended.
For example, with the SASL userid [email protected], the default domain is set to example.net, the Search base DN set to o=My Corp, c=US, and
theUsername attribute set to cn, the resulting DN would be cn=barabash, o=My Corp, c=US
The Search base DN value is set from the sasl_saslSearchSuffix option. The
Domain attribute is set from the sasl_saslDomainAttribute option (the default value is cn). The Username attribute is set from the sasl_saslUsernameAttribute
option (the default value is uid). • "Two searches" mapping
This mapping rule is similar to the "Domain Part search" mapping rule, except that instead of forcing all user entries to be directly below the domain suffix, step 2 performs a subtree search under the domain suffix for the user.
• If the SASL userid has a domain that is different from the default domain, then: • search from Search base DN for entries matching Domain attribute=domain.
The DN of the matching entry is used for domainsuffix. otherwise:
• set the domainsuffix to the Search base DN.
• Perform a subtree search from domainsuffix for entries matching Username
attribute=username. The resulting match is used as the DN. • "Single search" mapping
This mapping rule is the most flexible, as it allows users in the same subtree to have different SASL domains. It does this by searching for the complete SASL userid. • Search from Search base DN for an entry matching Full username attribute=userid.
The resulting match is used as the DN.
For example with the SASL userid [email protected], and Full username
attribute set to uid, the Directory Server would search for a single entry matching
The Full username attribute value is set from the
sasl_saslFullUsernameAttribute option.
7.7
LEMONADE related extensions
The SMTP server supports several extensions to Message Submission defined by the IETF Lemonade Working Group (http://www.ietf.org/html.charters/lemonade-charter.html). The M-Switch SMTP server implements all SMTP extensions listed in the Lemonade Profile document (RFC 4550, section 6). From this list of SMTP extensions, you only need to configure STARTTLS (see Section 7.3, “Using TLS with SMTP” for more details) and
BURL (see below) to enable them, as other extensions are supported automatically and do not need configuring.
Note: Even though SMTP AUTH is automatically advertised by the SMTP server, you might want to configure it as described in Section 7.6, “SMTP authentication”. To be able to assemble messages from pieces referenced by BURL URLs, the SMTP server needs to know how to authenticate to IMAP servers referenced by such URLs.
Information about allowed IMAP servers is kept in $(ETCDIR)/switch/burl.xml. This is an XML file, which has the following format:
• The top level XML element must be <endpoints>
• For each trusted IMAP server there is an <endpoint> XML element below the top level element, which does not contain any subordinate elements or text.
The <endpoint> XML element has one optional and three mandatory attributes: • host, which specifies the hostname or IP address of an IMAP server
• port, which specifies the port number of the IMAP server – this is optional and defaults to 143 if not specified
• username and password, which are the username and password used to authenticate to the server specified by the host and optional port
Here is an example $(ETCDIR)/switch/burl.xml:
<endpoints>
<endpoint host="imap.example.com" port="143" username="smtpserver" password="some-secret"/> </endpoints>
7.8
SMTP client
The SMTP client supports the following SMTP extensions:
Message size declaration [RFC 1870]
SIZE
8bit-MIME transport [RFC 1652]
8BITMIME
Client side pipelining [RFC 2920]
PIPELINING
Delivery Status Notifications [RFC 3461]
DSN
Enhanced Error Codes [RFC 2034]
ENHANCEDSTATUSCODES Secure SMTP over TLS [RFC 3207] STARTTLS Deliver by extension [RFC 2852] BY Message priority [RFC 6710] MT-PRIORITY
The SMTP client program for outbound messages makes use of additional tailoring variables in the channel specification. The following per-channel variables (also called ‘options’ below) are currently recognized:
noesmtp
do not attempt to use SMTP extensions
nomx
Do not use DNS MX records
port=<integer>
Set the TCP port to be used to integer
The following option affects SMTP client behaviour on unexpected disconnect:
reconnect_retries=<integer>
Set the number of reconnect retries to integer
If the SMTP client detects a TCP disconnect while sending a message to another SMTP server and this option is not 0, the SMTP client will immediately try to reconnect to the SMTP server instead of notifying Qmgr about the problem.
If the client receives a 4XX SMTP error code in the SMTP greeting after reconnecting, it will disconnect and reconnect again.
The reconnect_retries option contains the number of such reconnects, not counting the first reconnect attempt. The default value is 0, which means that SMTP client will not reconnect following a TCP disconnect.
The following option affects Delivery Status Notification (DSN) extension [RFC 3461] behaviour:
relaydsn
If this option is set to true and DSN is requested for a message, then the SMTP client will generate ‘relayed’ DSNs even if the receiving server supports DSN. The default is false.
The following options affect how a message content is converted before sending it to another host:
line=<integer>
Sets a limit on the length of line that is sent. SMTP and RFC 1652 state that no more than 998 characters should be sent before a line break. By default there is no limit on the line length. This option has no effect if encode=none is specified (see below).
encode=<value>
Controls how messages are sent. Values of none and default may result in sending messages which are invalid. The table below describes valid encode values and the resulting action on the SMTP sender.
If the body part is mime-unknown and the receiving host indicates support for the 8BITMIME ESMTP extension then the message will be marked as
default
BODY=8BITMIME, otherwise an attempt will be made to downgrade the content to a 7-bit transfer encoding if necessary. Any invalid binary data in headers or content parts will be passed as is. This setting does its best to send only valid messages but will not refuse to transmit a message that it cannot fix.
No conversion of content will occur on transmission. If the body part is mime-unknown and the receiving host indicates support for the 8BITMIME none
ESMTP extension the message will be marked as BODY=8BITMIME. Any invalid binary data in headers or content parts will be passed as is. 8-bit MIME content may be sent to hosts which do not support it. This setting does not alter a message in transit but may send messages which are invalid. If the body part is mime-unknown and the receiving host indicates support for the 8BITMIME ESMTP extension then the message will be marked as
strict
BODY=8BITMIME, otherwise an attempt will be made to downgrade the content to a 7-bit transfer encoding if necessary. Any invalid binary data in headers or content parts will cause non-delivery of the message. This setting
will not send invalid messages. It will attempt to downgrade messages with 8-bit content to a 7-bit transfer encoding.Jpara
An 8bit message is one which is flagged as 8bit when transferred into the message switch from a SMTP client, using the 8BITMIME SMTP extension [RFC 1652]. A message is also flagged as 8bit if, when the shaper channel processes a message, MIME body parts that have 8bit or binary content transfer encoding are found.
When an 8bit message is transferred to a host that supports the 8BITMIME extensions, it is flagged as an 8bit message to that host, and transferred unchanged. When the receiving host does not support the 8BITMIME extension, or the message is not flagged as 8bit, then the transfer method depends on the configuration of the encode option.
7.9
LMTP channel
LMTP (RFC 2033) is a variant of SMTP optimized for delivery to local POP/IMAP Message Stores, also supported by Isode’s M-Box server. Message Delivery by LMTP is provided by the slmtp process. This process is started by the Qmgr process (see Section 15.3, “Queue Manager”), which may run many instances of the slmtp program. (Note that the similarity of the SMTP and LMTP protocols mean that the same program is run when the SMTP and LMTP channels are invoked).
The LMTP channel is configured in the same way as the outbound SMTP channel (see
Section 7.8, “SMTP client”), with the following exceptions: • The channel name is usually lmtp
• The channel type is always out (type=out)
• The destination LMTP server is specified in the lmtp channel variable. This variable can contain one of the following:
• a Unix domain socket, for example:
"lmtp=/var/run/lmtp"
• TCP <hostname>:<port>, for example:
"lmtp=lmtp.example.com:2001"
Note: The latter form must be used on Windows.
Note: It is also possible to connect to LMTP over TCP by using lmtp=<hostname>
and port=<port>
Note: The TCP port number should NOT be set to 25.
The following example shows a typical configuration for the LMTP channel:
chan lmtp prog=slmtp show="with LMTP" type=out adr=822
The following channel variables used by outbound SMTP channel have no effect on the LMTP channel:
• noesmtp
• nomx