SquirrelMail needs a webserver with PHP support. Check
PHP install manual for
information about supported web servers and install procedures.
Some Linux and Unix distributions provide precompiled web server and php packages.
We recommend the following PHP settings:
register_globals off - a dangerous setting, not needed. We do
not release security advisories for issues only exploitable with this
setting on. Note that you can easily enable it only for some legacy
site that may need it and turn it off globally.
magic_quotes_{runtime,gpc,sybase} off - SquirrelMail may work
with any of these 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 - needed if your users want to attach files to
their mails.
safe_mode on or off - safe_mode on is only a tiny bint more
secure, in the SquirrelMail case. There may be some incompatibilities
with some functionality (see
Safe mode).
Install IMAP server
It depends on used email system. Email server needs IMAP service that knows
used email system layout. If you use Unix with standard sendmail server, you
might have to install UW IMAP, Dovecot or other IMAP server, that can use email
stored in /var/spool/mail/ directory. If you use Windows, you might have to
enable 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-dir and attachment dir, outside the webtree (e.g. in /var).
The data-dir (for user prefs) should be owned by the user the webserver
runs as (e.g. www-data). The attachment dir (for uploading files as
attachments) should be file mode 0730 and in the same group as the
webserver.
If you use PHP with safe mode enabled, check chapter about safe mode.
Configure SquirrelMail
Run config/conf.pl from the command line. Use the D option to load
predefined options for specific IMAP servers, and edit at least the
Server Settings and General Options (datadir).
Check your SquirrelMail configuration
Browse to http://example.com/yourwebmaillocation/src/configtest.php
to test your configuration for common errors.
Log into SquirrelMail
Browse to http://example.com/yourwebmaillocation/ to log in.
This chapter covers installation of SquirrelMail on generic Unix or Linux
system. It does not cover installation of operating system or tools required to
install web server or PHP.
Any version numbers used in examples are specific to the time when this
documentation is written. If current version numbers differ, make sure that you
are not using old, obsolete or vulnerable software.
Guide uses UW IMAP server as example. This IMAP server can be used in generic
email setup when incoming mail is stored in /var/spool/mail
directory. If you are planning to use webmail with big number of users or with
bigger mailboxes, consider using different IMAP server and redesign entire email
system.
# cd /usr/local/src
# tar -xzvf /usr/local/src/downloads/httpd-2.0.54.tar.gz
# cd httpd-2.0.54
# ./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-4.3.11.tar.bz2
# cd php-4.3.11
# ./configure --prefix=/usr/local/php \
> --with-apxs2=/usr/local/apache/bin/apxs
# make
# make install
If you configure PHP compilation with --disable-all option, you must add
--enable-session and --with-pcre-regex options.
# cd /usr/local/src
# tar -xzvf /usr/local/src/downloads/imap.tar.Z
Compile UW IMAP
cd /usr/local/src/imap-<someversion>
make port-name EXTRADRIVERS='' SSLTYPE=unix
Replace port-name with name that matches your system. Check Makefile
for possible values. If you haven't installed OpenSSL libraries and headers, use
SSLTYPE=none instead of SSLTYPE=unix.
# 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.5.tar.bz2
# mv squirrelmail-1.4.5 www
Configure SquirrelMail
Start SquirrelMail configuration utility. Configure SquirrelMail with UW
preset. Set data and attachment directories.
Configure access to SquirrelMail in Apache
Modify httpd.conf
Alias /squirrelmail /usr/local/squirrelmail/www
<Directory /usr/local/squirrelmail/www>
Options Indexes
AllowOverride none
DirectoryIndex index.php
Order allow,deny
allow from all
</Directory>
Log into SquirrelMail
After you add alias to SquirrelMail in apache configuration and restart apache,
you should be able to access SquirrelMail by going to
http://your-server/squirrelmail.
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:
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:
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://your-server/path-to-squirrelmail/src/configtest.php
and check if the configuration is correct so far. 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://your-server/path-to-squirrelmail/src/login.php
and try logging in. You should use a user name and password that
are known to work with your IMAP server.
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.
