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

Written by Tony BhimaniApril 1, 2006

RequirementsRedHat LinuxApache HTTPDIMAP ServerPHP with IMAPSquirrelMail 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.gzcd 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 /homemkdir squirrelmailcd squirrelmailmkdir htmlmkdir html/cgi-binmkdir logsmv /root/squirrelmail/* ./html/mv html/data/ ./sqdatachown -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.110NameVirtualHost 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 9Part 2 - Configuring SquirrelMail

Written by Tony BhimaniApril 1, 2006

RequirementsRedHat LinuxApache HTTPDIMAP ServerPHP with IMAPSquirrelMail 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 9Part 3 - Testing SquirrelMail

Written by Tony BhimaniApril 1, 2006

RequirementsRedHat LinuxApache HTTPDIMAP ServerPHP with IMAPSquirrelMail 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.