Customizing Firefox Using AutoConfig
AutoConfig files can be used to set and lock preferences that are not covered by group policy on Windows or the policies.json for Mac and Linux. This method can be used to automatically change user preferences or prevent the end user from modifiying specific preferences by locking them.
Table of Contents
Setting up AutoConfig
To use AutoConfig, you need to create two files, one at the top level, and one in a subdirectory. On Windows, paths are based on directory where Firefox is installed. On macOS, paths are based on the Contents/Resources directory of the Firefox.app.
<<< NOTE: The autoconfig.js file must use Unix end-of-line (LF), even on Windows systems with Firefox 60 or higher. >>>
The first file to create is named autoconfig.js and it must be placed into the
defaults/pref directory. It should contain the following two lines:
pref("general.config.filename", "firefox.cfg"); pref("general.config.obscure_value", 0);
The first line specifies the name of the AutoConfig file. The name of the file can be customized, but the location of the file cannot be changed.
The second line indicates that the AutoConfig should not be obscured. By default, Firefox expects the file to be byte shifted by 13 bytes in order to obfuscate it.
The second file to create is called firefox.cfg and it is placed at the top level of the Firefox directory. It should always begin with a commented line, such as:
// IMPORTANT: Start your code on the 2nd line
Although the extension of an AutoConfig file is typically
Functions of AutoConfig
The following functions are available within an AutoConfig file:
pref(prefName, value) – sets the user value of a preference. This function explicitly sets the preference as a user preference. That means that if the user has changed the value, it will get reset every time the browser is started.
defaultPref(prefName, value) – sets the default value of a preference. This is the value that a preference has when the user has not set any value or the user resets the preference. It can be permanently changed by the user.
lockPref(prefName, value) – sets the default value of a preference and locks it. This is the most commonly used function. Locking a preference prevents a user from changing it, and in most cases, disables the UI in preferences so it is obvious to the user that the preference has been disabled.
unlockPref(prefName) – unlocks a preference. As an example, this would be used in case where a preference should be locked for all users, but unlocked for particular users.
getPref(prefName) – retrieves the value of a preference. If the preference doesn’t exist, it displays an error. This function should only be used on preferences that always exist.
clearPref(prefName) – removes the user value of a preference, resetting it to its default value.
displayError(funcname, message) – displays an error in a specific format, which is a handy tool for debugging.
Netscape.cfg/AutoConfig failed. Please contact your system administrator. Error: [funcname] failed: [message]
getenv(name) – used to query environment variables. This can allow access to things like usernames and other system information.
Disabling UI Elements
In cases where UI elements are not automatically disabled in the preferencess, there are some “disable_button” preferences that when locked, disable buttons. For example, including
in your AutoConfig file will disable thebutton. Other preferences that lock buttons include:
The AutoConfig file can be managed centrally. To do so, the location of a secondary AutoConfig file in the primary AutoConfig file:
The URL can be any protocol supported by Firefox, including the
file: protocol to point to a file on a networked drive. The format of the remote AutoConfig file is the same as the AutoConfig file on the client, except that the first line is not ignored.
There are other preferences that control aspects of AutoConfig. The
autoadmin.refresh_interval preference causes the AutoConfig to refresh at a given interval specified in minutes. There are also preferences related to how offline mode is handled, including
Every time an AutoConfig file is retrieved remotely, a backup copy of that file is created in the user’s profile directory called
failover.jsc. If the preference
autoadmin.failover_to_cached is set to
false, Firefox reads the cached file, marks the browser as offline and locks the preference so the user cannot go online. If the preference is set to
true, it simply uses the cached file and continues. The preference
autoadmin.offline_failover controls whether or not the cached file is used when the user is offline. If it is set to
true, the cached file is used.
User Specific Preferences
If user specific information needs to be included in the AutoConfig file, the following preference should be set:
This will append a question mark (?) and an email address to the request.
Because Firefox doesn’t use email addresses, the
autoadmin.global_config_url. For example:
var user = getenv("USER"); lockPref("mail.identity.useremail", user); lockPref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js");