12.5 The Aliases Database

Reading the aliases file every time sendmail begins to run can slow mail delivery and create a lot of unnecessary computational overhead. To improve efficiency, sendmail has the ability to store aliases in a separate database format on disk. In this format, sendmail rarely needs to read the aliases file. Instead, it merely opens the database and performs lookups as necessary.

The sendmail program builds its database files by reading the aliases(5) file and rewriting that file in database format. Usually, the aliases file is called aliases. With that name, ndbm(3) database files are called aliases.pag and aliases.dir, and the db(5) database file is called aliases.db.

The sendmail program offers several forms of database, one of which is chosen at compile time (see confMAPDEF).

12.5.1 Rebuild the Alias Database

You tell sendmail to rebuild its database files by running it in -bi mode. This mode can be executed in two different ways:

% newaliases
% /usr/sbin/sendmail -bi

The first form is shorthand for the second. Either causes sendmail to rebuild those files. If the database is successfully built, sendmail prints a single line:

895 aliases, longest 565 bytes, 30444 bytes total

This shows that 895 entries appeared to the left of colons in the aliases file. The longest list of addresses to the right of a colon was 565 bytes (excluding the newline). And there were 30,444 total bytes of noncomment information in the file.

V8 sendmail supports multiple alias database files (see the AliasFile option, Section 24.9). Consequently, each line of its output is prefixed with the name of the alias file being rebuilt. For example:

/etc/aliasdir/users: 895 aliases, longest 565 bytes, 30444 bytes total
/etc/aliasdir/lists: 34 aliases, longest 89 bytes, 1296 bytes total

Beginning with V8.11, sendmail allows only root and the user listed with the TrustedUser option (TrustedUser) to rebuild the aliases database.^[14] If you are neither, you will see the following error message, and the database rebuild will fail:

^[14] V8.12 and above sendmail are no longer set-user-id root, which further limits who can rebuild aliases.

Permission denied (real uid not trusted)

12.5.2 Check the Right Side of Aliases

When V8 sendmail rebuilds the alias database files, it can optionally be told to check the legality of all addresses to the right of the colons. The CheckAliases option (CheckAliases) turns on this check:

O CheckAliases=True    # validate RHS in newaliases

Each address is validated by running it through the canonify rule set 3, then the parse rule set 0. Rule set parse must select a delivery agent for the address. If it does, the address is silently validated and accepted. If not, the address is skipped, and the following warning is printed:

address... bad address

Other errors might be printed before this line that indicate more specific reasons for the failure. For example:

... Unbalanced '<'

The -d20.1 debugging switch (see -d20.1) can be used to gain a better idea of why the address failed. But be forewarned: the -d20.1 switch can produce many screens of output.

In general, we do not recommend setting the CheckAliases option to true in the configuration file because it can cause each right-side address to be resolved through DNS and thus slow down the rebuild considerably. For better efficiency, leave the CheckAliases option off in the configuration file and turn it on only when rebuilding by hand:

% newaliases -OCheckAliases 
% newaliases -on                    old-style shorthand, still legal 

12.5.3 Use Trailing Dots

It is often desirable to create aliases files that have nonlocal addresses to the right of the colon:

# sean took a job at the fire station
sean:        sean@firehouse.eli.nv.us

Normally, there is no harm in putting nonlocal addresses in your aliases file. But terrible things can go wrong when the Internet goes bad. Consider, for example, when the name server for firehouse.eli.nv.us begins to act up. Then it is possible for you to run:

% newaliases -on

and have the run seem to hang, when it is only stuck, waiting for a bad name server to give back information about firehouse.eli.nv.us. If the wait is long, you might be tempted to kill the rebuild with a kill(8) of -9.

When sendmail's rebuild is killed while stuck, the aliases database can be left in an incomplete state or with a size of zero. In either instance, inbound mail will likely begin to bounce. When that happens, you can immediately rebuild with the -on omitted. This will restore the bad aliases database to a good state.

There might be times, however, when you want the aliases database rebuilt with the -on always included. In such an instance, we recommend that you reduce the risk of sendmail hanging by placing a dot at the end of any addresses that seem suspect. For example:

# sean took a job at the fire station
sean:        sean@firehouse.eli.nv.us.
                                      
                                   add a dot

The presence of the dot short-circuits sendmail's lookup of that address. The address is presumed good, and the rebuild of the aliases database can continue at a fast rate.

12.5.4 Prevent Simultaneous Rebuilds

The alias database files can be automatically rebuilt in two ways: automatically, by the daemon or by users sending mail (and thereby indirectly running sendmail),^[15] or explicitly, by users rebuilding the database with newaliases (or the -bi command-line switch). To prevent one rebuild from compromising and corrupting another, sendmail uses file locking.

^[15] Under pre-V8.12, this occurred only if the AutoRebuildAliases option (AutoRebuildAliases) was set to true. This option has been removed beginning with V8.12 sendmail, and the aliases database can no longer be automatically rebuilt.

The sendmail program uses flock(2) or fcntl(2) with F_SETLK to lock the aliases file (depending on how it was compiled). If the aliases file is already locked (because the database is currently being rebuilt), sendmail prints the following message:

Alias file name is already being rebuilt

If sendmail is attempting to rebuild because it was run as newaliases or with the -bi command-line switch, the previous message is printed, and the program exits. Otherwise, the previous message is printed, and sendmail waits for the aliases file to become unlocked.

Once the aliases file is locked, sendmail next looks to see whether the key @ appears in the database. If that key is missing, sendmail knows the database is still being rebuilt. If the AliasWait option (AliasWait) has a value, sendmail waits that amount of time for the other rebuild to finish. If the AliasWait option is missing or has a zero value, sendmail plows ahead, trusting the previous lock to prevent simultaneous rebuilds.

The sendmail program waits the number of seconds specified by the AliasWait option for an @ key to appear in the database. If that key doesn't appear within that wait, sendmail continues with the rebuild, assuming that some other process died while attempting to rebuild.

Before entering the key (the name to the left of the colon) and contents (everything to the right of the colon) pairs into the database, sendmail truncates the database (reduces it to size zero), thereby removing the @ key.^[16] After all the key and contents pairs have been written to the database, sendmail adds a new @ key to show that it is done.

^[16] Even though we show how sendmail rebuilds its aliases file, you should not take this as advice to use makemap(1) to perform that task. You should use newaliases (or the -bi command-line switch) only to rebuild.

Finally, sendmail closes the database and the aliases file. Closing the aliases file releases all locks it has on that file.

12.5.5 No DBM Aliasing

Some versions of Unix do not provide the libraries that are needed to compile sendmail with database support. When neither the db(3) nor ndbm(3) library is available, and when no other method for getting aliases is declared (such as nis), sendmail keeps aliases in its internal symbol table.

When the symbol table is used, sendmail reads the aliases text file only once, when sendmail starts or is forked as a child. If the aliases text file changes, a running daemon will not automatically recognize that change. Instead, the daemon must be killed, and restarted, before it can use any new aliases text file entries.

In general, we discourage you from running sendmail in daemon mode without external aliases database files.