15.2 Making the Users File

The format of /var/qmail/users/assign is fairly simple. It's a sequence of lines with two slightly different formats, one for an exact match and one for wildcards. An exact match line starts with an equals sign:

=local:user:uid:gid:homedir:dash:ext:

This means that mail to address local is delivered to user with user and group IDs uid and gid and home directory homedir, using a qmail file named .qmail dashext. (Usually dash and ext are null.)

A wildcard line starts with a plus sign:

+loc:user:uid:gid:homedir:dash:pre:

In this case, any address that starts with loc is handled by the given user, with pre inserted in front of the rest of the address to determine the name of the qmail file. (In this case dash is usually a dash, and pre is usually null.)

Here's a snippet from a real assign file:

+:alias:121:105:/var/qmail/alias:-:: =carol:carol:108:102:/usr/home/carol::: +carol-:carol:108:102:/usr/home/carol:-::

In this case, mail to carol is handled by the second line, and delivered using /usr/home/carol/.qmail, while mail to carol-ina is handled by the third line and delivered using /usr/home/carol/.qmail-ina. Any address not starting with carol is handled by the first catchall line so that mail to, say, fred is delivered using /var/qmail/alias/.qmail-fred. Note the hyphen in the third line in carol-, so that line matches any of carol's subaddresses, but not plain carol.

Usually the list of users in assign is more or less the same as the list in /etc/passwd, so qmail provides the qmail-pw2u utility to create your assign file. I use this Makefile to control the process:

cdb:        assign         ../bin/qmail-newu assign: /etc/passwd append exclude         cp assign assign.old         ../bin/qmail-pw2u < /etc/passwd > assign

When creating assign, qmail-pw2u uses approximately the same rules as qmail-getpw, ignoring any users that have a zero uid, don't own their home directory, or contain capital letters. For each user, the output contains two lines, with the username, user and group IDs, and home directory from the password file, as in the "carol" example.

Several command-line flags to qmail-pw2u modify the default behavior and are documented in the manpage, but I've never found the flags very useful. The only ones I've ever used are -h, fail if a user's home directory doesn't exist, and -c, change the separator character from a hyphen to something else, usually a plus sign for compatibility with the subaddressing in sendmail and postfix. What is useful is a set of auxiliary files in /var/qmail/users that modify the generated assign file:

exclude

A list of users to omit, either because they shouldn't get mail or because their mail setup isn't the default. It should include accounts such as bin, daemon, and uucp that don't have human readers to read the mail. (You can and should create qmail files in ~alias to forward mail sent to any of those addresses that are likely to get interesting mail, of course.)

include

A list of users to include. If this file exists, only users in the file have lines generated in the output.

append

The contents of this file are literally appended to the output. This is usually a combination of mail-only users not in the password file and modified info for specially handled users, e.g., users that don't use subaddresses.

mailnames

Mail aliases. A line of the form jim:jim:james:jimmy makes the second and subsequent fields aliases for the first, and creates a pair of output lines for each alias. Note that if the username doesn't appear as one of the aliases, there will be no entries for the user itself. Most system managers prefer to use .qmail files in ~alias or entries in /etc/aliases instead.

subusers

Users implemented as subaddresses of other users. A line of the form jim:fred:jf: creates a pair of lines so that mail to fred is treated as mail to jim-jf and mail to fred-ext as mail to jim-jf-ext. Except for the simplest setups, again I prefer qmail files in ~alias or entries in /etc/aliases.

Assuming you use the Makefile shown previously, you just need to run make in /var/qmail/users every time to add or delete a user to or from the password file. Qmail rechecks cdb for every local delivery so there's no need to restart qmail.