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/index.html | 6 ++ doc/qmail-remote-io.html | 53 +++++++++++++++ doc/qmail-remote.html | 172 +++++++++++++++++++++++++++++++++++++++++++++++ doc/qmail-smtpc.html | 79 ---------------------- 4 files changed, 231 insertions(+), 79 deletions(-) create mode 100644 doc/qmail-remote-io.html create mode 100644 doc/qmail-remote.html delete mode 100644 doc/qmail-smtpc.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 8dfae68..3b350ea 100644 --- a/doc/index.html +++ b/doc/index.html @@ -93,6 +93,12 @@ the previous versions of smtpd-starttls-proxy and the current one.

Internal commands

+ +

The qmail-remote-io internal program

Related resources

smtpd-starttls-proxy: the qmail-remote-io internal program

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

The `qmail-remote-io` internal program

+qmail-remote-io is a part of the SMTP client implemented by +qmail-remote. It manages the entirety +of the SMTP transaction except EHLO and STARTTLS. +

+qmail-remote-io is not meant to be invoked directly. It is +meant to be executed into by qmail-remote. +

Internal details

qmail-remote does the job of finding a +suitable SMTP server and connecting to it, saying EHLO and, if the user +has defined a control/trustanchors file and the server supports it, +STARTTLS.
If the connection is not encrypted, +qmail-remote execs qmail-remote-io +immediately, and qmail-remote-io proceeds with all the rest of the +SMTP transaction.
If the connection is encrypted, +qmail-remote execs +s6-tlsc +qmail-remote-io, instead, so any further exchange with the SMTP server +is protected by TLS.
qmail-remote-io does the same job in either case: it speaks +plaintext SMTP.

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: +

If the underlying OS and skalibs +support IPv6, then this qmail-remote does as well, and uses IPv4 and IPv6 +addresses indiscriminately when connecting to an MX.
It speaks ESMTP and will use STARTTLS if the server supports it.
All its DNS resolutions are done in parallel, which eliminates some +pathological cases where the original qmail-remote can hang around doing +nothing for a long time.

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

At installation time, qmail-remote creates the +/var/qmail/run directory, to host run-time information, and +the /var/qmail/run/qmail-remote directory, writable by user +qmailr. You can customize the qmail location and users at +configure time.
At run-time, qmail-remote stores some information under +/var/qmail/run/qmail-remote: +
- smtproutes.cdb is a cdb file containing the artificial +SMTP routes, automatically compiled from /var/qmail/control/smtproutes +whenever it changes. qmail-remote reads its route information +from the cdb file. This is a more efficient mechanism than the original +"constmap" one.
- smtproutes.lock, a lock file used when reading and +writing smtproutes.cdb.
- tcpto6, a binary file hosting connection timeout information +in a similar way to /var/qmail/queue/lock/tcpto, but for IPv6. +qmail-remote reuses the same tcpto file as the original +for IPv4 timeouts, and is still compatible with the +qmail-tcpto +program; however, a new file was necessary for IPv6, and creating it +under /var/qmail/queue/lock was tricky because the qmail queue +has very precise permissions and it is better to leave it untouched. +Since qmail-remote needed a new directory writable by qmailr +to host its SMTP routes map anyway, storing the tcpto6 files in the +same place is a logical decision.
qmail-remote uses the +skadns library +to perform DNS resolutions asynchronously. If you see a weird skadnsd +process running as a child of qmail-remote, that's why.
The whole SMTP exchange can happen either over a TLS-encrypted connection +after a STARTTLS command, or over a cleartext connection. To separate TLS +management from the SMTP client and avoid duplication of code, the SMTP +exchange is actually handled by a separate binary: +qmail-remote-io. If your process list +shows a qmail-remote-io process under qmail-rspawn instead +of the regular qmail-remote, that is normal, it means that +qmail-remote has found a suitable server and is transmitting its +data. If there is a +s6-tlsc-io +process running as the child of qmail-remote-io, it means that the +connection is happening under TLS.

smtpd-starttls-proxy: the qmail-smtpc program

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

The `qmail-smtpc` program

-qmail-smtpc is an SMTP client, meant to be used as a drop-in -replacement to -qmail-remote. -

- 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-smtpc follows the exact same interface as -qmail-remote. -The binary can literally be renamed qmail-remote then dropped -in /var/qmail/bin in place of the stock qmail-remote -program. With some patches, it can also be used by setting the -QMAILREMOTE environment variable to the path where qmail-smtpc -is installed. -

Differences with qmail-remote

If the underlying OS and skalibs -support IPv6, then qmail-smtpc does as well, and use IPv4 and IPv6 -addresses indiscriminately when connecting to an MX.
It speaks ESMTP and will use STARTTLS if the server supports it.

Control files

- qmail-smtpc uses a few extra control files in /var/qmail/control: -

- -

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.

Internal commands

Related resources

The qmail-remote-io internal program

Internal details

The qmail-remote program

Interface

Differences with other implementations of qmail-remote

Control files

Implementation notes

The qmail-smtpc program

Interface

Differences with qmail-remote

Control files

The `qmail-remote-io` internal program

The `qmail-remote` program

The `qmail-smtpc` program