Customizing Firefox Using AutoConfig

AutoConfig files can be used to set and lock preferences that are not covered by [[Customizing Firefox Using Group Policy|group policy on Windows]] or [[Customizing Firefox Using policies.json|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. __TOC__ == Setting up AutoConfig == To use AutoConfig, place two files into the Firefox directory. On Windows, they go in the same directory where Firefox is installed. On macOS, they go into the Contents/Resources directory of the Firefox.app. The first file to create is named '''autoconfig.js''' and it must be placed into the <code>browser/defaults/preferences</code> directory. It should contain the following lines: // IMPORTANT: Start your code on the 2nd line pref("general.config.filename", "mozilla.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 '''mozilla.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 <code>.cfg</code>, the AutoConfig file is a JavaScript file. This allows for additional Javascript to be written within the file to add different logic in different situations. == 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 lockPref("pref.privacy.disable_button.view_passwords",true); in your AutoConfig file will disable the {button View Passwords} button. Other preferences that lock buttons include: *pref.general.disable_button.default_browser *pref.browser.homepage.disable_button.current_page *pref.browser.homepage.disable_button.bookmark_page *pref.browser.homepage.disable_button.restore_default *security.disable_button.openCertManager *security.disable_button.openDeviceManager *app.update.disable_button.showUpdateHistory *pref.privacy.disable_button.cookie_exceptions *pref.privacy.disable_button.view_cookies *pref.privacy.disable_button.view_passwords *pref.privacy.disable_button.view_passwords_exceptions *pref.downloads.disable_button.edit_actions == Centralized Management == The AutoConfig file can be managed centrally. To do so, the location of a secondary AutoConfig file in the primary AutoConfig file: pref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js"); The URL can be any protocol supported by Firefox, including the <code>file:</code> 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 <code>autoadmin.refresh_interval</code> 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 <code>autoadmin.offline_failover</code> and <code>autoadmin.failover_to_cached</code>. Every time an AutoConfig file is retrieved remotely, a backup copy of that file is created in the user’s profile directory called <code>failover.jsc</code>. If the preference <code>autoadmin.failover_to_cached</code> is set to <code>false</code>, 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 <code>true</code>, it simply uses the cached file and continues. The preference <code>autoadmin.offline_failover</code> controls whether or not the cached file is used when the user is offline. If it is set to <code>true</code>, 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: pref("autoadmin.append_emailaddr", true); This will append a question mark (?) and an email address to the request. Because Firefox doesn’t use email addresses, the <code>mail.identity.useremail</code> preference must be set. If it is not set, Firefox will display a prompt asking for the email address. Because the AutoConfig file is a Javascript file, this preference can be set before setting <code>autoadmin.global_config_url</code>. For example: var user = getenv("USER"); lockPref("mail.identity.useremail", user); lockPref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js");

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.

Setting up AutoConfig

To use AutoConfig, place two files into the Firefox directory. On Windows, they go in the same directory where Firefox is installed. On macOS, they go into the Contents/Resources directory of the Firefox.app.

The first file to create is named autoconfig.js and it must be placed into the browser/defaults/preferences directory. It should contain the following lines:

// IMPORTANT: Start your code on the 2nd line
pref("general.config.filename", "mozilla.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 mozilla.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 .cfg, the AutoConfig file is a JavaScript file. This allows for additional Javascript to be written within the file to add different logic in different situations.

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

lockPref("pref.privacy.disable_button.view_passwords",true);

in your AutoConfig file will disable the View Passwords button. Other preferences that lock buttons include:

• pref.general.disable_button.default_browser
• pref.browser.homepage.disable_button.current_page
• pref.browser.homepage.disable_button.bookmark_page
• pref.browser.homepage.disable_button.restore_default
• security.disable_button.openCertManager
• security.disable_button.openDeviceManager
• app.update.disable_button.showUpdateHistory
• pref.privacy.disable_button.cookie_exceptions
• pref.privacy.disable_button.view_cookies
• pref.privacy.disable_button.view_passwords
• pref.privacy.disable_button.view_passwords_exceptions
• pref.downloads.disable_button.edit_actions

Centralized Management

The AutoConfig file can be managed centrally. To do so, the location of a secondary AutoConfig file in the primary AutoConfig file:

pref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js");

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 autoadmin.offline_failover and autoadmin.failover_to_cached.

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:

pref("autoadmin.append_emailaddr", true);

This will append a question mark (?) and an email address to the request.

Because Firefox doesn’t use email addresses, the mail.identity.useremail preference must be set. If it is not set, Firefox will display a prompt asking for the email address. Because the AutoConfig file is a Javascript file, this preference can be set before setting 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");