Rules are used in a broad sense here: let's rather call them "directives". Most directives will be rules, hence I used "My rules" in the dashboard.

Each line is a directive. Empty lines will be skipped.

The # character can be used for commenting, and for each line, the parser will ignore the first occurrence of # and everything following it.

A directive starts with a directive keyword, immediately followed by the : which character is used to tell a parser that we are dealing with a directive keyword.

There are currently two directives: rule: and matrix:. However, the rule: directive can be omitted, because it is implicit when there is no directive. Since most directives will be rules, it would be inconvenient to be forced to use rule: for each rule.

In the documentation below the square brackets ([]) are used to denote optional fields. Curly brackets ({}) are used to denote what should appear at a specific position.

Directive rule: syntax

source hostname {white spaces} destination hostname {white spaces} [request type {white spaces} [action]]

rule: is implicit, you don't have to use it (actually, currently the parser will not work if you use it...)

White spaces can be any number of space character or tab character.

source hostname is the context from which a net request is made, also known as the "scope". * can be used to denote "any context", aka the global scope.

destination hostname is where the net request is destined. * can be used to denote "any destination".

request type is the type of the net request. If omitted, the * type is assumed and means "any type". The available types are: cookie, css, image, media, font, script, fetch, frame, and other (plus the internal doc type for root documents). See The popup panel for what each type covers.

Note (nuMatrix): font is its own type — fonts are no longer matched under css. The xhr type was renamed to fetch; any old xhr rules are migrated automatically.

action is what to do when a net request matches source hostname, destination hostname and request type. Currently, the actions supported are:

• block: the request will be prevented (often referred as "blacklisted")
• allow: the request will be allowed (often referred as "whitelisted")
• inherit: the action will be inherited from another cell in the matrix, as per cell inheritance logic. It's what is often referred as "graylisted".

If action is omitted, allow is used -- because nuMatrix is naturally deny-default mode at heart.

For both source and destination, matching is hierarchical: a rule for a domain will be matched by all subdomains (except if another rule match for the subdomain).

Order of precedence

General principle: more specific rule overrides less specific rule. Precedence is defined in evaluateCellZXY method (see matrix.js).

Priority order is following: matrix-off > srcHostname > desHostname > type

The order of rules doesn't matter. It is undefined what the rule will have effect among the rules with the same priority.

Examples of rules

Forbid all requests to facebook.net, but allow all net requests of any type to facebook.net only when they are made from within facebook.com context:

* facebook.net * block
facebook.com facebook.net * allow

or

* facebook.net * block
facebook.com facebook.net *

or

* facebook.net * block
facebook.com facebook.net

The above rules all accomplish the same thing, as per default values.

Subdomains will also match, so www.facebook.net will also be filtered except from any subdomain of facebook.com.

Directive matrix-off: syntax

Disable or enable matrix filtering for a specific scope. Syntax:

matrix-off: {white spaces} source hostname {white spaces} state

source hostname is the context for which matrix filtering needs to be toggled on or off.

state can be one of true or false keyword.

Reminder: narrower scopes inherit the matrix-filtering switch state from broader scopes. So if you disable matrix-filtering in the global scope (*), then matrix-filtering will be turned off for all scopes, unless a scope has an explicit override of the matrix-filtering switch.

Other per-scope switch directives

matrix-off: is one of several per-scope switches, all of which share the same directive syntax:

{switch-name}: {white spaces} source hostname {white spaces} state

where state is true or false, and the state inherits from broader scopes just like matrix-off. The available switch names are:

See Per-scope switches for what each one does. Example:

webrtc-block: example.com true
isolate-scope: bank.example false

Note: individual URL rules (per-URL block/allow overrides created by right-clicking a cell) are not part of this rule text — they are stored separately and are not edited in the My rules pane.

nuMatrix wiki

Getting started

• Walkthrough
• Popup panel
• Extension icon
• Scope selector
• FAQ

Matrix and rules

• Rules syntax
• Domain and global rules
• Per-scope switches
• Individual URL rules
• Ruleset recipes
• Useful rulesets

Privacy and blocking

• Cookies
• Filter lists
• Tracking-parameter removal
• Behind-the-scene requests

Tools and advanced

• Logger
• Raw settings
• Cloud storage
• Keyboard navigation
• Privileged pages
• Permissions

Project

• Changes from HTTP Switchboard
• Privacy policy

nuMatrix: point-and-click matrix to filter net requests according to source, destination and type. A maintained fork of uMatrix. Source · Issues