From de33be8ad62f2c3c2f7c4030b1ebb301a73e0872 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 7 Feb 2026 14:08:53 +0000 Subject: final batch of code, this should be complete! --- doc/qmail-remote.html | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 doc/qmail-remote.html (limited to 'doc/qmail-remote.html') diff --git a/doc/qmail-remote.html b/doc/qmail-remote.html new file mode 100644 index 0000000..1cfc91a --- /dev/null +++ b/doc/qmail-remote.html @@ -0,0 +1,172 @@ + + + + + + smtpd-starttls-proxy: the qmail-remote program + + + + + + +

+smtpd-starttls-proxy
+Software
+skarnet.org +

+ +

The qmail-remote program

+ +

+qmail-remote is an SMTP client, meant to be used as a drop-in +replacement to the +qmail-remote +implementation in the original +qmail MTA, its +netqmail distribution, or its modern +notqmail successor. +

+ +

+ It is not meant to be invoked directly by the user; it only makes sense +in the context of a qmail, netqmail or notqmail installation. +

+ +

Interface

+ +

+ qmail-remote follows the exact same interface as the stock +qmail-remote. +The binary can literally be dropped +in /var/qmail/bin, replacing the previous binary by the same name. +With certain qmail patches, it can also be used without overwriting anything, +by running qmail with the QMAILREMOTE environment variable set to the path +where this version of qmail-remote is installed. +

+ +

Differences with other implementations of qmail-remote

+ +

+ The main benefits of this qmail-remote implementations are the following: +

+ + + +

Control files

+ +

+ qmail-remote uses the following control files in /var/qmail/control: +

+ +

+
me, helohost, smtproutes, timeoutconnect, timeoutremote
+
These files are used in the exact same way as in +stock qmail-remote.
+ +
timeoutdns +
Number of seconds will wait for any given DNS resolution to succeed. Default: +0, which means infinite (never time out on a resolution).
+ +
ipme
+
A list of the network IP addresses of the local machine, one per line. These can be +IPv4 or IPv6, in textual format. These addresses are used to eliminate SMTP loops: +qmail-remote will never connect to these addresses and never deliver mail +to them. Note that the stock qmail-remote automatically detects the local +IP addresses; this has several problems, one being OS portability, and another +being that this autodetection is just impossible in IPv6 — so we +delegate the listing of local IPs to the user here. Also, the best way to avoid +SMTP loops remains making sure that your locals and virtualdomains +files are correct and up-to-date, so that qmail-remote will never be +invoked on a recipient that should be handled locally.
+ +
trustanchors
+
Contains the path to the certificates for known trust anchors for X.509 +certificate validation. If the path ends with a slash, like /etc/ssl/certs/, +then it is interpreted as a directory containing hashes to the certificates. If +it does not, like /etc/ssl/cert.pem, then it is interpreted as a big +PEM file containing all the trust anchors. If the file is nonexistent or empty, +or only contains a newline, then STARTTLS is not attempted.
+ +
clientcert
+
If this file exists and is nonempty, it must contain the path to a client +certificate. This certificate will be sent to the server during a TLS negotiation. +This is useful in certain setups requiring client authentication.
+ +
clientkey
+
This file must be used in conjunction with clientcert. It contains +the path to the private key used to sign the client certificate. Note that access +to the private key file should be as restricted as possible, but the qmailr +user (or whatever user qmail-smtpc runs as) must be able to read it.
+ +
tlsstrictness
+
This file contains an integer representing the strictness level expected of +TLS connections. The default is 0, and means that an SMTP exchange +will attempt to use STARTTLS if the trustanchors information is provided +and the server advertises the capability, but will +proceed in cleartext if the server does not advertise STARTTLS support, or if the +STARTTLS command fails. 1 means that qmail-remote will +attempt to find a server that supports STARTTLS in order to transmit its e-mail, +but will fallback to cleartext if it cannot find any. 2 means that +qmail-remote will flat out refuse to send e-mail to servers that do not +support STARTTLS or fail to set it up.
+
+ +

Implementation notes

+ + + + + -- cgit v1.3.1