A virtusertable is a database that maps virtual (possibly nonexistent) domains into new addresses. Essentially, it gives you a database hook into the early part of the parse rule set 0. Note that this only reroutes delivery. It does not change mail headers.

By way of example, consider one mapping in a source text file:

info@stuff.for.sale.com       bob
info@stuff.wanted.com         hans@remote.host
info@auction.com              hans@remote.host
@fictional.com                user@another.host

The key portion (on the left) must be either a full address (user, host, and domain name), as in the first two lines, or an address without a host part (just a domain), as in the third line, or an address with the user part missing, as in the last line. This source text file is converted into a database with the makemap(1) program (Section 5.5).

The first three lines illustrate a full address for the key. The first line will be delivered to a local user (bob), the second and third to a remote user (hans@remote.host). The fourth line shows how all mail to a virtual domain (fictional.com) can be delivered to a single address, regardless of the user part.

Note that sendmail does multiple lookups, so one line can reference another. The following, for example, will work:

info@stuff.for.sale.com       forsale@fictional.com
@fictional.com                user@another.host

Here, mail to info@stuff.for.sale.com will be delivered to user@another.host.

Also note that virtual hosts, just like real hosts, need to belong to class w ($=w) for them to be recognized as local. Also note that beginning with V8.10, virtual hosts can also be listed in your mc file, or in an external file, by using the VIRTUSER_DOMAIN mc configuration macro (See this section) or the VIRTUSER_DOMAIN_FILE mc configuration macro (See this section). Hosts listed with these macros will be looked up in the virtusertable but will not be considered local.

If the value (the righthand side in virtusertable) is error:, the #error delivery agent is called. This allows error messages to be put into the database, as, for example:

info@for.sale.com    error:nouser We no longer sell things here   V8.9 and earlier
info@for.sale.com    error:5.7.0:550 We no longer sell things here    V8.10 and above

The text following the error: is passed to the #error delivery agent. The first token following the error: is passed in the $@ part. Note that, prior to V8.10, you had to use words or <sysexits.h > codes here, not DSN values (such as 5.7.0) because the latter were wrongly broken up into five tokens. Beginning with V8.10, you can also use DSN values here, and they will be handled properly. See error for a full description of the #error delivery agent and for tables of useful words for the $@ part.

You declare the virtusertable like this in your mc file:

FEATURE(`virtusertable')

This causes the following database declaration to appear in the configuration file:

Kvirtusertable hash /etc/mail/virtusertable

If you wish to use a different form of database (such as dbm) or a different location, the virtusertable feature accepts an argument:

FEATURE(`virtusertable',`dbm -o /etc/mail/virt_user_table')

If you provide a second argument for the virtusertable feature that is a literal LDAP:

FEATURE(`virtusertable', `LDAP')

the default becomes the following (we have wrapped the lines to fit the page):

Kauthinfo ldap -1 -v sendmailMTAMapValue -k (&(objectClass=sendmailMTAMapObject)
(|(sendmailMTACluster=${sendmailMTACluster})(sendmailMTAHost=$j))
(sendmailMTAMapName=virtuser)(sendmailMTAKey=%0))

See ldap (was ldapx) for a description of the ldap database type and its -1, -v, and -k switches.

In Section 19.5 we deal with the flow of rules through the parse rule set 0. For now, merely note that this virtusertable feature fits into the flow of rules through the parse rule set 0 like this:

VIRTUSER_DOMAIN mc macro

Beginning with V8.10 sendmail, a new macro was introduced to make it easier to add domains for use with the virtusertable feature. Called VIRTUSER_DOMAIN, it is used like this:

VIRTUSER_DOMAIN(`domain1 domain2 etc')

Each domain that you intend to list should be listed individually, each separated from the others by spaces. Multiple VIRTUSER_DOMAIN lists can be declared in your mc file like this:

VIRTUSER_DOMAIN(`domain1')
VIRTUSER_DOMAIN(`domain2')
VIRTUSER_DOMAIN(`etc')

If you are currently declaring virtual user domains in the $=w class, you are encouraged to convert to this new macro. Use of it will insulate you from change in the future. Note that hosts in $=w for masquerading should not be moved, but should, instead, be copied.

VIRTUSER_DOMAIN_FILE mc macro

Beginning with V8.10 sendmail, a new macro was introduced to make it easier to list domains for use with the virtusertable feature. Called VIRTUSER_DOMAIN_FILE, it is used like this:

VIRTUSER_DOMAIN_FILE(`/etc/mail/virtuserdomains')

This declaration causes domains to be read from the file /etc/mail/virtuserdomain. Because VIRTUSER_DOMAIN_FILE is implemented with an F configuration command (Section 22.1.2), you can add whatever F command arguments you desire. For example:

VIRTUSER_DOMAIN_FILE(`-o /etc/mail/virtuserdomains')

Here, the -o switch makes the presence of the /etc/mail/virtuserdomains file optional.

If you are currently storing virtual domains in the $=w class, you are encouraged to convert to this new VIRTUSER_DOMAIN_FILE macro. Use of it will insulate you from change in the future. Note that hosts in $=w for masquerading should instead be copied.