Skip to content

Latest commit

 

History

History
80 lines (64 loc) · 7.75 KB

README.md

File metadata and controls

80 lines (64 loc) · 7.75 KB

Autoconfig

Autoconfig is a mechanism that can be used to configure Firefox, Thunderbird, SeaMonkey, and other Gecko-based applications. An autoconfig file is a Javascript file that can modify preferences (application settings) through function calls, and perform other operations, during program startup. It is somewhat similar to the better known user.js file, but there are important differences between the two:

Characteristic autoconfig user.js
File location: Program directory Profile
File modification: Typically requires admin/elevated credentials Typically requires user credentials
Can affect: All profiles The profile where it resides
Function API: * getPrefBranch()
* pref(prefName, value)
* defaultPref(prefName, value)
* lockPref(prefName, value)
* lockPref(prefName)
* getPref(prefName)
* clearPref(prefName)
* setLDAPVersion(version)
* getLDAPAttributes(host, base, filter, attribs, isSecure)
* getLDAPValue(str, key)
* displayError(funcname, message)
* getenv(name)
* user_pref(prefName, value)
* pref(prefName, value)
* sticky_pref(prefName, value)
Javascript: Most language features supported File parser will only process the above function calls
Error handling: Exceptions, error dialogs, custom logging possibilities Typically silent aborting of file processing
Can use other browser APIs via XPCOM1: Yes No
Can be interactive: Yes No
Can override and restrict user modifications: Yes No
Geared toward: Organizations, admin, users who want its additional capabilities Those wanting simpler, inherently per-profile, pref setting capabilities

Due to the differences in function calls and other aspects, an autoconfig file and user.js are not interchangeable. Nor are they mutually exclusive. Both can be used at the same time. It is worth noting that they can perform similar preference modifications, and converting those calls may only involve changing the name of the function used. So someone prefering autoconfig may leverage user.js examples, and vice versa.

Most pages about autoconfig were created in the past and have not been kept up to date. Many examples refer to preferences and/or other things which are no longer applicable. However, the basic characteristics of autoconfig (such as the function call interface it uses) have been pretty stable. So even the oldest articles continue to have some relevancy.

If you are interested in this subject, I would suggest that you start with Mike Kaply's articles. Plus, play around in a test environment. Try manipulating prefs in different ways. Then check the results by reading prefs and viewing what appears in about:config and prefs.js. The autoconfig.js, test.cfg, and user.js files here are intended for such experimentation.

Mike Kaply Articles

Mozilla Autoconfig Related

Mozilla Source Code

Mozilla XPCOM Related

Dean Brundage Articles

Other Autoconfig Links

Related Links

User.js Overviews

User.js Examples


1 The deprecation of XUL/XPCOM addons eliminates the primary external consumer of those APIs. There are plans to remove some of those APIs and rewrite others. That, combined with the relative obscurity of autoconfig and its more telemetry-resistant user base, may lead to some XPCOM utilizing autoconfig files being broken. Those using, or wanting to use, autoconfig should keep this in mind. If there is something you are using, or believe is important to keep, you should get involved on the bugzilla and developer fronts.