Purpose

Mozilla Autoconfig (aka. Mission Control) allows administrators to centralize configuration and management of Mozilla Thunderbird. Settings specified via autoconfig can be changed at any time and are automatically applied when Mozilla Thunderbird starts up.

Writing Configuration Files

Autoconfig configuration files are Javascript files (aka ECMAScript). The file(s) are executed on Thunderbird startup, and any preferences they specify are applied to Thunderbird. Autoconfig provides a set of Pref API calls to manage preferences. In addition, most standard Javascript language features are supported, excluding DOM items. Furthermore, many Mozilla XPCOM components and interfaces can be used in config files.

Prefs API

Autoconfig provides a set of javascript Pref APIs to help manage preferences. The following functions are available:

function getPrefBranch(): Gets the root of the preferences tree.

function pref(prefName, value): Sets the currentvalue of the preference to the specified value.

function defaultPref(prefName, value): Makes the specified value the default value for a preference.

function lockPref(prefName, value): Locks a preference to the specified value. Users cannot change locked preferences.

function unlockPref(prefName): Unlocks a preference that was previously locked.

function getPref(prefName): Gets the value of the specified preference.

function setLDAPVersion(version): Sets the LDAP version used by the server. (Requires LDAP support)

function getLDAPAttributes(host, base, filter, attribs): Gets LDAP attributes from the given server. (Requires LDAP support)

function getLDAPValue(str, key): Gets the LDAP value for a given string, filtered by the key. (Requires LDAP support)

function displayError(funcname, message): Pops up a dialog box containing an error message when Thunderbird is started.

function getenv(name): Gets the value of the specified environment variable from the user's environment.

XPCOM API

You can also manipulate prefs using Mozilla XPCOM. In particular, the nsIPref and nsIPrefBranch interfaces provide a variety of methods for manipulating preferences. You can call any of the listed functions from Javascript, provided that it's definition is not preceeded by the [noscript] tag. To create an interface object in Javascript, use the following code:


var pref = Components.classes["@mozilla.org/preferences;1"].
             createInstance(Components.interfaces.nsIPref);

You can then call functions provided by that interface:


pref.lockPref("signon.rememberSignons");

Note that XPCOM isn't limited to prefs manipulation. XPCOM provides access to most of Thunderbird's functionality, including most of the internal C functions.

Setup

The following procedure can be used to setup Autoconfig:

1. Ensure Autoconfig is Enabled

For autoconfig to work, autoconfig support must be enabled during the build process. The current official Thunderbird builds have it enabled by default, so you shouldn't need to build Thunderbird yourself in most cases.

If you are building Thunderbird yourself, you'll need to ensure that autoconfig is enabled. autoconfig code is part of the pref extension. So you will have to add the option:


ac_add_options --enable-extensions=pref

To your .mozconfig file. To check whether a given Thunderbird binary includes the pref extension, go to the about:buildconfig page in the browser. If you see pref in the list of enabled extensions, you're all set.

If you plan on using LDAP as part of your configuration process, you will need to use a build that has LDAP support compiled in. LDAP support is enabled by default in the current official Thunderbird builds.

If you are building Thunderbird yourself, you should ensure that the


ac_add_options --disable-ldap

option is not present in the .mozconfig file you use to build Thunderbird.

NOTE: the getLDAP*() functions will fail if LDAP support is not compiled into your build.

For informantion on how to build Thunderbird, check out the Mozilla Build documentation and the Thunderbird Build Documentation. The Mozilla Build Configurator can help generate the .mozconfig file for your build.

2. Edit all.js

The greprefs/all.js file contains preferences that control the behavior and configuration of the Gecko Runtime Environment (GRE). For the purposes of autoconfig, there are two preferences that must be set in all.js -- general.config.filename and general.config.obscure_value.

The general.config.filename preference specifies the filename of the Mission Control configuration file. (For example: thunderbird.cfg). This file must be located in the root of the Mozilla Thunderbird binary directory (i.e. the same directory as thunderbird-bin on UNIX or thunderbird.exe on Windows).

The general.config.obscure_value preference specifies how the configuration file is obscured. Thunderbird expects that each byte in the file will be rotated by the specified value. The default value is 13. If this value is left unchanged, then the configuration file must be encoded as ROT13. Autoconfig will fail if the cfg file is not encoded as specified by this preference. A value of 0 indicates that the file is unencoded-- i.e. it is unobscured plain text. It is recommended that you set this value to 0. (This will allow you to skip the encoding step in part 3.)

Entries in this file are applied in order. If a preference is set multiple times, the last instance takes precedence. Here are a couple of sample entries that can be added to the end of all.js:


pref('general.config.obscure_value', 0);
pref('general.config.filename', 'thunderbird.cfg');

3. Create the .cfg File

On startup, Thunderbird will automatically read administrative settings from the cfg file. If you wish, you can handle all of Thunderbird's configuration in this file. However, a more flexible setup is to use this file as a callfile.

When used as a callfile, the .cfg file directs Thunderbird to load it's configuration from another location, such as a public website. This allows one to centralize configuration across multiple installations. You can retrieve the file using any of the protocols supported by Thunderbird. A sample callfile is shown below:


lockPref("autoadmin.global_config_url","http://example.com/autoadmin.js");
lockPref("autoadmin.append_emailaddr",false);

The first line directs Thunderbird to load the javascript file from the specified address. The second line tells Thunderbird not to append the user's email address to the request. If you want to dynamically generate the configuration file for each user, you will likely want to set this preference to true.

If you set the general.config.obscure_value in all.js to any value other than zero, you will need to encode your finished callfile before placing it in the Thunderbird binary directory. You can use the moz-byteshift.pl script to do so. For example, if you wanted to encode the file thunderbird.js to thunderbird.cfg using ROT13, you would use the command:


./moz-byteshift.pl -s 13 > thunderbird.js < thunderbird.cfg

4. Create the Configuration File

On startup, Thunderbird will automatically fetch the configuration file from the server and execute it. You should place all of your configuration settings in this file. Here's a short (incomplete) example:


var userName = getenv("USER");
lockPref("mail.server.server1.hostname", "mail.example.com");
lockPref("mail.server.server1.name", userName + "@example.com");
lockPref("mail.server.server1.port", 993);
lockPref("mail.server.server1.serverFilterName", "SpamAssassin");
lockPref("mail.server.server1.type", "imap");
lockPref("mail.server.server1.userName", userName);
defaultPref("mail.server.server1.cleanup_inbox_on_exit", true);
defaultPref("mail.server.server1.download_on_biff", true);
defaultPref("mail.server.server1.empty_trash_on_exit", true);
defaultPref("mail.server.server1.login_at_startup", true);

Security

Thunderbird supports GSSAPI, so you can use additional authentication methods against your mail server, aside from the ones built-in to Thunderbird. For example, you can set up Thunderbird for single sign-on using Kerberos, and use Autoconfig to configure the GSSAPI preferences for your environment.

Debugging

Debugging autoconfig is sometimes tricky. You set the following environement variables to provide some assistance.


set NSPR_LOG_MODULES=MCD:5
set NSPR_LOG_FILE=~/log.txt

These commands will enable logging in the MCD module. This will cause Thunderbird to note when it reads the autoadmin.js file, and where it reads it from.

The pref API also has a function to help debugging: displayError(). This function should popup a message on Thunderbird startup. Unfortunately it seems to be broken in the current version of Thunderbird.

You can check the status of preferences by looking at the about:config page in Thunderbird. All of the set preferences are listed, as well as their status.

Note: configuration files must be readable by all users for autoconfig to work. Make sure your file permissions are set properly.

Additional Resources

Autoconfig Guides

Mozilla Bugs

#222973 - Documentation needed for Mozilla Autoconfig.

The SIPB Thunderbird Locker - Maintainers

Home

Maintainers

Support