[ Copyright 2001 - 2007 by Privoxy Developers ]
-$Id: user-manual.sgml,v 2.44 2007/11/15 03:30:20 hal9 Exp $
+$Id: user-manual.sgml,v 2.46 2007/11/17 17:24:44 fabiankeil Exp $
The Privoxy User Manual gives users information on how to install, configure
and use Privoxy.
2.1. Binary Packages
2.1.1. Red Hat and Fedora RPMs
- 2.1.2. Debian
+ 2.1.2. Debian and Ubuntu
2.1.3. Windows
2.1.4. Solaris
2.1.5. OS/2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-2.1.2. Debian
+2.1.2. Debian and Ubuntu
DEBs can be installed with apt-get install privoxy, and will use /etc/privoxy
for the location of configuration files.
http://<URL> - A redirect to any image anywhere of the user's choosing
(advanced usage).
+Advanced users will eventually want to explore Privoxy filters as well. Filters
+are very different from blocks. A "block" blocks a site, page, or unwanted
+contented. Filters are a way of filtering or modifying what is actually on the
+page. An example filter usage: a text replacement of "no-no" for "nasty-word".
+That is a very simple example. This process can be used for ad blocking, but it
+is more in the realm of advanced usage and has some pitfalls to be wary off.
+
The quickest way to adjust any of these settings is with your browser through
the special Privoxy editor at http://config.privoxy.org/show-status (shortcut:
http://p.p/show-status). This is an internal page, and does not require
in user.action, but it will still be largely responsible for your overall
browsing experience.
-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 "+" preceding the action name
-enables the action, a "-" disables!). Also note how this long line has been
-made more readable by splitting it into multiple lines with line continuation.
+Again, at the start of matching, all actions are disabled, so there is no need
+to disable any actions here. (Remember: a "+" preceding the action name enables
+the action, a "-" disables!). Also note how this long line has been made more
+readable by splitting it into multiple lines with line continuation.
##########################################################################
# "Defaults" section:
##########################################################################
{ \
- -add-header \
- -client-header-filter{hide-tor-exit-notation} \
- -block \
- -content-type-overwrite \
- -crunch-client-header \
- -crunch-if-none-match \
- -crunch-incoming-cookies \
- -crunch-server-header \
- -crunch-outgoing-cookies \
+deanimate-gifs \
- -downgrade-http-version \
- -fast-redirects{check-decoded-url} \
- -filter{js-annoyances} \
- -filter{js-events} \
+filter{html-annoyances} \
- -filter{content-cookies} \
+filter{refresh-tags} \
- -filter{unsolicited-popups} \
- -filter{all-popups} \
- -filter{img-reorder} \
- -filter{banners-by-size} \
- -filter{banners-by-link} \
+filter{webbugs} \
- -filter{tiny-textforms} \
- -filter{jumping-windows} \
- -filter{frameset-borders} \
- -filter{demoronizer} \
- -filter{shockwave-flash} \
- -filter{quicktime-kioskmode} \
- -filter{fun} \
- -filter{crude-parental} \
+filter{ie-exploits} \
- -filter{google} \
- -filter{yahoo} \
- -filter{msn} \
- -filter{blogspot} \
- -filter{no-ping} \
- -force-text-mode \
- -handle-as-empty-document \
- -handle-as-image \
- -hide-accept-language \
- -hide-content-disposition \
- -hide-if-modified-since \
+hide-forwarded-for-headers \
+hide-from-header{block} \
+hide-referrer{forge} \
- -hide-user-agent \
- -inspect-jpegs \
- -kill-popups \
- -limit-connect \
+prevent-compression \
- -overwrite-last-modified \
- -redirect \
- -send-vanilla-wafer \
- -send-wafer \
- -server-header-filter{xml-to-html} \
- -server-header-filter{html-to-xml} \
+session-cookies-only \
+set-image-blocker{pattern} \
- -treat-forbidden-connects-like-blocks \
}
/ # forward slash will match *all* potential URL patterns.
-The default behavior is now set. Note that some actions, like not hiding the
-user agent, are part of a "general policy" that applies universally and won't
-get any exceptions defined later. Other choices, like not blocking (which is
-understandably the default!) need exceptions, i.e. we need to specify
-explicitly what we want to block in later sections.
+The default behavior is now set.
The first of our specialized sections is concerned with "fragile" sites, i.e.
sites that require minimum interference, because they are either very complex
So let's look at a few examples of things that one might typically do in
user.action:
-# My user.action file. <fred@foobar.com>
+# My user.action file. <fred@example.com>
As aliases are local to the actions file that they are defined in, you can't
{ +block }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/
+ another.example.net/more/junk/here/
The URLs of dynamically generated banners, especially from large banner farms,
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,
+the distributed actions file. So you'd like to turn it on in your private,
update-safe config, once and for all:
{ +filter{fun} }
Privoxy supports three different filter actions: filter to rewrite the content
that is send to the client, client-header-filter to rewrite headers that are
send by the client, and server-header-filter to rewrite headers that are send
-by the server, and
+by the server.
Privoxy also supports two tagger actions: client-header-tagger and
server-header-tagger. Taggers and filters use the same syntax in the filter
used to change the applying actions through sections with tag-patterns.
Multiple filter files can be defined through the filterfile config directive.
-The filters as supplied by the developers will be found in default.filter. It
-is recommended that any locally defined or modified filters go in a separately
+The filters as supplied by the developers are located in default.filter. It is
+recommended that any locally defined or modified filters go in a separately
defined file such as user.filter.
-Command tasks for content filters are to eliminate common annoyances in HTML
-and JavaScript, such as pop-up windows, exit consoles, crippled windows without
+Common tasks for content filters are to eliminate common annoyances in HTML and
+JavaScript, such as pop-up windows, exit consoles, crippled windows without
navigation tools, the infamous <BLINK> tag etc, to suppress images with certain
width and height attributes (standard banner sizes or web-bugs), or just to
have fun.
-Content filtering works on any text-based document type, including HTML,
-JavaScript, CSS etc. (all text/* MIME types, except text/plain). Substitutions
-are made at the source level, so if you want to "roll your own" filters, you
-should first be familiar with HTML syntax, and, of course, regular expressions.
+Enabled content filters are applied to any content whose "Content Type" header
+is recognised as a sign of text-based content, with the exception of text/
+plain. Use the force-text-mode action to also filter other content.
+
+Substitutions are made at the source level, so if you want to "roll your own"
+filters, you should first be familiar with HTML syntax, and, of course, regular
+expressions.
Just like the actions files, the filter file is organized in sections, which
are called filters here. Each filter consists of a heading line, that starts
Remember to flush caches! Note that the mail.google reference lacks the TLD
-portion (e.g. ".com". This will effectively match any TLD with google in it,
-such as mail.google.de, just as an example.
+portion (e.g. ".com"). This will effectively match any TLD with google in it,
+such as mail.google.de., just as an example.
If this still does not work, you will have to go through the remaining actions
one by one to find which one(s) is causing the problem.
experience.</P
><P
> 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 <SPAN
+ no need to disable any actions here. (Remember: a <SPAN
CLASS="QUOTE"
>"+"</SPAN
>
# "Defaults" section:
##########################################################################
{ \
- -<A
-HREF="actions-file.html#ADD-HEADER"
->add-header</A
-> \
- -<A
-HREF="actions-file.html#CLIENT-HEADER-FILTER"
->client-header-filter{hide-tor-exit-notation}</A
-> \
- -<A
-HREF="actions-file.html#BLOCK"
->block</A
-> \
- -<A
-HREF="actions-file.html#CONTENT-TYPE-OVERWRITE"
->content-type-overwrite</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-CLIENT-HEADER"
->crunch-client-header</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-IF-NONE-MATCH"
->crunch-if-none-match</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
->crunch-incoming-cookies</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-SERVER-HEADER"
->crunch-server-header</A
-> \
- -<A
-HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
->crunch-outgoing-cookies</A
-> \
+<A
HREF="actions-file.html#DEANIMATE-GIFS"
>deanimate-gifs</A
-> \
- -<A
-HREF="actions-file.html#DOWNGRADE-HTTP-VERSION"
->downgrade-http-version</A
-> \
- -<A
-HREF="actions-file.html#FAST-REDIRECTS"
->fast-redirects{check-decoded-url}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-JS-ANNOYANCES"
->filter{js-annoyances}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-JS-EVENTS"
->filter{js-events}</A
> \
+<A
HREF="actions-file.html#FILTER-HTML-ANNOYANCES"
>filter{html-annoyances}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-CONTENT-COOKIES"
->filter{content-cookies}</A
> \
+<A
HREF="actions-file.html#FILTER-REFRESH-TAGS"
>filter{refresh-tags}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-UNSOLICITED-POPUPS"
->filter{unsolicited-popups}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-ALL-POPUPS"
->filter{all-popups}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-IMG-REORDER"
->filter{img-reorder}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-BANNERS-BY-SIZE"
->filter{banners-by-size}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-BANNERS-BY-LINK"
->filter{banners-by-link}</A
> \
+<A
HREF="actions-file.html#FILTER-WEBBUGS"
>filter{webbugs}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-TINY-TEXTFORMS"
->filter{tiny-textforms}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-JUMPING-WINDOWS"
->filter{jumping-windows}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-FRAMESET-BORDERS"
->filter{frameset-borders}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-DEMORONIZER"
->filter{demoronizer}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-SHOCKWAVE-FLASH"
->filter{shockwave-flash}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-QUICKTIME-KIOSKMODE"
->filter{quicktime-kioskmode}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-FUN"
->filter{fun}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-CRUDE-PARENTAL"
->filter{crude-parental}</A
> \
+<A
HREF="actions-file.html#FILTER-IE-EXPLOITS"
>filter{ie-exploits}</A
> \
- -<A
-HREF="actions-file.html#FILTER-GOOGLE"
->filter{google}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-YAHOO"
->filter{yahoo}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-MSN"
->filter{msn}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-BLOGSPOT"
->filter{blogspot}</A
-> \
- -<A
-HREF="actions-file.html#FILTER-NO-PING"
->filter{no-ping}</A
-> \
- -<A
-HREF="actions-file.html#FORCE-TEXT-MODE"
->force-text-mode</A
-> \
- -<A
-HREF="actions-file.html#HANDLE-AS-EMPTY-DOCUMENT"
->handle-as-empty-document</A
-> \
- -<A
-HREF="actions-file.html#HANDLE-AS-IMAGE"
->handle-as-image</A
-> \
- -<A
-HREF="actions-file.html#HIDE-ACCEPT-LANGUAGE"
->hide-accept-language</A
-> \
- -<A
-HREF="actions-file.html#HIDE-CONTENT-DISPOSITION"
->hide-content-disposition</A
-> \
- -<A
-HREF="actions-file.html#HIDE-IF-MODIFIED-SINCE"
->hide-if-modified-since</A
-> \
+<A
HREF="actions-file.html#HIDE-FORWARDED-FOR-HEADERS"
>hide-forwarded-for-headers</A
+<A
HREF="actions-file.html#HIDE-REFERER"
>hide-referrer{forge}</A
-> \
- -<A
-HREF="actions-file.html#HIDE-USER-AGENT"
->hide-user-agent</A
-> \
- -<A
-HREF="actions-file.html#INSPECT-JPEGS"
->inspect-jpegs</A
-> \
- -<A
-HREF="actions-file.html#KILL-POPUPS"
->kill-popups</A
-> \
- -<A
-HREF="actions-file.html#LIMIT-CONNECT"
->limit-connect</A
> \
+<A
HREF="actions-file.html#PREVENT-COMPRESSION"
>prevent-compression</A
-> \
- -<A
-HREF="actions-file.html#OVERWRITE-LAST-MODIFIED"
->overwrite-last-modified</A
-> \
- -<A
-HREF="actions-file.html#REDIRECT"
->redirect</A
-> \
- -<A
-HREF="actions-file.html#SEND-VANILLA-WAFER"
->send-vanilla-wafer</A
-> \
- -<A
-HREF="actions-file.html#SEND-WAFER"
->send-wafer</A
-> \
- -<A
-HREF="actions-file.html#SERVER-HEADER-FILTER"
->server-header-filter{xml-to-html}</A
-> \
- -<A
-HREF="actions-file.html#SERVER-HEADER-FILTER"
->server-header-filter{html-to-xml}</A
> \
+<A
HREF="actions-file.html#SESSION-COOKIES-ONLY"
+<A
HREF="actions-file.html#SET-IMAGE-BLOCKER"
>set-image-blocker{pattern}</A
-> \
- -<A
-HREF="actions-file.html#TREAT-FORBIDDEN-CONNECTS-LIKE-BLOCKS"
->treat-forbidden-connects-like-blocks</A
> \
}
/ # forward slash will match *all* potential URL patterns.</PRE
></TABLE
></P
><P
-> The default behavior is now set. Note that some actions, like not hiding
- the user agent, are part of a <SPAN
-CLASS="QUOTE"
->"general policy"</SPAN
-> that applies
- universally and won't get any exceptions defined later. Other choices,
- like not blocking (which is <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->understandably</I
-></SPAN
-> the
- default!) need exceptions, i.e. we need to specify explicitly what we
- want to block in later sections.</P
+> The default behavior is now set.
+ </P
><P
> The first of our specialized sections is concerned with <SPAN
CLASS="QUOTE"
><H3
CLASS="SECT3"
><A
-NAME="AEN4484"
+NAME="AEN4433"
>8.7.2. user.action</A
></H3
><P
><TD
><PRE
CLASS="SCREEN"
-># My user.action file. <fred@foobar.com></PRE
+># My user.action file. <fred@example.com></PRE
></TD
></TR
></TABLE
>block</A
> }
www.example.com/nasty-ads/sponsor\.gif
- another.popular.site.net/more/junk/here/</PRE
+ another.example.net/more/junk/here/</PRE
></TD
></TR
></TABLE
CLASS="FILENAME"
>default.filter</TT
>,
- 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,
+ but it is disabled in the distributed actions file.
+ So you'd like to turn it on in your private,
update-safe config, once and for all:</P
><P
><TABLE
><H2
CLASS="SECT2"
><A
-NAME="AEN5368"
+NAME="AEN5318"
>14.2. Privoxy's Internal Pages</A
></H2
><P
Privoxy main page:
</P
><A
-NAME="AEN5382"
+NAME="AEN5332"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
editing of actions files:
</P
><A
-NAME="AEN5390"
+NAME="AEN5340"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
Show the source code version numbers:
</P
><A
-NAME="AEN5395"
+NAME="AEN5345"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
Show the browser's request headers:
</P
><A
-NAME="AEN5400"
+NAME="AEN5350"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
Show which actions apply to a URL and why:
</P
><A
-NAME="AEN5405"
+NAME="AEN5355"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
place:
</P
><A
-NAME="AEN5413"
+NAME="AEN5363"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
> Short cuts. Turn off, then on:
</P
><A
-NAME="AEN5417"
+NAME="AEN5367"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
</P
></BLOCKQUOTE
><A
-NAME="AEN5420"
+NAME="AEN5370"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><H2
CLASS="SECT2"
><A
-NAME="AEN5111"
+NAME="AEN5061"
>12.1. License</A
></H2
><P
>server-header-filter</A
></TT
>
- to rewrite headers that are send by the server, and</P
+ to rewrite headers that are send by the server.</P
><P
> <SPAN
CLASS="APPLICATION"
>filterfile</A
></TT
> config directive. The filters
- as supplied by the developers will be found in
+ as supplied by the developers are located in
<TT
CLASS="FILENAME"
>default.filter</TT
>.
</P
><P
-> Command tasks for content filters are to eliminate common annoyances in
+> Common tasks for content filters are to eliminate common annoyances in
HTML and JavaScript, such as pop-up windows,
exit consoles, crippled windows without navigation tools, the
infamous <BLINK> tag etc, to suppress images with certain
width and height attributes (standard banner sizes or web-bugs),
or just to have fun.</P
><P
-> Content filtering works on any text-based document type, including
- HTML, JavaScript, CSS etc. (all <TT
-CLASS="LITERAL"
->text/*</TT
->
- MIME types, <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->except</I
-></SPAN
-> <TT
+> Enabled content filters are applied to any content whose
+ <SPAN
+CLASS="QUOTE"
+>"Content Type"</SPAN
+> header is recognised as a sign
+ of text-based content, with the exception of <TT
CLASS="LITERAL"
>text/plain</TT
->).
- Substitutions are made at the source level, so if you want to <SPAN
+>.
+ Use the <A
+HREF="actions-file.html#FORCE-TEXT-MODE"
+>force-text-mode</A
+> action
+ to also filter other content.</P
+><P
+> Substitutions are made at the source level, so if you want to <SPAN
CLASS="QUOTE"
>"roll
your own"</SPAN
><H2
CLASS="SECT2"
><A
-NAME="AEN4638"
+NAME="AEN4588"
>9.1. Filter File Tutorial</A
></H2
><P
><BR></P
><P
CLASS="PUBDATE"
->$Id: user-manual.sgml,v 2.44 2007/11/15 03:30:20 hal9 Exp $<BR></P
+>$Id: user-manual.sgml,v 2.46 2007/11/17 17:24:44 fabiankeil Exp $<BR></P
><DIV
><DIV
CLASS="ABSTRACT"
></DT
><DT
>8.7.2. <A
-HREF="actions-file.html#AEN4484"
+HREF="actions-file.html#AEN4433"
>user.action</A
></DT
></DL
><DL
><DT
>9.1. <A
-HREF="filter-file.html#AEN4638"
+HREF="filter-file.html#AEN4588"
>Filter File Tutorial</A
></DT
><DT
><DL
><DT
>12.1. <A
-HREF="copyright.html#AEN5111"
+HREF="copyright.html#AEN5061"
>License</A
></DT
><DT
></DT
><DT
>14.2. <A
-HREF="appendix.html#AEN5368"
+HREF="appendix.html#AEN5318"
>Privoxy's Internal Pages</A
></DT
><DD