Locking Firefox Preferences with Autoconfig (mozilla.cfg)

System administrators often need to enforce specific browser settings across an organization to maintain security and compliance. This article provides a direct guide on how to use Firefox's Autoconfig feature—specifically utilizing the autoconfig.js and mozilla.cfg files—to configure and permanently lock browser preferences so end users cannot modify them.

Step 1: Create the autoconfig.js File

To instruct Firefox to load a custom configuration file at startup, you must first create a JavaScript file named autoconfig.js.

Navigate to the defaults/pref directory within the Firefox installation folder. Depending on your operating system, the standard paths are:

  • Windows: C:\Program Files\Mozilla Firefox\defaults\pref\
  • macOS: /Applications/Firefox.app/Contents/Resources/defaults/pref/
  • Linux: /usr/lib/firefox/defaults/pref/

Create the autoconfig.js file in this directory and add the following exact lines:

// First line must be a comment
pref("general.config.filename", "mozilla.cfg");
pref("general.config.obscure_value", 0);
  • Note: The first line of this file is ignored by Firefox, so it must always be a comment (//).
  • general.config.filename tells Firefox the name of the configuration file to look for.
  • general.config.obscure_value set to 0 tells Firefox that the mozilla.cfg file is written in plain text rather than byte-shifted (obscured) text.

Step 2: Create the mozilla.cfg File

Next, you need to create the mozilla.cfg file, which will contain the actual preferences you want to lock. This file must be placed in the root of the Firefox installation directory:

  • Windows: C:\Program Files\Mozilla Firefox\
  • macOS: /Applications/Firefox.app/Contents/Resources/
  • Linux: /usr/lib/firefox/

Create the mozilla.cfg file and ensure the very first line is a comment (//), as Firefox ignores the first line of this file as well. Below the first line, use the lockPref() function to lock specific settings.

Here is an example mozilla.cfg file:

// First line must be a comment

// Lock the browser homepage
lockPref("browser.startup.homepage", "https://www.example.com");
lockPref("browser.startup.page", 1);

// Disable the password manager
lockPref("signon.rememberSignons", false);

// Force enable Do Not Track
lockPref("privacy.donottrackheader.enabled", true);

// Disable telemetry
lockPref("toolkit.telemetry.enabled", false);

Understanding Autoconfig Functions

While lockPref() is used to prevent user changes, you can use other functions in mozilla.cfg depending on your administrative needs:

  • lockPref("preference.name", value); — Sets the preference and locks it completely. The user cannot change this setting in the Firefox UI or via about:config.
  • defaultPref("preference.name", value); — Sets the default value of a preference. The user can change it, but resetting the preference returns it to your defined default.
  • pref("preference.name", value); — Sets the preference at every startup. The user can change it during their browsing session, but it will revert to your setting the next time Firefox is launched.
  • clearPref("preference.name"); — Resets a preference back to Firefox's built-in default at startup, erasing any changes the user made.

Note on data types: Strings must be enclosed in quotes (e.g., "https://example.com"), while booleans (true or false) and integers (e.g., 1, 0) must not be in quotes.

Step 3: Verify the Configuration

To ensure the preferences are locked, launch Firefox and follow these steps:

  1. Type about:config into the address bar and press Enter.
  2. Accept the risk warning to proceed.
  3. Search for one of the preferences you configured in mozilla.cfg (for example, signon.rememberSignons).
  4. Verify that the preference appears greyed out and the edit/toggle button at the far right of the row is disabled.

If Firefox fails to launch and displays an "Failed to read the configuration file" error, double-check that both autoconfig.js and mozilla.cfg are in the correct directories, have the correct file extensions (not .txt), start with // on the first line, and contain valid JavaScript syntax.