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/
<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>
<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>
</sect4>
<sect4 id="trustfile"><title>trustfile</title>
-
<variablelist>
<varlistentry>
<term>Specifies:</term>
</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 ~ -->
<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>
</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>
<literal>
<msgtext>
<literallayout>
+# Sample default.action file <developers@privoxy.org>
# Settings -- Don't change! For internal Privoxy use ONLY.
{{settings}}
##########################################################################
# <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:
##########################################################################
# 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> \
<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> \
/ # 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
# 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
# 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/).)*$
# 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?.
.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]*.
# 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>
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 ~ -->
<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>
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>
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>
<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.
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
projects / privoxy.git / commitdiff