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 currentvalue of the preference to the specified value.
defaultPref(prefName, value) - Makes the specified value the default value for a preference.
lockPref(prefName, value) - Locks a preference to the specified value. Users cannot change locked preferences.
unlockPref(prefName) - Unlocks a preference that was previously locked.
getPref(prefName) - Gets the value of the specified preference.
clearPref(prefName) - Clears the specified preference.
displayError(funcname, message) - Pops up a dialog box containing an error message when Firefox is started.
getenv(name) - Gets the value of the specified environment variable from the user's environment.
setLDAPVersion(version) - Sets the LDAP version used by the server. (Thunderbird only)
getLDAPAttributes(host, base, filter, attribs) - Gets LDAP attributes from the given server. (Thunderbird only)
getLDAPValue(str, key) - Gets the LDAP value for a given string, filtered by the key. (Thunderbird only)
(I will cover each of these functions in detail in my next post.)
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. 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.
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."
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...
Can you email me your autoconfig? I'll run some tests locally. consulting at kaply dot com
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
Funnelcake is the result of a Mozilla test of CDNs (https://blog.mozilla.org/it/2012/08/03/dear-mozilla-mirrors-thank-you/).
It's random as to whether you got a funnelcake build.
The only different thing about the funnelcake build is that it has different values in distribution.ini.
Per my earlier note, the issue is that you put user_ before each setting.
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
Hi, Mike.
Is there a way to disable about:plugins in Firefox 14+?
This would be pretty straightforward to do. Why do you want to though? You can't change anything on that page.
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.