Nuts About SquirrelMail
Volume Number: 21 (2005)
Issue Number: 8
Column Tag: Programming
The Source Hound
Nuts About SquirrelMail
by Dean Shavit
alking into MacWorld Expo at the Moscone Center in San Francisco with an Exhibitor's badge the
day before the Expo opens is one of the strangest experiences to be had. There's the sound of duct
tape whizzing off of rolls, and the slap of mats falling into place, accompanied by the hum of
electrical equipment. It's a great chance to walk around and get acclimated to the lay of the land
before the crowds pile in.
Away from the Office
Sooner or later, though, the urge to check email hits, and then it becomes quite apparent that
even though the booths are partially set up, there's no open Airport networks available, and without
a password, no way to check email. But then, towards the back of Moscone, there's a few iMac G5s
setup for an "Internet cafe" and there's someone sitting there feverishly typing away. After testing
some of the other iMacs, it's obvious that the only one that works is the one he's using, and
sitting there politely isn't going to help, as if it were the last public phone on the planet (which
it is, sort of). What makes it even worse is that he's using SquirrelMail, and judging by the number
of folders and subfolders in the side bar, it's obvious that he's an email nutball, and that he's
never going to stop, since he's got access to everything he's every received, sent, and squirreled
away.
Every day I hear more and more instances of what I call the "great SMTP (Simple Mail Transfer
Protocol) lockdown," where ISPs such as Earthlink, Comcast, RCN and others are blocking all traffic
over TCP port 25, which means that it's become increasingly difficult to use a corporate email
account from home, without either setting up an alternate SMTP port or the ISP's own SMTP server.
Not too long ago, all a home broadband user had to do was use authenticated SMTP, but these days
even that's not a fait accompli. The ISPs claim to be blocking port 25 in the name of spam
prevention (and they usually do it without notifying their customers first), but it's pretty obvious
that they want to lock you into using their email servers and email addresses, which is the easiest
way they have of insuring that you won't switch to another ISP with a better deal or faster service.
My girlfriend, for example, switched to Covad DSL service over a year ago, yet still pays $14.95 a
month for Yahoo dial-up service, just so she can "save" her email address. It's a scam on a grand
scale--even if you're savvy enough to register your own domain name, and purchase email services or
even run your own email server, you might not be able to easily send mail via that account.
In these days of predatory if your broadband provider decides to block it. Where web browsing
speeds might be accelerating at a breakneck pace, but where sending email through any server except
for the ISP's is heavily deprecated, it's webmail that's becoming an absolutely critical service for
corporate email users when they're out of the office. After all, which ISP would dare to block TCP
port 80, through which all basic World Wide Web traffic travels? Although high-end groupware servers
like Microsoft Exchange and Lotus Notes have featured webmail since the mid 1990s, other entities
like Google are getting heavily into webmail services, taking advantage of their well-known brand
names and their ISP-independent status to lure email users to park their email addresses at the
gmail.com domain for the long term (with wickedly fast searches and two gigabytes of storage), so
that account holders may switch ISPs with impunity as they move from location to location or find
better deals on broadband, while being exposed to more and more of Google's pay-per-click ads, which
have now become both the ubiquitous marginalia and tip jars of web sites.
So, where once web-based email was the tool that was occasionally used to send and receive email
while away from the office when a corporate laptop wasn't available, it's now become a standard
arrow in the corporate quiver--often the lifeline of communication between remote email users and the
main office when standard email server is blocked, or when a VPN is too unwieldy or when corporate
IT help desk staffers want to draw a line in the sand when it comes to supporting their employees'
home networks.
Highly Trained Squirrels
Roald Dahl's Charlie and the Chocolate Factory featured a room full of specially trained
Squirrels that tested each nut that went into Wonka candy bars, then tossed out the bad nuts and
shelled the good. In the same vein, it seems that Apple's OS X Server Development team coveted
trained squirrels as well! The squirrels I'm speaking of are the hard-working rodents of the
SquirrelMail project, an open-source PHP (Pre HyperText Processor) script living at http://squirrelmail.sourceforge.net that leverages
the Apache web server to provide a powerful and extensible webmail service. The SquirrelMail team
describes the project as:
- . . . a standards-based webmail package written in PHP4. It includes built-in pure PHP
support for the IMAP and SMTP protocols, and all pages render in pure HTML 4.0 (with no JavaScript
required) for maximum compatibility across browsers. It has very few requirements and is very easy
to configure and install. SquirrelMail has all the functionality you would want from an email
client, including strong MIME support, address books, and folder manipulation.
From its inception, SquirrelMail was designed with the notion of "install once, access with any
browser, on any platform" in mind, which is a great compliment to the basic premise of web-based
email, where what operating system and web browser the user is running, and on what speed and type
of network (and with what ports blocked) makes little or no difference. Install SquirrelMail,
configure it, and then let the remote users do the rest themselves. It's a thing of beauty. Given
that Apache and PHP come pre-installed on nearly all UNIXy operating systems, it's no surprise that
SquirrelMail has become the darling of the Linux, BSD, and OS X worlds, and quite simply, one of the
most consistently popular projects at Sourceforge.net for a number of years, like Pink Floyd's "Dark
Side of the Moon," it's always hanging near the top of the charts.
Figure 1. Highly Trained
Squirrels Sort Your Mail for You
However, it seems that the OS X Server team wasn't exactly proud to employ the little varmint, so
they tried their best to hide the squirrel behind the scenes, a charade that's easily foiled by a
peek into the terminal (or just the OS X Server Web Services Documentation). Like many of the
open-source projects included with OS X Server, there's an amount of obfuscation to cover up the
origins of the goodies, at least at the GUI layer, but once logged into SquirrelMail, regardless of
whether the logo's an actual squirrel or postage stamp, there's no mistaking the interface!
Figure 2. "Squirrels?
What Squirrels?" OS X Server Webmail Logo
Getting Going (and Along) with OS X Server
Enabling SquirrelMail on OS X Server is a trifle, simply edit the web site settings in Server
Admin, and check the "webmail" box in the options list. Email services must be running and
configured, along with user accounts that have email boxes and IMAP (Internet Mail Access Protocol)
enabled. IMAP is a requirement for SquirrelMail (and all webmail programs designed with the sanity
of the administrator in mind). Using IMAP means that all messages
Figure 3. Checkbox to
Enable WebMail in Server Admin for Tiger Server
remain on the server, and are read on the server, with only the HTML representation of their
content actually transmitted back to the webmail users. If no attachments are involved, email
displays via the web browser as quickly as the server can process the messages and generate the HTML
(dependent, of course, on the connection speed of the user logging in). Once enabled, all the user
has to do is navigate to http://yourwebsitename/webmail, and then login at the prompt:
Figure 4.
Http://yoursite.com/webmail
Although SquirrelMail has been bundled with OS X Server starting with version 10.2, it really
started to kick some furry tail with OS X Server 10.3 and 10.4, which use the Cyrus IMAP server,
rather than the Apple Mail Server Carbonized from AppleShare IP that OS X Server 10.1 and 10.2
featured. With Cyrus, SquirrelMail absolutely flies, and with a decent broadband connection, can be
even faster than most non-web mail clients, such as Mail.app or Microsoft Entourage.
The Squirrel Behind the Curtain (a.k.a Road Kill)
Normally, SquirrelMail would be installed into a single directory as a separate virtual domain on
a web server, so that the users would go to http://webmail.yourdomain.com, rather than
http://www.yourdomain.com/webmail. Apple's implementation, however, makes it much easier to leverage
a single copy of SquirrelMail over multiple sites. Finding the "parts" of the SquirrelMail
installation isn't exactly straightforward. For example, the URL would suggest that SquirrelMail was
installed in a subfolder of the webroot /Library/WebServer/Documents, but it isn't! It's almost as
if OS X Server flattened the poor PHP script, scattering its code to the far corners of the OS X
Server filesystem. One interesting feature of Tiger Server is that when webmail is enabled in the
default web site, it's now indicated via an "Available services:" box under the Tiger Server Logo,
which serves as a hyperlink to SquirrelMail:
Figure 5. Webmail link
on Tiger Default Web Page
Apple's implementation of SquirrelMail starts in the /etc/httpd directory with the rather
self-explanatory httpd_squirrelmail.conf file:
nagitest:/etc/httpd mostadmin$ cat httpd_squirrelmail.conf
# Config file for linking SquirrelMail to MacOSX Server Web Server virtual host.
# Add the following line to each virtual host for which you want SquirrelMail:
# Include /etc/httpd/httpd_squirrelmail.conf
# Browsers will then be able to reference SquirrelMail with a URL like
# http://virtualhost.example.com/WebMail/
Alias /WebMail /usr/share/squirrelmail
Alias /webmail /usr/share/squirrelmail
<Directory /usr/share/squirrelmail>
Options Indexes FollowSymLinks
</Directory>
The crumb trail leads to /usr/share/squirrelmail, where the bulk of what a "normal" SquirrelMail
installation lives. The first thing to do is replace the postage stamp logo with the company, club,
user group, or house of worship logo. To do so, simply prepare the logo in one of the supported
formats (.png, .jpg. .gif), and copy it to the /usr/share/squirrelmail/images directory. Next, it's
time to fire up the SquirrelMail configure script:
nagitest:/usr/share/squirrelmail mostadmin$ sudo sh configure
SquirrelMail Configuration : Read: config.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
Command >> 1
This menu-driven configuration script is both simple and powerful. It's somewhat reminiscent of
the pre-web Internet, where a cousin of the Squirrel, known as Gopher, served up information via
text-driven menus. Changing the logo on the webmail login page is as simple as choosing
"Organization Preferences" from the menu and typing in the path to the new image:
SquirrelMail Configuration : Read: config.php (1.4.0)
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
Organization Preferences
1. Organization Name : Mac OS X Server WebMail
2. Organization Logo : mostlogo.gif
3. Org. Logo Width/Height : (0/0)
4. Organization Title : SquirrelMail $version
5. Signout Page :
6. Top Frame : _top
7. Provider link : http://www.squirrelmail.org/
8. Provider name : SquirrelMail
R Return to Main Menu
C Turn color on
S Save data
Q Quit
Command >>
Figure 6. Webmail login
with custom logo
To cover every single configuration option in SquirrelMail would take a very long time, but it's
interesting to note that the Configure script kicks off a perl script which lives in the
/usr/share/squirrelmail/config directory called conf.pl. Executing conf.pl (use sudo perl conf.pl)
from the command line brings up the familiar SquirrelMail configuration menu, but adds a little
extra hint when exiting:
Exiting conf.pl.
You might want to test your configuration by browsing to
http://your-squirrelmail-location/src/configtest.php
Happy SquirrelMailing!
While the configtest.php feature is nice, it also can be somewhat of a security risk, since it
reveals details about the server configuration, notably regarding the authentication settings of the
IMAP server. Another very important directory to administering SquirrelMail is /var/db/squirrelmail/
and its two subfolders, attachments and data. The attachments folder contains mine-encoded files
send with email messages:
nagitest:/var/db/squirrelmail/attachments root# ls -al
-rw------- 1 www wheel 2614916 Jul 26 23:55 NUSgHDdB6qiMQr0eO6CE3MPixlSXgSJB
-rw------- 1 www wheel 7947926 Jul 27 00:05 XHAca40O4T2xzloNZCzo5C3UznWAolY1
-rw------- 1 www wheel 4082991 Jul 26 23:58 bJEprLCFiVQKrY6QOu08ZtHKxWp5hfDr
It might not hurt to check this directory and periodically clean out the contents to save some
disk space. It may even be worthwhile to script a small cron or launchd job to periodically sweep
away the SquirrelMail droppings. In a similar vein, if a particular user experiences anomalies in
the display of their webmail, strange error messages, or long delays while logging in, it might be
worthwhile to clean up an session files, or delete the users' .pref files in the data folder. For
the most part, the out-of-the-box SquirrelMail configuration for OS X Server is pretty good, but can
be made a lot better with just a few more tweaks.
Adjusting Authentication
The first thing to do is to review how the SquirrelMail web interface sends its authentication
credentials to the imap server, and while there's technically no risk because the out-of-the-box
configuration has the IMAP server and the webmail server on the same box, the login credentials
aren't sent over the Internet. However, I still prefer SSL security for webmail, though "rolling
your own" SSL certificates is a topic for another column. It's mandatory if using SquirrelMail to
access an IMAP account on a remote server, which I do, because I like to run my own "Personal" copy
of SquirrelMail on my own G5, and sometimes my company provides webmail services for customers who
don't want or can't maintain their own webmail server for whatever reason. Also, disabling the login
and plain authentication types for Mail Services in OS X Server 10.4 requires that SquirrelMail also
be configured for an allowed authentication type, in this case cram-md5, which while not as secure
as SSL, is certainly much better than plain and login authentication, still used by a surprising
number of mail servers. First, the email service needs to be configured. Authentication types are
located in Server Admin, Mail Service, Settings, Advanced:
Figure 7. Disabling
Insecure IMAP Protocols
The next step is to adjust the authentication type in SquirrelMail's configure script, and that's
done in the IMAP server settings section of the Server Settings menu. Simple.
IMAP Settings
--------------
4. IMAP Server : localhost
5. IMAP Port : 143
6. Authentication type : cram-md5
7. Secure IMAP (TLS) : false
8. Server software : cyrus
Increasing the Attachment Size
Another out-of-the-box limitation is one imposed by the PHP library itself: SquirrelMail on OS X
Server can only handle email attachments of only two megabytes or less. While an Xserve running OS X
Server 10.3 or 10.4 with a gig of RAM and an Xserve RAID attached by fiber channel makes for a
flying SquirrelMail, the limit's simply the PHP default and with a few small edits, can be made to
match to the attachment size limit of the Mail server itself. However, I have to point in all
fairness out that the user experience of uploading a twenty-five megabyte attachment through a web
browser might be somewhat different than what end-users expect. As a matter of fact, I've found that
some end users don't adjust their expectations when working at home over a cable modem that might
download at similar speeds to what they're used to at the office, but with much slower upload
speeds. Even worse, I've had complaints of SquirrelMail "not working" simply because someone didn't
understand how long it would take to upload a ten megabyte PowerPoint presentation via a dial-up
connection.
Figure 8. SquirrelMail
default attachment size
Uploading large files via a web browser on OS X doesn't really offer much in the way of a
progress indicator, and if the connection's slow (like dialup) or flaky (like dialup over a
Bluetooth modem connection), then there's always the risk that the SquirrelMail user might be left
in limbo. But if they're forewarned, upping the attachment size can even make use of Cyrus's ability
to act as a file system, much like folks would use a .mac account or a gmail account to Squirrel
away or transfer files.
The first surprise is that the PHP distribution shipped with Tiger Server doesn't include an
active copy of the PHP.ini file, the standard PHP configuration file. Luckily, there's an
/etc/php.ini.default file that can be copied and edited to spec. First, make a copy of the file:
nagitest:/etc dean$ sudo cp /etc/php.ini.default /etc/php.ini
then, open up the php.ini file in a favorite editor. These days I'm partial to BBEdit's command
line "bbedit" tool, or TextWrangler's "edit" tool, but pico or vi will also work just fine. It's
helpful to have something with an easy search feature:
nagitest:/etc dean$ sudo pico php.ini
Now, find the first thing to adjust, the following line:
max_execution_time = 30 to max_execution_time = 600
this allows for longer uploads (ten minutes) without causing a timeout. Next, adjust the line
that reads:
memory_limit = 8m to read memory_limit = 32M
Next is the line:
post_max_size = 2M to post_max_size = 24M
Now the line:
upload_max_filesize = 2M to upload_max_filesize = 24M
Now, save the changes, and when back at the command prompt, issue the following command:
nagitest:/etc dean$ sudo apachectl restart
Restarting the Apache web server forces the PHP library to (re)read its configuration file. At
the bottom of the SquirrelMail page, the new max upload size is now reflected--24 megabytes.
Figure 9. Souped up
nuts! SquirrelMail stuffs its cheeks with attachments
Necessary Adjest[sic]ment, Fixing the SpellChecker
By default, the SquirrelSpell plugin of SquirrelMail is disabled in OS X Server, because turning
it on (easy to do in the plugins section of the configure script) reveals that the ispell library
it's looking for is nowhere to be found on OS X. And while there might be a nice dictionary
application and widget built into OS X 10.4, enabling the spellchecker in Mac OS X Server webmail is
the one of the most requested enhancements, second only to increased attachment sizes.
Figure 10. Where the
#%!@#!@# is ispell?
The SquirrelSpell plugin expects to find ispell in /sbin but it's not included with the base
install. OS X Server webmail is strictly BYOSC (bring your own spellchecker). There's three ways to
get a working copy of ispell. One is to download the source code, patch it by editing one of the
header files, and then install it. That, however, is just a bit too much work for something this
straightforward. The other two methods are either to use the Fink package manager
http://Fink.sourceforge.net, which I detailed in my February Source Hound Column, or the DarwinPorts
package manager, which I'll use for this example. In using either of the three methods, an
installation of Xcode 2.0 is required if installing onto OS X Server 10.4.
First, obtain and install either Xcode 1.5 if using Panther Server, or Xcode 2.0 if using Tiger
Server. Next, download a copy of the Darwin ports binary installer from
darwinports.opendarwin.org/downloads/DarwinPorts-1.0.dmg. Install the DarwinPorts software.
Next, navigate to /opt/local/bin, and issue the following command:
nagitest:/opt/local/bin dean$ sudo ./port install ispell
If all goes well, DarwinPorts will download, configure, compile, and even clean up after the
ispell installation, which will resulting in a compiled ispell at /opt/local/bin/ispell. Now all
that's necessary is to fool the SquirrelSpell plugin into thinking that ispell is in /sbin, where
it's supposed to be, and that's easy enough to accomplish with a symbolic link:
nagitest:/opt/local/bin dean$ sudo ln -s /opt/local/bin/ispell /sbin/ispell
Now, the SquirrelSpell plugin will be happy, and the spellcheck will work as advertised, making
the end users smile and chant with glee "thank you SquirrelMail, thank you!" But of course, they'll
be thanking no one, not even their system administrator, because it should have worked, right
out-of-the-box, everyone knows that all good email clients have spellcheckers, right?
Figure 11. Where's
ispell? There's ispell!
Take the Squirrel for a Walk
So now that SquirrelMail's using secure authentication, can handle decent-sized attachments, and
can catch the horrid spelling errors we all make while typing, is this the end for our beloved
flying squirrel, or can we take it places it hasn't been before? Well, SquirrelSpell's just the
beginning. Visit http://SquirrelMail.sourceforge.net and check out
some of the myriad of plugins, everything from server-side plugins for spam filtering to
out-of-office autoresponders to LDAP integration plugins for the SquirrelMail address book are
available to try, not to mention some fun stuff like appearance themes. SquirrelMail might be
inherently simple, but it has plugin support that no other webmail program can touch. What else
could be more uplifting and useful than a Squirrel that makes email fly away from the office, what
would be its perfect companion?
Figure 12. A Talking
Moose, of Course: "A problem drinker is one who never buys."
http://www.zathras.de/angelweb/moose.htm
In Next Month's Source Hound
I will return to the subject of my very first article for MacTech back in November of last
year--Apple's Directory Services a.k.a "Open Directory" I'll take a look at version III and the new
schema additions, features, and tools included with Tiger Server, as well as some open-source
goodies like phpLDAPadmin and ask a Tiger Open Directory Master to say "Ahhhhh" and take a deep look
inside...maybe for an OU or two?
Dean Shavit is an ACSA (Apple Certified System Administrator) who loves to use a Mac,
but hates paying for software. So each month he's on the hunt for the best Open-Source and freeware
solutions for OS X. Besides surfing for hours, following the scent of great source code, he's a
partner at MOST Training & Consulting in Chicago, where he trains system administrators in OS X and
OS X Server, facilitates Mac upgrade projects for customers, and writes for his own website, http://www.themachelpdesk.com. Recently, he became the
surprised father of an application: Mac HelpMate, available at http://www.machelpmate.com. If you have questions or comments
you can contact him: dean@macworkshops.com.
