Do note that these settings alter your browser behaviour quite a bit, so it is recommended to either create a completely new profile for Firefox or backup your existing profile directory before putting the user.js file in place.
To enable the Profile Manager, run Firefox with command-line arguments: firefox --no-remote -P
Single profile installation
Copy user.js in your current user profile directory, or (recommended) to a fresh, newly created Firefox profile directory.
With this installation method, if you change any of user.js settings through about:config or Firefox preferences dialogs, they will be reset to the user.js defined values after you restart Firefox. This makes sure they’re always back to secure defaults when starting the browser. However this prevents persistently changing settings you don’t consider appropriate. Either edit user.js directly, or use the system-wide installation method described below.
System-wide installation (all platforms)
Generate a file suitable for system-wide installation, by running make with one of the following targets:
systemwide_user.js: (the value will be used as default value for all Firefox Profiles where it is not explicitly set, it can be changed in about:config and is kept across browser sessions)
locked_user.js: (the value will be used as default value on Firefox profile creation, will be locked and can’t be changed) in user.js or in Firefox’s about:config or settings.
debian_locked.js: Debian specific. Users are not able to override preferences. See #415.
Copy the produced file to the Firefox installation directory. The file should be located at:
Note that JSON does not support comments, hence settings are documented in custom *_comment keys. Mozilla maintains a list of available policies: [1] [2](https://github.com/mozilla/policy-templates). The Enterprise Policy Generator add-on can be used to generate policies.json files from a graphical interface.
Updating using git
For any of the above methods, you can keep your browser’s user.js with the latest version available here: Clone the repository, and create a symbolic link from the appropriate location to the user.js file in the repository. Just run git pull in the repository when you want to update, then restart Firefox:
cd ~/.mozilla/firefox
git clone 'https://github.com/pyllyukko/user.js.git'
cd XXXXXXXX.your_profile_name
ln -s ../user.js/user.js user.js
Verifying
Verify that the settings are effective from about:support (check the “Important Modified Preferences” and “user.js Preferences” sections).
There’s a whole lot of settings that this modifies and they are divided in the following sections.
Some of the settings in this user.js file might seem redundant, as some of them are already set to the same values by default. We chose to explicitely set their values, which ensures these settings are enforced if a future Firefox update changes the default value.
HTML5 / APIs / DOM
HTML5 / APIs / DOM related settings. Mozilla is keen to implement every new HTML5 feature, which have had unforeseen security or privacy implications. This section disables many of those new and yet to be proven technologies.
This section tweaks the cipher suites used by Firefox. The idea is to support only the strongest ones with emphasis on forward secrecy, but without compromising compatibility with all those sites on the internet. As new crypto related flaws are discovered quite often, the cipher suites can be tweaked to mitigate these newly discovered threats.
This is not enough! Here’s some other tips how you can further harden Firefox:
By default your browser trusts 100’s of Certificate Authorities (CAs) from various organizations to guarantee privacy of your encrypted communications with websites. Some CAs have been known for misusing or deliberately abusing this power in the past, and a single malicious CA can compromise all your encrypted communications! To workaround this you may want to inspect the list of trusted certificates. [1]
Keep your browser updated! If you check Firefox’s security advisories, you’ll see that pretty much every new version of Firefox contains some security updates. If you don’t keep your browser updated, you’ve already lost the game.
Disable/uninstall all unnecessary extensions and plugins!
Use long and unique passwords/passphrases for each website/service.
Prefer open-source, reviewed and audited software and operating systems whenever possible.
Do not transmit information meant to be private over unencrypted communication channels.
Use a search engine that doesn’t track its users, and set it as default search engine.
WebAssembly is required for Unity web player/games
Enabling Mixed Display Content blocking can prevent images/styles… from loading properly when connection to the website is only partially secured
Disabling nonessential protocols breaks all interaction with custom protocols such as mailto:, irc:, magnet: … and breaks opening third-party mail/messaging/torrent/… clients when clicking on links with these protocols
Disabling system add-on updates prevents Mozilla from “hotfixing” your browser to patch critical problems (one possible use case from the documentation)
Containers are not available in Private Browsing mode
RFP breaks some keyboard shortcuts used in certain websites (see #443)
RFP changes your time zone
RFP breaks some DDoS protection pages (Cloudflare)
Fully automatic updates are disabled and left to package management systems on Linux. Windows users may want to change this setting.
Update check page might incorrectly report Firefox ESR as out-of-date
Do No Track must be enabled manually
Blocking referers across same eTLD sites breaks some login flows relying on them, consider lowering this pref to 1
Blocking 3rd-party cookies breaks a number of payment gateways
First-party isolation breaks Microsoft Teams
First-party isolation causes HTTP basic auth to ask for credentials for every new tab (see #425)
.URL shortcut files will be created with a generic icon
disabling “beforeunload” events may lead to losing data entered in web forms
OCSP leaks your IP and domains you visit to the CA when OCSP Stapling is not available on visited host
OCSP is vulnerable to replay attacks when nonce is not configured on the OCSP responder
OCSP adds latency (performance)
Short-lived certificates are not checked for revocation (security.pki.cert_short_lifetime_in_days, default:10)
Firefox falls back on plain OCSP when must-staple is not configured on the host certificate
security.OCSP.require will make the connection fail when the OCSP responder is unavailable
security.OCSP.require is known to break browsing on some captive portals
In addition see the current issues. You can use the web console to investigate what causes websites to break.
FAQ
Does this user.js file fix all security problems?
No. Please read Known problems and limitations, the project’s issue tracker, and report new issues there.
Please open separate issues for each individual problem/question you may have.
Why are obsolete/deprecated entries included in the user.js file?
This project is aimed at Firefox versions between the current ESR
and the latest Firefox release. We will wait for widespread deployment of the current ESR
(eg. adoption in major Linux distributions) before removing deprecated/obsolete preferences.
Presence of deprecated entries causes no known problems.
Installing the user.js file breaks xyz plugin/addon/extension, how can I fix it?
Yes please! All issues and pull requests are more than welcome. Please try
to break down your pull requests or commits into small / manageable entities,
so they are easier to process. All the settings in the user.js file
should have some official references to them, so the effect of those settings
can be easily verified from Mozilla’s documentation.
Feel free to follow the latest commits RSS feed
and other interesting feeds from the References section.
You may also reach other contributors through IRC (#user.js on Freenode) or Gitter.
Run make help to get a list of makefile targets used for frequent maintenance operations.
$ make help
locked_user.js generate a locked configuration file
systemwide_user.js generate a system-wide configuration file
debian_locked.js generate a locked, system-wide configuration file
policies.json generate policy file (https://github.com/mozilla/policy-templates/blob/master/README.md)
tests run all tests
test-acorn validate user.js syntax
test-shellcheck check/lint shell scripts
000-tor-browser.js download Tor Browser custom configuration reference
diff-tbb differences between values from this user.js and tor browser's values
diff-tbb-2 differences between values from this user.js and tor browser's values (alternate method)
diff-tbb-missing-from-user.js preferences that are present in tor browser's defaults, but not in this user.js
diff-sourceprefs.js download and sort all known preferences files from Firefox (mozilla-central) source
diff-upstream-duplicates preferences with common values with default Firefox configuration
diff-upstream-missing-from-user.js preferences present in firefox source but not covered by user.js
diff-upstream-deprecated preferences in hardened user.js that are no longer present in firefox source
diff-stats count preferences number, various stats
clean clean automatically generated files/build/test artifacts
doc-whatdoesitdo generate the README "What does it do?" section
doc-toc generate the README table of contents
help generate list of targets with descriptions