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