Installing Squirrelmail - A Beginner's Guide

by Terry Allen

There are a vast variety of ways & means to access email & for server admins these days, one of the most common tasks you might be asked is how users can access their email using the web. Fortunately, for Mac OSX users, the operating system is based on *nix & for iTools users this means that there are a vast array of packages to use for webmail.

After looking around at the plethora of different webmail solutions, I found that a good many of them used SQL databases etc..., whereas I wanted a standalone system which did not require any additional components, making for easier troubleshooting if things go wrong. for my purposes, Squirrelmail fitted the bill perfectly.

It must be a good package as Apple have added Squirrelmail in as part of the default installation on Mac OSX Server, but users of Mac OSX 'client' should have not trouble getting it up & running on their machines. One thing that Squirrelmail does require is having your webserver PHP enabled, but this is not at all difficult for iTools users as Tenon have a prebuilt package available for installation, making it pretty much a point & click excercise.

Once you have PHP enabled, the process is relatively painless & can be done almost entirely in the terminal, leaving you to use a browser for testing purposes. you do need to bear in mind here that I'm installing on a fairly standard iTools installation, which encompasses Postfix for mail serving needs, so if you're running some other mail server such as Post.Office from Tenon, you'll need to experiment a little. Also, I'm assuming that your mail server is running on the same machine as your webserver - if not, there will need to be some port options changed along the way, but the basic installation is pretty much the same.

So, head on over to the Squirrelmail website at www.squirrelmail.org & download the latest version (at the time of writing, the latest version was 1.4.2). While you're there, be sure to check out anything you might need to read up on, but the read-me file contained in the download is pretty self explanatory & I'll cover a couple of problems later on. I always try to pick the source 'tarball' for these things, so look for the link that ends in .tar.gz (i.e. squirrelmail-1.4.2.tar.gz)

Once you have the file, transfer it into the directory you want to install your Squirrelmail into by issuing the following command in the terminal (I'm logged in as the root user - you might want to run under a sudo user in case of error):

root# cp squirrelmail-1.4.2.tar.gz /library/tenon/webserver/websites/yourdomain.com/squirrelmail-1.4.2.tar.gz

Now you'll need to expand the 'tarball' by again at the command line issuing this command:

root# tar zxvf squirrelmail-1.4.2.tar.gz

After a few seconds, if you do a directory listing, you should see all the normal files you have in your web directory, plus the Squirrelmail tarball & the directory which it's now been expanded into:

root# ls -l

drwxr-sr-x 25 root 1000 850 2 Oct 06:12 squirrelmail-1.4.2
-rw-r--r-- 1 root www 2873562 11 Jan 19:28 squirrelmail-1.4.2.tar.gz

Now, navigate into your Squirrelmail directory like so:

root# cd squirrelmail-1.4.2

Navigate next into the config directory:

root# cd config

Squirrelmail can be set up one of 2 ways - the manual file edit or the automated Perl script option. No surprises here, we're taking the automated option as it rewrites all the configuration files for you, so again in the terminal, we need to now run the Perl script:

root# ./conf.pl

It'll give you a nice little bunch of menus which you can change various options to suit your own individual server setup, but for the moment, we only need to change a couple of things to have us up & running in fairly short order. the menu looks like this:

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 (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 >>

The first thing you'll want to change is under the Server Settings option - your domain name is the first option in the menu, so enter 2, then enter, then enter 1, then enter again & you should now see this:

Command >> 1

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

[example.com]:

Fill in your domain name & hit enter, the menu should now show the change you just made:

General
-------
1. Domain : mydomain.com
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

Command >>

Save your changes by hitting S then enter & return to the main menu by hitting R then enter again.

One other change which needs to be made is to set the appropriate IMAP server type in the Squirrelmail settings, so, from the main menu, choose option D, which'll give you a screen like this:

SquirrelMail Configuration : Read: config_default.php
---------------------------------------------------------
While we have been building SquirrelMail, we have discovered some
preferences that work better with some servers that don't work so
well with others. If you select your IMAP server, this option will
set some pre-defined settings for that server.

Please note that you will still need to go through and make sure
everything is correct. This does not change everything. There are
only a few settings that this will change.

Please select your IMAP server:
cyrus = Cyrus IMAP server
uw = University of Washington's IMAP server
exchange = Microsoft Exchange IMAP server
courier = Courier IMAP server
macosx = Mac OS X Mailserver
quit = Do not change anything
Command >>

For our purposes, running Postfix & the standard Tenon IMAPOP3d package, we just need to select uw - once done, Save your data from the main menu & quit back to the command line.

One last change before testing is to make change the ownership & permissions of the data directory. for security reasons, it's advised to move this directory out of the web server directories, but for the purposes of this tutorial, we'll leave it alone. Navigate back up one directory level to the main squirrelmail installation like this:

root# cd ..

Now, to change the ownership of the directory & it's contents, we need to issue this command:

root# chown -R www data

the reason for this is that we only want the webserver's user to be able to read & write to the directory - next, change the permissions as follows:

root# chmod 730 data

Now, we should be all set to go, so load up a web browser & enter the URL for your Squirrelmail installation - i.e. it should be something like: http://www.yourdomain.com/squirrelmail-1.4.2

All being well, you should be presented with a login screen like this:

Now try logging in with a valid mail user (i.e. your own should be a good start) & you should then be able to see a fairly good looking mail screen like this one:

Assuming it all worked, you should now be able to read any email which happens to be in your inbox, change appearance options, send & recieve email as you'd expect & you're all done, so good work, now you can go back & do some reading to modify your Squirrelmail to suit your needs, such as defining a place for attachments etc...

One problem I encountered during a much older Squirrelmail installation was that the php.ini file needed to have a setting called register_globals changed from OFF to be ON. This caused a login error, but as I didn't strike the error this time, perhaps it's been modified now to suit newer security arrangements. Possibly the only other problem may be that you need to define a different IMAP server type to suit your particular mail server. Other errors are well covered on the Squirrelmail website if you encounter any.

Enjoy your new installation & have fun modifying it or making a new theme to better suit your website.

Terry Allen runs the current version of Tenon's iTools along with a variety of different software & scripts. You can visit some of his sites at http://heard.com.au or http://itavservices.com