The AUTH_CDB patch allows qmail-smtpd to validate AUTH commands by reading a .cdb file, as opposed to running an external checkpassword program (like vpopmail's vchkpw.) There are several advantages to doing it this way:
It's fast. Because the information is stored in a .cdb file, any user's information can be retrieved with no more than two disk reads- and on most systems (i.e. systems which don't have thousands or mailboxes) it only takes one disk read.
It allows users to authenticate on machines other than where their mailbox resides. If you have a large network and are using one or more mailhub machines to handle the RBL, virus, and spam scanning before handing the message to the mailbox server, you can copy the .cdb file out to the mailhubs, and users will be able to authenticate on the mailhubs and relay their outbound mail, without involving the mailbox server at all.
Versions of the patch dated 2007-09-12 or later have the ability to set specific environment variables when a specific user logs in. This makes it possible to implement things like per-user message size limits (i.e. most users can send messages up to 5MB, people in certain departments can send up to 20MB per messages, and the managers and IT people have no limit at all) by adding or changing a DATABYTES environment variable.
There is a dis-advantage to doing it this way as well: you have to create the .cdb file, and you need to update it every time a mailbox is added or deleted, or somebody changes their password.
I have written a script called "mkauth" which reads the system and vpopmail password databases and either writes out a text file which can then be converted into the .cdb file, or writes out the .cdb file directly.
Of course the problem becomes knowing when to run it- which is why I created the onchange patch for vpopmail, so that any time vpopmail makes a change, it runs an external script which can be used to do pretty much anything you need to do, including running the script to rebuild the .cdb file.
The problem there is that when vpopmail runs the script, the script runs as whatever userid was running the vpopmail command- and if that user is not root, it won't have write access to the .cdb file we need to update. This is why I always set up a qmail-updater service, which listens for incoming data on a named pipe, and runs a certain command whenever data is received.
The idea is that any userid is able to send data to the pipe, but the service itself is running as root and only runs the exact script it's been programmed with. If this script happens to rebuild the .cdb files used for AUTH and validrcptto.cdb purposes, then the problem is solved, in a secure manner.
This page is not here to explain the vpopmail onchange patch or how a qmail-updater service works, I already have pages for that. This page will cover the specifics of working with the AUTH_CDB patch itself.
At the current time, the AUTH_CDB patch is only available as part of my combined qmail patch. This is because I wrote it as part of the combined patch, and it relies on code which is part of the earlier AUTH patch in order to do much of its work. At some point in the future I may have a go at building a stand-alone patch for djb's source code and for netqmail, but the truth is I don't really have the time to mess with it.
The AUTH_CDB code, which I was testing at the time, was accidentally released on 2006-03-08, with version "6c5" of the combined patch. Several people started using it, and nobody reported any problems (other than things like "how does it work?" and "how do i configure it?") so I'm pretty sure it works.
I later updated the code on 2007-09-12, with version 7.02 of the combined patch. I changed the file format- in addition to a user's encrypted password, the .cdb file can now also contain one or more environment variable definitions, which are added to the environment whenever that particular user logs in. A sample entry with an environment variable attached looks like this:
This walks through a sample process of creating and using an auth.cdb file. You will note that we actually create the file using a different name, and then rename it into place. This is to avoid the possibility that qmail-smtpd will try to read the file while it's in the process of being built, or doesn't have the correct permissions.
# cd /var/qmail
# mkauth Not necessary, I'm including it here so you can see what the output looks like.
# mkauth > auth.txt
# cdbmake-12 work.cdb work.tmp < auth.txt
# chown root:nofiles work.cdb
# chmod 0640 work.cdb
# mv work.cdb auth.cdb