Skip to content

Install SquirrelMail

SquirrelMail is webmail written in PHP. It uses HTML 4.0 with no JavaScript required, making it compatible across many browsers. It does not require any databases and is very easy to install and configure. It is GPL-licensed.

Its main drawback is its use of frames, which is bad for accessibility. Development, unfortunately, has stalled, so a C-based replacement will be needed.

Required

Before installing squirrelmail, opensmtpd must be properly configured, php and [dovecot must be installed and properly configured. Before installing squirrelmail, opensmtpd must be properly configured, php and [dovecot must be installed and properly configured.

Please test both sending and receiving email using another mail client before attempting to setup Squirrelmail.

Download the stable version snapshot package (1.4.23-svn.md)

$ ftp https://snapshots.squirrelmail.org/squirrelmail-20220205_0200-SVN.stable.tar.gz
$ tar xvzf squirrelmail-20220205_0200-SVN.stable.tar.gz

Optional: you can delete the original tarball once you are done extracting:

$ rm squirrelmail-20220205_0200-SVN.stable.tar.gz

Next, you want to move squirrelmail into your web documents folder. Make sure to replace mail.example.com with your actual domain:

$ doas mv squirrelmail.stable/squirrelmail /var/www/htdocs/mail.example.com
$ doas chown -R www:daemon /var/www/htdocs/mail.example.com/

NOTE: make sure to replace mail.example.com with your actual domain.

If the domain does not already exist, add the subdomain mail in /var/nsd/zones/master/example.com:

mail               A           10.0.0.1
mail               AAAA        2001:db8::

Replace 10.0.0.1 and 2001:db8:: with your real IPv4 and IPv6 addresses. Make sure to update the serial number, then:

$ doas nsd-control reload

Add this to /etc/httpd.conf:

server "mail.example.com" {
        listen on * port 80
        root "/htdocs/mail.example.com/"
        location "/.well-known/acme-challenge/*" {
                root "/acme"
                request strip 2
        }
        location "*.php" {
                fastcgi socket "/run/php-fpm.sock"
                root "/htdocs/mail.example.com"
        }
        directory index "index.php"
        connection max request body 26214400
        log access "webmail_access.log"
        log error "webmail_error.log"
}

(:if false:)

    location "/class/*" {

            block return 403

    }

    location "/config/*" {

            block return 403

    }

    location "/contrib/*" {

            block return 403

    }

    location "/data/*" {

            block return 403

    }

    location "/doc/*" {

            block return 403

    }

    location "/functions/*" {

            block return 403

    }

    location "/help/*" {

            block return 403

    }

    location "/include/*" {

            block return 403

    }

    location "/locale/*" {

            block return 403

    }

    location "/po/*" {

            block return 403

    }

(:ifend:)

For SSL/TLS, we recommend you use relayd for TLS acceleration rather than httpd's native SSL. This is so you can provide web services that do not use [openhttpd. For SSL/TLS, we recommend you use relayd for TLS acceleration rather than httpd's native SSL. This is so you can provide web services that do not use [openhttpd.

TLS with relayd

When using relayd for TLS acceleration, all that is needed are a few lines in /etc/relayd.conf:

tls { keypair mail.example.com }

Replace mail.example.com with your real domain. This provides the TLS cert for webmail.

In /etc/acme-client.conf, add this block:

domain mail.example.com {
        alternative names { example.com imap.example.com smtp.example.com pop.example.com pop3.example.com}
        domain key "/etc/ssl/private/mail.example.com.key"
        domain full chain certificate "/etc/ssl/mail.example.com.crt"
        sign with letsencrypt
}

Request the cert:

$ doas acme-client -v mail.example.com

Normally, the user www has no login shell for security. However, squirrelmail has this unusual perl configuration script that www needs to run. So first, we give www the default ksh shell:

$ doas chsh -s /bin/ksh www

Then, we switch to the user www and run the config script:

$ doas su www
$ cd /var/www/htdocs/mail.example.com/config
$ perl conf.pl

You should see the interactive menu:

SquirrelMail Configuration : Read: config_default.php (1.4.0)
---------------------------------------------------------
Main Menu --
1.  Organization Preferences
2.  Server Settings
3.  Folder Defaults
4.  General Options
5.  Themes
6.  Address Books
7.  Message of the Day (MOTD)
8.  Plugins
9.  Database
10. Languages
D.  Set pre-defined settings for specific IMAP servers
C   Turn color on
S   Save data
Q   Quit
Command >> 2

Type 2 to edit Server Settings:

Server Settings
General
-------
1.  Domain                 : mail.example.com
2.  Invert Time            : false
3.  Sendmail or SMTP       : SMTP
IMAP Settings
--------------
4.  IMAP Server            : localhost
5.  IMAP Port              : 143
6.  Authentication type    : login
7.  Secure IMAP (TLS)      : false
8.  Server software        : dovecot
9.  Delimiter              : detect
B.  Change Sendmail Config : /usr/sbin/sendmail
H.  Hide IMAP Server Settings
R   Return to Main Menu
C   Turn color on
S   Save data
Q   Quit
Command >> B

Once you're done with configuration, save your work and quit:

Command >> S
Data saved in config.php
Press enter to continue...
Command >> Q
Exiting conf.pl.
You might want to test your configuration by browsing to
http://your-squirrelmail-location/src/configtest.php
Happy SquirrelMailing!

Logout by typing ctrl+d and then disable the login shell for www:

$ ^D
$ doas chsh -s /sbin/nologin www

Because Squirrelmail will connect to IMAP via localhost, you will need a listener for 127.0.0.1 in /etc/dovecot/dovecot.conf:

listen = 10.0.0.1, 2001:db8::, 127.0.0.1

Make sure to replace 10.0.0.1 and 2001:db8:: with your real public IPv4 and IPv6 address.

You will want to restart dovecot if you need to make the change:

$ doas rcctl restart dovecot

We need to create folders that squirrelmail can write data to:

$ doas mkdir -p /var/www/var/local/squirrelmail/data
$ doas mkdir -p /var/www/var/local/squirrelmail/attach
$ doas chown -R www:daemon /var/www/var/local/squirrelmail

Remember, openhttpd runs chrooted in /var/www by default, which means you will

need to copy some essential system files.

If it does not exist already, create /var/www/etc/resolv.conf:

lookup file bind
nameserver 127.0.0.1

This provides information on where to lookup DNS records. You will need

to configure unbound.

If it does not exist already, create /var/www/etc/hosts:

127.0.0.1       localhost
::1             localhost

This defines localhost to be 127.0.0.1, which is necessary since squirrelmail will query IMAP and SMTP by using localhost.

Troubleshooting:

Error opening

ERROR
Error opening ../data/default_pref
Could not create initial preference file!
/var/local/squirrelmail/data/ should be writable by user
Please contact your system administrator and report this error.
Go to the login page

Make sure to create folders that squirrelmail can write to:

$ doas mkdir -p /var/www/var/local/squirrelmail/data
$ doas mkdir -p /var/www/var/local/squirrelmail/attach
$ doas chown -R www:daemon /var/www/var/local/squirrelmail

Squirrelmail cannot connect to IMAP

Make sure you have a listener for 127.0.0.1 in /etc/dovecot/dovecot.conf:

listen = 10.0.0.1, 2001:db8::, 127.0.0.1

Replace 10.0.0.1 and 2001:db8:: with your real IPv4 and IPv6 addresses.

Afterwards, restart dovecot if any changes were made:

$ doas rcctl restart dovecot

If Squirrelmail cannot resolve the name localhost, make sure you have the file /var/www/etc/hosts defined (see above).

Check logs

Check /var/www/logs/error.log for additional logs for debugging.

Sendmail

Squirrelmail should be able to use sendmail instead of SMTP. However, on OpenBSD 6.9, there appears to be some issues with the replacement femail instead of sendmail.

WARNING: This setup has errors.

To setup femail:

$ doas mkdir -p /var/www/etc/

Create /var/www/etc/femail.conf:

smtphost=127.0.0.1
myname=mail.example.com

Test if femail works

$ doas chroot -u www -g daemon /var/www /bin/femail -t -fusername@mail.example.com
To: other@domain.com
Subject: Alpha Bravo
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Charlie Delta Echo Foxtrot

Type ctrl+d to end the message

Baytuch notes

Permissions

cd /var/www/htdocs/
doas chown root:bin webmail
doas find ./webmail -type d -exec chmod 755 {} \;
doas find ./webmail -type f -exec chmod 644 {} \;
doas rm /var/www/htdocs/webmail/README                                                                                              
doas rm /var/www/htdocs/webmail/configure

PHP 7 compatibility fix

functions/global.php (451):
function sqsession_is_active() {
    if (session_status() === PHP_SESSION_ACTIVE) { return; }
    sqsession_start();
}

Configuring

doas touch /var/www/htdocs/webmail/config/config.php
doas chown www:www /var/www/htdocs/webmail/config/config.php
doas chmod 400 /var/www/htdocs/webmail/config/config.php

Security

(:if false:)

$ doas chmod -R o-rx /var/www/htdocs/mail.example.com/
$ doas chmod -R o-rx /var/www/var/local/squirrelmail

(:ifend:)

config.php.zip