-
Notifications
You must be signed in to change notification settings - Fork 3.2k
Dynamic filtering: rule syntax
A dynamic filtering rule is made of four components: a source, a destination, a request type, and then a keyword which tells what to do with a request which happens to match the three former components:
source destination type action
Valid rules:
rule type | source | destination | request type | action |
---|---|---|---|---|
Type-based |
* hostname |
* |
* image inline-script 1p-script 3p 3p-script 3p-frame
|
block noop allow
|
Hostname-based |
* hostname |
hostname |
*
|
block noop allow
|
Source hostname always corresponds to the hostname extracted from the URL of the web page in the browser.
The destination hostname corresponds to the hostname extracted from the URL of a remote resource which the web page is fetching (or trying to).
Tip:
In specific cases Dynamic URL filtering will allow for greater accuracy when controlling destination URL.
A rule always automatically propagates to all subdomains of the source hostname and all subdomains of the destination hostname -- unless the rule is overridden by a narrower rule in one of the subdomains.
Given that rules always propagate to subdomains, there is no need to prefix the hostname part with a wildcard *.
, doing so is invalid and will cause the the rule to be discarded.
By default uBO also applies some special behind-the-scene
scope rules:
- Behind the scene network requests
- https://github.com/uBlockOrigin/uBlock-issues/discussions/3226
The type is the type of the fetched resource.
A request can be blocked (block
), allowed (allow
), or ignored (noop
). A noop
rule will cause matching network requests to be ignored by the dynamic filtering engine, but those ignored network requests will still be subjected to static filtering (filter lists).
Type-based rules are used to filter specific types of request on a web page. Currently, seven types of network request exist which can be dynamically filtered:
-
*
: any type of request -
image
: images -
3p
: any request which 3rd-party to the web page -
inline-script
: inline script tags, i.e. scripts embedded in the main document -
1p-script
: 1st-party scripts, i.e. scripts which are pulled from the same domain name of the current web page -
3p-script
: 3rd-party scripts, i.e. scripts which are pulled from a different domain name than that of the current web page -
3p-frame
: 3rd-party frames, i.e. frames elements which are pulled from a different domain name than that of current web page
These rules can apply everywhere, or be specific to a website. For instance blocking 3rd-party frames is a very good habit security-wise: * * 3p-frame block
. This rule translates into "globally block 3rd-party frames".
Another example: wired.com * image block
, which means "block images from all origins when visiting a web page on wired.com".
Note that with type-based rules, the destination hostname is always *
, meaning "from anywhere".
Hostname-based rules are used to filter network resources according to their origin, i.e. according to which remote server a resource is pulled. Hostname-based rules have a higher specificity than type-based rules, and thus hostname-based rules always override type-based rules whenever a network request end up matching both a type- and a hostname-based rule.
With hostname-based rule, the request type is always *
, meaning the rule will apply to any type of request.
For example, * disqus.com * block
means "globally block all net requests to disqus.com
".
Just like type-based rules, a hostname-based rule can apply only when visiting a specific website, for example: wired.com disqus.com * noop
, which means "do not apply dynamic filtering to network requests to disqus.com
when visiting a web page on wired.com
. Since this last rule is more specific than the previous one, it will override the global blocking of disqus.com
everywhere.
A matching rule can do one of three things:
-
block
: matching network request will be blocked.-
block
dynamic filter rules override any existing static exception filters. - Thus you can use them to block with 100% certainty (unless you set another overriding dynamic filter rule).
-
-
allow
: matching network request will be allowed.-
allow
dynamic filters rules override any existing static and dynamic block filters. - Thus they are most useful to create finer-grained exceptions, and to un-break websites broken by some static filters somewhere.
-
-
noop
: exclude network requests from being subjected to dynamic filtering.- It cancels dynamic filtering, but it does not cancel static filtering.
hostname & type | local dynamic filtering | local static filters |
---|---|---|
all: | github.com * * block |
*$domain=github.com |
images: | github.com * image block |
*$image,domain=github.com |
3rd-party: | github.com * 3p block |
*$3p,domain=github.com |
inline scripts: | github.com * inline-script block |
||github.com^$inline-script |
1st-party scripts: | github.com * 1p-script block |
||github.com^$script,1p |
3rd-party scripts: | github.com * 3p-script block |
*$script,3p,domain=github.com |
3rd-party frames: | github.com * 3p-frame block |
*$subdocument,3p,domain=github.com |
hostname & type | global dynamic filtering | global static filters |
---|---|---|
all: | * * * block |
* |
images: | * * image block |
*$image |
3rd-party: | * * 3p block |
*$3p |
inline scripts: | * * inline-script block |
*$inline-script |
1st-party scripts: | * * 1p-script block |
*$script,1p |
3rd-party scripts: | * * 3p-script block |
*$script,3p |
3rd-party frames: | * * 3p-frame block |
*$subdocument,3p |
uBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.
- Wiki home
- About the Wiki documentation
- Permissions
- Privacy policy
- Info:
- The toolbar icon
- The popup user interface
- The context menu
-
Dashboard
- Settings pane
- Filter lists pane
- My filters pane
- My rules pane
- Trusted sites pane
- Keyboard shortcuts
- The logger
- Element picker
- Element zapper
-
Blocking mode
- Very easy mode
- Easy mode (default)
- Medium mode (optimal for advanced users)
- Hard mode
- Nightmare mode
- Strict blocking
- Few words about re-design of uBO's user interface
- Reference answers to various topics seen in the wild
- Overview of uBlock's network filtering engine
- uBlock's blocking and protection effectiveness:
- uBlock's resource usage and efficiency:
- Memory footprint: what happens inside uBlock after installation
- uBlock vs. ABP: efficiency compared
- Counterpoint: Who cares about efficiency, I have 8 GB RAM and|or a quad core CPU
- Debunking "uBlock Origin is less efficient than Adguard" claims
- Myth: uBlock consumes over 80MB
- Myth: uBlock is just slightly less resource intensive than Adblock Plus
- Myth: uBlock consumes several or several dozen GB of RAM
- Various videos showing side by side comparison of the load speed of complex sites
- Own memory usage: benchmarks over time
- Contributed memory usage: benchmarks over time
- Can uBO crash a browser?
- Tools, tests
- Deploying uBlock Origin
- Proposal for integration/unit testing
- uBlock Origin Core (Node.js):
- Troubleshooting:
- Good external guides:
- Scientific papers