Skip to content

Dynamic filtering: quick guide

Jump to bottom Edit New page
Raymond Hill edited this page Dec 7, 2020 · 89 revisions

Back to Dynamic-filtering

Dynamic filtering pane (available only to advanced users) can be toggled off/on by clicking on the Less/More buttons:

figure 1

IMPORTANT

Static filtering refers to the filters which comes from the filter lists, i.e. EasyList, EasyPrivacy, URLhaus Blocklist, etc. Dynamic filtering are those filtering rules which have an air of firewall rules.

Dynamic filtering rules overrides static filtering.

This means a block dynamic rule will override any existing allow static filters. This means you can block with 100% certainty using dynamic filtering rules. Similarly, an allow dynamic filtering rule will override any existing block static filters, i.e. you can allow with 100% certainty with dynamic filtering (useful to un-break sites broken by some static filters).

This may help understand how static and dynamic filtering interact: Overview of uBlock's network filtering engine.

The columns

First column: what is to be dynamically filtered:

figure 2

As you can see, you can create dynamic filtering rules for resource types, or hostnames according to their origin.

The color of an entry indicates whether all requests were blocked (reddish), all requests were allowed (greenish), or some were blocked some were allowed (yellowish).

In bold, domain names. Domain names are hostnames, but hostnames are not necessarily domain names from uBlock's point of view: domain names are extracted as per Mozilla Public Suffix list.

Second column: global dynamic filtering rules, i.e. whatever rule appears in this column applies everywhere, on all sites:

figure 3

Third column: local dynamic filtering rules, i.e. whatever rule appears in this column applies to the current site only:

figure 4

The cells in the third column gives an overview of how many requests were blocked/allowed:

  • - or + = between 1-9 network requests were blocked or allowed, respectively
  • -- or ++ = between 10-99 network requests were blocked or allowed, respectively
  • --- or +++ = 100 or more network requests were blocked or allowed, respectively
  • blank cell = no network requests occurred for the specific hostname

So there are global dynamic filtering rules, and local dynamic filtering rules.

By default, there are no dynamic filtering rules at install time, so nothing is blocked by default by the dynamic filtering engine. You will have to create your own rules, according to your own prerogatives.

Block rules

Sensible security- and privacy-wise: blocking all 3rd-party frames by default everywhere:

figure 5

All embedded 3rd-party frames were blocked on the page. Good. However it appears there was an embedded YouTube video in the article:

figure 6

If you want to block all 3rd-party frames by default, except for embedded YouTube videos on that particular site, two solutions.

Noop rules

First solution

Create a local noop rule for 3rd-party frames:

figure 7

It works, the embedded YouTube video can now be played.

Note that a cell with a noop rule is dark gray, while a cell with no rule at all is light gray (the default color). Hence gray means that no dynamic filtering will be applied to a cell. If a cell inherit a block or allow rule from a higher precedence cell, a noop rule can be used to override the inherited block or allow rule. Conceptually, the purpose of noop rules is to punch holes in your dynamic filtering ruleset so that network requests can pass through unimpeded.

However the above rule would result in all 3rd-party frames on the site to be unblocked. Not so good.

Second solution

Create a local noop rule for youtube.com (and for the specific page used as example, a noop rule for google.com also had to be created to un-break the embedded Youtube video):

figure 8

This will prevent dynamic filtering rules to apply to network requests to youtube.com, but only for the current site.

Important:

Remember that noop rules bypass only broader dynamic filtering rules, static filtering is left completely intact, which means you won't see ads in the embedded YouTube videos.

What if you want to block 3rd-party frames everywhere by default, but want whatever embedded YouTube video to not be blocked by default on any site?

It is just a matter of creating a global noop rule for youtube.com:

figure 9

Which means: do not apply any dynamically filtering rule to youtube.com by default (i.e. everywhere).

Important:

Local dynamic filtering rules override global ones.

In other words: More specific dynamic filtering rules override less specific ones. For example, dynamic filtering rules for youtube.com (specific) override dynamic filtering rules for 3rd-party frames (generic).

All dynamic rules are temporary by default: Click the padlock if you want to persist the ruleset for a specific web site.

figure 12

  • The padlock will be visible if and only if there is at least one temporary rule in the pane
  • This is really the optimal way to use dynamic filtering, as using this feature is often a matter of trial and error
  • This prevents ruleset pollution: your ruleset will be only those rules which you will have explicitly persisted
  • If you Ctrl-click to set/unset a rule, it will be immediately persisted (command ⌘-click on Mac)

Allow rules

We covered the block and noop dynamic filtering rules. What about the allow rule?

The dynamic filtering allow (green) rule is most useful to un-break sites broken by some static filters: allow rules will override all block filters from static filter lists, and because of this, allow rules are to be used only for exceptional cases and are rarely needed in the real world.

The only way to enable the ability to point-and-click to create allow rules is to either:

  • Tap twice on the Ctrl key while in the popup panel
    • This won't work in Firefox when privacy.resistFingerprinting is set to true
  • Set filterAuthorMode to true in advanced settings

Doing so will enable the allow rule creation widget in the popup panel:

figure 10

This small obstacle to easily create allow rule through point-and-click is by design, as it has been found over the years that too many users are misusing dynamic filtering by creating allow rules where noop rules should have been used.

To reiterate, creating allow rules will completely override related block filters from static filter lists, which may easily cause you to be less protected than if not using dynamic filtering at all -- allow rules are to be used exceptionally, and most of the time, temporarily -- they are typically most useful to filter list maintainers in order to quickly narrow down filter issues.

Furthermore, when an allow rule is set for the 1st-party domain, this will completely disable scriptlet injection and HTML filtering, again a behavior which is most useful to filter list maintainers. Scriptlet injection and HTML filtering are often used to deal with anti-blocker mechanisms.

Important: Typically, use only narrow allow dynamic filtering rules to un-break sites. As these allow rules override any static filtering, this means if you use a too broad allow dynamic filtering rule you could start to allow in ads/trackers/annoyances.

My rules pane

All the rules you create through the dynamic filtering panel will appear in the "My rules" pane in the dashboard:

figure 11

From there you can freely add/modify/delete your rules manually through plain text editing.

Now that you have a basic understand of dynamic filtering, you can head to medium blocking mode or hard blocking mode in order to learn more about using uBO in default-deny mode.

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

Clone this wiki locally