Roundcube

Debian packages

The main package is

roundcube

A DBMS-specific package is also required. I prefer to use PostgreSQL, so in my case the package is this:

roundcube-pgsql

An additional package with useful plugins should also be installed:

roundcube-plugins

Finally, in Debian testing there is another package with plugins that is not yet available in Debian jessie. This one I manually downloaded and installed because it contains the useful plugins listcommands and markasjunk2:

roundcube-plugins-extra

References

http://trac.roundcube.net/wiki/Howto_Config (some of the most important, but not all, configuration options are explained here)
http://trac.roundcube.net/wiki/Howto_Install (the Debian package already does most of the stuff explained in this document, so you can skip that)
/usr/share/doc/roundcube-plugins/README.Debian (for help on how to make plugins work)

Database configuration

When the Debian package installs, it delegates database configuration to dbconfig-common. The questions to answer are these:

Configure database for roundcube with dbconfig-common = yes
Database type = pgsql
PostgreSQL application password = secret (or leave empty)
- Not entering your own password causes a random password to be generated

If database access does not work ("unable to connect to database" error message in browser), manually set the DB user's password in /etc/roundcube/debian-db.php. In my case something probably went wrong during the initial setup with dbconfig-common, causing the wrong password to be written to /etc/roundcube/debian-db.php.

Web server configuration

Package configuration

As is customary on Debian, the package-specific configuration file for Apache is here:

/etc/roundcube/apache.conf

And a symlink to this was automatically dropped into Apache's configuration folder:

/etc/apache2/conf.d/roundcube

No need to touch this file.

Virtual host configuration

I have assigned an Apache vhost to Roundcube that is accessible under https://mail.herzbube.ch/ (previously this was assigned to SquirrelMail). These are the configuration details:

# --------------------------------------------------------------------------------
# mail.herzbube.ch
# --------------------------------------------------------------------------------
<VirtualHost *:80>
  ServerName mail.herzbube.ch
  Redirect permanent "/" "https://mail.herzbube.ch/"
</VirtualHost>

# --------------------------------------------------------------------------------
# SSL Host
# --------------------------------------------------------------------------------
<VirtualHost *:443>
  ServerName mail.herzbube.ch
  ServerAdmin webmaster@herzbube.ch
  ErrorLog ${APACHE_LOG_DIR}/mail.herzbube.ch/error.log
  CustomLog ${APACHE_LOG_DIR}/mail.herzbube.ch/access.log combined

  DocumentRoot /var/lib/roundcube

  <Directory /var/lib/roundcube/>
    php_admin_flag engine on
  </Directory>

  Include conf-available/pelargir-herzbube.ch-vhosts-ssl.conf
</VirtualHost>

Notes:

Roundcube already has a robots.txt that disallows all (located in /var/lib/roundcube/robots.txt)

.htaccess File

Roundcube requires a .htaccess file to function properly. On Debian, this is the .htaccess file that takes effect:

root@pelargir:~# ls -l /var/lib/roundcube/.htaccess 
lrwxrwxrwx 1 root root 23 May  9 10:59 /var/lib/roundcube/.htaccess -> /etc/roundcube/htaccess

To make it work, the virtual host configuration must contain the directive AllowOverride All inside a directory clause for /usr/share/roundcube. With older Debian packages it used to be necessary to explicitly add this directive to the vhost configuration, but modern Debian packages already contain the directive inside /etc/apache2/conf-available/roundcube.conf. A symptom if the directive is missing is this browser error message: "ERROR: Wrong 'suhosin.session.encrypt' option value. Read REQUIREMENTS section in INSTALL file or use Roundcube Installer, please!"

Roundcube configuration

The main configuration file is

/etc/roundcube/config.inc.php

It overrides the default option values that are set in

/etc/roundcube/defaults.inc.php

I changed the following things in config.inc.php:

$config['default_host'] = 'tls://mail.herzbube.ch';
- By default this variable is blank
- A blank variable causes a textbox to be displayed in the browser where the user has to enter the IMAP server
- Adding a value here suppresses the textbox
- Originally I specified localhost here, but after the upgrade to PHP 5.6 (which enables peer verification of SSL certificates by default) I had to specify a hostname that matches the SSL certificate handed out by the IMAP server
$config['force_https'] = true;
- By default this is is set to false
- The vhost also includes redirection to HTTPS, so strictly speaking this setting is not necessary, but because this is so important I don't mind having a double-insurance policy
$config['des_key'] = 'secret';
- A site-specific key is automatically generated by DebConf, so no need to manually generate it
- This key is used to encrypt the user's IMAP password in the session record
- The session record by default is stored in the PostgreSQL database
- This key is also used to encrypt the password in the client cookie if "remember password" is enabled
$config['draft_autosave'] = 60;
- The default is 300 seconds, which is not frequent enough for me
$config['enable_spellcheck'] = false;
- The default value for this is true, but the Debconf-generated config.inc.php sets this to false.
- I want to have spell checking enabled, so I comment this line
Plugin configuration: See next section.

The following are notable options that already have the correct default values (from defaults.inc.php), but which I would like to document here anyway:

$config['default_port'] = 143;
- Port 143 when combined with the tls:// prefix used in the "default_host" results in TLS over the regular IMAP port (i.e. STARTTLS)! Yay!!!
- Why I am I writing this? Because this was a long-standing issue with SquirrelMail, which does not support STARTTLS and therefore needs to connect to port 993
$config['auto_create_user'] = true;
- Security-trained eyes will get caught on this option (mine did). The default is already true, and it must be left like this
- The reason is that Roundcube internally keeps its own user table, and for a login to be successful, not only must it succeed on the IMAP level, in addition Roundcube also requires that a matching user record exists in its own table. Setting this option to true (the default) makes sure that successful IMAP logins automatically get an entry in the roundcube user table
$config['spellcheck_engine'] = 'pspell';
- The default for this in older versions of the Debian packages was "googie". This enables a spell checker based on GoogieSpell, which uses a Google service to perform online spell checking. I don't want to depend on Google for this, I prefer the PHP Pspell module instead.
- Note that for this to work, the Debian packages php-pspell and aspell must be installed. The current version of the Debian package roundcube-core (as of Debian buster) has a "Recommends" dependency on php-pspell
- To completely disable spell checking, add this configuration option to the Roundcube config file: $config['enable_spellcheck'] = false;

Plugins

General instructions

To enable the plugin, you have to add its name (or better: the plugin's folder name) to /etc/roundcube/config.inc.php. For instance:

$config['plugins'] = array('emoticons', 'listcommands', 'carddav');

IMPORTANT: The Roundcube plugin mechanism actually looks for the plugin in /var/lib/roundcube/plugins. To really make the plugin work, you therefore need a symlink, generated like this:

ln -s /usr/share/roundcube/plugins/foobar /var/lib/roundcube/plugins/foobar

The plugin may need database tweaks or other stuff. Refer to the plugin's INSTALL file for more details.

Last but not least, the plugin may need a configuration file. To keep in line with the Debian Roundcube plugin packages, this configuration file should be placed into the following folder (which you may need to create first)

/etc/roundcube/plugins/foobar/

IMPORTANT: When the plugin code executes, the current working directory is set to /usr/share/roundcube. If the config file is in /etc/roundcube, the plugin will therefore NOT find it, unless it looks for the file under its absolute path (unlikely, since /etc/roundcube is very much Debian specific). Probably the plugin looks for its config file under a relative path, such as plugins/foobar/config.inc.php. This means that you need ANOTHER symlink to make the whole thing work:

ln -s /etc/roundcube/plugins/foobar/config.inc.php /usr/share/roundcube/plugins/foobar/config.inc.php

listcommands

This plugin is part of the Debian package roundcube-plugins-extra
The plugin displays links such as "Subscribe" and "Unsubscribe" when an email is viewed that has been received from a mailing list

emoticons

This plugin is part of the Debian package roundcube-plugins
The plugin inserts nice smileys and other emoticons when the appropriate text representations (e.g. ":-)") are discovered in the email text

markasjunk2

This plugin is part of the Debian package roundcube-plugins-extra
The plugin displays links to either mark a message as spam (if it is not in the Junk folder), or as ham (if it is in the Junk folder)
The default configuration is largely OK, I just added the options to let markasjunk2 execute sa-learn when it processes a message. This is how the config file /etc/roundcube/plugins/markasjunk2/config.inc.php looks like:

$config['markasjunk2_learning_driver'] = 'cmd_learn';
$config['markasjunk2_spam_cmd'] = 'sa-learn --spam --username=%u %f';
$config['markasjunk2_ham_cmd'] = 'sa-learn --ham --username=%u %f';

If you want to diagnose the plugin, also add this to the config file:

// The log file is /var/log/roundcube/markasjunk2
$config['markasjunk2_debug'] = true;

Not seen here are the defaults for settings for so-called "flags" when a messge is marked as spam or ham. These settings refer to IMAP flags. The default flag that this plugin tries to set when a message is marked as spam is called "Junk". This flag is a non-standard flag, described as an extension in RFC5232. I checked whether Courier on my system handles this flag, but apparently it does not - the message file in question had the same name, regardless of whether I let markasjunk2 set the flag or not. Despite this, I left markasjunk2's default behaviour active, I might look into this on the Courier side at a later time.

zipdownload

This plugin is part of the Debian package roundcube-plugins
This plugin adds an option to download all attachments to a message in one zip file, when a message has multiple attachments. The plugin also allows the download of a selection of messages in 1 zip file.

The RCMCardDAV plugin

Summary

Of course I want to have access from my webmail to the contacts that are stored in my DAViCal server. There is indeed a very nice Roundcube plugin, RCMCardDAV, that does just that. Unfortunately, the Debian Roundcube packages do not contain that plugin, so I have to install it myself.

References

Website = https://www.benjamin-schieder.de/carddav.html
GitHub repo = https://github.com/blind-coder/rcmcarddav
Installation instructions for Composer: https://getcomposer.org/download/

Composer

RCMCardDAV's README on GitHub recommends to use "Composer", a PHP dependency manager, to install RCMCardDAV's dependencies.

I previously had no experience with Composer, but after a little bit of research, it appears that Composer is simply a single PHP script that is downloaded/installed into a local working directory, in this case the RCMCardDAV directory.

Composer can also be used when installed via Debian package composer. That's my preferred method.

Installation

# Get RCMCardDAV source code
mkdir -p /usr/local/share/roundcube/plugins
cd /usr/local/share/roundcube/plugins
git clone https://github.com/blind-coder/rcmcarddav.git carddav

# Install RCMCardDAV dependencies
cd carddav
composer install

Database

RCMCardDAV requires modifications to the Roundcube database scheme. You should not need to manually apply these changes, RCMCardDAV will apply them automatically when you log into Roundcube the next time after you have enabled RCMCardDAV. It is therefore best to log out of Roundcube before you enable the plugin.

RCMCardDAV creates a number of database tables in the Roundcube database, all with the prefix "carddav_". To check whether the tables are already present you can list all tables in the Roundcube database with this command. If you use MySQL then the command will be different, of course.

psql --host=localhost --dbname=roundcube --username=roundcube --command="\d"

If something goes wrong and you have to manually apply the database scheme changes, you will find the necessary DBMS-specific scripts in this subfolder:

/usr/local/share/roundcube/plugins/carddav/dbmigrations

Integration with Debian Roundcube

These commands integrate RCMCardDAV with the Debian Roundcube package. Note that the owner/permission modifications are important because when we are finished the config file will contain a password.

ln -s /usr/local/share/roundcube/plugins/carddav /usr/share/roundcube/plugins/carddav
ln -s /usr/share/roundcube/plugins/carddav /var/lib/roundcube/plugins/carddav
mkdir /etc/roundcube/plugins/carddav
cp /usr/local/share/roundcube/plugins/carddav/config.inc.php.dist /etc/roundcube/plugins/carddav/config.inc.php
ln -s /etc/roundcube/plugins/carddav/config.inc.php /usr/share/roundcube/plugins/carddav/config.inc.php
chgrp www-data /etc/roundcube/plugins/carddav/config.inc.php
chmod 640 /etc/roundcube/plugins/carddav/config.inc.php

RCMCardDAV configuration

Edit the config file

/etc/roundcube/plugins/carddav/config.inc.php

Add the following block at the end. This will add a so-called "preset" address book that all Roundcube users have access to. Obviously you need to change the details in this example so that they match your own setup.

$prefs['_GLOBAL']['pwstore_scheme'] = 'encrypted';

$prefs['addressbookshare'] = array(
  // required attributes
  'name'         =>  'Shared address book',
  // will be substituted for the roundcube username
  'username'     =>  'addressbookshare',
  // will be substituted for the roundcube password
  'password'     =>  'secret',
  // %u will be substituted for the CardDAV username
  'url'          =>  'https://cal.herzbube.ch/caldav.php/%u',
  'refresh_time' => '01:00:00',
);

Usage

Launch the web browser and log in to Roundcube to use your shiny new address book. Some notes:

The address book is generated only when the user logs in. IMPORTANT: If you were logged in while you made changes to the RCMCardDAV plugin's config file, you have to log out and log in again before you can see the newly configured address book!!!
Basically everything should be working now, e.g. start composing a new mail and when you enter something into the address field, RCMCardDAV should suggest matching contacts
On the "Address Book" page the global preset, and any user-specific, address books should now appear. If an address book is not read-only, you can now modify its entries or add new/remove existing entries

On the "Settings" page it is possible to add a user-specific address book

The configuration details for such an address book are stored in the database (as opposed to the global preset address book whose configuration details we added to the plugin config file)
The password entered by the user for the address book is encrypted with the user's IMAP password, because in the plugin config file we set the option "pwstore_scheme" to "encrypted"
If the user changes his or her IMAP password, the address book password cannot be decrypted anymore and must be re-entered

Troubleshooting

Logging

Roundcube can send logging output to syslog, but by default it sends logging output to files. The log files are placed in /var/lib/roundcube/logs, which on Debian is a symlink to this folder:

/var/log/roundcube

There are numerous options that can be set in /etc/roundcube/config.inc.php, to see them all check out the content of the defaults config file /etc/roundcube/defaults.inc.php. Two options that I have used so far:

// Log IMAP conversation to <log_dir>/imap or to syslog
$config['imap_debug'] = true;

The following line, if added to a plugin's source file, will send logging output to a file in the logging folder:

write_log("plugin.warn", "message");

In the example, "plugin.warn" forms a selector that sends the output to a file plugin.log using the "warn" level. Without the trailing ".warn" the output will probably be suppressed by a configuration option somewhere in the Roundcube or the syslog configuration (I don't know where exactly).

RCMCardDAV

To get useful diagnostics information from the RCMCardDAV plugin, find the source file that contains the functions debug() and debug_http(). In these functions, change the lines that invoke write_log() so that they use "carddav.warn" instead of just "carddav". Then change the constants DEBUG and/or DEBUG_HTTP to true.

Warning: DEBUG_HTTP generates massive amounts of log output, so you should start slowly and just use DEBUG at first.

Roundcube does not display dates

After upgrading to version 0.9.5-3 (I don't recall the previous version), Roundcube no longer displays any dates.

It appears that the solution is to set the timezone in php.ini (actually /etc/php5/apache2/php.ini):

date.timezone = Europe/Zurich

After the change Apache needs to be restarted.

Roundcube

Contents

Debian packages

References

Database configuration

Web server configuration

Package configuration

Virtual host configuration

.htaccess File

Roundcube configuration

Plugins

General instructions

listcommands

emoticons

markasjunk2

archive

zipdownload

The RCMCardDAV plugin

Summary

References

Composer

Installation

Database

Integration with Debian Roundcube

RCMCardDAV configuration

Usage

Troubleshooting

Logging

RCMCardDAV

Roundcube does not display dates

Navigation menu

Search