Raspberry Pi Email Server Part 3: Squirrelmail

Squirrelmail Logo

This is the third part of a five part tutorial that will show you how to install a full featured email server on your Raspberry Pi. This tutorial covers how to set up Webmail with Squirrelmail.

The parts are:
The Introduction & Contents Page (read first)
Raspberry Pi Email Server Part 1: Postfix
Raspberry Pi Email Server Part 2: Dovecot
Raspberry Pi Email Server Part 3: Squirrelmail
Raspberry Pi Email Server Part 4: Spam Detection with Spamassassin
Raspberry Pi Email Server Part 5: Spam Sorting with LMTP & Sieve

Installing Apache

If you don't already have apache installed (you might if you've followed my wordpress tutorial), then install it now.

sudo apt-get update
sudo apt-get install apache2

Enable the SSL apache module so that you can use HTTPS:

sudo a2enmod ssl

There are some "pre-made" virtualhost configurations that come with apache. This command will enable the "default-ssl" virtualhost, by creating a symbolic link from /etc/apache2/sites-available/default-ssl to /etc/apache2/sites-enabled/default-ssl:

sudo a2ensite default-ssl

Now reload apache to make the changes take effect:

sudo service apache2 reload

If you type the IP address or hostname of the pi into a web browser now, you should see the default Apache test page:


If you try the https version, you'll get a certificate error because you are using a self-signed SSL certificate. If you like, you can follow my CAcert tutorial to get a free SSL certificate for your domain, or you can just store an exception for the certificate and generate a proper one later.


That's it for Apache. If you want to know more about setting up Apache for multiple websites, subdomains, and SSL configurations, I suggest you read my tutorial explaining Apache's VirtualHost files.

Installing Squirrelmail

Now we need to install squirrelmail:

sudo apt-get update
sudo apt-get install squirrelmail

The basic configuration for squirrelmail is really easy, and can be done with the setup script. To run the script, use this command:

sudo squirrelmail-configure

Squirrelmail configuration menu

Choose “D” for pre-defined settings

Choose pre-defined server configuration

Now type “dovecot” and hit enter

Accept pre-defined configuration for use with Dovecot

Press enter to continue, then save and quit (press Q and save when prompted, or press S then Q).

The configuration script creates a configuration file for apache in /etc/squirrelmail/apache.conf. You need to create a symbolic link so that Apache2 will load your Squirrelmail apache configuration file when it starts up.

On Raspbian Wheezy, the command is:

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

On Raspbian Jessie, the apache configuration directory structure is more like ubuntu, with separate folders for configuration files that are available and files that are enabled. This command will create a symlink from the directory where enabled configuration is stored, to squirrelmail's apache configuration file:

sudo ln -s /etc/squirrelmail/apache.conf /etc/apache2/conf-enabled/squirrelmail.conf

On a related note, there's a convenience command a2enconf that works similarly to a2ensite: it creates a symlink from the conf-available directory to the conf-enabled directory. You should use this in situations where config already exists in conf-available, e.g. sudo a2enconf squirrelmail would create a symlink for a file called squirrelmail.conf.

Now reload Apache one more time so that it reads the config file we just symlinked:

sudo service apache2 reload

Now visit the IP address or hostname of your Pi again, but add /squirrelmail to the path, e.g., you should see the login page:


The squirrelmail configuration file just adds an alias that should affect every virtualhost, so if you install a wordpress site or something like that on your pi, you will be able to get to the squirrelmail login page by visiting yourdomain.com/squirrelmail.

Redirect http to https for secure login

Since you don't want to send your login details and confidential information over the internet without SSL, it's best to redirect all http URLs to https.

The default squirrelmail apache configuration file at /etc/squirrelmail/apache.conf contains some rewrite rules we can use, we just need to uncomment them. Open the file and uncomment the lines by removing the # at the start of each so that it looks like this:

<IfModule mod_rewrite.c>
  <IfModule mod_ssl.c>
    <Location /squirrelmail>
      RewriteEngine on
      RewriteCond %{HTTPS} !^on$ [NC]
      RewriteRule . https://%{HTTP_HOST}%{REQUEST_URI}  [L]

This configuration makes sure that the rewrite and ssl modules are enabled, and does nothing if they aren't. We already enabled the ssl module earlier, so all we need to do now is enable the rewrite module:

sudo a2enmod rewrite

And reload Apache:

sudo service apache2 reload

Now if you visit the HTTP page, you should be redirected to HTTPS.

Optional: Configuring Apache to serve Squirrelmail on a subdomain

If you would like to move the login page to the root of your domain (i.e. so that yourdomain.com would serve the login page for squirrelmail), or if you would like to serve it on a subdomain like mail.yourdomain.com, you can edit the configuration file. If not, you can skip this section.

By default, this line in /etc/squirrelmail/apache.conf means that http://www.yourdomain.com/squirrelmail will load squirrelmail:

Alias /squirrelmail /usr/share/squirrelmail

If you would rather have webmail on a subdomain like mail.yourdomain.com then you could edit the /etc/squirrelmail/apache.conf file to look like this (comment out the rest):

<VirtualHost *:80>
  DocumentRoot /usr/share/squirrelmail
  ServerName mail.yourdomain.com

<Directory /usr/share/squirrelmail>
  Options FollowSymLinks
  <IfModule mod_php5.c>
    php_flag register_globals off
  <IfModule mod_dir.c>
    DirectoryIndex index.php

  # access to configtest is limited by default to prevent information leak
  <Files configtest.php>
    order deny,allow
    deny from all
    allow from

Note that if you want to serve mail on a subdomain, then that subdomain needs a DNS record, so edit your records with your DNS provider accordingly.

However, the virtualhost code above only does HTTP. You also want an HTTPS virtualhost for the subdomain on port 443:

<IfModule mod_ssl.c>
<VirtualHost *:443>
  DocumentRoot /usr/share/squirrelmail
  ServerName mail.yourdomain.com

<Directory /usr/share/squirrelmail>
  Options FollowSymLinks
  <IfModule mod_php5.c>
    php_flag register_globals off
  <IfModule mod_dir.c>
    DirectoryIndex index.php

  # access to configtest is limited by default to prevent information leak
  <Files configtest.php>
    order deny,allow
    deny from all
    allow from

ErrorLog ${APACHE_LOG_DIR}/error.log
LogLevel warn
CustomLog ${APACHE_LOG_DIR}/ssl_access.log combined

SSLEngine on
SSLCertificateFile    /etc/ssl/certs/your-ssl-certificate.crt
SSLCertificateKeyFile /etc/ssl/private/your-ssl-certificate-keyfile.key


If you use this configuration, the rewrite rules from the "rewrite to HTTPS" section (the ones from the default config file) won't work. If you want an HTTPS-only solution, you can replace the virtualhost for port 80 with this:

<VirtualHost *:80>
ServerName mail.yourdomain.com
<IfModule mod_rewrite.c>
  <IfModule mod_ssl.c>
    <Location />
      RewriteEngine on
      RewriteCond %{HTTPS} !^on$ [NC]
      RewriteRule . https://%{HTTP_HOST}%{REQUEST_URI}  [L]

As before, make sure you have the rewrite module enabled:

sudo a2enmod rewrite

Now reload apache:

sudo service apache2 restart

If you get an error like this:

[....] Restarting web server: apache2[Fri Dec 06 15:54:04 2013] [warn] _default_ VirtualHost overlap on port 443, the first has precedence

Then add NameVirtualHost *:443 to the start of the SSL VirtualHost block, i.e.:

NameVirtualHost *:443
<IfModule mod_ssl.c>
<VirtualHost *:443>
  DocumentRoot /usr/share/squirrelmail
  ServerName mail.yourdomain.com

For more info on HTTP and HTTPS VirtualHost configuration on Apache2, see this tutorial of mine.

If all went to plan then you can navigate to mail.yourdomain.com and you should see the squirrelmail login page (you might need to forward some ports on your router if you haven't already - see the next section):

Squirrelmail login page

Port Forwarding

Squirrelmail will log in to your IMAP server on port 143 to display your emails. It doesn’t need to authenticate because it’s in your network (remember the permit_mynetworks parameter from the previous tutorials?). You don’t need to worry about it being an unencrypted connection, because the data isn't actually travelling over any insecure networks (the connection is internal). Similarly, you don’t need to open port 143 (“plain” imap without SSL/TLS) on your router because the connection happens within the Pi, and the content is actually served to you, the user, on port 443 (https).

So you do need to open ports 80 and 443 for http and https like below:

Port forwarding rules


Before you start testing your webmail, make sure that the permit_mynetworks parameters are uncommented in your postfix confuguration file /etc/postfix/main.cf (in both your smtpd_recipient_restrictions and smtpd_helo_restrictions).

Now reload your postfix configuration:

sudo service postfix reload

Try sending and receiving emails from within Squirrelmail. You should have no problems, but if you do please post a comment and I’ll try to help you out.

Customising the Squirrelmail Login

To customise the login page, run the configuration wizard:

sudo squirrelmail-configure
  1. Select “1″ (organisation preferences)
  2. Select “7″ and change to your domain (e.g. http://www.samhobbs.co.uk)
  3. Select “8″ and change to you/your organisation’s name

Squirrelmail Plugins

There are loads of plugins available for Squirrelmail, for all kinds of things. On most systems, these plugins are installed by downloading a .zip file to your server, unzipping the plugin to the right location and then tinkering with the settings manually.

Thankfully, some of the most commonly used plugins are available from the Raspbian repositories, so installation is much simpler. Here is a list of the plugins in the repo:

  1. squirrelmail-compatibility
  2. squirrelmail-decode
  3. squirrelmail-locales
  4. squirrelmail-lockout
  5. squirrelmail-logger
  6. squirrelmail-quicksave
  7. squirrelmail-secure-login
  8. squirrelmail-sent-confirmation
  9. squirrelmail-spam-buttons
  10. squirrelmail-viewashtml

The one I think is most useful and the one I’m going to use as an example is lockout.

To use the lockout package, we need to install the compatibility package, which basically makes sure that plugins built for different versions of squirrelmail can still work with the version you are running.

sudo apt-get update
sudo apt-get install squirrelmail-compatibility

Now we need to enable the plugin:

sudo squirrelmail-configure
  1. select “8″
  2. select “compatibility”
  3. select “S” (to save)
  4. select “Q” (to quit)

That’s all you need to do for the compatibility plugin. Now we can install the lockout plugin:

sudo apt-get install squirrelmail-lockout

Now for the configuration:

sudo squirrelmail-configure

Make sure that lockout is enabled

Now we can manually edit some settings. Before starting, I like to back up the default config files for reference:

cd /etc/squirrelmail
sudo cp lockout-table.php lockout-table.php.BAK
sudo cp lockout-config.php lockout-config.php.BAK

Now edit the lockout-table.php file. Read the comments in the file for an explanation of how the table works. I wanted to disable logins for the user “admin”, so I commented out the examples at the end of the file and replaced them with this:

user:		admin		locked_out.php

Now edit lockout-config.php and set $use_lockout_rules = 1; to turn on lockouts.

Now try and log in as the user you locked out, and you should get this message: “Access Denied / Please contact your system administrator”.

We can also lock out IP addresses of users who enter incorrect username/password combinations repeatedly. To do this, open lockout-config.php and set $max_login_attempts_per_IP = '3:5:0'.

The first number in this parameter is the number of incorrect attempts that are allowed before a ban. The second number is the time frame for these incorrect attempts, and the last number is the amount of time the ban lasts for when activated (0 is forever).

So, the setting I gave you above means that anyone who makes 3 incorrect attempts to authenticate in 5 minutes is permanently banned.

When a successful login is made, the count is reset to 0.

Data on current bad login attempts and bans is stored here: /var/lib/squirrelmail/data/lockout_plugin_login_failure_information

The plugin will add entries like this to keep track of bad logins:


…where 999.999.99.99 is the offending IP address

If you accidentally ban yourself, you’ll have to log in via SSH and edit this file to remove those lines.

That’s it, you’re done! Have fun exploring the other plugins!

The next two tutorials, Part 4 and Part 5 deal with spam detection and filtering.



I was in the process of testing, and had not uncommented the permit_mynetworks in the smtpd_recipient_restrictions = section, but was still able to send and receive from squirrel mail. I uncommented and there seems to be no change. Have I missed something?



Nope, everything is OK. Squirrelmail should still be able to send emails if you remove permit_mynetworks from your smtpd_recipient_restrictions = section because it has your password so it can authenticate. Perhaps this sentence is misleading:

It doesn’t need to authenticate because it’s in your network (remember the permit_mynetworks parameter from the previous tutorials?).

What I really mean is it doesn't have to, but could if it needed to!

Playing with the various access restrictions lists until things break is interesting, and a good way to learn. At one point (before I added permit_sasl_authenticated to my helo access restrictions) I found that removing the permit_mynetworks parameter from the helo_access_restrictions would give me the "get lost - you're lying about who you are" message when I tried to send email (because Squirrrelmail would helo with samhobbs.co.uk).


Using the exact text provided here for the Squirrel Mail apache.conf file I was able to get my mail.domain.com working on port 80, but when I commented out that section and put in the redirect config I keep getting redirected to the default Apache "Look it works" page instead of the Squirrel Mail login page. Is there something I missed? I confirmed the port 443 is open and correctly pointing at my Pi, and that the script has been typed correctly.



I think this may be my fault for missing a step. Unless you are already using Apache to serve https content you need to enable a couple of modules and reload apache:

sudo a2enmod headers
sudo a2enmod ssl
sudo service apache2 reload

Does that make a difference?


I've been unable to redirect to https, and hitting the http "It Works!" page, but the Squirrel Mail interface is available on https. I tried this instead and it works....Would this be easier or have I left my server wide open?

<VirtualHost *:80>
ServerName mail.example.com
Redirect permanent / https://mail.example.com/


Are you sure that mod_rewrite is on?

sudo a2enmod rewrite

Your solution only works for the root, so http://mail.example.com/foo would not be redirected.


That fixed it.

I am running Squirrel Mail from .com/ so my solution works for that setup I guess.

Now back to the suggested config and redirects to https are working fine.

Thanks :)

I'll update the tutorial to include that command, thanks for checking it through for me, it takes a few people to point out these things!

I must have enabled the module for another project before I set this up.


Hi, I'am having problem with the languages.. It's English only and I would
like to have at least Swedish. Any tricks to get it to work?


Try installing the squirrelmail-locales package:

sudo apt-get update
sudo apt-get install squirrelmail-locales

I imagine you'll have to run sudo squirrelmail-configure to enable the locales plugin, and look for locales settings in the menu.


Already installed and I have reinstalled the locals twice but it doesn't help.
Also reloaded apache2 and rebooted the whole thing..

Typical UK and US.. Forcing other countrys to speak English.. Haha...

Hmm... I don't actually have Squirrelmail on my machine any more, so it's difficult to know how to help. I have a feeling you need to enable it with squirrelmail-configure and select which locales you want to generate.

Have you run raspi-config to set the system locales? It may automatically detect which languages you have on the system and use those...

Sorry I can't be more help, I've never paid much attention to the locales - I'm spoiled because English is always the default (although it's often "US English"... shudder).


Hi there,

First of all, thank you for all of your great tutorials. I've managed to connect to postfix via my tablet and everything is working all good, except after installing squirrelmail I am unable to login through it - "Unknown user or password incorrect."

Also, I'm guessing this is in some way related, when loading the login page for mailsquirrel via my.domain/mailsquirrel, the page displays a lot of html tags i.e. bgcolor, width etc. I'm guessing that for whatever reason the username and/or password field is not be correctly submitted from the form because of this but was just wondering if I might have been missing something obvious?

Thanks, again.

Hmm...not sure what's causing this.

Can you post the relevant part of /var/log/mail.log that covers a failed login attempt?

You say you've managed to connect to postfix with your tablet, but have you connected to dovecot with IMAP? If Dovecot isn't configured properly then that may explain the failed login.

I can't think why you're seeing HTML tags, that's really strange.


The «Alias /squirrelmail /usr/share/squirrelmail» line doesn't work! The computer warns me that the "Alias" command doesn't exist. Do you mean (case-sensitive) "alias"? If that's the case, I don't follow, because, as I understood, that command creates short-hands for bash commands which only work for one session. Anyway I tried and it output an error saying that none of the two directories were found! I searched manually and it seems that «/squirrelmail» does not exist, but «/etc/squirrelmail», instead, does and «usr/share/squirrelmail» exists, but none are found by "alias", still.
I hope it's a simple mistake!

Sorry for the confusion, it's a line in squirrelmail's apache config file, not a command.

The Squirrelmail apache config file is here: /etc/apache2/conf.d/squirrelmail.conf symlinked from here: /etc/squirrelmail/apache.conf.

We commented it out/removed the alias line during the tutorial (at the start).


Brilliant tutorials. Thanks. Maybe I was getting a bit gung-ho after Steps 1 and 2 going so well but I missed the line
"I’m assuming you already have Apache2 installed at this point. If not, you could do that by following the relevant section of this tutorial."
and blew my happiness on the damn squirrel. Perhaps change "could" to "jolly well MUST". I don't mind you being prescriptive!

Glad you found it useful, thanks for the comment!

I cant seem to send outbound emails, I keep getting an error saying its been blocked :/

I get:
host mx3.hotmail.com[] said: 550
OU-002 (BAY004-MC2F35) Unfortunately, messages from weren't
sent. Please contact your Internet service provider since part of their
network is on our block list. You can also refer your provider to
http://mail.live.com/mail/troubleshooting.aspx#errors. (in reply to MAIL
FROM command)

have i missed something crucial?

Hi :)

That message indicates that your server managed to connect to hotmail/outlook, but the message was rejected by their server. Your IP address is probably in a blacklist (I'm guessing you have a dynamic IP address?).

If you want to check if your Pi is working, send me an email (my email address is on the get in touch page), and see what happens, since my server doesn't reject email from dynamic IP addresses like this.

If my guess is right, then you can work around your problem by relaying outgoing email through your ISP's SMTP server (since that won't be on a blocklist) or getting yourself a static IP address. Static IP addresses can be very cheap (was a one-off £5 charge for me) or very expensive depending on your ISP/country, so it's worth looking into.


I had the same problem all you have to do is use your ISP's SMTP server I looked up your ip and found your provider it should be SMTP.talktalk.net so if you change the SMTP server that squirrel mail uses to SMTP.talktalk.net it work

Sam, I am still stuck with Squirrel. I have it running from a web browser on the LAN and it seems to work in the localhost. I haven't opened up the ports yet and so I can only run it from within the LAN. I can see the inbox and I can compose emails and then see them in the outbox. I have sent emails from squirrel to the raspberry server and I can see those arrive in the squirrel inbox. I can send emails to the raspberry server from gmail and see those arrive in the squirrel inbox. But when I send emails from squirrel to gmail (or anyother email address) I don't see those arrive at their destination. I'm puzzled, but wondering if that gives us any clue as to what the problem is that I was having with the virtual host earlier? Anyway, getting late here now, I'll try this again tomorrow morning. Cheers George

love the tutorials, and am seriously thinking of making a web/mail server out of my RPi.
I was trying out the Squirrelmail and got:

ERROR: Could not complete request.
Reason Given: [SERVERBUG] Internal error occurred. Refer to server log for more information. [2014-10-07 12:53:43]

Any ideas why?

Thank you very much.

Hi Pedro,

Check your /var/log/mail.log to see if there are any relevant messages.

If I had to guess I'd say you haven't created your Maildir properly (as per part 1 of the tutorial), or the permissions are wrong - seems like IMAP is working because you would have got an error about logging in if not.

Post the output of ls -l /home/username where "username" is the account you log in with please, it should tell us more.


I am having the same issue where and the log says Sep 22 03:38:11 raspberrypi dovecot: imap(pi): Error: open(/var/mail/pi) failed: Permission denied (euid=1000(pi) egid=1000(pi) missing +w perm: /var/mail, we're not in group 8(mail), dir owned by 0:8 mode=0775)
Sep 22 03:38:11 raspberrypi dovecot: imap(pi): Error: Failed to autocreate mailbox INBOX: Internal error occurred. Refer to server log for more information. [2016-09-22 03:38:11]
Sep 22 03:38:11 raspberrypi dovecot: imap(pi): Connection closed in=21 out=465

The advice is the same, postfix is looking in /var/mail when it should be looking in /home/user/Maildir, did you forget to do the "tell Dovecot where your mailbox is" stage, or could that parameter be overwritten later in your config file?


Can you please cover how to install postfixadmin in this series.


Thanks for your comment :)

Although I think postfix.admin is probably a useful tool for some users, I don't think it really fits the use case I'm suggesting here, i.e. a family home email server.

Postfix.admin "is a web based interface to configure and manage a Postfix based email server for many users"... whereas I'm expecting people following this tutorial to have just a few users (or I would have gone for a virtual user setup).

Another aim of the tutorial is to teach people about configuring a mail server, and postfix.admin would obscure that with a GUI.

Also, adding a web-based interface just adds another attack surface for crackers to throw themselves against, and expanding the guide to include securing the web interface would probably make it so long that people would be put off. So, I hope you find a decent guide for configuring postfix.admin, but you won't find it here!


When I login to squirrelmail I get the following error.

Preference file, /var/lib/squirrelmail/data/(username).pref.tmp, could not be written. Contact your system administrator to resolve this issue.

Do you know to fix this.

Thanks for a great tutorial.



Add new comment