HOWTO: Install and Configure qmail on Mandrake Linux

The qmail rpm mentioned on this page has not been built for Mandrake 10.0. This patch applies against the qmail .spec file from the 9.2 src.rpm.

Note, however, that you can use the 9.2 urpmi sources on a 10.0 system with no ill effects.

This document is intended as a guide to installing, configuring and getting you to the point of sending and receiving test email with a qmail server on Mandrake Linux. We will also go into some detail on setting up POP3 (using qmail-pop3d) access to mail boxes, IMAP access (using Courier IMAP) and a web-mail system using SquirrelMail.

I wrote this guide as I have been unable to find any documentation which guides the new qmail user through the complete installation and use of a qmail server, including remote access, without getting overly technical or requiring the user to read vast wads of documentation. This howto is not necessarily a replacement for the excellent "Life With qmail", by Dave Sill, but serves to get the user up and running as quickly as possible.

Parts of this howto are based on Using qmail with Mandrake Linux, by Vince Danen. Vince also maintains the RPMHelp.net qmail distribution, without which this howto would be useless.

No documentaion about qmail would be complete without giving kudos to its creater: D. J. Bernstein. The original qmail distribution can be obtained from here

First off, we need to install qmail. If you are a Mandrake Linux user, you will be familiar with its advanced RPM handling tool: urpmi. For simplicity, we shall add an urpmi source to make installation as painless as possible. In the following command, simply replace 'x.x' with your Mandrake version. (e.g. 9.2)

[root@wibble root]# urpmi.addmedia qmail http://rpmhelp.vmlinuz.ca/x.x/RPMS/ with ../base/hdlist.cz

We now install qmail like so:

[root@wibble root]# urpmi qmail

This will prompt you if it is ok to install qmail, daemontools, and ucspi-tcp. Say 'yes'. If you get a warning about "The following packages have bad signatures", you may wish to import this GPG key which is the key used to sign all RPMHelp.net packages. You can do this with the following command, as root:

[root@wibble root]# lynx -source http://rpmhelp.vmlinuz.ca/rpmhelp.asc | gpg --import

Once the install completes, you will be warned to change the default postmaster account from 'nobody'. We shall talk about this in a moment.

We now need to run a few commands to initialise qmail:

[root@wibble root]# service qmail cdb

[root@wibble root]# /etc/cron.hourly/qmail

These commands initialise the tcprules database (so that qmail will accept connections - see Part 2) and initialise qmail's internal user database.

We can now start qmail with the following command:

[root@wibble root]# service qmail start

If you take a look in /var/log/qmail/current (the main qmail log file), you will see an entry similar to the following:

@400000003e19c06a0ad70064 status: local 0/20 remote 0/90

The RPMHelp.net qmail packages are designed to self-configure themselves, based on your system hostname. This may not be suitable if you want to host a mail server for a real domain, rather than local unix mail. For the purpose of completeness, we will asume that our server has a hostname of wibble.banana.com, but that we want to be the mail server for just banana.com (so we handle mail for billy@banana.com).

If we take a look in /var/qmail/control, we will find all of qmail's config files.

[root@wibble control]# ls -l
total 44
-rw-r--r--    1 root     qmail          40 Dec  5 06:43 aliasempty
-rw-r--r--    1 root     qmail          91 Dec  5 06:43 blacklists
-rw-r--r--    1 root     qmail           3 Dec  5 06:43 concurrencyincoming
-rw-r--r--    1 root     qmail           3 Dec  5 06:43 concurrencylocal
-rw-r--r--    1 root     qmail           3 Dec  5 06:43 concurrencyremote
-rw-r--r--    1 root     qmail          10 Dec  5 06:43 defaultdelivery
-rw-r--r--    1 root     qmail          17 Dec 13 11:49 defaultdomain
-rw-r--r--    1 root     qmail          34 Dec 13 11:49 locals
-rw-r--r--    1 root     qmail          24 Dec 13 11:49 me
-rw-r--r--    1 root     qmail          12 Dec 13 11:49 plusdomain
-rw-r--r--    1 root     qmail          24 Dec 13 11:49 rcpthosts

Several of these files will contain 'wibble.banana.com' so we will need to change them to just 'banana.com'

[root@wibble control]# grep wibble *
defaultdomain:wibble.banana.com
locals:wibble.banana.com
me:wibble.banana.com
plusdomain:wibble.banana.com
rcpthosts:wibble.banana.com

All of the above files (defaultdomain, locals, me, plusdomain and rcpthosts) need to have 'wibble.banana.com' changed to 'banana.com'

We now need to restart qmail:

[root@wibble root]# service qmail restart

You should see something like the following in /var/log/qmail/current :

@400000003e19c0692156dbd4 status: exiting
@400000003e19c06a0ad70064 status: local 0/20 remote 0/90

One important point to note is that, while this is now a fully functional SMTP mail server, capable of sending and receiving internet email, we will be unable to receive email from the Internet unless our mail server is visible to the outside world. To do this, you need to have an MX (Mail eXchange) record put in your Internet DNS zone file so that other sites can find out where to send email destined for your domain to. NOTE: If you have a normal modem/IDSN/ADSL connection to the internet, your ISP is very unlikely to give you an MX record as part of the standard deal. People who have their own domain, and/or run their own DNS servers should be able to do this with little trouble.

Remember the qmail installer warned you to change the default postmaster account? We shall do this now.

Change directory to /var/qmail/alias :

[root@wibble alias]# ls -la
total 8
drwxr-sr-x    2 alias    qmail          75 Dec 13 17:04 ./
drwxr-xr-x   11 root     qmail         122 Dec 13 11:49 ../
lrwxr-xr-x    1 alias    nofiles        17 Dec 13 11:49 .qmail-mailer-daemon -> .qmail-postmaster
-rw-r--r--    1 alias    nofiles         7 Dec 13 11:50 .qmail-postmaster

qmail uses files starting .qmail (these are refered to as "dot-qmail-alias files") in order to decide where to send mail. Anything in the filename after the - is treated as the first part of an email address (the part before the @ ). If you want to have a full-stop in the address, you use a colon (:), so filenames look like this: .qmail-m:watts , which translates to m.watts@domain.

So, the .qmail-postmaster file tells qmail where to direct mail for postmaster@wibble.com. (This address is used by qmail as a valid address to use in its automated error emails when something goes wrong). Open .qmail-postmaster in your favourite text editor (vim) and change the &nobody to whatever user account you want postmaster mail to go to (root is a bad choice since qmail doesn't like keeping a mailbox for root. Use your own username if you can't think of a suitable user).

As an aside, you can create as many .qmail alias files as you want - they don't have to correspond to valid user accounts. This means you can have several email addresses pointing to the same system account. You can also put a proper internet email address in a .qmail alias file if you want to do mail forwarding for a particular account.

.qmail-root should also be created and set to a vaild system user (not root). Once you have done this, you will probably start receiving mail from the cron program. This is normal and often very useful, although you may wish to set your mail client to filter these messages to a different folder.

Currently, we have installed qmail and configured it to handle the mail for a particular domain. We now need to configure user accounts so that users can send and receive mail. If you create a new user with 'useradd fred', that user will already have a mail spool. They will also have the email address of fred@banana.com.

By default, the RPMHelp.net qmail packages are set to use a Maildir spool for storing a users email. It adds a Maildir to /etc/skel (the skeleton directory on which all new system user accounts are based) so that all new users will have a working mail spool. (A mail spool is the location where any new mail is put by qmail). The alternative to using a Maildir is to use a traditional Unix mbox file. The KDE email client, KMail, uses mbox files by default, so you may wish to use one for incomming mail, although it can work with Maildirs just fine. Since we are going to work through installing Courier IMAP and SquirrelMail, which both work better (or only, in the case of Courier IMAP) with Maildirs, we will stick with those.

The other file that qmail puts into /etc/skel is a .qmail file. This is used to say where to put a users mail. a .qmail file in a users home directory overrides one in /var/qmail/alias for the same user. As with /var/qmail/alias .qmail files, one in a users home directory can contain a real email address so a user can setup their own mail forwarding. For a default user, ~/.qmail looks like this:

[root@wibble skel]# cat .qmail
./Maildir/

For an mbox mail spool, it would look like this (assuming the mbox file is called ~/Mail/incomming)

[root@wibble skel]# cat .qmail
./Mail/incomming

As you can see, the trailing / is the differentiator between a Maildir (directory) and an mbox (file).

Any existing account will need a ~/.qmail file creating and either set to put mail in an mbox (for which a simple 'touch ~/incomming' will do) or set to use a Maildir. The program 'maildirmake' (/var/qmail/bin) is used to create a Maildir. This can either be done as the user account in question, or done as root with a 'chown -R user:user Maildir' performed afterwards.

At this point we have a working SMTP server, and we have setup some user accounts. Now would be a good time to send some test email to see whether qmail is working properly. Currently, you will only be able to send and receive email from the server - we will look at using the server from other machines (relaying) in Part 4.

In your favourite mail client, you should set it up so that it uses your new server. You want to setup an SMTP server for sending email, and setup a Maildir or an mbox spool for receiving new mail. Wherever it asks you for a servername, use 'localhost'. the default SMTP port (25) is fine. You should be able to send an email to an external mail account (a hotmail account for example). You should also (assuming your DNS is setup correctly) be able to receive email for fred@banana.com (assuming fred is a valid user account on your server, and you are handling mail for banana.com). Tailing /var/log/qmail/current should let you watch as mail goes in and out. If you see any errors, check that you have setup qmail as above.

If you have followed the above instructions, you should by now have a fully working SMTP email server, capable of handling local Unix email, as well as sending email to vaild Internet email addresses - for users on the server only. This is fine if all of your users will only ever be using that one box for all of their work. Indeed, many University institiutions do mail in this way - telnet and pine used to be a very popular combination. These days, retreiving email through the POP3 or IMAP protocols from a box other than the mail server is a far more common occurance. POP3 and IMAP are both popular ways of retreiving email from a remote server. IMAP is more advanced than POP3, in that it is capable of keeping all mail on the server, and supports server-side mail directories (inbox, sent-items etc). Both of these are easy to setup and we shall now install both for completeness.

Assuming you still have the qmail urpmi source we used above, you can simply do:

[root@wibble root]# urpmi qmail-pop3d

Again, you may get a warning about an invalid signature. Importing the RPMHelp.net GPG key from the link above will solve this.

Once qmail-pop3d is installed, you only need to execute 'service qmail restart' and you will have a working POP3 server. This can be tested by adding a POP3 server for receiving email to your mail client setup, and sending an email to yourself. Remember to disable your local Unix mail settings otherwise this will not be a true test!

Installing Courier IMAP requires that you have a 'contrib' urpmi source defined. If you don't have one, use the tool at this site to add one

[root@wibble root]# urpmi courier-imap

Followed by:

[root@wibble root]# service courier-imap start

Assuming all goes well, you will be able to see a bunch of processes running if you 'ps ax | grep courier'

Courier IMAP already works with qmail, so you should be able to receive mail using IMAP in the same way we did with POP3 earlier.

At this point, you should have a working IMAP server which will allow you to collect mail. For a lot of people, a natural progression is to add a webmail front-end. This has several advantages; users can use a consistant interface from anywhere in the world, and firewall administation is made much easier (you only need to open the firewall to the server on port 80, or 443 (https)).

SquirrelMail is another package that can be obtained from the contrib tree.

[root@wibble root]# urpmi squirrelmail

Once SquirrelMail is installed, you should be able to at least see the SquirrelMail login page by going to http://yourip/webmail. If you have a DocumentRoot other than /var/www/html, you will need to move the webmail directory.

As root, you now need to tell SquirrelMail that it is talking to a Courier IMAP server:

# /var/www/squirrelmail/config/conf.pl

You should be presented with a config screen like so:

	SquirrelMail Configuration : Read: config.php (1.2.0)
	---------------------------------------------------------
	Main Menu --
	1.  Organization Preferences
	2.  Server Settings
	3.  Folder Defaults
	4.  General Options
	5.  Themes
	6.  Address Books (LDAP)
	7.  Message of the Day (MOTD)
	8.  Plugins
	9.  Database

	D.  Set pre-defined settings for specific IMAP servers

	C.  Turn color on
	S   Save data
	Q   Quit

	Command >>

If you pick option 'D', you can then type in 'courier' to set SquirrelMail to use Courier IMAP. Explore the other options if you wish - you can change the text on the login screen, logos and other things from option 1. Using option 2, you will want to set your 'Domain', which is used to generate a users email address. You can also change the 'Sendmail/SMTP' and 'IMAP' server settings here. These can be used to allow SquirrelMail to sit on a different server to the mail server(s). Since qmail includes a drop-in replacement for the Sendmail binary, you can leave the defaults. If you want to put SquirrelMail on a different box to your new qmail server, you will want to use SMTP - the settings should be straight-forward.

You may also need to change the "Default Folder Prefix" to "INBOX"

You should now be able to login to SquirrelMail, using normal system user account information, and send and receive email!

One of the most common problems people come across when building qmail servers for LANs is that qmail defaults to closed relaying. This means that (out of the box) a qmail server will not handle mail that is not destined for an user on that server. This can cause all sorts of confusion when you setup a qmail server to handle mail for a domain yet other machines in that domain cannot send mail through it. (A mail relay is a server that will accept mail that does not originate from that server, and is not destined for a user on that server.)

By default, qmail does not accept mail unless the mail message has a receipt address ('rcpt to' in SMTP speak) of a user on the server. This means that you would be able to send a message to fred@banana.com from another machine on the LAN and send a message to bill@pinepple.com from the server, but not send a message to bill@pineapple.com from a machine on the LAN that is using the banana.com qmail server.

One solution would be to add every email domain that you expect to send email to, to the /var/qmail/control/rcpthosts config file. As you can imagine, that is not a workable solution for most (if not all) users. As a result of this, qmail uses a different method to allow relaying from authorised hosts.

qmail is called from another D. J. Bernstein program - tcpserver. This keeps a database of IP addresses which are allowed to relay through that server. Once a connection from one of these machines is made, tcpserver sets an environment variable which overrides the rcpthosts file for the duration of that connection.

In a default configuration, the tcpserver config file for qmail is held in /etc/tcpserver.d/qmail-smtp. The following is the default file:

[root@wibble tcprules.d]# cat qmail-smtp
127.:allow,RELAYCLIENT=""

If you wanted to allow the 192.168.100.0/24 subnet to use your qmail server for relaying, you would need to add a line like:

192.168.100.:allow,RELAYCLIENT=""

NB: the . after the 100 IS important.

After you've edited this file, you need to rebuild the tcpserver database:

[root@wibble root]# service qmail cdb

By now, you should be have a working qmail server which is allowing all of your servers on the LAN to use it for sending mail. You should also have POP3 and IMAP remote access, as well as a nice WebMail client for your users to use when they are away from the network.

None of the things I have mentioned in this howto are Rocket Science - I wrote this after an afternoons work on a server, learning how everything fits together. Hopefully it will save you an afternoon and you can have a beer instead :^).

If you have any problems with the steps I mention here, or you spot something that I've missed - please drop me a line at m.watts (at) eris.qinetiq.com