+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Filter Files</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
-TITLE="Privoxy 3.0.5 User Manual"
+TITLE="Privoxy 3.0.9 User Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Actions Files"
HREF="templates.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
-HREF="../p_doc.css">
+HREF="../p_doc.css"><META
+HTTP-EQUIV="Content-Type"
+CONTENT="text/html;
+charset=ISO-8859-1">
<LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css">
</head
><BODY
><TH
COLSPAN="3"
ALIGN="center"
->Privoxy 3.0.5 User Manual</TH
+>Privoxy 3.0.9 User Manual</TH
></TR
><TR
><TD
CLASS="SECT1"
><A
NAME="FILTER-FILE"
-></A
->9. Filter Files</H1
+>9. Filter Files</A
+></H1
><P
-> On-the-fly text substitutions that can be invoked through the
- <TT
-CLASS="LITERAL"
-><A
-HREF="actions-file.html#FILTER"
->filter</A
-></TT
-> action need
+> On-the-fly text substitutions need
to be defined in a <SPAN
CLASS="QUOTE"
>"filter file"</SPAN
can then be invoked as an <SPAN
CLASS="QUOTE"
>"action"</SPAN
->. Multiple filter files can be
- defined through the <TT
+>.</P
+><P
+> <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> supports three different filter actions:
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#FILTER"
+>filter</A
+></TT
+> to
+ rewrite the content that is send to the client,
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CLIENT-HEADER-FILTER"
+>client-header-filter</A
+></TT
+>
+ to rewrite headers that are send by the client, and
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#SERVER-HEADER-FILTER"
+>server-header-filter</A
+></TT
+>
+ to rewrite headers that are send by the server.</P
+><P
+> <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> also supports two tagger actions:
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#CLIENT-HEADER-TAGGER"
+>client-header-tagger</A
+></TT
+>
+ and
+ <TT
+CLASS="LITERAL"
+><A
+HREF="actions-file.html#SERVER-HEADER-TAGGER"
+>server-header-tagger</A
+></TT
+>.
+ Taggers and filters use the same syntax in the filter files, the difference
+ is that taggers don't modify the text they are filtering, but use a rewritten
+ version of the filtered text as tag. The tags can then be used to change the
+ applying actions through sections with <A
+HREF="actions-file.html#TAG-PATTERN"
+>tag-patterns</A
+>.</P
+><P
+> Multiple filter files can be defined through the <TT
CLASS="LITERAL"
> <A
HREF="config.html#FILTERFILE"
>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
-> Typical reasons for doing these kinds of substitutions are to eliminate
- common annoyances in HTML and JavaScript, such as pop-up windows,
+> 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. The possibilities are endless.</P
+ or just to have fun.</P
><P
-> 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
> filters, you should first be familiar with HTML syntax,
- and, of course, regular expressions. By default, filters are only applied
- to the raw document content, but can be extended to the HTTP headers with
- the supplemental actions:
- <A
-HREF="actions-file.html#FILTER-CLIENT-HEADERS"
->filter-client-headers</A
-> and
- <A
-HREF="actions-file.html#FILTER-SERVER-HEADERS"
->filter-server-headers</A
->.</P
+ and, of course, regular expressions.</P
><P
> Just like the <A
HREF="actions-file.html"
>filters</I
></SPAN
>
- here. Each filter consists of a heading line, that starts with the
+ here. Each filter consists of a heading line, that starts with one of the
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
->keyword</I
+>keywords</I
></SPAN
> <TT
CLASS="LITERAL"
>FILTER:</TT
->, followed by
- the filter's <SPAN
+>,
+ <TT
+CLASS="LITERAL"
+>CLIENT-HEADER-FILTER:</TT
+> or <TT
+CLASS="LITERAL"
+>SERVER-HEADER-FILTER:</TT
+>
+ followed by the filter's <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>actions file</A
>.</P
><P
-> A filter header line for a filter called <SPAN
+> Filter definitions start with a header line that contains the filter
+ type, the filter name and the filter description.
+ A content filter header line for a filter called <SPAN
CLASS="QUOTE"
>"foo"</SPAN
> could look
><H2
CLASS="SECT2"
><A
-NAME="AEN4271"
-></A
->9.1. Filter File Tutorial</H2
+NAME="AEN4439"
+>9.1. Filter File Tutorial</A
+></H2
><P
> Now, let's complete our <SPAN
CLASS="QUOTE"
>"foo"</SPAN
-> filter. We have already defined
+> content filter. We have already defined
the heading, but the jobs are still missing. Since all it does is to replace
<SPAN
CLASS="QUOTE"
CLASS="SECT2"
><A
NAME="PREDEFINED-FILTERS"
-></A
->9.2. The Pre-defined Filters</H2
+>9.2. The Pre-defined Filters</A
+></H2
><P
>The distribution <TT
CLASS="FILENAME"
></UL
>
</P
+><P
+> Use with caution. This is an aggressive filter, and can break sites that
+ rely heavily on JavaScript.
+ </P
></DD
><DT
><SPAN
><P
> This is a very radical measure. It removes virtually all JavaScript event bindings, which
means that scripts can not react to user actions such as mouse movements or clicks, window
- resizing etc, anymore.
+ resizing etc, anymore. Use with caution!
</P
><P
> We <SPAN
to sneak cookies to the browser on the content level.
</P
><P
-> This filter disables HTML and JavaScript code that reads or sets cookies. Use
- it wherever you would also use the cookie crunch actions.
+> This filter disables most HTML and JavaScript code that reads or sets
+ cookies. It cannot detect all clever uses of these types of code, so it
+ should not be relied on as an absolute fix. Use it wherever you would also
+ use the cookie crunch actions.
</P
></DD
><DT
</P
><P
> Technical note: The filter works by redefining the window.open JavaScript
- function to a dummy function during the loading and rendering phase of each
- HTML page access, and restoring the function afterward.
+ function to a dummy function, <TT
+CLASS="LITERAL"
+>PrivoxyWindowOpen()</TT
+>,
+ during the loading and rendering phase of each HTML page access, and
+ restoring the function afterward.
+ </P
+><P
+> This is recommended only for browsers that cannot perform this function
+ reliably themselves. And be aware that some sites require such windows
+ in order to function normally. Use with caution.
</P
></DD
><DT
>all</I
></SPAN
> pop-up windows from opening.
- Note this should be used with more discretion than the above, since it is
- more likely to break some sites that require pop-ups for normal usage. Use
- with caution.
+ Note this should be used with even more discretion than the above, since
+ it is more likely to break some sites that require pop-ups for normal
+ usage. Use with caution.
</P
></DD
><DT
> Occasionally this filter will cause false positives on images that are not ads,
but just happen to be of one of the standard banner sizes.
</P
+><P
+> Recommended only for those who require extreme ad blocking. The default
+ block rules should catch 95+% of all ads <SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>without</I
+></SPAN
+> this filter enabled.
+ </P
></DD
><DT
><SPAN
As an HTML page is loaded by the browser, an embedded image tag causes the
browser to contact a third-party site, disclosing the tracking information
through the requested URL and/or cookies for that third-party domain, without
- the use ever becoming aware of the interaction with the third-party site.
+ the user ever becoming aware of the interaction with the third-party site.
HTML-ized spam also uses a similar technique to verify email addresses.
</P
><P
><P
> Many consider windows that move, or resize themselves to be abusive. This filter
neutralizes the related JavaScript code. Note that some sites might not display
- or behave as intended when using this filter.
+ or behave as intended when using this filter. Use with caution.
</P
></DD
><DT
></DT
><DD
><P
-> A collection of text replacements to disable malicious HTML and JavaScript
+> An experimental collection of text replacements to disable malicious HTML and JavaScript
code that exploits known security holes in Internet Explorer.
</P
><P
anything regarding this filter.
</P
></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>google</I
+></SPAN
+></DT
+><DD
+><P
+> A CSS based block for Google text ads. Also removes a width limitation
+ and the toolbar advertisement.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>yahoo</I
+></SPAN
+></DT
+><DD
+><P
+> Another CSS based block, this time for Yahoo text ads. And removes
+ a width limitation as well.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>msn</I
+></SPAN
+></DT
+><DD
+><P
+> Another CSS based block, this time for MSN text ads. And removes
+ tracking URLs, as well as a width limitation.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>blogspot</I
+></SPAN
+></DT
+><DD
+><P
+> Cleans up some Blogspot blogs. Read the fine print before using this one!
+ </P
+><P
+> This filter also intentionally removes some navigation stuff and sets the
+ page width to 100%. As a result, some rounded <SPAN
+CLASS="QUOTE"
+>"corners"</SPAN
+> would
+ appear to early or not at all and as fixing this would require a browser
+ that understands background-size (CSS3), they are removed instead.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>xml-to-html</I
+></SPAN
+></DT
+><DD
+><P
+> Server-header filter to change the Content-Type from xml to html.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>html-to-xml</I
+></SPAN
+></DT
+><DD
+><P
+> Server-header filter to change the Content-Type from html to xml.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>no-ping</I
+></SPAN
+></DT
+><DD
+><P
+> Removes the non-standard <TT
+CLASS="LITERAL"
+>ping</TT
+> attribute from
+ anchor and area HTML tags.
+ </P
+></DD
+><DT
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>hide-tor-exit-notation</I
+></SPAN
+></DT
+><DD
+><P
+> Client-header filter to remove the <B
+CLASS="COMMAND"
+>Tor</B
+> exit node notation
+ found in Host and Referer headers.
+ </P
+><P
+> If <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+> and <B
+CLASS="COMMAND"
+>Tor</B
+> are chained and <SPAN
+CLASS="APPLICATION"
+>Privoxy</SPAN
+>
+ is configured to use socks4a, one can use <SPAN
+CLASS="QUOTE"
+>"http://www.example.org.foobar.exit/"</SPAN
+>
+ to access the host <SPAN
+CLASS="QUOTE"
+>"www.example.org"</SPAN
+> through the
+ <B
+CLASS="COMMAND"
+>Tor</B
+> exit node <SPAN
+CLASS="QUOTE"
+>"foobar"</SPAN
+>.
+ </P
+><P
+> As the HTTP client isn't aware of this notation, it treats the
+ whole string <SPAN
+CLASS="QUOTE"
+>"www.example.org.foobar.exit"</SPAN
+> as host and uses it
+ for the <SPAN
+CLASS="QUOTE"
+>"Host"</SPAN
+> and <SPAN
+CLASS="QUOTE"
+>"Referer"</SPAN
+> headers. From the
+ server's point of view the resulting headers are invalid and can cause problems.
+ </P
+><P
+> An invalid <SPAN
+CLASS="QUOTE"
+>"Referer"</SPAN
+> header can trigger <SPAN
+CLASS="QUOTE"
+>"hot-linking"</SPAN
+>
+ protections, an invalid <SPAN
+CLASS="QUOTE"
+>"Host"</SPAN
+> header will make it impossible for
+ the server to find the right vhost (several domains hosted on the same IP address).
+ </P
+><P
+> This client-header filter removes the <SPAN
+CLASS="QUOTE"
+>"foo.exit"</SPAN
+> part in those headers
+ to prevent the mentioned problems. Note that it only modifies
+ the HTTP headers, it doesn't make it impossible for the server
+ to detect your <B
+CLASS="COMMAND"
+>Tor</B
+> exit node based on the IP address
+ the request is coming from.
+ </P
+></DD
></DL
></DIV
></DIV
projects / privoxy.git / blobdiff