-
Notifications
You must be signed in to change notification settings - Fork 0
/
Quickstart.html
109 lines (109 loc) · 11.6 KB
/
Quickstart.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title></title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="./github-markdown.css">
</head>
<body>
<h1 id="requestpolicy-continued---quick-start">RequestPolicy Continued - Quick Start</h1>
<p>Here is a quick tutorial on how to use RequestPolicy. If you have any questions or ideas, please <a href="https://github.com/RequestPolicyContinued/requestpolicy/issues">open a new issue</a>.</p>
<h2 id="setting-up---default-policy">Setting up - default policy</h2>
<p>The first thing to do when setting up RequestPolicy is to choose a <strong>default policy</strong>. It determines whether cross-site requests should be <strong>allowed or blocked by default</strong>, when there are no other rules that match the request. This affects ease of use for the addon, and your security/privacy level:</p>
<ul>
<li><strong>Allow requests by default.</strong> This is the less secure/private setting. All requests will be allowed by default unless you tell RequestPolicy not to allow them. This is also the easiest option: your browser behavior will not change from before installing RequestPolicy, websites will not break unexpectedly.</li>
<li><strong>Block requests by default.</strong> This is the most secure/private setting. RequestPolicy will block all cross-site requests that you have not explicitly approved. This will cause some websites not to display/function properly, so you will have to do some manual whitelisting, explained later.</li>
<li>For <strong>easier usage</strong> of this setting, you may want to enable <strong><a href="#Setting-up---subscriptions">subscriptions</a></strong> (see below).</li>
<li>For <strong>even more security/privacy</strong>, you can disable the option to <code>allow requests to the same domain</code>. Requests between subdomains of the same “site” will also be blocked. For example, <code>example.com -> subdomain.example.com</code> will be blocked. This will cause browsing on many sites to break.</li>
</ul>
<p>The default policy can be changed at any time by going to <code>Preferences > Manage policies > Default policy</code></p>
<table>
<tr>
<td style='background-color: #DDD; padding: 5px;'>💡</td>
<td>Blocking requests by default will cause many websites to break. For the first few weeks, you may frequently have to open the RequestPolicy menu to allow requests. Over time you will build up your policy for the websites you visit regularly and so you will only see broken websites when you visit sites you haven't visited before.</td>
</tr>
</table>
<hr />
<h2 id="setting-up---subscriptions">Setting up - subscriptions</h2>
<p>Subscriptions are preset rules maintained and verified by the community. These rules can fulfil different needs, such as blocking known web browsing tracking sites, or allowing requests to allow certain sites to display/work properly.</p>
<p><strong>Just select the subscriptions that you consider useful.</strong></p>
<table>
<tr>
<td style='background-color: #DDD; padding: 5px;'>💡</td>
<td>Keep in mind that enabling a subscription <b>automatically adds allow/block rules</b> to your RequestPolicy installation, and <b>downloads/updates them automatically</b> with the latest available version. If you want to know more precisely what rules are included in subscriptions, or want to contribute to subscriptions to make RequestPolicy easier to use for others, visit the subscriptions code repository at <a href="https://github.com/RequestPolicyContinued/subscriptions">https://github.com/RequestPolicyContinued/subscriptions</a></td>
</tr>
</table>
<p><em>Note: In case there is a user rule that conflicts with a subscription rule, the user rule always has priority.</em></p>
<hr />
<h2 id="usage-how-requestpolicy-works">Usage: How RequestPolicy Works</h2>
<p>Every time a web page tells Firefox to make a request to a different website, <strong>Firefox asks RequestPolicy</strong> whether the request should be allowed. To decide whether to allow the request, RequestPolicy looks for <a href="Rules.html">rules</a> in three places:</p>
<ul>
<li><strong>Your</strong> policy: rules you have created in RequestPolicy.</li>
<li><strong>Subscription</strong> policies: rules proposed by the community, maintained by the RequestPolicy developers.</li>
<li><strong>Default</strong> policy: the rule to use when no other rule matches.</li>
</ul>
<p>The rest of this tutorial will show you how to manage your policy.</p>
<hr />
<h2 id="toolbar-icon">Toolbar Icon</h2>
<p><img src="media/rp-1.png" /></p>
<p>Once RequestPolicy is installed, you will see a new <strong>flag icon</strong> at the top-right of your browser window. This flag <strong>turns red</strong> when RequestPolicy has blocked requests from the current website you are viewing. Clicking on the RequestPolicy icon brings up a menu of options.</p>
<h2 id="menu">Menu</h2>
<p>The <strong>left pane</strong> is divided in 2 sections: Origins and Destinations.<br />The <strong>right pane</strong> contains actions for the item you have selected form the left pane.</p>
<p><img style='width: 90%' src='media/menu.png'/></p>
<h3 id="destinations">Destinations</h3>
<p>Destinations are domains that are targets of a cross-site request. Commonly, this can be a <a href="https://en.wikipedia.org/wiki/Content_delivery_network">CDN</a>, a separate/special domain for images or scripts used on a site, embedded objects to integrate another site, or an advertising/metrics/statistics network.</p>
<h4 id="blocked-destinations">Blocked destinations</h4>
<p>These destinations are shown in red. Requests from the current page to these domains (e.g an embedded script or image hosted on this other domain) are blocked.</p>
<ul>
<li>Requests to these domains are never sent. Resources hosted on blocked destinations are not downloaded on your computer.</li>
<li>Blocked destinations are sorted by number of blocked requests (numbers on the right).</li>
<li>Blocking destinations <strong>prevents downloading unnecessary</strong> resources, as well as tracking scripts from third-parties.</li>
<li>It may also somehow <strong>break</strong> functionality or display if the blocked resources are needed to make the site work properly (“real” content images, usability scripts, styling…)</li>
</ul>
<p>If you <strong>click on one of the blocked destinations</strong>, you are given options to allow this destination. The first time you visit a site, if it doesn’t display or work properly, you will have to <strong>allow</strong> some destinations. Let’s say you are browsing example.com, and it doesn’t display properly:</p>
<p><img style='width: 90%' src='media/menu-full.png'/></p>
<p>Look in the menu for blocked destinations that have a <strong>large number of blocked requests</strong> (number on the right of the domain name). This might indicate that the page tries to load a lot of content from this domain, but RequestPolicy blocks it. Click on one of these destinations (eg. <code>example.net</code>). From there, the possible actions are displayed in the right pane.</p>
<p><strong>Allow requests from example.com to another.net:</strong> Use this if you want to allow pages from <code>example.com</code> to use content hosted on <code>another.net</code>.</p>
<ul>
<li>If content hosted on <code>another.net</code> is really required to display the page, the page will be working when you reload it (just click anywhere outside the menu).</li>
<li>You may need to allow several domains for the page to work correctly.</li>
<li>Over time you will learn to recognize destinations that need to be allowed, and those that are useless/harmful.</li>
</ul>
<p><strong>Allow requests to another.net:</strong> This will allow <strong>all</strong> requests to <code>another.net</code>, from any page, on any domain. This is not recommended unless you keep having to allow requests to <code>another.net</code> from <strong>many</strong> sites.</p>
<ul>
<li>You should only do this when you trust this destination does not track you across the web, is not a domain that hosts attackers, and has good security practices.</li>
</ul>
<p><strong>Block requests from example.com to another.net</strong> and <strong>Block all requests to another.net:</strong> This is useful if you want to mark this destination as untrusted/useless/harmful.</p>
<ul>
<li>Note that the <code>Block all requests by default</code> default policy will block requests to any domain, even if you do not manually block it. Still, manually blocking domains can be used to distinguish domains that you personally don’t trust (for example a known tracking/analytics domain)</li>
</ul>
<p><strong>Stop blocking/allowing requests to another.net:</strong> This removes the rule you had previously set for this destination. The <strong>default policy</strong> will be used instead.</p>
<p><em>Note: Each action has a Temporarily block/allow alternative. This will add a temporary rule that will be removed when you click the <code>Revoke all temporary permissions</code> menu item. When you close Firefox, all temporary rules are forgotten.</em></p>
<h4 id="allowed-destinations">Allowed destinations</h4>
<p>Requests to these destinations are allowed, because you manually allowed them, or the default policy is to <code>Allow requests by default</code>. The actions for allowed destinations are similar to those for blocked destinations.</p>
<h4 id="mixed-destinations">Mixed destinations</h4>
<p>If a destination had some requests to it blocked and others allowed, it would be listed under another category called “Mixed destinations”.</p>
<h3 id="origins">Origins</h3>
<p>Origins are domains from where cross-site requests originate. Commonly, this is <strong>the site you are currently visiting</strong> when the cross-site request is done (there is an exception, see below). For example this can be a <code><script></code> tag in the HTML page, or an <code><img></code> that tries to embed an image from another site. Origins have one action available:</p>
<p><strong>Allow requests from example.com:</strong> <strong>All</strong> requests originating from <code>example.com</code> will be allowed. Use this if you trust the site to never embed any harmful/useless content, and want it to work fully as intended by the site itself. This should only be used on very trustworthy sites.</p>
<ul>
<li>Note that it will be <code>Block all requests from example.com</code> if you use the <code>Allow requests by default</code> default policy.</li>
</ul>
<h4 id="other-origins">Other Origins</h4>
<p>It’s also possible that one of the destinations from this page was itself a document or redirect to some other destination. In that case, the destination is also an origin of requests and you’ll see it listed under <code>Other origins</code>. If you click on one of the other origins, the list of blocked and allowed destinations will change to show you the destinations from that origin.</p>
<hr />
<p><strong>That’s it! Now you should be able to do most of the things RequestPolicy is built for. For more advanced topics, you can read the documentation below.</strong></p>
<hr />
<h2 id="links">Links</h2>
<ul>
<li><a href="https://github.com/RequestPolicyContinued/requestpolicy/issues/665#issue-84260569">Updating from RP 0.5.xx to RPC</a></li>
<li><a href="https://github.com/RequestPolicyContinued/requestpolicy/issues/665#issuecomment-108138806">Using RequestPolicy with Default Deny and a short Whitelist</a></li>
</ul>
</body>
</html>