Roundcube

From HerzbubeWiki
Jump to navigation Jump to search

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


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-available/roundcube.conf

Which in turn is symlinked from 

/etc/apache2/conf-enabled/roundcube.conf

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/public_html
  Alias /robots.txt /var/www/mail.herzbube.ch/robots.txt

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

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


.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['imap_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
    • The default port, if not specified, is 143, which 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['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'] = true;
    • The default value for this is false, but I want to have spell checking enabled
    • The default spellcheck engine (set in defaults.inc.php) is "enchant" which requires the Debian package php-enchant. This package should be automatically installed due to a "Recommends" dependency from roundcube-core.
  • 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['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


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


markasjunk

  • This plugin is part of the Debian package roundcube-plugins
  • 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 markasjunk execute sa-learn when it processes a message. This is how the config file /etc/roundcube/plugins/markasjunk/config.inc.php looks like:
<?php
$config = [];
$config['markasjunk_learning_driver'] = 'cmd_learn';
$config['markasjunk_spam_cmd'] = 'sa-learn --spam --username=%u %f';
$config['markasjunk_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['markasjunk_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 flags that this plugin tries to set when a message is marked as spam or ham are called "Junk" and "NonJunk", respectively. These flags are non-standard flags, described as an extension in RFC5232. It's not clear whether Dovecot supports these flags. Courier did not support the flags when I was still using that IMAP server.


archive

  • This plugin is part of the Debian package roundcube-plugins
  • This plugin adds a button to move the selected messages to an archive folder. The folder (and the optional structure of subfolders) can be selected in the settings panel.


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 plugin requires the Debian package php-zip to be installed. If the package is missing errors are logged in /var/log/roundcube/errors.log.


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


Composer

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

With a very old pre-v4 version of the plugin where I cloned the Git repository I did follow that instruction. Old versions of this wiki page contain relevant information.

With modern plugin versions, however, the guide also has a section titled Installation with roundcube installed from Debian/Ubuntu repositories which recommends to install from a tarball. That is what I am following, for details see the next section.


Installation from tarball

The following steps install the source code from a freshly downloaded tarball. This already contains all the dependencies that one would normally need to install via PHP composer. 

mkdir -p /usr/local/share/roundcube/plugins/carddav-v5.1.0
cd /usr/local/share/roundcube/plugins/carddav-v5.1.0
wget https://github.com/mstilkerich/rcmcarddav/releases/download/v5.1.0/carddav-v5.1.0.tar.gz
tar xfpvz carddav-v5.1.0.tar.gz


Next we create a symlink that points to the installation. The symlink provides a stable name that points to a moving target - when we install a new version of the plugin we have to change the symlink so that it points to the new version. The following commands do all that: 

rm -f /usr/local/share/roundcube/plugins/carddav
ln -s /usr/local/share/roundcube/plugins/carddav-v5.1.0/carddav /usr/local/share/roundcube/plugins/carddav


The following commands need to be executed only once, when RCMCardDAV is installed for the very first time. The 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
chgrp www-data /etc/roundcube/plugins/carddav/config.inc.php
chmod 640 /etc/roundcube/plugins/carddav/config.inc.php


Finally, this command needs to be executed every time a new version of the plugin is installed: 

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


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. When the plugin is updated it will also apply schema updates automatically on next login. It is therefore important 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


RCMCardDAV configuration

If the plugin is updated, read the release notes to find out if any changes to the configuration are needed.


If changes are needed, or the plugin is installed for the first time, edit this 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. 

// Disallow users to add custom addressbooks (default: false)
$prefs['_GLOBAL']['fixed'] = true;

$prefs['addressbookshare'] = [
  'accountname'  =>  'Shared address book',

  'username'     =>  'addressbookshare',
  'password'     =>  'Tie7loongikoo^d',

  // User cannot modify these settings in the settings pane
  'fixed'        =>  ['discovery_url', 'username', 'password', 'ssl_noverify', 'preemptive_basic_auth'],

  // Explicitly specify the addressbook, because we don't want to use auto-discovery
  'extra_addressbooks' => [
    [ 
      // %u will be substituted for the CardDAV username
      'url'          =>  'https://cal.herzbube.ch/caldav.php/%u',

      // User cannot add, modify or delete addressbook entries
      'readonly'     =>  true,

      // Cached addressbook entries are refreshed from the server after this time
      'refresh_time' => '01:00:00',

      // User cannot modify these settings in the settings pane
      'fixed'        =>  ['url'],
    ],
  ],
];


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 default value of the config option "pwstore_scheme" is "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.

Retrieved from "https://wiki.herzbube.ch/index.php?title=Roundcube&oldid=7038"