X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=6172c9e8277b26c6ace189b63f86e8a4637dccac;hp=e02ca272a91f1ba1fa0a2b2f4430b51e80951e60;hb=ee0ab00a07f0abda120329e593e5587640960e57;hpb=2e0abe74efe81295cf9d2394f37cbd37d9b967dc diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index e02ca272..6172c9e8 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.37 2007/08/27 16:09:55 fabiankeil Exp $ + $Id: user-manual.sgml,v 2.80 2008/07/18 16:54:30 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.37 2007/08/27 16:09:55 fabiankeil Exp $ +$Id: user-manual.sgml,v 2.80 2008/07/18 16:54:30 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. @@ -444,171 +436,182 @@ How to install the binary packages depends on your operating system: What's New in this Release - There are many improvements and new features since Privoxy 3.0.6, the last stable release: + There are many improvements and new features since Privoxy 3.0.8, the last stable release: - Header filtering can be 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. + Added SOCKS5 support (with address resolution done by + the SOCKS5 server). Patch provided by Eric M. Hopper. - - - + + For a more detailed list of changes please have a look at the ChangeLog. + + @@ -622,46 +625,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 +800,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 +819,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 +849,9 @@ How to install the binary packages depends on your operating system: + @@ -835,7 +874,7 @@ How to install the binary packages depends on your operating system: Now enjoy surfing with enhanced control, comfort and privacy! - + @@ -875,7 +914,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 +1030,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 +1212,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 +1240,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 +1325,6 @@ How to install the binary packages depends on your operating system: - Windows @@ -1319,21 +1366,34 @@ 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, - double-click on the StartPrivoxy.command icon in the - /Library/Privoxy folder. Or, type this command - in the Terminal: + 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. - - /Library/Privoxy/StartPrivoxy.command - + 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. - You will be prompted for the administrator password. + An administrator username and password must be supplied in order for + the Privoxy Utility to perform any of the tasks. @@ -1406,11 +1466,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). @@ -1638,8 +1696,8 @@ for details.         ▪  Toggle Privoxy on or off -         ▪  Documentation +         ▪  Documentation @@ -1667,6 +1725,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. + + @@ -1898,7 +1964,7 @@ for details. The default profiles, and their associated actions, as pre-defined in - standard.action are: + standard.action are: Default Configurations @@ -2013,7 +2079,7 @@ for details. Image tag reordering no - no + yes yes @@ -2098,12 +2164,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 @@ -2147,7 +2216,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 @@ -2189,9 +2258,9 @@ for details. The pattern matching syntax is different for the domain and path parts of the URL. The domain part uses a simple globbing type matching technique, - while the path part uses a more flexible + while the path part uses more flexible Regular - Expressions (PCRE) based syntax. + Expressions (POSIX 1003.2). @@ -2269,8 +2338,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. @@ -2279,7 +2351,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.) @@ -2366,20 +2439,16 @@ for details. The Path Pattern - Privoxy uses Perl compatible (PCRE) + Privoxy uses modern POSIX 1003.2 Regular - Expression based syntax - (through the PCRE library) for - matching the path portion (after the slash), and is thus more flexible. + Expressions for matching the path portion (after the slash), + and is thus more flexible. There is an Appendix with a brief quick-start into regular - expressions, and full (very technical) documentation on PCRE regex syntax is available on-line - at http://www.pcre.org/man.txt. - You might also find the Perl man page on regular expressions (man perlre) - useful, which is available on-line at http://perldoc.perl.org/perlre.html. + expressions, you also might want to have a look at your operating system's documentation + on regular expressions (try man re_format). @@ -2481,7 +2550,7 @@ for details. can tell them apart from URL patterns. Everything after the colon including white space, is interpreted as a regular expression with path pattern syntax, except that tag patterns aren't left-anchored - automatically (Privoxy doesn't silently add a ^, + automatically (&my-app; doesn't silently add a ^, you have to do it yourself if you need it). @@ -2507,13 +2576,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. @@ -2571,7 +2642,7 @@ for details. -name # disable action name - Example: +block + Example: +handle-as-image @@ -2754,14 +2825,14 @@ for details. Type: - Boolean. + Parameterized. Parameter: - N/A + A block reason that should be given to the user. @@ -2770,14 +2841,10 @@ 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 - screen space -- it displays full-blown if space allows, or miniaturized and text-only - if loaded into a small frame or window. If you are using Privoxy - right now, you can take a look at the - BLOCKED - page. + 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 @@ -2807,18 +2874,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$ @@ -2883,6 +2950,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 @@ -2897,8 +2969,9 @@ for details. +# Hide Tor exit notation in Host and Referer Headers {+client-header-filter{hide-tor-exit-notation}} -.exit/ +/ @@ -2972,8 +3045,27 @@ for details. # Tag every request with the User-Agent header -{+client-header-filter{user-agent}} +{+client-header-tagger{user-agent}} / + +# Tagging itself doesn't change the action +# settings, sections with TAG patterns do: +# +# If it's a download agent, use a different forwarding proxy, +# show the real User-Agent and make sure resume works. +{+forward-override{forward-socks5 10.0.0.2:2222 .} \ + -hide-if-modified-since \ + -overwrite-last-modified \ + -hide-user-agent \ + -filter \ + -deanimate-gifs \ +} +TAG:^User-Agent: NetBSD-ftp/ +TAG:^User-Agent: Novell ZYPP Installer +TAG:^User-Agent: RPM APT-HTTP/ +TAG:^User-Agent: fetch libfetch/ +TAG:^User-Agent: Ubuntu APT-HTTP/ +TAG:^User-Agent: MPlayer/ @@ -3870,23 +3962,23 @@ problem-host.example.com - +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse + +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse. - +filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites) + +filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites). - +filter{html-annoyances} # Get rid of particularly annoying HTML abuse + +filter{html-annoyances} # Get rid of particularly annoying HTML abuse. - +filter{content-cookies} # Kill cookies that come in the HTML or JS content + +filter{content-cookies} # Kill cookies that come in the HTML or JS content. - +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups) + +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups). @@ -3898,43 +3990,43 @@ problem-host.example.com - +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective + +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective. - +filter{banners-by-size} # Kill banners by size + +filter{banners-by-size} # Kill banners by size. - +filter{banners-by-link} # Kill banners by their links to known clicktrackers + +filter{banners-by-link} # Kill banners by their links to known clicktrackers. - +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking) + +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking). - +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap + +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap. - +filter{jumping-windows} # Prevent windows from resizing and moving themselves + +filter{jumping-windows} # Prevent windows from resizing and moving themselves. - +filter{frameset-borders} # Give frames a border and make them resizeable + +filter{frameset-borders} # Give frames a border and make them resizable. - +filter{demoronizer} # Fix MS's non-standard use of standard charsets + +filter{demoronizer} # Fix MS's non-standard use of standard charsets. - +filter{shockwave-flash} # Kill embedded Shockwave Flash objects + +filter{shockwave-flash} # Kill embedded Shockwave Flash objects. - +filter{quicktime-kioskmode} # Make Quicktime movies savable + +filter{quicktime-kioskmode} # Make Quicktime movies saveable. @@ -3942,35 +4034,35 @@ problem-host.example.com - +filter{crude-parental} # Crude parental filtering (demo only) + +filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably. - +filter{ie-exploits} # Disable a known Internet Explorer bug exploits + +filter{ie-exploits} # Disable some known Internet Explorer bug exploits. - +filter{site-specifics} # Custom filters for specific site related problems + +filter{site-specifics} # Cure for site-specific problems. Don't apply generally! + + + + +filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags. - +filter{google} # Removes text ads and other Google specific improvements + +filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement. - +filter{yahoo} # Removes text ads and other Yahoo specific improvements + +filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation. - +filter{msn} # Removes text ads and other MSN specific improvements + +filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation. - +filter{blogspot} # Cleans up Blogspot blogs - - - - +filter{no-ping} # Removes non-standard ping attributes from anchor and area tags + +filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this. @@ -4099,7 +4191,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). @@ -4107,7 +4200,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). @@ -4118,7 +4212,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. @@ -4153,6 +4247,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 \ @@ -4234,7 +4330,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$ @@ -4321,11 +4417,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 @@ -4567,8 +4660,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 @@ -4577,7 +4670,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. @@ -4586,8 +4680,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} / @@ -4605,7 +4699,7 @@ new action Typical use: - Improve privacy by not embedding the source of the request in the HTTP headers. + Improve privacy by not forwarding the source of the request in the HTTP headers. @@ -4613,8 +4707,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. @@ -4640,7 +4733,7 @@ new action Notes: - It is safe to leave this on. + It is safe and recommended to leave this on. @@ -4766,11 +4859,9 @@ new action conditional-block to delete the header completely if the host has changed. - block to delete the header unconditionally. @@ -4804,7 +4895,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. @@ -4843,7 +4934,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 @@ -4883,10 +4974,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). - @@ -4924,16 +5011,14 @@ new action - -inspect-jpegs - + +limit-connect + Typical use: - To protect against the MS buffer over-run in JPEG processing + Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for untrusted sites @@ -4941,7 +5026,7 @@ new action Effect: - Protect against a known exploit + Specifies to which ports HTTP CONNECT requests are allowable. @@ -4950,7 +5035,7 @@ new action Type: - Boolean. + Parameterized. @@ -4958,7 +5043,8 @@ new action Parameter: - N/A + A comma-separated list of ports or port ranges (the latter using dashes, with the minimum + defaulting to 0 and the maximum to 65K). @@ -4967,41 +5053,56 @@ new action Notes: - See Microsoft Security Bulletin MS04-028. JPEG images are one of the most - common image types found across the Internet. The exploit as described can - 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. + By default, i.e. if no limit-connect action applies, + Privoxy allows HTTP CONNECT requests to all + ports. Use limit-connect if fine-grained control + is desired for some or all destinations. - 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. - - + 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 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. + - Example usage: + Example usages: - +inspect-jpegs + + + + + +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 ++limit-connect{,} # No HTTPS/SSL traffic is allowed + - - -kill-popups<anchor id="kill-popup"> + +prevent-compression Typical use: - Eliminate those annoying pop-up windows (deprecated) + + Ensure that servers send the content uncompressed, so it can be + passed through filters. + @@ -5009,8 +5110,7 @@ new action Effect: - While loading the document, replace JavaScript code that opens - pop-up windows with (syntactically neutral) dummy code on the fly. + Removes the Accept-Encoding header which can be used to ask for compressed transfer. @@ -5036,214 +5136,27 @@ new action 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. + More and more websites send their content compressed by default, which + is generally a good idea and saves bandwidth. But the filter and + deanimate-gifs + actions need access to the uncompressed data. - 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. + When compiled with zlib support (available since &my-app; 3.0.7), content that should be + filtered is decompressed on-the-fly and you don't have to worry about this action. + If you are using an older &my-app; version, or one that hasn't been compiled with zlib + support, this action can be used to convince the server to send the content uncompressed. - 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. + Most text-based instances compress very well, the size is seldom decreased by less than 50%, + for markup-heavy instances like news feeds saving more than 90% of the original size isn't + unusual. - 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 - - - - Typical use: - - Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for untrusted sites - - - - - Effect: - - - Specifies to which ports HTTP CONNECT requests are allowable. - - - - - - Type: - - - Parameterized. - - - - - Parameter: - - - A comma-separated list of ports or port ranges (the latter using dashes, with the minimum - defaulting to 0 and the maximum to 65K). - - - - - - Notes: - - - 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. - - - 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. - - - 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. - - - - - - Example usages: - - - - - - +limit-connect{443} # This is the default and need not be specified. -+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 -+limit-connect{,} # No HTTPS/SSL traffic is allowed - - - - - - - - -prevent-compression - - - - Typical use: - - - Ensure that servers send the content uncompressed, so it can be - passed through filters. - - - - - - Effect: - - - Removes the Accept-Encoding header which can be used to ask for compressed transfer. - - - - - - Type: - - - Boolean. - - - - - Parameter: - - - N/A - - - - - - Notes: - - - 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. - - - When compiled with zlib support (available since &my-app; 3.0.7), content that should be - filtered is decompressed on-the-fly and you don't have to worry about this action. - If you are using an older &my-app; version, or one that hasn't been compiled with zlib - support, this action can be used to convince the server to send the content uncompressed. - - - Most text-based instances compress very well, the size is seldom decreased by less than 50%, - for markup-heavy instances like news feeds saving more than 90% of the original size isn't - unusual. - - - Not using compression will therefore slow down the transfer, and you should only - enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all - predefined action settings. + Not using compression will therefore slow down the transfer, and you should only + enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all + predefined action settings. Note that some (rare) ill-configured sites don't handle requests for uncompressed @@ -5446,6 +5359,10 @@ new action and be aware that using your own redirects might make it possible to fingerprint your requests. + + In case of problems with your redirects, or simply to watch + them working, enable debug 128. + @@ -5466,73 +5383,20 @@ new action # (Note the $ at the end of the URL pattern to make sure # the request for the rewritten URL isn't redirected as well) {+redirect{s@$@&mode=expanded@}} -undeadly.org/cgi\?action=article&sid=\d*$ - - - - - - +undeadly.org/cgi\?action=article&sid=\d*$ +# Redirect Google search requests to MSN +{+redirect{s@^http://[^/]*/search\?q=([^&]*).*@http://search.msn.com/results.aspx?q=$1@}} +.google.com/search - - -send-vanilla-wafer +# Redirect MSN search requests to Yahoo +{+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}} +search.msn.com//results\.aspx\?q= - - - Typical use: - - - Feed log analysis scripts with useless data. - - - - - - Effect: - - - Sends a cookie with each request stating that you do not accept any copyright - on cookies sent to you, and asking the site operator not to track you. - - - - - - Type: - - - Boolean. - - - - - Parameter: - - - N/A - - - - - - Notes: - - - The vanilla wafer is a (relatively) unique header and could conceivably be used to track you. - - - This action is rarely used and not enabled in the default configuration. - - - - - - Example usage: - - - +send-vanilla-wafer +# Redirect remote requests for this manual +# to the local version delivered by Privoxy +{+redirect{s@^http://www@http://config@}} +www.privoxy.org/user-manual/ @@ -5541,72 +5405,6 @@ undeadly.org/cgi\?action=article&sid=\d*$ - - -send-wafer - - - - Typical use: - - - Send custom cookies or feed log analysis scripts with even more useless data. - - - - - - Effect: - - - Sends a custom, user-defined cookie with each request. - - - - - - Type: - - - Multi-value. - - - - - Parameter: - - - A string of the form name=value. - - - - - - Notes: - - - Being multi-valued, multiple instances of this action can apply to the same request, - resulting in multiple cookies being sent. - - - This action is rarely used and not enabled in the default configuration. - - - - - Example usage (section): - - - {+send-wafer{UsingPrivoxy=true}} -my-internal-testing-server.void - - - - - - - server-header-filter @@ -5698,7 +5496,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. @@ -5760,8 +5558,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}} / @@ -5980,81 +5778,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 @@ -6129,15 +5852,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 ;-) # @@ -6172,7 +5895,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 @@ -6243,14 +5966,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} @@ -6273,8 +5996,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. @@ -6286,77 +6008,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. + @@ -6407,8 +6086,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: @@ -6418,7 +6096,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 @@ -6521,7 +6199,7 @@ bs*.gsanet.com ########################################################################## # Block these fine banners: ########################################################################## -{ +block } +{ +block{Banner ads.} } # Generic patterns: # @@ -6645,7 +6323,7 @@ wiki. -# My user.action file. <fred@foobar.com> +# My user.action file. <fred@example.com> @@ -6667,14 +6345,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: @@ -6738,7 +6416,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: @@ -6746,9 +6424,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/ @@ -6794,8 +6472,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: @@ -6891,7 +6569,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. @@ -6899,7 +6577,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. @@ -6909,15 +6587,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 @@ -6926,9 +6603,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. @@ -7723,11 +7405,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. @@ -8167,8 +7855,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:
@@ -8355,13 +8045,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 @@ -8431,7 +8114,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 @@ -8613,19 +8298,14 @@ In file: user.action [ View ] [ Edit ] + +set-image-blocker {pattern} @@ -8642,21 +8322,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 @@ -8671,7 +8351,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 @@ -8737,21 +8417,16 @@ In file: user.action [ View ] [ Edit ] @@ -8793,7 +8468,7 @@ In file: user.action [ View ] [ Edit ] - { +block +handle-as-image } + { +block{Path starts with "ads".} +handle-as-image } /ads @@ -8874,8 +8549,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. @@ -8909,12 +8584,158 @@ In file: user.action [ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ][ View ] [ Edit ]