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.


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)

$ ftp
$ 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 with your actual domain:

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

NOTE: make sure to replace with your actual domain.

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

mail               A 
mail               AAAA        2001:db8::

Replace 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 "" {
        listen on * port 80
        root "/htdocs/"
        location "/.well-known/acme-challenge/*" {
                root "/acme"
                request strip 2
        location "*.php" {
                fastcgi socket "/run/php-fpm.sock"
                root "/htdocs/"
        directory index "index.php"
        connection max request body 26214400
        log access "webmail_access.log"
        log error "webmail_error.log"

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 }

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

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

domain {
        alternative names {}
        domain key "/etc/ssl/private/"
        domain full chain certificate "/etc/ssl/"
        sign with letsencrypt

Request the cert:

$ doas acme-client -v

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/
$ perl

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

1.  Domain                 :
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
You might want to test your configuration by browsing to
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 in /etc/dovecot/dovecot.conf:

listen =, 2001:db8::,

Make sure to replace 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

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:       localhost
::1             localhost

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


Error opening

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 in /etc/dovecot/dovecot.conf:

listen =, 2001:db8::,

Replace 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.


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:


Test if femail works

$ doas chroot -u www -g daemon /var/www /bin/femail -t
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


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; }


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