.TH s/qmail: qmail-remote 8
.SH NAME
qmail-remote \- send mail via SMTP(S) or QMTP(S)
.SH SYNOPSIS
.B qmail-remote
.I host
.I sender
.I recip
[
.I recip ...
]
.SH DESCRIPTION
.B 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 is
.BR qmail-remote 's
first argument,
.IR host .
.B qmail-remote
sends the message to
.IR host ,
or to a mail exchanger for
.I 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, 
.B qmail-remote 
will lookup automatically the corresponding TLSA
record in the DNS and uses this for X.509 certificate
validation.
.I host
can be either a fully-qualified domain name:

.EX
     silverton.berkeley.edu
.EE

or an IPv4 or IPv6  address enclosed in brackets:

.EX
     [128.32.183.163]
     [2001::163]
.EE
 
In case the primary mail exchanger for that Domain
will issue a 5xy reply message during the connection,
.B qmail-remote
will contact all responsible mail exchangers in turn
in order to deliver the message anyway.

The envelope recipient addresses are listed as
.I recip
arguments to
.BR qmail-remote .
The envelope sender address is listed as
.I sender\fP.

In case the remote host issues the EHLO SIZE extension,
.I qmail-remote
will handover the size of the message (in byte) 
prior of transmission and respects the remote host's reply code.

Note that
.B qmail-remote
does not take options
and does not follow the
.B getopt
standard.
.SH "TRANSPARENCY"
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.
.B qmail-remote
respects SMTPUTF8 and EAI addresses 
and converts the UNIX newline convention into the 
SMTP newline convention by inserting CR before each LF.

.SH "RESULTS"
.B qmail-remote
prints some number of 
.I recipient reports\fP,
followed by a
.I message report\fR.
Each report is terminated by a 0 byte.
Each report begins with a single letter:
.TP 5
r
Recipient report: acceptance.
.TP 5
h
Recipient report: permanent rejection.
.TP 5
s
Recipient report: temporary rejection.
.TP 5
K
Message report: success.
.I host
has taken responsibility for delivering the message to each
acceptable recipient.
.TP 5
Z
Message report: greylisted or temporary failure.
.TP 5
D
Message report: permanent failure.
.PP
After this letter comes a human-readable description of
what happened.

.B qmail-remote
may use SMTP Authenticaton to connect to remote hosts.
The following reports are provided:
.TP 5
K
no supported AUTH s/qmail: method found, continuing without authentication.
.TP 5
Z
Connected to 
.I host
but authentication was rejected (AUTH s/qmail: PLAIN).
.TP 5
Z
Connected to 
.I host 
but unable to base64encode (plain).
.TP 5
Z
Connected to 
.I host
but authentication was rejected (plain). 
.TP 5
Z
Connected to
.I host
but authentication was rejected (AUTH s/qmail: LOGIN).
.TP 5
Z
Connected to 
.I host
but unable to base64encode user.
.TP 5
Z
Connected to 
.I host 
but authentication was rejected (username).
.TP 5
Z
Connected to 
.I host 
but unable to base64encode pass.
.TP 5
Z
Connected to
.I host
but authentication was rejected (AUTH s/qmail: CRAM-MD5).
.TP 5
Z
Connected to
.I host
but unable to base64decode challenge.
.TP 5
Z
Connected to
.I host
but unable to base64encode username+digest.
.TP 5
Z
Connected to
.I host
but authentication was rejected (username+digest).
.PP
The recipient reports will always be printed in the same order as
.BR qmail-remote 's
.I recip
arguments.
Note that in failure cases there may be fewer
recipient reports
than
.I recip
arguments.
.PP
In case a CNAME can not be resovled 
.B qmail-remote
issues the following message:
.TP 5
Z
CNAME lookup failed temporarily for:
.IR host . 
.PP
If a SMTP connection is bound to a none-existing IP address
.B qmail-remote
will complain with the message:
.TP 5
Z
System resources temporarily unavailable.
.TP 5
Z
System can't bind to local ip address:
.IR ip .
.PP
In case a QMTP connection can not be established 
.B qmail-remote
will issue the error message:
.TP 5
Z 
recipient
.I host
did not talk proper QMTP.
.PP
On demand
.B qmail-remote
supports TLS/STARTTLS and will log the following notifications:
.TP 5
K
TLS transmitted message accepted
.TP 5
K
TLS (verfied CA) transmitted message accepted
.TP 5
K
TLS (verified CA+DN*) transmitted message accepted
.TP 5
K
TLS (verified CA+DN) transmitted message accepted
.TP 5
K
TLS (CERT pinning) transmitted message accepted
.TP 5
K
TLS (TLSA [EE|TA] validated) transmitted message accepted
.PP
.B qmail-remote 
needs to read some X.509 certificates and key files 
prior of setting up a TLS connection. Failures are indicated as:
.TP 5
Z
Can't load X.509 certificate:
.IR certfile .
.TP 5
Z
Can't load X.509 private key:
.IR keyfile .
.TP 5
Z
Keyfile does not match X.509 certificate:
.IR password .
.TP 5
Z
I wasn't able to process the TLS ciphers:
.IR ciphers .
.TP 5
Z
I wasn't able to setup CAFILE:
.I cafile
or CADIR:
.I cadir
for TLS.
.PP
Connection problems for TLS are not uncommon.
Here, 
.I host
is the domain or host to connect with and
.I remotehost
is the corresponding MX.
.B
qmail-remote
provides the following diagnostic messages:
.TP 5
Z
I wasn't able to create TLS context for:
.I host 
at
.IR remotehost .
.TP 5
Z
I wasn't able to establish a TLS connection with:
.I remotehost 
for 
.IR host .
.TP 5
Z
TLS connection/protocol error with host:
.I remotehost 
for 
.IR host .
.TP 5
Z
I wasn't able to negotiate a StartTLS connection with:
.I remotehost
for
.IR host .
.PP
For each MX to reach via TLS,
.B 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:
.TP 5
Z
Unable to obtain X.500 certificate from:
.I remotehost
for
.IR host .
.TP 5
Z
Unable to validate X.500 certificate Subject for:
.I host
at
.IR remotehost .
.TP 5
Z
TLSA X.509 cert required but missing from:
.I remotehost 
for
.IR host .
.TP 5
Z
Received X.500 certificate from:
.I remotehost 
for
.I host 
does not match provided fingerprint: 
.IR hashvalue .
.TP 5
Z
Received X.500 certificate from:
.I remotehost 
for
.I host 
posses an unknown digest method.
.PP
.SH "CONTROL FILES"
.TP 5
.I authsenders
Authenticated sender.
For each
.I sender 
included in 
.IR authsenders :
.I sender\fB:\fIrelay\fB;\fI[s]port\fB|\fIuser\fB|\fIpassword 
.B qmail-remote
will try SMTP Authentication 
of type CRAM-MD5, LOGIN, or PLAIN 
with the provided user name
.I user 
and password
.I password 
(the authentication information) 
and eventually relay the 
mail through
.I relay
on port
.IR port .
If 
.I port
is given als or prepended with
.I s
like
.I s587
\'implicit TLS\' is used omitting StartTLS upon connection.
The use of 
.I relay
and 
.I port 
follows the same rules as for
.IR smtproutes 
Note: In case
.I sender
is empty, 
.B qmail-remote
will try to deliver each outgoing mail 
SMTP authenticated. If the authentication
information is missing, the mail is 
delivered none-authenticated.
.I authsenders
can be constructed as follows:

.EX
   @example.com:relay.example.com|user|passwd
   info@example.com:relay.example.com;26|infouser|infopasswd
   :mailrelay.example.com|e=mc2|testpass
.EE
.TP 5
.I domaincerts
In case
.B qmail-remote
needs to present a client certificate to the server 
(for authentication purposes) the PEM encoded 
X.509 certificate can be provided per sending domain:
.IR domain\fB:\fIcertificate\fB|\fIkeyfile\fB|\fIpassword .
If 
.I domain
equals '*' this
.I certificate
is used as default.
The file 
.I certificate 
may include the private key, thus 
.I keyfile
can be omitted. Additionally, the private key can be protected with a
.IR password .

.TP 5
.I domainips
IP addresses to be used for outgoing connections.
Each line has the form
.IR domain\fB:\fIlocalip(%ifname)\fB|\fIhelohost ,
without any extra spaces.
If
.I domain
matches the domain part in
.IR sender ,
.B qmail-remote
will bind to
.IR localip
when connecting to
.IR host .
LLU IPv6 addresses need to be appended with the binding 
.IR ifname
following
.IR localip 
with a '%'.
If it matches, it will set the provided HELO string as greeting; 
otherwise, it will use the default.
.I domain 
can be the wildcard
.I *
in which case 
.B qmail-remote
binds to the provided address for any sender domain name.
.TP 5
.I helohost
Current host name,
for use solely in saying ehlo/hello to the remote SMTP server.
Default:
.IR me ,
if that is supplied;
otherwise
.B qmail-remote
refuses to run.
.TP 5
.I qmtproutes
Additional QMTP routes which have precedence over
.IR smtproutes .
QMTP routes should obey the form
.IR domain\fB:\fIrelay\fB;\fIport ,
without any extra spaces.
.I qmtproutes
follows the same syntax as
.IR smtproutes .
By default, 
.B qmail-remote
connects to QMTP service port 209. However
you can chose a dedicated high-port for QMTP communication
as defined in
.IR qmtproutes .
In case the QMTP port is chosen to be
.I 6209
the TLS secured QMTPS protocol will be used, 
irrespectively of the settings in 
.IR tlsdestinations .
.TP 5
.I smtproutes
Artificial SMTP routes.
Each route has the well-known form
.I domain\fB:\fIrelay 
or the enhanced syntax
.I domain\fB:\fIrelay;\fI[s]port\fB|\fIuser\fB|\fIpassword|localip
without any extra spaces.
If
.I domain
matches
.IR host ,
.B qmail-remote
will connect to
.IR relay ,
as if
.I host
had
.I relay
as its only MX.
(It will also avoid doing any CNAME lookups on
.IR recip .)
.I host
may include a semi-colon and a port number to use instead of the
normal SMTP port, 25. 
If 
.I port
is given as or prepended with
.I s
\'implicit TLS\' is assumed.
In case, a userid and password is
present,
.B qmail-remote
will try a SMTP authenticated session:

.EX
   inside.af.mil:firewall.af.mil;26
   :submission.myrelay.com;s587|myuserid|mypasswd
.EE

However,
.I authsenders
routes have precedence.

.I relay
may be empty;
this tells
.B qmail-remote
to look up MX records as usual.
.I smtproutes
may include wildcards:

.EX
   .af.mil:
   :heaven.af.mil
.EE

Here
any address ending with
.B .af.mil
(but not
.B af.mil
itself)
is routed by its MX records;
any other address is artificially routed to
.BR heaven.af.mil .

The outgoing IP address used by
.B qmail-remote
can be specified:

.EX
   :bouncehost.org||10.1.1.0
   :partnermx.net;42||2001::fefe
.EE

Note: 
.I localip
can be private IP address subject of NAT'ing.

Additionally,
.I smtproutes 
allows to forward bounces (with a 'Nullsender' MAIL FROM: <>)
literally expressed as '!@'
to a particular bounce host:

.EX
   !@:bouncehost.af.mil;27
.EE

The
.B qmail
system does not protect you if you create an artificial
mail loop between machines.
However,
you are always safe using
.I smtproutes
if you do not accept mail from the network.
.TP 5
.I timeoutconnect
Number of seconds
.B qmail-remote
will wait for the remote SMTP server to accept a connection.
Default: 60.
The kernel normally imposes a 75-second upper limit.
.TP 5
.I timeoutremote
Number of seconds
.B qmail-remote
will wait for each response from the remote SMTP server.
Default: 1200.
.TP 5
.I tlsdestinations
If present, this file advices
.B qmail-remote
to use TLS (optionally or mandatory) encryption for specific destination domains
as provided by the forward-path and to validate/verify 
the server certificate perhaps for a particular sender's domain:
.I destination:cafile|ciphers|verifydepth;[s]port|domain 
or
.IR destination:=fingerprint|ciphers|verifydepth;[s]port|domain .
Unless explicitely configured,
.B qmail-remote 
accepts any or no certificate provided by the server (opportunistic encryption)
using the following (single character) rules:

.EX
   (0) *:  # Enable TLS but fallback to NOTLS (default);
             server authentication is optional, given further settings
.EE

Special settings:

.EX
   (1) ?:  # fallthru to no TLS in case of TLS protocol errors (exceptional)
   (2) -:  # allow anonymous connections
   (3) /:  # disable TLSA lookup and verification
.EE

Double character rules instruct
.B qmail-remote
to require a STARTTLS or SMTPS connection (mandatory TLS):
 
.EX
   (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
.EE

Additionally, 
.B qmail-remote 
can be told to use per-domain connection settings: 

.EX
   (9) example.com:
  (10) securityfirst.com:/etc/ssl/cafile|!SSLv2:HIGH
  (11) remote.com:/etc/ssl/certdir/||3;465
  (12) mx.partner.com:/etc/ssl/partnerca||2|mydomain.net
  (13) =mx.myfriend.com:/etc/ssl/cacert||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: 
.EE

The ninth line requires from
.B qmail-remote 
to demand a STARTTLS connection for any destination
address targeting domain
.IR example.com .

The tenth line accepts STARTTLS connections
for
.I securityfirst.com
only, if the X.509 certificate can be verified against
the CA cert as provided via
.I /etc/ssl/cafile 
and with the acceptable ciphers 
.IR SSLv2:HIGH .

Line number eleven tells 
.B qmail-remote
to use a 
.I SMTPS
connection on port
.I 465
to any host at
.I remote.com
and accept this host only, if the peer's cert
can be validated against the CA certs available 
in
.I /etc/ssl/certdir/
and does not exceed a verification depth of
.IR 3 .

Line twelve shows an example, how 
.I tlsdestinations
can be bound exclusively to a sender domain. In the shown case,
only if
.I mx.mydomain.net
is used as sender domain, 
a connection for the destination address
.I mx.partner.com
is mandatory secured by TLS with a CA cert available as
.I /etc/ssl/partnerca 
with a verification depth of
.IR 2 .

Furthermore, the sample on line thirteen demonstrates the case where 
.B qmail-remote
sees a destination address concatinated with
.IR = .
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 
.IR cacert
CA certificate and does not exceed a verification depth of
.IR 1 .

In case a certain
.I destination
may use 'wildcard' domain names in the SAN/DN, 
.B qmail-remote
can cope with this (line fourteeen) 
prepending the destination with a '~':
.IR ~wildneighor.net .
This mechanism also supports partial matching
of SAN/DN and domain name.

In the same sense (line fiveteen), 
.B 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 
.I - 
as key encryption cipher and discards 
.I !RSA
for authentication if told so.

Certificate pinning for a particular 
.I %host
indicated by the leading character '%' is shown on line sixteen.
Instead of the CA file, now the
.I =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.  
.BR 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'.
.B qmail-remote
can be instructed to omit the STARTTLS command for the recipient address
.I nosslhost.example.com 
as indicated with a leading 
.I ! 
as shown on line seventeen. This behavior can be relaxed (line nineteen) using
.I ? 
followed by a colon, a host, or domain name. Now 
.B 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. 

.B qmail-remote
allows an \'implicit TLS\' connection on any port, if 
.I port
is prended with an 
.I 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, 
.I port
equals 
.IR 465 , 
SMTPS will be used instead of STARTTLS and if 
.I port 
equals 
.IR 6209 , 
QMTPS is the chosen transport protocol.
The settings here overrule previous instructions.

Finally, TLSA lookups can be disabled, prepending a
domain name with
.I /
for the target domain as shown on line twenty.

Note that 'destination' is subject of the
forwarding rules as provided by
.IR authsenders ,
.IR qmtproutes  ,
and
.IR smtproutes .
.SU "ADDENDUM"
.B qmail-remote 
needs to read the message from a file in order
to announce the 
.I 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
.I QMTP(S)
will fail.
.SH "RETURN CODES"
.B qmail-remote
always exits
.I 0
for SMTP(S) delivery. 
In case of QMTP(S)
.I 1
is returned in case a buffer feed fails and
.I 0
otherwise.
.SH "SEE ALSO"
addresses(5),
envelopes(5),
qmail-control(5),
qmail-send(8),
qmail-smtpd(8),
qmail-smtpam(8),
qmail-dksign(8),
qmail-dkim(8),
qmail-tcpto(8)