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