Mozilla, money, microformats and more

Post navigation

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:

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.

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:

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:

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.

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).

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…

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

This almost works for me! But the problem I have is that the bookmarks don’t load the first time I load firefox, if I close and re-open they show up. This wouldn’t normally be a problem except for the fact that due to our use of non-persistent desktops every time my users log in they are opening firefox for the first time, so they have to open it twice to get these to load.

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!.

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!

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 ?

In your example for autoadmin.global_config_url, please use an https URL, and please explicitly note that global_config_url can present a security issue for users if they ever use their systems on untrusted networks (e.g. a coffee shop).

Is the location of the auto-config file (firefox.cfg in your example) still ‘located in the same place as the executable’ for firefox versions later than 21? I am using Firefox 31ESR in Red Hat Enterprise Linux and I have set a config file in browser/defaults/preferences, which sets obscure to 0 and the name of the config file. The obscure value sticks, but the config filename results in Firefox reporting it cannot read the preferences file, and it automatically shuts down.

I enjoyed reading your blog. We have a different problem: Our company has created a desktop app that is called from the browser using a URI. We have found ways to disable the URI warnings on IE and Chrome but not on Firefox. Wondering if you have come across this problem?

Hi Mike,
This information is very cool. Do you know if it is possible to customize Desktop notifications in Firefox? I noticed that most people usually want to get rid of it. However, I do like them and am searching for a way to configure them so that I can extend the amount of time it is displayed or keep them (stacked if multiple ones appear) until I manually close each one.

Thanks for all of your time helping. I have read through many of your posts. I am having issues getting an all user *.cfg file to load successfully. I was able to get it to work with just the startpage in the cfg file, but made some changes to add one lockPref at a time … and can’t get it to work anymore.

I have a file called local-settings.js located here:
C:\Program Files (x86)\Mozilla Firefox\defaults\pref
It is configured as such (tried with and without the “//” blank line):
//
pref(“general.config.filename”, “firefox.cfg”);

You are right. That was an afterthought. I have removed it, and it still wont load. I can not even get one line to load for some reason. I tried this, and could not get it to load:
//
lockPref(“browser.startup.homepage”, “http://mywebpage.com”);

(mywebpage.com is generic)
Like I said, it worked with the just the homepage until I started adding to it, now I can’t even get it to work at all. Is it saving something in a cache file somewhere that I need to be clearing before every test?

after years we want to restrict and configure installed FF by autoconfig in our authority. I found your blog and read it very interested.
Is there any way to configure the point privacy -> history to Firefox will use custom settings for history as selected?
This is my last unconfigured point in the autoconfig.js and all trys with change on gui and look at about:config brought no solution.

First off, I wanted to say your blog is extremely helpful. I’ve been able to make some pretty decent changes to Firefox 40.0.3. I’ve run into a slight hiccup though. I work at a university, originally we ran FF in enforced private mode for lab/classroom/kiosk computers. We’ve been getting requests to allow Netflix and Amazon instant video in those areas. Unfortunately Netflix does not play nicely with private mode. We also want to enforce clearing of the cache, passwords etc.

I’ve managed to get the preferences running, but on the initial run FF still saves passwords. It will clear them after you exit the second time though. I was wondering if you had seen that before or had any insight.

I logon to Netflix and ask it to remember me, close and reopen FF. When I go to http://www.netflix.com again it doesn’t prompt me to logon and takes me to the screen where you choose which profile you want to use for your account. If I close FF again, on subsequent loads Netflix will always prompt for logon and password.

From what I can tell the config file is loading, the home page has been reset and if I go to about:config the settings I am using all show up as locked. It’s just that some of the modifications don’t go into effect until FF is loaded a second time.

I thought
lockPref(“privacy.clearOnShutdown.cookies”, true);
would have addressed that. Anyhow one of the other engineers at my work helped me find a workaround. We had to use a powershell script to apply the changes directly to prefs.js which probably isn’t the preferred method, but oh well we got it working. Thanks for the help Mike!

I need to configure firefox to print silentlly but, the problem is
it detected window.print() script and print the loaded window.
I need to make silent printing to print from a certain url.
this url is a generic handler that process pdf.

I’m hoping that you can help me figure out what I am doing wrong. I could swear that my settings worked for one day. Then, I went to deploy to my organization and nothing. Tried again with the same files on my workstation and now nothing. I have Firefox 43.0.4.

Love this blog and all the easy customization. It’s been a huge help so far! WE currently are on the ESR but are having issues with it not updating. I am pretty sure we are blocking the url somewhere but I was wondering what the ESR update url is so I can add it to our allow list.

I have Installed Mozilla FF v49 on a Windows 2003 server with Citrix Presentation Server 4.5 installed.
I published mozilla on CTX and have no issues when using the default config.
As I need to lockdown the config for the end-users, I created an autoconfig.js file and a mozilla.cfg file.
The cfg file or the autoconfig.js does not seem to load.
What am I doing wrong here?
Autoconfig: