From 52c8abca8514f97aca66c8e3f81cf95018ddd737 Mon Sep 17 00:00:00 2001 From: oes Date: Tue, 14 May 2002 15:29:12 +0000 Subject: [PATCH] Completed proofreading the actions chapter --- doc/source/user-manual.sgml | 1423 +++++++++++++++++++++-------------- 1 file changed, 847 insertions(+), 576 deletions(-) diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index f047e9e1..95af6626 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -27,7 +27,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 1.106 2002/05/10 01:48:20 hal9 Exp $ + $Id: user-manual.sgml,v 1.107 2002/05/12 03:20:41 hal9 Exp $ Copyright (C) 2001, 2002 Privoxy Developers See LICENSE. @@ -53,7 +53,7 @@ -$Id: user-manual.sgml,v 1.106 2002/05/10 01:48:20 hal9 Exp $ +$Id: user-manual.sgml,v 1.107 2002/05/12 03:20:41 hal9 Exp $ -<emphasis>+add-header</emphasis> +<emphasis>add-header</emphasis> - Type: - + Typical use: - Multi-value. + Confuse log analysis, custom applications - + - Purpose and typical uses: + Effect: - Send a user defined HTTP header to the web server. Can be used to confuse log analysis. + Sends a user defined HTTP header to the web server. - Possible values: + Type: + - - Any value is possible. Validity of the defined HTTP headers is not checked. - It is recommended that you use the X- prefix - for custom headers. - + Multi-value. - Example usage: + Parameter: - - {+add-header{X-User-Tracking: sucks}} - .example.com + + Any string value is possible. Validity of the defined HTTP headers is not checked. + It is recommended that you use the X- prefix + for custom headers. + - + Notes: @@ -3175,139 +3173,156 @@ forward-socks4 and forward-socks4a + + + Example usage: + + + +add-header{X-User-Tracking: sucks} + + + -<emphasis>+block</emphasis> +<emphasis>block</emphasis> - Type: - + Typical use: - Boolean. + Block ads or other obnoxious content - Purpose and typical uses: + Effect: Requests for URLs to which this action applies are blocked, i.e. the requests are not forwarded to the remote server, but answered locally with a substitute page or image, - as determined by the handle-as-image and - set-image-blocker actions. - It is typically used to block ads or other obnoxious content. + as determined by the handle-as-image + and set-image-blocker actions. - Possible values: + Type: + - N/A + Boolean. - + - Example usage: + Parameter: - - {+block} - .banners.example.com - .ads.r.us - + N/A - + Notes: - If a URL matches one of the blocked patterns, Privoxy - will intercept the URL and display its special BLOCKED page - instead. If there is sufficient space, a large red banner will appear with - a friendly message about why the page was blocked, and a way to go there - anyway. If there is insufficient space a smaller BLOCKED - page will appear without the red banner. - Click here - to view the default blocked HTML page (Privoxy must be running - for this to work as intended!). + 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 minaturized 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. - - A very important exception is if the URL matches both - +block and +handle-as-image, - then it will be handled by - +set-image-blocker - (see below). It is important to understand this process, in order - to understand how Privoxy is able to deal with - ads and other objectionable content. + A very important exception occurs if both + block and handle-as-image, + apply to the same request: it will then be replaced by an image. If + set-image-blocker + (see below) also applies, the type of image will be determined by its parameter, + if not, the standard checkerboard pattern is sent. - The +filter - action can also perform some of the - same functionality as +block, but by virtue of very - different programming techniques, and is most often used for different - reasons. + It is important to understand this process, in order + to understand how Privoxy deals with + ads and other unwanted content. + + The filter + action can perform a very similar task, by blocking + banner images and other content through rewriting the relevant URLs in the + document's HTML source, so they don't get requested in the first place. + Note that this is a totally different technique, and it's easy to confuse the two. + + + + + + Example usage (section): + + + {+block} # Block and replace with "blocked" page +.nasty-stuff.example.com + +{+block +handle-as-image} # Block and replace with image +.ad.doubleclick.net +.ads.r.us + + -<emphasis>+deanimate-gifs</emphasis> +<emphasis>deanimate-gifs</emphasis> - Type: - + Typical use: - Parameterized. + Stop those annoying, distracting animated GIF images. - Typical uses: + Effect: - To stop those annoying, distracting animated GIF images. + De-animate GIF animations, i.e. reduce them to their first or last image. - Possible values: + Type: + - - last or first - + Parameterized. - + - Example usage: + Parameter: - - {+deanimate-gifs{last}} - .example.com - + + last or first + - + Notes: - De-animate all animated GIF images, i.e. reduce them to their last frame. This will also shrink the images considerably (in bytes, not pixels!). If the option first is given, the first frame of the animation is used as the replacement. If last is given, the last @@ -3315,37 +3330,56 @@ forward-socks4 and forward-socks4a most banner animations, but also has the risk of not showing the entire last frame (if it is only a delta to an earlier frame). + + You can safely use this action with patterns that will also match non-GIF + objects, because no attempt will be made at anything that doesn't look like + a GIF. + + + Example usage: + + + +deanimate-gifs{last} + + + -<emphasis>+downgrade-http-version</emphasis> +<emphasis>downgrade-http-version</emphasis> - Type: - + Typical use: - Boolean. + Work around (very rare) problems with HTTP/1.1 - Typical uses: + Effect: - +downgrade-http-version will downgrade HTTP/1.1 client requests to - HTTP/1.0 and downgrade the responses as well. + Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0. - Possible values: + Type: + + + Boolean. + + + + + Parameter: N/A @@ -3353,25 +3387,26 @@ forward-socks4 and forward-socks4a - - Example usage: + + Notes: - - {+downgrade-http-version} - .example.com - + + This is a left-over from the time when Privoxy + didn't support important HTTP/1.1 features well. It is left here for the + unlikely case that you experience HTTP/1.1 related problems with some server + out there. Not all (optional) HTTP/1.1 features are supported yet, so there + is a chance you might need this action. + - Notes: + Example usage (section): - - Use this action for servers that use HTTP/1.1 protocol features that - Privoxy doesn't handle well yet. HTTP/1.1 is - only partially implemented. Default is not to downgrade requests. This is - an infrequently needed action, and is used to help with rare problem sites only. - + + {+downgrade-http-version} +problem-host.example.com + @@ -3380,46 +3415,39 @@ forward-socks4 and forward-socks4a -<emphasis>+fast-redirects</emphasis> +<emphasis>fast-redirects</emphasis> - Type: - + Typical use: - Boolean. + Fool some click-tracking scripts and speed up indirect links - Typical uses: + Effect: - The +fast-redirects action enables interception of - redirect requests from one server to another, which - are used to track users.Privoxy can cut off - all but the last valid URL in a redirect request and send a local redirect - back to your browser without contacting the intermediate site(s). + Cut off all but the last valid URL from requests. - Possible values: + Type: + - - N/A - + Boolean. - + - Example usage: + Parameter: - - {+fast-redirects} - .example.com - + + N/A + @@ -3428,10 +3456,10 @@ forward-socks4 and forward-socks4a Many sites, like yahoo.com, don't just link to other sites. Instead, they - will link to some script on their own server, giving the destination as a + will link to some script on their own servers, giving the destination as a parameter, which will then redirect you to the final target. URLs resulting from this scheme typically look like: - http://some.place/some_script?http://some.where-else. + http://some.place/click-tracker.cgi?target=http://some.where.else. Sometimes, there are even multiple consecutive redirects encoded in the @@ -3442,137 +3470,79 @@ forward-socks4 and forward-socks4a the advertisers. - This is a normally on feature, and often requires exceptions - for sites that are sensitive to defeating this mechanism. + This feature is currently not very smart and is scheduled for improvement. + It is likely to break some sites. There is a bunch of exceptions to this action in + default.action, should you decide to turn it on by default. + + Example usage: + + + {+fast-redirects} + + + + -<emphasis>+filter</emphasis> +<emphasis>filter</emphasis> - Type: - + Typical use: - Parameterized. + Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc. - Typical uses: + Effect: - Apply page filtering as defined by named sections of the - default.filter file to the specified site(s). - Filtering can be any modification of the raw - page content, including re-writing or deletion of content. + Text documents, including HTML and JavaScript, to which this action applies, are filterd on-the-fly + through the specified regular expression based substitutions. - Possible values: + Type: + - - +filter must include the name of one of the section identifiers - from default.filter (or whatever - filterfile is specified in config). - + Parameterized. - + - Example usage (from the current default.filter): + Parameter: - - - - +filter{html-annoyances}: Get rid of particularly annoying HTML abuse. - - - - - - +filter{js-annoyances}: Get rid of particularly annoying JavaScript abuse - - - - - - +filter{content-cookies}: Kill cookies that come in the HTML or JS content - - - - - - +filter{popups}: Kill all popups in JS and HTML - - - - - - +filter{frameset-borders}: Give frames a border and make them resizable - - - - - - +filter{webbugs}: Squish WebBugs (1x1 invisible GIFs used for user tracking) - - - - - - +filter{refresh-tags}: Kill automatic refresh tags (for dial-on-demand setups) - - - - - - +filter{fun}: Text replacements for subversive browsing fun! - - - - - - +filter{nimda}: Remove Nimda (virus) code. - - - - - - +filter{banners-by-size}: Kill banners by size (very efficient!) - - - - - - +filter{shockwave-flash}: Kill embedded Shockwave Flash objects - - - - - - +filter{crude-parental}: Kill all web pages that contain the words "sex" or "warez" - - + + The name of a filter, as defined in the filter file + (typically default.filter, set by the + filterfile + option in the config file) + - + Notes: - This is potentially a very powerful feature! And requires a knowledge - of regular expressions if you want to roll your own. - Filtering operates on a line by line basis throughout the entire page. + For your convenience, there are a bunch of pre-defined filters available + in the distribution filter file that you can use. See the example below for + a list. + + + This is potentially a very powerful feature! But rolling your own + filters requires a knowledge of regular expressions and HTML. Filtering requires buffering the page content, which may appear to @@ -3581,45 +3551,118 @@ forward-socks4 and forward-socks4a since the page is not incrementally displayed.) This effect will be more noticeable on slower connections. + + At this time, Privoxy cannot (yet!) uncompress compressed + documents. If you want filtering to work on all documents, even those that + would normally be sent compressed, use the + prevent-compression + action in conjuction with filter. + Filtering can achieve some of the effects as the - +block - action, i.e. it can be used to block ads and banners. In the overall - scheme of things, filtering is one of the first things Privoxy - does with a web page. So other most other actions are applied to the - already filtered page. + block + action, i.e. it can be used to block ads and banners. + + + Feedback with suggestions for new or improved filters is particularly + welcome! + + Example usage (with filters from the distribution default.filter file): + + + + +filter{html-annoyances} # Get rid of particularly annoying HTML abuse. + + + + +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse + + + + +filter{banners-by-size} # Kill banners by size (very efficient!) + + + + +filter{content-cookies} # Kill cookies that come sneaking in the HTML or JS content + + + + +filter{popups} # Kill all popups in JS and HTML + + + + +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking) + + + + +filter{fun} # Text replacements for subversive browsing fun! + + + + +filter{frameset-borders} # Give frames a border and make them resizable + + + + +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups) + + + + +filter{nimda} # Remove Nimda (virus) code. + + + + +filter{shockwave-flash} # Kill embedded Shockwave Flash objects + + + + +filter{crude-parental} # Kill all web pages that contain the words "sex" or "warez" + + + - -<emphasis>+hide-forwarded-for-headers</emphasis> + +<emphasis>handle-as-image</emphasis> - Type: - + Typical use: - Boolean. + Mark URLs as belonging to images (so they'll be replaced by images if they get blocked) - Typical uses: + Effect: - Block any existing X-Forwarded-for HTTP header, and do not add a new one. + This action alone doesn't do anything noticeable. It just marks URLs as images. + If the block action also applies, + the presence or absence of this mark decides whether an HTML blocked + page, or a replacement image (as determined by the set-image-blocker action) will be sent to the + client as a substitute for the blocked content. - Possible values: + Type: + + + Boolean. + + + + + Parameter: N/A @@ -3628,448 +3671,544 @@ forward-socks4 and forward-socks4a - Example usage: + Notes: - - {+hide-forwarded-for-headers} - .example.com - + + The below generic example section is actually part of default.action. + It marks all URLs with well-known image file name extensions as images and should + be left intact. + + + Users will probably only want to use the handle-as-image action in conjunction with + block, to block sources of banners, whose URLs don't + reflect the file type, like in the second example section. + + + Note that you cannot treat HTML pages as images in most cases. For instance, (inline) ad + frames require an HTML page to be sent, or they won't display properly. + Forcing handle-as-image in this situation will not replace the + ad frame with an image, but lead to error messages. + - Notes: + Example usage (sections): - It is fairly safe to leave this on. It does not seem to break many sites. + # Generic image extensions: +# +{+handle-as-image} +/.*\.(gif|jpg|jpeg|png|bmp|ico)$ + +# 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 + - - -<emphasis>+hide-from-header</emphasis> + +<emphasis>hide-forwarded-for-headers</emphasis> - Type: - + Typical use: - Parameterized. + Improve privacy by hiding the true source of the request - Typical uses: + Effect: - To block the browser from sending your email address in a From: - header. + Deletes any existing X-Forwarded-for: HTTP header from client requests, + and prevents adding a new one. - Possible values: + Type: + + + Boolean. + + + + + Parameter: - Keyword: block, or any user defined value. + N/A - Example usage: + Notes: - - {+hide-from-header{block}} - .example.com - + + 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. + - Notes: + Example usage: - - The keyword block will completely remove the header - (not to be confused with the +block action). - Alternately, you can specify any value you prefer to send to the web - server. + + +hide-forwarded-for-headers - - -<emphasis>+hide-referer</emphasis> - + +<emphasis>hide-from-header</emphasis> + - Type: - + Typical use: - Parameterized. + Keep your (old and ill) browser from telling web servers your email address - Typical uses: + Effect: - Don't send the Referer: (sic) HTTP header to the web site. - Or, alternately send a forged header instead. + Deletes any existing From: HTTP header, or replaces it with the + specified string. - Possible values: + Type: + + + Parameterized. + + + + + Parameter: - Prevent the header from being sent with the keyword, block. - Or, forge a URL to one from the same server as the request. - Or, set to user defined value of your choice. + Keyword: block, or any user defined value. - Example usage: + Notes: - - {+hide-referer{forge}} - .example.com - + + The keyword block will completely remove the header + (not to be confused with the block + action). + + + Alternately, you can specify any value you prefer to be sent to the web + server. If you do, it is a matter of fairness not to use any address that + is actually used by a real person. + + + This action is rarely needed, as modern web browsers don't send + From: headers anymore. + - Notes: + Example usage: - forge is the preferred option here, since some servers will - not send images back otherwise. + +hide-from-header{block} or + +hide-from-header{spam-me-senseless@sittingduck.example.com} - - +hide-referrer is an alternate spelling of - +hide-referer. It has the exact same parameters, and can be freely - mixed with, +hide-referer. (referrer is the - correct English spelling, however the HTTP specification has a bug - it - requires it to be spelled as referer.) - - - -<emphasis>+hide-user-agent</emphasis> - + +<emphasis>hide-referrer</emphasis> + - Type: - + Typical use: - Parameterized. + Conceal which link you followed to get to a particular site - Typical uses: + Effect: - To change the User-Agent: header so web servers can't tell - your browser type. Who's business is it anyway? + Deletes the Referer: (sic) HTTP header from the client request, + or replaces it with a forged one. - Possible values: + Type: + - - Any user defined string. - + Parameterized. - + - Example usage: + Parameter: - - {+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}} - .msn.com - + + + block to delete the header completely. + + + forge to pretend to be coming from the homepage of the server we are talking to. + + + Any other string to set a user defined referrer. + + - + Notes: - Warning! This breaks many web sites that depend on this in order - to determine how the target browser will respond to various - requests. Use with caution. + forge is the preferred option here, since some servers will + not send images back otherwise, in an attempt to prevent their valuable + content from being embedded elsewhere (and hence, without being surrounded + by their banners. + + hide-referer is an alternate spelling of + hide-referrer and the two can be can be freely + substituted with each other. (referrer is the + correct English spelling, however the HTTP specification has a bug - it + requires it to be spelled as referer.) + + + Example usage: + + + +hide-referrer{forge} or + +hide-referrer{http://www.yahoo.com/} + + + + - -<emphasis>+handle-as-image</emphasis> + +<emphasis>hide-user-agent</emphasis> - Type: - + Typical use: - Boolean. + Conceal your type of browser and client operating system - Typical uses: + Effect: - To define what Privoxy should treat - automatically as an image, and is an important ingredient of how - ads are handled. + Replaces the value of the User-Agent: HTTP header + in client requests with the specified value. - Possible values: + Type: + - - N/A - + Parameterized. - + - Example usage: + Parameter: - - {+handle-as-image} - /.*\.(gif|jpg|jpeg|png|bmp|ico) - + + Any user-defined string. + - + Notes: - This only has meaning if the URL (or pattern) also is - +blocked, in which case a user definable image can - be sent rather than a HTML page. This is integral to the whole concept of - ad blocking: the URL must match both a +block rule, - and +handle-as-image. - (See +set-image-blocker - below for control over what will actually be displayed by the browser.) + Warning! This breaks many web sites that depend on this in order + to customize their content for the different browser types by looking + at this header (which, btw, is NOT a smart way to + do that!). - There is little reason to change the default definition for this action. + Using this action in multi-user setups or wherever diffrerent types of + browsers will access the same Privoxy is + not recommended. In single-user, single-browser + setups, you might use it to delete your OS version information from + the headers, because it is an invitation to exploit known bugs for your + OS. - + + This action is scheduled for improvement. + + + + Example usage: + + + +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + + + - -<emphasis>+set-image-blocker</emphasis> + +<emphasis>kill-popups<anchor id="kill-popup"></emphasis> - Type: - + Typical use: - Parameterized. + Eliminate those annoying pop-up windows + + + + + Effect: + + + While loading the document, replace JavaScript code that opens + pop-up windows with (syntactically neutral) dummy code on the fly. + - Typical uses: + Type: + - - Decide what to do with URLs that end up tagged with both - +block - and +handle-as-image, - e.g an advertisement. - + Boolean. - Possible values: + Parameter: - There are four available options: -set-image-blocker will send a HTML - blocked page, usually resulting in a broken - image icon. - +set-image-blocker{blank} will send a - 1x1 transparent GIF image. - +set-image-blocker{pattern} will send a - checkerboard type pattern (the default). And finally, - +set-image-blocker{http://xyz.com} will - send a HTTP temporary redirect to the specified image. This has the - advantage of the icon being being cached by the browser, which will speed - up the display. + N/A - Example usage: + Notes: - - {+set-image-blocker{blank}} - .example.com - + + This action is easily confused with a built-in harwired 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{popups} does. + + + 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 it's filter equivalent. + + + Killing all pop-ups is a dangerous business. Many shops and banks rely on + pop-ups to display forms, shopping carts etc, and killing only the unwanted pop-ups + would require artificial intelligance in Privoxy. + 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. + + + - Notes: + Example usage: - - If you want invisible ads, they need to meet - criteria as matching both images and blocked - actions. And then, image-blocker should be set to - blank for invisibility. Note you cannot treat HTML pages as - images in most cases. For instance, frames require an HTML page to - display. So a frame that is an ad, typically cannot be treated as an image. - Forcing an image in this situation just will not work - reliably. - + +kill-popups - + -<emphasis>+limit-connect</emphasis> +<emphasis>limit-connect</emphasis> - Type: - + Typical use: - Parameterized. + Prevent abuse of Privoxy as a TCP relay - Typical uses: + Effect: - By default, Privoxy only allows HTTP CONNECT - requests to port 443 (the standard, secure HTTPS port). Use - +limit-connect to disable this altogether, or to allow - more ports. + Specifies to which ports HTTP CONNECT requests are allowable. - Possible values: + Type: + - - Any valid port number, or port number range. - + Parameterized. - + - Example usages: + Parameter: - - - - - +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-} # Port less than 3, 7, 20 to 100 and above 500 are OK. - + + 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 proxy. + (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. - - If you want to allow CONNECT for more ports than this, or want to forbid - CONNECT altogether, you can specify a comma separated list of ports and - port ranges (the latter using dashes, with the minimum defaulting to 0 and - max to 65K). - If you don't know what any of this means, there probably is no reason to - change this one. + change this one, since the default is already very restrictive. + + 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 (gaping security hole!) + + + -<emphasis>+prevent-compression</emphasis> +<emphasis>prevent-compression</emphasis> - Type: - + Typical use: - Boolean. + + Ensure that servers send the content uncompressed, so it can be + passed through filters + - Typical uses: + Effect: - Prevent the specified websites from compressing HTTP data. + Adds a header to the request that asks for uncompressed transfer. - Possible values: + Type: + + + Boolean. + + + + + Parameter: N/A @@ -4078,28 +4217,45 @@ forward-socks4 and forward-socks4a - Example usage: + Notes: - - {+prevent-compression} - .example.com - + + More and more websites send their content compressed by default, which + is generally a good idea and saves bandwidth. But for the filter, deanimate-gifs + and kill-popups actions to work, + Privoxy needs access to the uncompressed data. + Unfortunately, Privoxy can't yet(!) uncompress, filter, and + re-compress the content on the fly. So if you want to ensure that all websites, including + those that normally compress, can be filtered, you need to use this action. + + + This will slow down transfers from those websites, though. If you use any of the above-mentioned + actions, you will typically want to use prevent-compression in conjunction + with them. + + + Note that some (rare) ill-configured sites don't handle requests for uncompressed + documents correctly (they send an empty document body). If you use prevent-compression + per default, you'll have to add exceptions for those sites. See the example for how to do that. + - Notes: + Example usage (sections): - Some websites do this, which can be a problem for - Privoxy, since - +filter, - +kill-popups - and +gif-deanimate - will not work on compressed data. This will slow down connections to those - websites, though. Default typically is to turn - prevent-compression on. + # Set default: +# +{+prevent-compression} +/ # Match all sites + +# Make exceptions for ill sites: +# +{-prevent-compression} +www.debianhelp.org +www.pclinuxonline.com @@ -4107,30 +4263,40 @@ forward-socks4 and forward-socks4a + - -<emphasis>+session-cookies-only</emphasis> + +<emphasis>prevent-reading-cookies</emphasis> - Type: - + Typical use: - Boolean. + + Prevent the web server from reading any cookies from your system + - Typical uses: + Effect: - Allow cookies for the current browser session only. + Deletes any Cookie: HTTP headers from client requests. - Possible values: + Type: + + + Boolean. + + + + + Parameter: N/A @@ -4139,30 +4305,27 @@ forward-socks4 and forward-socks4a - Example usage (disabling): + Notes: - - {-session-cookies-only} - .example.com - + + This action is only concerned with outgoing cookies. For + incoming cookies, use + prevent-setting-cookies. + Use both to disable cookies completely. + + + It makes no sense at all to use this action in conjunction + with the session-cookies-only action, + since it would prevent the session cookies from being read. + - Notes: + Example usage: - If websites set cookies, +session-cookies-only will make sure - they are erased when you exit and restart your web browser. This makes - profiling cookies useless, but won't break sites which require cookies so - that you can log in for transactions. This is generally turned on for all - sites, and is the recommended setting. - - - +prevent-*-cookies actions should be turned off as well (see - below), for +session-cookies-only to work. Or, else no cookies - will get through at all. For, persistent cookies that survive - across browser sessions, see below as well. + +prevent-reading-cookies @@ -4172,30 +4335,38 @@ forward-socks4 and forward-socks4a - -<emphasis>+prevent-reading-cookies</emphasis> + +<emphasis>prevent-setting-cookies</emphasis> - Type: - + Typical use: - Boolean. + + Prevent the web server from setting any cookies on your system + - Typical uses: + Effect: - Explicitly prevent the web server from reading any cookies on your - system. + Deletes any Set-Cookie: HTTP headers from server replies. - Possible values: + Type: + + + Boolean. + + + + + Parameter: N/A @@ -4204,61 +4375,68 @@ forward-socks4 and forward-socks4a - Example usage: + Notes: - - {+prevent-reading-cookies} - .example.com - + + This action is only concerned with incoming cookies. For + outgoing cookies, use + prevent-reading-cookies. + Use both to disable cookies completely. + + + It makes no sense at all to use this action in conjunction + with the session-cookies-only action, + since it would prevent the session cookies from being set. + - Notes: + Example usage: - Often used in conjunction with +prevent-setting-cookies to - disable cookies completely. Note that - +session-cookies-only - requires these to both be disabled (or else it never gets any cookies to cache). - - - For persistent cookies to work (i.e. they survive across browser - sessions and reboots), all three cookie settings should be off - for the specified sites. + +prevent-setting-cookies - - -<emphasis>+prevent-setting-cookies</emphasis> + +<emphasis>session-cookies-only</emphasis> - Type: - + Typical use: - Boolean. + + Allow only temporary session cookies (for the current browser session only). + - Typical uses: + Effect: - Explicitly block the web server from storing cookies on your - system. + Deletes the expires field from Set-Cookie: server headers. + Most browsers will not store such cookies permanently and forget them in between sessions. + + Type: + + + Boolean. + + + - Possible values: + Parameter: N/A @@ -4267,52 +4445,82 @@ forward-socks4 and forward-socks4a - Example usage: + Notes: - - {+prevent-setting-cookies} - .example.com - + + This is less strict than prevent-setting-cookies / + prevent-reading-cookies and allows you to browse + websites that insist or rely on setting cookies, without compromising your privacy too badly. + + + Most browsers will not permanently store cookies that have been processed by + session-cookies-only and will forget about them between sessions. + This makes profiling cookies useless, but won't break sites which require cookies so + that you can log in for transactions. This is generally turned on for all + sites, and is the recommended setting. + + + It makes no sense at all to use session-cookies-only + together with prevent-setting-cookies or + prevent-reading-cookies. If you do, cookies + will be plainly killed. + + + Note that it is up to the browser how it handles such cookies without an expires + field. If you use an exotic browser, you might want to try it out to be sure. + + + prevent-keeping-cookies is an alternate name for this action. + - Notes: + Example usage: - Often used in conjunction with +prevent-reading-cookies to - disable cookies completely (see above). + +session-cookies-only - - -<emphasis>+kill-popups<anchor id="kill-popups"></emphasis> + +<emphasis>send-vanilla-wafer</emphasis> + - Type: - + Typical use: - Boolean. + + Feed log analysis scripts with useless data. + - Typical uses: + Effect: - Stop those annoying JavaScript pop-up windows! + 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. - Possible values: + Type: + + + Boolean. + + + + + Parameter: N/A @@ -4321,31 +4529,23 @@ forward-socks4 and forward-socks4a - Example usage: + Notes: - - {+kill-popups} - .example.com - + + 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. + - Notes: + Example usage: - +kill-popups uses a built in filter to disable pop-ups - that use the window.open() function, etc. This is - one of the first actions processed by Privoxy - as it contacts the remote web server. This action is not always 100% reliable, - and is supplemented by +filter{popups}. - - @@ -4354,100 +4554,138 @@ forward-socks4 and forward-socks4a - -<emphasis>+send-vanilla-wafer</emphasis> + +<emphasis>send-wafer</emphasis> - Type: - + Typical use: - Boolean. + + Send custom cookies or feed log analysis scripts with even more useless data. + - Typical uses: + Effect: - Sends a cookie for every site stating that you do not accept any copyright - on cookies sent to you, and asking them not to track you. + Sends a custom, user-defined cookie with each request. - Possible values: + Type: + + + Multi-value. + + + + + Parameter: - N/A + A string of the form name=value. - Example usage: + Notes: - - {+send-vanilla-wafer} - .example.com - + + 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. + - - Notes: + Example usage (section): - This action only applies if you are using a jarfile - for saving cookies. Of course, this is a (relatively) unique header and - could conceivably be used to track you. + {+send-wafer{UsingPrivoxy=true}} +my-internal-testing-server.void - - -<emphasis>+send-wafer</emphasis> + +<emphasis>set-image-blocker</emphasis> - Type: - + Typical use: - Multi-value. + Choose the replacement for blocked images - Typical uses: + Effect: - This allows you to send an arbitrary, user definable cookie. + This action alone doesn't do anything noticeable. If both + block and handle-as-image also + apply, i.e. if the request is to be blocked as an image, + then the parameter of this action decides what will be + sent as a replacement. - Possible values: + Type: + - - User specified cookie name and corresponding value. - + Parameterized. - + - Example usage: - - - {+send-wafer{name=value}} - .example.com - + Parameter: + + + + + pattern to send a built-in checkerboard pattern image. The image is visually + decent, scales very well, and makes it obvious where banners were busted. + + + + + blank to send a built-in transparent image. This makes banners disappear + completely, but makes it hard to detect where Privoxy has blocked + images on a given page and complicates troubleshooting if Privoxy + has blocked innocent images, like navigation icons. + + + + + target-url to + send a redirect to target-url. You can redirect + to any image anywhere, even in your local filesystem (via file:/// URL). + + + A good application of redirects is to use special Privoxy-built-in + URLs, which send the built-in images, as target-url. + This has the same visual effect as specifying blank or pattern in + the first place, but enables your browser to cache the replacement image, instead of requesting + it over and over again. + + + @@ -4455,12 +4693,41 @@ forward-socks4 and forward-socks4a Notes: - This can be specified multiple times in order to add as many cookies as you - like. + The URLs for the built-in images are http://config.privoxy.org/send-banner?type=type, where type is + either blank or pattern. + + + There is a third (advanced) type, called auto. It is NOT to be + used in set-image-blocker, but meant for use from filters. + Auto will select the type of image that would have applied to the referring page, had it been an image. + + Example usage: + + + Built-in pattern: + + + +set-image-blocker{pattern} + + + Redirect to the BSD devil: + + + +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} + + + Redirect to the built-in pattern for better caching: + + + +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern} + + + @@ -5954,6 +6221,10 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + Revision 1.107 2002/05/12 03:20:41 hal9 + Small clarifications for 127.0.0.1 vs localhost for listen-address since this + apparently an important distinction for some OS's. + Revision 1.106 2002/05/10 01:48:20 hal9 This is mostly proposed copyright/licensing additions and changes. Docs are still GPL, but licensing and copyright are more visible. Also, copyright -- 2.39.2