Remove kill-popups action.
[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 p-authors SYSTEM "p-authors.sgml">
13 <!entity config SYSTEM "p-config.sgml">
14 <!entity p-version "3.0.9">
15 <!entity p-status "UNRELEASED">
16 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
17 <!entity % p-not-stable "INCLUDE">
18 <!entity % p-stable "IGNORE">
19 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
20 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
21 <!entity % p-readme "IGNORE">
22 <!entity % user-man "IGNORE">
23 <!entity % config-file "IGNORE">
24 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
25 <!entity  my-copy "&copy;">         <!-- kludge for docbook2man           -->
26 <!entity % draft "IGNORE">          <!-- WIP stuff    -->
27 <!entity  my-app "<application>Privoxy</application>">
28 ]>
29 <!--
30  File        :  $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
31
32  Purpose     :  user manual
33                 This file belongs into
34                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
35
36  $Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 fabiankeil Exp $
37
38  Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
39  See LICENSE.
40
41  ========================================================================
42  NOTE: Please read developer-manual/documentation.html before touching 
43  anything in this, or other Privoxy documentation.
44  ========================================================================
45
46 -->
47
48 <article id="index">
49 <artheader>
50
51 <title>Privoxy &p-version; User Manual</title>
52
53 <pubdate>
54  <subscript>
55 <!-- Completely the wrong markup, but very little is allowed  -->
56 <!-- in this part of an article. FIXME -->
57  <link linkend="copyright">Copyright</link> &my-copy; 2001 - 2008 by 
58  <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
59  </subscript>
60 </pubdate>
61
62 <pubdate>$Id: user-manual.sgml,v 2.66 2008/03/06 16:33:47 fabiankeil Exp $</pubdate>
63
64 <!--
65
66 Note: the following should generate a separate page, and a live link to it,
67 all nicely done. But it doesn't for some mysterious reason. Please leave
68 commented unless it can be fixed proper. For the time being, the
69 copyright/license declarations will be in their own sgml.
70
71 Hal.
72
73
74 -->
75
76
77 <abstract>
78
79 <![%dummy;[
80  <para>
81  <comment>
82   This is here to keep vim syntax file from breaking :/
83   If I knew enough to fix it, I would.
84   PLEASE DO NOT REMOVE! HB: hal@foobox.net
85  </comment>
86  </para>
87 ]]>
88
89  <para>
90   The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
91   install, configure and use <ulink
92   url="http://www.privoxy.org/">Privoxy</ulink>.
93  </para>
94
95 <!-- Include privoxy.sgml boilerplate: -->
96  &p-intro;
97 <!-- end privoxy.sgml -->
98
99  <para>
100   You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at  <ulink
101   url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
102   Please see the <link linkend="contact">Contact section</link> on how to
103   contact the developers.
104  </para>
105
106 <!--   <para> -->
107 <!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
108 <!--   </para> -->
109 </abstract>
110
111 </artheader>
112
113 <!--   ~~~~~       New section      ~~~~~     -->
114 <sect1 label="1" id="introduction"><title>Introduction</title>
115 <para>
116  This documentation is included with the current &p-status; version of
117  <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[, 
118  and is mostly complete at this point. The most up to date reference for the
119  time being is still the comments in the source files and in the individual
120  configuration files. Development of a new version is currently nearing
121  completion, and includes significant changes and enhancements over
122  earlier versions. ]]>.
123 </para>
124
125 <!-- include only in non-stable versions -->
126 <![%p-not-stable;[
127 <para>
128  Since this is a &p-status; version, not all new features are well tested. This
129  documentation may be slightly out of sync as a result (especially with 
130  CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
131  not many! 
132 </para>
133 ]]>
134
135 <!--   ~~~~~       New section      ~~~~~     -->
136 <sect2 id="features"><title>Features</title>
137 <para>
138  In addition to the core 
139  features of ad blocking and 
140  <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
141  <application>Privoxy</application> provides many supplemental
142  features<![%p-not-stable;[, some of them currently under development]]>, 
143  that give the end-user more control, more privacy and more freedom:
144 </para>
145 <!-- Include newfeatures.sgml boilerplate here: -->
146  &newfeatures;
147 <!-- end boilerplate -->
148 </sect2>
149
150 </sect1>
151
152 <!--  ~  End section  ~  -->
153
154
155 <!--   ~~~~~       New section      ~~~~~     -->
156 <sect1 id="installation"><title>Installation</title>
157
158 <para>
159  <application>Privoxy</application> is available both in convenient pre-compiled
160  packages for a wide range of operating systems, and as raw source code.
161  For most users, we recommend using the packages, which can be downloaded from our
162  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
163  Page</ulink>.
164 </para>
165
166 <para>
167  Note: 
168  On some platforms, the installer may remove previously installed versions, if 
169  found. (See below for your platform). In any case <emphasis>be sure to backup
170  your old configuration if it is valuable to you.</emphasis> See the <link
171  linkend="upgradersnote">note to upgraders</link> section below.
172 </para>
173
174 <!--   ~~~~~       New section      ~~~~~     --> 
175 <sect2 id="installation-packages"><title>Binary Packages</title>
176 <para>
177 How to install the binary packages depends on your operating system:
178 </para>
179
180 <!-- XXX: The installation sections should be sorted -->
181
182 <!--   ~~~~~       New section      ~~~~~     -->
183 <sect3 id="installation-pack-rpm"><title>Red Hat and Fedora RPMs</title>
184
185 <para>
186  RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
187  and will use <filename>/etc/privoxy</filename> for the location 
188  of configuration files.
189 </para>
190
191 <para>
192  Note that on Red Hat, <application>Privoxy</application> will
193  <emphasis>not</emphasis> be automatically started on system boot. You will
194  need to enable that using <command>chkconfig</command>,
195  <command>ntsysv</command>, or similar methods. 
196 </para>
197
198 <para>
199  If you have problems with failed dependencies, try rebuilding the SRC RPM: 
200  <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm</literal>. This 
201  will use your locally installed libraries and RPM version. 
202 </para>
203
204 <para>
205  Also note that if you have a <application>Junkbuster</application> RPM installed
206  on your system, you need to remove it first, because the packages conflict.
207  Otherwise, RPM will try to remove <application>Junkbuster</application>
208  automatically if found, before installing <application>Privoxy</application>.
209 </para>
210 </sect3>
211
212 <!--   ~~~~~       New section      ~~~~~     -->
213 <sect3 id="installation-deb"><title>Debian and Ubuntu</title>
214 <para>
215  DEBs can be installed with <literal>apt-get install privoxy</literal>,
216  and will use <filename>/etc/privoxy</filename> for the location of 
217  configuration files.
218 </para>
219 </sect3>
220
221 <!--   ~~~~~       New section      ~~~~~     -->
222 <sect3 id="installation-pack-win"><title>Windows</title>
223
224 <para>
225  Just double-click the installer, which will guide you through
226  the installation process. You will find the configuration files
227  in the same directory as you installed <application>Privoxy</application> in. 
228 </para>
229 <para>
230  Version 3.0.5 beta introduced full <application>Windows</application> service
231  functionality. On Windows only, the <application>Privoxy</application>
232  program has two new command line arguments to install and uninstall
233  <application>Privoxy</application> as a <emphasis>service</emphasis>.
234 </para>
235  <variablelist>
236   <varlistentry>
237    <term>Arguments:</term>
238    <listitem>
239     <para>
240      <replaceable class="parameter">--install</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
241     </para>
242     <para>
243      <replaceable class="parameter">--uninstall</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
244     </para>
245    </listitem>
246   </varlistentry>
247  </variablelist>
248  <para>
249  After invoking <application>Privoxy</application> with
250  <command>--install</command>, you will need to bring up the
251  <application>Windows</application> service console to assign the user you
252  want <application>Privoxy</application> to run under, and whether or not you
253  want it to run whenever the system starts. You can start the
254  <application>Windows</application> services console with the following
255  command: <command>services.msc</command>.  If you do not take the manual step
256  of modifying <application>Privoxy's</application> service settings, it will
257  not start.  Note too that you will need to give Privoxy a user account that
258  actually exists, or it will not be permitted to 
259  write to its log and configuration files.
260 </para>
261
262 </sect3>
263
264 <!--   ~~~~~       New section      ~~~~~     -->
265 <sect3 id="installation-pack-bintgz"><title>Solaris <!--, NetBSD, HP-UX--></title>
266
267 <para>
268  Create a new directory, <literal>cd</literal> to it, then unzip and
269  untar the archive. For the most part, you'll have to figure out where
270  things go. <!-- FIXME, more info needed? -->
271 </para>
272 </sect3>
273
274 <!--   ~~~~~       New section      ~~~~~     -->
275 <sect3 id="installation-os2"><title>OS/2</title>
276
277 <para>
278  First, make sure that no previous installations of
279  <application>Junkbuster</application> and / or 
280  <application>Privoxy</application> are left on your
281  system. Check that no <application>Junkbuster</application>
282  or <application>Privoxy</application> objects are in
283  your startup folder.
284
285 </para>
286
287 <para>
288  Then, just double-click the WarpIN self-installing archive, which will
289  guide you through the installation process. A shadow of the
290  <application>Privoxy</application> executable will be placed in your
291  startup folder so it will start automatically whenever OS/2 starts.
292 </para>
293
294 <para>
295  The directory you choose to install <application>Privoxy</application>
296  into will contain all of the configuration files.
297 </para>
298 </sect3>
299
300 <!--   ~~~~~       New section      ~~~~~     -->
301 <sect3 id="installation-mac"><title>Mac OS X</title>
302 <para>
303  Unzip the downloaded file (you can either double-click on the zip file
304  icon from the Finder, or from the desktop if you downloaded it there).
305  Then, double-click on the package installer icon and follow the
306  installation process.
307 </para>
308 <para>
309  The privoxy service will automatically start after a successful
310  installation (in addition to every time your computer starts up).  To
311  prevent the privoxy service from automatically starting when your
312  computer starts up, remove or rename the folder named
313  <literal>/Library/StartupItems/Privoxy</literal>. 
314 </para>
315 <para>
316  To manually start or stop the privoxy service, use the Privoxy Utility
317  for Mac OS X.  This application controls the privoxy service (e.g.
318  starting and stopping the service as well as uninstalling the software).
319 </para>
320 </sect3>
321
322 <!--   ~~~~~       New section      ~~~~~     -->
323 <sect3 id="installation-amiga"><title>AmigaOS</title>
324 <para>
325  Copy and then unpack the <filename>lha</filename> archive to a suitable location. 
326  All necessary files will be installed into <application>Privoxy</application>
327  directory, including all configuration and log files. To uninstall, just 
328  remove this directory.
329 </para>
330 </sect3>
331
332 <!--   ~~~~~       New section      ~~~~~     -->
333 <sect3 id="installation-tbz"><title>FreeBSD</title>
334
335 <para>
336  Privoxy is part of FreeBSD's Ports Collection, you can build and install
337  it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
338 </para>
339 <para>
340  If you don't use the ports, you can fetch and install
341  the package with <literal>pkg_add -r privoxy</literal>.
342 </para>
343 <para>
344  The port skeleton and the package can also be downloaded from the
345  <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
346  Page</ulink>, but there's no reason to use them unless you're interested in the
347  beta releases which are only available there.
348 </para>
349 </sect3>
350
351 <!--   ~~~~~       New section      ~~~~~     -->
352 <sect3 id="installattion-gentoo"><title>Gentoo</title>
353 <para>
354  Gentoo source packages (Ebuilds) for <application>Privoxy</application> are 
355  contained in the Gentoo  Portage Tree (they are not on the download page, 
356  but there is a Gentoo section, where you can see when a new 
357  <application>Privoxy</application> Version is added to the  Portage Tree).
358 </para>
359 <para>
360  Before installing <application>Privoxy</application> under Gentoo just do 
361  first <literal>emerge rsync</literal> to get the latest changes from the 
362  Portage tree. With <literal>emerge privoxy</literal> you install the latest 
363  version.
364 </para>
365 <para>
366  Configuration files are in <filename>/etc/privoxy</filename>, the 
367  documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
368  and the Log directory is in <filename>/var/log/privoxy</filename>.
369 </para>
370 </sect3>
371
372 </sect2>
373
374 <!--   ~~~~~       New section      ~~~~~     -->
375 <sect2 id="installation-source"><title>Building from Source</title>
376
377 <para>
378  The most convenient way to obtain the <application>Privoxy</application> sources
379  is to download the source tarball from our 
380  <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;package_id=10571">project download
381  page</ulink>.
382 </para>
383
384 <para>
385  If you like to live on the bleeding edge and are not afraid of using
386  possibly unstable development versions, you can check out the up-to-the-minute
387  version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
388  CVS repository</ulink>. 
389 <!-- 
390  deprecated...out of business.
391  or simply download <ulink
392  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
393  tarball.</ulink>
394 -->
395 </para>
396
397 <!-- include buildsource.sgml boilerplate: -->
398 &buildsource;
399 <!-- end boilerplate -->
400
401 </sect2>
402 <!--   ~~~~~       New section      ~~~~~     --> 
403 <sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
404 <para>
405  As user feedback comes in and development continues, we will make updated versions
406  of both the main <link linkend="actions-file">actions file</link> (as a <ulink
407  url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;release_id=103670">separate
408  package</ulink>) and the software itself (including the actions file) available for
409  download.
410 </para>
411
412 <para>
413  If you wish to receive an email notification whenever we release updates of
414  <application>Privoxy</application> or the actions file, <ulink
415  url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
416  to our announce  mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
417 </para>
418
419 <para>
420  In order not to lose your personal changes and adjustments when updating
421  to the latest <literal>default.action</literal> file we <emphasis>strongly
422  recommend</emphasis> that you use <literal>user.action</literal> and 
423  <literal>user.filter</literal> for your local
424  customizations of <application>Privoxy</application>. See the <link
425  linkend="actions-file">Chapter on actions files</link> for details.
426 </para>
427
428 </sect2>
429
430
431 </sect1>
432
433 <!--  ~  End section  ~  -->
434
435 <!--   ~~~~~       New section      ~~~~~     -->
436 <sect1 id="whatsnew">
437 <title>What's New in this Release</title>
438 <para>
439  There are many improvements and new features since <application>Privoxy 3.0.6</application>, the last stable release:
440 </para>
441
442 <para>
443  <itemizedlist>
444   <listitem>
445    <para>
446     Two new actions <link
447           linkend="server-header-tagger">server-header-tagger</link>
448           and <link
449           linkend="client-header-tagger">client-header-tagger</link>
450           that can be used to create arbitrary <quote>tags</quote>
451           based on client and server headers.
452           These <quote>tags</quote> can then subsequently be used
453           to control the other actions used for the current request,
454           greatly increasing &my-app;'s flexibility and selectivity. See <link
455           linkend="tag-pattern">tag patterns</link> for more information on tags.
456    </para>
457   </listitem>
458
459   <listitem>
460    <para>
461     Header filtering is done with dedicated header filters now. As a result
462     the actions <quote>filter-client-headers</quote> and <quote>filter-server-headers</quote>
463     that were introduced with <application>Privoxy 3.0.5</application> to apply
464     content filters to the headers have been removed.
465     See the new actions <link
466           linkend="server-header-filter">server-header-filter</link>
467           and <link
468           linkend="client-header-filter">client-header-filter</link> for details.
469    </para>
470   </listitem>
471   <listitem>
472    <para>
473      There are four new options for the main <filename>config</filename> file:
474    </para>
475
476      <itemizedlist>
477        <listitem>
478         <para>
479           <link
480           linkend="allow-cgi-request-crunching">allow-cgi-request-crunching</link>
481           which allows requests for Privoxy's internal CGI pages to be
482           blocked, redirected or (un)trusted like ordinary requests.
483         </para>
484        </listitem>
485        <listitem>
486         <para>
487           <link
488           linkend="split-large-forms">split-large-forms</link>
489           that will work around a browser bug that caused IE6 and IE7 to
490           ignore the Submit button on the Privoxy's edit-actions-for-url CGI
491           page.
492           </para>
493        </listitem>
494        <listitem>
495         <para>
496           <link
497           linkend="accept-intercepted-requests">accept-intercepted-requests</link>
498           which allows to combine Privoxy with any packet filter to create an
499           intercepting proxy for HTTP/1.1 requests (and for HTTP/1.0 requests
500           with Host header set). This means clients can be forced to use
501           &my-app; even if their proxy settings are configured differently.
502          </para>
503        </listitem>
504        <listitem>
505         <para>
506           <link
507           linkend="templdir">templdir</link>
508           to designate an alternate location for &my-app;'s 
509           locally customized CGI templates so that
510           these are not overwritten during upgrades.         
511         </para>
512        </listitem>
513        </itemizedlist>
514     </listitem>
515
516   <listitem>
517    <para>
518    A new command line option <literal>--pre-chroot-nslookup hostname</literal> to
519    initialize the resolver library before chroot'ing. On some systems this
520    reduces the number of files that must be copied into the chroot tree.
521    (Patch provided by Stephen Gildea)
522    </para>
523   </listitem>
524
525   <listitem>
526    <para>
527      The <link
528           linkend="forward-override">forward-override</link> action 
529      allows changing of the forwarding settings through the actions files.
530      Combined with tags, this allows to choose the forwarder based on
531      client headers like the <literal>User-Agent</literal>, or the request origin.
532   </para>
533   </listitem>
534
535   <listitem>
536    <para>
537      The  <link
538           linkend="redirect">redirect</link> action can now use regular
539           expression substitutions against the original URL.
540    </para>
541   </listitem>
542
543   <listitem>
544    <para>
545      <application>zlib</application> support is now available as a compile
546      time option to filter compressed content. Patch provided by Wil Mahan.
547    </para>
548   </listitem>
549     <listitem>
550     <para>
551      Improve various filters, and add new ones.
552    </para>
553   </listitem>
554
555
556   <listitem>
557    <para>
558     Include support for RFC 3253 so that <filename>Subversion</filename> works
559     with &my-app;. Patch provided by Petr Kadlec.
560    </para>
561   </listitem>
562
563   <listitem>
564    <para>
565      Logging can be completely turned off by not specifying a logfile directive.
566    </para>
567   </listitem>
568
569
570   <listitem>
571    <para>
572      A number of improvements to Privoxy's internal CGI pages, including the
573      use of favicons for error and control pages.
574    </para>
575   </listitem>
576
577   <listitem>
578    <para>
579      Many bugfixes, memory leaks addressed, code improvements, and logging 
580      improvements.
581    </para>
582   </listitem>
583
584  </itemizedlist>
585 </para>
586 <para>
587  For a more detailed list of changes please have a look at the ChangeLog.
588 </para>
589
590 <!--   ~~~~~       New section      ~~~~~     -->
591
592 <sect2 id="upgradersnote">
593 <title>Note to Upgraders</title>
594
595 <para>
596  A quick list of things to be aware of before upgrading from earlier 
597  versions of <application>Privoxy</application>:
598 </para>
599
600 <para>
601  <itemizedlist>
602
603  <listitem>
604   <para>
605    The recommended way to upgrade &my-app; is to backup your old 
606    configuration files, install the new ones, verify that &my-app;
607    is working correctly and finally merge back your changes using
608    <application>diff</application> and maybe <application>patch</application>.
609   </para>
610   <para>
611    There are a number of new features in each &my-app; release and
612    most of them have to be explicitly enabled in the configuration
613    files. Old configuration files obviously don't do that and due
614    to syntax changes using old configuration files with a new
615    &my-app; isn't always possible anyway.
616   </para>
617  </listitem>
618  <listitem>
619   <para>  
620     Note that some installers remove earlier versions completely,
621     including configuration files, therefore you should really save
622     any important configuration files!
623   </para>
624  </listitem>
625  <listitem>
626   <para>  
627    On the other hand, other installers don't overwrite existing configuration 
628    files, thinking you will want to do that yourself.
629   </para>
630  </listitem>
631  <listitem>
632   <para>  
633    <filename>standard.action</filename> now only includes the enabled actions.
634    Not all actions as before.
635   </para>
636  </listitem>
637  <listitem>
638   <para>
639    In the default configuration only fatal errors are logged now.
640    You can change that in the <link linkend="DEBUG">debug section</link>
641    of the configuration file. You may also want to enable more verbose
642    logging until you verified that the new &my-app; version is working
643    as expected.
644   </para>
645  </listitem>
646
647  <listitem>
648     <para>
649      Three other config file settings are now off by default: 
650      <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
651      <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
652      and  <link linkend="enable-edit-actions">enable-edit-actions</link>. 
653      If you use or want these, you will need to explicitly enable them, and
654      be aware of the security issues involved. 
655     </para>
656   </listitem>
657
658   <listitem>
659    <para>
660     The <quote>filter-client-headers</quote> and
661     <quote>filter-server-headers</quote> actions that were introduced with
662     <application>Privoxy 3.0.5</application> to apply content filters to
663     the headers  have been removed and replaced with new actions.
664     See the <link
665           linkend="whatsnew">What's New section</link> above.
666    </para>
667   </listitem>
668
669
670 <!--
671  <listitem>
672   <para>  
673    What constitutes a <quote>default</quote> configuration has changed, 
674    and you may want to review which actions are <quote>on</quote> by 
675    default. This is primarily a matter of emphasis, but some features 
676    you may have been used to, may now be <quote>off</quote> by default.
677    There are also a number of new actions and filters you may want to
678    consider, most of which are not fully incorporated into the default
679    settings as yet (see above).
680   </para>
681  </listitem>
682 -->
683 <!--
684   <listitem>
685    <para>
686     The default actions setting is now <literal>Cautious</literal>. Previous
687     releases had a default setting of <literal>Medium</literal>. Experienced
688     users may want to adjust this, as it is fairly conservative by &my-app;
689     standards and past practices. See <ulink
690     url="http://config.privoxy.org/edit-actions-list?f=default">
691     http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
692     should try the default settings for a while before turning up the volume.
693    </para>
694   </listitem>
695
696   <listitem>
697    <para>
698     The default setting has filtering turned <emphasis>off</emphasis>, which
699     subsequently means that compression is <emphasis>on</emphasis>. Remember
700     that filtering does not work on compressed pages, so if you use, or want to
701     use, filtering, you will need to force compression off. Example:
702    </para>
703    <para>
704  <screen>
705   { +<link linkend="filter">filter</link>{google}  +<link linkend="prevent-compression">prevent-compression</link> }
706    .google.</screen>
707    </para>
708    <para>
709     Or if you use a number of filters, or filter many sites, you may just want
710     to turn off compression for all sites in
711     <filename>default.action</filename> (or
712     <filename>user.action</filename>). 
713    </para>
714
715   </listitem>
716
717   <listitem>
718   <para>
719    Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is 
720    off by default now. If you've liked this feature in the past, you may want 
721    to turn it back on in <filename>user.action</filename> now.
722   </para>
723   </listitem>
724
725
726   <listitem>
727   <para>
728    Some installers may not automatically start
729    <application>Privoxy</application> after installation.
730   </para>
731  </listitem> 
732 -->
733
734  </itemizedlist>
735 </para>
736
737 </sect2>
738 </sect1>
739
740 <!--   ~~~~~       New section      ~~~~~     -->
741 <sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
742 <para>
743  <itemizedlist>
744
745  <listitem>
746   <para>
747   Install <application>Privoxy</application>. See the <link
748   linkend="installation">Installation Section</link> below for platform specific
749   information. 
750  </para>
751  </listitem>  
752
753  <listitem>
754   <para>
755    Advanced users and those who want to offer <application>Privoxy</application>
756    service to more than just their local machine should check the <link
757    linkend="config">main config file</link>, especially the <link
758    linkend="access-control">security-relevant</link> options. These are 
759    off by default.
760   </para>
761  </listitem>  
762
763  <listitem>
764   <para>
765   Start <application>Privoxy</application>, if the installation program has
766   not done this already (may vary according to platform). See the section
767   <link linkend="startup">Starting <application>Privoxy</application></link>.
768   </para>
769  </listitem>
770
771  <listitem>
772   <para>
773    Set your browser to use <application>Privoxy</application> as HTTP and
774    HTTPS (SSL)  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
775    by setting the proxy configuration for address of
776    <literal>127.0.0.1</literal> and port <literal>8118</literal>.
777    <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or 
778    any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
779    browser from using these protocols.
780   </para>
781  </listitem>  
782
783  <listitem>
784   <para>
785     Flush your browser's disk and memory caches, to remove any cached ad images.
786     If using <application>Privoxy</application> to manage 
787     <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
788     you should remove any currently stored cookies too.
789   </para>
790  </listitem> 
791
792  <listitem>
793   <para>
794    A default installation should provide a reasonable starting point for 
795    most. There will undoubtedly be occasions where you will want to adjust the
796    configuration, but that can be dealt with as the need arises. Little 
797    to no initial configuration is required in most cases, you may want
798    to enable the
799    <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
800    Be sure to read the warnings first.
801   </para>
802   <para>
803    See the <link linkend="configuration">Configuration section</link> for more
804    configuration options, and how to customize your installation.
805    You might also want to look at the <link
806    linkend="quickstart-ad-blocking">next section</link> for a quick
807    introduction to how <application>Privoxy</application> blocks ads and
808    banners.
809 </para>
810  </listitem> 
811
812  <listitem>
813   <para>
814     If you experience ads that slip through, innocent images that are
815     blocked, or otherwise feel the need to fine-tune
816     <application>Privoxy's</application> behavior, take a look at the <link
817     linkend="actions-file">actions files</link>. As a quick start, you might
818     find the <link linkend="act-examples">richly commented examples</link>
819     helpful. You can also view and edit the actions files through the <ulink
820     url="http://config.privoxy.org">web-based user interface</ulink>. The
821     Appendix <quote><link linkend="actionsanat">Troubleshooting: Anatomy of an
822     Action</link></quote> has hints on how to understand and debug actions that
823     <quote>misbehave</quote>.
824   </para>
825  </listitem> 
826
827 <!--
828  Did anyone test these lately?
829  fk 2007-11-10
830  <listitem>
831   <para>
832    For easy access to &my-app;'s most important controls, drag the provided
833    <link linkend="bookmarklets">Bookmarklets</link> into your browser's
834    personal toolbar.
835   </para>
836  </listitem> 
837 -->
838
839  <listitem>
840   <para>
841    Please see the section <link linkend="contact">Contacting the
842    Developers</link> on how to report bugs, problems with websites or to get
843    help. 
844   </para>
845  </listitem> 
846
847  <listitem>
848   <para>
849    Now enjoy surfing with enhanced control, comfort and privacy!
850   </para>
851  </listitem> 
852
853  </itemizedlist>
854 </para>
855
856
857 <!--   ~~~~~       New section      ~~~~~     -->
858
859 <sect2 id="quickstart-ad-blocking">
860 <title>Quickstart to Ad Blocking</title>
861 <!--
862  NOTE:  This section is deliberately redundant for those that don't 
863  want to read the whole thing (which is getting lengthy).
864 -->
865 <para>
866  Ad blocking is but one of <application>Privoxy's</application>
867  array of features. Many of these features are for the technically minded advanced 
868  user. But, ad and banner blocking is surely common ground for everybody.
869 </para>
870 <para> 
871  This section will provide a quick summary of ad blocking so 
872  you can get up to speed quickly without having to read the more extensive
873  information provided below, though this is highly recommended.
874 </para>
875 <para>
876  First a bit of a warning ... blocking ads is much like blocking SPAM: the
877  more aggressive you are about it, the more likely you are to block 
878  things that were not intended. And the more likely that some things 
879  may not work as intended. So there is a trade off here. If you want
880  extreme ad free browsing, be prepared to deal with more
881  <quote>problem</quote> sites, and to spend more time adjusting the
882  configuration to solve these unintended consequences. In short, there is 
883  not an easy way to eliminate <emphasis>all</emphasis> ads. Either take 
884  the easy way and settle for <emphasis>most</emphasis> ads blocked with the
885  default configuration, or jump in and tweak it for your personal surfing
886  habits and preferences.
887 </para>
888 <para>
889  Secondly, a brief explanation of <application>Privoxy's </application>
890  <quote>actions</quote>. <quote>Actions</quote> in this context, are 
891  the directives we use to tell <application>Privoxy</application> to perform
892  some task relating to HTTP transactions (i.e. web browsing). We tell
893  <application>Privoxy</application> to take some <quote>action</quote>. Each
894  action has a unique name and function. While there are many potential
895  <application>actions</application> in <application>Privoxy's</application>
896  arsenal, only a few are used for ad blocking. <link
897  linkend="actions">Actions</link>, and <link linkend="actions-file">action
898  configuration files</link>, are explained in depth below.
899 </para>
900 <para>
901  Actions are specified in <application>Privoxy's</application> configuration,
902  followed by one or more URLs to which the action should apply. URLs 
903  can actually be URL type <link linkend="af-patterns">patterns</link> that use
904  wildcards so they can apply potentially to a range of similar URLs. The
905  actions, together with the URL patterns are called a section.
906 </para>
907 <para>
908  When you connect to a website, the full URL will either match one or more
909  of the sections as defined in <application>Privoxy's</application> configuration,
910  or not. If so, then <application>Privoxy</application> will perform the
911  respective actions. If not, then nothing special happens. Furthermore, web
912  pages may contain embedded, secondary URLs that your web browser will
913  use to load additional components of the page, as it parses the
914  original page's HTML content. An ad image for instance, is just an URL
915  embedded in the page somewhere. The image itself may be on the same server,
916  or a server somewhere else on the Internet. Complex web pages will have many
917  such embedded URLs. &my-app; can deal with each URL individually, so, for
918  instance, the main page text is not touched, but images from such-and-such
919  server are blocked.
920 </para>
921
922 <para>
923  The most important actions for basic ad blocking are:  <literal><link
924  linkend="block">block</link></literal>, <literal><link
925  linkend="handle-as-image">handle-as-image</link></literal>, 
926  <literal><link
927  linkend="handle-as-empty-document">handle-as-empty-document</link></literal>,and
928  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
929 </para>
930
931 <para>
932  <itemizedlist>
933   
934  <listitem>
935   <para>
936    <literal><link linkend="block">block</link></literal> - this is perhaps 
937    the single most used action, and is particularly important for ad blocking.
938    This action stops any contact between your browser and any URL patterns
939    that match this action's configuration. It can be used for blocking ads,
940    but also anything that is determined to be unwanted. By itself, it simply
941    stops any communication with the remote server and sends
942    <application>Privoxy</application>'s own built-in BLOCKED page instead to
943    let you now what has happened (with some exceptions, see below).
944   </para>
945  </listitem> 
946
947  <listitem>
948   <para>
949    <literal><link linkend="handle-as-image">handle-as-image</link></literal> - 
950    tells <application>Privoxy</application> to treat this URL as an image.
951    <application>Privoxy</application>'s default configuration already does this
952    for all common image types (e.g. GIF), but there are many situations where this
953    is not so easy to determine. So we'll force it in these cases. This is particularly
954    important for ad blocking, since  only if we know that it's an image of
955    some kind, can we replace it with an image of our choosing, instead of the 
956    <application>Privoxy</application> BLOCKED page (which would only result in
957    a <quote>broken image</quote> icon). There are some limitations to this
958    though. For instance, you can't just brute-force an image substitution for
959    an entire HTML page in most situations.
960   </para>
961  </listitem> 
962
963  <listitem>
964   <para>
965    <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal> - 
966    sends an empty document instead of <application>Privoxy's</application> 
967    normal BLOCKED HTML page. This is useful for file types that are neither 
968    HTML nor images, such as blocking JavaScript files.
969   </para>
970  </listitem> 
971
972  <listitem>
973   <para>
974    <literal><link
975    linkend="set-image-blocker">set-image-blocker</link></literal> - tells
976    <application>Privoxy</application> what to display in place of an ad image that
977    has hit a block rule. For this to come into play, the URL must match a
978    <literal><link linkend="block">block</link></literal> action somewhere in the
979    configuration, <emphasis>and</emphasis>, it must also match an
980    <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
981   </para>
982   <para>
983    The configuration options on what to display instead of the ad are:
984   </para>
985   <simplelist>
986    <member>
987     &nbsp;&nbsp;&nbsp;<emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad 
988     replacement is obvious. This is the default.
989    </member>
990   </simplelist>
991   <simplelist>
992    <member>
993     &nbsp;&nbsp;&nbsp;<emphasis>blank</emphasis> - A very small empty GIF image is displayed.
994     This is the so-called <quote>invisible</quote> configuration option.
995    </member>
996   </simplelist>
997   <simplelist>
998    <member>
999     &nbsp;&nbsp;&nbsp;<emphasis>http://&lt;URL&gt;</emphasis> - A redirect to any image anywhere
1000     of the user's choosing (advanced usage).
1001    </member>
1002   </simplelist>
1003   </listitem> 
1004
1005 </itemizedlist>
1006 </para>
1007
1008 <para>
1009  Advanced users will eventually want to explore &my-app;
1010  <literal><link linkend="filter">filters</link></literal> as well. Filters 
1011  are very different from <literal><link
1012  linkend="block">blocks</link></literal>.
1013  A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
1014  are a way of filtering or modifying what is actually on the page. An example
1015  filter usage: a text replacement of <quote>no-no</quote> for
1016  <quote>nasty-word</quote>. That is a very simple example. This process can be
1017  used for ad blocking, but it is more in the realm of advanced usage and has
1018  some pitfalls to be wary off.
1019 </para>
1020
1021 <para>
1022  The quickest way to adjust any of these settings is with your browser through
1023  the special <application>Privoxy</application> editor at <ulink
1024  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1025  (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This 
1026  is an internal page, and does not require Internet access.
1027 </para>
1028
1029 <para>
1030  Note that as of <application>Privoxy</application> 3.0.7 beta the
1031  action editor is disabled by default. Check the
1032  <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
1033   section in the configuration file</ulink> to learn why and in which
1034  cases it's safe to enable again.
1035 </para>
1036
1037 <para>
1038  If you decided to enable the action editor, select the appropriate
1039  <quote>actions</quote> file, and click
1040  <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
1041  local preferences in <filename>user.action</filename> since this is not
1042  meant to be overwritten during upgrades, and will over-ride the settings in
1043  other files. Here you can insert new <quote>actions</quote>, and URLs for ad
1044  blocking or other purposes, and make other adjustments to the configuration.
1045  <application>Privoxy</application> will detect these changes automatically.
1046 </para>
1047
1048 <para>
1049  A quick and simple step by step example:
1050 </para>
1051
1052 <para>
1053  <itemizedlist>
1054
1055   <listitem>
1056    <para>
1057      Right click on the ad image to be blocked, then select 
1058      <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
1059      pop-up menu. 
1060    </para>
1061   </listitem> 
1062   <listitem>
1063    <para>
1064     Set your browser to 
1065     <ulink
1066  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1067    </para>
1068   </listitem> 
1069   <listitem>
1070    <para>
1071     Find <filename>user.action</filename> in the top section, and click 
1072     on <quote><guibutton>Edit</guibutton></quote>:
1073    </para>
1074
1075  <!-- image of editor and actions files selections -->
1076  <para>
1077   <figure pgwide="0" float="0"><title>Actions Files in Use</title>
1078    <mediaobject>
1079      <imageobject>
1080       <imagedata  fileref="files-in-use.jpg" format="jpg">
1081        </imageobject> 
1082        <textobject>
1083         <phrase>[ Screenshot of Actions Files in Use ]</phrase>
1084       </textobject>
1085    </mediaobject>
1086   </figure>
1087  </para>
1088  </listitem> 
1089  
1090  <listitem>
1091   <para>
1092    You should have a section with only
1093    <literal><link linkend="block">block</link></literal> listed under 
1094    <quote>Actions:</quote>.
1095    If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
1096    button, and in the new section that just appeared, click the 
1097    <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
1098    This will bring up a list of all actions. Find
1099    <literal><link linkend="block">block</link></literal> near the top, and click
1100    in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
1101    just below the list.
1102   </para>
1103  </listitem> 
1104  <listitem>
1105   <para>
1106    Now, in the <literal><link linkend="block">block</link></literal> actions section,
1107    click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
1108    browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
1109    Remove the <literal>http://</literal> at the beginning of the URL. Then, click
1110    <quote><guibutton>Submit</guibutton></quote> (or
1111    <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
1112   </para>
1113  </listitem> 
1114  <listitem>
1115   <para>
1116    Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
1117    (or flush all browser caches). The image should be gone now.
1118   </para>
1119  </listitem> 
1120  
1121  </itemizedlist>
1122 </para>
1123
1124 <para>
1125  This is a very crude and simple example. There might be good reasons to use a 
1126  wildcard pattern match to include potentially similar images from the same
1127  site. For a more extensive explanation of <quote>patterns</quote>, and 
1128  the entire actions concept, see <link linkend="actions-file">the Actions
1129  section</link>.
1130 </para>
1131
1132 <para>
1133  For advanced users who want to hand edit their config files, you might want
1134  to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
1135  The ideas explained therein also apply to the web-based editor.
1136 </para>
1137 <para>
1138  There are also various 
1139  <link linkend="filter">filters</link> that can be used for ad blocking 
1140  (filters are a special subset of actions). These 
1141  fall into the <quote>advanced</quote> usage category, and are explained in
1142  depth in later sections. 
1143 </para>
1144
1145 </sect2>
1146
1147 </sect1>
1148
1149 <!--  ~  End section  ~  -->
1150
1151
1152 <!--   ~~~~~       New section      ~~~~~     -->
1153 <sect1 id="startup">
1154 <title>Starting Privoxy</title>
1155 <para>
1156  Before launching <application>Privoxy</application> for the first time, you
1157  will want to configure your browser(s) to use
1158  <application>Privoxy</application> as a HTTP and HTTPS (SSL) 
1159  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
1160  127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
1161  used port 8000). This is the one configuration step <emphasis>that must be done
1162 </emphasis>!
1163 </para>
1164 <para>
1165  Please note that <application>Privoxy</application> can only proxy HTTP and 
1166  HTTPS traffic. It will not work with FTP or other protocols.
1167 </para>
1168
1169  <!-- image of Mozilla Proxy configuration -->
1170  <para>
1171   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1172   Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
1173    <mediaobject>
1174      <imageobject>
1175       <imagedata  fileref="proxy_setup.jpg" format="jpg">
1176        </imageobject> 
1177        <textobject>
1178         <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
1179       </textobject>
1180    </mediaobject>
1181   </figure>
1182  </para>
1183  
1184
1185 <para> 
1186  With <application>Firefox</application>, this is typically set under:
1187 </para>
1188  
1189 <literallayout>
1190  <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> ->  <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
1191
1192 </literallayout>
1193
1194 <para> 
1195  Or optionally on some platforms:
1196 </para>
1197  
1198 <literallayout>
1199  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
1200
1201 </literallayout>
1202
1203
1204 <para> 
1205  With <application>Netscape</application> (and
1206  <application>Mozilla</application>), this can be set under:
1207 </para>
1208
1209
1210 <literallayout>
1211 <!-- Mix ascii and gui art, something for everybody -->
1212 <!-- spacing on this is tricky -->
1213  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
1214
1215 </literallayout>
1216
1217 <para>
1218  For <application>Internet Explorer v.5-7</application>: 
1219 </para>
1220
1221 <literallayout>
1222  <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
1223 </literallayout>
1224
1225 <para>
1226  Then, check <quote>Use Proxy</quote> and fill in the appropriate info
1227  (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
1228  proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
1229  checkboxes like <quote>Use the same proxy server for all protocols</quote> is
1230  <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
1231 </para>
1232
1233  <!-- image of IE Proxy configuration -->
1234  <para>
1235   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1236   Internet Explorer HTTP and HTTPS (Secure) Settings</title>
1237    <mediaobject>
1238      <imageobject>
1239       <imagedata  fileref="proxy2.jpg" format="jpg">
1240        </imageobject> 
1241        <textobject>
1242         <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
1243       </textobject>
1244    </mediaobject>
1245   </figure>
1246  </para>
1247
1248
1249 <para>
1250  After doing this, flush your browser's disk and memory caches to force a
1251  re-reading of all pages and to get rid of any ads that may be cached. Remove 
1252  any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
1253  if you want <application>Privoxy</application> to manage that. You are now
1254  ready to start enjoying the benefits of using
1255  <application>Privoxy</application>!
1256 </para>
1257
1258 <para>
1259  <application>Privoxy</application> itself is typically started by specifying the
1260  main configuration file to be used on the command line. If no configuration
1261  file is specified on the command line, <application>Privoxy</application>
1262  will look for a file named <filename>config</filename> in the current
1263  directory. Except on Win32 where it will try <filename>config.txt</filename>.
1264 </para>
1265
1266 <sect2 id="start-redhat">
1267 <title>Red Hat and Fedora</title>
1268 <para>
1269  A default Red Hat installation may not start &my-app; upon boot. It will use
1270  the file <filename>/etc/privoxy/config</filename> as its main configuration
1271  file.
1272 </para>
1273 <para>
1274  <screen>
1275  # /etc/rc.d/init.d/privoxy start
1276 </screen>
1277 </para>
1278 <para>
1279  Or ...
1280 </para>
1281 <para>
1282  <screen>
1283  # service privoxy start
1284 </screen>
1285 </para>
1286 </sect2>
1287
1288 <sect2 id="start-debian">
1289 <title>Debian</title>
1290 <para>
1291  We use a script. Note that Debian typically starts &my-app; upon booting per
1292  default.  It will use the file
1293  <filename>/etc/privoxy/config</filename> as its main configuration
1294  file.
1295 </para>
1296 <para>
1297  <screen>
1298  # /etc/init.d/privoxy start
1299 </screen>
1300 </para>
1301 </sect2>
1302
1303 <sect2 id="start-windows">
1304 <title>Windows</title>
1305 <para>
1306 Click on the &my-app; Icon to start <application>Privoxy</application>. If no configuration file is
1307  specified on the command line, <application>Privoxy</application> will look
1308  for a file named <filename>config.txt</filename>. Note that Windows will
1309  automatically start &my-app; when the system starts if you chose that option
1310  when installing.
1311 </para>
1312 <para>
1313  <application>Privoxy</application> can run with full Windows service functionality.
1314  On Windows only, the &my-app; program has two new command line arguments
1315  to install and uninstall &my-app; as a service. See the 
1316  <link linkend="installation-pack-win">Windows Installation
1317  instructions</link> for details.
1318 </para>
1319 </sect2>
1320
1321 <sect2 id="start-unices">
1322 <title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
1323 <para>
1324 Example Unix startup command:
1325 </para>
1326 <para>
1327  <screen>
1328  # /usr/sbin/privoxy /etc/privoxy/config
1329 </screen>
1330 </para>
1331 </sect2>
1332
1333 <sect2 id="start-os2">
1334 <title>OS/2</title>
1335 <para>
1336  During installation, <application>Privoxy</application> is configured to
1337  start automatically when the system restarts. You can start it manually by
1338  double-clicking on the <application>Privoxy</application> icon in the
1339  <application>Privoxy</application> folder.
1340 </para>
1341 </sect2>
1342
1343 <sect2 id="start-macosx">
1344 <title>Mac OS X</title>
1345 <para>
1346   After downloading the privoxy software, unzip the downloaded file by
1347   double-clicking on the zip file icon.  Then, double-click on the
1348   installer package icon and follow the installation process.
1349 </para>
1350 <para>
1351   The privoxy service will automatically start after a successful
1352   installation.  In addition, the privoxy service will automatically
1353   start every time your computer starts up.
1354 </para>
1355 <para>
1356   To prevent the privoxy service from automatically starting when your
1357   computer starts up, remove or rename the folder named
1358   /Library/StartupItems/Privoxy.
1359 </para>
1360 <para>
1361   A simple application named Privoxy Utility has been created which
1362   enables administrators to easily start and stop the privoxy service.
1363 </para>
1364 <para>
1365   In addition, the Privoxy Utility presents a simple way for
1366   administrators to edit the various privoxy config files.  A method
1367   to uninstall the software is also available.
1368 </para>
1369 <para>
1370   An administrator username and password must be supplied in order for
1371   the Privoxy Utility to perform any of the tasks.
1372 </para>
1373 <para>
1374  During installation, <application>Privoxy</application> is configured to
1375  start automatically when the system restarts.  To start &my-app; manually,
1376  double-click on the <literal>StartPrivoxy.command</literal> icon in the
1377  <literal>/Library/Privoxy</literal> folder.  Or, type this command
1378  in the Terminal:
1379 </para>
1380 <para>
1381   <screen>
1382   /Library/Privoxy/StartPrivoxy.command
1383   </screen>
1384 </para>
1385 <para>
1386  You will be prompted for the administrator password.
1387 </para>
1388 </sect2>
1389
1390
1391 <sect2 id="start-amigaos">
1392 <title>AmigaOS</title>
1393 <para>
1394  Start <application>Privoxy</application> (with RUN &lt;&gt;NIL:) in your
1395  <filename>startnet</filename> script (AmiTCP), in
1396  <filename>s:user-startup</filename> (RoadShow), as startup program in your
1397  startup script (Genesis), or as startup action (Miami and MiamiDx). 
1398  <application>Privoxy</application> will automatically quit when you quit your
1399  TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
1400  <application>Privoxy</application> is still running).
1401 </para>
1402 </sect2>
1403
1404 <sect2 id="start-gentoo">
1405 <title>Gentoo</title>
1406 <para>
1407  A script is again used. It will use the file <filename>/etc/privoxy/config 
1408  </filename> as its main configuration file.
1409 </para>
1410 <para>
1411  <screen>
1412  /etc/init.d/privoxy start
1413  </screen>
1414 </para>
1415 <para>
1416  Note that <application>Privoxy</application> is not automatically started at 
1417  boot time by default. You can change this with the <literal>rc-update</literal> 
1418  command.
1419 </para>
1420 <para> 
1421  <screen>
1422  rc-update add privoxy default
1423  </screen>
1424 </para>
1425 </sect2>
1426
1427 <!--
1428
1429 <para>
1430  See the section <link linkend="cmdoptions">Command line options</link> for
1431  further info.
1432 </para>
1433
1434 must find a better place for this paragraph
1435
1436 <para>
1437  The included default configuration files should give a reasonable starting
1438  point. Most of the per site configuration is done in the
1439  <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
1440  where various cookie actions are defined, ad and banner blocking, and other
1441  aspects of <application>Privoxy</application> configuration. There are several
1442  such files included, with varying levels of aggressiveness. 
1443 </para>
1444
1445 <para>
1446  You will probably want to keep an eye out for sites for which you may prefer
1447  persistent cookies, and add these to your actions configuration as needed. By
1448  default, most of these will be accepted only during the current browser
1449  session (aka <quote>session cookies</quote>), unless you add them to the
1450  configuration. If you want the browser to handle this instead, you will need
1451  to edit <filename>user.action</filename> (or through the web based interface)
1452  and disable this feature. If you use more than one browser, it would make
1453  more sense to let <application>Privoxy</application> handle this. In which
1454  case, the browser(s) should be set to accept all cookies.
1455 </para>
1456
1457 <para>
1458  Another feature where you will probably want to define exceptions for trusted
1459  sites is the popup-killing (through  <ulink
1460  url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>),
1461  because your favorite shopping, banking, or leisure site may need
1462  popups (explained below). 
1463 </para>
1464
1465 <para>
1466  <application>Privoxy</application> does not support all of the optional HTTP/1.1
1467  features yet. In the unlikely event that you experience inexplicable problems
1468  with browsers that use HTTP/1.1 per default
1469  (like <application>Mozilla</application> or recent versions of I.E.), you might
1470  try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit -&gt;
1471  Preferences -&gt; Debug -&gt; Networking</literal>.
1472  Alternatively, set the <quote>+downgrade-http-version</quote> config option in
1473  <filename>default.action</filename> which will downgrade your browser's HTTP
1474  requests from HTTP/1.1 to HTTP/1.0 before processing them.
1475 </para>
1476
1477 <para>
1478  After running <application>Privoxy</application> for a while, you can 
1479  start to fine tune the configuration to suit your personal, or site, 
1480  preferences and requirements. There are many, many aspects that can 
1481  be customized. <quote>Actions</quote> 
1482  can be adjusted by pointing your browser to 
1483  <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1484  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), 
1485  and then follow the link to <quote>View &#38; Change the Current Configuration</quote>. 
1486  (This is an internal page and does not require Internet access.)
1487 </para>
1488
1489 <para>
1490  In fact, various aspects of <application>Privoxy</application>
1491  configuration can be viewed from this page, including 
1492  current configuration parameters, source code version numbers, 
1493  the browser's request headers, and <quote>actions</quote> that apply 
1494  to a given URL. In addition to the actions file 
1495  editor mentioned above, <application>Privoxy</application> can also 
1496  be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
1497 </para>
1498
1499 <para>
1500  If you encounter problems, try loading the page without
1501  <application>Privoxy</application>. If that helps, enter the URL where
1502  you have the problems into <ulink url="http://p.p/show-url-info">the browser
1503  based rule tracing utility</ulink>. See which rules apply and why, and
1504  then try turning them off for that site one after the other, until the problem
1505  is gone. When you have found the culprit, you might want to turn the rest on
1506  again.
1507 </para>
1508
1509 <para>
1510  If the above paragraph sounds gibberish to you, you might want to <link
1511  linkend="actions-file">read more about the actions concept</link>
1512  or even dive deep into the <link linkend="actionsanat">Appendix
1513  on actions</link>.
1514 </para>
1515
1516 <para>
1517  If you can't get rid of the problem at all, think you've found a bug in
1518  Privoxy, want to propose a new feature or smarter rules, please see the 
1519  section <link linkend="contact"><quote>Contacting the
1520  Developers</quote></link> below. 
1521 </para>
1522
1523 -->
1524
1525 <!--   ~~~~~       New section      ~~~~~     -->
1526 <sect2 id="cmdoptions">
1527 <title>Command Line Options</title>
1528 <para>
1529  <application>Privoxy</application> may be invoked with the following
1530  command-line options:
1531 </para>
1532
1533 <para>
1534  <itemizedlist>
1535
1536  <listitem>
1537   <para>
1538     <emphasis>--version</emphasis>
1539   </para>
1540   <para>
1541      Print version info and exit. Unix only.
1542   </para>
1543  </listitem> 
1544  <listitem>
1545   <para>
1546     <emphasis>--help</emphasis>
1547   </para>
1548   <para>
1549    Print short usage info and exit. Unix only.
1550   </para>
1551  </listitem> 
1552  <listitem>
1553   <para>
1554    <emphasis>--no-daemon</emphasis>
1555   </para>
1556   <para>
1557    Don't become a daemon, i.e. don't fork and become process group
1558    leader, and don't detach from controlling tty. Unix only.
1559   </para>
1560  </listitem> 
1561  <listitem>
1562   <para>
1563    <emphasis>--pidfile FILE</emphasis>
1564   </para>
1565   <para>
1566    On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
1567    <emphasis>FILE</emphasis> on exit. Failure to create or delete the
1568    <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
1569    option is given, no PID file will be used. Unix only.
1570   </para>
1571  </listitem> 
1572  <listitem>
1573   <para>
1574    <emphasis>--user USER[.GROUP]</emphasis>
1575   </para>
1576   <para>
1577    After (optionally) writing the PID file, assume the user  ID  of
1578    <emphasis>USER</emphasis>, and if included the GID of GROUP.  Exit if the
1579    privileges are not sufficient to do so. Unix only.
1580   </para>
1581  </listitem>
1582  <listitem>
1583   <para>
1584    <emphasis>--chroot</emphasis>
1585   </para>
1586   <para>
1587    Before changing to the user ID given in the <emphasis>--user</emphasis> option, 
1588    chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
1589    process that the directory tree starts there. If set up carefully, this can limit 
1590    the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
1591    Unix only.
1592   </para>
1593  </listitem>
1594  <listitem>
1595   <para>
1596    <emphasis>--pre-chroot-nslookup hostname</emphasis>
1597   </para>
1598   <para>
1599    Specifies a hostname to look up before doing a chroot. On some systems, initializing the
1600    resolver library involves reading config files from /etc and/or loading additional shared
1601    libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
1602    the number of files that must be copied into the chroot tree.
1603   </para>
1604   <para>
1605    For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
1606    your local name server (listed in /etc/resolv.conf) can resolve without recursion
1607    (that is, without having to ask any other name servers). The hostname need not exist,
1608    but if it doesn't, an error message (which can be ignored) will be output.
1609   </para>
1610  </listitem>
1611
1612  <listitem>
1613   <para>
1614     <emphasis>configfile</emphasis>
1615   </para>
1616   <para>
1617     If no <emphasis>configfile</emphasis> is included on the command line, 
1618     <application>Privoxy</application> will look for a file named 
1619     <quote>config</quote> in the current directory (except on Win32 
1620     where it will look for <quote>config.txt</quote> instead). Specify 
1621     full path to avoid confusion. If no config file is found, 
1622     <application>Privoxy</application> will fail to start.
1623   </para>
1624  </listitem> 
1625
1626  </itemizedlist>
1627 </para>
1628
1629 <para>
1630  On <application>MS Windows</application> only there are two additional 
1631  command-line options to allow <application>Privoxy</application> to install and 
1632  run as a <emphasis>service</emphasis>. See the 
1633 <link linkend="installation-pack-win">Window Installation section</link> 
1634 for details.
1635 </para>
1636
1637 </sect2>
1638
1639 </sect1>
1640
1641 <!--  ~  End section  ~  -->
1642
1643
1644 <!--   ~~~~~       New section      ~~~~~     -->
1645 <sect1 id="configuration"><title>Privoxy Configuration</title>
1646  <para>
1647   All <application>Privoxy</application> configuration is stored  
1648   in text files. These files can be edited with a text editor.
1649   Many important aspects of <application>Privoxy</application> can 
1650   also be controlled easily with a web browser.
1651  </para>
1652
1653
1654 <!--   ~~~~~       New section      ~~~~~     -->
1655
1656 <sect2>
1657 <title>Controlling Privoxy with Your Web Browser</title>
1658 <para>
1659  <application>Privoxy</application>'s user interface can be reached through the special 
1660  URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1661  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), 
1662  which is a built-in page and works without Internet access.
1663  You will see the following section:
1664
1665 </para>
1666
1667 <!-- Needs to be put in a table and colorized  -->
1668 <screen>
1669  <msgtext>
1670  <bridgehead renderas="sect2">&nbsp;&nbsp;&nbsp;&nbsp;Privoxy Menu</bridgehead>
1671
1672  <simplelist>
1673  <member>
1674   &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>
1675  </member>
1676  <member>
1677   &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>
1678  </member>
1679  <member>
1680   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
1681  </member>
1682  <member>
1683   &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>
1684  </member>
1685  <member>
1686   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
1687  </member>
1688  <member>
1689   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://www.privoxy.org/
1690   &p-version;/user-manual/">Documentation</ulink>
1691  </member>
1692  </simplelist>
1693  </msgtext>
1694 </screen>
1695
1696
1697 <para>
1698  This should be self-explanatory. Note the first item leads to an editor for the
1699  <link linkend="actions-file">actions files</link>, which is where the ad, banner,
1700  cookie, and URL blocking magic is configured as well as other advanced features of
1701  <application>Privoxy</application>. This is an easy way to adjust various
1702  aspects of <application>Privoxy</application> configuration. The actions
1703  file, and other configuration files, are explained in detail below. 
1704 </para>
1705
1706 <para>
1707  <quote>Toggle Privoxy On or Off</quote> is handy for sites that might 
1708  have problems with your current actions and filters. You can in fact use
1709  it as a test to see whether it is <application>Privoxy</application> 
1710  causing the problem or not. <application>Privoxy</application> continues 
1711  to run as a proxy in this case, but all manipulation is disabled, i.e.
1712  <application>Privoxy</application> acts like a normal forwarding proxy. There
1713  is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
1714  that you can toggle <application>Privoxy</application> with one click from
1715  your browser.
1716 </para>
1717
1718 <para>
1719  Note that several of the features described above are disabled by default
1720  in <application>Privoxy</application> 3.0.7 beta and later.
1721  Check the
1722  <ulink url="config.html">configuration file</ulink> to learn why
1723  and in which cases it's safe to enable them again.
1724 </para>
1725
1726 </sect2>
1727
1728 <!--  ~  End section  ~  -->
1729
1730
1731
1732
1733 <!--   ~~~~~       New section      ~~~~~     -->
1734
1735 <sect2 id="confoverview">
1736 <title>Configuration Files Overview</title>
1737 <para>
1738  For Unix, *BSD and Linux, all configuration files are located in
1739  <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
1740  AmigaOS these are all in the same directory as the 
1741  <application>Privoxy</application> executable. <![%p-not-stable;[ The name
1742  and number of configuration files has changed from previous versions, and is
1743  subject to change as development progresses.]]>
1744 </para>
1745
1746 <para>
1747  The installed defaults provide a reasonable starting point, though 
1748  some settings may be aggressive by some standards. For the time being, the
1749  principle configuration files are:
1750 </para>
1751
1752 <para>
1753  <itemizedlist>
1754
1755   <listitem>
1756    <para>
1757      The <link linkend="config">main configuration file</link> is named <filename>config</filename>
1758      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
1759      on Windows. This is a required file.
1760    </para>
1761   </listitem> 
1762
1763   <listitem>
1764    <para>
1765     <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
1766     is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
1767     content modification, cookie handling etc should be applied by default. It also defines many
1768     exceptions (both positive and negative) from this default set of actions that enable 
1769     <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
1770     as many websites as possible.
1771    </para>
1772    <para>
1773     Multiple actions files may be defined in <filename>config</filename>. These 
1774     are processed in the order they are defined. Local customizations and locally 
1775     preferred exceptions to the default policies  as defined in
1776     <filename>default.action</filename> (which you will most probably want
1777     to define sooner or later) are probably best applied in
1778     <filename>user.action</filename>, where you can preserve them across
1779     upgrades. <filename>standard.action</filename> is only for
1780     <application>Privoxy's</application> internal use.
1781    </para>
1782    <para>    
1783     There is also a web based editor that can be accessed from
1784     <ulink
1785     url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1786     (Shortcut: <ulink
1787     url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
1788     various actions files. 
1789    </para>
1790   </listitem> 
1791
1792   <listitem>
1793    <para>
1794     <quote>Filter files</quote> (the <link linkend="filter-file">filter
1795     file</link>) can be used to re-write the raw page content, including
1796     viewable text as well as embedded HTML and JavaScript, and whatever else
1797     lurks on any given web page. The filtering jobs are only pre-defined here;
1798     whether to apply them or not is up to the actions files. 
1799     <filename>default.filter</filename> includes various filters made 
1800     available for use by the developers. Some are much more intrusive than 
1801     others, and all should be used with caution. You may define additional 
1802     filter files in <filename>config</filename> as you can with 
1803     actions files. We suggest <filename>user.filter</filename> for any 
1804     locally defined filters or customizations.
1805    </para>
1806   </listitem> 
1807
1808  </itemizedlist>
1809 </para>
1810
1811 <para>
1812  The syntax of the configuration and filter files may change between different
1813  Privoxy versions, unfortunately some enhancements cost backwards compatibility.
1814  <!-- Add link to documentation-->
1815 </para>
1816
1817 <para>
1818  All files use the <quote><literal>#</literal></quote> character to denote a
1819  comment (the rest of the line will be ignored) and understand line continuation
1820  through placing a backslash ("<literal>\</literal>") as the very last character
1821  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
1822  its special function. Placing a <literal>#</literal> in front of an otherwise
1823  valid configuration line to prevent it from being interpreted is called "commenting
1824  out" that line. Blank lines are ignored.
1825 </para>
1826
1827 <para>
1828  The actions files and filter files  
1829  can use Perl style <link linkend="regex">regular expressions</link> for
1830  maximum flexibility. 
1831 </para>
1832
1833 <para>
1834  After making any changes, there is no need to restart
1835  <application>Privoxy</application> in order for the changes to take
1836  effect. <application>Privoxy</application> detects such changes 
1837  automatically. Note, however, that it may take one or two additional
1838  requests for the change to take effect. When changing the listening address
1839  of <application>Privoxy</application>, these <quote>wake up</quote> requests
1840  must obviously be sent to the <emphasis>old</emphasis> listening address.
1841 </para>
1842
1843 <![%p-not-stable;[
1844 <para>
1845  While under development, the configuration content is subject to change. 
1846  The below documentation may not be accurate by the time you read this. 
1847  Also, what constitutes a <quote>default</quote> setting, may change, so 
1848  please check all your configuration files on important issues.
1849 </para>
1850 ]]>
1851
1852 </sect2>
1853 </sect1>
1854 <!--  ~  End section  ~  -->
1855
1856
1857 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1858
1859 <!-- **************************************************** -->
1860 <!-- Include config.sgml here -->
1861 <!-- This is where the entire config file is detailed. -->
1862  &config;
1863 <!-- end include  -->
1864
1865
1866 <!--  ~  End section  ~  -->
1867
1868
1869
1870 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1871
1872 <sect1 id="actions-file"><title>Actions Files</title>
1873
1874 <para>
1875  The actions files are used to define what <emphasis>actions</emphasis>
1876  <application>Privoxy</application> takes for which URLs, and thus determines
1877  how ad images, cookies and various other aspects of HTTP content and
1878  transactions are handled, and on which sites (or even parts thereof). 
1879  There are a number of such actions, with a wide range of functionality.
1880  Each action does something a little different.
1881  These actions give us a veritable arsenal of tools with which to exert 
1882  our control, preferences and independence. Actions can be combined so that 
1883  their effects are aggregated when applied against a given set of URLs.
1884 </para> 
1885 <para>
1886  There 
1887  are three action files included with <application>Privoxy</application> with
1888  differing purposes:
1889  </para>
1890  
1891  <para>
1892   <itemizedlist>
1893    <listitem>
1894     <para>
1895      <filename>default.action</filename> - is the primary action file 
1896      that sets the initial values for all actions. It is intended to 
1897      provide a base level of functionality for
1898      <application>Privoxy's</application> array of features. So it is 
1899      a set of broad rules that should work reasonably well as-is for most users.
1900      This is the file that the developers are keeping updated, and <link
1901      linkend="installation-keepupdated">making available to users</link>.
1902      The user's preferences as set in <filename>standard.action</filename>,
1903      e.g. either <literal>Cautious</literal> (the default),
1904      <literal>Medium</literal>, or <literal>Advanced</literal> (see
1905      below).
1906     </para>
1907    </listitem> 
1908    <listitem>
1909     <para>
1910      <filename>user.action</filename> - is intended to be for local site 
1911      preferences and exceptions. As an example, if your ISP or your bank
1912      has specific requirements, and need special handling, this kind of 
1913      thing should go here. This file will not be upgraded.
1914     </para>
1915   </listitem> 
1916    <listitem>
1917     <para>
1918      <filename>standard.action</filename> - is used only by the web based editor
1919      at <ulink url="http://config.privoxy.org/edit-actions-list?f=default">
1920      http://config.privoxy.org/edit-actions-list?f=default</ulink>, 
1921      to set various pre-defined sets of rules for the default actions section
1922      in <filename>default.action</filename>. 
1923      </para>
1924      <para>
1925      <guibutton>Edit</guibutton>  <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton>  <guibutton>Set to Advanced</guibutton>
1926      </para>
1927      <para>
1928      These have increasing levels of aggressiveness <emphasis>and have no
1929      influence on your browsing unless you select them explicitly in the
1930      editor</emphasis>. A default installation should be pre-set to 
1931      <literal>Cautious</literal> (versions prior to 3.0.5 were set to
1932      <literal>Medium</literal>). New users should try this for a while before
1933      adjusting the settings to more aggressive levels. The more aggressive 
1934      the settings, then the more likelihood there is of problems such as sites 
1935      not working as they should.
1936      </para>
1937      <para>
1938       The <guibutton>Edit</guibutton> button allows you to turn each 
1939       action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
1940       button changes the actions list to low/safe settings which will activate 
1941       ad blocking and a minimal set of &my-app;'s features, and subsequently
1942       there will be less of a chance for accidental problems. The
1943       <guibutton>Medium</guibutton> button sets the list to a medium level of
1944       other features and a low level set of privacy features. The
1945       <guibutton>Advanced</guibutton> button sets the list to a high level of
1946       ad blocking and medium level of privacy. See the chart below. The latter
1947       three buttons over-ride any changes via with the
1948       <guibutton>Edit</guibutton> button. More fine-tuning can be done in the
1949       lower sections of this internal page.
1950      </para>
1951      <para>
1952      It is not recommend to edit the <filename>standard.action</filename> file
1953      itself.
1954     </para>
1955     <para>
1956      The default profiles, and their associated actions, as pre-defined in
1957      <filename>standard.action</filename> are<!-- different than this table which is out of date -->:
1958     </para>
1959     <para>
1960     <table frame=all><title>Default Configurations</title>
1961     <tgroup cols=4 align=left colsep=1 rowsep=1>
1962     <colspec colname=c1>
1963     <colspec colname=c2>
1964     <colspec colname=c3>
1965     <colspec colname=c4>
1966     <thead>
1967     <row>
1968       <entry>Feature</entry>
1969       <entry>Cautious</entry>
1970       <entry>Medium</entry>
1971       <entry>Advanced</entry>
1972     </row>
1973     </thead>
1974     <!--  <tfoot> -->
1975     <!--  <row> -->
1976     <!--    <entry>f1</entry> -->
1977     <!--    <entry>f2</entry> -->
1978     <!--    <entry>f3</entry> -->
1979     <!--    <entry>f4</entry> -->
1980     <!--  </row> -->
1981     <!--  </tfoot> -->
1982     <tbody>
1983
1984     <row>
1985       <entry>Ad-blocking Aggressiveness</entry>
1986       <entry>medium</entry>
1987       <entry>high</entry>
1988       <entry>high</entry>
1989     </row>
1990
1991     <row>
1992       <entry>Ad-filtering by size</entry>
1993       <entry>no</entry>
1994       <entry>yes</entry>
1995       <entry>yes</entry>
1996     </row>
1997
1998     <row>
1999       <entry>Ad-filtering by link</entry>
2000       <entry>no</entry>
2001       <entry>no</entry>
2002       <entry>yes</entry>
2003     </row>
2004     <row>
2005       <entry>Pop-up killing</entry>
2006       <entry>blocks only</entry>
2007       <entry>blocks only</entry>
2008       <entry>blocks only</entry>
2009     </row>
2010     
2011     <row>
2012       <entry>Privacy Features</entry>
2013       <entry>low</entry>
2014       <entry>medium</entry>
2015       <entry>medium/high</entry>
2016     </row>
2017
2018     <row>
2019       <entry>Cookie handling</entry>
2020       <entry>none</entry>
2021       <entry>session-only</entry>
2022       <entry>kill</entry>
2023     </row>
2024
2025     <row>
2026       <entry>Referer forging</entry>
2027       <entry>no</entry>
2028       <entry>yes</entry>
2029       <entry>yes</entry>
2030     </row>
2031
2032
2033     <row>
2034       <entry>GIF de-animation</entry>
2035       <entry>no</entry>
2036       <entry>yes</entry>
2037       <entry>yes</entry>
2038     </row>
2039
2040
2041     <row>
2042       <entry>Fast redirects</entry>
2043       <entry>no</entry>
2044       <entry>no</entry>
2045       <entry>yes</entry>
2046     </row>
2047
2048     <row>
2049       <entry>HTML taming</entry>
2050       <entry>no</entry>
2051       <entry>no</entry>
2052       <entry>yes</entry>
2053     </row>
2054
2055     <row>
2056       <entry>JavaScript taming</entry>
2057       <entry>no</entry>
2058       <entry>no</entry>
2059       <entry>yes</entry>
2060     </row>
2061
2062     <row>
2063       <entry>Web-bug killing</entry>
2064       <entry>no</entry>
2065       <entry>yes</entry>
2066       <entry>yes</entry>
2067     </row>
2068
2069     <row>
2070       <entry>Image tag reordering</entry>
2071       <entry>no</entry>
2072       <entry>no</entry>
2073       <entry>yes</entry>
2074     </row>
2075
2076     </tbody>
2077     </tgroup>
2078     </table>
2079     </para>
2080
2081    </listitem> 
2082   </itemizedlist>
2083  </para> 
2084
2085 <para>
2086  The list of actions files to be used are defined in the main configuration 
2087  file, and are processed in the order they are defined (e.g.
2088  <filename>default.action</filename> is typically processed before
2089  <filename>user.action</filename>). The content of these can all be viewed and
2090  edited from <ulink
2091  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2092  The over-riding principle when applying actions, is that the last action that
2093  matches a given URL wins. The broadest, most general rules go first
2094  (defined in <filename>default.action</filename>),
2095  followed by any exceptions (typically also in
2096  <filename>default.action</filename>), which are then followed lastly by any
2097  local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>). 
2098  Generally, <filename>user.action</filename> has the last word.
2099  </para>
2100
2101 <para>
2102  An actions file typically has multiple sections. If you want to use
2103  <quote>aliases</quote> in an actions file, you have to place the (optional)
2104  <link linkend="aliases">alias section</link> at the top of that file.
2105  Then comes the default set of rules which will apply universally to all
2106  sites and pages (be <emphasis>very careful</emphasis> with using such a
2107  universal set in <filename>user.action</filename> or any other actions file after 
2108  <filename>default.action</filename>, because it will override the result
2109  from consulting any previous file). And then below that,
2110  exceptions to the defined universal policies. You can regard
2111  <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
2112  with the advantage that it is a separate file, which makes preserving your
2113  personal settings across <application>Privoxy</application> upgrades easier.
2114 </para>
2115
2116 <para> 
2117  Actions can be used to block anything you want, including ads, banners, or
2118  just some obnoxious URL whose content you would rather not see. Cookies can be accepted
2119  or rejected, or accepted only during the current browser session (i.e. not
2120  written to disk), content can be modified, some JavaScripts tamed, user-tracking
2121  fooled, and much more. See below for a <link linkend="actions">complete list
2122  of actions</link>.
2123 </para>
2124
2125 <!--   ~~~~~       New section      ~~~~~     -->
2126 <sect2>
2127 <title>Finding the Right Mix</title>
2128 <para>
2129  Note that some <link linkend="actions">actions</link>, like cookie suppression
2130  or script disabling, may render some sites unusable that rely on these
2131  techniques to work properly. Finding the right mix of actions is not always easy and
2132  certainly a matter of personal taste. And, things can always change, requiring 
2133  refinements in the configuration. In general, it can be said that the more
2134  <quote>aggressive</quote> your default settings (in the top section of the
2135  actions file) are, the more exceptions for <quote>trusted</quote> sites you
2136  will have to make later. If, for example, you want to crunch all cookies per
2137  default, you'll have to make exceptions from that rule for sites that you
2138  regularly use and that require cookies for actually useful purposes, like maybe
2139  your bank, favorite shop, or newspaper.
2140 </para>
2141
2142 <para>
2143  We have tried to provide you with reasonable rules to start from in the
2144  distribution actions files. But there is no general rule of thumb on these
2145  things. There just are too many variables, and sites are constantly changing.
2146  Sooner or later you will want to change the rules (and read this chapter again :).
2147 </para>
2148 </sect2>
2149
2150 <!--   ~~~~~       New section      ~~~~~     -->
2151 <sect2>
2152 <title>How to Edit</title>
2153 <para>
2154  The easiest way to edit the actions files is with a browser by
2155  using our browser-based editor, which can be reached from <ulink
2156  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2157  Note: the config file option <link
2158  linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
2159  this to work. The editor allows both fine-grained control over every single
2160  feature on a per-URL basis, and easy choosing from wholesale sets of defaults
2161  like <quote>Cautious</quote>, <quote>Medium</quote> or
2162  <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
2163  aggressive, and will be more likely to cause problems for some sites.
2164  Experienced users only! 
2165  </para>
2166
2167 <para>
2168  If you prefer plain text editing to GUIs, you can of course also directly edit the
2169  the actions files with your favorite text editor. Look at
2170  <filename>default.action</filename> which is richly commented with many 
2171  good examples.
2172 </para>
2173 </sect2>
2174
2175
2176 <sect2 id="actions-apply">
2177 <title>How Actions are Applied to Requests</title>
2178 <para>
2179  Actions files are divided into sections. There are special sections,
2180  like the <quote><link linkend="aliases">alias</link></quote> sections which will
2181  be discussed later. For now let's concentrate on regular sections: They have a
2182  heading line (often split up to multiple lines for readability) which consist
2183  of a list of actions, separated by whitespace and enclosed in curly braces.
2184  Below that, there is a list of URL and tag patterns, each on a separate line.
2185 </para>
2186
2187 <para>
2188  To determine which actions apply to a request, the URL of the request is
2189  compared to all URL patterns in each <quote>action file</quote>.
2190  Every time it matches, the list of applicable actions for the request is
2191  incrementally updated, using the heading of the section in which the
2192  pattern is located. The same is done again for tags and tag patterns later on.
2193 </para>
2194
2195 <para>
2196  If multiple applying sections set the same action differently,
2197  the last match wins. If not, the effects are aggregated.
2198  E.g. a URL might match a regular section with a heading line of <literal>{ 
2199  +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
2200  then later another one with just <literal>{
2201  +<link linkend="block">block</link> }</literal>, resulting
2202  in <emphasis>both</emphasis> actions to apply. And there may well be 
2203  cases where you will want to combine actions together. Such a section then 
2204  might look like:
2205 </para>
2206
2207  <para>
2208  <screen>
2209   { +<literal>handle-as-image</literal>  +<literal>block{Banner ads.}</literal> }
2210   # Block these as if they were images. Send no block page.
2211    banners.example.com
2212    media.example.com/.*banners
2213    .example.com/images/ads/</screen>
2214  </para>
2215
2216 <para>
2217  You can trace this process for URL patterns and any given URL by visiting <ulink
2218  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2219 </para>
2220
2221 <para>
2222  Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2223  Troubleshooting: Anatomy of an Action</link> section.
2224 </para>
2225 </sect2>
2226
2227 <!--   ~~~~~       New section      ~~~~~     -->
2228 <sect2 id="af-patterns">
2229 <title>Patterns</title>
2230 <para> 
2231  As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
2232  to determine what <emphasis>actions</emphasis> might apply to which sites and
2233  pages your browser attempts to access. These <quote>patterns</quote> use wild
2234  card type <emphasis>pattern</emphasis> matching to achieve a high degree of
2235  flexibility. This allows one expression to be expanded and potentially match
2236  against many similar patterns.
2237 </para>
2238  
2239 <para>
2240  Generally, an URL pattern has the form
2241  <literal>&lt;domain&gt;/&lt;path&gt;</literal>, where both the
2242  <literal>&lt;domain&gt;</literal> and <literal>&lt;path&gt;</literal> are
2243  optional. (This is why the special <literal>/</literal> pattern matches all
2244  URLs). Note that the protocol portion of the URL pattern (e.g.
2245  <literal>http://</literal>) should <emphasis>not</emphasis> be included in
2246  the pattern. This is assumed already!
2247 </para>
2248 <para>
2249  The pattern matching syntax is different for the domain and path parts of
2250  the URL. The domain part uses a simple globbing type matching technique, 
2251  while the path part uses a more flexible 
2252  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2253   Expressions (PCRE)</quote></ulink> based syntax.
2254 </para>
2255
2256 <variablelist>
2257  <varlistentry>
2258   <term><literal>www.example.com/</literal></term>
2259   <listitem>
2260    <para>
2261     is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2262     regardless of which document on that server is requested. So ALL pages in
2263     this domain would be covered by the scope of this action. Note that a 
2264     simple <literal>example.com</literal> is different and would NOT match.
2265    </para>
2266   </listitem>
2267  </varlistentry>
2268  <varlistentry>
2269   <term><literal>www.example.com</literal></term>
2270   <listitem>
2271    <para>
2272     means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2273     be omitted.
2274    </para>
2275   </listitem>
2276  </varlistentry>
2277  <varlistentry>
2278   <term><literal>www.example.com/index.html$</literal></term>
2279   <listitem>
2280    <para>
2281     matches all the documents on <literal>www.example.com</literal>
2282     whose name starts with <literal>/index.html</literal>.
2283    </para>
2284   </listitem>
2285  </varlistentry>
2286  <varlistentry>
2287   <term><literal>www.example.com/index.html$</literal></term>
2288   <listitem>
2289    <para>
2290     matches only the single document <literal>/index.html</literal>
2291     on <literal>www.example.com</literal>.
2292    </para>
2293   </listitem>
2294  </varlistentry>
2295  <varlistentry>
2296   <term><literal>/index.html$</literal></term>
2297   <listitem>
2298    <para>
2299     matches the document <literal>/index.html</literal>, regardless of the domain,
2300     i.e. on <emphasis>any</emphasis> web server anywhere.
2301    </para>
2302   </listitem>
2303  </varlistentry>
2304  <varlistentry>
2305   <term><literal>index.html</literal></term>
2306   <listitem>
2307    <para>
2308     matches nothing, since it would be interpreted as a domain name and
2309     there is no top-level domain called <literal>.html</literal>. So its 
2310     a mistake.
2311    </para>
2312   </listitem>
2313  </varlistentry>
2314 </variablelist>
2315
2316
2317 <!--   ~~~~~       New section      ~~~~~     -->
2318 <sect3><title>The Domain Pattern</title>
2319
2320 <para>
2321  The matching of the domain part offers some flexible options: if the
2322  domain starts or ends with a dot, it becomes unanchored at that end. 
2323  For example:
2324 </para>
2325
2326 <variablelist>
2327  <varlistentry>
2328   <term><literal>.example.com</literal></term>
2329   <listitem>
2330    <para>
2331     matches any domain with first-level domain <literal>com</literal>
2332     and second-level domain <literal>example</literal>.
2333     For example <literal>www.example.com</literal>,
2334     <literal>example.com</literal> and <literal>foo.bar.baz.example.com</literal>.
2335     Note that it wouldn't match if the second-level domain was <literal>another-example</literal>.
2336    </para>
2337   </listitem>
2338  </varlistentry>
2339  <varlistentry>
2340   <term><literal>www.</literal></term>
2341   <listitem>
2342    <para>
2343     matches any domain that <emphasis>STARTS</emphasis> with
2344     <literal>www.</literal> (It also matches the domain
2345     <literal>www</literal> but most of the time that doesn't matter.)
2346    </para>
2347   </listitem>
2348  </varlistentry>
2349  <varlistentry>
2350   <term><literal>.example.</literal></term>
2351   <listitem>
2352    <para>
2353     matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>.
2354     And, by the way, also included would be any files or documents that exist
2355     within that domain since no path limitations are specified. (Correctly
2356     speaking: It matches any FQDN that contains <literal>example</literal> as
2357     a domain.) This might be <literal>www.example.com</literal>,
2358     <literal>news.example.de</literal>, or
2359     <literal>www.example.net/cgi/testing.pl</literal> for instance. All these
2360     cases are matched. 
2361    </para>
2362   </listitem>
2363  </varlistentry>
2364 </variablelist>
2365
2366 <para>
2367  Additionally, there are wild-cards that you can use in the domain names
2368  themselves. These work similarly to shell globbing type wild-cards:
2369  <quote>*</quote> represents zero or more arbitrary characters (this is
2370  equivalent to the 
2371  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2372  Expression</quote></ulink> based syntax of <quote>.*</quote>),
2373  <quote>?</quote>  represents any single character (this is equivalent to the
2374  regular expression syntax of a simple <quote>.</quote>), and you can define
2375  <quote>character classes</quote> in square brackets which is similar to 
2376  the same regular expression technique. All of this can be freely mixed:
2377 </para>
2378
2379 <variablelist>
2380  <varlistentry>
2381   <term><literal>ad*.example.com</literal></term>
2382   <listitem>
2383    <para>
2384     matches <quote>adserver.example.com</quote>, 
2385     <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2386    </para>
2387   </listitem>
2388  </varlistentry>
2389  <varlistentry>
2390   <term><literal>*ad*.example.com</literal></term>
2391   <listitem>
2392    <para>
2393     matches all of the above, and then some.
2394    </para>
2395   </listitem>
2396  </varlistentry>
2397  <varlistentry>
2398   <term><literal>.?pix.com</literal></term>
2399   <listitem>
2400    <para>
2401     matches <literal>www.ipix.com</literal>,
2402     <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc. 
2403    </para>
2404   </listitem>
2405  </varlistentry>
2406  <varlistentry>
2407   <term><literal>www[1-9a-ez].example.c*</literal></term>
2408   <listitem>
2409    <para>
2410      matches <literal>www1.example.com</literal>, 
2411      <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>, 
2412      <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis> 
2413      <literal>wwww.example.com</literal>.
2414    </para>
2415   </listitem>
2416  </varlistentry>
2417 </variablelist>
2418
2419 <para>
2420  While flexible, this is not the sophistication of full regular expression based syntax.
2421 </para>
2422
2423 </sect3>
2424
2425 <!--  ~  End section  ~  -->
2426
2427
2428 <!--   ~~~~~       New section      ~~~~~     -->
2429 <sect3><title>The Path Pattern</title>
2430
2431 <para>
2432  <application>Privoxy</application> uses Perl compatible (PCRE)
2433   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2434   Expression</quote></ulink> based syntax 
2435  (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2436  matching the path portion (after the slash), and is thus more flexible.
2437 </para>
2438
2439 <para>
2440  There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2441  expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2442  at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2443  You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2444  useful, which is available on-line at <ulink
2445  url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>.
2446 </para>
2447
2448 <para>
2449  Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2450  i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak 
2451  for the beginning of a line).
2452 </para>
2453
2454 <para>
2455  Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
2456  by default, but you can switch to case sensitive at any point in the pattern by using the 
2457  <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
2458  only documents whose path starts with <literal>PaTtErN</literal> in
2459  <emphasis>exactly</emphasis> this capitalization.
2460 </para>
2461
2462 <variablelist>
2463  <varlistentry>
2464   <term><literal>.example.com/.*</literal></term>
2465   <listitem>
2466    <para>
2467      Is equivalent to just <quote>.example.com</quote>, since any documents 
2468      within that domain are matched with or without the <quote>.*</quote>
2469      regular expression. This is redundant
2470    </para>
2471   </listitem>
2472  </varlistentry>
2473  <varlistentry>
2474   <term><literal>.example.com/.*/index.html$</literal></term>
2475   <listitem>
2476    <para>
2477     Will match any page in the domain of <quote>example.com</quote> that is
2478     named <quote>index.html</quote>, and that is part of some path. For
2479     example, it matches <quote>www.example.com/testing/index.html</quote> but
2480     NOT <quote>www.example.com/index.html</quote> because the regular
2481     expression called for at least two <quote>/'s</quote>, thus the path 
2482     requirement. It also would match 
2483     <quote>www.example.com/testing/index_html</quote>, because of the 
2484     special meta-character <quote>.</quote>.
2485    </para>
2486   </listitem>
2487  </varlistentry>
2488  <varlistentry>
2489   <term><literal>.example.com/(.*/)?index\.html$</literal></term>
2490   <listitem>
2491    <para>
2492     This regular expression is conditional so it will match any page 
2493     named <quote>index.html</quote> regardless of path which in this case can 
2494     have one or more <quote>/'s</quote>. And this one must contain exactly 
2495     <quote>.html</quote> (but does not have to end with that!).
2496    </para>
2497   </listitem>
2498  </varlistentry>
2499  <varlistentry>
2500   <term><literal>.example.com/(.*/)(ads|banners?|junk)</literal></term>
2501   <listitem>
2502    <para>
2503     This regular expression will match any path of <quote>example.com</quote>
2504     that contains any of the words <quote>ads</quote>, <quote>banner</quote>, 
2505     <quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
2506     The path does not have to end in these words, just contain them.
2507    </para>
2508   </listitem>
2509  </varlistentry>
2510  <varlistentry>
2511   <term><literal>.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</literal></term>
2512   <listitem>
2513    <para>
2514     This is very much the same as above, except now it must end in either 
2515     <quote>.jpg</quote>, <quote>.jpeg</quote>, <quote>.gif</quote> or <quote>.png</quote>. So this 
2516     one is limited to common image formats.
2517    </para>
2518   </listitem>
2519  </varlistentry>
2520
2521 </variablelist>
2522 <para>
2523  There are many, many good examples to be found in <filename>default.action</filename>, 
2524  and more tutorials below in <link linkend="regex">Appendix on regular expressions</link>.
2525 </para>
2526
2527 </sect3>
2528
2529 <!--  ~  End section  ~  -->
2530
2531
2532 <!--   ~~~~~       New section      ~~~~~     -->
2533 <sect3 id="tag-pattern"><title>The Tag Pattern</title>
2534
2535 <para>
2536  Tag patterns are used to change the applying actions based on the
2537  request's tags. Tags can be created with either the
2538  <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
2539  or the  <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
2540 </para>
2541
2542 <para>
2543  Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
2544  can tell them apart from URL patterns. Everything after the colon
2545  including white space, is interpreted as a regular expression with
2546  path pattern syntax, except that tag patterns aren't left-anchored
2547  automatically (&my-app; doesn't silently add a <quote>^</quote>,
2548  you have to do it yourself if you need it).
2549 </para>
2550
2551 <para>
2552  To match all requests that are tagged with <quote>foo</quote>
2553  your pattern line should be <quote>TAG:^foo$</quote>,
2554  <quote>TAG:foo</quote> would work as well, but it would also
2555  match requests whose tags contain <quote>foo</quote> somewhere.
2556  <quote>TAG: foo</quote> wouldn't work as it requires white space.
2557 </para>
2558
2559 <para>
2560  Sections can contain URL and tag patterns at the same time,
2561  but tag patterns are checked after the URL patterns and thus
2562  always overrule them, even if they are located before the URL patterns.
2563 </para>
2564
2565 <para>
2566  Once a new tag is added, Privoxy checks right away if it's matched by one
2567  of the tag patterns and updates the action settings accordingly. As a result
2568  tags can be used to activate other tagger actions, as long as these other
2569  taggers look for headers that haven't already be parsed.
2570 </para>
2571
2572 <para>
2573  For example you could tag client requests which use the
2574  <literal>POST</literal> method,
2575  then use this tag to activate another tagger that adds a tag if cookies
2576  are sent, and then use a block action based on the cookie tag. This allows
2577  the outcome of one action, to be input into a subsequent action. However if
2578  you'd reverse the position of the described taggers, and activated the
2579  method tagger based on the cookie tagger, no method tags would be created.
2580  The method tagger would look for the request line, but at the time
2581  the cookie tag is created, the request line has already been parsed.
2582 </para>
2583
2584 <para>
2585  While this is a limitation you should be aware of, this kind of
2586  indirection is seldom needed anyway and even the example doesn't
2587  make too much sense.
2588 </para>
2589
2590 </sect3>
2591
2592 </sect2>
2593
2594 <!--  ~  End section  ~  -->
2595
2596
2597 <!--   ~~~~~       New section      ~~~~~     -->
2598
2599 <sect2 id="actions">
2600 <title>Actions</title>
2601 <para>
2602  All actions are disabled by default, until they are explicitly enabled
2603  somewhere in an actions file. Actions are turned on if preceded with a
2604  <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
2605  <literal>+action</literal> means <quote>do that action</quote>, e.g.
2606  <literal>+block</literal> means <quote>please block URLs that match the
2607  following patterns</quote>, and <literal>-block</literal> means <quote>don't
2608  block URLs that match the following patterns, even if <literal>+block</literal>
2609  previously applied.</quote>
2610
2611 </para>
2612
2613 <para> 
2614  Again, actions are invoked by placing them on a line, enclosed in curly braces and
2615  separated by whitespace, like in 
2616  <literal>{+some-action -some-other-action{some-parameter}}</literal>,
2617  followed by a list of URL patterns, one per line, to which they apply.
2618  Together, the actions line and the following pattern lines make up a section
2619  of the actions file. 
2620 </para>
2621
2622 <para> 
2623  Actions fall into three categories:
2624 </para>
2625
2626 <para>
2627  <itemizedlist>
2628  <listitem>
2629   <para>  
2630    Boolean, i.e the action can only be <quote>enabled</quote> or
2631    <quote>disabled</quote>. Syntax:
2632   </para>
2633   <para>
2634    <screen>
2635   +<replaceable class="function">name</replaceable>        # enable action <replaceable class="parameter">name</replaceable>
2636   -<replaceable class="function">name</replaceable>        # disable action <replaceable class="parameter">name</replaceable></screen>
2637   </para>
2638   <para>  
2639    Example: <literal>+handle-as-image</literal>
2640   </para>
2641  </listitem>
2642
2643
2644  <listitem>
2645   <para>  
2646    Parameterized, where some value is required in order to enable this type of action.
2647    Syntax:
2648   </para>
2649   <para>
2650    <screen>
2651   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}  # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
2652                # overwriting parameter from previous match if necessary
2653   -<replaceable class="function">name</replaceable>         # disable action. The parameter can be omitted</screen>
2654   </para>
2655   <para>
2656    Note that if the URL matches multiple positive forms of a parameterized action,
2657    the last match wins, i.e. the params from earlier matches are simply ignored.
2658   </para>
2659   <para>  
2660    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>
2661   </para>
2662  </listitem>
2663  
2664  <listitem>
2665   <para>  
2666    Multi-value. These look exactly like parameterized actions,
2667    but they behave differently: If the action applies multiple times to the
2668    same URL, but with different parameters, <emphasis>all</emphasis> the parameters
2669    from <emphasis>all</emphasis> matches are remembered. This is used for actions
2670    that can be executed for the same request repeatedly, like adding multiple
2671    headers, or filtering through multiple filters. Syntax:
2672   </para>
2673   <para>
2674    <screen>
2675   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
2676   -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
2677                 # If it was the last one left, disable the action.
2678   <replaceable class="parameter">-name</replaceable>          # disable this action completely and remove all parameters from the list</screen>
2679   </para>
2680   <para>  
2681    Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
2682    <literal>+filter{html-annoyances}</literal>
2683   </para>
2684  </listitem>
2685
2686  </itemizedlist>
2687 </para>
2688
2689 <para>
2690  If nothing is specified in any actions file, no <quote>actions</quote> are
2691  taken. So in this case <application>Privoxy</application> would just be a
2692  normal, non-blocking, non-filtering proxy. You must specifically enable the
2693  privacy and blocking features you need (although the provided default actions
2694  files will give a good starting point).
2695 </para>
2696
2697 <para>
2698  Later defined action sections always over-ride earlier ones of the same type.
2699  So exceptions to any rules you make, should come in the latter part of the file (or 
2700  in a file that is processed later when using multiple actions files such 
2701  as <filename>user.action</filename>). For multi-valued actions, the actions
2702  are applied in the order they are specified. Actions files are processed in
2703  the order they are defined in <filename>config</filename> (the default
2704  installation has three actions files). It also quite possible for any given
2705  URL to match more than one <quote>pattern</quote> (because of wildcards and
2706  regular expressions), and thus to trigger more than one set of actions! Last
2707  match wins.
2708 </para>
2709
2710 <!-- start actions listing -->
2711 <para>
2712  The list of valid <application>Privoxy</application> actions are:
2713 </para>
2714
2715
2716 <!-- ********************************************************** -->
2717 <!-- Please note the below defined actions use id's that are    -->
2718 <!-- probably linked from other places, so please don't change. -->
2719 <!--                                                            -->
2720 <!-- ********************************************************** -->
2721
2722
2723 <!--   ~~~~~       New section      ~~~~~     -->
2724
2725 <sect3 renderas="sect4" id="add-header">
2726 <title>add-header</title>
2727
2728 <variablelist>
2729  <varlistentry>
2730   <term>Typical use:</term>
2731   <listitem>
2732    <para>Confuse log analysis, custom applications</para>
2733   </listitem>
2734  </varlistentry>
2735
2736  <varlistentry>
2737   <term>Effect:</term>
2738   <listitem>
2739    <para>
2740     Sends a user defined HTTP header to the web server.
2741    </para>
2742   </listitem>
2743  </varlistentry>
2744
2745  <varlistentry>
2746   <term>Type:</term>
2747   <!-- boolean, parameterized, Multi-value -->
2748   <listitem>
2749    <para>Multi-value.</para>
2750   </listitem>
2751  </varlistentry>
2752  
2753  <varlistentry>
2754   <term>Parameter:</term>
2755   <listitem>
2756    <para>
2757     Any string value is possible. Validity of the defined HTTP headers is not checked.
2758     It is recommended that you use the <quote><literal>X-</literal></quote> prefix
2759     for custom headers.
2760    </para>
2761   </listitem>
2762  </varlistentry>
2763  
2764 <varlistentry>
2765   <term>Notes:</term>
2766   <listitem>
2767    <para>
2768     This action may be specified multiple times, in order to define multiple 
2769     headers. This is rarely needed for the typical user. If you don't know what 
2770     <quote>HTTP headers</quote> are, you definitely don't need to worry about this 
2771     one.
2772    </para>
2773   </listitem>
2774  </varlistentry>
2775
2776  <varlistentry>
2777   <term>Example usage:</term>
2778   <listitem>
2779     <para>
2780      <screen>+add-header{X-User-Tracking: sucks}</screen>
2781    </para>
2782   </listitem>
2783  </varlistentry>
2784 </variablelist>
2785 </sect3>
2786
2787
2788 <!--   ~~~~~       New section      ~~~~~     -->
2789 <sect3 renderas="sect4" id="block">
2790 <title>block</title>
2791
2792 <variablelist>
2793  <varlistentry>
2794   <term>Typical use:</term>
2795   <listitem>
2796    <para>Block ads or other unwanted content</para>
2797   </listitem>
2798  </varlistentry>
2799
2800  <varlistentry>
2801   <term>Effect:</term>
2802   <listitem>
2803    <para>
2804     Requests for URLs to which this action applies are blocked, i.e. the
2805     requests are trapped by &my-app; and the requested URL is never retrieved,
2806     but is answered locally with a substitute page or image, as determined by
2807     the <literal><link
2808     linkend="handle-as-image">handle-as-image</link></literal>,
2809     <literal><link
2810     linkend="set-image-blocker">set-image-blocker</link></literal>, and 
2811     <literal><link
2812     linkend="handle-as-empty-document">handle-as-empty-document</link></literal> actions.
2813     
2814    </para>
2815   </listitem>
2816  </varlistentry>
2817
2818  <varlistentry>
2819   <term>Type:</term>
2820   <!-- boolean, parameterized, Multi-value -->
2821   <listitem>
2822    <para>Parameterized.</para>
2823   </listitem>
2824  </varlistentry>
2825
2826  <varlistentry>
2827   <term>Parameter:</term>
2828   <listitem>
2829    <para>A block reason that should be given to the user.</para>
2830   </listitem>
2831  </varlistentry>
2832  
2833 <varlistentry>
2834   <term>Notes:</term>
2835   <listitem>
2836    <para>
2837     <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
2838     for requests to blocked pages. This page contains the block reason given as
2839     parameter, a link to find out why the block action applies, and a click-through
2840     to the blocked content (the latter only if the force feature is available and
2841     enabled).
2842    </para>
2843 <!--
2844 This doesn't actually work in all browser configuration and the user probably doesn't care anyway.
2845    <para>
2846     The <quote>BLOCKED</quote> page adapts to the available
2847     screen space -- it displays full-blown if space allows, or miniaturized and text-only
2848     if loaded into a small frame or window. If you are using <application>Privoxy</application>
2849     right now, you can take a look at the 
2850     <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
2851     page</ulink>.
2852    </para>
2853 -->
2854    <para> 
2855     A very important exception occurs if <emphasis>both</emphasis> 
2856     <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
2857     apply to the same request: it will then be replaced by an image. If 
2858     <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
2859     (see below) also applies, the type of image will be determined by its parameter,
2860     if not, the standard checkerboard pattern is sent.
2861    </para>
2862    <para>
2863     It is important to understand this process, in order 
2864     to understand how <application>Privoxy</application> deals with 
2865     ads and other unwanted content. Blocking is a core feature, and one 
2866     upon which various other features depend.
2867    </para>
2868    <para>
2869     The <literal><link linkend="filter">filter</link></literal>
2870     action can perform a very similar task, by <quote>blocking</quote>
2871     banner images and other content through rewriting the relevant URLs in the
2872     document's HTML source, so they don't get requested in the first place.
2873     Note that this is a totally different technique, and it's easy to confuse the two.
2874    </para>
2875   </listitem>
2876  </varlistentry>
2877
2878  <varlistentry>
2879   <term>Example usage (section):</term>
2880   <listitem>
2881     <para>
2882      <screen>{+block{No nasty stuff for you.}}
2883 # Block and replace with "blocked" page
2884  .nasty-stuff.example.com
2885
2886 {+block{Doubleclick banners.} +handle-as-image} 
2887 # Block and replace with image
2888  .ad.doubleclick.net
2889  .ads.r.us/banners/
2890
2891 {+block{Layered ads.} +handle-as-empty-document} 
2892 # Block and then ignore
2893  adserver.example.net/.*\.js$</screen>
2894     </para>
2895   </listitem>
2896  </varlistentry>
2897
2898
2899 </variablelist>
2900 </sect3>
2901
2902
2903 <!--   ~~~~~       New section      ~~~~~     -->
2904 <sect3 renderas="sect4" id="client-header-filter">
2905 <title>client-header-filter</title>
2906
2907 <variablelist>
2908  <varlistentry>
2909   <term>Typical use:</term>
2910   <listitem>
2911    <para>
2912    Rewrite or remove single client headers.
2913    </para>
2914   </listitem>
2915  </varlistentry>
2916
2917  <varlistentry>
2918   <term>Effect:</term>
2919   <listitem>
2920    <para>
2921     All client headers to which this action applies are filtered on-the-fly through
2922     the specified regular expression based substitutions.
2923    </para>
2924   </listitem>
2925  </varlistentry>
2926
2927  <varlistentry>
2928   <term>Type:</term>
2929   <!-- boolean, parameterized, Multi-value -->
2930   <listitem>
2931    <para>Parameterized.</para>
2932   </listitem>
2933  </varlistentry>
2934
2935  <varlistentry>
2936   <term>Parameter:</term>
2937   <listitem>
2938    <para>
2939     The name of a client-header filter, as defined in one of the
2940     <link linkend="filter-file">filter files</link>.
2941    </para>
2942   </listitem>
2943  </varlistentry>
2944  
2945  <varlistentry>
2946   <term>Notes:</term>
2947   <listitem>
2948    <para>
2949     Client-header filters are applied to each header on its own, not to
2950     all at once. This makes it easier to diagnose problems, but on the downside
2951     you can't write filters that only change header x if header y's value is z.
2952     You can do that by using tags though.
2953    </para>
2954    <para>
2955     Client-header filters are executed after the other header actions have finished
2956     and use their output as input.
2957    </para>
2958    <para>
2959     If the request URL gets changed, &my-app; will detect that and use the new
2960     one. This can be used to rewrite the request destination behind the client's
2961     back, for example to specify a Tor exit relay for certain requests.
2962    </para>
2963    <para>
2964     Please refer to the <link linkend="filter-file">filter file chapter</link>
2965     to learn which client-header filters are available by default, and how to
2966     create your own.
2967    </para>
2968
2969   </listitem>
2970  </varlistentry>
2971
2972  <varlistentry>
2973   <term>Example usage (section):</term>
2974   <listitem>
2975     <para>
2976      <screen>
2977 # Hide Tor exit notation in Host and Referer Headers
2978 {+client-header-filter{hide-tor-exit-notation}}
2979 /
2980     </screen>
2981     </para>
2982   </listitem>
2983  </varlistentry>
2984
2985 </variablelist>
2986 </sect3>
2987
2988
2989 <!--   ~~~~~       New section      ~~~~~     -->
2990 <sect3 renderas="sect4" id="client-header-tagger">
2991 <title>client-header-tagger</title>
2992
2993 <variablelist>
2994  <varlistentry>
2995   <term>Typical use:</term>
2996   <listitem>
2997    <para>
2998    Block requests based on their headers.
2999    </para>
3000   </listitem>
3001  </varlistentry>
3002
3003  <varlistentry>
3004   <term>Effect:</term>
3005   <listitem>
3006    <para>
3007     Client headers to which this action applies are filtered on-the-fly through
3008     the specified regular expression based substitutions, the result is used as
3009     tag. 
3010    </para>
3011   </listitem>
3012  </varlistentry>
3013
3014  <varlistentry>
3015   <term>Type:</term>
3016   <!-- boolean, parameterized, Multi-value -->
3017   <listitem>
3018    <para>Parameterized.</para>
3019   </listitem>
3020  </varlistentry>
3021
3022  <varlistentry>
3023   <term>Parameter:</term>
3024   <listitem>
3025    <para>
3026     The name of a client-header tagger, as defined in one of the
3027     <link linkend="filter-file">filter files</link>.
3028    </para>
3029   </listitem>
3030  </varlistentry>
3031  
3032  <varlistentry>
3033   <term>Notes:</term>
3034   <listitem>
3035    <para>
3036     Client-header taggers are applied to each header on its own,
3037     and as the header isn't modified, each tagger <quote>sees</quote>
3038     the original.
3039    </para>
3040    <para>
3041     Client-header taggers are the first actions that are executed
3042     and their tags can be used to control every other action.
3043    </para>
3044  </listitem>
3045  </varlistentry>
3046
3047  <varlistentry>
3048   <term>Example usage (section):</term>
3049   <listitem>
3050     <para>
3051      <screen>
3052 # Tag every request with the User-Agent header
3053 {+client-header-tagger{user-agent}}
3054 /
3055     </screen>
3056     </para>
3057   </listitem>
3058  </varlistentry>
3059
3060 </variablelist>
3061 </sect3>
3062
3063
3064 <!--   ~~~~~       New section      ~~~~~     -->
3065 <sect3 renderas="sect4" id="content-type-overwrite">
3066 <title>content-type-overwrite</title>
3067
3068 <variablelist>
3069  <varlistentry>
3070   <term>Typical use:</term>
3071   <listitem>
3072    <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
3073   </listitem>
3074  </varlistentry>
3075
3076  <varlistentry>
3077   <term>Effect:</term>
3078   <listitem>
3079    <para>
3080     Replaces the <quote>Content-Type:</quote> HTTP server header.
3081    </para>
3082   </listitem>
3083  </varlistentry>
3084
3085  <varlistentry>
3086   <term>Type:</term>
3087   <!-- Boolean, Parameterized, Multi-value -->
3088   <listitem>
3089    <para>Parameterized.</para>
3090   </listitem>
3091  </varlistentry>
3092
3093  <varlistentry>
3094   <term>Parameter:</term>
3095   <listitem>
3096    <para>
3097     Any string. 
3098    </para>    
3099   </listitem>
3100  </varlistentry>
3101  
3102  <varlistentry>
3103   <term>Notes:</term>
3104   <listitem>
3105    <para>
3106     The <quote>Content-Type:</quote> HTTP server header is used by the
3107     browser to decide what to do with the document. The value of this
3108     header can cause the browser to open a download menu instead of
3109     displaying the document by itself, even if the document's format is
3110     supported by the browser. 
3111    </para>
3112    <para>
3113     The declared content type can also affect which rendering mode
3114     the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
3115     many browsers treat it as yet another broken HTML document.
3116     If it is send as <quote>application/xml</quote>, browsers with
3117     XHTML support will only display it, if the syntax is correct.
3118    </para>
3119    <para>
3120     If you see a web site that proudly uses XHTML buttons, but sets
3121     <quote>Content-Type: text/html</quote>, you can use &my-app;
3122     to overwrite it with <quote>application/xml</quote> and validate
3123     the web master's claim inside your XHTML-supporting browser.
3124     If the syntax is incorrect, the browser will complain loudly. 
3125    </para>
3126    <para>
3127     You can also go the opposite direction: if your browser prints
3128     error messages instead of rendering a document falsely declared
3129     as XHTML, you can overwrite the content type with
3130     <quote>text/html</quote> and have it rendered as broken HTML document. 
3131    </para>
3132    <para>
3133     By default <literal>content-type-overwrite</literal> only replaces
3134     <quote>Content-Type:</quote> headers that look like some kind of text.
3135     If you want to overwrite it unconditionally, you have to combine it with
3136     <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
3137     This limitation exists for a reason, think twice before circumventing it.
3138    </para>
3139    <para>
3140     Most of the time it's easier to replace this action with a custom
3141     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3142     It allows you to activate it for every document of a certain site and it will still
3143     only replace the content types you aimed at.
3144    </para>
3145    <para>
3146     Of course you can apply <literal>content-type-overwrite</literal>
3147     to a whole site and then make URL based exceptions, but it's a lot
3148     more work to get the same precision. 
3149    </para>
3150   </listitem>
3151  </varlistentry>
3152
3153  <varlistentry>
3154   <term>Example usage (sections):</term>
3155   <listitem>
3156     <para>
3157      <screen># Check if www.example.net/ really uses valid XHTML
3158 { +content-type-overwrite{application/xml} }
3159 www.example.net/
3160
3161 # but leave the content type unmodified if the URL looks like a style sheet
3162 {-content-type-overwrite}
3163 www.example.net/.*\.css$
3164 www.example.net/.*style
3165 </screen>
3166    </para>
3167   </listitem>
3168  </varlistentry>
3169 </variablelist>
3170 </sect3>
3171
3172
3173 <!--   ~~~~~       New section      ~~~~~     -->
3174 <sect3 renderas="sect4" id="crunch-client-header">
3175 <!--
3176 new action
3177 -->
3178 <title>crunch-client-header</title>
3179
3180 <variablelist>
3181  <varlistentry>
3182   <term>Typical use:</term>
3183   <listitem>
3184    <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
3185   </listitem>
3186  </varlistentry>
3187
3188  <varlistentry>
3189   <term>Effect:</term>
3190   <listitem>
3191    <para>
3192     Deletes every header sent by the client that contains the string the user supplied as parameter.
3193    </para>
3194   </listitem>
3195  </varlistentry>
3196
3197  <varlistentry>
3198   <term>Type:</term>
3199   <!-- Boolean, Parameterized, Multi-value -->
3200   <listitem>
3201    <para>Parameterized.</para>
3202   </listitem>
3203  </varlistentry>
3204
3205  <varlistentry>
3206   <term>Parameter:</term>
3207   <listitem>
3208    <para>
3209     Any string.
3210    </para>    
3211   </listitem>
3212  </varlistentry>
3213  
3214  <varlistentry>
3215   <term>Notes:</term>
3216   <listitem>
3217    <para>
3218     This action allows you to block client headers for which no dedicated
3219     <application>Privoxy</application> action exists.
3220     <application>Privoxy</application> will remove every client header that
3221     contains the string you supplied as parameter.
3222    </para>
3223    <para>
3224     Regular expressions are <emphasis>not supported</emphasis> and you can't
3225     use this action to block different headers in the same request, unless
3226     they contain the same string.
3227    </para>
3228    <para>
3229     <literal>crunch-client-header</literal> is only meant for quick tests.
3230     If you have to block several different headers, or only want to modify
3231     parts of them, you should use a
3232     <literal><link linkend="client-header-filter">client-header filter</link></literal>.
3233    </para>
3234     <warning>
3235      <para>
3236       Don't block any header without understanding the consequences.
3237      </para>
3238     </warning>
3239   </listitem>
3240  </varlistentry>
3241
3242  <varlistentry>
3243   <term>Example usage (section):</term>
3244   <listitem>
3245     <para>
3246      <screen># Block the non-existent "Privacy-Violation:" client header 
3247 { +crunch-client-header{Privacy-Violation:} }
3248 /
3249     </screen>
3250    </para>
3251   </listitem>
3252  </varlistentry>
3253 </variablelist>
3254 </sect3>
3255
3256
3257 <!--   ~~~~~       New section      ~~~~~     -->
3258 <sect3 renderas="sect4" id="crunch-if-none-match">
3259 <title>crunch-if-none-match</title>
3260 <!--
3261 new action
3262 -->
3263 <variablelist>
3264  <varlistentry>
3265   <term>Typical use:</term>
3266   <listitem>
3267    <para>Prevent yet another way to track the user's steps between sessions.</para>
3268   </listitem>
3269  </varlistentry>
3270
3271  <varlistentry>
3272   <term>Effect:</term>
3273   <listitem>
3274    <para>
3275     Deletes the <quote>If-None-Match:</quote> HTTP client header.
3276    </para>
3277   </listitem>
3278  </varlistentry>
3279
3280  <varlistentry>
3281   <term>Type:</term>
3282   <!-- Boolean, Parameterized, Multi-value -->
3283   <listitem>
3284    <para>Boolean.</para>
3285   </listitem>
3286  </varlistentry>
3287
3288  <varlistentry>
3289   <term>Parameter:</term>
3290   <listitem>
3291    <para>
3292     N/A
3293    </para>    
3294   </listitem>
3295  </varlistentry>
3296  
3297  <varlistentry>
3298   <term>Notes:</term>
3299   <listitem>
3300    <para>
3301     Removing the <quote>If-None-Match:</quote> HTTP client header
3302     is useful for filter testing, where you want to force a real
3303     reload instead of getting status code <quote>304</quote> which
3304     would cause the browser to use a cached copy of the page.
3305    </para>
3306    <para>
3307     It is also useful to make sure the header isn't used as a cookie
3308     replacement (unlikely but possible).
3309    </para>
3310    <para>
3311     Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
3312     caching problems, as long as the <quote>If-Modified-Since:</quote> header
3313     isn't blocked or missing as well.
3314    </para>
3315    <para>
3316     It is recommended to use this action together with
3317     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
3318     and
3319     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
3320    </para>
3321   </listitem>
3322  </varlistentry>
3323
3324  <varlistentry>
3325   <term>Example usage (section):</term>
3326   <listitem>
3327     <para>
3328      <screen># Let the browser revalidate cached documents but don't
3329 # allow the server to use the revalidation headers for user tracking.
3330 {+hide-if-modified-since{-60} \
3331  +overwrite-last-modified{randomize} \
3332  +crunch-if-none-match}
3333 /   </screen>
3334    </para>
3335   </listitem>
3336  </varlistentry>
3337 </variablelist>
3338 </sect3>
3339
3340
3341 <!--   ~~~~~       New section      ~~~~~     -->
3342 <sect3 renderas="sect4" id="crunch-incoming-cookies">
3343 <title>crunch-incoming-cookies</title>
3344
3345 <variablelist>
3346  <varlistentry>
3347   <term>Typical use:</term>
3348   <listitem>
3349    <para>
3350     Prevent the web server from setting HTTP cookies on your system
3351    </para>
3352   </listitem>
3353  </varlistentry>
3354
3355  <varlistentry>
3356   <term>Effect:</term>
3357   <listitem>
3358    <para>
3359     Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
3360    </para>
3361   </listitem>
3362  </varlistentry>
3363
3364  <varlistentry>
3365   <term>Type:</term>
3366   <!-- Boolean, Parameterized, Multi-value -->
3367   <listitem>
3368    <para>Boolean.</para>
3369   </listitem>
3370  </varlistentry>
3371
3372  <varlistentry>
3373   <term>Parameter:</term>
3374   <listitem>
3375    <para>
3376     N/A
3377    </para>
3378   </listitem>
3379  </varlistentry>
3380  
3381  <varlistentry>
3382   <term>Notes:</term>
3383   <listitem>
3384    <para>
3385     This action is only concerned with <emphasis>incoming</emphasis> HTTP cookies. For
3386     <emphasis>outgoing</emphasis> HTTP cookies, use
3387     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
3388     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3389    </para>
3390    <para>
3391     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3392     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3393     since it would prevent the session cookies from being set. See also 
3394     <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
3395    </para>
3396   </listitem>
3397  </varlistentry>
3398
3399  <varlistentry>
3400   <term>Example usage:</term>
3401   <listitem>
3402    <para>
3403     <screen>+crunch-incoming-cookies</screen>
3404    </para>
3405   </listitem>
3406  </varlistentry>
3407 </variablelist>
3408 </sect3>
3409
3410
3411 <!--   ~~~~~       New section      ~~~~~     -->
3412 <sect3 renderas="sect4" id="crunch-server-header">
3413 <title>crunch-server-header</title>
3414 <!--
3415 new action
3416 -->
3417 <variablelist>
3418  <varlistentry>
3419   <term>Typical use:</term>
3420   <listitem>
3421    <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
3422   </listitem>
3423  </varlistentry>
3424
3425  <varlistentry>
3426   <term>Effect:</term>
3427   <listitem>
3428    <para>
3429     Deletes every header sent by the server that contains the string the user supplied as parameter.
3430    </para>
3431   </listitem>
3432  </varlistentry>
3433
3434  <varlistentry>
3435   <term>Type:</term>
3436   <!-- Boolean, Parameterized, Multi-value -->
3437   <listitem>
3438    <para>Parameterized.</para>
3439   </listitem>
3440  </varlistentry>
3441
3442  <varlistentry>
3443   <term>Parameter:</term>
3444   <listitem>
3445    <para>
3446     Any string.
3447    </para>    
3448   </listitem>
3449  </varlistentry>
3450  
3451  <varlistentry>
3452   <term>Notes:</term>
3453   <listitem>
3454    <para>
3455     This action allows you to block server headers for which no dedicated
3456     <application>Privoxy</application> action exists. <application>Privoxy</application>
3457     will remove every server header that contains the string you supplied as parameter.
3458    </para>
3459    <para>
3460     Regular expressions are <emphasis>not supported</emphasis> and you can't
3461     use this action to block different headers in the same request, unless
3462     they contain the same string.
3463    </para>
3464    <para>
3465     <literal>crunch-server-header</literal> is only meant for quick tests.
3466     If you have to block several different headers, or only want to modify
3467     parts of them, you should use a custom
3468     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3469    </para>
3470     <warning>
3471      <para>
3472      Don't block any header without understanding the consequences.
3473      </para>
3474     </warning>
3475   </listitem>
3476  </varlistentry>
3477
3478  <varlistentry>
3479   <term>Example usage (section):</term>
3480   <listitem>
3481     <para>
3482      <screen># Crunch server headers that try to prevent caching
3483 { +crunch-server-header{no-cache} }
3484 /   </screen>
3485    </para>
3486   </listitem>
3487  </varlistentry>
3488 </variablelist>
3489 </sect3>
3490
3491
3492 <!--   ~~~~~       New section      ~~~~~     -->
3493 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
3494 <title>crunch-outgoing-cookies</title>
3495
3496 <variablelist>
3497  <varlistentry>
3498   <term>Typical use:</term>
3499   <listitem>
3500    <para>
3501     Prevent the web server from reading any HTTP cookies from your system
3502    </para>
3503   </listitem>
3504  </varlistentry>
3505
3506  <varlistentry>
3507   <term>Effect:</term>
3508   <listitem>
3509    <para>
3510     Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
3511    </para>
3512   </listitem>
3513  </varlistentry>
3514
3515  <varlistentry>
3516   <term>Type:</term>
3517   <!-- Boolean, Parameterized, Multi-value -->
3518   <listitem>
3519    <para>Boolean.</para>
3520   </listitem>
3521  </varlistentry>
3522
3523  <varlistentry>
3524   <term>Parameter:</term>
3525   <listitem>
3526    <para>
3527     N/A
3528    </para>
3529   </listitem>
3530  </varlistentry>
3531  
3532  <varlistentry>
3533   <term>Notes:</term>
3534   <listitem>
3535    <para>
3536     This action is only concerned with <emphasis>outgoing</emphasis> HTTP cookies. For
3537     <emphasis>incoming</emphasis> HTTP cookies, use
3538     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
3539     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3540    </para>
3541    <para>
3542     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3543     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3544     since it would prevent the session cookies from being read.
3545    </para>
3546   </listitem>
3547  </varlistentry>
3548
3549  <varlistentry>
3550   <term>Example usage:</term>
3551   <listitem>
3552    <para>
3553     <screen>+crunch-outgoing-cookies</screen>
3554    </para>
3555   </listitem>
3556  </varlistentry>
3557
3558 </variablelist>
3559 </sect3>
3560
3561
3562 <!--   ~~~~~       New section      ~~~~~     -->
3563 <sect3 renderas="sect4" id="deanimate-gifs">
3564 <title>deanimate-gifs</title>
3565
3566 <variablelist>
3567  <varlistentry>
3568   <term>Typical use:</term>
3569   <listitem>
3570    <para>Stop those annoying, distracting animated GIF images.</para>
3571   </listitem>
3572  </varlistentry>
3573
3574  <varlistentry>
3575   <term>Effect:</term>
3576   <listitem>
3577    <para>
3578     De-animate GIF animations, i.e. reduce them to their first or last image.
3579    </para>
3580   </listitem>
3581  </varlistentry>
3582
3583  <varlistentry>
3584   <term>Type:</term>
3585   <!-- boolean, parameterized, Multi-value -->
3586   <listitem>
3587    <para>Parameterized.</para>
3588   </listitem>
3589  </varlistentry>
3590
3591  <varlistentry>
3592   <term>Parameter:</term>
3593   <listitem>
3594    <para>
3595     <quote>last</quote> or <quote>first</quote>
3596    </para>
3597   </listitem>
3598  </varlistentry>
3599  
3600  <varlistentry>
3601   <term>Notes:</term>
3602   <listitem>
3603    <para>
3604     This will also shrink the images considerably (in bytes, not pixels!). If
3605     the option <quote>first</quote> is given, the first frame of the animation
3606     is used as the replacement. If <quote>last</quote> is given, the last
3607     frame of the animation is used instead, which probably makes more sense for
3608     most banner animations, but also has the risk of not showing the entire
3609     last frame (if it is only a delta to an earlier frame).
3610    </para>
3611    <para>
3612     You can safely use this action with patterns that will also match non-GIF
3613     objects, because no attempt will be made at anything that doesn't look like
3614     a GIF.
3615    </para>
3616   </listitem>
3617  </varlistentry>
3618
3619  <varlistentry>
3620   <term>Example usage:</term>
3621   <listitem>
3622     <para>
3623       <screen>+deanimate-gifs{last}</screen>
3624     </para>
3625   </listitem>
3626  </varlistentry>
3627 </variablelist>
3628 </sect3>
3629
3630 <!--   ~~~~~       New section      ~~~~~     -->
3631 <sect3 renderas="sect4" id="downgrade-http-version">
3632 <title>downgrade-http-version</title>
3633
3634 <variablelist>
3635  <varlistentry>
3636   <term>Typical use:</term>
3637   <listitem>
3638    <para>Work around (very rare) problems with HTTP/1.1</para>
3639   </listitem>
3640  </varlis