Update filters and taggers
[privoxy.git] / doc / source / user-manual.sgml
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2 <!entity % dummy "IGNORE">
3 <!entity supported SYSTEM "supported.sgml">
4 <!entity newfeatures SYSTEM "newfeatures.sgml">
5 <!entity p-intro SYSTEM "privoxy.sgml">
6 <!entity seealso SYSTEM "seealso.sgml">
7 <!entity buildsource SYSTEM "buildsource.sgml">
8 <!entity contacting SYSTEM "contacting.sgml">
9 <!entity history SYSTEM "history.sgml">
10 <!entity copyright SYSTEM "copyright.sgml">
11 <!entity license SYSTEM "license.sgml">
12 <!entity GPLv2 SYSTEM "../../LICENSE">
13 <!entity p-authors SYSTEM "p-authors.sgml">
14 <!entity config SYSTEM "p-config.sgml">
15 <!entity changelog SYSTEM "changelog.sgml">
16 <!entity p-version "3.0.21">
17 <!entity p-status "stable">
18 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
19 <!entity % p-not-stable "IGNORE">
20 <!entity % p-stable "INCLUDE">
21 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
22 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
23 <!entity % p-readme "IGNORE">
24 <!entity % user-man "IGNORE">
25 <!entity % config-file "IGNORE">
26 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
27 <!entity  my-copy "&copy;">         <!-- kludge for docbook2man           -->
28 <!entity % draft "IGNORE">          <!-- WIP stuff    -->
29 <!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml    -->
30 <!entity  my-app "<application>Privoxy</application>">
31 ]>
32 <!--
33  File        :  $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
34
35  Purpose     :  user manual
36                 This file belongs into
37                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
38
39  $Id: user-manual.sgml,v 2.173 2013/03/01 17:44:24 fabiankeil Exp $
40
41  Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
42  See LICENSE.
43
44  ========================================================================
45  NOTE: Please read developer-manual/documentation.html before touching
46  anything in this, or other Privoxy documentation.
47  ========================================================================
48
49 -->
50
51 <article id="index">
52 <artheader>
53
54 <title>Privoxy &p-version; User Manual</title>
55
56 <pubdate>
57  <subscript>
58 <!-- Completely the wrong markup, but very little is allowed  -->
59 <!-- in this part of an article. FIXME -->
60  <link linkend="copyright">Copyright</link> &my-copy; 2001-2013 by
61  <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
62  </subscript>
63 </pubdate>
64
65 <pubdate>$Id: user-manual.sgml,v 2.173 2013/03/01 17:44:24 fabiankeil Exp $</pubdate>
66
67 <!--
68
69 Note: the following should generate a separate page, and a live link to it,
70 all nicely done. But it doesn't for some mysterious reason. Please leave
71 commented unless it can be fixed proper. For the time being, the
72 copyright/license declarations will be in their own sgml.
73
74 Hal.
75
76
77 -->
78
79
80 <abstract>
81
82 <![%dummy;[
83  <para>
84  <comment>
85   This is here to keep vim syntax file from breaking :/
86   If I knew enough to fix it, I would.
87   PLEASE DO NOT REMOVE! HB: hal@foobox.net
88  </comment>
89  </para>
90 ]]>
91
92  <para>
93   The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
94   install, configure and use <ulink
95   url="http://www.privoxy.org/">Privoxy</ulink>.
96  </para>
97
98 <!-- Include privoxy.sgml boilerplate: -->
99  &p-intro;
100 <!-- end privoxy.sgml -->
101
102  <para>
103   You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at  <ulink
104   url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
105   Please see the <link linkend="contact">Contact section</link> on how to
106   contact the developers.
107  </para>
108
109 <!--   <para> -->
110 <!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
111 <!--   </para> -->
112 </abstract>
113
114 </artheader>
115
116 <!--   ~~~~~       New section      ~~~~~     -->
117 <sect1 label="1" id="introduction"><title>Introduction</title>
118 <para>
119  This documentation is included with the current &p-status; version of
120  <application>Privoxy</application>, &p-version;<![%p-not-stable;[,
121  and is mostly complete at this point. The most up to date reference for the
122  time being is still the comments in the source files and in the individual
123  configuration files. Development of a new version is currently nearing
124  completion, and includes significant changes and enhancements over
125  earlier versions]]>.
126 </para>
127
128 <!-- include only in non-stable versions -->
129 <![%p-not-stable;[
130 <para>
131  Since this is a &p-status; version, not all new features are well tested. This
132  documentation may be slightly out of sync as a result (especially with
133  CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
134  not many!
135 </para>
136 ]]>
137
138 <!--   ~~~~~       New section      ~~~~~     -->
139 <sect2 id="features"><title>Features</title>
140 <para>
141  In addition to the core
142  features of ad blocking and
143  <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
144  <application>Privoxy</application> provides many supplemental
145  features<![%p-not-stable;[, some of them currently under development]]>,
146  that give the end-user more control, more privacy and more freedom:
147 </para>
148 <!-- Include newfeatures.sgml boilerplate here: -->
149  &newfeatures;
150 <!-- end boilerplate -->
151 </sect2>
152
153 </sect1>
154
155 <!--  ~  End section  ~  -->
156
157
158 <!--   ~~~~~       New section      ~~~~~     -->
159 <sect1 id="installation"><title>Installation</title>
160
161 <para>
162  <application>Privoxy</application> is available both in convenient pre-compiled
163  packages for a wide range of operating systems, and as raw source code.
164  For most users, we recommend using the packages, which can be downloaded from our
165  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
166  Page</ulink>.
167 </para>
168
169 <para>
170  Note:
171  On some platforms, the installer may remove previously installed versions, if
172  found. (See below for your platform). In any case <emphasis>be sure to backup
173  your old configuration if it is valuable to you.</emphasis> See the <link
174  linkend="upgradersnote">note to upgraders</link> section below.
175 </para>
176
177 <!--   ~~~~~       New section      ~~~~~     -->
178 <sect2 id="installation-packages"><title>Binary Packages</title>
179 <para>
180 How to install the binary packages depends on your operating system:
181 </para>
182
183 <!-- XXX: The installation sections should be sorted -->
184
185 <!--   ~~~~~       New section      ~~~~~     -->
186 <sect3 id="installation-deb"><title>Debian and Ubuntu</title>
187 <para>
188  DEBs can be installed with <literal>apt-get install privoxy</literal>,
189  and will use <filename>/etc/privoxy</filename> for the location of
190  configuration files.
191 </para>
192 </sect3>
193
194 <!--   ~~~~~       New section      ~~~~~     -->
195 <sect3 id="installation-pack-win"><title>Windows</title>
196
197 <para>
198  Just double-click the installer, which will guide you through
199  the installation process. You will find the configuration files
200  in the same directory as you installed <application>Privoxy</application> in.
201 </para>
202 <para>
203  Version 3.0.5 beta introduced full <application>Windows</application> service
204  functionality. On Windows only, the <application>Privoxy</application>
205  program has two new command line arguments to install and uninstall
206  <application>Privoxy</application> as a <emphasis>service</emphasis>.
207 </para>
208  <variablelist>
209   <varlistentry>
210    <term>Arguments:</term>
211    <listitem>
212     <para>
213      <replaceable class="parameter">--install</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
214     </para>
215     <para>
216      <replaceable class="parameter">--uninstall</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
217     </para>
218    </listitem>
219   </varlistentry>
220  </variablelist>
221  <para>
222  After invoking <application>Privoxy</application> with
223  <command>--install</command>, you will need to bring up the
224  <application>Windows</application> service console to assign the user you
225  want <application>Privoxy</application> to run under, and whether or not you
226  want it to run whenever the system starts. You can start the
227  <application>Windows</application> services console with the following
228  command: <command>services.msc</command>.  If you do not take the manual step
229  of modifying <application>Privoxy's</application> service settings, it will
230  not start.  Note too that you will need to give Privoxy a user account that
231  actually exists, or it will not be permitted to
232  write to its log and configuration files.
233 </para>
234
235 </sect3>
236
237 <!--   ~~~~~       New section      ~~~~~     -->
238 <sect3 id="installation-os2"><title>OS/2</title>
239
240 <para>
241  First, make sure that no previous installations of
242  <application>Junkbuster</application> and / or
243  <application>Privoxy</application> are left on your
244  system. Check that no <application>Junkbuster</application>
245  or <application>Privoxy</application> objects are in
246  your startup folder.
247
248 </para>
249
250 <para>
251  Then, just double-click the WarpIN self-installing archive, which will
252  guide you through the installation process. A shadow of the
253  <application>Privoxy</application> executable will be placed in your
254  startup folder so it will start automatically whenever OS/2 starts.
255 </para>
256
257 <para>
258  The directory you choose to install <application>Privoxy</application>
259  into will contain all of the configuration files.
260 </para>
261 </sect3>
262
263 <!--   ~~~~~       New section      ~~~~~     -->
264 <sect3 id="installation-mac"><title>Mac OS X</title>
265 <para>
266  Installation instructions for the OS X platform depend upon whether
267  you downloaded a ready-built installation package (.pkg or .mpkg) or have
268  downloaded the source code.
269 </para>
270 </sect3>
271 <sect3 renderas="sect4" id="OS-X-install-from-package">
272 <title>Installation from ready-built package</title>
273 <para>
274  The downloaded file will either be a .pkg (for OS X 10.5 upwards) or a bzipped
275  .mpkg file (for OS X 10.4). The former can be double-clicked as is and the
276  installation will start; double-clicking the latter will unzip the .mpkg file
277  which can then be double-clicked to commence the installation.
278 </para>
279 <para>
280  The privoxy service will automatically start after a successful installation
281  (and thereafter every time your computer starts up) however you will need to
282  configure your web browser(s) to use it. To do so, configure them to use a
283  proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
284 </para>
285 <para>
286  To prevent the privoxy service from automatically starting when your computer
287  starts up, remove or rename the file <literal>/Library/LaunchDaemons/org.ijbswa.privoxy.plist</literal>
288  (on OS X 10.5 and higher) or the folder named
289  <literal>/Library/StartupItems/Privoxy</literal> (on OS X 10.4 'Tiger').
290 </para>
291 <para>
292  To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
293  and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
294  administrator account, using sudo.
295 </para>
296 <para>
297  To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
298  administrator account.
299 </para>
300 </sect3>
301 <sect3 renderas="sect4" id="OS-X-install-from-source">
302 <title>Installation from source</title>
303 <para>
304  To build and install the Privoxy source code on OS X you will need to obtain
305  the macsetup module from the Privoxy Sourceforge CVS repository (refer to
306  Sourceforge help for details of how to set up a CVS client to have read-only
307  access to the repository). This module contains scripts that leverage the usual
308  open-source tools (available as part of Apple's free of charge Xcode
309  distribution or via the usual open-source software package managers for OS X
310  (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary
311  and associated files. The macsetup module's README file contains complete
312  instructions for its use.
313 </para>
314 <para>
315  The privoxy service will automatically start after a successful installation
316  (and thereafter every time your computer starts up) however you will need to
317  configure your web browser(s) to use it. To do so, configure them to use a
318  proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
319 </para>
320 <para>
321  To prevent the privoxy service from automatically starting when your computer
322  starts up, remove or rename the file <literal>/Library/LaunchDaemons/org.ijbswa.privoxy.plist</literal>
323  (on OS X 10.5 and higher) or the folder named
324  <literal>/Library/StartupItems/Privoxy</literal> (on OS X 10.4 'Tiger').
325 </para>
326 <para>
327  To manually start or stop the privoxy service, use the Privoxy Utility
328  for Mac OS X (also part of the macsetup module).  This application can start
329  and stop the privoxy service and display its log and configuration files.
330 </para>
331 <para>
332  To uninstall, run the macsetup module's uninstall.sh as sudo from an
333  administrator account.
334 </para>
335 </sect3>
336
337 <!--   ~~~~~       New section      ~~~~~     -->
338 <sect3 id="installation-freebsd"><title>FreeBSD</title>
339
340 <para>
341  Privoxy is part of FreeBSD's Ports Collection, you can build and install
342  it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
343 </para>
344 </sect3>
345
346 </sect2>
347
348 <!--   ~~~~~       New section      ~~~~~     -->
349 <sect2 id="installation-source"><title>Building from Source</title>
350
351 <para>
352  The most convenient way to obtain the <application>Privoxy</application> sources
353  is to download the source tarball from our
354  <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;package_id=10571">project download
355  page</ulink>.
356 </para>
357
358 <para>
359  If you like to live on the bleeding edge and are not afraid of using
360  possibly unstable development versions, you can check out the up-to-the-minute
361  version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
362  CVS repository</ulink>.
363 <!--
364  deprecated...out of business.
365  or simply download <ulink
366  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
367  tarball.</ulink>
368 -->
369 </para>
370
371 <!-- include buildsource.sgml boilerplate: -->
372 &buildsource;
373 <!-- end boilerplate -->
374
375 </sect2>
376 <!--   ~~~~~       New section      ~~~~~     -->
377 <sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
378
379 <para>
380  If you wish to receive an email notification whenever we release updates of
381  <application>Privoxy</application> or the actions file, <ulink
382  url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
383  to our announce  mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
384 </para>
385
386 <para>
387  In order not to lose your personal changes and adjustments when updating
388  to the latest <literal>default.action</literal> file we <emphasis>strongly
389  recommend</emphasis> that you use <literal>user.action</literal> and
390  <literal>user.filter</literal> for your local
391  customizations of <application>Privoxy</application>. See the <link
392  linkend="actions-file">Chapter on actions files</link> for details.
393 </para>
394
395 </sect2>
396
397
398 </sect1>
399
400 <!--  ~  End section  ~  -->
401
402 <!--   ~~~~~       New section      ~~~~~     -->
403 <sect1 id="whatsnew">
404 <title>What's New in this Release</title>
405
406 &changelog;
407
408 <!--   ~~~~~       New section      ~~~~~     -->
409
410 <sect2 id="upgradersnote">
411 <title>Note to Upgraders</title>
412
413 <para>
414  A quick list of things to be aware of before upgrading from earlier
415  versions of <application>Privoxy</application>:
416 </para>
417
418 <para>
419  <itemizedlist>
420
421  <listitem>
422   <para>
423    The recommended way to upgrade &my-app; is to backup your old
424    configuration files, install the new ones, verify that &my-app;
425    is working correctly and finally merge back your changes using
426    <application>diff</application> and maybe <application>patch</application>.
427   </para>
428   <para>
429    There are a number of new features in each &my-app; release and
430    most of them have to be explicitly enabled in the configuration
431    files. Old configuration files obviously don't do that and due
432    to syntax changes using old configuration files with a new
433    &my-app; isn't always possible anyway.
434   </para>
435  </listitem>
436  <listitem>
437   <para>
438     Note that some installers remove earlier versions completely,
439     including configuration files, therefore you should really save
440     any important configuration files!
441   </para>
442  </listitem>
443  <listitem>
444   <para>
445    On the other hand, other installers don't overwrite existing configuration
446    files, thinking you will want to do that yourself.
447   </para>
448  </listitem>
449  <listitem>
450   <para>
451    In the default configuration only fatal errors are logged now.
452    You can change that in the <link linkend="DEBUG">debug section</link>
453    of the configuration file. You may also want to enable more verbose
454    logging until you verified that the new &my-app; version is working
455    as expected.
456   </para>
457  </listitem>
458
459  <listitem>
460     <para>
461      Three other config file settings are now off by default:
462      <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
463      <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
464      and  <link linkend="enable-edit-actions">enable-edit-actions</link>.
465      If you use or want these, you will need to explicitly enable them, and
466      be aware of the security issues involved.
467     </para>
468   </listitem>
469
470 <!--
471  <listitem>
472   <para>
473    What constitutes a <quote>default</quote> configuration has changed,
474    and you may want to review which actions are <quote>on</quote> by
475    default. This is primarily a matter of emphasis, but some features
476    you may have been used to, may now be <quote>off</quote> by default.
477    There are also a number of new actions and filters you may want to
478    consider, most of which are not fully incorporated into the default
479    settings as yet (see above).
480   </para>
481  </listitem>
482 -->
483 <!--
484   <listitem>
485    <para>
486     The default actions setting is now <literal>Cautious</literal>. Previous
487     releases had a default setting of <literal>Medium</literal>. Experienced
488     users may want to adjust this, as it is fairly conservative by &my-app;
489     standards and past practices. See <ulink
490     url="http://config.privoxy.org/edit-actions-list?f=default">
491     http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
492     should try the default settings for a while before turning up the volume.
493    </para>
494   </listitem>
495
496   <listitem>
497    <para>
498     The default setting has filtering turned <emphasis>off</emphasis>, which
499     subsequently means that compression is <emphasis>on</emphasis>. Remember
500     that filtering does not work on compressed pages, so if you use, or want to
501     use, filtering, you will need to force compression off. Example:
502    </para>
503    <para>
504  <screen>
505   { +<link linkend="filter">filter</link>{google}  +<link linkend="prevent-compression">prevent-compression</link> }
506    .google.</screen>
507    </para>
508    <para>
509     Or if you use a number of filters, or filter many sites, you may just want
510     to turn off compression for all sites in
511     <filename>default.action</filename> (or
512     <filename>user.action</filename>).
513    </para>
514
515   </listitem>
516
517   <listitem>
518   <para>
519    Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is
520    off by default now. If you've liked this feature in the past, you may want
521    to turn it back on in <filename>user.action</filename> now.
522   </para>
523   </listitem>
524
525
526   <listitem>
527   <para>
528    Some installers may not automatically start
529    <application>Privoxy</application> after installation.
530   </para>
531  </listitem>
532 -->
533
534  </itemizedlist>
535 </para>
536
537 </sect2>
538 </sect1>
539
540 <!--   ~~~~~       New section      ~~~~~     -->
541 <sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
542 <para>
543  <itemizedlist>
544
545  <listitem>
546   <para>
547   Install <application>Privoxy</application>. See the <link
548   linkend="installation">Installation Section</link> below for platform specific
549   information.
550  </para>
551  </listitem>
552
553  <listitem>
554   <para>
555    Advanced users and those who want to offer <application>Privoxy</application>
556    service to more than just their local machine should check the <link
557    linkend="config">main config file</link>, especially the <link
558    linkend="access-control">security-relevant</link> options. These are
559    off by default.
560   </para>
561  </listitem>
562
563  <listitem>
564   <para>
565   Start <application>Privoxy</application>, if the installation program has
566   not done this already (may vary according to platform). See the section
567   <link linkend="startup">Starting <application>Privoxy</application></link>.
568   </para>
569  </listitem>
570
571  <listitem>
572   <para>
573    Set your browser to use <application>Privoxy</application> as HTTP and
574    HTTPS (SSL)  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
575    by setting the proxy configuration for address of
576    <literal>127.0.0.1</literal> and port <literal>8118</literal>.
577    <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or
578    any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
579    browser from using these protocols.
580   </para>
581  </listitem>
582
583  <listitem>
584   <para>
585     Flush your browser's disk and memory caches, to remove any cached ad images.
586     If using <application>Privoxy</application> to manage
587     <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
588     you should remove any currently stored cookies too.
589   </para>
590  </listitem>
591
592  <listitem>
593   <para>
594    A default installation should provide a reasonable starting point for
595    most. There will undoubtedly be occasions where you will want to adjust the
596    configuration, but that can be dealt with as the need arises. Little
597    to no initial configuration is required in most cases, you may want
598    to enable the
599    <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
600    Be sure to read the warnings first.
601   </para>
602   <para>
603    See the <link linkend="configuration">Configuration section</link> for more
604    configuration options, and how to customize your installation.
605    You might also want to look at the <link
606    linkend="quickstart-ad-blocking">next section</link> for a quick
607    introduction to how <application>Privoxy</application> blocks ads and
608    banners.
609 </para>
610  </listitem>
611
612  <listitem>
613   <para>
614     If you experience ads that slip through, innocent images that are
615     blocked, or otherwise feel the need to fine-tune
616     <application>Privoxy's</application> behavior, take a look at the <link
617     linkend="actions-file">actions files</link>. As a quick start, you might
618     find the <link linkend="act-examples">richly commented examples</link>
619     helpful. You can also view and edit the actions files through the <ulink
620     url="http://config.privoxy.org">web-based user interface</ulink>. The
621     Appendix <quote><link linkend="actionsanat">Troubleshooting: Anatomy of an
622     Action</link></quote> has hints on how to understand and debug actions that
623     <quote>misbehave</quote>.
624   </para>
625  </listitem>
626
627 <!--
628  Did anyone test these lately?
629  fk 2007-11-10
630  <listitem>
631   <para>
632    For easy access to &my-app;'s most important controls, drag the provided
633    <link linkend="bookmarklets">Bookmarklets</link> into your browser's
634    personal toolbar.
635   </para>
636  </listitem>
637 -->
638
639  <listitem>
640   <para>
641    Please see the section <link linkend="contact">Contacting the
642    Developers</link> on how to report bugs, problems with websites or to get
643    help.
644   </para>
645  </listitem>
646
647  <listitem>
648   <para>
649    Now enjoy surfing with enhanced control, comfort and privacy!
650   </para>
651  </listitem>
652
653  </itemizedlist>
654 </para>
655
656
657 <!--   ~~~~~       New section      ~~~~~     -->
658
659 <sect2 id="quickstart-ad-blocking">
660 <title>Quickstart to Ad Blocking</title>
661 <!--
662  NOTE:  This section is deliberately redundant for those that don't
663  want to read the whole thing (which is getting lengthy).
664 -->
665 <para>
666  Ad blocking is but one of <application>Privoxy's</application>
667  array of features. Many of these features are for the technically minded advanced
668  user. But, ad and banner blocking is surely common ground for everybody.
669 </para>
670 <para>
671  This section will provide a quick summary of ad blocking so
672  you can get up to speed quickly without having to read the more extensive
673  information provided below, though this is highly recommended.
674 </para>
675 <para>
676  First a bit of a warning ... blocking ads is much like blocking SPAM: the
677  more aggressive you are about it, the more likely you are to block
678  things that were not intended. And the more likely that some things
679  may not work as intended. So there is a trade off here. If you want
680  extreme ad free browsing, be prepared to deal with more
681  <quote>problem</quote> sites, and to spend more time adjusting the
682  configuration to solve these unintended consequences. In short, there is
683  not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
684  the easy way and settle for <emphasis>most</emphasis> ads blocked with the
685  default configuration, or jump in and tweak it for your personal surfing
686  habits and preferences.
687 </para>
688 <para>
689  Secondly, a brief explanation of <application>Privoxy's </application>
690  <quote>actions</quote>. <quote>Actions</quote> in this context, are
691  the directives we use to tell <application>Privoxy</application> to perform
692  some task relating to HTTP transactions (i.e. web browsing). We tell
693  <application>Privoxy</application> to take some <quote>action</quote>. Each
694  action has a unique name and function. While there are many potential
695  <application>actions</application> in <application>Privoxy's</application>
696  arsenal, only a few are used for ad blocking. <link
697  linkend="actions">Actions</link>, and <link linkend="actions-file">action
698  configuration files</link>, are explained in depth below.
699 </para>
700 <para>
701  Actions are specified in <application>Privoxy's</application> configuration,
702  followed by one or more URLs to which the action should apply. URLs
703  can actually be URL type <link linkend="af-patterns">patterns</link> that use
704  wildcards so they can apply potentially to a range of similar URLs. The
705  actions, together with the URL patterns are called a section.
706 </para>
707 <para>
708  When you connect to a website, the full URL will either match one or more
709  of the sections as defined in <application>Privoxy's</application> configuration,
710  or not. If so, then <application>Privoxy</application> will perform the
711  respective actions. If not, then nothing special happens. Furthermore, web
712  pages may contain embedded, secondary URLs that your web browser will
713  use to load additional components of the page, as it parses the
714  original page's HTML content. An ad image for instance, is just an URL
715  embedded in the page somewhere. The image itself may be on the same server,
716  or a server somewhere else on the Internet. Complex web pages will have many
717  such embedded URLs. &my-app; can deal with each URL individually, so, for
718  instance, the main page text is not touched, but images from such-and-such
719  server are blocked.
720 </para>
721
722 <para>
723  The most important actions for basic ad blocking are:  <literal><link
724  linkend="block">block</link></literal>, <literal><link
725  linkend="handle-as-image">handle-as-image</link></literal>,
726  <literal><link
727  linkend="handle-as-empty-document">handle-as-empty-document</link></literal>,and
728  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
729 </para>
730
731 <para>
732  <itemizedlist>
733
734  <listitem>
735   <para>
736    <literal><link linkend="block">block</link></literal> - this is perhaps
737    the single most used action, and is particularly important for ad blocking.
738    This action stops any contact between your browser and any URL patterns
739    that match this action's configuration. It can be used for blocking ads,
740    but also anything that is determined to be unwanted. By itself, it simply
741    stops any communication with the remote server and sends
742    <application>Privoxy</application>'s own built-in BLOCKED page instead to
743    let you now what has happened (with some exceptions, see below).
744   </para>
745  </listitem>
746
747  <listitem>
748   <para>
749    <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
750    tells <application>Privoxy</application> to treat this URL as an image.
751    <application>Privoxy</application>'s default configuration already does this
752    for all common image types (e.g. GIF), but there are many situations where this
753    is not so easy to determine. So we'll force it in these cases. This is particularly
754    important for ad blocking, since  only if we know that it's an image of
755    some kind, can we replace it with an image of our choosing, instead of the
756    <application>Privoxy</application> BLOCKED page (which would only result in
757    a <quote>broken image</quote> icon). There are some limitations to this
758    though. For instance, you can't just brute-force an image substitution for
759    an entire HTML page in most situations.
760   </para>
761  </listitem>
762
763  <listitem>
764   <para>
765    <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal> -
766    sends an empty document instead of <application>Privoxy's</application>
767    normal BLOCKED HTML page. This is useful for file types that are neither
768    HTML nor images, such as blocking JavaScript files.
769   </para>
770  </listitem>
771
772  <listitem>
773   <para>
774    <literal><link
775    linkend="set-image-blocker">set-image-blocker</link></literal> - tells
776    <application>Privoxy</application> what to display in place of an ad image that
777    has hit a block rule. For this to come into play, the URL must match a
778    <literal><link linkend="block">block</link></literal> action somewhere in the
779    configuration, <emphasis>and</emphasis>, it must also match an
780    <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
781   </para>
782   <para>
783    The configuration options on what to display instead of the ad are:
784   </para>
785   <simplelist>
786    <member>
787     &nbsp;&nbsp;&nbsp;<emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad
788     replacement is obvious. This is the default.
789    </member>
790   </simplelist>
791   <simplelist>
792    <member>
793     &nbsp;&nbsp;&nbsp;<emphasis>blank</emphasis> - A very small empty GIF image is displayed.
794     This is the so-called <quote>invisible</quote> configuration option.
795    </member>
796   </simplelist>
797   <simplelist>
798    <member>
799     &nbsp;&nbsp;&nbsp;<emphasis>http://&lt;URL&gt;</emphasis> - A redirect to any image anywhere
800     of the user's choosing (advanced usage).
801    </member>
802   </simplelist>
803   </listitem>
804
805 </itemizedlist>
806 </para>
807
808 <para>
809  Advanced users will eventually want to explore &my-app;
810  <literal><link linkend="filter">filters</link></literal> as well. Filters
811  are very different from <literal><link
812  linkend="block">blocks</link></literal>.
813  A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
814  are a way of filtering or modifying what is actually on the page. An example
815  filter usage: a text replacement of <quote>no-no</quote> for
816  <quote>nasty-word</quote>. That is a very simple example. This process can be
817  used for ad blocking, but it is more in the realm of advanced usage and has
818  some pitfalls to be wary off.
819 </para>
820
821 <para>
822  The quickest way to adjust any of these settings is with your browser through
823  the special <application>Privoxy</application> editor at <ulink
824  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
825  (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
826  is an internal page, and does not require Internet access.
827 </para>
828
829 <para>
830  Note that as of <application>Privoxy</application> 3.0.7 beta the
831  action editor is disabled by default. Check the
832  <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
833   section in the configuration file</ulink> to learn why and in which
834  cases it's safe to enable again.
835 </para>
836
837 <para>
838  If you decided to enable the action editor, select the appropriate
839  <quote>actions</quote> file, and click
840  <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
841  local preferences in <filename>user.action</filename> since this is not
842  meant to be overwritten during upgrades, and will over-ride the settings in
843  other files. Here you can insert new <quote>actions</quote>, and URLs for ad
844  blocking or other purposes, and make other adjustments to the configuration.
845  <application>Privoxy</application> will detect these changes automatically.
846 </para>
847
848 <para>
849  A quick and simple step by step example:
850 </para>
851
852 <para>
853  <itemizedlist>
854
855   <listitem>
856    <para>
857      Right click on the ad image to be blocked, then select
858      <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
859      pop-up menu.
860    </para>
861   </listitem>
862   <listitem>
863    <para>
864     Set your browser to
865     <ulink
866  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
867    </para>
868   </listitem>
869   <listitem>
870    <para>
871     Find <filename>user.action</filename> in the top section, and click
872     on <quote><guibutton>Edit</guibutton></quote>:
873    </para>
874
875  <!-- image of editor and actions files selections -->
876  <para>
877   <figure pgwide="0" float="0"><title>Actions Files in Use</title>
878    <mediaobject>
879      <imageobject>
880       <imagedata  fileref="files-in-use.jpg" format="jpg">
881        </imageobject>
882        <textobject>
883         <phrase>[ Screenshot of Actions Files in Use ]</phrase>
884       </textobject>
885    </mediaobject>
886   </figure>
887  </para>
888  </listitem>
889
890  <listitem>
891   <para>
892    You should have a section with only
893    <literal><link linkend="block">block</link></literal> listed under
894    <quote>Actions:</quote>.
895    If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
896    button, and in the new section that just appeared, click the
897    <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
898    This will bring up a list of all actions. Find
899    <literal><link linkend="block">block</link></literal> near the top, and click
900    in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
901    just below the list.
902   </para>
903  </listitem>
904  <listitem>
905   <para>
906    Now, in the <literal><link linkend="block">block</link></literal> actions section,
907    click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
908    browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
909    Remove the <literal>http://</literal> at the beginning of the URL. Then, click
910    <quote><guibutton>Submit</guibutton></quote> (or
911    <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
912   </para>
913  </listitem>
914  <listitem>
915   <para>
916    Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
917    (or flush all browser caches). The image should be gone now.
918   </para>
919  </listitem>
920
921  </itemizedlist>
922 </para>
923
924 <para>
925  This is a very crude and simple example. There might be good reasons to use a
926  wildcard pattern match to include potentially similar images from the same
927  site. For a more extensive explanation of <quote>patterns</quote>, and
928  the entire actions concept, see <link linkend="actions-file">the Actions
929  section</link>.
930 </para>
931
932 <para>
933  For advanced users who want to hand edit their config files, you might want
934  to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
935  The ideas explained therein also apply to the web-based editor.
936 </para>
937 <para>
938  There are also various
939  <link linkend="filter">filters</link> that can be used for ad blocking
940  (filters are a special subset of actions). These
941  fall into the <quote>advanced</quote> usage category, and are explained in
942  depth in later sections.
943 </para>
944
945 </sect2>
946
947 </sect1>
948
949 <!--  ~  End section  ~  -->
950
951
952 <!--   ~~~~~       New section      ~~~~~     -->
953 <sect1 id="startup">
954 <title>Starting Privoxy</title>
955 <para>
956  Before launching <application>Privoxy</application> for the first time, you
957  will want to configure your browser(s) to use
958  <application>Privoxy</application> as a HTTP and HTTPS (SSL)
959  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
960  127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
961  used port 8000). This is the one configuration step <emphasis>that must be done
962 </emphasis>!
963 </para>
964 <para>
965  Please note that <application>Privoxy</application> can only proxy HTTP and
966  HTTPS traffic. It will not work with FTP or other protocols.
967 </para>
968
969  <!-- image of Mozilla Proxy configuration -->
970  <para>
971   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
972   Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
973    <mediaobject>
974      <imageobject>
975       <imagedata  fileref="proxy_setup.jpg" format="jpg">
976        </imageobject>
977        <textobject>
978         <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
979       </textobject>
980    </mediaobject>
981   </figure>
982  </para>
983
984
985 <para>
986  With <application>Firefox</application>, this is typically set under:
987 </para>
988
989 <literallayout>
990  <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> ->  <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
991
992 </literallayout>
993
994 <para>
995  Or optionally on some platforms:
996 </para>
997
998 <literallayout>
999  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
1000
1001 </literallayout>
1002
1003
1004 <para>
1005  With <application>Netscape</application> (and
1006  <application>Mozilla</application>), this can be set under:
1007 </para>
1008
1009
1010 <literallayout>
1011 <!-- Mix ascii and gui art, something for everybody -->
1012 <!-- spacing on this is tricky -->
1013  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
1014
1015 </literallayout>
1016
1017 <para>
1018  For <application>Internet Explorer v.5-7</application>:
1019 </para>
1020
1021 <literallayout>
1022  <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
1023 </literallayout>
1024
1025 <para>
1026  Then, check <quote>Use Proxy</quote> and fill in the appropriate info
1027  (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
1028  proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
1029  checkboxes like <quote>Use the same proxy server for all protocols</quote> is
1030  <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
1031 </para>
1032
1033  <!-- image of IE Proxy configuration -->
1034  <para>
1035   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1036   Internet Explorer HTTP and HTTPS (Secure) Settings</title>
1037    <mediaobject>
1038      <imageobject>
1039       <imagedata  fileref="proxy2.jpg" format="jpg">
1040        </imageobject>
1041        <textobject>
1042         <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
1043       </textobject>
1044    </mediaobject>
1045   </figure>
1046  </para>
1047
1048
1049 <para>
1050  After doing this, flush your browser's disk and memory caches to force a
1051  re-reading of all pages and to get rid of any ads that may be cached. Remove
1052  any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
1053  if you want <application>Privoxy</application> to manage that. You are now
1054  ready to start enjoying the benefits of using
1055  <application>Privoxy</application>!
1056 </para>
1057
1058 <para>
1059  <application>Privoxy</application> itself is typically started by specifying the
1060  main configuration file to be used on the command line. If no configuration
1061  file is specified on the command line, <application>Privoxy</application>
1062  will look for a file named <filename>config</filename> in the current
1063  directory. Except on Win32 where it will try <filename>config.txt</filename>.
1064 </para>
1065
1066 <sect2 id="start-debian">
1067 <title>Debian</title>
1068 <para>
1069  We use a script. Note that Debian typically starts &my-app; upon booting per
1070  default.  It will use the file
1071  <filename>/etc/privoxy/config</filename> as its main configuration
1072  file.
1073 </para>
1074 <para>
1075  <screen>
1076  # /etc/init.d/privoxy start
1077 </screen>
1078 </para>
1079 </sect2>
1080
1081 <sect2 id="start-windows">
1082 <title>Windows</title>
1083 <para>
1084 Click on the &my-app; Icon to start <application>Privoxy</application>. If no configuration file is
1085  specified on the command line, <application>Privoxy</application> will look
1086  for a file named <filename>config.txt</filename>. Note that Windows will
1087  automatically start &my-app; when the system starts if you chose that option
1088  when installing.
1089 </para>
1090 <para>
1091  <application>Privoxy</application> can run with full Windows service functionality.
1092  On Windows only, the &my-app; program has two new command line arguments
1093  to install and uninstall &my-app; as a service. See the
1094  <link linkend="installation-pack-win">Windows Installation
1095  instructions</link> for details.
1096 </para>
1097 </sect2>
1098
1099 <sect2 id="start-unices">
1100 <title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
1101 <para>
1102 Example Unix startup command:
1103 </para>
1104 <para>
1105  <screen>
1106  # /usr/sbin/privoxy /etc/privoxy/config
1107 </screen>
1108 </para>
1109 </sect2>
1110
1111 <sect2 id="start-os2">
1112 <title>OS/2</title>
1113 <para>
1114  During installation, <application>Privoxy</application> is configured to
1115  start automatically when the system restarts. You can start it manually by
1116  double-clicking on the <application>Privoxy</application> icon in the
1117  <application>Privoxy</application> folder.
1118 </para>
1119 </sect2>
1120
1121 <sect2 id="start-macosx">
1122 <title>Mac OS X</title>
1123 <para>
1124   After downloading the privoxy software, unzip the downloaded file by
1125   double-clicking on the zip file icon.  Then, double-click on the
1126   installer package icon and follow the installation process.
1127 </para>
1128 <para>
1129   The privoxy service will automatically start after a successful
1130   installation.  In addition, the privoxy service will automatically
1131   start every time your computer starts up.
1132 </para>
1133 <para>
1134   To prevent the privoxy service from automatically starting when your
1135   computer starts up, remove or rename the folder named
1136   /Library/StartupItems/Privoxy.
1137 </para>
1138 <para>
1139   A simple application named Privoxy Utility has been created which
1140   enables administrators to easily start and stop the privoxy service.
1141 </para>
1142 <para>
1143   In addition, the Privoxy Utility presents a simple way for
1144   administrators to edit the various privoxy config files.  A method
1145   to uninstall the software is also available.
1146 </para>
1147 <para>
1148   An administrator username and password must be supplied in order for
1149   the Privoxy Utility to perform any of the tasks.
1150 </para>
1151 </sect2>
1152
1153
1154 <!--
1155
1156 <para>
1157  See the section <link linkend="cmdoptions">Command line options</link> for
1158  further info.
1159 </para>
1160
1161 must find a better place for this paragraph
1162
1163 <para>
1164  The included default configuration files should give a reasonable starting
1165  point. Most of the per site configuration is done in the
1166  <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
1167  where various cookie actions are defined, ad and banner blocking, and other
1168  aspects of <application>Privoxy</application> configuration. There are several
1169  such files included, with varying levels of aggressiveness.
1170 </para>
1171
1172 <para>
1173  You will probably want to keep an eye out for sites for which you may prefer
1174  persistent cookies, and add these to your actions configuration as needed. By
1175  default, most of these will be accepted only during the current browser
1176  session (aka <quote>session cookies</quote>), unless you add them to the
1177  configuration. If you want the browser to handle this instead, you will need
1178  to edit <filename>user.action</filename> (or through the web based interface)
1179  and disable this feature. If you use more than one browser, it would make
1180  more sense to let <application>Privoxy</application> handle this. In which
1181  case, the browser(s) should be set to accept all cookies.
1182 </para>
1183
1184 <para>
1185  Another feature where you will probably want to define exceptions for trusted
1186  sites is the popup-killing (through  <ulink
1187  url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>),
1188  because your favorite shopping, banking, or leisure site may need
1189  popups (explained below).
1190 </para>
1191
1192 <para>
1193  <application>Privoxy</application> does not support all of the optional HTTP/1.1
1194  features yet. In the unlikely event that you experience inexplicable problems
1195  with browsers that use HTTP/1.1 per default
1196  (like <application>Mozilla</application> or recent versions of I.E.), you might
1197  try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit -&gt;
1198  Preferences -&gt; Debug -&gt; Networking</literal>.
1199  Alternatively, set the <quote>+downgrade-http-version</quote> config option in
1200  <filename>default.action</filename> which will downgrade your browser's HTTP
1201  requests from HTTP/1.1 to HTTP/1.0 before processing them.
1202 </para>
1203
1204 <para>
1205  After running <application>Privoxy</application> for a while, you can
1206  start to fine tune the configuration to suit your personal, or site,
1207  preferences and requirements. There are many, many aspects that can
1208  be customized. <quote>Actions</quote>
1209  can be adjusted by pointing your browser to
1210  <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1211  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
1212  and then follow the link to <quote>View &#38; Change the Current Configuration</quote>.
1213  (This is an internal page and does not require Internet access.)
1214 </para>
1215
1216 <para>
1217  In fact, various aspects of <application>Privoxy</application>
1218  configuration can be viewed from this page, including
1219  current configuration parameters, source code version numbers,
1220  the browser's request headers, and <quote>actions</quote> that apply
1221  to a given URL. In addition to the actions file
1222  editor mentioned above, <application>Privoxy</application> can also
1223  be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
1224 </para>
1225
1226 <para>
1227  If you encounter problems, try loading the page without
1228  <application>Privoxy</application>. If that helps, enter the URL where
1229  you have the problems into <ulink url="http://p.p/show-url-info">the browser
1230  based rule tracing utility</ulink>. See which rules apply and why, and
1231  then try turning them off for that site one after the other, until the problem
1232  is gone. When you have found the culprit, you might want to turn the rest on
1233  again.
1234 </para>
1235
1236 <para>
1237  If the above paragraph sounds gibberish to you, you might want to <link
1238  linkend="actions-file">read more about the actions concept</link>
1239  or even dive deep into the <link linkend="actionsanat">Appendix
1240  on actions</link>.
1241 </para>
1242
1243 <para>
1244  If you can't get rid of the problem at all, think you've found a bug in
1245  Privoxy, want to propose a new feature or smarter rules, please see the
1246  section <link linkend="contact"><quote>Contacting the
1247  Developers</quote></link> below.
1248 </para>
1249
1250 -->
1251
1252 <!--   ~~~~~       New section      ~~~~~     -->
1253 <sect2 id="cmdoptions">
1254 <title>Command Line Options</title>
1255 <para>
1256  <application>Privoxy</application> may be invoked with the following
1257  command-line options:
1258 </para>
1259
1260 <para>
1261  <itemizedlist>
1262
1263  <listitem>
1264   <para>
1265    <emphasis>--config-test</emphasis>
1266   </para>
1267   <para>
1268    Exit after loading the configuration files before binding to
1269    the listen address. The exit code signals whether or not the
1270    configuration files have been successfully loaded.
1271   </para>
1272   <para>
1273    If the exit code is 1, at least one of the configuration files
1274    is invalid, if it is 0, all the configuration files have been
1275    successfully loaded (but may still contain errors that can
1276    currently only be detected at run time).
1277   </para>
1278   <para>
1279    This option doesn't affect the log setting, combination with
1280    <emphasis>--no-daemon</emphasis> is recommended if a configured
1281    log file shouldn't be used.
1282   </para>
1283  </listitem>
1284  <listitem>
1285   <para>
1286     <emphasis>--version</emphasis>
1287   </para>
1288   <para>
1289      Print version info and exit. Unix only.
1290   </para>
1291  </listitem>
1292  <listitem>
1293   <para>
1294     <emphasis>--help</emphasis>
1295   </para>
1296   <para>
1297    Print short usage info and exit. Unix only.
1298   </para>
1299  </listitem>
1300  <listitem>
1301   <para>
1302    <emphasis>--no-daemon</emphasis>
1303   </para>
1304   <para>
1305    Don't become a daemon, i.e. don't fork and become process group
1306    leader, and don't detach from controlling tty. Unix only.
1307   </para>
1308  </listitem>
1309  <listitem>
1310   <para>
1311    <emphasis>--pidfile FILE</emphasis>
1312   </para>
1313   <para>
1314    On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
1315    <emphasis>FILE</emphasis> on exit. Failure to create or delete the
1316    <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
1317    option is given, no PID file will be used. Unix only.
1318   </para>
1319  </listitem>
1320  <listitem>
1321   <para>
1322    <emphasis>--user USER[.GROUP]</emphasis>
1323   </para>
1324   <para>
1325    After (optionally) writing the PID file, assume the user  ID  of
1326    <emphasis>USER</emphasis>, and if included the GID of GROUP.  Exit if the
1327    privileges are not sufficient to do so. Unix only.
1328   </para>
1329  </listitem>
1330  <listitem>
1331   <para>
1332    <emphasis>--chroot</emphasis>
1333   </para>
1334   <para>
1335    Before changing to the user ID given in the <emphasis>--user</emphasis> option,
1336    chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
1337    process that the directory tree starts there. If set up carefully, this can limit
1338    the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
1339    Unix only.
1340   </para>
1341  </listitem>
1342  <listitem>
1343   <para>
1344    <emphasis>--pre-chroot-nslookup hostname</emphasis>
1345   </para>
1346   <para>
1347    Specifies a hostname to look up before doing a chroot. On some systems, initializing the
1348    resolver library involves reading config files from /etc and/or loading additional shared
1349    libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
1350    the number of files that must be copied into the chroot tree.
1351   </para>
1352   <para>
1353    For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
1354    your local name server (listed in /etc/resolv.conf) can resolve without recursion
1355    (that is, without having to ask any other name servers). The hostname need not exist,
1356    but if it doesn't, an error message (which can be ignored) will be output.
1357   </para>
1358  </listitem>
1359
1360  <listitem>
1361   <para>
1362     <emphasis>configfile</emphasis>
1363   </para>
1364   <para>
1365     If no <emphasis>configfile</emphasis> is included on the command line,
1366     <application>Privoxy</application> will look for a file named
1367     <quote>config</quote> in the current directory (except on Win32
1368     where it will look for <quote>config.txt</quote> instead). Specify
1369     full path to avoid confusion. If no config file is found,
1370     <application>Privoxy</application> will fail to start.
1371   </para>
1372  </listitem>
1373
1374  </itemizedlist>
1375 </para>
1376
1377 <para>
1378  On <application>MS Windows</application> only there are two additional
1379  command-line options to allow <application>Privoxy</application> to install and
1380  run as a <emphasis>service</emphasis>. See the
1381 <link linkend="installation-pack-win">Window Installation section</link>
1382 for details.
1383 </para>
1384
1385 </sect2>
1386
1387 </sect1>
1388
1389 <!--  ~  End section  ~  -->
1390
1391
1392 <!--   ~~~~~       New section      ~~~~~     -->
1393 <sect1 id="configuration"><title>Privoxy Configuration</title>
1394  <para>
1395   All <application>Privoxy</application> configuration is stored
1396   in text files. These files can be edited with a text editor.
1397   Many important aspects of <application>Privoxy</application> can
1398   also be controlled easily with a web browser.
1399  </para>
1400
1401
1402 <!--   ~~~~~       New section      ~~~~~     -->
1403
1404 <sect2>
1405 <title>Controlling Privoxy with Your Web Browser</title>
1406 <para>
1407  <application>Privoxy</application>'s user interface can be reached through the special
1408  URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1409  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
1410  which is a built-in page and works without Internet access.
1411  You will see the following section:
1412
1413 </para>
1414
1415 <!-- Needs to be put in a table and colorized  -->
1416 <screen>
1417  <msgtext>
1418  <bridgehead renderas="sect2">&nbsp;&nbsp;&nbsp;&nbsp;Privoxy Menu</bridgehead>
1419
1420  <simplelist>
1421  <member>
1422   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
1423  </member>
1424  <member>
1425   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
1426  </member>
1427  <member>
1428   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
1429  </member>
1430  <member>
1431   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
1432  </member>
1433  <member>
1434   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
1435  </member>
1436  <member>
1437   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink
1438   url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
1439  </member>
1440  </simplelist>
1441  </msgtext>
1442 </screen>
1443
1444
1445 <para>
1446  This should be self-explanatory. Note the first item leads to an editor for the
1447  <link linkend="actions-file">actions files</link>, which is where the ad, banner,
1448  cookie, and URL blocking magic is configured as well as other advanced features of
1449  <application>Privoxy</application>. This is an easy way to adjust various
1450  aspects of <application>Privoxy</application> configuration. The actions
1451  file, and other configuration files, are explained in detail below.
1452 </para>
1453
1454 <para>
1455  <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
1456  have problems with your current actions and filters. You can in fact use
1457  it as a test to see whether it is <application>Privoxy</application>
1458  causing the problem or not. <application>Privoxy</application> continues
1459  to run as a proxy in this case, but all manipulation is disabled, i.e.
1460  <application>Privoxy</application> acts like a normal forwarding proxy. There
1461  is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
1462  that you can toggle <application>Privoxy</application> with one click from
1463  your browser.
1464 </para>
1465
1466 <para>
1467  Note that several of the features described above are disabled by default
1468  in <application>Privoxy</application> 3.0.7 beta and later.
1469  Check the
1470  <ulink url="config.html">configuration file</ulink> to learn why
1471  and in which cases it's safe to enable them again.
1472 </para>
1473
1474 </sect2>
1475
1476 <!--  ~  End section  ~  -->
1477
1478
1479
1480
1481 <!--   ~~~~~       New section      ~~~~~     -->
1482
1483 <sect2 id="confoverview">
1484 <title>Configuration Files Overview</title>
1485 <para>
1486  For Unix, *BSD and Linux, all configuration files are located in
1487  <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
1488  AmigaOS these are all in the same directory as the
1489  <application>Privoxy</application> executable. <![%p-not-stable;[ The name
1490  and number of configuration files has changed from previous versions, and is
1491  subject to change as development progresses.]]>
1492 </para>
1493
1494 <para>
1495  The installed defaults provide a reasonable starting point, though
1496  some settings may be aggressive by some standards. For the time being, the
1497  principle configuration files are:
1498 </para>
1499
1500 <para>
1501  <itemizedlist>
1502
1503   <listitem>
1504    <para>
1505      The <link linkend="config">main configuration file</link> is named <filename>config</filename>
1506      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
1507      on Windows. This is a required file.
1508    </para>
1509   </listitem>
1510
1511   <listitem>
1512    <para>
1513     <filename>match-all.action</filename> is used to define which <quote>actions</quote>
1514     relating to banner-blocking, images, pop-ups, content modification, cookie handling
1515     etc should be applied by default. It should be the first actions file loaded.
1516    </para>
1517    <para>
1518     <filename>default.action</filename> defines many exceptions (both positive and negative)
1519     from the default set of actions that's configured in <filename>match-all.action</filename>.
1520     It should be the second actions file loaded and shouldn't be edited by the user.
1521    </para>
1522    <para>
1523     Multiple actions files may be defined in <filename>config</filename>. These
1524     are processed in the order they are defined. Local customizations and locally
1525     preferred exceptions to the default policies as defined in
1526     <filename>match-all.action</filename> (which you will most probably want
1527     to define sooner or later) are best applied in <filename>user.action</filename>,
1528     where you can preserve them across upgrades. The file isn't installed by all
1529     installers, but you can easily create it yourself with a text editor.
1530    </para>
1531    <para>
1532     There is also a web based editor that can be accessed from
1533     <ulink
1534     url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1535     (Shortcut: <ulink
1536     url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
1537     various actions files.
1538    </para>
1539   </listitem>
1540
1541   <listitem>
1542    <para>
1543     <quote>Filter files</quote> (the <link linkend="filter-file">filter
1544     file</link>) can be used to re-write the raw page content, including
1545     viewable text as well as embedded HTML and JavaScript, and whatever else
1546     lurks on any given web page. The filtering jobs are only pre-defined here;
1547     whether to apply them or not is up to the actions files.
1548     <filename>default.filter</filename> includes various filters made
1549     available for use by the developers. Some are much more intrusive than
1550     others, and all should be used with caution. You may define additional
1551     filter files in <filename>config</filename> as you can with
1552     actions files. We suggest <filename>user.filter</filename> for any
1553     locally defined filters or customizations.
1554    </para>
1555   </listitem>
1556
1557  </itemizedlist>
1558 </para>
1559
1560 <para>
1561  The syntax of the configuration and filter files may change between different
1562  Privoxy versions, unfortunately some enhancements cost backwards compatibility.
1563  <!-- Add link to documentation-->
1564 </para>
1565
1566 <para>
1567  All files use the <quote><literal>#</literal></quote> character to denote a
1568  comment (the rest of the line will be ignored) and understand line continuation
1569  through placing a backslash ("<literal>\</literal>") as the very last character
1570  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
1571  its special function. Placing a <literal>#</literal> in front of an otherwise
1572  valid configuration line to prevent it from being interpreted is called "commenting
1573  out" that line. Blank lines are ignored.
1574 </para>
1575
1576 <para>
1577  The actions files and filter files
1578  can use Perl style <link linkend="regex">regular expressions</link> for
1579  maximum flexibility.
1580 </para>
1581
1582 <para>
1583  After making any changes, there is no need to restart
1584  <application>Privoxy</application> in order for the changes to take
1585  effect. <application>Privoxy</application> detects such changes
1586  automatically. Note, however, that it may take one or two additional
1587  requests for the change to take effect. When changing the listening address
1588  of <application>Privoxy</application>, these <quote>wake up</quote> requests
1589  must obviously be sent to the <emphasis>old</emphasis> listening address.
1590 </para>
1591
1592 <![%p-not-stable;[
1593 <para>
1594  While under development, the configuration content is subject to change.
1595  The below documentation may not be accurate by the time you read this.
1596  Also, what constitutes a <quote>default</quote> setting, may change, so
1597  please check all your configuration files on important issues.
1598 </para>
1599 ]]>
1600
1601 </sect2>
1602 </sect1>
1603 <!--  ~  End section  ~  -->
1604
1605
1606 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1607
1608 <!-- **************************************************** -->
1609 <!-- Include config.sgml here -->
1610 <!-- This is where the entire config file is detailed. -->
1611  &config;
1612 <!-- end include  -->
1613
1614
1615 <!--  ~  End section  ~  -->
1616
1617
1618
1619 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1620
1621 <sect1 id="actions-file"><title>Actions Files</title>
1622
1623
1624 <!--
1625   XXX: similar descriptions are in the Configuration Files sections.
1626   We should only describe them at one place.
1627 -->
1628 <para>
1629  The actions files are used to define what <emphasis>actions</emphasis>
1630  <application>Privoxy</application> takes for which URLs, and thus determines
1631  how ad images, cookies and various other aspects of HTTP content and
1632  transactions are handled, and on which sites (or even parts thereof).
1633  There are a number of such actions, with a wide range of functionality.
1634  Each action does something a little different.
1635  These actions give us a veritable arsenal of tools with which to exert
1636  our control, preferences and independence. Actions can be combined so that
1637  their effects are aggregated when applied against a given set of URLs.
1638 </para>
1639 <para>
1640  There
1641  are three action files included with <application>Privoxy</application> with
1642  differing purposes:
1643 </para>
1644 <para>
1645  <itemizedlist>
1646   <listitem>
1647    <para>
1648     <filename>match-all.action</filename> - is used to define which
1649     <quote>actions</quote> relating to banner-blocking, images, pop-ups,
1650     content modification, cookie handling etc should be applied by default.
1651     It should be the first actions file loaded
1652    </para>
1653   </listitem>
1654   <listitem>
1655    <para>
1656     <filename>default.action</filename> - defines many exceptions (both
1657     positive and negative) from the default set of actions that's configured
1658     in <filename>match-all.action</filename>. It is a set of rules that should
1659     work reasonably well as-is for most users. This file is only supposed to
1660     be edited by the developers. It should be the second actions file loaded.
1661    </para>
1662   </listitem>
1663   <listitem>
1664    <para>
1665     <filename>user.action</filename> - is intended to be for local site
1666     preferences and exceptions. As an example, if your ISP or your bank
1667     has specific requirements, and need special handling, this kind of
1668     thing should go here. This file will not be upgraded.
1669    </para>
1670   </listitem>
1671   <listitem>
1672    <para>
1673     <guibutton>Edit</guibutton>  <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton>  <guibutton>Set to Advanced</guibutton>
1674    </para>
1675    <para>
1676     These have increasing levels of aggressiveness <emphasis>and have no
1677     influence on your browsing unless you select them explicitly in the
1678     editor</emphasis>. A default installation should be pre-set to
1679     <literal>Cautious</literal>. New users should try this for a while before
1680     adjusting the settings to more aggressive levels. The more aggressive
1681     the settings, then the more likelihood there is of problems such as sites
1682     not working as they should.
1683    </para>
1684    <para>
1685     The <guibutton>Edit</guibutton> button allows you to turn each
1686     action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
1687     button changes the actions list to low/safe settings which will activate
1688     ad blocking and a minimal set of &my-app;'s features, and subsequently
1689     there will be less of a chance for accidental problems. The
1690     <guibutton>Medium</guibutton> button sets the list to a medium level of
1691     other features and a low level set of privacy features. The
1692     <guibutton>Advanced</guibutton> button sets the list to a high level of
1693     ad blocking and medium level of privacy. See the chart below. The latter
1694     three buttons over-ride any changes via with the
1695     <guibutton>Edit</guibutton> button. More fine-tuning can be done in the
1696     lower sections of this internal page.
1697    </para>
1698    <para>
1699     While the actions file editor allows to enable these settings in all
1700     actions files, they are only supposed to be enabled in the first one
1701     to make sure you don't unintentionally overrule earlier rules.
1702    </para>
1703    <para>
1704     The default profiles, and their associated actions, as pre-defined in
1705     <filename>default.action</filename> are:
1706    </para>
1707    <para>
1708     <table frame=all><title>Default Configurations</title>
1709     <tgroup cols=4 align=left colsep=1 rowsep=1>
1710     <colspec colname=c1>
1711     <colspec colname=c2>
1712     <colspec colname=c3>
1713     <colspec colname=c4>
1714     <thead>
1715     <row>
1716       <entry>Feature</entry>
1717       <entry>Cautious</entry>
1718       <entry>Medium</entry>
1719       <entry>Advanced</entry>
1720     </row>
1721     </thead>
1722     <!--  <tfoot> -->
1723     <!--  <row> -->
1724     <!--    <entry>f1</entry> -->
1725     <!--    <entry>f2</entry> -->
1726     <!--    <entry>f3</entry> -->
1727     <!--    <entry>f4</entry> -->
1728     <!--  </row> -->
1729     <!--  </tfoot> -->
1730     <tbody>
1731
1732     <row>
1733       <entry>Ad-blocking Aggressiveness</entry>
1734       <entry>medium</entry>
1735       <entry>high</entry>
1736       <entry>high</entry>
1737     </row>
1738
1739     <row>
1740       <entry>Ad-filtering by size</entry>
1741       <entry>no</entry>
1742       <entry>yes</entry>
1743       <entry>yes</entry>
1744     </row>
1745
1746     <row>
1747       <entry>Ad-filtering by link</entry>
1748       <entry>no</entry>
1749       <entry>no</entry>
1750       <entry>yes</entry>
1751     </row>
1752     <row>
1753       <entry>Pop-up killing</entry>
1754       <entry>blocks only</entry>
1755       <entry>blocks only</entry>
1756       <entry>blocks only</entry>
1757     </row>
1758
1759     <row>
1760       <entry>Privacy Features</entry>
1761       <entry>low</entry>
1762       <entry>medium</entry>
1763       <entry>medium/high</entry>
1764     </row>
1765
1766     <row>
1767       <entry>Cookie handling</entry>
1768       <entry>none</entry>
1769       <entry>session-only</entry>
1770       <entry>kill</entry>
1771     </row>
1772
1773     <row>
1774       <entry>Referer forging</entry>
1775       <entry>no</entry>
1776       <entry>yes</entry>
1777       <entry>yes</entry>
1778     </row>
1779
1780     <row>
1781       <entry>GIF de-animation</entry>
1782       <entry>no</entry>
1783       <entry>yes</entry>
1784       <entry>yes</entry>
1785     </row>
1786
1787     <row>
1788       <entry>Fast redirects</entry>
1789       <entry>no</entry>
1790       <entry>no</entry>
1791       <entry>yes</entry>
1792     </row>
1793
1794     <row>
1795       <entry>HTML taming</entry>
1796       <entry>no</entry>
1797       <entry>no</entry>
1798       <entry>yes</entry>
1799     </row>
1800
1801     <row>
1802       <entry>JavaScript taming</entry>
1803       <entry>no</entry>
1804       <entry>no</entry>
1805       <entry>yes</entry>
1806     </row>
1807
1808     <row>
1809       <entry>Web-bug killing</entry>
1810       <entry>no</entry>
1811       <entry>yes</entry>
1812       <entry>yes</entry>
1813     </row>
1814
1815     <row>
1816       <entry>Image tag reordering</entry>
1817       <entry>no</entry>
1818       <entry>yes</entry>
1819       <entry>yes</entry>
1820     </row>
1821
1822     </tbody>
1823     </tgroup>
1824     </table>
1825     </para>
1826
1827   </listitem>
1828  </itemizedlist>
1829 </para>
1830
1831 <para>
1832  The list of actions files to be used are defined in the main configuration
1833  file, and are processed in the order they are defined (e.g.
1834  <filename>default.action</filename> is typically processed before
1835  <filename>user.action</filename>). The content of these can all be viewed and
1836  edited from <ulink
1837  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
1838  The over-riding principle when applying actions, is that the last action that
1839  matches a given URL wins. The broadest, most general rules go first
1840  (defined in <filename>default.action</filename>),
1841  followed by any exceptions (typically also in
1842  <filename>default.action</filename>), which are then followed lastly by any
1843  local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>).
1844  Generally, <filename>user.action</filename> has the last word.
1845  </para>
1846
1847 <para>
1848  An actions file typically has multiple sections. If you want to use
1849  <quote>aliases</quote> in an actions file, you have to place the (optional)
1850  <link linkend="aliases">alias section</link> at the top of that file.
1851  Then comes the default set of rules which will apply universally to all
1852  sites and pages (be <emphasis>very careful</emphasis> with using such a
1853  universal set in <filename>user.action</filename> or any other actions file after
1854  <filename>default.action</filename>, because it will override the result
1855  from consulting any previous file). And then below that,
1856  exceptions to the defined universal policies. You can regard
1857  <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
1858  with the advantage that it is a separate file, which makes preserving your
1859  personal settings across <application>Privoxy</application> upgrades easier.
1860 </para>
1861
1862 <para>
1863  Actions can be used to block anything you want, including ads, banners, or
1864  just some obnoxious URL whose content you would rather not see. Cookies can be accepted
1865  or rejected, or accepted only during the current browser session (i.e. not
1866  written to disk), content can be modified, some JavaScripts tamed, user-tracking
1867  fooled, and much more. See below for a <link linkend="actions">complete list
1868  of actions</link>.
1869 </para>
1870
1871 <!--   ~~~~~       New section      ~~~~~     -->
1872 <sect2>
1873 <title>Finding the Right Mix</title>
1874 <para>
1875  Note that some <link linkend="actions">actions</link>, like cookie suppression
1876  or script disabling, may render some sites unusable that rely on these
1877  techniques to work properly. Finding the right mix of actions is not always easy and
1878  certainly a matter of personal taste. And, things can always change, requiring
1879  refinements in the configuration. In general, it can be said that the more
1880  <quote>aggressive</quote> your default settings (in the top section of the
1881  actions file) are, the more exceptions for <quote>trusted</quote> sites you
1882  will have to make later. If, for example, you want to crunch all cookies per
1883  default, you'll have to make exceptions from that rule for sites that you
1884  regularly use and that require cookies for actually useful purposes, like maybe
1885  your bank, favorite shop, or newspaper.
1886 </para>
1887
1888 <para>
1889  We have tried to provide you with reasonable rules to start from in the
1890  distribution actions files. But there is no general rule of thumb on these
1891  things. There just are too many variables, and sites are constantly changing.
1892  Sooner or later you will want to change the rules (and read this chapter again :).
1893 </para>
1894 </sect2>
1895
1896 <!--   ~~~~~       New section      ~~~~~     -->
1897 <sect2>
1898 <title>How to Edit</title>
1899 <para>
1900  The easiest way to edit the actions files is with a browser by
1901  using our browser-based editor, which can be reached from <ulink
1902  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
1903  Note: the config file option <link
1904  linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
1905  this to work. The editor allows both fine-grained control over every single
1906  feature on a per-URL basis, and easy choosing from wholesale sets of defaults
1907  like <quote>Cautious</quote>, <quote>Medium</quote> or
1908  <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
1909  aggressive, and will be more likely to cause problems for some sites.
1910  Experienced users only!
1911  </para>
1912
1913 <para>
1914  If you prefer plain text editing to GUIs, you can of course also directly edit the
1915  the actions files with your favorite text editor. Look at
1916  <filename>default.action</filename> which is richly commented with many
1917  good examples.
1918 </para>
1919 </sect2>
1920
1921
1922 <sect2 id="actions-apply">
1923 <title>How Actions are Applied to Requests</title>
1924 <para>
1925  Actions files are divided into sections. There are special sections,
1926  like the <quote><link linkend="aliases">alias</link></quote> sections which will
1927  be discussed later. For now let's concentrate on regular sections: They have a
1928  heading line (often split up to multiple lines for readability) which consist
1929  of a list of actions, separated by whitespace and enclosed in curly braces.
1930  Below that, there is a list of URL and tag patterns, each on a separate line.
1931 </para>
1932
1933 <para>
1934  To determine which actions apply to a request, the URL of the request is
1935  compared to all URL patterns in each <quote>action file</quote>.
1936  Every time it matches, the list of applicable actions for the request is
1937  incrementally updated, using the heading of the section in which the
1938  pattern is located. The same is done again for tags and tag patterns later on.
1939 </para>
1940
1941 <para>
1942  If multiple applying sections set the same action differently,
1943  the last match wins. If not, the effects are aggregated.
1944  E.g. a URL might match a regular section with a heading line of <literal>{
1945  +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
1946  then later another one with just <literal>{
1947  +<link linkend="block">block</link> }</literal>, resulting
1948  in <emphasis>both</emphasis> actions to apply. And there may well be
1949  cases where you will want to combine actions together. Such a section then
1950  might look like:
1951 </para>
1952
1953  <para>
1954  <screen>
1955   { +<literal>handle-as-image</literal>  +<literal>block{Banner ads.}</literal> }
1956   # Block these as if they were images. Send no block page.
1957    banners.example.com
1958    media.example.com/.*banners
1959    .example.com/images/ads/</screen>
1960  </para>
1961
1962 <para>
1963  You can trace this process for URL patterns and any given URL by visiting <ulink
1964  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
1965 </para>
1966
1967 <para>
1968  Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
1969  Troubleshooting: Anatomy of an Action</link> section.
1970 </para>
1971 </sect2>
1972
1973 <!--   ~~~~~       New section      ~~~~~     -->
1974 <sect2 id="af-patterns">
1975 <title>Patterns</title>
1976 <para>
1977  As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
1978  to determine what <emphasis>actions</emphasis> might apply to which sites and
1979  pages your browser attempts to access. These <quote>patterns</quote> use wild
1980  card type <emphasis>pattern</emphasis> matching to achieve a high degree of
1981  flexibility. This allows one expression to be expanded and potentially match
1982  against many similar patterns.
1983 </para>
1984
1985 <para>
1986  Generally, an URL pattern has the form
1987  <literal>&lt;domain&gt;&lt;port&gt;/&lt;path&gt;</literal>, where the
1988  <literal>&lt;domain&gt;</literal>, the <literal>&lt;port&gt;</literal>
1989  and the <literal>&lt;path&gt;</literal> are optional. (This is why the special
1990  <literal>/</literal> pattern matches all URLs). Note that the protocol
1991  portion of the URL pattern (e.g. <literal>http://</literal>) should
1992  <emphasis>not</emphasis> be included in the pattern. This is assumed already!
1993 </para>
1994 <para>
1995  The pattern matching syntax is different for the domain and path parts of
1996  the URL. The domain part uses a simple globbing type matching technique,
1997  while the path part uses more flexible
1998  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
1999   Expressions</quote></ulink> (POSIX 1003.2).
2000 </para>
2001 <para>
2002  The port part of a pattern is a decimal port number preceded by a colon
2003  (<literal>:</literal>). If the domain part contains a numerical IPv6 address,
2004  it has to be put into angle brackets
2005  (<literal>&lt;</literal>, <literal>&gt;</literal>).
2006 </para>
2007
2008 <variablelist>
2009  <varlistentry>
2010   <term><literal>www.example.com/</literal></term>
2011   <listitem>
2012    <para>
2013     is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2014     regardless of which document on that server is requested. So ALL pages in
2015     this domain would be covered by the scope of this action. Note that a
2016     simple <literal>example.com</literal> is different and would NOT match.
2017    </para>
2018   </listitem>
2019  </varlistentry>
2020  <varlistentry>
2021   <term><literal>www.example.com</literal></term>
2022   <listitem>
2023    <para>
2024     means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2025     be omitted.
2026    </para>
2027   </listitem>
2028  </varlistentry>
2029  <varlistentry>
2030   <term><literal>www.example.com/index.html</literal></term>
2031   <listitem>
2032    <para>
2033     matches all the documents on <literal>www.example.com</literal>
2034     whose name starts with <literal>/index.html</literal>.
2035    </para>
2036   </listitem>
2037  </varlistentry>
2038  <varlistentry>
2039   <term><literal>www.example.com/index.html$</literal></term>
2040   <listitem>
2041    <para>
2042     matches only the single document <literal>/index.html</literal>
2043     on <literal>www.example.com</literal>.
2044    </para>
2045   </listitem>
2046  </varlistentry>
2047  <varlistentry>
2048   <term><literal>/index.html$</literal></term>
2049   <listitem>
2050    <para>
2051     matches the document <literal>/index.html</literal>, regardless of the domain,
2052     i.e. on <emphasis>any</emphasis> web server anywhere.
2053    </para>
2054   </listitem>
2055  </varlistentry>
2056  <varlistentry>
2057   <term><literal>/</literal></term>
2058   <listitem>
2059    <para>
2060     Matches any URL because there's no requirement for either the
2061     domain or the path to match anything.
2062    </para>
2063   </listitem>
2064  </varlistentry>
2065  <varlistentry>
2066   <term><literal>:8000/</literal></term>
2067   <listitem>
2068    <para>
2069     Matches any URL pointing to TCP port 8000.
2070    </para>
2071   </listitem>
2072  </varlistentry>
2073  <varlistentry>
2074   <term><literal>&lt;2001:db8::1&gt;/</literal></term>
2075   <listitem>
2076    <para>
2077     Matches any URL with the host address <literal>2001:db8::1</literal>.
2078     (Note that the real URL uses plain brackets, not angle brackets.)
2079    </para>
2080   </listitem>
2081  </varlistentry>
2082  <varlistentry>
2083   <term><literal>index.html</literal></term>
2084   <listitem>
2085    <para>
2086     matches nothing, since it would be interpreted as a domain name and
2087     there is no top-level domain called <literal>.html</literal>. So its
2088     a mistake.
2089    </para>
2090   </listitem>
2091  </varlistentry>
2092 </variablelist>
2093
2094
2095 <!--   ~~~~~       New section      ~~~~~     -->
2096 <sect3><title>The Domain Pattern</title>
2097
2098 <para>
2099  The matching of the domain part offers some flexible options: if the
2100  domain starts or ends with a dot, it becomes unanchored at that end.
2101  For example:
2102 </para>
2103
2104 <variablelist>
2105  <varlistentry>
2106   <term><literal>.example.com</literal></term>
2107   <listitem>
2108    <para>
2109     matches any domain with first-level domain <literal>com</literal>
2110     and second-level domain <literal>example</literal>.
2111     For example <literal>www.example.com</literal>,
2112     <literal>example.com</literal> and <literal>foo.bar.baz.example.com</literal>.
2113     Note that it wouldn't match if the second-level domain was <literal>another-example</literal>.
2114    </para>
2115   </listitem>
2116  </varlistentry>
2117  <varlistentry>
2118   <term><literal>www.</literal></term>
2119   <listitem>
2120    <para>
2121     matches any domain that <emphasis>STARTS</emphasis> with
2122     <literal>www.</literal> (It also matches the domain
2123     <literal>www</literal> but most of the time that doesn't matter.)
2124    </para>
2125   </listitem>
2126  </varlistentry>
2127  <varlistentry>
2128   <term><literal>.example.</literal></term>
2129   <listitem>
2130    <para>
2131     matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>.
2132     And, by the way, also included would be any files or documents that exist
2133     within that domain since no path limitations are specified. (Correctly
2134     speaking: It matches any FQDN that contains <literal>example</literal> as
2135     a domain.) This might be <literal>www.example.com</literal>,
2136     <literal>news.example.de</literal>, or
2137     <literal>www.example.net/cgi/testing.pl</literal> for instance. All these
2138     cases are matched.
2139    </para>
2140   </listitem>
2141  </varlistentry>
2142 </variablelist>
2143
2144 <para>
2145  Additionally, there are wild-cards that you can use in the domain names
2146  themselves. These work similarly to shell globbing type wild-cards:
2147  <quote>*</quote> represents zero or more arbitrary characters (this is
2148  equivalent to the
2149  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2150  Expression</quote></ulink> based syntax of <quote>.*</quote>),
2151  <quote>?</quote>  represents any single character (this is equivalent to the
2152  regular expression syntax of a simple <quote>.</quote>), and you can define
2153  <quote>character classes</quote> in square brackets which is similar to
2154  the same regular expression technique. All of this can be freely mixed:
2155 </para>
2156
2157 <variablelist>
2158  <varlistentry>
2159   <term><literal>ad*.example.com</literal></term>
2160   <listitem>
2161    <para>
2162     matches <quote>adserver.example.com</quote>,
2163     <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2164    </para>
2165   </listitem>
2166  </varlistentry>
2167  <varlistentry>
2168   <term><literal>*ad*.example.com</literal></term>
2169   <listitem>
2170    <para>
2171     matches all of the above, and then some.
2172    </para>
2173   </listitem>
2174  </varlistentry>
2175  <varlistentry>
2176   <term><literal>.?pix.com</literal></term>
2177   <listitem>
2178    <para>
2179     matches <literal>www.ipix.com</literal>,
2180     <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2181    </para>
2182   </listitem>
2183  </varlistentry>
2184  <varlistentry>
2185   <term><literal>www[1-9a-ez].example.c*</literal></term>
2186   <listitem>
2187    <para>
2188      matches <literal>www1.example.com</literal>,
2189      <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2190      <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2191      <literal>wwww.example.com</literal>.
2192    </para>
2193   </listitem>
2194  </varlistentry>
2195 </variablelist>
2196
2197 <para>
2198  While flexible, this is not the sophistication of full regular expression based syntax.
2199 </para>
2200
2201 </sect3>
2202
2203 <!--  ~  End section  ~  -->
2204
2205
2206 <!--   ~~~~~       New section      ~~~~~     -->
2207 <sect3><title>The Path Pattern</title>
2208
2209 <para>
2210  <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
2211   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2212   Expressions</quote></ulink> for matching the path portion (after the slash),
2213   and is thus more flexible.
2214 </para>
2215
2216 <para>
2217  There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2218  expressions, you also might want to have a look at your operating system's documentation
2219  on regular expressions (try <literal>man re_format</literal>).
2220 </para>
2221
2222 <para>
2223  Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2224  i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
2225  for the beginning of a line).
2226 </para>
2227
2228 <para>
2229  Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
2230  by default, but you can switch to case sensitive at any point in the pattern by using the
2231  <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
2232  only documents whose path starts with <literal>PaTtErN</literal> in
2233  <emphasis>exactly</emphasis> this capitalization.
2234 </para>
2235
2236 <variablelist>
2237  <varlistentry>
2238   <term><literal>.example.com/.*</literal></term>
2239   <listitem>
2240    <para>
2241      Is equivalent to just <quote>.example.com</quote>, since any documents
2242      within that domain are matched with or without the <quote>.*</quote>
2243      regular expression. This is redundant
2244    </para>
2245   </listitem>
2246  </varlistentry>
2247  <varlistentry>
2248   <term><literal>.example.com/.*/index.html$</literal></term>
2249   <listitem>
2250    <para>
2251     Will match any page in the domain of <quote>example.com</quote> that is
2252     named <quote>index.html</quote>, and that is part of some path. For
2253     example, it matches <quote>www.example.com/testing/index.html</quote> but
2254     NOT <quote>www.example.com/index.html</quote> because the regular
2255     expression called for at least two <quote>/'s</quote>, thus the path
2256     requirement. It also would match
2257     <quote>www.example.com/testing/index_html</quote>, because of the
2258     special meta-character <quote>.</quote>.
2259    </para>
2260   </listitem>
2261  </varlistentry>
2262  <varlistentry>
2263   <term><literal>.example.com/(.*/)?index\.html$</literal></term>
2264   <listitem>
2265    <para>
2266     This regular expression is conditional so it will match any page
2267     named <quote>index.html</quote> regardless of path which in this case can
2268     have one or more <quote>/'s</quote>. And this one must contain exactly
2269     <quote>.html</quote> (but does not have to end with that!).
2270    </para>
2271   </listitem>
2272  </varlistentry>
2273  <varlistentry>
2274   <term><literal>.example.com/(.*/)(ads|banners?|junk)</literal></term>
2275   <listitem>
2276    <para>
2277     This regular expression will match any path of <quote>example.com</quote>
2278     that contains any of the words <quote>ads</quote>, <quote>banner</quote>,
2279     <quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
2280     The path does not have to end in these words, just contain them.
2281    </para>
2282   </listitem>
2283  </varlistentry>
2284  <varlistentry>
2285   <term><literal>.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</literal></term>
2286   <listitem>
2287    <para>
2288     This is very much the same as above, except now it must end in either
2289     <quote>.jpg</quote>, <quote>.jpeg</quote>, <quote>.gif</quote> or <quote>.png</quote>. So this
2290     one is limited to common image formats.
2291    </para>
2292   </listitem>
2293  </varlistentry>
2294
2295 </variablelist>
2296 <para>
2297  There are many, many good examples to be found in <filename>default.action</filename>,
2298  and more tutorials below in <link linkend="regex">Appendix on regular expressions</link>.
2299 </para>
2300
2301 </sect3>
2302
2303 <!--  ~  End section  ~  -->
2304
2305
2306 <!--   ~~~~~       New section      ~~~~~     -->
2307 <sect3 id="tag-pattern"><title>The Tag Pattern</title>
2308
2309 <para>
2310  Tag patterns are used to change the applying actions based on the
2311  request's tags. Tags can be created with either the
2312  <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
2313  or the  <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
2314 </para>
2315
2316 <para>
2317  Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
2318  can tell them apart from URL patterns. Everything after the colon
2319  including white space, is interpreted as a regular expression with
2320  path pattern syntax, except that tag patterns aren't left-anchored
2321  automatically (&my-app; doesn't silently add a <quote>^</quote>,
2322  you have to do it yourself if you need it).
2323 </para>
2324
2325 <para>
2326  To match all requests that are tagged with <quote>foo</quote>
2327  your pattern line should be <quote>TAG:^foo$</quote>,
2328  <quote>TAG:foo</quote> would work as well, but it would also
2329  match requests whose tags contain <quote>foo</quote> somewhere.
2330  <quote>TAG: foo</quote> wouldn't work as it requires white space.
2331 </para>
2332
2333 <para>
2334  Sections can contain URL and tag patterns at the same time,
2335  but tag patterns are checked after the URL patterns and thus
2336  always overrule them, even if they are located before the URL patterns.
2337 </para>
2338
2339 <para>
2340  Once a new tag is added, Privoxy checks right away if it's matched by one
2341  of the tag patterns and updates the action settings accordingly. As a result
2342  tags can be used to activate other tagger actions, as long as these other
2343  taggers look for headers that haven't already be parsed.
2344 </para>
2345
2346 <para>
2347  For example you could tag client requests which use the
2348  <literal>POST</literal> method,
2349  then use this tag to activate another tagger that adds a tag if cookies
2350  are sent, and then use a block action based on the cookie tag. This allows
2351  the outcome of one action, to be input into a subsequent action. However if
2352  you'd reverse the position of the described taggers, and activated the
2353  method tagger based on the cookie tagger, no method tags would be created.
2354  The method tagger would look for the request line, but at the time
2355  the cookie tag is created, the request line has already been parsed.
2356 </para>
2357
2358 <para>
2359  While this is a limitation you should be aware of, this kind of
2360  indirection is seldom needed anyway and even the example doesn't
2361  make too much sense.
2362 </para>
2363
2364 </sect3>
2365
2366 </sect2>
2367
2368 <!--  ~  End section  ~  -->
2369
2370
2371 <!--   ~~~~~       New section      ~~~~~     -->
2372
2373 <sect2 id="actions">
2374 <title>Actions</title>
2375 <para>
2376  All actions are disabled by default, until they are explicitly enabled
2377  somewhere in an actions file. Actions are turned on if preceded with a
2378  <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
2379  <literal>+action</literal> means <quote>do that action</quote>, e.g.
2380  <literal>+block</literal> means <quote>please block URLs that match the
2381  following patterns</quote>, and <literal>-block</literal> means <quote>don't
2382  block URLs that match the following patterns, even if <literal>+block</literal>
2383  previously applied.</quote>
2384
2385 </para>
2386
2387 <para>
2388  Again, actions are invoked by placing them on a line, enclosed in curly braces and
2389  separated by whitespace, like in
2390  <literal>{+some-action -some-other-action{some-parameter}}</literal>,
2391  followed by a list of URL patterns, one per line, to which they apply.
2392  Together, the actions line and the following pattern lines make up a section
2393  of the actions file.
2394 </para>
2395
2396 <para>
2397  Actions fall into three categories:
2398 </para>
2399
2400 <para>
2401  <itemizedlist>
2402  <listitem>
2403   <para>
2404    Boolean, i.e the action can only be <quote>enabled</quote> or
2405    <quote>disabled</quote>. Syntax:
2406   </para>
2407   <para>
2408    <screen>
2409   +<replaceable class="function">name</replaceable>        # enable action <replaceable class="parameter">name</replaceable>
2410   -<replaceable class="function">name</replaceable>        # disable action <replaceable class="parameter">name</replaceable></screen>
2411   </para>
2412   <para>
2413    Example: <literal>+handle-as-image</literal>
2414   </para>
2415  </listitem>
2416
2417
2418  <listitem>
2419   <para>
2420    Parameterized, where some value is required in order to enable this type of action.
2421    Syntax:
2422   </para>
2423   <para>
2424    <screen>
2425   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}  # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
2426                # overwriting parameter from previous match if necessary
2427   -<replaceable class="function">name</replaceable>         # disable action. The parameter can be omitted</screen>
2428   </para>
2429   <para>
2430    Note that if the URL matches multiple positive forms of a parameterized action,
2431    the last match wins, i.e. the params from earlier matches are simply ignored.
2432   </para>
2433   <para>
2434    Example: <literal>+hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4}</literal>
2435   </para>
2436  </listitem>
2437
2438  <listitem>
2439   <para>
2440    Multi-value. These look exactly like parameterized actions,
2441    but they behave differently: If the action applies multiple times to the
2442    same URL, but with different parameters, <emphasis>all</emphasis> the parameters
2443    from <emphasis>all</emphasis> matches are remembered. This is used for actions
2444    that can be executed for the same request repeatedly, like adding multiple
2445    headers, or filtering through multiple filters. Syntax:
2446   </para>
2447   <para>
2448    <screen>
2449   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
2450   -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
2451                 # If it was the last one left, disable the action.
2452   <replaceable class="parameter">-name</replaceable>          # disable this action completely and remove all parameters from the list</screen>
2453   </para>
2454   <para>
2455    Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
2456    <literal>+filter{html-annoyances}</literal>
2457   </para>
2458  </listitem>
2459
2460  </itemizedlist>
2461 </para>
2462
2463 <para>
2464  If nothing is specified in any actions file, no <quote>actions</quote> are
2465  taken. So in this case <application>Privoxy</application> would just be a
2466  normal, non-blocking, non-filtering proxy. You must specifically enable the
2467  privacy and blocking features you need (although the provided default actions
2468  files will give a good starting point).
2469 </para>
2470
2471 <para>
2472  Later defined action sections always over-ride earlier ones of the same type.
2473  So exceptions to any rules you make, should come in the latter part of the file (or
2474  in a file that is processed later when using multiple actions files such
2475  as <filename>user.action</filename>). For multi-valued actions, the actions
2476  are applied in the order they are specified. Actions files are processed in
2477  the order they are defined in <filename>config</filename> (the default
2478  installation has three actions files). It also quite possible for any given
2479  URL to match more than one <quote>pattern</quote> (because of wildcards and
2480  regular expressions), and thus to trigger more than one set of actions! Last
2481  match wins.
2482 </para>
2483
2484 <!-- start actions listing -->
2485 <para>
2486  The list of valid <application>Privoxy</application> actions are:
2487 </para>
2488
2489
2490 <!-- ********************************************************** -->
2491 <!-- Please note the below defined actions use id's that are    -->
2492 <!-- probably linked from other places, so please don't change. -->
2493 <!--                                                            -->
2494 <!-- ********************************************************** -->
2495
2496
2497 <!--   ~~~~~       New section      ~~~~~     -->
2498
2499 <sect3 renderas="sect4" id="add-header">
2500 <title>add-header</title>
2501
2502 <variablelist>
2503  <varlistentry>
2504   <term>Typical use:</term>
2505   <listitem>
2506    <para>Confuse log analysis, custom applications</para>
2507   </listitem>
2508  </varlistentry>
2509
2510  <varlistentry>
2511   <term>Effect:</term>
2512   <listitem>
2513    <para>
2514     Sends a user defined HTTP header to the web server.
2515    </para>
2516   </listitem>
2517  </varlistentry>
2518
2519  <varlistentry>
2520   <term>Type:</term>
2521   <!-- boolean, parameterized, Multi-value -->
2522   <listitem>
2523    <para>Multi-value.</para>
2524   </listitem>
2525  </varlistentry>
2526
2527  <varlistentry>
2528   <term>Parameter:</term>
2529   <listitem>
2530    <para>
2531     Any string value is possible. Validity of the defined HTTP headers is not checked.
2532     It is recommended that you use the <quote><literal>X-</literal></quote> prefix
2533     for custom headers.
2534    </para>
2535   </listitem>
2536  </varlistentry>
2537
2538 <varlistentry>
2539   <term>Notes:</term>
2540   <listitem>
2541    <para>
2542     This action may be specified multiple times, in order to define multiple
2543     headers. This is rarely needed for the typical user. If you don't know what
2544     <quote>HTTP headers</quote> are, you definitely don't need to worry about this
2545     one.
2546    </para>
2547    <para>
2548     Headers added by this action are not modified by other actions.
2549    </para>
2550   </listitem>
2551  </varlistentry>
2552
2553  <varlistentry>
2554   <term>Example usage:</term>
2555   <listitem>
2556     <para>
2557      <screen>+add-header{X-User-Tracking: sucks}</screen>
2558    </para>
2559   </listitem>
2560  </varlistentry>
2561 </variablelist>
2562 </sect3>
2563
2564
2565 <!--   ~~~~~       New section      ~~~~~     -->
2566 <sect3 renderas="sect4" id="block">
2567 <title>block</title>
2568
2569 <variablelist>
2570  <varlistentry>
2571   <term>Typical use:</term>
2572   <listitem>
2573    <para>Block ads or other unwanted content</para>
2574   </listitem>
2575  </varlistentry>
2576
2577  <varlistentry>
2578   <term>Effect:</term>
2579   <listitem>
2580    <para>
2581     Requests for URLs to which this action applies are blocked, i.e. the
2582     requests are trapped by &my-app; and the requested URL is never retrieved,
2583     but is answered locally with a substitute page or image, as determined by
2584     the <literal><link
2585     linkend="handle-as-image">handle-as-image</link></literal>,
2586     <literal><link
2587     linkend="set-image-blocker">set-image-blocker</link></literal>, and
2588     <literal><link
2589     linkend="handle-as-empty-document">handle-as-empty-document</link></literal> actions.
2590
2591    </para>
2592   </listitem>
2593  </varlistentry>
2594
2595  <varlistentry>
2596   <term>Type:</term>
2597   <!-- boolean, parameterized, Multi-value -->
2598   <listitem>
2599    <para>Parameterized.</para>
2600   </listitem>
2601  </varlistentry>
2602
2603  <varlistentry>
2604   <term>Parameter:</term>
2605   <listitem>
2606    <para>A block reason that should be given to the user.</para>
2607   </listitem>
2608  </varlistentry>
2609
2610 <varlistentry>
2611   <term>Notes:</term>
2612   <listitem>
2613    <para>
2614     <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
2615     for requests to blocked pages. This page contains the block reason given as
2616     parameter, a link to find out why the block action applies, and a click-through
2617     to the blocked content (the latter only if the force feature is available and
2618     enabled).
2619    </para>
2620    <para>
2621     A very important exception occurs if <emphasis>both</emphasis>
2622     <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
2623     apply to the same request: it will then be replaced by an image. If
2624     <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
2625     (see below) also applies, the type of image will be determined by its parameter,
2626     if not, the standard checkerboard pattern is sent.
2627    </para>
2628    <para>
2629     It is important to understand this process, in order
2630     to understand how <application>Privoxy</application> deals with
2631     ads and other unwanted content. Blocking is a core feature, and one
2632     upon which various other features depend.
2633    </para>
2634    <para>
2635     The <literal><link linkend="filter">filter</link></literal>
2636     action can perform a very similar task, by <quote>blocking</quote>
2637     banner images and other content through rewriting the relevant URLs in the
2638     document's HTML source, so they don't get requested in the first place.
2639     Note that this is a totally different technique, and it's easy to confuse the two.
2640    </para>
2641   </listitem>
2642  </varlistentry>
2643
2644  <varlistentry>
2645   <term>Example usage (section):</term>
2646   <listitem>
2647     <para>
2648      <screen>{+block{No nasty stuff for you.}}
2649 # Block and replace with "blocked" page
2650  .nasty-stuff.example.com
2651
2652 {+block{Doubleclick banners.} +handle-as-image}
2653 # Block and replace with image
2654  .ad.doubleclick.net
2655  .ads.r.us/banners/
2656
2657 {+block{Layered ads.} +handle-as-empty-document}
2658 # Block and then ignore
2659  adserver.example.net/.*\.js$</screen>
2660     </para>
2661   </listitem>
2662  </varlistentry>
2663
2664
2665 </variablelist>
2666 </sect3>
2667
2668
2669 <!--   ~~~~~       New section      ~~~~~     -->
2670 <sect3 renderas="sect4" id="change-x-forwarded-for">
2671 <title>change-x-forwarded-for</title>
2672
2673 <variablelist>
2674  <varlistentry>
2675   <term>Typical use:</term>
2676   <listitem>
2677    <para>Improve privacy by not forwarding the source of the request in the HTTP headers.</para>
2678   </listitem>
2679  </varlistentry>
2680
2681  <varlistentry>
2682   <term>Effect:</term>
2683   <listitem>
2684    <para>
2685     Deletes the <quote>X-Forwarded-For:</quote> HTTP header from the client request,
2686     or adds a new one.
2687    </para>
2688   </listitem>
2689  </varlistentry>
2690
2691  <varlistentry>
2692   <term>Type:</term>
2693   <!-- Boolean, Parameterized, Multi-value -->
2694   <listitem>
2695    <para>Parameterized.</para>
2696   </listitem>
2697  </varlistentry>
2698
2699  <varlistentry>
2700   <term>Parameter:</term>
2701   <listitem>
2702    <itemizedlist>
2703     <listitem>
2704      <para><quote>block</quote> to delete the header.</para>
2705     </listitem>
2706     <listitem>
2707      <para>
2708        <quote>add</quote> to create the header (or append
2709        the client's IP address to an already existing one).
2710      </para>
2711     </listitem>
2712    </itemizedlist>
2713   </listitem>
2714  </varlistentry>
2715
2716  <varlistentry>
2717   <term>Notes:</term>
2718   <listitem>
2719    <para>
2720     It is safe and recommended to use <literal>block</literal>.
2721    </para>
2722    <para>
2723     Forwarding the source address of the request may make
2724     sense in some multi-user setups but is also a privacy risk.
2725    </para>
2726   </listitem>
2727  </varlistentry>
2728  <varlistentry>
2729   <term>Example usage:</term>
2730   <listitem>
2731     <para>
2732      <screen>+change-x-forwarded-for{block}</screen>
2733    </para>
2734   </listitem>
2735  </varlistentry>
2736 </variablelist>
2737 </sect3>
2738
2739 <!--   ~~~~~       New section      ~~~~~     -->
2740 <sect3 renderas="sect4" id="client-header-filter">
2741 <title>client-header-filter</title>
2742
2743 <variablelist>
2744  <varlistentry>
2745   <term>Typical use:</term>
2746   <listitem>
2747    <para>
2748    Rewrite or remove single client headers.
2749    </para>
2750   </listitem>
2751  </varlistentry>
2752
2753  <varlistentry>
2754   <term>Effect:</term>
2755   <listitem>
2756    <para>
2757     All client headers to which this action applies are filtered on-the-fly through
2758     the specified regular expression based substitutions.
2759    </para>
2760   </listitem>
2761  </varlistentry>
2762
2763  <varlistentry>
2764   <term>Type:</term>
2765   <!-- boolean, parameterized, Multi-value -->
2766   <listitem>
2767    <para>Parameterized.</para>
2768   </listitem>
2769  </varlistentry>
2770
2771  <varlistentry>
2772   <term>Parameter:</term>
2773   <listitem>
2774    <para>
2775     The name of a client-header filter, as defined in one of the
2776     <link linkend="filter-file">filter files</link>.
2777    </para>
2778   </listitem>
2779  </varlistentry>
2780
2781  <varlistentry>
2782   <term>Notes:</term>
2783   <listitem>
2784    <para>
2785     Client-header filters are applied to each header on its own, not to
2786     all at once. This makes it easier to diagnose problems, but on the downside
2787     you can't write filters that only change header x if header y's value is z.
2788     You can do that by using tags though.
2789    </para>
2790    <para>
2791     Client-header filters are executed after the other header actions have finished
2792     and use their output as input.
2793    </para>
2794    <para>
2795     If the request URI gets changed, &my-app; will detect that and use the new
2796     one. This can be used to rewrite the request destination behind the client's
2797     back, for example to specify a Tor exit relay for certain requests.
2798    </para>
2799    <para>
2800     Please refer to the <link linkend="filter-file">filter file chapter</link>
2801     to learn which client-header filters are available by default, and how to
2802     create your own.
2803    </para>
2804
2805   </listitem>
2806  </varlistentry>
2807
2808  <varlistentry>
2809   <term>Example usage (section):</term>
2810   <listitem>
2811     <para>
2812      <screen>
2813 # Hide Tor exit notation in Host and Referer Headers
2814 {+client-header-filter{hide-tor-exit-notation}}
2815 /
2816     </screen>
2817    </para>
2818   </listitem>
2819  </varlistentry>
2820
2821 </variablelist>
2822 </sect3>
2823
2824
2825 <!--   ~~~~~       New section      ~~~~~     -->
2826 <sect3 renderas="sect4" id="client-header-tagger">
2827 <title>client-header-tagger</title>
2828
2829 <variablelist>
2830  <varlistentry>
2831   <term>Typical use:</term>
2832   <listitem>
2833    <para>
2834    Block requests based on their headers.
2835    </para>
2836   </listitem>
2837  </varlistentry>
2838
2839  <varlistentry>
2840   <term>Effect:</term>
2841   <listitem>
2842    <para>
2843     Client headers to which this action applies are filtered on-the-fly through
2844     the specified regular expression based substitutions, the result is used as
2845     tag.
2846    </para>
2847   </listitem>
2848  </varlistentry>
2849
2850  <varlistentry>
2851   <term>Type:</term>
2852   <!-- boolean, parameterized, Multi-value -->
2853   <listitem>
2854    <para>Parameterized.</para>
2855   </listitem>
2856  </varlistentry>
2857
2858  <varlistentry>
2859   <term>Parameter:</term>
2860   <listitem>
2861    <para>
2862     The name of a client-header tagger, as defined in one of the
2863     <link linkend="filter-file">filter files</link>.
2864    </para>
2865   </listitem>
2866  </varlistentry>
2867
2868  <varlistentry>
2869   <term>Notes:</term>
2870   <listitem>
2871    <para>
2872     Client-header taggers are applied to each header on its own,
2873     and as the header isn't modified, each tagger <quote>sees</quote>
2874     the original.
2875    </para>
2876    <para>
2877     Client-header taggers are the first actions that are executed
2878     and their tags can be used to control every other action.
2879    </para>
2880  </listitem>
2881  </varlistentry>
2882
2883  <varlistentry>
2884   <term>Example usage (section):</term>
2885   <listitem>
2886     <para>
2887      <screen>
2888 # Tag every request with the User-Agent header
2889 {+client-header-tagger{user-agent}}
2890 /
2891
2892 # Tagging itself doesn't change the action
2893 # settings, sections with TAG patterns do:
2894 #
2895 # If it's a download agent, use a different forwarding proxy,
2896 # show the real User-Agent and make sure resume works.
2897 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
2898  -hide-if-modified-since      \
2899  -overwrite-last-modified     \
2900  -hide-user-agent             \
2901  -filter                      \
2902  -deanimate-gifs              \
2903 }
2904 TAG:^User-Agent: NetBSD-ftp/
2905 TAG:^User-Agent: Novell ZYPP Installer
2906 TAG:^User-Agent: RPM APT-HTTP/
2907 TAG:^User-Agent: fetch libfetch/
2908 TAG:^User-Agent: Ubuntu APT-HTTP/
2909 TAG:^User-Agent: MPlayer/
2910     </screen>
2911    </para>
2912    <para>
2913      <screen>
2914 # Tag all requests with the Range header set
2915 {+client-header-tagger{range-requests}}
2916 /
2917
2918 # Disable filtering for the tagged requests.
2919 #
2920 # With filtering enabled Privoxy would remove the Range headers
2921 # to be able to filter the whole response. The downside is that
2922 # it prevents clients from resuming downloads or skipping over
2923 # parts of multimedia files.
2924 {-filter -deanimate-gifs}
2925 TAG:^RANGE-REQUEST$
2926     </screen>
2927     </para>
2928   </listitem>
2929  </varlistentry>
2930
2931 </variablelist>
2932 </sect3>
2933
2934
2935 <!--   ~~~~~       New section      ~~~~~     -->
2936 <sect3 renderas="sect4" id="content-type-overwrite">
2937 <title>content-type-overwrite</title>
2938
2939 <variablelist>
2940  <varlistentry>
2941   <term>Typical use:</term>
2942   <listitem>
2943    <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
2944   </listitem>
2945  </varlistentry>
2946
2947  <varlistentry>
2948   <term>Effect:</term>
2949   <listitem>
2950    <para>
2951     Replaces the <quote>Content-Type:</quote> HTTP server header.
2952    </para>
2953   </listitem>
2954  </varlistentry>
2955
2956  <varlistentry>
2957   <term>Type:</term>
2958   <!-- Boolean, Parameterized, Multi-value -->
2959   <listitem>
2960    <para>Parameterized.</para>
2961   </listitem>
2962  </varlistentry>
2963
2964  <varlistentry>
2965   <term>Parameter:</term>
2966   <listitem>
2967    <para>
2968     Any string.
2969    </para>
2970   </listitem>
2971  </varlistentry>
2972
2973  <varlistentry>
2974   <term>Notes:</term>
2975   <listitem>
2976    <para>
2977     The <quote>Content-Type:</quote> HTTP server header is used by the
2978     browser to decide what to do with the document. The value of this
2979     header can cause the browser to open a download menu instead of
2980     displaying the document by itself, even if the document's format is
2981     supported by the browser.
2982    </para>
2983    <para>
2984     The declared content type can also affect which rendering mode
2985     the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
2986     many browsers treat it as yet another broken HTML document.
2987     If it is send as <quote>application/xml</quote>, browsers with
2988     XHTML support will only display it, if the syntax is correct.
2989    </para>
2990    <para>
2991     If you see a web site that proudly uses XHTML buttons, but sets
2992     <quote>Content-Type: text/html</quote>, you can use &my-app;
2993     to overwrite it with <quote>application/xml</quote> and validate
2994     the web master's claim inside your XHTML-supporting browser.
2995     If the syntax is incorrect, the browser will complain loudly.
2996    </para>
2997    <para>
2998     You can also go the opposite direction: if your browser prints
2999     error messages instead of rendering a document falsely declared
3000     as XHTML, you can overwrite the content type with
3001     <quote>text/html</quote> and have it rendered as broken HTML document.
3002    </para>
3003    <para>
3004     By default <literal>content-type-overwrite</literal> only replaces
3005     <quote>Content-Type:</quote> headers that look like some kind of text.
3006     If you want to overwrite it unconditionally, you have to combine it with
3007     <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
3008     This limitation exists for a reason, think twice before circumventing it.
3009    </para>
3010    <para>
3011     Most of the time it's easier to replace this action with a custom
3012     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3013     It allows you to activate it for every document of a certain site and it will still
3014     only replace the content types you aimed at.
3015    </para>
3016    <para>
3017     Of course you can apply <literal>content-type-overwrite</literal>
3018     to a whole site and then make URL based exceptions, but it's a lot
3019     more work to get the same precision.
3020    </para>
3021   </listitem>
3022  </varlistentry>
3023
3024  <varlistentry>
3025   <term>Example usage (sections):</term>
3026   <listitem>
3027     <para>
3028      <screen># Check if www.example.net/ really uses valid XHTML
3029 { +content-type-overwrite{application/xml} }
3030 www.example.net/
3031
3032 # but leave the content type unmodified if the URL looks like a style sheet
3033 {-content-type-overwrite}
3034 www.example.net/.*\.css$
3035 www.example.net/.*style
3036 </screen>
3037    </para>
3038   </listitem>
3039  </varlistentry>
3040 </variablelist>
3041 </sect3>
3042
3043
3044 <!--   ~~~~~       New section      ~~~~~     -->
3045 <sect3 renderas="sect4" id="crunch-client-header">
3046 <!--
3047 new action
3048 -->
3049 <title>crunch-client-header</title>
3050
3051 <variablelist>
3052  <varlistentry>
3053   <term>Typical use:</term>
3054   <listitem>
3055    <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
3056   </listitem>
3057  </varlistentry>
3058
3059  <varlistentry>
3060   <term>Effect:</term>
3061   <listitem>
3062    <para>
3063     Deletes every header sent by the client that contains the string the user supplied as parameter.
3064    </para>
3065   </listitem>
3066  </varlistentry>
3067
3068  <varlistentry>
3069   <term>Type:</term>
3070   <!-- Boolean, Parameterized, Multi-value -->
3071   <listitem>
3072    <para>Parameterized.</para>
3073   </listitem>
3074  </varlistentry>
3075
3076  <varlistentry>
3077   <term>Parameter:</term>
3078   <listitem>
3079    <para>
3080     Any string.
3081    </para>
3082   </listitem>
3083  </varlistentry>
3084
3085  <varlistentry>
3086   <term>Notes:</term>
3087   <listitem>
3088    <para>
3089     This action allows you to block client headers for which no dedicated
3090     <application>Privoxy</application> action exists.
3091     <application>Privoxy</application> will remove every client header that
3092     contains the string you supplied as parameter.
3093    </para>
3094    <para>
3095     Regular expressions are <emphasis>not supported</emphasis> and you can't
3096     use this action to block different headers in the same request, unless
3097     they contain the same string.
3098    </para>
3099    <para>
3100     <literal>crunch-client-header</literal> is only meant for quick tests.
3101     If you have to block several different headers, or only want to modify
3102     parts of them, you should use a
3103     <literal><link linkend="client-header-filter">client-header filter</link></literal>.
3104    </para>
3105     <warning>
3106      <para>
3107       Don't block any header without understanding the consequences.
3108      </para>
3109     </warning>
3110   </listitem>
3111  </varlistentry>
3112
3113  <varlistentry>
3114   <term>Example usage (section):</term>
3115   <listitem>
3116     <para>
3117      <screen># Block the non-existent "Privacy-Violation:" client header
3118 { +crunch-client-header{Privacy-Violation:} }
3119 /
3120     </screen>
3121    </para>
3122   </listitem>
3123  </varlistentry>
3124 </variablelist>
3125 </sect3>
3126
3127
3128 <!--   ~~~~~       New section      ~~~~~     -->
3129 <sect3 renderas="sect4" id="crunch-if-none-match">
3130 <title>crunch-if-none-match</title>
3131 <!--
3132 new action
3133 -->
3134 <variablelist>
3135  <varlistentry>
3136   <term>Typical use:</term>
3137   <listitem>
3138    <para>Prevent yet another way to track the user's steps between sessions.</para>
3139   </listitem>
3140  </varlistentry>
3141
3142  <varlistentry>
3143   <term>Effect:</term>
3144   <listitem>
3145    <para>
3146     Deletes the <quote>If-None-Match:</quote> HTTP client header.
3147    </para>
3148   </listitem>
3149  </varlistentry>
3150
3151  <varlistentry>
3152   <term>Type:</term>
3153   <!-- Boolean, Parameterized, Multi-value -->
3154   <listitem>
3155    <para>Boolean.</para>
3156   </listitem>
3157  </varlistentry>
3158
3159  <varlistentry>
3160   <term>Parameter:</term>
3161   <listitem>
3162    <para>
3163     N/A
3164    </para>
3165   </listitem>
3166  </varlistentry>
3167
3168  <varlistentry>
3169   <term>Notes:</term>
3170   <listitem>
3171    <para>
3172     Removing the <quote>If-None-Match:</quote> HTTP client header
3173     is useful for filter testing, where you want to force a real
3174     reload instead of getting status code <quote>304</quote> which
3175     would cause the browser to use a cached copy of the page.
3176    </para>
3177    <para>
3178     It is also useful to make sure the header isn't used as a cookie
3179     replacement (unlikely but possible).
3180    </para>
3181    <para>
3182     Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
3183     caching problems, as long as the <quote>If-Modified-Since:</quote> header
3184     isn't blocked or missing as well.
3185    </para>
3186    <para>
3187     It is recommended to use this action together with
3188     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
3189     and
3190     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
3191    </para>
3192   </listitem>
3193  </varlistentry>
3194
3195  <varlistentry>
3196   <term>Example usage (section):</term>
3197   <listitem>
3198     <para>
3199      <screen># Let the browser revalidate cached documents but don't
3200 # allow the server to use the revalidation headers for user tracking.
3201 {+hide-if-modified-since{-60} \
3202  +overwrite-last-modified{randomize} \
3203  +crunch-if-none-match}
3204 /   </screen>
3205    </para>
3206   </listitem>
3207  </varlistentry>
3208 </variablelist>
3209 </sect3>
3210
3211
3212 <!--   ~~~~~       New section      ~~~~~     -->
3213 <sect3 renderas="sect4" id="crunch-incoming-cookies">
3214 <title>crunch-incoming-cookies</title>
3215
3216 <variablelist>
3217  <varlistentry>
3218   <term>Typical use:</term>
3219   <listitem>
3220    <para>
3221     Prevent the web server from setting HTTP cookies on your system
3222    </para>
3223   </listitem>
3224  </varlistentry>
3225
3226  <varlistentry>
3227   <term>Effect:</term>
3228   <listitem>
3229    <para>
3230     Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
3231    </para>
3232   </listitem>
3233  </varlistentry>
3234
3235  <varlistentry>
3236   <term>Type:</term>
3237   <!-- Boolean, Parameterized, Multi-value -->
3238   <listitem>
3239    <para>Boolean.</para>
3240   </listitem>
3241  </varlistentry>
3242
3243  <varlistentry>
3244   <term>Parameter:</term>
3245   <listitem>
3246    <para>
3247     N/A
3248    </para>
3249   </listitem>
3250  </varlistentry>
3251
3252  <varlistentry>
3253   <term>Notes:</term>
3254   <listitem>
3255    <para>
3256     This action is only concerned with <emphasis>incoming</emphasis> HTTP cookies. For
3257     <emphasis>outgoing</emphasis> HTTP cookies, use
3258     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
3259     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3260    </para>
3261    <para>
3262     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3263     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3264     since it would prevent the session cookies from being set. See also
3265     <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
3266    </para>
3267   </listitem>
3268  </varlistentry>
3269
3270  <varlistentry>
3271   <term>Example usage:</term>
3272   <listitem>
3273    <para>
3274     <screen>+crunch-incoming-cookies</screen>
3275    </para>
3276   </listitem>
3277  </varlistentry>
3278 </variablelist>
3279 </sect3>
3280
3281
3282 <!--   ~~~~~       New section      ~~~~~     -->
3283 <sect3 renderas="sect4" id="crunch-server-header">
3284 <title>crunch-server-header</title>
3285 <!--
3286 new action
3287 -->
3288 <variablelist>
3289  <varlistentry>
3290   <term>Typical use:</term>
3291   <listitem>
3292    <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
3293   </listitem>
3294  </varlistentry>
3295
3296  <varlistentry>
3297   <term>Effect:</term>
3298   <listitem>
3299    <para>
3300     Deletes every header sent by the server that contains the string the user supplied as parameter.
3301    </para>
3302   </listitem>
3303  </varlistentry>
3304
3305  <varlistentry>
3306   <term>Type:</term>
3307   <!-- Boolean, Parameterized, Multi-value -->
3308   <listitem>
3309    <para>Parameterized.</para>
3310   </listitem>
3311  </varlistentry>
3312
3313  <varlistentry>
3314   <term>Parameter:</term>
3315   <listitem>
3316    <para>
3317     Any string.
3318    </para>
3319   </listitem>
3320  </varlistentry>
3321
3322  <varlistentry>
3323   <term>Notes:</term>
3324   <listitem>
3325    <para>
3326     This action allows you to block server headers for which no dedicated
3327     <application>Privoxy</application> action exists. <application>Privoxy</application>
3328     will remove every server header that contains the string you supplied as parameter.
3329    </para>
3330    <para>
3331     Regular expressions are <emphasis>not supported</emphasis> and you can't
3332     use this action to block different headers in the same request, unless
3333     they contain the same string.
3334    </para>
3335    <para>
3336     <literal>crunch-server-header</literal> is only meant for quick tests.
3337     If you have to block several different headers, or only want to modify
3338     parts of them, you should use a custom
3339     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3340    </para>
3341     <warning>
3342      <para>
3343      Don't block any header without understanding the consequences.
3344      </para>
3345     </warning>
3346   </listitem>
3347  </varlistentry>
3348
3349  <varlistentry>
3350   <term>Example usage (section):</term>
3351   <listitem>
3352     <para>
3353      <screen># Crunch server headers that try to prevent caching
3354 { +crunch-server-header{no-cache} }
3355 /   </screen>
3356    </para>
3357   </listitem>
3358  </varlistentry>
3359 </variablelist>
3360 </sect3>
3361
3362
3363 <!--   ~~~~~       New section      ~~~~~     -->
3364 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
3365 <title>crunch-outgoing-cookies</title>
3366
3367 <variablelist>
3368  <varlistentry>
3369   <term>Typical use:</term>
3370   <listitem>
3371    <para>
3372     Prevent the web server from reading any HTTP cookies from your system
3373    </para>
3374   </listitem>
3375  </varlistentry>
3376
3377  <varlistentry>
3378   <term>Effect:</term>
3379   <listitem>
3380    <para>
3381     Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
3382    </para>
3383   </listitem>
3384  </varlistentry>
3385
3386  <varlistentry>
3387   <term>Type:</term>
3388   <!-- Boolean, Parameterized, Multi-value -->
3389   <listitem>
3390    <para>Boolean.</para>
3391   </listitem>
3392  </varlistentry>
3393
3394  <varlistentry>
3395   <term>Parameter:</term>
3396   <listitem>
3397    <para>
3398     N/A
3399    </para>
3400   </listitem>
3401  </varlistentry>
3402
3403  <varlistentry>
3404   <term>Notes:</term>
3405   <listitem>
3406    <para>
3407     This action is only concerned with <emphasis>outgoing</emphasis> HTTP cookies. For
3408     <emphasis>incoming</emphasis> HTTP cookies, use
3409     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
3410     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3411    </para>
3412    <para>
3413     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3414     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3415     since it would prevent the session cookies from being read.
3416    </para>
3417   </listitem>
3418  </varlistentry>
3419
3420  <varlistentry>
3421   <term>Example usage:</term>
3422   <listitem>
3423    <para>
3424     <screen>+crunch-outgoing-cookies</screen>
3425    </para>
3426   </listitem>
3427  </varlistentry>
3428
3429 </variablelist>
3430 </sect3>
3431
3432
3433 <!--   ~~~~~       New section      ~~~~~     -->
3434 <sect3 renderas="sect4" id="deanimate-gifs">
3435 <title>deanimate-gifs</title>
3436
3437 <variablelist>
3438  <varlistentry>
3439   <term>Typical use:</term>
3440   <listitem>
3441    <para>Stop those annoying, distracting animated GIF images.</para>
3442   </listitem>
3443  </varlistentry>
3444
3445  <varlistentry>
3446   <term>Effect:</term>
3447   <listitem>
3448    <para>
3449     De-animate GIF animations, i.e. reduce them to their first or last image.
3450    </para>
3451   </listitem>
3452  </varlistentry>
3453
3454  <varlistentry>
3455   <term>Type:</term>
3456   <!-- boolean, parameterized, Multi-value -->
3457   <listitem>
3458    <para>Parameterized.</para>
3459   </listitem>
3460  </varlistentry>
3461
3462  <varlistentry>
3463   <term>Parameter:</term>
3464   <listitem>
3465    <para>
3466     <quote>last</quote> or <quote>first</quote>
3467    </para>
3468   </listitem>
3469  </varlistentry>
3470
3471  <varlistentry>
3472   <term>Notes:</term>
3473   <listitem>
3474    <para>
3475     This will also shrink the images considerably (in bytes, not pixels!). If
3476     the option <quote>first</quote> is given, the first frame of the animation
3477     is used as the replacement. If <quote>last</quote> is given, the last
3478     frame of the animation is used instead, which probably makes more sense for
3479     most banner animations, but also has the risk of not showing the entire
3480     last frame (if it is only a delta to an earlier frame).
3481    </para>
3482    <para>
3483     You can safely use this action with patterns that will also match non-GIF
3484     objects, because no attempt will be made at anything that doesn't look like
3485     a GIF.
3486    </para>
3487   </listitem>
3488  </varlistentry>
3489
3490  <varlistentry>
3491   <term>Example usage:</term>
3492   <listitem>
3493     <para>
3494       <screen>+deanimate-gifs{last}</screen>
3495     </para>
3496   </listitem>
3497  </varlistentry>
3498 </variablelist>
3499 </sect3>
3500
3501 <!--   ~~~~~       New section      ~~~~~     -->
3502 <sect3 renderas="sect4" id="downgrade-http-version">
3503 <title>downgrade-http-version</title>
3504
3505 <variablelist>
3506  <varlistentry>
3507   <term>Typical use:</term>
3508   <listitem>
3509    <para>Work around (very rare) problems with HTTP/1.1</para>
3510   </listitem>
3511  </varlistentry>
3512
3513  <varlistentry>
3514   <term>Effect:</term>
3515   <listitem>
3516    <para>
3517     Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3518    </para>
3519   </listitem>
3520  </varlistentry>
3521
3522  <varlistentry>
3523   <term>Type:</term>
3524   <!-- boolean, parameterized, Multi-value -->
3525   <listitem>
3526    <para>Boolean.</para>
3527   </listitem>
3528  </varlistentry>
3529
3530  <varlistentry>
3531   <term>Parameter:</term>
3532   <listitem>
3533    <para>
3534     N/A
3535    </para>
3536   </listitem>
3537  </varlistentry>
3538
3539 <varlistentry>
3540   <term>Notes:</term>
3541   <listitem>
3542    <para>
3543     This is a left-over from the time when <application>Privoxy</application>
3544     didn't support important HTTP/1.1 features well. It is left here for the
3545     unlikely case that you experience HTTP/1.1-related problems with some server
3546     out there.
3547    </para>
3548    <para>
3549     Note that enabling this action is only a workaround. It should not
3550     be enabled for sites that work without it. While it shouldn't break
3551     any pages, it has an (usually negative) performance impact.
3552   </para>
3553   <para>
3554     If you come across a site where enabling this action helps, please report it,
3555     so the cause of the problem can be analyzed. If the problem turns out to be
3556     caused by a bug in  <application>Privoxy</application> it should be
3557     fixed so the following release works without the work around.
3558    </para>
3559   </listitem>
3560  </varlistentry>
3561
3562  <varlistentry>
3563   <term>Example usage (section):</term>
3564   <listitem>
3565     <para>
3566      <screen>{+downgrade-http-version}
3567 problem-host.example.com</screen>
3568     </para>
3569   </listitem>
3570  </varlistentry>
3571
3572 </variablelist>
3573 </sect3>
3574
3575 <!--   ~~~~~       New section      ~~~~~     -->
3576 <sect3 renderas="sect4" id="fast-redirects">
3577 <title>fast-redirects</title>
3578
3579 <variablelist>
3580  <varlistentry>
3581   <term>Typical use:</term>
3582   <listitem>
3583    <para>Fool some click-tracking scripts and speed up indirect links.</para>
3584   </listitem>
3585  </varlistentry>
3586
3587  <varlistentry>
3588   <term>Effect:</term>
3589   <listitem>
3590    <para>
3591     Detects redirection URLs and redirects the browser without contacting
3592     the redirection server first.
3593    </para>
3594   </listitem>
3595  </varlistentry>
3596
3597  <varlistentry>
3598   <term>Type:</term>
3599   <!-- boolean, parameterized, Multi-value -->
3600   <listitem>
3601    <para>Parameterized.</para>
3602   </listitem>
3603  </varlistentry>
3604
3605  <varlistentry>
3606   <term>Parameter:</term>
3607   <listitem>
3608    <itemizedlist>
3609     <listitem>
3610      <para>
3611       <quote>simple-check</quote> to just search for the string <quote>http://</quote>
3612       to detect redirection URLs.
3613      </para>
3614     </listitem>
3615     <listitem>
3616      <para>
3617       <quote>check-decoded-url</quote> to decode URLs (if necessary) before searching
3618       for redirection URLs.
3619      </para>
3620     </listitem>
3621    </itemizedlist>
3622   </listitem>
3623  </varlistentry>
3624
3625  <varlistentry>
3626   <term>Notes:</term>
3627   <listitem>
3628    <para>
3629     Many sites, like yahoo.com, don't just link to other sites. Instead, they
3630     will link to some script on their own servers, giving the destination as a
3631     parameter, which will then redirect you to the final target. URLs
3632     resulting from this scheme typically look like:
3633     <quote>http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/</quote>.
3634   </para>
3635    <para>
3636     Sometimes, there are even multiple consecutive redirects encoded in the
3637     URL. These redirections via scripts make your web browsing more traceable,
3638     since the server from which you follow such a link can see where you go
3639     to. Apart from that, valuable bandwidth and time is wasted, while your
3640     browser asks the server for one redirect after the other. Plus, it feeds
3641     the advertisers.
3642    </para>
3643    <para>
3644     This feature is currently not very smart and is scheduled for improvement.
3645     If it is enabled by default, you will have to create some exceptions to
3646     this action. It can lead to failures in several ways:
3647    </para>
3648    <para>
3649     Not every URLs with other URLs as parameters is evil.
3650     Some sites offer a real service that requires this information to work.
3651     For example a validation service needs to know, which document to validate.
3652     <literal>fast-redirects</literal> assumes that every URL parameter that
3653     looks like another URL is a redirection target, and will always redirect to
3654     the last one. Most of the time the assumption is correct, but if it isn't,
3655     the user gets redirected anyway.
3656    </para>
3657    <para>
3658     Another failure occurs if the URL contains other parameters after the URL parameter.
3659     The URL:
3660     <quote>http://www.example.org/?redirect=http%3a//www.example.net/&amp;foo=bar</quote>.
3661     contains the redirection URL <quote>http://www.example.net/</quote>,
3662     followed by another parameter. <literal>fast-redirects</literal> doesn't know that
3663     and will cause a redirect to <quote>http://www.example.net/&amp;foo=bar</quote>.
3664     Depending on the target server configuration, the parameter will be silently ignored
3665     or lead to a <quote>page not found</quote> error. You can prevent this problem by
3666     first using the <literal><link linkend="redirect">redirect</link></literal> action
3667     to remove the last part of the URL, but it requires a little effort.
3668    </para>
3669    <para>
3670     To detect a redirection URL, <literal>fast-redirects</literal> only
3671     looks for the string <quote>http://</quote>, either in plain text
3672     (invalid but often used) or encoded as <quote>http%3a//</quote>.
3673     Some sites use their own URL encoding scheme, encrypt the address
3674     of the target server or replace it with a database id. In theses cases
3675     <literal>fast-redirects</literal> is fooled and the request reaches the
3676     redirection server where it probably gets logged.
3677    </para>
3678   </listitem>
3679  </varlistentry>
3680
3681  <varlistentry>
3682   <term>Example usage:</term>
3683   <listitem>
3684     <para>
3685      <screen>
3686  { +fast-redirects{simple-check} }
3687    one.example.com
3688
3689  { +fast-redirects{check-decoded-url} }
3690    another.example.com/testing</screen>
3691     </para>
3692   </listitem>
3693  </varlistentry>
3694
3695 </variablelist>
3696 </sect3>
3697
3698
3699 <!--   ~~~~~       New section      ~~~~~     -->
3700 <sect3 renderas="sect4" id="filter">
3701 <title>filter</title>
3702
3703 <variablelist>
3704  <varlistentry>
3705   <term>Typical use:</term>
3706   <listitem>
3707    <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
3708          do fun text replacements, add personalized effects, etc.</para>
3709   </listitem>
3710  </varlistentry>
3711
3712  <varlistentry>
3713   <term>Effect:</term>
3714   <listitem>
3715    <para>
3716     All instances of text-based type, most notably HTML and JavaScript, to which
3717     this action applies, can be filtered on-the-fly through the specified regular
3718     expression based substitutions. (Note: as of version 3.0.3 plain text documents
3719     are exempted from filtering, because web servers often use the
3720    <literal>text/plain</literal> MIME type for all files whose type they don't know.)
3721    </para>
3722   </listitem>
3723  </varlistentry>
3724
3725  <varlistentry>
3726   <term>Type:</term>
3727   <!-- boolean, parameterized, Multi-value -->
3728   <listitem>
3729    <para>Parameterized.</para>
3730   </listitem>
3731  </varlistentry>
3732
3733  <varlistentry>
3734   <term>Parameter:</term>
3735   <listitem>
3736    <para>
3737     The name of a content filter, as defined in the <link linkend="filter-file">filter file</link>.
3738     Filters can be defined in one or more  files as defined by the
3739     <literal><link linkend="filterfile">filterfile</link></literal>
3740     option in the <link linkend="config">config file</link>.
3741     <filename>default.filter</filename> is the collection of filters
3742     supplied by the developers. Locally defined filters should go
3743     in their own file, such as <filename>user.filter</filename>.
3744    </para>
3745    <para>
3746      When used in its negative form,
3747      and without parameters, <emphasis>all</emphasis> filtering is completely disabled.
3748   </para>
3749   </listitem>
3750  </varlistentry>
3751
3752  <varlistentry>
3753   <term>Notes:</term>
3754   <listitem>
3755    <para>
3756     For your convenience, there are a number of pre-defined filters available
3757     in the distribution filter file that you can use. See the examples below for
3758     a list.
3759    </para>
3760    <para>
3761     Filtering requires buffering the page content, which may appear to
3762     slow down page rendering since nothing is displayed until all content has
3763     passed the filters. (The total time until the page is completely rendered
3764     doesn't change much, but it may be perceived as slower since the page is
3765     not incrementally displayed.)
3766     This effect will be more noticeable on slower connections.
3767    </para>
3768    <para>
3769    <quote>Rolling your own</quote>
3770     filters requires a knowledge of
3771      <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
3772      Expressions</quote></ulink> and
3773       <ulink url="http://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
3774     This is very powerful feature, and potentially very intrusive.
3775     Filters should be used with caution, and where an equivalent
3776     <quote>action</quote> is not available.
3777    </para>
3778    <para>
3779     The amount of data that can be filtered is limited to the
3780     <literal><link linkend="buffer-limit">buffer-limit</link></literal>
3781     option in the main <link linkend="config">config file</link>. The
3782     default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
3783     data, and all pending data, is passed through unfiltered.
3784    </para>
3785    <para>
3786     Inappropriate MIME types, such as zipped files, are not filtered at all.
3787     (Again, only text-based types except plain text). Encrypted SSL data
3788     (from HTTPS servers) cannot be filtered either, since this would violate
3789     the integrity of the secure transaction. In some situations it might
3790     be necessary to protect certain text, like source code, from filtering
3791     by defining appropriate <literal>-filter</literal> exceptions.
3792    </para>
3793    <para>
3794     Compressed content can't be filtered either, but if &my-app;
3795     is compiled with zlib support and a supported compression algorithm
3796     is used (gzip or deflate), &my-app; can first decompress the content
3797     and then filter it.
3798    </para>
3799    <para>
3800     If you use a &my-app; version without zlib support, but want filtering to work on
3801     as much documents as possible, even those that would normally be sent compressed,
3802     you must use the <literal><link linkend="prevent-compression">prevent-compression</link></literal>
3803     action in conjunction with <literal>filter</literal>.
3804    </para>
3805    <para>
3806     Content filtering can achieve some of the same effects as the
3807     <literal><link linkend="block">block</link></literal>
3808     action, i.e. it can be used to block ads and banners. But the mechanism
3809     works quite differently. One effective use, is to block ad banners
3810     based on their size (see below), since many of these seem to be somewhat
3811     standardized.
3812    </para>
3813    <para>
3814     <link linkend="contact">Feedback</link> with suggestions for new or
3815     improved filters is particularly welcome!
3816    </para>
3817    <para>
3818     The below list has only the names and a one-line description of each
3819     predefined filter. There are <link linkend="predefined-filters">more
3820     verbose explanations</link> of what these filters do in the <link
3821     linkend="filter-file">filter file chapter</link>.
3822    </para>
3823   </listitem>
3824  </varlistentry>
3825
3826  <varlistentry>
3827   <term>Example usage (with filters from the distribution <filename>default.filter</filename> file).
3828   See <link linkend="PREDEFINED-FILTERS">the Predefined Filters section</link> for
3829   more explanation on each:</term>
3830   <listitem>
3831    <para>
3832     <anchor id="filter-js-annoyances">
3833     <screen>+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse.</screen>
3834    </para>
3835    <para>
3836     <anchor id="filter-js-events">
3837     <screen>+filter{js-events}           # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
3838    </para>
3839    <para>
3840     <anchor id="filter-html-annoyances">
3841     <screen>+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.</screen>
3842    </para>
3843    <para>
3844     <anchor id="filter-content-cookies">
3845     <screen>+filter{content-cookies}     # Kill cookies that come in the HTML or JS content.</screen>
3846    </para>
3847    <para>
3848     <anchor id="filter-refresh-tags">
3849     <screen>+filter{refresh-tags}        # Kill automatic refresh tags if refresh time is larger than 9 seconds.</screen>
3850    </para>
3851    <para>
3852     <anchor id="filter-unsolicited-popups">
3853     <screen>+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows.</screen>
3854    </para>
3855    <para>
3856     <anchor id="filter-all-popups">
3857     <screen>+filter{all-popups}          # Kill all popups in JavaScript and HTML.</screen>
3858    </para>
3859    <para>
3860     <anchor id="filter-img-reorder">
3861     <screen>+filter{img-reorder}         # Reorder attributes in &lt;img&gt; tags to make the banners-by-* filters more effective.</screen>
3862    </para>
3863    <para>
3864     <anchor id="filter-banners-by-size">
3865     <screen>+filter{banners-by-size}     # Kill banners by size.</screen>
3866    </para>
3867    <para>
3868     <anchor id="filter-banners-by-link">
3869     <screen>+filter{banners-by-link}     # Kill banners by their links to known clicktrackers.</screen>
3870    </para>
3871    <para>
3872     <anchor id="filter-webbugs">
3873     <screen>+filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
3874    </para>
3875    <para>
3876     <anchor id="filter-tiny-textforms">
3877     <screen>+filter{tiny-textforms}      # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
3878    </para>
3879    <para>
3880     <anchor id="filter-jumping-windows">
3881     <screen>+filter{jumping-windows}     # Prevent windows from resizing and moving themselves.</screen>
3882    </para>
3883    <para>
3884     <anchor id="filter-frameset-borders">
3885     <screen>+filter{frameset-borders}    # Give frames a border and make them resizable.</screen>
3886    </para>
3887    <para>
3888     <anchor id="filter-iframes">
3889     <screen>+filter{iframes}             # Removes all detected iframes. Should only be enabled for individual sites.</screen>
3890    </para>
3891    <para>
3892     <anchor id="filter-demoronizer">
3893     <screen>+filter{demoronizer}         # Fix MS's non-standard use of standard charsets.</screen>
3894    </para>
3895    <para>
3896     <anchor id="filter-shockwave-flash">
3897     <screen>+filter{shockwave-flash}     # Kill embedded Shockwave Flash objects.</screen>
3898    </para>
3899    <para>
3900     <anchor id="filter-quicktime-kioskmode">
3901     <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
3902    </para>
3903    <para>
3904     <anchor id="filter-fun">
3905     <screen>+filter{fun}                 # Text replacements for subversive browsing fun!</screen>
3906    </para>
3907    <para>
3908     <anchor id="filter-crude-parental">
3909     <screen>+filter{crude-parental}      # Crude parental filtering. Note that this filter doesn't work reliably.</screen>
3910    </para>
3911    <para>
3912     <anchor id="filter-ie-exploits">
3913     <screen>+filter{ie-exploits}         # Disable some known Internet Explorer bug exploits.</screen>
3914    </para>
3915    <para>
3916     <anchor id="filter-site-specifics">
3917     <screen>+filter{site-specifics}      # Cure for site-specific problems. Don't apply generally!</screen>
3918    </para>
3919    <para>
3920     <anchor id="filter-no-ping">
3921     <screen>+filter{no-ping}             # Removes non-standard ping attributes in &lt;a&gt; and &lt;area&gt; tags.</screen>
3922    </para>
3923    <para>
3924     <anchor id="filter-google">
3925     <screen>+filter{google}              # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
3926    </para>
3927    <para>
3928     <anchor id="filter-yahoo">
3929     <screen>+filter{yahoo}               # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
3930    </para>
3931    <para>
3932     <anchor id="filter-msn">
3933     <screen>+filter{msn}                 # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
3934    </para>
3935    <para>
3936     <anchor id="filter-blogspot">
3937     <screen>+filter{blogspot}            # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
3938    </para>
3939   </listitem>
3940  </varlistentry>
3941 </variablelist>
3942 </sect3>
3943
3944
3945 <!--   ~~~~~       New section      ~~~~~     -->
3946 <sect3 renderas="sect4" id="force-text-mode">
3947 <title>force-text-mode</title>
3948 <!--
3949 new action
3950 -->
3951 <variablelist>
3952  <varlistentry>
3953   <term>Typical use:</term>
3954   <listitem>
3955    <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format.   </para>
3956   </listitem>
3957  </varlistentry>
3958
3959  <varlistentry>
3960   <term>Effect:</term>
3961   <listitem>
3962    <para>
3963     Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
3964    </para>
3965   </listitem>
3966  </varlistentry>
3967
3968  <varlistentry>
3969   <term>Type:</term>
3970   <!-- Boolean, Parameterized, Multi-value -->
3971   <listitem>
3972    <para>Boolean.</para>
3973   </listitem>
3974  </varlistentry>
3975
3976  <varlistentry>
3977   <term>Parameter:</term>
3978   <listitem>
3979    <para>
3980     N/A
3981    </para>
3982   </listitem>
3983  </varlistentry>
3984
3985  <varlistentry>
3986   <term>Notes:</term>
3987   <listitem>
3988    <para>
3989     As explained <literal><link linkend="filter">above</link></literal>,
3990     <application>Privoxy</application> tries to only filter files that are
3991     in some kind of text format. The same restrictions apply to
3992     <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
3993     <literal>force-text-mode</literal> declares a document as text,
3994     without looking at the <quote>Content-Type:</quote> first.
3995    </para>
3996    <warning>
3997     <para>
3998      Think twice before activating this action. Filtering binary data
3999      with regular expressions can cause file damage.
4000     </para>
4001    </warning>
4002   </listitem>
4003  </varlistentry>
4004
4005  <varlistentry>
4006   <term>Example usage:</term>
4007   <listitem>
4008    <para>
4009      <screen>
4010 +force-text-mode
4011      </screen>
4012    </para>
4013   </listitem>
4014  </varlistentry>
4015 </variablelist>
4016 </sect3>
4017
4018
4019 <!--   ~~~~~       New section      ~~~~~     -->
4020 <sect3 renderas="sect4" id="forward-override">
4021 <title>forward-override</title>
4022 <!--
4023 new action
4024 -->
4025 <variablelist>
4026  <varlistentry>
4027   <term>Typical use:</term>
4028   <listitem>
4029    <para>Change the forwarding settings based on User-Agent or request origin</para>
4030   </listitem>
4031  </varlistentry>
4032
4033  <varlistentry>
4034   <term>Effect:</term>
4035   <listitem>
4036    <para>
4037     Overrules the forward directives in the configuration file.
4038    </para>
4039   </listitem>
4040  </varlistentry>
4041
4042  <varlistentry>
4043   <term>Type:</term>
4044   <!-- Boolean, Parameterized, Multi-value -->
4045   <listitem>
4046    <para>Multi-value.</para>
4047   </listitem>
4048  </varlistentry>
4049
4050  <varlistentry>
4051   <term>Parameter:</term>
4052   <listitem>
4053    <itemizedlist>
4054     <listitem>
4055      <para><quote>forward .</quote> to use a direct connection without any additional proxies.</para>
4056     </listitem>
4057     <listitem>
4058      <para>
4059       <quote>forward 127.0.0.1:8123</quote> to use the HTTP proxy listening at 127.0.0.1 port 8123.
4060      </para>
4061     </listitem>
4062     <listitem>
4063      <para>
4064       <quote>forward-socks4a 127.0.0.1:9050 .</quote> to use the socks4a proxy listening at
4065       127.0.0.1 port 9050. Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote>
4066       to use a socks4 connection  (with local DNS resolution) instead, use <quote>forward-socks5</quote>
4067       for socks5 connections (with remote DNS resolution).
4068      </para>
4069     </listitem>
4070     <listitem>
4071      <para>
4072       <quote>forward-socks4a 127.0.0.1:9050 proxy.example.org:8000</quote> to use the socks4a proxy
4073       listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
4074       Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection
4075       (with local DNS resolution) instead, use <quote>forward-socks5</quote>
4076       for socks5 connections (with remote DNS resolution).
4077      </para>
4078     </listitem>
4079    </itemizedlist>
4080   </listitem>
4081  </varlistentry>
4082
4083  <varlistentry>
4084   <term>Notes:</term>
4085   <listitem>
4086    <para>
4087     This action takes parameters similar to the
4088     <link linkend="forwarding">forward</link> directives in the configuration
4089     file, but without the URL pattern. It can be used as replacement, but normally it's only
4090     used in cases where matching based on the request URL isn't sufficient.
4091    </para>
4092    <warning>
4093     <para>
4094      Please read the description for the <link linkend="forwarding">forward</link> directives before
4095      using this action. Forwarding to the wrong people will reduce your privacy and increase the
4096      chances of man-in-the-middle attacks.
4097     </para>
4098     <para>
4099      If the ports are missing or invalid, default values will be used. This might change
4100      in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
4101      to exit.
4102     </para>
4103     <para>
4104      Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
4105      to verify that your forward settings do what you thought the do.
4106     </para>
4107    </warning>
4108   </listitem>
4109  </varlistentry>
4110
4111  <varlistentry>
4112   <term>Example usage:</term>
4113   <listitem>
4114    <para>
4115      <screen>
4116 # Always use direct connections for requests previously tagged as
4117 # <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
4118 # resuming downloads continues to work.
4119 # This way you can continue to use Tor for your normal browsing,
4120 # without overloading the Tor network with your FreeBSD ports updates
4121 # or downloads of bigger files like ISOs.
4122 # Note that HTTP headers are easy to fake and therefore their
4123 # values are as (un)trustworthy as your clients and users.
4124 {+forward-override{forward .} \
4125  -hide-if-modified-since      \
4126  -overwrite-last-modified     \
4127 }
4128 TAG:^User-Agent: fetch libfetch/2\.0$
4129      </screen>
4130    </para>
4131   </listitem>
4132  </varlistentry>
4133 </variablelist>
4134 </sect3>
4135
4136
4137 <!--   ~~~~~       New section      ~~~~~     -->
4138 <sect3 renderas="sect4" id="handle-as-empty-document">
4139 <title>handle-as-empty-document</title>
4140 <!--
4141 new action
4142 -->
4143 <variablelist>
4144  <varlistentry>
4145   <term>Typical use:</term>
4146   <listitem>
4147    <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
4148   </listitem>
4149  </varlistentry>
4150
4151  <varlistentry>
4152   <term>Effect:</term>
4153   <listitem>
4154    <para>
4155     This action alone doesn't do anything noticeable. It just marks URLs.
4156     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4157     the presence or absence of this mark decides whether an HTML <quote>BLOCKED</quote>
4158     page, or an empty document will be sent to the client as a substitute for the blocked content.
4159     The <emphasis>empty</emphasis> document isn't literally empty, but actually contains a single space.
4160    </para>
4161   </listitem>
4162  </varlistentry>
4163
4164  <varlistentry>
4165   <term>Type:</term>
4166   <!-- Boolean, Parameterized, Multi-value -->
4167   <listitem>
4168    <para>Boolean.</para>
4169   </listitem>
4170  </varlistentry>
4171
4172  <varlistentry>
4173   <term>Parameter:</term>
4174   <listitem>
4175    <para>
4176     N/A
4177    </para>
4178   </listitem>
4179  </varlistentry>
4180
4181  <varlistentry>
4182   <term>Notes:</term>
4183   <listitem>
4184    <para>
4185     Some browsers complain about syntax errors if JavaScript documents
4186     are blocked with <application>Privoxy's</application>
4187     default HTML page; this option can be used to silence them.
4188     And of course this action can also be used to eliminate the &my-app;
4189     BLOCKED message in frames.
4190    </para>
4191    <para>
4192     The content type for the empty document can be specified with
4193     <literal><link linkend="content-type-overwrite">content-type-overwrite{}</link></literal>,
4194     but usually this isn't necessary.
4195    </para>
4196   </listitem>
4197  </varlistentry>
4198
4199  <varlistentry>
4200   <term>Example usage:</term>
4201   <listitem>
4202    <para>
4203      <screen># Block all documents on example.org that end with ".js",
4204 # but send an empty document instead of the usual HTML message.
4205 {+block{Blocked JavaScript} +handle-as-empty-document}
4206 example.org/.*\.js$
4207      </screen>
4208    </para>
4209   </listitem>
4210  </varlistentry>
4211 </variablelist>
4212 </sect3>
4213
4214
4215 <!--   ~~~~~       New section      ~~~~~     -->
4216 <sect3 renderas="sect4" id="handle-as-image">
4217 <title>handle-as-image</title>
4218
4219 <variablelist>
4220  <varlistentry>
4221   <term>Typical use:</term>
4222   <listitem>
4223    <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>
4224   </listitem>
4225  </varlistentry>
4226
4227  <varlistentry>
4228   <term>Effect:</term>
4229   <listitem>
4230    <para>
4231     This action alone doesn't do anything noticeable. It just marks URLs as images.
4232     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4233     the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
4234     page, or a replacement image (as determined by the <literal><link
4235     linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
4236     client as a substitute for the blocked content.
4237    </para>
4238   </listitem>
4239  </varlistentry>
4240
4241  <varlistentry>
4242   <term>Type:</term>
4243   <!-- Boolean, Parameterized, Multi-value -->
4244   <listitem>
4245    <para>Boolean.</para>
4246   </listitem>
4247  </varlistentry>
4248
4249  <varlistentry>
4250   <term>Parameter:</term>
4251   <listitem>
4252    <para>
4253     N/A
4254    </para>
4255   </listitem>
4256  </varlistentry>
4257
4258  <varlistentry>
4259   <term>Notes:</term>
4260   <listitem>
4261    <para>
4262     The below generic example section is actually part of <filename>default.action</filename>.
4263     It marks all URLs with well-known image file name extensions as images and should
4264     be left intact.
4265    </para>
4266    <para>
4267     Users will probably only want to use the handle-as-image action in conjunction with
4268     <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
4269     reflect the file type, like in the second example section.
4270    </para>
4271    <para>
4272     Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
4273     frames require an HTML page to be sent, or they won't display properly.
4274     Forcing <literal>handle-as-image</literal> in this situation will not replace the
4275     ad frame with an image, but lead to error messages.
4276    </para>
4277   </listitem>
4278  </varlistentry>
4279
4280  <varlistentry>
4281   <term>Example usage (sections):</term>
4282   <listitem>
4283    <para>
4284      <screen># Generic image extensions:
4285 #
4286 {+handle-as-image}
4287 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
4288
4289 # These don't look like images, but they're banners and should be
4290 # blocked as images:
4291 #
4292 {+block{Nasty banners.} +handle-as-image}
4293 nasty-banner-server.example.com/junk.cgi\?output=trash
4294 </screen>
4295    </para>
4296   </listitem>
4297  </varlistentry>
4298 </variablelist>
4299 </sect3>
4300
4301
4302 <!--   ~~~~~       New section      ~~~~~     -->
4303 <sect3 renderas="sect4" id="hide-accept-language">
4304 <title>hide-accept-language</title>
4305 <!--
4306 new action
4307 -->
4308 <variablelist>
4309  <varlistentry>
4310   <term>Typical use:</term>
4311   <listitem>
4312    <para>Pretend to use different language settings.</para>
4313   </listitem>
4314  </varlistentry>
4315
4316  <varlistentry>
4317   <term>Effect:</term>
4318   <listitem>
4319    <para>
4320     Deletes or replaces the <quote>Accept-Language:</quote> HTTP header in client requests.
4321    </para>
4322   </listitem>
4323  </varlistentry>
4324
4325  <varlistentry>
4326   <term>Type:</term>
4327   <!-- Boolean, Parameterized, Multi-value -->
4328   <listitem>
4329    <para>Parameterized.</para>
4330   </listitem>
4331  </varlistentry>
4332
4333  <varlistentry>
4334   <term>Parameter:</term>
4335   <listitem>
4336    <para>
4337     Keyword: <quote>block</quote>, or any user defined value.
4338    </para>
4339   </listitem>
4340  </varlistentry>
4341
4342  <varlistentry>
4343   <term>Notes:</term>
4344   <listitem>
4345    <para>
4346     Faking the browser's language settings can be useful to make a
4347     foreign User-Agent set with
4348     <literal><link linkend="hide-user-agent">hide-user-agent</link></literal>
4349     more believable.
4350    </para>
4351    <para>
4352     However some sites with content in different languages check the
4353     <quote>Accept-Language:</quote> to decide which one to take by default.
4354     Sometimes it isn't possible to later switch to another language without
4355     changing the <quote>Accept-Language:</quote> header first.
4356    </para>
4357    <para>
4358     Therefore it's a good idea to either only change the
4359     <quote>Accept-Language:</quote> header to languages you understand,
4360     or to languages that aren't wide spread.
4361    </para>
4362    <para>
4363     Before setting the <quote>Accept-Language:</quote> header
4364     to a rare language, you should consider that it helps to
4365     make your requests unique and thus easier to trace.
4366     If you don't plan to change this header frequently,
4367     you should stick to a common language.
4368    </para>
4369   </listitem>
4370  </varlistentry>
4371
4372  <varlistentry>
4373   <term>Example usage (section):</term>
4374   <listitem>
4375     <para>
4376      <screen># Pretend to use Canadian language settings.
4377 {+hide-accept-language{en-ca} \
4378 +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
4379 }
4380 /   </screen>
4381    </para>
4382   </listitem>
4383  </varlistentry>
4384 </variablelist>
4385 </sect3>
4386
4387
4388 <!--   ~~~~~       New section      ~~~~~     -->
4389 <sect3 renderas="sect4" id="hide-content-disposition">
4390 <title>hide-content-disposition</title>
4391 <!--
4392 new action
4393 -->
4394 <variablelist>
4395  <varlistentry>
4396   <term>Typical use:</term>
4397   <listitem>
4398    <para>Prevent download menus for content you prefer to view inside the browser.</para>
4399   </listitem>
4400  </varlistentry>
4401
4402  <varlistentry>
4403   <term>Effect:</term>
4404   <listitem>
4405    <para>
4406     Deletes or replaces the <quote>Content-Disposition:</quote> HTTP header set by some servers.
4407    </para>
4408   </listitem>
4409  </varlistentry>
4410
4411  <varlistentry>
4412   <term>Type:</term>
4413   <!-- Boolean, Parameterized, Multi-value -->
4414   <listitem>
4415    <para>Parameterized.</para>
4416   </listitem>
4417  </varlistentry>
4418
4419  <varlistentry>
4420   <term>Parameter:</term>
4421   <listitem>
4422    <para>
4423     Keyword: <quote>block</quote>, or any user defined value.
4424    </para>
4425   </listitem>
4426  </varlistentry>
4427
4428  <varlistentry>
4429   <term>Notes:</term>
4430   <listitem>
4431    <para>
4432     Some servers set the <quote>Content-Disposition:</quote> HTTP header for
4433     documents they assume you want to save locally before viewing them.
4434     The <quote>Content-Disposition:</quote> header contains the file name
4435     the browser is supposed to use by default.
4436    </para>
4437    <para>
4438     In most browsers that understand this header, it makes it impossible to
4439     <emphasis>just view</emphasis> the document, without downloading it first,
4440     even if it's just a simple text file or an image.
4441    </para>
4442    <para>
4443     Removing the <quote>Content-Disposition:</quote> header helps
4444     to prevent this annoyance, but some browsers additionally check the
4445     <quote>Content-Type:</quote> header, before they decide if they can
4446     display a document without saving it first. In these cases, you have
4447     to change this header as well, before the browser stops displaying
4448     download menus.
4449    </para>
4450    <para>
4451     It is also possible to change the server's file name suggestion
4452     to another one, but in most cases it isn't worth the time to set
4453     it up.
4454    </para>
4455    <para>
4456     This action will probably be removed in the future,
4457     use server-header filters instead.
4458    </para>
4459   </listitem>
4460  </varlistentry>
4461
4462  <varlistentry>
4463   <term>Example usage:</term>
4464   <listitem>
4465     <para>
4466      <screen># Disarm the download link in Sourceforge's patch tracker
4467 { -filter \
4468  +content-type-overwrite{text/plain}\
4469  +hide-content-disposition{block} }
4470  .sourceforge.net/tracker/download\.php</screen>
4471    </para>
4472   </listitem>
4473  </varlistentry>
4474 </variablelist>
4475 </sect3>
4476
4477
4478 <!--   ~~~~~       New section      ~~~~~     -->
4479 <sect3 renderas="sect4" id="hide-if-modified-since">
4480 <title>hide-if-modified-since</title>
4481 <!--
4482 new action
4483 -->
4484 <variablelist>
4485  <varlistentry>
4486   <term>Typical use:</term>
4487   <listitem>
4488    <para>Prevent yet another way to track the user's steps between sessions.</para>
4489   </listitem>
4490  </varlistentry>
4491
4492  <varlistentry>
4493   <term>Effect:</term>
4494   <listitem>
4495    <para>
4496     Deletes the <quote>If-Modified-Since:</quote> HTTP client header or modifies its value.
4497    </para>
4498   </listitem>
4499  </varlistentry>
4500
4501  <varlistentry>
4502   <term>Type:</term>
4503   <!-- Boolean, Parameterized, Multi-value -->
4504   <listitem>
4505    <para>Parameterized.</para>
4506   </listitem>
4507  </varlistentry>
4508
4509  <varlistentry>
4510   <term>Parameter:</term>
4511   <listitem>
4512    <para>
4513     Keyword: <quote>block</quote>, or a user defined value that specifies a range of hours.
4514    </para>
4515   </listitem>
4516  </varlistentry>
4517
4518  <varlistentry>
4519   <term>Notes:</term>
4520   <listitem>
4521    <para>
4522     Removing this header is useful for filter testing, where you want to force a real
4523     reload instead of getting status code <quote>304</quote>, which would cause the
4524     browser to use a cached copy of the page.
4525    </para>
4526    <para>
4527     Instead of removing the header, <literal>hide-if-modified-since</literal> can
4528     also add or subtract a random amount of time to/from the header's value.
4529     You specify a range of minutes where the random factor should be chosen from and
4530     <application>Privoxy</application> does the rest. A negative value means
4531     subtracting, a positive value adding.
4532    </para>
4533    <para>
4534     Randomizing the value of the <quote>If-Modified-Since:</quote> makes
4535     it less likely that the server can use the time as a cookie replacement,
4536     but you will run into caching problems if the random range is too high.
4537    </para>
4538    <para>
4539     It is a good idea to only use a small negative value and let
4540     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
4541     handle the greater changes.
4542    </para>
4543    <para>
4544     It is also recommended to use this action together with
4545     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>,
4546     otherwise it's more or less pointless.
4547    </para>
4548   </listitem>
4549  </varlistentry>
4550
4551  <varlistentry>
4552   <term>Example usage (section):</term>
4553   <listitem>
4554     <para>
4555      <screen># Let the browser revalidate but make tracking based on the time less likely.
4556 {+hide-if-modified-since{-60} \
4557  +overwrite-last-modified{randomize} \
4558  +crunch-if-none-match}
4559 /</screen>
4560    </para>
4561   </listitem>
4562  </varlistentry>
4563 </variablelist>
4564 </sect3>
4565
4566
4567 <!--   ~~~~~       New section      ~~~~~     -->
4568 <sect3 renderas="sect4" id="hide-from-header">
4569 <title>hide-from-header</title>
4570
4571 <variablelist>
4572  <varlistentry>
4573   <term>Typical use:</term>
4574   <listitem>
4575    <para>Keep your (old and ill) browser from telling web servers your email address</para>
4576   </listitem>
4577  </varlistentry>
4578
4579  <varlistentry>
4580   <term>Effect:</term>
4581   <listitem>
4582    <para>
4583     Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
4584     specified string.
4585    </para>
4586   </listitem>
4587  </varlistentry>
4588
4589  <varlistentry>
4590   <term>Type:</term>
4591   <!-- Boolean, Parameterized, Multi-value -->
4592   <listitem>
4593    <para>Parameterized.</para>
4594   </listitem>
4595  </varlistentry>
4596
4597  <varlistentry>
4598   <term>Parameter:</term>
4599   <listitem>
4600    <para>
4601     Keyword: <quote>block</quote>, or any user defined value.
4602    </para>
4603   </listitem>
4604  </varlistentry>
4605
4606  <varlistentry>
4607   <term>Notes:</term>
4608   <listitem>
4609    <para>
4610     The keyword <quote>block</quote> will completely remove the header
4611     (not to be confused with the <literal><link linkend="block">block</link></literal>
4612     action).
4613    </para>
4614    <para>
4615     Alternately, you can specify any value you prefer to be sent to the web
4616     server. If you do, it is a matter of fairness not to use any address that
4617     is actually used by a real person.
4618    </para>
4619    <para>
4620     This action is rarely needed, as modern web browsers don't send
4621     <quote>From:</quote> headers anymore.
4622    </para>
4623   </listitem>
4624  </varlistentry>
4625
4626  <varlistentry>
4627   <term>Example usage:</term>
4628   <listitem>
4629    <para>
4630     <screen>+hide-from-header{block}</screen> or
4631     <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
4632    </para>
4633   </listitem>
4634  </varlistentry>
4635 </variablelist>
4636 </sect3>
4637
4638
4639 <!--   ~~~~~       New section      ~~~~~     -->
4640 <sect3 renderas="sect4" id="hide-referrer">
4641 <title>hide-referrer</title>
4642 <anchor id="hide-referer">
4643 <variablelist>
4644  <varlistentry>
4645   <term>Typical use:</term>
4646   <listitem>
4647    <para>Conceal which link you followed to get to a particular site</para>
4648   </listitem>
4649  </varlistentry>
4650
4651  <varlistentry>
4652   <term>Effect:</term>
4653   <listitem>
4654    <para>
4655     Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
4656     or replaces it with a forged one.
4657    </para>
4658   </listitem>
4659  </varlistentry>
4660
4661  <varlistentry>
4662   <term>Type:</term>
4663   <!-- Boolean, Parameterized, Multi-value -->
4664   <listitem>
4665    <para>Parameterized.</para>
4666   </listitem>
4667  </varlistentry>
4668
4669  <varlistentry>
4670   <term>Parameter:</term>
4671   <listitem>
4672    <itemizedlist>
4673     <listitem>
4674      <para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
4675     </listitem>
4676     <listitem>
4677      <para><quote>conditional-forge</quote> to forge the header if the host has changed.</para>
4678     </listitem>
4679     <listitem>
4680      <para><quote>block</quote> to delete the header unconditionally.</para>
4681     </listitem>
4682     <listitem>
4683      <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
4684     </listitem>
4685     <listitem>
4686      <para>Any other string to set a user defined referrer.</para>
4687     </listitem>
4688    </itemizedlist>
4689   </listitem>
4690  </varlistentry>
4691
4692  <varlistentry>
4693   <term>Notes:</term>
4694   <listitem>
4695    <para>
4696     <literal>conditional-block</literal> is the only parameter,
4697     that isn't easily detected in the server's log file. If it blocks the
4698     referrer, the request will look like the visitor used a bookmark or
4699     typed in the address directly.
4700    </para>
4701    <para>
4702     Leaving the referrer unmodified for requests on the same host
4703     allows the server owner to see the visitor's <quote>click path</quote>,
4704     but in most cases she could also get that information by comparing
4705     other parts of the log file: for example the User-Agent if it isn't
4706     a very common one, or the user's IP address if it doesn't change between
4707     different requests.
4708    </para>
4709    <para>
4710     Always blocking the referrer, or using a custom one, can lead to
4711     failures on servers that check the referrer before they answer any
4712     requests, in an attempt to prevent their content from being
4713     embedded or linked to elsewhere.
4714    </para>
4715    <para>
4716     Both <literal>conditional-block</literal> and <literal>forge</literal>
4717     will work with referrer checks, as long as content and valid referring page
4718     are on the same host. Most of the time that's the case.
4719    </para>
4720    <para>
4721     <literal>hide-referer</literal> is an alternate spelling of
4722     <literal>hide-referrer</literal> and the two can be can be freely
4723     substituted with each other. (<quote>referrer</quote> is the
4724     correct English spelling, however the HTTP specification has a bug - it
4725     requires it to be spelled as <quote>referer</quote>.)
4726    </para>
4727   </listitem>
4728  </varlistentry>
4729
4730  <varlistentry>
4731   <term>Example usage:</term>
4732   <listitem>
4733    <para>
4734      <screen>+hide-referrer{forge}</screen> or
4735      <screen>+hide-referrer{http://www.yahoo.com/}</screen>
4736    </para>
4737   </listitem>
4738  </varlistentry>
4739 </variablelist>
4740 </sect3>
4741
4742
4743 <!--   ~~~~~       New section      ~~~~~     -->
4744 <sect3 renderas="sect4" id="hide-user-agent">
4745 <title>hide-user-agent</title>
4746
4747 <variablelist>
4748  <varlistentry>
4749   <term>Typical use:</term>
4750   <listitem>
4751    <para>Try to conceal your type of browser and client operating system</para>
4752   </listitem>
4753  </varlistentry>
4754
4755  <varlistentry>
4756   <term>Effect:</term>
4757   <listitem>
4758    <para>
4759     Replaces the value of the <quote>User-Agent:</quote> HTTP header
4760     in client requests with the specified value.
4761    </para>
4762   </listitem>
4763  </varlistentry>
4764
4765  <varlistentry>
4766   <term>Type:</term>
4767   <!-- Boolean, Parameterized, Multi-value -->
4768   <listitem>
4769    <para>Parameterized.</para>
4770   </listitem>
4771  </varlistentry>
4772
4773  <varlistentry>
4774   <term>Parameter:</term>
4775   <listitem>
4776    <para>
4777     Any user-defined string.
4778    </para>
4779   </listitem>
4780  </varlistentry>
4781
4782  <varlistentry>
4783   <term>Notes:</term>
4784   <listitem>
4785    <warning>
4786     <para>
4787      This can lead to problems on web sites that depend on looking at this header in
4788      order to customize their content for different browsers (which, by the
4789      way, is <emphasis>NOT</emphasis> the right thing to do: good web sites
4790      work browser-independently).
4791     </para>
4792    </warning>
4793    <para>
4794     Using this action in multi-user setups or wherever different types of
4795     browsers will access the same <application>Privoxy</application> is
4796     <emphasis>not recommended</emphasis>. In single-user, single-browser
4797     setups, you might use it to delete your OS version information from
4798     the headers, because it is an invitation to exploit known bugs for your
4799     OS. It is also occasionally useful to forge this in order to access
4800     sites that won't let you in otherwise (though there may be a good
4801     reason in some cases).
4802    </para>
4803    <para>
4804      More information on known user-agent strings can be found at
4805      <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
4806      and
4807      <ulink url="http://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
4808    </para>
4809    </listitem>
4810  </varlistentry>
4811
4812  <varlistentry>
4813   <term>Example usage:</term>
4814   <listitem>
4815    <para>
4816      <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
4817    </para>
4818   </listitem>
4819  </varlistentry>
4820 </variablelist>
4821 </sect3>
4822
4823
4824 <!--   ~~~~~       New section      ~~~~~     -->
4825 <sect3 renderas="sect4" id="limit-connect">
4826 <title>limit-connect</title>
4827
4828 <variablelist>
4829  <varlistentry>
4830   <term>Typical use:</term>
4831   <listitem>
4832    <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay or disable SSL for untrusted sites</para>
4833   </listitem>
4834  </varlistentry>
4835
4836  <varlistentry>
4837   <term>Effect:</term>
4838   <listitem>
4839    <para>
4840     Specifies to which ports HTTP CONNECT requests are allowable.
4841    </para>
4842   </listitem>
4843  </varlistentry>
4844
4845  <varlistentry>
4846   <term>Type:</term>
4847   <!-- Boolean, Parameterized, Multi-value -->
4848   <listitem>
4849    <para>Parameterized.</para>
4850   </listitem>
4851  </varlistentry>
4852
4853  <varlistentry>
4854   <term>Parameter:</term>
4855   <listitem>
4856    <para>
4857     A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
4858     defaulting to 0 and the maximum to 65K).
4859    </para>
4860   </listitem>
4861  </varlistentry>
4862
4863  <varlistentry>
4864   <term>Notes:</term>
4865   <listitem>
4866    <para>
4867     By default, i.e. if no <literal>limit-connect</literal> action applies,
4868     <application>Privoxy</application> allows HTTP CONNECT requests to all
4869     ports. Use <literal>limit-connect</literal> if fine-grained control
4870     is desired for some or all destinations.
4871    </para>
4872    <para>
4873     The CONNECT methods exists in HTTP to allow access to secure websites
4874     (<quote>https://</quote> URLs) through proxies. It works very simply:
4875     the proxy connects to the server on the specified port, and then
4876     short-circuits its connections to the client and to the remote server.
4877     This means CONNECT-enabled proxies can be used as TCP relays very easily.
4878   </para>
4879   <para>
4880    <application>Privoxy</application> relays HTTPS traffic without seeing
4881    the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
4882    filters. By specifying an invalid port range you can disable HTTPS entirely.
4883   </para>
4884   </listitem>
4885  </varlistentry>
4886
4887  <varlistentry>
4888   <term>Example usages:</term>
4889   <listitem>
4890    <!-- I had trouble getting the spacing to look right in my browser -->
4891    <!-- I probably have the wrong font setup, bollocks. -->
4892    <!-- Apparently the emphasis tag uses a proportional font no matter what -->
4893     <para>
4894      <screen>+limit-connect{443}                   # Port 443 is OK.
4895 +limit-connect{80,443}                # Ports 80 and 443 are OK.
4896 +limit-connect{-3, 7, 20-100, 500-}   # Ports less than 3, 7, 20 to 100 and above 500 are OK.
4897 +limit-connect{-}                     # All ports are OK
4898 +limit-connect{,}                     # No HTTPS/SSL traffic is allowed</screen>
4899    </para>
4900   </listitem>
4901  </varlistentry>
4902 </variablelist>
4903 </sect3>
4904
4905
4906 <!--   ~~~~~       New section      ~~~~~     -->
4907 <sect3 renderas="sect4" id="limit-cookie-lifetime">
4908 <title>limit-cookie-lifetime</title>
4909
4910 <variablelist>
4911  <varlistentry>
4912   <term>Typical use:</term>
4913   <listitem>
4914    <para>Limit the lifetime of HTTP cookies to a couple of minutes or hours.</para>
4915   </listitem>
4916  </varlistentry>
4917
4918  <varlistentry>
4919   <term>Effect:</term>
4920   <listitem>
4921    <para>
4922     Overwrites the expires field in Set-Cookie server headers if it's above the specified limit.
4923    </para>
4924   </listitem>
4925  </varlistentry>
4926
4927  <varlistentry>
4928   <term>Type:</term>
4929   <!-- Boolean, Parameterized, Multi-value -->
4930   <listitem>
4931    <para>Parameterized.</para>
4932   </listitem>
4933  </varlistentry>
4934
4935  <varlistentry>
4936   <term>Parameter:</term>
4937   <listitem>
4938    <para>
4939     The lifetime limit in minutes, or 0.
4940    </para>
4941   </listitem>
4942  </varlistentry>
4943
4944  <varlistentry>
4945   <term>Notes:</term>
4946   <listitem>
4947    <para>
4948     This action reduces the lifetime of HTTP cookies coming from the
4949     server to the specified number of minutes, starting from the time
4950     the cookie passes Privoxy.
4951    </para>
4952    <para>
4953     Cookies with a lifetime below the limit are not modified.
4954     The lifetime of session cookies is set to the specified limit.
4955    </para>
4956    <para>
4957     The effect of this action depends on the server.
4958    </para>
4959    <para>
4960     In case of servers which refresh their cookies with each response
4961     (or at least frequently), the lifetime limit set by this action
4962     is updated as well.
4963     Thus, a session associated with the cookie continues to work with
4964     this action enabled, as long as a new request is made before the
4965     last limit set is reached.
4966    </para>
4967    <para>
4968     However, some servers send their cookies once, with a lifetime of several
4969     years (the year 2037 is a popular choice), and do not refresh them
4970     until a certain event in the future, for example the user logging out.
4971     In this case this action may limit the absolute lifetime of the session,
4972     even if requests are made frequently.
4973    </para>
4974    <para>
4975     If the parameter is <quote>0</quote>, this action behaves like
4976     <literal><link linkend="session-cookies-only">session-cookies-only</link></literal>.
4977    </para>
4978   </listitem>
4979  </varlistentry>
4980
4981  <varlistentry>
4982   <term>Example usages:</term>
4983   <listitem>
4984     <para>
4985      <screen>+limit-cookie-lifetime{60}
4986        </screen>
4987    </para>
4988   </listitem>
4989  </varlistentry>
4990 </variablelist>
4991 </sect3>
4992
4993 <!--   ~~~~~       New section      ~~~~~     -->
4994 <sect3 renderas="sect4" id="prevent-compression">
4995 <title>prevent-compression</title>
4996
4997 <variablelist>
4998  <varlistentry>
4999   <term>Typical use:</term>
5000   <listitem>
5001    <para>
5002     Ensure that servers send the content uncompressed, so it can be
5003     passed through <literal><link linkend="filter">filter</link></literal>s.
5004    </para>
5005   </listitem>
5006  </varlistentry>
5007
5008  <varlistentry>
5009   <term>Effect:</term>
5010   <listitem>
5011    <para>
5012     Removes the Accept-Encoding header which can be used to ask for compressed transfer.
5013    </para>
5014   </listitem>
5015  </varlistentry>
5016
5017  <varlistentry>
5018   <term>Type:</term>
5019   <!-- Boolean, Parameterized, Multi-value -->
5020   <listitem>
5021    <para>Boolean.</para>
5022   </listitem>
5023  </varlistentry>
5024
5025  <varlistentry>
5026   <term>Parameter:</term>
5027   <listitem>
5028    <para>
5029     N/A
5030    </para>
5031   </listitem>
5032  </varlistentry>
5033
5034  <varlistentry>
5035   <term>Notes:</term>
5036   <listitem>
5037    <para>
5038     More and more websites send their content compressed by default, which
5039     is generally a good idea and saves bandwidth. But the <literal><link
5040     linkend="filter">filter</link></literal> and
5041     <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
5042     actions need access to the uncompressed data.
5043    </para>
5044    <para>
5045     When compiled with zlib support (available since &my-app; 3.0.7), content that should be
5046     filtered is decompressed on-the-fly and you don't have to worry about this action.
5047     If you are using an older &my-app; version, or one that hasn't been compiled with zlib
5048     support, this action can be used to convince the server to send the content uncompressed.
5049    </para>
5050    <para>
5051     Most text-based instances compress very well, the size is seldom decreased by less than 50%,
5052     for markup-heavy instances like news feeds saving more than 90% of the original size isn't
5053     unusual.
5054    </para>
5055    <para>
5056     Not using compression will therefore slow down the transfer, and you should only
5057     enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all
5058     predefined action settings.
5059    </para>
5060    <para>
5061     Note that some (rare) ill-configured sites don't handle requests for uncompressed
5062     documents correctly. Broken PHP applications tend to send an empty document body,
5063     some IIS versions only send the beginning of the content. If you enable
5064     <literal>prevent-compression</literal> per default, you might want to add
5065     exceptions for those sites. See the example for how to do that.
5066    </para>
5067   </listitem>
5068  </varlistentry>
5069
5070  <varlistentry>
5071   <term>Example usage (sections):</term>
5072   <listitem>
5073    <para>
5074     <screen>
5075 # Selectively turn off compression, and enable a filter
5076 #
5077 { +filter{tiny-textforms} +prevent-compression }
5078 # Match only these sites
5079  .google.
5080  sourceforge.net
5081  sf.net
5082
5083 # Or instead, we could set a universal default:
5084 #
5085 { +prevent-compression }
5086  / # Match all sites
5087
5088 # Then maybe make exceptions for broken sites:
5089 #
5090 { -prevent-compression }
5091 .compusa.com/</screen>
5092    </para>
5093   </listitem>
5094  </varlistentry>
5095
5096 </variablelist>
5097 </sect3>
5098
5099
5100 <!--   ~~~~~       New section      ~~~~~     -->
5101 <sect3 renderas="sect4" id="overwrite-last-modified">
5102 <title>overwrite-last-modified</title>
5103 <!--
5104 new action
5105 -->
5106 <variablelist>
5107  <varlistentry>
5108   <term>Typical use:</term>
5109   <listitem>
5110    <para>Prevent yet another way to track the user's steps between sessions.</para>
5111   </listitem>
5112  </varlistentry>
5113
5114  <varlistentry>
5115   <term>Effect:</term>
5116   <listitem>
5117    <para>
5118     Deletes the <quote>Last-Modified:</quote> HTTP server header or modifies its value.
5119    </para>
5120   </listitem>
5121  </varlistentry>
5122
5123  <varlistentry>
5124   <term>Type:</term>
5125   <!-- Boolean, Parameterized, Multi-value -->
5126   <listitem>
5127    <para>Parameterized.</para>
5128   </listitem>
5129  </varlistentry>
5130
5131  <varlistentry>
5132   <term>Parameter:</term>
5133   <listitem>
5134    <para>
5135     One of the keywords: <quote>block</quote>, <quote>reset-to-request-time</quote>
5136     and <quote>randomize</quote>
5137    </para>
5138   </listitem>
5139  </varlistentry>
5140
5141  <varlistentry>
5142   <term>Notes:</term>
5143   <listitem>
5144    <para>
5145     Removing the <quote>Last-Modified:</quote> header is useful for filter
5146     testing, where you want to force a real reload instead of getting status
5147     code <quote>304</quote>, which would cause the browser to reuse the old
5148     version of the page.
5149    </para>
5150    <para>
5151     The <quote>randomize</quote> option overwrites the value of the
5152     <quote>Last-Modified:</quote> header with a randomly chosen time
5153     between the original value and the current time. In theory the server
5154     could send each document with a different <quote>Last-Modified:</quote>
5155     header to track visits without using cookies. <quote>Randomize</quote>
5156     makes it impossible and the browser can still revalidate cached documents.
5157    </para>
5158    <para>
5159     <quote>reset-to-request-time</quote> overwrites the value of the
5160     <quote>Last-Modified:</quote> header with the current time. You could use
5161     this option together with
5162     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
5163     to further customize your random range.
5164    </para>
5165    <para>
5166     The preferred parameter here is <quote>randomize</quote>. It is safe
5167     to use, as long as the time settings are more or less correct.
5168     If the server sets the <quote>Last-Modified:</quote> header to the time
5169     of the request, the random range becomes zero and the value stays the same.
5170     Therefore you should later randomize it a second time with
5171     <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>,
5172     just to be sure.
5173    </para>
5174    <para>
5175     It is also recommended to use this action together with
5176     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
5177    </para>
5178   </listitem>
5179  </varlistentry>
5180
5181  <varlistentry>
5182   <term>Example usage:</term>
5183   <listitem>
5184     <para>
5185      <screen># Let the browser revalidate without being tracked across sessions
5186 { +hide-if-modified-since{-60} \
5187  +overwrite-last-modified{randomize} \
5188  +crunch-if-none-match}
5189 /</screen>
5190    </para>
5191   </listitem>
5192  </varlistentry>
5193 </variablelist>
5194 </sect3>
5195
5196
5197 <!--   ~~~~~       New section      ~~~~~     -->
5198 <sect3 renderas="sect4" id="redirect">
5199 <title>redirect</title>
5200 <!--
5201 new action
5202 -->
5203 <variablelist>
5204  <varlistentry>
5205   <term>Typical use:</term>
5206   <listitem>
5207    <para>
5208     Redirect requests to other sites.
5209    </para>
5210   </listitem>
5211  </varlistentry>
5212
5213  <varlistentry>
5214   <term>Effect:</term>
5215   <listitem>
5216    <para>
5217     Convinces the browser that the requested document has been moved
5218     to another location and the browser should get it from there.
5219    </para>
5220   </listitem>
5221  </varlistentry>
5222
5223  <varlistentry>
5224   <term>Type:</term>
5225   <!-- Boolean, Parameterized, Multi-value -->
5226   <listitem>
5227    <para>Parameterized</para>
5228   </listitem>
5229  </varlistentry>
5230
5231  <varlistentry>
5232   <term>Parameter:</term>
5233   <listitem>
5234    <para>
5235     An absolute URL or a single pcrs command.
5236    </para>
5237   </listitem>
5238  </varlistentry>
5239
5240  <varlistentry>
5241   <term>Notes:</term>
5242   <listitem>
5243    <para>
5244     Requests to which this action applies are answered with a
5245     HTTP redirect to URLs of your choosing. The new URL is
5246     either provided as parameter, or derived by applying a
5247     single pcrs command to the original URL.
5248    </para>
5249    <para>
5250     The syntax for pcrs commands is documented in the
5251     <link linkend="filter-file">filter file</link> section.
5252    </para>
5253    <para>
5254     This action will be ignored if you use it together with
5255     <literal><link linkend="block">block</link></literal>.
5256     It can be combined with
5257     <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
5258     to redirect to a decoded version of a rewritten URL.
5259    </para>
5260    <para>
5261     Use this action carefully, make sure not to create redirection loops
5262     and be aware that using your own redirects might make it
5263     possible to fingerprint your requests.
5264    </para>
5265    <para>
5266     In case of problems with your redirects, or simply to watch
5267     them working, enable <link linkend="DEBUG">debug 128</link>.
5268    </para>
5269   </listitem>
5270  </varlistentry>
5271
5272  <varlistentry>
5273   <term>Example usages:</term>
5274   <listitem>
5275    <para>
5276     <screen># Replace example.com's style sheet with another one
5277 { +redirect{http://localhost/css-replacements/example.com.css} }
5278  example.com/stylesheet\.css
5279
5280 # Create a short, easy to remember nickname for a favorite site
5281 # (relies on the browser accept and forward invalid URLs to &my-app;)
5282 { +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
5283  a
5284
5285 # Always use the expanded view for Undeadly.org articles
5286 # (Note the $ at the end of the URL pattern to make sure
5287 # the request for the rewritten URL isn't redirected as well)
5288 {+redirect{s@$@&amp;mode=expanded@}}
5289 undeadly.org/cgi\?action=article&amp;sid=\d*$
5290
5291 # Redirect Google search requests to MSN
5292 {+redirect{s@^http://[^/]*/search\?q=([^&amp;]*).*@http://search.msn.com/results.aspx?q=$1@}}
5293 .google.com/search
5294
5295 # Redirect MSN search requests to Yahoo
5296 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&amp;]*).*@http://search.yahoo.com/search?p=$1@}}
5297 search.msn.com//results\.aspx\?q=
5298
5299 # Redirect remote requests for this manual
5300 # to the local version delivered by Privoxy
5301 {+redirect{s@^http://www@http://config@}}
5302 www.privoxy.org/user-manual/</screen>
5303    </para>
5304   </listitem>
5305  </varlistentry>
5306
5307 </variablelist>
5308 </sect3>
5309
5310
5311 <!--   ~~~~~       New section      ~~~~~     -->
5312 <sect3 renderas="sect4" id="server-header-filter">
5313 <title>server-header-filter</title>
5314
5315 <variablelist>
5316  <varlistentry>
5317   <term>Typical use:</term>
5318   <listitem>
5319    <para>
5320    Rewrite or remove single server headers.
5321    </para>
5322   </listitem>
5323  </varlistentry>
5324
5325  <varlistentry>
5326   <term>Effect:</term>
5327   <listitem>
5328    <para>
5329     All server headers to which this action applies are filtered on-the-fly
5330     through the specified regular expression based substitutions.
5331    </para>
5332   </listitem>
5333  </varlistentry>
5334
5335  <varlistentry>
5336   <term>Type:</term>
5337   <!-- boolean, parameterized, Multi-value -->
5338   <listitem>
5339    <para>Parameterized.</para>
5340   </listitem>
5341  </varlistentry>
5342
5343  <varlistentry>
5344   <term>Parameter:</term>
5345   <listitem>
5346    <para>
5347     The name of a server-header filter, as defined in one of the
5348     <link linkend="filter-file">filter files</link>.
5349    </para>
5350   </listitem>
5351  </varlistentry>
5352
5353  <varlistentry>
5354   <term>Notes:</term>
5355   <listitem>
5356    <para>
5357     Server-header filters are applied to each header on its own, not to
5358     all at once. This makes it easier to diagnose problems, but on the downside
5359     you can't write filters that only change header x if header y's value is z.
5360     You can do that by using tags though.
5361    </para>
5362    <para>
5363     Server-header filters are executed after the other header actions have finished
5364     and use their output as input.
5365    </para>
5366    <para>
5367     Please refer to the <link linkend="filter-file">filter file chapter</link>
5368     to learn which server-header filters are available by default, and how to
5369     create your own.
5370    </para>
5371  </listitem>
5372  </varlistentry>
5373
5374  <varlistentry>
5375   <term>Example usage (section):</term>
5376   <listitem>
5377     <para>
5378      <screen>
5379 {+server-header-filter{html-to-xml}}
5380 example.org/xml-instance-that-is-delivered-as-html
5381
5382 {+server-header-filter{xml-to-html}}
5383 example.org/instance-that-is-delivered-as-xml-but-is-not
5384     </screen>
5385     </para>
5386   </listitem>
5387  </varlistentry>
5388
5389 </variablelist>
5390 </sect3>
5391
5392
5393 <!--   ~~~~~       New section      ~~~~~     -->
5394 <sect3 renderas="sect4" id="server-header-tagger">
5395 <title>server-header-tagger</title>
5396
5397 <variablelist>
5398  <varlistentry>
5399   <term>Typical use:</term>
5400   <listitem>
5401    <para>
5402    Enable or disable filters based on the Content-Type header.
5403    </para>
5404   </listitem>
5405  </varlistentry>
5406
5407  <varlistentry>
5408   <term>Effect:</term>
5409   <listitem>
5410    <para>
5411     Server headers to which this action applies are filtered on-the-fly through
5412     the specified regular expression based substitutions, the result is used as
5413     tag.
5414    </para>
5415   </listitem>
5416  </varlistentry>
5417
5418  <varlistentry>
5419   <term>Type:</term>
5420   <!-- boolean, parameterized, Multi-value -->
5421   <listitem>
5422    <para>Parameterized.</para>
5423   </listitem>
5424  </varlistentry>
5425
5426  <varlistentry>
5427   <term>Parameter:</term>
5428   <listitem>
5429    <para>
5430     The name of a server-header tagger, as defined in one of the
5431     <link linkend="filter-file">filter files</link>.
5432    </para>
5433   </listitem>
5434  </varlistentry>
5435
5436  <varlistentry>
5437   <term>Notes:</term>
5438   <listitem>
5439    <para>
5440     Server-header taggers are applied to each header on its own,
5441     and as the header isn't modified, each tagger <quote>sees</quote>
5442     the original.
5443    </para>
5444    <para>
5445     Server-header taggers are executed before all other header actions
5446     that modify server headers. Their tags can be used to control
5447     all of the other server-header actions, the content filters
5448     and the crunch actions (<link linkend="redirect">redirect</link>
5449     and <link linkend="block">block</link>).
5450    </para>
5451    <para>
5452     Obviously crunching based on tags created by server-header taggers
5453     doesn't prevent the request from showing up in the server's log file.
5454    </para>
5455
5456  </listitem>
5457  </varlistentry>
5458
5459  <varlistentry>
5460   <term>Example usage (section):</term>
5461   <listitem>
5462     <para>
5463      <screen>
5464 # Tag every request with the content type declared by the server
5465 {+server-header-tagger{content-type}}
5466 /
5467     </screen>
5468     </para>
5469   </listitem>
5470  </varlistentry>
5471
5472 </variablelist>
5473 </sect3>
5474
5475
5476 <!--   ~~~~~       New section      ~~~~~     -->
5477 <sect3 renderas="sect4" id="session-cookies-only">
5478 <title>session-cookies-only</title>
5479
5480 <variablelist>
5481  <varlistentry>
5482   <term>Typical use:</term>
5483   <listitem>
5484    <para>
5485     Allow only temporary <quote>session</quote> cookies (for the current
5486     browser session <emphasis>only</emphasis>).
5487    </para>
5488   </listitem>
5489  </varlistentry>
5490
5491  <varlistentry>
5492   <term>Effect:</term>
5493   <listitem>
5494    <para>
5495     Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote>
5496     server headers. Most browsers will not store such cookies permanently and
5497     forget them in between sessions.
5498    </para>
5499   </listitem>
5500  </varlistentry>
5501
5502 <varlistentry>
5503   <term>Type:</term>
5504   <!-- Boolean, Parameterized, Multi-value -->
5505   <listitem>
5506    <para>Boolean.</para>
5507   </listitem>
5508  </varlistentry>
5509
5510  <varlistentry>
5511   <term>Parameter:</term>
5512   <listitem>
5513    <para>
5514     N/A
5515    </para>
5516   </listitem>
5517  </varlistentry>
5518
5519  <varlistentry>
5520   <term>Notes:</term>
5521   <listitem>
5522    <para>
5523     This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
5524     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
5525     websites that insist or rely on setting cookies, without compromising your privacy too badly.
5526    </para>
5527    <para>
5528     Most browsers will not permanently store cookies that have been processed by
5529     <literal>session-cookies-only</literal> and will forget about them between sessions.
5530     This makes profiling cookies useless, but won't break sites which require cookies so
5531     that you can log in for transactions. This is generally turned on for all
5532     sites, and is the recommended setting.
5533    </para>
5534    <para>
5535     It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
5536     together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
5537     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
5538     will be plainly killed.
5539    </para>
5540    <para>
5541     Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
5542     field. If you use an exotic browser, you might want to try it out to be sure.
5543    </para>
5544    <para>
5545     This setting also has no effect on cookies that may have been stored
5546     previously by the browser before starting <application>Privoxy</application>.
5547     These would have to be removed manually.
5548    </para>
5549    <para>
5550      <application>Privoxy</application> also uses
5551      the <link linkend="filter-content-cookies">content-cookies filter</link>
5552      to block some types of cookies. Content cookies are not effected by
5553      <literal>session-cookies-only</literal>.
5554    </para>
5555   </listitem>
5556  </varlistentry>
5557
5558  <varlistentry>
5559   <term>Example usage:</term>
5560   <listitem>
5561    <para>
5562      <screen>+session-cookies-only</screen>
5563    </para>
5564   </listitem>
5565  </varlistentry>
5566 </variablelist>
5567 </sect3>
5568
5569
5570 <!--   ~~~~~       New section      ~~~~~     -->
5571 <sect3 renderas="sect4" id="set-image-blocker">
5572 <title>set-image-blocker</title>
5573
5574 <variablelist>
5575  <varlistentry>
5576   <term>Typical use:</term>
5577   <listitem>
5578    <para>Choose the replacement for blocked images</para>
5579   </listitem>
5580  </varlistentry>
5581
5582  <varlistentry>
5583   <term>Effect:</term>
5584   <listitem>
5585    <para>
5586      This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
5587      <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
5588      linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
5589      apply, i.e. if the request is to be blocked as an image,
5590      <emphasis>then</emphasis> the parameter of this action decides what will be
5591      sent as a replacement.
5592    </para>
5593   </listitem>
5594  </varlistentry>
5595
5596  <varlistentry>
5597   <term>Type:</term>
5598   <!-- Boolean, Parameterized, Multi-value -->
5599   <listitem>
5600    <para>Parameterized.</para>
5601   </listitem>
5602  </varlistentry>
5603
5604  <varlistentry>
5605   <term>Parameter:</term>
5606   <listitem>
5607    <itemizedlist>
5608     <listitem>
5609      <para>
5610       <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
5611       decent, scales very well, and makes it obvious where banners were busted.
5612      </para>
5613     </listitem>
5614     <listitem>
5615      <para>
5616       <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
5617       completely, but makes it hard to detect where <application>Privoxy</application> has blocked
5618       images on a given page and complicates troubleshooting if <application>Privoxy</application>
5619       has blocked innocent images, like navigation icons.
5620      </para>
5621     </listitem>
5622     <listitem>
5623      <para>
5624       <quote><replaceable class="parameter">target-url</replaceable></quote> to
5625       send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
5626       to any image anywhere, even in your local filesystem via <quote>file:///</quote> URL.
5627       (But note that not all browsers support redirecting to a local file system).
5628      </para>
5629      <para>
5630       A good application of redirects is to use special <application>Privoxy</application>-built-in
5631       URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
5632       This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
5633       the first place, but enables your browser to cache the replacement image, instead of requesting
5634       it over and over again.
5635      </para>
5636     </listitem>
5637    </itemizedlist>
5638   </listitem>
5639  </varlistentry>
5640
5641  <varlistentry>
5642   <term>Notes:</term>
5643   <listitem>
5644    <para>
5645     The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
5646     class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
5647     either <quote>blank</quote> or <quote>pattern</quote>.
5648    </para>
5649    <para>
5650     There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
5651     used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
5652     Auto will select the type of image that would have applied to the referring page, had it been an image.
5653    </para>
5654   </listitem>
5655  </varlistentry>
5656
5657  <varlistentry>
5658   <term>Example usage:</term>
5659   <listitem>
5660    <para>
5661     Built-in pattern:
5662    </para>
5663    <para>
5664     <screen>+set-image-blocker{pattern}</screen>
5665    </para>
5666    <para>
5667     Redirect to the BSD daemon:
5668    </para>
5669    <para>
5670     <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
5671    </para>
5672    <para>
5673     Redirect to the built-in pattern for better caching:
5674    </para>
5675    <para>
5676     <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
5677    </para>
5678   </listitem>
5679  </varlistentry>
5680 </variablelist>
5681 </sect3>
5682
5683
5684 <!--   ~~~~~       New section      ~~~~~     -->
5685 <sect3>
5686 <title>Summary</title>
5687 <para>
5688  Note that many of these actions have the potential to cause a page to
5689  misbehave, possibly even not to display at all. There are many ways
5690  a site designer may choose to design his site, and what HTTP header
5691  content, and other criteria, he may depend on. There is no way to have hard
5692  and fast rules for all sites. See the <link
5693  linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
5694  actions.
5695 </para>
5696 </sect3>
5697 </sect2>
5698
5699 <!--   ~~~~~       New section      ~~~~~     -->
5700 <sect2 id="aliases">
5701 <title>Aliases</title>
5702 <para>
5703  Custom <quote>actions</quote>, known to <application>Privoxy</application>
5704  as <quote>aliases</quote>, can be defined by combining other actions.
5705  These can in turn be invoked just like the built-in actions.
5706  Currently, an alias name can contain any character except space, tab,
5707  <quote>=</quote>,
5708  <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
5709  recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
5710  <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
5711  Alias names are not case sensitive, and are not required to start with a
5712  <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
5713  expanded.
5714 </para>
5715 <para>
5716  Aliases can be used throughout the actions file, but they <emphasis>must be
5717  defined in a special section at the top of the file!</emphasis>
5718  And there can only be one such section per actions file. Each actions file may
5719  have its own alias section, and the aliases defined in it are only visible
5720  within that file.
5721 </para>
5722 <para>
5723  There are two main reasons to use aliases: One is to save typing for frequently
5724  used combinations of actions, the other one is a gain in flexibility: If you
5725  decide once how you want to handle shops by defining an alias called
5726  <quote>shop</quote>, you can later change your policy on shops in
5727  <emphasis>one</emphasis> place, and your changes will take effect everywhere
5728  in the actions file where the <quote>shop</quote> alias is used. Calling aliases
5729  by their purpose also makes your actions files more readable.
5730 </para>
5731 <para>
5732  Currently, there is one big drawback to using aliases, though:
5733  <application>Privoxy</application>'s built-in web-based action file
5734  editor honors aliases when reading the actions files, but it expands
5735  them before writing. So the effects of your aliases are of course preserved,
5736  but the aliases themselves are lost when you edit sections that use aliases
5737  with it.
5738 </para>
5739
5740 <para>
5741  Now let's define some aliases...
5742 </para>
5743
5744 <para>
5745  <screen>
5746  # Useful custom aliases we can use later.
5747  #
5748  # Note the (required!) section header line and that this section
5749  # must be at the top of the actions file!
5750  #
5751  {{alias}}
5752
5753  # These aliases just save typing later:
5754  # (Note that some already use other aliases!)
5755  #
5756  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5757  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5758  +block-as-image      = +block{Blocked image.} +handle-as-image
5759  allow-all-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
5760
5761  # These aliases define combinations of actions
5762  # that are useful for certain types of sites:
5763  #
5764  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>
5765
5766  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link>
5767
5768  # Short names for other aliases, for really lazy people ;-)
5769  #
5770  c0 = +crunch-all-cookies
5771  c1 = -crunch-all-cookies</screen>
5772 </para>
5773
5774 <para>
5775  ...and put them to use. These sections would appear in the lower part of an
5776  actions file and define exceptions to the default actions (as specified further
5777  up for the <quote>/</quote> pattern):
5778 </para>
5779
5780 <para>
5781  <screen>
5782  # These sites are either very complex or very keen on
5783  # user data and require minimal interference to work:
5784  #
5785  {fragile}
5786  .office.microsoft.com
5787  .windowsupdate.microsoft.com
5788  # Gmail is really mail.google.com, not gmail.com
5789  mail.google.com
5790
5791  # Shopping sites:
5792  # Allow cookies (for setting and retrieving your customer data)
5793  #
5794  {shop}
5795  .quietpc.com
5796  .worldpay.com   # for quietpc.com
5797  mybank.example.com
5798
5799  # These shops require pop-ups:
5800  #
5801  {-filter{all-popups} -filter{unsolicited-popups}}
5802   .dabs.com
5803   .overclockers.co.uk</screen>
5804 </para>
5805
5806 <para>
5807  Aliases like <quote>shop</quote> and <quote>fragile</quote> are typically used for
5808  <quote>problem</quote> sites that require more than one action to be disabled
5809  in order to function properly.
5810 </para>
5811 </sect2>
5812 <!--
5813 hal stop here
5814 -->
5815 <!--   ~~~~~       New section      ~~~~~     -->
5816 <sect2 id="act-examples">
5817 <title>Actions Files Tutorial</title>
5818 <para>
5819  The above chapters have shown <link linkend="actions-file">which actions files
5820  there are and how they are organized</link>, how actions are <link
5821  linkend="actions">specified</link> and <link linkend="actions-apply">applied
5822  to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
5823  define and use <link linkend="aliases">aliases</link>. Now, let's look at an
5824  example <filename>match-all.action</filename>, <filename>default.action</filename>
5825  and <filename>user.action</filename> file and see how all these pieces come together:
5826 </para>
5827
5828 <sect3>
5829 <title>match-all.action</title>
5830 <para>
5831  Remember <emphasis>all actions are disabled when matching starts</emphasis>,
5832  so we have to explicitly enable the ones we want.
5833 </para>
5834
5835 <para>
5836  While the <filename>match-all.action</filename> file only contains a
5837  single section, it is probably the most important one. It has only one
5838  pattern, <quote><literal>/</literal></quote>, but this pattern
5839  <link linkend="af-patterns">matches all URLs</link>. Therefore, the set of
5840  actions used in this <quote>default</quote> section <emphasis>will
5841  be applied to all requests as a start</emphasis>. It can  be partly or
5842  wholly overridden by other actions files like <filename>default.action</filename>
5843  and <filename>user.action</filename>, but it will still be largely responsible
5844  for your overall browsing experience.
5845 </para>
5846
5847 <para>
5848  Again, at the start of matching, all actions are disabled, so there is
5849  no need to disable any actions here. (Remember: a <quote>+</quote>
5850  preceding the action name enables the action, a <quote>-</quote> disables!).
5851  Also note how this long line has been made more readable by splitting it into
5852  multiple lines with line continuation.
5853 </para>
5854
5855 <para>
5856  <screen>
5857 { \
5858  +<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
5859  +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
5860  +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
5861 }
5862 / # Match all URLs
5863  </screen>
5864 </para>
5865
5866 <para>
5867  The default behavior is now set.
5868 </para>
5869 </sect3>
5870
5871 <sect3>
5872 <title>default.action</title>
5873
5874 <para>
5875  If you aren't a developer, there's no need for you to edit the
5876  <filename>default.action</filename> file. It is maintained by
5877  the &my-app; developers and if you disagree with some of the
5878  sections, you should overrule them in your <filename>user.action</filename>.
5879 </para>
5880
5881 <para>
5882  Understanding the <filename>default.action</filename> file can
5883  help you with your <filename>user.action</filename>, though.
5884 </para>
5885
5886 <para>
5887  The first section in this file is a special section for internal use
5888  that prevents older &my-app; versions from reading the file:
5889 </para>
5890
5891 <para>
5892  <screen>
5893 ##########################################################################
5894 # Settings -- Don't change! For internal Privoxy use ONLY.
5895 ##########################################################################
5896 {{settings}}
5897 for-privoxy-version=3.0.11</screen>
5898 </para>
5899
5900 <para>
5901  After that comes the (optional) alias section. We'll use the example
5902  section from the above <link linkend="aliases">chapter on aliases</link>,
5903  that also explains why and how aliases are used:
5904 </para>
5905
5906 <para>
5907  <screen>
5908 ##########################################################################
5909 # Aliases
5910 ##########################################################################
5911 {{alias}}
5912
5913  # These aliases just save typing later:
5914  # (Note that some already use other aliases!)
5915  #
5916  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5917  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5918  +block-as-image      = +block{Blocked image.} +handle-as-image
5919  mercy-for-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
5920
5921  # These aliases define combinations of actions
5922  # that are useful for certain types of sites:
5923  #
5924  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>
5925  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
5926 </para>
5927
5928 <para>
5929  The first of our specialized sections is concerned with <quote>fragile</quote>
5930  sites, i.e. sites that require minimum interference, because they are either
5931  very complex or very keen on tracking you (and have mechanisms in place that
5932  make them unusable for people who avoid being tracked). We will simply use
5933  our pre-defined <literal>fragile</literal> alias instead of stating the list
5934  of actions explicitly:
5935 </para>
5936
5937 <para>
5938  <screen>
5939 ##########################################################################
5940 # Exceptions for sites that'll break under the default action set:
5941 ##########################################################################
5942
5943 # "Fragile" Use a minimum set of actions for these sites (see alias above):
5944 #
5945 { fragile }
5946 .office.microsoft.com           # surprise, surprise!
5947 .windowsupdate.microsoft.com
5948 mail.google.com</screen>
5949 </para>
5950
5951 <para>
5952  Shopping sites are not as fragile, but they typically
5953  require cookies to log in, and pop-up windows for shopping
5954  carts or item details. Again, we'll use a pre-defined alias:
5955 </para>
5956
5957 <para>
5958  <screen>
5959 # Shopping sites:
5960 #
5961 { shop }
5962 .quietpc.com
5963 .worldpay.com   # for quietpc.com
5964 .jungle.com
5965 .scan.co.uk</screen>
5966 </para>
5967
5968 <para>
5969  The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
5970  action, which may have been enabled in <filename>match-all.action</filename>,
5971  breaks some sites. So disable it for popular sites where we know it misbehaves:
5972 </para>
5973
5974 <para>
5975  <screen>
5976 { -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
5977 login.yahoo.com
5978 edit.*.yahoo.com
5979 .google.com
5980 .altavista.com/.*(like|url|link):http
5981 .altavista.com/trans.*urltext=http
5982 .nytimes.com</screen>
5983 </para>
5984
5985 <para>
5986  It is important that <application>Privoxy</application> knows which
5987  URLs belong to images, so that <emphasis>if</emphasis> they are to
5988  be blocked, a substitute image can be sent, rather than an HTML page.
5989  Contacting the remote site to find out is not an option, since it
5990  would destroy the loading time advantage of banner blocking, and it
5991  would feed the advertisers information about you. We can mark any
5992  URL as an image with the <literal><link
5993  linkend="handle-as-image">handle-as-image</link></literal> action,
5994  and marking all URLs that end in a known image file extension is a
5995  good start:
5996 </para>
5997
5998 <para>
5999  <screen>
6000 ##########################################################################
6001 # Images:
6002 ##########################################################################
6003
6004 # Define which file types will be treated as images, in case they get
6005 # blocked further down this file:
6006 #
6007 { +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
6008 /.*\.(gif|jpe?g|png|bmp|ico)$</screen>
6009 </para>
6010
6011 <para>
6012  And then there are known banner sources. They often use scripts to
6013  generate the banners, so it won't be visible from the URL that the
6014  request is for an image. Hence we block them <emphasis>and</emphasis>
6015  mark them as images in one go, with the help of our
6016  <literal>+block-as-image</literal> alias defined above. (We could of
6017  course just as well use <literal>+<link linkend="block">block</link>
6018  +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
6019  Remember that the type of the replacement image is chosen by the
6020  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
6021  action. Since all URLs have matched the default section with its
6022  <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
6023  action before, it still applies and needn't be repeated:
6024 </para>
6025
6026 <para>
6027  <screen>
6028 # Known ad generators:
6029 #
6030 { +block-as-image }
6031 ar.atwola.com
6032 .ad.doubleclick.net
6033 .ad.*.doubleclick.net
6034 .a.yimg.com/(?:(?!/i/).)*$
6035 .a[0-9].yimg.com/(?:(?!/i/).)*$
6036 bs*.gsanet.com
6037 .qkimg.net</screen>
6038 </para>
6039
6040 <para>
6041  One of the most important jobs of <application>Privoxy</application>
6042  is to block banners. Many of these can be <quote>blocked</quote>
6043  by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
6044  action, which we enabled above, and which deletes the references to banner
6045  images from the pages while they are loaded, so the browser doesn't request
6046  them anymore, and hence they don't need to be blocked here. But this naturally
6047  doesn't catch all banners, and some people choose not to use filters, so we
6048  need a comprehensive list of patterns for banner URLs here, and apply the
6049  <literal><link linkend="block">block</link></literal> action to them.
6050 </para>
6051 <para>
6052  First comes many generic patterns, which do most of the work, by
6053  matching typical domain and path name components of banners. Then comes
6054  a list of individual patterns for specific sites, which is omitted here
6055  to keep the example short:
6056 </para>
6057
6058 <para>
6059  <screen>
6060 ##########################################################################
6061 # Block these fine banners:
6062 ##########################################################################
6063 { <link linkend="BLOCK">+block{Banner ads.}</link> }
6064
6065 # Generic patterns:
6066 #
6067 ad*.
6068 .*ads.
6069 banner?.
6070 count*.
6071 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
6072 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
6073
6074 # Site-specific patterns (abbreviated):
6075 #
6076 .hitbox.com</screen>
6077 </para>
6078
6079 <para>
6080  It's quite remarkable how many advertisers actually call their banner
6081  servers ads.<replaceable>company</replaceable>.com, or call the directory
6082  in which the banners are stored simply <quote>banners</quote>. So the above
6083  generic patterns are surprisingly effective.
6084 </para>
6085 <para>
6086  But being very generic, they necessarily also catch URLs that we don't want
6087  to block. The pattern <literal>.*ads.</literal> e.g. catches
6088  <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
6089  but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
6090  <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
6091  well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
6092  section above.
6093 </para>
6094 <para>
6095  Note that these are exceptions to exceptions from the default! Consider the URL
6096  <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
6097  so it wouldn't get blocked. Then comes the defaults section, which matches the
6098  URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
6099  action once again. Then it matches <literal>.*ads.</literal>, an exception to the
6100  general non-blocking policy, and suddenly
6101  <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
6102  <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
6103  applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
6104  with no <literal><link linkend="BLOCK">block</link></literal> action applying.
6105 </para>
6106
6107 <para>
6108  <screen>
6109 ##########################################################################
6110 # Save some innocent victims of the above generic block patterns:
6111 ##########################################################################
6112
6113 # By domain:
6114 #
6115 { -<link linkend="BLOCK">block</link> }
6116 adv[io]*.  # (for advogato.org and advice.*)
6117 adsl.      # (has nothing to do with ads)
6118 adobe.     # (has nothing to do with ads either)
6119 ad[ud]*.   # (adult.* and add.*)
6120 .edu       # (universities don't host banners (yet!))
6121 .*loads.   # (downloads, uploads etc)
6122
6123 # By path:
6124 #
6125 /.*loads/
6126
6127 # Site-specific:
6128 #
6129 www.globalintersec.com/adv # (adv = advanced)
6130 www.ugu.com/sui/ugu/adv</screen>
6131 </para>
6132
6133 <para>
6134  Filtering source code can have nasty side effects,
6135  so make an exception for our friends at sourceforge.net,
6136  and all paths with <quote>cvs</quote> in them. Note that
6137  <literal>-<link linkend="FILTER">filter</link></literal>
6138  disables <emphasis>all</emphasis> filters in one fell swoop!
6139 </para>
6140
6141 <para>
6142  <screen>
6143 # Don't filter code!
6144 #
6145 { -<link linkend="FILTER">filter</link> }
6146 /(.*/)?cvs
6147 bugzilla.
6148 developer.
6149 wiki.
6150 .sourceforge.net</screen>
6151 </para>
6152
6153 <para>
6154  The actual <filename>default.action</filename> is of course much more
6155  comprehensive, but we hope this example made clear how it works.
6156 </para>
6157
6158 </sect3>
6159
6160 <sect3><title>user.action</title>
6161
6162 <para>
6163  So far we are painting with a broad brush by setting general policies,
6164  which would be a reasonable starting point for many people. Now,
6165  you might want to be more specific and have customized rules that
6166  are more suitable to your personal habits and preferences. These would
6167  be for narrowly defined situations like your ISP or your bank, and should
6168  be placed in <filename>user.action</filename>, which is parsed after all other
6169  actions files and hence has the last word, over-riding any previously
6170  defined actions. <filename>user.action</filename> is also a
6171  <emphasis>safe</emphasis> place for your personal settings, since
6172  <filename>default.action</filename> is actively maintained by the
6173  <application>Privoxy</application> developers and you'll probably want
6174  to install updated versions from time to time.
6175 </para>
6176
6177 <para>
6178  So let's look at a few examples of things that one might typically do in
6179  <filename>user.action</filename>:
6180 </para>
6181
6182
6183 <!-- brief sample user.action here -->
6184
6185 <para>
6186  <screen>
6187 # My user.action file. &lt;fred@example.com&gt;</screen>
6188 </para>
6189
6190 <para>
6191  As <link linkend="aliases">aliases</link> are local to the actions
6192  file that they are defined in, you can't use the ones from
6193  <filename>default.action</filename>, unless you repeat them here:
6194 </para>
6195
6196 <para>
6197  <screen>
6198 # Aliases are local to the file they are defined in.
6199 # (Re-)define aliases for this file:
6200 #
6201 {{alias}}
6202 #
6203 # These aliases just save typing later, and the alias names should
6204 # be self explanatory.
6205 #
6206 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
6207 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
6208  allow-all-cookies  = -crunch-all-cookies -session-cookies-only
6209  allow-popups       = -filter{all-popups}
6210 +block-as-image     = +block{Blocked as image.} +handle-as-image
6211 -block-as-image     = -block
6212
6213 # These aliases define combinations of actions that are useful for
6214 # certain types of sites:
6215 #
6216 fragile     = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
6217 shop        = -crunch-all-cookies allow-popups
6218
6219 # Allow ads for selected useful free sites:
6220 #
6221 allow-ads   = -block -filter{banners-by-size} -filter{banners-by-link}
6222
6223 # Alias for specific file types that are text, but might have conflicting
6224 # MIME types. We want the browser to force these to be text documents.
6225 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>
6226
6227 </para>
6228
6229 <para>
6230  Say you have accounts on some sites that you visit regularly, and
6231  you don't want to have to log in manually each time. So you'd like
6232  to allow persistent cookies for these sites. The
6233  <literal>allow-all-cookies</literal> alias defined above does exactly
6234  that, i.e. it disables crunching of cookies in any direction, and the
6235  processing of cookies to make them only temporary.
6236 </para>
6237
6238 <para>
6239  <screen>
6240 { allow-all-cookies }
6241  sourceforge.net
6242  .yahoo.com
6243  .msdn.microsoft.com
6244  .redhat.com</screen>
6245 </para>
6246
6247 <para>
6248  Your bank is allergic to some filter, but you don't know which, so you disable them all:
6249 </para>
6250
6251 <para>
6252  <screen>
6253 { -<link linkend="FILTER">filter</link> }
6254  .your-home-banking-site.com</screen>
6255 </para>
6256
6257 <para>
6258  Some file types you may not want to filter for various reasons:
6259 </para>
6260
6261 <para>
6262  <screen>
6263 # Technical documentation is likely to contain strings that might
6264 # erroneously get altered by the JavaScript-oriented filters:
6265 #
6266 .tldp.org
6267 /(.*/)?selfhtml/
6268
6269 # And this stupid host sends streaming video with a wrong MIME type,
6270 # so that Privoxy thinks it is getting HTML and starts filtering:
6271 #
6272 stupid-server.example.com/</screen>
6273 </para>
6274
6275 <para>
6276  Example of a simple <link linkend="BLOCK">block</link> action. Say you've
6277  seen an ad on your favourite page on example.com that you want to get rid of.
6278  You have right-clicked the image, selected <quote>copy image location</quote>
6279  and pasted the URL below while removing the leading http://, into a
6280  <literal>{ +block{} }</literal> section. Note that <literal>{ +handle-as-image
6281  }</literal> need not be specified, since all URLs ending in
6282  <literal>.gif</literal> will be tagged as images by the general rules as set
6283  in default.action anyway:
6284 </para>
6285
6286 <para>
6287  <screen>
6288 { +<link linkend="BLOCK">block</link>{Nasty ads.} }
6289  www.example.com/nasty-ads/sponsor\.gif
6290  another.example.net/more/junk/here/</screen>
6291 </para>
6292
6293 <para>
6294  The URLs of dynamically generated banners, especially from large banner
6295  farms, often don't use the well-known image file name extensions, which
6296  makes it impossible for <application>Privoxy</application> to guess
6297  the file type just by looking at the URL.
6298  You can use the <literal>+block-as-image</literal> alias defined above for
6299  these cases.
6300  Note that objects which match this rule but then turn out NOT to be an
6301  image are typically rendered as a <quote>broken image</quote> icon by the
6302  browser. Use cautiously.
6303 </para>
6304
6305 <para>
6306  <screen>
6307 { +block-as-image }
6308  .doubleclick.net
6309  .fastclick.net
6310  /Realmedia/ads/
6311  ar.atwola.com/</screen>
6312 </para>
6313
6314 <para>
6315  Now you noticed that the default configuration breaks Forbes Magazine,
6316  but you were too lazy to find out which action is the culprit, and you
6317  were again too lazy to give <link linkend="contact">feedback</link>, so
6318  you just used the <literal>fragile</literal> alias on the site, and
6319  -- <emphasis>whoa!</emphasis> -- it worked. The <literal>fragile</literal>
6320  aliases disables those actions that are most likely to break a site. Also,
6321  good for testing purposes to see if it is <application>Privoxy</application>
6322  that is causing the problem or not. We later find other regular sites
6323  that misbehave, and add those to our personalized list of troublemakers:
6324 </para>
6325
6326 <para>
6327 <screen>
6328 { fragile }
6329  .forbes.com
6330  webmail.example.com
6331  .mybank.com</screen>
6332 </para>
6333
6334 <para>
6335  You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
6336  but it is disabled in the distributed actions file.
6337  So you'd like to turn it on in your private,
6338  update-safe config, once and for all:
6339 </para>
6340
6341 <para>
6342 <screen>
6343 { +<link linkend="filter-fun">filter{fun}</link> }
6344  / # For ALL sites!</screen>
6345 </para>
6346
6347 <para>
6348  Note that the above is not really a good idea: There are exceptions
6349  to the filters in <filename>default.action</filename> for things that
6350  really shouldn't be filtered, like code on CVS->Web interfaces. Since
6351  <filename>user.action</filename> has the last word, these exceptions
6352  won't be valid for the <quote>fun</quote> filtering specified here.
6353 </para>
6354
6355 <para>
6356  You might also worry about how your favourite free websites are
6357  funded, and find that they rely on displaying banner advertisements
6358  to survive. So you might want to specifically allow banners for those
6359  sites that you feel provide value to you:
6360 </para>
6361
6362 <para>
6363 <screen>
6364 { allow-ads }
6365  .sourceforge.net
6366  .slashdot.org
6367  .osdn.net</screen>
6368 </para>
6369
6370 <para>
6371  Note that <literal>allow-ads</literal> has been aliased to
6372  <literal>-<link linkend="block">block</link></literal>,
6373  <literal>-<link linkend="filter-banners-by-size">filter{banners-by-size}</link></literal>, and
6374  <literal>-<link linkend="filter-banners-by-link">filter{banners-by-link}</link></literal> above.
6375 </para>
6376
6377 <para>
6378  Invoke another alias here to force an over-ride of the MIME type <literal>
6379  application/x-sh</literal> which typically would open a download type
6380  dialog. In my case, I want to look at the shell script, and then I can save
6381  it should I choose to.
6382 </para>
6383
6384 <para>
6385 <screen>
6386 { handle-as-text }
6387  /.*\.sh$</screen>
6388 </para>
6389
6390 <para>
6391  <filename>user.action</filename> is generally the best place to define
6392  exceptions and additions to the default policies of
6393  <filename>default.action</filename>. Some actions are safe to have their
6394  default policies set here though. So let's set a default policy to have a
6395  <quote>blank</quote> image as opposed to the checkerboard pattern for
6396  <emphasis>ALL</emphasis> sites. <quote>/</quote> of course matches all URL
6397  paths and patterns:
6398 </para>
6399
6400 <para>
6401 <screen>
6402 { +<link linkend="set-image-blocker">set-image-blocker{blank}</link> }
6403 / # ALL sites</screen>
6404 </para>
6405
6406 </sect3>
6407 </sect2>
6408
6409 <!--  ~  End section  ~  -->
6410
6411 </sect1>
6412
6413 <!--  ~  End section  ~  -->
6414
6415 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6416
6417 <sect1 id="filter-file">
6418 <title>Filter Files</title>
6419
6420 <para>
6421  On-the-fly text substitutions need
6422  to be defined in a <quote>filter file</quote>. Once defined, they
6423  can then be invoked as an <quote>action</quote>.
6424 </para>
6425
6426 <para>
6427  &my-app; supports three different filter actions:
6428  <literal><link linkend="filter">filter</link></literal> to
6429  rewrite the content that is send to the client,
6430  <literal><link linkend="client-header-filter">client-header-filter</link></literal>
6431  to rewrite headers that are send by the client, and
6432  <literal><link linkend="server-header-filter">server-header-filter</link></literal>
6433  to rewrite headers that are send by the server.
6434 </para>
6435
6436 <para>
6437  &my-app; also supports two tagger actions:
6438  <literal><link linkend="client-header-tagger">client-header-tagger</link></literal>
6439  and
6440  <literal><link linkend="server-header-tagger">server-header-tagger</link></literal>.
6441  Taggers and filters use the same syntax in the filter files, the difference
6442  is that taggers don't modify the text they are filtering, but use a rewritten
6443  version of the filtered text as tag. The tags can then be used to change the
6444  applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
6445 </para>
6446
6447
6448 <para>
6449  Multiple filter files can be defined through the <literal> <link
6450  linkend="filterfile">filterfile</link></literal> config directive. The filters
6451  as supplied by the developers are located in
6452  <filename>default.filter</filename>. It is recommended that any locally
6453  defined or modified filters go in a separately defined file such as
6454  <filename>user.filter</filename>.
6455  </para>
6456
6457 <para>
6458  Common tasks for content filters are to eliminate common annoyances in
6459  HTML and JavaScript, such as pop-up windows,
6460  exit consoles, crippled windows without navigation tools, the
6461  infamous &lt;BLINK&gt; tag etc, to suppress images with certain
6462  width and height attributes (standard banner sizes or web-bugs),
6463  or just to have fun.
6464 </para>
6465
6466 <para>
6467  Enabled content filters are applied to any content whose
6468  <quote>Content Type</quote> header is recognised as a sign
6469  of text-based content, with the exception of <literal>text/plain</literal>.
6470  Use the <link linkend="FORCE-TEXT-MODE">force-text-mode</link> action
6471  to also filter other content.
6472 </para>
6473
6474 <para>
6475  Substitutions are made at the source level, so if you want to <quote>roll
6476  your own</quote> filters, you should first be familiar with HTML syntax,
6477  and, of course, regular expressions.
6478 </para>
6479
6480 <para>
6481  Just like the <link linkend="actions-file">actions files</link>, the
6482  filter file is organized in sections, which are called <emphasis>filters</emphasis>
6483  here. Each filter consists of a heading line, that starts with one of the
6484  <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
6485  <literal>CLIENT-HEADER-FILTER:</literal> or <literal>SERVER-HEADER-FILTER:</literal>
6486  followed by the filter's <emphasis>name</emphasis>, and a short (one line)
6487  <emphasis>description</emphasis> of what it does. Below that line
6488  come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
6489  text substitutions. By convention, the name of a filter
6490  should describe what the filter <emphasis>eliminates</emphasis>. The
6491  comment is used in the <ulink url="http://config.privoxy.org/">web-based
6492  user interface</ulink>.
6493 </para>
6494
6495 <para>
6496  Once a filter called <replaceable>name</replaceable> has been defined
6497  in the filter file, it can be invoked by using an action of the form
6498  +<literal><link linkend="filter">filter</link>{<replaceable>name</replaceable>}</literal>
6499  in any <link linkend="actions-file">actions file</link>.
6500 </para>
6501
6502 <para>
6503  Filter definitions start with a header line that contains the filter
6504  type, the filter name and the filter description.
6505  A content filter header line for a filter called <quote>foo</quote> could look
6506  like this:
6507 </para>
6508
6509 <para>
6510  <screen>FILTER: foo Replace all "foo" with "bar"</screen>
6511 </para>
6512
6513 <para>
6514  Below that line, and up to the next header line, come the jobs that
6515  define what text replacements the filter executes. They are specified
6516  in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
6517  <literal>s///</literal> operator. If you are familiar with Perl, you
6518  will find this to be quite intuitive, and may want to look at the
6519  PCRS documentation for the subtle differences to Perl behaviour. Most
6520  notably, the non-standard option letter <literal>U</literal> is supported,
6521  which turns the default to ungreedy matching.
6522 </para>
6523
6524 <para>
6525  If you are new to
6526   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
6527   Expressions</quote></ulink>, you might want to take a look at
6528  the <link linkend="regex">Appendix on regular expressions</link>, and
6529  see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
6530  manual</ulink> for
6531  <ulink url="http://perldoc.perl.org/perlop.html">the
6532  <literal>s///</literal> operator's syntax</ulink> and <ulink
6533  url="http://perldoc.perl.org/perlre.html">Perl-style regular
6534  expressions</ulink> in general.
6535  The below examples might also help to get you started.
6536 </para>
6537
6538
6539 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6540
6541 <sect2><title>Filter File Tutorial</title>
6542 <para>
6543  Now, let's complete our <quote>foo</quote> content filter. We have already defined
6544  the heading, but the jobs are still missing. Since all it does is to replace
6545  <quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
6546  needed:
6547 </para>
6548
6549 <para>
6550  <screen>s/foo/bar/</screen>
6551 </para>
6552
6553 <para>
6554  But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
6555  of <quote>foo</quote> should be replaced? Our current job will only take
6556  care of the first <quote>foo</quote> on each page. For global substitution,
6557  we'll need to add the <literal>g</literal> option:
6558 </para>
6559
6560 <para>
6561  <screen>s/foo/bar/g</screen>
6562 </para>
6563
6564 <para>
6565  Our complete filter now looks like this:
6566 </para>
6567 <para>
6568  <screen>FILTER: foo Replace all "foo" with "bar"
6569 s/foo/bar/g</screen>
6570 </para>
6571
6572 <para>
6573  Let's look at some real filters for more interesting examples. Here you see
6574  a filter that protects against some common annoyances that arise from JavaScript
6575  abuse. Let's look at its jobs one after the other:
6576 </para>
6577
6578
6579 <para>
6580  <screen>
6581 FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
6582
6583 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
6584 #
6585 s|(&lt;script.*)document\.referrer(.*&lt;/script&gt;)|$1"Not Your Business!"$2|Usg</screen>
6586 </para>
6587
6588 <para>
6589  Following the header line and a comment, you see the job. Note that it uses
6590  <literal>|</literal> as the delimiter instead of <literal>/</literal>, because
6591  the pattern contains a forward slash, which would otherwise have to be escaped
6592  by a backslash (<literal>\</literal>).
6593 </para>
6594
6595 <para>
6596  Now, let's examine the pattern: it starts with the text <literal>&lt;script.*</literal>
6597  enclosed in parentheses. Since the dot matches any character, and <literal>*</literal>
6598  means: <quote>Match an arbitrary number of the element left of myself</quote>, this
6599  matches <quote>&lt;script</quote>, followed by <emphasis>any</emphasis> text, i.e.
6600  it matches the whole page, from the start of the first &lt;script&gt; tag.
6601 </para>
6602
6603 <para>
6604  That's more than we want, but the pattern continues: <literal>document\.referrer</literal>
6605  matches only the exact string <quote>document.referrer</quote>. The dot needed to
6606  be <emphasis>escaped</emphasis>, i.e. preceded by a backslash, to take away its
6607  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
6608  Match from the start of the first &lt;script&gt; tag in a the page, up to, and including,
6609  the text <quote>document.referrer</quote>, if <emphasis>both</emphasis> are present
6610  in the page (and appear in that order).
6611 </para>
6612
6613 <para>
6614  But there's still more pattern to go. The next element, again enclosed in parentheses,
6615  is <literal>.*&lt;/script&gt;</literal>. You already know what <literal>.*</literal>
6616  means, so the whole pattern translates to: Match from the start of the first  &lt;script&gt;
6617  tag in a page to the end of the last &lt;script&gt; tag, provided that the text
6618  <quote>document.referrer</quote> appears somewhere in between.
6619 </para>
6620
6621 <para>
6622  This is still not the whole story, since we have ignored the options and the parentheses:
6623  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
6624  remembered and be available through the variables <literal>$1, $2, ...</literal> in
6625  the substitute. The <literal>U</literal> option switches to ungreedy matching, which means
6626  that the first <literal>.*</literal> in the pattern will only <quote>eat up</quote> all
6627  text in between <quote>&lt;script</quote> and the <emphasis>first</emphasis> occurrence
6628  of <quote>document.referrer</quote>, and that the second <literal>.*</literal> will
6629  only span the text up to the <emphasis>first</emphasis> <quote>&lt;/script&gt;</quote>
6630  tag. Furthermore, the <literal>s</literal> option says that the match may span
6631  multiple lines in the page, and the <literal>g</literal> option again means that the
6632  substitution is global.
6633 </para>
6634
6635 <para>
6636  So, to summarize, the pattern means: Match all scripts that contain the text
6637  <quote>document.referrer</quote>. Remember the parts of the script from
6638  (and including) the start tag up to (and excluding) the string
6639  <quote>document.referrer</quote> as <literal>$1</literal>, and the part following
6640  that string, up to and including the closing tag, as <literal>$2</literal>.
6641 </para>
6642
6643 <para>
6644  Now the pattern is deciphered, but wasn't this about substituting things? So
6645  lets look at the substitute: <literal>$1"Not Your Business!"$2</literal> is
6646  easy to read: The text remembered as <literal>$1</literal>, followed by
6647  <literal>"Not Your Business!"</literal> (<emphasis>including</emphasis>
6648  the quotation marks!), followed by the text remembered as <literal>$2</literal>.
6649  This produces an exact copy of the original string, with the middle part
6650  (the <quote>document.referrer</quote>) replaced by <literal>"Not Your
6651  Business!"</literal>.
6652 </para>
6653
6654 <para>
6655  The whole job now reads: Replace <quote>document.referrer</quote> by
6656  <literal>"Not Your Business!"</literal> wherever it appears inside a
6657  &lt;script&gt tag. Note that this job won't break JavaScript syntax,
6658  since both the original and the replacement are syntactically valid
6659  string objects. The script just won't have access to the referrer
6660  information anymore.
6661 </para>
6662
6663 <para>
6664  We'll show you two other jobs from the JavaScript taming department, but
6665  this time only point out the constructs of special interest:
6666 </para>
6667
6668 <para>
6669  <screen>
6670 # The status bar is for displaying link targets, not pointless blahblah
6671 #
6672 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
6673 </para>
6674
6675 <para>
6676  <literal>\s</literal> stands for whitespace characters (space, tab, newline,
6677  carriage return, form feed), so that <literal>\s*</literal> means: <quote>zero
6678  or more whitespace</quote>. The <literal>?</literal> in <literal>.*?</literal>
6679  makes this matching of arbitrary text ungreedy. (Note that the <literal>U</literal>
6680  option is not set). The <literal>['"]</literal> construct means: <quote>a single
6681  <emphasis>or</emphasis> a double quote</quote>. Finally, <literal>\1</literal> is
6682  a back-reference to the first parenthesis just like <literal>$1</literal> above,
6683  with the difference that in the <emphasis>pattern</emphasis>, a backslash indicates
6684  a back-reference, whereas in the <emphasis>substitute</emphasis>, it's the dollar.
6685 </para>
6686
6687 <para>
6688  So what does this job do? It replaces assignments of single- or double-quoted
6689  strings to the <quote>window.status</quote> object with a dummy assignment
6690  (using a variable name that is hopefully odd enough not to conflict with
6691  real variables in scripts). Thus, it catches many cases where e.g. pointless
6692  descriptions are displayed in the status bar instead of the link target when
6693  you move your mouse over links.
6694 </para>
6695
6696 <para>
6697  <screen>
6698 # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
6699 #
6700 s/(&lt;body [^&gt;]*)onunload(.*&gt;)/$1never$2/iU</screen>
6701 </para>
6702
6703 <para>
6704  Including the
6705  <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">OnUnload
6706  event binding</ulink> in the HTML DOM was a <emphasis>CRIME</emphasis>.
6707  When I close a browser window, I want it to close and die. Basta.
6708  This job replaces the <quote>onunload</quote> attribute in
6709  <quote>&lt;body&gt</quote> tags with the dummy word <literal>never</literal>.
6710  Note that the <literal>i</literal> option makes the pattern matching
6711  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
6712  a minimal match: In the first parenthesis, we had to use <literal>[^&gt;]*</literal>
6713  instead of <literal>.*</literal> to prevent the match from exceeding the
6714  &lt;body&gt tag if it doesn't contain <quote>OnUnload</quote>, but the page's
6715  content does.
6716 </para>
6717
6718 <para>
6719  The last example is from the fun department:
6720 </para>
6721
6722 <para>
6723  <screen>
6724 FILTER: fun Fun text replacements
6725
6726 # Spice the daily news:
6727 #
6728 s/microsoft(?!\.com)/MicroSuck/ig</screen>
6729 </para>
6730
6731 <para>
6732  Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
6733  in the job's pattern, which means: Don't match, if the string
6734  <quote>.com</quote> appears directly following <quote>microsoft</quote>
6735  in the page. This prevents links to microsoft.com from being trashed, while
6736  still replacing the word everywhere else.
6737 </para>
6738
6739 <para>
6740  <screen>
6741 # Buzzword Bingo (example for extended regex syntax)
6742 #
6743 s* industry[ -]leading \
6744 |  cutting[ -]edge \
6745 |  customer[ -]focused \
6746 |  market[ -]driven \
6747 |  award[ -]winning # Comments are OK, too! \
6748 |  high[ -]performance \
6749 |  solutions[ -]based \
6750 |  unmatched \
6751 |  unparalleled \
6752 |  unrivalled \
6753 *&lt;font color="red"&gt;&lt;b&gt;BINGO!&lt;/b&gt;&lt;/font&gt; \
6754 *igx</screen>
6755 </para>
6756
6757 <para>
6758  The <literal>x</literal> option in this job turns on extended syntax, and allows for
6759  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting.
6760 </para>
6761
6762 <para>
6763  You get the idea?
6764 </para>
6765 </sect2>
6766
6767 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6768
6769 <sect2 id="predefined-filters"><title>The Pre-defined Filters</title>
6770
6771 <!--
6772
6773  Note each filter is also listed in the +filter action section above. Please
6774  keep these listings in sync.
6775
6776 -->
6777
6778 <para>
6779 The distribution <filename>default.filter</filename> file contains a selection of
6780 pre-defined filters for your convenience:
6781 </para>
6782
6783 <variablelist>
6784  <varlistentry>
6785   <term><emphasis>js-annoyances</emphasis></term>
6786   <listitem>
6787    <para>
6788     The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
6789     To that end, it
6790    <itemizedlist>
6791     <listitem>
6792      <para>
6793       replaces JavaScript references to the browser's referrer information
6794       with the string "Not Your Business!". This compliments the <literal><link
6795       linkend="hide-referrer">hide-referrer</link></literal> action on the content level.
6796      </para>
6797     </listitem>
6798     <listitem>
6799      <para>
6800       removes the bindings to the DOM's
6801       <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">unload
6802       event</ulink> which we feel has no right to exist and is responsible for most <quote>exit consoles</quote>, i.e.
6803       nasty windows that pop up when you close another one.
6804      </para>
6805     </listitem>
6806     <listitem>
6807      <para>
6808       removes code that causes new windows to be opened with undesired properties, such as being
6809       full-screen, non-resizeable, without location, status or menu bar etc.
6810      </para>
6811     </listitem>
6812    </itemizedlist>
6813    </para>
6814    <para>
6815     Use with caution. This is an aggressive filter, and can break sites that
6816     rely heavily on JavaScript.
6817    </para>
6818   </listitem>
6819  </varlistentry>
6820
6821  <varlistentry>
6822   <term><emphasis>js-events</emphasis></term>
6823   <listitem>
6824    <para>
6825     This is a very radical measure. It removes virtually all JavaScript event bindings, which
6826     means that scripts can not react to user actions such as mouse movements or clicks, window
6827     resizing etc, anymore. Use with caution!
6828    </para>
6829    <para>
6830     We <emphasis>strongly discourage</emphasis> using this filter as a default since it breaks
6831     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
6832     need to go there).
6833    </para>
6834   </listitem>
6835  </varlistentry>
6836
6837 <varlistentry>
6838   <term><emphasis>html-annoyances</emphasis></term>
6839   <listitem>
6840    <para>
6841     This filter will undo many common instances of HTML based abuse.
6842    </para>
6843    <para>
6844     The <literal>BLINK</literal> and <literal>MARQUEE</literal> tags
6845     are neutralized (yeah baby!), and browser windows will be created as
6846     resizeable (as of course they should be!), and will have location,
6847     scroll and menu bars -- even if specified otherwise.
6848    </para>
6849   </listitem>
6850  </varlistentry>
6851
6852  <varlistentry>
6853   <term><emphasis>content-cookies</emphasis></term>
6854   <listitem>
6855    <para>
6856     Most cookies are set in the HTTP dialog, where they can be intercepted
6857     by the
6858     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>
6859     and <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>
6860     actions. But web sites increasingly make use of HTML meta tags and JavaScript
6861     to sneak cookies to the browser on the content level.
6862    </para>
6863    <para>
6864     This filter disables most HTML and JavaScript code that reads or sets
6865     cookies. It cannot detect all clever uses of these types of code, so it
6866     should not be relied on as an absolute fix. Use it wherever you would also
6867     use the cookie crunch actions.
6868    </para>
6869   </listitem>
6870  </varlistentry>
6871
6872  <varlistentry>
6873   <term><emphasis>refresh-tags</emphasis></term>
6874   <listitem>
6875    <para>
6876     Disable any refresh tags if the interval is greater than nine seconds (so
6877     that redirections done via refresh tags are not destroyed). This is useful
6878     for dial-on-demand setups, or for those who find this HTML feature
6879     annoying.
6880    </para>
6881   </listitem>
6882  </varlistentry>
6883
6884  <varlistentry>
6885   <term><emphasis>unsolicited-popups</emphasis></term>
6886   <listitem>
6887    <para>
6888     This filter attempts to prevent only <quote>unsolicited</quote> pop-up
6889     windows from opening, yet still allow pop-up windows that the user
6890     has explicitly chosen to open. It was added in version 3.0.1,
6891     as an improvement over earlier such filters.
6892    </para>
6893    <para>
6894     Technical note: The filter works by redefining the window.open JavaScript
6895     function to a dummy function, <literal>PrivoxyWindowOpen()</literal>,
6896     during the loading and rendering phase of each HTML page access, and
6897     restoring the function afterward.
6898    </para>
6899    <para>
6900     This is recommended only for browsers that cannot perform this function
6901     reliably themselves. And be aware that some sites require such windows
6902     in order to function normally. Use with caution.
6903    </para>
6904   </listitem>
6905  </varlistentry>
6906
6907  <varlistentry>
6908   <term><emphasis>all-popups</emphasis></term>
6909   <listitem>
6910    <para>
6911     Attempt to prevent <emphasis>all</emphasis> pop-up windows from opening.
6912     Note this should be used with even more discretion than the above, since
6913     it is more likely to break some sites that require pop-ups for normal
6914     usage. Use with caution.
6915    </para>
6916   </listitem>
6917  </varlistentry>
6918
6919  <varlistentry>
6920   <term><emphasis>img-reorder</emphasis></term>
6921   <listitem>
6922    <para>
6923     This is a helper filter that has no value if used alone. It makes the
6924     <literal>banners-by-size</literal> and <literal>banners-by-link</literal>
6925     (see below) filters more effective and should be enabled together with them.
6926    </para>
6927   </listitem>
6928  </varlistentry>
6929
6930  <varlistentry>
6931   <term><emphasis>banners-by-size</emphasis></term>
6932   <listitem>
6933    <para>
6934     This filter removes image tags purely based on what size they are. Fortunately
6935     for us, many ads and banner images tend to conform to certain standardized
6936     sizes, which makes this filter quite effective for ad stripping purposes.
6937    </para>
6938    <para>
6939     Occasionally this filter will cause false positives on images that are not ads,
6940     but just happen to be of one of the standard banner sizes.
6941    </para>
6942    <para>
6943     Recommended only for those who require extreme ad blocking. The default
6944     block rules should catch 95+% of all ads <emphasis>without</emphasis> this filter enabled.
6945    </para>
6946   </listitem>
6947  </varlistentry>
6948
6949  <varlistentry>
6950   <term><emphasis>banners-by-link</emphasis></term>
6951   <listitem>
6952    <para>
6953     This is an experimental filter that attempts to kill any banners if
6954     their URLs seem to point to known or suspected click trackers. It is currently
6955     not of much value and is not recommended for use by default.
6956    </para>
6957   </listitem>
6958  </varlistentry>
6959
6960  <varlistentry>
6961   <term><emphasis>webbugs</emphasis></term>
6962   <listitem>
6963    <para>
6964     Webbugs are small, invisible images (technically 1X1 GIF images), that
6965     are used to track users across websites, and collect information on them.
6966     As an HTML page is loaded by the browser, an embedded image tag causes the
6967     browser to contact a third-party site, disclosing the tracking information
6968     through the requested URL and/or cookies for that third-party domain, without
6969     the user ever becoming aware of the interaction with the third-party site.
6970     HTML-ized spam also uses a similar technique to verify email addresses.
6971    </para>
6972    <para>
6973     This filter removes the HTML code that loads such <quote>webbugs</quote>.
6974    </para>
6975   </listitem>
6976  </varlistentry>
6977
6978  <varlistentry>
6979   <term><emphasis>tiny-textforms</emphasis></term>
6980   <listitem>
6981    <para>
6982     A rather special-purpose filter that can be used to enlarge textareas (those
6983     multi-line text boxes in web forms) and turn off hard word wrap in them.
6984     It was written for the sourceforge.net tracker system where such boxes are
6985     a nuisance, but it can be handy on other sites, too.
6986    </para>
6987    <para>
6988     It is not recommended to use this filter as a default.
6989    </para>
6990   </listitem>
6991  </varlistentry>
6992
6993  <varlistentry>
6994   <term><emphasis>jumping-windows</emphasis></term>
6995   <listitem>
6996    <para>
6997     Many consider windows that move, or resize themselves to be abusive. This filter
6998     neutralizes the related JavaScript code. Note that some sites might not display
6999     or behave as intended when using this filter. Use with caution.
7000    </para>
7001   </listitem>
7002  </varlistentry>
7003
7004  <varlistentry>
7005   <term><emphasis>frameset-borders</emphasis></term>
7006   <listitem>
7007    <para>
7008     Some web designers seem to assume that everyone in the world will view their
7009     web sites using the same browser brand and version, screen resolution etc,
7010     because only that assumption could explain why they'd use static frame sizes,
7011     yet prevent their frames from being resized by the user, should they be too
7012     small to show their whole content.
7013    </para>
7014    <para>
7015     This filter removes the related HTML code. It should only be applied to sites
7016     which need it.
7017    </para>
7018   </listitem>
7019  </varlistentry>
7020
7021  <varlistentry>
7022   <term><emphasis>demoronizer</emphasis></term>
7023   <listitem>
7024    <para>
7025     Many Microsoft products that generate HTML use non-standard extensions (read:
7026     violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
7027     HTML documents to display with errors on standard-compliant platforms.
7028    </para>
7029    <para>
7030     This filter translates the MS-only characters into Latin-1 equivalents.
7031     It is not necessary when using MS products, and will cause corruption of
7032     all documents that use 8-bit character sets other than Latin-1. It's mostly
7033     worthwhile for Europeans on non-MS platforms, if weird garbage characters
7034     sometimes appear on some pages, or user agents that don't correct for this on
7035     the fly.
7036 <!--
7037     My version of Mozilla (ancient) shows litte square boxes for quote
7038     characters, and apostrophes on moronized pages. So many pages have this, I
7039     can read them fine now. HB 08/27/06
7040 -->
7041    </para>
7042   </listitem>
7043  </varlistentry>
7044
7045  <varlistentry>
7046   <term><emphasis>shockwave-flash</emphasis></term>
7047   <listitem>
7048    <para>
7049     A filter for shockwave haters. As the name suggests, this filter strips code
7050     out of web pages that is used to embed shockwave flash objects.
7051    </para>
7052    <para>
7053    </para>
7054   </listitem>
7055  </varlistentry>
7056
7057  <varlistentry>
7058   <term><emphasis>quicktime-kioskmode</emphasis></term>
7059   <listitem>
7060    <para>
7061     Change HTML code that embeds Quicktime objects so that kioskmode, which
7062     prevents saving, is disabled.
7063    </para>
7064   </listitem>
7065  </varlistentry>
7066
7067  <varlistentry>
7068   <term><emphasis>fun</emphasis></term>
7069   <listitem>
7070    <para>
7071     Text replacements for subversive browsing fun. Make fun of your favorite
7072     Monopolist or play buzzword bingo.
7073    </para>
7074   </listitem>
7075  </varlistentry>
7076
7077  <varlistentry>
7078   <term><emphasis>crude-parental</emphasis></term>
7079   <listitem>
7080    <para>
7081     A demonstration-only filter that shows how <application>Privoxy</application>
7082     can be used to delete web content on a keyword basis.
7083    </para>
7084   </listitem>
7085  </varlistentry>
7086
7087  <varlistentry>
7088   <term><emphasis>ie-exploits</emphasis></term>
7089   <listitem>
7090    <para>
7091     An experimental collection of text replacements to disable malicious HTML and JavaScript
7092     code that exploits known security holes in Internet Explorer.
7093    </para>
7094    <para>
7095     Presently, it only protects against Nimda and a cross-site scripting bug, and
7096     would need active maintenance to provide more substantial protection.
7097    </para>
7098   </listitem>
7099  </varlistentry>
7100
7101  <varlistentry>
7102   <term><emphasis>site-specifics</emphasis></term>
7103   <listitem>
7104    <para>
7105     Some web sites have very specific problems, the cure for which doesn't apply
7106     anywhere else, or could even cause damage on other sites.
7107    </para>
7108    <para>
7109     This is a collection of such site-specific cures which should only be applied
7110     to the sites they were intended for, which is what the supplied
7111     <filename>default.action</filename> file does. Users shouldn't need to change
7112     anything regarding this filter.
7113    </para>
7114   </listitem>
7115  </varlistentry>
7116
7117  <varlistentry>
7118   <term><emphasis>google</emphasis></term>
7119   <listitem>
7120    <para>
7121     A CSS based block for Google text ads. Also removes a width limitation
7122     and the toolbar advertisement.
7123    </para>
7124   </listitem>
7125  </varlistentry>
7126
7127   <varlistentry>
7128   <term><emphasis>yahoo</emphasis></term>
7129   <listitem>
7130    <para>
7131     Another CSS based block, this time for Yahoo text ads. And removes
7132     a width limitation as well.
7133    </para>
7134   </listitem>
7135  </varlistentry>
7136
7137   <varlistentry>
7138   <term><emphasis>msn</emphasis></term>
7139   <listitem>
7140    <para>
7141     Another CSS based block, this time for MSN text ads. And removes
7142     tracking URLs, as well as a width limitation.
7143    </para>
7144   </listitem>
7145  </varlistentry>
7146
7147  <varlistentry>
7148   <term><emphasis>blogspot</emphasis></term>
7149   <listitem>
7150    <para>
7151     Cleans up some Blogspot blogs. Read the fine print before using this one!
7152    </para>
7153    <para>
7154     This filter also intentionally removes some navigation stuff and sets the
7155     page width to 100%. As a result, some rounded <quote>corners</quote> would
7156     appear to early or not at all and as fixing this would require a browser
7157     that understands background-size (CSS3), they are removed instead.
7158    </para>
7159   </listitem>
7160  </varlistentry>
7161
7162   <varlistentry>
7163   <term><emphasis>xml-to-html</emphasis></term>
7164   <listitem>
7165    <para>
7166     Server-header filter to change the Content-Type from xml to html.
7167    </para>
7168   </listitem>
7169  </varlistentry>
7170
7171   <varlistentry>
7172   <term><emphasis>html-to-xml</emphasis></term>
7173   <listitem>
7174    <para>
7175     Server-header filter to change the Content-Type from html to xml.
7176    </para>
7177   </listitem>
7178  </varlistentry>
7179
7180   <varlistentry>
7181   <term><emphasis>no-ping</emphasis></term>
7182   <listitem>
7183    <para>
7184     Removes the non-standard <literal>ping</literal> attribute from
7185     anchor and area HTML tags.
7186    </para>
7187   </listitem>
7188  </varlistentry>
7189
7190   <varlistentry>
7191   <term><emphasis>hide-tor-exit-notation</emphasis></term>
7192   <listitem>
7193    <para>
7194     Client-header filter to remove the <command>Tor</command> exit node notation
7195     found in Host and Referer headers.
7196    </para>
7197    <para>
7198     If &my-app; and <command>Tor</command> are chained and &my-app;
7199     is configured to use socks4a, one can use <quote>http://www.example.org.foobar.exit/</quote>
7200     to access the host <quote>www.example.org</quote> through the
7201     <command>Tor</command> exit node <quote>foobar</quote>.
7202    </para>
7203    <para>
7204     As the HTTP client isn't aware of this notation, it treats the
7205     whole string <quote>www.example.org.foobar.exit</quote> as host and uses it
7206     for the <quote>Host</quote> and <quote>Referer</quote> headers. From the
7207     server's point of view the resulting headers are invalid and can cause problems.
7208    </para>
7209    <para>
7210     An invalid <quote>Referer</quote> header can trigger <quote>hot-linking</quote>
7211     protections, an invalid <quote>Host</quote> header will make it impossible for
7212     the server to find the right vhost (several domains hosted on the same IP address).
7213    </para>
7214    <para>
7215     This client-header filter removes the <quote>foo.exit</quote> part in those headers
7216     to prevent the mentioned problems. Note that it only modifies
7217     the HTTP headers, it doesn't make it impossible for the server
7218     to detect your <command>Tor</command> exit node based on the IP address
7219     the request is coming from.
7220    </para>
7221   </listitem>
7222  </varlistentry>
7223
7224 <!--
7225  <varlistentry>
7226   <term><emphasis> </emphasis></term>
7227   <listitem>
7228    <para>
7229    </para>
7230    <para>
7231    </para>
7232   </listitem>
7233  </varlistentry>
7234 -->
7235 </variablelist>
7236
7237 </sect2>
7238 </sect1>
7239
7240 <!--  ~  End section  ~  -->
7241
7242
7243
7244 <!--   ~~~~~       New section      ~~~~~     -->
7245
7246 <sect1 id="templates">
7247 <title>Privoxy's Template Files</title>
7248 <para>
7249  All <application>Privoxy</application> built-in pages, i.e. error pages such as the
7250  <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
7251  error page</ulink>, the <ulink
7252  url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
7253  page</ulink>
7254  and all pages of its <ulink url="http://config.privoxy.org/">web-based
7255  user interface</ulink>, are generated from <emphasis>templates</emphasis>.
7256  (<application>Privoxy</application> must be running for the above links to work as
7257  intended.)
7258 </para>
7259
7260 <para>
7261  These templates are stored in a subdirectory of the <link linkend="confdir">configuration
7262  directory</link> called <filename>templates</filename>. On Unixish platforms,
7263  this is typically
7264  <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
7265 </para>
7266
7267 <para>
7268  The templates are basically normal HTML files, but with place-holders (called symbols
7269  or exports), which <application>Privoxy</application> fills at run time. It
7270  is possible to edit the templates with a normal text editor, should you want
7271  to customize them. (<emphasis>Not recommended for the casual
7272  user</emphasis>). Should you create your own custom templates, you should use
7273  the <filename>config</filename> setting <link linkend="templdir">templdir</link>
7274  to specify an alternate location, so your templates do not get overwritten
7275  during upgrades.
7276  </para>
7277  <para>
7278  Note that just like in configuration files, lines starting
7279  with <literal>#</literal> are ignored when the templates are filled in.
7280 </para>
7281
7282 <para>
7283  The place-holders are of the form <literal>@name@</literal>, and you will
7284  find a list of available symbols, which vary from template to template,
7285  in the comments at the start of each file. Note that these comments are not
7286  always accurate, and that it's probably best to look at the existing HTML
7287  code to find out which symbols are supported and what they are filled in with.
7288 </para>
7289
7290 <para>
7291  A special application of this substitution mechanism is to make whole
7292  blocks of HTML code disappear when a specific symbol is set. We use this
7293  for many purposes, one of them being to include the beta warning in all
7294  our user interface (CGI) pages when <application>Privoxy</application>
7295  is in an alpha or beta development stage:
7296 </para>
7297
7298 <para>
7299  <screen>
7300 &lt;!-- @if-unstable-start --&gt;
7301
7302   ... beta warning HTML code goes here ...
7303
7304 &lt;!-- if-unstable-end@ --&gt;</screen>
7305 </para>
7306
7307 <para>
7308  If the "unstable" symbol is set, everything in between and including
7309  <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
7310  will disappear, leaving nothing but an empty comment:
7311 </para>
7312
7313 <para>
7314  <screen>&lt;!--  --&gt;</screen>
7315 </para>
7316
7317 <para>
7318  There's also an if-then-else construct and an <literal>#include</literal>
7319  mechanism, but you'll sure find out if you are inclined to edit the
7320  templates ;-)
7321 </para>
7322
7323 <para>
7324  All templates refer to a style located at
7325  <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
7326  This is, of course, locally served by <application>Privoxy</application>
7327  and the source for it can be found and edited in the
7328  <filename>cgi-style.css</filename> template.
7329 </para>
7330
7331 </sect1>
7332
7333 <!--  ~  End section  ~  -->
7334
7335
7336
7337 <!--   ~~~~~       New section      ~~~~~     -->
7338
7339 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
7340 Requests</title>
7341
7342 <!-- Include contacting.sgml boilerplate: -->
7343  &contacting;
7344 <!-- end boilerplate -->
7345
7346 </sect1>
7347
7348 <!--  ~  End section  ~  -->
7349
7350
7351 <!--   ~~~~~       New section      ~~~~~     -->
7352 <sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
7353
7354 <!-- Include copyright.sgml: -->
7355  &copyright;
7356 <!-- end copyright -->
7357
7358 <para>
7359  <application>Privoxy</application> is free software; you can
7360  redistribute it and/or modify it under the terms of the
7361  <citetitle>GNU General Public License</citetitle>, version 2,
7362  as published by the Free Software Foundation and included in
7363  the next section.
7364 </para>
7365
7366 <!--   ~~~~~       New section      ~~~~~     -->
7367 <sect2 id="license"><title>License</title>
7368 <para>
7369  <screen><![ RCDATA [ &GPLv2; ]]></screen>
7370 </para>
7371
7372 </sect2>
7373 <!--  ~  End section  ~  -->
7374
7375
7376 <!--   ~~~~~       New section      ~~~~~     -->
7377
7378 <sect2 id="history"><title>History</title>
7379 <!-- Include history.sgml: -->
7380  &history;
7381 <!-- end history -->
7382 </sect2>
7383
7384 <sect2 id="authors"><title>Authors</title>
7385 <!-- Include p-authors.sgml: -->
7386  &p-authors;
7387 <!-- end authors -->
7388 </sect2>
7389
7390 </sect1>
7391
7392 <!--  ~  End section  ~  -->
7393
7394
7395 <!--   ~~~~~       New section      ~~~~~     -->
7396 <sect1 id="seealso"><title>See Also</title>
7397 <!-- Include seealso.sgml: -->
7398  &seealso;
7399 <!-- end seealso -->
7400 </sect1>
7401
7402
7403
7404 <!--   ~~~~~       New section      ~~~~~     -->
7405 <sect1 id="appendix"><title>Appendix</title>
7406
7407
7408 <!--   ~~~~~       New section      ~~~~~     -->
7409 <sect2 id="regex">
7410 <title>Regular Expressions</title>
7411 <para>
7412  <application>Privoxy</application> uses Perl-style <quote>regular
7413  expressions</quote> in its <link linkend="actions-file">actions
7414  files</link> and <link linkend="filter-file">filter file</link>,
7415  through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
7416 <!--
7417  dead 08/27/06
7418  <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
7419 -->
7420  <application>PCRS</application> libraries.
7421 </para>
7422
7423 <para>
7424  If you are reading this, you probably don't understand what <quote>regular
7425  expressions</quote> are, or what they can do. So this will be a very brief
7426  introduction only. A full explanation would require a <ulink
7427  url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
7428 </para>
7429
7430 <para>
7431  Regular expressions provide a language to describe patterns that can be
7432  run against strings of characters (letter, numbers, etc), to see if they
7433  match the string or not. The  patterns are themselves (sometimes complex)
7434  strings of literal characters, combined with  wild-cards, and other special
7435  characters, called meta-characters. The <quote>meta-characters</quote> have
7436  special meanings and are used to build complex patterns to be matched against.
7437  Perl Compatible Regular Expressions are an especially convenient
7438  <quote>dialect</quote> of the regular expression language.
7439 </para>
7440
7441 <para>
7442  To make a simple analogy, we do something similar when we use wild-card
7443  characters when listing files with the <command>dir</command> command in DOS.
7444  <literal>*.*</literal> matches all filenames. The <quote>special</quote>
7445  character here is the asterisk which matches any and all characters. We can be
7446  more specific and use <literal>?</literal> to match just individual
7447  characters. So <quote>dir file?.text</quote> would match
7448  <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
7449  matching, using a similar technique to <quote>regular expressions</quote>!
7450 </para>
7451
7452 <para>
7453  Regular expressions do essentially the same thing, but are much, much more
7454  powerful. There are many more <quote>special characters</quote> and ways of
7455  building complex patterns however. Let's look at a few of the common ones,
7456  and then some examples:
7457 </para>
7458
7459 <para><simplelist>
7460  <member>
7461   <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
7462   <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
7463  </member>
7464 </simplelist></para>
7465
7466 <para><simplelist>
7467  <member>
7468   <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
7469   times. Either/or.
7470  </member>
7471 </simplelist></para>
7472
7473 <para><simplelist>
7474  <member>
7475   <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
7476   times.
7477  </member>
7478 </simplelist></para>
7479
7480 <para><simplelist>
7481  <member>
7482   <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
7483   times.
7484  </member>
7485 </simplelist></para>
7486
7487 <para><simplelist>
7488  <member>
7489   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
7490   the following character should be taken literally. This is used where one of the
7491   special characters (e.g. <quote>.</quote>) needs to be taken literally and
7492   not as a special meta-character. Example: <quote>example\.com</quote>, makes
7493   sure the period is recognized only as a period (and not expanded to its
7494   meta-character meaning of any single character).
7495  </member>
7496 </simplelist></para>
7497
7498 <para><simplelist>
7499  <member>
7500   <emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
7501   any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
7502   matches any numeric digit (zero through nine). As an example, we can combine
7503   this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
7504  </member>
7505 </simplelist></para>
7506
7507 <para><simplelist>
7508  <member>
7509   <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
7510   or multiple sub-expressions.
7511  </member>
7512 </simplelist></para>
7513
7514 <para><simplelist>
7515  <member>
7516   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
7517   <quote>or</quote> conditional statement. A match is successful if the
7518   sub-expression on either side of <quote>|</quote> matches. As an example:
7519   <quote>/(this|that) example/</quote> uses grouping and the bar character
7520   and would match either <quote>this example</quote> or <quote>that
7521   example</quote>, and nothing else.
7522  </member>
7523 </simplelist></para>
7524
7525 <para>
7526  These are just some of the ones you are likely to use when matching URLs with
7527  <application>Privoxy</application>, and is a long way from a definitive
7528  list. This is enough to get us started with a few simple examples which may
7529  be more illuminating:
7530 </para>
7531
7532 <para>
7533  <emphasis><literal>/.*/banners/.*</literal></emphasis> - A  simple example
7534  that uses the common combination of <quote>.</quote> and <quote>*</quote> to
7535  denote any character, zero or more times. In other words, any string at all.
7536  So we start with a literal forward slash, then our regular expression pattern
7537  (<quote>.*</quote>) another literal forward slash, the string
7538  <quote>banners</quote>, another forward slash, and lastly another
7539  <quote>.*</quote>. We are building
7540  a directory path here. This will match any file with the path that has a
7541  directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
7542  any characters, and this could conceivably be more forward slashes, so it
7543  might expand into a much longer looking path. For example, this could match:
7544  <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
7545  <quote>/banners/annoying.html</quote>, or almost an infinite number of other
7546  possible combinations, just so it has <quote>banners</quote> in the path
7547  somewhere.
7548 </para>
7549
7550 <para>
7551  And now something a little more complex:
7552 </para>
7553
7554 <para>
7555  <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
7556  We have several literal forward slashes again (<quote>/</quote>), so we are
7557  building another expression that is a file path statement. We have another
7558  <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
7559  it matches our expression. The only true literal that <emphasis>must
7560  match</emphasis> our pattern is <application>adv</application>, together with
7561  the forward slashes. What comes after the <quote>adv</quote> string is the
7562  interesting part.
7563 </para>
7564
7565 <para>
7566  Remember the <quote>?</quote> means the preceding expression (either a
7567  literal character or anything grouped with <quote>(...)</quote> in this case)
7568  can exist or not, since this means either zero or one match. So
7569  <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
7570  individual sub-expressions: <quote>(er)</quote>,
7571  <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
7572  means <quote>or</quote>. We have two of those. For instance,
7573  <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
7574  <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
7575  attempt at matching as many variations of <quote>advertisement</quote>, and
7576  similar, as possible. So this would expand to match just <quote>adv</quote>,
7577  or <quote>advert</quote>, or <quote>adverts</quote>, or
7578  <quote>advertising</quote>, or <quote>advertisement</quote>, or
7579  <quote>advertisements</quote>. You get the idea. But it would not match
7580  <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
7581  changing our regular expression to:
7582  <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
7583  either spelling.
7584 </para>
7585
7586 <para>
7587  <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
7588  another path statement with forward slashes. Anything in the square brackets
7589  <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
7590  shorthand expression to mean any digit one through nine. It is the same as
7591  saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
7592  means one or more of the preceding expression must be included. The preceding
7593  expression here is what is in the square brackets -- in this case, any digit
7594  one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
7595  This includes a <quote>|</quote>, so this needs to match the expression on
7596  either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
7597  side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
7598  since the <quote>?</quote> means the letter <quote>e</quote> is optional and
7599  can be matched once or not at all. So we are building an expression here to
7600  match image GIF or JPEG type image file. It must include the literal
7601  string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
7602  (which is now a literal, and not a special character, since it is escaped
7603  with <quote>\</quote>), and lastly either <quote>gif</quote>, or
7604  <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
7605  include: <quote>//advert1.jpg</quote>,
7606  <quote>/nasty/ads/advert1234.gif</quote>,
7607  <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
7608  <quote>advert1.gif</quote> (no leading slash), or
7609  <quote>/adverts232.jpg</quote> (the expression does not include an
7610  <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
7611  in the expression anywhere).
7612 </para>
7613
7614 <para>
7615  We are barely scratching the surface of regular expressions here so that you
7616  can understand the default <application>Privoxy</application>
7617  configuration files, and maybe use this knowledge to customize your own
7618  installation. There is much, much more that can be done with regular
7619  expressions. Now that you know enough to get started, you can learn more on
7620  your own :/
7621 </para>
7622
7623 <para>
7624  More reading on Perl Compatible Regular expressions:
7625  <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
7626 </para>
7627
7628 <para>
7629  For information on regular expression based substitutions and their applications
7630  in filters, please see the <link linkend="filter-file">filter file tutorial</link>
7631  in this manual.
7632 </para>
7633 </sect2>
7634
7635 <!--  ~  End section  ~  -->
7636
7637
7638 <!--   ~~~~~       New section      ~~~~~     -->
7639 <sect2>
7640 <title>Privoxy's Internal Pages</title>
7641
7642 <para>
7643  Since <application>Privoxy</application> proxies each requested
7644  web page, it is easy for <application>Privoxy</application> to
7645  trap certain special URLs. In this way, we can talk directly to
7646  <application>Privoxy</application>, and see how it is
7647  configured, see how our rules are being applied, change these
7648  rules and other configuration options, and even turn
7649  <application>Privoxy's</application> filtering off, all with
7650  a web browser.
7651
7652 </para>
7653
7654 <para>
7655  The URLs listed below are the special ones that allow direct access
7656  to <application>Privoxy</application>. Of course,
7657  <application>Privoxy</application> must be running to access these. If
7658  not, you will get a friendly error message. Internet access is not
7659  necessary either.
7660 </para>
7661
7662 <para>
7663  <itemizedlist>
7664
7665  <listitem>
7666   <para>
7667    Privoxy main page:
7668   </para>
7669   <blockquote>
7670    <para>
7671      <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
7672    </para>
7673   </blockquote>
7674   <para>
7675    There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
7676    doesn't provide a fall-back to a real page, in case the request is not
7677    sent through <application>Privoxy</application>)
7678   </para>
7679  </listitem>
7680
7681  <listitem>
7682   <para>
7683     Show information about the current configuration, including viewing and
7684     editing of actions files:
7685   </para>
7686    <blockquote>
7687    <para>
7688     <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
7689    </para>
7690   </blockquote>
7691  </listitem>
7692
7693  <listitem>
7694   <para>
7695     Show the source code version numbers:
7696   </para>
7697   <blockquote>
7698    <para>
7699     <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
7700    </para>
7701   </blockquote>
7702  </listitem>
7703
7704  <listitem>
7705   <para>
7706    Show the browser's request headers:
7707   </para>
7708   <blockquote>
7709    <para>
7710     <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
7711    </para>
7712   </blockquote>
7713  </listitem>
7714
7715  <listitem>
7716   <para>
7717    Show which actions apply to a URL and why:
7718   </para>
7719    <blockquote>
7720    <para>
7721     <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
7722    </para>
7723   </blockquote>
7724  </listitem>
7725
7726  <listitem>
7727   <para>
7728    Toggle Privoxy on or off. This feature can be turned off/on in the main
7729    <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
7730    continues to run, but only as a pass-through proxy, with no actions taking
7731    place:
7732   </para>
7733    <blockquote>
7734    <para>
7735     <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
7736    </para>
7737   </blockquote>
7738   <para>
7739    Short cuts. Turn off, then on:
7740   </para>
7741    <blockquote>
7742    <para>
7743      <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
7744    </para>
7745   </blockquote>
7746    <blockquote>
7747    <para>
7748      <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
7749    </para>
7750   </blockquote>
7751  </listitem>
7752
7753  </itemizedlist>
7754 </para>
7755
7756 <para>
7757  These may be bookmarked for quick reference. See next.
7758
7759 </para>
7760
7761 <sect3 id="bookmarklets">
7762 <title>Bookmarklets</title>
7763 <para>
7764  Below are some <quote>bookmarklets</quote> to allow you to easily access a
7765  <quote>mini</quote> version of some of <application>Privoxy's</application>
7766  special pages. They are designed for MS Internet Explorer, but should work
7767  equally well in Netscape, Mozilla, and other browsers which support
7768  JavaScript. They are designed to run directly from your bookmarks - not by
7769  clicking the links below (although that should work for testing).
7770 </para>
7771 <para>
7772  To save them, right-click the link and choose <quote>Add to Favorites</quote>
7773  (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
7774  the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
7775  Bookmarklet directly from your favorites/bookmarks. For even faster access,
7776  you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
7777  Toolbar</quote> (Netscape), and run them with a single click.
7778 </para>
7779
7780 <para>
7781  <itemizedlist>
7782
7783   <listitem>
7784    <para>
7785     <ulink
7786     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
7787    </para>
7788   </listitem>
7789
7790   <listitem>
7791    <para>
7792     <ulink
7793     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
7794    </para>
7795   </listitem>
7796
7797   <listitem>
7798    <para>
7799     <ulink
7800     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
7801    </para>
7802   </listitem>
7803
7804   <listitem>
7805    <para>
7806     <ulink
7807     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
7808    </para>
7809   </listitem>
7810 <!--
7811   <listitem>
7812    <para>
7813     <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
7814    </para>
7815   </listitem>
7816  -->
7817   <listitem>
7818    <para>
7819     <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
7820    </para>
7821   </listitem>
7822  </itemizedlist>
7823 </para>
7824
7825 <para>
7826  Credit: The site which gave us the general idea for these bookmarklets is
7827  <ulink url="http://www.bookmarklets.com/">www.bookmarklets.com</ulink>. They
7828  have more information about bookmarklets.
7829 </para>
7830
7831
7832 </sect3>
7833
7834 </sect2>
7835
7836
7837 <!--   ~~~~~       New section      ~~~~~     -->
7838 <sect2 id="chain">
7839 <title>Chain of Events</title>
7840 <para>
7841  Let's take a quick look at how some of <application>Privoxy's</application>
7842  core features are triggered, and the ensuing sequence of events when a web
7843  page is requested by your browser:
7844 </para>
7845
7846 <para>
7847  <itemizedlist>
7848  <listitem>
7849   <para>
7850    First, your web browser requests a web page. The browser knows to send
7851    the request to <application>Privoxy</application>, which will in turn,
7852    relay the request to the remote web server after passing the following
7853    tests:
7854   </para>
7855  </listitem>
7856  <listitem>
7857   <para>
7858    <application>Privoxy</application> traps any request for its own internal CGI
7859    pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
7860   </para>
7861  </listitem>
7862  <listitem>
7863   <para>
7864    Next, <application>Privoxy</application> checks to see if the URL
7865    matches any <link
7866    linkend="BLOCK"><quote>+block</quote></link> patterns. If
7867    so, the URL is then blocked, and the remote web server will not be contacted.
7868    <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
7869    and
7870    <link linkend="HANDLE-AS-EMPTY-DOCUMENT"><quote>+handle-as-empty-document</quote></link>
7871    are then checked, and if there is no match, an
7872    HTML <quote>BLOCKED</quote> page is sent back to the browser. Otherwise, if
7873    it does match, an image is returned for the former, and an empty text
7874    document for the latter. The type of image would depend on the setting of
7875    <link linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
7876    (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
7877   </para>
7878  </listitem>
7879  <listitem>
7880   <para>
7881    Untrusted URLs are blocked. If URLs are being added to the
7882    <filename>trust</filename> file, then that is done.
7883   </para>
7884  </listitem>
7885  <listitem>
7886   <para>
7887    If the URL pattern matches the <link
7888    linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
7889    it is then processed. Unwanted parts of the requested URL are stripped.
7890   </para>
7891  </listitem>
7892  <listitem>
7893   <para>
7894    Now the rest of the client browser's request headers are processed. If any
7895    of these match any of the relevant actions (e.g. <link
7896    linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
7897    etc.), headers are suppressed or forged as determined by these actions and
7898    their parameters.
7899   </para>
7900  </listitem>
7901  <listitem>
7902   <para>
7903    Now the web server starts sending its response back (i.e. typically a web
7904    page).
7905   </para>
7906  </listitem>
7907  <listitem>
7908   <para>
7909    First, the server headers are read and processed to determine, among other
7910    things, the MIME type (document type) and encoding. The headers are then
7911    filtered as determined by the
7912    <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
7913    <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
7914    and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
7915    actions.
7916   </para>
7917  </listitem>
7918  <listitem>
7919   <para>
7920    If any <link linkend="FILTER"><quote>+filter</quote></link> action
7921    or <link
7922    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
7923    action applies (and the document type fits the action), the rest of the page is
7924    read into memory (up to a configurable limit). Then the filter rules (from
7925    <filename>default.filter</filename> and any other filter files) are
7926    processed against the buffered content. Filters are applied in the order
7927    they are specified in one of the filter files. Animated GIFs, if present,
7928    are reduced to either the first or last frame, depending on the action
7929    setting.The entire page, which is now filtered, is then sent by
7930    <application>Privoxy</application> back to your browser.
7931   </para>
7932   <para>
7933    If neither a <link linkend="FILTER"><quote>+filter</quote></link> action
7934    or <link
7935    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
7936    matches, then <application>Privoxy</application> passes the raw data through
7937    to the client browser as it becomes available.
7938   </para>
7939  </listitem>
7940  <listitem>
7941   <para>
7942    As the browser receives the now (possibly filtered) page content, it
7943    reads and then requests any URLs that may be embedded within the page
7944    source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
7945    frames), sounds, etc. For each of these objects, the browser issues a
7946    separate request (this is easily viewable in <application>Privoxy's</application>
7947    logs). And each such request is in turn processed just as above. Note that a
7948    complex web page will have many, many such embedded URLs. If these
7949    secondary requests are to a different server, then quite possibly a very
7950    differing set of actions is triggered.
7951   </para>
7952  </listitem>
7953
7954  </itemizedlist>
7955 </para>
7956 <para>
7957  NOTE: This is somewhat of a simplistic overview of what happens with each URL
7958  request. For the sake of brevity and simplicity, we have focused on
7959  <application>Privoxy's</application> core features only.
7960 </para>
7961
7962 </sect2>
7963
7964
7965 <!--   ~~~~~       New section      ~~~~~     -->
7966 <sect2 id="actionsanat">
7967 <title>Troubleshooting: Anatomy of an Action</title>
7968
7969 <para>
7970  The way <application>Privoxy</application> applies
7971  <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
7972  to any given URL can be complex, and not always so
7973  easy to understand what is happening. And sometimes we need to be able to
7974  <emphasis>see</emphasis> just what <application>Privoxy</application> is
7975  doing. Especially, if something <application>Privoxy</application> is doing
7976  is causing us a problem inadvertently. It can be a little daunting to look at
7977  the actions and filters files themselves, since they tend to be filled with
7978  <link linkend="regex">regular expressions</link> whose consequences are not
7979  always so obvious.
7980 </para>
7981
7982 <para>
7983  One quick test to see if <application>Privoxy</application> is causing a problem
7984  or not, is to disable it temporarily. This should be the first troubleshooting
7985  step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
7986  and easy way to do this (be sure to flush caches afterward!). Looking at the
7987  logs is a good idea too. (Note that both the toggle feature and logging are
7988  enabled via <filename>config</filename> file settings, and may need to be
7989  turned <quote>on</quote>.)
7990 </para>
7991 <para>
7992  Another easy troubleshooting step to try is if you have done any
7993  customization of your installation, revert back to the installed
7994  defaults and see if that helps. There are times the developers get complaints
7995  about one thing or another, and the problem is more related to a customized
7996  configuration issue.
7997 </para>
7998
7999 <para>
8000  <application>Privoxy</application> also provides the
8001  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
8002  page that can show us very specifically how <application>actions</application>
8003  are being applied to any given URL. This is a big help for troubleshooting.
8004 </para>
8005
8006 <para>
8007  First, enter one URL (or partial URL) at the prompt, and then
8008  <application>Privoxy</application> will tell us
8009  how the current configuration will handle it. This will not
8010  help with filtering effects (i.e. the <link
8011  linkend="FILTER"><quote>+filter</quote></link> action) from
8012  one of the filter files since this is handled very
8013  differently and not so easy to trap! It also will not tell you about any other
8014  URLs that may be embedded within the URL you are testing. For instance, images
8015  such as ads are expressed as URLs within the raw page source of HTML pages. So
8016  you will only get info for the actual URL that is pasted into the prompt area
8017  -- not any sub-URLs. If you want to know about embedded URLs like ads, you
8018  will have to dig those out of the HTML source. Use your browser's <quote>View
8019  Page Source</quote> option for this. Or right click on the ad, and grab the
8020  URL.
8021 </para>
8022
8023 <para>
8024  Let's try an example, <ulink url="http://google.com">google.com</ulink>,
8025  and look at it one section at a time in a sample configuration (your real
8026  configuration may vary):
8027 </para>
8028
8029 <para>
8030  <screen>
8031  Matches for http://www.google.com:
8032
8033  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8034
8035  {+change-x-forwarded-for{block}
8036  +deanimate-gifs {last}
8037  +fast-redirects {check-decoded-url}
8038  +filter {refresh-tags}
8039  +filter {img-reorder}
8040  +filter {banners-by-size}
8041  +filter {webbugs}
8042  +filter {jumping-windows}
8043  +filter {ie-exploits}
8044  +hide-from-header {block}
8045  +hide-referrer {forge}
8046  +session-cookies-only
8047  +set-image-blocker {pattern}
8048 /
8049
8050  { -session-cookies-only }
8051  .google.com
8052
8053  { -fast-redirects }
8054  .google.com
8055
8056 In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8057 (no matches in this file)
8058 </screen>
8059 </para>
8060
8061 <para>
8062  This is telling us how we have defined our
8063  <link linkend="ACTIONS"><quote>actions</quote></link>, and
8064  which ones match for our test case, <quote>google.com</quote>.
8065  Displayed is all the actions that are available to us. Remember,
8066  the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
8067  denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
8068  are <quote>off</quote>. Each example we try may provide a slightly different
8069  end result, depending on our configuration directives.
8070 </para>
8071 <para>
8072  The first listing
8073   is for our <filename>default.action</filename> file. The large, multi-line
8074   listing, is how the actions are set to match for all URLs, i.e. our default
8075   settings. If you look at your <quote>actions</quote> file, this would be the
8076   section just below the <quote>aliases</quote> section near the top. This
8077   will apply to all URLs as signified by the single forward slash at the end
8078   of the listing -- <quote> / </quote>.
8079 </para>
8080
8081 <para>
8082  But we have defined additional actions that would be exceptions to these general
8083  rules, and then we list specific URLs (or patterns) that these exceptions
8084  would apply to. Last match wins. Just below this then are two explicit
8085  matches for <quote>.google.com</quote>. The first is negating our previous
8086  cookie setting, which was for <link
8087  linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
8088  (i.e. not persistent). So we will allow persistent cookies for google, at
8089  least that is how it is in this example. The second turns
8090  <emphasis>off</emphasis> any <link
8091  linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
8092  action, allowing this to take place unmolested. Note that there is a leading
8093  dot here -- <quote>.google.com</quote>. This will match any hosts and
8094  sub-domains, in the google.com domain also, such as
8095  <quote>www.google.com</quote> or <quote>mail.google.com</quote>. But it would not
8096  match <quote>www.google.de</quote>! So, apparently, we have these two actions
8097  defined as exceptions to the general rules at the top somewhere in the lower
8098  part of our <filename>default.action</filename> file, and
8099  <quote>google.com</quote> is referenced somewhere in these latter sections.
8100 </para>
8101
8102 <para>
8103  Then, for our <filename>user.action</filename> file, we again have no hits.
8104  So there is nothing google-specific that we might have added to our own, local
8105  configuration. If there was, those actions would over-rule any actions from
8106  previously processed files, such as <filename>default.action</filename>.
8107  <filename>user.action</filename> typically has the last word. This is the
8108  best place to put hard and fast exceptions,
8109 </para>
8110
8111 <para>
8112  And finally we pull it all together in the bottom section and summarize how
8113  <application>Privoxy</application> is applying all its <quote>actions</quote>
8114  to <quote>google.com</quote>:
8115
8116 </para>
8117
8118 <para>
8119  <screen>
8120
8121  Final results:
8122
8123  -add-header
8124  -block
8125  +change-x-forwarded-for{block}
8126  -client-header-filter{hide-tor-exit-notation}
8127  -content-type-overwrite
8128  -crunch-client-header
8129  -crunch-if-none-match
8130  -crunch-incoming-cookies
8131  -crunch-outgoing-cookies
8132  -crunch-server-header
8133  +deanimate-gifs {last}
8134  -downgrade-http-version
8135  -fast-redirects
8136  -filter {js-events}
8137  -filter {content-cookies}
8138  -filter {all-popups}
8139  -filter {banners-by-link}
8140  -filter {tiny-textforms}
8141  -filter {frameset-borders}
8142  -filter {demoronizer}
8143  -filter {shockwave-flash}
8144  -filter {quicktime-kioskmode}
8145  -filter {fun}
8146  -filter {crude-parental}
8147  -filter {site-specifics}
8148  -filter {js-annoyances}
8149  -filter {html-annoyances}
8150  +filter {refresh-tags}
8151  -filter {unsolicited-popups}
8152  +filter {img-reorder}
8153  +filter {banners-by-size}
8154  +filter {webbugs}
8155  +filter {jumping-windows}
8156  +filter {ie-exploits}
8157  -filter {google}
8158  -filter {yahoo}
8159  -filter {msn}
8160  -filter {blogspot}
8161  -filter {no-ping}
8162  -force-text-mode
8163  -handle-as-empty-document
8164  -handle-as-image
8165  -hide-accept-language
8166  -hide-content-disposition
8167  +hide-from-header {block}
8168  -hide-if-modified-since
8169  +hide-referrer {forge}
8170  -hide-user-agent
8171  -limit-connect
8172  -overwrite-last-modified
8173  -prevent-compression
8174  -redirect
8175  -server-header-filter{xml-to-html}
8176  -server-header-filter{html-to-xml}
8177  -session-cookies-only
8178  +set-image-blocker {pattern} </screen>
8179 </para>
8180
8181 <para>
8182  Notice the only difference here to the previous listing, is to
8183  <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
8184  which are activated specifically for this site in our configuration,
8185  and thus show in the <quote>Final Results</quote>.
8186 </para>
8187
8188 <para>
8189  Now another example, <quote>ad.doubleclick.net</quote>:
8190 </para>
8191
8192 <para>
8193  <screen>
8194
8195  { +block{Domains starts with "ad"} }
8196   ad*.
8197
8198  { +block{Domain contains "ad"} }
8199   .ad.
8200
8201  { +block{Doubleclick banner server} +handle-as-image }
8202   .[a-vx-z]*.doubleclick.net
8203 </screen>
8204 </para>
8205
8206 <para>
8207  We'll just show the interesting part here - the explicit matches. It is
8208  matched three different times. Two <quote>+block{}</quote> sections,
8209  and a <quote>+block{} +handle-as-image</quote>,
8210  which is the expanded form of one of our aliases that had been defined as:
8211  <quote>+block-as-image</quote>. (<link
8212  linkend="ALIASES"><quote>Aliases</quote></link> are defined in
8213  the first section of the actions file and typically used to combine more
8214  than one action.)
8215 </para>
8216
8217 <para>
8218  Any one of these would have done the trick and blocked this as an unwanted
8219  image. This is unnecessarily redundant since the last case effectively
8220  would also cover the first. No point in taking chances with these guys
8221  though ;-) Note that if you want an ad or obnoxious
8222  URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
8223  is done here -- as both a <link
8224  linkend="BLOCK"><quote>+block{}</quote></link>
8225  <emphasis>and</emphasis> an
8226  <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
8227  The custom alias <quote><literal>+block-as-image</literal></quote> just
8228  simplifies the process and make it more readable.
8229 </para>
8230
8231 <para>
8232  One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
8233  This one is giving us problems. We are getting a blank page. Hmmm ...
8234 </para>
8235
8236 <para>
8237  <screen>
8238
8239  Matches for http://www.example.net/adsl/HOWTO/:
8240
8241  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8242
8243  {-add-header
8244   -block
8245   +change-x-forwarded-for{block}
8246   -client-header-filter{hide-tor-exit-notation}
8247   -content-type-overwrite
8248   -crunch-client-header
8249   -crunch-if-none-match
8250   -crunch-incoming-cookies
8251   -crunch-outgoing-cookies
8252   -crunch-server-header
8253   +deanimate-gifs
8254   -downgrade-http-version
8255   +fast-redirects {check-decoded-url}
8256   -filter {js-events}
8257   -filter {content-cookies}
8258   -filter {all-popups}
8259   -filter {banners-by-link}
8260   -filter {tiny-textforms}
8261   -filter {frameset-borders}
8262   -filter {demoronizer}
8263   -filter {shockwave-flash}
8264   -filter {quicktime-kioskmode}
8265   -filter {fun}
8266   -filter {crude-parental}
8267   -filter {site-specifics}
8268   -filter {js-annoyances}
8269   -filter {html-annoyances}
8270   +filter {refresh-tags}
8271   -filter {unsolicited-popups}
8272   +filter {img-reorder}
8273   +filter {banners-by-size}
8274   +filter {webbugs}
8275   +filter {jumping-windows}
8276   +filter {ie-exploits}
8277   -filter {google}
8278   -filter {yahoo}
8279   -filter {msn}
8280   -filter {blogspot}
8281   -filter {no-ping}
8282   -force-text-mode
8283   -handle-as-empty-document
8284   -handle-as-image
8285   -hide-accept-language
8286   -hide-content-disposition
8287   +hide-from-header{block}
8288   +hide-referer{forge}
8289   -hide-user-agent
8290   -overwrite-last-modified
8291   +prevent-compression
8292   -redirect
8293   -server-header-filter{xml-to-html}
8294   -server-header-filter{html-to-xml}
8295   +session-cookies-only
8296   +set-image-blocker{blank} }
8297    /
8298
8299  { +block{Path contains "ads".} +handle-as-image }
8300   /ads
8301 </screen>
8302 </para>
8303
8304 <para>
8305  Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
8306  configuration! But we did not want this at all! Now we see why we get the
8307  blank page. It is actually triggering two different actions here, and
8308  the effects are aggregated so that the URL is blocked, and &my-app; is told
8309  to treat the block as if it were an image. But this is, of course, all wrong.
8310   We could now add a new action below this (or better in our own
8311   <filename>user.action</filename> file) that explicitly
8312   <emphasis>un</emphasis> blocks (
8313   <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
8314   <quote>adsl</quote> in them (remember, last match in the configuration
8315   wins). There are various ways to handle such exceptions. Example:
8316 </para>
8317
8318 <para>
8319  <screen>
8320
8321  { -block }
8322   /adsl
8323 </screen>
8324 </para>
8325
8326 <para>
8327  Now the page displays ;-)
8328  Remember to flush your browser's caches when making these kinds of changes to
8329  your configuration to insure that you get a freshly delivered page! Or, try
8330  using <literal>Shift+Reload</literal>.
8331 </para>
8332
8333 <para>
8334  But now what about a situation where we get no explicit matches like
8335  we did with:
8336 </para>
8337
8338 <para>
8339  <screen>
8340
8341  { +block{Path starts with "ads".} +handle-as-image }
8342  /ads
8343 </screen>
8344 </para>
8345
8346 <para>
8347  That actually was very helpful and pointed us quickly to where the problem
8348  was. If you don't get this kind of match, then it means one of the default
8349  rules in the first section of <filename>default.action</filename> is causing
8350  the problem. This would require some guesswork, and maybe a little trial and
8351  error to isolate the offending rule. One likely cause would be one of the
8352  <link linkend="FILTER"><quote>+filter</quote></link> actions.
8353  These tend to be harder to troubleshoot.
8354  Try adding the URL for the site to one of aliases that turn off
8355  <link linkend="FILTER"><quote>+filter</quote></link>:
8356 </para>
8357
8358 <para>
8359  <screen>
8360
8361  { shop }
8362  .quietpc.com
8363  .worldpay.com   # for quietpc.com
8364  .jungle.com
8365  .scan.co.uk
8366  .forbes.com
8367 </screen>
8368 </para>
8369
8370 <para>
8371  <quote><literal>{ shop }</literal></quote> is an <quote>alias</quote> that expands to
8372  <quote><literal>{ -filter -session-cookies-only }</literal></quote>.
8373  Or you could do your own exception to negate filtering:
8374
8375 </para>
8376
8377 <para>
8378  <screen>
8379
8380  { -filter }
8381  # Disable ALL filter actions for sites in this section
8382  .forbes.com
8383  developer.ibm.com
8384  localhost
8385 </screen>
8386 </para>
8387
8388 <para>
8389  This would turn off all filtering for these sites. This is best
8390  put in <filename>user.action</filename>, for local site
8391  exceptions. Note that when a simple domain pattern is used by itself (without
8392  the subsequent path portion), all sub-pages within that domain are included
8393  automatically in the scope of the action.
8394 </para>
8395
8396 <para>
8397  Images that are inexplicably being blocked, may well be hitting the
8398 <link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
8399  rule, which assumes
8400  that images of certain sizes are ad banners (works well
8401  <emphasis>most of the time</emphasis>  since these tend to be standardized).
8402 </para>
8403
8404 <para>
8405  <quote><literal>{ fragile }</literal></quote> is an alias that disables most
8406  actions that are the most likely to cause trouble. This can be used as a
8407  last resort for problem sites.
8408 </para>
8409 <para>
8410  <screen>
8411
8412  { fragile }
8413  # Handle with care: easy to break
8414  mail.google.
8415  mybank.example.com</screen>
8416 </para>
8417
8418
8419 <para>
8420  <emphasis>Remember to flush caches!</emphasis> Note that the
8421  <literal>mail.google</literal> reference lacks the TLD portion (e.g.
8422  <quote>.com</quote>). This will effectively match any TLD with
8423  <literal>google</literal> in it, such as <literal>mail.google.de.</literal>,
8424  just as an example.
8425 </para>
8426 <para>
8427  If this still does not work, you will have to go through the remaining
8428  actions one by one to find which one(s) is causing the problem.
8429 </para>
8430
8431 </sect2>
8432
8433 </sect1>
8434
8435  <!--
8436
8437  This program is free software; you can redistribute it
8438  and/or modify it under the terms of the GNU General
8439  Public License as published by the Free Software
8440  Foundation; either version 2 of the License, or (at
8441  your option) any later version.
8442
8443  This program is distributed in the hope that it will
8444  be useful, but WITHOUT ANY WARRANTY; without even the
8445  implied warranty of MERCHANTABILITY or FITNESS FOR A
8446  PARTICULAR PURPOSE.  See the GNU General Public
8447  License for more details.
8448
8449  The GNU General Public License should be included with
8450  this file.  If not, you can view it at
8451  http://www.gnu.org/copyleft/gpl.html
8452  or write to the Free Software Foundation, Inc.,
8453  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
8454  USA
8455
8456  -->
8457
8458 </article>