SYNOPSIS

       qmail-remote host sender recip [ recip ...  ]


DESCRIPTION

       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 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 corresponing TLSA/DANE
       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.



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.  qmail-remote respects
       SMTPUTF8 and EAI addresses and converts the UNIX newline convention
       into the SMTP newline convention by inserting CR before each LF.



RESULTS

       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:


       qmail-remote may use SMTP Authenticaton to connect to remote hosts.
       The following reports are provided:

       K    no supported AUTH s/qmail: method found, continuing without
            authentication.

       Z    Connected to host but authentication was rejected (AUTH s/qmail:
            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 s/qmail:
            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 (AUTH s/qmail:
            CRAM-MD5).

       Z    Connected to host but unable to base64decode challenge.

       Z    Connected to host but unable to base64encode username+digest.

       Z    Connected to host but authentication was rejected
            (username+digest).

       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:

       Z    CNAME lookup failed temporarily for: host.

       If a SMTP connection is bound to a none-existing IP address
       qmail-remote will complain with the message:

       Z    System resources temporarily unavailable.

       Z    System can't bind to local ip address: ip.

       In case a QMTP connection can not be established qmail-remote will
       issue the error message:


       K    TLS (DANE) transmitted message accepted

       For each SMTP MTA to reach via TLS, qmail-remote performs an automatic
       TLSA/DANE lookup comparing the received X.509 fingerprints with the
       issued cert during the TLS handshake.

       Z    Can't load X.509 certificate: host.

       Z    Can't load X.509 private key: host.

       Z    I wasn't able to create TLS context for host.

       Z    I wasn't able to process the TLS ciphers: ciphers.

       Z    I wasn't able to setup CAFILE: cafile or CADIR: cadir for TLS.

       Z    I wasn't able to establish a TLS connection with: host.

       Z    I wasn't able to gracefully close the TLS connection with: host.

       Z    Unable to obtain X.500 certificate from: host.

       Z    Unable to verify X.500 certificate from: host.

       Z    Unable to validate X.500 certificate Subject for: host.

       Z    Received X.500 certificate from host does not match provided
            fingerprint: SHA-1 fingerprint.

       Z    I wasn't able to establish a TLS connection with: host.

       Z    I wasn't able to gracefully close the TLS connection with: host.

       Z    I wasn't able to negotiate a TLS connection with: host.

       qmail-remote always exits zero.



CONTROL FILES

       authsenders
            Authenticated sender.  For each sender included in authsenders:
            sender:relay;[s]port|user|password qmail-remote will try SMTP
            Authentication of type CRAM-MD5, LOGIN, or PLAIN with the provided
            user name user and password password (the authentication
            information) and eventually relay the mail through relay on port
            port.  If port is given als or prepended with s like s587
            ´implicit TLS´ is used omitting StartTLS upon connection.  The use
            of relay and port follows the same rules as for smtproutes Note:
            In case sender is empty, qmail-remote will try to deliver each
            outgoing mail SMTP authenticated. If the authentication
            information is missing, the mail is delivered none-authenticated.


       domainips
            IP addresses to be used for outgoing connections.  Each line has
            the form domain:localip(%ifname)|helohost, without any extra
            spaces.  If domain matches the domain part in sender, qmail-remote
            will bind to localip when connecting to host.  LLU IPv6 addresses
            need to be appended with the binding ifname following localip with
            a '%'.  If it matches, it will set the provided HELO string as
            greeting; otherwise, it will use the default.  domain can be the
            wildcard * in which case qmail-remote binds to the provided
            address for any sender domain name.

       helohost
            Current host name, for use solely in saying ehlo/hello to the
            remote SMTP server.  Default: me, if that is supplied; otherwise
            qmail-remote refuses to run.

       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.  In case the QMTP port is chosen to be
            6209 the TLS secured QMTPS protocol will be used, irrespectively
            of the settings in tlsdestinations.

       smtproutes
            Artificial SMTP routes.  Each route has the well-known form
            domain:relay or the enhanced syntax
            domain:relay;[s]port|user|password|localip 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.) host may include a semi-colon
            and a port number to use instead of the normal SMTP port, 25.  If
            port is given as or prepended with s ´implicit TLS´ is assumed.
            In case, a userid and password is present, qmail-remote will try a
            SMTP authenticated session:

               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
               !@: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.

       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.

       tlsdestinations
            If present, this file advices qmail-remote to use TLS (optinally
            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:
            destination:cafile|ciphers|verifydepth;[s]port|domain or
            destination:=fingerprint|ciphers|verifydepth;[s]port|domain.
            Unless explicitely configured, qmail-remote accepts any or no
            certificate provided by the server (opportunistic encryption)
            using the following (single character) rules:

               (0) ?:  # fallthru to no TLS
               (1) -:  # allow anonymous connections
               (2) *:  # validate X.509 certs
               (3) /:  # disable DANE 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 '*'
               (7) =*: # cert + validate SAN/DN against FQDN
               (8) /*: # don't do DANE 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|!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:

            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 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 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.

            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.

            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, DANE/TLSA lookus pand evaluation 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.

SEE ALSO

       addresses(5), envelopes(5), qmail-control(5), qmail-send(8), qmail-
       smtpd(8), qmail-smtpam(8), qmail-tcpto(8)

Man(1) output converted with man2html