Webmail using Roundcube

This page deals with the installation of Roundcube as a web mail interface. 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.

If my spare time allows it this guide will be extended by alternative mail clients like Horde, Rainloop and Nextcloud.

Installation

Start by installing the software packages:

apt install 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:

Or course choose mysql when asked:

When asked for a password just press ENTER.

Configure Apache

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

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

Limit access to localhost

The main configuration file of Roundcube is located at /etc/roundcube/config.inc.php. Feel free to customize the file. However I suggest that you make these changes:

$config['default_host'] = 'tls://webmail.example.org';

If you do not set the default_host here then Roundcube will ask the user for the name of the mail server at login. We don’t want that.

Also for sending emails you should use the same submission port as other email clients use:

$config['smtp_server'] = 'tls://webmail.example.org';
$config['smtp_port'] = 587;

So now when your users enter https://webmail.example.org/ in their browser they will get the Roundcube webmail application. Voila. Webmail works.

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

Plugins

Roundcube comes with various plugins that you can offer your users. I suggest to use 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 my 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:

  • $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 even if the user chooses to keep his old password.
  • $config['password_algorithm'] = 'dovecot';
    Make Roundcube use the below dovecot-based settings.
  • $config['password_dovecotpw'] = '/usr/bin/doveadm pw -s BLF-CRYPT';
    The command to create a hash for a new password that the user entered.
  • $config['password_dovecotpw_method'] = 'BLF-CRYPT';
    Add a prefix to the password hash that explicitly designates it as a bcrypt hash. That makes it easy if in the future we want to use other hashing algorithms.
  • $config['password_dovecotpw_with_method'] = true;
    Enable the above setting.
  • $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 actually change data in the database.
  • $config['password_query'] = "UPDATE virtual_users SET password=%D WHERE email=%u";
    The SQL query that is run to write the new password hash into the database. %D is a placeholder for the new password hash. And %u is obviously the email address.

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 (yeah, it’s a bit hidden). Now logout and login with the new password. Does it work? Great.

sieve plugin

Sieve is used for server-side rules. Dovecot executes these rules every time a new email comes in. Of course every 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 reach 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 if it contains “test” in the mail’s subject line:

require ["fileinto"];
if header :contains "subject" "test"
{
  fileinto "INBOX.test";
}

But hardly anyone manages rules like that. Roundcube’s rule editor is more user-friendly.

Try adding a sieve rule for john@example.org in Roundcube. If it works you will find the machine-readable sieve code at /var/vmail/example.org/john/sieve/roundcube.sieve.

56 thoughts on “Webmail using Roundcube”

  1. Florian Effenberger

    For completeness, a note to restart Apache should be added – otherwise the changed DocumentRoot directive is not in effect 🙂

  2. …just in case you are struggling with the same “Could not save new password. Encryption function missing.” error as I did:

    Find the “disable_functions” statement in your php.ini file and check whether the “proc_open” function is listed there. In my case it was. As a result, the subprocess, which is supposed to calculate hash of the new password, could not be spawned properly. The “[…] proc_open() has been disabled for security reasons […]” message in /var/log/roundcube/errors pointed me in that direction.

    1. I am keep getting this error “Could not save new password. Encryption function missing” even though disable_functions are clear (everything is allowed). What’s wrong with this plugin?

      1. After few minutes of debugging it turned out to be a problem with permissions for /etc/dovecot/conf.d/90-sieve.conf. Update password function is executed as www-data user which had no permissions to read above file.

        1. Stephane Prunier

          Add the same issue, in fact several files in dovecot conf.d were not accessible by www-data user.
          Troubleshooted using :
          # su – www-data -s /bin/bash
          # doveadm pw -s BLF-CRYPT -p secret
          this produced 2 errors :
          1. doveconf: Fatal: Error in configuration file /etc/dovecot/conf.d/10-tcpwrapper.conf line 0: Couldn’t open include file /etc/dovecot/conf.d/10-ssl.conf: Permission denied
          and
          2. Error: net_connect_unix(/var/run/dovecot/stats-writer) failed: Permission denied

          both can be solved by setting correct perms

          1. I also think that definition in cfg /usr/share/roundcube/plugins/password/password.php file is incorrect:

            $config[‘password_dovecotpw’] = ‘/usr/bin/doveadm pw -s BLF-CRYPT’;

            because by looking at /usr/share/roundcube/plugins/password/password.php file we see following section:
            case ‘dovecot’:
            $pipe = proc_open(“$dovecotpw -s ‘$method'”, $spec, $pipes);

            But it somehow works 😉 Weird.

          2. Oh, I meant

            I also think that definition in cfg /etc/roundcube/plugins/password/config.inc.php file is incorrect:

  3. In case you edit the php files and the screen comes up empty, take a look in /var/log/apache2/error.log – it always show some clue. My mistake was look into /var/lib/roundcube/logs

  4. Hello Christoph,

    Thank you for the great tutorials for many years.

    You wrote to set:
    $config[‘smtp_host’] = ‘tls://webmail.example.org’;
    I don’t find that in my roundcube config. I did find:
    $config[‘smtp_server’] = ‘localhost’;

    I guess it is probably the same but maybe you can confirm that?

    1. Yes – at this moment I also stopped and looked for where I have something wrong entered 🙂
      Great tutorial – many thanks!
      I have several mail servers on Deban without mysql but now I am happy to read and set up a new server. Many thanks for your work.

  5. Just a remark… My debian installer enabled mpm_event by default for apache2, which is not compatible with PHP. So, had to:

    a2dismod mpm_event
    a2enmod mpm_prefork
    a2enmod mpm_php7.3
    systemctl restart apache2

  6. Also, I think www-data needs read privileges for the config.inc.php and debian-db.php file. So maybe:

    chgrp www-data config.inc.php
    chgrp www-data debian-db.php
    chmod g+x config.inc.php
    chmod g+x debian-db.php

  7. Apologies, for nit-picking yet again.

    Under ‘Limiting access to localhost’ both the variables are set to point to the external, actual domain name.

    I am just wondering, whether I can get away with jus setting ‘tls://localhost’, making the multi-domain hosting yet one bit easier.

    1. And, yes, in fact, then we don’t even need TLS technically, but I reckon, otherwise the auth might not be triggered.

  8. Just for the record: I’ve tried it, and it works fine with just plain ‘localhost’ for both ‘default_host’ and ‘smtp_server’. Also cross-checked with the previous tutorials, and those suggest just simply ‘localhost’.

  9. Charles Atkinson

    Further to Stephane Prunier’s comment about /var/run/dovecot/stats-writer, it is the subject of https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=903161 which was unresolved on 12 Jun 2020.

    Several solutions have been proposed. None of the solutions which do not required modifying a non-configuration file installed by package are pretty. Perhaps the least ugly solution is to edit /etc/dovecot/conf.d/10-master.conf and add
    unix_listener stats-writer {
    group = dovecot
    mode = 0666
    user = root
    }

  10. Charles Atkinson

    Correction. The extra lines must be
    service stats {
    unix_listener stats-writer {
    group = dovecot
    mode = 0666
    user = root
    }
    }

  11. Charles Atkinson

    Further to Stephane Prunier’s comment about /var/run/dovecot/stats-writer, it is the subject of https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=903161 which was unresolved on 12 Jun 2020.

    Several solutions have been proposed. None of the solutions which do not require modifying a non-configuration file installed by package are pretty. Perhaps the least ugly solution is to edit /etc/dovecot/conf.d/10-master.conf and add

    service stats {
    unix_listener stats-writer {
    group = dovecot
    mode = 0666
    user = root
    }
    }

  12. Charles Atkinson

    Correction. The additional lines should be

    service stats {
    unix_listener stats-writer {
    group = dovecot
    mode = 0666
    user = root
    }
    }

  13. Marek Łabno

    If I use the purchased certificate and add to 10-ssl.conf (wildcard fullchain.crt privkey.key) roundcube has no connection to the server.

  14. Everything works fine besides managesieve filters. Vacation message doesn’t sent email. I should something change in 20-managesieve.conf or it should works with default configuration?

  15. Paul Smith

    Hi, am really stuck with roundcube. I log in as a user, but when I check settings, emails. user interface, etc. It just sits stuck on “refused to connect.” on the right panel or “Loading”, but just does not load.

    Checked in /var/log, all logs, and nothing of interest. I followed some of the advice in the comments to no avail.

    Am php7.3, latest install on everything else. I don’t suspect a guide issue as it looks like others have got this going. This section of the guide is straightforward, so, hopefully can eliminate the nut on the end of the keyboard as an issue.

    Any pointers or solutions will be much appretiated.

    1. Have you verified your firewall is accepting the appropriate ports? That’s my usual issue when I get the “no response” and/or “refused” errors.

      1. Paul Smith

        Roughly guessing its the way I set my subdomain up. This is out of my area of expertise.
        ?_task=mail&_token=hw3j31ahPz0MeymXmxJ1bEg9V7Fn47Xh:1 Refused to display ‘https://WHEREEVER.com/skins/larry/watermark.html’ in a frame because it set ‘X-Frame-Options’ to

      2. Paul Smith

        I think this is ok.

        ufw status
        Status: active

        To Action From
        — —— —-
        22/tcp ALLOW Anywhere
        25 ALLOW Anywhere
        443 ALLOW Anywhere
        80 ALLOW Anywhere
        3306 DENY Anywhere
        110 ALLOW Anywhere
        143 ALLOW Anywhere
        993 ALLOW Anywhere
        995 ALLOW Anywhere
        465 ALLOW Anywhere
        587 ALLOW Anywhere
        24 ALLOW Anywhere
        4190 ALLOW Anywhere
        51074 ALLOW Anywhere
        22/tcp (v6) ALLOW Anywhere (v6)
        25 (v6) ALLOW Anywhere (v6)
        443 (v6) ALLOW Anywhere (v6)
        80 (v6) ALLOW Anywhere (v6)
        3306 (v6) DENY Anywhere (v6)
        110 (v6) ALLOW Anywhere (v6)
        143 (v6) ALLOW Anywhere (v6)
        993 (v6) ALLOW Anywhere (v6)
        995 (v6) ALLOW Anywhere (v6)
        465 (v6) ALLOW Anywhere (v6)
        587 (v6) ALLOW Anywhere (v6)
        24 (v6) ALLOW Anywhere (v6)
        4190 (v6) ALLOW Anywhere (v6)
        51074 (v6) ALLOW Anywhere (v6)

        1. paul smith

          I got it all working. Don’t ask me how!!!!

          Thanks for the guide.

          My advise to others is take your time. Be carefull with your cut and paste and your passwords, its so easy to mess something up.

          Also, your server, if you are renting it from someone, they may have additional firewall restrictions which you may not be aware of. This will trip you up!

          Good luck.

          p.s. Still some issues with Thuderbird, but am sure it can be sorted, eventually….

  16. For the Roundcube Password plugin, I’d suggest adding the following setting the config.inc.php file:

    $config[‘password_confirm_current’] = true;

    This will cause Roundcube to require your current password before allowing you to change to a new one.

  17. Hi Cristoph,
    I try to test roundcube, but when I insert username and password (in mutt is all ok), roundcube tell me:

    Impossibile connettersi al server IMAP

    Thisi is my /etc/roundcube/plugins/password/config.inc.php:

    what can i check?

  18. Hi Cristoph,
    I try to test roundcube, but when I insert username and password (in mutt is all ok), roundcube tell me:

    Impossibile connettersi al server IMAP

    This is my /etc/roundcube/plugins/password/config.inc.php:
    I omit start and stop tag of php.

    // Empty configuration for password
    // See /usr/share/roundcube/plugins/password/config.inc.php.dist for instructions
    // Check the access right of the file if you put sensitive information in it.
    ###$config=array();
    $config[‘password_driver’] = ‘sql’;
    $config[‘password_minimum_length’] = 12;
    $config[‘password_force_save’] = true;
    $config[‘password_algorithm’] = ‘dovecot’;
    $config[‘password_dovecotpw’] = ‘/usr/bin/doveadm pw -s BLF-CRYPT’;
    $config[‘password_dovecotpw_method’] = ‘BLF-CRYPT’;
    $config[‘password_dovecotpw_with_method’] = true;
    $config[‘password_db_dsn’] = ‘mysql://mailadmin:installationpassword@localhost/mailserver’;
    $config[‘password_query’] = “UPDATE virtual_users SET password=%D WHERE email=%u”;

    what can i check?

  19. Thanks Christoph, I found the error. I had done a copy and paste without replacing the domain. I had never used roundcube.

  20. Now when I enter the username and password, it waits for a long time and does nothing

  21. It rest in “loading…” for a long time and then does nothing more.
    which log can i watch?
    If I do tail -f /var/log/syslog, seems that roundcube does not query dovecot. while with mutt I see it interacting with dovecot.
    What can i check now?

  22. Hi thanks for the workaround!
    in dovecote configuration (/etc/dovecot/conf.f/10-auth.conf) I have below configuration>>

    disable_plaintext_auth = yes
    auth_mechanisms = plain login
    !include auth-passwdfile.conf.ext

    In /etc/dovecot/conf.d/auth-passwdfile.conf.ext file I have below configuration:
    passdb {
    driver = passwd-file
    args = scheme=PLAIN username_format=%u /etc/dovecot/dovecot-users
    }

    userdb {
    driver = static
    args = uid=vmail gid=vmail home=/var/mail/vhosts/%d/%n

    And I have listed my virtual users at dovecot-users file in below format:

    user@domain:password

    User login/logout mail send/receive is working fine.

    But I can not figure out the password changing mechanism. It will be appreciated if you look into my issue to help me. Thanks in advance.

  23. Using $config[‘default_host’] = ‘tls://mail.example.org’; slowed roundcube down by a lot.

    Since it was installed on the mailserver itself I changed it back to $config[‘default_host’] = ‘localhost’;

    This changed the loading time from 10+ seconds back to within a second.

    Hope this helps somebody

    @Christoph I really love your tutorial! My teacher showed it to me ~7 years ago, have been using it ever since. Keep up the great work!

  24. Hello !

    At first I want to congratulate you for this very instructive tutorial. It is really useful and well written !
    I must confess that I’m a little bit lost with some informations regarding the ports that will finally be used. I followed your tuto up to the “Roundcube” section. Everything works fine, and I sucessfully connected my A**le mail software to my server. Receiving and sending emails works like a charm, in a really fast way.

    I do not find the same simplicity when trying to connect to it with “Rainloop”, which is a very light PHP webmail I prefer to use instead of Roundcube. It always gives me Timeout errors when I try to connect to my server. It is always unable to connect my server, and I really don’t understand why, with errors like that :
    – “Imap”:”stream_socket_client(): unable to connect to tcp:\/\/mail.test.test:143 (Connection timed out)” (obviously not the address of my server, just changed it here :))

    I am wondering if I’m not mistaken with the indications I give regarding the ports. Could you tell me what options I should use for IMAP and SMTP ? I opened the submission port as recommended, but I face errors every time, with all the ports. Is it also good to indicate “STARTTLS” ? Is there any possibility that the recommended configurations of your tuto blocks any connection from this software ?

    Maybe this post will also be useful for those who will try to manually configure ther server in another mail software.

    I hope you’ll be able to help me and want to thank you again for your job !

    Best regards,
    Arnaud

    1. Hi,
      Can anybody help me ? I must confess that I’m a little bit blocked…
      Best regards,

      Arnaud

  25. Thought this would help someone who is implementing with SSL

    /etc/roundcube/config.inc.php should have these entries otherwise your roundcube may hang and give you failed login errors as it did to me.

    $config[‘default_host’] = ‘ssl://your-host.tld’;
    $config[‘default_port’] = ‘993’;
    $config[‘smtp_server’] = ‘ssl://your-host.tld’;
    $config[‘smtp_port’] = ‘587’;

  26. Hallo,
    ich hab nach der Anleitung alles perfekt hinbekommen aber hätte gerne roundcube in der Version 1.4.11. wie führe ich das Upgrade aus bzw. ist es überhaupt möglich?

  27. help me please
    roundcube after having put username and password it turns in circles nothing happens.
    storage server connection error

    1. Did you get the server name right in the Roundcube configuration or are you typing it in by hand?

      The server should appear after this text in /etc/roundcube/config.inc.php:

      $config[‘default_host’] =

      1. as of this comment (2021-10-21_02-24-04), if you set `$config[‘default_host’] =` to `localhost` roundcube will respond much, MUCH faster than setting it to the FQDN of the host.

        As an aside, do **not** use PHP 8.0 if you’re trying to set this up on Debian Bullseye. The version of Roundcube on Bullseye is not fully compatible with PHP 8.0. If you must use sury.org packages, go with PHP 7.4.

  28. Hi Christoph,

    Thank you for the tutorial. I followed all the steps but I’m stuck connecting to roundcube.
    The roundcube page tells me ‘Roundcube: Connection to storage server failed’. So I googled with that error phrase and find a hint: modifying tls://webmail.myhost.name to ssl://webmail.myhost.name in the config.inc.php.
    Although it changed the result (now it takes time until displaying error), it didn’t help.
    Do you, or anyone else here have an idea of how can I correct the situation?

    Regards 🙂

    1. Hi Antoine
      If you google more details about your error message, you also find this possible problems:
      – dovecot not running (did you check, that the service is running properly?)
      – did you install the required mysql extensions for php?

      The correct connection string should be tls://your.domain.tld.

      1. Hi Benjamin,
        Thank for your, I’ll give a look at your second hint because I already checked via systemctl that dovecot was running fine.
        I’ll put back tls://webmail.myhost.name restart daemons and will keep you informed.

      2. Antoine FINET

        Hi Benjamin,
        I double checked the current guide from its beginning to its end and installed everything. So I think that the required mysql extension is installed, moreover adminer works so I’m confident that it’s not a missing extension. Maybe I double missed a mandatory package to install, can you point me which package should be installed please?

      3. Got it working. The problem was upstream, Dovecot failed to connect to MariaDB. Set mailserver’s password again, and modified back tests I made.

  29. Ole Christian

    Great guide! The question is, what am I missing in the guide? I was struggling with Roundcube. It turns out my installation would not allow access outside /usr/share or /var/www by default. To make Roundcube work, I had to add to /etc/apache2/apache2.conf the following:

    AllowOverride None
    Require all granted

    What did I miss in the guide?
    Cheers!

Leave a Reply

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

Scroll to Top