X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=fc78f12da39f682d1e3663f3c758e0de603a987c;hp=b4a32574692901eca39cb39fcbc79ad3b9415191;hb=7200b36362d29ad2961b1d89321df46263d0f3e5;hpb=f01b992d60547a210a4a934cc853bad505d94803 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index b4a32574..fc78f12d 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -13,7 +13,7 @@ - + @@ -36,9 +36,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.193 2014/07/18 10:01:39 fabiankeil Exp $ + $Id: user-manual.sgml,v 2.217 2017/01/23 12:59:45 fabiankeil Exp $ - Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/ + Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/ See LICENSE. ======================================================================== @@ -57,12 +57,12 @@ - Copyright &my-copy; 2001-2014 by - Privoxy Developers + Copyright &my-copy; 2001-2016 by + Privoxy Developers -$Id: user-manual.sgml,v 2.193 2014/07/18 10:01:39 fabiankeil Exp $ +$Id: user-manual.sgml,v 2.217 2017/01/23 12:59:45 fabiankeil Exp $ @@ -101,14 +101,11 @@ Hal. You can find the latest version of the Privoxy User Manual at http://www.privoxy.org/user-manual/. + url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/. Please see the Contact section on how to contact the developers. - - - @@ -162,7 +159,7 @@ Hal. Privoxy is available both in convenient pre-compiled packages for a wide range of operating systems, and as raw source code. For most users, we recommend using the packages, which can be downloaded from our - Privoxy Project + Privoxy Project Page. @@ -351,14 +348,14 @@ How to install the binary packages depends on your operating system: The most convenient way to obtain the Privoxy sources is to download the source tarball from our - project download + project download page. If you like to live on the bleeding edge and are not afraid of using possibly unstable development versions, you can check out the up-to-the-minute - version directly from the + version directly from the CVS repository. - + Controlling Privoxy with Your Web Browser Privoxy's user interface can be reached through the special @@ -1424,7 +1439,7 @@ for details.         ▪  Documentation + url="https://www.privoxy.org/&p-version;/user-manual/">Documentation @@ -1855,7 +1870,7 @@ for details. - + Finding the Right Mix Note that some actions, like cookie suppression @@ -1880,7 +1895,7 @@ for details. - + How to Edit The easiest way to edit the actions files is with a browser by @@ -2201,7 +2216,7 @@ for details. -The Path Pattern +The Path Pattern Privoxy uses modern POSIX 1003.2 @@ -2301,18 +2316,18 @@ for details. -The Tag Pattern +The Request 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 + Request tag patterns are used to change the applying actions based on the + request's tags. Tags can be created based on HTTP headers with either + the client-header-tagger or the server-header-tagger action. - Tag patterns have to start with TAG:, so &my-app; - can tell them apart from URL patterns. Everything after the colon + Request tag patterns have to start with TAG:, so &my-app; + can tell them apart from other patterns. Everything after the colon including white space, is interpreted as a regular expression with path pattern syntax, except that tag patterns aren't left-anchored automatically (&my-app; doesn't silently add a ^, @@ -2328,15 +2343,15 @@ for details. - Sections can contain URL and tag patterns at the same time, - but tag patterns are checked after the URL patterns and thus + Sections can contain URL and request tag patterns at the same time, + but request tag patterns are checked after the URL patterns and thus always overrule them, even if they are located before the URL patterns. - Once a new tag is added, Privoxy checks right away if it's matched by one - of the tag patterns and updates the action settings accordingly. As a result - tags can be used to activate other tagger actions, as long as these other + Once a new request tag is added, Privoxy checks right away if it's matched by one + of the request tag patterns and updates the action settings accordingly. As a result + request tags can be used to activate other tagger actions, as long as these other taggers look for headers that haven't already be parsed. @@ -2361,21 +2376,80 @@ for details. -The Negative Tag Patterns +The Negative Request Tag Patterns - To match requests that do not have a certain tag, specify a negative tag pattern + To match requests that do not have a certain request tag, specify a negative tag pattern by prefixing the tag pattern line with either NO-REQUEST-TAG: or NO-RESPONSE-TAG: instead of TAG:. - Negative tag patterns created with NO-REQUEST-TAG: are checked + Negative request tag patterns created with NO-REQUEST-TAG: are checked after all client headers are scanned, the ones created with NO-RESPONSE-TAG: are checked after all server headers are scanned. In both cases all the created tags are considered. + + + +The Client Tag Pattern + + + + + + This is an experimental feature. The syntax is likely to change in future versions. + + + + + Client tag patterns are not set based on HTTP headers but based on + the client's IP address. Users can enable them themselves, but the + Privoxy admin controls which tags are available and what their effect + is. + + + + After a client-specific tag has been defined with the + client-specific-tag, + directive, action sections can be activated based on the tag by using a + CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same priority + as URL patterns, as a result the last matching pattern wins. Tags that + are created based on client or server headers are evaluated later on + and can overrule CLIENT-TAG and URL patterns! + + + The tag is set for all requests that come from clients that requested + it to be set. Note that "clients" are differentiated by IP address, + if the IP address changes the tag has to be requested again. + + + Clients can request tags to be set by using the CGI interface http://config.privoxy.org/client-tags. + + + + Example: + + + + +# If the admin defined the client-specific-tag circumvent-blocks, +# and the request comes from a client that previously requested +# the tag to be set, overrule all previous +block actions that +# are enabled based on URL to CLIENT-TAG patterns. +{-block} +CLIENT-TAG:^circumvent-blocks$ + +# This section is not overruled because it's located after +# the previous one. +{+block{Nobody is supposed to request this.}} +example.org/blocked-example-page + + @@ -2568,7 +2642,16 @@ for details. Example usage: - +add-header{X-User-Tracking: sucks} + # Add a DNT ("Do not track") header to all requests, +# event to those that already have one. +# +# This is just an example, not a recommendation. +# +# There is no reason to believe that user-tracking websites care +# about the DNT header and depending on the User-Agent, adding the +# header may make user-tracking easier. +{+add-header{DNT: 1}} +/ @@ -2778,7 +2861,7 @@ for details. Type: - Parameterized. + Multi-value. @@ -2865,7 +2948,7 @@ for details. Type: - Parameterized. + Multi-value. @@ -3616,7 +3699,7 @@ problem-host.example.com Type: - Parameterized. + Multi-value. @@ -3828,7 +3911,7 @@ problem-host.example.com Type: - Parameterized. + Multi-value. @@ -4145,7 +4228,7 @@ new action Type: - Multi-value. + Parameterized. @@ -4178,6 +4261,32 @@ new action for socks5 connections (with remote DNS resolution). + + + forward-webserver 127.0.0.1:80 to use the HTTP + server listening at 127.0.0.1 port 80 without adjusting the + request headers. + + + This makes it more convenient to use Privoxy to make + existing websites available as onion services as well. + + + Many websites serve content with hardcoded URLs and + can't be easily adjusted to change the domain based + on the one used by the client. + + + Putting Privoxy between Tor and the webserver (or an stunnel + that forwards to the webserver) allows to rewrite headers and + content to make client and server happy at the same time. + + + Using Privoxy for webservers that are only reachable through + onion addresses and whose location is supposed to be secret + is not recommended and should not be necessary anyway. + + @@ -5390,7 +5499,7 @@ new action # Create a short, easy to remember nickname for a favorite site # (relies on the browser to accept and forward invalid URLs to &my-app;) -{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} } +{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} } a # Always use the expanded view for Undeadly.org articles @@ -5460,7 +5569,7 @@ www.privoxy.org/user-manual/ Type: - Parameterized. + Multi-value. @@ -5543,7 +5652,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Type: - Parameterized. + Multi-value. @@ -5814,7 +5923,7 @@ TAG:^image/ - + Summary Note that many of these actions have the potential to cause a page to @@ -5957,7 +6066,7 @@ hal stop here and user.action file and see how all these pieces come together: - + match-all.action Remember all actions are disabled when matching starts, @@ -6000,7 +6109,7 @@ hal stop here - + default.action @@ -6061,7 +6170,7 @@ for-privoxy-version=3.0.11 The first of our specialized sections is concerned with fragile sites, i.e. sites that require minimum interference, because they are either very complex or very keen on tracking you (and have mechanisms in place that - make them unusable for people who avoid being tracked). We will simply use + make them unusable for people who avoid being tracked). We will use our pre-defined fragile alias instead of stating the list of actions explicitly: @@ -6211,7 +6320,7 @@ count*. It's quite remarkable how many advertisers actually call their banner servers ads.company.com, or call the directory - in which the banners are stored simply banners. So the above + in which the banners are stored literally banners. So the above generic patterns are surprisingly effective. @@ -6289,7 +6398,7 @@ wiki. -user.action +user.action So far we are painting with a broad brush by setting general policies, @@ -6667,8 +6776,10 @@ stupid-server.example.com/ The non-standard option letter D (dynamic) allows to use the variables $host, $origin (the IP address the request came from), - $path and $url. They will be replaced with the value they refer to before - the filter is executed. + $path, $url and $listen-address (the address on which Privoxy accepted the + client request. Example: 127.0.0.1:8118). + They will be replaced with the value they refer to before the filter + is executed. @@ -6703,7 +6814,7 @@ stupid-server.example.com/ -Filter File Tutorial +Filter File Tutorial Now, let's complete our foo content filter. We have already defined the heading, but the jobs are still missing. Since all it does is to replace @@ -7425,9 +7536,10 @@ pre-defined filters for your convenience: External filters read the content from STDIN and write the rewritten - content to STDOUT. The environment variables PRIVOXY_URL, PRIVOXY_PATH, - PRIVOXY_HOST, PRIVOXY_ORIGIN can be used to get some details about the - client request. + content to STDOUT. + The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST, + PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details + about the client request. &my-app; will temporary store the content to filter in the @@ -7873,7 +7985,7 @@ Requests - + Privoxy's Internal Pages