Request Control Rule consists of Pattern, Types and Action.
Requests that match a pattern and types of an active rule will be intercepted taking the action of the rule.
Pattern filters matched requests by Scheme, Host and Path.
Supported schemes are http
and https
.
http
| Match a http scheme. |
https
| Match a https scheme. |
http/https
| Match both http and https schemes. |
Host pattern may match the host of the request URL in following ways:
www.example.com
| Matches a complete host. | |
*.example.com
| Matches the given host and any of its subdomains. | Will match example.com and all subdomains of example.com e.g. www.example.com , good.example.com |
www.example.*
| Matches the given host and manually listed top-level domains. (can be combined with the subdomain matching) | Write the top-level domains to the top-level domain name list (e.g. com, org). |
*
| Matches any host. |
Path pattern may subsequently contain any combination of "*" wildcard and any of the characters that are allowed in URL path. The "*" wildcard matches any portion of path and it may appear more than once.
Below are examples of using path patterns.
*
| Matches any path. |
path/a/b/
| Matches the exact path "path/a/b/". |
*b*
| Matches a path that contains a component "b" somewhere in the middle. |
Matches an empty path. |
Filter matched requests by the type of request. The type indicates the requested resource. All supported types are listed below.
Type | Details |
---|---|
Document | Indicates a DOM document at the top-level that is retrieved directly within a browser tab. (main frame) |
Sub document | Indicates a DOM document that is retrieved inside another DOM document (<iframe> and <frame> elements). |
Stylesheet | Indicates a stylesheet (for example, <style> elements). |
Script | Indicates an executable script (such as JavaScript) loaded with <script> element or the Worker API. |
Image | Indicates an image (for example, <img> elements). |
Object | Indicates a generic object (<object> and <embed> elements). |
Plugin | Indicates a request made by a plugin. (object_subrequest) |
XMLHttpRequest | Indicates a request made by an XMLHttpRequest (xhr) or by Fetch API. |
XSLT | Indicates an XSLT style sheet transformation for an XML document. |
Ping | Indicates a ping request triggered by an <a> element using the ping attribute. Only in use if browser.send_pings is enabled. |
Speculative | Indicates a predictive TCP and/or TLS handsake for a request that browser has determined to be coming soon. Only in use if network.http.speculative-parallel-limit is greater than 0. |
Beacon | Indicates a Beacon request. |
XML DTD | Indicates a DTD loaded by an XML document. |
Font | Indicates a font loaded via @font-face rule. |
Media | Indicates a video or audio load (<video> and <audio> elements). |
WebSocket | Indicates a WebSocket load. |
CSP Report | Indicates a Content Security Policy report. |
Imageset | Indicates a request to load an <img> (with the srcset attribute) or <picture> element. |
Web Manifest | Indicates a request to load a Web App Manifest. |
Other | Indicates a request that is not classified as being any of the above types. |
- Skip URL redirection and/or remove URL query parameters.
- Redirect requests to manually configured redirect URL.
- Upgrade non-secure HTTP requests to secure HTTPS.
- Cancel requests before they are made.
- Whitelist and optionally log requests.
Following matchers extend the matching capabilities of WebRequest API.
Filter matched requests by patterns that can be defined as a string with support for wildcards "?" and "*" (where "?" matches any single character and "*" matches zero or more characters), or as a regular expression pattern.
Include and exclude pattern matching is case insensitive as opposed to Host and Path which are case sensitive.
Below are examples of using include and exclude patterns:
login
| Matches URLs containing "login". |
log?n
| Matches for example URLs containing "login" and "logon". |
a*b
| Matches URLs where "a" is followed by "b" |
/[?&]a=\d+(&|$)/
| Matches URLs containing parameter "a" with digits as value. |
Filter matched requests by origin of request.
Any | Matches requests with any origin |
Same domain | Matches requests on same domain |
Same origin | Matches requests on same origin. Adheres to the Same-origin policy. |
Third party domain | Matches requests to third party domain |
Third party origin | Matches requests to third party origin |
- Whitelist rule
- Block rule
- Secure rule
- Redirect rule
- Filter rule
Filter rule supports URL query parameter trimming. Trimmed URL parameters are defined either as literal strings with support for "*" and "?" wildcards or using regular expression.
Below are examples of using query parameter trimming patterns.
utm_source
| Trims any "utm_source" parameter |
utm_*
| Trims any parameter starting with "utm_" |
/[0-9]+/
| Trims any parameter containing only digits |
Keeps only parameters that are defined in trimmed parameters list. All other parameters will be removed.
Removes all URL query parameters from matched request.
Redirect rule supports redirecting requests to a manually configured URL. The redirect URL may be parametrized using parameter expansion and redirect instructions. Parameter expansion allows to access and manipulate a set of named parameters of the original URL. Redirect instructions can be used to replace named parameters of original request URL (e.g. by instructing requests to redirect to a different port).
Both methods may be combined. Redirect instructions will be parsed and applied first before parameter expansions.
Parameter expansion may also be used within a redirect instruction.
{parameter}Access a named parameter of the original request URL. Available named parameters are listed at the end of this section.
Parameter expansion supports the following string manipulation formats:
{parameter/pattern/replacement}
Replaces the first matched substring in expanded parameter.
{parameter//pattern/replacement}
Replaces all occurrences of matched substring in expanded parameter.
The pattern is written in regular expression. A number of special replacement patterns are supported, including referencing of capture groups which are described below.
$n
| Inserts the n-th captured group counting from 1. |
$`
| Inserts the portion of the string that precedes the matched substring. |
$'
| Inserts the portion of the string that follows the matched substring. |
$&
| Inserts the matched substring. |
$$
| Inserts a "$". |
{parameter:offset:length}Extract a part of the expanded parameter. Offset determines the starting position. It begins from 0 and can be a negative value counting from the end of the string.
{parameter|encodingRule}Decode or encode an expanded pattern.
encodeURI
| Encodes a pattern as URI. It does not encode the following characters: ":", "/", ";", and "?". |
decodeURI
| Decodes an encoded URI. |
encodeURIComponent
| Encodes a pattern as a component of URI. Encodes all special characters reserved for URI. |
decodeURIComponent
| Decodes an encoded URI component. |
encodeBase64
| Encode a pattern as Base64 string. |
decodeBase64
| Decodes an encoded Base64 string. |
{parameter(manipulation1)|(manipulation2)...|(manipulationN)}String manipulation rules can be chained using a "|" pipe character. The output is the result of manipulations chain.
https://{hostname}/new/pathUses the hostname of the original request.
https://{hostname/([a-z]{2}).*/$1}/new/pathCaptures a part of the hostname of the original request.
https://{hostname::-3|/\.co/\.com}/new/pathUses the hostname of the original request but manipulate its length by three cutting it from the end and replace ".co" with ".com".
{search.url|decodeURIComponent}Captures "url" search parameter and decodes it.
[parameter=value]Replace a certain part of the original request. Available named URL parameters are listed at the end of this section.
[parameter={parameter<manipulations>}]
The value of a redirect instruction can be parametrized using the parameter expansion described above.
[port=8080]Redirects the original request to a port 8080.
[port=8080][hostname=localhost]Redirects the original request to a port 8080 of localhost.
[port=8080][hostname=localhost][hash={pathname}]Redirects the original request to a port 8080 of localhost where hash is the original request's path.
Names of the supported parameters and their example outputs are listed in the table below.
Example address used as input:
https://www.example.com:8080/some/path?query=value#hash
Name | Output |
---|---|
protocol |
https:
|
hostname |
www.example.com
|
port |
:8080
|
pathname |
/some/path
|
search |
?query=value
|
search.query |
value
|
hash |
#hash
|
host |
www.example.com:8080
|
origin |
https://www.example.com:8080
|
href |
https://www.example.com:8080/some/path?query=value#hash
|
This manual page is build upon the material of the following MDN wiki documents and is licenced under CC-BY-SA 2.5.
- Match patterns by Mozilla Contributors is licensed under CC-BY-SA 2.5.
- webRequest.ResourceType by Mozilla Contributors is licensed under CC-BY-SA 2.5.
- URL by Mozilla Contributors is licensed under CC-BY-SA 2.5.