X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=70979575fb88926678af78c778ecfdfc7464049f;hp=468488a3e99af9d3f2e8fcef7d565ff48c064386;hb=d74ec2c8f9726f42df2ce1e45749d74dee43b781;hpb=dcd0697f82133864e459774116055509faad4e89 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 468488a3..70979575 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -11,11 +11,11 @@ - - + + - - + + @@ -32,9 +32,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.12 2006/08/14 08:40:39 fabiankeil Exp $ + $Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $ - Copyright (C) 2001- 2003 Privoxy Developers + Copyright (C) 2001- 2006 Privoxy Developers See LICENSE. ======================================================================== @@ -58,7 +58,7 @@ -$Id: user-manual.sgml,v 2.12 2006/08/14 08:40:39 fabiankeil Exp $ +$Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $ @@ -382,76 +386,157 @@ automatically start Privoxy in the boot process. - -Note to Upgraders + +What's New in this Release - There are very significant changes from earlier - Junkbuster versions to the current - Privoxy. The number, names, syntax, and - purposes of configuration files have substantially changed. - Junkbuster 2.0.x configuration - files will not migrate, Junkbuster 2.9.x - and Privoxy configurations will need to be - ported. The functionalities of the old blockfile, - cookiefile and imagelist - are now combined into the actions - files. - default.action, is the main actions file. Local - exceptions should best be put into user.action. - - - A filter file (typically - default.filter) is new as of Privoxy - 2.9.x, and provides some of the new sophistication (explained - below). config is much the same as before. + There are many new features in Privoxy &p-version; + : + - If upgrading from a 2.0.x version, you will have to use the new config - files, and possibly adapt any personal rules from your older files. - When porting personal rules over from the old blockfile - to the new actions files, please note that even the pattern syntax has - changed. If upgrading from 2.9.x development versions, it is still - recommended to use the new configuration files. + + + + Mulitiple filter files can now be specifed in config. + + + + + + There are a number of new actions: + + + + + + + + content-type-overwrite + + + + + crunch-client-header + + + + + crunch-if-none-match + + + + + crunch-server-header + + + + + fast-redirects + + + + + force-text-mode + + + + + handle-as-empty-document + + + + + hide-accept-language + + + + + hide-content-disposition + + + + + hide-if-modified-since + + + + + hide-referrer + + + + + inspect-jpegs + + + + + overwrite-last-modified + + + + + redirect + + + + + treat-forbidden-connects-like-blocks + + + + + + + + + + + MS-Windows versions can now be installed and + started as a service. + + + + + + In addition, there are various bug fixes and enhancements, including + error pages are no longer cached, better DNS error handling, and logging + improvements. + + + + + + + + + +Note to Upgraders + - A quick list of things to be aware of before upgrading: + A quick list of things to be aware of before upgrading from earlier + versions of Privoxy: - - - The default listening port is now 8118 due to a conflict with another - service (NAS). - - - Some installers may remove earlier versions completely. Save any - important configuration files! + Some installers may remove earlier versions completely, including + configuration files. Save any important configuration files! - - Privoxy is controllable with a web browser - at the special URL: http://config.privoxy.org/ - (Shortcut: http://p.p/). Many - aspects of configuration can be done here, including temporarily disabling - Privoxy. - - - - - The primary configuration files for cookie management, ad and banner - blocking, and many other aspects of Privoxy - configuration are the actions - files. It is strongly recommended to become familiar with the new - actions concept below, before modifying these files. Locally defined rules - should go into user.action. + + What constitutes a default configuration has changed, + and you may want to review which actions are on by + default. This is primarily a matter of emphasis, but some features + you may have been used to, may now be off by default. - + + @@ -463,6 +548,7 @@ automatically start Privoxy in the boot process. + @@ -470,13 +556,6 @@ automatically start Privoxy in the boot process. - - - If upgrading, from versions before 2.9.16, please back up any configuration - files. See the Note to Upgraders Section. - - - Install Privoxy. See the - Now enjoy surfing with enhanced comfort and privacy! + Now enjoy surfing with enhanced control, comfort and privacy! @@ -857,11 +936,32 @@ automatically start Privoxy in the boot process. + + + With Firefox, this can be set under: + + + + + + Tools + |_ + Options + |_ + General + |_ + Connection Settings + |_ + Manual Proxy Configuration + + + With Netscape (and Mozilla), this can be set under: - + + @@ -906,7 +1006,7 @@ automatically start Privoxy in the boot process. - Privoxy is typically started by specifying the + Privoxy itself is typically started by specifying the main configuration file to be used on the command line. If no configuration file is specified on the command line, Privoxy will look for a file named config in the current @@ -1285,7 +1385,8 @@ must find a better place for this paragraph         ▪  Toggle Privoxy on or off -         ▪  Documentation +         ▪  Documentation @@ -1381,12 +1482,17 @@ must find a better place for this paragraph - default.filter (the filter + Filter files (the filter file) can be used to re-write the raw page content, including viewable text as well as embedded HTML and JavaScript, and whatever else lurks on any given web page. The filtering jobs are only pre-defined here; - whether to apply them or not is up to the actions files. Only one filter - file may be defined. + whether to apply them or not is up to the actions files. + default.filter includes various filters made + available for use by the developers. Some are much more intrusive than + others, and all should be used with caution. You may define additional + filter files in config as you can with + actions files. We suggest user.filter for any + locally defined filters or customizations. @@ -1404,7 +1510,7 @@ must find a better place for this paragraph - The actions files and default.filter + The actions files and filter files can use Perl style regular expressions for maximum flexibility. @@ -2229,6 +2335,9 @@ must find a better place for this paragraph + content-type-overwrite @@ -2338,6 +2447,9 @@ www.example.net/*.style + crunch-server-header @@ -2421,7 +2533,9 @@ www.example.net/*.style crunch-if-none-match - + Typical use: @@ -2572,7 +2686,9 @@ www.example.net/*.style crunch-server-header - + Typical use: @@ -2585,7 +2701,7 @@ www.example.net/*.style Effect: - Deletes every header send by the server that contains the string the user supplied as parameter. + Deletes every header sent by the server that contains the string the user supplied as parameter. @@ -3006,17 +3122,23 @@ problem-host.example.com Parameterized. - + Parameter: - The name of a filter, as defined in the filter file - (typically default.filter, set by the + The name of a filter, as defined in the filter file. + Filters can be defined in one or more files as defined by the filterfile - option in the config file). When used in its negative form, - and without parameters, filtering is completely disabled. + option in the config file. + default.filter is the collection of filters + supplied by the developers. Locally defined filters should go + in their own file, such as user.filter. + + When used in its negative form, + and without parameters, filtering is completely disabled. + @@ -3036,7 +3158,7 @@ problem-host.example.com noticeable on slower connections. - This is very powerful feature, but rolling your own + This is very powerful feature, and rolling your own filters requires a knowledge of regular expressions and HTML. @@ -3176,7 +3298,9 @@ problem-host.example.com force-text-mode - + Typical use: @@ -3225,7 +3349,7 @@ problem-host.example.com Think twice before activating this action. Filtering binary data - with regular expressions can cause file damages. + with regular expressions can cause file damage. @@ -3248,7 +3372,9 @@ problem-host.example.com handle-as-empty-document - + Typical use: @@ -3412,7 +3538,9 @@ ad.doubleclick.net hide-accept-language - + Typical use: @@ -3465,7 +3593,7 @@ ad.doubleclick.net Therefore it's a good idea to either only change the Accept-Language: header to languages you understand, - or to languages that aren't widely spread. + or to languages that aren't wide spread. Before setting the Accept-Language: header @@ -3496,7 +3624,9 @@ ad.doubleclick.net hide-content-disposition - + Typical use: @@ -3536,20 +3666,20 @@ ad.doubleclick.net Some servers set the Content-Disposition: HTTP header for - documents they assume you want to safe locally before viewing them. + documents they assume you want to save locally before viewing them. The Content-Disposition: header contains the file name the browser is supposed to use by default. - In most browser that understand this header, it makes it impossible to + In most browsers that understand this header, it makes it impossible to just view the document, without downloading it first, even if it's just a simple text file or an image. Removing the Content-Disposition: header helps - to prevent this annoyance, but some browser additionally check the - Content-Type: header, before they decide if the can - display a document without saving it first. In these cases you have + to prevent this annoyance, but some browsers additionally check the + Content-Type: header, before they decide if they can + display a document without saving it first. In these cases, you have to change this header as well, before the browser stops displaying download menus. @@ -3580,7 +3710,9 @@ ad.doubleclick.net hide-if-modified-since - + Typical use: @@ -3633,7 +3765,7 @@ ad.doubleclick.net 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 to high. + caching problems if the random range is too high. It is a good idea to only use a small negative value and let @@ -3666,7 +3798,9 @@ ad.doubleclick.net hide-forwarded-for-headers - + Typical use: @@ -3987,6 +4121,73 @@ ad.doubleclick.net + + +inspect-jpegs + + + + Typical use: + + To protect against the MS buffer over-run in JPEG processing + + + + + Effect: + + + To protect against a known exploit + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + 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 unwanted intrusion. + + + + + + + Example usage: + + +inspect-jpegs + + + + + + + + kill-popups<anchor id="kill-popup"> @@ -4260,7 +4461,9 @@ www.pclinuxonline.com overwrite-last-modified - + Typical use: @@ -4355,7 +4558,9 @@ www.pclinuxonline.com redirect - + Typical use: @@ -4773,7 +4978,9 @@ my-internal-testing-server.void treat-forbidden-connects-like-blocks - + Typical use: @@ -4978,7 +5185,9 @@ my-internal-testing-server.void in order to function properly. - + Actions Files Tutorial @@ -4999,7 +5208,7 @@ Every config file should start with a short comment stating its purpose: - # Sample default.action file <developers@privoxy.org> + # Sample default.action file <ijbswa-developers@lists.sourceforge.net> @@ -5626,20 +5835,24 @@ ar.atwola.com/ -The Filter File +Filter Files All text substitutions that can be invoked through the - filter action - must first be defined in the filter file, which is typically - called default.filter and which can be - selected through the + filter action which + must first be defined in a filter file, such as + default.filter. Mulitple filter files can be + defined through the filterfile config - option. + option. The filters as supplied by the developers will be found in + default.filter. It is recommended that any locally + defined or modified filters go in a separately defined file such as + user.filter. + - Typical reasons for doing such substitutions are to eliminate + Typical reasons for doing these kinds of substitutions 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 @@ -5691,10 +5904,9 @@ ar.atwola.com/ in a syntax that imitates Perl's s/// operator. If you are familiar with Perl, you will find this to be quite intuitive, and may want to look at the - PCRS man page - for the subtle differences to Perl behaviour. Most notably, the non-standard - option letter U is supported, which turns the default - to ungreedy matching. + PCRS documentation for the subtle differences to Perl behaviour. Most + notably, the non-standard option letter U is supported, + which turns the default to ungreedy matching. @@ -6181,7 +6393,7 @@ pre-defined filters for your convenience: Many Microsoft products that generate HTML use non-standard extensions (read: - violations) of the ISO 8859-1 aka Latin-1 character set. This causes those + violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those HTML documents to display with errors on standard-compliant platforms. @@ -6189,7 +6401,13 @@ pre-defined filters for your convenience: It is not necessary when using MS products, and will cause corruption of all documents that use 8-bit character sets other than Latin-1. It's mostly worthwhile for Europeans on non-MS platforms, if wierd garbage characters - sometimes appear on some pages. + sometimes appear on some pages, or user agents that don't correct for this on + the fly. + @@ -6459,7 +6677,11 @@ Requests expressions in its actions files and filter file, through the PCRE and + + PCRS libraries. @@ -6847,12 +7069,13 @@ Requests url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status - + Privoxy - Why? @@ -6965,8 +7188,8 @@ Requests action applies (and the document type fits the action), the rest of the page is read into memory (up to a configurable limit). Then the filter rules (from default.filter) are processed against the buffered - content. Filters are applied in the order they are specified in the - default.filter file. Animated GIFs, if present, are + content. Filters are applied in the order they are specified in one of the + filter files. Animated GIFs, if present, are reduced to either the first or last frame, depending on the action setting.The entire page, which is now filtered, is then sent by Privoxy back to your browser. @@ -7034,7 +7257,7 @@ Requests how the current configuration will handle it. This will not help with filtering effects (i.e. the +filter action) from - the default.filter file since this is handled very + one of the filter files since this is handled very differently and not so easy to trap! It also will not tell you about any other URLs that may be embedded within the URL you are testing. For instance, images such as ads are expressed as URLs within the raw page source of HTML pages. So @@ -7184,7 +7407,8 @@ In file: user.action [ View ] [ Edit ] Notice the only difference here to the previous listing, is to - fast-redirects and session-cookies-only. + fast-redirects and session-cookies-only, + which are actived specifically for this site in our configuration. @@ -7391,6 +7615,10 @@ In file: user.action [ View ] [ Edit ]