5. Configuring SquirrelMail

SquirrelMail stores interface configuration in config/config.php file. This file can be controlled with SquirrelMail configuration utility config/conf.pl. Default configuration values are stored and documented in config/config_default.php file.

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

5.2 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.3 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.

Requirements

CRAM/DIGEST-MD5
* If you have the mhash extension to PHP, it will automatically
  be used, which may help performance on heavily loaded servers.
  ** NOTE: mhash is optional and no longer a requirement **  (SINCE WHEN?)
* PHP XML extension needed for digest-md5 authentication.

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.4 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.5 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 user@example.com.pref, 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.6 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 users' data storage and won't be able to use database to store users' data.

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 needs the DB database abstraction layer, which is a part of the PHP Extension and Application Repository (PEAR), to provide database backends. 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.

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:

-- Note: Change the SquirrelMail config variable $prefs_user_field in
--       "config/config.php" from the default "user" to "username" since "user"
--       is a reserved word in PostgreSQL.
CREATE TABLE "userprefs" (
   "username" varchar(128) NOT NULL,
   "prefkey" varchar(64) NOT NULL,
   "prefval" text,
   CONSTRAINT "userprefs_pkey" PRIMARY KEY ("prefkey", "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.7 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, or with the Vlogin or Multilogin plugins, or write your own custom server mapping function. These tools allow users to be transparently redirected to their correct mail servers.

Perdition proxy

Perdition is POP and IMAP proxy server, that can redirect users to appropriate mail servers.

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 mapping by a user defined function instead of IMAP server's address. If IMAP server's address is set to map:some_function_name, SquirrelMail functions should use provided username as first function argument and replace mapping with address returned by function.

SquirrelMail provides example map_yp_alias function that uses ypmatch program to get IMAP servers from yellowpages (NIS).

This feature is experimental. If some code does not take into account use of mapping in imap server's address configuration, it might be broken.

5.8 Other configuration issues

Other configuration issues.