5. Configuring SquirrelMail

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.

5.1 Configuration files and tools

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 source.

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 SquirrelMail Project.

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 file.

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.

Manual configuration

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.

5.2 Basic configuration

In order to use SquirrelMail you must create a configuration file. Default configuration should adjusted to match your setup. Main things that should be checked are:

• Default domain (2. Server settings > 1. Domain)
• Addresses of IMAP and SMTP servers.
• Type of IMAP server. See next chapter about selecting IMAP server.

You might want to change:

• Organization Preferences (1. Organization Preferences)

Read the chapter Customizing SquirrelMail for more tips on how to make your SquirrelMail installation blend with your site.

5.3 Selecting IMAP server

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 configuration options.

SquirrelMail provides configuration presets for Cyrus, UW, Courier, Exchange, EIMS (Mac OS X), hmailServer, mercury32 and dovecot IMAP servers. See chapter about Presets for more information about server specific settings.

5.4 Authentication

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 methods.

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.

5.5 StartTLS, IMAPS, SSMTP

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).

TLS requirements

• 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 PHP bug #29934.

STARTTLS requirements

• 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.

5.6 Default user preferences

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.

1. Log into your own account (or a test account) and get all your configuration set to what you'd like the defaults to be.
2. 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.
3. 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.
4. 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 once.

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:

show_html_default=1
custom_css=sans-10.css

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

Forced preferences

If you want to force some preference settings for all your users, it's possible when using 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 functions/db_prefs.php.

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.

5.7 Using database backends

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 above.

If you do not have PDO support, SquirrelMail will need the DB database abstraction layer, which is a part of the PHP Extension and Application Repository (PEAR) to provide database support. In such cases, make sure that your database is compatible with PEAR DB, that PEAR is installed, and that the directory containing PEAR is in PHP's include path (PHP configuration variable: include_path).

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 squirreluser@localhost 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' =
OLD_PASSWORD('sqpassword'); 

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:sqpassword@localhost/squirrelmail or pgsql://squirreluser:sqpassword@localhost/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,
  label varchar(255),
  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"
  ("firstname", "lastname");

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 administration plugin.

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 not recommended.

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,
   "prefval" text,
   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.

Primary keys

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 sizes.

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.

5.8 Using more than one IMAP server

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 proxy

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.

Multilogin plugin

Found in the main SquirrelMail plugins repository, this plugin allows the manual selection of login server on the login page.

sqimap_get_user_server

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 Pages).

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.