Migrating from Sendmail to qmail

< Free Open Study >

If you've got an existing Sendmail installation with active users, upgrading to qmail with minimal impact to your users requires careful planning and execution. Although Sendmail and qmail are 100-percent compatible "on the wire," there are major differences in the way they work that are potentially visible to users and administrators.

The two major incompatibilities, from a user's perspective, are in the areas of delivery disposition via .forward/.qmail files and mailbox location/format. The difference in administration—beyond the initial setup—is primarily in the implementation of aliases.

Delivery Disposition

Sendmail uses $HOME/.forward to let the user tell Sendmail how to deliver messages. The .forward file, for example, is where a filter such as Procmail would be invoked. And, of course, it also allows messages be forwarded to another address.

qmail uses $HOME/.qmail, which is in a similar, but not completely compatible format.

The dot-forward package (http://cr.yp.to/dot-forward.html) allows qmail to deliver through .forward files.

Installing dot-forward

To install the dot-forward package, follow these steps:

Download the source tarball using your Web browser or a command-line Web utility. At the time of this writing, version 0.71 is the current release. For example, using the wget utility, do this:

 $ wget http://cr.yp.to/software/dot-forward-0.71.tar.gz —13:56:03— http://cr.yp.to/software/dot-forward-0.71.tar.gz            => 'dot-forward-0.71.tar.gz' Connecting to cr.yp.to:80. . . connected! HTTP request sent, awaiting response. . . 200 OK Length: 26,352 [application/x-gzip]     0K -> . . .. . .. . .. . . .. . .. . .. . . ... [100%] 13:56:21 (1.78 KB/s) - 'dot-forward-0.71.tar.gz' saved [26352/26352] $

Unpack the tarball:

 $ zcat dot-forward-0.71.tar.gz | tar xf - $

Build and install dot-forward:

 $ su Password: rootpassword # cd dot-forward-0.71 # make setup check (cat warn-auto.sh; \ echo CC=\''head -1 conf-cc'\'; \ echo LD=\''head -1 conf-ld'\' \ ...lots of output, ending with something like: ./load instcheck hier.o auto_qmail.o strerr.a substdio.a \ error.a str.a ./instcheck #

Configure dot-forward to be run by default for all users. This is accomplished by setting the defaultdelivery argument to qmail-start to something that delivers messages to dot-forward. The /var/qmail/boot directory includes several example /var/qmail/rc scripts that use dot-forward, which you might want to look at. If you followed the installation instructions in Chapter 2, though, your /var/qmail/rc script reads defaultdelivery from the defaultdelivery control file, which probably looks something like this:
```
 ./Maildir/ 
```

To invoke dot-forward, edit /var/qmail/control/defaultdelivery and add a new line at the top of the file containing this:

 |dot-forward .forward

The result should look something like this:

 |dot-forward .forward ./Maildir/

Then restart qmail:

 # qmailctl restart Restarting qmail: * Stopping qmail-smtpd. * Sending qmail-send SIGTERM and restarting. * Restarting qmail-smtpd. #

In the "Mailbox Location and Format" section, you'll probably be modifying the second line of defaultdelivery, so you might want to save the restart until then.

Compatibility Issues

dot-forward handles the most frequently used .forward constructs: delivery to programs, forwarding to addresses, and comments, but it doesn't support delivery to files or the :include: mechanism. Both of these cases can be handled using extension addresses and .qmail files. For example, if a user's .forward file contains this:

 :include: addresses /home/maryjane/Mail/backup

It could be rewritten as this:

 maryjane-addresses maryjane-backup

where .qmail-addresses is a copy of the addresses file—assuming it contains a list of addresses, one per line, and .qmail-backup contains this:

 /home/maryjane/Mail/backup

Mailbox Location and Format

Most Sendmail installations use a separate Message Delivery Agent (MDA), /bin/mail or mail.local, to deliver mail to mailboxes stored in a central spool directory such as /var/spool/mail, /usr/spool/mail, or /var/mail. Most qmail installations use qmail's built-in MDA to deliver to mailboxes stored in the user's home directory. When migrating from Sendmail to qmail, you have the choice of configuring qmail to deliver the mail the same way Sendmail did or of switching to qmail's home directory storage. You also have the option of switching from the mbox-format mailboxes that /bin/mail and mail.local support to qmail's maildir mailbox format.

For minimum impact on users, it's probably best to retain the mailbox location and format used under Sendmail—at least initially. Once qmail is up and running and has proven to be performing as desired, you can plan a migration to maildir format or home directory delivery without potential confusion regarding Sendmail/qmail compatibility issues. You can even migrate in stages: first to home directory mailbox storage, then to maildir format—and you don't have to migrate all users at once, though that might be easier in the long run.

Delivering Mail Sendmail-Style

Sendmail doesn't include an MDA. It invokes a separate MDA as specified in its configuration file, sendmail.cf. On most systems, the MDA used is /bin/mail, though later versions of Berkeley Software Distribution (BSD) use /usr/libexec/mail.local.

To configure qmail to use one of these MDAs by default, modify the defaultdelivery parameter to qmail-start, which is usually invoked from /var/qmail/rc. If you installed qmail following the directions in Chapter 2, "Installing qmail," the defaultdelivery argument is set to the contents of /var/qmail/control/defaultdelivery.

The directory /var/qmail/boot contains example /var/qmail/rc scripts that invoke /bin/mail and mail.local.

For example, if your /var/qmail/control/defaultdelivery script contains this:

 |dot-forward .forward ./Mailbox

And you're on a System V-like system such as Linux, you'd change it to this:

 |dot-forward .forward |preline -f /bin/mail -r "${SENDER:-MAILER-DAEMON}" -d "$USER"

Note

/bin/mail is run by preline, so messages will include a Delivered-To header field documenting the recipient address and used for loop detection. The -f flag to preline prevents it from adding the mbox message prefix line starting with From, which /bin/mail will add.

Migrating to Home Directory Delivery

To switch to home directory mailbox storage in mbox format, you need to perform three tasks:

You need to move existing mailboxes to their owner's home directories.
You need to configure qmail to deliver to those mailboxes.
You need to reconfigure MUAs and mailbox servers to use the new location.

These changes should be coordinated with users to minimize confusion and complaints.

Moving Mailboxes to Home Directories

The first step is to shut down the MTA, whether it's Sendmail or qmail, so you don't have to worry about messages arriving during the move.

The next step is to move the existing mailboxes. If your mailboxes are stored in /var/spool/mail/username, and you want to move them to /home/username/Mailbox, you could do something like this:

 # cd /var/spool/mail # for i in *; do > mv $i ~$i/Mailbox > done #

This loops through each of the mailboxes and executes an mv command to move it to the new location.

Caution

You should create a shell or Perl script to do this more carefully—for example, to make sure that /home/username/Mailbox doesn't exist before you move the system mailbox there.

Configuring qmail to Deliver to Home Directory Mboxes

Once again, configuring qmail's default delivery instructions requires modifying the defaultdelivery argument to qmail-start and restarting qmail. If you've enabled dot-forward, you already know which file to edit, probably /var/qmail/control/defaultdelivery or /var/qmail/rc.

To cause qmail to deliver to $HOME/Mailbox, make sure that defaultdelivery contains ./Mailbox.

For example, if your defaultdelivery file contains this:

 |dot-forward .forward ./Maildir/

You would change the second line to this:

 |dot-forward .forward ./Mailbox

Note

Make sure you remove the trailing slash (/), or qmail-local will think that ./Mailbox/ is supposed to be a maildir, and deliveries will be deferred.

Finally, restart qmail to begin delivering to the new location.

Migrating to Maildir-Format Mailboxes

To switch to the maildir mailbox format, you need to perform several tasks:

Move existing mailboxes to their owner's home directories.
Convert mailboxes from mbox to maildir.
Configure qmail to deliver to those mailboxes.
Reconfigure MUAs and mailbox servers to reflect the format.

The first two steps can be combined into one.

Caution

Before changing the mailbox format, ensure that supported MUAs and mailbox servers support the new format.

Moving Mailboxes to Home Directories and Converting to Maildir Format

The first step is to shut down the MTA, whether it's Sendmail or qmail, so you don't have to worry about messages arriving during the move.

The second step is most easily accomplished using a script called convert- and-create, available from http://www.qmail.org/convert-and-create. This script not only moves existing mbox mailboxes to the owner's home directory and converts them to maildir format, it also creates empty maildir mailboxes for users who have no mail in the central spool directory. The last step is critical because qmail-local will defer deliveries to users whose maildir mailboxes don't exist.

Download and run convert-and-create:

 # wget http://www.qmail.org/convert-and-create —09:55:51—  http://www.qmail.org/convert-and-create             => 'convert-and-create' Connecting to www.qmail.org:80. . . connected! HTTP request sent, awaiting response. . . 200 OK Length: 1,884 [text/plain]     0K -> .                                                             [100%] 09:56:23 (162.93 B/s) - 'convert-and-create' saved [1884/1884] # chmod 750 convert-and-create # ./convert-and-create root warning: bin is 1, but /bin is owned by 0, skipping. warning: daemon is 2, but /sbin is owned by 0, skipping. warning: adm's home dir, /var/adm, doesn't exist (passwd: *), skipping. . . .additional output. . . jim suzanne janice #

Examine convert-and-create's output carefully to be sure that it did what you wanted. For example, the first line of output shows it created a mailbox for root, which qmail will never use. If it's empty, you should remove it. The other output warns about various system accounts and is normal.

Configuring qmail to Deliver to Home Directory Maildirs

To cause qmail to deliver to $HOME/Maildir/, make sure that defaultdelivery contains ./Maildir/.

For example, if your defaultdelivery file contains this:

 |dot-forward .forward ./Mailbox

You would change the second line to this:

 |dot-forward .forward ./Maildir/

Note

Make sure you include the trailing slash (/), or qmail-local will think that ./Maildir is supposed to be an mbox, and deliveries will be deferred.

Finally, restart qmail to begin delivering to the new location.

Aliases

Sendmail uses aliases stored in a database, typically /etc/aliases, which are usually converted to a machine-readable database for faster lookups, usually aliases.db or aliases.dir and aliases.pag.

qmail implements aliases via .qmail files in the home directory of the alias user or via the optional qmail-users mechanism if /var/qmail/users/cdb exists.

When migrating from Sendmail to qmail, you have two choices: convert the Sendmail aliases to qmail aliases or install the fastforward package, which implements Sendmail-style alias databases under qmail.

Converting Sendmail-Style Aliases to qmail-Style Aliases

Entries in /etc/aliases are in the format

 alias: expansion

where expansion is a comma-separated list of the following:

Forwarding address, for example: maryjane@isp.example.net
File delivery, for example: /usr/local/majordomo/incoming-log
Program delivery, for example: |/usr/local/bin/info-responder
File includes, for example: :include: /usr/local/mail/lists/users

Some of these might be enclosed in double quotes, especially program deliveries that contain spaces.

The general strategy for converting these to qmail aliases is

Create /var/qmail/alias/.qmail-alias.
Put each forwarding address, program delivery, and file delivery in the alias in the .qmail-alias file, converting to qmail format as necessary.
For each file included, create a new .qmail file in /var/qmail/alias with the contents of the include file and add a forwarding entry to .qmail-alias for the new file.

For example, say /etc/aliases contains this:

 1 root: erica, rachel 2 users: root, :include:/usr/local/etc/users 3 help: "|/usr/local/bin/autohelp", /usr/local/log/help-mail

For line 1, you would create /var/qmail/alias/.qmail-root containing this:

 &erica &rachel

For line 2, you could create /var/qmail/alias/.qmail-users containing this:

 &root &user-list

And create /var/qmail/alias/.qmail-user-list containing the contents of /usr/local/etc/users. Make sure that .qmail-user-list is in the proper format: one address per line, each address beginning with a letter, number, or ampersand (&).

For line 3, you could create /var/qmail/alias/.qmail-help containing this:

 |/usr/local/bin/autohelp /usr/local/log/help-mail

However, if the delivery to autohelp fails, qmail-local won't deliver a copy to help-mail. To make the deliveries independent, you should put the autohelp delivery into a separate .qmail file. So, /var/qmail/alias/.qmail-help would contain this:

 &help-autohelp /usr/local/log/help-mail

And /var/qmail/alias/.qmail-help-autohelp would contain this:

 |/usr/local/bin/autohelp

Using fastforward to Implement Sendmail-Style Aliases

fastforward is not included with the qmail source tarball. You'll have to download the fastforward source tarball, unpack it, build the binaries, install them, and configure qmail to use fastforward. To do this, follow these steps:

Download the source tarball using your Web browser or the wget utility. At the time of this writing, 0.51 is the current version of fastforward. For example, using wget:

 $ wget http://cr.yp.to/software/fastforward-0.51.tar.gz --11:49:15--  http://cr.yp.to/software/fastforward-0.51.tar.gz             => 'fastforward-0.51.tar.gz' Connecting to cr.yp.to:80. . . connected! HTTP request sent, awaiting response. . . 200 OK Length: 40,659 [application/x-gzip]      0K -> . . .. . .. . .. . . .. . .. . .. . . .. . .. . .. . . .. . .. . .               [100%] 11:49:40 (2.33 KB/s) - 'fastforward-0.51.tar.gz' saved [40659/40659] $

Unpack the tarball:

 $ zcat fastforward-0.51.tar.gz | tar xf - $

Build and install the binaries:

 $ cd fastforward-0.51 $ su  Password: rootpassword # make setup check (cat warn-auto.sh; \ echo CC=\''head -1 conf-cc'\'; \ echo LD=\''head -1 conf-ld'\' \ ...lots of output ending with something like: ./load instcheck hier.o auto_qmail.o strerr.a substdio.a \ error.a str.a ./instcheck #

Convert /etc/aliases to the machine-readable format that fastforward uses:
```
 # /var/qmail/bin/newaliases # 
```
This will create /etc/aliases.cdb.
Configure qmail to use fastforward. This is accomplished by invoking fastforward from /var/qmail/alias/.qmail-default, the .qmail file that catches all otherwise undeliverable mail. For example, if there is currently no .qmail-default file:
```
 # cd /var/qmail/alias # ls .qmail-default ls: .qmail-default: No such file or directory # echo "| fastforward -d /etc/aliases.cdb" > .qmail-default # 
```

That's it: Mail to all undeliverable local addresses will now be passed to fast-forward, which will attempt to deliver the mail via /etc/aliases before bouncing it as undeliverable.

Compatibility Issues

fastforward is not 100-percent Sendmail compatible. Making fastforward completely Sendmail-compatible would introduce some security problems. Other incompatibilities result from additional flexibility or functionality provided by fastforward. Others are just a result of the way fastforward works. All of these incompatibilities are documented in the newaliases and newinclude man pages. The incompatibilities most likely to impact a smooth migration from Sendmail to qmail are:

Aliases in /etc/aliases will not override valid mail users or their extension addresses. This is because fastforward is run from /var/qmail/alias/.qmail-default, which is only consulted for undeliverable addresses. The qmail-users mechanism can be used to override delivery to valid mail users. See Chapter 3, "Configuring qmail: The Basics," for more information on qmail-users.
File deliveries are not supported. File deliveries can and should be done through extension addresses and .qmail files specifying file delivery.
Sendmail's behavior with circular aliases depends on the version of Sendmail employed. fastforward's behavior is documented in the setforward man page.
Sendmail complains about duplicate aliases. fastforward silently uses the first one it finds.
fastforward doesn't handle backslashes (\) and quoting the same as Sendmail. fastforward's quoting is Request For Comments (RFC)-compliant, and Sendmail's backslash trick—where \user means "deliver to user's mailbox," not "forward to user"—isn't needed with qmail to prevent loops.
fastforward doesn't allow vertical bars (|) before double quotes (").
Sendmail skips deliveries to aliases containing missing or unreadable :include: files. fastforward defers such deliveries.
If an alias includes the same recipient both inside and outside of a mailing list, fastforward sends the message twice, once with each envelope sender. Sendmail sends the message once with an unpredictable envelope sender.
Sendmail reads include files directly. fastforward reads machine-readable versions of include files generated by newinclude.
fastforward include files cannot include file or program deliveries.

< Free Open Study >