4ea6bc0a1784f46cb7e2be4bb4baeb2d5fa28625
[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.30">
18 <!entity p-status "UNRELEASED">
19 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
20 <!entity % p-not-stable "INCLUDE">
21 <!entity % p-stable "IGNORE">
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-2021 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-2021 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="https://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="https://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="https://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="https://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="https://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="https://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="https://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="https://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     Note that to change the destination host for
2937     <link linkend="HTTPS-INSPECTION">https-inspected</link>
2938     requests a protocol and host has to be added to the URI.
2939    </para>
2940    <para>
2941     If <link linkend="HTTPS-INSPECTION">https inspection</link>
2942     is enabled, the protocol can be downgraded from https to http
2943     but upgrading a request from http to https is currently not
2944     supported.
2945    </para>
2946    <para>
2947     After detecting a rewrite, &my-app; does not update the actions
2948     used for the request based on the new host.
2949    </para>
2950    <para>
2951     Please refer to the <link linkend="filter-file">filter file chapter</link>
2952     to learn which client-header filters are available by default, and how to
2953     create your own.
2954    </para>
2955
2956   </listitem>
2957  </varlistentry>
2958
2959  <varlistentry>
2960   <term>Example usage (section):</term>
2961   <listitem>
2962      <screen>
2963 # Hide Tor exit notation in Host and Referer Headers
2964 {+client-header-filter{hide-tor-exit-notation}}
2965 /
2966 </screen>
2967   </listitem>
2968  </varlistentry>
2969
2970 </variablelist>
2971 </sect3>
2972
2973 <!--   ~~~~~       New section      ~~~~~     -->
2974 <sect3 renderas="sect4" id="client-body-filter">
2975 <title>client-body-filter</title>
2976
2977 <variablelist>
2978  <varlistentry>
2979   <term>Typical use:</term>
2980   <listitem>
2981    <para>
2982    Rewrite or remove client request body.
2983    </para>
2984   </listitem>
2985  </varlistentry>
2986
2987  <varlistentry>
2988   <term>Effect:</term>
2989   <listitem>
2990    <para>
2991     All request bodies to which this action applies are filtered on-the-fly through
2992     the specified regular expression based substitutions.
2993    </para>
2994   </listitem>
2995  </varlistentry>
2996
2997  <varlistentry>
2998   <term>Type:</term>
2999   <!-- boolean, parameterized, Multi-value -->
3000   <listitem>
3001    <para>Multi-value.</para>
3002   </listitem>
3003  </varlistentry>
3004
3005  <varlistentry>
3006   <term>Parameter:</term>
3007   <listitem>
3008    <para>
3009     The name of a client-body filter, as defined in one of the
3010     <link linkend="filter-file">filter files</link>.
3011    </para>
3012   </listitem>
3013  </varlistentry>
3014
3015  <varlistentry>
3016   <term>Notes:</term>
3017   <listitem>
3018    <para>
3019     Please refer to the <link linkend="filter-file">filter file chapter</link>
3020     to learn how to create your own client-body filters.
3021    </para>
3022    <para>
3023     The distribution <filename>default.filter</filename> file contains a selection of
3024     client-body filters for example purposes.
3025    </para>
3026    <para>
3027     The amount of data that can be filtered is limited by the
3028     <literal><link linkend="buffer-limit">buffer-limit</link></literal>
3029     option in the main <link linkend="config">config file</link>. The
3030     default is 4096 KB (4 Megs). Once this limit is exceeded, the whole
3031     request body is passed through unfiltered.
3032    </para>
3033   </listitem>
3034  </varlistentry>
3035
3036  <varlistentry>
3037   <term>Example usage (section):</term>
3038   <listitem>
3039      <screen>
3040 # Remove "test" everywhere in the request body
3041 {+client-body-filter{remove-test}}
3042 /
3043 </screen>
3044   </listitem>
3045  </varlistentry>
3046
3047 </variablelist>
3048 </sect3>
3049
3050
3051 <!--   ~~~~~       New section      ~~~~~     -->
3052 <sect3 renderas="sect4" id="client-header-tagger">
3053 <title>client-header-tagger</title>
3054
3055 <variablelist>
3056  <varlistentry>
3057   <term>Typical use:</term>
3058   <listitem>
3059    <para>
3060    Block requests based on their headers.
3061    </para>
3062   </listitem>
3063  </varlistentry>
3064
3065  <varlistentry>
3066   <term>Effect:</term>
3067   <listitem>
3068    <para>
3069     Client headers to which this action applies are filtered on-the-fly through
3070     the specified regular expression based substitutions, the result is used as
3071     tag.
3072    </para>
3073   </listitem>
3074  </varlistentry>
3075
3076  <varlistentry>
3077   <term>Type:</term>
3078   <!-- boolean, parameterized, Multi-value -->
3079   <listitem>
3080    <para>Multi-value.</para>
3081   </listitem>
3082  </varlistentry>
3083
3084  <varlistentry>
3085   <term>Parameter:</term>
3086   <listitem>
3087    <para>
3088     The name of a client-header tagger, as defined in one of the
3089     <link linkend="filter-file">filter files</link>.
3090    </para>
3091   </listitem>
3092  </varlistentry>
3093
3094  <varlistentry>
3095   <term>Notes:</term>
3096   <listitem>
3097    <para>
3098     Client-header taggers are applied to each header on its own,
3099     and as the header isn't modified, each tagger <quote>sees</quote>
3100     the original.
3101    </para>
3102    <para>
3103     Client-header taggers are the first actions that are executed
3104     and their tags can be used to control every other action.
3105    </para>
3106  </listitem>
3107  </varlistentry>
3108
3109  <varlistentry>
3110   <term>Example usage (section):</term>
3111   <listitem>
3112      <screen>
3113 # Tag every request with the User-Agent header
3114 {+client-header-tagger{user-agent}}
3115 /
3116
3117 # Tagging itself doesn't change the action
3118 # settings, sections with TAG patterns do:
3119 #
3120 # If it's a download agent, use a different forwarding proxy,
3121 # show the real User-Agent and make sure resume works.
3122 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
3123  -hide-if-modified-since      \
3124  -overwrite-last-modified     \
3125  -hide-user-agent             \
3126  -filter                      \
3127  -deanimate-gifs              \
3128 }
3129 TAG:^User-Agent: NetBSD-ftp/
3130 TAG:^User-Agent: Novell ZYPP Installer
3131 TAG:^User-Agent: RPM APT-HTTP/
3132 TAG:^User-Agent: fetch libfetch/
3133 TAG:^User-Agent: Ubuntu APT-HTTP/
3134 TAG:^User-Agent: MPlayer/
3135 </screen>
3136
3137      <screen>
3138 # Tag all requests with the Range header set
3139 {+client-header-tagger{range-requests}}
3140 /
3141
3142 # Disable filtering for the tagged requests.
3143 #
3144 # With filtering enabled Privoxy would remove the Range headers
3145 # to be able to filter the whole response. The downside is that
3146 # it prevents clients from resuming downloads or skipping over
3147 # parts of multimedia files.
3148 {-filter -deanimate-gifs}
3149 TAG:^RANGE-REQUEST$
3150 </screen>
3151
3152      <screen>
3153 # Tag all requests with the client IP address
3154 #
3155 # (Technically the client IP address isn't included in the
3156 # client headers but client-header taggers can set it anyway.
3157 # For details see the tagger in default.filter)
3158 {+client-header-tagger{client-ip-address}}
3159 /
3160
3161 # Change forwarding settings for requests coming from address 10.0.0.1
3162 {+forward-override{forward-socks5 127.0.1.2:2222 .}}
3163 TAG:^IP-ADDRESS: 10\.0\.0\.1$
3164 </screen>
3165   </listitem>
3166  </varlistentry>
3167
3168 </variablelist>
3169 </sect3>
3170
3171
3172 <!--   ~~~~~       New section      ~~~~~     -->
3173 <sect3 renderas="sect4" id="content-type-overwrite">
3174 <title>content-type-overwrite</title>
3175
3176 <variablelist>
3177  <varlistentry>
3178   <term>Typical use:</term>
3179   <listitem>
3180    <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
3181   </listitem>
3182  </varlistentry>
3183
3184  <varlistentry>
3185   <term>Effect:</term>
3186   <listitem>
3187    <para>
3188     Replaces the <quote>Content-Type:</quote> HTTP server header.
3189    </para>
3190   </listitem>
3191  </varlistentry>
3192
3193  <varlistentry>
3194   <term>Type:</term>
3195   <!-- Boolean, Parameterized, Multi-value -->
3196   <listitem>
3197    <para>Parameterized.</para>
3198   </listitem>
3199  </varlistentry>
3200
3201  <varlistentry>
3202   <term>Parameter:</term>
3203   <listitem>
3204    <para>
3205     Any string.
3206    </para>
3207   </listitem>
3208  </varlistentry>
3209
3210  <varlistentry>
3211   <term>Notes:</term>
3212   <listitem>
3213    <para>
3214     The <quote>Content-Type:</quote> HTTP server header is used by the
3215     browser to decide what to do with the document. The value of this
3216     header can cause the browser to open a download menu instead of
3217     displaying the document by itself, even if the document's format is
3218     supported by the browser.
3219    </para>
3220    <para>
3221     The declared content type can also affect which rendering mode
3222     the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
3223     many browsers treat it as yet another broken HTML document.
3224     If it is send as <quote>application/xml</quote>, browsers with
3225     XHTML support will only display it, if the syntax is correct.
3226    </para>
3227    <para>
3228     If you see a web site that proudly uses XHTML buttons, but sets
3229     <quote>Content-Type: text/html</quote>, you can use &my-app;
3230     to overwrite it with <quote>application/xml</quote> and validate
3231     the web master's claim inside your XHTML-supporting browser.
3232     If the syntax is incorrect, the browser will complain loudly.
3233    </para>
3234    <para>
3235     You can also go the opposite direction: if your browser prints
3236     error messages instead of rendering a document falsely declared
3237     as XHTML, you can overwrite the content type with
3238     <quote>text/html</quote> and have it rendered as broken HTML document.
3239    </para>
3240    <para>
3241     By default <literal>content-type-overwrite</literal> only replaces
3242     <quote>Content-Type:</quote> headers that look like some kind of text.
3243     If you want to overwrite it unconditionally, you have to combine it with
3244     <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
3245     This limitation exists for a reason, think twice before circumventing it.
3246    </para>
3247    <para>
3248     Most of the time it's easier to replace this action with a custom
3249     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3250     It allows you to activate it for every document of a certain site and it will still
3251     only replace the content types you aimed at.
3252    </para>
3253    <para>
3254     Of course you can apply <literal>content-type-overwrite</literal>
3255     to a whole site and then make URL based exceptions, but it's a lot
3256     more work to get the same precision.
3257    </para>
3258   </listitem>
3259  </varlistentry>
3260
3261  <varlistentry>
3262   <term>Example usage (sections):</term>
3263   <listitem>
3264      <screen># Check if www.example.net/ really uses valid XHTML
3265 { +content-type-overwrite{application/xml} }
3266 www.example.net/
3267
3268 # but leave the content type unmodified if the URL looks like a style sheet
3269 {-content-type-overwrite}
3270 www.example.net/.*\.css$
3271 www.example.net/.*style
3272 </screen>
3273   </listitem>
3274  </varlistentry>
3275 </variablelist>
3276 </sect3>
3277
3278
3279 <!--   ~~~~~       New section      ~~~~~     -->
3280 <sect3 renderas="sect4" id="crunch-client-header">
3281 <!--
3282 new action
3283 -->
3284 <title>crunch-client-header</title>
3285
3286 <variablelist>
3287  <varlistentry>
3288   <term>Typical use:</term>
3289   <listitem>
3290    <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
3291   </listitem>
3292  </varlistentry>
3293
3294  <varlistentry>
3295   <term>Effect:</term>
3296   <listitem>
3297    <para>
3298     Deletes every header sent by the client that contains the string the user supplied as parameter.
3299    </para>
3300   </listitem>
3301  </varlistentry>
3302
3303  <varlistentry>
3304   <term>Type:</term>
3305   <!-- Boolean, Parameterized, Multi-value -->
3306   <listitem>
3307    <para>Parameterized.</para>
3308   </listitem>
3309  </varlistentry>
3310
3311  <varlistentry>
3312   <term>Parameter:</term>
3313   <listitem>
3314    <para>
3315     Any string.
3316    </para>
3317   </listitem>
3318  </varlistentry>
3319
3320  <varlistentry>
3321   <term>Notes:</term>
3322   <listitem>
3323    <para>
3324     This action allows you to block client headers for which no dedicated
3325     <application>Privoxy</application> action exists.
3326     <application>Privoxy</application> will remove every client header that
3327     contains the string you supplied as parameter.
3328    </para>
3329    <para>
3330     Regular expressions are <emphasis>not supported</emphasis> and you can't
3331     use this action to block different headers in the same request, unless
3332     they contain the same string.
3333    </para>
3334    <para>
3335     <literal>crunch-client-header</literal> is only meant for quick tests.
3336     If you have to block several different headers, or only want to modify
3337     parts of them, you should use a
3338     <literal><link linkend="client-header-filter">client-header filter</link></literal>.
3339    </para>
3340     <warning>
3341      <para>
3342       Don't block any header without understanding the consequences.
3343      </para>
3344     </warning>
3345   </listitem>
3346  </varlistentry>
3347
3348  <varlistentry>
3349   <term>Example usage (section):</term>
3350   <listitem>
3351      <screen># Block the non-existent "Privacy-Violation:" client header
3352 { +crunch-client-header{Privacy-Violation:} }
3353 /
3354 </screen>
3355   </listitem>
3356  </varlistentry>
3357 </variablelist>
3358 </sect3>
3359
3360
3361 <!--   ~~~~~       New section      ~~~~~     -->
3362 <sect3 renderas="sect4" id="crunch-if-none-match">
3363 <title>crunch-if-none-match</title>
3364 <!--
3365 new action
3366 -->
3367 <variablelist>
3368  <varlistentry>
3369   <term>Typical use:</term>
3370   <listitem>
3371    <para>Prevent yet another way to track the user's steps between sessions.</para>
3372   </listitem>
3373  </varlistentry>
3374
3375  <varlistentry>
3376   <term>Effect:</term>
3377   <listitem>
3378    <para>
3379     Deletes the <quote>If-None-Match:</quote> HTTP client header.
3380    </para>
3381   </listitem>
3382  </varlistentry>
3383
3384  <varlistentry>
3385   <term>Type:</term>
3386   <!-- Boolean, Parameterized, Multi-value -->
3387   <listitem>
3388    <para>Boolean.</para>
3389   </listitem>
3390  </varlistentry>
3391
3392  <varlistentry>
3393   <term>Parameter:</term>
3394   <listitem>
3395    <para>
3396     N/A
3397    </para>
3398   </listitem>
3399  </varlistentry>
3400
3401  <varlistentry>
3402   <term>Notes:</term>
3403   <listitem>
3404    <para>
3405     Removing the <quote>If-None-Match:</quote> HTTP client header
3406     is useful for filter testing, where you want to force a real
3407     reload instead of getting status code <quote>304</quote> which
3408     would cause the browser to use a cached copy of the page.
3409    </para>
3410    <para>
3411     It is also useful to make sure the header isn't used as a cookie
3412     replacement (unlikely but possible).
3413    </para>
3414    <para>
3415     Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
3416     caching problems, as long as the <quote>If-Modified-Since:</quote> header
3417     isn't blocked or missing as well.
3418    </para>
3419    <para>
3420     It is recommended to use this action together with
3421     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
3422     and
3423     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
3424    </para>
3425   </listitem>
3426  </varlistentry>
3427
3428  <varlistentry>
3429   <term>Example usage (section):</term>
3430   <listitem>
3431      <screen># Let the browser revalidate cached documents but don't
3432 # allow the server to use the revalidation headers for user tracking.
3433 {+hide-if-modified-since{-60} \
3434  +overwrite-last-modified{randomize} \
3435  +crunch-if-none-match}
3436 /
3437 </screen>
3438   </listitem>
3439  </varlistentry>
3440 </variablelist>
3441 </sect3>
3442
3443
3444 <!--   ~~~~~       New section      ~~~~~     -->
3445 <sect3 renderas="sect4" id="crunch-incoming-cookies">
3446 <title>crunch-incoming-cookies</title>
3447
3448 <variablelist>
3449  <varlistentry>
3450   <term>Typical use:</term>
3451   <listitem>
3452    <para>
3453     Prevent the web server from setting HTTP cookies on your system
3454    </para>
3455   </listitem>
3456  </varlistentry>
3457
3458  <varlistentry>
3459   <term>Effect:</term>
3460   <listitem>
3461    <para>
3462     Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
3463    </para>
3464   </listitem>
3465  </varlistentry>
3466
3467  <varlistentry>
3468   <term>Type:</term>
3469   <!-- Boolean, Parameterized, Multi-value -->
3470   <listitem>
3471    <para>Boolean.</para>
3472   </listitem>
3473  </varlistentry>
3474
3475  <varlistentry>
3476   <term>Parameter:</term>
3477   <listitem>
3478    <para>
3479     N/A
3480    </para>
3481   </listitem>
3482  </varlistentry>
3483
3484  <varlistentry>
3485   <term>Notes:</term>
3486   <listitem>
3487    <para>
3488     This action is only concerned with <emphasis>incoming</emphasis> HTTP cookies. For
3489     <emphasis>outgoing</emphasis> HTTP cookies, use
3490     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
3491     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3492    </para>
3493    <para>
3494     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3495     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3496     since it would prevent the session cookies from being set. See also
3497     <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
3498    </para>
3499   </listitem>
3500  </varlistentry>
3501
3502  <varlistentry>
3503   <term>Example usage:</term>
3504   <listitem>
3505     <screen>+crunch-incoming-cookies</screen>
3506   </listitem>
3507  </varlistentry>
3508 </variablelist>
3509 </sect3>
3510
3511
3512 <!--   ~~~~~       New section      ~~~~~     -->
3513 <sect3 renderas="sect4" id="crunch-server-header">
3514 <title>crunch-server-header</title>
3515 <!--
3516 new action
3517 -->
3518 <variablelist>
3519  <varlistentry>
3520   <term>Typical use:</term>
3521   <listitem>
3522    <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
3523   </listitem>
3524  </varlistentry>
3525
3526  <varlistentry>
3527   <term>Effect:</term>
3528   <listitem>
3529    <para>
3530     Deletes every header sent by the server that contains the string the user supplied as parameter.
3531    </para>
3532   </listitem>
3533  </varlistentry>
3534
3535  <varlistentry>
3536   <term>Type:</term>
3537   <!-- Boolean, Parameterized, Multi-value -->
3538   <listitem>
3539    <para>Parameterized.</para>
3540   </listitem>
3541  </varlistentry>
3542
3543  <varlistentry>
3544   <term>Parameter:</term>
3545   <listitem>
3546    <para>
3547     Any string.
3548    </para>
3549   </listitem>
3550  </varlistentry>
3551
3552  <varlistentry>
3553   <term>Notes:</term>
3554   <listitem>
3555    <para>
3556     This action allows you to block server headers for which no dedicated
3557     <application>Privoxy</application> action exists. <application>Privoxy</application>
3558     will remove every server header that contains the string you supplied as parameter.
3559    </para>
3560    <para>
3561     Regular expressions are <emphasis>not supported</emphasis> and you can't
3562     use this action to block different headers in the same request, unless
3563     they contain the same string.
3564    </para>
3565    <para>
3566     <literal>crunch-server-header</literal> is only meant for quick tests.
3567     If you have to block several different headers, or only want to modify
3568     parts of them, you should use a custom
3569     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3570    </para>
3571     <warning>
3572      <para>
3573      Don't block any header without understanding the consequences.
3574      </para>
3575     </warning>
3576   </listitem>
3577  </varlistentry>
3578
3579  <varlistentry>
3580   <term>Example usage (section):</term>
3581   <listitem>
3582      <screen># Crunch server headers that try to prevent caching
3583 { +crunch-server-header{no-cache} }
3584 /
3585 </screen>
3586   </listitem>
3587  </varlistentry>
3588 </variablelist>
3589 </sect3>
3590
3591
3592 <!--   ~~~~~       New section      ~~~~~     -->
3593 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
3594 <title>crunch-outgoing-cookies</title>
3595
3596 <variablelist>
3597  <varlistentry>
3598   <term>Typical use:</term>
3599   <listitem>
3600    <para>
3601     Prevent the web server from reading any HTTP cookies from your system
3602    </para>
3603   </listitem>
3604  </varlistentry>
3605
3606  <varlistentry>
3607   <term>Effect:</term>
3608   <listitem>
3609    <para>
3610     Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
3611    </para>
3612   </listitem>
3613  </varlistentry>
3614
3615  <varlistentry>
3616   <term>Type:</term>
3617   <!-- Boolean, Parameterized, Multi-value -->
3618   <listitem>
3619    <para>Boolean.</para>
3620   </listitem>
3621  </varlistentry>
3622
3623  <varlistentry>
3624   <term>Parameter:</term>
3625   <listitem>
3626    <para>
3627     N/A
3628    </para>
3629   </listitem>
3630  </varlistentry>
3631
3632  <varlistentry>
3633   <term>Notes:</term>
3634   <listitem>
3635    <para>
3636     This action is only concerned with <emphasis>outgoing</emphasis> HTTP cookies. For
3637     <emphasis>incoming</emphasis> HTTP cookies, use
3638     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
3639     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3640    </para>
3641    <para>
3642     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3643     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3644     since it would prevent the session cookies from being read.
3645    </para>
3646   </listitem>
3647  </varlistentry>
3648
3649  <varlistentry>
3650   <term>Example usage:</term>
3651   <listitem>
3652     <screen>+crunch-outgoing-cookies</screen>
3653   </listitem>
3654  </varlistentry>
3655
3656 </variablelist>
3657 </sect3>
3658
3659
3660 <!--   ~~~~~       New section      ~~~~~     -->
3661 <sect3 renderas="sect4" id="deanimate-gifs">
3662 <title>deanimate-gifs</title>
3663
3664 <variablelist>
3665  <varlistentry>
3666   <term>Typical use:</term>
3667   <listitem>
3668    <para>Stop those annoying, distracting animated GIF images.</para>
3669   </listitem>
3670  </varlistentry>
3671
3672  <varlistentry>
3673   <term>Effect:</term>
3674   <listitem>
3675    <para>
3676     De-animate GIF animations, i.e. reduce them to their first or last image.
3677    </para>
3678   </listitem>
3679  </varlistentry>
3680
3681  <varlistentry>
3682   <term>Type:</term>
3683   <!-- boolean, parameterized, Multi-value -->
3684   <listitem>
3685    <para>Parameterized.</para>
3686   </listitem>
3687  </varlistentry>
3688
3689  <varlistentry>
3690   <term>Parameter:</term>
3691   <listitem>
3692    <para>
3693     <quote>last</quote> or <quote>first</quote>
3694    </para>
3695   </listitem>
3696  </varlistentry>
3697
3698  <varlistentry>
3699   <term>Notes:</term>
3700   <listitem>
3701    <para>
3702     This will also shrink the images considerably (in bytes, not pixels!). If
3703     the option <quote>first</quote> is given, the first frame of the animation
3704     is used as the replacement. If <quote>last</quote> is given, the last
3705     frame of the animation is used instead, which probably makes more sense for
3706     most banner animations, but also has the risk of not showing the entire
3707     last frame (if it is only a delta to an earlier frame).
3708    </para>
3709    <para>
3710     You can safely use this action with patterns that will also match non-GIF
3711     objects, because no attempt will be made at anything that doesn't look like
3712     a GIF.
3713    </para>
3714   </listitem>
3715  </varlistentry>
3716
3717  <varlistentry>
3718   <term>Example usage:</term>
3719   <listitem>
3720       <screen>+deanimate-gifs{last}</screen>
3721   </listitem>
3722  </varlistentry>
3723 </variablelist>
3724 </sect3>
3725
3726
3727 <!--   ~~~~~       New section      ~~~~~     -->
3728 <sect3 renderas="sect4" id="delay-response">
3729 <title>delay-response</title>
3730
3731 <variablelist>
3732  <varlistentry>
3733   <term>Typical use:</term>
3734   <listitem>
3735    <para>Delay responses to the client to reduce the load</para>
3736   </listitem>
3737  </varlistentry>
3738
3739  <varlistentry>
3740   <term>Effect:</term>
3741   <listitem>
3742    <para>
3743     Delays responses to the client by sending the response in ca. 10 byte chunks.
3744    </para>
3745   </listitem>
3746  </varlistentry>
3747
3748  <varlistentry>
3749   <term>Type:</term>
3750   <!-- boolean, parameterized, Multi-value -->
3751   <listitem>
3752    <para>Parameterized.</para>
3753   </listitem>
3754  </varlistentry>
3755
3756  <varlistentry>
3757   <term>Parameter:</term>
3758   <listitem>
3759    <para>
3760     <quote>Number of milliseconds</quote>
3761    </para>
3762   </listitem>
3763  </varlistentry>
3764
3765  <varlistentry>
3766   <term>Notes:</term>
3767   <listitem>
3768    <para>
3769     Sometimes when JavaScript code is used to fetch advertisements
3770     it doesn't respect Privoxy's blocks and retries to fetch the
3771     same resource again causing unnecessary load on the client.
3772    </para>
3773    <para>
3774     This action delays responses to the client and can be combined
3775     with <literal><link linkend="block">blocks</link></literal>
3776     to slow down the JavaScript code, thus reducing
3777     the load on the client.
3778    </para>
3779    <para>
3780     When used without <literal><link linkend="block">blocks</link></literal>
3781     the action can also be used to simulate a slow internet connection.
3782    </para>
3783   </listitem>
3784  </varlistentry>
3785
3786  <varlistentry>
3787   <term>Example usage:</term>
3788   <listitem>
3789       <screen>+delay-response{100}</screen>
3790   </listitem>
3791  </varlistentry>
3792 </variablelist>
3793 </sect3>
3794
3795
3796 <!--   ~~~~~       New section      ~~~~~     -->
3797 <sect3 renderas="sect4" id="downgrade-http-version">
3798 <title>downgrade-http-version</title>
3799
3800 <variablelist>
3801  <varlistentry>
3802   <term>Typical use:</term>
3803   <listitem>
3804    <para>Work around (very rare) problems with HTTP/1.1</para>
3805   </listitem>
3806  </varlistentry>
3807
3808  <varlistentry>
3809   <term>Effect:</term>
3810   <listitem>
3811    <para>
3812     Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3813    </para>
3814   </listitem>
3815  </varlistentry>
3816
3817  <varlistentry>
3818   <term>Type:</term>
3819   <!-- boolean, parameterized, Multi-value -->
3820   <listitem>
3821    <para>Boolean.</para>
3822   </listitem>
3823  </varlistentry>
3824
3825  <varlistentry>
3826   <term>Parameter:</term>
3827   <listitem>
3828    <para>
3829     N/A
3830    </para>
3831   </listitem>
3832  </varlistentry>
3833
3834 <varlistentry>
3835   <term>Notes:</term>
3836   <listitem>
3837    <para>
3838     This is a left-over from the time when <application>Privoxy</application>
3839     didn't support important HTTP/1.1 features well. It is left here for the
3840     unlikely case that you experience HTTP/1.1-related problems with some server
3841     out there.
3842    </para>
3843    <para>
3844     Note that enabling this action is only a workaround. It should not
3845     be enabled for sites that work without it. While it shouldn't break
3846     any pages, it has an (usually negative) performance impact.
3847   </para>
3848   <para>
3849     If you come across a site where enabling this action helps, please report it,
3850     so the cause of the problem can be analyzed. If the problem turns out to be
3851     caused by a bug in  <application>Privoxy</application> it should be
3852     fixed so the following release works without the work around.
3853    </para>
3854   </listitem>
3855  </varlistentry>
3856
3857  <varlistentry>
3858   <term>Example usage (section):</term>
3859   <listitem>
3860      <screen>{+downgrade-http-version}
3861 problem-host.example.com</screen>
3862   </listitem>
3863  </varlistentry>
3864
3865 </variablelist>
3866 </sect3>
3867
3868
3869 <!--   ~~~~~       New section      ~~~~~     -->
3870 <sect3 renderas="sect4" id="external-filter">
3871 <title>external-filter</title>
3872
3873 <variablelist>
3874  <varlistentry>
3875   <term>Typical use:</term>
3876   <listitem>
3877    <para>Modify content using a programming language of your choice.</para>
3878   </listitem>
3879  </varlistentry>
3880
3881  <varlistentry>
3882   <term>Effect:</term>
3883   <listitem>
3884    <para>
3885     All instances of text-based type, most notably HTML and JavaScript, to which
3886     this action applies, can be filtered on-the-fly through the specified external
3887     filter.
3888     By default plain text documents are exempted from filtering, because web
3889     servers often use the <literal>text/plain</literal> MIME type for all files
3890     whose type they don't know.)
3891    </para>
3892   </listitem>
3893  </varlistentry>
3894
3895  <varlistentry>
3896   <term>Type:</term>
3897   <!-- boolean, parameterized, Multi-value -->
3898   <listitem>
3899    <para>Multi-value.</para>
3900   </listitem>
3901  </varlistentry>
3902
3903  <varlistentry>
3904   <term>Parameter:</term>
3905   <listitem>
3906    <para>
3907     The name of an external content filter, as defined in the
3908     <link linkend="filter-file">filter file</link>.
3909     External filters can be defined in one or more files as defined by the
3910     <literal><link linkend="filterfile">filterfile</link></literal>
3911     option in the <link linkend="config">config file</link>.
3912    </para>
3913    <para>
3914     When used in its negative form,
3915     and without parameters, <emphasis>all</emphasis> filtering with external
3916     filters is completely disabled.
3917   </para>
3918   </listitem>
3919  </varlistentry>
3920
3921  <varlistentry>
3922   <term>Notes:</term>
3923   <listitem>
3924    <para>
3925     External filters are scripts or programs that can modify the content in
3926     case common <literal><link linkend="filter">filters</link></literal>
3927     aren't powerful enough. With the exception that this action doesn't
3928     use pcrs-based filters, the notes in the
3929     <literal><link linkend="filter">filter</link></literal> section apply.
3930    </para>
3931    <warning>
3932     <para>
3933      Currently external filters are executed with &my-app;'s privileges.
3934      Only use external filters you understand and trust.
3935     </para>
3936    </warning>
3937    <para>
3938     This feature is experimental, the <literal><link
3939     linkend="external-filter-syntax">syntax</link></literal>
3940     may change in the future.
3941    </para>
3942
3943   </listitem>
3944  </varlistentry>
3945
3946  <varlistentry>
3947   <term>Example usage:</term>
3948   <listitem>
3949     <screen>+external-filter{fancy-filter}</screen>
3950   </listitem>
3951  </varlistentry>
3952 </variablelist>
3953 </sect3>
3954
3955 <!--   ~~~~~       New section      ~~~~~     -->
3956 <sect3 renderas="sect4" id="fast-redirects">
3957 <title>fast-redirects</title>
3958
3959 <variablelist>
3960  <varlistentry>
3961   <term>Typical use:</term>
3962   <listitem>
3963    <para>Fool some click-tracking scripts and speed up indirect links.</para>
3964   </listitem>
3965  </varlistentry>
3966
3967  <varlistentry>
3968   <term>Effect:</term>
3969   <listitem>
3970    <para>
3971     Detects redirection URLs and redirects the browser without contacting
3972     the redirection server first.
3973    </para>
3974   </listitem>
3975  </varlistentry>
3976
3977  <varlistentry>
3978   <term>Type:</term>
3979   <!-- boolean, parameterized, Multi-value -->
3980   <listitem>
3981    <para>Parameterized.</para>
3982   </listitem>
3983  </varlistentry>
3984
3985  <varlistentry>
3986   <term>Parameter:</term>
3987   <listitem>
3988    <itemizedlist>
3989     <listitem>
3990      <para>
3991       <quote>simple-check</quote> to just search for the string <quote>http://</quote>
3992       to detect redirection URLs.
3993      </para>
3994     </listitem>
3995     <listitem>
3996      <para>
3997       <quote>check-decoded-url</quote> to decode URLs (if necessary) before searching
3998       for redirection URLs.
3999      </para>
4000     </listitem>
4001    </itemizedlist>
4002   </listitem>
4003  </varlistentry>
4004
4005  <varlistentry>
4006   <term>Notes:</term>
4007   <listitem>
4008    <para>
4009     Many sites, like yahoo.com, don't just link to other sites. Instead, they
4010     will link to some script on their own servers, giving the destination as a
4011     parameter, which will then redirect you to the final target. URLs
4012     resulting from this scheme typically look like:
4013     <quote>http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/</quote>.
4014   </para>
4015    <para>
4016     Sometimes, there are even multiple consecutive redirects encoded in the
4017     URL. These redirections via scripts make your web browsing more traceable,
4018     since the server from which you follow such a link can see where you go
4019     to. Apart from that, valuable bandwidth and time is wasted, while your
4020     browser asks the server for one redirect after the other. Plus, it feeds
4021     the advertisers.
4022    </para>
4023    <para>
4024     This feature is currently not very smart and is scheduled for improvement.
4025     If it is enabled by default, you will have to create some exceptions to
4026     this action. It can lead to failures in several ways:
4027    </para>
4028    <para>
4029     Not every URLs with other URLs as parameters is evil.
4030     Some sites offer a real service that requires this information to work.
4031     For example a validation service needs to know, which document to validate.
4032     <literal>fast-redirects</literal> assumes that every URL parameter that
4033     looks like another URL is a redirection target, and will always redirect to
4034     the last one. Most of the time the assumption is correct, but if it isn't,
4035     the user gets redirected anyway.
4036    </para>
4037    <para>
4038     Another failure occurs if the URL contains other parameters after the URL parameter.
4039     The URL:
4040     <quote>http://www.example.org/?redirect=http%3a//www.example.net/&amp;foo=bar</quote>.
4041     contains the redirection URL <quote>http://www.example.net/</quote>,
4042     followed by another parameter. <literal>fast-redirects</literal> doesn't know that
4043     and will cause a redirect to <quote>http://www.example.net/&amp;foo=bar</quote>.
4044     Depending on the target server configuration, the parameter will be silently ignored
4045     or lead to a <quote>page not found</quote> error. You can prevent this problem by
4046     first using the <literal><link linkend="redirect">redirect</link></literal> action
4047     to remove the last part of the URL, but it requires a little effort.
4048    </para>
4049    <para>
4050     To detect a redirection URL, <literal>fast-redirects</literal> only
4051     looks for the string <quote>http://</quote>, either in plain text
4052     (invalid but often used) or encoded as <quote>http%3a//</quote>.
4053     Some sites use their own URL encoding scheme, encrypt the address
4054     of the target server or replace it with a database id. In these cases
4055     <literal>fast-redirects</literal> is fooled and the request reaches the
4056     redirection server where it probably gets logged.
4057    </para>
4058   </listitem>
4059  </varlistentry>
4060
4061  <varlistentry>
4062   <term>Example usage:</term>
4063   <listitem>
4064      <screen>
4065  { +fast-redirects{simple-check} }
4066    one.example.com
4067
4068  { +fast-redirects{check-decoded-url} }
4069    another.example.com/testing</screen>
4070   </listitem>
4071  </varlistentry>
4072
4073 </variablelist>
4074 </sect3>
4075
4076
4077 <!--   ~~~~~       New section      ~~~~~     -->
4078 <sect3 renderas="sect4" id="filter">
4079 <title>filter</title>
4080
4081 <variablelist>
4082  <varlistentry>
4083   <term>Typical use:</term>
4084   <listitem>
4085    <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size),
4086          do fun text replacements, add personalized effects, etc.</para>
4087   </listitem>
4088  </varlistentry>
4089
4090  <varlistentry>
4091   <term>Effect:</term>
4092   <listitem>
4093    <para>
4094     All instances of text-based type, most notably HTML and JavaScript, to which
4095     this action applies, can be filtered on-the-fly through the specified regular
4096     expression based substitutions. (Note: as of version 3.0.3 plain text documents
4097     are exempted from filtering, because web servers often use the
4098    <literal>text/plain</literal> MIME type for all files whose type they don't know.)
4099    </para>
4100   </listitem>
4101  </varlistentry>
4102
4103  <varlistentry>
4104   <term>Type:</term>
4105   <!-- boolean, parameterized, Multi-value -->
4106   <listitem>
4107    <para>Multi-value.</para>
4108   </listitem>
4109  </varlistentry>
4110
4111  <varlistentry>
4112   <term>Parameter:</term>
4113   <listitem>
4114    <para>
4115     The name of a content filter, as defined in the <link linkend="filter-file">filter file</link>.
4116     Filters can be defined in one or more  files as defined by the
4117     <literal><link linkend="filterfile">filterfile</link></literal>
4118     option in the <link linkend="config">config file</link>.
4119     <filename>default.filter</filename> is the collection of filters
4120     supplied by the developers. Locally defined filters should go
4121     in their own file, such as <filename>user.filter</filename>.
4122    </para>
4123    <para>
4124      When used in its negative form,
4125      and without parameters, <emphasis>all</emphasis> filtering is completely disabled.
4126   </para>
4127   </listitem>
4128  </varlistentry>
4129
4130  <varlistentry>
4131   <term>Notes:</term>
4132   <listitem>
4133    <para>
4134     For your convenience, there are a number of pre-defined filters available
4135     in the distribution filter file that you can use. See the examples below for
4136     a list.
4137    </para>
4138    <para>
4139     Filtering requires buffering the page content, which may appear to
4140     slow down page rendering since nothing is displayed until all content has
4141     passed the filters. (The total time until the page is completely rendered
4142     doesn't change much, but it may be perceived as slower since the page is
4143     not incrementally displayed.)
4144     This effect will be more noticeable on slower connections.
4145    </para>
4146    <para>
4147    <quote>Rolling your own</quote>
4148     filters requires a knowledge of
4149      <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
4150      Expressions</quote></ulink> and
4151       <ulink url="https://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
4152     This is very powerful feature, and potentially very intrusive.
4153     Filters should be used with caution, and where an equivalent
4154     <quote>action</quote> is not available.
4155    </para>
4156    <para>
4157     The amount of data that can be filtered is limited by the
4158     <literal><link linkend="buffer-limit">buffer-limit</link></literal>
4159     option in the main <link linkend="config">config file</link>. The
4160     default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
4161     data, and all pending data, is passed through unfiltered.
4162    </para>
4163    <para>
4164     Inappropriate MIME types, such as zipped files, are not filtered at all.
4165     (Again, only text-based types except plain text). Encrypted SSL data
4166     (from HTTPS servers) cannot be filtered either, since this would violate
4167     the integrity of the secure transaction. In some situations it might
4168     be necessary to protect certain text, like source code, from filtering
4169     by defining appropriate <literal>-filter</literal> exceptions.
4170    </para>
4171    <para>
4172     Compressed content can't be filtered either, but if &my-app;
4173     is compiled with zlib support and a supported compression algorithm
4174     is used (gzip or deflate), &my-app; can first decompress the content
4175     and then filter it.
4176    </para>
4177    <para>
4178     If you use a &my-app; version without zlib support, but want filtering to work on
4179     as much documents as possible, even those that would normally be sent compressed,
4180     you must use the <literal><link linkend="prevent-compression">prevent-compression</link></literal>
4181     action in conjunction with <literal>filter</literal>.
4182    </para>
4183    <para>
4184     Content filtering can achieve some of the same effects as the
4185     <literal><link linkend="block">block</link></literal>
4186     action, i.e. it can be used to block ads and banners. But the mechanism
4187     works quite differently. One effective use, is to block ad banners
4188     based on their size (see below), since many of these seem to be somewhat
4189     standardized.
4190    </para>
4191    <para>
4192     <link linkend="contact">Feedback</link> with suggestions for new or
4193     improved filters is particularly welcome!
4194    </para>
4195    <para>
4196     The below list has only the names and a one-line description of each
4197     predefined filter. There are <link linkend="predefined-filters">more
4198     verbose explanations</link> of what these filters do in the <link
4199     linkend="filter-file">filter file chapter</link>.
4200    </para>
4201   </listitem>
4202  </varlistentry>
4203
4204  <varlistentry>
4205   <term>Example usage (with filters from the distribution <filename>default.filter</filename> file).
4206   See <link linkend="PREDEFINED-FILTERS">the Predefined Filters section</link> for
4207   more explanation on each:</term>
4208   <listitem>
4209    <para>
4210     <anchor id="filter-js-annoyances">
4211    </para>
4212     <screen>+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse.</screen>
4213    <para>
4214     <anchor id="filter-js-events">
4215    </para>
4216     <screen>+filter{js-events}           # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
4217    <para>
4218     <anchor id="filter-html-annoyances">
4219    </para>
4220     <screen>+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.</screen>
4221    <para>
4222     <anchor id="filter-content-cookies">
4223    </para>
4224     <screen>+filter{content-cookies}     # Kill cookies that come in the HTML or JS content.</screen>
4225    <para>
4226     <anchor id="filter-refresh-tags">
4227    </para>
4228     <screen>+filter{refresh-tags}        # Kill automatic refresh tags if refresh time is larger than 9 seconds.</screen>
4229    <para>
4230     <anchor id="filter-unsolicited-popups">
4231    </para>
4232     <screen>+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows.</screen>
4233    <para>
4234     <anchor id="filter-all-popups">
4235    </para>
4236     <screen>+filter{all-popups}          # Kill all popups in JavaScript and HTML.</screen>
4237    <para>
4238     <anchor id="filter-img-reorder">
4239    </para>
4240     <screen>+filter{img-reorder}         # Reorder attributes in &lt;img&gt; tags to make the banners-by-* filters more effective.</screen>
4241    <para>
4242     <anchor id="filter-banners-by-size">
4243    </para>
4244     <screen>+filter{banners-by-size}     # Kill banners by size.</screen>
4245    <para>
4246     <anchor id="filter-banners-by-link">
4247    </para>
4248     <screen>+filter{banners-by-link}     # Kill banners by their links to known clicktrackers.</screen>
4249    <para>
4250     <anchor id="filter-webbugs">
4251    </para>
4252     <screen>+filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
4253    <para>
4254     <anchor id="filter-tiny-textforms">
4255    </para>
4256     <screen>+filter{tiny-textforms}      # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
4257    <para>
4258     <anchor id="filter-jumping-windows">
4259    </para>
4260     <screen>+filter{jumping-windows}     # Prevent windows from resizing and moving themselves.</screen>
4261    <para>
4262     <anchor id="filter-frameset-borders">
4263    </para>
4264     <screen>+filter{frameset-borders}    # Give frames a border and make them resizable.</screen>
4265    <para>
4266     <anchor id="filter-iframes">
4267    </para>
4268     <screen>+filter{iframes}             # Removes all detected iframes. Should only be enabled for individual sites.</screen>
4269    <para>
4270     <anchor id="filter-demoronizer">
4271    </para>
4272     <screen>+filter{demoronizer}         # Fix MS's non-standard use of standard charsets.</screen>
4273    <para>
4274     <anchor id="filter-shockwave-flash">
4275    </para>
4276     <screen>+filter{shockwave-flash}     # Kill embedded Shockwave Flash objects.</screen>
4277    <para>
4278     <anchor id="filter-quicktime-kioskmode">
4279    </para>
4280     <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
4281    <para>
4282     <anchor id="filter-fun">
4283    </para>
4284     <screen>+filter{fun}                 # Text replacements for subversive browsing fun!</screen>
4285    <para>
4286     <anchor id="filter-crude-parental">
4287    </para>
4288     <screen>+filter{crude-parental}      # Crude parental filtering. Note that this filter doesn't work reliably.</screen>
4289    <para>
4290     <anchor id="filter-ie-exploits">
4291    </para>
4292     <screen>+filter{ie-exploits}         # Disable some known Internet Explorer bug exploits.</screen>
4293    <para>
4294     <anchor id="filter-site-specifics">
4295    </para>
4296     <screen>+filter{site-specifics}      # Cure for site-specific problems. Don't apply generally!</screen>
4297    <para>
4298     <anchor id="filter-no-ping">
4299    </para>
4300     <screen>+filter{no-ping}             # Removes non-standard ping attributes in &lt;a&gt; and &lt;area&gt; tags.</screen>
4301    <para>
4302     <anchor id="filter-github">
4303    </para>
4304     <screen>+filter{github}              # Removes the annoying "Sign-Up" banner and the Cookie disclaimer.</screen>
4305    <para>
4306     <anchor id="filter-google">
4307    </para>
4308     <screen>+filter{google}              # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
4309    <para>
4310     <anchor id="filter-yahoo">
4311    </para>
4312     <screen>+filter{yahoo}               # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
4313    <para>
4314     <anchor id="filter-msn">
4315    </para>
4316     <screen>+filter{msn}                 # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
4317    <para>
4318     <anchor id="filter-blogspot">
4319    </para>
4320     <screen>+filter{blogspot}            # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
4321    <para>
4322     <anchor id="filter-sourceforge">
4323    </para>
4324     <screen>+filter{sourceforge}         # Reduces the amount of ads for proprietary software on SourceForge.</screen>
4325   </listitem>
4326  </varlistentry>
4327 </variablelist>
4328 </sect3>
4329
4330
4331 <!--   ~~~~~       New section      ~~~~~     -->
4332 <sect3 renderas="sect4" id="force-text-mode">
4333 <title>force-text-mode</title>
4334 <!--
4335 new action
4336 -->
4337 <variablelist>
4338  <varlistentry>
4339   <term>Typical use:</term>
4340   <listitem>
4341    <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format.   </para>
4342   </listitem>
4343  </varlistentry>
4344
4345  <varlistentry>
4346   <term>Effect:</term>
4347   <listitem>
4348    <para>
4349     Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
4350    </para>
4351   </listitem>
4352  </varlistentry>
4353
4354  <varlistentry>
4355   <term>Type:</term>
4356   <!-- Boolean, Parameterized, Multi-value -->
4357   <listitem>
4358    <para>Boolean.</para>
4359   </listitem>
4360  </varlistentry>
4361
4362  <varlistentry>
4363   <term>Parameter:</term>
4364   <listitem>
4365    <para>
4366     N/A
4367    </para>
4368   </listitem>
4369  </varlistentry>
4370
4371  <varlistentry>
4372   <term>Notes:</term>
4373   <listitem>
4374    <para>
4375     As explained <literal><link linkend="filter">above</link></literal>,
4376     <application>Privoxy</application> tries to only filter files that are
4377     in some kind of text format. The same restrictions apply to
4378     <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
4379     <literal>force-text-mode</literal> declares a document as text,
4380     without looking at the <quote>Content-Type:</quote> first.
4381    </para>
4382    <warning>
4383     <para>
4384      Think twice before activating this action. Filtering binary data
4385      with regular expressions can cause file damage.
4386     </para>
4387    </warning>
4388   </listitem>
4389  </varlistentry>
4390
4391  <varlistentry>
4392   <term>Example usage:</term>
4393   <listitem>
4394      <screen>
4395 +force-text-mode
4396 </screen>
4397   </listitem>
4398  </varlistentry>
4399 </variablelist>
4400 </sect3>
4401
4402
4403 <!--   ~~~~~       New section      ~~~~~     -->
4404 <sect3 renderas="sect4" id="forward-override">
4405 <title>forward-override</title>
4406 <!--
4407 new action
4408 -->
4409 <variablelist>
4410  <varlistentry>
4411   <term>Typical use:</term>
4412   <listitem>
4413    <para>Change the forwarding settings based on User-Agent or request origin</para>
4414   </listitem>
4415  </varlistentry>
4416
4417  <varlistentry>
4418   <term>Effect:</term>
4419   <listitem>
4420    <para>
4421     Overrules the forward directives in the configuration file.
4422    </para>
4423   </listitem>
4424  </varlistentry>
4425
4426  <varlistentry>
4427   <term>Type:</term>
4428   <!-- Boolean, Parameterized, Multi-value -->
4429   <listitem>
4430    <para>Parameterized.</para>
4431   </listitem>
4432  </varlistentry>
4433
4434  <varlistentry>
4435   <term>Parameter:</term>
4436   <listitem>
4437    <itemizedlist>
4438     <listitem>
4439      <para><quote>forward .</quote> to use a direct connection without any additional proxies.</para>
4440     </listitem>
4441     <listitem>
4442      <para>
4443       <quote>forward 127.0.0.1:8123</quote> to use the HTTP proxy listening at 127.0.0.1 port 8123.
4444      </para>
4445     </listitem>
4446     <listitem>
4447      <para>
4448       <quote>forward-socks4a 127.0.0.1:9050 .</quote> to use the socks4a proxy listening at
4449       127.0.0.1 port 9050. Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote>
4450       to use a socks4 connection  (with local DNS resolution) instead, use <quote>forward-socks5</quote>
4451       for socks5 connections (with remote DNS resolution).
4452      </para>
4453     </listitem>
4454     <listitem>
4455      <para>
4456       <quote>forward-socks4a 127.0.0.1:9050 proxy.example.org:8000</quote> to use the socks4a proxy
4457       listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
4458       Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection
4459       (with local DNS resolution) instead, use <quote>forward-socks5</quote>
4460       for socks5 connections (with remote DNS resolution).
4461      </para>
4462     </listitem>
4463     <listitem>
4464      <para>
4465       <quote>forward-webserver 127.0.0.1:80</quote> to use the HTTP
4466       server listening at 127.0.0.1 port 80 without adjusting the
4467       request headers.
4468      </para>
4469      <para>
4470       This makes it more convenient to use Privoxy to make
4471       existing websites available as onion services as well.
4472      </para>
4473      <para>
4474       Many websites serve content with hardcoded URLs and
4475       can't be easily adjusted to change the domain based
4476       on the one used by the client.
4477      </para>
4478      <para>
4479       Putting Privoxy between Tor and the webserver (or an stunnel
4480       that forwards to the webserver) allows to rewrite headers and
4481       content to make client and server happy at the same time.
4482      </para>
4483      <para>
4484       Using Privoxy for webservers that are only reachable through
4485       onion addresses and whose location is supposed to be secret
4486       is not recommended and should not be necessary anyway.
4487      </para>
4488     </listitem>
4489    </itemizedlist>
4490   </listitem>
4491  </varlistentry>
4492
4493  <varlistentry>
4494   <term>Notes:</term>
4495   <listitem>
4496    <para>
4497     This action takes parameters similar to the
4498     <link linkend="forwarding">forward</link> directives in the configuration
4499     file, but without the URL pattern. It can be used as replacement, but normally it's only
4500     used in cases where matching based on the request URL isn't sufficient.
4501    </para>
4502    <warning>
4503     <para>
4504      Please read the description for the <link linkend="forwarding">forward</link> directives before
4505      using this action. Forwarding to the wrong people will reduce your privacy and increase the
4506      chances of man-in-the-middle attacks.
4507     </para>
4508     <para>
4509      If the ports are missing or invalid, default values will be used. This might change
4510      in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
4511      to exit. Due to design limitations, invalid parameter syntax isn't detected until the
4512      action is used the first time.
4513     </para>
4514     <para>
4515      Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
4516      to verify that your forward settings do what you thought the do.
4517     </para>
4518    </warning>
4519   </listitem>
4520  </varlistentry>
4521
4522  <varlistentry>
4523   <term>Example usage:</term>
4524   <listitem>
4525      <screen>
4526 # Use an ssh tunnel for requests previously tagged as
4527 # <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
4528 # resuming downloads continues to work.
4529 #
4530 # This way you can continue to use Tor for your normal browsing,
4531 # without overloading the Tor network with your FreeBSD ports updates
4532 # or downloads of bigger files like ISOs.
4533 #
4534 # Note that HTTP headers are easy to fake and therefore their
4535 # values are as (un)trustworthy as your clients and users.
4536 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
4537  -hide-if-modified-since      \
4538  -overwrite-last-modified     \
4539 }
4540 TAG:^User-Agent: fetch libfetch/2\.0$
4541 </screen>
4542   </listitem>
4543  </varlistentry>
4544 </variablelist>
4545 </sect3>
4546
4547
4548 <!--   ~~~~~       New section      ~~~~~     -->
4549 <sect3 renderas="sect4" id="handle-as-empty-document">
4550 <title>handle-as-empty-document</title>
4551 <!--
4552 new action
4553 -->
4554 <variablelist>
4555  <varlistentry>
4556   <term>Typical use:</term>
4557   <listitem>
4558    <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
4559   </listitem>
4560  </varlistentry>
4561
4562  <varlistentry>
4563   <term>Effect:</term>
4564   <listitem>
4565    <para>
4566     This action alone doesn't do anything noticeable. It just marks URLs.
4567     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4568     the presence or absence of this mark decides whether an HTML <quote>BLOCKED</quote>
4569     page, or an empty document will be sent to the client as a substitute for the blocked content.
4570     The <emphasis>empty</emphasis> document isn't literally empty, but actually contains a single space.
4571    </para>
4572   </listitem>
4573  </varlistentry>
4574
4575  <varlistentry>
4576   <term>Type:</term>
4577   <!-- Boolean, Parameterized, Multi-value -->
4578   <listitem>
4579    <para>Boolean.</para>
4580   </listitem>
4581  </varlistentry>
4582
4583  <varlistentry>
4584   <term>Parameter:</term>
4585   <listitem>
4586    <para>
4587     N/A
4588    </para>
4589   </listitem>
4590  </varlistentry>
4591
4592  <varlistentry>
4593   <term>Notes:</term>
4594   <listitem>
4595    <para>
4596     Some browsers complain about syntax errors if JavaScript documents
4597     are blocked with <application>Privoxy's</application>
4598     default HTML page; this option can be used to silence them.
4599     And of course this action can also be used to eliminate the &my-app;
4600     BLOCKED message in frames.
4601    </para>
4602    <para>
4603     The content type for the empty document can be specified with
4604     <literal><link linkend="content-type-overwrite">content-type-overwrite{}</link></literal>,
4605     but usually this isn't necessary.
4606    </para>
4607   </listitem>
4608  </varlistentry>
4609
4610  <varlistentry>
4611   <term>Example usage:</term>
4612   <listitem>
4613      <screen># Block all documents on example.org that end with ".js",
4614 # but send an empty document instead of the usual HTML message.
4615 {+block{Blocked JavaScript} +handle-as-empty-document}
4616 example.org/.*\.js$
4617 </screen>
4618   </listitem>
4619  </varlistentry>
4620 </variablelist>
4621 </sect3>
4622
4623
4624 <!--   ~~~~~       New section      ~~~~~     -->
4625 <sect3 renderas="sect4" id="handle-as-image">
4626 <title>handle-as-image</title>
4627
4628 <variablelist>
4629  <varlistentry>
4630   <term>Typical use:</term>
4631   <listitem>
4632    <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they do get blocked</emphasis>, rather than HTML pages)</para>
4633   </listitem>
4634  </varlistentry>
4635
4636  <varlistentry>
4637   <term>Effect:</term>
4638   <listitem>
4639    <para>
4640     This action alone doesn't do anything noticeable. It just marks URLs as images.
4641     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4642     the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
4643     page, or a replacement image (as determined by the <literal><link
4644     linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
4645     client as a substitute for the blocked content.
4646    </para>
4647   </listitem>
4648  </varlistentry>
4649
4650  <varlistentry>
4651   <term>Type:</term>
4652   <!-- Boolean, Parameterized, Multi-value -->
4653   <listitem>
4654    <para>Boolean.</para>
4655   </listitem>
4656  </varlistentry>
4657
4658  <varlistentry>
4659   <term>Parameter:</term>
4660   <listitem>
4661    <para>
4662     N/A
4663    </para>
4664   </listitem>
4665  </varlistentry>
4666
4667  <varlistentry>
4668   <term>Notes:</term>
4669   <listitem>
4670    <para>
4671     The below generic example section is actually part of <filename>default.action</filename>.
4672     It marks all URLs with well-known image file name extensions as images and should
4673     be left intact.
4674    </para>
4675    <para>
4676     Users will probably only want to use the handle-as-image action in conjunction with
4677     <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
4678     reflect the file type, like in the second example section.
4679    </para>
4680    <para>
4681     Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
4682     frames require an HTML page to be sent, or they won't display properly.
4683     Forcing <literal>handle-as-image</literal> in this situation will not replace the
4684     ad frame with an image, but lead to error messages.
4685    </para>
4686   </listitem>
4687  </varlistentry>
4688
4689  <varlistentry>
4690   <term>Example usage (sections):</term>
4691   <listitem>
4692      <screen># Generic image extensions:
4693 #
4694 {+handle-as-image}
4695 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
4696
4697 # These don't look like images, but they're banners and should be
4698 # blocked as images:
4699 #
4700 {+block{Nasty banners.} +handle-as-image}
4701 nasty-banner-server.example.com/junk.cgi\?output=trash
4702 </screen>
4703   </listitem>
4704  </varlistentry>
4705 </variablelist>
4706 </sect3>
4707
4708
4709 <!--   ~~~~~       New section      ~~~~~     -->
4710 <sect3 renderas="sect4" id="hide-accept-language">
4711 <title>hide-accept-language</title>
4712 <!--
4713 new action
4714 -->
4715 <variablelist>
4716  <varlistentry>
4717   <term>Typical use:</term>
4718   <listitem>
4719    <para>Pretend to use different language settings.</para>
4720   </listitem>
4721  </varlistentry>
4722
4723  <varlistentry>
4724   <term>Effect:</term>
4725   <listitem>
4726    <para>
4727     Deletes or replaces the <quote>Accept-Language:</quote> HTTP header in client requests.
4728    </para>
4729   </listitem>
4730  </varlistentry>
4731
4732  <varlistentry>
4733   <term>Type:</term>
4734   <!-- Boolean, Parameterized, Multi-value -->
4735   <listitem>
4736    <para>Parameterized.</para>
4737   </listitem>
4738  </varlistentry>
4739
4740  <varlistentry>
4741   <term>Parameter:</term>
4742   <listitem>
4743    <para>
4744     Keyword: <quote>block</quote>, or any user defined value.
4745    </para>
4746   </listitem>
4747  </varlistentry>
4748
4749  <varlistentry>
4750   <term>Notes:</term>
4751   <listitem>
4752    <para>
4753     Faking the browser's language settings can be useful to make a
4754     foreign User-Agent set with
4755     <literal><link linkend="hide-user-agent">hide-user-agent</link></literal>
4756     more believable.
4757    </para>
4758    <para>
4759     However some sites with content in different languages check the
4760     <quote>Accept-Language:</quote> to decide which one to take by default.
4761     Sometimes it isn't possible to later switch to another language without
4762     changing the <quote>Accept-Language:</quote> header first.
4763    </para>
4764    <para>
4765     Therefore it's a good idea to either only change the
4766     <quote>Accept-Language:</quote> header to languages you understand,
4767     or to languages that aren't wide spread.
4768    </para>
4769    <para>
4770     Before setting the <quote>Accept-Language:</quote> header
4771     to a rare language, you should consider that it helps to
4772     make your requests unique and thus easier to trace.
4773     If you don't plan to change this header frequently,
4774     you should stick to a common language.
4775    </para>
4776   </listitem>
4777  </varlistentry>
4778
4779  <varlistentry>
4780   <term>Example usage (section):</term>
4781   <listitem>
4782      <screen># Pretend to use Canadian language settings.
4783 {+hide-accept-language{en-ca} \
4784 +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
4785 }
4786 /
4787 </screen>
4788   </listitem>
4789  </varlistentry>
4790 </variablelist>
4791 </sect3>
4792
4793
4794 <!--   ~~~~~       New section      ~~~~~     -->
4795 <sect3 renderas="sect4" id="hide-content-disposition">
4796 <title>hide-content-disposition</title>
4797 <!--
4798 new action
4799 -->
4800 <variablelist>
4801  <varlistentry>
4802   <term>Typical use:</term>
4803   <listitem>
4804    <para>Prevent download menus for content you prefer to view inside the browser.</para>
4805   </listitem>
4806  </varlistentry>
4807
4808  <varlistentry>
4809   <term>Effect:</term>
4810   <listitem>
4811    <para>
4812     Deletes or replaces the <quote>Content-Disposition:</quote> HTTP header set by some servers.
4813    </para>
4814   </listitem>
4815  </varlistentry>
4816
4817  <varlistentry>
4818   <term>Type:</term>
4819   <!-- Boolean, Parameterized, Multi-value -->
4820   <listitem>
4821    <para>Parameterized.</para>
4822   </listitem>
4823  </varlistentry>
4824
4825  <varlistentry>
4826   <term>Parameter:</term>
4827   <listitem>
4828    <para>
4829     Keyword: <quote>block</quote>, or any user defined value.
4830    </para>
4831   </listitem>
4832  </varlistentry>
4833
4834  <varlistentry>
4835   <term>Notes:</term>
4836   <listitem>
4837    <para>
4838     Some servers set the <quote>Content-Disposition:</quote> HTTP header for
4839     documents they assume you want to save locally before viewing them.
4840     The <quote>Content-Disposition:</quote> header contains the file name
4841     the browser is supposed to use by default.
4842    </para>
4843    <para>
4844     In most browsers that understand this header, it makes it impossible to
4845     <emphasis>just view</emphasis> the document, without downloading it first,
4846     even if it's just a simple text file or an image.
4847    </para>
4848    <para>
4849     Removing the <quote>Content-Disposition:</quote> header helps
4850     to prevent this annoyance, but some browsers additionally check the
4851     <quote>Content-Type:</quote> header, before they decide if they can
4852     display a document without saving it first. In these cases, you have
4853     to change this header as well, before the browser stops displaying
4854     download menus.
4855    </para>
4856    <para>
4857     It is also possible to change the server's file name suggestion
4858     to another one, but in most cases it isn't worth the time to set
4859     it up.
4860    </para>
4861    <para>
4862     This action will probably be removed in the future,
4863     use server-header filters instead.
4864    </para>
4865   </listitem>
4866  </varlistentry>
4867
4868  <varlistentry>
4869   <term>Example usage:</term>
4870   <listitem>
4871      <screen># Disarm the download link in Sourceforge's patch tracker
4872 { -filter \
4873  +content-type-overwrite{text/plain}\
4874  +hide-content-disposition{block} }
4875  .sourceforge.net/tracker/download\.php</screen>
4876   </listitem>
4877  </varlistentry>
4878 </variablelist>
4879 </sect3>
4880
4881
4882 <!--   ~~~~~       New section      ~~~~~     -->
4883 <sect3 renderas="sect4" id="hide-if-modified-since">
4884 <title>hide-if-modified-since</title>
4885 <!--
4886 new action
4887 -->
4888 <variablelist>
4889  <varlistentry>
4890   <term>Typical use:</term>
4891   <listitem>
4892    <para>Prevent yet another way to track the user's steps between sessions.</para>
4893   </listitem>
4894  </varlistentry>
4895
4896  <varlistentry>
4897   <term>Effect:</term>
4898   <listitem>
4899    <para>
4900     Deletes the <quote>If-Modified-Since:</quote> HTTP client header or modifies its value.
4901    </para>
4902   </listitem>
4903  </varlistentry>
4904
4905  <varlistentry>
4906   <term>Type:</term>
4907   <!-- Boolean, Parameterized, Multi-value -->
4908   <listitem>
4909    <para>Parameterized.</para>
4910   </listitem>
4911  </varlistentry>
4912
4913  <varlistentry>
4914   <term>Parameter:</term>
4915   <listitem>
4916    <para>
4917     Keyword: <quote>block</quote>, or a user defined value that specifies a range of hours.
4918    </para>
4919   </listitem>
4920  </varlistentry>
4921
4922  <varlistentry>
4923   <term>Notes:</term>
4924   <listitem>
4925    <para>
4926     Removing this header is useful for filter testing, where you want to force a real
4927     reload instead of getting status code <quote>304</quote>, which would cause the
4928     browser to use a cached copy of the page.
4929    </para>
4930    <para>
4931     Instead of removing the header, <literal>hide-if-modified-since</literal> can
4932     also add or subtract a random amount of time to/from the header's value.
4933     You specify a range of minutes where the random factor should be chosen from and
4934     <application>Privoxy</application> does the rest. A negative value means
4935     subtracting, a positive value adding.
4936    </para>
4937    <para>
4938     Randomizing the value of the <quote>If-Modified-Since:</quote> makes
4939     it less likely that the server can use the time as a cookie replacement,
4940     but you will run into caching problems if the random range is too high.
4941    </para>
4942    <para>
4943     It is a good idea to only use a small negative value and let
4944     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
4945     handle the greater changes.
4946    </para>
4947    <para>
4948     It is also recommended to use this action together with
4949     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>,
4950     otherwise it's more or less pointless.
4951    </para>
4952   </listitem>
4953  </varlistentry>
4954
4955  <varlistentry>
4956   <term>Example usage (section):</term>
4957   <listitem>
4958      <screen># Let the browser revalidate but make tracking based on the time less likely.
4959 {+hide-if-modified-since{-60} \
4960  +overwrite-last-modified{randomize} \
4961  +crunch-if-none-match}
4962 /</screen>
4963   </listitem>
4964  </varlistentry>
4965 </variablelist>
4966 </sect3>
4967
4968
4969 <!--   ~~~~~       New section      ~~~~~     -->
4970 <sect3 renderas="sect4" id="hide-from-header">
4971 <title>hide-from-header</title>
4972
4973 <variablelist>
4974  <varlistentry>
4975   <term>Typical use:</term>
4976   <listitem>
4977    <para>Keep your (old and ill) browser from telling web servers your email address</para>
4978   </listitem>
4979  </varlistentry>
4980
4981  <varlistentry>
4982   <term>Effect:</term>
4983   <listitem>
4984    <para>
4985     Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
4986     specified string.
4987    </para>
4988   </listitem>
4989  </varlistentry>
4990
4991  <varlistentry>
4992   <term>Type:</term>
4993   <!-- Boolean, Parameterized, Multi-value -->
4994   <listitem>
4995    <para>Parameterized.</para>
4996   </listitem>
4997  </varlistentry>
4998
4999  <varlistentry>
5000   <term>Parameter:</term>
5001   <listitem>
5002    <para>
5003     Keyword: <quote>block</quote>, or any user defined value.
5004    </para>
5005   </listitem>
5006  </varlistentry>
5007
5008  <varlistentry>
5009   <term>Notes:</term>
5010   <listitem>
5011    <para>
5012     The keyword <quote>block</quote> will completely remove the header
5013     (not to be confused with the <literal><link linkend="block">block</link></literal>
5014     action).
5015    </para>
5016    <para>
5017     Alternately, you can specify any value you prefer to be sent to the web
5018     server. If you do, it is a matter of fairness not to use any address that
5019     is actually used by a real person.
5020    </para>
5021    <para>
5022     This action is rarely needed, as modern web browsers don't send
5023     <quote>From:</quote> headers anymore.
5024    </para>
5025   </listitem>
5026  </varlistentry>
5027
5028  <varlistentry>
5029   <term>Example usage:</term>
5030   <listitem>
5031     <screen>+hide-from-header{block}</screen>
5032     <para>or</para>
5033     <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
5034   </listitem>
5035  </varlistentry>
5036 </variablelist>
5037 </sect3>
5038
5039
5040 <!--   ~~~~~       New section      ~~~~~     -->
5041 <sect3 renderas="sect4" id="hide-referrer">
5042 <title>hide-referrer</title>
5043 <anchor id="hide-referer">
5044 <variablelist>
5045  <varlistentry>
5046   <term>Typical use:</term>
5047   <listitem>
5048    <para>Conceal which link you followed to get to a particular site</para>
5049   </listitem>
5050  </varlistentry>
5051
5052  <varlistentry>
5053   <term>Effect:</term>
5054   <listitem>
5055    <para>
5056     Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
5057     or replaces it with a forged one.
5058    </para>
5059   </listitem>
5060  </varlistentry>
5061
5062  <varlistentry>
5063   <term>Type:</term>
5064   <!-- Boolean, Parameterized, Multi-value -->
5065   <listitem>
5066    <para>Parameterized.</para>
5067   </listitem>
5068  </varlistentry>
5069
5070  <varlistentry>
5071   <term>Parameter:</term>
5072   <listitem>
5073    <itemizedlist>
5074     <listitem>
5075      <para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
5076     </listitem>
5077     <listitem>
5078      <para><quote>conditional-forge</quote> to forge the header if the host has changed.</para>
5079     </listitem>
5080     <listitem>
5081      <para><quote>block</quote> to delete the header unconditionally.</para>
5082     </listitem>
5083     <listitem>
5084      <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
5085     </listitem>
5086     <listitem>
5087      <para>Any other string to set a user defined referrer.</para>
5088     </listitem>
5089    </itemizedlist>
5090   </listitem>
5091  </varlistentry>
5092
5093  <varlistentry>
5094   <term>Notes:</term>
5095   <listitem>
5096    <para>
5097     <literal>conditional-block</literal> is the only parameter,
5098     that isn't easily detected in the server's log file. If it blocks the
5099     referrer, the request will look like the visitor used a bookmark or
5100     typed in the address directly.
5101    </para>
5102    <para>
5103     Leaving the referrer unmodified for requests on the same host
5104     allows the server owner to see the visitor's <quote>click path</quote>,
5105     but in most cases she could also get that information by comparing
5106     other parts of the log file: for example the User-Agent if it isn't
5107     a very common one, or the user's IP address if it doesn't change between
5108     different requests.
5109    </para>
5110    <para>
5111     Always blocking the referrer, or using a custom one, can lead to
5112     failures on servers that check the referrer before they answer any
5113     requests, in an attempt to prevent their content from being
5114     embedded or linked to elsewhere.
5115    </para>
5116    <para>
5117     Both <literal>conditional-block</literal> and <literal>forge</literal>
5118     will work with referrer checks, as long as content and valid referring page
5119     are on the same host. Most of the time that's the case.
5120    </para>
5121    <para>
5122     <literal>hide-referer</literal> is an alternate spelling of
5123     <literal>hide-referrer</literal> and the two can be can be freely
5124     substituted with each other. (<quote>referrer</quote> is the
5125     correct English spelling, however the HTTP specification has a bug - it
5126     requires it to be spelled as <quote>referer</quote>.)
5127    </para>
5128   </listitem>
5129  </varlistentry>
5130
5131  <varlistentry>
5132   <term>Example usage:</term>
5133   <listitem>
5134      <screen>+hide-referrer{forge}</screen>
5135      <para>or</para>
5136      <screen>+hide-referrer{http://www.yahoo.com/}</screen>
5137   </listitem>
5138  </varlistentry>
5139 </variablelist>
5140 </sect3>
5141
5142
5143 <!--   ~~~~~       New section      ~~~~~     -->
5144 <sect3 renderas="sect4" id="hide-user-agent">
5145 <title>hide-user-agent</title>
5146
5147 <variablelist>
5148  <varlistentry>
5149   <term>Typical use:</term>
5150   <listitem>
5151    <para>Try to conceal your type of browser and client operating system</para>
5152   </listitem>
5153  </varlistentry>
5154
5155  <varlistentry>
5156   <term>Effect:</term>
5157   <listitem>
5158    <para>
5159     Replaces the value of the <quote>User-Agent:</quote> HTTP header
5160     in client requests with the specified value.
5161    </para>
5162   </listitem>
5163  </varlistentry>
5164
5165  <varlistentry>
5166   <term>Type:</term>
5167   <!-- Boolean, Parameterized, Multi-value -->
5168   <listitem>
5169    <para>Parameterized.</para>
5170   </listitem>
5171  </varlistentry>
5172
5173  <varlistentry>
5174   <term>Parameter:</term>
5175   <listitem>
5176    <para>
5177     Any user-defined string.
5178    </para>
5179   </listitem>
5180  </varlistentry>
5181
5182  <varlistentry>
5183   <term>Notes:</term>
5184   <listitem>
5185    <warning>
5186     <para>
5187      This can lead to problems on web sites that depend on looking at this header in
5188      order to customize their content for different browsers (which, by the
5189      way, is <emphasis>NOT</emphasis> the right thing to do: good web sites
5190      work browser-independently).
5191     </para>
5192    </warning>
5193    <para>
5194     Using this action in multi-user setups or wherever different types of
5195     browsers will access the same <application>Privoxy</application> is
5196     <emphasis>not recommended</emphasis>. In single-user, single-browser
5197     setups, you might use it to delete your OS version information from
5198     the headers, because it is an invitation to exploit known bugs for your
5199     OS. It is also occasionally useful to forge this in order to access
5200     sites that won't let you in otherwise (though there may be a good
5201     reason in some cases).
5202    </para>
5203    <para>
5204      More information on known user-agent strings can be found at
5205      <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
5206      and
5207      <ulink url="https://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
5208    </para>
5209    </listitem>
5210  </varlistentry>
5211
5212  <varlistentry>
5213   <term>Example usage:</term>
5214   <listitem>
5215      <screen>+hide-user-agent{Mozilla/5.0 (X11; ElectroBSD i386; rv:78.0) Gecko/20100101 Firefox/78.0}</screen>
5216   </listitem>
5217  </varlistentry>
5218 </variablelist>
5219 </sect3>
5220
5221
5222 <!--   ~~~~~       New section      ~~~~~     -->
5223 <sect3 renderas="sect4" id="https-inspection">
5224 <title>https-inspection</title>
5225
5226 <variablelist>
5227  <varlistentry>
5228   <term>Typical use:</term>
5229   <listitem>
5230    <para>Filter encrypted requests and responses</para>
5231   </listitem>
5232  </varlistentry>
5233
5234  <varlistentry>
5235   <term>Effect:</term>
5236   <listitem>
5237    <para>
5238     Encrypted requests are decrypted, filtered and forwarded encrypted.
5239    </para>
5240   </listitem>
5241  </varlistentry>
5242
5243  <varlistentry>
5244   <term>Type:</term>
5245   <!-- boolean, parameterized, Multi-value -->
5246   <listitem>
5247    <para>Boolean.</para>
5248   </listitem>
5249  </varlistentry>
5250
5251  <varlistentry>
5252   <term>Parameter:</term>
5253   <listitem>
5254    <para>
5255     N/A
5256    </para>
5257   </listitem>
5258  </varlistentry>
5259
5260 <varlistentry>
5261   <term>Notes:</term>
5262   <listitem>
5263    <para>
5264     This action allows &my-app; to filter encrypted requests and responses.
5265     For this to work &my-app; has to generate a certificate and send it
5266     to the client which has to accept it.
5267    </para>
5268    <para>
5269     Before this works the directives in the
5270     <literal><ulink url="config.html#HTTPS-INSPECTION-DIRECTIVES">HTTPS inspection section</ulink></literal>
5271     of the config file have to be configured.
5272    </para>
5273    <para>
5274     Note that the action has to be enabled based on the CONNECT
5275     request which doesn't contain a path. Enabling it based on
5276     a pattern with path doesn't work as the path is only seen
5277     by &my-app; if the action is already enabled.
5278    </para>
5279    <para>
5280     This is an experimental feature.
5281    </para>
5282   </listitem>
5283  </varlistentry>
5284
5285  <varlistentry>
5286   <term>Example usage (section):</term>
5287   <listitem>
5288      <screen>{+https-inspection}
5289 www.example.com</screen>
5290   </listitem>
5291  </varlistentry>
5292
5293 </variablelist>
5294 </sect3>
5295
5296
5297 <!--   ~~~~~       New section      ~~~~~     -->
5298 <sect3 renderas="sect4" id="ignore-certificate-errors">
5299 <title>ignore-certificate-errors</title>
5300
5301 <variablelist>
5302  <varlistentry>
5303   <term>Typical use:</term>
5304   <listitem>
5305    <para>Filter encrypted requests and responses without verifying the certificate</para>
5306   </listitem>
5307  </varlistentry>
5308
5309  <varlistentry>
5310   <term>Effect:</term>
5311   <listitem>
5312    <para>
5313     Encrypted requests are forwarded to sites without verifying the certificate.
5314    </para>
5315   </listitem>
5316  </varlistentry>
5317
5318  <varlistentry>
5319   <term>Type:</term>
5320   <!-- Boolean, Parameterized, Multi-value -->
5321   <listitem>
5322    <para>Boolean.</para>
5323   </listitem>
5324  </varlistentry>
5325
5326  <varlistentry>
5327   <term>Parameter:</term>
5328   <listitem>
5329    <para>
5330     N/A
5331    </para>
5332   </listitem>
5333  </varlistentry>
5334
5335  <varlistentry>
5336   <term>Notes:</term>
5337   <listitem>
5338    <para>
5339     When the
5340     <link linkend="HTTPS-INSPECTION"><quote>+https-inspection</quote></link>
5341     action is used &my-app; by default verifies that the remote site uses a valid
5342     certificate.
5343    </para>
5344    <para>
5345     If the certificate can't be validated by &my-app; the connection is aborted.
5346    </para>
5347    <para>
5348     This action disables the certificate check so requests to sites
5349     with certificates that can't be validated are allowed.
5350    </para>
5351    <para>
5352     Note that enabling this action allows Man-in-the-middle attacks.
5353    </para>
5354    </listitem>
5355  </varlistentry>
5356
5357  <varlistentry>
5358   <term>Example usage:</term>
5359   <listitem>
5360    <screen>
5361     {+ignore-certificate-errors}
5362     www.example.org
5363    </screen>
5364   </listitem>
5365  </varlistentry>
5366 </variablelist>
5367 </sect3>
5368
5369
5370 <!--   ~~~~~       New section      ~~~~~     -->
5371 <sect3 renderas="sect4" id="limit-connect">
5372 <title>limit-connect</title>
5373
5374 <variablelist>
5375  <varlistentry>
5376   <term>Typical use:</term>
5377   <listitem>
5378    <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay or disable SSL for untrusted sites</para>
5379   </listitem>
5380  </varlistentry>
5381
5382  <varlistentry>
5383   <term>Effect:</term>
5384   <listitem>
5385    <para>
5386     Specifies to which ports HTTP CONNECT requests are allowable.
5387    </para>
5388   </listitem>
5389  </varlistentry>
5390
5391  <varlistentry>
5392   <term>Type:</term>
5393   <!-- Boolean, Parameterized, Multi-value -->
5394   <listitem>
5395    <para>Parameterized.</para>
5396   </listitem>
5397  </varlistentry>
5398
5399  <varlistentry>
5400   <term>Parameter:</term>
5401   <listitem>
5402    <para>
5403     A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
5404     defaulting to 0 and the maximum to 65K).
5405    </para>
5406   </listitem>
5407  </varlistentry>
5408
5409  <varlistentry>
5410   <term>Notes:</term>
5411   <listitem>
5412    <para>
5413     By default, i.e. if no <literal>limit-connect</literal> action applies,
5414     <application>Privoxy</application> allows HTTP CONNECT requests to all
5415     ports. Use <literal>limit-connect</literal> if fine-grained control
5416     is desired for some or all destinations.
5417    </para>
5418    <para>
5419     The CONNECT methods exists in HTTP to allow access to secure websites
5420     (<quote>https://</quote> URLs) through proxies. It works very simply:
5421     the proxy connects to the server on the specified port, and then
5422     short-circuits its connections to the client and to the remote server.
5423     This means CONNECT-enabled proxies can be used as TCP relays very easily.
5424   </para>
5425   <para>
5426    <application>Privoxy</application> relays HTTPS traffic without seeing
5427    the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
5428    filters. By specifying an invalid port range you can disable HTTPS entirely.
5429   </para>
5430   </listitem>
5431  </varlistentry>
5432
5433  <varlistentry>
5434   <term>Example usages:</term>
5435   <listitem>
5436    <!-- I had trouble getting the spacing to look right in my browser -->
5437    <!-- I probably have the wrong font setup, bollocks. -->
5438    <!-- Apparently the emphasis tag uses a proportional font no matter what -->
5439      <screen>+limit-connect{443}                   # Port 443 is OK.
5440 +limit-connect{80,443}                # Ports 80 and 443 are OK.
5441 +limit-connect{-3, 7, 20-100, 500-}   # Ports less than 3, 7, 20 to 100 and above 500 are OK.
5442 +limit-connect{-}                     # All ports are OK
5443 +limit-connect{,}                     # No HTTPS/SSL traffic is allowed</screen>
5444   </listitem>
5445  </varlistentry>
5446 </variablelist>
5447 </sect3>
5448
5449
5450 <!--   ~~~~~       New section      ~~~~~     -->
5451 <sect3 renderas="sect4" id="limit-cookie-lifetime">
5452 <title>limit-cookie-lifetime</title>
5453
5454 <variablelist>
5455  <varlistentry>
5456   <term>Typical use:</term>
5457   <listitem>
5458    <para>Limit the lifetime of HTTP cookies to a couple of minutes or hours.</para>
5459   </listitem>
5460  </varlistentry>
5461
5462  <varlistentry>
5463   <term>Effect:</term>
5464   <listitem>
5465    <para>
5466     Overwrites the expires field in Set-Cookie server headers if it's above the specified limit.
5467    </para>
5468   </listitem>
5469  </varlistentry>
5470
5471  <varlistentry>
5472   <term>Type:</term>
5473   <!-- Boolean, Parameterized, Multi-value -->
5474   <listitem>
5475    <para>Parameterized.</para>
5476   </listitem>
5477  </varlistentry>
5478
5479  <varlistentry>
5480   <term>Parameter:</term>
5481   <listitem>
5482    <para>
5483     The lifetime limit in minutes, or 0.
5484    </para>
5485   </listitem>
5486  </varlistentry>
5487
5488  <varlistentry>
5489   <term>Notes:</term>
5490   <listitem>
5491    <para>
5492     This action reduces the lifetime of HTTP cookies coming from the
5493     server to the specified number of minutes, starting from the time
5494     the cookie passes Privoxy.
5495    </para>
5496    <para>
5497     Cookies with a lifetime below the limit are not modified.
5498     The lifetime of session cookies is set to the specified limit.
5499    </para>
5500    <para>
5501     The effect of this action depends on the server.
5502    </para>
5503    <para>
5504     In case of servers which refresh their cookies with each response
5505     (or at least frequently), the lifetime limit set by this action
5506     is updated as well.
5507     Thus, a session associated with the cookie continues to work with
5508     this action enabled, as long as a new request is made before the
5509     last limit set is reached.
5510    </para>
5511    <para>
5512     However, some servers send their cookies once, with a lifetime of several
5513     years (the year 2037 is a popular choice), and do not refresh them
5514     until a certain event in the future, for example the user logging out.
5515     In this case this action may limit the absolute lifetime of the session,
5516     even if requests are made frequently.
5517    </para>
5518    <para>
5519     If the parameter is <quote>0</quote>, this action behaves like
5520     <literal><link linkend="session-cookies-only">session-cookies-only</link></literal>.
5521    </para>
5522   </listitem>
5523  </varlistentry>
5524
5525  <varlistentry>
5526   <term>Example usages:</term>
5527   <listitem>
5528      <screen>+limit-cookie-lifetime{60}</screen>
5529   </listitem>
5530  </varlistentry>
5531 </variablelist>
5532 </sect3>
5533
5534 <!--   ~~~~~       New section      ~~~~~     -->
5535 <sect3 renderas="sect4" id="prevent-compression">
5536 <title>prevent-compression</title>
5537
5538 <variablelist>
5539  <varlistentry>
5540   <term>Typical use:</term>
5541   <listitem>
5542    <para>
5543     Ensure that servers send the content uncompressed, so it can be
5544     passed through <literal><link linkend="filter">filter</link></literal>s.
5545    </para>
5546   </listitem>
5547  </varlistentry>
5548
5549  <varlistentry>
5550   <term>Effect:</term>
5551   <listitem>
5552    <para>
5553     Removes the Accept-Encoding header which can be used to ask for compressed transfer.
5554    </para>
5555   </listitem>
5556  </varlistentry>
5557
5558  <varlistentry>
5559   <term>Type:</term>
5560   <!-- Boolean, Parameterized, Multi-value -->
5561   <listitem>
5562    <para>Boolean.</para>
5563   </listitem>
5564  </varlistentry>
5565
5566  <varlistentry>
5567   <term>Parameter:</term>
5568   <listitem>
5569    <para>
5570     N/A
5571    </para>
5572   </listitem>
5573  </varlistentry>
5574
5575  <varlistentry>
5576   <term>Notes:</term>
5577   <listitem>
5578    <para>
5579     More and more websites send their content compressed by default, which
5580     is generally a good idea and saves bandwidth. But the <literal><link
5581     linkend="filter">filter</link></literal> and
5582     <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
5583     actions need access to the uncompressed data.
5584    </para>
5585    <para>
5586     When compiled with zlib support (available since &my-app; 3.0.7), content that should be
5587     filtered is decompressed on-the-fly and you don't have to worry about this action.
5588     If you are using an older &my-app; version, or one that hasn't been compiled with zlib
5589     support, this action can be used to convince the server to send the content uncompressed.
5590    </para>
5591    <para>
5592     Most text-based instances compress very well, the size is seldom decreased by less than 50%,
5593     for markup-heavy instances like news feeds saving more than 90% of the original size isn't
5594     unusual.
5595    </para>
5596    <para>
5597     Not using compression will therefore slow down the transfer, and you should only
5598     enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all
5599     predefined action settings.
5600    </para>
5601    <para>
5602     Note that some (rare) ill-configured sites don't handle requests for uncompressed
5603     documents correctly. Broken PHP applications tend to send an empty document body,
5604     some IIS versions only send the beginning of the content and some content delivery
5605     networks let the connection time out.
5606     If you enable <literal>prevent-compression</literal> per default, you might
5607     want to add exceptions for those sites. See the example for how to do that.
5608    </para>
5609   </listitem>
5610  </varlistentry>
5611
5612  <varlistentry>
5613   <term>Example usage (sections):</term>
5614   <listitem>
5615     <screen>
5616 # Selectively turn off compression, and enable a filter
5617 #
5618 { +filter{tiny-textforms} +prevent-compression }
5619 # Match only these sites
5620  .google.
5621  sourceforge.net
5622  sf.net
5623
5624 # Or instead, we could set a universal default:
5625 #
5626 { +prevent-compression }
5627  / # Match all sites
5628
5629 # Then maybe make exceptions for broken sites:
5630 #
5631 { -prevent-compression }
5632 .compusa.com/</screen>
5633   </listitem>
5634  </varlistentry>
5635
5636 </variablelist>
5637 </sect3>
5638
5639
5640 <!--   ~~~~~       New section      ~~~~~     -->
5641 <sect3 renderas="sect4" id="overwrite-last-modified">
5642 <title>overwrite-last-modified</title>
5643 <!--
5644 new action
5645 -->
5646 <variablelist>
5647  <varlistentry>
5648   <term>Typical use:</term>
5649   <listitem>
5650    <para>Prevent yet another way to track the user's steps between sessions.</para>
5651   </listitem>
5652  </varlistentry>
5653
5654  <varlistentry>
5655   <term>Effect:</term>
5656   <listitem>
5657    <para>
5658     Deletes the <quote>Last-Modified:</quote> HTTP server header or modifies its value.
5659    </para>
5660   </listitem>
5661  </varlistentry>
5662
5663  <varlistentry>
5664   <term>Type:</term>
5665   <!-- Boolean, Parameterized, Multi-value -->
5666   <listitem>
5667    <para>Parameterized.</para>
5668   </listitem>
5669  </varlistentry>
5670
5671  <varlistentry>
5672   <term>Parameter:</term>
5673   <listitem>
5674    <para>
5675     One of the keywords: <quote>block</quote>, <quote>reset-to-request-time</quote>
5676     and <quote>randomize</quote>
5677    </para>
5678   </listitem>
5679  </varlistentry>
5680
5681  <varlistentry>
5682   <term>Notes:</term>
5683   <listitem>
5684    <para>
5685     Removing the <quote>Last-Modified:</quote> header is useful for filter
5686     testing, where you want to force a real reload instead of getting status
5687     code <quote>304</quote>, which would cause the browser to reuse the old
5688     version of the page.
5689    </para>
5690    <para>
5691     The <quote>randomize</quote> option overwrites the value of the
5692     <quote>Last-Modified:</quote> header with a randomly chosen time
5693     between the original value and the current time. In theory the server
5694     could send each document with a different <quote>Last-Modified:</quote>
5695     header to track visits without using cookies. <quote>Randomize</quote>
5696     makes it impossible and the browser can still revalidate cached documents.
5697    </para>
5698    <para>
5699     <quote>reset-to-request-time</quote> overwrites the value of the
5700     <quote>Last-Modified:</quote> header with the current time. You could use
5701     this option together with
5702     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
5703     to further customize your random range.
5704    </para>
5705    <para>
5706     The preferred parameter here is <quote>randomize</quote>. It is safe
5707     to use, as long as the time settings are more or less correct.
5708     If the server sets the <quote>Last-Modified:</quote> header to the time
5709     of the request, the random range becomes zero and the value stays the same.
5710     Therefore you should later randomize it a second time with
5711     <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>,
5712     just to be sure.
5713    </para>
5714    <para>
5715     It is also recommended to use this action together with
5716     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
5717    </para>
5718   </listitem>
5719  </varlistentry>
5720
5721  <varlistentry>
5722   <term>Example usage:</term>
5723   <listitem>
5724      <screen># Let the browser revalidate without being tracked across sessions
5725 { +hide-if-modified-since{-60} \
5726  +overwrite-last-modified{randomize} \
5727  +crunch-if-none-match}
5728 /</screen>
5729   </listitem>
5730  </varlistentry>
5731 </variablelist>
5732 </sect3>
5733
5734
5735 <!--   ~~~~~       New section      ~~~~~     -->
5736 <sect3 renderas="sect4" id="redirect">
5737 <title>redirect</title>
5738 <!--
5739 new action
5740 -->
5741 <variablelist>
5742  <varlistentry>
5743   <term>Typical use:</term>
5744   <listitem>
5745    <para>
5746     Redirect requests to other sites.
5747    </para>
5748   </listitem>
5749  </varlistentry>
5750
5751  <varlistentry>
5752   <term>Effect:</term>
5753   <listitem>
5754    <para>
5755     Convinces the browser that the requested document has been moved
5756     to another location and the browser should get it from there.
5757    </para>
5758   </listitem>
5759  </varlistentry>
5760
5761  <varlistentry>
5762   <term>Type:</term>
5763   <!-- Boolean, Parameterized, Multi-value -->
5764   <listitem>
5765    <para>Parameterized</para>
5766   </listitem>
5767  </varlistentry>
5768
5769  <varlistentry>
5770   <term>Parameter:</term>
5771   <listitem>
5772    <para>
5773     An absolute URL or a single pcrs command.
5774    </para>
5775   </listitem>
5776  </varlistentry>
5777
5778  <varlistentry>
5779   <term>Notes:</term>
5780   <listitem>
5781    <para>
5782     Requests to which this action applies are answered with a
5783     HTTP redirect to URLs of your choosing. The new URL is
5784     either provided as parameter, or derived by applying a
5785     single pcrs command to the original URL.
5786    </para>
5787    <para>
5788     The syntax for pcrs commands is documented in the
5789     <link linkend="filter-file">filter file</link> section.
5790    </para>
5791    <para>
5792     Requests can't be blocked and redirected at the same time,
5793     applying this action together with
5794     <literal><link linkend="block">block</link></literal>
5795     is a configuration error. Currently the request is blocked
5796     and an error message logged, the behavior may change in the
5797     future and result in Privoxy rejecting the action file.
5798    </para>
5799    <para>
5800     This action can be combined with
5801     <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
5802     to redirect to a decoded version of a rewritten URL.
5803    </para>
5804    <para>
5805     Use this action carefully, make sure not to create redirection loops
5806     and be aware that using your own redirects might make it
5807     possible to fingerprint your requests.
5808    </para>
5809    <para>
5810     In case of problems with your redirects, or simply to watch
5811     them working, enable <link linkend="DEBUG">debug 128</link>.
5812    </para>
5813   </listitem>
5814  </varlistentry>
5815
5816  <varlistentry>
5817   <term>Example usages:</term>
5818   <listitem>
5819     <screen># Replace example.com's style sheet with another one
5820 { +redirect{http://localhost/css-replacements/example.com.css} }
5821  example.com/stylesheet\.css
5822
5823 # Create a short, easy to remember nickname for a favorite site
5824 # (relies on the browser to accept and forward invalid URLs to &my-app;)
5825 { +redirect{https://www.privoxy.org/user-manual/actions-file.html} }
5826  a
5827
5828 # Always use the expanded view for Undeadly.org articles
5829 # (Note the $ at the end of the URL pattern to make sure
5830 # the request for the rewritten URL isn't redirected as well)
5831 {+redirect{s@$@&amp;mode=expanded@}}
5832 undeadly.org/cgi\?action=article&amp;sid=\d*$
5833
5834 # Redirect Google search requests to MSN
5835 {+redirect{s@^http://[^/]*/search\?q=([^&amp;]*).*@http://search.msn.com/results.aspx?q=$1@}}
5836 .google.com/search
5837
5838 # Redirect MSN search requests to Yahoo
5839 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&amp;]*).*@http://search.yahoo.com/search?p=$1@}}
5840 search.msn.com//results\.aspx\?q=
5841
5842 # Redirect http://example.com/&amp;bla=fasel&amp;toChange=foo (and any other value but "bar")
5843 # to       http://example.com/&amp;bla=fasel&amp;toChange=bar
5844 #
5845 # The URL pattern makes sure that the following request isn't redirected again.
5846 {+redirect{s@toChange=[^&amp;]+@toChange=bar@}}
5847 example.com/.*toChange=(?!bar)
5848
5849 # Add a shortcut to look up illumos bugs
5850 {+redirect{s@^http://i([0-9]+)/.*@https://www.illumos.org/issues/$1@}}
5851 # Redirected URL = http://i4974/
5852 # Redirect Destination = https://www.illumos.org/issues/4974
5853 i[0-9][0-9][0-9][0-9]*/
5854
5855 # Redirect requests for the old Tor Hidden Service of the Privoxy website to the new one
5856 {+redirect{s@^http://jvauzb4sb3bwlsnc.onion/@http://l3tczdiiwoo63iwxty4lhs6p7eaxop5micbn7vbliydgv63x5zrrrfyd.onion/@}}
5857 jvauzb4sb3bwlsnc.onion/
5858
5859 # Redirect remote requests for this manual
5860 # to the local version delivered by Privoxy
5861 {+redirect{s@^http://www@http://config@}}
5862 www.privoxy.org/user-manual/</screen>
5863   </listitem>
5864  </varlistentry>
5865
5866 </variablelist>
5867 </sect3>
5868
5869
5870 <!--   ~~~~~       New section      ~~~~~     -->
5871 <sect3 renderas="sect4" id="server-header-filter">
5872 <title>server-header-filter</title>
5873
5874 <variablelist>
5875  <varlistentry>
5876   <term>Typical use:</term>
5877   <listitem>
5878    <para>
5879    Rewrite or remove single server headers.
5880    </para>
5881   </listitem>
5882  </varlistentry>
5883
5884  <varlistentry>
5885   <term>Effect:</term>
5886   <listitem>
5887    <para>
5888     All server headers to which this action applies are filtered on-the-fly
5889     through the specified regular expression based substitutions.
5890    </para>
5891   </listitem>
5892  </varlistentry>
5893
5894  <varlistentry>
5895   <term>Type:</term>
5896   <!-- boolean, parameterized, Multi-value -->
5897   <listitem>
5898    <para>Multi-value.</para>
5899   </listitem>
5900  </varlistentry>
5901
5902  <varlistentry>
5903   <term>Parameter:</term>
5904   <listitem>
5905    <para>
5906     The name of a server-header filter, as defined in one of the
5907     <link linkend="filter-file">filter files</link>.
5908    </para>
5909   </listitem>
5910  </varlistentry>
5911
5912  <varlistentry>
5913   <term>Notes:</term>
5914   <listitem>
5915    <para>
5916     Server-header filters are applied to each header on its own, not to
5917     all at once. This makes it easier to diagnose problems, but on the downside
5918     you can't write filters that only change header x if header y's value is z.
5919     You can do that by using tags though.
5920    </para>
5921    <para>
5922     Server-header filters are executed after the other header actions have finished
5923     and use their output as input.
5924    </para>
5925    <para>
5926     Please refer to the <link linkend="filter-file">filter file chapter</link>
5927     to learn which server-header filters are available by default, and how to
5928     create your own.
5929    </para>
5930  </listitem>
5931  </varlistentry>
5932
5933  <varlistentry>
5934   <term>Example usage (section):</term>
5935   <listitem>
5936      <screen>
5937 {+server-header-filter{html-to-xml}}
5938 example.org/xml-instance-that-is-delivered-as-html
5939
5940 {+server-header-filter{xml-to-html}}
5941 example.org/instance-that-is-delivered-as-xml-but-is-not
5942 </screen>
5943   </listitem>
5944  </varlistentry>
5945
5946 </variablelist>
5947 </sect3>
5948
5949
5950 <!--   ~~~~~       New section      ~~~~~     -->
5951 <sect3 renderas="sect4" id="server-header-tagger">
5952 <title>server-header-tagger</title>
5953
5954 <variablelist>
5955  <varlistentry>
5956   <term>Typical use:</term>
5957   <listitem>
5958    <para>
5959    Enable or disable filters based on the Content-Type header.
5960    </para>
5961   </listitem>
5962  </varlistentry>
5963
5964  <varlistentry>
5965   <term>Effect:</term>
5966   <listitem>
5967    <para>
5968     Server headers to which this action applies are filtered on-the-fly through
5969     the specified regular expression based substitutions, the result is used as
5970     tag.
5971    </para>
5972   </listitem>
5973  </varlistentry>
5974
5975  <varlistentry>
5976   <term>Type:</term>
5977   <!-- boolean, parameterized, Multi-value -->
5978   <listitem>
5979    <para>Multi-value.</para>
5980   </listitem>
5981  </varlistentry>
5982
5983  <varlistentry>
5984   <term>Parameter:</term>
5985   <listitem>
5986    <para>
5987     The name of a server-header tagger, as defined in one of the
5988     <link linkend="filter-file">filter files</link>.
5989    </para>
5990   </listitem>
5991  </varlistentry>
5992
5993  <varlistentry>
5994   <term>Notes:</term>
5995   <listitem>
5996    <para>
5997     Server-header taggers are applied to each header on its own,
5998     and as the header isn't modified, each tagger <quote>sees</quote>
5999     the original.
6000    </para>
6001    <para>
6002     Server-header taggers are executed before all other header actions
6003     that modify server headers. Their tags can be used to control
6004     all of the other server-header actions, the content filters
6005     and the crunch actions (<link linkend="redirect">redirect</link>
6006     and <link linkend="block">block</link>).
6007    </para>
6008    <para>
6009     Obviously crunching based on tags created by server-header taggers
6010     doesn't prevent the request from showing up in the server's log file.
6011    </para>
6012
6013  </listitem>
6014  </varlistentry>
6015
6016  <varlistentry>
6017   <term>Example usage (section):</term>
6018   <listitem>
6019      <screen>
6020 # Tag every request with the content type declared by the server
6021 {+server-header-tagger{content-type}}
6022 /
6023
6024 # If the response has a tag starting with 'image/' enable an external
6025 # filter that only applies to images.
6026 #
6027 # Note that the filter is not available by default, it's just a
6028 # <literal><link linkend="external-filter-syntax">silly example</link></literal>.
6029 {+external-filter{rotate-image} +force-text-mode}
6030 TAG:^image/
6031 </screen>
6032   </listitem>
6033  </varlistentry>
6034
6035 </variablelist>
6036 </sect3>
6037
6038
6039 <!--   ~~~~~       New section      ~~~~~     -->
6040 <sect3 renderas="sect4" id="suppress-tag">
6041 <title>suppress-tag</title>
6042
6043 <variablelist>
6044  <varlistentry>
6045   <term>Typical use:</term>
6046   <listitem>
6047    <para>
6048    Suppress client or server tag.
6049    </para>
6050   </listitem>
6051  </varlistentry>
6052
6053  <varlistentry>
6054   <term>Effect:</term>
6055   <listitem>
6056    <para>
6057     Server or client tags to which this action applies are not added to the request,
6058     thus making all actions that are specific to these request tags inactive.
6059    </para>
6060   </listitem>
6061  </varlistentry>
6062
6063  <varlistentry>
6064   <term>Type:</term>
6065   <!-- boolean, parameterized, Multi-value -->
6066   <listitem>
6067    <para>Multi-value.</para>
6068   </listitem>
6069  </varlistentry>
6070
6071  <varlistentry>
6072   <term>Parameter:</term>
6073   <listitem>
6074    <para>
6075     The result tag of a server-header or client-header tagger, as defined in one of the
6076     <link linkend="filter-file">filter files</link>.
6077    </para>
6078   </listitem>
6079  </varlistentry>
6080
6081  <varlistentry>
6082   <term>Example usage (section):</term>
6083   <listitem>
6084      <screen>
6085 # Suppress tag produced by range-requests client-header tagger for requests coming from address 10.0.0.1
6086 {+suppress-tag{RANGE-REQUEST}}
6087 TAG:^IP-ADDRESS: 10\.0\.0\.1$
6088 </screen>
6089   </listitem>
6090  </varlistentry>
6091
6092 </variablelist>
6093 </sect3>
6094
6095
6096 <!--   ~~~~~       New section      ~~~~~     -->
6097 <sect3 renderas="sect4" id="session-cookies-only">
6098 <title>session-cookies-only</title>
6099
6100 <variablelist>
6101  <varlistentry>
6102   <term>Typical use:</term>
6103   <listitem>
6104    <para>
6105     Allow only temporary <quote>session</quote> cookies (for the current
6106     browser session <emphasis>only</emphasis>).
6107    </para>
6108   </listitem>
6109  </varlistentry>
6110
6111  <varlistentry>
6112   <term>Effect:</term>
6113   <listitem>
6114    <para>
6115     Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote>
6116     server headers. Most browsers will not store such cookies permanently and
6117     forget them in between sessions.
6118    </para>
6119   </listitem>
6120  </varlistentry>
6121
6122 <varlistentry>
6123   <term>Type:</term>
6124   <!-- Boolean, Parameterized, Multi-value -->
6125   <listitem>
6126    <para>Boolean.</para>
6127   </listitem>
6128  </varlistentry>
6129
6130  <varlistentry>
6131   <term>Parameter:</term>
6132   <listitem>
6133    <para>
6134     N/A
6135    </para>
6136   </listitem>
6137  </varlistentry>
6138
6139  <varlistentry>
6140   <term>Notes:</term>
6141   <listitem>
6142    <para>
6143     This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
6144     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
6145     websites that insist or rely on setting cookies, without compromising your privacy too badly.
6146    </para>
6147    <para>
6148     Most browsers will not permanently store cookies that have been processed by
6149     <literal>session-cookies-only</literal> and will forget about them between sessions.
6150     This makes profiling cookies useless, but won't break sites which require cookies so
6151     that you can log in for transactions. This is generally turned on for all
6152     sites, and is the recommended setting.
6153    </para>
6154    <para>
6155     It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
6156     together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
6157     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
6158     will be plainly killed.
6159    </para>
6160    <para>
6161     Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
6162     field. If you use an exotic browser, you might want to try it out to be sure.
6163    </para>
6164    <para>
6165     This setting also has no effect on cookies that may have been stored
6166     previously by the browser before starting <application>Privoxy</application>.
6167     These would have to be removed manually.
6168    </para>
6169    <para>
6170      <application>Privoxy</application> also uses
6171      the <link linkend="filter-content-cookies">content-cookies filter</link>
6172      to block some types of cookies. Content cookies are not effected by
6173      <literal>session-cookies-only</literal>.
6174    </para>
6175   </listitem>
6176  </varlistentry>
6177
6178  <varlistentry>
6179   <term>Example usage:</term>
6180   <listitem>
6181      <screen>+session-cookies-only</screen>
6182   </listitem>
6183  </varlistentry>
6184 </variablelist>
6185 </sect3>
6186
6187
6188 <!--   ~~~~~       New section      ~~~~~     -->
6189 <sect3 renderas="sect4" id="set-image-blocker">
6190 <title>set-image-blocker</title>
6191
6192 <variablelist>
6193  <varlistentry>
6194   <term>Typical use:</term>
6195   <listitem>
6196    <para>Choose the replacement for blocked images</para>
6197   </listitem>
6198  </varlistentry>
6199
6200  <varlistentry>
6201   <term>Effect:</term>
6202   <listitem>
6203    <para>
6204      This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
6205      <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
6206      linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
6207      apply, i.e. if the request is to be blocked as an image,
6208      <emphasis>then</emphasis> the parameter of this action decides what will be
6209      sent as a replacement.
6210    </para>
6211   </listitem>
6212  </varlistentry>
6213
6214  <varlistentry>
6215   <term>Type:</term>
6216   <!-- Boolean, Parameterized, Multi-value -->
6217   <listitem>
6218    <para>Parameterized.</para>
6219   </listitem>
6220  </varlistentry>
6221
6222  <varlistentry>
6223   <term>Parameter:</term>
6224   <listitem>
6225    <itemizedlist>
6226     <listitem>
6227      <para>
6228       <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
6229       decent, scales very well, and makes it obvious where banners were busted.
6230      </para>
6231     </listitem>
6232     <listitem>
6233      <para>
6234       <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
6235       completely, but makes it hard to detect where <application>Privoxy</application> has blocked
6236       images on a given page and complicates troubleshooting if <application>Privoxy</application>
6237       has blocked innocent images, like navigation icons.
6238      </para>
6239     </listitem>
6240     <listitem>
6241      <para>
6242       <quote><replaceable class="parameter">target-url</replaceable></quote> to
6243       send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
6244       to any image anywhere, even in your local filesystem via <quote>file:///</quote> URL.
6245       (But note that not all browsers support redirecting to a local file system).
6246      </para>
6247      <para>
6248       A good application of redirects is to use special <application>Privoxy</application>-built-in
6249       URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
6250       This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
6251       the first place, but enables your browser to cache the replacement image, instead of requesting
6252       it over and over again.
6253      </para>
6254     </listitem>
6255    </itemizedlist>
6256   </listitem>
6257  </varlistentry>
6258
6259  <varlistentry>
6260   <term>Notes:</term>
6261   <listitem>
6262    <para>
6263     The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
6264     class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
6265     either <quote>blank</quote> or <quote>pattern</quote>.
6266    </para>
6267    <para>
6268     There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
6269     used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
6270     Auto will select the type of image that would have applied to the referring page, had it been an image.
6271    </para>
6272   </listitem>
6273  </varlistentry>
6274
6275  <varlistentry>
6276   <term>Example usage:</term>
6277   <listitem>
6278    <para>
6279     Built-in pattern:
6280    </para>
6281     <screen>+set-image-blocker{pattern}</screen>
6282    <para>
6283     Redirect to the BSD daemon:
6284    </para>
6285     <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
6286    <para>
6287     Redirect to the built-in pattern for better caching:
6288    </para>
6289     <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
6290   </listitem>
6291  </varlistentry>
6292 </variablelist>
6293 </sect3>
6294
6295
6296 <!--   ~~~~~       New section      ~~~~~     -->
6297 <sect3 id="summary">
6298 <title>Summary</title>
6299 <para>
6300  Note that many of these actions have the potential to cause a page to
6301  misbehave, possibly even not to display at all. There are many ways
6302  a site designer may choose to design his site, and what HTTP header
6303  content, and other criteria, he may depend on. There is no way to have hard
6304  and fast rules for all sites. See the <link
6305  linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
6306  actions.
6307 </para>
6308 </sect3>
6309 </sect2>
6310
6311 <!--   ~~~~~       New section      ~~~~~     -->
6312 <sect2 id="aliases">
6313 <title>Aliases</title>
6314 <para>
6315  Custom <quote>actions</quote>, known to <application>Privoxy</application>
6316  as <quote>aliases</quote>, can be defined by combining other actions.
6317  These can in turn be invoked just like the built-in actions.
6318  Currently, an alias name can contain any character except space, tab,
6319  <quote>=</quote>,
6320  <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
6321  recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
6322  <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
6323  Alias names are not case sensitive, and are not required to start with a
6324  <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
6325  expanded.
6326 </para>
6327 <para>
6328  Aliases can be used throughout the actions file, but they <emphasis>must be
6329  defined in a special section at the top of the file!</emphasis>
6330  And there can only be one such section per actions file. Each actions file may
6331  have its own alias section, and the aliases defined in it are only visible
6332  within that file.
6333 </para>
6334 <para>
6335  There are two main reasons to use aliases: One is to save typing for frequently
6336  used combinations of actions, the other one is a gain in flexibility: If you
6337  decide once how you want to handle shops by defining an alias called
6338  <quote>shop</quote>, you can later change your policy on shops in
6339  <emphasis>one</emphasis> place, and your changes will take effect everywhere
6340  in the actions file where the <quote>shop</quote> alias is used. Calling aliases
6341  by their purpose also makes your actions files more readable.
6342 </para>
6343 <para>
6344  Currently, there is one big drawback to using aliases, though:
6345  <application>Privoxy</application>'s built-in web-based action file
6346  editor honors aliases when reading the actions files, but it expands
6347  them before writing. So the effects of your aliases are of course preserved,
6348  but the aliases themselves are lost when you edit sections that use aliases
6349  with it.
6350 </para>
6351
6352 <para>
6353  Now let's define some aliases...
6354 </para>
6355
6356  <screen>
6357  # Useful custom aliases we can use later.
6358  #
6359  # Note the (required!) section header line and that this section
6360  # must be at the top of the actions file!
6361  #
6362  {{alias}}
6363
6364  # These aliases just save typing later:
6365  # (Note that some already use other aliases!)
6366  #
6367  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
6368  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
6369  +block-as-image      = +block{Blocked image.} +handle-as-image
6370  allow-all-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
6371
6372  # These aliases define combinations of actions
6373  # that are useful for certain types of sites:
6374  #
6375  fragile     = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="PREVENT-COMPRESSION">prevent-compression</link>
6376
6377  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link>
6378
6379  # Short names for other aliases, for really lazy people ;-)
6380  #
6381  c0 = +crunch-all-cookies
6382  c1 = -crunch-all-cookies</screen>
6383
6384 <para>
6385  ...and put them to use. These sections would appear in the lower part of an
6386  actions file and define exceptions to the default actions (as specified further
6387  up for the <quote>/</quote> pattern):
6388 </para>
6389
6390  <screen>
6391  # These sites are either very complex or very keen on
6392  # user data and require minimal interference to work:
6393  #
6394  {fragile}
6395  .office.microsoft.com
6396  .windowsupdate.microsoft.com
6397  # Gmail is really mail.google.com, not gmail.com
6398  mail.google.com
6399
6400  # Shopping sites:
6401  # Allow cookies (for setting and retrieving your customer data)
6402  #
6403  {shop}
6404  .quietpc.com
6405  .worldpay.com   # for quietpc.com
6406  mybank.example.com
6407
6408  # These shops require pop-ups:
6409  #
6410  {-filter{all-popups} -filter{unsolicited-popups}}
6411   .dabs.com
6412   .overclockers.co.uk</screen>
6413
6414 <para>
6415  Aliases like <quote>shop</quote> and <quote>fragile</quote> are typically used for
6416  <quote>problem</quote> sites that require more than one action to be disabled
6417  in order to function properly.
6418 </para>
6419 </sect2>
6420 <!--
6421 hal stop here
6422 -->
6423 <!--   ~~~~~       New section      ~~~~~     -->
6424 <sect2 id="act-examples">
6425 <title>Actions Files Tutorial</title>
6426 <para>
6427  The above chapters have shown <link linkend="actions-file">which actions files
6428  there are and how they are organized</link>, how actions are <link
6429  linkend="actions">specified</link> and <link linkend="actions-apply">applied
6430  to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
6431  define and use <link linkend="aliases">aliases</link>. Now, let's look at an
6432  example <filename>match-all.action</filename>, <filename>default.action</filename>
6433  and <filename>user.action</filename> file and see how all these pieces come together:
6434 </para>
6435
6436 <sect3 id="match-all">
6437 <title>match-all.action</title>
6438 <para>
6439  Remember <emphasis>all actions are disabled when matching starts</emphasis>,
6440  so we have to explicitly enable the ones we want.
6441 </para>
6442
6443 <para>
6444  While the <filename>match-all.action</filename> file only contains a
6445  single section, it is probably the most important one. It has only one
6446  pattern, <quote><literal>/</literal></quote>, but this pattern
6447  <link linkend="af-patterns">matches all URLs</link>. Therefore, the set of
6448  actions used in this <quote>default</quote> section <emphasis>will
6449  be applied to all requests as a start</emphasis>. It can  be partly or
6450  wholly overridden by other actions files like <filename>default.action</filename>
6451  and <filename>user.action</filename>, but it will still be largely responsible
6452  for your overall browsing experience.
6453 </para>
6454
6455 <para>
6456  Again, at the start of matching, all actions are disabled, so there is
6457  no need to disable any actions here. (Remember: a <quote>+</quote>
6458  preceding the action name enables the action, a <quote>-</quote> disables!).
6459  Also note how this long line has been made more readable by splitting it into
6460  multiple lines with line continuation.
6461 </para>
6462
6463  <screen>
6464 { \
6465  +<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
6466  +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
6467  +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
6468 }
6469 / # Match all URLs
6470 </screen>
6471
6472 <para>
6473  The default behavior is now set.
6474 </para>
6475 </sect3>
6476
6477 <sect3 id="default-action">
6478 <title>default.action</title>
6479
6480 <para>
6481  If you aren't a developer, there's no need for you to edit the
6482  <filename>default.action</filename> file. It is maintained by
6483  the &my-app; developers and if you disagree with some of the
6484  sections, you should overrule them in your <filename>user.action</filename>.
6485 </para>
6486
6487 <para>
6488  Understanding the <filename>default.action</filename> file can
6489  help you with your <filename>user.action</filename>, though.
6490 </para>
6491
6492 <para>
6493  The first section in this file is a special section for internal use
6494  that prevents older &my-app; versions from reading the file:
6495 </para>
6496
6497  <screen>
6498 ##########################################################################
6499 # Settings -- Don't change! For internal Privoxy use ONLY.
6500 ##########################################################################
6501 {{settings}}
6502 for-privoxy-version=3.0.11</screen>
6503
6504 <para>
6505  After that comes the (optional) alias section. We'll use the example
6506  section from the above <link linkend="aliases">chapter on aliases</link>,
6507  that also explains why and how aliases are used:
6508 </para>
6509
6510  <screen>
6511 ##########################################################################
6512 # Aliases
6513 ##########################################################################
6514 {{alias}}
6515
6516  # These aliases just save typing later:
6517  # (Note that some already use other aliases!)
6518  #
6519  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
6520  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
6521  +block-as-image      = +block{Blocked image.} +handle-as-image
6522  mercy-for-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
6523
6524  # These aliases define combinations of actions
6525  # that are useful for certain types of sites:
6526  #
6527  fragile     = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link>
6528  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
6529
6530 <para>
6531  The first of our specialized sections is concerned with <quote>fragile</quote>
6532  sites, i.e. sites that require minimum interference, because they are either
6533  very complex or very keen on tracking you (and have mechanisms in place that
6534  make them unusable for people who avoid being tracked). We will use
6535  our pre-defined <literal>fragile</literal> alias instead of stating the list
6536  of actions explicitly:
6537 </para>
6538
6539  <screen>
6540 ##########################################################################
6541 # Exceptions for sites that'll break under the default action set:
6542 ##########################################################################
6543
6544 # "Fragile" Use a minimum set of actions for these sites (see alias above):
6545 #
6546 { fragile }
6547 .office.microsoft.com           # surprise, surprise!
6548 .windowsupdate.microsoft.com
6549 mail.google.com</screen>
6550
6551 <para>
6552  Shopping sites are not as fragile, but they typically
6553  require cookies to log in, and pop-up windows for shopping
6554  carts or item details. Again, we'll use a pre-defined alias:
6555 </para>
6556
6557  <screen>
6558 # Shopping sites:
6559 #
6560 { shop }
6561 .quietpc.com
6562 .worldpay.com   # for quietpc.com
6563 .jungle.com
6564 .scan.co.uk</screen>
6565
6566 <para>
6567  The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
6568  action, which may have been enabled in <filename>match-all.action</filename>,
6569  breaks some sites. So disable it for popular sites where we know it misbehaves:
6570 </para>
6571
6572  <screen>
6573 { -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
6574 login.yahoo.com
6575 edit.*.yahoo.com
6576 .google.com
6577 .altavista.com/.*(like|url|link):http
6578 .altavista.com/trans.*urltext=http
6579 .nytimes.com</screen>
6580
6581 <para>
6582  It is important that <application>Privoxy</application> knows which
6583  URLs belong to images, so that <emphasis>if</emphasis> they are to
6584  be blocked, a substitute image can be sent, rather than an HTML page.
6585  Contacting the remote site to find out is not an option, since it
6586  would destroy the loading time advantage of banner blocking, and it
6587  would feed the advertisers information about you. We can mark any
6588  URL as an image with the <literal><link
6589  linkend="handle-as-image">handle-as-image</link></literal> action,
6590  and marking all URLs that end in a known image file extension is a
6591  good start:
6592 </para>
6593
6594  <screen>
6595 ##########################################################################
6596 # Images:
6597 ##########################################################################
6598
6599 # Define which file types will be treated as images, in case they get
6600 # blocked further down this file:
6601 #
6602 { +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
6603 /.*\.(gif|jpe?g|png|bmp|ico)$</screen>
6604
6605 <para>
6606  And then there are known banner sources. They often use scripts to
6607  generate the banners, so it won't be visible from the URL that the
6608  request is for an image. Hence we block them <emphasis>and</emphasis>
6609  mark them as images in one go, with the help of our
6610  <literal>+block-as-image</literal> alias defined above. (We could of
6611  course just as well use <literal>+<link linkend="block">block</link>
6612  +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
6613  Remember that the type of the replacement image is chosen by the
6614  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
6615  action. Since all URLs have matched the default section with its
6616  <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
6617  action before, it still applies and needn't be repeated:
6618 </para>
6619
6620  <screen>
6621 # Known ad generators:
6622 #
6623 { +block-as-image }
6624 ar.atwola.com
6625 .ad.doubleclick.net
6626 .ad.*.doubleclick.net
6627 .a.yimg.com/(?:(?!/i/).)*$
6628 .a[0-9].yimg.com/(?:(?!/i/).)*$
6629 bs*.gsanet.com
6630 .qkimg.net</screen>
6631
6632 <para>
6633  One of the most important jobs of <application>Privoxy</application>
6634  is to block banners. Many of these can be <quote>blocked</quote>
6635  by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
6636  action, which we enabled above, and which deletes the references to banner
6637  images from the pages while they are loaded, so the browser doesn't request
6638  them anymore, and hence they don't need to be blocked here. But this naturally
6639  doesn't catch all banners, and some people choose not to use filters, so we
6640  need a comprehensive list of patterns for banner URLs here, and apply the
6641  <literal><link linkend="block">block</link></literal> action to them.
6642 </para>
6643 <para>
6644  First comes many generic patterns, which do most of the work, by
6645  matching typical domain and path name components of banners. Then comes
6646  a list of individual patterns for specific sites, which is omitted here
6647  to keep the example short:
6648 </para>
6649
6650  <screen>
6651 ##########################################################################
6652 # Block these fine banners:
6653 ##########################################################################
6654 { <link linkend="BLOCK">+block{Banner ads.}</link> }
6655
6656 # Generic patterns:
6657 #
6658 ad*.
6659 .*ads.
6660 banner?.
6661 count*.
6662 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
6663 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
6664
6665 # Site-specific patterns (abbreviated):
6666 #
6667 .hitbox.com</screen>
6668
6669 <para>
6670  It's quite remarkable how many advertisers actually call their banner
6671  servers ads.<replaceable>company</replaceable>.com, or call the directory
6672  in which the banners are stored literally <quote>banners</quote>. So the above
6673  generic patterns are surprisingly effective.
6674 </para>
6675 <para>
6676  But being very generic, they necessarily also catch URLs that we don't want
6677  to block. The pattern <literal>.*ads.</literal> e.g. catches
6678  <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
6679  but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
6680  <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
6681  well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
6682  section above.
6683 </para>
6684 <para>
6685  Note that these are exceptions to exceptions from the default! Consider the URL
6686  <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
6687  so it wouldn't get blocked. Then comes the defaults section, which matches the
6688  URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
6689  action once again. Then it matches <literal>.*ads.</literal>, an exception to the
6690  general non-blocking policy, and suddenly
6691  <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
6692  <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
6693  applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
6694  with no <literal><link linkend="BLOCK">block</link></literal> action applying.
6695 </para>
6696
6697  <screen>
6698 ##########################################################################
6699 # Save some innocent victims of the above generic block patterns:
6700 ##########################################################################
6701
6702 # By domain:
6703 #
6704 { -<link linkend="BLOCK">block</link> }
6705 adv[io]*.  # (for advogato.org and advice.*)
6706 adsl.      # (has nothing to do with ads)
6707 adobe.     # (has nothing to do with ads either)
6708 ad[ud]*.   # (adult.* and add.*)
6709 .edu       # (universities don't host banners (yet!))
6710 .*loads.   # (downloads, uploads etc)
6711
6712 # By path:
6713 #
6714 /.*loads/
6715
6716 # Site-specific:
6717 #
6718 www.globalintersec.com/adv # (adv = advanced)
6719 www.ugu.com/sui/ugu/adv</screen>
6720
6721 <para>
6722  Filtering source code can have nasty side effects,
6723  so make an exception for our friends at sourceforge.net,
6724  and all paths with <quote>cvs</quote> in them. Note that
6725  <literal>-<link linkend="FILTER">filter</link></literal>
6726  disables <emphasis>all</emphasis> filters in one fell swoop!
6727 </para>
6728
6729  <screen>
6730 # Don't filter code!
6731 #
6732 { -<link linkend="FILTER">filter</link> }
6733 /(.*/)?cvs
6734 bugzilla.
6735 developer.
6736 wiki.
6737 .sourceforge.net</screen>
6738
6739 <para>
6740  The actual <filename>default.action</filename> is of course much more
6741  comprehensive, but we hope this example made clear how it works.
6742 </para>
6743
6744 </sect3>
6745
6746 <sect3 id="user-action"><title>user.action</title>
6747
6748 <para>
6749  So far we are painting with a broad brush by setting general policies,
6750  which would be a reasonable starting point for many people. Now,
6751  you might want to be more specific and have customized rules that
6752  are more suitable to your personal habits and preferences. These would
6753  be for narrowly defined situations like your ISP or your bank, and should
6754  be placed in <filename>user.action</filename>, which is parsed after all other
6755  actions files and hence has the last word, over-riding any previously
6756  defined actions. <filename>user.action</filename> is also a
6757  <emphasis>safe</emphasis> place for your personal settings, since
6758  <filename>default.action</filename> is actively maintained by the
6759  <application>Privoxy</application> developers and you'll probably want
6760  to install updated versions from time to time.
6761 </para>
6762
6763 <para>
6764  So let's look at a few examples of things that one might typically do in
6765  <filename>user.action</filename>:
6766 </para>
6767
6768
6769 <!-- brief sample user.action here -->
6770
6771  <screen>
6772 # My user.action file. &lt;fred@example.com&gt;</screen>
6773
6774 <para>
6775  As <link linkend="aliases">aliases</link> are local to the actions
6776  file that they are defined in, you can't use the ones from
6777  <filename>default.action</filename>, unless you repeat them here:
6778 </para>
6779
6780  <screen>
6781 # Aliases are local to the file they are defined in.
6782 # (Re-)define aliases for this file:
6783 #
6784 {{alias}}
6785 #
6786 # These aliases just save typing later, and the alias names should
6787 # be self explanatory.
6788 #
6789 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
6790 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
6791  allow-all-cookies  = -crunch-all-cookies -session-cookies-only
6792  allow-popups       = -filter{all-popups}
6793 +block-as-image     = +block{Blocked as image.} +handle-as-image
6794 -block-as-image     = -block
6795
6796 # These aliases define combinations of actions that are useful for
6797 # certain types of sites:
6798 #
6799 fragile     = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
6800 shop        = -crunch-all-cookies allow-popups
6801
6802 # Allow ads for selected useful free sites:
6803 #
6804 allow-ads   = -block -filter{banners-by-size} -filter{banners-by-link}
6805
6806 # Alias for specific file types that are text, but might have conflicting
6807 # MIME types. We want the browser to force these to be text documents.
6808 handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
6809
6810 <para>
6811  Say you have accounts on some sites that you visit regularly, and
6812  you don't want to have to log in manually each time. So you'd like
6813  to allow persistent cookies for these sites. The
6814  <literal>allow-all-cookies</literal> alias defined above does exactly
6815  that, i.e. it disables crunching of cookies in any direction, and the
6816  processing of cookies to make them only temporary.
6817 </para>
6818
6819  <screen>
6820 { allow-all-cookies }
6821  sourceforge.net
6822  .yahoo.com
6823  .msdn.microsoft.com
6824  .redhat.com</screen>
6825
6826 <para>
6827  Your bank is allergic to some filter, but you don't know which, so you disable them all:
6828 </para>
6829
6830  <screen>
6831 { -<link linkend="FILTER">filter</link> }
6832  .your-home-banking-site.com</screen>
6833
6834 <para>
6835  Some file types you may not want to filter for various reasons:
6836 </para>
6837
6838  <screen>
6839 # Technical documentation is likely to contain strings that might
6840 # erroneously get altered by the JavaScript-oriented filters:
6841 #
6842 .tldp.org
6843 /(.*/)?selfhtml/
6844
6845 # And this stupid host sends streaming video with a wrong MIME type,
6846 # so that Privoxy thinks it is getting HTML and starts filtering:
6847 #
6848 stupid-server.example.com/</screen>
6849
6850 <para>
6851  Example of a simple <link linkend="BLOCK">block</link> action. Say you've
6852  seen an ad on your favourite page on example.com that you want to get rid of.
6853  You have right-clicked the image, selected <quote>copy image location</quote>
6854  and pasted the URL below while removing the leading http://, into a
6855  <literal>{ +block{} }</literal> section. Note that <literal>{ +handle-as-image
6856  }</literal> need not be specified, since all URLs ending in
6857  <literal>.gif</literal> will be tagged as images by the general rules as set
6858  in default.action anyway:
6859 </para>
6860
6861  <screen>
6862 { +<link linkend="BLOCK">block</link>{Nasty ads.} }
6863  www.example.com/nasty-ads/sponsor\.gif
6864  another.example.net/more/junk/here/</screen>
6865
6866 <para>
6867  The URLs of dynamically generated banners, especially from large banner
6868  farms, often don't use the well-known image file name extensions, which
6869  makes it impossible for <application>Privoxy</application> to guess
6870  the file type just by looking at the URL.
6871  You can use the <literal>+block-as-image</literal> alias defined above for
6872  these cases.
6873  Note that objects which match this rule but then turn out NOT to be an
6874  image are typically rendered as a <quote>broken image</quote> icon by the
6875  browser. Use cautiously.
6876 </para>
6877
6878  <screen>
6879 { +block-as-image }
6880  .doubleclick.net
6881  .fastclick.net
6882  /Realmedia/ads/
6883  ar.atwola.com/</screen>
6884
6885 <para>
6886  Now you noticed that the default configuration breaks Forbes Magazine,
6887  but you were too lazy to find out which action is the culprit, and you
6888  were again too lazy to give <link linkend="contact">feedback</link>, so
6889  you just used the <literal>fragile</literal> alias on the site, and
6890  -- <emphasis>whoa!</emphasis> -- it worked. The <literal>fragile</literal>
6891  aliases disables those actions that are most likely to break a site. Also,
6892  good for testing purposes to see if it is <application>Privoxy</application>
6893  that is causing the problem or not. We later find other regular sites
6894  that misbehave, and add those to our personalized list of troublemakers:
6895 </para>
6896
6897 <screen>
6898 { fragile }
6899  .forbes.com
6900  webmail.example.com
6901  .mybank.com</screen>
6902
6903 <para>
6904  You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
6905  but it is disabled in the distributed actions file.
6906  So you'd like to turn it on in your private,
6907  update-safe config, once and for all:
6908 </para>
6909
6910 <screen>
6911 { +<link linkend="filter-fun">filter{fun}</link> }
6912  / # For ALL sites!</screen>
6913
6914 <para>
6915  Note that the above is not really a good idea: There are exceptions
6916  to the filters in <filename>default.action</filename> for things that
6917  really shouldn't be filtered, like code on CVS->Web interfaces. Since
6918  <filename>user.action</filename> has the last word, these exceptions
6919  won't be valid for the <quote>fun</quote> filtering specified here.
6920 </para>
6921
6922 <para>
6923  You might also worry about how your favourite free websites are
6924  funded, and find that they rely on displaying banner advertisements
6925  to survive. So you might want to specifically allow banners for those
6926  sites that you feel provide value to you:
6927 </para>
6928
6929 <screen>
6930 { allow-ads }
6931  .sourceforge.net
6932  .slashdot.org
6933  .osdn.net</screen>
6934
6935 <para>
6936  Note that <literal>allow-ads</literal> has been aliased to
6937  <literal>-<link linkend="block">block</link></literal>,
6938  <literal>-<link linkend="filter-banners-by-size">filter{banners-by-size}</link></literal>, and
6939  <literal>-<link linkend="filter-banners-by-link">filter{banners-by-link}</link></literal> above.
6940 </para>
6941
6942 <para>
6943  Invoke another alias here to force an over-ride of the MIME type <literal>
6944  application/x-sh</literal> which typically would open a download type
6945  dialog. In my case, I want to look at the shell script, and then I can save
6946  it should I choose to.
6947 </para>
6948
6949 <screen>
6950 { handle-as-text }
6951  /.*\.sh$</screen>
6952
6953 <para>
6954  <filename>user.action</filename> is generally the best place to define
6955  exceptions and additions to the default policies of
6956  <filename>default.action</filename>. Some actions are safe to have their
6957  default policies set here though. So let's set a default policy to have a
6958  <quote>blank</quote> image as opposed to the checkerboard pattern for
6959  <emphasis>ALL</emphasis> sites. <quote>/</quote> of course matches all URL
6960  paths and patterns:
6961 </para>
6962
6963 <screen>
6964 { +<link linkend="set-image-blocker">set-image-blocker{blank}</link> }
6965 / # ALL sites</screen>
6966
6967 </sect3>
6968 </sect2>
6969
6970 <!--  ~  End section  ~  -->
6971
6972 </sect1>
6973
6974 <!--  ~  End section  ~  -->
6975
6976 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6977
6978 <sect1 id="filter-file">
6979 <title>Filter Files</title>
6980
6981 <para>
6982  On-the-fly text substitutions need
6983  to be defined in a <quote>filter file</quote>. Once defined, they
6984  can then be invoked as an <quote>action</quote>.
6985 </para>
6986
6987 <para>
6988  &my-app; supports four different pcrs-based filter actions:
6989  <literal><link linkend="filter">filter</link></literal> to
6990  rewrite the content that is send to the client,
6991  <literal><link linkend="client-header-filter">client-header-filter</link></literal>
6992  to rewrite headers that are send by the client,
6993  <literal><link linkend="server-header-filter">server-header-filter</link></literal>
6994  to rewrite headers that are send by the server, and
6995  <literal><link linkend="client-body-filter">client-body-filter</link></literal>
6996  to rewrite client request body.
6997 </para>
6998
6999 <para>
7000  &my-app; also supports two tagger actions:
7001  <literal><link linkend="client-header-tagger">client-header-tagger</link></literal>
7002  and
7003  <literal><link linkend="server-header-tagger">server-header-tagger</link></literal>.
7004  Taggers and filters use the same syntax in the filter files, the difference
7005  is that taggers don't modify the text they are filtering, but use a rewritten
7006  version of the filtered text as tag. The tags can then be used to change the
7007  applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
7008 </para>
7009
7010 <para>
7011  Finally &my-app; supports the
7012  <literal><link linkend="external-filter">external-filter</link></literal> action
7013  to enable <literal><link linkend="external-filter-syntax">external filters</link></literal>
7014  written in proper programming languages.
7015 </para>
7016
7017
7018 <para>
7019  Multiple filter files can be defined through the <literal> <link
7020  linkend="filterfile">filterfile</link></literal> config directive. The filters
7021  as supplied by the developers are located in
7022  <filename>default.filter</filename>. It is recommended that any locally
7023  defined or modified filters go in a separately defined file such as
7024  <filename>user.filter</filename>.
7025  </para>
7026
7027 <para>
7028  Common tasks for content filters are to eliminate common annoyances in
7029  HTML and JavaScript, such as pop-up windows,
7030  exit consoles, crippled windows without navigation tools, the
7031  infamous &lt;BLINK&gt; tag etc, to suppress images with certain
7032  width and height attributes (standard banner sizes or web-bugs),
7033  or just to have fun.
7034 </para>
7035
7036 <para>
7037  Enabled content filters are applied to any content whose
7038  <quote>Content Type</quote> header is recognised as a sign
7039  of text-based content, with the exception of <literal>text/plain</literal>.
7040  Use the <link linkend="FORCE-TEXT-MODE">force-text-mode</link> action
7041  to also filter other content.
7042 </para>
7043
7044 <para>
7045  Substitutions are made at the source level, so if you want to <quote>roll
7046  your own</quote> filters, you should first be familiar with HTML syntax,
7047  and, of course, regular expressions.
7048 </para>
7049
7050 <para>
7051  Just like the <link linkend="actions-file">actions files</link>, the
7052  filter file is organized in sections, which are called <emphasis>filters</emphasis>
7053  here. Each filter consists of a heading line, that starts with one of the
7054  <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
7055  <literal>CLIENT-HEADER-FILTER:</literal>, <literal>SERVER-HEADER-FILTER:</literal> or
7056  <literal>CLIENT-BODY-FILTER:</literal>
7057  followed by the filter's <emphasis>name</emphasis>, and a short (one line)
7058  <emphasis>description</emphasis> of what it does. Below that line
7059  come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
7060  text substitutions. By convention, the name of a filter
7061  should describe what the filter <emphasis>eliminates</emphasis>. The
7062  comment is used in the <ulink url="http://config.privoxy.org/">web-based
7063  user interface</ulink>.
7064 </para>
7065
7066 <para>
7067  Once a filter called <replaceable>name</replaceable> has been defined
7068  in the filter file, it can be invoked by using an action of the form
7069  +<literal><link linkend="filter">filter</link>{<replaceable>name</replaceable>}</literal>
7070  in any <link linkend="actions-file">actions file</link>.
7071 </para>
7072
7073 <para>
7074  Filter definitions start with a header line that contains the filter
7075  type, the filter name and the filter description.
7076  A content filter header line for a filter called <quote>foo</quote> could look
7077  like this:
7078 </para>
7079
7080  <screen>FILTER: foo Replace all "foo" with "bar"</screen>
7081
7082 <para>
7083  Below that line, and up to the next header line, come the jobs that
7084  define what text replacements the filter executes. They are specified
7085  in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
7086  <literal>s///</literal> operator. If you are familiar with Perl, you
7087  will find this to be quite intuitive, and may want to look at the
7088  PCRS documentation for the subtle differences to Perl behaviour.
7089 </para>
7090
7091 <para>
7092  Most notably, the non-standard option letter <literal>U</literal> is supported,
7093  which turns the default to ungreedy matching (add <literal>?</literal> to
7094  quantifiers to turn them greedy again).
7095 </para>
7096
7097 <para>
7098  The non-standard option letter <literal>D</literal> (dynamic) allows
7099  to use the variables $host, $origin (the IP address the request came from),
7100  $path, $url and $listen-address (the address on which Privoxy accepted the
7101  client request. Example: 127.0.0.1:8118).
7102  They will be replaced with the value they refer to before the filter
7103  is executed.
7104 </para>
7105
7106 <para>
7107  Note that '$' is a bad choice for a delimiter in a dynamic filter as you
7108  might end up with unintended variables if you use a variable name
7109  directly after the delimiter. Variables will be resolved without
7110  escaping anything, therefore you also have to be careful not to chose
7111  delimiters that appear in the replacement text. For example '<' should
7112  be save, while '?' will sooner or later cause conflicts with $url.
7113 </para>
7114
7115 <para>
7116  The non-standard option letter <literal>T</literal> (trivial) prevents
7117  parsing for backreferences in the substitute. Use it if you want to include
7118  text like '$&' in your substitute without quoting.
7119 </para>
7120
7121 <para>
7122  If you are new to
7123   <ulink url="https://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
7124   Expressions</quote></ulink>, you might want to take a look at
7125  the <link linkend="regex">Appendix on regular expressions</link>, and
7126  see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
7127  manual</ulink> for
7128  <ulink url="http://perldoc.perl.org/perlop.html">the
7129  <literal>s///</literal> operator's syntax</ulink> and <ulink
7130  url="http://perldoc.perl.org/perlre.html">Perl-style regular
7131  expressions</ulink> in general.
7132  The below examples might also help to get you started.
7133 </para>
7134
7135
7136 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
7137
7138 <sect2 id="filter-file-tut"><title>Filter File Tutorial</title>
7139 <para>
7140  Now, let's complete our <quote>foo</quote> content filter. We have already defined
7141  the heading, but the jobs are still missing. Since all it does is to replace
7142  <quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
7143  needed:
7144 </para>
7145
7146  <screen>s/foo/bar/</screen>
7147
7148 <para>
7149  But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
7150  of <quote>foo</quote> should be replaced? Our current job will only take
7151  care of the first <quote>foo</quote> on each page. For global substitution,
7152  we'll need to add the <literal>g</literal> option:
7153 </para>
7154
7155  <screen>s/foo/bar/g</screen>
7156
7157 <para>
7158  Our complete filter now looks like this:
7159 </para>
7160
7161  <screen>FILTER: foo Replace all "foo" with "bar"
7162 s/foo/bar/g</screen>
7163
7164 <para>
7165  Let's look at some real filters for more interesting examples. Here you see
7166  a filter that protects against some common annoyances that arise from JavaScript
7167  abuse. Let's look at its jobs one after the other:
7168 </para>
7169
7170
7171  <screen>
7172 FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
7173
7174 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
7175 #
7176 s|(&lt;script.*)document\.referrer(.*&lt;/script&gt;)|$1"Not Your Business!"$2|Usg</screen>
7177
7178 <para>
7179  Following the header line and a comment, you see the job. Note that it uses
7180  <literal>|</literal> as the delimiter instead of <literal>/</literal>, because
7181  the pattern contains a forward slash, which would otherwise have to be escaped
7182  by a backslash (<literal>\</literal>).
7183 </para>
7184
7185 <para>
7186  Now, let's examine the pattern: it starts with the text <literal>&lt;script.*</literal>
7187  enclosed in parentheses. Since the dot matches any character, and <literal>*</literal>
7188  means: <quote>Match an arbitrary number of the element left of myself</quote>, this
7189  matches <quote>&lt;script</quote>, followed by <emphasis>any</emphasis> text, i.e.
7190  it matches the whole page, from the start of the first &lt;script&gt; tag.
7191 </para>
7192
7193 <para>
7194  That's more than we want, but the pattern continues: <literal>document\.referrer</literal>
7195  matches only the exact string <quote>document.referrer</quote>. The dot needed to
7196  be <emphasis>escaped</emphasis>, i.e. preceded by a backslash, to take away its
7197  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
7198  Match from the start of the first &lt;script&gt; tag in a the page, up to, and including,
7199  the text <quote>document.referrer</quote>, if <emphasis>both</emphasis> are present
7200  in the page (and appear in that order).
7201 </para>
7202
7203 <para>
7204  But there's still more pattern to go. The next element, again enclosed in parentheses,
7205  is <literal>.*&lt;/script&gt;</literal>. You already know what <literal>.*</literal>
7206  means, so the whole pattern translates to: Match from the start of the first  &lt;script&gt;
7207  tag in a page to the end of the last &lt;script&gt; tag, provided that the text
7208  <quote>document.referrer</quote> appears somewhere in between.
7209 </para>
7210
7211 <para>
7212  This is still not the whole story, since we have ignored the options and the parentheses:
7213  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
7214  remembered and be available through the variables <literal>$1, $2, ...</literal> in
7215  the substitute. The <literal>U</literal> option switches to ungreedy matching, which means
7216  that the first <literal>.*</literal> in the pattern will only <quote>eat up</quote> all
7217  text in between <quote>&lt;script</quote> and the <emphasis>first</emphasis> occurrence
7218  of <quote>document.referrer</quote>, and that the second <literal>.*</literal> will
7219  only span the text up to the <emphasis>first</emphasis> <quote>&lt;/script&gt;</quote>
7220  tag. Furthermore, the <literal>s</literal> option says that the match may span
7221  multiple lines in the page, and the <literal>g</literal> option again means that the
7222  substitution is global.
7223 </para>
7224
7225 <para>
7226  So, to summarize, the pattern means: Match all scripts that contain the text
7227  <quote>document.referrer</quote>. Remember the parts of the script from
7228  (and including) the start tag up to (and excluding) the string
7229  <quote>document.referrer</quote> as <literal>$1</literal>, and the part following
7230  that string, up to and including the closing tag, as <literal>$2</literal>.
7231 </para>
7232
7233 <para>
7234  Now the pattern is deciphered, but wasn't this about substituting things? So
7235  lets look at the substitute: <literal>$1"Not Your Business!"$2</literal> is
7236  easy to read: The text remembered as <literal>$1</literal>, followed by
7237  <literal>"Not Your Business!"</literal> (<emphasis>including</emphasis>
7238  the quotation marks!), followed by the text remembered as <literal>$2</literal>.
7239  This produces an exact copy of the original string, with the middle part
7240  (the <quote>document.referrer</quote>) replaced by <literal>"Not Your
7241  Business!"</literal>.
7242 </para>
7243
7244 <para>
7245  The whole job now reads: Replace <quote>document.referrer</quote> by
7246  <literal>"Not Your Business!"</literal> wherever it appears inside a
7247  &lt;script&gt tag. Note that this job won't break JavaScript syntax,
7248  since both the original and the replacement are syntactically valid
7249  string objects. The script just won't have access to the referrer
7250  information anymore.
7251 </para>
7252
7253 <para>
7254  We'll show you two other jobs from the JavaScript taming department, but
7255  this time only point out the constructs of special interest:
7256 </para>
7257
7258  <screen>
7259 # The status bar is for displaying link targets, not pointless blahblah
7260 #
7261 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
7262
7263 <para>
7264  <literal>\s</literal> stands for whitespace characters (space, tab, newline,
7265  carriage return, form feed), so that <literal>\s*</literal> means: <quote>zero
7266  or more whitespace</quote>. The <literal>?</literal> in <literal>.*?</literal>
7267  makes this matching of arbitrary text ungreedy. (Note that the <literal>U</literal>
7268  option is not set). The <literal>['"]</literal> construct means: <quote>a single
7269  <emphasis>or</emphasis> a double quote</quote>. Finally, <literal>\1</literal> is
7270  a back-reference to the first parenthesis just like <literal>$1</literal> above,
7271  with the difference that in the <emphasis>pattern</emphasis>, a backslash indicates
7272  a back-reference, whereas in the <emphasis>substitute</emphasis>, it's the dollar.
7273 </para>
7274
7275 <para>
7276  So what does this job do? It replaces assignments of single- or double-quoted
7277  strings to the <quote>window.status</quote> object with a dummy assignment
7278  (using a variable name that is hopefully odd enough not to conflict with
7279  real variables in scripts). Thus, it catches many cases where e.g. pointless
7280  descriptions are displayed in the status bar instead of the link target when
7281  you move your mouse over links.
7282 </para>
7283
7284  <screen>
7285 # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
7286 #
7287 s/(&lt;body [^&gt;]*)onunload(.*&gt;)/$1never$2/iU</screen>
7288
7289 <para>
7290  Including the
7291  <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">OnUnload
7292  event binding</ulink> in the HTML DOM was a <emphasis>CRIME</emphasis>.
7293  When I close a browser window, I want it to close and die. Basta.
7294  This job replaces the <quote>onunload</quote> attribute in
7295  <quote>&lt;body&gt</quote> tags with the dummy word <literal>never</literal>.
7296  Note that the <literal>i</literal> option makes the pattern matching
7297  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
7298  a minimal match: In the first parenthesis, we had to use <literal>[^&gt;]*</literal>
7299  instead of <literal>.*</literal> to prevent the match from exceeding the
7300  &lt;body&gt tag if it doesn't contain <quote>OnUnload</quote>, but the page's
7301  content does.
7302 </para>
7303
7304 <para>
7305  The last example is from the fun department:
7306 </para>
7307
7308  <screen>
7309 FILTER: fun Fun text replacements
7310
7311 # Spice the daily news:
7312 #
7313 s/microsoft(?!\.com)/MicroSuck/ig</screen>
7314
7315 <para>
7316  Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
7317  in the job's pattern, which means: Don't match, if the string
7318  <quote>.com</quote> appears directly following <quote>microsoft</quote>
7319  in the page. This prevents links to microsoft.com from being trashed, while
7320  still replacing the word everywhere else.
7321 </para>
7322
7323  <screen>
7324 # Buzzword Bingo (example for extended regex syntax)
7325 #
7326 s* industry[ -]leading \
7327 |  cutting[ -]edge \
7328 |  customer[ -]focused \
7329 |  market[ -]driven \
7330 |  award[ -]winning # Comments are OK, too! \
7331 |  high[ -]performance \
7332 |  solutions[ -]based \
7333 |  unmatched \
7334 |  unparalleled \
7335 |  unrivalled \
7336 *&lt;font color="red"&gt;&lt;b&gt;BINGO!&lt;/b&gt;&lt;/font&gt; \
7337 *igx</screen>
7338
7339 <para>
7340  The <literal>x</literal> option in this job turns on extended syntax, and allows for
7341  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting.
7342 </para>
7343
7344 <para>
7345  You get the idea?
7346 </para>
7347 </sect2>
7348
7349 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
7350
7351 <sect2 id="predefined-filters"><title>The Pre-defined Filters</title>
7352
7353 <!--
7354
7355  Note each filter is also listed in the +filter action section above. Please
7356  keep these listings in sync.
7357
7358 -->
7359
7360 <para>
7361 The distribution <filename>default.filter</filename> file contains a selection of
7362 pre-defined filters for your convenience:
7363 </para>
7364
7365 <variablelist>
7366  <varlistentry>
7367   <term><emphasis>js-annoyances</emphasis></term>
7368   <listitem>
7369    <para>
7370     The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
7371     To that end, it
7372    </para>
7373    <itemizedlist>
7374     <listitem>
7375      <para>
7376       replaces JavaScript references to the browser's referrer information
7377       with the string "Not Your Business!". This compliments the <literal><link
7378       linkend="hide-referrer">hide-referrer</link></literal> action on the content level.
7379      </para>
7380     </listitem>
7381     <listitem>
7382      <para>
7383       removes the bindings to the DOM's
7384       <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">unload
7385       event</ulink> which we feel has no right to exist and is responsible for most <quote>exit consoles</quote>, i.e.
7386       nasty windows that pop up when you close another one.
7387      </para>
7388     </listitem>
7389     <listitem>
7390      <para>
7391       removes code that causes new windows to be opened with undesired properties, such as being
7392       full-screen, non-resizeable, without location, status or menu bar etc.
7393      </para>
7394     </listitem>
7395    </itemizedlist>
7396    <para>
7397     Use with caution. This is an aggressive filter, and can break sites that
7398     rely heavily on JavaScript.
7399    </para>
7400   </listitem>
7401  </varlistentry>
7402
7403  <varlistentry>
7404   <term><emphasis>js-events</emphasis></term>
7405   <listitem>
7406    <para>
7407     This is a very radical measure. It removes virtually all JavaScript event bindings, which
7408     means that scripts can not react to user actions such as mouse movements or clicks, window
7409     resizing etc, anymore. Use with caution!
7410    </para>
7411    <para>
7412     We <emphasis>strongly discourage</emphasis> using this filter as a default since it breaks
7413     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
7414     need to go there).
7415    </para>
7416   </listitem>
7417  </varlistentry>
7418
7419 <varlistentry>
7420   <term><emphasis>html-annoyances</emphasis></term>
7421   <listitem>
7422    <para>
7423     This filter will undo many common instances of HTML based abuse.
7424    </para>
7425    <para>
7426     The <literal>BLINK</literal> and <literal>MARQUEE</literal> tags
7427     are neutralized (yeah baby!), and browser windows will be created as
7428     resizeable (as of course they should be!), and will have location,
7429     scroll and menu bars -- even if specified otherwise.
7430    </para>
7431   </listitem>
7432  </varlistentry>
7433
7434  <varlistentry>
7435   <term><emphasis>content-cookies</emphasis></term>
7436   <listitem>
7437    <para>
7438     Most cookies are set in the HTTP dialog, where they can be intercepted
7439     by the
7440     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>
7441     and <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>
7442     actions. But web sites increasingly make use of HTML meta tags and JavaScript
7443     to sneak cookies to the browser on the content level.
7444    </para>
7445    <para>
7446     This filter disables most HTML and JavaScript code that reads or sets
7447     cookies. It cannot detect all clever uses of these types of code, so it
7448     should not be relied on as an absolute fix. Use it wherever you would also
7449     use the cookie crunch actions.
7450    </para>
7451   </listitem>
7452  </varlistentry>
7453
7454  <varlistentry>
7455   <term><emphasis>refresh-tags</emphasis></term>
7456   <listitem>
7457    <para>
7458     Disable any refresh tags if the interval is greater than nine seconds (so
7459     that redirections done via refresh tags are not destroyed). This is useful
7460     for dial-on-demand setups, or for those who find this HTML feature
7461     annoying.
7462    </para>
7463   </listitem>
7464  </varlistentry>
7465
7466  <varlistentry>
7467   <term><emphasis>unsolicited-popups</emphasis></term>
7468   <listitem>
7469    <para>
7470     This filter attempts to prevent only <quote>unsolicited</quote> pop-up
7471     windows from opening, yet still allow pop-up windows that the user
7472     has explicitly chosen to open. It was added in version 3.0.1,
7473     as an improvement over earlier such filters.
7474    </para>
7475    <para>
7476     Technical note: The filter works by redefining the window.open JavaScript
7477     function to a dummy function, <literal>PrivoxyWindowOpen()</literal>,
7478     during the loading and rendering phase of each HTML page access, and
7479     restoring the function afterward.
7480    </para>
7481    <para>
7482     This is recommended only for browsers that cannot perform this function
7483     reliably themselves. And be aware that some sites require such windows
7484     in order to function normally. Use with caution.
7485    </para>
7486   </listitem>
7487  </varlistentry>
7488
7489  <varlistentry>
7490   <term><emphasis>all-popups</emphasis></term>
7491   <listitem>
7492    <para>
7493     Attempt to prevent <emphasis>all</emphasis> pop-up windows from opening.
7494     Note this should be used with even more discretion than the above, since
7495     it is more likely to break some sites that require pop-ups for normal
7496     usage. Use with caution.
7497    </para>
7498   </listitem>
7499  </varlistentry>
7500
7501  <varlistentry>
7502   <term><emphasis>img-reorder</emphasis></term>
7503   <listitem>
7504    <para>
7505     This is a helper filter that has no value if used alone. It makes the
7506     <literal>banners-by-size</literal> and <literal>banners-by-link</literal>
7507     (see below) filters more effective and should be enabled together with them.
7508    </para>
7509   </listitem>
7510  </varlistentry>
7511
7512  <varlistentry>
7513   <term><emphasis>banners-by-size</emphasis></term>
7514   <listitem>
7515    <para>
7516     This filter removes image tags purely based on what size they are. Fortunately
7517     for us, many ads and banner images tend to conform to certain standardized
7518     sizes, which makes this filter quite effective for ad stripping purposes.
7519    </para>
7520    <para>
7521     Occasionally this filter will cause false positives on images that are not ads,
7522     but just happen to be of one of the standard banner sizes.
7523    </para>
7524    <para>
7525     Recommended only for those who require extreme ad blocking. The default
7526     block rules should catch 95+% of all ads <emphasis>without</emphasis> this filter enabled.
7527    </para>
7528   </listitem>
7529  </varlistentry>
7530
7531  <varlistentry>
7532   <term><emphasis>banners-by-link</emphasis></term>
7533   <listitem>
7534    <para>
7535     This is an experimental filter that attempts to kill any banners if
7536     their URLs seem to point to known or suspected click trackers. It is currently
7537     not of much value and is not recommended for use by default.
7538    </para>
7539   </listitem>
7540  </varlistentry>
7541
7542  <varlistentry>
7543   <term><emphasis>webbugs</emphasis></term>
7544   <listitem>
7545    <para>
7546     Webbugs are small, invisible images (technically 1X1 GIF images), that
7547     are used to track users across websites, and collect information on them.
7548     As an HTML page is loaded by the browser, an embedded image tag causes the
7549     browser to contact a third-party site, disclosing the tracking information
7550     through the requested URL and/or cookies for that third-party domain, without
7551     the user ever becoming aware of the interaction with the third-party site.
7552     HTML-ized spam also uses a similar technique to verify email addresses.
7553    </para>
7554    <para>
7555     This filter removes the HTML code that loads such <quote>webbugs</quote>.
7556    </para>
7557   </listitem>
7558  </varlistentry>
7559
7560  <varlistentry>
7561   <term><emphasis>tiny-textforms</emphasis></term>
7562   <listitem>
7563    <para>
7564     A rather special-purpose filter that can be used to enlarge textareas (those
7565     multi-line text boxes in web forms) and turn off hard word wrap in them.
7566     It was written for the sourceforge.net tracker system where such boxes are
7567     a nuisance, but it can be handy on other sites, too.
7568    </para>
7569    <para>
7570     It is not recommended to use this filter as a default.
7571    </para>
7572   </listitem>
7573  </varlistentry>
7574
7575  <varlistentry>
7576   <term><emphasis>jumping-windows</emphasis></term>
7577   <listitem>
7578    <para>
7579     Many consider windows that move, or resize themselves to be abusive. This filter
7580     neutralizes the related JavaScript code. Note that some sites might not display
7581     or behave as intended when using this filter. Use with caution.
7582    </para>
7583   </listitem>
7584  </varlistentry>
7585
7586  <varlistentry>
7587   <term><emphasis>frameset-borders</emphasis></term>
7588   <listitem>
7589    <para>
7590     Some web designers seem to assume that everyone in the world will view their
7591     web sites using the same browser brand and version, screen resolution etc,
7592     because only that assumption could explain why they'd use static frame sizes,
7593     yet prevent their frames from being resized by the user, should they be too
7594     small to show their whole content.
7595    </para>
7596    <para>
7597     This filter removes the related HTML code. It should only be applied to sites
7598     which need it.
7599    </para>
7600   </listitem>
7601  </varlistentry>
7602
7603  <varlistentry>
7604   <term><emphasis>demoronizer</emphasis></term>
7605   <listitem>
7606    <para>
7607     Many Microsoft products that generate HTML use non-standard extensions (read:
7608     violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
7609     HTML documents to display with errors on standard-compliant platforms.
7610    </para>
7611    <para>
7612     This filter translates the MS-only characters into Latin-1 equivalents.
7613     It is not necessary when using MS products, and will cause corruption of
7614     all documents that use 8-bit character sets other than Latin-1. It's mostly
7615     worthwhile for Europeans on non-MS platforms, if weird garbage characters
7616     sometimes appear on some pages, or user agents that don't correct for this on
7617     the fly.
7618 <!--
7619     My version of Mozilla (ancient) shows little square boxes for quote
7620     characters, and apostrophes on moronized pages. So many pages have this, I
7621     can read them fine now. HB 08/27/06
7622 -->
7623    </para>
7624   </listitem>
7625  </varlistentry>
7626
7627  <varlistentry>
7628   <term><emphasis>shockwave-flash</emphasis></term>
7629   <listitem>
7630    <para>
7631     A filter for shockwave haters. As the name suggests, this filter strips code
7632     out of web pages that is used to embed shockwave flash objects.
7633    </para>
7634    <para>
7635    </para>
7636   </listitem>
7637  </varlistentry>
7638
7639  <varlistentry>
7640   <term><emphasis>quicktime-kioskmode</emphasis></term>
7641   <listitem>
7642    <para>
7643     Change HTML code that embeds Quicktime objects so that kioskmode, which
7644     prevents saving, is disabled.
7645    </para>
7646   </listitem>
7647  </varlistentry>
7648
7649  <varlistentry>
7650   <term><emphasis>fun</emphasis></term>
7651   <listitem>
7652    <para>
7653     Text replacements for subversive browsing fun. Make fun of your favorite
7654     Monopolist or play buzzword bingo.
7655    </para>
7656   </listitem>
7657  </varlistentry>
7658
7659  <varlistentry>
7660   <term><emphasis>crude-parental</emphasis></term>
7661   <listitem>
7662    <para>
7663     A demonstration-only filter that shows how <application>Privoxy</application>
7664     can be used to delete web content on a keyword basis.
7665    </para>
7666   </listitem>
7667  </varlistentry>
7668
7669  <varlistentry>
7670   <term><emphasis>ie-exploits</emphasis></term>
7671   <listitem>
7672    <para>
7673     An experimental collection of text replacements to disable malicious HTML and JavaScript
7674     code that exploits known security holes in Internet Explorer.
7675    </para>
7676    <para>
7677     Presently, it only protects against Nimda and a cross-site scripting bug, and
7678     would need active maintenance to provide more substantial protection.
7679    </para>
7680   </listitem>
7681  </varlistentry>
7682
7683  <varlistentry>
7684   <term><emphasis>site-specifics</emphasis></term>
7685   <listitem>
7686    <para>
7687     Some web sites have very specific problems, the cure for which doesn't apply
7688     anywhere else, or could even cause damage on other sites.
7689    </para>
7690    <para>
7691     This is a collection of such site-specific cures which should only be applied
7692     to the sites they were intended for, which is what the supplied
7693     <filename>default.action</filename> file does. Users shouldn't need to change
7694     anything regarding this filter.
7695    </para>
7696   </listitem>
7697  </varlistentry>
7698
7699  <varlistentry>
7700   <term><emphasis>google</emphasis></term>
7701   <listitem>
7702    <para>
7703     A CSS based block for Google text ads. Also removes a width limitation
7704     and the toolbar advertisement.
7705    </para>
7706   </listitem>
7707  </varlistentry>
7708
7709   <varlistentry>
7710   <term><emphasis>yahoo</emphasis></term>
7711   <listitem>
7712    <para>
7713     Another CSS based block, this time for Yahoo text ads. And removes
7714     a width limitation as well.
7715    </para>
7716   </listitem>
7717  </varlistentry>
7718
7719   <varlistentry>
7720   <term><emphasis>msn</emphasis></term>
7721   <listitem>
7722    <para>
7723     Another CSS based block, this time for MSN text ads. And removes
7724     tracking URLs, as well as a width limitation.
7725    </para>
7726   </listitem>
7727  </varlistentry>
7728
7729  <varlistentry>
7730   <term><emphasis>blogspot</emphasis></term>
7731   <listitem>
7732    <para>
7733     Cleans up some Blogspot blogs. Read the fine print before using this one!
7734    </para>
7735    <para>
7736     This filter also intentionally removes some navigation stuff and sets the
7737     page width to 100%. As a result, some rounded <quote>corners</quote> would
7738     appear to early or not at all and as fixing this would require a browser
7739     that understands background-size (CSS3), they are removed instead.
7740    </para>
7741   </listitem>
7742  </varlistentry>
7743
7744   <varlistentry>
7745   <term><emphasis>xml-to-html</emphasis></term>
7746   <listitem>
7747    <para>
7748     Server-header filter to change the Content-Type from xml to html.
7749    </para>
7750   </listitem>
7751  </varlistentry>
7752
7753   <varlistentry>
7754   <term><emphasis>html-to-xml</emphasis></term>
7755   <listitem>
7756    <para>
7757     Server-header filter to change the Content-Type from html to xml.
7758    </para>
7759   </listitem>
7760  </varlistentry>
7761
7762   <varlistentry>
7763   <term><emphasis>no-ping</emphasis></term>
7764   <listitem>
7765    <para>
7766     Removes the non-standard <literal>ping</literal> attribute from
7767     anchor and area HTML tags.
7768    </para>
7769   </listitem>
7770  </varlistentry>
7771
7772   <varlistentry>
7773   <term><emphasis>hide-tor-exit-notation</emphasis></term>
7774   <listitem>
7775    <para>
7776     Client-header filter to remove the <command>Tor</command> exit node notation
7777     found in Host and Referer headers.
7778    </para>
7779    <para>
7780     If &my-app; and <command>Tor</command> are chained and &my-app;
7781     is configured to use socks4a, one can use <quote>http://www.example.org.foobar.exit/</quote>
7782     to access the host <quote>www.example.org</quote> through the
7783     <command>Tor</command> exit node <quote>foobar</quote>.
7784    </para>
7785    <para>
7786     As the HTTP client isn't aware of this notation, it treats the
7787     whole string <quote>www.example.org.foobar.exit</quote> as host and uses it
7788     for the <quote>Host</quote> and <quote>Referer</quote> headers. From the
7789     server's point of view the resulting headers are invalid and can cause problems.
7790    </para>
7791    <para>
7792     An invalid <quote>Referer</quote> header can trigger <quote>hot-linking</quote>
7793     protections, an invalid <quote>Host</quote> header will make it impossible for
7794     the server to find the right vhost (several domains hosted on the same IP address).
7795    </para>
7796    <para>
7797     This client-header filter removes the <quote>foo.exit</quote> part in those headers
7798     to prevent the mentioned problems. Note that it only modifies
7799     the HTTP headers, it doesn't make it impossible for the server
7800     to detect your <command>Tor</command> exit node based on the IP address
7801     the request is coming from.
7802    </para>
7803   </listitem>
7804  </varlistentry>
7805
7806 <!--
7807  <varlistentry>
7808   <term><emphasis> </emphasis></term>
7809   <listitem>
7810    <para>
7811    </para>
7812    <para>
7813    </para>
7814   </listitem>
7815  </varlistentry>
7816 -->
7817 </variablelist>
7818
7819 </sect2>
7820
7821 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
7822 <sect2 id="external-filter-syntax"><title>External filter syntax</title>
7823 <para>
7824  External filters are scripts or programs that can modify the content in
7825  case common <literal><link linkend="filter">filters</link></literal>
7826  aren't powerful enough.
7827 </para>
7828 <para>
7829  External filters can be written in any language the platform &my-app; runs
7830  on supports.
7831 </para>
7832 <para>
7833  They are controlled with the
7834  <literal><link linkend="external-filter">external-filter</link></literal> action
7835  and have to be defined in the <literal><link linkend="filterfile">filterfile</link></literal>
7836  first.
7837 </para>
7838 <para>
7839  The header looks like any other filter, but instead of pcrs jobs, external
7840  filters contain a single job which can be a program or a shell script (which
7841  may call other scripts or programs).
7842 </para>
7843 <para>
7844  External filters read the content from STDIN and write the rewritten
7845  content to STDOUT.
7846  The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST,
7847  PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details
7848  about the client request.
7849 </para>
7850 <para>
7851  &my-app; will temporary store the content to filter in the
7852  <literal><link linkend="temporary-directory">temporary-directory</link></literal>.
7853 </para>
7854
7855  <screen>
7856 EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
7857 /bin/cat
7858
7859 # Incorrect reimplementation of the filter above in POSIX shell.
7860 #
7861 # Note that it's a single job that spans multiple lines, the line
7862 # breaks are not passed to the shell, thus the semicolons are required.
7863 #
7864 # If the script isn't trivial, it is recommended to put it into an external file.
7865 #
7866 # In general, writing external filters entirely in POSIX shell is not
7867 # considered a good idea.
7868 EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
7869 while read line; \
7870 do \
7871   echo "$line"; \
7872 done
7873
7874 EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value.
7875 /usr/local/bin/convert - -rotate 180 -
7876
7877 EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment.
7878 /usr/local/bin/convert - -pointsize 16 -fill white  -annotate +17+418 "[citation needed]" -
7879 </screen>
7880
7881 <warning>
7882  <para>
7883   Currently external filters are executed with &my-app;'s privileges!
7884   Only use external filters you understand and trust.
7885  </para>
7886 </warning>
7887 <para>
7888  External filters are experimental and the syntax may change in the future.
7889 </para>
7890 </sect2>
7891
7892 </sect1>
7893
7894 <!--  ~  End section  ~  -->
7895
7896
7897
7898 <!--   ~~~~~       New section      ~~~~~     -->
7899
7900 <sect1 id="templates">
7901 <title>Privoxy's Template Files</title>
7902 <para>
7903  All <application>Privoxy</application> built-in pages, i.e. error pages such as the
7904  <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
7905  error page</ulink>, the <ulink
7906  url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
7907  page</ulink>
7908  and all pages of its <ulink url="http://config.privoxy.org/">web-based
7909  user interface</ulink>, are generated from <emphasis>templates</emphasis>.
7910  (<application>Privoxy</application> must be running for the above links to work as
7911  intended.)
7912 </para>
7913
7914 <para>
7915  These templates are stored in a subdirectory of the <link linkend="confdir">configuration
7916  directory</link> called <filename>templates</filename>. On Unixish platforms,
7917  this is typically
7918  <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
7919 </para>
7920
7921 <para>
7922  The templates are basically normal HTML files, but with place-holders (called symbols
7923  or exports), which <application>Privoxy</application> fills at run time. It
7924  is possible to edit the templates with a normal text editor, should you want
7925  to customize them. (<emphasis>Not recommended for the casual
7926  user</emphasis>). Should you create your own custom templates, you should use
7927  the <filename>config</filename> setting <link linkend="templdir">templdir</link>
7928  to specify an alternate location, so your templates do not get overwritten
7929  during upgrades.
7930  </para>
7931  <para>
7932  Note that just like in configuration files, lines starting
7933  with <literal>#</literal> are ignored when the templates are filled in.
7934 </para>
7935
7936 <para>
7937  The place-holders are of the form <literal>@name@</literal>, and you will
7938  find a list of available symbols, which vary from template to template,
7939  in the comments at the start of each file. Note that these comments are not
7940  always accurate, and that it's probably best to look at the existing HTML
7941  code to find out which symbols are supported and what they are filled in with.
7942 </para>
7943
7944 <para>
7945  A special application of this substitution mechanism is to make whole
7946  blocks of HTML code disappear when a specific symbol is set. We use this
7947  for many purposes, one of them being to include the beta warning in all
7948  our user interface (CGI) pages when <application>Privoxy</application>
7949  is in an alpha or beta development stage:
7950 </para>
7951
7952  <screen>
7953 &lt;!-- @if-unstable-start --&gt;
7954
7955   ... beta warning HTML code goes here ...
7956
7957 &lt;!-- if-unstable-end@ --&gt;</screen>
7958
7959 <para>
7960  If the "unstable" symbol is set, everything in between and including
7961  <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
7962  will disappear, leaving nothing but an empty comment:
7963 </para>
7964
7965  <screen>&lt;!--  --&gt;</screen>
7966
7967 <para>
7968  There's also an if-then-else construct and an <literal>#include</literal>
7969  mechanism, but you'll sure find out if you are inclined to edit the
7970  templates ;-)
7971 </para>
7972
7973 <para>
7974  All templates refer to a style located at
7975  <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
7976  This is, of course, locally served by <application>Privoxy</application>
7977  and the source for it can be found and edited in the
7978  <filename>cgi-style.css</filename> template.
7979 </para>
7980
7981 </sect1>
7982
7983 <!--  ~  End section  ~  -->
7984
7985
7986
7987 <!--   ~~~~~       New section      ~~~~~     -->
7988
7989 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
7990 Requests</title>
7991
7992 <!-- Include contacting.sgml boilerplate: -->
7993  &contacting;
7994 <!-- end boilerplate -->
7995
7996 </sect1>
7997
7998 <!--  ~  End section  ~  -->
7999
8000
8001 <!--   ~~~~~       New section      ~~~~~     -->
8002 <sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
8003
8004 <!-- Include copyright.sgml: -->
8005  &copyright;
8006 <!-- end copyright -->
8007
8008 <para>
8009  <application>Privoxy</application> is free software; you can
8010  redistribute and/or modify its source code under the terms
8011  of the <citetitle>GNU General Public License</citetitle>
8012  as published by the Free Software Foundation, either version 2
8013  of the license, or (at your option) any later version.
8014 </para>
8015
8016 <para>
8017  The same is true for <application>Privoxy</application> binaries
8018  unless they are linked with a
8019  <ulink url="https://tls.mbed.org/">mbed TLS</ulink> version
8020  that is licensed under the Apache 2.0 license in which
8021  case you can redistribute and/or modify the <application>Privoxy</application>
8022  binaries under the terms of the <citetitle>GNU General Public License</citetitle>
8023  as published by the Free Software Foundation, either version 3
8024  of the license, or (at your option) any later version.
8025 </para>
8026
8027 <para>
8028  Both licenses are included in the next section.
8029 </para>
8030
8031 <!--   ~~~~~       New section      ~~~~~     -->
8032 <sect2 id="license"><title>License</title>
8033
8034 <sect3 id="gplv2"><title>GNU General Public License version 2</title>
8035  <screen><![ RCDATA [ &GPLv2; ]]></screen>
8036 </sect3>
8037
8038 <sect3 id="gplv3"><title>GNU General Public License version 3</title>
8039  <screen><![ RCDATA [ &GPLv3; ]]></screen>
8040 </sect3>
8041
8042 </sect2>
8043 <!--  ~  End section  ~  -->
8044
8045
8046 <!--   ~~~~~       New section      ~~~~~     -->
8047
8048 <sect2 id="history"><title>History</title>
8049 <!-- Include history.sgml: -->
8050  &history;
8051 <!-- end history -->
8052 </sect2>
8053
8054 <sect2 id="authors"><title>Authors</title>
8055 <!-- Include p-authors.sgml: -->
8056  &p-authors;
8057 <!-- end authors -->
8058 </sect2>
8059
8060 </sect1>
8061
8062 <!--  ~  End section  ~  -->
8063
8064
8065 <!--   ~~~~~       New section      ~~~~~     -->
8066 <sect1 id="seealso"><title>See Also</title>
8067 <!-- Include seealso.sgml: -->
8068  &seealso;
8069 <!-- end seealso -->
8070 </sect1>
8071
8072
8073
8074 <!--   ~~~~~       New section      ~~~~~     -->
8075 <sect1 id="appendix"><title>Appendix</title>
8076
8077
8078 <!--   ~~~~~       New section      ~~~~~     -->
8079 <sect2 id="regex">
8080 <title>Regular Expressions</title>
8081 <para>
8082  <application>Privoxy</application> uses Perl-style <quote>regular
8083  expressions</quote> in its <link linkend="actions-file">actions
8084  files</link> and <link linkend="filter-file">filter file</link>,
8085  through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
8086 <!--
8087  dead 08/27/06
8088  <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
8089 -->
8090  <application>PCRS</application> libraries.
8091 </para>
8092
8093 <para>
8094  If you are reading this, you probably don't understand what <quote>regular
8095  expressions</quote> are, or what they can do. So this will be a very brief
8096  introduction only. A full explanation would require a <ulink
8097  url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
8098 </para>
8099
8100 <para>
8101  Regular expressions provide a language to describe patterns that can be
8102  run against strings of characters (letter, numbers, etc), to see if they
8103  match the string or not. The  patterns are themselves (sometimes complex)
8104  strings of literal characters, combined with  wild-cards, and other special
8105  characters, called meta-characters. The <quote>meta-characters</quote> have
8106  special meanings and are used to build complex patterns to be matched against.
8107  Perl Compatible Regular Expressions are an especially convenient
8108  <quote>dialect</quote> of the regular expression language.
8109 </para>
8110
8111 <para>
8112  To make a simple analogy, we do something similar when we use wild-card
8113  characters when listing files with the <command>dir</command> command in DOS.
8114  <literal>*.*</literal> matches all filenames. The <quote>special</quote>
8115  character here is the asterisk which matches any and all characters. We can be
8116  more specific and use <literal>?</literal> to match just individual
8117  characters. So <quote>dir file?.text</quote> would match
8118  <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
8119  matching, using a similar technique to <quote>regular expressions</quote>!
8120 </para>
8121
8122 <para>
8123  Regular expressions do essentially the same thing, but are much, much more
8124  powerful. There are many more <quote>special characters</quote> and ways of
8125  building complex patterns however. Let's look at a few of the common ones,
8126  and then some examples:
8127 </para>
8128
8129 <simplelist>
8130  <member>
8131   <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
8132   <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
8133  </member>
8134 </simplelist>
8135
8136 <simplelist>
8137  <member>
8138   <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
8139   times. Either/or.
8140  </member>
8141 </simplelist>
8142
8143 <simplelist>
8144  <member>
8145   <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
8146   times.
8147  </member>
8148 </simplelist>
8149
8150 <simplelist>
8151  <member>
8152   <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
8153   times.
8154  </member>
8155 </simplelist>
8156
8157 <simplelist>
8158  <member>
8159   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
8160   the following character should be taken literally. This is used where one of the
8161   special characters (e.g. <quote>.</quote>) needs to be taken literally and
8162   not as a special meta-character. Example: <quote>example\.com</quote>, makes
8163   sure the period is recognized only as a period (and not expanded to its
8164   meta-character meaning of any single character).
8165  </member>
8166 </simplelist>
8167
8168 <simplelist>
8169  <member>
8170   <emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
8171   any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
8172   matches any numeric digit (zero through nine). As an example, we can combine
8173   this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
8174  </member>
8175 </simplelist>
8176
8177 <simplelist>
8178  <member>
8179   <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
8180   or multiple sub-expressions.
8181  </member>
8182 </simplelist>
8183
8184 <simplelist>
8185  <member>
8186   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
8187   <quote>or</quote> conditional statement. A match is successful if the
8188   sub-expression on either side of <quote>|</quote> matches. As an example:
8189   <quote>/(this|that) example/</quote> uses grouping and the bar character
8190   and would match either <quote>this example</quote> or <quote>that
8191   example</quote>, and nothing else.
8192  </member>
8193 </simplelist>
8194
8195 <para>
8196  These are just some of the ones you are likely to use when matching URLs with
8197  <application>Privoxy</application>, and is a long way from a definitive
8198  list. This is enough to get us started with a few simple examples which may
8199  be more illuminating:
8200 </para>
8201
8202 <para>
8203  <emphasis><literal>/.*/banners/.*</literal></emphasis> - A  simple example
8204  that uses the common combination of <quote>.</quote> and <quote>*</quote> to
8205  denote any character, zero or more times. In other words, any string at all.
8206  So we start with a literal forward slash, then our regular expression pattern
8207  (<quote>.*</quote>) another literal forward slash, the string
8208  <quote>banners</quote>, another forward slash, and lastly another
8209  <quote>.*</quote>. We are building
8210  a directory path here. This will match any file with the path that has a
8211  directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
8212  any characters, and this could conceivably be more forward slashes, so it
8213  might expand into a much longer looking path. For example, this could match:
8214  <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
8215  <quote>/banners/annoying.html</quote>, or almost an infinite number of other
8216  possible combinations, just so it has <quote>banners</quote> in the path
8217  somewhere.
8218 </para>
8219
8220 <para>
8221  And now something a little more complex:
8222 </para>
8223
8224 <para>
8225  <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
8226  We have several literal forward slashes again (<quote>/</quote>), so we are
8227  building another expression that is a file path statement. We have another
8228  <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
8229  it matches our expression. The only true literal that <emphasis>must
8230  match</emphasis> our pattern is <application>adv</application>, together with
8231  the forward slashes. What comes after the <quote>adv</quote> string is the
8232  interesting part.
8233 </para>
8234
8235 <para>
8236  Remember the <quote>?</quote> means the preceding expression (either a
8237  literal character or anything grouped with <quote>(...)</quote> in this case)
8238  can exist or not, since this means either zero or one match. So
8239  <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
8240  individual sub-expressions: <quote>(er)</quote>,
8241  <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
8242  means <quote>or</quote>. We have two of those. For instance,
8243  <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
8244  <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
8245  attempt at matching as many variations of <quote>advertisement</quote>, and
8246  similar, as possible. So this would expand to match just <quote>adv</quote>,
8247  or <quote>advert</quote>, or <quote>adverts</quote>, or
8248  <quote>advertising</quote>, or <quote>advertisement</quote>, or
8249  <quote>advertisements</quote>. You get the idea. But it would not match
8250  <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
8251  changing our regular expression to:
8252  <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
8253  either spelling.
8254 </para>
8255
8256 <para>
8257  <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
8258  another path statement with forward slashes. Anything in the square brackets
8259  <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
8260  shorthand expression to mean any digit one through nine. It is the same as
8261  saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
8262  means one or more of the preceding expression must be included. The preceding
8263  expression here is what is in the square brackets -- in this case, any digit
8264  one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
8265  This includes a <quote>|</quote>, so this needs to match the expression on
8266  either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
8267  side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
8268  since the <quote>?</quote> means the letter <quote>e</quote> is optional and
8269  can be matched once or not at all. So we are building an expression here to
8270  match image GIF or JPEG type image file. It must include the literal
8271  string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
8272  (which is now a literal, and not a special character, since it is escaped
8273  with <quote>\</quote>), and lastly either <quote>gif</quote>, or
8274  <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
8275  include: <quote>//advert1.jpg</quote>,
8276  <quote>/nasty/ads/advert1234.gif</quote>,
8277  <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
8278  <quote>advert1.gif</quote> (no leading slash), or
8279  <quote>/adverts232.jpg</quote> (the expression does not include an
8280  <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
8281  in the expression anywhere).
8282 </para>
8283
8284 <para>
8285  We are barely scratching the surface of regular expressions here so that you
8286  can understand the default <application>Privoxy</application>
8287  configuration files, and maybe use this knowledge to customize your own
8288  installation. There is much, much more that can be done with regular
8289  expressions. Now that you know enough to get started, you can learn more on
8290  your own :/
8291 </para>
8292
8293 <para>
8294  More reading on Perl Compatible Regular expressions:
8295  <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
8296 </para>
8297
8298 <para>
8299  For information on regular expression based substitutions and their applications
8300  in filters, please see the <link linkend="filter-file">filter file tutorial</link>
8301  in this manual.
8302 </para>
8303 </sect2>
8304
8305 <!--  ~  End section  ~  -->
8306
8307
8308 <!--   ~~~~~       New section      ~~~~~     -->
8309 <sect2 id="internal-pages">
8310 <title>Privoxy's Internal Pages</title>
8311
8312 <para>
8313  Since <application>Privoxy</application> proxies each requested
8314  web page, it is easy for <application>Privoxy</application> to
8315  trap certain special URLs. In this way, we can talk directly to
8316  <application>Privoxy</application>, and see how it is
8317  configured, see how our rules are being applied, change these
8318  rules and other configuration options, and even turn
8319  <application>Privoxy's</application> filtering off, all with
8320  a web browser.
8321 </para>
8322
8323 <para>
8324  The URLs listed below are the special ones that allow direct access
8325  to <application>Privoxy</application>. Of course,
8326  <application>Privoxy</application> must be running to access these. If
8327  not, you will get a friendly error message. Internet access is not
8328  necessary either.
8329 </para>
8330
8331  <itemizedlist>
8332
8333  <listitem>
8334   <para>
8335    Privoxy main page:
8336   </para>
8337   <blockquote>
8338    <para>
8339      <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
8340    </para>
8341   </blockquote>
8342   <para>
8343    There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
8344    doesn't provide a fall-back to a real page, in case the request is not
8345    sent through <application>Privoxy</application>)
8346   </para>
8347  </listitem>
8348
8349  <listitem>
8350   <para>
8351     View and toggle client tags:
8352   </para>
8353    <blockquote>
8354    <para>
8355     <ulink url="http://config.privoxy.org/client-tags">http://config.privoxy.org/client-tags</ulink>
8356    </para>
8357   </blockquote>
8358  </listitem>
8359
8360  <listitem>
8361   <para>
8362     Show information about the current configuration, including viewing and
8363     editing of actions files:
8364   </para>
8365    <blockquote>
8366    <para>
8367     <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
8368    </para>
8369   </blockquote>
8370  </listitem>
8371
8372  <listitem>
8373   <para>
8374    Show the browser's request headers:
8375   </para>
8376   <blockquote>
8377    <para>
8378     <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
8379    </para>
8380   </blockquote>
8381  </listitem>
8382
8383  <listitem>
8384   <para>
8385    Show which actions apply to a URL and why:
8386   </para>
8387    <blockquote>
8388    <para>
8389     <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
8390    </para>
8391   </blockquote>
8392  </listitem>
8393
8394  <listitem>
8395   <para>
8396    Toggle Privoxy on or off. This feature can be turned off/on in the main
8397    <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
8398    continues to run, but only as a pass-through proxy, with no actions taking
8399    place:
8400   </para>
8401    <blockquote>
8402    <para>
8403     <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
8404    </para>
8405   </blockquote>
8406   <para>
8407    Short cuts. Turn off, then on:
8408   </para>
8409    <blockquote>
8410    <para>
8411      <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
8412    </para>
8413   </blockquote>
8414    <blockquote>
8415    <para>
8416      <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
8417    </para>
8418   </blockquote>
8419  </listitem>
8420
8421  </itemizedlist>
8422
8423 </sect2>
8424
8425
8426 <!--   ~~~~~       New section      ~~~~~     -->
8427 <sect2 id="chain">
8428 <title>Chain of Events</title>
8429 <para>
8430  Let's take a quick look at how some of <application>Privoxy's</application>
8431  core features are triggered, and the ensuing sequence of events when a web
8432  page is requested by your browser:
8433 </para>
8434
8435  <itemizedlist>
8436  <listitem>
8437   <para>
8438    First, your web browser requests a web page. The browser knows to send
8439    the request to <application>Privoxy</application>, which will in turn,
8440    relay the request to the remote web server after passing the following
8441    tests:
8442   </para>
8443  </listitem>
8444  <listitem>
8445   <para>
8446    <application>Privoxy</application> traps any request for its own internal CGI
8447    pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
8448   </para>
8449  </listitem>
8450  <listitem>
8451   <para>
8452    Next, <application>Privoxy</application> checks to see if the URL
8453    matches any <link
8454    linkend="BLOCK"><quote>+block</quote></link> patterns. If
8455    so, the URL is then blocked, and the remote web server will not be contacted.
8456    <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
8457    and
8458    <link linkend="HANDLE-AS-EMPTY-DOCUMENT"><quote>+handle-as-empty-document</quote></link>
8459    are then checked, and if there is no match, an
8460    HTML <quote>BLOCKED</quote> page is sent back to the browser. Otherwise, if
8461    it does match, an image is returned for the former, and an empty text
8462    document for the latter. The type of image would depend on the setting of
8463    <link linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
8464    (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
8465   </para>
8466  </listitem>
8467  <listitem>
8468   <para>
8469    Untrusted URLs are blocked. If URLs are being added to the
8470    <filename>trust</filename> file, then that is done.
8471   </para>
8472  </listitem>
8473  <listitem>
8474   <para>
8475    If the URL pattern matches the <link
8476    linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
8477    it is then processed. Unwanted parts of the requested URL are stripped.
8478   </para>
8479  </listitem>
8480  <listitem>
8481   <para>
8482    Now the rest of the client browser's request headers are processed. If any
8483    of these match any of the relevant actions (e.g. <link
8484    linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
8485    etc.), headers are suppressed or forged as determined by these actions and
8486    their parameters.
8487   </para>
8488  </listitem>
8489  <listitem>
8490   <para>
8491    Now the web server starts sending its response back (i.e. typically a web
8492    page).
8493   </para>
8494  </listitem>
8495  <listitem>
8496   <para>
8497    First, the server headers are read and processed to determine, among other
8498    things, the MIME type (document type) and encoding. The headers are then
8499    filtered as determined by the
8500    <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
8501    <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
8502    and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
8503    actions.
8504   </para>
8505  </listitem>
8506  <listitem>
8507   <para>
8508    If any <link linkend="FILTER"><quote>+filter</quote></link> action
8509    or <link
8510    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
8511    action applies (and the document type fits the action), the rest of the page is
8512    read into memory (up to a configurable limit). Then the filter rules (from
8513    <filename>default.filter</filename> and any other filter files) are
8514    processed against the buffered content. Filters are applied in the order
8515    they are specified in one of the filter files. Animated GIFs, if present,
8516    are reduced to either the first or last frame, depending on the action
8517    setting.The entire page, which is now filtered, is then sent by
8518    <application>Privoxy</application> back to your browser.
8519   </para>
8520   <para>
8521    If neither a <link linkend="FILTER"><quote>+filter</quote></link> action
8522    or <link
8523    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
8524    matches, then <application>Privoxy</application> passes the raw data through
8525    to the client browser as it becomes available.
8526   </para>
8527  </listitem>
8528  <listitem>
8529   <para>
8530    As the browser receives the now (possibly filtered) page content, it
8531    reads and then requests any URLs that may be embedded within the page
8532    source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
8533    frames), sounds, etc. For each of these objects, the browser issues a
8534    separate request (this is easily viewable in <application>Privoxy's</application>
8535    logs). And each such request is in turn processed just as above. Note that a
8536    complex web page will have many, many such embedded URLs. If these
8537    secondary requests are to a different server, then quite possibly a very
8538    differing set of actions is triggered.
8539   </para>
8540  </listitem>
8541
8542  </itemizedlist>
8543
8544 <para>
8545  NOTE: This is somewhat of a simplistic overview of what happens with each URL
8546  request. For the sake of brevity and simplicity, we have focused on
8547  <application>Privoxy's</application> core features only.
8548 </para>
8549
8550 </sect2>
8551
8552
8553 <!--   ~~~~~       New section      ~~~~~     -->
8554 <sect2 id="actionsanat">
8555 <title>Troubleshooting: Anatomy of an Action</title>
8556
8557 <para>
8558  The way <application>Privoxy</application> applies
8559  <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
8560  to any given URL can be complex, and not always so
8561  easy to understand what is happening. And sometimes we need to be able to
8562  <emphasis>see</emphasis> just what <application>Privoxy</application> is
8563  doing. Especially, if something <application>Privoxy</application> is doing
8564  is causing us a problem inadvertently. It can be a little daunting to look at
8565  the actions and filters files themselves, since they tend to be filled with
8566  <link linkend="regex">regular expressions</link> whose consequences are not
8567  always so obvious.
8568 </para>
8569
8570 <para>
8571  One quick test to see if <application>Privoxy</application> is causing a problem
8572  or not, is to disable it temporarily. This should be the first troubleshooting
8573  step (be sure to flush caches afterward!). Looking at the
8574  logs is a good idea too. (Note that both the toggle feature and logging are
8575  enabled via <filename>config</filename> file settings, and may need to be
8576  turned <quote>on</quote>.)
8577 </para>
8578 <para>
8579  Another easy troubleshooting step to try is if you have done any
8580  customization of your installation, revert back to the installed
8581  defaults and see if that helps. There are times the developers get complaints
8582  about one thing or another, and the problem is more related to a customized
8583  configuration issue.
8584 </para>
8585
8586 <para>
8587  <application>Privoxy</application> also provides the
8588  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
8589  page that can show us very specifically how <application>actions</application>
8590  are being applied to any given URL. This is a big help for troubleshooting.
8591 </para>
8592
8593 <para>
8594  First, enter one URL (or partial URL) at the prompt, and then
8595  <application>Privoxy</application> will tell us
8596  how the current configuration will handle it. This will not
8597  help with filtering effects (i.e. the <link
8598  linkend="FILTER"><quote>+filter</quote></link> action) from
8599  one of the filter files since this is handled very
8600  differently and not so easy to trap! It also will not tell you about any other
8601  URLs that may be embedded within the URL you are testing. For instance, images
8602  such as ads are expressed as URLs within the raw page source of HTML pages. So
8603  you will only get info for the actual URL that is pasted into the prompt area
8604  -- not any sub-URLs. If you want to know about embedded URLs like ads, you
8605  will have to dig those out of the HTML source. Use your browser's <quote>View
8606  Page Source</quote> option for this. Or right click on the ad, and grab the
8607  URL.
8608 </para>
8609
8610 <para>
8611  Let's try an example, <ulink url="http://google.com">google.com</ulink>,
8612  and look at it one section at a time in a sample configuration (your real
8613  configuration may vary):
8614 </para>
8615
8616  <screen>
8617  Matches for http://www.google.com:
8618
8619  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8620
8621  {+change-x-forwarded-for{block}
8622  +deanimate-gifs {last}
8623  +fast-redirects {check-decoded-url}
8624  +filter {refresh-tags}
8625  +filter {img-reorder}
8626  +filter {banners-by-size}
8627  +filter {webbugs}
8628  +filter {jumping-windows}
8629  +filter {ie-exploits}
8630  +hide-from-header {block}
8631  +hide-referrer {forge}
8632  +session-cookies-only
8633  +set-image-blocker {pattern}
8634 /
8635
8636  { -session-cookies-only }
8637  .google.com
8638
8639  { -fast-redirects }
8640  .google.com
8641
8642 In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8643 (no matches in this file)
8644 </screen>
8645
8646 <para>
8647  This is telling us how we have defined our
8648  <link linkend="ACTIONS"><quote>actions</quote></link>, and
8649  which ones match for our test case, <quote>google.com</quote>.
8650  Displayed is all the actions that are available to us. Remember,
8651  the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
8652  denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
8653  are <quote>off</quote>. Each example we try may provide a slightly different
8654  end result, depending on our configuration directives.
8655 </para>
8656 <para>
8657  The first listing
8658   is for our <filename>default.action</filename> file. The large, multi-line
8659   listing, is how the actions are set to match for all URLs, i.e. our default
8660   settings. If you look at your <quote>actions</quote> file, this would be the
8661   section just below the <quote>aliases</quote> section near the top. This
8662   will apply to all URLs as signified by the single forward slash at the end
8663   of the listing -- <quote> / </quote>.
8664 </para>
8665
8666 <para>
8667  But we have defined additional actions that would be exceptions to these general
8668  rules, and then we list specific URLs (or patterns) that these exceptions
8669  would apply to. Last match wins. Just below this then are two explicit
8670  matches for <quote>.google.com</quote>. The first is negating our previous
8671  cookie setting, which was for <link
8672  linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
8673  (i.e. not persistent). So we will allow persistent cookies for google, at
8674  least that is how it is in this example. The second turns
8675  <emphasis>off</emphasis> any <link
8676  linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
8677  action, allowing this to take place unmolested. Note that there is a leading
8678  dot here -- <quote>.google.com</quote>. This will match any hosts and
8679  sub-domains, in the google.com domain also, such as
8680  <quote>www.google.com</quote> or <quote>mail.google.com</quote>. But it would not
8681  match <quote>www.google.de</quote>! So, apparently, we have these two actions
8682  defined as exceptions to the general rules at the top somewhere in the lower
8683  part of our <filename>default.action</filename> file, and
8684  <quote>google.com</quote> is referenced somewhere in these latter sections.
8685 </para>
8686
8687 <para>
8688  Then, for our <filename>user.action</filename> file, we again have no hits.
8689  So there is nothing google-specific that we might have added to our own, local
8690  configuration. If there was, those actions would over-rule any actions from
8691  previously processed files, such as <filename>default.action</filename>.
8692  <filename>user.action</filename> typically has the last word. This is the
8693  best place to put hard and fast exceptions,
8694 </para>
8695
8696 <para>
8697  And finally we pull it all together in the bottom section and summarize how
8698  <application>Privoxy</application> is applying all its <quote>actions</quote>
8699  to <quote>google.com</quote>:
8700 </para>
8701
8702  <screen>
8703  Final results:
8704
8705  -add-header
8706  -block
8707  +change-x-forwarded-for{block}
8708  -client-header-filter{hide-tor-exit-notation}
8709  -content-type-overwrite
8710  -crunch-client-header
8711  -crunch-if-none-match
8712  -crunch-incoming-cookies
8713  -crunch-outgoing-cookies
8714  -crunch-server-header
8715  +deanimate-gifs {last}
8716  -downgrade-http-version
8717  -fast-redirects
8718  -filter {js-events}
8719  -filter {content-cookies}
8720  -filter {all-popups}
8721  -filter {banners-by-link}
8722  -filter {tiny-textforms}
8723  -filter {frameset-borders}
8724  -filter {demoronizer}
8725  -filter {shockwave-flash}
8726  -filter {quicktime-kioskmode}
8727  -filter {fun}
8728  -filter {crude-parental}
8729  -filter {site-specifics}
8730  -filter {js-annoyances}
8731  -filter {html-annoyances}
8732  +filter {refresh-tags}
8733  -filter {unsolicited-popups}
8734  +filter {img-reorder}
8735  +filter {banners-by-size}
8736  +filter {webbugs}
8737  +filter {jumping-windows}
8738  +filter {ie-exploits}
8739  -filter {google}
8740  -filter {yahoo}
8741  -filter {msn}
8742  -filter {blogspot}
8743  -filter {no-ping}
8744  -force-text-mode
8745  -handle-as-empty-document
8746  -handle-as-image
8747  -hide-accept-language
8748  -hide-content-disposition
8749  +hide-from-header {block}
8750  -hide-if-modified-since
8751  +hide-referrer {forge}
8752  -hide-user-agent
8753  -limit-connect
8754  -overwrite-last-modified
8755  -prevent-compression
8756  -redirect
8757  -server-header-filter{xml-to-html}
8758  -server-header-filter{html-to-xml}
8759  -session-cookies-only
8760  +set-image-blocker {pattern}
8761 </screen>
8762
8763 <para>
8764  Notice the only difference here to the previous listing, is to
8765  <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
8766  which are activated specifically for this site in our configuration,
8767  and thus show in the <quote>Final Results</quote>.
8768 </para>
8769
8770 <para>
8771  Now another example, <quote>ad.doubleclick.net</quote>:
8772 </para>
8773
8774  <screen>
8775  { +block{Domains starts with "ad"} }
8776   ad*.
8777
8778  { +block{Domain contains "ad"} }
8779   .ad.
8780
8781  { +block{Doubleclick banner server} +handle-as-image }
8782   .[a-vx-z]*.doubleclick.net
8783 </screen>
8784
8785 <para>
8786  We'll just show the interesting part here - the explicit matches. It is
8787  matched three different times. Two <quote>+block{}</quote> sections,
8788  and a <quote>+block{} +handle-as-image</quote>,
8789  which is the expanded form of one of our aliases that had been defined as:
8790  <quote>+block-as-image</quote>. (<link
8791  linkend="ALIASES"><quote>Aliases</quote></link> are defined in
8792  the first section of the actions file and typically used to combine more
8793  than one action.)
8794 </para>
8795
8796 <para>
8797  Any one of these would have done the trick and blocked this as an unwanted
8798  image. This is unnecessarily redundant since the last case effectively
8799  would also cover the first. No point in taking chances with these guys
8800  though ;-) Note that if you want an ad or obnoxious
8801  URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
8802  is done here -- as both a <link
8803  linkend="BLOCK"><quote>+block{}</quote></link>
8804  <emphasis>and</emphasis> an
8805  <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
8806  The custom alias <quote><literal>+block-as-image</literal></quote> just
8807  simplifies the process and make it more readable.
8808 </para>
8809
8810 <para>
8811  One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
8812  This one is giving us problems. We are getting a blank page. Hmmm ...
8813 </para>
8814
8815  <screen>
8816  Matches for http://www.example.net/adsl/HOWTO/:
8817
8818  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8819
8820  {-add-header
8821   -block
8822   +change-x-forwarded-for{block}
8823   -client-header-filter{hide-tor-exit-notation}
8824   -content-type-overwrite
8825   -crunch-client-header
8826   -crunch-if-none-match
8827   -crunch-incoming-cookies
8828   -crunch-outgoing-cookies
8829   -crunch-server-header
8830   +deanimate-gifs
8831   -downgrade-http-version
8832   +fast-redirects {check-decoded-url}
8833   -filter {js-events}
8834   -filter {content-cookies}
8835   -filter {all-popups}
8836   -filter {banners-by-link}
8837   -filter {tiny-textforms}
8838   -filter {frameset-borders}
8839   -filter {demoronizer}
8840   -filter {shockwave-flash}
8841   -filter {quicktime-kioskmode}
8842   -filter {fun}
8843   -filter {crude-parental}
8844   -filter {site-specifics}
8845   -filter {js-annoyances}
8846   -filter {html-annoyances}
8847   +filter {refresh-tags}
8848   -filter {unsolicited-popups}
8849   +filter {img-reorder}
8850   +filter {banners-by-size}
8851   +filter {webbugs}
8852   +filter {jumping-windows}
8853   +filter {ie-exploits}
8854   -filter {google}
8855   -filter {yahoo}
8856   -filter {msn}
8857   -filter {blogspot}
8858   -filter {no-ping}
8859   -force-text-mode
8860   -handle-as-empty-document
8861   -handle-as-image
8862   -hide-accept-language
8863   -hide-content-disposition
8864   +hide-from-header{block}
8865   +hide-referer{forge}
8866   -hide-user-agent
8867   -overwrite-last-modified
8868   +prevent-compression
8869   -redirect
8870   -server-header-filter{xml-to-html}
8871   -server-header-filter{html-to-xml}
8872   +session-cookies-only
8873   +set-image-blocker{blank} }
8874    /
8875
8876  { +block{Path contains "ads".} +handle-as-image }
8877   /ads
8878 </screen>
8879
8880 <para>
8881  Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
8882  configuration! But we did not want this at all! Now we see why we get the
8883  blank page. It is actually triggering two different actions here, and
8884  the effects are aggregated so that the URL is blocked, and &my-app; is told
8885  to treat the block as if it were an image. But this is, of course, all wrong.
8886   We could now add a new action below this (or better in our own
8887   <filename>user.action</filename> file) that explicitly
8888   <emphasis>un</emphasis> blocks (
8889   <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
8890   <quote>adsl</quote> in them (remember, last match in the configuration
8891   wins). There are various ways to handle such exceptions. Example:
8892 </para>
8893
8894  <screen>
8895  { -block }
8896   /adsl
8897 </screen>
8898
8899 <para>
8900  Now the page displays ;-)
8901  Remember to flush your browser's caches when making these kinds of changes to
8902  your configuration to insure that you get a freshly delivered page! Or, try
8903  using <literal>Shift+Reload</literal>.
8904 </para>
8905
8906 <para>
8907  But now what about a situation where we get no explicit matches like
8908  we did with:
8909 </para>
8910
8911  <screen>
8912  { +block{Path starts with "ads".} +handle-as-image }
8913  /ads
8914 </screen>
8915
8916 <para>
8917  That actually was very helpful and pointed us quickly to where the problem
8918  was. If you don't get this kind of match, then it means one of the default
8919  rules in the first section of <filename>default.action</filename> is causing
8920  the problem. This would require some guesswork, and maybe a little trial and
8921  error to isolate the offending rule. One likely cause would be one of the
8922  <link linkend="FILTER"><quote>+filter</quote></link> actions.
8923  These tend to be harder to troubleshoot.
8924  Try adding the URL for the site to one of aliases that turn off
8925  <link linkend="FILTER"><quote>+filter</quote></link>:
8926 </para>
8927
8928  <screen>
8929  { shop }
8930  .quietpc.com
8931  .worldpay.com   # for quietpc.com
8932  .jungle.com
8933  .scan.co.uk
8934  .forbes.com
8935 </screen>
8936
8937 <para>
8938  <quote><literal>{ shop }</literal></quote> is an <quote>alias</quote> that expands to
8939  <quote><literal>{ -filter -session-cookies-only }</literal></quote>.
8940  Or you could do your own exception to negate filtering:
8941 </para>
8942
8943  <screen>
8944  { -filter }
8945  # Disable ALL filter actions for sites in this section
8946  .forbes.com
8947  developer.ibm.com
8948  localhost
8949 </screen>
8950
8951 <para>
8952  This would turn off all filtering for these sites. This is best
8953  put in <filename>user.action</filename>, for local site
8954  exceptions. Note that when a simple domain pattern is used by itself (without
8955  the subsequent path portion), all sub-pages within that domain are included
8956  automatically in the scope of the action.
8957 </para>
8958
8959 <para>
8960  Images that are inexplicably being blocked, may well be hitting the
8961 <link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
8962  rule, which assumes
8963  that images of certain sizes are ad banners (works well
8964  <emphasis>most of the time</emphasis>  since these tend to be standardized).
8965 </para>
8966
8967 <para>
8968  <quote><literal>{ fragile }</literal></quote> is an alias that disables most
8969  actions that are the most likely to cause trouble. This can be used as a
8970  last resort for problem sites.
8971 </para>
8972
8973  <screen>
8974  { fragile }
8975  # Handle with care: easy to break
8976  mail.google.
8977  mybank.example.com</screen>
8978
8979
8980 <para>
8981  <emphasis>Remember to flush caches!</emphasis> Note that the
8982  <literal>mail.google</literal> reference lacks the TLD portion (e.g.
8983  <quote>.com</quote>). This will effectively match any TLD with
8984  <literal>google</literal> in it, such as <literal>mail.google.de.</literal>,
8985  just as an example.
8986 </para>
8987 <para>
8988  If this still does not work, you will have to go through the remaining
8989  actions one by one to find which one(s) is causing the problem.
8990 </para>
8991
8992 </sect2>
8993
8994 </sect1>
8995
8996  <!--
8997
8998  This program is free software; you can redistribute it
8999  and/or modify it under the terms of the GNU General
9000  Public License as published by the Free Software
9001  Foundation; either version 2 of the License, or (at
9002  your option) any later version.
9003
9004  This program is distributed in the hope that it will
9005  be useful, but WITHOUT ANY WARRANTY; without even the
9006  implied warranty of MERCHANTABILITY or FITNESS FOR A
9007  PARTICULAR PURPOSE.  See the GNU General Public
9008  License for more details.
9009
9010  The GNU General Public License should be included with
9011  this file.  If not, you can view it at
9012  http://www.gnu.org/copyleft/gpl.html
9013  or write to the Free Software Foundation, Inc.,
9014  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
9015  USA
9016
9017  -->
9018
9019 </article>