SquirrelMail is one of the original open-source webmail clients: plain PHP, no JavaScript requirement, and no database needed. For more than a decade it was the default webmail on countless Linux servers and hosting control panels.

Project status: read this first¶

• The last stable release, 1.4.22, dates from 2011.
• Development continues only as nightly snapshots of the 1.4.23-svn (stable branch) and 1.5.2-svn (development branch). The project itself tells administrators to run a recent snapshot, which is where PHP 7/8 compatibility and security fixes live. The 1.4.22 tarball does not work on modern PHP and has known vulnerabilities.
• Most distributions (Debian, Ubuntu, current Fedora and RHEL) no longer package it.
• It has no 2FA, no modern responsive UI, and no CSRF/XSS hardening comparable to current webmail.

Recommendation: don't deploy SquirrelMail for new installs. Use Roundcube or SnappyMail. This guide exists to keep an existing installation running safely and to get users off it cleanly.

How it works¶

 Browser ──HTTPS──► Web server + PHP ──IMAP(S)──► Dovecot / any IMAP server
                     (SquirrelMail)  ──SMTP────► Postfix (submission)
                         │
                         └── data_dir: per-user prefs, address books, signatures (flat files)

• Stateless IMAP client: every page load opens an IMAP connection, does its work and disconnects. That's slow on large mailboxes, but simple, and it works with any IMAP server.
• Authentication is the IMAP login. SquirrelMail has no user database. If IMAP accepts the username and password, you're in.
• Preferences (identities, signatures, address book, folder options) live in flat files in data_dir, one set per user, or optionally in a SQL database.
• Sending goes through SMTP (recommended) or by running the local sendmail binary.

Installing a snapshot¶

# Prerequisites (RHEL-family shown; adjust for apt)
sudo dnf install httpd php php-mbstring php-intl
# or nginx + php-fpm

# Download the latest 1.4.x snapshot tarball from squirrelmail.org/download.php, then:
sudo mkdir -p /usr/share/squirrelmail
sudo tar -xzf squirrelmail-*-1.4.23-svn*.tar.gz -C /usr/share/squirrelmail --strip-components=1

# Data and attachment directories OUTSIDE the web root, writable only by the web server user
sudo mkdir -p /var/lib/squirrelmail/{data,attach}
sudo chown -R apache:apache /var/lib/squirrelmail      # www-data on Debian
sudo chmod 0730 /var/lib/squirrelmail/attach           # web server can write, not list

Web server¶

Apache:

# /etc/httpd/conf.d/squirrelmail.conf
Alias /webmail /usr/share/squirrelmail
<Directory /usr/share/squirrelmail>
    Options -Indexes
    AllowOverride None
    Require all granted
</Directory>
# Library and config directories never need to be fetched directly
<DirectoryMatch "^/usr/share/squirrelmail/(config|include|class|functions|locale|po|doc)/">
    Require all denied
</DirectoryMatch>

nginx + PHP-FPM:

location /webmail {
    alias /usr/share/squirrelmail;
    index index.php;
    location ~ ^/webmail/(config|include|class|functions|locale|po|doc)/ { deny all; }
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $request_filename;
        fastcgi_pass unix:/run/php-fpm/www.sock;
    }
}

Serve it only over HTTPS. Logins are plain IMAP passwords.

Configuring with conf.pl¶

SquirrelMail is configured with an interactive Perl menu that writes config/config.php:

cd /usr/share/squirrelmail/config
sudo ./conf.pl

The settings that matter:

Save (S), quit (Q), then browse to https://mail.domain.tld/webmail/src/configtest.php. It checks PHP extensions, directory permissions, and IMAP/SMTP connectivity. Delete or block configtest.php afterwards.

Hardening¶

• Use SMTP, not sendmail. CVE-2017-7692 was a remote code execution flaw caused by passing user-controlled addresses to the sendmail binary. Sending via SMTP sidesteps that whole class of bug.
• Run a current snapshot and re-check the download page periodically. Snapshots are the only place fixes land.
• Keep data_dir and attach_dir outside the document root, owned by the web server user, and not world-readable.
• HTTPS only, with Strict-Transport-Security. Set the PHP session cookie to Secure and HttpOnly (session.cookie_secure = 1, session.cookie_httponly = 1).
• Limit exposure. Put it behind your reverse proxy with an SSO/2FA gateway, or reachable only over VPN, so the unmaintained code isn't facing the whole internet.
• Rate-limit logins with fail2ban on the IMAP server's auth failures. Every webmail login attempt is an IMAP login.
• Minimize plugins. Third-party plugins are often older and less audited than the core.

Troubleshooting¶

Migrating to Roundcube¶

Roundcube talks to the same IMAP and SMTP servers, so mail itself doesn't move. Only the per-user settings that SquirrelMail kept in data_dir do:

1. Install Roundcube pointed at the same IMAP/SMTP hosts.
2. Enable Roundcube's bundled squirrelmail_usercopy plugin and point it at the old SquirrelMail data_dir (or its preferences database). On each user's first Roundcube login, it imports their identities, signatures and address book.
3. Run both side by side for a while. Redirect /webmail to Roundcube once users have logged in at least once.
4. Remove SquirrelMail, its web server config, and (after a retention period) data_dir.

Folder names, flags and read state are all on the IMAP server, so users see their mailbox exactly as before.