[ Current Issue Home | Issue #4 Home | FAQ ]��

The FreeBSD 'zine
Featured Articles: Sendmail
## A Virtual Hosting How-to
## Jim Mock <>

Back in January's Issue #1, I covered some of anti-spam features in an article entitled 'Stomping spam with Sendmail', which seemed to be well received. I had originally planned on following it up in February's Issue #2 with this article, but somehow it never came to life, so I figured it was about time it got done.

The rest of this article will cover setting up sendmail virtual hosts and hopefully will provide a decent starting point for you if you decide to venture into the realm of virtual email hosting.

What is virtual email hosting?

Virtual email hosting is simply a spiffy term used to describe hosting mulitple email domains. Sometimes users want the same username in their email address, but at different domains. If that sounds confusing or you don't quite understand it, allow me to explain..

Let's say a customer of yours, we'll call him John, has registered his domain name, we'll use johnsdomain.com, and wants to receive email at his domain. However, another customer, Bob, has registered his domain name, bobsdomain.com, and wants to receive email his domain as well. This doesn't become a problem until they both want to use the same address(es), such as webmaster or sales. Once that need arises, you need to be able to tell sendmail how to handle it, which is where the 'virtusertable' feature of sendmail comes in. To sum it up, sendmail's virtusertable feature allows users of two different domains to both have the same 'username' part of email addresses they receive, such as [email protected] and [email protected].

How do I do it?

There are really two parts to setting up email virtual hosting. The first is the DNS configuration for the domain which isn't going to be covered here. This assumes you've already chosen a domain, registered it, and set up the DNS configuration with the exception of MX records, which will be covered very generally. If you want full details on MX records, they're covered in the Sendmail book (the Bat Book) by .

Configuring MX records

To configure the MX (Mail eXchanger) records for your domain, you'll need to edit your DNS configuration. You've got two options for MX records:

  1. If the mail server which will serve your domain has a full-time connection to the 'net, it should be the primary MX host for your domain. It would look like the following in your DNS configuration (using johnsdomain.com):
            johnsdomain.com   IN    MX   10   mail.yourdomain.com.

  2. If the mail server does not have a full-time connection, you'll need to find another machine to queue the mail for your domain while it's off line. Then you'd point your MX records at that machine as well. For example:
            johnsdomain.com   IN    MX   10   mail.yourdomain.com.
            johnsdomain.com   IN    MX   20   mail.otherdomain.com.

Be sure to get permission from the owner of 'mail.otherdomain.com' before using it as a secondary MX host.

Configuring sendmail

Now that you have the DNS records set up correctly (hopefully), you can move on to the sendmail configuration. This assumes that you already have downloaded the sendmail source and installed sendmail. If you haven't, do so now. Instructions and help can be found on the .

The first thing you'll want to do is read through the sendmail-8.9.x/cf/README file. It provides instructions on creating a hostname.mc file in the sendmail-8.9.x/cf/cf directory. Here's what the .mc file (rock.mc) from one of my servers looks like:

        [copyright info snipped for space]
        # This is the sendmail-8.9.x config file for rock.ghis.net
        # Author: Jim Mock <[email protected]>
        # Last modified:  Thu Mar 4 1999 14:26:02
        VERSIONID(`@(#)rock.mc       1.1 (rock.ghis.net) 3/4/99')

To take advantage of the virtusertable feature, add the following line:

        FEATURE(virtusertable, hash -o /etc/mail/virtusertable)dnl

You may also have some other FEATURE() and define()'s along with it (psst, now would be a good time to add the anti-spam features from Issue #1), but the virtusertable feature is the key to making virtual email hosting work.

After you've created or modified your .mc file you'll need to generate a new sendmail.cf. To do so, perform the following from inside the sendmail-8.9.x/cf/cf directory:

        # m4 ../m4/cf.m4 hostname.mc > sendmail.cf

You should now see a sendmail.cf in the sendmail-8.9.x/cf/cf directory. The next step is to copy it to /etc, however I suggest backing up your existing /etc/sendmail.cf BEFORE copying it. It will save you time and headaches if you mess up.

        # cp /etc/sendmail.cf /etc/sendmail.cf.bak
        # cp sendmail.cf /etc

Now you should have the new file, and a backup of the old sendmail.cf in /etc. Don't forget that any domains you're providing mail services for must be added to /etc/sendmail.cw.

The next step is creating the virtual user table.

Creating the virtual user table

Since our .mc file's FEATURE line for virtusertable is set to use /etc/mail/virtusertable as the database file, we'd better use it or we'll have problems because sendmail won't know where to find it.

        # cd /etc/mail
        # pico virtusertable

Replace pico with the editor of your choice.

The table you're about to create is a database that maps virtual addresses into real addresses. It's a text file where each line has a key/value pair separated by a TAB. An example table using johnsdomain.com would look like this:

        [email protected]    jsmith
        [email protected]    [email protected]
        @johnsdomain.com        jsmith

In the above example, the address [email protected] is mapped to the local user jsmith, the [email protected] is mapped to the remote user [email protected], and any other mail for johnsdomain.com goes to the local user jsmith.

Here's another slightly different example:

        [email protected]    jsmith
        [email protected]     error:nouser No such user here
        @johnsdomain.com        %[email protected]

In this example, mail to [email protected] still goes to the local user jsmith, mail sent to [email protected] gets bounced with the indicated error message, and every other user johnsdomain.com will be mapped to a remote user of the same name at johnsdomain.net.

Here's another example using both johnsdomain.com and bobsdomain.com:

        # johnsdomain.com
        [email protected]            jsmith
        [email protected]            [email protected]
        [email protected]           [email protected]
        [email protected]       [email protected]
        [email protected]         [email protected]
        [email protected]             jsmith
        @johnsdomain.com                jsmith
        # bobsdomain.com
        [email protected]              bjones
        [email protected]             jacko
        [email protected]            [email protected]
        [email protected]        [email protected]
        [email protected]          [email protected]
        [email protected]              bjones
        @bobsdomain.com                 bjones

The above example shows how you can use the same username part of an email address (sales, webmaster, support, etc.) for multiple domains hosted on the same machine. In the example, any mail sent to [email protected] gets mapped to [email protected], while any mail sent to [email protected] gets mapped to [email protected]. The same goes for the webmaster, support, and ceo email addresses as well.

One thing of note, is that if you have a local user, mike for example, and there is no key for [email protected] and no catch-all key for @somedomain.com, sendmail will fall back to the local user mike when resolving [email protected]. To prevent this, either use a catch-all key or a key for [email protected] in the virtusertable.

Also, if you want a virtual address to resolve to more than one real address, you need to do it indirectly. Set the virtual address to resolve to a local alias, and then have the alias resolve to the set of addresses. For example, in your virtusertable:

        [email protected]             support

and in your /etc/aliases file:

        support:        [email protected], [email protected]

Remember to run the newaliases command after making changes to /etc/aliases.

Building the virtual user table

The next step is to actually build the virtusertable. To do so, run the following command:

        makemap hash /etc/mail/virtusertable < /etc/mail/virtusertable

Restart sendmail

The final step is to restart sendmail. You can do so a few different ways, I usually just do the following:

        # killall -HUP sendmail

After restarting it, make sure that sendmail restarted without errors. To see if sendmail is running:

        # ps auxw |grep sendmail

If it doesn't show up as running, then it didn't restart. If that's the case, check your maillog to see what happened:

        # tail -f /var/log/maillog

Correct any errors you find in the log, and restart sendmail:

        # /usr/sbin/sendmail -bd -q15m

Note that you do not need to restart sendmail if you're only changing the virtual user table. You only need to restart it if you modify sendmail.cf.

Good luck,

- Jim

Return to Issue #4

Contact: <>
Last modified: $Date: 1999/06/26 05:33:25 $
Copyright � 2023, The FreeBSD 'zine
All rights reserved.