X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=a94d1d29988dde207849f9c629c6f11a4e73e9f1;hp=9f7a8a22cc34b713c9b83701ee2cee03cf121c53;hb=f4107f65b676b63a199fe4230e58695757f9f199;hpb=5ffca8e39df2da75bcc3458307c25893a47fdf16 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 9f7a8a22..a94d1d29 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -11,11 +11,11 @@ - - + + - - + + @@ -33,9 +33,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.33 2007/07/27 10:57:35 hal9 Exp $ + $Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 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.33 2007/07/27 10:57:35 hal9 Exp $ +$Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 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,32 +298,24 @@ How to install the binary packages depends on your operating system: -Mac OSX - - Unzip the downloaded file (you can either double-click on the file - from the finder, or from the desktop if you downloaded it there). - Then, double-click on the package installer icon named - Privoxy.pkg - and follow the installation process. - Privoxy will be installed in the folder - /Library/Privoxy. - It will start automatically whenever you start up. To prevent it from - starting automatically, remove or rename the folder - /Library/StartupItems/Privoxy. - +Mac OS X - To start Privoxy by hand, double-click on - StartPrivoxy.command in the - /Library/Privoxy folder. - Or, type this command in the Terminal: + Unzip the downloaded file (you can either double-click on the zip file + icon from the Finder, or from the desktop if you downloaded it there). + Then, double-click on the package installer icon and follow the + installation process. - - /Library/Privoxy/StartPrivoxy.command - + The privoxy service will automatically start after a successful + installation (in addition to every time your computer starts up). To + prevent the privoxy service from automatically starting when your + computer starts up, remove or rename the folder named + /Library/StartupItems/Privoxy. - You will be prompted for the administrator password. + To manually start or stop the privoxy service, use the Privoxy Utility + for Mac OS X. This application controls the privoxy service (e.g. + starting and stopping the service as well as uninstalling the software). @@ -351,8 +343,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 +443,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 +600,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 +775,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 +794,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 +824,9 @@ How to install the binary packages depends on your operating system: + @@ -835,7 +849,7 @@ How to install the binary packages depends on your operating system: Now enjoy surfing with enhanced control, comfort and privacy! - + @@ -875,7 +889,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 +1005,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 +1187,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 +1215,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 +1300,6 @@ How to install the binary packages depends on your operating system: - Windows @@ -1319,7 +1341,35 @@ Example Unix startup command: -Mac OSX +Mac OS X + + After downloading the privoxy software, unzip the downloaded file by + double-clicking on the zip file icon. Then, double-click on the + installer package icon and follow the installation process. + + + The privoxy service will automatically start after a successful + installation. In addition, the privoxy service will automatically + start every time your computer starts up. + + + To prevent the privoxy service from automatically starting when your + computer starts up, remove or rename the folder named + /Library/StartupItems/Privoxy. + + + A simple application named Privoxy Utility has been created which + enables administrators to easily start and stop the privoxy service. + + + In addition, the Privoxy Utility presents a simple way for + administrators to edit the various privoxy config files. A method + to uninstall the software is also available. + + + An administrator username and password must be supplied in order for + the Privoxy Utility to perform any of the tasks. + During installation, Privoxy is configured to start automatically when the system restarts. To start &my-app; manually, @@ -1406,11 +1456,9 @@ must find a better place for this paragraph Another feature where you will probably want to define exceptions for trusted - sites is the popup-killing (through the +kill-popups and - +filter{popups} - actions), because your favorite shopping, banking, or leisure site may need + sites is the popup-killing (through +filter{popups}), + because your favorite shopping, banking, or leisure site may need popups (explained below). @@ -1513,7 +1561,6 @@ must find a better place for this paragraph --pidfile FILE - On startup, write the process ID to FILE. Delete the @@ -1525,7 +1572,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 +1579,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 +1591,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 +1715,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 +1809,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 +1954,7 @@ for details. The default profiles, and their associated actions, as pre-defined in - standard.action are: + standard.action are: Default Configurations @@ -2022,7 +2090,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 +2109,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 +2136,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 +2154,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 @@ -2135,7 +2206,7 @@ for details. - { +handle-as-image +block } + { +handle-as-image +block{Banner ads.} } # Block these as if they were images. Send no block page. banners.example.com media.example.com/.*banners @@ -2166,7 +2237,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 @@ -2257,8 +2328,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. @@ -2267,7 +2341,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.) @@ -2460,16 +2535,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). @@ -2495,13 +2570,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. @@ -2559,7 +2636,7 @@ for details. -name # disable action name - Example: +block + Example: +handle-as-image @@ -2612,14 +2689,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 @@ -2742,14 +2819,14 @@ for details. Type: - Boolean. + Parameterized. Parameter: - N/A + A block reason that should be given to the user. @@ -2758,15 +2835,22 @@ for details. Privoxy sends a special BLOCKED page - for requests to blocked pages. This page contains links to find out why the request - was blocked, and a click-through to the blocked content (the latter only if compiled with the - force feature enabled). The BLOCKED page adapts to the available + for requests to blocked pages. This page contains the block reason given as + parameter, a link to find out why the block action applies, and a click-through + to the blocked content (the latter only if the force feature is available and + enabled). + + A very important exception occurs if both block and handle-as-image, @@ -2795,18 +2879,18 @@ for details. Example usage (section): - {+block} + {+block{No nasty stuff for you.}} # Block and replace with "blocked" page .nasty-stuff.example.com -{+block +handle-as-image} +{+block{Doubleclick banners.} +handle-as-image} # Block and replace with image .ad.doubleclick.net .ads.r.us/banners/ -{+block +handle-as-empty-document} +{+block{Layered ads.} +handle-as-empty-document} # Block and then ignore - adserver.exampleclick.net/.*\.js$ + adserver.example.net/.*\.js$ @@ -2871,6 +2955,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 @@ -2885,8 +2974,9 @@ for details. +# Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} -.exit/ +/ @@ -2960,7 +3050,7 @@ for details. # Tag every request with the User-Agent header -{+client-header-filter{user-agent}} +{+client-header-tagger{user-agent}} / @@ -3235,8 +3325,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} / @@ -3256,7 +3347,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 @@ -3712,7 +3803,7 @@ problem-host.example.com { +fast-redirects{simple-check} } - .example.com + one.example.com { +fast-redirects{check-decoded-url} } another.example.com/testing @@ -3933,7 +4024,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 @@ -4057,7 +4148,7 @@ new action Effect: - Overrules the forward directives in the configuration files. + Overrules the forward directives in the configuration file. @@ -4086,7 +4177,8 @@ 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. + to use a socks4 connection (with local DNS resolution) instead, use forward-socks5 + for socks5 connections (with remote DNS resolution). @@ -4094,7 +4186,8 @@ new action 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. + (with local DNS resolution) instead, use forward-socks5 + for socks5 connections (with remote DNS resolution). @@ -4105,7 +4198,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. @@ -4140,6 +4233,8 @@ 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 \ @@ -4221,7 +4316,7 @@ new action # Block all documents on example.org that end with ".js", # but send an empty document instead of the usual HTML message. -{+block +handle-as-empty-document} +{+block{Blocked JavaScript} +handle-as-empty-document} example.org/.*\.js$ @@ -4308,11 +4403,8 @@ example.org/.*\.js$ # These don't look like images, but they're banners and should be # blocked as images: # -{+block +handle-as-image} -some.nasty-banner-server.com/junk.cgi?output=trash - -# Banner source! Who cares if they also have non-image content? -ad.doubleclick.net +{+block{Nasty banners.} +handle-as-image} +nasty-banner-server.example.com/junk.cgi\?output=trash @@ -4474,6 +4566,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. + @@ -4550,8 +4646,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 @@ -4560,7 +4656,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. @@ -4569,8 +4666,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} / @@ -4584,14 +4681,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. @@ -4599,8 +4693,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. @@ -4626,13 +4719,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. @@ -4758,6 +4845,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. @@ -4791,7 +4881,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. @@ -4830,7 +4920,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 @@ -4870,10 +4960,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). - @@ -4913,14 +4999,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 @@ -4959,12 +5042,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 this exploit. + tries to prevent this exploit if delivered through unencrypted HTTP. - Note that the described exploit is only one of many, - using this action does not mean that you no longer - have to patch the client. + 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. @@ -4980,105 +5064,6 @@ new action - - -kill-popups<anchor id="kill-popup"> - - - - Typical use: - - Eliminate those annoying pop-up windows (deprecated) - - - - - Effect: - - - While loading the document, replace JavaScript code that opens - pop-up windows with (syntactically neutral) dummy code on the fly. - - - - - - Type: - - - Boolean. - - - - - Parameter: - - - N/A - - - - - - Notes: - - - This action is basically a built-in, hardwired special-purpose filter - action, but there are important differences: For kill-popups, - the document need not be buffered, so it can be incrementally rendered while - downloading. But kill-popups doesn't catch as many pop-ups as - filter{all-popups} - does and is not as smart as filter{unsolicited-popups} - is. - - - Think of it as a fast and efficient replacement for a filter that you - can use if you don't want any filtering at all. Note that it doesn't make - sense to combine it with any filter action, - since as soon as one filter applies, - the whole document needs to be buffered anyway, which destroys the advantage of - the kill-popups action over its filter equivalent. - - - Killing all pop-ups unconditionally is problematic. Many shops and banks rely on - pop-ups to display forms, shopping carts etc, and the filter{unsolicited-popups} - does a better job of catching only the unwanted ones. - - - If the only kind of pop-ups that you want to kill are exit consoles (those - really nasty windows that appear when you close an other - one), you might want to use - filter{js-annoyances} - instead. - - - This action is most appropriate for browsers that don't have any controls - for unwanted pop-ups. Not recommended for general usage. - - - - - - - - Example usage: - - +kill-popups - - - - - - limit-connect @@ -5123,26 +5108,21 @@ new action By default, i.e. if no limit-connect action applies, - Privoxy only allows HTTP CONNECT - requests to port 443 (the standard, secure HTTPS port). Use - limit-connect if more fine-grained control is desired - for some or all destinations. + Privoxy allows HTTP CONNECT requests to all + ports. Use limit-connect if fine-grained control + is desired for some or all destinations. The CONNECT methods exists in HTTP to allow access to secure websites (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 the decoded content. Websites can leverage this limitation to circumvent &my-app;'s filters. By specifying an invalid port range you can disable HTTPS entirely. - If you plan to disable SSL by default, consider enabling - treat-forbidden-connects-like-blocks - as well, to be able to quickly create exceptions. @@ -5154,7 +5134,7 @@ new action - +limit-connect{443} # This is the default and need not be specified. + +limit-connect{443} # Port 443 is OK. +limit-connect{80,443} # Ports 80 and 443 are OK. +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK. +limit-connect{-} # All ports are OK @@ -5212,9 +5192,9 @@ new action More and more websites send their content compressed by default, which is generally a good idea and saves bandwidth. But the filter, deanimate-gifs - and kill-popups actions need - access to the uncompressed data. + linkend="filter">filter and + deanimate-gifs + actions need access to the uncompressed data. When compiled with zlib support (available since &my-app; 3.0.7), content that should be @@ -5685,7 +5665,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. @@ -5747,8 +5727,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}} / @@ -5967,81 +5947,6 @@ example.org/instance-that-is-delivered-as-xml-but-is-not - - -treat-forbidden-connects-like-blocks - - - - Typical use: - - Block forbidden connects with an easy to find error message. - - - - - Effect: - - - If this action is enabled, Privoxy no longer - makes a difference between forbidden connects and ordinary blocks. - - - - - - Type: - - - Boolean - - - - - Parameter: - - N/A - - - - - Notes: - - - By default Privoxy answers - forbidden Connect requests - with a short error message inside the headers. If the browser doesn't display - headers (most don't), you just see an empty page. - - - With this action enabled, Privoxy displays - the message that is used for ordinary blocks instead. If you decide - to make an exception for the page in question, you can do so by - following the See why link. - - - For Connect requests the clients tell - Privoxy which host they are interested - in, but not which document they plan to get later. As a result, the - Go there anyway wouldn't work and is therefore suppressed. - - - - - - Example usage: - - - +treat-forbidden-connects-like-blocks - - - - - - - Summary @@ -6116,15 +6021,15 @@ new action # +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies - +block-as-image = +block +handle-as-image + +block-as-image = +block{Blocked image.} +handle-as-image allow-all-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} # These aliases define combinations of actions # that are useful for certain types of sites: # - fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups -prevent-compression + fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -prevent-compression - shop = -crunch-all-cookies -filter{all-popups} -kill-popups + shop = -crunch-all-cookies -filter{all-popups} # Short names for other aliases, for really lazy people ;-) # @@ -6159,7 +6064,7 @@ new action # These shops require pop-ups: # - {-kill-popups -filter{all-popups} -filter{unsolicited-popups}} + {-filter{all-popups} -filter{unsolicited-popups}} .dabs.com .overclockers.co.uk @@ -6230,14 +6135,14 @@ that also explains why and how aliases are used: # +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies - +block-as-image = +block +handle-as-image + +block-as-image = +block{Blocked image.} +handle-as-image mercy-for-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} # These aliases define combinations of actions # that are useful for certain types of sites: # - fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups - shop = -crunch-all-cookies -filter{all-popups} -kill-popups + fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer + shop = -crunch-all-cookies -filter{all-popups} @@ -6260,8 +6165,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. @@ -6273,77 +6177,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. + @@ -6394,8 +6255,7 @@ mail.google.com now. Mozilla users, who can turn on smart handling of unwanted pop-ups in their browsers, can safely choose - -filter{popups} (and - -kill-popups) above + -filter{popups} above and hence don't need this section. Anyway, disabling an already disabled action doesn't hurt, so we'll define our exceptions regardless of what was chosen in the defaults section: @@ -6405,7 +6265,7 @@ mail.google.com # These sites require pop-ups too :( # -{ -kill-popups -filter{popups} } +{ -filter{popups} } .dabs.com .overclockers.co.uk .deutsche-bank-24.de @@ -6508,7 +6368,7 @@ bs*.gsanet.com ########################################################################## # Block these fine banners: ########################################################################## -{ +block } +{ +block{Banner ads.} } # Generic patterns: # @@ -6632,7 +6492,7 @@ wiki. -# My user.action file. <fred@foobar.com> +# My user.action file. <fred@example.com> @@ -6654,14 +6514,14 @@ wiki. +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies allow-all-cookies = -crunch-all-cookies -session-cookies-only - allow-popups = -filter{all-popups} -kill-popups -+block-as-image = +block +handle-as-image + allow-popups = -filter{all-popups} ++block-as-image = +block{Blocked as image.} +handle-as-image -block-as-image = -block # These aliases define combinations of actions that are useful for # certain types of sites: # -fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups +fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer shop = -crunch-all-cookies allow-popups # Allow ads for selected useful free sites: @@ -6725,7 +6585,7 @@ stupid-server.example.com/ seen an ad on your favourite page on example.com that you want to get rid of. You have right-clicked the image, selected copy image location and pasted the URL below while removing the leading http://, into a - { +block } section. Note that { +handle-as-image + { +block{} } section. Note that { +handle-as-image } need not be specified, since all URLs ending in .gif will be tagged as images by the general rules as set in default.action anyway: @@ -6733,9 +6593,9 @@ stupid-server.example.com/ -{ +block } +{ +block{Nasty ads.} } www.example.com/nasty-ads/sponsor\.gif - another.popular.site.net/more/junk/here/ + another.example.net/more/junk/here/ @@ -6781,8 +6641,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: @@ -6878,7 +6738,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. @@ -6886,7 +6746,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. @@ -6896,15 +6756,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 @@ -6913,9 +6772,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. @@ -7710,11 +7574,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. @@ -8154,8 +8024,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:
@@ -8342,13 +8214,6 @@ Requests actions. - - - If the +kill-popups - action applies, and it is an HTML or JavaScript document, the popup-code in the - response is filtered on-the-fly as it is received. - - If any +filter action @@ -8418,7 +8283,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 @@ -8460,71 +8327,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 } @@ -8611,7 +8430,7 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ] + +set-image-blocker {pattern} @@ -8677,21 +8494,21 @@ In file: user.action [ View ] [ Edit ] - { +block } + { +block{Domains starts with "ad"} } ad*. - { +block } + { +block{Domain contains "ad"} } .ad. - { +block +handle-as-image } + { +block{Doubleclick banner server} +handle-as-image } .[a-vx-z]*.doubleclick.net We'll just show the interesting part here - the explicit matches. It is - matched three different times. Two +block sections, - and a +block +handle-as-image, + matched three different times. Two +block{} sections, + and a +block{} +handle-as-image, which is the expanded form of one of our aliases that had been defined as: +block-as-image. (Aliases are defined in @@ -8706,7 +8523,7 @@ In file: user.action [ View ] [ Edit ]ad.doubleclick.net is done here -- as both a +block + linkend="BLOCK">+block{} and an +handle-as-image. The custom alias +block-as-image just @@ -8773,7 +8590,6 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ] @@ -8828,7 +8643,7 @@ In file: user.action [ View ] [ Edit ] - { +block +handle-as-image } + { +block{Path starts with "ads".} +handle-as-image } /ads @@ -8909,8 +8724,8 @@ In file: user.action [ 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. @@ -8944,6 +8759,126 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ]