From Wiki99

↑ Computers ↑
← prev: Apache next: Backup Hardware →

---

Contents 1 Introduction 2 Download and Preliminaries 3 Create the Directories Used by SquirrelMail 4 Configure SquirrelMail 5 Launch SquirrelMail and See if it Works 6 Upgrading SquirrelMail 7 Adding security 7.1 Copy the .pem file 7.2 Tell apache to use SSL 7.3 Test 7.4 Force squirrelmail to only use HTTPS

Introduction

Once you have your mail system working well, receiving mail, sending mail, displaying mail in Mail.app, you may want to extend the system to display mail via a web interface. This can be useful if you find yourself in situations where you don't have access to your copy of Mail.app, for example when you are using a friend's computer or a computer at a library.

There appear to be two main choices for webmail on MacOS X, namely OpenWebMail and SquirrelMail. Apple has chosen SquirrelMail for OSX server, so we can presumably trust it to work pretty well with OS X, so that's what we will use.

Download and Preliminaries

The first thing we need to do is download the application. Go to http://www.squirrelmail.org/download.php, and choose your download. You probably want the stable version. The three files listed are compressed in different ways, but you probably want to download the .bz2 file which is the smallest one. You can ignore the md5 links. A page will come up asking which server to download from and after a brief period the download will be on your desktop and decompressed. At this point you have a folder named something like squirrelmail-1.4.2 on your desktop and you have to install it.

There is a document called INSTALL in this folder, and you may want to read it, but it's probably easier to follow my instructions because the INSTALL instructions are generic to a variety of platforms, mine are MacOSX specific.

Step 1 would be to make sure that the web server understands PHP, the language used by SquirrelMail. We've already done that.

Step 2 would be setting up imap, and we've already done that.

Create the Directories Used by SquirrelMail

For step 3 we need to create two directories for SquirrelMail. The install docs are so vague in their suggestions as to how to name these are where to put them that they are close to useless. Here are some concrete suggestions.

First we create a directory that will hold the SquirrelMail data for all users, along with various other config stuff, and we set it to be owned by the web server so no-one else can write into it. Type

sudo mkdir /Library/Preferences/SquirrelMail_data
sudo chown -R www /Library/Preferences/SquirrelMail_data
sudo chgrp -R www /Library/Preferences/SquirrelMail_data

Next we need to create a directory that holds large attachments while they are in the process of being fed out over the network. This this is a spooling sort of operation, we'll place it in /var/spool, so type

sudo mkdir /var/spool/SquirrelMail_OutgoingAttachments
sudo chown -R www /var/spool/SquirrelMail_OutgoingAttachments
sudo chgrp -R www /var/spool/SquirrelMail_OutgoingAttachments
sudo chmod 730 /var/spool/SquirrelMail_OutgoingAttachments

Configure SquirrelMail

Step 4 is now to configure SquirrelMail. Type

or whatever is appropriate for your downloaded and decompressed squirrelmail directory. Type

and a simple text-based program will come up to allow you to configure your SquirrelMail. At this stage you probably don't really know what changes you want to make, so it's best just to make the essential changes. Later on you can run this program again, or modify the file that this program generates directly in a text editor.

So what are the essential changes?

• Type 2 to change Server Settings and then
  • 1 to set your domain name, eg bluecloud.com,
  • then type r to return to the main menu.
• Type 3 for Folder Options and then
  • 3 to change Trash folder from INBOX.Trash to INBOX/Trash
  • 4 to set Sent Folder from INBOX.Sent to INBOX/Sent Messages
  • 5 to set Drafts from INBOX.Drafts to INBOX/Drafts
  • then type r to return to the main menu.
• Type 4 for General options and then
  • 1 to set Data Directory to /Library/Preferences/SquirrelMail_data
  • 2 to set Attachment Directory to /var/spool/SquirrelMail_OutgoingAttachments
  • then type r to return to the main menu.
• Now type s to save the configuration, then q to quit.

Finally we have to move the squirrelmail folder to somewhere where Apache can see it. Type

Launch SquirrelMail and See if it Works

You should now be set. Open your web browser and type in

You should get a login window. Type your name and password. The webmail page should come up, your mail on the right, your mail folders on the left.

I personally find the default display of SquirrelMail pretty ugly, so I right away go to the Options Link, choose the Display Preferences link, and set

• the Custom Stylesheet to sans-10 and
• Enable Alternating Row Colors to No.

After making these choices, scroll to the bottom of the page and hit Submit, then click the INBOX link on the left to see the new look.

At this point you should be good. You now have webmail access to you imap server. When you are not logged into the server, you will, of course, not type the URL localhost/squirrelmail to access your webmail, but instead your domain name, for example www.bluecloud.com/squirrelmail.

Your domain name is actually bluecloud.com, and if you use bluecloud.com/squirrelmail that will also work. The reason www.bluecloud.com works is that EasyDNS by default sets things up so that any traffic to www.bluecloud.com goes directly to bluecloud.com. This is a convenience they provide because most people, even if they remember your URL as bluecloud.com, will probably type it as www.bluecloud.com just out of habit.

Upgrading SquirrelMail

You want to get into the habit of visiting http://www.squirrelmail.org at least once a month to see if the code has been updated. When an update occurs, naturally you want to upgrade with the least amount of pain.

For all my web applications, I use a few conventions to make my life easier.

First I retain a copy of the original source that I used to create the web application, eg squirrelmail-1.4.2.tar.bz2. I store this in the web application folder itself on the server so that I don't lose it. The point of this is that if I ever get confused about what changes I made to the web application, I can expand that source archive and diff my entire web app folder against the source to see exactly what I changed.

Next I create a folder in each web app named  !My Changed Files and in this I store an alias to every file in the web app that I change (or that is changed for me). You can get a list of these files by, as I said in the previous paragraph, doing a folder diff of your version of the web app folder against the original source.

In the case of SquirrelMail, the app preferences are stored in squirrelmail/config/config.php, so you want to create an alias to that file in squirrelmail/!My Changed Files. Unless you're doing something strange, you probably won't modify any other SquirrelMail file.

Now when it's time to upgrade you want to do something like this:

1. Move the squirrelmail-1.4.3.tar.bz2 source file into the unpacked squirrelmail-1.4.3 folder

2. Move the new squirrelmail-1.4.3 folder to /Library/WebServer/Documents

3. Look in /Library/WebServer/Documents/squirrelmail/!My Changed Files, and for each file you see, resolve the alias, and copy the file the alias points to to the corresponding position in /Library/WebServer/Documents/squirrelmail-1.4.3

4. Create folder /Library/WebServer/Documents/squirrelmail-1.4.3/!My Changed Files and create new aliases in it of all the files you copied over in the previous step

5. Rename /Library/WebServer/Documents/squirrelmail to /Library/WebServer/Documents/squirrelmail~

6. Rename /Library/WebServer/Documents/squirrelmail-1.4.3 to /Library/WebServer/Documents/squirrelmail

(It is a common convention in UNIX to name backup files by adding a ~ to the end of the file name, as we did above. If you don't like this, you can do whatever you like, eg add a suffix of .bak.)

(If you are working with the command line, you may wonder how you type a directory name like  !My Changed Files. You can change the name to something you know how to type if you like, or you can use tab-completion. In the command line type cd /L then the tab key, and the bash shell will fill in L to Library. Continue to type /W tab, and bash will fill in W to WebServer and so on. When you're at /Library/WebServer/Documents/squirrelmail/! the tab will fill in the name as \!My\ Changed\ Files/ with all the problematic characters escaped so the shell can handle them.

Most people type in two characters or so of a directory or file name when using tab completion because when using just a single name you might have two files or directories that both begin with that name. When bash cannot find a unique completion for a name, it will beep. If you tab again, it will list the various possible file or directory names that begin with the letters you've typed so far and you can see what more you need to type.

A second way of getting a problematic file or directory name into the shell is to find the file or folder in the finder and drag-and-drop it into the shell. The full path name, escaped so the shell can understand it, will be dumped on the command line.)

If everything went well, you should now be able to type in the URL you use for mail, for example www.bluecloud.com/squirrelmail and everything should work just like before. If you've followed what I said, you obviously have everything you need if anything goes wrong. You have both the original source, the new source, and, in squirrelmail~, the old, working, version of the web application. In the worst case scenario, you can simply throw away the new version of squirrelmail and rename squirrelmail~ back to squirrelmail.

If a major upgrade is involved (eg instead of 1.4.2 to 1.4.3, this is an upgrade to say 1.5 or even 2.0), you should read what the developers have to say about upgrading. The basic idea will remain what I have just given you, but there may be some extra step you need to perform to configure things for whatever new features the new software version adds.

Adding security

We now have to confront the same old stupid problem that we have encountered at every stage of setting up mail --- idiotically designed protocols that by default send passwords over the network in cleartext. If we want the password sent to squirrelmail to be encrypted, along with the mail traffic, we have to do something.

Since this is a project involving the web browser, the solution, as you'd expect, involves using SSL. Fortunately, given all the work we've already done setting up SSL for binc, getting apache to use SSL is pretty easy.

Copy the .pem file

We can use the same .pem file (with the non-encrypted password added to it) that we used for binc, and doing this is definitely easiest in terms of configuration.
So first of all, let's get that file to where apache can read it:

Tell apache to use SSL

Now we have to modify the apache config file to tell it to use SSL on port 443. First open the apache config file for editing:

scroll down five or six pages to the line

and uncomment the line by removing the # character at the start of the line. Scroll down another page or so to the line

And again uncomment it by removing the leading # character. These steps tell apache to load the SSL code when it starts up.

Next scroll all the way to the bottom, and add the lines

<IfModule mod_ssl.c>
    Listen 443
    Listen 80
</IfModule>
<VirtualHost _default_:443>
     <IfModule mod_ssl.c>
        SSLEngine on
        SSLCertificateFile /etc/httpd/apache.pem
        SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
     </IfModule>
</VirtualHost>

The first few lines here state that if SSL is active, apache should listen on both ports 80 and 443. (Normally it listens only on port 80.) The next few lines tell apache how to handle requests that come in on port 443. Pretty obviously they tell the program to use SSL and where the certificate file is. The SetEnvIf stuff is, big surprise, to work around bugs in Internet Explorer which apparently still persist in IE 6; I don't know about IE 7.

Test

Save your changes and restart apache:

You will also, if you are using any sort of NAT as most of us are, need to tell your NAT box (eg an Airport base station) to route incoming requests on port 443 to your server's local network IP address and port 443, as we discussed much earlier when discussing IP addressing and NAT.

With this done, secure HTTP is now set up on your machine. You can test it by going to a client machine and entering the URL https:bluecloud.com/squirrelmail.

Force squirrelmail to only use HTTPS

But this is not completely satisfactory. If you enter the full URL, including the https part, you will get an SSL connection. But if, like most people, you simply enter bluecloud.com/squirrelmail you will get a non-secure HTTP connection.

To get around this, once again open httpd.conf for editing, scroll to the bottom and add the following lines:

<Directory "/Library/WebServer/Documents/squirrelmail">
<IfModule mod_rewrite.c>
        RewriteEngine On
        RewriteCond %{SERVER_PORT}      !^443$
        RewriteRule ^(.*)$      https://%{SERVER_NAME}/squirrelmail/ [L,R=303]
</IfModule>
</Directory>

What these lines do is modify any URL that tries to connect to squirrelmail using a port that is not port 443 to an https URL.

Once again you can test this --- now enter a simple bluecloud.com/squirrelmail URL in your browser and you'll see that it automatically gets changed to an https URL.

---

← prev: Apache next: Backup Hardware →