Webmail using Roundcube

This feature is completely optional. If you are eager to get finished then skip this page and maybe come back later. You can still access your mail server using a mail user agent like Thunderbird.

Power users may still want to use a mail client like Thunderbird. But most users nowadays seem to prefer reading their emails in the web browser. Let us install a web application for that purpose: Roundcube. Roundcube is the software that was also used in the previous versions of this guide. So, if your users are used to it… just stay with it.

Installation

Start by installing the software packages:

sudo apt install -y roundcube roundcube-plugins roundcube-plugins-extra roundcube-mysql

Roundcube stores user settings in the database. So, you will get asked to set up database access.

Choose Yes.

When asked for a password just press ENTER.

Configure Apache

Do you remember that earlier in this guide I asked you how want to name your mail server? Whether you want to use one common name like “webmail.example.org” for all your domains? Or if you prefer different host names for each domain like “webmail.domain1.com” and “webmail.domain2.com”? If you want to use just more then you will have to create one virtual host configuration per domain. The following instructions will just deal with one common host name.

To get Apache to serve the Roundcube application you need to edit the /etc/apache2/sites-available/webmail.example.org-https.conf file. I suggest you change the DocumentRoot line to:

DocumentRoot /var/lib/roundcube/public_html

All URLs are relative to that directory. So, if you go to https://webmail.example.com/ then files are looked up in that directory.

Also add this line within the same VirtualHost section to add a couple of prepared security settings:

Include /etc/roundcube/apache.conf

And as usual Apache needs to be restarted after the configuration change:

sudo systemctl restart apache2

Check that Apache is running properly:

systemctl status apache2

In case of a problem run “sudo apache2ctl configtest” to find the cause.

Limit access to localhost

The main configuration file of Roundcube is located at /etc/roundcube/config.inc.php. Feel free to customize the file. Fortunately, nowadays the basic settings are already as we need them. However, these two settings need to be changed by you:

$config['default_host'] = ‘’;
$config['smtp_server'] = 'localhost';

For example, I changed them to:

$config[‘default_host’] = ‘localhost’;
$config[‘smtp_server’] = “tls://webmail.umd.me.uk”;

Be default the login screen provides a text box where you need to enter the IMAP host which you want to connect. This box is hidden by setting the default_host to be localhost.

Restart apache2 server. Now when your users enter https://webmail.example.org/ in their browser they should get the Roundcube login form.

Keep in mind that we are using the email address as the account name of the user. So, when logging in please enter the email address as the user name. E.g., ‘john@example.org’ and password ‘summersun’.

Plugins

Roundcube comes with various plugins that you can offer your users. I recommend at least these two: Again, edit the /etc/roundcube/config.inc.php file and look for the plugins configuration. To enable the recommended plugins change it to: 
        $config['plugins'] = array(
            'managesieve',
            'password'
        );

password plugin

Plugins are configured through files located in the /etc/roundcube/plugins directory. Let’s begin with the password plugin. Edit the /etc/roundcube/plugins/password/config.inc.php file.

Oops, that file looks pretty empty. But it refers us to an example file at /usr/share/roundcube/plugins/password/config.inc.php.dist. There are many different methods to let users change their passwords. As we store that information in the SQL database, that is the part we need to set up.

Remove the empty definition line of $config from your config.inc.php file. Let’s go through the required settings one by one: Make sure that this config file is not world-readable:

sudo chown root:www-data /etc/roundcube/plugins/password/config.inc.php
sudo chmod u=rw,g=r,o= /etc/roundcube/plugins/password/config.inc.php

Try it. Log into Roundcube as john@example.org with password ‘summersun’. Go to the Settings. Choose Password. Enter a new password twice. You should get a success message at the bottom right. Now logout and login with the new password. Does it work? Great.

sieve plugin

Sieve is a simple programming language to be used for server-side rules. Dovecot executes these rules every time a new email comes in. There are global rules that are executed for every email. And of course, every user/mailbox can have its own rules. To manage sieve rules Dovecot offers the managesieve interface that you enabled earlier. So, we just need to tell Roundcube how to access it.

The configuration file for Roundcube’s managesieve plugin is found at /etc/roundcube/plugins/managesieve/config.inc.php. This time just one setting is required to tell Roundcube which server to talk to:

$config['managesieve_host'] = 'localhost';

Sieve rules are stored in a special syntax on the server. This is an example that moves all incoming emails to the test folder that have “test” in the subject: 
        require ["fileinto"];
        if header :contains "subject" "test"
        {
          fileinto "INBOX/test";
        }
You do not need to learn this syntax though. Roundcube’s sieve rule editor is way more user-friendly.

Try adding a sieve rule for john@example.org in Roundcube. That feature is located in Settings/Filters. You will find the machine-readable sieve code at /var/vmail/example.org/john/sieve/roundcube.sieve.

The rule editor looks like this:

Roundcube Filter

0. Testing email delivery

So far you have spent considerable time with theory and configuration. Are you worried whether all you did actually leads to a working mail server? Before we do the final steps let’s take a break and verify that everything you did so far works as expected.

You can get a list of all files and directories within by running:

sudo find /var/vmail

You may still get something along the lines of:

/var/vmail/umd.me.uk/sjin1239
/var/vmail/umd.me.uk/sjin1239/Maildir
/var/vmail/umd.me.uk/sjin1239/Maildir/cur
/var/vmail/umd.me.uk/sjin1239/Maildir/tmp
/var/vmail/umd.me.uk/sjin1239/Maildir/dovecot.list.index.log
/var/vmail/umd.me.uk/sjin1239/Maildir/dovecot-uidvalidity.6869d39b
/var/vmail/umd.me.uk/sjin1239/Maildir/dovecot.index.log
/var/vmail/umd.me.uk/sjin1239/Maildir/new
/var/vmail/umd.me.uk/sjin1239/Maildir/dovecot-uidlist
/var/vmail/umd.me.uk/sjin1239/Maildir/dovecot-uidvalidity

Basically, the schema you see here is /var/vmail/DOMAIN/USER/Maildir/…

Eeach IMAP mail folder has three subdirectories:

Send a test email

It is time to send a new email into the system. Open a new terminal window and run

tail -f /var/log/mail.log

to see what the mail server is doing. Now let’s send an email to sjin1239. My favorite tool for mail tests is swaks that you installed earlier. In the original terminal run:

swaks --to sjin1239@umd.me.uk --server localhost

If all works as expected, your mail.log will show a lot of technical information about the email delivery. Let me explain what happens at each stage.

If everything worked as expected Postfix has accepted the email and forwarded it to Dovecot which in turn wrote the email in sjin1239’s maildir.

Look again:

sudo find /var/vmail

Dovecot has now created a directory structure for sjin1239 and created a new file:

/var/vmail/
[…]
/var/vmail/umd.me.uk/sjin1239/Maildir/new/1762718252.M298981P723801.webmail.umd.me.uk,S=731,W=751
[…]

The file will have a different name on your system – that’s okay. It is the only file in the “new” folder.

You can also use a slightly more comfortable tool to access Maildirs that will come handy for you as a mail server administrator: “mutt”.

sudo mutt -f /var/vmail/umd.me.uk/sjin1239/Maildir

What you see now are the contents of sjin1239’s mailbox:

mutt Inbox

Using mutt is a nice way to check mailboxes while you are logged in to the mail server.

To reiterate what happens when you receive an email:

  1. Postfix receives the email (using the “swaks” command in this example – but usually through the network using the SMTP protocol from other servers)
  2. Postfix talks to Dovecot via LMTP and hands over the email
  3. Dovecot runs through the user’s Sieve rules
  4. Dovecot writes the email file to disk

Accessing the email via IMAP (Roundcube)

Now that the email has been delivered you can talk to Dovecot using the IMAP protocol to retrieve your email again. Are you still logged in via the Roundcube webmail interface? Then just reload and you will see the email.

roundcube email content