Even though the size of this documentation might indicate otherwise,
SquirrelMail is quite easy to configure. On the other hand, mailsystems are
quite complicated for a beginner so a few configuration tips might be useful.
SquirrelMail configuration is file based. If you've installed SquirrelMail
directly from source you'll find the configuration file in
config/config.php, but if you're using a SquirrelMail package from your
OS distribution the actual configuration file may be located somewhere else
(such as /etc/) - usually with a symbolic link from
config/config.php. Read the documentation that came with the
distribution package to find out more about OS distribution specific details.
The rest of these instuctions assumes that you've installed SquirrelMail from
There are three ways to change the SquirrelMail configuration file: using the
configuration tool, using the Administrator plugin, or editing the configuration
file manually. The first of these ways is the one recommended by the
Please note that if there are users logged in when the configuration is changed,
those users might not be affected by the changes until after they have logged
out. This is a side effect of the caching of data for logged in users.
The configuration tool
Included in the SquirrelMail distribution is a Perl script, located at
config/conf.pl, which helps when creating or editing the configuration
The first thing to do when configuring from scratch is to choose an IMAP server
using "D. Set pre-defined settings for specific IMAP servers". This will change
SquirrelMail configuration to match a default installation of the IMAP server
of your choice.
The next step is to go through all the menu selections and set the configuration
options to the values most suitable for your installation. Each configuration
option is described in the tool to help you make the right choices.
Even if you don't have Perl accessible at the computer where SquirrelMail is
insalled, you can use config/conf.pl if you have access to a computer
with Perl installed. Just copy config/conf.pl to the computer with
Perl, use it to create a configuration file, and then upload the configuration
file to config/config.php in your SquirrelMail installation.
Note that some OS distributions have their own tools to configure SquirrelMail,
which you might use instead (Debian, Ubuntu, and other Debian derived
distributions have "squirrelmail-configure", which can be run even outside the
SquirrelMail installation directory). Read the documentation that came with the
distribution package to find out more about OS distribution specific details.
The Administrator plugin
SquirrelMail also includes the Administrator plugin as part of the distribution.
Some administrators considers this to be a more user-friendly tool than the Perl
script. It can be used instead of config/conf.pl, but is less safe
since it requires the web server to have write access to the configuration file.
Read plugins/administrator/INSTALL for instructions on how to install
it and set up the administrator user.
Once the Administrator plugin is configured and enabled, the SquirrelMail
configuration can be changed using a web interface within SquirrelMail. Log in
as a user with assigned administrator privileges and click "Options >
Administration". The Configuration Administrator page will open, providing you
with options to configure SquirrelMail (for instance enabling and disabling
plugins). When done, click "Save" to update the configuration at the server.
Even though you can use the Administrator plugin in all cases where
documentation suggests config/conf.pl, there's one exception to the
rule: the first installation. Since the Administrator plugin only can be used
from within SquirrelMail, you have to configure SquirrelMail using the
configuration tool or manually the first time.
Since config/config.php is a PHP file, SquirrelMail can also be
configured manually with the editor of your choice. A sample configuration is
provided in config/config_default.php, so copy
config/config_default.php to config/config.php and then edit
config/config.php to match your installation. The configuration options
are documented within the file to help you make the right choices. Note that
manually configuring SquirrelMail needs you to follow the PHP syntax. Make sure
that there is no trailing
end of line character and save the configuration.
Some IMAP servers use specific IMAP folder layout or need some tweaks in IMAP
client's configuration. In order to set SquirrelMail according to your server's
requirements you might have to set more than 10 different SquirrelMail
options. SquirrelMail simplifies modification of these settings by providing
special configuration command. If you select D command in SquirrelMail
configuration utility, you will be asked to select your IMAP server and all
settings will be adjusted according to selected IMAP server.
For example, correct combination of SquirrelMail settings can hide INBOX prefix
in courier IMAP server. Value that is set in IMAP "Server software"
configuration option can fix search issues in EIMS or hmailServer, provide
workarounds for some folder subscription errors in mercury32 IMAP server, but it
does not affect system folder names, folder prefix, delimiter and other specific
SquirrelMail provides configuration presets for Cyrus, UW, Courier, Exchange,
EIMS (Mac OS X), hmailServer, mercury32 and dovecot IMAP servers. See chapter
Presets for more information about server
Next to plain text logins for IMAP and SMTP, SquirrelMail supports the CRAM-MD5
and DIGEST-MD5 authentication mechanisms. It is possible to use different
methods for both IMAP and SMTP. Unless the administrator changes the
authentication methods, SquirrelMail will default to the "classic" plain text
POP before SMTP
Some SMTP servers require POP3 authentication before accepting messages to
external recipients. SquirrelMail supports POP before SMTP. You can
enable it in SMTP server settings "POP before SMTP" option. SquirrelMail
uses same username and password that was used for IMAP authentication.
Using different username for SMTP relaying
If SMTP server uses different username and password for authentication,
since 1.5.1 version SquirrelMail can use one username and password for entire
SquirrelMail installation. They can be set in config/config_local.php$smtp_sitewide_user and $smtp_sitewide_pass configuration variables.
If you use older SquirrelMail version and want to use single user/password
for SMTP authentication, you might have to install local SMTP server and set it
as smart relay. See SMTP server's documentation about email relaying through
other SMTP server.
SquirrelMail is able to connect to IMAP and SMTP servers that use TLS.
Since 1.5.1 version SquirrelMail is able to connect to IMAP and SMTP
servers that use STARTTLS (which is different from TLS).
PHP 4.3.0 or higher
The server you wish to use TLS on must have a dedicated port listening
for TLS connections.
If you use PHP 4.3.x, OpenSSL support must be compiled staticly. See
SquirrelMail 1.5.1 or higher
PHP 5.1.0 or higher with stream_socket_enable_crypto() function support.
IMAP or SMTP server with STARTTLS extension support.
TLS can be enabled in SquirrelMail configuration utility, "Server settings"
section. If you want to use IMAP with TLS, you should select command that
updates IMAP settings, enable TLS in "Secure IMAP (TLS)" option and set
secure IMAP port in "IMAP Port" option. Secure IMAP servers use tcp 993
port by default. If you want to use SMTP with TLS, you should select command
that updates SMTP settings, enable TLS in "Secure SMTP (TLS)" option and
set secure SMTP port in "SMTP Port" option. Secure SMTP servers use tcp 465
port by default.
STARTTLS extensions are enabled by selecting use of them in "Secure IMAP
(TLS)" or "Secure SMTP (TLS)" selection menu. These extensions
work by enabling encryption on plain text service ports. IMAP and SMTP ports
should be set to standard plain text IMAP and SMTP ports.
Note: There is no point in using TLS if your IMAP server is localhost. You need
root to sniff the loopback interface, and if you don't trust root, or an attacker
already has root, the game is over. You've got a lot more to worry about beyond
having the loopback interface sniffed.
If SquirrelMail is configured to use file-based preferences, default preferences
are stored in your data directory in a file called default_pref. As you add
plugins to your SquirrelMail installation, you might want to configure some of
them on your own account and then propagate those settings to all of your users.
Or you may simply want to change the default theme, etc. This is what you need
to do to accomplish that.
Log into your own account (or a test account) and get all your
configuration set to what you'd like the defaults to be.
Open the preference file related to the account you used. It's in the
data directory and looks something like username.pref or
[email protected], depending on what your usernames look like.
Find the relevant settings. Most plugin settings are identified by the
plugin's name being the first thing on the line. Note that some plugins
can have multiple setting lines.
Copy those settings into the default_pref file in the data
directory. If you want to duplicate all settings, you can copy the
entire file, but be careful that nothing with your name, mail address,
or other personal items get copied.
Note that the default_pref file works only for users that don't have an
existing preference file (i.e. new users which haven't logged in yet). If you
want to add preferences to existing user accounts, you should edit (manually or
by a script) their existing preference files. It's not recommended to delete the
preference files, since that will revert all preferences edited by your
users, including such settings as their real names.
An example script
TODO: Write a better script (in Perl) providing this functionality and include it the SquirrelMail distribution.
This is a simple shell solution to edit more than one user preference file at
If you, for example, want mails to display as HTML by default and change the
font to a custom one by using CSS, create a file containing:
Save the file as /tmp/default.pref, change to the data directory, and
run the following command from the prompt:
for l in `ls *.pref`; do cat /tmp/default.pref >> $l; done
If you want to force some preference settings for all your users, it's possible
the Forced Preferences plugin. It works regardless of if the users have set their
own preferences or not.
Default database backend preferences
If you're using a database base backend, the default settings are stored in the
array $default, in the beginning of the dbPrefs class in
TODO: Having to edit the SquirrelMail source is bad. It should be possible to use default_pref for database backends as well, but unfortunately that's currently not a SquirrelMail feature.
On sites with many users you might want to store your user data in a database
instead of in files. SquirrelMail can be configured to do this. Note, however,
that some SquirrelMail plugins are designed to use different files for user
data storage and won't be able to use the database, so it is strongly
recommended to make sure you have a correctly configured data directory even
when using a database as explained here.
Methods for storing both personal address books and user preferences in a
database is included as a part of the distribution.
Configuring PEAR DB
SquirrelMail comes with PDO support for connecting to most databases, so
PEAR DB support is not required unless your version of PHP does not
include PDO. PDO should come preinstalled with PHP version 5.1 and
Note that some systems include PEAR with PHP, have PEAR and PHP as separate
packages, or comes without a pre-packaged version of PEAR thus forcing you to
install it manually. Check your system documentation to find out the details.
Creating the database
First you need to create a database and a database user with access to
SELECT, INSERT, UPDATE, and DELETE in that database. For
MySQL you would normally do something like:
mysql> CREATE DATABASE squirrelmail;
mysql> GRANT select,insert,update,delete ON squirrelmail.*
TO [email protected] IDENTIFIED BY 'sqpassword';
Note that MySQL changed its password handling in 4.1, so you might need to force
the password to be in the older form. See
the MySQL 4.1 manual for more information.
mysql> SET PASSWORD FOR 'squirreluser' =
Constructing a data source name
Both the address books and the preferences need to be configured with a data
source name (DSN). The DSN should look something like
mysql://squirreluser:[email protected]/squirrelmail or
pgsql://squirreluser:[email protected]/squirrelmail. See the
PHP Pear DB manual for more details about DSN syntax. SquirrelMail's PDO support uses the same
DSN syntax as Pear DB.
When including a sensitive password in your DSN, please make sure that you
tighten the permissions on config/config.php accordingly, so untrusted
users can't read it.
Storing address books in the database
Create a table for the address books. The table structure should be similar to
this for MySQL:
CREATE TABLE address (
owner varchar(128) DEFAULT '' NOT NULL,
nickname varchar(16) DEFAULT '' NOT NULL,
firstname varchar(128) DEFAULT '' NOT NULL,
lastname varchar(128) DEFAULT '' NOT NULL,
email varchar(128) DEFAULT '' NOT NULL,
PRIMARY KEY (owner,nickname),
KEY firstname (firstname,lastname)
and similar to this for PostgreSQL:
CREATE TABLE "address" (
"owner" varchar(128) NOT NULL,
"nickname" varchar(16) NOT NULL,
"firstname" varchar(128) NOT NULL,
"lastname" varchar(128) NOT NULL,
"email" varchar(128) NOT NULL,
"label" varchar(255) NOT NULL,
CONSTRAINT "address_pkey" PRIMARY KEY ("nickname", "owner")
CREATE UNIQUE INDEX "address_firstname_key" ON "address"
Don't forget to configure SquirrelMail with the DSN and the table name. This can
be done using either the SquirrelMail configuration utility or via the
The global address book uses same table format as the personal address books.
You can even use same table if you don't have a user named "global", but that's
Storing preferences in the database
Create a table for the preferences. The table structure should be similar to
this for MySQL:
CREATE TABLE userprefs (
user varchar(128) DEFAULT '' NOT NULL,
prefkey varchar(64) DEFAULT '' NOT NULL,
prefval BLOB DEFAULT '' NOT NULL,
PRIMARY KEY (user,prefkey)
and for PostgreSQL:
CREATE TABLE "userprefs" (
"user" varchar(128) NOT NULL,
"prefkey" varchar(64) NOT NULL,
CONSTRAINT "userprefs_pkey" PRIMARY KEY ("prefkey", "username")
-- Note: "user" is a reserved keyword in PostgreSQL and it could cause
-- problems when it is used as a column name as above. SquirrelMail
-- knows about this issue and should work OK with "user", but if you
-- decide to change it to something else (such as "username"), you'll
-- also need to change the SquirrelMail config variable $prefs_user_field
-- in "config/config.php" to match (or use the configuration tool,
-- 9. Database --> 5. Field for username).
Note the difference in the table column definitions between the MySQL and the
PostgreSQL structures above: the first column in the MySQL command is "user" and
for PostgreSQL it is "username". The default config.php file is configured
for the MySQL case, so you'll get a syntax error if you try to use the above
statements literally and don't account for the different column name.
Don't forget to configure SquirrelMail with the DSN, the table name, and the
field names. This can be done using either the SquirrelMail configuration
utility or via the administration plugin.
You must set primary keys correctly. If keys are not set correctly,
database entries might be duplicated when users change their preferences.
Oversized field values
Database fields have size limits. Preference table example sets 128
character limit to owner field, 64 character limit to preference key
field and 64KB (database BLOB field size) limit to value field.
If interface tries to insert data without checking field limits, it
can cause data loss or database errors. Table information functions
provided by Pear DB libraries are not accurate and some database
backends don't support them. Since 1.5.1 SquirrelMail provides
configuration options that set allowed field sizes.
If you see oversized field errors in your error logs - check your
database structure. Issue can be solved by increasing database field
If you want to get more debugging information - check setKey() function
in dbPrefs class. Class is stored in functions/db_prefs.php
Converting files to database
A conversion tool called flat2sql.pl is included since SquirrelMail 1.5.1.
It's also possible to download the lastest version from the
repository. flat2sql.pl converts the existing files to a number of
SQL statements, that can be used to insert the data into the database.
SquirrelMail is designed to work with one IMAP server. If you want to use the same
SquirrelMail installation with multiple IMAP servers, you should be able to
implement this with Perdition mail proxy, with the Login Manager (vlogin) or
Multilogin plugins, or by writing your own custom server mapping function. These
tools allow users to be transparently redirected to their correct mail servers.
In the future, SquirrelMail will natively provide users with the ability to
check mail on multiple IMAP servers during one login session (some plumbing
for this feature has been added for this into version 1.5.2, but full support
is not yet implemented).
Perdition is POP and
IMAP proxy server, that can redirect users to appropriate mail servers.
Login Manager (vlogin) plugin
Found in the main SquirrelMail plugins repository, this plugin helps manage
and manipulate usernames given at login time, and allows the use of different
SquirrelMail settings (such as login page image, or IMAP server) for each
domain, each user, or each user group.
Found in the main SquirrelMail plugins repository, this plugin allows the
manual selection of login server on the login page.
SquirrelMail can use a custom mapping provided by a user-defined function
instead of the IMAP server address in the main configuration file. If the
IMAP server address is set to map:some_function_name, SquirrelMail
will call that function (e.g., "some_function_name") to determine what IMAP
server address to use, passing the username as the first argument. The
function is expected to return the IMAP server address for that username.
SquirrelMail provides an example function called map_yp_alias that
uses the ypmatch program to get the IMAP server address from NIS (Yellow
This feature is experimental. If code somewhere in SquirrelMail or in a plugin
does not take into account the use of this custom mapping, it will break.