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.


Start by installing the software packages:

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:

systemctl restart apache2

Check that Apache is running properly:

systemctl status apache2

In case of a problem run “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['imap_host'] = "tls://webmail.example.org:143";
$config['smtp_host'] = 'tls://webmail.example.org:587';

So now when your users enter https://webmail.example.org/ in their browser they should get the Roundcube login form:

Login failed? Storage server can’t be reached?

In that case please double check your Dovecot 10-ssl.conf file if you set the path to your Let’s Encrypt certificate correctly. Also check the /var/lib/roundcube/logs/errors.log file for errors.

Username == email address

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


Roundcube comes with various plugins that you can offer your users. I recommend at least these two:

  • password: Let the user change their access password.
  • managesieve: Let the user manage rules that apply to incoming email. They can move mails to specific folders automatically for example.

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(

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.

No more doveadm

In previous versions of this guide I used the “doveadm pw” command to generate passwords. This is no longer needed. Roundcube can now generate the passwords in the right format to be understood by Dovecot.

Remove the empty definition line of $config from your config.inc.php file. Let’s go through the required settings one by one:

  • $config['password_driver'] = 'sql';
    Simple. Use SQL as a backend.
  • $config['password_minimum_length'] = 12;
    Allow no passwords shorter than 12 characters. I consider longer passwords more secure than short passwords with weird characters. You can even choose a larger minimum.
  • $config['password_force_save'] = true;
    This will overwrite the password in the database even if it hasn’t changed. It helps us improve the strength of the password hash by re-encoding it with a better algorithm even if the user chooses to keep his old password.
  • $config['password_algorithm'] = 'blowfish-crypt';
    The cryptographic algorithm to encode the password. This one is considered very secure and supported by Dovecot.
  • $config['password_algorithm_prefix'] = '{CRYPT}';
    Prepend every password with this string so that Dovecot knows how we encrypted the password.
  • $config['password_db_dsn'] = 'mysql://mailadmin:gefk6lA2brMOeb8eR5WYaMEdKDQfnF@localhost/mailserver';
    Connection information for the local database. Use your own password for the mailadmin (!) database user here. We cannot use the restricted mailserver user because we have to write to the database if the user changes his password.
  • $config['password_query'] = "UPDATE virtual_users SET password=%P WHERE email=%u";
    The SQL query that is run to write the new password hash into the database. %P is a placeholder for the new password hash. And %u is the logged-in user and conveniently matches the email address.

Make sure that this config file is not world-readable:

chown root:www-data /etc/roundcube/plugins/password/config.inc.php
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. Edit the file and again remove the empty or comment the $config line. You can again find all possible configuration options in the /usr/share/roundcube/plugins/managesieve/config.inc.php.dist file.

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 “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:

10 thoughts on “Webmail using Roundcube”

  1. Roundcube complained that $config[‘imap_host’] had an undefined array key. This makes some sense, so I changed [“tls://webmail.example.org:143”]; to ‘tls://webmail.example.org:143’; e.g. get rid of the array [] definition and that did the trick.

    Errors such as these can be found in /var/lib/roundcube/logs/errors.log

    1. Christoph Haas

      Thanks for the hint. It seems to work but is indeed wrong syntax. I have changed that.

  2. Hi Christoph,

    As always – very good job!
    I’ve got an error when I tried to send mail via RoundCube because declared port for SMTP(587) is not opened. As I remember, Submission port were mentioned in earlier tutorials (additional configuration in /etc/postfix/master.cf file is needed).
    I can’t find this part of configuration… more over, in /etc/postfix/main.cf we should change paths to certificate and key. Maybe I missed something?

  3. For those that would like to use nginx as a webserver, I’ve had luck with the following config:

    location /roundcube {
    alias /var/lib/roundcube/public_html;

    location ~ /roundcube(/.*\.php)$ {
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
    fastcgi_split_path_info ^/roundcube/(.+\.php)(/.*)$;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $request_filename;
    fastcgi_param PATH_INFO $fastcgi_path_info;

    Save as a seperate conf file and then include it into your main file and it *should* be good to go!

  4. If you are using Debian Bookworm with Apache, there’s no need to add

    Include /etc/roundcube/apache.conf

    because the installation adds the same config as


    and enables it.

  5. In the “password plugin” section is
    $config[‘password_algorithm_prefix’] = ‘{CRYPT}’;
    supposed to be
    $config[‘password_algorithm_prefix’] = ‘{BLF-CRYPT}’;

    1. After reading the help for “doveadm help pw” it says:

      By default the CRYPT scheme will be used (with the $2y$ bcrypt format).

      So I guess ‘{CRYPT}’ it is.

  6. When I tried to send my first email from Roundcube I got an “SMTP Authetication fail” . I searched and found a solution. In the roundcube “config.inc.php” the setting for the local host was :
    $config[‘smtp_host’] = ‘localhost:587’; This setting caused the error. I changed it to : $config[‘smtp_host’] = ‘tls://%n:587’;
    the %n variable is just the name of the server. Example: mailserver1.example.com . Is there a step I missed that would allow for
    $config[‘smtp_host’] = ‘localhost:587’; to work?

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to Top