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