X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Factions-file.html;h=52b7fe1ea096aa0fc770e89ac25af50a3afb76bc;hp=72b9a064357bde67447ccedb2fa08972b5ddf4d9;hb=c27e23a43e40973e170cf901c729b14da6d3b9e8;hpb=e61fdec519cef582a2dc5507543a006b539ad3f4 diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 72b9a064..52b7fe1e 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -1,13 +1,13 @@ +
The actions files are used to define what
Actions can be used to block anything you want, including ads, banners, or
- just some obnoxious URL that you would rather not see. Cookies can be accepted
+ just some obnoxious URL whose content you would rather not see. Cookies can be accepted
or rejected, or accepted only during the current browser session (i.e. not
- written to disk), content can be modified, JavaScripts tamed, user-tracking
+ written to disk), content can be modified, some JavaScripts tamed, user-tracking
fooled, and much more. See below for a complete list
@@ -686,9 +531,9 @@ CLASS="SECT2"
> Note that some We have tried to provide you with reasonable rules to start from in the
distribution actions files. But there is no general rule of thumb on these
@@ -721,9 +566,9 @@ CLASS="SECT2"
> The easiest way to edit the actions files is with a browser by
using our browser-based editor, which can be reached from http://config.privoxy.org/show-status.
- The editor allows both fine-grained control over every single feature on a
- per-URL basis, and easy choosing from wholesale sets of defaults like
- enable-edit-actions must be enabled for
+ this to work. The editor allows both fine-grained control over every single
+ feature on a per-URL basis, and easy choosing from wholesale sets of defaults
+ like "Cautious", "Medium" or or
+ "Advanced".
- Warning: the . Warning: the "Advanced" setting is more aggressive, and
- will be more likely to cause problems for some sites. Experienced users only! If you prefer plain text editing to GUIs, you can of course also directly edit the
the actions files with your favorite text editor. Look at
@@ -763,8 +614,8 @@ CLASS="SECT2"
CLASS="SECT2"
>8.3. How Actions are Applied to Requests8.3. How Actions are Applied to Requests Actions files are divided into sections. There are special sections,
like the 8.4. Patterns8.4. Patterns
As mentioned, Generally, a URL pattern has the form
+> Generally, an URL pattern has the form
<domain>/<path> matches all the documents on www.example.com
+ whose name starts with /index.html.
+ matches nothing, since it would be interpreted as a domain name and
+> matches nothing, since it would be interpreted as a domain name and
there is no top-level domain called .html The matching of the domain part offers some flexible options: if the
domain starts or ends with a dot, it becomes unanchored at that end.
@@ -1047,17 +915,29 @@ CLASS="LITERAL"
> matches any domain that ENDS in
- matches any domain with first-level domain .example.comcom
+ and second-level domain example.
+ For example www.example.com,
+ example.com and foo.bar.baz.example.com.
+ Note that it wouldn't match if the second-level domain was another-example.
8.4.3. The Tag Pattern8.4.3. The Tag Pattern Tag patterns are used to change the applying actions based on the
request's tags. Tags can be created with either the
client-header-tagger
or the server-header-tagger action.
can tell them apart from URL patterns. Everything after the colon
including white space, is interpreted as a regular expression with
- path patterns syntax, except that tag patterns aren't left-anchored
- automatically (Privoxy doesn't silently add a Privoxy doesn't silently add a "^",
@@ -1533,7 +1420,11 @@ CLASS="QUOTE"
match requests whose tags contain "foo" somewhere. Sections can contain URL and tag patterns at the same time,
but tag patterns are checked after the URL patterns and thus
@@ -1544,13 +1435,18 @@ CLASS="QUOTE"
tags can be used to activate other tagger actions, as long as these other
taggers look for headers that haven't already be parsed. For example you could tag client requests which use the POST method,
- use this tag to activate another tagger that adds a tag if cookies
- are send, and then block based on the cookie tag. However if you'd
- reverse the position of the described taggers, and activated the method
- tagger based on the cookie tagger, no method tags would be created.
+> For example you could tag client requests which use the
+ POST method,
+ then use this tag to activate another tagger that adds a tag if cookies
+ are sent, and then use a block action based on the cookie tag. This allows
+ the outcome of one action, to be input into a subsequent action. However if
+ you'd reverse the position of the described taggers, and activated the
+ method tagger based on the cookie tagger, no method tags would be created.
The method tagger would look for the request line, but at the time
- the cookie tag is created the request line has already been parsed. While this is a limitation you should be aware of, this kind of
indirection is seldom needed anyway and even the example doesn't
@@ -1563,8 +1459,8 @@ CLASS="SECT2"
CLASS="SECT2"
>8.5. Actions8.5. Actions All actions are disabled by default, until they are explicitly enabled
somewhere in an actions file. Actions are turned on if preceded with a
@@ -1726,7 +1622,7 @@ CLASS="REPLACEABLE"
>
Example: +hide-user-agent{ Mozilla 1.0 }+hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}
Later defined actions always over-ride earlier ones. So exceptions
- to any rules you make, should come in the latter part of the file (or
+> Later defined action sections always over-ride earlier ones of the same type.
+ So exceptions to any rules you make, should come in the latter part of the file (or
in a file that is processed later when using multiple actions files such
as 8.5.1. add-header8.5.1. add-header If the request URL gets changed, Privoxy will detect that and use the new
+ one. This can be used to rewrite the request destination behind the client's
+ back, for example to specify a Tor exit relay for certain requests.
+ Please refer to the filter file chapter8.5.4. client-header-tagger8.5.4. client-header-tagger It is also useful to make sure the header isn't used as a cookie
- replacement.
+ replacement (unlikely but possible).
Blocking the "If-Modified-Since:" header
- isn't blocked as well.
+ isn't blocked or missing as well.
It is recommended to use this action together with
@@ -2702,8 +2606,9 @@ WIDTH="90%"
> Prevent the web server from setting any cookies on your system
+> Prevent the web server from setting HTTP cookies on your system
It makes 8.5.9. crunch-server-header8.5.9. crunch-server-header Prevent the web server from reading any cookies from your system
+> Prevent the web server from reading any HTTP cookies from your system
Overrules the forward directives in the configuration files.
+> Overrules the forward directives in the configuration file.
8.5.15. force-text-mode8.5.15. force-text-modeFeature Cautious Medium Advanced Ad-blocking Aggressiveness medium high high Ad-filtering by size no yes yes Ad-filtering by link no no yes Pop-up killing blocks only blocks only blocks only Privacy Features low medium medium/high Cookie handling none session-only kill Referer forging no yes yes GIF de-animation no yes yes Fast redirects no no yes HTML taming no no yes JavaScript taming no no yes Web-bug killing no yes yes http://config.privoxy.org/show-status.
The over-riding principle when applying actions, is that the last action that
- matches a given URL, wins. The broadest, most general rules go first
+ matches a given URL wins. The broadest, most general rules go first
(defined in default.actiondefault.action,
- with the advantage that is a separate file, which makes preserving your
+ with the advantage that it is a separate file, which makes preserving your
personal settings across PrivoxyImage tag reordering no no yes 8.1. Finding the Right Mix
8.1. Finding the Right Mix8.2. How to Edit
8.2. How to Edit8.4.1. The Domain Pattern
8.4.1. The Domain Pattern8.4.2. The Path Pattern
8.4.2. The Path Pattern# Tag every request with the User-Agent header
-{+client-header-filter{user-agent}}
+{+client-header-tagger{user-agent}}
/
8.5.5. content-type-overwrite8.5.5. content-type-overwrite# Let the browser revalidate cached documents without being tracked across sessions
-{ +hide-if-modified-since{-60} \
+># Let the browser revalidate cached documents but don't
+# allow the server to use the revalidation headers for user tracking.
+{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/
8.5.8. crunch-incoming-cookies8.5.8. crunch-incoming-cookies { +fast-redirects{simple-check} }
- .example.com
+ one.example.com
{ +fast-redirects{check-decoded-url} }
another.example.com/testing
8.5.14. filter8.5.14. filter+filter{ie-exploits} # Disable some known Internet Explorer bug exploits
+filter{ie-exploits} # Disable a known Internet Explorer bug exploits
This action will probably be removed in the future, + use server-header filters instead. +
It is a good idea to only use a small negative value and let @@ -5066,7 +4977,8 @@ CLASS="LITERAL" HREF="actions-file.html#CRUNCH-IF-NONE-MATCH" >crunch-if-none-match. +>, + otherwise it's more or less pointless.
# Let the browser revalidate without being tracked across sessions -{ +hide-if-modified-since{-60} \ +># Let the browser revalidate but make tracking based on the time less likely. +{+hide-if-modified-since{-60} \ +overwrite-last-modified{randomize} \ +crunch-if-none-match} /8.5.22. hide-forwarded-for-headers8.5.22. hide-forwarded-for-headers
Improve privacy by hiding the true source of the request
Improve privacy by not forwarding the source of the request in the HTTP headers.It is fairly safe to leave this on. -
This action is scheduled for improvement: It should be able to generate forged - "X-Forwarded-for:" headers using random IP addresses from a specified network, - to make successive requests from the same client look like requests from a pool of different - users sharing the same proxy. +> It is safe and recommended to leave this on.
"conditional-forge" to forge the header if the host has changed.
"block" to delete the header unconditionally.
Always blocking the referrer, or using a custom one, can lead to failures on servers that check the referrer before they answer any - requests, in an attempt to prevent their valuable content from being + requests, in an attempt to prevent their content from being embedded or linked to elsewhere.
8.5.25. hide-user-agent8.5.25. hide-user-agent
Conceal your type of browser and client operating system
Try to conceal your type of browser and client operating systemThis action is scheduled for improvement. +> More information on known user-agent strings can be found at + http://www.user-agents.org/ + and + http://en.wikipedia.org/wiki/User_agent.
To protect against the MS buffer over-run in JPEG processing
Try to protect against a MS buffer over-run in JPEG processingNote that the exploit mentioned is several years old + and it's unlikely that your client is still vulnerable + against it. This action may be removed in one of the + next releases.
This action doesn't work very reliable and may be removed in future releases. +
8.5.29. prevent-compression8.5.29. prevent-compression Disable or disable filters based on the Content-Type header.
+> Enable or disable filters based on the Content-Type header.
Note that many of these actions have the potential to cause a page to
misbehave, possibly even not to display at all. There are many ways
@@ -7296,8 +7223,8 @@ CLASS="SECT2"
CLASS="SECT2"
>8.6. Aliases8.6. Aliases Custom 8.7. Actions Files Tutorial8.7. Actions Files Tutorial The above chapters have shown Every config file should start with a short comment stating its purpose: Again, at the start of matching, all actions are disabled, so there is
- no real need to disable any actions here, but we will do that nonetheless,
- to have a complete listing for your reference. (Remember: a "+"
@@ -7766,178 +7692,26 @@ CLASS="SCREEN"
# "Defaults" section:
##########################################################################
{ \
- -add-header \
- -client-header-filter{hide-tor-exit-notation} \
- -block \
- -content-type-overwrite \
- -crunch-client-header \
- -crunch-if-none-match \
- -crunch-incoming-cookies \
- -crunch-server-header \
- -crunch-outgoing-cookies \
+deanimate-gifs \
- -downgrade-http-version \
- -fast-redirects{check-decoded-url} \
- -filter{js-annoyances} \
- -filter{js-events} \
+filter{html-annoyances} \
- -filter{content-cookies} \
+filter{refresh-tags} \
- -filter{unsolicited-popups} \
- -filter{all-popups} \
- -filter{img-reorder} \
- -filter{banners-by-size} \
- -filter{banners-by-link} \
+filter{webbugs} \
- -filter{tiny-textforms} \
- -filter{jumping-windows} \
- -filter{frameset-borders} \
- -filter{demoronizer} \
- -filter{shockwave-flash} \
- -filter{quicktime-kioskmode} \
- -filter{fun} \
- -filter{crude-parental} \
+filter{ie-exploits} \
- -filter{google} \
- -filter{yahoo} \
- -filter{msn} \
- -filter{blogspot} \
- -filter{no-ping} \
- -force-text-mode \
- -handle-as-empty-document \
- -handle-as-image \
- -hide-accept-language \
- -hide-content-disposition \
- -hide-if-modified-since \
+hide-forwarded-for-headershide-referrer{forge} \
- -hide-user-agent \
- -inspect-jpegs \
- -kill-popups \
- -limit-connect \
+prevent-compression \
- -overwrite-last-modified \
- -redirect \
- -send-vanilla-wafer \
- -send-wafer \
- -server-header-filter{xml-to-html} \
- -server-header-filter{html-to-xml} \
+set-image-blocker{pattern} \
- -treat-forbidden-connects-like-blocks \
}
/ # forward slash will match *all* potential URL patterns. The default behavior is now set. Note that some actions, like not hiding
- the user agent, are part of a "general policy" that applies
- universally and won't get any exceptions defined later. Other choices,
- like not blocking (which is understandably the
- default!) need exceptions, i.e. we need to specify explicitly what we
- want to block in later sections. The first of our specialized sections is concerned with So far we are painting with a broad brush by setting general policies,
which would be a reasonable starting point for many people. Now,
@@ -8560,7 +8277,7 @@ WIDTH="100%"
> 8.5.36. session-cookies-only8.5.36. session-cookies-only# Tag every request with the declared content type
-{+client-header-filter{content-type}}
+># Tag every request with the content type declared by the server
+{+server-header-tagger{content-type}}
/
8.5.39. Summary
8.5.39. Summary8.7.1. default.action
8.7.1. default.action8.7.2. user.action
8.7.2. user.action block }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/default.filter,
- but it is disabled in the distributed actions file. (My colleagues on the team just
- don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
+ but it is disabled in the distributed actions file.
+ So you'd like to turn it on in your private,
update-safe config, once and for all:# My user.action file. <fred@foobar.com>
# My user.action file. <fred@example.com>