Installation and configuration of obm-autoconf

Installation

To install obm-autoconf on the server, please run the following command

yum install obm-autoconf

or

apt-get install obm-autoconf

depending on the Linux flavor you're using.

If you want you can add a reverse proxy configuration so that /obm-autoconf is exposed on your top-level OBM URL. Otherwise, the server will listen on the default obm-tomcat port (8080 by default) at the /obm-autoconf endpoint.

Configuration

In order to make the service run, you need to deploy the configuration file (config.xml) to tell the Thunderbird extensions which settings to handle.
This is done in the file:

/usr/share/obm-autoconf/config.xml

The config.xml file is an XML document adopting the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<directories>
    <directory />
    ...
</directories>
<preferences>
    <preference />
    ...
</preferences>
<extensions>
    <extension>
        <targetApplication />
        <targetPlatform />
    </extension>
    ...
</extensions>
</configuration>

The directories section allows you to configure LDAP directories.
The preferences section allows you to set preferences.
The extensions section allows you to configure extensions to be installed on client computers.

The Thunderbird extensions that obm-autoconf can deploy are located in the /usr/share/obm-autoconf/xpi directory. It is possible to download extensions from the Internet directly, but for security and performance reasons, Linagora recommends installing these extensions on the server and making sure that the extensions are downloaded from the server.

Configuring LDAP directories

To add an LDAP directory to the configuration, you will need to add a directory element to the directories section of the configuration file. This element follows the following definition:

<directory id="" label="" uri="" autocomplete=""/>

With the following details:

  • The id attribute defines the unique identifier of the directory. The latter must be globally unique throughout the configuration.
  • The label attribute defines the label, or the description of the directory. This value will be displayed to the user in Thunderbird.
  • The uri attribute defines the URI for accessing the directory. This attribute has a complex structure detailed below.
  • The autocomplete attribute is used to define whether the directory is accessed by Thunderbird during auto-completion of addresses. Possible values ​​are true or false.

Sample configuration:

<directory id="ldap-directory-0001" label="People" uri="ldap://ldap.myserver.com:389/ou=people,dc=server.com??sub?(objectclass=inetOrgPerson)" autocomplete="true"/>

The uri attribute MUST follow the format ldap://%HOST%:%PORT%/%BASE%??%SCOPE%?%FILTER%. Variables are:

  • %HOST% - The host name or IP address of the LDAP server
  • %PORT% - The port on which the client must connect to the LDAP server. LDAP default port is 389
  • %BASE% - The search base
  • %SCOPE% - The scope of the search. Possible values ​​are "no value" (search in the database only), "sub" (the entire branch, from the search base) or "one" (a depth level)
  • %FILTER% - The LDAP filter used for searching

To remove an LDAP directory from the configuration, simply remove the associated directory element from the configuration file.

Configuring preferences

In order to add a preference to the configuration, it will be necessary to add a preference element to the preferences section of the configuration file. This element follows the following definition:

<preference type="" name="" value="" set=""/> 

With the following details:

  • The type attribute defines the type of the preference. Possible values ​​are string (string), integer (integer), or boolean (Boolean, true or false).
  • The name attribute defines the name of the preference.
  • The value attribute defines the value of the preference.
  • The set attribute defines the lock type for the preference. Possible values ​​are user (no lock, the user can change the value) or lock (the value is locked, the user can not modify it).

The use of lock triggers, depending on the preference entered, the display in Thunderbird of messages indicating that the administrator has locked access to preference or functionality.

Sample configuration:

<preference type="boolean" name="app.update.enabled" value="false" set="lock"/> 

To remove a preference, simply remove the associated preference item from the configuration file.

Mozilla does not provide an exhaustive list of preferences available in Thunderbird but provides a graphical editor to navigate preferences and the following page, although not exhaustive, has many preferences listed.

Configuring extensions

In order to configure the deployment of a new extension, it will be necessary to add an extension element in the extensions section of the configuration file. This element follows the following definition:

<extension id="" src="" version=""> 
    <targetApplication id="" minVersion="" maxVersion=""/> 
    <targetPlatform name=""/>
</extension>

With the following details:

  • The id attribute of the extension element defines the identifier of the extension to be installed. This value must imperatively reflect the identifier entered in the manifest of the extension (file install.rdf).
  • The src attribute defines the URL from which the extension should be downloaded by clients.
  • The version attribute defines the version of the extension to be deployed.
  • The id attribute of the targetApplication element defines the identifier of the target application. The identifier of Thunderbird is {3550f703-e582-4d05-9a08-453d09bdfdc6}.
  • The minVersion attribute specifies the minimum version of Thunderbird to use the extension.
  • The maxVersion attribute specifies the maximum version of Thunderbird to use the extension.

Using these two attributes limits the use of certain extensions to certain versions of Thunderbird. This also allows you to use different versions of the same extension depending on the version of Thunderbird.

  • The name attribute of the targetPlatform element indicates the operating system required to use the extension. Possible values ​​are WINNT (Windows), Darwin (Mac) or Linux.

It is possible to not include the targetPlatform element at all, indicating that the extension can be used on any operating system.

Sample configuration:

<extension id="{e2fda1a4-762b-4020-b5ad-a41df1933103}" src="https://obm2.appli.dgfip/obm-autoconf/xpi/lightning-1.9.24obm-tb-linux_x86.xpi" version="1.9.24obm">
    <targetApplication id="{3550f703-e582-4d05-9a08-453d09bdfdc6}" minVersion="17.0" maxVersion="17.*"/> 
    <targetPlatform name="Linux"/> 
</extension>

To remove an extension, simply remove the associated extension from the configuration file.

Using the Thunderbird extension

To enable Thunderbird clients to synchronize with OBM, you need to follow these steps:

  • Download this extension
  • Unzip (a xpi file is actually a ZIP archive) the extension to a temporary folder
  • Edit the file modules/specificRules.jsm with any text editor to change the global config object at the top of the file. This object contains the LDAP server address, the IMAP and SMTP server details, etc. If required, and depending how you deployed the obm-autoconf backend, also change the initial and periodic LDAP URLs at the bottom of the file.
  • Zip back the extension into a .xpi file
  • Install the resulting extension into a fresh Thunderbird profile. Details on how to create or manage profiles is out of scope of this document.

At next Thunderbird restart, you'll be prompted for a email address and a password. Once done, you will have the following created automatically:

  • A IMAP account
  • An associated SMTP account
  • New extensions deployed, depending on the configuration
  • New settings deployed, such as default OBM connector settings, depending on the configuration
  • New LDAP directories deployed, depending on the configuration