Importing SquirrelMail Address Books to Roundcube

Overview

Warning:
  • This document is only valid for cPanel & WHM versions 78 and 80.
  • Roundcube version 1.3.8 and earlier does not support email addresses that contain Unicode characters.
  • We recommend that only experienced server administrators perform the steps in this document.
  • Because cPanel, L.L.C. doesn’t develop SquirrelMail, cPanel Technical Support can’t help with address book imports.
Note:

For instructions on how to migrate SquirrelMail address books to Horde, read our Importing SquirrelMail Address Books to Horde documentation.

This document describes the roundcube_squirrelmail_contact_import plugin.

We deprecated SquirrelMail in cPanel & WHM version 74 and removed it in cPanel & WHM version 78. The roundcube_squirrelmail_contact_import plugin migrates a SquirrelMail user’s email contact list to their Roundcube address book. When a Roundcube user logs in to their email account after the hosting provider installs the plugin, the system migrates the user’s SquirrelMail contacts to Roundcube.

Install and uninstall the plugin

To install the plugin, run the following command as the root user: 

yum install roundcube-squirrelmail-contacts-import-plugin

The system adds the following files to the /usr/local/cpanel/base/3rdparty/roundcube/plugins/ directory: 

1
2
3
4
5

cpanel_squirrelmail_contact_import/
cpanel_squirrelmail_contact_import/config.inc.php
cpanel_squirrelmail_contact_import/config.inc.php.dist
cpanel_squirrelmail_contact_import/cpanel_squirrelmail_contact_import.php
cpanel_squirrelmail_contact_import/LICENSE.md

To uninstall the plugin, run the following command: 

yum remove roundcube-squirrelmail-contacts-import-plugin

Configuration options

You can configure the following options for the plugin in the /usr/local/cpanel/base/3rdparty/roundcube/plugins/cpanel_squirrelmail_contact_import/config.inc.php file:

Option Description Example
cpanel_squirrelmail_data_dir Sets the full path to the SquirrelMail data directory. 
$config['cpanel_squirrelmail_data_dir'] = getenv('HOME'). '/.sqmaildata';
cpanel_squirrelmail_run_once Creates a touch file in the cpanel_squirrelmail_data_dir to prevent the plugin from running more than once. 
$config['cpanel_squirrelmail_run_once'] = true;
cpanel_squirrelmail_unique Checks for duplicate email addresses. 
$config['cpanel_squirrelmail_unique'] = false;
cpanel_squirrelmail_group_name Creates a new email folder for imported SquirrelMail contacts.
Note:
If you enable this option and set the cpanel_squirrelmail_unique option to true, the system adds any duplicate email addresses to new email groups. 
$config['cpanel_squirrelmail_group_name'] = 'SquirrelMail Contacts';
cpanel_squirrelmail_log_level Configures the type of information for the system to record in the cPanel user’s /home/user/tmp/error.log file.
  • 0 — Disable this setting.
  • 1 — Only record errors in the error.log file.
  • 2 — Record all information in the error.log file.
 
$config['cpanel_squirrelmail_log_level'] = 1;
cpanel_squirrelmail_file_charset Configures the SquirrelMail files’ character set. To configure this option for the ASCII character set, leave this option blank. 
$config['cpanel_squirrelmail_file_charset'] = '';

The full configuration file will resemble the following example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// full path to the squirrelmail data directory
$config['cpanel_squirrelmail_data_dir'] = getenv('HOME'). '/.sqmaildata';

// Place a "touch" file in $config['cpanel_squirrelmail_data_dir'], preventing the plugin from
// running again if the file exits.
$config['cpanel_squirrelmail_run_once'] = true;

// whether or not to check for duplicate addresses - if used with the
// cpanel_squirrelmail_group_name option duplicates will be added to new groups
$config['cpanel_squirrelmail_unique'] = false;

// optional new group name for imported contacts - set to false to disable
$config['cpanel_squirrelmail_group_name'] = 'SquirrelMail Contacts';

// log level 0 to disable, 1 for errors only, 2 for verbose
// the default log file is the cpanel users /home/user/tmp/error
$config['cpanel_squirrelmail_log_level'] = 1;

// file charset - e.g. 'EUC-JP'. Leave empty for ASCII.
$config['cpanel_squirrelmail_file_charset'] = '';

The Roundcube interface

After you install the plugin, the system migrates any SquirrelMail contacts to Roundcube. These contacts reside in the SquirrelMail mailbox. This mailbox resides in the Personal Addresses mailbox in the Groups section of the roundcube interface.


Log file

The log data for this plugin resides in the /home/username/logs/roundcube file and resembles the following example:

Note:
  • In cPanel & WHM version 78, the log data resides in the /home/username/tmp/errors file.
  • In these filepaths, username represents a cPanel user’s username.
  • This example displays a list of SquirrelMail address book migration errors.
1
2
3
4
5

[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid ökçe - ökçe@nothing.com for user hoboloco@nothing.com]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid Dörte - Dörte@Sörensen.nothing.com for user hoboloco@nothing.com]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid θσερ - θσερ@εχαμπλε.ψομ for user hoboloco@nothing.com]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid 用户@例子 - 用户@例子.广告 for user hoboloco@nothing.com]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid Pelé@nothing.com - Pelé@nothing.com for user hoboloco@nothing.com]