Hostperm.1

From MozillaZine Knowledge Base
Jump to: navigation, search
hostperm.1 is a file in the profile folder. The file name is incorrectly capitalized in the title of this article due to technical limitations in the software which powers the Knowledge Base.

The file "hostperm.1" dictates what page elements sites are allowed to load in Firefox 2 or below and in Mozilla Suite/SeaMonkey 1.x. (Starting in Firefox 3 and SeaMonkey 2, site permissions are stored in the file permissions.sqlite and hostperm.1 is no longer used.)

A basic hostperm.1 entry looks like this: 

 host	selector	policy	domain

Each element is separated from the previous element by a tab, and a new line starts a new entry.

Because hostperm.1 is an outlet for Gecko's nsIContentPolicy code, it deals only with loading files, not with inline tags. As a result, rules in hostperm.1 will not affect inline styles, inline scripts, or DOM event scripts, to name a few common examples. Tags with a src= attribute are affected, because the src attribute specifies an external file to load (which is therefore controlled by nsIContentPolicy).

Editing

It is not recommended that users edit this file manually. However, changes may be made using a plain text editor if needed, using the following guide.

Basic editing

Host

The host column always contains the word "host". The host entry should always be followed by a tab.

Selector

The selector controls the page elements to which a rule applies. Possible values are cookie, document, image, object, other, popup, refresh, script, stylesheet, and subdocument. The selector entry should always be followed by a tab.

Policy

There are three possible values for policy. A value of 1 maps to "allow", 2 maps to "deny" (or block), and 3 maps to "deny third-party". "Allow" is the default policy; in other words, a blank hostperm.1 file will allow everything. In general, "third-party" means those elements which are hosted on a different server from the HTML page host. For instance, if http://example.com/index.html has images or scripts hosted on http://adserver.somedomain.com, these images and scripts would be considered "third-party". The policy entry should always be followed by a tab.

Domain

The domain column is used to specify the scope of a rule. Typically, rules will be applied to a single domain (e.g., anything ending in example.com) or a single subdomain (e.g., adserver.example.com). The domain entry should always be followed by a line break, even if it is the last entry in the file.

At least for Firefox 2.0.0.7, FQDN and non-FQDN domains appear to be considered separate. For a rule to apply to both "example.com/" and "example.com./", both "example.com" and "example.com." would need to be used.

Fine-tuning

Selectors

Explanations of each of the 10 different selectors are given below.

cookie

Use the cookie selector to control cookie policy for a given domain. For example, the following blocks all cookie requests from example.com and its subdomains: 

 host	cookie	2	example.com

In the case of cookies, a policy value of 8 will force all cookies set by that domain to expire when quitting the browser.

document

Use the document selector to control top-level document policy for a given domain. The following will cause all content on example.com and its subdomains to be blank: 

 host	document	2	example.com
image

Use the image selector to control the loading of images for a given domain. Inline images (that is, those specified in HTML source with an <img> tag) and CSS images are both affected by this selector. Note that, if used to block images, the image area will still be displayed, but will render as blank space. The following will cause all images on example.com and its subdomains to be rendered as blank: 

 host	image	2	example.com
object

Use the object selector to control the contents of <embed> and <object> tags, like plug-in content.

This selector does not control the contents of <object> tags on 1.8 branch or earlier builds (i.e., Firefox 1.5.x, Camino 1.0.x, etc.). These builds will also render blocked content as a two-pixel vertical line with a height as specified by the HTML file. Recent trunk builds block <object> properly and render both <embed> and <object> content as invisible.

The following will cause all <embed> and <object> tags on example.com and its subdomains to be blocked: 

 host	object	2	example.com
other

The other selector is related to XBL bindings.

popup

Use the popup selector to control pop-up window policy for a given domain. The following will prevent most pop-up windows on example.com and its subdomains: 

 host	popup	2	example.com
refresh

Use the refresh selector to control the actions of a <meta> refresh tag?

script

Use the script selector to control a domain's ability to run scripts. This policy does not apply to inline scripts or those specified as part of DOM events (e.g., onLoad, onClick, etc.). The following will block all scripts specified with a src attribute on example.com and its subdomains: 

 host	script	2	example.com
stylesheet

Use the stylesheet selector to control the functionality of cascading style sheets. This policy does not apply to inline styles, but only to sheets specified through <link> tags or @import directives. The following will block all imported stylesheets on example.com and its subdomains: 

 host	stylesheet	2	example.com
subdocument

Use the subdocument selector to control the display of framesets, iframes, and <object> tags on a given domain. Frameset contents, if blocked, will be rendered blank, but the frame itself will still show. Iframes will be rendered as blank, but in the page-specified width and height, with page-specified border, if present. <object> tags are rendered the same way as iframes. The following will render blank all framesets, iframes, and <object> tags on example.com and its subdomains: 

 host	subdocument	2	example.com

Policy

If you use a site that requires cookies to be functional, but you wish to prevent that site's advertisers from tracking you via the use of cookies, you might wish to add the following, which will block all cookies set by code from any page in the example.com domain, except those set by example.com or its subdomains: 

 host	cookie	3	example.com

See also the Domain section immediately below; setting good cookie-blocking rules often requires complex combinations of policy and specific domain settings.

Domain

The Internet places no practical limitation on the number of subdomains possible on a given domain. It is possible to have a server with the address a.b.c.d.e.f.g.example.com, for instance. It is important to remember that rules in hostperm.1 start matching from the end of the server address, so that 

 host	script	2	example.com

will block all scripts from example.com, adserver.example.com, www.example.com, mail.example.com, etc. Similarly, 

 host	cookie	2	adserver.example.com

will block z.adserver.example.com, a.adserver.example.com, c.adserver.example.com, etc. The hostperm.1 file can often be optimized by condensing separate rules like this, but be careful -- it's easy to block more than you intended by being too aggressive with the domain column.

The domain column can be used for fine-tuning, too, as in this example that blocks cookies from adserver.example.com while allowing example.com to set cookies that aren't third-party: 

 host	cookie	2	adserver.example.com
 host	cookie	3	example.com

It may also be advantageous to set a rule that applies to all servers in a given top-level domain. For example, if you wanted to deny the use of cookies to any site in the .biz TLD and block scripts on all sites in Russia, you could use the following two rules: 

 host	cookie	2	biz
 host	script	2	ru

Moving

This file can be moved or copied to a different profile without any modifications.

Deleting

Deleting hostperm.1 will delete the whitelists and blacklists ("Exceptions Lists" in Camino) for cookies, popups, scripts, images, etc. A new file may be created by whitelisting or blacklisting cookies, popups, scripts, or images from any site.

Related bugs

See also

Retrieved from "https://kb.mozillazine.org/index.php?title=Hostperm.1&oldid=38085"