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