From MozillaZine Knowledge Base
Jump to navigationJump to search

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).


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


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


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.


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 has images or scripts hosted on, these images and scripts would be considered "third-party". The policy entry should always be followed by a tab.


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 or a single subdomain (e.g., 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, FQDN and non-FQDN domains appear to be considered separate. For a rule to apply to both "" and "", both "" and "" would need to be used.



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


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

 host	cookie	2

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


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

 host	document	2

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 and its subdomains to be rendered as blank:

 host	image	2

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 and its subdomains to be blocked:

 host	object	2

The other selector is related to XBL bindings.


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

 host	popup	2

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


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 and its subdomains:

 host	script	2

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 and its subdomains:

 host	stylesheet	2

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 and its subdomains:

 host	subdocument	2


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 domain, except those set by or its subdomains:

 host	cookie	3

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


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, 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

will block all scripts from,,,, etc. Similarly,

 host	cookie	2

will block,,, 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 while allowing to set cookies that aren't third-party:

 host	cookie	2
 host	cookie	3

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


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


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