SquirrelMail

This page is slowly getting out of date since I no longer actively use SquirrelMail (I have switched to Roundcube). The information in here was last verified to be correct for SquirrelMail 1.4.21 on a Debian system.

Debian package

The following Debian packages need to be installed:

squirrelmail

Web server configuration

Package configuration

The squirrelmail package installs the file

/etc/squirrelmail/apache.conf

This file contains most of the web server configuration necessary to run the software. It needs to be manually linked into the Apache config directory:

ln -s /etc/squirrelmail/apache.conf /etc/apache2/conf.d/squirrelmail.conf

Virtual host configuration

I have assigned an Apache vhost to SquirrelMail that is accessible under http://mail2.herzbube.ch/ (previously mail.herzbube.ch, but this is now taken by Roundcube). These are the configuration details:

# --------------------------------------------------------------------------------
# mail2.herzbube.ch
# --------------------------------------------------------------------------------
<VirtualHost *:80>
  ServerName mail2.herzbube.ch
  ServerAdmin webmaster@herzbube.ch
  ErrorLog /var/log/apache2/herzbube.ch/error.log
  CustomLog /var/log/apache2/herzbube.ch/access.log combined

  DocumentRoot /usr/share/squirrelmail
  Alias /robots.txt /var/www/herzbube.ch/mail.herzbube.ch/robots.txt

  <Directory /usr/share/squirrelmail>
    Require all granted
    <IfModule mod_php5.c>
      php_admin_flag engine on
      php_value memory_limit 64M
      php_value upload_max_filesize 10M
    </IfModule>
  </Directory>
  <Directory /var/www/mail.herzbube.ch/>
    Require all granted
  </Directory>
</VirtualHost>

# --------------------------------------------------------------------------------
# SSL Host
# --------------------------------------------------------------------------------
<IfModule mod_ssl.c>
  <VirtualHost *:443>
    ServerName mail2.herzbube.ch
    ServerAdmin webmaster@herzbube.ch
    ErrorLog /var/log/apache2/herzbube.ch/error.log
    CustomLog /var/log/apache2/herzbube.ch/access.log combined

    DocumentRoot /usr/share/squirrelmail
    Alias /robots.txt /var/www/herzbube.ch/mail.herzbube.ch/robots.txt

    <Directory /usr/share/squirrelmail>
      Require all granted
      <IfModule mod_php5.c>
        php_admin_flag engine on
        php_value memory_limit 64M
        php_value upload_max_filesize 10M
      </IfModule>
    </Directory>
    <Directory /var/www/mail.herzbube.ch/>
      Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile    /etc/ssl/certs/herzbube.ch.crt
    SSLCertificateKeyFile /etc/ssl/private/herzbube.ch.key.unsecure
    SSLCertificateChainFile /etc/ssl/certs/cacert.org.certchain
    SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
  </VirtualHost>
</IfModule>

Note: The memory required by SquirrelMail increases with the size of email attachments. The current value is sufficient for day-to-day use, but sometimes I encounter attachments that require massive amounts of memory. I have not yet figured out how to handle this gracefully/dynamically.

Configuration

SSL/TLS

Unfortunately SquirrelMail does not support the STARTTLS command, therefore SquirrelMail must connect to the IMAP server on port 993.

Step-by-step configuration

To configure squirrelmail you have to execute

cd /etc/squirrelmail
./conf.pl

These are the settings to make:

• Server settings
  • domain = herzbube.ch
  • IMAP port = 993 (143 is for unencrypted traffic, or 1443 if imapproxy is used)
  • server software = courier
  • secure IMAP (TLS) = yes
• Folder defaults
  • default folder prefix = INBOX. (the "." is appended automatically; note: this is necessary since SM 1.5 in order to make the "INBOX" folder list entry a clickable link)
  • Trash/Sent/Drafts folder = Trash/Sent/Drafts (necessary since SM 1.5)
  • default unseen notify = 3 ("on all folders")
  • default unseen type = 2 ("unseen and total messages")
• General Options
  • data directory = /var/lib/squirrelmail/data (root/www-data 730)
  • attachment directory = /var/spool/squirrelmail/attach (root/www-data 730)
  • allow server thread sort = yes
  • allow server-side sorting = yes
• Themes
  • default theme = blue steel
• Address books
  • change LDAP servers, then add a host with the following details
    • host = localhost
    • base DN = ou=addressbook,dc=herzbube,dc=ch
    • bind DN = cn=readonly-addressbook,ou=users,dc=herzbube,dc=ch
    • bind password = secret
      • Note: /etc/squirrelmail/config.php stores the password in clear text, therefore the file needs to be protected

chown root:www-data /etc/squirrelmail/config.php
chmod 640 /etc/squirrelmail/config.php

• Plugins
  • add these plugins
    • calendar
    • message_details
    • info
  • remove these plugins
    • sent_subfolders

Plugins

General instructions for installing a plugin

• Extract the plugin files (first move aside an already existing plugin folder if you are upgrading from an earlier version):

cd /usr/share/squirrelmail/plugins/
tar xfvz /var/archive/squirrelmail/foobar.tar.gz

• go the newly created plugin directory, read the README and/or INSTALL file and perform any necessary manual changes
• execute /etc/squirrelmail/conf.pl and activate the plugin under item 8

To Patch Or Not To Patch

A lot of plugins require SquirrelMail to be patched. I prefer not to use these plugins because it breaks a smooth upgrade of the Debian package. I already suffer enough from repeatedly applying my own LDAP patch to abook_ldap_server.php.

compatibility

Currently installed:

• version = 2.0.14
• source = Debian package "squirrelmail-compatibility"

Notes:

• in case this plugin is installed manually, a patch must be applied for SquirrelMail < 1.5.1 (SM 1.5.1 and above should automatically load the plugin); run the patch from the plugin directory, i.e.

cd /usr/share/squirrelmail/plugins/compatibility
patch -p0 < patches/compatibility_patch-1.4.10.diff 

• the plugin does not need to be activated in conf.pl, unless the "Plugin updates" plugin is used

delete_move_next

Currently installed:

• version = 3.0
• source = Debian package "squirrelmail"

Notes:

• no configuration necessary, just activate the plugin
• the plugin is enabled for every user by default, if a user does not want the plugin she can disable it under "display preferences"

gpg

Currently installed:

• version = 2.1
• source = manual download

Notes:

• no configuration necessary, just activate the plugin
• local changes could be made to gpg_local_prefs.txt
• version 2.1 fixes the conflict with attachment_doc (version 2.0 displayed the following message when an attachment was viewed: "unable to define SM_PATH in GPG Plugin setup.php")
• it appears that the plugin is broken these days; see Bugzilla issue 48 for details

attachment_doc

I don't use this plugin anymore, because it didn't work very well in the first place, plus it requires too many dependencies to be installed.

Previously installed:

• version = 1.2
• source = manual download

Notes:

• requires the Debian package wv to display MS Word file attachments
• requires the Debian package pdftohtml to display .pdf file attachments
• requires another Debian package to display .sxw (OpenOffice) file attachments; I don't know the package name (the plugin README refers to it as php-xml), but the package seems to be already installed
• inside the include directory: copy config.php.sample to config.php, then perform the following changes
  • $bindir = "/usr/bin";
  • $pdftohtmlcmd = "cd $dirname; $bindir/pdftohtml -q -c -noframes $pdfname $htmlname";
• the output directory ($dirname inside config.php) requires read/write perimissions for the user that the web server runs as:

chown www-data:www-data tmp
chmod 755 tmp

Note 1: attachment_doc 1.2 conflicts with version 2.0 of the gpg plugin. Version 2.1 of the gpg plugin fixes the problem.

Note 2: Installing the wv package leads to a series of other Debian packages being installed, among them the GTK library, but also various other X11 libraries. This is the price for comfort :-(

variable_sent_folder

Currently installed:

• version = 0.4
• source = manual download

Notes:

• no configuration necessary, just activate the plugin

listcommands

Currently installed:

• version = SquirrelMail Core
• source = Debian package "squirrelmail"

Notes:

• no configuration necessary, just activate the plugin

fortune

Currently installed:

• version = ?
• source = Debian package "squirrelmail"

Notes:

• requires the Debian package fortune-mod for the binary /usr/games/fortune
• no configuration necessary, just activate the plugin
• the plugin is disabled for every user by default, if a user wants the plugin she can enable it under "display preferences"

ldapquery

Currently installed:

• version = 2.0
• source = manual download

Modify config.php as follows:

$ldq_authreqd = true;
$ldq_attributes = array ('cn','sn','givenname','o',
                         'street','l','postalcode',
                         'homePhone','mobilePhone','workPhone','otherPhone',
                         'mail', 'labeleduri', 'description');
$ldq_searchobjs = array ('addressbookEntry','*');
$ldq_searchattrs = array ('cn','mail','location','description');

selectrange

Currently installed:

• version = 3.7.1
• source = manual download

Notes:

• no configuration necessary, just activate the plugin
• the user can change settings under "display preferences"

show_headers

Currently installed:

• version = 1.3
• source = manual download

Notes:

• no configuration necessary, just activate the plugin
• the user can change settings under "display preferences"

mark_read

Currently installed:

• version = 2.0.1
• source = manual download

Notes:

• no patch necessary for SquirrelMail >= 1.4.2
• no configuration necessary, just activate the plugin
• the user can change settings on the "Folders" page

advanced_settings

Currently installed:

• version = 1.2.1.sm
• source = manual download

Notes:

• no configuration necessary, just activate the plugin
• the user can change settings on the "Options->Advanced settings" page

quicksave

Currently installed:

• version = 2.4.2
• source = Debian package "squirrelmail-quicksave"

Notes:

• requires the compatibility plugin (>= 2.0.7)
• no configuration necessary, just activate the plugin
• the user can change settings on the "Options->Display preferences" page
• read the INSTALL file for upgrade instructions (usually none required)

smime

Currently installed:

• version = 0.7
• source = manual download

Notes:

• before activating the plugin, inside the plugin directory, copy the file config_example.php to config.php
• read the INSTALL file for upgrade instructions (usually none required)
• if a message is displayed that this plugin can handle (those that are sent in the "multipart/signed" mime format), the plugin will display a header labelled "S/MIME signed by" followed by the signer's name and an indicator whether or not the signature could be verified ("verified" if verification was possible; I have not yet made a test for the negative case); in addition, the plugin displays links that let you view and download the certificate

secure_login

Currently installed:

• version = 1.4
• source = Debian package "squirrelmail-secure-login"

Notes:

• no configuration necessary, just activate the plugin
• I have started to use this plugin instead of show_ssl_link because it enforces SSL login - I have become somewhat paranoid, and I sometimes forget to switch to SSL when I access SquirrelMail from outside of my LAN

spam_buttons

Currently installed:

• version = 2.3
• source = Debian package "squirrelmail-spam-buttons"

Notes:

• manual configuration in /etc/squirrelmail/spam-buttons-config.php

$sb_spam_header_name = 'X-Spam-Status';
$sb_spam_header_value = '/^Yes/i';
$sb_not_spam_header_name = 'X-Spam-Status';
$sb_not_spam_header_value = '/^No/i';
$sb_auto_create_destination_folder = 1;
$sb_report_spam_by_move_to_folder = 'INBOX.Junk.Training-spam';
$sb_report_not_spam_by_move_to_folder = 'INBOX.Junk.Training-ham';

• the user can change settings on the "Options->Display preferences" page

empty_folders

Currently installed:

• version = 2.0.1
• source = manual download

Notes:

• no configuration necessary, just activate the plugin
• the user can change settings on the "Folders" page

Plugins that can be used from SM 1.5 onwards

With SM 1.4, the following plugins require that an original SM file is patched. With SM 1.5 no such patch is necessary and the plugin can be used just like that:

• reply_buttons
• custom_from

Plugins that should be considered in the future

• update
  • installation seems pretty complex
• vlogin
  • too complicated for now

Don't use the following plugins

• show_ssl_link
  • must be manually downloaded
  • requires the compatibility plugin
  • no configuration necessary, just activate the plugin
  • displays a link on the login page when the page is accessed using regular HTTP; the link can be clicked to switch to an SSL encrypted connection
  • disabled because these days I prefer the secure-login plugin which enforces SSL
• sent_subfolders
  • pre-installed by the Debian squirrelmail package
  • no configuration necessary, just activate the plugin
  • the plugin is disabled for every user by default, if a user wants the plugin she can enable it under "display preferences"
  • places mails in a sub-folder of "Sent" depending on the month, quarter or year the message was sent
  • disabled because not useful enough

LDAP addressbook

By default squirrelmail performs a search in the cn attribute of LDAP entries. I want to extend this search so that it also includes the description attribute, because I store information there that identifies groups of people.

For this we have to change the file /usr/share/squirrelmail/functions/abook_ldap_server.php: where the expression

"cn=$expr"

appears, it must be replaced by

(|(cn=$expr)(l=$expr)(description=$expr))

Note about the attributes that an LDAP search returns, and the fields that the attributes are mapped to:

• dn (nickname)
• o (label [if ou is empty])
• ou (label)
• sn (lastname [surname])
• givenname (firstname)
• cn (name [fullname])
• mail (email)
• telephonenumber (phone)

Upgrade of Debian package

Currently the following patches need to be repeated when the SquirrelMail Debian package is upgraded:

• my own LDAP patch (see above)

Compatibility plugin patch

Before the compatibility plugin was wrapped in its own Debian package, a patch for that plugin had also to be applied after each update of the SquirrelMail package. This is no longer the case, but I keep the following, now obsolete, information for historical sake.

Without the compatibility plugin patch, SquirrelMail may display the following error message (at least this was the case after upgrading to SM 1.4.15):

Cannot redeclare sqauth_read_password()

Note: You may need to apply a patch whose file name does not exactly match the SquirrelMail version that is installed. For instance, with SM 1.4.15 and the compatibility plugin at version 2.0.13, I had to apply the patch file compatibility_patch-1.4.11.diff (although I would have expected to find a patch file named compatibility_patch-1.4.15.diff).