diff options
Diffstat (limited to 'man/qmail-remote.8')
| -rw-r--r-- | man/qmail-remote.8 | 806 |
1 files changed, 806 insertions, 0 deletions
diff --git a/man/qmail-remote.8 b/man/qmail-remote.8 new file mode 100644 index 0000000..363c972 --- /dev/null +++ b/man/qmail-remote.8 @@ -0,0 +1,806 @@ +.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 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) |