From: hal9 <hal9@users.sourceforge.net> 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/@default-cgi@/faq/%22https:/user-manual/static/@default-cgi@send-stylesheet?a=commitdiff_plain;h=2ee4589040849085b6d40584d9bdb755699115fd;p=privoxy.git -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 @@ <artheader> <title>Privoxy User Manual</title> -<pubdate>$Id: user-manual.sgml,v 1.95 2002/04/26 17:23:29 swa Exp $</pubdate> +<pubdate>$Id: user-manual.sgml,v 1.96 2002/04/27 05:32:00 hal9 Exp $</pubdate> <authorgroup> <author> @@ -883,7 +883,7 @@ automatically start Privoxy in the boot process. <para> <application>Privoxy</application> 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 <application>Privoxy</application> where to find those other files. </para> @@ -1195,7 +1195,6 @@ actionsfile </sect4> <sect4 id="trustfile"><title>trustfile</title> - <variablelist> <varlistentry> <term>Specifies:</term> @@ -1249,6 +1248,55 @@ actionsfile </variablelist> </sect4> +<sect4 id="user-manual"><title>user-manual</title> +<variablelist> + <varlistentry> + <term>Specifies:</term> + <listitem> + <para> + Location of the <application>Privoxy</application> User Manual. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Type of value:</term> + <listitem> + <para>A fully qualified URI</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Default value:</term> + <listitem> + <para><ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Effect if unset:</term> + <listitem> + <para> + The default will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Notes:</term> + <listitem> + <para> + 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. + </para> + <para> + A more useful example (Unix): + </para> + <para> + <emphasis>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</emphasis> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect4> + </sect3> <!-- ~ End section ~ --> @@ -3213,61 +3261,73 @@ forward-socks4 and forward-socks4a</title> <listitem> <simplelist> <member> + <anchor id="filter-html-annoyances"> <emphasis>+filter{html-annoyances}</emphasis>: Get rid of particularly annoying HTML abuse. </member> </simplelist> <simplelist> <member> + <anchor id="filter-js-annoyances"> <emphasis>+filter{js-annoyances}</emphasis>: Get rid of particularly annoying JavaScript abuse </member> </simplelist> <simplelist> <member> + <anchor id="filter-content-cookies"> <emphasis>+filter{content-cookies}</emphasis>: Kill cookies that come in the HTML or JS content </member> </simplelist> <simplelist> <member> + <anchor id="filter-popups"> <emphasis>+filter{popups}</emphasis>: Kill all popups in JS and HTML </member> </simplelist> <simplelist> <member> + <anchor id="filter-frameset-borders"> <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable </member> </simplelist> <simplelist> <member> + <anchor id="filter-webbugs"> <emphasis>+filter{webbugs}</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking) </member> </simplelist> <simplelist> <member> + <anchor id="filter-refresh-tags"> <emphasis>+filter{refresh-tags}</emphasis>: Kill automatic refresh tags (for dial-on-demand setups) </member> </simplelist> <simplelist> <member> + <anchor id="filter-fun"> <emphasis>+filter{fun}</emphasis>: Text replacements for subversive browsing fun! </member> </simplelist> <simplelist> <member> + <anchor id="filter-nimda"> <emphasis>+filter{nimda}</emphasis>: Remove Nimda (virus) code. </member> </simplelist> <simplelist> <member> + <anchor id="filter-banners-by-size"> <emphasis>+filter{banners-by-size}</emphasis>: Kill banners by size (<emphasis>very</emphasis> efficient!) </member> </simplelist> <simplelist> <member> + <anchor id="filter-shockwave-flash"> <emphasis>+filter{shockwave-flash}</emphasis>: Kill embedded Shockwave Flash objects </member> </simplelist> <simplelist> <member> + <anchor id="filter-crude-parental"> <emphasis>+filter{crude-parental}</emphasis>: Kill all web pages that contain the words "sex" or "warez" </member> </simplelist> @@ -4173,27 +4233,46 @@ forward-socks4 and forward-socks4a</title> </sect4> +<!-- ~~~~~ New section ~~~~~ --> +<sect4> +<title>Summary</title> +<para> + 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 <link + linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting + actions. +</para> +</sect4> + + <!-- ~~~~~ New section ~~~~~ --> <sect4 id="act-examples" renderas="sect3"> -<title>Actions Examples</title> +<title>Sample Actions Files</title> <para> - 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 <quote>-</quote>, in place of the <quote>+</quote>. 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 <quote>on</quote>. - But, other actions that are turned on the default section <emphasis>do +</para> + +<para> + But, other actions that are turned on in the default section <emphasis>do typically require</emphasis> exceptions to be listed in the latter sections of one of our actions file. For instance, by default no URLs are <quote>blocked</quote> (i.e. in the default definitions of <filename>default.action</filename>). 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. + <emphasis>enable</emphasis> ad blocking in the lower sections. But we need to + be very selective about what we do block. Thus, the default is <quote>off</quote> + for blocking. </para> <para> - Below is a liberally commented <filename>default.action</filename> 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 <filename>default.action</filename> 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 <filename>user.action</filename> with similar examples. </para> @@ -4201,6 +4280,7 @@ forward-socks4 and forward-socks4a</title> <literal> <msgtext> <literallayout> +# 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 ########################################################################## # <ulink url="configuration.html#ALIASES">Aliases</ulink> 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). ########################################################################## { \ <ulink url="configuration.html#ADD-HEADER">-add-header</ulink> \ @@ -4239,17 +4326,17 @@ for-privoxy-version=3.0 <ulink url="configuration.html#DEANIMATE-GIFS">-deanimate-gifs</ulink> \ <ulink url="configuration.html#DOWNGRADE-HTTP-VERSION">-downgrade-http-version</ulink> \ <ulink url="configuration.html#FAST-REDIRECTS">+fast-redirects</ulink> \ - <ulink url="configuration.html#FILTER">+filter{html-annoyances}</ulink> \ - <ulink url="configuration.html#FILTER">+filter{js-annoyances}</ulink> \ - <ulink url="configuration.html#FILTER">-filter{content-cookies}</ulink> \ - <ulink url="configuration.html#FILTER">-filter{popups}</ulink> \ - <ulink url="configuration.html#FILTER">+filter{webbugs}</ulink> \ - <ulink url="configuration.html#FILTER">-filter{refresh-tags}</ulink> \ - <ulink url="configuration.html#FILTER">-filter{fun}</ulink> \ - <ulink url="configuration.html#FILTER">+filter{nimda}</ulink> \ - <ulink url="configuration.html#FILTER">+filter{banners-by-size}</ulink> \ - <ulink url="configuration.html#FILTER">-filter{shockwave-flash}</ulink> \ - <ulink url="configuration.html#FILTER">-filter{crude-prental}</ulink> \ + <ulink url="configuration.html#FILTER-HTML-ANNOYANCES">+filter{html-annoyances}</ulink> \ + <ulink url="configuration.html#FILTER-JS-ANNOYANCES">+filter{js-annoyances}</ulink> \ + <ulink url="configuration.html#FILTER-CONTENT-COOKIES">-filter{content-cookies}</ulink> \ + <ulink url="configuration.html#FILTER-POPUPS">-filter{popups}</ulink> \ + <ulink url="configuration.html#FILTER-WEBBUGS">+filter{webbugs}</ulink> \ + <ulink url="configuration.html#FILTER-REFRESH-TAGS">-filter{refresh-tags}</ulink> \ + <ulink url="configuration.html#FILTER-FUN">-filter{fun}</ulink> \ + <ulink url="configuration.html#FILTER-NIMDA">+filter{nimda}</ulink> \ + <ulink url="configuration.html#FILTER-BANNERS-BY-SIZE">+filter{banners-by-size}</ulink> \ + <ulink url="configuration.html#FILTER-SHOCKWAVE-FLASH">-filter{shockwave-flash}</ulink> \ + <ulink url="configuration.html#FILTER-CRUDE-PARENTAL">-filter{crude-prental}</ulink> \ <ulink url="configuration.html#HIDE-FORWARDED-FOR-HEADERS">+hide-forwarded-for-headers</ulink> \ <ulink url="configuration.html#HIDE-FROM-HEADER">+hide-from-header{block}</ulink> \ <ulink url="configuration.html#HIDE-REFERER">-hide-referrer</ulink> \ @@ -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 <ulink url="configuration.html#KILL-POPUPS">-kill-popups</ulink> <ulink url="configuration.html#FILTER-POPUPS">-filter{popups}</ulink> } .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: + { <ulink url="configuration.html#FAST-REDIRECTS">-fast-redirects</ulink> } 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} + { <ulink url="configuration.html#HANDLE-AS-IMAGE">+handle-as-image</ulink> } /.*\.(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 <ulink url="configuration.html#SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></ulink> - {+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: + { <ulink url="configuration.html#BLOCK">+block</ulink> } 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: + { <ulink url="configuration.html#BLOCK">-block</ulink> } 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: + { <ulink url="configuration.html#FILTER">-filter</ulink> } .sourceforge.net - </literallayout> </msgtext> </literal> @@ -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 <filename>user.action</filename>, 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. </para> <para> - Now an example of a few things that one might do with a <filename>user.action</filename> - file. This is where user preferences are defined. + Now a few examples of some things that one might do with a + <filename>user.action</filename> file. </para> <!-- brief sample user.action here --> - -<!-- This is the old stuff. Left in temporarily for reference --> -<!-- To be deleted when above is finished --> -<para> - Some examples: -</para> - -<para> - Turn off cookies by default, then allow a few through for specified sites - (showing an excerpt from the <quote>default</quote> section of an actions - file ONLY): -</para> - <para> <literal> <msgtext> <literallayout> - # 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 - - </literallayout> - </msgtext> - </literal> -</para> - -<para> - Now turn off <quote>fast redirects</quote>, and then we allow two exceptions: -</para> - -<para> - <literal> - <msgtext> - <literallayout> - # 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 - </literallayout> - </msgtext> - </literal> -</para> - -<para> - Turn on page filtering according to rules in the defined sections - of <filename>default.filter</filename>, and make one exception for - Sourceforge: - </para> - -<para> - <literal> - <msgtext> - <literallayout> - # 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 - </literallayout> - </msgtext> - </literal> -</para> +# 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 -<para> - Now some URLs that we want <quote>blocked</quote> (normally generates - the <quote>blocked</quote> banner). Typically, the <quote>block</quote> - 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 <link - linkend="regex">regular expressions</link> that will expand to match multiple - URLs: </para> +# Fragile sites should have the minimum changes: + fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ + -prevent-cookies -kill-popups -<para> - <literal> - <msgtext> - <literallayout> - # 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 <ulink url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink> need not be specified, +# since all URLs ending in .gif will be tagged as images by the +# general rules in default.action anyway. + { <ulink url="configuration.html#BLOCK">+block</ulink> } + 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: +# + { <ulink url="configuration.html#FILTER-POPUPS">-filter{popups}</ulink> <ulink url="configuration.html#KILL-POPUPS">-kill-popups</ulink> } + .my-example-bank.com + +# This site is delicate, and requires kid-glove +# treatment. + { fragile } + .forbes.com </literallayout> </msgtext> </literal> </para> -<para> - 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 <link - linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting - actions. -</para> </sect4> - </sect3> <!-- ~ End section ~ --> @@ -4541,7 +4548,8 @@ for-privoxy-version=3.0 <emphasis>must be defined before other actions</emphasis> in the actions file! And there can only be one set of <quote>aliases</quote> 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 <quote>+</quote> or + <quote>-</quote> sign in front, since they are merely expanded. </para> <para> @@ -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 - <filename>default.filter</filename>, located in the config directory. + oddly enough <filename>default.filter</filename>, located in the config + directory. </para> <para> @@ -4727,16 +4736,14 @@ for-privoxy-version=3.0 should match one of the section identifiers in the filter file itself. Example: </para> -<para> - <screen> +<screen> +filter{html-annoyances} - </screen> -</para> +</screen> <para> This would activate that particular filter. Similarly, <quote>+filter</quote> can be turned off for selected sites as: - <quote>-filter{html-annoyances}</quote>. Remember, all actions are off by + <quote>-filter{html-annoyances}</quote>. Remember too, all actions are off by default, unless they are explicity enabled in one of the actions files. </para> @@ -4754,14 +4761,18 @@ for-privoxy-version=3.0 <title>Templates</title> <para> When <application>Privoxy</application> 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 - <filename>/etc/privoxy/templates</filename> by default. These may be - customized, if desired. <filename>cgi-style.css</filename> is - used to control the HTML attributes (fonts, etc). -</para> -<para> - The default <quote>Blocked</quote> banner page with the bright red top + pages, such as a <ulink url="http://bogus_404_page.com">404 Not Found error page</ulink> + (<application>Privoxy</application> must be running for link to work as + intended), it uses the appropriate template. On Linux, BSD, and Unix, these + are located in <filename>/etc/privoxy/templates</filename> by default. These + may be customized, if desired. <filename>cgi-style.css</filename> is used to + control the HTML attributes (fonts, etc). +</para> +<para> + The default +<ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html">Blocked +(<application>Privoxy</application> needs to be running for page to display)</ulink> + banner page with the bright red top banner, is called just <quote><filename>blocked</filename></quote>. This may be customized or replaced with something else if desired. @@ -5700,6 +5711,10 @@ Requests</title> 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