From: oes Date: Wed, 15 May 2002 21:07:25 +0000 (+0000) Subject: Extended and further commented the example actions files X-Git-Tag: v_3_0_branchpoint~63 X-Git-Url: http://www.privoxy.org/gitweb/@default-cgi@/faq/%22https:/@default-cgi@show-url-info?a=commitdiff_plain;h=82ea2d1f61521d5749b2f15bbf8dcd30e3e50660;p=privoxy.git Extended and further commented the example actions files --- diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 87f06d19..465a82e5 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -26,8 +26,8 @@ Purpose : user manual This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - - $Id: user-manual.sgml,v 1.111 2002/05/14 23:01:36 oes Exp $ + + $Id: user-manual.sgml,v 1.112 2002/05/15 03:57:14 hal9 Exp $ Copyright (C) 2001, 2002 Privoxy Developers See LICENSE. @@ -53,7 +53,7 @@ -$Id: user-manual.sgml,v 1.111 2002/05/14 23:01:36 oes Exp $ +$Id: user-manual.sgml,v 1.112 2002/05/15 03:57:14 hal9 Exp $ + - Now a few examples of some things that one might do with a - user.action file. + +# My user.action file. <fred@foobar.com> - + + As aliases are local to the actions + file that they are defined in, you can't use the ones from + default.action, unless you repeat them here: + - - - -# Sample user.action file. - -# Any aliases you want to use need to be re-defined here. -# Alias to turn off cookie handling, ie allow all cookies unmolested. - -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \ - -session-cookies-only - -# Fragile sites should have the minimum changes: - fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ - -crunch-all-cookies -kill-popups - -# 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 explicitly turning off any and all cookie handling, -# even though the crunch-*-cookies settings were disabled in our above -# default.action anyway. So cookies from these domains will come through -# unmolested. - { -crunch-all-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 home banking needs to open -# popup windows, but you have chosen to kill popups by -# default. This will allow it for your-example-bank.com: + +# (Re-)define aliases for this file: # - { -filter{popups} -kill-popups } - .my-example-bank.com +{{alias}} +-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies +mercy-for-cookies = -crunch-all-cookies -session-cookies-only +fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups +shop = mercy-for-cookies -filter{popups} -kill-popups + + + Say you have accounts on some sites that you visit regularly, and + you don't want to have to log in manually each time. So you'd like + to allow persistent cookies for these sites. The + mercy-for-cookies alias defined above does exactly + that, i.e. it disables crunching of cookies in any direction, and + processing of cookies to make them temporary. + -# This site is delicate, and requires kid-glove -# treatment. - { fragile } - .forbes.com - - - + + +{ mercy-for-cookies } +sunsolve.sun.com +slashdot.org +.yahoo.com +.msdn.microsoft.com +.redhat.com - - + + Your bank needs popups and is allergic to some filter, but you don't + know which, so you disable them all: + + + +{ -filter -kill-popups } +.your-home-banking-site.com + + + While browsing the web with Privoxy you + noticed some ads that sneaked through, but you were too lazy to + report them through our fine and easy feedback + system, so you have added them here: + - + + +{ +block } +www.a-popular-site.com/some/unobvious/path +another.popular.site.net/more/junk/here/ + + + + Note that, assuming the banners in the above example have regular image + extensions (most do), + +handle-as-image + need not be specified, since all URLs ending in these extensions will + already have been tagged as images in the relevant section of + default.action by now. + + + + Then you noticed that the default configuration breaks Forbes Magazine, + but you were too lazy to find out which action is the culprit, and you + were again too lazy to give feedback, so + you just used the fragile alias on the site, and + -- whoa! -- it worked: + + + + +{ fragile } +.forbes.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, + update-safe config, once and for all: + + + + +{ +filter{fun} } +/ # For ALL sites! + + + + Note that the above is not really a good idea: There are exceptions + to the filters in default.action for things that + really shouldn't be filtered, like code on CVS->Web interfaces. Since + user.action has the last word, these exceptions + won't be valid for the fun filtering specified here. + But you're the boss. + + + + + + @@ -5280,8 +5520,8 @@ fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ The <emphasis>+filter</emphasis> Action - Filters are enabled with the +filter action from within + 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: @@ -5852,14 +6092,14 @@ Requests Next, Privoxy checks to see if the URL - matches any +block patterns. If + matches any +block patterns. If so, the URL is then blocked, and the remote web server will not be contacted. - +handle-as-image + +handle-as-image is then checked and if it does not match, an HTML BLOCKED page is sent back. Otherwise, if it does match, - an image is returned. The type of image depends on the setting of +set-image-blocker + an image is returned. The type of image depends on the setting of +set-image-blocker (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere). @@ -5871,16 +6111,16 @@ Requests - If the URL pattern matches the +fast-redirects action, + If the URL pattern matches the +fast-redirects action, it is then processed. Unwanted parts of the requested URL are stripped. Now the rest of the client browser's request headers are processed. If any - of these match any of the relevant actions (e.g. +hide-user-agent, + of these match any of the relevant actions (e.g. +hide-user-agent, etc.), headers are suppressed or forged as determined by these actions and their parameters. @@ -5895,25 +6135,25 @@ Requests First, the server headers are read and processed to determine, among other things, the MIME type (document type) and encoding. The headers are then - filtered as determined by the - +crunch-incoming-cookies, - +session-cookies-only, - and +downgrade-http-version + filtered as deterimed by the + +crunch-incoming-cookies, + +session-cookies-only, + and +downgrade-http-version actions. - If the +kill-popups + 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 a +filter - or +deanimate-gifs + If a +filter + or +deanimate-gifs 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 @@ -5924,9 +6164,9 @@ Requests Privoxy back to your browser. - If neither +filter - or +deanimate-gifs + If neither +filter + or +deanimate-gifs matches, then Privoxy passes the raw data through to the client browser as it becomes available. @@ -5954,8 +6194,8 @@ Requests The way Privoxy applies - actions - and filters + actions + and filters to any given URL can be complex, and not always so easy to understand what is happening. And sometimes we need to be able to see just what Privoxy is @@ -5984,8 +6224,8 @@ Requests First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell us how the current configuration will handle it. This will not - help with filtering effects (i.e. the +filter action) from + help with filtering effects (i.e. the +filter action) from the default.filter file 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 @@ -6034,7 +6274,7 @@ Requests This tells us how we have defined our - actions, and + actions, and which ones match for our example, google.com. The first listing is any matches for the standard.action file. No hits at all here on standard. Then next is default, or @@ -6051,12 +6291,12 @@ Requests rules, and then list specific URLs (or patterns) that these exceptions would apply to. Last match wins. Just below this then are two explicit matches for .google.com. The first is negating our previous cookie setting, - which was for +session-cookies-only + which was for +session-cookies-only (i.e. not persistent). So we will allow persistent cookies for google. The second turns off any - +fast-redirects + +fast-redirects action, allowing this to take place unmolested. Note that there is a leading dot here -- .google.com. This will match any hosts and sub-domains, in the google.com domain also, such as @@ -6119,8 +6359,8 @@ Requests We'll just show the interesting part here, the explicit matches. It is matched three different times. Each as an +block +handle-as-image, which is the expanded form of one of our aliases that had been defined as: - +imageblock. (Aliases are defined in + +imageblock. (Aliases are defined in the first section of the actions file and typically used to combine more than one action.) @@ -6131,11 +6371,11 @@ Requests would also cover the first. No point in taking chances with these guys though ;-) Note that if you want an ad or obnoxious URL to be invisible, it should be defined as ad.doubleclick.net - is done here -- as both a +block + is done here -- as both a +block and an - +handle-as-image. + +handle-as-image. The custom alias +imageblock just simplifies the process and make it more readable. @@ -6271,8 +6511,12 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + Revision 1.112 2002/05/15 03:57:14 hal9 + Spell check. A few minor edits here and there for better syntax and + clarification. + Revision 1.111 2002/05/14 23:01:36 oes - Fixing the fixes + Fixing the fixes Revision 1.110 2002/05/14 19:10:45 oes Restored alphabetical order of actions