From: hal9 Date: Sat, 27 Apr 2002 05:32:00 +0000 (+0000) Subject: -Add short section to Filter Files to tie in with +filter action. X-Git-Tag: v_3_0_branchpoint~176 X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=commitdiff_plain;h=ed70e742f22c7a2eff07f2509e74080190271796 -Add short section to Filter Files to tie in with +filter action. -Start rewrite of examples in Actions Examples (not finished). --- diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 30b9c8ef..15ac7f60 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.94 2002/04/26 05:24:36 hal9 Exp $ + $Id: user-manual.sgml,v 1.95 2002/04/26 17:23:29 swa 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.94 2002/04/26 05:24:36 hal9 Exp $ +$Id: user-manual.sgml,v 1.95 2002/04/26 17:23:29 swa Exp $ @@ -454,7 +454,6 @@ automatically start Privoxy in the boot process. - # /usr/sbin/privoxy /etc/privoxy/config @@ -978,11 +977,11 @@ automatically start Privoxy in the boot process. +actionsfile + -actionsfile - @@ -1043,7 +1042,8 @@ actionsfile -<anchor id="default.filter">filterfile +filterfile + Specifies: @@ -1793,9 +1793,9 @@ actionsfile +ACLs: permit-access and deny-access -ACLs: permit-access and deny-access @@ -2081,9 +2081,9 @@ ACLs: permit-access and deny-access +forward-socks4 and forward-socks4a -forward-socks4 and forward-socks4a @@ -2458,7 +2458,7 @@ forward-socks4 and forward-socks4a - Anything you want can blocked, including ads, banners, or just some obnoxious + Anything you want can be blocked, including ads, banners, or just some obnoxious URL that you would rather not see is done here. Cookies can be accepted or rejected, or accepted only during the current browser session (i.e. not written to disk), content can be modified, JavaScripts tamed, user-tracking fooled, and much more. @@ -2822,12 +2822,13 @@ forward-socks4 and forward-socks4a Later defined actions always over-ride earlier ones. So exceptions - to any rules you make, should come in the latter part of the file. For - multi-valued actions, the actions are applied in the order they are - specified. Actions files are processed in the order they are defined - in config (the default installation has three - actions files). It also quite possible for any given URL pattern to - match more than one action! + to any rules you make, should come in the latter part of the file (or + in a file that is processed later when using multiple actions files). For + multi-valued actions, the actions are applied in the order they are specified. + Actions files are processed in the order they are defined in + config (the default installation has three actions + files). It also quite possible for any given URL pattern to match more than + one action! @@ -2846,7 +2847,7 @@ forward-socks4 and forward-socks4a -<emphasis>+add-header{Name: value}</emphasis> +<emphasis>+add-header</emphasis> @@ -2950,8 +2951,8 @@ forward-socks4 and forward-socks4a 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. + 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!). @@ -3418,9 +3419,8 @@ forward-socks4 and forward-socks4a -<emphasis><anchor id="hide-referrer">+hide-referer</emphasis> - - +<emphasis>+hide-referer</emphasis> + Type: @@ -4182,12 +4182,215 @@ forward-socks4 and forward-socks4a 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 - typically require exceptions to be listed in the lower sections of - actions file. E.g. 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. + 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. + + + + 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 + user.action with similar examples. + + + + + + + +# Settings -- Don't change! For internal Privoxy use ONLY. +{{settings}} +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. +########################################################################## + +# Some useful aliases. + -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies + +imageblock = +block +handle-as-image + +# Fragile sites should have the minimum changes: + fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ + -prevent-cookies -kill-popups + +# Shops should be allowed to set persistent cookies + shop = -filter -prevent-cookies -session-cookies-only + + +########################################################################## +# Begin default action settings. Anything in this section will match +# all URLs -- UNLESS we have exceptions that 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. +########################################################################## + { \ + -add-header \ + -block \ + -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} \ + +hide-forwarded-for-headers \ + +hide-from-header{block} \ + -hide-referrer \ + -hide-user-agent \ + -handle-as-image \ + +set-image-blocker{pattern} \ + -limit-connect \ + +prevent-compression \ + -session-cookies-only \ + -prevent-reading-cookies \ + -prevent-setting-cookies \ + -kill-popups \ + -send-vanilla-wafer \ + -send-wafer \ + } + / # forward slash will match *all* potential URL patterns. + +########################################################################## +# Default behavior is now set. Time for some exceptions to our +# default actions. +########################################################################## + +# These sites are very complex and require very minimal interference. +# 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} + .quietpc.com + .worldpay.com # for quietpc.com + .jungle.com + .scan.co.uk + + +# 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}} + .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\? + login.yahoo.com + edit.europe.yahoo.com + .google.com + .altavista.com/.*(like|url|link):http + .altavista.com/trans.*urltext=http + .nytimes.com + + +# Define which file types will be treated as images. Important +# for ad blocking. + {+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 +# determined by the setting of +set-image-blocker + {+imageblock} + ar.atwola.com + .ad.doubleclick.net + .a.yimg.com/(?:(?!/i/).)*$ + .a[0-9].yimg.com/(?:(?!/i/).)*$ + bs*.gsanet.com + bs*.einets.com + .qkimg.net + ad.*.doubleclick.net + + +# 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} + 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 + + +# 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} + advogato.org + adsl. + ad[ud]*. + advice. +# Let's just trust all .edu top level domains. + .edu + www.ugu.com/sui/ugu/adv +# We'll need to access to path names containing 'download' + .*downloads. + /downloads/ +# 'adv' is for globalintersec and means advanced, not advertisement + www.globalintersec.com/adv + + +# 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} + .sourceforge.net + + + + + + + + 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 + user.action, which is parsed after all other + actions files. So any settings here, will have the last word. + + Now an example of a few things that one might do with a user.action + file. This is where user preferences are defined. + + + + + + + Some examples: @@ -4513,6 +4716,32 @@ forward-socks4 and forward-socks4a + + + +The +filter Action + + Filters are enabled with the +filter action from within + one of the actions files. +filter requires one parameter, which + 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 + default, unless they are explicity enabled in one of the actions files. + + + + @@ -5471,6 +5700,9 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + 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 + Revision 1.94 2002/04/26 05:24:36 hal9 -Add most of Andreas suggestions to Chain of Events section. -A few other minor corrections and touch up.