September 9, 2008

How to build a local IMAP server

Author: Keith Fieldhouse

The usual practice of configuring your email client to retrieve email from your ISP's servers works well, but not for all situations. Suppose you add a laptop as a compliment to your desktop machine, or you'd occasionally like to use your spouse's computer to read your email -- you can run into problems trying to keep all of your email clients in sync. You can use IMAP (Internet Mail Access Protocol) instead of POP3 (Post Office Protocol), but then you need to store all of your email on your ISP's servers indefinitely, which has its own drawbacks. Here's a way you can set up a single machine on your own network to fetch and store your email and serve it to any number of email clients.

We're not talking about setting up a full-blown Internet email server. A "real" Internet mail server is public server identified as the mail host for a particular domain. When other servers have email for that domain they contact the mail server and hand off the email. The mail server then distributes that email to the appropriate users. We'll leave the responsibility of securely managing a public email server to our ISP and configure our local email server to periodically retrieve our email from our ISP's servers. This way, our server does not need to be directly exposed to the Internet at all.

For our example, we'll use as a base a system running the latest version (Hardy Heron) of Ubuntu Server, but the principles and software described here are applicable to any Linux distribution.

The install of Ubuntu Server can, for the most part, follow the defaults. When you get to the Software Selection screen, select Mail Server to install some of the email software you'll require automatically -- in particular, Postfix, a program that handles the distribution of mail on the server. Because you selected Mail Server you'll be asked additional configuration questions as the installation proceeds. In particular, you'll be asked to enter a fully qualified domain name (FQDN) to be used in the event an email address doesn't have a domain name associated with it. This won't used in this configuration; you can enter the domain name of your most often used email address.

You'll also be asked to enter an SMTP (Simple Mail Transport Protocol) relay host. For now, enter the SMTP host that you use in your regular email client -- typically a server on your ISP's network.

If you're using another Linux distribution to build this server, just make sure that mail server software is installed. Postfix, qmail, or even sendmail would all work equally well in the configuration described here.

Fetching the mail

Since we're not connecting this server directly to the Internet and not being contacted directly by other mail servers, we'll need some way to obtain our email. Fetchmail is designed for just this purpose.

Fetchmail functions in two parts. One acts like an email client, retrieving email for specific accounts using the POP3 or IMAP protocol. Rather than storing these messages and displaying them, as an email client like Thunderbird would, the second part of Fetchmail takes over. It connects to the MTA (Mail Transport Agent) on the server and provides it with email messages, just as if the server had been contacted by an external mail server with messages. Then the local mail handling machinery on the server takes over.

Fetchmail is not installed by default on Ubuntu Server, but you can install it easily using sudo apt-get install fetchmail. To configure the software, you must enter the email addresses that you plan to "fetch" and the users that mail is for. If you're going to serve email to more than the one user you created, you should create the other accounts on the server now with the adduser command. Users' email addresses and their account names don't have to match (although that may help keep them organized). The usernames and passwords that you create at this time will be the ones that you use when you configure email clients later.

Fetchmail has a built-in "daemon" mode where it runs in the background and periodically checks for messages as specified in a configuration file. On Ubuntu Server you can arrange for Fetchmail to be started at boot time by editing the file /etc/default/fetchmail and changing the line that reads START_DAEMON=no to read START_DAEMON=yes.

To test the configuration before installing it, create a file named fetchmailrc in a convenient working directory and populate it with lines for each user:

poll proto pop3 user saul with password competent is saul here
poll proto pop3 user fred with password stolid is fred here
poll proto pop3 user orrie with password slick is orrie here

Fetchmail's configuration language is chatty but fairly easy to read. The lines above poll using the POP3 protocol to fetch the mail for the users saul, fred, and orrie on the remote server and place that mail in the inboxes for the corresponding users on our local mail server. It would have been just as valid to fetch mail from saul, fred, and orrie on the remote server and place all of that email into a single user's inbox on the local machine. The poll commands shown are fairly generic. The fetchmail documentation details a large number of additional options. One of the most common would be to add options ssl in order to use SSL for those servers (such as Gmail's POP server) that require or provide it.

To test your fetchmailrc configuration, run the command fetchmail -v -f fetchmailrc. This will run Fetchmail against your configuration file and print out a lot of information about how things are proceeding, including whether there are any problems. When you are satisfied with the way things are going, install the fetchmailrc file to /etc/fetchmailrc and start the Fetchmail daemon by issuing the command sudo /etc/inid.d/fetcmail start.

Serving the mail

Once you've retrieved the mail onto the server, you need to provide access to it. We'll do that using the Dovecot email server and the IMAP protocol. Dovecot is easy to configure, and is pre-installed when when you choose Mail Server during the Ubuntu installation. If you don't already have it on your server box, you can easily install it from your distributions package repository.

We only need to make one configuration change to the default Dovecot installation. Edit the file /etc/dovecot/dovecot.conf and find the section that describes the mail_location variable. Add a line to the file that reads:


This tells Dovecot several things. First, mail will be stored in mbox format (a venerable and straightforward mail storage format). Second, the directory Mail in the account's home directory should be used to hold any IMAP folders the user creates with an email client. Finally, incoming mail is kept in an mbox file named after the user's account (%u) name in the /var/mail directory.

Once you've made this change, restart the Dovecot server with the command /etc/init.d/dovecot restart.

At this point you should have functioning mail server. To test it, start your favorite email client, add an account, and configure it to point to your server. By default, Dovecot is configured to listen to external IP addresses only on port 993, which is assigned to IMAP + SSL (also known as IMAPS), so specify that protocol when configuring your client. Use one of the accounts and passwords that you created on the server.

Processing the mail

Once you have connected your client to the Dovecot server, you may decide that you'd like to do some processing of the incoming mail on the server rather than in the client. This insures that such processing is done regardless of which client you happen to be connecting with.

You can do a lot of server-side processing with a program called procmail. Procmail has a pattern-based configuration language that allows you to process incoming email in just about any way you can imagine. As an example, we'll use procmail to filter out spam using another program called SpamAssassin.

The default server installation doesn't install SpamAssassin, but you can install it with apt-get. To activate it, copy the file /usr/share/doc/spamassassin/procmail.example to ~/.procmailrc for each of the users for which you want to run the filter. After you've copied the file, add the following line to the top of it:


With this setting, procmail changes to the directory specified so that further folder and file references are relative to that directory.

The supplied .procmailrc will move spam into two different folders, almost-certainly-spam and probably-spam, depending on how likely SpamAssassin considers it to be spam. You can add additional rules to the .procmailrc file to do other processing. For example, the following rule will move any mail that was sent to an address with "mail-list" in the "To:" field to the folder Mail-List in the Mail directory.

* O_mail-list

Procmail's configuration language is powerful and complex. The procmail homepage contains links to a variety of Web sites with examples of useful procmail "recipes."

That's all it takes to build your own local mail infrastructure. The server is powerful and flexible and capable of dealing with the email needs of small and medium-sized groups. Once set up, such a server requires little maintenance beyond making sure that /var/mail and the individual users' ~/Mail directories are appropriately backed up. Each of the components we used is time-tested and configurable enough to be adaptable to an organization's specific requirements. With a little effort up front, you'll have an email system that will serve your needs for a long time.


  • Mail & Messaging
Click Here!