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