3. Installing SquirrelMail

3.1 Quick and Dirty install

In order to use SquirrelMail, you should take the following steps.

Download all required software

You can find the SquirrelMail package at the SquirrelMail site. PHP can be found at the PHP site.

Install web server and PHP (version 4.1.0 or above)

SquirrelMail needs a web server with PHP support. Please refere to the PHP installation manual for information about what web servers PHP works with and its installation procedures.

Note that some Linux and Unix distributions provide a precompiled web server with PHP support built in.

We recommend the following PHP settings:

• register_globals off - This is a dangerous setting when enabled, and is not generally needed for most recent PHP applications. We no longer release security advisories for issues only exploitable with this setting turned on because it has long been a well-known weakness in PHP (and has been removed from PHP 6). Note that you can easily enable it only for a single legacy application that may require it while keeping the default off for the rest of your applications.
• magic_quotes_{runtime, gpc, sybase} off - SquirrelMail may work with any of these turned on, but if you experience stray backslashes in your mail or other strange behaviour, it may be advisable to turn them off.
• file_uploads on - This is needed if your users want to attach files to their emails.
• safe_mode on or off - Turning safe mode on in SquirrelMail's case is not much more secure than having it off. When it is enabled, incompatibilities with some functionality may arise (see our safe mode notes).

Install IMAP server

What IMAP server you can use depends on what the other components in your email system are and how they were installed and configured. The IMAP server needs to understand and be compatible with how messages are stored on your system.

If you use Unix or Linux with a standard sendmail MTA server, you probably have to install an IMAP server that works with mail stored in /var/spool/mail/, such as UW IMAP, Dovecot, etc.

If you are running your email server on a Windows platform, you might have to enable an IMAP service that is bundled with your email server.

If your email server does not support IMAP, you might have to find some other email server product.

Unpack SquirrelMail package

Unpack the SquirrelMail package in a web-accessible location.

Prepare data and attachment directories

Select a data dirrectory and attachment dirrectory outside of the web server's reach (for example in a Unix or Linux environment, a subdirectory of /var is a good place for these).

The data directory is where SquirrelMail user preferences are stored - even when you have configured SquirrelMail to store user preferences in a database, some plugins might still need to use this directory. The attachment directory is used mainly for temporary storage of file uploads that will become email attachments.

Both of these directories should be writable (not readable) by the web server and no one else (except you). In a Unix or Linux environment, that means that they should be owned by the root user if possible (otherwise whatever user you log in as), their group should be the same as that that the web server runs as (e.g. "www-data", "apache", "nobody", "wheel", etc.), and their permissions should be 0730 (rwx-wx---).

If you use PHP with safe mode enabled, check our safe mode notes which explain other possible limitations on these directories.

Directory access considerations

Only a small subset of the SquirrelMail source code needs to be directly accessible to users' browsers. The rest of the source code is used internally by SquirrelMail. Leaving the entire source tree open to outside access is not a problem or vulnerability, but some attackers have been known to snoop for old versions of SquirrelMail by trying to inspect things such as the ChangeLog file. If you want to employ the maximum level of protection against snoops and would-be attackers, you can make use of the .htaccess files that come with the SquirrelMail source code by adding "AllowOverride AuthConfig" to the Directory settings for SquirrelMail in your Apache configuration file (if using the Apache web server), or you can use the Directory settings suggested in the Apache configuration section below.

Configure SquirrelMail

Run config/conf.pl (or just configure) from the command line. This is a Perl script, so if you do not have Perl installed, please refer to our notes about how to configure SquirrelMail without shell access.

Use the D option to load predefined settings for your particular IMAP server, and edit at least the Server Settings and General Options (making sure to set the "Data Directory" and "Attachment Directory" settings).

Check your SquirrelMail configuration

Browse to http://example.com/squirrelmail/src/configtest.php to test your configuration for common errors. You'll need to adjust the "example.com" and "squirrelmail" parts to match the location where you installed it. Note that in SquirrelMail versions 1.5.0 and up, if you are accessing configtest.php from any place other than the machine where SquirrelMail is installed, you'll need to make sure $allow_remote_configtest is enabled in your configuration file to do so (or see "11. Tweaks" ==> "7. Allow remote configtest" in the configuration utility). If you do that, be sure to disable it again when you are finished.

Log into SquirrelMail

Browse to http://example.com/squirrelmail/ to log in. Again, you'll need to change "example.com" and "squirrelmail" to whatever the location is that you have it installed.

3.2 Installing SquirrelMail on Unix and Linux systems

This chapter covers the installation of SquirrelMail and related packages on a generic Unix or Linux system. It does not cover the installation of the operating system or any other tools required for a fully functional email system.

Any version numbers used in these examples are specific to the time when this documentation was written. You should generally use the most up to date versions of all software involved. That is, if there are newer versions of these packages available now, you'll probably want to substitute the newer numbers in the examples below. Make sure that you are not using old, obsolete or vulnerable software!

This guide uses the UW IMAP server, because it is a simple (and ubiquitous) example and because it can be used in most generic email system setups where incoming mail is stored in the /var/spool/mail directory. If you are planning to offer webmail on a system with a large number of users or where users have large mailboxes, consider planning a better email system design and using different IMAP server software.

PLEASE NOTE that before you begin installing such things as a web server, PHP or an IMAP server, you should check whether or not your system already has such software installed. Many server-class systems come with that kind of software ready to go. Also note that these installation instructions use generic compilation commands that should work on most any system, however your system may have more graceful (and even easier) ways to install software, like the apt-get tool in systems such as Debian and the yum tool in systems such as Fedora/Red Hat.

Typically, you'll need to have root-level access to your server to perform these operations.

Download required software

You will need:

• Apache - http://httpd.apache.org/download.cgi
• PHP - http://php.net/downloads.php
• UW IMAP - http://www.washington.edu/imap/
• SquirrelMail - http://squirrelmail.org/download.php

# install -d /usr/local/src/downloads
# cd /usr/local/src/downloads
# wget http://some-apache-mirror-server/apache/httpd/httpd-2.2.11.tar.gz
# wget http://www.php.net/get/php-5.2.9.tar.bz2/from/a/mirror
# wget ftp://ftp.cac.washington.edu/mail/imap.tar.Z
# wget http://some-sourceforge-mirror/some-path/squirrelmail-1.4.17.tar.bz2

Unpack and install Apache

# cd /usr/local/src
# tar -xzvf /usr/local/src/downloads/httpd-2.2.11.tar.gz
# cd httpd-2.2.11
# ./configure --prefix=/usr/local/apache --enable-module=so
# make
# make install

Unpack and install PHP

# cd /usr/local/src
# tar --bzip2 -xvf /usr/local/src/downloads/php-5.2.9.tar.bz2
# cd php-5.2.9
# ./configure --prefix=/usr/local/php \
> --with-apxs2=/usr/local/apache/bin/apxs
# make
# make install

Note that if you decide to configure your PHP compilation with the --disable-all option, you must also add the --enable-session and --with-pcre-regex options.

Add PHP support to Apache

In your main Apache configuration file (typically /etc/httpd/conf/httpd.conf), add this:

<IfModule mod_php5.c>
  AddType application/x-httpd-php .php
</IfModule>

Restart Apache and check if PHP is working

Execute the restart request from the command line:

# /usr/local/apache/bin/apachectl graceful

Create a test file in the document root of Apache and put this in it:

<?php phpinfo(); ?>

Load that file in a web browser and make sure it displays a page describing your PHP system details.

Unpack and install IMAP server

Unpack the UW IMAP package.

# cd /usr/local/src
# tar -xzvf /usr/local/src/downloads/imap.tar.Z

Compile UW IMAP:

# cd /usr/local/src/imap-<some version>
# make port-name EXTRADRIVERS='' SSLTYPE=unix

Replace "port-name" above with the name that matches your system. Check the file "Makefile" for possible values. If you haven't installed OpenSSL libraries and headers, use "SSLTYPE=none" instead of "SSLTYPE=unix".

Install IMAP server binary:

# strip imapd/imapd
# install -d /usr/local/libexec/
# cp imapd/imapd /usr/local/libexec/

Enable IMAP server in inetd.conf:

imap2 stream tcp nowait root /usr/sbin/tcpd /usr/local/libexec/imapd

Now, restart inetd.

Prepare SquirrelMail directories

Make sure to change "nogroup" to whatever group Apache will be running as. You can check what that is by looking at the value of the "Group" setting in your Apache main configuration file (probably /etc/httpd/conf/httpd.conf).

# mkdir /usr/local/squirrelmail
# cd /usr/local/squirrelmail
# mkdir data temp
# chgrp nogroup data temp
# chmod 0730 data temp

Unpack SquirrelMail

# cd /usr/local/squirrelmail
# tar --bzip2 -xvf /usr/local/src/downloads/squirrelmail-1.4.17.tar.bz2
# mv squirrelmail-1.4.17 www

Configure SquirrelMail

Run the SquirrelMail configuration utility.

# cd /usr/local/squirrelmail
# www/configure

This is a Perl script, so if you do not have Perl installed, please refer to our notes about how to configure SquirrelMail without shell access.

Select the "D" option and then configure SquirrelMail with the "uw" preset. Also make sure to set the data and attachment directory settings ("/usr/local/squirrelmail/data" and "/usr/local/squirrelmail/temp" respectively) under "4. General Options". Make any other changes as you see fit, select "S" to save and then "Q" to quit.

Configure access to SquirrelMail in Apache

Modify your main Apache configuration file (typically /etc/httpd/conf/httpd.conf) by adding the following:

Alias /squirrelmail /usr/local/squirrelmail/www
<Directory /usr/local/squirrelmail/www>
  Options None
  AllowOverride None
  DirectoryIndex index.php
  Order Allow,Deny
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/*>
  Deny from all
</Directory>
<Directory /usr/local/squirrelmail/www/scripts>
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/images>
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/plugins>
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/src>
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/templates>
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/themes>
  Allow from all
</Directory>
<Directory /usr/local/squirrelmail/www/contrib>
  Order Deny,Allow
  Deny from All
  Allow from 127
  Allow from 10
  Allow from 192
</Directory>
<Directory /usr/local/squirrelmail/www/doc>
  Order Deny,Allow
  Deny from All
  Allow from 127
  Allow from 10
  Allow from 192
</Directory>

Now restart Apache from the command line:

# /usr/local/apache/bin/apachectl graceful

You also might be interested in how to alias different locations to your SquirrelMail installation.

Log into SquirrelMail

Now you should be able to access SquirrelMail by going to http://example.com/squirrelmail.

3.3 Installing SquirrelMail on a hosted service without shell access

This chapter discusses how to install SquirrelMail on a server where you do not have shell access or administrative access.

Requirements

First, check the general SquirrelMail requirements.

Additionally, you should be able to:

• add files to your web server's document directory
• execute PHP scripts (see the wiki page about testing PHP settings).
• PHP scripts should be able to connect to your IMAP, SMTP and any other servers that are used by SquirrelMail.

Optional features:

• Control of PHP settings with .htaccess files
• PHP access to a SQL database.

You will need:

• the address and type of the IMAP server you plan to use
• the address of the SMTP server you plan to use

Installation

SquirrelMail is installed by copying all of its files to the web server. You should be able to do that with a FTP, SFTP or FTP-SSL client program.

Configuration

You need to create a configuration file for SquirrelMail. If you have Perl on your own computer, you can run the SquirrelMail configuration script (conf.pl, found in the config/ directory) on your computer, using it to adjust your configuration, choose save when done, and then upload the resultant config.php file to the web server. Be sure to put this file into the SquirrelMail config/ directory on your web server. You can now skip to the next step below - testing your configuration.

If you don't have Perl on your computer, you'll need to create the configuration file by hand. Make a copy of config_default.php (also found in the config/ directory), naming it config.php, then open it in your favorite text editor or PHP editor (see below). You must save the file as plain text - do not use a word processor's document format. When you're done with it, put it in the SquirrelMail config/ directory on your web server.

Editing the configuration file is fairly easy: the comments in the default configuration file that you are starting with do a good job of explaining what each setting is for. Keep in mind that the configuration file is actually a PHP script and must contain valid PHP syntax. This means that you should only change values that are (usually but not always) in quotes, making sure not to alter anything else. It is especially important that you leave the semicolons at the end of each line. Always save a copy of the original file in case you make a mistake and need to start over.

When editing the configuration file by hand, you don't have to change ALL the settings in the default configuration file, but there are several that are mandatory:

1. Default Domain: This is set in the $domain setting and is the part after the "@" sign in the mail addresses on your mail server. For example:

$domain = 'example.org';

2. Paths to Data and Attachment Directories: These are set in the $data_dir and $attachment_dir settings. These should usually be the full path from the root directory of your hard disk, not a path that is relative to your web or FTP directory. However, it is possible to specify a relative path from the SquirrelMail src/ directory (for example, ../data might work for $data_dir), but this is discouraged in favor of more robust full path specification and placing these directories apart from the SquirrelMail code itself. The web server must have write permission to these directories (your FTP access permissions are not the same as the web server's access permissions). See the comments in the configuration file for more information about setting the correct directory permissions (you may need to ask your hosting service to do this for you). For example:

$data_dir = '/var/lib/squirrelmail/data/';
$attachment_dir = '/var/spool/squirrelmail/attachments/';

3. Address of the IMAP Server: This is set in the $imapServerAddress variable. For example:

$imapServerAddress = 'imap.example.org';

4. IMAP Encryption: You may use encryption for your IMAP connections if desired or necessary. If you don't know what this means, chances are that you may not need it and can skip this step. To do this, you will have to modify the $imapPort and $use_imap_tls settings. For example:

$imapPort = 993;
$use_imap_tls = true;

5. Address of the SMTP Server, SMTP Port and SMTP Encryption Settings: You must set the $smtpServerAddress, $smtpPort and $use_smtp_tls settings. These are similar to the IMAP settings explained above. Encrypted SMTP typically uses port 465, and may not be necessary if you are unaware of whether your SMTP server supports encryption. For example:

$smtpServerAddress = 'smtp.example.org';
$smtpPort = 25;
$use_smtp_tls = false;

6. IMAP Server Settings: Check the file presets.txt in the SquirrelMail doc/ directory to see if your IMAP server type is listed there. If so, adjust the settings in your configuration file according to the ones that match your server type.

7. Optional: It is easier to continue to configure SquirelMail using a web interface (the "administrator" plugin), however this requires that the web server is able to overwrite the configuration file - some hosting environments do not allow this or require you to ask them to do it for you. This can also be a security risk that you may wish to weigh against the trouble of continuing to edit other configuration settings by hand. If you decide to (and are able to) proceed in this fashion, you'll add "administrator" as the first plugin in the configuration file. Find this part of the configuration file:

/**
 * To install plugins, just add elements to this array that have
 * the plugin directory name relative to the /plugins/ directory.
 * For instance, for the 'sqclock' plugin, you'd put a line like
 * the following.
 *    $plugins[0] = 'sqclock';
 *    $plugins[1] = 'attachment_common';
 */
// Add list of enabled plugins here

Just after that, you'll add this line:

$plugins[0] = 'administrator';

Next, you'll need to tell the administrator plugin who the administrator is (so that only you have access to it and your normal users do not). Create a file named admins with your IMAP user name in it and upload it to the SquirrelMail config/ directory. When you have logged in to SquirrelMail (see below), click on the "Options" link at the top of the page. If your user name matches the one that is in admins file, you should now see an "Administration" block on the SquirrelMail options page which can be used to further configure SquirrelMail.

Test your configuration

After you have uploaded config.php to the SquirrelMail config/ directory, go to http://example.com/squirrelmail/src/configtest.php and check if the configuration is correct so far. You'll need to adjust the "example.com" and "squirrelmail" parts to match the location where you installed it. Note that in SquirrelMail versions 1.5.0 and up, if you are accessing configtest.php from any place other than the machine where SquirrelMail is installed, you'll need to make sure $allow_remote_configtest is enabled in your configuration file to do so (or see "11. Tweaks" ==> "7. Allow remote configtest" in the configuration utility). If you do that, be sure to disable it again when you are finished.

Every time you change your configuration file, it is a good idea to re-visit this page to make sure everything is working correctly. This page includes making a test connection to the IMAP server, so make sure it is working correctly and accepting connections.

First login

Go to http://example.com/squirrelmail/src/login.php and try logging in. You'll need to adjust the "example.com" and "squirrelmail" parts to match the location where you installed it. You should use a user name and password that are known to work with your IMAP server.

3.4 Prepackaged SquirrelMail installs

If your operating system distribution provides prepackaged SquirrelMail, it might be a good idea to use that. The drawback is that you probably don't have the latest and greatest version. But on the plus side: the whole installation step is managed for you, it integrates better with the rest of your system and you're provided with security updates automatically.

SquirrelMail provides RPM packages. There are two packaging flavors. Standard package that can be used on RedHat 8.x or later. 7.x.noarch.rpm package is designed for RedHat 7.x systems. Main difference between packages - standard package contains standard Apache configuration file with /webmail/ alias in /etc/httpd/conf.d and different package dependencies. There are other SquirrelMail packages created by RedHat, Fedora, SuSE and other RPM distributions.

Debian packages can be downloaded from the Debian website or you can install them with your favorite Debian package manager. For example: apt-get install squirrelmail. If you use Debian stable and SquirrelMail package is a little bit outdated, you might be able to install newer SquirrelMail package from testing or unstable. This is not guaranteed to work though.

FreeBSD includes two different SquirrelMail packages in their ports collection.