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](http://www.w3.org/XML/) adopting the following structure:





...

...






...

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:

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:

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:

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: 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](https://support.mozilla.org/fr/kb/editeur-de-configuration) to navigate preferences and [the following page](http://kb.mozillazine.org/About:config_entries), 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: 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: 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](http://download.obm.org/mozilla-addons/obm-autoconf-client/stable/obm-au...) * 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 Air Jordan 1