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

       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 mes-
       sage 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  generat-
       ing illegal messages.


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:

       r    Recipient report: acceptance.

       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	(user-
	    name+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:

       Z    recipient host did not talk	proper QMTP.


       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 fin-
	    gerprint: SHA-1 fingerprint.

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

       Z    I wasn't able to grafefully	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;port|user|password qmail-remote will try SMTP Authen-
	    tication 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.  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 informa-
	    tion is missing, the mail is delivered none-authenticated.	 auth-
	    senders can	be constructed as follows:

	       @example.com:relay.example.com|user|passwd
	       info@example.com:relay.example.com;26|infouser|infopasswd
	       :mailrelay.example.com|e=mc2|testpass

       domaincerts
	    In	case qmail-remote needs	to present a client certificate	to the
	    server (for	authentication purposes) the PEM  encoded  X.509  cer-
	    tificate  can  be  provided	 per  sending  domain: domain:certifi-
	    cate|keyfile|password.  If domain equals '*' this  certificate  is
	    used  as  default.	 The  file certificate may include the private
	    key, thus keyfile can be omitted. Additionally,  the  private  key
	    can	be protected with a password.


       domainips
	    In  case qmail-remote needs to present a client certificate to the
	    server (for authentication purposes) the PEM  encoded  X.509  cer-
	    tificate  can  be  provided  per  sending  domain: domain:certifi-
	    cate|keyfile|password  If domain equals '*' this  certificate  is
	    used  as  default.   The  file certificate may include the private
	    key, thus keyfile can be omitted. Additionally,  the  private  key
	    can be protected with a password.

       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.  How-
	    ever 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	form  domain:relay  or
	    domain:relay|user|password	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. In case, a userid and pass-
	    word is present, qmail-remote will try a SMTP  authenticated  ses-
	    sion:

	       inside.af.mil:firewall.af.mil;26
	       :submission.myrelay.com;587|myuserid|mypasswd

	    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
	    routed by its MX records; any other	address	is artificially	routed
	    to heaven.af.mil.

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

	       !@: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  pro-
	    vided  by  the forward-path and to validate/verify the server cer-
	    tificate  perhaps  for  a  particular  sender's  domain:  destina-
	    tion:cafile|ciphers|verifydepth;port|domain  or  destination:=fin-
	    gerprint|ciphers|verifydepth;port|domain.  Unless explicitely con-
	    figured, qmail-remote  accepts  any or no certificate provided by
	    the server (opportunistic encryption) using the following  (single
	    character) rules:

	       (1) -:  # allow anonymous connections
	       (2) *:  # validate X.509 certs

	    Double character rules instruct qmail-remote to require a STARTTLS
	    or SMTPS connection	(mandatory):

	       (3) -*: # allow anonymous connections
	       (4) +*: # require X.509 certs
	       (5) ~*: # cert +	validate SAN/DN, however accept	'*'
	       (6) =*: # cert +	validate SAN/DN	against	FQDN

	    Additionally, qmail-remote can be  instructed  to  use  per-domain
	    connection settings:

	       (7) example.com:
	       (8) securityfirst.com:/etc/ssl/cafile|!SSLv2:HIGH
	       (9) remote.com:/etc/ssl/certdir/||3;465
	      (10) mx.partner.com:/etc/ssl/partnerca||2|mydomain.net
	      (11) =mx.myfriend.com:/etc/ssl/cacert||4
	      (12) ~wildneighbor.net:
	      (13) -adhonlydomain.com:||aNULL:!kRSA
	      (14) %peer.partner.com:=E44194C56EF.....
	      (15) !nosslhost.example.com:
	      (16) hiddenpartner.org:;35

	    The	 seventh  line requires	from qmail-remote to demand a STARTTLS
	    connection for any	destination  address  targeting	 domain	 exam-
	    ple.com.

	    The	 eighths  line	accepts	 STARTTLS  connections	for  security-
	    first.com only, if the X.509 certificate can be  verified  against
	    the	 CA  cert as provided via /etc/ssl/cafile and with the accept-
	    able ciphers SSLv2:HIGH.

	    Line number	nine tells qmail-remote	to use a SMTPS	connection  on
	    port  465  to any host at remote.com and accept this host only, if
	    the	peer's cert can	be validated against a (hashed)	CA cert	avail-
	    able in /etc/ssl/certdir/ and does not exceed a verification depth
	    of 3.

	    Line 10 shows an example, how tlsdestinations can be bound	exclu-
	    sively  to	a  sender  domain. In the shown	case, only if mx.mydo-
	    main.net is	used as	sender domain, a connection for	 the  destina-
	    tion  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  in  line	11 demonstrates	the case where
	    qmail-remote sees a	destination address  concatinated  with	 a  =.
	    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 exeed 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  12)  prepending
            the destination with a '~': ~wildneighor.net.

            In  the  same sense (line 13), qmail-remote may accept TLS connec-
            tions based on Anonymous DH (ADH) - where the server does not pro-
            vide a cert for authentication - once the domain name is prepended
            with a - as key encryption cipher and discards !RSA for  authenti-
            cation if told so.

            Certificate  pinning for a particular %host indicated by the lead-
            ing character '%' is shown on line 14.  Instead of  the  ca  file,
            now the =fingerprint of the peer host certificate needs to be pro-
            vided.  The X.509 fingerprint should prepended with an equal  sign
            ('=') and to be stripped from additional colons (':'). The finger-
            print string is evaluated case-insensitive.   qmail-remote's  cer-
            tificate   pinning  supports  SHA1,  SHA224,  SHA256,  and  SHA512
            digests, determined by the length of the fingerprint given.

	    Finally,  qmail-remote can be instructed to	omit the STARTTLS com-
	    mand for the recipient address nosslhost.example.com as  indicated
	    with a leading !  as shown on line 15.

	    In	case,  no  perticular  ciphers	or  CA	certs  are required, a
	    colon/semi-colon ':;' can be used as shortcut (line	 16).	Gener-
	    ally,  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.

	    Note that 'destination' is subject of the forwarding rules as pro-
	    vided 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)



				       8		 s/qmail:(qmal-remote)

Man(1) output converted with man2html
and me!