The remote host is qmail-remote's first argument, host. qmail-remote sends the message to host, or to a mail exchanger for host listed in the Domain Name System, via the Simple Mail Transfer Protocol (SMTP/ESMTP) perhaps encrypted via STARTTLS/TLS or the Quick Mail Transfer Protocol (QMTP/QMTPS). Prior of setting up a TLS connection, qmail-remote will lookup automatically the corresponding TLSA record in the DNS and uses this for X.509 certificate validation. host can be either a fully-qualified domain name:
silverton.berkeley.edu
or an IPv4 or IPv6 address enclosed in brackets:
[128.32.183.163]
[2001::163]
In case the primary mail exchanger for that Domain
will issue a 5xy reply message during the connection,
qmail-remote
will contact all responsible mail exchangers in turn
in order to deliver the message anyway.
The envelope recipient addresses are listed as recip arguments to qmail-remote. The envelope sender address is listed as sender.
In case the remote host issues the EHLO SIZE extension, qmail-remote will handover the size of the message (in byte) prior of transmission and respects the remote host's reply code.
Note that qmail-remote does not take options and does not follow the getopt standard.
After this letter comes a human-readable description of what happened.
qmail-remote may use SMTP Authenticaton to connect to remote hosts. The following reports are provided:
The recipient reports will always be printed in the same order as qmail-remote's recip arguments. Note that in failure cases there may be fewer recipient reports than recip arguments.
In case a CNAME can not be resovled qmail-remote issues the following message:
If a SMTP connection is bound to a none-existing IP address qmail-remote will complain with the message:
In case a QMTP connection can not be established qmail-remote will issue the error message:
On demand qmail-remote supports TLS/STARTTLS and will log the following notifications:
qmail-remote needs to read some X.509 certificates and key files prior of setting up a TLS connection. Failures are indicated as:
Connection problems for TLS are not uncommon. Here, host is the domain or host to connect with and remotehost is the corresponding MX. qmail-remote provides the following diagnostic messages:
For each MX to reach via TLS, qmail-remote performs an automatic TLSA lookup comparing the received X.509 fingerprints with the issued cert during the TLS handshake. X.509 certificate checks can also been performed. Failures here are given as:
@example.com:relay.example.com|user|passwd
info@example.com:relay.example.com;26|infouser|infopasswd
:mailrelay.example.com|e=mc2|testpass
inside.af.mil:firewall.af.mil;26
:submission.myrelay.com;s587|myuserid|mypasswd
However, authsenders routes have precedence.
relay may be empty; this tells qmail-remote to look up MX records as usual. smtproutes may include wildcards:
.af.mil:
:heaven.af.mil
Here any address ending with .af.mil (but not af.mil itself) is routed by its MX records; any other address is artificially routed to heaven.af.mil.
The outgoing IP address used by qmail-remote can be specified:
:bouncehost.org||10.1.1.0
:partnermx.net;42||2001::fefe
Note: localip can be private IP address subject of NAT'ing.
Additionally, smtproutes allows to forward bounces (with a 'Nullsender' MAIL FROM: <>) literally expressed as '!@' to a particular bounce host:
!@:bouncehost.af.mil;27
The qmail system does not protect you if you create an artificial mail loop between machines. However, you are always safe using smtproutes if you do not accept mail from the network.
(0) *: # Enable TLS but fallback to NOTLS (default);
server authentication is optional, given further settings
Special settings:
(1) ?: # fallthru to no TLS in case of TLS protocol errors (exceptional)
(2) -: # allow anonymous connections
(3) /: # disable TLSA lookup and verification
Double character rules instruct
qmail-remote
to require a STARTTLS or SMTPS connection (mandatory TLS):
(4) -*: # at least anonymous connections
(5) +*: # require and validate X.509 certs
(6) ~*: # cert + validate SAN/DN, however accept wildcard certs and partial matching
(7) =*: # cert + validate SAN/DN against FQDN
(8) /*: # don't do TSLA lookup and X.509 matching
Additionally, qmail-remote can be told to use per-domain connection settings:
(9) example.com:
(10) securityfirst.com:/etc/ssl/cafile.pem|!SSLv2:HIGH
(11) remote.com:/etc/ssl/certdir/||3;465
(12) mx.partner.com:/etc/ssl/partnerca.pem||2|mydomain.net
(13) =mx.myfriend.com:/etc/ssl/cacert.pem||4
(14) ~wildneighbor.net:
(15) -adhonlydomain.com:||aNULL:!kRSA
(16) %peer.partner.com:=E44194C56EF.....
(17) !nosslhost.example.com:
(18) hiddenpartner.org:;35
(19) ?tlsold.net:
(20) /nodane.org:
The ninth line requires from qmail-remote to demand a STARTTLS connection for any destination address targeting domain example.com.
The tenth line accepts STARTTLS connections for securityfirst.com only, if the X.509 certificate can be verified against the CA cert as provided via /etc/ssl/cafile.pem and with the acceptable ciphers SSLv2:HIGH.
Line number eleven tells qmail-remote to use a SMTPS connection on port 465 to any host at remote.com and accept this host only, if the peer's cert can be validated against the CA certs available in /etc/ssl/certdir/ and does not exceed a verification depth of 3.
Line twelve shows an example, how tlsdestinations can be bound exclusively to a sender domain. In the shown case, only if mx.mydomain.net is used as sender domain, a connection for the destination address mx.partner.com is mandatory secured by TLS with a CA cert available as /etc/ssl/partnerca.pem with a verification depth of 2.
Furthermore, the sample on line thirteen demonstrates the case where qmail-remote sees a destination address concatinated with =. Now it will only accept the certificate, if the X.509's DN can be validated against the FQDN of the server (by means of a DNS lookup) and it verifies against the cacert.pem CA certificate and does not exceed a verification depth of 1.
In case a certain destination may use 'wildcard' domain names in the SAN/DN, qmail-remote can cope with this (line fourteeen) prepending the destination with a '~': ~wildneighor.net. This mechanism also supports partial matching of SAN/DN and domain name.
In the same sense (line fiveteen), qmail-remote may accept TLS connections based on Anonymous DH (ADH) - where the server does not provide a cert for authentication - once the domain name is prepended with a - as key encryption cipher and discards !RSA for authentication if told so.
Certificate pinning for a particular %host indicated by the leading character '%' is shown on line sixteen. Instead of the CA file, now the =fingerprint of the peer host certificate needs to be provided. The X.509 fingerprint should prepended with an equal sign ('=') and to be stripped from additional colons (':'). The fingerprint string is evaluated case-insensitive. qmail-remote's certificate pinning supports SHA1, SHA224, SHA256, and SHA512 digests, determined by the length of the fingerprint given.
Note, that in this case, no TLSA validation is performed; it is thus a 'silent' verification'. qmail-remote can be instructed to omit the STARTTLS command for the recipient address nosslhost.example.com as indicated with a leading ! as shown on line seventeen. This behavior can be relaxed (line nineteen) using ? followed by a colon, a host, or domain name. Now qmail-remote will initally try a TLS connection by however is alllowed to switch back to none-encryption mode, in case this is not possible due protocol reasons.
qmail-remote allows an 'implicit TLS' connection on any port, if port is prended with an s even without providing the port.
In case, no particular ciphers or CA certs are required, a colon/semi-colon ':;' can be used as shortcut (line eighteen). Generally, any port can be provided after the semi-colon. If however, port equals 465, SMTPS will be used instead of STARTTLS and if port equals 6209, QMTPS is the chosen transport protocol. The settings here overrule previous instructions.
Finally, TLSA lookups can be disabled, prepending a domain name with / for the target domain as shown on line twenty.
Note that 'destination' is subject of the forwarding rules as provided by authsenders, qmtproutes, and smtproutes. qmail-remote needs to read the message from a (seekable) file in order to announce the SIZE in the SMTP dialogue. However, if called through a pipe, it will not provide this information to the receiving MTA. More severe, a delivery over QMTP(S) will fail.