From: hal9 Date: Sat, 27 Apr 2002 21:04:42 +0000 (+0000) Subject: -Rewrite of Actions File example. X-Git-Tag: v_3_0_branchpoint~166 X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=commitdiff_plain;h=2ee4589040849085b6d40584d9bdb755699115fd -Rewrite of Actions File example. -Add section for user-manual directive in config. --- diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 15ac7f60..b73373eb 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -25,7 +25,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 1.95 2002/04/26 17:23:29 swa Exp $ + $Id: user-manual.sgml,v 1.96 2002/04/27 05:32:00 hal9 Exp $ Written by and Copyright (C) 2001 the SourceForge Privoxy team. http://www.privoxy.org/ @@ -46,7 +46,7 @@ Privoxy User Manual -$Id: user-manual.sgml,v 1.95 2002/04/26 17:23:29 swa Exp $ +$Id: user-manual.sgml,v 1.96 2002/04/27 05:32:00 hal9 Exp $ @@ -883,7 +883,7 @@ automatically start Privoxy in the boot process. Privoxy can (and normally does) use a number of - other files for additional configuration and logging. + other files for additional configuration, help and logging. This section of the configuration file tells Privoxy where to find those other files. @@ -1195,7 +1195,6 @@ actionsfile trustfile - Specifies: @@ -1249,6 +1248,55 @@ actionsfile +user-manual + + + Specifies: + + + Location of the Privoxy User Manual. + + + + + Type of value: + + A fully qualified URI + + + + Default value: + + http://www.privoxy.org/user-manual/ + + + + Effect if unset: + + + The default will be used. + + + + + Notes: + + + The User Manual is used for help hints from some of the internal CGI pages. + It is normally packaged with the binary distributions, and would make more + sense to have this pointed at a locally installed copy. + + + A more useful example (Unix): + + +   user-manual  file:///usr/share/doc/privoxy-&p-version;/user-manual/ + + + + + + @@ -3213,61 +3261,73 @@ forward-socks4 and forward-socks4a + +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" @@ -4173,27 +4233,46 @@ forward-socks4 and forward-socks4a + + +Summary + + Note that many of these actions have the potential to cause a page to + misbehave, possibly even not to display at all. There are many ways + a site designer may choose to design his site, and what HTTP header + content, and other criteria, he may depend on. There is no way to have hard + and fast rules for all sites. See the Appendix for a brief example on troubleshooting + actions. + + + + -Actions Examples +Sample Actions Files - Note that the meaning of any of the above examples is reversed by preceding + Remember that the meaning of any of the above references is reversed by preceding the action with a -, in place of the +. Also, that some actions are turned on in the default section of the actions file, and require little to no additional configuration. These are just on. - But, other actions that are turned on the default section do + + + + But, other actions that are turned on in the default section do typically require exceptions to be listed in the latter sections of one of our actions file. For instance, by default no URLs are blocked (i.e. in the default definitions of default.action). We need exceptions to this in order to - enable ad blocking in the lower sections. But we need to be very selective - about what we do block. + enable ad blocking in the lower sections. But we need to + be very selective about what we do block. Thus, the default is off + for blocking. - Below is a liberally commented default.action file to - demonstrate how all the pieces come together. And to show how exceptions to - the default policies can be handled. This is followed by a + Below is a liberally commented sample default.action file + to demonstrate how all the pieces come together. And to show how exceptions + to the default policies can be handled. This is followed by a brief user.action with similar examples. @@ -4201,6 +4280,7 @@ forward-socks4 and forward-socks4a +# Sample default.action file <developers@privoxy.org> # Settings -- Don't change! For internal Privoxy use ONLY. {{settings}} @@ -4209,12 +4289,18 @@ for-privoxy-version=3.0 ########################################################################## # Aliases must be defined *before* they are used. These are -# easier to remember, and combine several actions into one. Once defined -# they can be used just like any built-in action. +# easier to remember, and can combine several actions into one. Once +# defined they can be used just like any built-in action -- but within +# this file only! Aliases do not require a + or - sign. ########################################################################## # Some useful aliases. - -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies +# Alias to turn off cookie handling, ie allow all cookies unmolested. + -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \ + -session-cookies-only + +# Alias to both block and treat as if an image for ad blocking +# purposes. +imageblock = +block +handle-as-image # Fragile sites should have the minimum changes: @@ -4227,11 +4313,12 @@ for-privoxy-version=3.0 ########################################################################## # Begin default action settings. Anything in this section will match -# all URLs -- UNLESS we have exceptions that match defined below this +# all URLs -- UNLESS we have exceptions that also match, defined below this # section. We will show all potential actions here whether they are on # or off. We could omit any disabled action if we wanted, since all # actions are 'off' by default anyway. Shown for completeness only. -# Actions are enabled if preceded by a '+', otherwise they are disabled. +# Actions are enabled if preceded by a '+', otherwise they are disabled +# (unless an alias has been defined without this). ########################################################################## { \ -add-header \ @@ -4239,17 +4326,17 @@ for-privoxy-version=3.0 -deanimate-gifs \ -downgrade-http-version \ +fast-redirects \ - +filter{html-annoyances} \ - +filter{js-annoyances} \ - -filter{content-cookies} \ - -filter{popups} \ - +filter{webbugs} \ - -filter{refresh-tags} \ - -filter{fun} \ - +filter{nimda} \ - +filter{banners-by-size} \ - -filter{shockwave-flash} \ - -filter{crude-prental} \ + +filter{html-annoyances} \ + +filter{js-annoyances} \ + -filter{content-cookies} \ + -filter{popups} \ + +filter{webbugs} \ + -filter{refresh-tags} \ + -filter{fun} \ + +filter{nimda} \ + +filter{banners-by-size} \ + -filter{shockwave-flash} \ + -filter{crude-prental} \ +hide-forwarded-for-headers \ +hide-from-header{block} \ -hide-referrer \ @@ -4268,21 +4355,21 @@ for-privoxy-version=3.0 / # forward slash will match *all* potential URL patterns. ########################################################################## -# Default behavior is now set. Time for some exceptions to our -# default actions. +# Default behavior is now set. Now we will define some exceptions to our +# default action policies. ########################################################################## # These sites are very complex and require very minimal interference. -# We'll disable most actions with our 'fragile' alias. - {fragile} +# We'll disable most actions with our 'fragile' alias: + { fragile } .office.microsoft.com # surprise, surprise! .windowsupdate.microsoft.com # Shopping sites - not as fragile but require some special # handling. We still want to block ads, and we will allow -# persistant cookies via the 'shop' alias. - {shop} +# persistant cookies via the 'shop' alias: + { shop } .quietpc.com .worldpay.com # for quietpc.com .jungle.com @@ -4291,15 +4378,14 @@ for-privoxy-version=3.0 # These sites require pop-ups too :( We'll combine our 'shop' # alias with two other actions into one rule to allow all popups. - {shop -no-popups -filter{popups}} + { shop -kill-popups -filter{popups} } .dabs.com .overclockers.co.uk # The 'Fast-redirects' action breaks some sites. Disable this action -# for these known sensitive sites. - {-fast-redirects} - www.ukc.ac.uk/cgi-bin/wac\.cgi\? +# for these known sensitive sites: + { -fast-redirects } login.yahoo.com edit.europe.yahoo.com .google.com @@ -4310,16 +4396,16 @@ for-privoxy-version=3.0 # Define which file types will be treated as images. Important # for ad blocking. - {+handle-as-image} + { +handle-as-image } /.*\.(gif|jpe?g|png|bmp|ico) # Now lets list some domains that are known ad generators. And -# our alias here will block these as well as force them to be -# treated as images. This combination of actions is important -# for ad blocking. What the browser will show instead is +# our alias that we use here will block these as well as force +# them to be treated as images. This combination of actions is +# important for ad blocking. What the browser will show instead is # determined by the setting of +set-image-blocker - {+imageblock} + { +imageblock } ar.atwola.com .ad.doubleclick.net .a.yimg.com/(?:(?!/i/).)*$ @@ -4332,8 +4418,8 @@ for-privoxy-version=3.0 # These will just simply be blocked. They will generate the BLOCKED # banner page, if matched. Heavy use of wildcards and regular -# expressions in this example. - {+block} +# expressions in this example. Enable block action: + { +block } ad*. .*ads. banner?. @@ -4343,10 +4429,11 @@ for-privoxy-version=3.0 .hitbox.com -# The above block section will catch some sites we DO NOT want -# blocked via the wildcards and regular expressions. Now let's set -# exceptions to the exceptions so the good guys get better treatment. - {-block} +# The above block section will probably inadvertantly catch some +# sites we DO NOT want blocked via the wildcards and regular expressions. +# Now let's set exceptions to the exceptions so the good guys get better +# treatment. Disable block action: + { -block } advogato.org adsl. ad[ud]*. @@ -4364,9 +4451,9 @@ for-privoxy-version=3.0 # Don't filter *anything* from our friends at sourceforge. # Notice we don't have to name the individual filter # identifiers -- we just turn them all off in one fell swoop. - {-filter} +# Disable all filters for this one site: + { -filter } .sourceforge.net - @@ -4376,152 +4463,72 @@ for-privoxy-version=3.0 So far we are painting with a broad brush by setting general policies. The above would be a reasonable starting point for many situations. Now, we want to be more specific and have customized rules that are more suitable - to our personal habits and preferences. These should be placed in + to our personal habits and preferences. These would be for narrowly defined + situations like your ISP or your bank, and should be placed in user.action, which is parsed after all other - actions files. So any settings here, will have the last word. + actions files and should not be clobbered by upgrades. So any settings here, + will have the last word and over-ride any previously defined actions. - Now an example of a few things that one might do with a user.action - file. This is where user preferences are defined. + Now a few examples of some things that one might do with a + user.action file. - - - - - Some examples: - - - - Turn off cookies by default, then allow a few through for specified sites - (showing an excerpt from the default section of an actions - file ONLY): - - - # Excerpt only: - # Allow cookies to and from the server, but - # for this browser session ONLY - { - # other actions normally listed here... - -prevent-setting-cookies \ - -prevent-reading-cookies \ - +session-cookies-only \ - } - / # match all URLs +# Sample user.action file. - # Exceptions to the above, sites that benefit from persistent cookies - # that are saved from one browser session to the next. - { -session-cookies-only } - .javasoft.com - .sun.com - .yahoo.com - .msdn.microsoft.com - .redhat.com - - - - - - - - Now turn off fast redirects, and then we allow two exceptions: - - - - - - - # Turn them off (excerpt only)! - { - # other actions normally listed here... - +fast-redirects - } - / # match all URLs - - # Reverse it for these two sites, which don't work right without it. - {-fast-redirects} - www.ukc.ac.uk/cgi-bin/wac\.cgi\? - login.yahoo.com - - - - - - - Turn on page filtering according to rules in the defined sections - of default.filter, and make one exception for - Sourceforge: - - - - - - - # Run everything through the filter file, using only certain - # specified sections: - { - # other actions normally listed here... - +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}\ - +filter{webbugs} +filter{nimda} +filter{banners-by-size} - } - / #match all URLs - - # Then disable filtering of code from all sourceforge domains! - {-filter} - .sourceforge.net - - - - +# Any aliases you want to use need to be re-defined here. +# Alias to turn off cookie handling, ie allow all cookies unmolested. + -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \ + -session-cookies-only - - Now some URLs that we want blocked (normally generates - the blocked banner). Typically, the block - action is off by default in the upper section of an actions file, then enabled - against certain URLs and patterns in the lower part of the file. Many of these use regular expressions that will expand to match multiple - URLs: +# Fragile sites should have the minimum changes: + fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ + -prevent-cookies -kill-popups - - - - - # Blocklist: - {+block} - ad*. - .*ads. - banner?. - count*. - /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?) - /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/ - .hitbox.com - /.*/(ng)?adclient\.cgi - /.*/(plain|live|rotate)[-_.]?ads?/ - /.*/abanners/ - /autoads/ +# Allow persistent cookies for a few regular sites that we +# trust via our above alias. These will be saved from one browser session +# to the next. We are explicity turning off any and all cookie handling, +# even though the prevent-*-cookie settings were disabled in our above +# default.action anyway. So cookies from these domains will come through +# unmolested. + { -prevent-cookies } + .sun.com + .yahoo.com + .msdn.microsoft.com + .redhat.com + + +# My ISP uses obnoxious self promoting images on many pages. +# Nuke them :) Note that +handle-as-image need not be specified, +# since all URLs ending in .gif will be tagged as images by the +# general rules in default.action anyway. + { +block } + www.my-isp-example.com/logo[0-9].gif + +# Say the site where you do your homebanking needs to open +# popup windows, but you have chosen to kill popups by +# default. This will allow it for your-example-bank.com: +# + { -filter{popups} -kill-popups } + .my-example-bank.com + +# This site is delicate, and requires kid-glove +# treatment. + { fragile } + .forbes.com - - Note that many of these actions have the potential to cause a page to - misbehave, possibly even not to display at all. There are many ways - a site designer may choose to design his site, and what HTTP header - content, and other criteria, he may depend on. There is no way to have hard - and fast rules for all sites. See the Appendix for a brief example on troubleshooting - actions. - - @@ -4541,7 +4548,8 @@ for-privoxy-version=3.0 must be defined before other actions in the actions file! And there can only be one set of aliases defined per file. Each actions file may have its own aliases, but they are - only visible within that file. + only visible within that file. Aliases do not requir a + or + - sign in front, since they are merely expanded. @@ -4623,7 +4631,8 @@ for-privoxy-version=3.0 Any web page can be dynamically modified with the filter file. This modification can be removal, or re-writing, of any web page content, including tags and non-visible content. The default filter file is - default.filter, located in the config directory. + oddly enough default.filter, located in the config + directory. @@ -4727,16 +4736,14 @@ for-privoxy-version=3.0 should match one of the section identifiers in the filter file itself. Example: - - + +filter{html-annoyances} - - + This would activate that particular filter. Similarly, +filter can be turned off for selected sites as: - -filter{html-annoyances}. Remember, all actions are off by + -filter{html-annoyances}. Remember too, all actions are off by default, unless they are explicity enabled in one of the actions files. @@ -4754,14 +4761,18 @@ for-privoxy-version=3.0 Templates When Privoxy displays one of its internal - pages, such as a 404 Not Found error page, it uses the appropriate template. - On Linux, BSD, and Unix, these are located in - /etc/privoxy/templates by default. These may be - customized, if desired. cgi-style.css is - used to control the HTML attributes (fonts, etc). - - - The default Blocked banner page with the bright red top + pages, such as a 404 Not Found error page + (Privoxy must be running for link to work as + intended), it uses the appropriate template. On Linux, BSD, and Unix, these + are located in /etc/privoxy/templates by default. These + may be customized, if desired. cgi-style.css is used to + control the HTML attributes (fonts, etc). + + + The default +Blocked +(Privoxy needs to be running for page to display) + banner page with the bright red top banner, is called just blocked. This may be customized or replaced with something else if desired. @@ -5700,6 +5711,10 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + Revision 1.96 2002/04/27 05:32:00 hal9 + -Add short section to Filter Files to tie in with +filter action. + -Start rewrite of examples in Actions Examples (not finished). + Revision 1.95 2002/04/26 17:23:29 swa bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot