SquirrelMail 1.4.

6 on RedHat Linux 9
Part 1 - Installing SquirrelMail & Configuring the Apache Virtual Host

Written by Tony Bhimani

April 1, 2006

Requirements
RedHat Linux
Apache HTTPD
IMAP Server
PHP with IMAP
SquirrelMail 1.4.6

The SquirrelMail tutorial is the second part of a series I started this week on installing
webmail access on a server. We began with setting up an IMAP server using Dovecot
that provides the back-end and now we conclude with SquirrelMail being the front-end.
This tutorial will teach you how to install and configure the SquirrelMail 1.4.6 package,
set up an Apache virtual host for your webmai sitel, and verify your installation actually
works. Before you continue you should already have Sendmail or another SMTP server
and Dovecot or another other IMAP server installed and working. My Sendmail install
uses SMTP AUTH to deny relaying abuse and that will play a part later on when
configuring SquirrelMail. Dovecot should be configured as an IMAP server and not
necessarily utilizing SSL/TLS. In Part 1 we'll download and install SquirrelMail and
configure Apache for the webmail site.

At the time of this writing the latest stable version of SquirrelMail is 1.4.6 which is
available at http://www.squirrelmail.org/. Once again the target operating system is
RedHat 9. I know it's kind of dated and I promise one of these days I'll use a more up-to-
date OS. We'll start by downloading the SquirrelMail package.

Make sure you're logged in as root and are in your home directory. Start by downloading
the SquirrelMail gzip file using wget.

wget http://easynews.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-
1.4.6.tar.gz
Using tar we'll unzip the package and then move into the squirrelmail-1.4.6 directory that
was extracted.

tar zxf squirrelmail-1.4.6.tar.gz

cd squirrelmail-1.4.6

SquirrelMail comes with a text-based configuration utility that makes creating the config
file. We'll do the SquirrelMail configuration in the second part of this guide. Next we're
going to set up an Apache virtual host for our webmail site. We're going to create some
directories, move the SquirrelMail files to the document root, move the data folder
outside the document root, and change ownership of the data folder to the apache user (or
whatever user your httpd process runs as). I chose to install SquirrelMail in /home in a
directory called squirrelmail. You may want to put it somewhere else like in /var or
/var/www. It's up to you.

cd /home
mkdir squirrelmail
cd squirrelmail
mkdir html
mkdir html/cgi-bin
mkdir logs
mv /root/squirrelmail/* ./html/
mv html/data/ ./sqdata
chown -R apache.apache sqdata
Let me explain the structure. The html directory is the document root of the webmail site.
We also create a cgi-bin directory for our own purposes (not SquirrelMail) if we ever
need it in the future. A logs directory is created for our web server logs. The contents of
the extracted squirrelmail tar.gz is moved to the html directory. We then move the data
directory from html to /home/squirrelmail/sqdata - thus renaming it. It's not a requirement
to rename it, it's merely so we know it's SquirrelMail data (your address book,
preferences, signature and other files are stored there). We then recursively change
ownership of sqdata to the apache user & group. SquirrelMail will need to be able to
write to this directory and our httpd process runs as apache. Typically httpd runs as
apache by default if you installed via RPM's. If you didn't change it in httpd.conf then
yours should be the same.

Next we'll configure an Apache virtual host for our webmail site. If this is the first time
you're configuring Apache then you'll have to edit two lines (ServerName and
NameVirtualHost) located in /etc/httpd/conf/httpd.conf. Use your machine's IP address
for both of these directives.

ServerName 192.168.1.110
NameVirtualHost 192.168.1.110:80

Open /etc/httpd/conf/httpd.conf with an editor like vi or pico and scroll all the way to the
end of the file. We'll add our new VirtualHost there.

vi /etc/httpd/conf/httpd.conf

<VirtualHost 192.168.1.110:80>
ServerAdmin admin@domain.com
ServerName 192.168.1.110
DocumentRoot /home/squirrelmail/html
ScriptAlias /cgi-bin/ /home/squirrelmail/html/cgi-bin/
ErrorLog /home/squirrelmail/logs/error_log
CustomLog /home/squirrelmail/logs/access_log combined
</VirtualHost>
We created a name based virtual host and will listen on port 80. We use six directives to
configure our site (ServerAdmin, ServerName, DocumentRoot, ScriptAlias, ErrorLog,
and CustomLog).

• ServerAdmin specifies the email address of the administrator (that's you).

• ServerName is the IP address or FQDN of your site. I used an IP for this example
but you'll want to use something like webmail.yourdomain.com. Be sure to add
whatever host you use to your DNS zone file otherwise your webmail site won't
be accessible. Read my BIND tutorial for more information on adding a new host.
• DocumentRoot is the path to your HTML files or otherwise known as your web
site root.
• ScriptAlias is used to create a cgi-bin for executable CGI/Perl scripts. It's mapped
to http://host.yourdomain.com/cgi-bin/.
• ErrorLog defines the name of your web server error file for this site. Any 404,
500, and other HTTP or PHP errors will be written to this file.
• CustomLog creates a log of people that access your web site. At the end we use
combined to tell Apache to use the combined format for log file entries. If you
wanted to use a web server log analysis program like Awstats to parse your logs
for HTML report creation then using the combined format is ideal.

Save your changes and exit your editor. We have to tell Apache to reload httpd.conf and
this can be accomplished by restarting the httpd process (or using graceful).

/etc/init.d/httpd restart
SquirrelMail 1.4.6 on RedHat Linux 9
Part 2 - Configuring SquirrelMail

Written by Tony Bhimani

April 1, 2006

Requirements
RedHat Linux
Apache HTTPD
IMAP Server
PHP with IMAP
SquirrelMail 1.4.6

SquirrelMail has now been installed and Apache is ready to serve our webmail site.
Before we can use SquirrelMail we have to configure it to our specifications. Included in
the package is a text-based menu driven system that makes configuring SquirrelMail
easy. In the html folder there is a script called configure. By selecting menu choices and
entering our server settings, preferences, plugins, and other features, configure will
generate a configuration file SquirrelMail uses to render our webmail site correctly.

We start by moving to the html directory and running configure.

cd /home/squirrelmail/html/
./configure
You should now see the screen above. There are several options to choose from like
Organization Preferences, Server Settings, Themes, etc. At the bottom is a prompt asking
for a command. The command is the number corresponding to the items in the main
menu. All you do is enter the number and press the [enter] key to be taken to that section
of configuration. We'll start with Organization Preferences.

The item we'll want to change is Organization Name, Title, Provider link, Provider name,
and optionally Logo and its dimensions. If you do change the logo then you should copy
your logo to the images directory within /home/squirrelmail/html and use
../images/your_logo.ext when you specify it for option 2. Also be sure to change the
dimensions with option 3 otherwise your logo may appear distorted on the webmail sign-
in page. Go ahead and change the default values to those that represent your
server/domain.

When you're done, type in R and then press [enter] to return to the main menu. Go to the
Server Settings section.
The first thing to do is change the domain from example.com to your domain name. Once
you have done that then we'll edit the IMAP settings using option A. All we have to
change is the IMAP Server from localhost to our IP address of the server.

Conitnue on to change the SMTP Settings using option B. There are two thing we have to
change and they're the SMTP Server and SMTP Authentication. Use your IP address
instead of localhost. You may be asking why not just leave it as localhost? It'll work but
your email headers will look odd. It'll say it's coming from localhost when people receive
email from you. Plus there will be some nonsense about a non-authenticated user and
apache@localhost showing up. There are others things I care not to list. Trust me, you'll
want to use your WAN or LAN IP instead of localhost.
This next part about SMTP Authentication is optional. If you followed my Sendmail
tutorial or configured your SMTP server with SMTP AUTH then you'll need to change
option 7 from none to login. If you don't then you won't be able to send mail out - you'll
get relaying denied errors. Proceed with option 7 and either let it auto-detect your
authentication mechanisms or skip that and enter login.
When you're done the SMTP Server should be set to your IP and Authentication as login.

Return to the main menu and selection option 3 for Folder Defaults. In that section you'll
see the Trash, Sent, and Drafts folders are INBOX.Trash, INBOX.Sent, and
INBOX.Drafts respectively. You may want to change them by removing the INBOX
prefix so they're more visually appealing.
Return to the main menu and proceed to General Options (option 4).
Since we moved the Data Directory outside our document root we'll have to change it.
Mine is located at /home/squirrelmail/sqdata/ and option 1 will need to be changed.

Return to the main menu. I'll next show you how to configure the default CSS file from
Themes (option 5). This is totally optional and you may want to skip it and continue on
to the Plugins section.

From Themes do option 2 for CSS and set the default file to ../themes/css/verdana-10.css.
You can change this later if you want to browse the themes/css directory for other style
sheets.

Return to the main menu and go to Plugins (option 8). Plugins enhance SquirrelMail's
capabilities and there are over 200 plugins available at http://www.squirrelmail.org/. One
that you may be interested in is the Change_passwd plugin. It allows you to change your
system password from within SquirrelMail. Adding a new plugin involves downloading
the package, extracting its contents, moving the extracted folder to the plugins directory
(/home/squirrelmail/html/plugins/ in our case), running the configure script, adding the
plugin through the Plugins section, and then saving the changes to your config file. I
won't be showing you how to do it in this guide.
SquirrelMail does come preloaded with some useful plugins like a calendar, spell-check,
spamcop, and more. We'll be adding abook_take, administrator, calendar,
delete_move_next, message_details, newmail, sent_subfolders, spamcop, and
squirrelspell.

before and after

Return to the main menu. There are other sections you can configure if you want, but for
this guide we're done. The last thing to do save our new config file and exit the configure
script. Press Q and hit [enter]. The configure script will prompt you to save your
changes. Tell it to save them with Y and [enter].

SquirrelMail is now configured and ready to be accessed through our browser. We'll do
that next.
quirrelMail 1.4.6 on RedHat Linux 9
Part 3 - Testing SquirrelMail

Written by Tony Bhimani

April 1, 2006

Requirements
RedHat Linux
Apache HTTPD
IMAP Server
PHP with IMAP
SquirrelMail 1.4.6

Our SquirrelMail installation is all configured and ready to be tested. For this part we'll
log in to SquirrelMail, set up our profile, send ourselves a test message, and then send a
message to an email address not handled by our server.

Open up your favorite browser and go to your webmail site. I used an IP address for my
webmail access but you should have used a real URL like
http://webmail.yourdomain.com.
Enter your system username and password and login into SquirrelMail. Once you've
logged in you'll be in your Inbox.
You'll want to update your profile by setting your full name, email address, and reply-to
address. Click the Options link on top.
The are several options to choose from but select Personal Information. Enter your
Name, Email Address, Reply-To Address, and save your changes. Go back to your Inbox.

In my Dovecot tutorial I sent myself a test message confirming a successful installation. I

originally viewed that message through Outlook Express and now I can do the same from
SquirrelMail.
Now we'll send a message to ourselves from SquirrelMail to verify that our SMTP Server
settings work. Click the Compose link on top. In the To field put in your email address,
enter a subject, and put something in the body. When you're done click the Send button.
Once the message is sent, SquirrelMail will place you back in your Inbox. Click the
Check mail link in the upper left and if everything worked you should see a new
message in your Inbox.
Take a look at your message. If you updated your personal settings then it should say it's
from your name and email address and received by your address.
Now we know local mail works. The real test is to see if a message can be sent to an
external domain. Compose a new message and if you have a Hotmail, Yahoo, or Gmail
account, send it there. I sent a test to my Yahoo account and it was successfully received.
<Rant>
I should mention I originally sent two tests to my Hotmail account and I never got them. I
checked /var/log/maillog and the messages were sent and received by mx1.hotmail.com.
I've had my Hotmail account almost since it started and ever since Microsoft took over
it's been one problem after another. I once had a two week span of never receiving any
mail and now the 90% of mail I do get is spam. Hotmail sucks.
</Rant>

Try sending a message to your domain address from your free Hotmail, Yahoo, or Gmail
account if you have one. If you receive it then your SquirrelMail setup is working
perfectly.

You're done! You now have webmail for your domain. If you have any questions about
this guide then please post them to the forum.

Tut

This little tutorial will show you how to create custom SquirrelMail login pages for many
virtual hosts, or in plain English, you have one copy of SquirrelMail and host many web
sites on a single server. The purpose is to provide a unique login page for each web site
domain without installing multiple copies of SquirrelMail. This is very useful if you are
running a webhosting business or you host your friend’s web sites (like I do) and you
don’t want SquirrelMail branded with your name but theirs. If that isn’t a good enough
reason then how about the fact that the default SquirrelMail login page is boring and you
should jazz it up with a custom web site theme.

The following screenshots are examples of some webmail login pages on my server.
They all use the same copy of SquirrelMail (version 1.4.6) but with my tweaks each
domain has a custom login page.

This walkthrough makes the assumption that you have HTML, PHP, and some graphic
design skills. To edit the SquirrelMail files you should know how to copy and paste and
understand PHP, but to create your own custom templates you’ll need to know HTML,
PHP, and graphics. You should also have root access to your server or have the ability to
upload the modified SquirrelMail files to your server. The other obvious assumption is
that you have SquirrelMail 1.4.6 installed and configured on your server (using another
version of SquirrelMail may work, but I don’t know how much their code changed
between revisions). If you don’t have SquirrelMail installed then you can check out my
SquirrelMail 1.4.6 tutorial on XenoCafe. With that said, let’s get started.

1. You should already know where SquirrelMail is installed on your server and have it
configured for each domain that accesses it. For this howto I’ll use the example directory
location of /www/webmail/html/ and the Apache virtual host file for webmail has a
ServerAlias directive set for each domain (webmail.domain1.com,
webmail.domain2.com, etc…). See my Apache Web Server tutorial for more information
on setting up virtual hosts.

2. The way I accomplished custom webmail login pages was to create a directory in
/www/webmail/html/ called hosts. This directory is where all your templates are stored
for each custom webmail login page and their associated images. Start by creating a host
directory in your webmail root directory (for clarification, this is the same top level
directory where the SquirrelMail "src" directory exists).

cd /www/webmail/html/
mkdir hosts

3. There are three SquirrelMail PHP files that we’ll need to edit. The primary one is
called global.php that resides in the functions directory. We’ll insert our custom function
called show_login_page that makes custom logins possible. Let’s take a look at this login
page function we’re creating.

function show_login_page( $errTitle="", $errString="" ) {

$httphost = strtolower( $_SERVER["HTTP_HOST"] );

switch ($httphost) {
case "webmail.domain1.com":
require( SM_PATH . "hosts/domain1/domain1.php" );
break;

case "domain2.com":
case "www.domain2.com":
case "webmail.domain2.com":
include( SM_PATH . "hosts/domain2/domain2.php" );
break;

default:
require( SM_PATH . "hosts/default/default.php" );
break;
}

This function accepts two arguments ($errTitle and $errString). You’ll learn about these
later when we modify one of the other SquirrelMail files. $httphost contains the server
name of which web site the user is visiting. This is acquired from the global
$_SERVER["HTTP_HOST"] PHP variable. We use a switch/case structure to evaluate
the HTTP HOST name. Depending on which host is visited the custom template for that
host is shown for the login page. The host names are set up through Apache virtual hosts
and DNS, in the case of the webmail subdomain. For www.domain.com and domain.com,
it is assumed access to the site is coming from a /webmail directory. That can be
established via symbolic links like so.

ln -s /www/webmail/html/ /www/domain/html/webmail

So webmail can be accessed from http://webmail.domain.com or from

http://www.domain.com/webmail since both paths map to the same physical space.
You’ll see the PHP include function being used once a host is matched. The include
function inserts your custom login page’s code as part of the HTML output to the web
browser. The path to the PHP page is within the hosts directory we created earlier. For
each host you want to serve custom logins you’ll create a subdirectory within hosts (I use
the domain name without the ending .com, .net, etc). You’ll store your custom login page
and image files within that domain directory. The last part of the switch/case is the
default login page. This is shown when there are no HTTP HOST matches and thus
displays the default SquirrelMail login page.

Open up the functions/global.php file in a text editor and add the show_login_page
function to the end of the file right above the ending ?> PHP tag. Customize the hosts for
your server and save the file when you’re done.

4. Next we’ll edit the src/login.php page. We’re basically gonna strip out parts of the
exsiting SquirrelMail code and replace it with a call to our show_login_page function.
Make a backup copy of login.php and open the original in a text editor. Delete everything
in the file and insert this code.

<?php

/**
* login.php -- simple login screen
*
* Copyright (c) 1999-2006 The SquirrelMail Project Team
* Licensed under the GNU GPL. For full terms see the file COPYING.
*
* This a simple login screen. Some housekeeping is done to clean
* cookies and find language.
*
* @version $Id: login.php,v 1.98.2.11 2006/02/03 22:27:55 jervfors Exp
$
* @package squirrelmail
*/

/**
* Path for SquirrelMail required files.
* @ignore
*/
define("SM_PATH","../");

/* SquirrelMail required files. */

require_once(SM_PATH . "functions/strings.php");
require_once(SM_PATH . "config/config.php");
require_once(SM_PATH . "functions/i18n.php");
require_once(SM_PATH . "functions/plugin.php");
require_once(SM_PATH . "functions/constants.php");
require_once(SM_PATH . "functions/page_header.php");
require_once(SM_PATH . "functions/html.php");
require_once(SM_PATH . "functions/global.php");
require_once(SM_PATH . "functions/forms.php");

/**
* $squirrelmail_language is set by a cookie when the user selects
* language and logs out
*/
set_up_language($squirrelmail_language, TRUE, TRUE);

/**
* Find out the base URI to set cookies.
*/
if (!function_exists("sqm_baseuri")){
require_once(SM_PATH . "functions/display_messages.php");
}
$base_uri = sqm_baseuri();

/*
* In case the last session was not terminated properly, make sure
* we get a new one.
*/

sqsession_destroy();

header("Pragma: no-cache");

do_hook("login_cookie");

$loginname_value = (sqGetGlobalVar("loginname", $loginname) ?

htmlspecialchars($loginname) : "");

if(sqgetGlobalVar("mailto", $mailto)) {
$rcptaddress = "<input type=\"hidden\" name=\"mailto\"
value=\"$mailto\" />\n";
} else {
$rcptaddress = "";
}

show_login_page();

?>

Save your changes when you’re done and then we’ll move on to the last file.

5. The last file we edit is functions/display_messages.php. This file contains functions to

display any messages (error or otherwise) on the screen, such as login failures, IMAP
failures, etc. We need to change the logout_error function so when a login failure occurs
that our custom page is shown instead of the default SquirrelMail version. Replace the
logout_error function with this code.

function logout_error( $errString, $errTitle = "" ) {

list($junk, $errString, $errTitle) = do_hook("logout_error",

$errString, $errTitle);

if ( $errTitle == "" ) {
$errTitle = $errString;
}

show_login_page($errTitle, $errString);

If you were wondering about those arguments to our show_login_page function, now you
can see what they’re for. SquirrelMail uses a hook to capture error messages on events.
All we are doing is passing those error values to our login page function. When you
intially go to the page, no errors are shown. If you login in and provide invalid
information, our same login page will be shown again, but this time it’ll have the error
messages within it. It’s similar to a postback but the URL is different. When we defined
our login page function, we initialized those arguments with default null string values so
no errors would show. When logout_error is called we pass the errors so they will be
shown.

6. SquirrelMail’s PHP files are done so what’s left is to go over the steps of creating a
custom login theme. I’ll now go over the parts you need to include when creating a
template. Here is an example of the default template.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>

<head>
<meta name="robots" content="noindex,nofollow">
<link rel="stylesheet" type="text/css" href="../themes/css/verdana-
10.css" />
<title>Domain - Login<?php echo (($errTitle != "" ) ? " - ".$errTitle :
""); ?></title><script language="JavaScript" type="text/javascript">
<!--
function squirrelmail_loginpage_onload() {
document.forms[0].js_autodetect_results.value = "<?php echo
SMPREF_JS_ON; ?>";
var textElements = 0;
for (i = 0; i < document.forms[0].elements.length; i++) {
if (document.forms[0].elements[i].type == "text" ||
document.forms[0].elements[i].type == "password" ) {
textElements++;
if (textElements == <?php echo (isset($loginname) ? 2 : 1); ?>)
{
document.forms[0].elements[i].focus();
break;
 }
}
}
}
// -->
</script>

<style type="text/css">
<!--
/* avoid stupid IE6 bug with frames and scrollbars */
body {
voice-family: "\"}\"";
voice-family: inherit;
width: expression(document.documentElement.clientWidth - 30);
}
-->
</style>

</head>

<body text="#000000" bgcolor="#ffffff" link="#0000cc" vlink="#0000cc"

alink="#0000cc" onLoad="squirrelmail_loginpage_onload();">
<form action="redirect.php" method="post">
<table bgcolor="#ffffff" border="0" cellspacing="0" cellpadding="0"
width="100%"><tr><td align="center"><center><img
src="http://webmail.domain.com/images/domain_logo.gif" alt="Domain
Logo" width="180" height="50" /><br />
<small>SquirrelMail version 1.4.6<br />
By the SquirrelMail Project Team<br /></small>
<table bgcolor="#ffffff" border="0" width="350"><tr><td
bgcolor="#dcdcdc" align="center"><b>Domain Login</b>
</td>
</tr>
<tr><td bgcolor="#ffffff" align="left">
<table bgcolor="#ffffff" align="center" border="0" width="100%"><tr><td
align="right" width="30%">Name:</td>
<td align="left" width="*"><input type="text" name="login_username"
value="<?php echo $loginname_value; ?>" />
</td>
</tr>

<tr><td align="right" width="30%">Password:</td>

<td align="left" width="*"><input type="password" name="secretkey" />
<input type="hidden" name="js_autodetect_results" value="<?php echo
SMPREF_JS_OFF; ?>" />
<?php echo $rcptaddress; ?>
<input type="hidden" name="just_logged_in" value="1" />
</td>
</tr>
</table>
</td>
</tr>
<tr><td align="left"><center><input type="submit" value="Login" />
</center></td>
</tr>
</table>
</center>
<br><?php if ($errString != "" ) { echo "<center><font size=\"2\"
face=\"Arial, Helvetica, sans-serif\"
color=\"#ff0000\"><strong>$errString</strong></font></center>"; } ?>
</td>
</tr>
</table>
</form>
</body></html>

The code pieces in bold should be included in your template. I won’t go in depth over the
code, that’s why I said you should know HTML and PHP.

I’ve included a zip file containing the altered PHP files and a couple templates to give
you examples to follow when creating your own custom login pages. Be sure to read the
README file included in the zip.