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