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
- 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.
- Unlocks a preference that was previously locked.
- Gets the value of the specified preference.
- 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.
- Gets the value of the specified environment variable from the user's environment.
var pref = Components.classes["@mozilla.org/preferences;1"]. createInstance(Components.interfaces.nsIPref);
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.
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.
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
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:
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);
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 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:
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.
- Firefox Autoconfig Setup at MIT
- Mozilla Autoconfig Guide
- Automatic Mozilla Configuration
- Pre-Configuring Mozilla
- Files in Mozilla Profile Directories
- Mozilla Preferences Manual
- #222973 - Documentation needed for Mozilla Autoconfig.