<!entity % p-config "IGNORE">
<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
<!entity my-copy "©"> <!-- kludge for docbook2man -->
-<!entity % draft "IGNORE"> <!-- WIP -->
+<!entity % draft "IGNORE"> <!-- WIP stuff -->
]>
<!--
File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.116 2002/05/17 03:23:46 hal9 Exp $
+ $Id: user-manual.sgml,v 1.122 2002/05/24 13:24:08 oes Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 1.116 2002/05/17 03:23:46 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.122 2002/05/24 13:24:08 oes Exp $</pubdate>
<!--
]]>
<para>
- The user manual gives users information on how to install, configure and use
- <ulink
+ The <citetitle>User Manual</citetitle> gives users information on how to
+ install, configure and use <ulink
url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
</para>
<!-- end privoxy.sgml -->
<para>
- You can find the latest version of the user manual at <ulink
+ You can find the latest version of the <citetitle>User Manual</citetitle> at <ulink
url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
Please see the <ulink url="contact.html">Contact section</ulink> on how to
contact the developers.
</para>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-rpm"><title>Red Hat, SuSE RPMs and Conectiva</title>
+<sect3 id="installation-pack-rpm"><title>Red Hat, SuSE and Conectiva RPMs</title>
<para>
RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
<para>
If you have problems with failed dependencies, try rebuilding the SRC RPM:
- <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This
+ <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm</literal>. This
will use your locally installed libraries and RPM version.
</para>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-deb"><title>Debian</title>
<para>
- FIXME.
+ DEBs can be installed with <literal>dpkg -i
+ privoxy_&p-version;-1.deb</literal>, and will use
+ <filename>/etc/privoxy</filename> for the location of configuration
+ files.
</para>
</sect3>
</itemizedlist>
</para>
+
<!-- ~~~~~ New section ~~~~~ -->
-<![%draft;[
<sect2 id="quickstart-ad-blocking">
<title>Quickstart to Ad Blocking</title>
<!--
- FIXME: This is unfinished. Do not publish yet!
+ NOTE: This section is deliberately redundant for those that don't
+ want to read the whole thing (which is getting lengthy).
-->
<para>
Ad blocking is but one of <application>Privoxy's</application>
array of features. Many of these features are for the technically minded advanced
- user. But, ad blocking is surely common ground for everybody.
+ user. But, ad and banner blocking is surely common ground for everybody.
</para>
<para>
- This section will provide a quick overview of ad blocking so
+ This section will provide a quick summary of ad blocking so
you can get up to speed quickly without having to read the more extensive
- information provided below, though this is highly recommeneded.
+ information provided below, though this is highly recommended.
</para>
<para>
First a bit of a warning ... blocking ads is much like blocking SPAM: the
- more aggressive you are about it, the more likely you are to block a few
+ more aggressive you are about it, the more likely you are to block
things that were not intended. So there is a trade off here. If you want
extreme ad free browsing, be prepared to deal with more
<quote>problem</quote> sites, and to spend more time adjusting the
- configuration to solve these unintended consequences.
+ configuration to solve these unintended consequences. In short, there is
+ not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
+ the easy way and settle for <emphasis>most</emphasis> ads blocked with the
+ default configuration, or jump in and tweak it for your personal surfing
+ habits and preferences.
</para>
<para>
- Secondly, a quick note on <application>Privoxy's </application>
+ Secondly, a brief explanation of <application>Privoxy's </application>
<quote>actions</quote>. <quote>Actions</quote> in this context, are
the directives we use to tell <application>Privoxy</application> to perform
some task relating to HTTP transactions (i.e. web browsing). We tell
Actions are specified in <application>Privoxy's</application> configuration,
followed by one or more URLs to which the action should apply. URLs
can actually be URL type <link linkend="af-patterns">patterns</link> that use
- wildcards so they can apply potentially to a range of similar URLs.
+ wildcards so they can apply potentially to a range of similar URLs. The
+ actions, together with the URL patterns are called a section.
</para>
<para>
- When you connect to a website, the full path of the URL will either match one
- of actions as defined in <application>Privoxy's</application> configuration,
+ When you connect to a website, the full URL will either match one or more
+ of the sections as defined in <application>Privoxy's</application> configuration,
or not. If so, then <application>Privoxy</application> will perform the
- action accordingly. If not, then nothing special happens. Futhermore, web
+ respective actions. If not, then nothing special happens. Futhermore, web
pages may contain embedded, secondary URLs that your web browser will
- display as it parses the original page's HTML content. An ad image for
- instance, is just a URL embedded in the page somewhere. The image itself may
- be on the same server, or a server somewhere else on the Internet. Complex
- web pages will have many such embedded URLs.
+ use to load additional components of the page, as it parses the
+ original page's HTML content. An ad image for instance, is just an URL
+ embedded in the page somewhere. The image itself may be on the same server,
+ or a server somewhere else on the Internet. Complex web pages will have many
+ such embedded URLs.
</para>
<para>
- The actions we need to know about for ad blocking are: <link
- linkend="block">block</link>, <link
- linkend="handle-as-image">handle-as-image</link>, and <link
- linkend="set-image-blocker">set-image-blocker</link>.
+ The actions we need to know about for ad blocking are: <literal><link
+ linkend="block">block</link></literal>, <literal><link
+ linkend="handle-as-image">handle-as-image</link></literal>, and
+ <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
</para>
<para>
<listitem>
<para>
- <link linkend="block"><emphasis>block</emphasis></link> - this action stops
+ <literal><link linkend="block">block</link></literal> - this action stops
any contact between your browser and any URL patterns that match this
action's configuration. It can be used for blocking ads, but also anything
that is determined to be unwanted. By itself, it simply stops any
- communication with the remote server. If this is the only action that
- matches for a particular URL, then <application>Privoxy</application> will
- display its own BLOCKED page to let you now what has happened.
+ communication with the remote server and sends <application>Privoxy</application>'s
+ own built-in BLOCKED page instead to let you now what has happened.
</para>
</listitem>
<listitem>
<para>
- <link linkend="handle-as-image"><emphasis>handle-as-image</emphasis></link> -
- forces <application>Privoxy</application> to treat this URL as if it were
- an image. <application>Privoxy</application> knows about common image
- types (e.g. GIF), but there are many situations where this does not apply.
- So we'll force it. This is particularly important for ad blocking, since
- once we can treat it as an image, we can make more intelligent decisisions
- on how to handle it. There are some limitations to this though. For
- instance, you can't just force an image substituion for an entire HTML page
- in most situations.
+ <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
+ tells <application>Privoxy</application> to treat this URL as an image.
+ <application>Privoxy</application>'s default configuration already does this
+ for all common image types (e.g. GIF), but there are many situations where this
+ is not so easy to determine. So we'll force it in these cases. This is particularly
+ important for ad blocking, since only if we know that it's an image of
+ some kind, can we replace it with an image of our chosing, instead of the
+ <application>Privoxy</application> BLOCKED page (which would only result in
+ a <quote>broken image</quote> icon). There are some limitations to this
+ though. For instance, you can't just brute-force an image substituion for
+ an entire HTML page in most situations.
</para>
</listitem>
<listitem>
<para>
- <link
- linkend="set-image-blocker"><emphasis>set-image-blocker</emphasis></link> -
- tells <application>Privoxy</application> what to display in place of
- an ad image that has hit a block rule. For this to come into play,
- the URL must match a block action somewhere in the configuration.
- <emphasis>And</emphasis>, it must also either be of a known image type, or
- match an <link
- linkend="handle-as-image"><emphasis>handle-as-image</emphasis></link>
- action.
+ <literal><link
+ linkend="set-image-blocker">set-image-blocker</link></literal> - tells
+ <application>Privoxy</application> what to display in place of an ad image that
+ has hit a block rule. For this to come into play, the URL must match a
+ <literal><link linkend="block">block</link></literal> action somewhere in the
+ configuration, <emphasis>and</emphasis>, it must also match an
+ <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
</para>
<para>
The configuration options on what to display instead of the ad are:
</simplelist>
<simplelist>
<member>
- <emphasis>http://<URL></emphasis> - A redirect to any URL of the
- user's choosing.
+ <emphasis>http://<URL></emphasis> - A redirect to any image anywhere
+ of the user's choosing (advanced usage).
</member>
</simplelist>
</listitem>
</itemizedlist>
</para>
+<para>
+ The quickest way to adjust any of these settings is with your browser through
+ the special <application>Privoxy</application> editor at <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
+ is an internal page, and does not require Internet access. Select the
+ appropriate <quote>actions</quote> file, and click
+ <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
+ local preferences in <filename>user.action</filename> since this is not
+ meant to be overwritten during upgrades, and will over-ride the settings in
+ other files. Here you can insert new <quote>actions</quote>, and URLs for ad
+ blocking or other purposes, and make other adjustments to the configuration.
+ <application>Privoxy</application> will detect these changes automatically.
+</para>
+
+<para>
+ A quick and simple step by step example:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Right click on the ad image to be blocked, then select
+ <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
+ pop-up menu.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set your browser to
+ <ulink
+ url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Find <filename>user.action</filename> in the top section, and click
+ on <quote><guibutton>Edit</guibutton></quote>:
+ </para>
+
+ <!-- image of editor and actions files selections -->
+ <para>
+ <figure pgwide="0" float="0"><title>Actions Files in Use</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../images/files-in-use.jpg" format="jpg">
+ </imageobject>
+ <textobject>
+ <phrase>[ Screenshot of Actions Files in Use ]</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You should have a section with only
+ <literal><link linkend="block">block</link></literal> listed under
+ <quote>Actions:</quote>.
+ If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
+ button, and in the new section that just appeared, click the
+ <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
+ This will bring up a list of all actions. Find
+ <literal><link linkend="block">block</link></literal> near the top, and click
+ in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
+ just below the list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now, in the <literal><link linkend="block">block</link></literal> actions section,
+ click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
+ browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
+ Remove the <literal>http://</literal> at the beginning of the URL. Then, click
+ <quote><guibutton>Submit</guibutton></quote> (or
+ <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
+ (or flush all browser caches). The image should be gone now.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+<para>
+ This is a very crude and simple example. There might be good reasons to use a
+ wildcard pattern match to include potentially similar images from the same
+ site. For a more extensive explanation of <quote>patterns</quote>, and
+ the entire actions concept, see <link linkend="actions-file">the Actions
+ section</link>.
+</para>
+
+<para>
+ For advanced users who want to hand edit their config files, you might want
+ to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
+ The ideas explained thererin also apply to the web-based editor.
+</para>
+
</sect2>
-]]>
</sect1>
127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
used port 8000). This is the one configuration step that must be done!
</para>
+
+ <!-- image of Mozilla Proxy configuration -->
+ <para>
+ <figure pgwide="0" float="0"><title>Proxy Configuration (Mozilla)</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../images/proxy_setup.jpg" format="jpg">
+ </imageobject>
+ <textobject>
+ <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
<para>
With <application>Netscape</application> (and
- <application>Mozilla</application>), this can be set under <literal>Edit
- -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
- For <application>Internet Explorer</application>: <literal>Tools ->
- Internet Properties -> Connections -> LAN Setting</literal>. Then,
- check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
- 127.0.0.1, Port: 8118). Include if HTTPS proxy support too.
+ <application>Mozilla</application>), this can be set under:
+</para>
+
+<literallayout>
+<!-- Mix ascii and gui art, something for everybody -->
+<!-- spacing on this is tricky -->
+ <guibutton>Edit</guibutton>
+ |_
+ <guibutton>Preferences</guibutton>
+ |_
+ <guibutton>Advanced</guibutton>
+ |_
+ <guibutton>Proxies</guibutton>
+ |_
+ <guibutton>HTTP Proxy</guibutton>
+</literallayout>
+
+<para>
+ For <application>Internet Explorer</application>:
+</para>
+
+<literallayout>
+<!-- Mix ascii and gui art, something for everybody -->
+<!-- spacing on this is tricky -->
+ <guibutton>Tools</guibutton>
+ |_
+ <guibutton>Internet Properties</guibutton>
+ |_
+ <guibutton>Connections</guibutton>
+ |_
+ <guibutton>LAN Settings</guibutton>
+</literallayout>
+
+<para>
+ Then, check <quote>Use Proxy</quote> and fill in the appropriate info
+ (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
+ proxy support too.
</para>
<para>
directory. Except on Win32 where it will try <filename>config.txt</filename>.
</para>
-<sect2 id="start-redhatdebian">
-<title>RedHat, Conectiva and Debian</title>
+<sect2 id="start-redhat">
+<title>RedHat and Conectiva</title>
<para>
-We use a script. Note that RedHat does not start Privoxy upon booting per
-default. It will use the file <filename>/etc/privoxy/config</filename> as its
-main configuration file. FIXME: Debian??
+ We use a script. Note that RedHat does not start Privoxy upon booting per
+ default. It will use the file <filename>/etc/privoxy/config</filename> as
+ its main configuration file.
</para>
<para>
<screen>
</para>
</sect2>
+<sect2 id="start-debian">
+<title>Debian</title>
+<para>
+ We use a script. Note that Debian starts Privoxy upon booting per
+ default. It will use the file
+ <filename>/etc/privoxy/config</filename> as its main configuration
+ file.
+</para>
+<para>
+ <screen>
+ # /etc/init.d/privoxy start
+</screen>
+</para>
+</sect2>
+
<sect2 id="start-suse">
<title>SuSE</title>
<para>
<!-- Needs to be put in a table and colorized -->
<screen>
<msgtext>
- <bridgehead renderas="sect2">Privoxy Menu</bridgehead>
+ <bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
<simplelist>
<member>
<para>
If you leave out the IP address, <application>Privoxy</application> will
bind to all interfaces (addresses) on your machine and may become reachable
- from the Internet. In that case, consider using access control lists (ACL's)
- (see <quote>ACLs</quote> below), or a firewall.
+ from the Internet. In that case, consider using <link
+ linkend="acls">access control lists</link> (ACL's, see below), and/or
+ a firewall.
+ </para>
+ <para>
+ If you open <application>Privoxy</application> to untrusted users, you will
+ also want to turn off the <literal><link
+ linkend="enable-edit-actions">enable-edit-actions</link></literal> and
+ <literal><link linkend="enable-remote-toggle">enable-remote-toggle</link></literal>
+ options!
</para>
</listitem>
</varlistentry>
<sect3 renderas="sect4" id="acls"><title>
ACLs: permit-access and deny-access</title>
-<anchor id="permit-acces">
-<anchor id="deny-acces">
+<anchor id="permit-access">
+<anchor id="deny-access">
<variablelist>
<varlistentry>
<title>How Actions are Applied to URLs</title>
<para>
Actions files are divided into sections. There are special sections,
- like the <quote><link linkend="aliases">alias</link></quote> sections which will be discussed later. For now
- let's concentrate on regular sections: They have a heading line (often split
- up to multiple lines for readability) which consist of a list of actions,
- separated by whitespace and enclosed in curly braces. Below that, there
- is a list of URL patterns, each on a separate line.
+ like the <quote><link linkend="aliases">alias</link></quote> sections which will
+ be discussed later. For now let's concentrate on regular sections: They have a
+ heading line (often split up to multiple lines for readability) which consist
+ of a list of actions, separated by whitespace and enclosed in curly braces.
+ Below that, there is a list of URL patterns, each on a separate line.
</para>
<para>
applicable actions for the URL is incrementally updated, using the heading
of the section in which the pattern is located. If multiple matches for
the same URL set the same action differently, the last match wins. If not,
- the effects are aggregated (e.g. a URL might match both the
- <ulink url="actions-file.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>
- and <ulink url="actions-file.html#BLOCK"><quote>+block</quote></ulink> actions).
-
+ the effects are aggregated. E.g. a URL might match a regular section with
+ a heading line of <literal>{
+ +<ulink url="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</ulink> }</literal>,
+ then later another one with just <literal>{
+ +<ulink url="actions-file.html#BLOCK">block</ulink> }</literal>, resulting
+ in <emphasis>both</emphasis> actions to apply.
</para>
<para>
</para>
<para>
- Please also note that matching in the path is case
- <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
- sensitive at any point in the pattern by using the
- <quote>(?-i)</quote> switch:
- <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
- documents whose path starts with <literal>PaTtErN</literal> in
+ Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
+ by default, but you can switch to case sensitive at any point in the pattern by using the
+ <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
+ only documents whose path starts with <literal>PaTtErN</literal> in
<emphasis>exactly</emphasis> this capitalization.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="add-header">
-<title><emphasis>add-header</emphasis></title>
+<title>add-header</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="block">
-<title><emphasis>block</emphasis></title>
+<title>block</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="crunch-incoming-cookies">
-<title><emphasis>crunch-incoming-cookies</emphasis></title>
+<title>crunch-incoming-cookies</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="crunch-outgoing-cookies">
-<title><emphasis>crunch-outgoing-cookies</emphasis></title>
+<title>crunch-outgoing-cookies</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="deanimate-gifs">
-<title><emphasis>deanimate-gifs</emphasis></title>
+<title>deanimate-gifs</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="downgrade-http-version">
-<title><emphasis>downgrade-http-version</emphasis></title>
+<title>downgrade-http-version</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="fast-redirects">
-<title><emphasis>fast-redirects</emphasis></title>
+<title>fast-redirects</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="filter">
-<title><emphasis>filter</emphasis></title>
+<title>filter</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="handle-as-image">
-<title><emphasis>handle-as-image</emphasis></title>
+<title>handle-as-image</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="hide-forwarded-for-headers">
-<title><emphasis>hide-forwarded-for-headers</emphasis></title>
+<title>hide-forwarded-for-headers</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="hide-from-header">
-<title><emphasis>hide-from-header</emphasis></title>
+<title>hide-from-header</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="hide-referrer">
-<title><emphasis>hide-referrer</emphasis></title>
+<title>hide-referrer</title>
<anchor id="hide-referer">
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="hide-user-agent">
-<title><emphasis>hide-user-agent</emphasis></title>
+<title>hide-user-agent</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="kill-popups">
-<title><emphasis>kill-popups<anchor id="kill-popup"></emphasis></title>
+<title>kill-popups<anchor id="kill-popup"></title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="limit-connect">
-<title><emphasis>limit-connect</emphasis></title>
+<title>limit-connect</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="prevent-compression">
-<title><emphasis>prevent-compression</emphasis></title>
+<title>prevent-compression</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="send-vanilla-wafer">
-<title><emphasis>send-vanilla-wafer</emphasis></title>
+<title>send-vanilla-wafer</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="send-wafer">
-<title><emphasis>send-wafer</emphasis></title>
+<title>send-wafer</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="session-cookies-only">
-<title><emphasis>session-cookies-only</emphasis></title>
+<title>session-cookies-only</title>
<variablelist>
<varlistentry>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="set-image-blocker">
-<title><emphasis>set-image-blocker</emphasis></title>
+<title>set-image-blocker</title>
<variablelist>
<varlistentry>
<para>
The first regular section is probably the most important. It has only
one pattern, <quote><literal>/</literal></quote>, but this pattern
- <link linkend="af-patterns">matches all URLs.</link>. Therefore, the
+ <link linkend="af-patterns">matches all URLs</link>. Therefore, the
set of actions used in this <quote>default</quote> section <emphasis>will
be applied to all requests as a start</emphasis>. It can be partly or
wholly overridden by later matches further down this file, or in user.action,
<para>
Again, at the start of matching, all actions are disabled, so there is
no real need to disable any actions here, but we will do that nonetheless,
- to have a complete listing for your reference. (Remember: A <quote>+</quote>
+ to have a complete listing for your reference. (Remember: a <quote>+</quote>
preceding the action name enables the action, a <quote>-</quote> disables!).
Also note how this long line has been made more readable by splitting it into
multiple lines with line continuation.
<para>
So far we are painting with a broad brush by setting general policies,
which would be a reasonable starting point for many people. Now,
- you'd maybe want to be more specific and have customized rules that
+ you might want to be more specific and have customized rules that
are more suitable to your 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
and all pages of its <ulink url="http://config.privoxy.org/">web-based
user interface</ulink>, are generated from <emphasis>templates</emphasis>.
(<application>Privoxy</application> must be running for the above links to work as
- intended)
+ intended.)
</para>
<para>
<ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
</para>
</listitem>
-
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
+ </para>
+ </listitem>
</itemizedlist>
</para>
<screen>
Matches for http://google.com:
---- File standard ---
-(no matches in this file)
-
---- File default ---
-
-{ -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects
- -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
- +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
- +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
- +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
- -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
- +prevent-compression +session-cookies-only -crunch-outgoing-cookies
- -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer }
+ In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
+
+{-add-header
+ -block
+ -crunch-outgoing-cookies
+ -crunch-incoming-cookies
+ +deanimate-gifs{last}
+ -downgrade-http-version
+ +fast-redirects
+ -filter{popups}
+ -filter{fun}
+ -filter{shockwave-flash}
+ -filter{crude-parental}
+ +filter{html-annoyances}
+ +filter{js-annoyances}
+ +filter{content-cookies}
+ +filter{webbugs}
+ +filter{refresh-tags}
+ +filter{nimda}
+ +filter{banners-by-size}
+ +hide-forwarded-for-headers
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -handle-as-image
+ -kill-popups
+ -limit-connect
+ +prevent-compression
+ -send-vanilla-wafer
+ -send-wafer
+ +session-cookies-only
+ +set-image-blocker{pattern} }
/
{ -session-cookies-only }
{ -fast-redirects }
.google.com
---- File user ---
+In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
(no matches in this file)
</screen>
</para>
<screen>
Final results:
- -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects
- -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
- +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
- +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
- +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
- -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
- +prevent-compression -session-cookies-only -crunch-outgoing-cookies
- -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer
+
+ -add-header
+ -block
+ -crunch-outgoing-cookies
+ -crunch-incoming-cookies
+ +deanimate-gifs{last}
+ -downgrade-http-version
+ -fast-redirects
+ -filter{popups}
+ -filter{fun}
+ -filter{shockwave-flash}
+ -filter{crude-parental}
+ +filter{html-annoyances}
+ +filter{js-annoyances}
+ +filter{content-cookies}
+ +filter{webbugs}
+ +filter{refresh-tags}
+ +filter{nimda}
+ +filter{banners-by-size}
+ +hide-forwarded-for-headers
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -handle-as-image
+ -kill-popups
+ -limit-connect
+ +prevent-compression
+ -send-vanilla-wafer
+ -send-wafer
+ -session-cookies-only
+ +set-image-blocker{pattern}
</screen>
</para>
<para>
One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
- This one is giving us problems. We are getting a blank page. Hmmm...
+ This one is giving us problems. We are getting a blank page. Hmmm ...
</para>
<para>
Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
- { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects
- +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}
- +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
- +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}
- +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}
- +prevent-compression +session-cookies-only -crunch-incoming-cookies
- -crunch-outgoing-cookies +kill-popups -send-vanilla-wafer -send-wafer }
+ In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
+
+ {-add-header
+ -block
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ +deanimate-gifs
+ -downgrade-http-version
+ +fast-redirects
+ +filter{html-annoyances}
+ +filter{js-annoyances}
+ +filter{kill-popups}
+ +filter{webbugs}
+ +filter{nimda}
+ +filter{banners-by-size}
+ +filter{hal}
+ +filter{fun}
+ +hide-forwarded-for-headers
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -handle-as-image
+ +kill-popups
+ +prevent-compression
+ -send-vanilla-wafer
+ -send-wafer
+ +session-cookies-only
+ +set-image-blocker{blank} }
/
{ +block +handle-as-image }
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.122 2002/05/24 13:24:08 oes
+ Added Bookmarklet for one-click pre-filled access to show-url-info
+
+ Revision 1.121 2002/05/23 23:20:17 oes
+ - Changed more (all?) references to actions to the
+ <literal><link> style.
+ - Small fixes in the actions chapter
+ - Small clarifications in the quickstart to ad blocking
+ - Removed <emphasis> from <title>s since the new doc CSS
+ renders them red (bad in TOC).
+
+ Revision 1.120 2002/05/23 19:16:43 roro
+ Correct Debian specials (installation and startup).
+
+ Revision 1.119 2002/05/22 17:17:05 oes
+ Added Security hint
+
+ Revision 1.118 2002/05/21 04:54:55 hal9
+ -New Section: Quickstart to Ad Blocking
+ -Reformat Actions Anatomy to match new CGI layout
+
+ Revision 1.117 2002/05/17 13:56:16 oes
+ - Reworked & extended Templates chapter
+ - Small changes to Regex appendix
+ - #included authors.sgml into (C) and hist chapter
+
Revision 1.116 2002/05/17 03:23:46 hal9
Fixing merge conflict in Quickstart section.