X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=3f88ffb0961355e4b666b11631555ac015fac70a;hp=173f56afa9514e771dddb3bad724f6c48b9bda83;hb=043a1d495ada3ded930834bd238dbdc90bac47ef;hpb=826ee9c69c67ad4913c9bc2cc052f6a077eecbc3 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 173f56af..3f88ffb0 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -11,7 +11,7 @@ - + @@ -33,9 +33,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.32 2007/06/07 12:36:22 fabiankeil Exp $ + $Id: user-manual.sgml,v 2.57 2008/02/03 19:10:14 fabiankeil Exp $ - Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/ + Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/ See LICENSE. ======================================================================== @@ -54,12 +54,12 @@ - Copyright &my-copy; 2001 - 2007 by + Copyright &my-copy; 2001 - 2008 by Privoxy Developers -$Id: user-manual.sgml,v 2.32 2007/06/07 12:36:22 fabiankeil Exp $ +$Id: user-manual.sgml,v 2.57 2008/02/03 19:10:14 fabiankeil Exp $ -Debian +Debian and Ubuntu DEBs can be installed with apt-get install privoxy, and will use /etc/privoxy for the location of @@ -227,7 +227,7 @@ How to install the binary packages depends on your operating system: in the same directory as you installed Privoxy in. - Version 3.0.4 introduced full Windows service + Version 3.0.5 beta introduced full Windows service functionality. On Windows only, the Privoxy program has two new command line arguments to install and uninstall Privoxy as a service. @@ -262,7 +262,7 @@ How to install the binary packages depends on your operating system: -Solaris, NetBSD, HP-UX +Solaris <!--, NetBSD, HP-UX--> Create a new directory, cd to it, then unzip and @@ -298,7 +298,7 @@ How to install the binary packages depends on your operating system: -Mac OSX +Mac OS X Unzip the downloaded file (you can either double-click on the file from the finder, or from the desktop if you downloaded it there). @@ -351,8 +351,8 @@ How to install the binary packages depends on your operating system: The port skeleton and the package can also be downloaded from the File Release - Page, but if you're interested in stable releases only you don't - gain anything by using them. + Page, but there's no reason to use them unless you're interested in the + beta releases which are only available there. @@ -451,163 +451,149 @@ How to install the binary packages depends on your operating system: - Header filtering can be done with dedicated header filters now. As a result + Two new actions server-header-tagger + and client-header-tagger + that can be used to create arbitrary tags + based on client and server headers. + These tags can then subsequently be used + to control the other actions used for the current request, + greatly increasing &my-app;'s flexibility and selectivity. See tag patterns for more information on tags. + + + + + + Header filtering is done with dedicated header filters now. As a result the actions filter-client-headers and filter-server-headers that were introduced with Privoxy 3.0.5 to apply - the content filters to the headers as, well have been removed again. + content filters to the headers have been removed. + See the new actions server-header-filter + and client-header-filter for details. + + + + + There are four new options for the main config file: + + + + + + allow-cgi-request-crunching + which allows requests for Privoxy's internal CGI pages to be + blocked, redirected or (un)trusted like ordinary requests. + + + + + split-large-forms + that will work around a browser bug that caused IE6 and IE7 to + ignore the Submit button on the Privoxy's edit-actions-for-url CGI + page. + + + + + accept-intercepted-requests + which allows to combine Privoxy with any packet filter to create an + intercepting proxy for HTTP/1.1 requests (and for HTTP/1.0 requests + with Host header set). This means clients can be forced to use + &my-app; even if their proxy settings are configured differently. + + + + + templdir + to designate an alternate location for &my-app;'s + locally customized CGI templates so that + these are not overwritten during upgrades. + + + + + + + + A new command line option --pre-chroot-nslookup hostname to + initialize the resolver library before chroot'ing. On some systems this + reduces the number of files that must be copied into the chroot tree. + (Patch provided by Stephen Gildea) - + + For a more detailed list of changes please have a look at the ChangeLog. + @@ -622,46 +608,74 @@ How to install the binary packages depends on your operating system: + + + The recommended way to upgrade &my-app; is to backup your old + configuration files, install the new ones, verify that &my-app; + is working correctly and finally merge back your changes using + diff and maybe patch. + + + There are a number of new features in each &my-app; release and + most of them have to be explicitly enabled in the configuration + files. Old configuration files obviously don't do that and due + to syntax changes using old configuration files with a new + &my-app; isn't always possible anyway. + + - Some installers may remove earlier versions completely, including - configuration files. Save any important configuration files! + Note that some installers remove earlier versions completely, + including configuration files, therefore you should really save + any important configuration files! - On the other hand, other installers may not overwrite any existing configuration - files, thinking you will want to do that. You may want to manually check - your saved files against the newer versions to see if the improvements have - merit, or whether there are new options that you may want to consider. - There are a number of new features, but most won't be available unless - these features are incorporated into your configuration somehow. + On the other hand, other installers don't overwrite existing configuration + files, thinking you will want to do that yourself. - - See the full documentation on - fast-redirects - which has changed syntax, and will require adjustments to local configs, - such as user.action. You must reference the new - syntax: - - - - { +fast-redirects{check-decoded-url} } - .example.com - mybank.com - .google. - + + standard.action now only includes the enabled actions. + Not all actions as before. + + + + + In the default configuration only fatal errors are logged now. + You can change that in the debug section + of the configuration file. You may also want to enable more verbose + logging until you verified that the new &my-app; version is working + as expected. + + - - The jarfile, - cookie logger, is off by default now. + Three other config file settings are now off by default: + enable-remote-toggle, + enable-remote-http-toggle, + and enable-edit-actions. + If you use or want these, you will need to explicitly enable them, and + be aware of the security issues involved. + + + The filter-client-headers and + filter-server-headers actions that were introduced with + Privoxy 3.0.5 to apply content filters to + the headers have been removed and replaced with new actions. + See the What's New section above. + + + + + + - Some installers may not automatically start Privoxy after installation. - +--> + @@ -769,7 +783,8 @@ How to install the binary packages depends on your operating system: by setting the proxy configuration for address of 127.0.0.1 and port 8118. DO NOT activate proxying for FTP or - any protocols besides HTTP and HTTPS (SSL)! It won't work! + any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your + browser from using these protocols. @@ -787,7 +802,10 @@ How to install the binary packages depends on your operating system: A default installation should provide a reasonable starting point for most. There will undoubtedly be occasions where you will want to adjust the configuration, but that can be dealt with as the need arises. Little - to no initial configuration is required in most cases. + to no initial configuration is required in most cases, you may want + to enable the + web-based action editor though. + Be sure to read the warnings first. See the Configuration section for more @@ -814,6 +832,9 @@ How to install the binary packages depends on your operating system: + @@ -835,7 +857,7 @@ How to install the binary packages depends on your operating system: Now enjoy surfing with enhanced control, comfort and privacy! - + @@ -875,7 +897,7 @@ How to install the binary packages depends on your operating system: Secondly, a brief explanation of Privoxy's actions. Actions in this context, are the directives we use to tell Privoxy to perform - some task relating to WWW transactions (i.e. web browsing). We tell + some task relating to HTTP transactions (i.e. web browsing). We tell Privoxy to take some action. Each action has a unique name and function. While there are many potential actions in Privoxy's @@ -991,13 +1013,38 @@ How to install the binary packages depends on your operating system: + + Advanced users will eventually want to explore &my-app; + filters as well. Filters + are very different from blocks. + A block blocks a site, page, or unwanted contented. Filters + are a way of filtering or modifying what is actually on the page. An example + filter usage: a text replacement of no-no for + nasty-word. That is a very simple example. This process can be + used for ad blocking, but it is more in the realm of advanced usage and has + some pitfalls to be wary off. + + The quickest way to adjust any of these settings is with your browser through the special Privoxy editor at http://config.privoxy.org/show-status (shortcut: http://p.p/show-status). This - is an internal page, and does not require Internet access. Select the - appropriate actions file, and click + is an internal page, and does not require Internet access. + + + + Note that as of Privoxy 3.0.7 beta the + action editor is disabled by default. Check the + enable-edit-actions + section in the configuration file to learn why and in which + cases it's safe to enable again. + + + + If you decided to enable the action editor, select the appropriate + actions file, and click Edit. It is best to put personal or local preferences in user.action since this is not meant to be overwritten during upgrades, and will over-ride the settings in @@ -1148,7 +1195,7 @@ How to install the binary packages depends on your operating system: - Tools -> Options -> General -> Connection Settings -> Manual Proxy Configuration + Tools -> Options -> Advanced -> Network ->Connection -> Settings @@ -1176,7 +1223,7 @@ How to install the binary packages depends on your operating system: - For Internet Explorer v.5-6: + For Internet Explorer v.5-7: @@ -1261,23 +1308,6 @@ How to install the binary packages depends on your operating system: - Windows @@ -1319,7 +1349,7 @@ Example Unix startup command: -Mac OSX +Mac OS X During installation, Privoxy is configured to start automatically when the system restarts. To start &my-app; manually, @@ -1415,9 +1445,9 @@ must find a better place for this paragraph - Privoxy is HTTP/1.1 compliant, but not all of - the optional 1.1 features are as yet supported. In the unlikely event that - you experience inexplicable problems with browsers that use HTTP/1.1 per default + Privoxy does not support all of the optional HTTP/1.1 + features yet. In the unlikely event that you experience inexplicable problems + with browsers that use HTTP/1.1 per default (like Mozilla or recent versions of I.E.), you might try to force HTTP/1.0 compatibility. For Mozilla, look under Edit -> Preferences -> Debug -> Networking. @@ -1513,7 +1543,6 @@ must find a better place for this paragraph --pidfile FILE - On startup, write the process ID to FILE. Delete the @@ -1525,7 +1554,6 @@ must find a better place for this paragraph --user USER[.GROUP] - After (optionally) writing the PID file, assume the user ID of @@ -1533,10 +1561,9 @@ must find a better place for this paragraph privileges are not sufficient to do so. Unix only. - + --chroot - Before changing to the user ID given in the --user option, @@ -1546,6 +1573,24 @@ must find a better place for this paragraph Unix only. + + + --pre-chroot-nslookup hostname + + + Specifies a hostname to look up before doing a chroot. On some systems, initializing the + resolver library involves reading config files from /etc and/or loading additional shared + libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces + the number of files that must be copied into the chroot tree. + + + For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that + your local name server (listed in /etc/resolv.conf) can resolve without recursion + (that is, without having to ask any other name servers). The hostname need not exist, + but if it doesn't, an error message (which can be ignored) will be output. + + + configfile @@ -1652,6 +1697,14 @@ for details. your browser. + + Note that several of the features described above are disabled by default + in Privoxy 3.0.7 beta and later. + Check the + configuration file to learn why + and in which cases it's safe to enable them again. + + @@ -1738,12 +1791,9 @@ for details. - The syntax of all configuration files has remained the same throughout the - 3.x series. There have been enhancements, but no changes that would preclude - the use of any configuration file from one version to the next. (There is - one exception: +fast-redirects which - has enhanced syntax and will require updating any local configs from earlier - versions.) + The syntax of the configuration and filter files may change between different + Privoxy versions, unfortunately some enhancements cost backwards compatibility. + @@ -1886,7 +1936,7 @@ for details. The default profiles, and their associated actions, as pre-defined in - standard.action are: + standard.action are: Default Configurations @@ -2022,7 +2072,7 @@ for details. edited from 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.action), followed by any exceptions (typically also in default.action), which are then followed lastly by any @@ -2041,15 +2091,15 @@ for details. from consulting any previous file). And then below that, exceptions to the defined universal policies. You can regard user.action as an appendix to default.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 Privoxy upgrades easier. 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 of actions. @@ -2068,7 +2118,7 @@ for details. will have to make later. If, for example, you want to crunch all cookies per default, you'll have to make exceptions from that rule for sites that you regularly use and that require cookies for actually useful purposes, like maybe - your bank, favorite shop, or newspaper. + your bank, favorite shop, or newspaper. @@ -2086,12 +2136,15 @@ for details. 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 - Cautious, Medium or Advanced. - Warning: the Advanced setting is more aggressive, and - will be more likely to cause problems for some sites. Experienced users only! - + Note: the config file option 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 + Advanced. 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 @@ -2166,7 +2219,7 @@ for details. - Generally, a URL pattern has the form + Generally, an URL pattern has the form <domain>/<path>, where both the <domain> and <path> are optional. (This is why the special / pattern matches all @@ -2204,7 +2257,16 @@ for details. - www.example.com/index.html + www.example.com/index.html$ + + + matches all the documents on www.example.com + whose name starts with /index.html. + + + + + www.example.com/index.html$ matches only the single document /index.html @@ -2213,7 +2275,7 @@ for details. - /index.html + /index.html$ matches the document /index.html, regardless of the domain, @@ -2225,7 +2287,7 @@ for details. 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. So its a mistake. @@ -2248,8 +2310,11 @@ for details. .example.com - matches any domain that ENDS in - .example.com + matches any domain with first-level domain com + 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. @@ -2258,7 +2323,8 @@ for details. matches any domain that STARTS with - www. + www. (It also matches the domain + www but most of the time that doesn't matter.) @@ -2387,7 +2453,7 @@ for details. - .example.com/.*/index.html + .example.com/.*/index.html$ Will match any page in the domain of example.com that is @@ -2402,7 +2468,7 @@ for details. - .example.com/(.*/)?index\.html + .example.com/(.*/)?index\.html$ This regular expression is conditional so it will match any page @@ -2451,16 +2517,16 @@ for details. 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. + 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 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 ^, + path pattern syntax, except that tag patterns aren't left-anchored + automatically (&my-app; doesn't silently add a ^, you have to do it yourself if you need it). @@ -2469,6 +2535,7 @@ for details. your pattern line should be TAG:^foo$, TAG:foo would work as well, but it would also match requests whose tags contain foo somewhere. + TAG: foo wouldn't work as it requires white space. @@ -2485,13 +2552,15 @@ for details. - 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. + the cookie tag is created, the request line has already been parsed. @@ -2570,7 +2639,7 @@ for details. the last match wins, i.e. the params from earlier matches are simply ignored. - Example: +hide-user-agent{ Mozilla 1.0 } + Example: +hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4} @@ -2602,14 +2671,14 @@ for details. If nothing is specified in any actions file, no actions are taken. So in this case Privoxy would just be a - normal, non-blocking, non-anonymizing proxy. You must specifically enable the + normal, non-blocking, non-filtering proxy. You must specifically enable the privacy and blocking features you need (although the provided default actions files will give a good starting point). - 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 user.action). For multi-valued actions, the actions are applied in the order they are specified. Actions files are processed in @@ -2861,6 +2930,11 @@ for details. Client-header filters are executed after the other header actions have finished and use their output as input. + + If the request URL gets changed, &my-app; 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 chapter to learn which client-header filters are available by default, and how to @@ -2875,8 +2949,9 @@ for details. +# Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} -.exit/ +/ @@ -2950,7 +3025,7 @@ for details. # Tag every request with the User-Agent header -{+client-header-filter{user-agent}} +{+client-header-tagger{user-agent}} / @@ -2963,9 +3038,6 @@ for details. - content-type-overwrite @@ -3208,12 +3280,12 @@ new action It is also useful to make sure the header isn't used as a cookie - replacement. + replacement (unlikely but possible). Blocking the If-None-Match: header shouldn't cause any caching problems, as long as 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 @@ -3228,8 +3300,9 @@ new action Example usage (section): - # 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} / @@ -3249,7 +3322,7 @@ new action Typical use: - Prevent the web server from setting any cookies on your system + Prevent the web server from setting HTTP cookies on your system @@ -3284,10 +3357,10 @@ new action Notes: - This action is only concerned with incoming cookies. For - outgoing cookies, use + This action is only concerned with incoming HTTP cookies. For + outgoing HTTP cookies, use crunch-outgoing-cookies. - Use both to disable cookies completely. + Use both to disable HTTP cookies completely. It makes no sense at all to use this action in conjunction @@ -3400,7 +3473,7 @@ new action Typical use: - Prevent the web server from reading any cookies from your system + Prevent the web server from reading any HTTP cookies from your system @@ -3435,10 +3508,10 @@ new action Notes: - This action is only concerned with outgoing cookies. For - incoming cookies, use + This action is only concerned with outgoing HTTP cookies. For + incoming HTTP cookies, use crunch-incoming-cookies. - Use both to disable cookies completely. + Use both to disable HTTP cookies completely. It makes no sense at all to use this action in conjunction @@ -3574,8 +3647,8 @@ new action This is a left-over from the time when Privoxy didn't support important HTTP/1.1 features well. It is left here for the unlikely case that you experience HTTP/1.1 related problems with some server - out there. Not all (optional) HTTP/1.1 features are supported yet, so there - is a chance you might need this action. + out there. Not all HTTP/1.1 features and requirements are supported yet, + so there is a chance you might need this action. @@ -3705,7 +3778,7 @@ problem-host.example.com { +fast-redirects{simple-check} } - .example.com + one.example.com { +fast-redirects{check-decoded-url} } another.example.com/testing @@ -3926,7 +3999,7 @@ problem-host.example.com - +filter{ie-exploits} # Disable some known Internet Explorer bug exploits + +filter{ie-exploits} # Disable a known Internet Explorer bug exploits @@ -4050,7 +4123,7 @@ new action Effect: - Overrules the forward directives in the configuration files. + Overrules the forward directives in the configuration file. @@ -4077,17 +4150,19 @@ new action - forward-socks4a 127.0.0.1:9050 . to use the socks4a proxy listening at 127.0.0.1 port 9050. - Replace forward-socks4a with forward-socks4 to use a socks4 connection (with local DNS - resolution) instead. + forward-socks4a 127.0.0.1:9050 . to use the socks4a proxy listening at + 127.0.0.1 port 9050. Replace forward-socks4a with forward-socks4 + to use a socks4 connection (with local DNS resolution) instead, use forward-socks5 + for socks5 connections (with remote DNS resolution). forward-socks4a 127.0.0.1:9050 proxy.example.org:8000 to use the socks4a proxy listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000. - Replace forward-socks4a with forward-socks4 to use a socks4 connection (with local DNS - resolution) instead. + Replace forward-socks4a with forward-socks4 to use a socks4 connection + (with local DNS resolution) instead, use forward-socks5 + for socks5 connections (with remote DNS resolution). @@ -4098,7 +4173,7 @@ new action Notes: - This action takes parameters similar to the + This action takes parameters similar to the forward directives in the configuration file, but without the URL pattern. It can be used as replacement, but normally it's only used in cases where matching based on the request URL isn't sufficient. @@ -4133,11 +4208,13 @@ new action # This way you can continue to use Tor for your normal browsing, # without overloading the Tor network with your FreeBSD ports updates # or downloads of bigger files like ISOs. +# Note that HTTP headers are easy to fake and therefore their +# values are as (un)trustworthy as your clients and users. {+forward-override{forward .} \ -hide-if-modified-since \ -overwrite-last-modified \ } -TAG:^User-Agent: fetch libfetch/2.0$ +TAG:^User-Agent: fetch libfetch/2\.0$ @@ -4302,7 +4379,7 @@ example.org/.*\.js$ # blocked as images: # {+block +handle-as-image} -some.nasty-banner-server.com/junk.cgi?output=trash +some.nasty-banner-server.com/junk.cgi\?output=trash # Banner source! Who cares if they also have non-image content? ad.doubleclick.net @@ -4467,6 +4544,10 @@ new action to another one, but in most cases it isn't worth the time to set it up. + + This action will probably be removed in the future, + use server-header filters instead. + @@ -4543,8 +4624,8 @@ new action Randomizing the value of the If-Modified-Since: makes - sure it isn't used as a cookie replacement, but you will run into - caching problems if the random range is too high. + it less likely that the server can use the time as a cookie replacement, + but you will run into caching problems if the random range is too high. It is a good idea to only use a small negative value and let @@ -4553,7 +4634,8 @@ new action It is also recommended to use this action together with - crunch-if-none-match. + crunch-if-none-match, + otherwise it's more or less pointless. @@ -4562,8 +4644,8 @@ new action Example usage (section): - # 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} / @@ -4577,14 +4659,11 @@ new action hide-forwarded-for-headers - Typical use: - Improve privacy by hiding the true source of the request + Improve privacy by not forwarding the source of the request in the HTTP headers. @@ -4592,8 +4671,7 @@ new action Effect: - Deletes any existing X-Forwarded-for: HTTP header from client requests, - and prevents adding a new one. + Deletes any existing X-Forwarded-for: HTTP header from client requests. @@ -4619,13 +4697,7 @@ new action Notes: - 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. @@ -4751,6 +4823,9 @@ new action conditional-block to delete the header completely if the host has changed. + + conditional-forge to forge the header if the host has changed. + block to delete the header unconditionally. @@ -4784,7 +4859,7 @@ new action 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. @@ -4823,7 +4898,7 @@ new action Typical use: - Conceal your type of browser and client operating system + Try to conceal your type of browser and client operating system @@ -4863,10 +4938,6 @@ new action order to customize their content for different browsers (which, by the way, is NOT the right thing to do: good web sites work browser-independently). - @@ -4906,14 +4977,11 @@ new action inspect-jpegs - Typical use: - To protect against the MS buffer over-run in JPEG processing + Try to protect against a MS buffer over-run in JPEG processing @@ -4952,7 +5020,13 @@ new action allow execution of code on the target system, giving an attacker access to the system in question by merely planting an altered JPEG image, which would have no obvious indications of what lurks inside. This action - prevents unwanted intrusion. + tries to prevent this exploit if delivered through unencrypted HTTP. + + + Note 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. @@ -5047,13 +5121,9 @@ new action This action is most appropriate for browsers that don't have any controls for unwanted pop-ups. Not recommended for general usage. - - @@ -5121,8 +5191,7 @@ new action (https:// URLs) through proxies. It works very simply: the proxy connects to the server on the specified port, and then short-circuits its connections to the client and to the remote server. - This can be a big security hole, since CONNECT-enabled proxies can be - abused as TCP relays very easily. + This means CONNECT-enabled proxies can be used as TCP relays very easily. Privoxy relays HTTPS traffic without seeing @@ -5673,7 +5742,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not Typical use: - Disable or disable filters based on the Content-Type header. + Enable or disable filters based on the Content-Type header. @@ -5735,8 +5804,8 @@ example.org/instance-that-is-delivered-as-xml-but-is-not -# 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}} / @@ -6248,8 +6317,7 @@ that also explains why and how aliases are used: 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 + + no need to disable any actions here. (Remember: a + preceding the action name enables the action, a - disables!). Also note how this long line has been made more readable by splitting it into multiple lines with line continuation. @@ -6261,77 +6329,34 @@ that also explains why and how aliases are used: # "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-headers \ +hide-from-header{block} \ +hide-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} \ +session-cookies-only \ +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 default behavior is now set. + @@ -6620,7 +6645,7 @@ wiki. -# My user.action file. <fred@foobar.com> +# My user.action file. <fred@example.com> @@ -6723,7 +6748,7 @@ stupid-server.example.com/ { +block } www.example.com/nasty-ads/sponsor\.gif - another.popular.site.net/more/junk/here/ + another.example.net/more/junk/here/ @@ -6769,8 +6794,8 @@ stupid-server.example.com/ You like the fun text replacements in 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: @@ -6866,7 +6891,7 @@ stupid-server.example.com/ client-header-filter to rewrite headers that are send by the client, and server-header-filter - to rewrite headers that are send by the server, and + to rewrite headers that are send by the server. @@ -6874,7 +6899,7 @@ stupid-server.example.com/ client-header-tagger and server-header-tagger. - Taggers and filters use the same syntax in the filter files, the differnce + Taggers and filters use the same syntax in the filter files, the difference is that taggers don't modify the text they are filtering, but use a rewritten version of the filtered text as tag. The tags can then be used to change the applying actions through sections with tag-patterns. @@ -6884,15 +6909,14 @@ stupid-server.example.com/ Multiple filter files can be defined through the filterfile config directive. The filters - as supplied by the developers will be found in + as supplied by the developers are located in default.filter. It is recommended that any locally defined or modified filters go in a separately defined file such as user.filter. - - + - Command tasks for content filters are to eliminate common annoyances in + Common tasks for content filters are to eliminate common annoyances in HTML and JavaScript, such as pop-up windows, exit consoles, crippled windows without navigation tools, the infamous <BLINK> tag etc, to suppress images with certain @@ -6901,9 +6925,14 @@ stupid-server.example.com/ - Content filtering works on any text-based document type, including - HTML, JavaScript, CSS etc. (all text/* - MIME types, except text/plain). + Enabled content filters are applied to any content whose + Content Type header is recognised as a sign + of text-based content, with the exception of text/plain. + Use the force-text-mode action + to also filter other content. + + + Substitutions are made at the source level, so if you want to roll your own filters, you should first be familiar with HTML syntax, and, of course, regular expressions. @@ -7698,11 +7727,17 @@ pre-defined filters for your convenience: The templates are basically normal HTML files, but with place-holders (called symbols - or exports), which Privoxy fills at run time. You can - edit the templates with a normal text editor, should you want to customize them. - (Not recommended for the casual user). Note that - just like in configuration files, lines starting with # are - ignored when the templates are filled in. + or exports), which Privoxy fills at run time. It + is possible to edit the templates with a normal text editor, should you want + to customize them. (Not recommended for the casual + user). Should you create your own custom templates, you should use + the config setting templdir + to specify an alternate location, so your templates do not get overwritten + during upgrades. + + + Note that just like in configuration files, lines starting + with # are ignored when the templates are filled in. @@ -8142,8 +8177,10 @@ Requests - Toggle Privoxy on or off. In this case, Privoxy continues - to run, but only as a pass-through proxy, with no actions taking place: + Toggle Privoxy on or off. This feature can be turned off/on in the main + config file. When toggled off, Privoxy + continues to run, but only as a pass-through proxy, with no actions taking + place:
@@ -8406,7 +8443,9 @@ Requests or not, is to disable it temporarily. This should be the first troubleshooting step. See the Bookmarklets section on a quick and easy way to do this (be sure to flush caches afterward!). Looking at the - logs is a good idea too. + logs is a good idea too. (Note that both the toggle feature and logging are + enabled via config file settings, and may need to be + turned on.) Another easy troubleshooting step to try is if you have done any @@ -8448,71 +8487,23 @@ Requests - Matches for http://google.com: + Matches for http://www.google.com: In file: default.action [ View ] [ Edit ] - {-add-header - -block - -client-header-filter{hide-tor-exit-notation} - -content-type-overwrite - -crunch-client-header - -crunch-if-none-match - -crunch-incoming-cookies - -crunch-outgoing-cookies - -crunch-server-header - +deanimate-gifs {last} - -downgrade-http-version + {+deanimate-gifs {last} +fast-redirects {check-decoded-url} - -filter {js-events} - -filter {content-cookies} - -filter {all-popups} - -filter {banners-by-link} - -filter {tiny-textforms} - -filter {frameset-borders} - -filter {demoronizer} - -filter {shockwave-flash} - -filter {quicktime-kioskmode} - -filter {fun} - -filter {crude-parental} - -filter {site-specifics} - -filter {js-annoyances} - -filter {html-annoyances} +filter {refresh-tags} - -filter {unsolicited-popups} +filter {img-reorder} +filter {banners-by-size} +filter {webbugs} +filter {jumping-windows} +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-forwarded-for-headers +hide-from-header {block} - -hide-if-modified-since +hide-referrer {forge} - -hide-user-agent - -inspect-jpegs - -kill-popups - -limit-connect - -overwrite-last-modified - +prevent-compression - -redirect - -send-vanilla-wafer - -send-wafer - -server-header-filter{xml-to-html} - -server-header-filter{html-to-xml} +session-cookies-only +set-image-blocker {pattern} - -treat-forbidden-connects-like-blocks } / { -session-cookies-only } @@ -8599,7 +8590,7 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ] Remember to flush caches! Note that the mail.google reference lacks the TLD portion (e.g. - .com. This will effectively match any TLD with - google in it, such as mail.google.de, + .com). This will effectively match any TLD with + google in it, such as mail.google.de., just as an example. @@ -8932,6 +8923,101 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ]