Ruleset recipes
[documentation is currently being fleshed out]
Ruleset recipes ("recipes" thereafter) are community-contributed rulesets suggested to you when you visit a given web site. Recipes are specific, they contain only the necessary rules to un-break a specific web site or behavior.
When one or more recipes are available for a given web site, they will be suggested to you in the popup panel (through the puzzle icon), such that you can inspect the rules and easily import them into your own ruleset if you agree with the rules.
Recipes are never automatically imported, they always require that you explicitly import them. You may inspect all the rules by expanding the recipe.
When you import a recipe, the rules are always imported into your temporary ruleset.
Some recipes may contain rules which are not visible from the current matrix, or contain rules which affect multiple scopes. Here is an example of such recipe, already present as a stock one:
Youtube with account
youtube.com *
example.com 1st-party script
example.com googlevideo.com *
example.com googlevideo.com xhr
accounts.google.com 1st-party *
accounts.google.com 1st-party cookie
accounts.google.com gstatic.com *
accounts.google.com gstatic.com script
When you import this recipe (let's say into the example.com scope), temporary rules will be created in the current scope, and rules will also be created in the accounts.google.com scope (to allow logging in the current case). If you are satisfied that all the rules in the recipe are to be kept permanently, click the padlock icon aside the recipe, this will save all the rules for that specific recipe. If you were to use the popup panel padlock, only the rules which are currently visible in the popup panel would be saved.
Everybody is free to create whatever ruleset they see fit.
Given this, it is impossible to guarantee that any given recipe will un-break a given web site as intended by the recipe author. Hence there are some guidelines about contributing recipes that are likely to work for most users. If a recipe does not work as intended because they are imported into rather restrictive personal ruleset, this will be for the user to work out.
Recipe authors should craft their recipes as if they were to be imported in the following ruleset -- this will be the most restrictive destination ruleset supported by recipe contributors:
* * * block
* * script block
* * frame block
* first-party * allow
* first-party frame allow
This is the most restrictive destination ruleset supported: all 3rd-party resources are blocked, all scripts (1st- and 3rd-party) are blocked, and all 3rd-party frames are explicitly blocked.
In order to minimize the amount of rules to be imported, recipes should list the necessary rules from broadest to narrowest -- uMatrix will always discard rules from a recipe which are not necessary given the content of the destination ruleset.
Here is an example using an existing stock recipe:
Vimeo as 3rd-party
* player.vimeo.com
_ player.vimeo.com *
_ player.vimeo.com script
_ player.vimeo.com frame
_ vimeocdn.com *
_ vimeocdn.com script
The first line is the name of the recipe, to be used in the popup panel. It must make the purpose of the recipe obvious.
The second line is the condition which tells uMatrix when a recipe should be presented to the user in the popup panel. It's made of two parts: the 1st-party hostname and the 3rd-party hostname which must be matched in the current matrix for the recipe to be considered relevant.
In the specific example above, the condition to match is * player.vimeo.com, which means: the recipe is relevant for any given scope in which player.vimeo.com is a 3rd-party.
The other lines are rules to be imported.
The special underscore symbol _ is a scope placeholder, it is meant to be replaced by the scope currently selected in the popup panel.
Once a user imports a recipe, uMatrix will evaluate each rule in order of appearance, and determine whether it must be imported according to whether the resources specified in a rule is currently blocked or not. If a resource is not blocked, the rule won't be imported.
For example, if a user imports the above recipe into the default ruleset (the one in effect when you first install uMatrix), the rule [current scope] player.vimeo.com script allow won't be imported, because the rule [current scope] player.vimeo.com * allow will already have caused the [current scope] player.vimeo.com script cell to be allowed, and similarly the rule [current scope] vimeocdn.com script allow won't be be needed.
Recipe contributors must never specify globally-scoped rules in their recipes, unless such behavior is made very clear by the recipe name. For example, the following recipe could be crafted to whitelist some popular CDN:
Globally whitelist jsDelivr CDN
* cdn.jsdelivr.net
* cdn.jsdelivr.net *
* cdn.jsdelivr.net script
Note the use of the word globally in the recipe name, and also note that global scope * was used as the scope in the rules rather than the placeholder _ typically found in non-global recipes.
The only types which should be used explicitly in a recipe ruleset are the following: *, script, frame -- these are the only types needed to accommodate the strictest supported ruleset. There is an exception however: you may declare a rule for any other types if and only if this the only type necessary to unbreak the site. An example of this:
Google Translate API: globally allow
* translate.googleapis.com
* translate.googleapis.com xhr
The ruleset recipe above is useful for Chromium-based browsers, as it allows the "Translate to English" feature to work properly. Nothing more than a xhr is needed for the feature to work properly.
A ruleset recipes file MUST start with the following line:
! uMatrix: Ruleset recipes 1.0
If this line is not present, uMatrix will (silently) ignore the content of the file (even though you will be able to import it).
Optionally, the following lines -- which may be used by uMatrix:
! Title: Rulesets for English websites
! Maintainer: uMatrix
Each ruleset recipe MUST be separated by an empty line.