SolutionBase: Set up Web-based e-mail quickly using SquirrelMail

A good alternative to a traditional client/server-based e-mail solution is to simply set up one that's Web-based. In this article, Jack Wallen shows how to configure Web-based e-mail quickly and easily using SquirrelMail.

SquirrelMail's tagline is "Webmail For Nuts". The way I see it, SquirrelMail is web-based email for those nutty about solid, free solutions for an often difficult-to-fill need. SquirrelMail is one of those packages all-too-often overlooked for one reason: it's free. This of course is the bane of a lot of open source software. Like many OSS tools, SquirrelMail seems to remain, however, in the background running like a champion on many an ISP. In this article, I'll show you what it is and how to get it up and running.

What's SquirrelMail?

The ISP I use for both personal sites and client sites uses SquirrelMail. That's where I first discovered this little gem of a mail system. SquirrelMail is a simple to set up, easy to use, reliable web front-end written in PHP that supports IMAP and SMTP protocols. SquirrelMail has a number of add-ons and a small list of requirements. SquirrelMail is also simple to install and easy to learn.

There are two requirements to meet for installing SquirrelMail:

  • Web server with PHP >= 4.1.2 installed.
  • Access to an IMAP server which supports IMAP 4 rev 1.

The OS is actually irrelevant. Your OS only needs to stably support PHP. So, in order to get SquirrelMail to install, you will have to install an IMAP server such as Dovecot (my IMAP server of choice) and PHP. I, of course, would suggest doing a full install of a Linux distro first, then installing Dovecot, followed by SquirrelMail.

The real instructions

I'm going to assume you've met all the requirements for SquirrelMail on your server. With that out of the way, you'll need to download the latest release of SquirrelMail. This file will look something like squirrelmail-1.4.10a.tar.gz.

The first thing to do is to move that file into your Web server document root. I am installing on an OpenSuSE 10.2, so the document root is located in /srv/www/htdocs/. Once you have moved the file, unpack it. If you downloaded the gzipped .tar file, the command would be tar xvzf squirrelmail-RELEASE-NUMBER.tar.gz.

This next trick will save your users a lot of typing. If you just use the directory as-is, your users will have to point their browsers to something like every time they want to check their e-mail. Instead, change the name of the directory. You can change the name of the directory to webmail if you like. Make it something your users can remember.

In Linux, a file gets renamed from the command line with the mv command. So rename the directory like so:

mv squirrelmail-1.4.10 webmail

and you're ready to continue.

Once you have renamed your directory, change into that directory and, as root, run the configure script. Note: If you are within the SquirrelMail directory, to run the configure script, use the command ./configure.

When you run the configure script, you're going to be presented with a few configuration options. The first option is the Main configuration menu:

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

D.   Set pre-defined settings for specific IMAP servers

C    Turn color on
S    Save data
Q    Quit

The first option I will select will be the Organizational Preferences. So, at the SquirrelMail command prompt, I will select:

Command >> 1

The new configuration menu looks like:

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Organization Preferences
1.   Organization Name       : SquirrelMail
2.   Organization Logo       : ../images/sm_logo.png
3.   Org. Logo Width/Height  : (308/111)
4.   Organization Title      : SquirrelMail $version
5.   Signout Page            :
6.   Top Frame               : _top
7.   Provider link           :
8.   Provider name           : SquirrelMail

R    Return to Main Menu
C    Turn color on
S    Save data
Q    Quit

As you can see, the first choice -- Organization Name -- is set as SquirrelMail. You will want to change this to reflect your client's company name. Select:

Command >>   1

You will then see a brief set of instructions telling you that if you change the Organization Title, new title will appear in most places where SquirrelMail would be named. One other very important bit of information regards names that begin with $. If your company title begins with the $ symbol, it would be treated as the beginning of a variable.

Fortunately, the SquirrelMail developers thought of this and allowed for the inclusion of a $ symbol in the name, but it must be preceded by a \ first. For example, if your company's name is $avings, you'll have to enter \$avings in order to use this as your Organization Title.

I'm going to use my company's name for this option.

[SquirrelMail]: TransLinux

Now we are back to the Organization Preferences menu.

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Organization Preferences
1.   Organization Name       : TransLinux
2.   Organization Logo       : ../images/sm_logo.png
3.   Org. Logo Width/Height  : (308/111)
4.   Organization Title      : SquirrelMail $version
5.   Signout Page            :
6.   Top Frame               : _top
7.   Provider link           :
8.   Provider name           : SquirrelMail

R    Return to Main Menu
C    Turn color on
S    Save data
Q    Quit

From this same sub-menu, you can configure your company's logo and a few other tidbits of information. Once you are finished with this screen, press [R] to return to the main Configuration window.

Of course, you will have to configure your server settings. To do this, press [2] to enter the Server Settings submenu.

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Server Settings

1.   Domain                  :
2.   Invert Time             : false
3.   Sendmail or SMTP        : SMTP

A.   Update IMAP Settings    : localhost:143 (other)
B.   Update SMTP Settings    : localhost:25

R    Return to Main Menu
C    Turn color on
S    Save data
Q    Quit

Now you need to set the Domain option. Select the 1 option, and you will be greeted with the following text:

The domain name is the suffix at the end of all email addresses.   If
for example, your email address is, then your domain
would be


where is the domain associated with your client.

The other options to configure are:

  • Invert Time: This option is to get around an IBM AIX/Solaris bug that always reads the time zone as positive. If are using either of those OSs, set this option to false.
  • Sendmail or SMTP: Set this to match outgoing mail system will you be using.
  • Update IMAP Settings: Configure your IMAP address and port.
  • Update SMTP Settings: Configure your SMTP address and port.

Once you have finished these configurations, press [R] to return to the main menu; press [S] to save your configurations. You will be greeted with this message upon saving:

Data saved in config.php
Press enter to continue...

You will then be taken back to the main menu. Press [Q] to quit, at which point you will see:

You might want to test your configuration by browsing to

Happy SquirrelMailing!

Before you open up the configtest.php file, you need to follow a few steps not outlined in the installation instructions. Create the following directories:


Then chmod -R 777 the /var/squirrelmail directory.

Fire up Firefox

The next step is to run the configtest.php file in your browser. The address in our example will be . When you open that page, you will see the following text:

SquirrelMail configtest
This script will try to check some aspects of your SquirrelMail configuration and point you to errors whereever it can find them. You need to go run in the config/ directory first before you run this script.

SquirrelMail version:


Config file version:


Config file last modified:

10 May 2007 14:55:15

Checking PHP configuration...
       PHP version 5.2.0 OK.
       PHP extensions OK.
Checking paths...
       Data dir OK.
       Attachment dir OK.
       Plugins are not enabled in config.
       Themes OK.
       Default language OK.
       Base URL detected as: http://linux-wsbm/squirrelmail/src (location base autodetected)
Checking outgoing mail service....
       SMTP server OK (220 ESMTP Postfix)
Checking IMAP service....
       IMAP server ready (* OK Dovecot ready.)
Checking internationalization (i18n) settings...
         gettext - Gettext functions are unavailable. SquirrelMail will use slower internal gettext functions.
         mbstring - Mbstring functions are unavailable. Japanese translation won't work.
         recode - Recode functions are unavailable.
         iconv - Iconv functions are available.
         timezone - Webmail users can change their time zone settings.
Checking database functions...
       not using database functionality.
Congratulations, your SquirrelMail setup looks fine to me!

Now that you know it's working fine, let's secure it up and log in. The first thing you will need to do is find out which user is running your Web server. If you're using Apache, you will find this information in the httpd.conf file under the variable called webusername. You need to do is change the ownership of the data directory to the webuser. If your webuser is apache, run the command:

chown -R apache data

from the /var/www/html/webmail directory. Note: Remember, the webmail directory is the squirrelmail-1.4.10 directory, renamed.

Now give the attachments directory over to root with the command chown -R root attachments. Finally, give the attachments directory write (but not read) permissions with this command:

chmod -R 730 attachments

Now you are ready to log in.

Logging in for the first time

Point your browser to to log in to your SquirrelMail server. The index file in that directory will actually point your browser to http://yourdomain/com/webmail/src/login.php but your users don't need to know that. Figure A illustrates the SquirrelMail login screen.

Figure A

A login screen so clean even a squirrel would find nothing to dig up.

Once you log in with your username/password, you will see the main window, the home of your e-mail (see Figure B).

Figure B

The SquirrelMail interface is as simple and user-friendly as it gets.

Further configurations

Now that you have the system up and running where do you go? Outside of revisiting the configuration script (which you should do anyway, to polish up your configuration), you will need to install a few plug-ins before you can do much more.

There are two administration plug-ins you should install. The first plug in you'll need to download is called admin_add. Download this file and then move it to the webmail/plugins directory. Note: I am not including the full path to the plug-ins directory and assuming the standard set in this article is where webmail is the SquirrelMail directory.

Once the plug-in is in the directory, unpack it. Create a file called admins and place it in the /webmail/config directory. In this file, you will place the name(s) of the users (one per line) that will be allowed access to the admin tool. After the last name place, type a few empty carriage returns and save the file.

Now you have to revisit the configure script. Change to the webmail directory and run ./configure again. Now that you're in the configuration menu, enter [8] for the plug-ins menu. You should now see a listing of plug-ins. All you have to do is enter the number for each plug-in to install. So look for the admin_add plug-in, enter the number for that, and press [Enter]. Now add the administrator plug-in in the same way.

Once you have those two plug-ins added, press [S] (to Save) and [Q] (to Quit).

Now log back into SquirrelMail with one of the users added to the admins file. Once logged in, select the Options link and you'll see some Administrator entries now available as seen in Figure C.

Figure C

Before adding the admin plug-ins, the only options available are those for the individual users' account.

The admin_add plug-in just allows those able to use it to add or remove administrators to the system. This is handy for dealing with this issue remotely (when an ssh connection is not available). The real administration takes place within the Administration plug-in. But ultimately what this plug-in does is act as a Web-based interface for the configuration script. As recommended in the Administration plug-in, it is best to use the configuration script because there is additional information to be given, but the plug-in is nice for those who don't like using text-based tools.

Final thoughts

SquirrelMail is one of the most reliable Web-based e-mail systems I've used. I know a lot of hosts that take advantage of this system, and with good reason: it's cost effective, reliable, simple, user-friendly, and cross platform. So if you have a need for a Web-based email system, give SquirrelMail a try. You'd be nuts if you don't try it.