''userdb'' '''

The User Database is a special database file that you create for use by sendmail. It causes sender and recipient addresses to be rewritten under control of an external database. Ordinarily, any local address is first looked up in the aliases database. If it is not found there, that user's ~/.forward is next examined. If the User Database is enabled, the address is looked up in that database after aliasing and before forwarding, but only if the selected delivery agent has the F=@ flag set (F=@).

In the sections that follow, we describe the use of this database in detail, but first we will note a few important points.

Although we illustrate here that a lookup can be done using a database file, a remote lookup can also be done via a User Database server, or via a network service. Those forms of lookup are described in UserDatabaseSpec.

You can also look up addresses in the User Database with rule sets using this userdb database-map type. To do so, you declare it like this:

Kname userdb  switches  field

Here, the name is the name you will use in later rule sets. The field is either a literal maildrop or mailname (see See this section). The possible switches are shown in Table 23-27.

One use for this database-map type might be to intercept each RCPT TO: address, and log whether it will be transformed by the User Database:

Kudb userdb -f -a.FOUND maildrop
Klog syslog

SLocal_check_rcpt
R $*                  $: $>canonify $1
R $+ < @ $* > $*      $: $1<@$2>$3 $| $(udb $1 $)
R $* $| $* . FOUND    $: $(log $1 transformed by userdb into $2 $) $1

Here, we declare a userdb database-map type called udb. The -f says to look up addresses in a case-insensitive manner. The -a says to append a literal .FOUND to any match. Finally, the maildrop says to look up a recipient address with a :maildrop suffix attached.

We also declare a syslog database-map type (syslog) named log, which we will use to syslog the result.

The rule set in Local_check_rcpt (Section 7.1.3) contains three rules, and they are called just after each RCPT TO: command. In the first rule we make sure the address is focused. In the second rule we first arrange to return the original address in the workspace (the $1<@$2>$3 in the RHS) and a $| separator. Then we perform the lookup and add that result to the workspace.

The third rule looks for a workspace that ends in a literal .FOUND and, if it finds such a workspace, logs the result. For a focused address such as gw<@wash.dc.gov>, the result might be:

gw<@wash.dc.gov> transformed by userdb into george@retired.wash.dc.gov

Enable the User Database

The User Database is automatically enabled when you compile sendmail if you include support for NEWDB or HESIOD (USERDB). To see whether a precompiled version of sendmail includes User Database support, run it with the -d0.1 switch:

% /usr/sbin/sendmail -d0.1 -bt < /dev/null 
Version 8.12
 Compiled with: LOG MIME8TO7 NETINET NETUNIX NEWDB SCANF USERDB  XDEBUG
                                                           
                                                         note

If USERDB is listed, User Database support is included.

Next, you must declare the location of the database file with the UserDatabaseSpec option (UserDatabaseSpec):

OU/etc/mail/userdb                        in your cf file (V8)
O UserDatabaseSpec=/etc/mail/userdb       in your cf file (V8.7 and above)
define(`confUSERDB_SPEC',/etc/mail/userdb)    in your mc file

Here, the location of the database file is set to be /etc/mail/userdb. You can also enable a default location for the database file that will take effect should the UserDatabaseSpec option be missing by defining that location with UDB_DEFAULT_SPEC when compiling (UDB_DEFAULT_SPEC).

Create the User Database

The User Database is a btree-type (btree) database file created from a source text file using the makemap program:

% makemap btree /etc/mail/userdb.db < /etc/mail/userdb 
             
      this type is mandatory for the User Database

Here, /etc/mail/userdb is the source-text file that is input, and /etc/mail/userdb.db is the database we are creating (the one defined by the UserDatabaseSpec option in the previous section).^[18]

^[18] The .db is added automatically if it is missing. We include it here for clarity.

The source text file is composed of key and value pairs, one pair per line:

key    value
      
  whitespace

The key is a user's login name, a colon, and one of two possible keywords: maildrop or mailname. The keyword determines the nature of the value.

maildrop

For maildrop, the value is the official delivery address for this user. If there are multiple official addresses, they can be listed as a single compound value, with separating commas. For example:

root:maildrop         sysadmin@here.us.edu,bill@there.us.edu

Or they can be listed on individual lines:

root:maildrop         sysadmin@here.us.edu
root:maildrop         bill@there.us.edu

This latter form requires you to use the -d command-line switch with the makemap(1) program (-d) when creating the database, but it has the advantage of being a simpler source file to manage.

mailname

The mailname keyword causes a "reverse alias" transformation. That is, it causes the login name in the key to be changed into the address in the value for outgoing mail. For example:

bob:mailname          Bob.Roberts@Here.US.EDU

This causes mail sent by bob to go out addressed as though it is from Bob.Roberts@Here.US.EDU.^[19] This transformation occurs in the header and envelope. But note that the sender-envelope is not rewritten by UDB unless the F=i flag (F=i) is present in the delivery agent that is selected for the sender. Also note that the recipient headers are not rewritten by UDB unless the F=j flag (F=j) is set for the delivery agent that was selected for the recipient.

^[19] Using full names in outgoing mail is probably not a good idea. Unlike login names, full names are not guaranteed to be unique. If current users expect to be able to receive mail under full names, future users with the same full name might be out of luck. Always weigh convenience against maintainable uniqueness when designing your mail setup.

Naturally, the maildrop and mailname keywords should occur in pairs. Each outgoing address that is created with mailname should have a corresponding maildrop entry so that return mail can be delivered. In the previous example a reasonable pair might look like this:

bob:mailname          Bob.Roberts@Here.US.EDU
Bob.Roberts:maildrop  bob

Here, outgoing mail from the user named bob will be addressed as though it is from Bob.Roberts@Here.US.EDU. Incoming mail (whether it is original or in reply to the outgoing) will be addressed as though it is to the name Bob.Roberts, which will be transformed into and delivered to the local user bob.

A :default outgoing hostname

The mailname keyword allows the host part of outgoing addresses to mask the real hostname of the originating machine. This property can, for example, be used to convert the hostname into a firewall name:

bob:mailname          bob@Firewall.US.EDU

Here, the canonical name of bob's machine is Here.US.EDU. The mailname keyword causes outgoing mail from bob to appear as though it is from the firewall machine (Firewall.US.EDU) instead.

Ordinarily, this transformation is not automatic. Each username that is to appear to be from the firewall machine will need an entry such as that in the User Database (see earlier example). To automate this process, you can use the special username :default in a mailname declaration:

:default:mailname     Firewall.US.EDU

If a maildrop entry is found for a particular name, but no corresponding mailname record is found, the outgoing address is ordinarily unchanged. If, however, a default hostname has been defined with :default, that hostname replaces the local hostname for all addresses that lack their own mailname entry:

:default:mailname     Firewall.US.EDU
bob:maildrop          bob@here.us.edu

In this example the user bob has a maildrop entry but lacks a mailname entry. Outgoing mail from this user will have the :default hostname used instead of the local hostname. The user sally, on the other hand, has neither a maildrop entry nor a mailname entry and so will not have her outgoing address rewritten.