qconfirm - How it works
qconfirm-check checks for each message if the envelope sender of this message is allowed to send mail to the user owning the .qmail file it was invoked from.
If qconfirm-check already knows this envelope sender, or was told to accept mails from this sender, it immediately exits with 0, and so allows the mail to be processed further in the .qmail file. If not, qconfirm-check injects a confirmation request message to the envelope sender asking for a reply, and exits 99 to defer the message temporarily. The message will stay in the qmail queue and will be tried to be delivered in a little while.
qconfirm-check then defers this message
on future delivery attempts and all other messages from the same envelope
sender temporarily without injecting another confirmation request message
until a reply to the confirmation request message is received (Exception:
see the -t option).
If queuelifetime has expired for a message before a reply to the
confirmation request was received, the message is bounced and never
delivered to the recipient.
The sender mail address is split into two parts, the local part
and the host part. For example if the sender mail address is
firstname.lastname@example.org, the local part is floyd, the
host part is smarden.org.
These two parts are concatenated in reverse order with a "=-"
in between, any uppercase letter is converted to lowercase, and finally
each dot, slash, and apostrophe is replaced by a colon. So the id for
email@example.com is smarden:org=-floyd.
smarden:org=-floyd-extension smarden:org=-floyd-default smarden:org=-default defaultIf at least one of these files exists in the ~/.qconfirm/ok/ directory, the message is allowed to be processed further in the .qmail file. If qconfirm-check runs with the -b option, the same matching takes place for the .qconfirm/bad/ directory.
Extended envelope sender domain matchingIf qconfirm-check runs with the -d option, it additionally checks the host part of the id with a wildcard similar to qmail-smtpd's rcpthosts. For example, the address firstname.lastname@example.org with the id list:smarden:org=-floyd-list is matched by the following files:
list:smarden:org :smarden:org :orgExtended domain matching is applied after matching the envelope sender address id.
Sending the confirmation requestIf the envelope sender isn't matched to be allowed, qconfirm-check creates a random key, creates a file with the filename "id" in the ~/.qconfirm/pending/ directory containing the key, and creates a .qmail-qconfirm-key file in the user's home directory to handle the reply to the confirmation request. qconfirm-check injects the confirmation request message to the envelope sender address with the from header: user-qconfirm-key@host.
Handling the reply to the confirmation requestThe reply to the confirmation request messages goes to the address user-qconfirm-key@host and so is handled by the .qmail-qconfirm-key file. qconfirm-check automatically has set up a program delivery to qconfirm-accept in this .qmail file. So if a mail to this address is received, qconfirm-accept is invoked. qconfirm-accept then moves the file with the filename "id" from the ~/.qconfirm/pending/ directory to the ~/.qconfirm/ok/ directory, writes the message (the reply to the confirmation request) to this file, and removes the .qmail-qconfirm-key file it was invoked from.
The next time qmail tries to deliver a temporarily deferred or a new message from this envelope sender, qconfirm-check matches the sender to be allowed and allows the message to be processed further in the .qmail file. If the file in the ~/.qconfirm/ok/ directory that matched the envelope sender is not empty, qconfirm-check optionally injects a confirmation acknowledgement message to the envelope sender, including the contents of the file at the bottom of the message, and then truncates this file to the size 0.
Handling bounces from confirmation requestsqconfirm can be configured to process bounces from confirmation request messages, and so to reduce the amount of doublebounces reaching the postmaster's mailboxes. See Handling bounce messages for details. qconfirm-check is running in message mode, each single message must go through the confirmation process. The id qconfirm-check uses for identifying a message is not created from the envelope sender but is the inode number of the message stored in the qmail mail queue.
Gerrit Pape <email@example.com> $Id: technical.html,v 1.9 2003/01/02 13:52:03 pape Exp $