- <anchor id="filter-msn">
- <screen>+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
- </para>
- <para>
- <anchor id="filter-blogspot">
- <screen>+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="force-text-mode">
-<title>force-text-mode</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format. </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- As explained <literal><link linkend="filter">above</link></literal>,
- <application>Privoxy</application> tries to only filter files that are
- in some kind of text format. The same restrictions apply to
- <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
- <literal>force-text-mode</literal> declares a document as text,
- without looking at the <quote>Content-Type:</quote> first.
- </para>
- <warning>
- <para>
- Think twice before activating this action. Filtering binary data
- with regular expressions can cause file damage.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>
-+force-text-mode
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="forward-override">
-<title>forward-override</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Change the forwarding settings based on User-Agent or request origin</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Overrules the forward directives in the configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Multi-value.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para><quote>forward .</quote> to use a direct connection without any additional proxies.</para>
- </listitem>
- <listitem>
- <para>
- <quote>forward 127.0.0.1:8123</quote> to use the HTTP proxy listening at 127.0.0.1 port 8123.
- </para>
- </listitem>
- <listitem>
- <para>
- <quote>forward-socks4a 127.0.0.1:9050 .</quote> to use the socks4a proxy listening at
- 127.0.0.1 port 9050. Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote>
- to use a socks4 connection (with local DNS resolution) instead, use <quote>forward-socks5</quote>
- for socks5 connections (with remote DNS resolution).
- </para>
- </listitem>
- <listitem>
- <para>
- <quote>forward-socks4a 127.0.0.1:9050 proxy.example.org:8000</quote> to use the socks4a proxy
- listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
- Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection
- (with local DNS resolution) instead, use <quote>forward-socks5</quote>
- for socks5 connections (with remote DNS resolution).
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This action takes parameters similar to the
- <link linkend="forwarding">forward</link> directives in the configuration
- file, but without the URL pattern. It can be used as replacement, but normally it's only
- used in cases where matching based on the request URL isn't sufficient.
- </para>
- <warning>
- <para>
- Please read the description for the <link linkend="forwarding">forward</link> directives before
- using this action. Forwarding to the wrong people will reduce your privacy and increase the
- chances of man-in-the-middle attacks.
- </para>
- <para>
- If the ports are missing or invalid, default values will be used. This might change
- in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
- to exit.
- </para>
- <para>
- Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
- to verify that your forward settings do what you thought the do.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>
-# Always use direct connections for requests previously tagged as
-# <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
-# resuming downloads continues to work.
-# This way you can continue to use Tor for your normal browsing,
-# without overloading the Tor network with your FreeBSD ports updates
-# or downloads of bigger files like ISOs.
-# Note that HTTP headers are easy to fake and therefore their
-# values are as (un)trustworthy as your clients and users.
-{+forward-override{forward .} \
- -hide-if-modified-since \
- -overwrite-last-modified \
-}
-TAG:^User-Agent: fetch libfetch/2\.0$
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="handle-as-empty-document">
-<title>handle-as-empty-document</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- This action alone doesn't do anything noticeable. It just marks URLs.
- If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
- the presence or absence of this mark decides whether an HTML <quote>BLOCKED</quote>
- page, or an empty document will be sent to the client as a substitute for the blocked content.
- The <emphasis>empty</emphasis> document isn't literally empty, but actually contains a single space.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Some browsers complain about syntax errors if JavaScript documents
- are blocked with <application>Privoxy's</application>
- default HTML page; this option can be used to silence them.
- And of course this action can also be used to eliminate the &my-app;
- BLOCKED message in frames.
- </para>
- <para>
- The content type for the empty document can be specified with
- <literal><link linkend="content-type-overwrite">content-type-overwrite{}</link></literal>,
- but usually this isn't necessary.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen># Block all documents on example.org that end with ".js",
-# but send an empty document instead of the usual HTML message.
-{+block{Blocked JavaScript} +handle-as-empty-document}
-example.org/.*\.js$
- </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="handle-as-image">
-<title>handle-as-image</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they do get blocked</emphasis>, rather than HTML pages)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- This action alone doesn't do anything noticeable. It just marks URLs as images.
- If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
- the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
- page, or a replacement image (as determined by the <literal><link
- linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
- client as a substitute for the blocked content.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The below generic example section is actually part of <filename>default.action</filename>.
- It marks all URLs with well-known image file name extensions as images and should
- be left intact.
- </para>
- <para>
- Users will probably only want to use the handle-as-image action in conjunction with
- <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
- reflect the file type, like in the second example section.
- </para>
- <para>
- Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
- frames require an HTML page to be sent, or they won't display properly.
- Forcing <literal>handle-as-image</literal> in this situation will not replace the
- ad frame with an image, but lead to error messages.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (sections):</term>
- <listitem>
- <para>
- <screen># Generic image extensions:
-#
-{+handle-as-image}
-/.*\.(gif|jpg|jpeg|png|bmp|ico)$
-
-# These don't look like images, but they're banners and should be
-# blocked as images:
-#
-{+block{Nasty banners.} +handle-as-image}
-nasty-banner-server.example.com/junk.cgi\?output=trash
-</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="hide-accept-language">
-<title>hide-accept-language</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Pretend to use different language settings.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes or replaces the <quote>Accept-Language:</quote> HTTP header in client requests.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Keyword: <quote>block</quote>, or any user defined value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Faking the browser's language settings can be useful to make a
- foreign User-Agent set with
- <literal><link linkend="hide-user-agent">hide-user-agent</link></literal>
- more believable.
- </para>
- <para>
- However some sites with content in different languages check the
- <quote>Accept-Language:</quote> to decide which one to take by default.
- Sometimes it isn't possible to later switch to another language without
- changing the <quote>Accept-Language:</quote> header first.
- </para>
- <para>
- Therefore it's a good idea to either only change the
- <quote>Accept-Language:</quote> header to languages you understand,
- or to languages that aren't wide spread.
- </para>
- <para>
- Before setting the <quote>Accept-Language:</quote> header
- to a rare language, you should consider that it helps to
- make your requests unique and thus easier to trace.
- If you don't plan to change this header frequently,
- you should stick to a common language.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen># Pretend to use Canadian language settings.
-{+hide-accept-language{en-ca} \
-+hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
-}
-/ </screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="hide-content-disposition">
-<title>hide-content-disposition</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Prevent download menus for content you prefer to view inside the browser.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes or replaces the <quote>Content-Disposition:</quote> HTTP header set by some servers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Keyword: <quote>block</quote>, or any user defined value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Some servers set the <quote>Content-Disposition:</quote> HTTP header for
- documents they assume you want to save locally before viewing them.
- The <quote>Content-Disposition:</quote> header contains the file name
- the browser is supposed to use by default.
- </para>
- <para>
- In most browsers that understand this header, it makes it impossible to
- <emphasis>just view</emphasis> the document, without downloading it first,
- even if it's just a simple text file or an image.
- </para>
- <para>
- Removing the <quote>Content-Disposition:</quote> header helps
- to prevent this annoyance, but some browsers additionally check the
- <quote>Content-Type:</quote> header, before they decide if they can
- display a document without saving it first. In these cases, you have
- to change this header as well, before the browser stops displaying
- download menus.
- </para>
- <para>
- It is also possible to change the server's file name suggestion
- to another one, but in most cases it isn't worth the time to set
- it up.
- </para>
- <para>
- This action will probably be removed in the future,
- use server-header filters instead.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen># Disarm the download link in Sourceforge's patch tracker
-{ -filter \
- +content-type-overwrite{text/plain}\
- +hide-content-disposition{block} }
- .sourceforge.net/tracker/download\.php</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="hide-if-modified-since">
-<title>hide-if-modified-since</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Prevent yet another way to track the user's steps between sessions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes the <quote>If-Modified-Since:</quote> HTTP client header or modifies its value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Keyword: <quote>block</quote>, or a user defined value that specifies a range of hours.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Removing this header is useful for filter testing, where you want to force a real
- reload instead of getting status code <quote>304</quote>, which would cause the
- browser to use a cached copy of the page.
- </para>
- <para>
- Instead of removing the header, <literal>hide-if-modified-since</literal> can
- also add or subtract a random amount of time to/from the header's value.
- You specify a range of minutes where the random factor should be chosen from and
- <application>Privoxy</application> does the rest. A negative value means
- subtracting, a positive value adding.
- </para>
- <para>
- Randomizing the value of the <quote>If-Modified-Since:</quote> makes
- it less likely that the server can use the time as a cookie replacement,
- but you will run into caching problems if the random range is too high.
- </para>
- <para>
- It is a good idea to only use a small negative value and let
- <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
- handle the greater changes.
- </para>
- <para>
- It is also recommended to use this action together with
- <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>,
- otherwise it's more or less pointless.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen># Let the browser revalidate but make tracking based on the time less likely.
-{+hide-if-modified-since{-60} \
- +overwrite-last-modified{randomize} \
- +crunch-if-none-match}
-/</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="hide-from-header">
-<title>hide-from-header</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Keep your (old and ill) browser from telling web servers your email address</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
- specified string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Keyword: <quote>block</quote>, or any user defined value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The keyword <quote>block</quote> will completely remove the header
- (not to be confused with the <literal><link linkend="block">block</link></literal>
- action).
- </para>
- <para>
- Alternately, you can specify any value you prefer to be sent to the web
- server. If you do, it is a matter of fairness not to use any address that
- is actually used by a real person.
- </para>
- <para>
- This action is rarely needed, as modern web browsers don't send
- <quote>From:</quote> headers anymore.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+hide-from-header{block}</screen> or
- <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="hide-referrer">
-<title>hide-referrer</title>
-<anchor id="hide-referer">
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Conceal which link you followed to get to a particular site</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
- or replaces it with a forged one.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
- </listitem>
- <listitem>
- <para><quote>conditional-forge</quote> to forge the header if the host has changed.</para>
- </listitem>
- <listitem>
- <para><quote>block</quote> to delete the header unconditionally.</para>
- </listitem>
- <listitem>
- <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
- </listitem>
- <listitem>
- <para>Any other string to set a user defined referrer.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- <literal>conditional-block</literal> is the only parameter,
- that isn't easily detected in the server's log file. If it blocks the
- referrer, the request will look like the visitor used a bookmark or
- typed in the address directly.
- </para>
- <para>
- Leaving the referrer unmodified for requests on the same host
- allows the server owner to see the visitor's <quote>click path</quote>,
- but in most cases she could also get that information by comparing
- other parts of the log file: for example the User-Agent if it isn't
- a very common one, or the user's IP address if it doesn't change between
- different requests.
- </para>
- <para>
- Always blocking the referrer, or using a custom one, can lead to
- failures on servers that check the referrer before they answer any
- requests, in an attempt to prevent their content from being
- embedded or linked to elsewhere.
- </para>
- <para>
- Both <literal>conditional-block</literal> and <literal>forge</literal>
- will work with referrer checks, as long as content and valid referring page
- are on the same host. Most of the time that's the case.
- </para>
- <para>
- <literal>hide-referer</literal> is an alternate spelling of
- <literal>hide-referrer</literal> and the two can be can be freely
- substituted with each other. (<quote>referrer</quote> is the
- correct English spelling, however the HTTP specification has a bug - it
- requires it to be spelled as <quote>referer</quote>.)
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+hide-referrer{forge}</screen> or
- <screen>+hide-referrer{http://www.yahoo.com/}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="hide-user-agent">
-<title>hide-user-agent</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Try to conceal your type of browser and client operating system</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Replaces the value of the <quote>User-Agent:</quote> HTTP header
- in client requests with the specified value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- Any user-defined string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <warning>
- <para>
- This can lead to problems on web sites that depend on looking at this header in
- order to customize their content for different browsers (which, by the
- way, is <emphasis>NOT</emphasis> the right thing to do: good web sites
- work browser-independently).
- </para>
- </warning>
- <para>
- Using this action in multi-user setups or wherever different types of
- browsers will access the same <application>Privoxy</application> is
- <emphasis>not recommended</emphasis>. In single-user, single-browser
- setups, you might use it to delete your OS version information from
- the headers, because it is an invitation to exploit known bugs for your
- OS. It is also occasionally useful to forge this in order to access
- sites that won't let you in otherwise (though there may be a good
- reason in some cases).
- </para>
- <para>
- More information on known user-agent strings can be found at
- <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
- and
- <ulink url="http://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="limit-connect">
-<title>limit-connect</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay or disable SSL for untrusted sites</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Specifies to which ports HTTP CONNECT requests are allowable.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
- defaulting to 0 and the maximum to 65K).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- By default, i.e. if no <literal>limit-connect</literal> action applies,
- <application>Privoxy</application> allows HTTP CONNECT requests to all
- ports. Use <literal>limit-connect</literal> if fine-grained control
- is desired for some or all destinations.
- </para>
- <para>
- The CONNECT methods exists in HTTP to allow access to secure websites
- (<quote>https://</quote> URLs) through proxies. It works very simply:
- the proxy connects to the server on the specified port, and then
- short-circuits its connections to the client and to the remote server.
- This means CONNECT-enabled proxies can be used as TCP relays very easily.
- </para>
- <para>
- <application>Privoxy</application> relays HTTPS traffic without seeing
- the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
- filters. By specifying an invalid port range you can disable HTTPS entirely.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usages:</term>
- <listitem>
- <!-- I had trouble getting the spacing to look right in my browser -->
- <!-- I probably have the wrong font setup, bollocks. -->
- <!-- Apparently the emphasis tag uses a proportional font no matter what -->
- <para>
- <screen>+limit-connect{443} # Port 443 is OK.
-+limit-connect{80,443} # Ports 80 and 443 are OK.
-+limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
-+limit-connect{-} # All ports are OK
-+limit-connect{,} # No HTTPS/SSL traffic is allowed</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="prevent-compression">
-<title>prevent-compression</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Ensure that servers send the content uncompressed, so it can be
- passed through <literal><link linkend="filter">filter</link></literal>s.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Removes the Accept-Encoding header which can be used to ask for compressed transfer.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- More and more websites send their content compressed by default, which
- is generally a good idea and saves bandwidth. But the <literal><link
- linkend="filter">filter</link></literal> and
- <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
- actions need access to the uncompressed data.
- </para>
- <para>
- When compiled with zlib support (available since &my-app; 3.0.7), content that should be
- filtered is decompressed on-the-fly and you don't have to worry about this action.
- If you are using an older &my-app; version, or one that hasn't been compiled with zlib
- support, this action can be used to convince the server to send the content uncompressed.
- </para>
- <para>
- Most text-based instances compress very well, the size is seldom decreased by less than 50%,
- for markup-heavy instances like news feeds saving more than 90% of the original size isn't
- unusual.
- </para>
- <para>
- Not using compression will therefore slow down the transfer, and you should only
- enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all
- predefined action settings.
- </para>
- <para>
- Note that some (rare) ill-configured sites don't handle requests for uncompressed
- documents correctly. Broken PHP applications tend to send an empty document body,
- some IIS versions only send the beginning of the content. If you enable
- <literal>prevent-compression</literal> per default, you might want to add
- exceptions for those sites. See the example for how to do that.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (sections):</term>
- <listitem>
- <para>
- <screen>
-# Selectively turn off compression, and enable a filter
-#
-{ +filter{tiny-textforms} +prevent-compression }
-# Match only these sites
- .google.
- sourceforge.net
- sf.net
-
-# Or instead, we could set a universal default:
-#
-{ +prevent-compression }
- / # Match all sites
-
-# Then maybe make exceptions for broken sites:
-#
-{ -prevent-compression }
-.compusa.com/</screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="overwrite-last-modified">
-<title>overwrite-last-modified</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Prevent yet another way to track the user's steps between sessions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes the <quote>Last-Modified:</quote> HTTP server header or modifies its value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- One of the keywords: <quote>block</quote>, <quote>reset-to-request-time</quote>
- and <quote>randomize</quote>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Removing the <quote>Last-Modified:</quote> header is useful for filter
- testing, where you want to force a real reload instead of getting status
- code <quote>304</quote>, which would cause the browser to reuse the old
- version of the page.
- </para>
- <para>
- The <quote>randomize</quote> option overwrites the value of the
- <quote>Last-Modified:</quote> header with a randomly chosen time
- between the original value and the current time. In theory the server
- could send each document with a different <quote>Last-Modified:</quote>
- header to track visits without using cookies. <quote>Randomize</quote>
- makes it impossible and the browser can still revalidate cached documents.
- </para>
- <para>
- <quote>reset-to-request-time</quote> overwrites the value of the
- <quote>Last-Modified:</quote> header with the current time. You could use
- this option together with
- <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
- to further customize your random range.
- </para>
- <para>
- The preferred parameter here is <quote>randomize</quote>. It is safe
- to use, as long as the time settings are more or less correct.
- If the server sets the <quote>Last-Modified:</quote> header to the time
- of the request, the random range becomes zero and the value stays the same.
- Therefore you should later randomize it a second time with
- <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>,
- just to be sure.
- </para>
- <para>
- It is also recommended to use this action together with
- <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen># Let the browser revalidate without being tracked across sessions
-{ +hide-if-modified-since{-60} \
- +overwrite-last-modified{randomize} \
- +crunch-if-none-match}
-/</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="redirect">
-<title>redirect</title>
-<!--
-new action
--->
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Redirect requests to other sites.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Convinces the browser that the requested document has been moved
- to another location and the browser should get it from there.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- An absolute URL or a single pcrs command.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Requests to which this action applies are answered with a
- HTTP redirect to URLs of your choosing. The new URL is
- either provided as parameter, or derived by applying a
- single pcrs command to the original URL.
- </para>
- <para>
- This action will be ignored if you use it together with
- <literal><link linkend="block">block</link></literal>.
- It can be combined with
- <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
- to redirect to a decoded version of a rewritten URL.
- </para>
- <para>
- Use this action carefully, make sure not to create redirection loops
- and be aware that using your own redirects might make it
- possible to fingerprint your requests.
- </para>
- <para>
- In case of problems with your redirects, or simply to watch
- them working, enable <link linkend="DEBUG">debug 128</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usages:</term>
- <listitem>
- <para>
- <screen># Replace example.com's style sheet with another one
-{ +redirect{http://localhost/css-replacements/example.com.css} }
- example.com/stylesheet\.css
-
-# Create a short, easy to remember nickname for a favorite site
-# (relies on the browser accept and forward invalid URLs to &my-app;)
-{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
- a
-
-# Always use the expanded view for Undeadly.org articles
-# (Note the $ at the end of the URL pattern to make sure
-# the request for the rewritten URL isn't redirected as well)
-{+redirect{s@$@&mode=expanded@}}
-undeadly.org/cgi\?action=article&sid=\d*$
-
-# Redirect Google search requests to MSN
-{+redirect{s@^http://[^/]*/search\?q=([^&]*).*@http://search.msn.com/results.aspx?q=$1@}}
-.google.com/search
-
-# Redirect MSN search requests to Yahoo
-{+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}}
-search.msn.com//results\.aspx\?q=
-
-# Redirect remote requests for this manual
-# to the local version delivered by Privoxy
-{+redirect{s@^http://www@http://config@}}
-www.privoxy.org/user-manual/</screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="server-header-filter">
-<title>server-header-filter</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Rewrite or remove single server headers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- All server headers to which this action applies are filtered on-the-fly
- through the specified regular expression based substitutions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- The name of a server-header filter, as defined in one of the
- <link linkend="filter-file">filter files</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Server-header filters are applied to each header on its own, not to
- all at once. This makes it easier to diagnose problems, but on the downside
- you can't write filters that only change header x if header y's value is z.
- You can do that by using tags though.
- </para>
- <para>
- Server-header filters are executed after the other header actions have finished
- and use their output as input.
- </para>
- <para>
- Please refer to the <link linkend="filter-file">filter file chapter</link>
- to learn which server-header filters are available by default, and how to
- create your own.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen>
-{+server-header-filter{html-to-xml}}
-example.org/xml-instance-that-is-delivered-as-html
-
-{+server-header-filter{xml-to-html}}
-example.org/instance-that-is-delivered-as-xml-but-is-not
- </screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="server-header-tagger">
-<title>server-header-tagger</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Enable or disable filters based on the Content-Type header.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Server headers to which this action applies are filtered on-the-fly through
- the specified regular expression based substitutions, the result is used as
- tag.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- boolean, parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- The name of a server-header tagger, as defined in one of the
- <link linkend="filter-file">filter files</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- Server-header taggers are applied to each header on its own,
- and as the header isn't modified, each tagger <quote>sees</quote>
- the original.
- </para>
- <para>
- Server-header taggers are executed before all other header actions
- that modify server headers. Their tags can be used to control
- all of the other server-header actions, the content filters
- and the crunch actions (<link linkend="redirect">redirect</link>
- and <link linkend="block">block</link>).
- </para>
- <para>
- Obviously crunching based on tags created by server-header taggers
- doesn't prevent the request from showing up in the server's log file.
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage (section):</term>
- <listitem>
- <para>
- <screen>
-# Tag every request with the content type declared by the server
-{+server-header-tagger{content-type}}
-/
- </screen>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="session-cookies-only">
-<title>session-cookies-only</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>
- Allow only temporary <quote>session</quote> cookies (for the current
- browser session <emphasis>only</emphasis>).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote>
- server headers. Most browsers will not store such cookies permanently and
- forget them in between sessions.
- </para>
- </listitem>
- </varlistentry>
-
-<varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Boolean.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <para>
- N/A
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
- <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
- websites that insist or rely on setting cookies, without compromising your privacy too badly.
- </para>
- <para>
- Most browsers will not permanently store cookies that have been processed by
- <literal>session-cookies-only</literal> and will forget about them between sessions.
- This makes profiling cookies useless, but won't break sites which require cookies so
- that you can log in for transactions. This is generally turned on for all
- sites, and is the recommended setting.
- </para>
- <para>
- It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
- together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
- <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
- will be plainly killed.
- </para>
- <para>
- Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
- field. If you use an exotic browser, you might want to try it out to be sure.
- </para>
- <para>
- This setting also has no effect on cookies that may have been stored
- previously by the browser before starting <application>Privoxy</application>.
- These would have to be removed manually.
- </para>
- <para>
- <application>Privoxy</application> also uses
- the <link linkend="filter-content-cookies">content-cookies filter</link>
- to block some types of cookies. Content cookies are not effected by
- <literal>session-cookies-only</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- <screen>+session-cookies-only</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="set-image-blocker">
-<title>set-image-blocker</title>
-
-<variablelist>
- <varlistentry>
- <term>Typical use:</term>
- <listitem>
- <para>Choose the replacement for blocked images</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Effect:</term>
- <listitem>
- <para>
- This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
- <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
- linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
- apply, i.e. if the request is to be blocked as an image,
- <emphasis>then</emphasis> the parameter of this action decides what will be
- sent as a replacement.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Type:</term>
- <!-- Boolean, Parameterized, Multi-value -->
- <listitem>
- <para>Parameterized.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Parameter:</term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
- decent, scales very well, and makes it obvious where banners were busted.
- </para>
- </listitem>
- <listitem>
- <para>
- <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
- completely, but makes it hard to detect where <application>Privoxy</application> has blocked
- images on a given page and complicates troubleshooting if <application>Privoxy</application>
- has blocked innocent images, like navigation icons.
- </para>
- </listitem>
- <listitem>
- <para>
- <quote><replaceable class="parameter">target-url</replaceable></quote> to
- send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
- to any image anywhere, even in your local filesystem via <quote>file:///</quote> URL.
- (But note that not all browsers support redirecting to a local file system).
- </para>
- <para>
- A good application of redirects is to use special <application>Privoxy</application>-built-in
- URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
- This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
- the first place, but enables your browser to cache the replacement image, instead of requesting
- it over and over again.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Notes:</term>
- <listitem>
- <para>
- The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
- class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
- either <quote>blank</quote> or <quote>pattern</quote>.
- </para>
- <para>
- There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
- used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
- Auto will select the type of image that would have applied to the referring page, had it been an image.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Example usage:</term>
- <listitem>
- <para>
- Built-in pattern:
- </para>
- <para>
- <screen>+set-image-blocker{pattern}</screen>
- </para>
- <para>
- Redirect to the BSD daemon:
- </para>
- <para>
- <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
- </para>
- <para>
- Redirect to the built-in pattern for better caching:
- </para>
- <para>
- <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
-<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>
-</sect3>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="aliases">
-<title>Aliases</title>
-<para>
- Custom <quote>actions</quote>, known to <application>Privoxy</application>
- as <quote>aliases</quote>, can be defined by combining other actions.
- These can in turn be invoked just like the built-in actions.
- Currently, an alias name can contain any character except space, tab,
- <quote>=</quote>,
- <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
- recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
- <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
- Alias names are not case sensitive, and are not required to start with a
- <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
- expanded.
-</para>
-<para>
- Aliases can be used throughout the actions file, but they <emphasis>must be
- defined in a special section at the top of the file!</emphasis>
- And there can only be one such section per actions file. Each actions file may
- have its own alias section, and the aliases defined in it are only visible
- within that file.
-</para>
-<para>
- There are two main reasons to use aliases: One is to save typing for frequently
- used combinations of actions, the other one is a gain in flexibility: If you
- decide once how you want to handle shops by defining an alias called
- <quote>shop</quote>, you can later change your policy on shops in
- <emphasis>one</emphasis> place, and your changes will take effect everywhere
- in the actions file where the <quote>shop</quote> alias is used. Calling aliases
- by their purpose also makes your actions files more readable.
-</para>
-<para>
- Currently, there is one big drawback to using aliases, though:
- <application>Privoxy</application>'s built-in web-based action file
- editor honors aliases when reading the actions files, but it expands
- them before writing. So the effects of your aliases are of course preserved,
- but the aliases themselves are lost when you edit sections that use aliases
- with it.
-</para>
-
-<para>
- Now let's define some aliases...
-</para>
-
-<para>
- <screen>
- # Useful custom aliases we can use later.
- #
- # Note the (required!) section header line and that this section
- # must be at the top of the actions file!
- #
- {{alias}}
-
- # These aliases just save typing later:
- # (Note that some already use other aliases!)
- #
- +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
- -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
- +block-as-image = +block{Blocked image.} +handle-as-image
- allow-all-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
-
- # These aliases define combinations of actions
- # that are useful for certain types of sites:
- #
- fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="PREVENT-COMPRESSION">prevent-compression</link>
-
- shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link>
-
- # Short names for other aliases, for really lazy people ;-)
- #
- c0 = +crunch-all-cookies
- c1 = -crunch-all-cookies</screen>
-</para>
-
-<para>
- ...and put them to use. These sections would appear in the lower part of an
- actions file and define exceptions to the default actions (as specified further
- up for the <quote>/</quote> pattern):
-</para>
-
-<para>
- <screen>
- # These sites are either very complex or very keen on
- # user data and require minimal interference to work:
- #
- {fragile}
- .office.microsoft.com
- .windowsupdate.microsoft.com
- # Gmail is really mail.google.com, not gmail.com
- mail.google.com
-
- # Shopping sites:
- # Allow cookies (for setting and retrieving your customer data)
- #
- {shop}
- .quietpc.com
- .worldpay.com # for quietpc.com
- mybank.example.com
-
- # These shops require pop-ups:
- #
- {-filter{all-popups} -filter{unsolicited-popups}}
- .dabs.com
- .overclockers.co.uk</screen>
-</para>
-
-<para>
- Aliases like <quote>shop</quote> and <quote>fragile</quote> are typically used for
- <quote>problem</quote> sites that require more than one action to be disabled
- in order to function properly.
-</para>
-</sect2>
-<!--
-hal stop here
--->
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="act-examples">
-<title>Actions Files Tutorial</title>
-<para>
- The above chapters have shown <link linkend="actions-file">which actions files
- there are and how they are organized</link>, how actions are <link
- linkend="actions">specified</link> and <link linkend="actions-apply">applied
- to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
- define and use <link linkend="aliases">aliases</link>. Now, let's look at an
- example <filename>match-all.action</filename>, <filename>default.action</filename>
- and <filename>user.action</filename> file and see how all these pieces come together:
-</para>
-
-<sect3>
-<title>match-all.action</title>
-<para>
- Remember <emphasis>all actions are disabled when matching starts</emphasis>,
- so we have to explicitly enable the ones we want.
-</para>
-
-<para>
- While the <filename>match-all.action</filename> file only contains a
- single section, it is probably the most important one. It has only one
- pattern, <quote><literal>/</literal></quote>, but this pattern
- <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 other actions files like <filename>default.action</filename>
- and <filename>user.action</filename>, but it will still be largely responsible
- for your overall browsing experience.
-</para>
-
-<para>
- Again, at the start of matching, all actions are disabled, so there is
- no need to disable any actions here. (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>
-
-<para>
- <screen>
-{ \
- +<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
- +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
- +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
-}
-/ # Match all URLs
- </screen>
-</para>
-
-<para>
- The default behavior is now set.
-</para>
-</sect3>
-
-<sect3>
-<title>default.action</title>
-
-<para>
- If you aren't a developer, there's no need for you to edit the
- <filename>default.action</filename> file. It is maintained by
- the &my-app; developers and if you disagree with some of the
- sections, you should overrule them in your <filename>user.action</filename>.
-</para>
-
-<para>
- Understanding the <filename>default.action</filename> file can
- help you with your <filename>user.action</filename>, though.
-</para>
-
-<para>
- The first section in this file is a special section for internal use
- that prevents older &my-app; versions from reading the file:
-</para>
-
-<para>
- <screen>
-##########################################################################
-# Settings -- Don't change! For internal Privoxy use ONLY.
-##########################################################################
-{{settings}}
-for-privoxy-version=3.0.11</screen>
-</para>
-
-<para>
- After that comes the (optional) alias section. We'll use the example
- section from the above <link linkend="aliases">chapter on aliases</link>,
- that also explains why and how aliases are used:
-</para>
-
-<para>
- <screen>
-##########################################################################
-# Aliases
-##########################################################################
-{{alias}}
-
- # These aliases just save typing later:
- # (Note that some already use other aliases!)
- #
- +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
- -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
- +block-as-image = +block{Blocked image.} +handle-as-image
- mercy-for-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
-
- # These aliases define combinations of actions
- # that are useful for certain types of sites:
- #
- fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link>
- shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
-</para>
-
-<para>
- The first of our specialized sections is concerned with <quote>fragile</quote>
- sites, i.e. sites that require minimum interference, because they are either
- very complex or very keen on tracking you (and have mechanisms in place that
- make them unusable for people who avoid being tracked). We will simply use
- our pre-defined <literal>fragile</literal> alias instead of stating the list
- of actions explicitly:
-</para>
-
-<para>
- <screen>
-##########################################################################
-# Exceptions for sites that'll break under the default action set:
-##########################################################################
-
-# "Fragile" Use a minimum set of actions for these sites (see alias above):
-#
-{ fragile }
-.office.microsoft.com # surprise, surprise!
-.windowsupdate.microsoft.com
-mail.google.com</screen>
-</para>
-
-<para>
- Shopping sites are not as fragile, but they typically
- require cookies to log in, and pop-up windows for shopping
- carts or item details. Again, we'll use a pre-defined alias:
-</para>
-
-<para>
- <screen>
-# Shopping sites:
-#
-{ shop }
-.quietpc.com
-.worldpay.com # for quietpc.com
-.jungle.com
-.scan.co.uk</screen>
-</para>
-
-<para>
- The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
- action, which may have been enabled in <filename>match-all.action</filename>,
- breaks some sites. So disable it for popular sites where we know it misbehaves:
-</para>
-
-<para>
- <screen>
-{ -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
-login.yahoo.com
-edit.*.yahoo.com
-.google.com
-.altavista.com/.*(like|url|link):http
-.altavista.com/trans.*urltext=http
-.nytimes.com</screen>
-</para>
-
-<para>
- It is important that <application>Privoxy</application> knows which
- URLs belong to images, so that <emphasis>if</emphasis> they are to
- be blocked, a substitute image can be sent, rather than an HTML page.
- Contacting the remote site to find out is not an option, since it
- would destroy the loading time advantage of banner blocking, and it
- would feed the advertisers information about you. We can mark any
- URL as an image with the <literal><link
- linkend="handle-as-image">handle-as-image</link></literal> action,
- and marking all URLs that end in a known image file extension is a
- good start:
-</para>
-
-<para>
- <screen>
-##########################################################################
-# Images:
-##########################################################################
-
-# Define which file types will be treated as images, in case they get
-# blocked further down this file:
-#
-{ +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
-/.*\.(gif|jpe?g|png|bmp|ico)$</screen>
-</para>
-
-<para>
- And then there are known banner sources. They often use scripts to
- generate the banners, so it won't be visible from the URL that the
- request is for an image. Hence we block them <emphasis>and</emphasis>
- mark them as images in one go, with the help of our
- <literal>+block-as-image</literal> alias defined above. (We could of
- course just as well use <literal>+<link linkend="block">block</link>
- +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
- Remember that the type of the replacement image is chosen by the
- <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
- action. Since all URLs have matched the default section with its
- <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
- action before, it still applies and needn't be repeated:
-</para>
-
-<para>
- <screen>
-# Known ad generators:
-#
-{ +block-as-image }
-ar.atwola.com
-.ad.doubleclick.net
-.ad.*.doubleclick.net
-.a.yimg.com/(?:(?!/i/).)*$
-.a[0-9].yimg.com/(?:(?!/i/).)*$
-bs*.gsanet.com
-.qkimg.net</screen>
-</para>
-
-<para>
- One of the most important jobs of <application>Privoxy</application>
- is to block banners. Many of these can be <quote>blocked</quote>
- by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
- action, which we enabled above, and which deletes the references to banner
- images from the pages while they are loaded, so the browser doesn't request
- them anymore, and hence they don't need to be blocked here. But this naturally
- doesn't catch all banners, and some people choose not to use filters, so we
- need a comprehensive list of patterns for banner URLs here, and apply the
- <literal><link linkend="block">block</link></literal> action to them.
-</para>
-<para>
- First comes many generic patterns, which do most of the work, by
- matching typical domain and path name components of banners. Then comes
- a list of individual patterns for specific sites, which is omitted here
- to keep the example short:
-</para>
-
-<para>
- <screen>
-##########################################################################
-# Block these fine banners:
-##########################################################################
-{ <link linkend="BLOCK">+block{Banner ads.}</link> }
-
-# Generic patterns:
-#
-ad*.
-.*ads.
-banner?.
-count*.
-/.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
-/(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
-
-# Site-specific patterns (abbreviated):
-#
-.hitbox.com</screen>
-</para>
-
-<para>
- It's quite remarkable how many advertisers actually call their banner
- servers ads.<replaceable>company</replaceable>.com, or call the directory
- in which the banners are stored simply <quote>banners</quote>. So the above
- generic patterns are surprisingly effective.
-</para>
-<para>
- But being very generic, they necessarily also catch URLs that we don't want
- to block. The pattern <literal>.*ads.</literal> e.g. catches
- <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
- but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
- <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
- well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
- section above.
-</para>
-<para>
- Note that these are exceptions to exceptions from the default! Consider the URL
- <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
- so it wouldn't get blocked. Then comes the defaults section, which matches the
- URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
- action once again. Then it matches <literal>.*ads.</literal>, an exception to the
- general non-blocking policy, and suddenly
- <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
- <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
- applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
- with no <literal><link linkend="BLOCK">block</link></literal> action applying.
-</para>
-
-<para>
- <screen>
-##########################################################################
-# Save some innocent victims of the above generic block patterns:
-##########################################################################
-
-# By domain:
-#
-{ -<link linkend="BLOCK">block</link> }
-adv[io]*. # (for advogato.org and advice.*)
-adsl. # (has nothing to do with ads)
-adobe. # (has nothing to do with ads either)
-ad[ud]*. # (adult.* and add.*)
-.edu # (universities don't host banners (yet!))
-.*loads. # (downloads, uploads etc)
-
-# By path:
-#
-/.*loads/
-
-# Site-specific:
-#
-www.globalintersec.com/adv # (adv = advanced)
-www.ugu.com/sui/ugu/adv</screen>
-</para>
-
-<para>
- Filtering source code can have nasty side effects,
- so make an exception for our friends at sourceforge.net,
- and all paths with <quote>cvs</quote> in them. Note that
- <literal>-<link linkend="FILTER">filter</link></literal>
- disables <emphasis>all</emphasis> filters in one fell swoop!
-</para>
-
-<para>
- <screen>
-# Don't filter code!
-#
-{ -<link linkend="FILTER">filter</link> }
-/(.*/)?cvs
-bugzilla.
-developer.
-wiki.
-.sourceforge.net</screen>
-</para>
-
-<para>
- The actual <filename>default.action</filename> is of course much more
- comprehensive, but we hope this example made clear how it works.
-</para>
-
-</sect3>
-
-<sect3><title>user.action</title>
-
-<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 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
- actions files and hence has the last word, over-riding any previously
- defined actions. <filename>user.action</filename> is also a
- <emphasis>safe</emphasis> place for your personal settings, since
- <filename>default.action</filename> is actively maintained by the
- <application>Privoxy</application> developers and you'll probably want
- to install updated versions from time to time.
-</para>
-
-<para>
- So let's look at a few examples of things that one might typically do in
- <filename>user.action</filename>:
-</para>
-
-
-<!-- brief sample user.action here -->
-
-<para>
- <screen>
-# My user.action file. <fred@example.com></screen>
-</para>
-
-<para>
- As <link linkend="aliases">aliases</link> are local to the actions
- file that they are defined in, you can't use the ones from
- <filename>default.action</filename>, unless you repeat them here:
-</para>
-
-<para>
- <screen>
-# Aliases are local to the file they are defined in.
-# (Re-)define aliases for this file:
-#
-{{alias}}
-#
-# These aliases just save typing later, and the alias names should
-# be self explanatory.
-#
-+crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
--crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
- allow-all-cookies = -crunch-all-cookies -session-cookies-only
- allow-popups = -filter{all-popups}
-+block-as-image = +block{Blocked as image.} +handle-as-image
--block-as-image = -block
-
-# These aliases define combinations of actions that are useful for
-# certain types of sites:
-#
-fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
-shop = -crunch-all-cookies allow-popups
-
-# Allow ads for selected useful free sites:
-#
-allow-ads = -block -filter{banners-by-size} -filter{banners-by-link}
-
-# Alias for specific file types that are text, but might have conflicting
-# MIME types. We want the browser to force these to be text documents.
-handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
-
-</para>
-
-<para>
- Say you have accounts on some sites that you visit regularly, and
- you don't want to have to log in manually each time. So you'd like
- to allow persistent cookies for these sites. The
- <literal>allow-all-cookies</literal> alias defined above does exactly
- that, i.e. it disables crunching of cookies in any direction, and the
- processing of cookies to make them only temporary.
-</para>
-
-<para>
- <screen>
-{ allow-all-cookies }
- sourceforge.net
- .yahoo.com
- .msdn.microsoft.com
- .redhat.com</screen>
-</para>
-
-<para>
- Your bank is allergic to some filter, but you don't know which, so you disable them all:
-</para>
-
-<para>
- <screen>
-{ -<link linkend="FILTER">filter</link> }
- .your-home-banking-site.com</screen>
-</para>
-
-<para>
- Some file types you may not want to filter for various reasons:
-</para>
-
-<para>
- <screen>
-# Technical documentation is likely to contain strings that might
-# erroneously get altered by the JavaScript-oriented filters:
-#
-.tldp.org
-/(.*/)?selfhtml/
-
-# And this stupid host sends streaming video with a wrong MIME type,
-# so that Privoxy thinks it is getting HTML and starts filtering:
-#
-stupid-server.example.com/</screen>
-</para>
-
-<para>
- Example of a simple <link linkend="BLOCK">block</link> action. Say you've
- seen an ad on your favourite page on example.com that you want to get rid of.
- You have right-clicked the image, selected <quote>copy image location</quote>
- and pasted the URL below while removing the leading http://, into a
- <literal>{ +block{} }</literal> section. Note that <literal>{ +handle-as-image
- }</literal> need not be specified, since all URLs ending in
- <literal>.gif</literal> will be tagged as images by the general rules as set
- in default.action anyway:
-</para>
-
-<para>
- <screen>
-{ +<link linkend="BLOCK">block</link>{Nasty ads.} }
- www.example.com/nasty-ads/sponsor\.gif
- another.example.net/more/junk/here/</screen>
-</para>
-
-<para>
- The URLs of dynamically generated banners, especially from large banner
- farms, often don't use the well-known image file name extensions, which
- makes it impossible for <application>Privoxy</application> to guess
- the file type just by looking at the URL.
- You can use the <literal>+block-as-image</literal> alias defined above for
- these cases.
- Note that objects which match this rule but then turn out NOT to be an
- image are typically rendered as a <quote>broken image</quote> icon by the
- browser. Use cautiously.
-</para>
-
-<para>
- <screen>
-{ +block-as-image }
- .doubleclick.net
- .fastclick.net
- /Realmedia/ads/
- ar.atwola.com/</screen>
-</para>
-
-<para>
- Now you noticed that the default configuration breaks Forbes Magazine,
- but you were too lazy to find out which action is the culprit, and you
- were again too lazy to give <link linkend="contact">feedback</link>, so
- you just used the <literal>fragile</literal> alias on the site, and
- -- <emphasis>whoa!</emphasis> -- it worked. The <literal>fragile</literal>
- aliases disables those actions that are most likely to break a site. Also,
- good for testing purposes to see if it is <application>Privoxy</application>
- that is causing the problem or not. We later find other regular sites
- that misbehave, and add those to our personalized list of troublemakers:
-</para>
-
-<para>
-<screen>
-{ fragile }
- .forbes.com
- webmail.example.com
- .mybank.com</screen>
-</para>
-
-<para>
- You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
- 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:
-</para>
-
-<para>
-<screen>
-{ +<link linkend="filter-fun">filter{fun}</link> }
- / # For ALL sites!</screen>
-</para>
-
-<para>
- Note that the above is not really a good idea: There are exceptions
- to the filters in <filename>default.action</filename> for things that
- really shouldn't be filtered, like code on CVS->Web interfaces. Since
- <filename>user.action</filename> has the last word, these exceptions
- won't be valid for the <quote>fun</quote> filtering specified here.
-</para>
-
-<para>
- You might also worry about how your favourite free websites are
- funded, and find that they rely on displaying banner advertisements
- to survive. So you might want to specifically allow banners for those
- sites that you feel provide value to you:
-</para>