Hack 29. Remotely Manage User Configurations
Make sure all users in an enterprise have a uniform set of configured preferences.
This hack shows how to take configuration control away from the Firefox user. Firefox provides a little support for locking preference files. It provides no support for other parts of the profile. This means that most parts of the profile must be managed with filesystem access controls, such as ownership and read/write permissions. This is something of a problem if you require extensive configuration control.
On the plus side, the two configuration features described later in this hack, ReadConfig and AutoConfig, apply to Netscape 4.x-7.x and all these Mozilla-based products: Mozilla Application Suite, Firefox, Thunderbird, Camino, and probably a few others as well. They can be used to manage all these products from one central point. The two features are sometimes collectively called autoconfig.
3.9.1. Locking Files Using the Operating System
Many of the files in the profile that you would want to lock (for example, cookies.txt, mimeTypes.rdf, and the Chrome subdirectory) are located directly underneath the profile's salted directory name. It is not enough to make these files read-only. The user can remove them if write permission remains on the parent directory (permission models differ in detail between Unix and Windows). Default versions will then be regenerated the next time Firefox starts up, with read/write permissions restored. So making files read-only isn't enough.
If write permission is taken off the salted directory, extensions or other oddities that are installed at a later date will not be able to add their files to that directory. The salted directory is a common place for such oddities. Currently, the only solution to this extension problem is to assess each extension for impact using an unlocked test system before approving it for use.
You might also want to lock files in the install area. If Firefox runs over a network from a central application server, you can lock all the default (or modified) preference files and other default configuration in the install area.
It is also important to lock the registry.dat file. Users can change their profile entirely if they can modify or replace this file, so remove that possibility.
3.9.2. Surviving Special Preference Configuration Rules
There are four special syntax arrangements for .cfg scripts:
The first line invalid rule is quite confusing, because it means that Firefox ignores that first line completely. Recommended practice is to make sure files look like this:
#Mozilla Example Security Header Line lock_pref("example.pref.enabled",true); lock_pref("example.pref2.enabled",true); ...
This example shows that ill-advised use:
// Mozilla Example Security Header Line lock_pref("example.pref.enabled",true); lock_pref("example.pref2.enabled",true); ...
lock_pref("example.pref.enabled",true); // line 1 - ignored and lost lock_pref("example.pref2.enabled",true); // line 2 - recognized ...
lock_pref("check.config.enabled",true); // my check
This preference has no special meaning; it is a made-up flag. If it appears in about:config, your file has been read successfully. Don't forget to delete it using about:config before testing changes to your files.
3.9.3. Locking Preferences Using ReadConfig
ReadConfig is a small enhancement to the preferences system [Hack #23] designed to lock down preferences using a local file. It doesn't appear anywhere in the Firefox GUI or in the files supplied at install time. Two files must be modified for ReadConfig to work. First, Firefox must be told that ReadConfig is enabled. This is done with normal preferences:
Those preferences should be set in the install area, either as part of a custom Firefox installation or hacked into place afterward. They are not set by default. acme is an opaque string that names the organization (vendor) providing the custom install of Firefox (you). These preferences must be put in a file called all.js, and nowhere else. This file must be put in the install area here:
The other file, acme.cfg, is a new file that must be placed at the top of the install area in the same directory as the Firefox binary (e.g., C:\Program Files\Firefox). The following preference controls the shrouding (trivial encryption) of this acme.cfg file. The normal case is encryption using a simple ROT-13 algorithm:
Set this preference to 0 (zero) to ease testing of ReadConfig. It allows an unshrouded acme.cfg file to be read.
Summarizing all that, a minimal all.js file designed to enable ReadConfig with a standard, shrouded file looks like this:
lock_pref("general.config.vendor","acme"); lock_pref("general.config.filename","acme.cfg"); lock_pref("general.config.obscure_value",13); lock_pref("check.alljs.enabled",true); // my syntax OK flag
On startup, Firefox will see these preferences. It will load, unshroud, and first-line-strip the acme.cfg file, and then interpret its contents.
3.9.4. Updating Preferences Using AutoConfig
AutoConfig is also a small enhancement to the preference system. It doesn't appear in the Firefox GUI anywhere, or in the default install files. It allows preferences to be set from a file delivered by a web server. It facilitates centralized control; preferences can be modified in one place and automatically reapplied to all users the next time that Firefox starts up. In that respect, it is similar to the AutoProxy feature [Hack #15], but the similarity ends quickly.
autoadmin.global_config_url /* set to a http: or ftp: URL */
This preference can be put in any preference file. The only sensible place to put it is inside a ReadConfig .cfg file, where the user can't change it. The only place that uses this preference for its fundamental purpose is the internal bit of Mozilla that reads the .cfg files.
AutoConfig writes a file to the Firefox profile failover.jsc., which is a copy of the web-delivered configuration script grabbed automatically by Firefox. The configuration script is downloaded each time the profile is switched. Firefox 1.0 doesn't yet support live profile switching (unless you add an extension), so the download occurs only when Firefox starts up. It also occurs if there's no profile at all (but that is an abnormal state of affairs).
Several preferences control the way AutoConfig behaves. They should also be set somewhere that's away from the user's grubby hands.
The following preference indicates whether to tell the server who the user is, using dodgy HTTP GET syntax to send the user's email address to the server:
autoadmin.append_emailaddr /* default = false, set to true */
Firefox will do its best to find in the preference system a Thunderbird, Mozilla Email & News, or Netscape Email email address to use. The sent URL will look like this:
A sample server-supplied AutoConfig file looks like this:
lock_pref("browser.chrome.toolbar_tips",false); // whatever's needed lock_pref("check.autoconfig.enabled",true); // my syntax OK flag
3.9.5. Handling Failover Scenarios
autoadmin.offline_failover /* default = false, set to true */
If this preference is set to true, Firefox will read the locally stored failover.jsc file instead of reaching out over the network.
This further preference indicates what AutoConfig must do if Firefox fails to retrieve the configuration script from a web server:
autoadmin.failover_to_cached /* default = false, set to true */
If this preference is set to TRue, Firefox will read the failover.jsc file if retrieval or parsing of the autoconfig.jsc file fails for any reason. If that happens, Firefox will also lock this preference, which prevents any online activity until the browser restarts.
Finally, this preference is a security measure designed to stop clients from being flooded with bad configuration data:
network.online /* set to true or false */