Customizing Firefox - Autoconfig Files

I’m doing a series where I go over each method of customizing Firefox (that I know about) and detail how it works and what it can change. Next up in our series on customizing Firefox is the infamous autoconfig file.

Before I go into detail about how autoconfig works, I want to give you a quick history lesson. This is the story of Netscape Mission Control Desktop (MCD).

MCD was Netscape's enterprise solution for customizing Netscape Communicator. If you were to look at an installation of Communicator, you would see a file called netscape.cfg file in the same directory where the executable was located. MCD worked by generating a new netscape.cfg with various customizations and then packaging that file as a part of a standard Communicator install. The file was byte shifted by 7 bytes, so a user could not modify the file, and if they removed it, Communicator wouldn't start at all.

When Netscape was open sourced, MCD fell by the way side. It was written using a lot of technology that made it difficult to port to something usable. Fortunately for us, the autoconfig infrastructure was left in place.

Autoconfig files are handled a little differently in Firefox then they were in Netscape Communicator. First off, a config file is not required. In order to use a config file, you have to specify that you want to use one in a default preferences file. It looks like this:

pref('general.config.filename', 'firefox.cfg');

You can specify any name you like, but the file still must be located in the same place as the executable.

Remember that byte shifting we talked about? With Firefox it is a shift by 13 bytes and it is still required by default. (Thunderbird has removed the need to shift the bytes - the autoconfig can be used as is.) If you would like to obfuscate your config file by byte shifting it, you can do that. Most people turn off the obfuscation by setting this preference in the same file where you specified the config file:

pref('general.config.obscure_value', 0);

There's a bug open to have Firefox not obscure the file.

So now that you've told Firefox where to get the file and whether or not to obfuscate the file, it's time to create it. Here's an example firefox.cfg

// IMPORTANT: Start your code on the 2nd line
pref("browser.rights.3.shown", true);

Now after reading the first article in this series, you might be thinking "Oh, the format is exactly the same as a default preferences" and you would be very, very wrong. This is the 2nd most misunderstood thing about autoconfig files. (The 1st is that the first line in the autoconfig file is ignored.)

Autoconfig files are real Javascript files that allow full code execution including access to XPCOM components.

That pref line above is not the same as a pref line in a preferences file, it is a call to a function called pref(). The file prefcalls.js defines a set of convenience functions that are provided for autoconfig authors. With all credit to the SIPB Firefox Locker, those functions are:

getPrefBranch() - Gets the root of the preferences tree.

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. You can see a lot of these preferences here. There are tons of examples on the web that show various locking of prefs. There’s really no way to create an exhaustive list of all the preferences that can be locked.

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]

While this can be handy for debugging, It’s a very cryptic error that I don't recommend using.

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

setLDAPVersion(version), getLDAPAttributes(host, base, filter, attribs), and getLDAPValue(str, key) are LDAP functions that are only available in Thunderbird. I don’t know enough about these to do them justice, but there is a great post on A Brundage Web-log that covers them.

I cannot stress this enough - while these are the documented functions for an AutoConfig file, the AutoConfig file is a Javascript file with full access to XPCOM Components. These means you can have some pretty complex autoconfig files. This also means you can do some really cool stuff. For instance, what if you wanted to remove history and bookmarks every time the browser started up? You could have an autoconfig file that looked like this:

//
const Cc = Components.classes;
const Ci = Components.interfaces;
var profileDir = Cc["@mozilla.org/file/directory_service;1"]
                 .getService(Ci.nsIProperties)
                 .get("ProfD", Ci.nsILocalFile);
profileDir.append("places.sqlite");
profileDir.remove(false);

This is going to open up some really cool stuff for us later (dynamically generating userChrome.css and userContent.css), but for now let's finish up our autoconfig discussion.

Now at this point you might be asking "Is there any way to centrally manage my configuration?" The answer is yes.

If you want to put your configuration on a server, you can specify the location like this in your config file:

pref("autoadmin.global_config_url","http://yourdomain.com/autoconfigfile.js");
or
lockPref("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.

I'll be honest though - I have no idea what those prefs do. Feel free to peruse the code and try to figure it out.
Update: I figured out what these prefs do. It will be in the next post.

So that's how you create an autoconfig file. In our next post, we'll look at each of the autoconfig convenience functions and explain what they do. We'll also talk about when to use an autoconfig file.

Please note: I reserve the right to delete comments that are offensive or off-topic.

Leave a Reply

Your email address will not be published. Required fields are marked *

52 thoughts on “Customizing Firefox - Autoconfig Files

  1. I think the quote below should have been a footnote on all of your other posts.

    "Remember that byte shifting we talked about? With Firefox it is a shift by 13 bytes and it is still required by default."

  2. Hi Mike,

    Very interesting stuff. I read your response here

    http://mike.kaply.com/2012/04/13/customizing-firefox-extensions-and-the-cck-wizard/

    regarding using autoconfig to set a default home page and some other settings for multiple users. I'm trying to do this in a networked school environment and started following the steps you outlined, but since I'm not really a coder, I was hoping you could give me some more step-by-step instructions. Here's what I did thus far:

    1. Found the channel-prefs.js file in C:\Program Files (x86)\Mozilla Firefox\defaults\pref
    2. Edited this file by adding the text you wrote in this article:
    pref('general.config.filename', 'firefox.cfg');
    3. Created a new file in the same location called "firefox.cfg"
    4. Edited firefox.cfg to read:

    //Skipped Line
    browser.startup.homepage=http://www.grcs.org

    When I restarted the browser, I got an error message about a failure to read the preferences file.

    I've also tried using the CCK wizard to create preferences. This has worked great, except that the preferences only load under the login in which I created the preferences - if I try a different login, there's no change (welcome screen shows, home page doesn't).

    I'd really appreciate your insight into how to best get this to work!

    Thanks,
    Chris

    • The format of the autoconfig file is:

      pref("browser.startup.homepage", "http://www.grcs.org");

      Although, browser startup homepage is the exception:

      Do:

      pref("browser.startup.homepage", "data:text/plain,http://www.grcs.org");

      • Thanks - that fix works great for my login, but the autoconfig file settings do not work when logged in as a different user (i.e. no homepage shown). Any ideas why that might be happening?

        • If a user has already set their homepage, that won't work. It sets the "default" homepage. Is it possible that happened in this case?

          • Nope. This is a brand new computer - tried logging in with a domain account that had never before logged into the computer, and it went to the regular firefox welcome page instead of the homepage.

        • Ah, the welcome page. That's different then the homepage.

          To keep that from coming up, you need to a different preference. I believe setting:

          pref("startup.homepage_welcome_url", "");

          will prevent that from happening.

          • No luck, sadly. Tried a third unique login after making this change, and it first popped up with the Import settings and data wizard. Then loaded firefox with the welcome screen and start page and a choice to choose firefox as the default browser. So whatever I'm putting in the autoconfig clearly doesn't carry over to new users (even though it should, since it's not in a user's folder, it's in the Program Files folder). If this works, there must be something else that I'm missing...

          • Hi Mike,

            I can confirm the same issue as Chris, but it's inconsistent. I'm trying to create a corporate deployment build of Firefox complete with default corp web start page, etc etc. I'm using two VM Win7 machines so that I can easily roll back to snapshots with a clean install. I'm using two as I'm currently working in two different office (nightmare!) One works perfectly and the default settings work, the other steadfastly refuse to pickup the defaults.

            channel-prefs.js

            //@line 2 "e:\builds\moz2_slave\rel-m-rel-w32-bld\build\browser\app\profile\channel-prefs.js"
            pref("app.update.channel", "release");

            prefs.js

            user_pref("browser.bookmarks.restore_default_bookmarks", false);
            user_pref("browser.cache.disk.capacity", 1048576);
            user_pref("browser.cache.disk.smart_size.first_run", false);
            user_pref("browser.migration.version", 6);
            user_pref("browser.places.smartBookmarksVersion", 4);
            user_pref("browser.rights.3.shown", true);
            user_pref("browser.startup.homepage", "[corpwebsite]");
            user_pref("browser.startup.homepage_override.buildID", "20120713134347");
            user_pref("browser.startup.homepage_override.mstone", "14.0.1");
            user_pref("browser.taskbar.lastgroupid", "E7CF176E110C211B");
            user_pref("extensions.blocklist.pingCountVersion", 0);
            user_pref("extensions.bootstrappedAddons", "{}");
            user_pref("extensions.databaseSchema", 12);
            user_pref("extensions.enabledAddons", "{972ce4c6-7e08-4474-a285-3208198ce6fd}:14.0.1");
            user_pref("extensions.installCache", "[{\"name\":\"app-global\",\"addons\":{\"{972ce4c6-7e08-4474-a285-3208198ce6fd}\":{\"descriptor\":\"C:\\\\Program Files (x86)\\\\Mozilla Firefox\\\\extensions\\\\{972ce4c6-7e08-4474-a285-3208198ce6fd}\",\"mtime\":1345542931133}}}]");
            user_pref("extensions.lastAppVersion", "14.0.1");
            user_pref("extensions.lastPlatformVersion", "14.0.1");
            user_pref("extensions.pendingOperations", false);
            user_pref("extensions.shownSelectionUI", true);
            user_pref("intl.charsetmenu.browser.cache", "UTF-8");
            user_pref("network.cookie.prefsMigrated", true);
            user_pref("places.history.expiration.transient_current_max_pages", 53676);
            user_pref("privacy.sanitize.migrateFx3Prefs", true);
            user_pref("toolkit.startup.last_success", 1345543802);
            user_pref("urlclassifier.keyupdatetime.https://sb-ssl.google.com/safebrowsing/newkey", 1348135812);
            user_pref("xpinstall.whitelist.add", "");

            I have tried prefs.js in both defaults\prefs and defaults\preferences to no avail. They just don't get copied to the user's profile. I am selecting Don't Import Anything when FF launches.

            If I manually copy prefs.js to any profile, FF picks up the settings.

            Cheers,

            Matt

            • user_pref is not used in autoconfig files or default pref files.

              It's only used in the user's prefs.js.

              So remove user_ from everything in that file.

          • Hi Mike,

            I've done some further testing. I managed to get my install files and default pref files across from the VM that worked. I tried the pref files with the installer on the VM that didn't work. Still the same problem.

            So I tried using the install files from the VM that did work on the VM where it wasn't working and hey presto, it worked.

            So I checked out the versions, both were 14.0.1, however the one that didn't work was the vanilla installer (I also tried the EN-GB only installer and this also failed), the one that did was the funnelcake installer (how I ended up with this I don't know). So it seems there is a major bug in 14.0.1 regardless of Mozilla think should now be the correct default\pref folder as in some releases it now seems that neither folder works.

            Cheers,

            Matt

          • Thanks Mike,

            I changed all the settings from user_pref to pref...it did not fix the problem, still only the funnlecake installer works.

            Cheers,

            Matt

            • In your comments about files, I see no reference to how you actually set up the config file.

              Per the instructions in this post, you create a new file called autoconfig.js. It contains:

              pref('general.config.filename', 'firefox.cfg');
              pref('general.config.obscure_value', 0);

              Then you create a file in the same directory as the Firefox executable called firefox.cfg.

              In it, you place:

              // IMPORTANT: Start your code on the 2nd line
              pref("browser.rights.3.shown", true);

              For example.

              This will set your preferences. There are no JS files except for the autoconfig.js that sets up the config file.

              I also suggest adding one preference first to verify everything works before you try a lot of preferences.

              Also, it appears that you just grabbed a prefs.js file and are trying to use it. That's not really a good idea. You should figure out what preferences you need to change and only change those.

          • Hi Mike,

            Ok slightly a case of too much haste on my part, having read you post on the change of pref directory I inferred from it and other Mozilla posts that you create all your default js files here. With this already in mind I did glaze over the top of this post, it was Chris's post that caught my attention.

            So having added autoconfig.js and firefox.cfg, all seems to be well. Why oh why there can't just be a single auto config file to edit (which is always there but blank, or has all the defaults), I don't know. I'm sure there's a very good reason otherwise I'm sure the devs wouldn't have wasted their time concocting such an odd implementation.

            Anyway, many thanks for your perception and help. :)

            Cheers,

            Matt

  3. Hi.

    I have all i need to customize Firefox 17.0.1 using de mozilla.cfg and pref.js in preferences folder. I have a software web based that works only with firefox, so with the same installer i install php, mysql, apache, firefox, etc, in the client pc. It is necesary that de margins be set in 0px for correctly software's permormance. In firefox 3.6 it was possible this thing using pref("print.print_margin_bottom", "0");, but not in firefox 4 or last. Do you knoy how to do this?
    Thanks, sorry form my english.

    • Sorry, I missed this. To set the margins, it is unfortunately printer specific.

      so:

      pref("print.PRINTERNAME.print_margin_bottom", "0");

      This is a pretty big deficiency in Firefox right now.

  4. hi mike,
    i have been reading your articles.
    i am facing the problem in making the custom config file.

    i tired step by step as you told to do
    first i located channel-prefs.js file and removed the pref("app.update.channel", "release");
    with this two lines
    pref("general.config.filename", "firfox.cfg");
    pref("general.config.obscure_value", 0);

    and created firfox.cfg file in the same location where channel-prefs.js exist.

    and edit my firfox.cfg file
    leaving 1 line.
    pref('browser.rights.3.shown', true);
    pref('browser.startup.homepage', 'http://www.grcs.org');
    and then i restarted my firefox so its giving me this error
    Failed to read the configuration file. Please contact your system administrator

    please tell me what i am doing wrong ?

    it will be very great if you give me advice .

    • First, you shouldn't remove the app.update.channel pref frmo channel-prefs.js.

      Second, it appears that the first line of your firefox.cfg file doesn't start with a comment:

      // Must have a comment as the first line,

      • Thanks alot for your reply I would look into it .
        I have one question
        I want to change my printer height and width with respect to my application environment .eg.in one page I want print the document in a4size and in other page I am using my custom size I have jsprintsetup add on but its not changing the size of the paper print is coming in a4 size until and unless I change the paper size from printer dialog .then after searching on google I found your articles about customizing Firefox. Is there any way to change the size dynamically while my application is running from js ?
        It will be very great :) thanks in advance

      • hi mike,
        i have tried as what you told me to do .
        no error is coming up but when i restart the firefox with this setting
        //this is great
        pref(‘browser.rights.3.shown’, true);
        pref(‘browser.startup.homepage’, ‘http://www.google.com’);
        nothing happens and when i checked the about:config file its show main about:home
        on the browser.startup.homepage.

  5. Late to the gaqme, but first like some others, kudos to you since this is the best resource I have found to figure out ways to implement FireFox ESR into corporate environment, locking preferences down, including about:config.

    We created a GPO in our Windows network to run a vb script on system startup, based on computer group membership. The vb script runs the Firefox ESR 17.0.7 install executable silently and with configuration.ini file to not install the Maintenance Service. Nice thing is this upgrades any public release version of Firefox lower than 17 to ESR 17.0.7, and also downgrades any public release version higher than 17 to ESR 17.0.7.

    The script then creates the defaults\preferences folder, copies a pref.js file to it, copies an override.ini file to the Firefox install folder, and copies an autoconfig file also to the Firefox install folder for which the prefs.js file points to.

    The autoconfig cfg file has many of our lockdown preferences, and includes auto creation of the usercontent.css and userchrome.css files for even more lockdown and display preferences.

    Here's where things got tricky and I got lost. We'd like to put the autoconfig file, not in the Firefox install folder, but on a network share, so changes to the one cfg file applies to all new instances of Firefox start throughout the company. I thought I understood the one section about using "autoadmin.global_config_url" but then realized it was pointing to a js file and maybe what I want to do isn't even possible. Is it? If it is, what am I messing up? Thanks a ton.

  6. Hi Mike, I am trying to get Firefox 24.0 to change the location of the profiles parent directory from ~/.mozilla/firefox to ~/.mozilla/firefox24. The only two preferences that seem likely to help are profile.migration_behavior and profile.migration_directory.

    So I have been trying to set up some lockPref entries to force these but I am not having any luck at all. In fact I tried your simple example with with network.proxy.type setting it to 0 and its not even working with that.. It appears to be ignoring the contents of the file completely no matter what is in it.

    Do you have any suggestions that might help?

    autoconfig.js:

    //
    pref("general.obscure_value", 0);
    pref("general.config.filename", "firefox.cfg");
    //

    firefox.cfg:
    //
    pref("network.proxy.type", 0);

  7. Hello Mike,

    thanks for this great site. Learned a lot from you!

    I only have the Problem that i cannot set the default search engine. I created a search.js in the browser/defaults/preferences Folder containing the following lines of code:

    pref("browser.search.selectedEngine", "Bing");
    pref("browser.search.defaultenginename", "Bing");

    I want to set this value for every new Profile, and i want the Users to be able to change it.
    When i create a new Profile and go to "about:config" it shows the correct Value, but Google is still selected in the Searchbar. The Status of those two settings is "default" instead of "user set". And when i change the search engine via the searchbar every Provider gets saved when i restart Firefox, only the one i configured (Bing) does not.

    Can you help me here?

    Thanks!

  8. Mike,

    I've been using firefox version 17.0 ESR and it has been working fine and not updating past version 17, but recently it upgraded to version 24.x which breaks my application. Did something change to make version 17 ESR upgrade to 24. It was my understanding that the ESR version did not do that.

    Thanks
    Mark

  9. I'm running firefox 24.2.0 on a RHEL 6.5 box and trying to set a bookmark in the toolbar folder. In /usr/lib64/firefox/browser/defaults/preferences I've created all-xxx.js:
    //
    pref("general.config.obscure_value", 0);
    pref("MCD.logging.console", "All");
    pref("MCD.logging.dump", "All");
    pref("general.config.filename", "firefox.cfg");

    and firefox.cfg:
    //
    //
    try {
    var ios = Components.classes["@mozilla.org/network/io-service;1"].getService(Components.interfaces.nsIIOService);
    var uri = ios.newURI("https://localhost:61000", null, null);
    var navBookmarksService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"].getService(Components.interfaces.nsINavBookmarksService);
    if (!navBookmarksService.isBookmarked(uri)) {
    navBookmarksService.insertBookmark(navBookmarksService.toolbarFolder, uri, navBookmarksService.DEFAULT_INDEX, "Add X");
    }
    } catch(e) {displayError("firefox.cfg", e);}

    When I start firefox I get a popup saying 'Failed to read the configuration file. Please contact your system administrator.' which of course isn't much help. The permission on both files are the same. I also treid commenting out everything in firefox.cfg but got the same result.

    In an effort to debug the problem I tried:
    NSPR_LOG_FILE=mcd.log NSPR_LOG_MODULES=MCD:5 AUTOCONFIG_DEBUG=1 firefox

    and got the following in the log file:
    1302652704[7f564d850260]: general.config.filename = firefox.cfg
    1302652704[7f564d850260]: evaluating .cfg file firefox.cfg with obscureValue 0
    1302652704[7f564d850260]: error evaluating .cfg file firefox.cfg 80520012

    Do you have any suggestions on what I can do to further debug this problem?

    Thanks,
    Ted

    • Sure. So when I put this file in my editor, I saw “ and ” instead of "

      This is a surprisingly common (and frustrating) problem. In all your files, make sure you're using real double quotes (") and that should work.

      It fixed it for me.

      (and yes, wordpress is screwing this up for me on my blog too. Frustrating)

  10. Mike,
    I am new to the configuring Firefox and have manually hacked a config file with various locked preferences I then decided to have a look at CCK2. Have come to the end of the config within CCK2 decided to use the autoconfig.zip option. Yet it might be plainly obvious to most who have used cck before, however i cannot find anything that tells me how to 'deploy' this autoconfig.zip within a packeged distribution of firefox esf so that it uses my config. Am i missing a blog post or a help page if so can you point me in the direction or let me know how its done.
    Thanks,

      • Sorry might not have been clear, I dont want to modify the Firefox package itself, but i want to deploy the autoconfig.zip alongside the firefox install. Can i just deploy firefox, install it, then unzip the autoconfig.zip into the root dir of firefox? If so i need to slap my forehead and exclaim DOH!.

  11. I am using Firefox version 26 (sorry if I am quoting the incorrect version number), but when I downloaded, this is what it says and i tried using mozilla.cfg but that doesn't work. Tried for 2 days to get it to work. Then my colleague renamed to firefox.cfg. It works. Change the CFG file name and the pointer and you are good to go. Stupid version change. Thanks for your posts!

  12. I have been trying unsuccessfully to stop Firefox from being my default browser. i came across the same question & ended up here at your blog. Your explanation is too complicated for me. I just want to delete Firefox & never use it again but can't seem to do this. Firefox has been too much of a problem for me this past yr.... especially when trying to compose e-mails in Yahoo. HOW CAN I DELETE FIREFOX ? How do I stop having firefox open up every time I turn on my computer ?