Purpose
Mozilla Autoconfig (aka. Mission Control) allows administrators to centralize configuration and management of Mozilla Firefox. Settings specified via autoconfig can be changed at any time and are automatically applied when Mozilla Firefox starts up.
Writing Configuration Files
Autoconfig configuration files are Javascript files (aka ECMAScript). The file(s) are executed on Firefox startup, and any preferences they specify are applied to Firefox. 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 Firefox 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);
pref.lockPref("signon.rememberSignons");
Note that XPCOM isn't limited to prefs manipulation. XPCOM provides access to most of Firefox's functionality, including most of the internal C functions.
Administrative Preferences
Several preferences control the behavior of Mozilla Autoconfig. For a complete list, check the Admin Section of the Mozilla Preferences Manual.
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 Firefox builds have it enabled by default, so you shouldn't need to build Firefox yourself in most cases.
If you are building Firefox 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 Firefox 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 Firefox builds.
If you are building Firefox yourself, you should ensure that the
ac_add_options --disable-ldap
option is not present in the .mozconfig file you use to build Firefox.
NOTE: the getLDAP*() functions will fail if LDAP support is not compiled into your build.
For informantion on how to build Firefox, check out the Mozilla Build documentation and the Firefox 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: firefox.cfg). This file must be located in the root of the Mozilla Firefox binary directory (i.e. the same directory as firefox-bin on UNIX or firefox.exe on Windows).
The general.config.obscure_value preference specifies how the configuration file is obscured. Firefox 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', 'firefox.cfg');
3. Create the .cfg File
On startup, Firefox will automatically read administrative settings from the cfg file. If you wish, you can handle all of Firefox'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 Firefox 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 Firefox. A sample callfile is shown below:
lockPref("autoadmin.global_config_url","http://yourdomain.com/autoadmin.js");
lockPref("autoadmin.append_emailaddr",false);
The first line directs Firefox to load the javascript file from the specified address. The second line tells Firefox 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 Firefox binary directory. You can use the moz-byteshift.pl script to do so. For example, if you wanted to encode the file firefox.js to firefox.cfg using ROT13, you would use the command:
./moz-byteshift.pl -s 13 > firefox.js < firefox.cfg
4. Create the Configuration File
On startup, Firefox 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 example:
// Set Cache Directory
var env_user = getenv("USER");
var cache_dir = "/var/tmp/MozillaFirefox-" + env_user + "/Cache/";
lockPref('browser.cache.disk.parent_directory', cache_dir);
// Security Settings
lockPref("signon.rememberSignons", false);
Security
Firefox supports GSSAPI, so you can use additional authentication methods against your mail server, aside from the ones built-in to Firefox. For example, you can set up Firefox 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 Firefox 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 Firefox startup. Unfortunately it seems
to be broken in the current version of Firefox.
You can check the status of preferences by looking at the about:config page in Firefox. 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
- Firefox Autoconfig Setup at MIT
- Mozilla Autoconfig Guide
- Automatic Mozilla Configuration
- Pre-Configuring Mozilla
- Files in Mozilla Profile Directories
- Mozilla Preferences Manual
Mozilla Bugs
- #222973 - Documentation needed for Mozilla Autoconfig.