The qmail-users Mechanism

---

qmail-users is a system for assigning addresses to users. Normally, local deliveries are handled by qmail-lspawn, which runs qmail-getpw to determine which user the address belongs to, where their home directory resides, their UID, GID, and the breakdown of the address if it's an extension address.

However, if the file /var/qmail/users/cdb exists, qmail-lspawn attempts to look up the delivery details there first. The users/cdb file is a binary database generated from users/assign using the qmail-newu command. The assign file is a table of assignments. There are two kinds of assignments: simple and wildcard.

Note 

assign contains a series of assignments, one per line, followed by a line containing a single dot (.). If you create assign manually, don't forget to add the "dot" line.

Simple Assignment

A simple assignment looks like

 =address:user:uid:gid:directory:dash:extension: 

What this means is that messages received for address will run as user user, with the specified uid and gid, and the file directory/.qmaildashextension will specify how the messages are to be delivered.

For example, say you want mail for the local recipient info to be handled by user andy (UID=35, GID=20, directory=/home/andy) using the file /home/andy/.qmail-info. The following simple assignment will accomplish that:

 =info:andy:35:20:/home/andy:-:info: 

Note 

If multiple simple assignments specify the same address, qmail-lspawn will use the first one.

Wildcard Assignment

A wildcard assignment looks like

 +prefix:user:uid:gid:directory:dash:prepend: 

What this means is that messages received for addresses of the form prefixrest will run as user user, with the specified uid and gid, and the file directory/.qmaildashprependrest will specify how the messages are to be delivered.

For example, given the following wildcard assignment:

 +andy-:andy:35:20:/home/andy:-:: 

A message for andy-info will be delivered as user andy using the directions in /home/andy/.qmail-info.

Note 

More specific wildcard assignments take precedence over less specific wildcard assignments, and simple assignments take precedence over wildcard assignments.

qmail-users Programs

qmail-users has two helper programs: qmail-newu and qmail-pw2u. qmail-newu processes the assign file and generates a constant database (CDB) file called cdb in /var/qmail/users. CDB is a binary (machine readable, not human readable) format that can be accessed quickly by qmail-lspawn, even when there are thousands of assignments.

qmail-pw2u converts the system user database, /etc/passwd, into a series of assignments suitable for assign. qmail-pw2u uses a set of files to modify the translation rules:

• include—specific users to include in assign

• exclude—specific users to exclude from assign

• mailnames—alternative "mailnames" for users

• subusers—extra addresses handled by a user, with an optional .qmail extension

• append—miscellaneous assignments

Caution 

If you use qmail-pw2u, don't forget to re-run qmail-pw2u and qmail-newu whenever you add users, remove users, change UIDs, or change GIDs.

---