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