Deploying Firefox in an enterprise environment

This page is an attempt to document the process of managing Mozilla Firefox on Windows and macOS computers in the enterprise setting, from start to finish. If you have questions, please e-mail the Enterprise Working Group mailing list at enterprise@mozilla.org. Better yet, subscribe to the list and join in the ongoing discussions.

Choose a Firefox variant

Rapid Release (RR)

Mozilla publishes a new version with incremented main version number, new features, and bug fixes every six weeks (and, as needed, additional security releases in between). On the day a major version is released, in most cases (see below for an exception) Mozilla stops providing bug fixes for the previous one.

For the planned dates for upcoming releases, see the column 'release date' in the Future branch dates table in the Mozilla wiki.

Extended Support Release (ESR)

Every seventh major version of Firefox is declared an Extended Support Release. These versions get serious bugs fixed in minor versions, for 54 weeks (nine of the six-week release cycles). There is an overlap of 12 weeks (two release cycles) between two successive ESR releases, during which both ESR releases get bug fixes.

The major ESR releases so far have been versions 10, 17, 24, 31, 38 and 45.

Many enterprises and other organizations with centrally-managed computing environments prefer to use the ESR rather than the RR versions, because then they need to test for compatibility only every 42 weeks instead of every 6 weeks. Also if there are any issues, they have 12 weeks additional time (the overlap between two ESR releases) to find a solution (in addition to the 6 weeks that they can get by testing the beta version).

Note that there can be undesired side effects if you switch from a RR version to an earlier ESR version, for example from version 26-RR back to 24.2-ESR, even if they were published on the same day. The reason for this is that often new features are built into the RR versions for test purposes before they are finished, but disabled by preference settings. Eventually Mozilla decides to toggle the feature on in a certain version. If you then downgrade to a previous version, all users keep their latest settings in their profile directories. Thus the option is now switched on, although the feature does not yet fully work in that version. If you want to switch from RR to ESR, you should do so when a new ESR release comes out.

Installation

Get the full, redistributable installer from
http://www.mozilla.org/firefox/all/ (RR)
or
https://www.mozilla.org/firefox/organizations/all.html (ESR)
rather than the "stub" or "downloader" that you get by clicking the "Download" button.
Install using the software distribution method of your choice.
The command line option for a silent install is -ms.
Optionally you can specify an INI file, for example to disable the placement of shortcuts and the installation of the MaintenanceService; see Installer Command Line Arguments.

Configuration

Find the Firefox program directory where the Firefox executable is located. For example,

in Windows this is typically either
C:\Program Files\Mozilla Firefox or
C:\Program Files (x86)\Mozilla Firefox

in macOS it is typically
/Applications/Firefox.app/Contents/MacOS

If you are specifying a configuration INI file and have set InstallDirectoryName or InstallDirectoryPath, then use that path. Subfolders mentioned below are relative to this program directory.
Create a JavaScript file. By convention autoconfig.js, but other filenames will work. For best results, it should be early in the alphabet.

in Windows
defaults\pref

on Mac
Firefox.app/Contents/Resources/defaults/pref

on Linux
defaults/pref

The three lines that you need are:
```
// Any comment. You must start the file with a comment!
pref("general.config.filename", "mozilla.cfg");
pref("general.config.obscure_value", 0)
```
The first line of the autoconfig.js and mozilla.cfg is ignored. The line shouldn't contain any configuration, nor multiline comment (/*...*/) without closing "*/".
Create a .cfg file in the Firefox program directory. By convention, mozilla.cfg, but it can be any file name really. It just has to match what is specified in general.config.filename preference above. Skip or comment out the first line, then start setting your preferences. To learn what preferences to set, go to about:config on a copy of Firefox that you have configured correctly and look for preferences that are "user set", or see the example below. Any preference that appears in about:config (and a few that don't) can be set using one of the following functions:

pref

sets the preference as if a user had set it, every time you start the browser. So users can make changes, but they will be erased on restart. If you set a particular preference this way, it shows up in about:config as "user set".

defaultPref

is used to alter the default value, though users can set it normally and their changes will be saved between sessions. If preferences are reset to default through the GUI or some other method, this is what they will go back to. Appears in about:config as "default".

lockPref

is used to lock preferences so they cannot be changed through the GUI or about:config. In many cases the GUI will change to reflect this, graying out or removing options. Appears in about:config as "locked". Some config items require lockPref to be set, such as app.update.enabled. It will not work if it set with just pref.

clearPref

can be used to "blank" certain preferences. This can be useful e.g. to disable functions that rely on comparing version numbers.

The first line of the autoconfig.js and mozilla.cfg is ignored. The line shouldn't contain any configuration, nor multiline comment (/*...*/) without closing "*/".

See Customizing Firefox autoconfig files and Customizing Firefox autoconfig files continued for more detail. For fancier stuff like disabling UI elements, you may want to use the CCK2 extension.

Example configuration file

You may see references to "complex preferences" that need to be specified in a different way; the default homepage is one, as in the example below. For more info on individual preferences, search the Knowledgebase.

// Any comment. You must start the file with a comment!
// Disable updater
lockPref("app.update.enabled", false);
// make absolutely sure it is really off
lockPref("app.update.auto", false);
lockPref("app.update.mode", 0);
lockPref("app.update.service.enabled", false);
// Disable Add-ons compatibility checking
clearPref("extensions.lastAppVersion"); 
// Don't show 'know your rights' on first run
pref("browser.rights.3.shown", true);
// Don't show WhatsNew on first run after every update
pref("browser.startup.homepage_override.mstone","ignore");
// Set default homepage - users can change
// Requires a complex preference
defaultPref("browser.startup.homepage","data:text/plain,browser.startup.homepage=http://home.example.com");

// Disable the internal PDF viewer
pref("pdfjs.disabled", true);
// Disable the flash to javascript converter
pref("shumway.disabled", true);
// Don't ask to install the Flash plugin
pref("plugins.notifyMissingFlash", false);
//Disable plugin checking
lockPref("plugins.hide_infobar_for_outdated_plugin", true);
clearPref("plugins.update.url");
// Disable health reporter
lockPref("datareporting.healthreport.service.enabled", false);
// Disable all data upload (Telemetry and FHR)
lockPref("datareporting.policy.dataSubmissionEnabled", false);
// Disable crash reporter
lockPref("toolkit.crashreporter.enabled", false);
Components.classes["@mozilla.org/toolkit/crash-reporter;1"].getService(Components.interfaces.nsICrashReporter).submitReports = false;

Packaging Extensions

Install the extension on a test machine. Look in about:support under Extensions to find the GUID.
Look in the Profile directory (ex: %APPDATA%\Mozilla\Firefox\Profiles on Win7; to find it, click Show Folder in about:support), then under "extensions" for the add-on you want. Note whether it is a single .xpi file (basically a zip file) or extracted to a folder with multiple files.
Decide how you want to deploy it. The simplest method is to drop the .xpi or folder into the program directory/distribution/extensions, but this only works for profiles created after the extension is installed. Also, if you manually update firefox by re-installing it, this directory will be deleted, so make sure you re-install the extensions as well. See Integrating add-ons into Firefox/ for alternative methods.

Also keep in mind: Add-on scopes redux

Changes Over Time

Changes in Directory Structure

The directory structure within the program directory has changed twice. When you read descriptions that were written before version 21 came out, you must take these changes into account:

In version 14 some of the pref settings stopped working when they were in a file in directory defaults/pref. The fix was to create a directory defaults/preferences and put them there.
In version 21 the new directory named browser was created. The file override.ini and the directories defaults/preferences, defaults/profile, extensions, plugins, and searchplugins were moved there. Plug-ins in the directory plugins can be reactivated by setting the preference plugins.load_appdir_plugins to true.

Custom settings in defaults/pref that worked in a version of Firefox before 21 may fail in a current or future version. If this happens, copy or move your customized files into the corresponding directories in browser/defaults/preferences and redeploy.

Mac Directory Change

Due to Apple's stricter approach to software signing, as of about version 35 or so configuration files should now be placed relative to /Applications/Firefox.app/Contents/Resources (so mozilla.cfg should go there, and autoconfig.js under /Applications/Firefox.app/Contents/Resources/defaults/pref.)

Changes in ESR 24 and newer with Adobe PDF Files

Firefox RR 19.x changed the default viewer for Adobe PDF files to use the internal Firefox viewer. This change is now in the ESR version as of 24.x, and the setting (on Windows) is changed to use the internal Firefox viewer when upgrading from 17.x, even if an external viewer had already been configured. The name of the Content Type is also changed from Adobe Acrobat Document to Portable Document Format (PDF), which makes it difficult to locate via the Tools, Options, Applications tab. To disable this, set pdfjs.disabled to true as in the example file above.