-
-
Notifications
You must be signed in to change notification settings - Fork 3
qmail remote.8
qmail-remote - send mail via SMTP / ESMTP or QMTP
qmail-remote host sender qqeh size recip [ recip ... ]
qmail-remote reads a mail message from its input and sends the message to one or more recipients at a remote host. The remote host host is qmail-remote's first argument. 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) or the Quick Mail Transfer Protocol (QMTP). QMTP is implemented by qmail-qmtpd. host can be either a fully-qualified domain name:
silverton.berkeley.edu
or an IP address enclosed in brackets:
[128.32.183.163]
The size parameter is only used if the remote host uses the ESMTP SIZE extension defined in RFC- 1870. It gives the size of the message in bytes. qmail-remote does not use this value to process the mail, the value is only passed to the remote mailserver.
The envelope recipient addresses are listed as recip arguments to qmail-remote.
The envelope sender address is listed as sender.
If the environment variable SMTPUTF8 is defined, qmail-remote will respect SMTPUTF8 and EAI addresses. If message is utf8, qmail-remote will use idn2_lookup_u8(3) to perform IDNA2008 lookup string conversion on host.
Any Qmail Queue Extra Header (QQEH) information passed to qmail-queue(8), is passed in the qqeh argument.
If qmail-remote is not able to get the greeting from the remote SMTP server, it tries the next MX (as per rfc-2821(5)) under the following conditions
1. connection to remote host gets dropped without a greeting from the remote host
2. greeting code >= 400 and < 500
3. ehlo/helo code >= 400 and < 500 (enabled by setting TRY_NEXT_MX_HELO_FAIL environment variable)
4. connection to the remote host times out.
In these cases, the remote host's IP address is recorded in the timeout table /var/indimail/queue/lock/tcpto, which causes subsequent deliveries to back off from the IP address and try the next MX (if it exists). qmail-tcpto(8) can be used to print the TCP timeout table.
qmail-remote is MXPS compliant. If it sees the MX record
12801 mailin-01.mx.aol.com
it will try a QMTP connection to mailin-01.mx.aol.com before trying a SMTP connection to mailin-01.mx.aol.com. The point is that QMTP is faster than SMTP. If the QMTP connection attempt fails, the client tries a SMTP connection to port 25 as usual. qmail-remote does not try SMTP if the QMTP connection attempt succeeds but mail delivery through that connection fails. You can disable MXPS by setting DISABLE_MXPS environment variable.
qmail-remote will issue the STARTTLS command if it finds the remote server supports STARTTLS and it finds a valid certificate in /etc/indimail/certs/clientcert.pem. qmail-remote will revert to non-encrypted session if the TLS connection fails.
qmail-remote can use authenticated SMTP for remote deliveries if username and secret is provided in the /etc/indimail/smtproutes control file described in the section CONTROL FILES. qmail-remote uses libgsasl to use GNU Simple Authentication and Security Layer detailed here https://www.gnu.org/software/gsasl. qmail-remote supports LOGIN, PLAIN, CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-RIPEMD, DIGEST-MD5 authentication using built-in functions and SCRAM-SHA-1, SCRAM-SHA-256, SCRAM-SHA-1-PLUS, SCRAM-SHA-256-PLUS authentication provided by libgsasl. Note that DIGEST-MD5 has been moved to historic (https://www.rfc-editor.org/rfc/rfc6331.html).
qmail-remote normally gets called by qmail-rspawn but can be called by spawn-filter when you set the QMAILREMOTE environment variable to /usr/sbin/spawn-filter. spawn-filter(8) can do tasks like filtering, running custom scripts, etc before running qmail-remote. qmail-remote is controlled by several environment variables, described in this manual. It is possible to have an elaborate scheme to run a custom script/program instead of qmail-remote by setting the QMAILREMOTE environment variable as full path to your custom script/program. The custom script can then call qmail-remote after doing certain things. A useful utility to call in such custom scripts/programs is the ctrlenv(8) utility. ctrlenv(8) can call qmail-remote after seting various environment variables based on the recip address. Note that qmail-remote does does not follow the getopt standard and it is not possible to set options. In cases where you want a customized behaviour, it is possible to do that with a combination of QMAILREMOTE and the ctrlenv(8) utility.
qmail-remote supports DANE verfication, described in RFC-7671. if the environment variable DANE_VERIFICATION is set without '@' sign, then qmail-remote will use it's own internal dane verification function.
DANE_VERIFICATION=""
If this variable is set as host@port, then qmail-remote will use the tlsacheck(3) function and attempt to verify DANE status by connecting to qmail-daned(8) - qmail DANE verification daemon
DANE_VERIFICATION="127.0.0.1@1998"
DANE verification can be restricted on per host basis by having the tlsadomains control file.
End-of-file in SMTP is encoded as dot CR LF. A dot at the beginning of a line is encoded as dot dot. It is impossible in SMTP to send a message that does not end with a newline. qmail-remote converts the UNIX newline convention into the SMTP newline convention by inserting CR before each LF.
It is a violation of the SMTP protocol to send a message that contains long lines or non-ASCII characters. However, qmail-remote will happily send such messages. It is the user's responsibility to avoid generating illegal messages.
qmail-remote may use SMTP Authenticaton to connect to remote hosts. The following reports are provided:
K
no supported AUTH method found, continuing without authentication.
Z
Connected to host but authentication was rejected (AUTH PLAIN).
Z
Connected to host but unable to base64encode (plain).
Z
Connected to host but authentication was rejected (plain)."
Z
Connected to host but authentication was rejected (AUTH LOGIN).
Z
Connected to host but unable to base64encode user.
Z
Connected to host but authentication was rejected (username).
Z
Connected to host but unable to base64encode pass.
Z
Connected to host but authentication was rejected (password).
Z
Connected to host but authentication was rejected (AUTH LOGIN, PLAIN,
CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-RIPEMD,
DIGEST-MD5, SCRAM-SHA-1, SCRAM-SHA-256, SCRAM-SHA-1-PLUS,
SCRAM-SHA-256-PLUS)
Z
Connected to host but unable to base64decode challenge.
Z
Connected to host but got no challenge.
Z
Connected to host but unable to base64encode username+digest.
Z
Connected to host but authentication was rejected (username+digest).
qmail-remote prints some number of recipient reports, followed by a message report. Each report is terminated by a 0 byte. Each report begins with a single letter:
r
Recipient report: acceptance.
h
Recipient report: permanent rejection.
s
Recipient report: temporary rejection.
K
Message report: success. host has taken responsibility for delivering
the message to each acceptable recipient.
Z
Message report: temporary failure.
D
Message report: permanent failure.
After this letter comes a human-readable description of what happened.
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.
If ONSUCCESS_REMOTE environment variable is defined and points to a program, qmail-remote will execute the same, with uid qmailr, on successful email delivery to remote host host. The exit status of qmail-remote will be the exit status of the program. The argument passed to this program will be the same as those for qmail-remote.
If ONFAILURE_REMOTE environment variable is defined and points to a program, qmail-remote will execute the same, with uid qmailr, on a failed email delivery to remote host host. The exit status of qmail-remote will be the exit status of the program. The argumen t passed to this program will be the same as those for qmail-remote.
If ONTEMPORARY_REMOTE environment variable is defined and points to a program, qmail-remote will execute the same, with uid qmailr, on a deferred email delivery to remote host host. The exit status of qmail-remote will be the exit status of the program. The argument passed to this program will be the same as those for qmail-remote.
If neither of these variables ONSUCCESS_REMOTE, ONFAILURE_REMOTE and ONTEMPORARY_REMOTE are defined, qmail-remote will always return zero exit status.
When these two variables are set, qmail-remote will also set the following environment variables
SMTPTEXT
This will contain last SMTP conversion with the remote SMTP server. In
case of any error, this will contain the latest local error that
happened while conversing with the remote SMTP server.
SMTPCODE
This will contain the 3 digit SMTP code returned by the remote SMTP
server.
SMTPHOST
This will contain the IP of the remote SMTP server
SMTPSTATUS
This will be either 'D' or 'Z' indicating permanent or temporary failure
response from the remote SMTP server.
qmail-remote uses many environment variables. These environment variables can be recipient specific by using envrules. See spawn-filter(8) for more details.
qmail-remote by default looks at /etc/indimail/control for all control files. This path can be changed by defining the CONTROLDIR environment variable.
outgoingip
file containing local IP addresses to be bound on socket and used on
outgoing connections. Default: system-defined. The value 0.0.0.0 is
equivalent to the system default. You can have multiple IP addresses one
per line, one per line for each IP. qmail-remote will use the
modulus operator with the current time to pick a single IP address.
outgoingip.host
file having a local IP address to be bound on socket and used on
outgoing connections. host is the domain or host to which the mail is
being delivered. * outgoingip.host* takes precedence over outgoingip.
You can also set the IP address for outgoing connection by setting the
environment variable OUTGOINGIP. OUTGOINGIP overrides the
control files outgoingip and outgoingip.host. You can have multiple
IP addresses, one per line for each IP. qmail-remote will use the
modulus operator with the current time to pick a single IP address.
domainbindings
file having local IP addresses to be bound based on envelope sender
domain or envelope sender address. Each binding has the form
domain:local-ip, or sender_addr:local-ip , without any extra
spaces. If domain matches * host*, or sender_addr matches * sender*,
qmail-remote will bind the local side of the socket for the outgoing
connection to local-ip. local-ip may be empty; this tells
qmail-remote to let the OS choose the local address for outgoing
connections as usual. domainbindings may include wildcards:
user1@example.com:6.5.4.3
example.com:5.6.7.8
.example.com:5.6.7.9
heaven.af.mil:1.2.3.4
:1.2.3.5
Here the connection for any message with an envelope sender address ending with .example.com (but not example.com itself) is bound to local address ** 5.6.7.9**, while envelope senders in example.com (but not user1@example.com itself) are bound to 5.6.7.8, and senders in heaven.af.mil are bound to ** 1.2.3.4**. Connection for message with an envelope sender address of user1@example.com gets bound to 6.5.4.3. All other outgoing connections (including messages with the null return-path) use the OS-chosen default local address. If you have the following line,
:1.2.3.5
then all connections with address not matching any line in domainbindings, will get bound to 1.2.3.5. The ** qmail** system does not protect you if you specify an invalid local address to bind to. domainbindings takes precedence over outgoingip. The name for domainbindings control file can be configured by setting DOMAINBINDINGS environment variable.
bindroutes
Artificial interface binding routes. Each route has the form
remote-address:local-address, without any extra spaces. If the
address of the host to which we are delivering matches the remote
address, then bind the socket to the interface matching the local
address, making it appear as if the connection had originated from the
named local address instead of the default local address. bindroutes
may contain suffix wildcards. bindroutes takes precedence over
domainbindings.
# Send this on the internal net
10.:10.0.0.1
# Rest goes on external "mail" address (yes, its bogus!)
:301.32.1.1
# Hey, we could 'cheat' on stopping qmail-remote sending to this host
555.123.123.123:this-isnt-an-ip-address
helohost
Current host name, for use solely in saying hello to the remote SMTP
server. Default: me, if that is supplied; otherwise qmail-remote
refuses to run. If the envelope sender address matches a domain in the
domainbindings control file, the envelope sender domain will be used
instead of this value.
helohostbyip
Map helohost for specific outgoing IPs.s, for use solely in saying hello
to the remote SMTP server. Default: me, if that is supplied; otherwise
qmail-remote refuses to run. If the envelope sender address matches
a domain in the domainbindings control file, the envelope sender
domain will be used instead of this value.
smtproutes
Artificial SMTP routes. Each route has the form domain:relay,
without any extra spaces. If domain matches host, qmail-remote
will connect to relay, as if host had relay as its only MX. (It
will also avoid doing any CNAME lookups on recip.) relay may include
a colon and a port number to use instead of the normal SMTP port, 25:
inside.af.mil:firewall.af.mil:26
relay may be empty; this tells qmail-remote to look up MX records as usual. port value of 465 (deprecated smtps port) causes TLS session to be started. 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 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. Additionally, smtproutes allows to forward bounces (with a 'Nullsender' MAIL FROM: <>) literally expressed as '!@' to a particular bounce host:
!@:bouncehost.af.mil:27
You can override the smtproutes filename by setting environment variable SMTPROUTESFILE.
The smtproutes control file is bypassed if the SMTPROUTE environment variable is set by qmail-rspawn. The SMTPROUTE environment variable has the same format as the entries in smtproutes control files. It is used in a clustered environment where a single domain can exist across multiple hosts. In such a case the SMTPROUTE variable points to the host where the user's mailbox lies. You can also use X-SMTPROUTES environment variable. SMTPROUTE env variable takes precendence over X-SMTPROUTES variable. Unlike SMTPROUTE, X-SMTPROUTES variable is not unset by qmail-rspawn for each delivery.
route may also have the form
domain:relay:port:penalty:max_tolerance<sp>username<sp>password
or
domain:relay:port<sp>username<sp>password
without any extra spaces. If the environment variable AUTH_SMTP is set, qmail-remote will use username and password (or secret for SCRAM authentication methods) to relay out mails through server relay using authenticated SMTP. <sp> is a single space character. AUTH_SMTP can also have the values SCRAM-SHA-1, SCRAM-SHA-256, SCRAM-SHA256, SCRAM-SHA-1-PLUS, SCRAM-SHA-256-PLUS, DIGEST-MD5, CRAM-RIPEMD, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-MD5, LOGIN or PLAIN to use the desired authentication method. You can disable specific AUTH methods by defining any one more more of the following environment variables. When using SCRAM authentication, the secret can be a clear text password or a salted password. The salted password should be a hex-encoded string (40 characters for SCRAM-SHA-1 and 64 characters for SCRAM-SHA-256) with the user’s PBKDF2-prepared password. The salted password value can be derived by using the --mkpasswd parameter for the gsasl(1) utility. indimail has vpasswd(1) / vmoduser(1), which use gsasl_scram_secrets_from_password(3) API to set passwords for AUTH PLAIN, LOGIN, CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD, DIGEST-MD5, SCRAM-SHA-1, SCRAM-SHA-256 methods. The hex-encoded salted password can be used to avoid storing a clear-text credential in the client, however note that an attacker who steal it may impersonate both a SCRAM client and SCRAM server. If the property is not available, qmail-remote will ask for the clear text password instead. You need to set the environment variable SALTED_PASSWORD for qmail-remote to use the secret as a salted password.
DISABLE_AUTH_LOGIN
DISABLE_AUTH_PLAIN
DISABLE_CRAM_MD5
DISABLE_CRAM_SHA1
DISABLE_CRAM_SHA224
DISABLE_CRAM_SHA256
DISABLE_CRAM_SHA384
DISABLE_CRAM_SHA512
DISABLE_CRAM_RIPEMD
DISABLE_DIGEST_MD5
DISABLE_SCRAM_SHA1
DISABLE_SCRAM_SHA256
DISABLE_SCRAM_SHA1_PLUS
DISABLE_SCRAM_SHA256_PLUS
If you set the environment variable SECURE_AUTH, AUTH LOGIN and AUTH PLAIN gets disabled, unless qmail-remote has opened a TLS session wth the remote host. See the control file clientcert.pem.
If all connections to the relay server fail for a max_tolerance seconds, further connections to the same server are avoided for a period of at least penalty seconds. The default maximum period of failures that will be tolerated - max_tolerance is 120 seconds and the minimum penalty - penalty is 1 hour. By setting the penalty to 0, connections to the server will be attempted inspite of failures. The default values of 1 hour for minimum penalty, can be changed by setting the environment variable MIN_PENALTY. The default value of 120 seconds for max_tolerance can be changed by setting the environment variable MAX_TOLERANCE.
moresmtproutes.cdb
This file gives smtproutes functionality on a per-user basis. You need
to create moresmtproutes.cdb file in the following format
<email_address><sp><ip_address>
Then run the following command in /usr/libexec/indimail directory
cdbmake-12 moresmtproutes.cdb < moresmtproutes.tmp < moresmtproutes.cdb
A route obtained from moresmtproutes.cdb overrides control file smtproutes or environment variable SMTPROUTE. One can also redirect all bounces to a host by specifying
!@<sp><ip_address>
You can override the moresmtproutes.cdb filename by setting environment variable MORESMTPROUTESCDB.
qmtproutes
Additional QMTP routes which have precedence over smtproutes. QMTP
routes should obey the form domain:relay:port, without any extra
spaces. qmtproutes follows the same syntax as smtproutes. By
default, qmail-remote connects to QMTP service port 209. However you
can chose a dedicated high-port for QMTP communication as defined in
qmtproutes. If the recipient domain is listed neither in qmtproutes
nor in smtproutes, qmail-remote will choose the protocol according
to MX priority. The qmtproutes control file is bypassed if the
QMTPROUTE environment variable is set by qmail-rspawn. The
QMTPROUTE environment variable has the same format as the entries in
qmtproutes control files. It is used in a clustered environment where a
single domain can exist across multiple hosts. In such a case the
QMTPROUTE variable points to the host where the user's mailbox lies.
You can override the qmtproutes filename by setting environment variable QMTPROUTESFILE.
timeoutconnect
Number of seconds qmail-remote will wait for the remote SMTP server
to accept a connection. Default: 60. The kernel normally imposes a
75-second upper limit.
timeoutremote
Number of seconds qmail-remote will wait for each response from the
remote SMTP server. Default: 1200.
signkey
Key for Bounce Address Tag Validation (BATV) signing. The filename can
be overriden by the environment variable SIGNKEY.
nosignhosts
Exclusions of remote hosts for Bounce Address Tag Validation (BATV) that
do not work with signed addresses.
Attention: If a host has more that one hostname, please list them all in nosignhosts.
nosignmydoms
Exclusions of domains you host for Bounce Address Tag Validation (BATV).
tlsclientmethod
The TLS protocol list. Accepted values are SSLv23, SSLv3, TLSv1,
TLSv1_1, TLSv1_2, TLSv1_3. The default is TLSv1_2 for OpenSSL Version <
1.0.1. Without this control file OpenSSL Version >= 1.0.1 uses
TLS_client_method(3ossl) where the actual protocol version used will be
negotiated to the highest version mutually supported by the client and
the server. The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2
and TLSv1.3. The default location of /etc/indimail/control can be
overriden by environment variable CONTROLDIR.
tlsclientciphers
A set of OpenSSL client cipher strings. Multiple ciphers contained in a
string should be separated by a colon. The default location of
/etc/indimail/control can be overriden by environment variable
CONTROLDIR
notlhosts
domains for which qmail-remote will not initiate TLS sesson. This
file in /etc/indimail/control or directory defined by the CONTROLDIR
envirnoment variable, shouldn't be confused with notlshosts directory
in the directory defined by the CERTDIR environment variable.
For TLS sessions, the default location of /etc/indimail/control can be overriden by environment variable CERTDIR. This affects the location of below files/directories clientcert.pem, servercert.pem, tlshosts/<FQDN>.pem, tlshosts/exhaustivelist, notlshosts/<FQDN>, notlshosts/host.
clientcert.pem
SSL certificate that is used to authenticate with the remote server
during a TLS session. If clientcert.pem does not exist, qmail-remote
will not negotiate TLS. The default location of /etc/indimail/control
can be overriden by environment variable CERTDIR. clientcert.pem can
be overriden by environment variable CLIENTCERT.
tlshosts/<FQDN>.pem
qmail-remote requires TLS authentication from servers for which this
file exists (<FQDN> is the fully-qualified domain name of the
remote SMTP server). One of the dNSName or the CommonName attributes
have to match. The file contains the trusted CA certificates. The
default location of /etc/indimail/control can be overriden by
environment variable CERTDIR.
tlshosts/exhaustivelist
if this file exists no TLS will be tried on hosts other than those for
which a file tlshosts/<FQDN>.pem exists. The default location of
/etc/indimail/control can be overriden by environment variable
CERTDIR.
WARNING: this option may cause mail to be delayed, bounced, doublebounced, or lost.
notlshosts/<FQDN>
qmail-remote will not try TLS on servers for which this file exists
(<FQDN> is the fully-qualified domain name of the remote SMTP
server). (tlshosts/<FQDN>.pem takes precedence over this file
however). The default location of /etc/indimail/control can be overriden
by environment variable CERTDIR.
notlshosts/host
qmail-remote will not try TLS on servers for which this file exists
(host is the domain name of the recipient). (tlshosts/<FQDN>.pem
takes precedence over this file however). The default location of
/etc/indimail/control can be overriden by environment variable
CERTDIR.
tlsadomains
file having the list of MX hosts for which TLSA records needs to be
verified. If this control file is present, TLSA verification will be
skipped for all domains not in this file. If a file with the name
tlsadomains.cdb exists, qmail-remote will use cdb(3) lookup
in addition to the normal in-memory search in a table of tlsa
verification enforced domains.
addresses(5), envelopes(5), qmtp(5), qmail-control(5), qmail-send(8), spawn-filter(8), qmail-rspawn(8), qmail-smtpd(8), qmail-qmtpd(8), qmail-daned(8), tlsacheck(3), qmail-tcpok(8), qmail-tcpto(8), idn2_lookup_u8(3) ctrlenv(8), gsasl_scram_secrets_from_password(3) gsasl(1) vpasswd(1), vmoduser(1),