Install SquirrelMail

Update July 2017: SquirrelMail seems to have been abandoned by its developer. I’d strongly consider using Roundcube instead.

So now you have an Ubuntu 12.04 mail server set up with Postfix, Dovecot, virtual users, and a spam filtering system. But you have another problem: your IT department at work won’t let you add your own email accounts to the Outlook mail program they make you use. Furthermore, they don’t want you using your phone in the office, so reading your personal email is a problem. One workaround is a web-based email client like the SquirrelMail web mail system.

SquirrelMail lets you log in and read your personal email like you’d read any other web site. And since you access it using standard software over standard network ports (HTTP and HTTPS, TCP/80 and TCP/443), it’s hard for your employer to block.

This article assumes you have a standard LAMP setup with Apache 2/PHP 5/mysqli running on your server. It also presumes you’re familiar with Apache virtual hosting. If not, you may want to refer to the Apache documentation.

Installing SquirrelMail

Step 1: Installation

$ apt-get install squirrelmail squirrelmail-compatibility

Step 2: Set up an Apache virtual host

Edit the provided /etc/squirrelmail/apache.conf configuration file:

# Uncomment and change this part
<VirtualHost *:80>
  DocumentRoot /usr/share/squirrelmail
  ServerName # the URL where you want SquirrelMail to live

Step 3: Make your SquirrelMail web site accessible

Create a symbolic link to the SquirrelMail config file so Apache knows about it, then restart Apache:

$ ln -s /etc/squirrelmail/apache.conf /etc/apache2/sites-available/
$ a2ensite
$ service apache2 restart

If you don’t want the web interface to be publicly accessible, you can put an .htaccess file in /usr/share/squirrelmail to require a double login.

Step 4: Allow users to change their passwords from the web interface

Since we’re using MySQL to store our email domains and users, we’ll install the change_sqlpass plugin:

$ cd /usr/share/squirrelmail/plugins
$ wget
$ tar -xvzf change_sqlpass-3.3-1.2.tar.gz
$ cd change_sqlpass
$ cp config.php.sample config.php

This allows SquirrelMail to authenticate usenames and passwords against the mail database we created in our Postfix/Dovecot article. This way people can’t log in unless they have a mail account on our server.

Step 5: Set up change_sqlpass for our local database.

Edit /usr/share/squirrelmail/plugins/change_sqlpass/config.php (as usual, I’m only including the settings I changed):

// Change mailuser:mailpass to your local username and password, and change mailserver to your mail database
$csp_dsn = 'mysql://mailuser:mailpass@localhost/mailserver';

// Pretty self-explanatory: how do you query your virtual_users table? 
$lookup_password_query = 'SELECT count(*) FROM virtual_users WHERE email = "%1" AND password = %4';

// Password update, ensure this matches your MySQL virtual_users table
$password_update_queries = array(
   'UPDATE virtual_users SET password = %4 WHERE email = "%1"',
   // 'UPDATE user_flags SET force_change_pwd = 0 WHERE username = "%1"',
   // 'UPDATE users SET crypt_password = %4, force_change_pwd = 0 WHERE username = "%1"',

// In our previous article, we used the MySQL encrypt() function to store passwords; this function does the same
$password_encryption = 'MYSQLENCRYPT';

// Set to a4 to match MYSQLENCRYPT method
$csp_salt_static = '"a4"';

// Comment out csp_salt_query; it won't be used anyway
//$csp_salt_query = '';

Step 6: Configure SquirrelMail for our mail server

Run the /usr/sbin/squirrelmail-configure configuration utility.

  1. Tell SquirrelMail we’re using Dovecot.
    • From the main menu, hit D to set up a pre-defined configuration for specific IMAP servers
    • Type ‘dovecot’ followed by enter
  2. We’re only using IMAP over port 993 with TLS, so specify that.

    From the main menu, hit 2 for server settings, then A for IMAP settings, and ensure you’ve set the following:

    4.  IMAP Server            : localhost
    5.  IMAP Port              : 993
    6.  Authentication type    : login
    7.  Secure IMAP (TLS)      : true
    8.  Server software        : dovecot
    9.  Delimiter              : detect
  3. Now we need to activate the change_sqlpass plugin we just configured.
    • From the main menu, hit 8 for plugin settings
    • Hit 6 to activate compatibility (a change_sqlpass prerequisite)
    • Hit 6 again to activate change_sqlpass
  4. Finally, hit S to save your configuration settings, followed by Q to quit the config utility.

Step 7: Test SquirrelMail

In your web browser, go to the URL you configured in Step 2 and try logging in with one of the virtual usernames and passwords stored in your database. Just for yuks, go to Options and try changing your password to see if you’ve got the change_sqlpass plugin working. If everything works, you’re all set. If something breaks, remember to check your Apache2 error.log and mail.log files.

Step 8: Additional testing with configtest.php.

You can also go to to see any problems with your configuration. By default, access to this file is blocked in /etc/squirrelmail/apache.conf:

  <Files configtest.php>
    order deny,allow
    deny from all
    allow from

To open this file to web access, comment out these two lines and restart Apache:

    #deny from all
    #allow from

Once you’re done testing, you should uncomment these lines and restart Apache to block the configtest.php file again.

Step 9: Store the address books and user preferences in your database (optional)

Install the prerequisites:

$ apt-get install php-db php-pear

Then just follow the very clear directions in the main SquirrelMail documentation to create your database, tables, and data sources using MySQL and the /usr/sbin/squirrelmail-configure utility. I don’t care much about these features so I usually skip this step.

Now you can read your email from anywhere you have web access. Wasn’t that easy?


Leave a Reply

Your email address will not be published. Required fields are marked *