Raw settings - uBlockOrigin/uMatrix-issues GitHub Wiki

These settings are for users who want to further customize the behavior or appearance of uMatrix.

Keep in mind that any of these raw settings may be removed in the future, more may be added, or existing ones may become mainstream settings with a dedicated UI. Some of these raw settings may exist for experimental purpose only.

To restore any one setting to its original built-in value, just remove the whole setting.

assetFetchBypassBrowserCache

Default: false

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

If set to true, uMatrix will ensure the browser cache is bypassed when fetching a remote resource.

This is for the convenience of filter list maintainers who may want to test the latest version of their lists when fetched from their remote location.

assetFetchTimeout

Default: 30 seconds.

uMatrix 1.4.1b4 and above.

The number of seconds after which uMatrix throws an error when a remote server fails to respond to a request.

autoUpdateAssetFetchPeriod

Default: 120 seconds.

uMatrix 1.4.1b4 and above.

When the auto-updater kicks in and an asset in need of update is fetched, this is the number of seconds to wait before fetching the next asset which needs to be updated. The delay helps spread the load on CPU and memory as a result of loading/parsing/compiling the filter lists which have been updated.

cacheStorageAPI

Default: unset.

uMatrix 1.4.1b4/1.4.1b6 and above.

If set to browser.storage.local, uMatrix will use WebExtensions storage as a backend to cache storage.

Additionally, should indexedDB not be available for whatever reason, uMatrix will automatically fallback to browser.storage.local.

If set to indexedDB, uMatrix will use IndexedDB as a backend to the cache storage, potentially increasing performance and reducing memory usage. See uBO #328 for details. Bad side effects - filter lists will be out of date in Chrome incognito mode - uBO #399.

If unset, uMatrix will use whatever backend storage which is optimal for the current platform.

cacheStorageCompression

Default: true.

uMatrix 1.4.1b4/1.4.1b6 and above.

If set to true, uMatrix will lz4-compress data before storing it in its cache storage. The cache storage is used for storing downloaded filter lists, compiled filter lists, selfies. This setting work when IndexedDB is used as the cache storage backend (by default with Firefox/Firefox for Android). See uBO #141 for related discussion.

cnameIgnore1stParty

Default: true.

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

Whether uMatrix should ignore to re-run a network request through the filtering engine when the CNAME hostname is 1st-party to the alias hostname.

cnameIgnoreExceptions

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

Whether to bypass the uncloaking of network requests which were excepted by filters/rules.

This is necessary so as to avoid undue breakage by having exception filters being rendered useless as a result of CNAME-uncloaking.

For example, google-analytics.com uncloaks to www-google-analytics.l.google.com and both hostnames appear in Peter Lowe's list, which means exception filters for google-analytics.com (to fix site breakage) would be rendered useless as the uncloaking would cause the network request to be ultimately blocked.

cnameIgnoreList

Default: unset.

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

Possible values:

  • Space-separated list of hostnames.
  • * - all hostnames.

This tells uMatrix to NOT re-run the network request through uMatrix filtering engine with the CNAME hostname.

This is useful to exclude commonly used actual hostnames from being re-run through uMatrix filtering engine, so as to avoid pointless overhead.

cnameIgnoreRootDocument

Default: true.

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

Tells uMatrix to skip CNAME-lookup for root document.

cnameMaxTTL

Default: 60 minutes.

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

This tells uMatrix to clear its CNAME cache after the specified time.

For efficiency purpose, uMatrix will cache alias=>CNAME associations for reuse so as to reduce calls to browser.dns.resolve. All the associations will be cleared after the specified time to ensure the map does not grow too large and too ensure uMatrix uses up to date CNAME information.

cnameReplayFullURL

Default: false.

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

Tells uMatrix whether after CNAME-uncloaking replay through the filtering engine the whole URL or just the origin part of it.

Replaying only the origin part is meant to lower undue breakage and improve performance by avoiding repeating the pattern-matching of the whole URL -- which pattern-matching was most likely already accomplished with the original request.

consoleLogLevel

Default: unset.

uMatrix 1.4.1b4 and above.

For development purposes only.

If set to info, prints debug messages to the browser console.

contributorMode

Default: false.

Introduced in v1.3.4.

Enables contributor mode.

New text area "My recipes" in Dashboard, Assets tab. Makes easier to test and contribute ruleset recipes. (WIP)

disableCSPReportInjection

  • Type: boolean
  • false (default): do inject a Content-Security-Policy-Report-Only header in response headers, as needed.
  • true: never inject a Content-Security-Policy-Report-Only header in response headers.
    • Disabling the injection of Content-Security-Policy-Report-Only will render uMatrix unable to report to you whether web workers are used by a web page when these are not to be blocked.

The Content-Security-Policy-Report-Only is currently injected by uMatrix to detect the use of web workers on a site, when web workers are not forbidden.

The main purpose of this setting is to serve as a workaround for issue #912. This setting may go away whenever the root issue is resolved in Chromium.

disableWebAssembly

Default: false.

Introduced in v1.3.4.

For development purposes only.

If set to true, turns off WebAssembly optimizations in uMatrix code.

enforceEscapedFragment

  • Type: boolean (default to true)

Whether uMatrix should replace an instance of #! to ?_escaped_fragment_= in a document URL when first-party scripts are blocked.

See issue #940 for details.

framePlaceholder

  • Type: boolean
  • true (default): replace non-collapsed blocked frame with a placeholder.
  • false: do not replace non-collapsed blocked frame with a placeholder.

framePlaceholderBackground

  • Type: string
  • default (default): use the background value from placeholderBackground.
  • Otherwise a valid CSS background property value to be used as is.

framePlaceholderDocument

  • Type: string
  • An HTML document source with no newline character.

imagePlaceholder

  • Type: boolean
  • true (default): replace non-collapsed blocked image with a placeholder.
  • false: do not replace non-collapsed blocked image with a placeholder.

Use false to prevent the use of placeholder for blocked images and thus eliminate the ability of image placeholder styling information to be used as fingerprint information.

imagePlaceholderBackground

  • Type: string
  • default (default): use the background value from placeholderBackground.
  • Otherwise a valid CSS background property value to be used as is.

Note that using a custom value for image placeholder can make you fingerprintable.

imagePlaceholderBorder

  • Type: string
  • default (default): : use the border value from placeholderBorder.
  • Otherwise a valid CSS border property value to be used as is.

Note that using a custom value for image placeholder can make you fingerprintable.

loggerPopupType

Default: popup.

uMatrix 1.4.1b4 and above, based on uBlock Origin commit.

Control the type of window to be used when the logger is launched as a separate window. Introduced to solve issues with missing/disabled titlebar buttons, resizing, incorrect drawing (uBO #663).

Possible values:

  • popup - browser window without toolbars (default)
  • normal - normal browser window with all toolbars and buttons
  • any other value defined in Chromium or Firefox documentation.

manualUpdateAssetFetchPeriod

Default: 500 milliseconds.

uMatrix 1.4.1b4 and above.

When clicking the "Update now" button in the "Assets" pane in the dashboard, this is the number of milliseconds to wait before fetching the next asset which needs to be updated. The delay helps spread the load incurred as a result of loading/processing new filter lists, and its purpose is also to be considerate to remote servers by not subjecting them to rapid-fire requests.

placeholderBackground

  • Type: string
  • Default value is an internal CSS background value.
  • Otherwise a valid CSS background property to be used as placeholder background.

Override this value if you want to customize the background value for all placeholders.

Note that using a custom value for image placeholder can make you fingerprintable.

placeholderBorder

  • Type: string
  • Default value is an internal CSS border value.
  • Otherwise a valid CSS border property to be used as placeholder background.

Override this value if you want to customize the border value for all placeholders.

Note that using a custom value for image placeholder can make you fingerprintable.

suspendTabsUntilReady

Default: unset.

uMatrix 1.3.17b1/1.4.1b4 and above.

Possible values:

  • unset - leave it to the platform to pick the optimal behavior (default, Firefox - enabled, Chromium - disabled)
  • no - do no suspend tab loading at launch time
  • yes - suspend tab loading at launch time

In Firefox this feature is active by default thanks to "persistent startup listeners".

If enabled, uMatrix will hard block all network requests when the browser launches until all the filter lists and rules are loaded and ready, at which time uMatrix will force a reload of the tabs for which there were network requests blocked during the setup phase.

Disclaimer: especially in Chromium based browsers, even with this setting enabled, it's impossible for uMatrix to guarantee with 100% certainty that everything will be properly blocked when the browser is launched. This is a by-design browser issue -- do not open an issue on uMatrix issue tracker about this.

Related browser issues: