Skip to content

Deploying uBlock Origin

Jump to bottom Edit New page
linsui edited this page Mar 6, 2023 · 41 revisions

I do not know much about enterprise deployment, so I will let a knowledgeable person guide you:

Customizing the settings

Administrators can force specific configurations to deploy uBlock Origin (uBO). At launch time, uBO will look for a setting named adminSettings, and if it exists, it will parse, extract and overwrite a user's settings with the administrator-assigned ones.

New standalone settings are getting added as per demand. See "Deploying uBlock Origin: configuration".

For Firefox, the setting can be configured in "Native manifests" and Policies. Refer to Mozilla documentation about "Managed storage manifests" and its location for the Native manifests approach. See Mozilla's policy template for the Policies approch. You can also consult this specific comment in uBO issue tracker.

You must add the adminSettings entry in about:config for Firefox-legacy. The key name is extensions.ublock0.adminSettings, and the value is a plain string that must be JSON-parseable.

For Chrome, adminSettings must be an entry part of the policy for the extension. See https://www.chromium.org/administrators/configuring-policy-for-extensions/.

For managing Chrome via Google Workspace, you can use this apps-script to generate a policy JSON that will modify Trusted Sites for all designated users.

This effort is still a work in progress with limitations. For example, merging an admin's settings with the user's settings is impossible because the settings get overwritten. Hopefully, I will address this limitation eventually, as time permits. (See https://github.com/gorhill/uBlock/issues/832#issuecomment-248138558).

The content of adminSettings is pretty straightforward: configure uBO as you wish for your users, then create a backup using the "Backup to file" in the Settings pane. Now open this backup file using a text editor, and remove all entries you do not want to overwrite while taking care to end up with a valid JSON file (mind trailing commas, etc.). All the entries left are the ones that will become overwritten on the user's side.

For example, I created a backup file after having customized uBO and removed everything except for the "Color-blind friendly" setting to force that setting to be set on the user's side. Resulting text file:

{
  "userSettings": {
    "colorBlindFriendly": true
  }
}

Now, this json object can be used as the value for adminSettings.

Modifying the list of stock assets

You can configure the content of the "Filter lists" tab by providing a custom version of the assets.json file.

In the assetsBootstrapLocation key, you must add the URL of the modified assets.json file.

Implementation: #2314

Further readings

Here are issues related to the customization of settings for deployed uBO. There may be some advice in these that you find helpful:

uBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.

Clone this wiki locally