Customizing Firefox Using AutoConfig

AutoConfig files can be used to set and lock preferences that are not covered by Firefox policies. To use AutoConfig, you place two files into the Firefox directories. 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 you need to create is called autoconfig.js and it gets 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. You can specify any name you like, but the location of the file cannot be changed. The second line indicated that you do not want the AutoConfig to be obscured. By default, Firefox expects the file to be byte shifted by 13 bytes in order to obfuscate it. The second files you need to create is called firefox.cfg and it gets placed at the top level. It should always begin with a commented line: // IMPORTANT: Start your code on the 2nd line Although the extension of an AutoConfig file is typically cfg, the AutoConfig file itself is a JavaScript file. This means that you can write JavaScript within the file to have different logic in different situations. 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. lockPref(prefName, value) – sets the default value of a preference and locks it. This is the function that is most familiar to people when it comes to AutoConfig files. 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. In cases where you don’t see things getting disabled in preferences, there are some “disable_button” preferences that when locked, disable buttons. For example, if you lock the pref pref.privacy.disable_button.view_passwords it will disable the “View Passwords” button. The other preferences that lock buttons are: 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. unlockPref(prefName) – unlocks a preference. As an example, there might be cases where you lock a preference for everyone and then unlock it for a particular user. getPref(prefName) – retrieves the value of a preference. If the preference doesn’t exist, it displays an error. You should only use this on preferences that you know 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. Netscape.cfg/AutoConfig failed. Please contact your system administrator. Error: [funcname] failed: [message] This is handy for debugging. getenv(name) – allows you to query environment variables. This can allow you to do things like get things like usernames and other system information. If you want to centrally manage your AutoConfig file, you can specify 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. This includes specifying 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. If you want to have user specific information in your configuration, you can set another preference: pref("autoadmin.append_emailaddr", true); This will append a question mark (?) and an email address to the request. You may be wondering where that email address comes from. Because Firefox doesn’t use email addresses, you’ll need to set it. If you don’t, Firefox will display a prompt asking your for the email address. The preference is called mail.identity.useremail and is a string preference. Because the autoconfig file is a JS file, you can set this preference before setting autoadmin.global_config_url. You might do something like this: var user = getenv("USER"); lockPref("mail.identity.useremail", user); lockPref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js"); There are a few other preferences that control aspects of AutoConfig. autoadmin.refresh_interval causes the AutoConfig to refresh at a given interval specified in minutes. There are also some preferences related to how offline is handled, including autoadmin.offline_failover and autoadmin.failover_to_cached. Here’s how they work. 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 and then 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 then continues. The preference autoadmin.offline_failover controls whether or not the cached file is used when the user is simply offline. If it is set to true, the cached file is used.

AutoConfig files can be used to set and lock preferences that are not covered by Firefox policies.

To use AutoConfig, you place two files into the Firefox directories. 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 you need to create is called autoconfig.js and it gets 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. You can specify any name you like, but the location of the file cannot be changed.

The second line indicated that you do not want the AutoConfig to be obscured. By default, Firefox expects the file to be byte shifted by 13 bytes in order to obfuscate it.

The second files you need to create is called firefox.cfg and it gets placed at the top level.

It should always begin with a commented line:

// IMPORTANT: Start your code on the 2nd line

Although the extension of an AutoConfig file is typically cfg, the AutoConfig file itself is a JavaScript file. This means that you can write JavaScript within the file to have different logic in different situations.

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.

lockPref(prefName, value) – sets the default value of a preference and locks it. This is the function that is most familiar to people when it comes to AutoConfig files. 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. In cases where you don’t see things getting disabled in preferences, there are some “disable_button” preferences that when locked, disable buttons. For example, if you lock the pref

pref.privacy.disable_button.view_passwords

it will disable the “View Passwords” button. The other preferences that lock buttons are:

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.

unlockPref(prefName) – unlocks a preference. As an example, there might be cases where you lock a preference for everyone and then unlock it for a particular user.

getPref(prefName) – retrieves the value of a preference. If the preference doesn’t exist, it displays an error. You should only use this on preferences that you know 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.

   Netscape.cfg/AutoConfig failed. Please contact your system administrator.
   Error: [funcname] failed: [message]

This is handy for debugging.

getenv(name) – allows you to query environment variables. This can allow you to do things like get things like usernames and other system information.

If you want to centrally manage your AutoConfig file, you can specify 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. This includes specifying 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.

If you want to have user specific information in your configuration, you can set another preference:

pref("autoadmin.append_emailaddr", true);

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

You may be wondering where that email address comes from. Because Firefox doesn’t use email addresses, you’ll need to set it. If you don’t, Firefox will display a prompt asking your for the email address. The preference is called mail.identity.useremail and is a string preference. Because the autoconfig file is a JS file, you can set this preference before setting autoadmin.global_config_url. You might do something like this:

var user = getenv("USER"); lockPref("mail.identity.useremail", user); lockPref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js");

There are a few other preferences that control aspects of AutoConfig. autoadmin.refresh_interval causes the AutoConfig to refresh at a given interval specified in minutes. There are also some preferences related to how offline is handled, including autoadmin.offline_failover and autoadmin.failover_to_cached. Here’s how they work.

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 and then 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 then continues. The preference autoadmin.offline_failover controls whether or not the cached file is used when the user is simply offline. If it is set to true, the cached file is used.