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