add sqmail-4.2.29asqmail-4.2

1 files changed, 795 insertions, 0 deletions

diff --git a/man/qmail-remote.8 b/man/qmail-remote.8
new file mode 100644
index 0000000..8f94e8a
--- /dev/null
+++ b/man/qmail-remote.8
@@ -0,0 +1,795 @@
+.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 .
+.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)