Configuration

Contents

• Settings
• Inject
• Group
• Rules
• Fields

The operation of Karma Blocker is divided into sections like the common .ini file format. There are four valid kinds of lines:

• A group header.

  I.E.: [Settings], [Group].

• A configuration directive.

  Always a field name, an equals sign, then a value appropriate for the field.

  I.E.: threshold=5.

• A comment (valid anywhere).

  A hash mark followed by anything, up to the end of the line. I.E.: # This group will ...

• A blank line.

Whitespace (newline, space, tab) can exist between any valid tokens; it will be ignored. A comment can start anywhere, not only at the beginning of a line. The values usually fall into one of these groups:

number :

Any positive or negative integer or floating point number.

string :

Any character string, delimited by single or double quotes. Strings do not span lines.

boolean :

Either of true or false, exactly.

Settings

The [Settings] section describes the overall operation of Karma Blocker.

Field	Values	Description
threshold	number	The threshold is the minimum score required to block. Each group gets a score; each matching group's score is added together. When that total is greater than or equal to the threshold, the resource will be blocked.
cutoff	number	The cutoff functions just like the threshold. The difference between the two is that the threshold is only compared after all groups have been checked, while the cutoff is checked after every group. If, at any point, the score is greater than or equal to the cutoff, the request is immediately denied. (Immediately accepted if it is less than or equal to the negative value of the cutoff.)
collapse	boolean	Collapse not only blocked elements, but their containers. Intended to only block "empty" containers, but can be over aggressive, so it is configurable, and off by default.

Inject

The [Inject] section controls injection of dummy content into web pages.

Field	Values	Description
function	string	This line may be repeated one or more times. For each time that it is provided, a function with the name passed will be placed into content pages. Use this to avoid "something is undefined" error messages when scripts are blocked. You may use "dotted object" notation, so i.e. foo.bar will create a function foo with a property bar (which is also a function).

Group

The [Group] section is the main meat of Karma Blocker. You may have one or more group sections.

Field	Values	Description
name	string	A name which will be displayed in the monitor window.
match	One of: any, all	This group matches when any of its rules match, or matches when all of its rules match. (Default: any)
score	number	When this group matches, this score is added onto the total karma for this resource. (Default: 1)
rule	see below	The rule line specifies a field, an operator, and a value to check for. Since it is complicated, it gets its own section.

Rules

Rules come in a simple format with many possibilities: a field, an operator, and a value. Each field has different values that are appropriate to match it; different values have different appropriate operators.

Operators:

Name	Operator	Description
Equals	==	Field matches value exactly.
Not equals	!=	Boolean opposite of equals.
Matches	=~	Applies a regular expression (regex) to the field. The regex should be expressed as a string. For those who know JavaScript: this string is passed directly to the new RegExp() constructor. For everyone else: this means that you do not need to backslash-escape forward slashes. Otherwise, this is a standard regex expressed as a string, with all the capabilities of Mozilla's engine.
Not matches	!~	Boolean opposite of matches.
Starts-with	^=	Though this could be written as a regex with the match operator, the starts-with operator uses plain string operations, so there should be no character escaping.
Ends-with	$=	Complement to starts-with.
Less than	<	Field is less than value. E.G. $rule=$origin.tag.width<100
Greater than	>	Field is greater than value.

(Note: all comparisons are done in a case-insensitive manner.)

Fields

Field	Values	Description
$thirdParty	boolean	When the referrer is a different domain than the resource, third party is true. Equals is the only operator that makes sense for this field.
$type	script, image, stylesheet, object, object_subrequest, subdocument, ping, font, media	These values are based on the constants defined in the Mozilla interface nsIContentPolicy. Most of these are self-explanitory, but read that page for a more thorough description. Equals and not equals are the only operators that make sense for this field.
$url	string	The (full) URL of the resource being evaluated. Also available: $url.host, $url.path, $url.scheme, for just those parts of the URL.
$origin	string	The (full) URL of the "origin" of the resource being evaluated. Also known as the "referrer". Also available: $origin.host, $origin.path, $origin.scheme for just those parts of the URL.
$origin.tag	string	The HTML tag name (i.e. img, style, script, object) that this resource is being loaded into.
$origin.tag.*	string	For each attribute of the origin tag, its value. For example, $origin.tag.width or $origin.tag.height.