a0f5e66881aeb0690d6d0a30c865fe6bce54f0cf
[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 p-authors SYSTEM "p-authors.sgml">
13 <!entity config SYSTEM "p-config.sgml">
14 <!entity p-version "3.0.14">
15 <!entity p-status "BETA">
16 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
17 <!entity % p-not-stable "INCLUDE">
18 <!entity % p-stable "IGNORE">
19 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
20 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
21 <!entity % p-readme "IGNORE">
22 <!entity % user-man "IGNORE">
23 <!entity % config-file "IGNORE">
24 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
25 <!entity  my-copy "&copy;">         <!-- kludge for docbook2man           -->
26 <!entity % draft "IGNORE">          <!-- WIP stuff    -->
27 <!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml    -->
28 <!entity  my-app "<application>Privoxy</application>">
29 ]>
30 <!--
31  File        :  $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
32
33  Purpose     :  user manual
34                 This file belongs into
35                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
36
37  $Id: user-manual.sgml,v 2.110 2009/07/18 16:25:17 fabiankeil Exp $
38
39  Copyright (C) 2001-2009 Privoxy Developers http://www.privoxy.org/
40  See LICENSE.
41
42  ========================================================================
43  NOTE: Please read developer-manual/documentation.html before touching 
44  anything in this, or other Privoxy documentation.
45  ========================================================================
46
47 -->
48
49 <article id="index">
50 <artheader>
51
52 <title>Privoxy &p-version; User Manual</title>
53
54 <pubdate>
55  <subscript>
56 <!-- Completely the wrong markup, but very little is allowed  -->
57 <!-- in this part of an article. FIXME -->
58  <link linkend="copyright">Copyright</link> &my-copy; 2001-2009 by 
59  <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
60  </subscript>
61 </pubdate>
62
63 <pubdate>$Id: user-manual.sgml,v 2.110 2009/07/18 16:25:17 fabiankeil Exp $</pubdate>
64
65 <!--
66
67 Note: the following should generate a separate page, and a live link to it,
68 all nicely done. But it doesn't for some mysterious reason. Please leave
69 commented unless it can be fixed proper. For the time being, the
70 copyright/license declarations will be in their own sgml.
71
72 Hal.
73
74
75 -->
76
77
78 <abstract>
79
80 <![%dummy;[
81  <para>
82  <comment>
83   This is here to keep vim syntax file from breaking :/
84   If I knew enough to fix it, I would.
85   PLEASE DO NOT REMOVE! HB: hal@foobox.net
86  </comment>
87  </para>
88 ]]>
89
90  <para>
91   The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
92   install, configure and use <ulink
93   url="http://www.privoxy.org/">Privoxy</ulink>.
94  </para>
95
96 <!-- Include privoxy.sgml boilerplate: -->
97  &p-intro;
98 <!-- end privoxy.sgml -->
99
100  <para>
101   You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at  <ulink
102   url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
103   Please see the <link linkend="contact">Contact section</link> on how to
104   contact the developers.
105  </para>
106
107 <!--   <para> -->
108 <!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
109 <!--   </para> -->
110 </abstract>
111
112 </artheader>
113
114 <!--   ~~~~~       New section      ~~~~~     -->
115 <sect1 label="1" id="introduction"><title>Introduction</title>
116 <para>
117  This documentation is included with the current &p-status; version of
118  <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
119  and is mostly complete at this point. The most up to date reference for the
120  time being is still the comments in the source files and in the individual
121  configuration files. Development of a new version is currently nearing
122  completion, and includes significant changes and enhancements over
123  earlier versions.]]>.
124 </para>
125
126 <!-- include only in non-stable versions -->
127 <![%p-not-stable;[
128 <para>
129  Since this is a &p-status; version, not all new features are well tested. This
130  documentation may be slightly out of sync as a result (especially with 
131  CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
132  not many! 
133 </para>
134 ]]>
135
136 <!--   ~~~~~       New section      ~~~~~     -->
137 <sect2 id="features"><title>Features</title>
138 <para>
139  In addition to the core 
140  features of ad blocking and 
141  <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookie</ulink> management,
142  <application>Privoxy</application> provides many supplemental
143  features<![%p-not-stable;[, some of them currently under development]]>, 
144  that give the end-user more control, more privacy and more freedom:
145 </para>
146 <!-- Include newfeatures.sgml boilerplate here: -->
147  &newfeatures;
148 <!-- end boilerplate -->
149 </sect2>
150
151 </sect1>
152
153 <!--  ~  End section  ~  -->
154
155
156 <!--   ~~~~~       New section      ~~~~~     -->
157 <sect1 id="installation"><title>Installation</title>
158
159 <para>
160  <application>Privoxy</application> is available both in convenient pre-compiled
161  packages for a wide range of operating systems, and as raw source code.
162  For most users, we recommend using the packages, which can be downloaded from our
163  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
164  Page</ulink>.
165 </para>
166
167 <para>
168  Note: 
169  On some platforms, the installer may remove previously installed versions, if 
170  found. (See below for your platform). In any case <emphasis>be sure to backup
171  your old configuration if it is valuable to you.</emphasis> See the <link
172  linkend="upgradersnote">note to upgraders</link> section below.
173 </para>
174
175 <!--   ~~~~~       New section      ~~~~~     --> 
176 <sect2 id="installation-packages"><title>Binary Packages</title>
177 <para>
178 How to install the binary packages depends on your operating system:
179 </para>
180
181 <!-- XXX: The installation sections should be sorted -->
182
183 <!--   ~~~~~       New section      ~~~~~     -->
184 <sect3 id="installation-pack-rpm"><title>Red Hat and Fedora RPMs</title>
185
186 <para>
187  RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
188  and will use <filename>/etc/privoxy</filename> for the location 
189  of configuration files.
190 </para>
191
192 <para>
193  Note that on Red Hat, <application>Privoxy</application> will
194  <emphasis>not</emphasis> be automatically started on system boot. You will
195  need to enable that using <command>chkconfig</command>,
196  <command>ntsysv</command>, or similar methods. 
197 </para>
198
199 <para>
200  If you have problems with failed dependencies, try rebuilding the SRC RPM: 
201  <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm</literal>. This 
202  will use your locally installed libraries and RPM version. 
203 </para>
204
205 <para>
206  Also note that if you have a <application>Junkbuster</application> RPM installed
207  on your system, you need to remove it first, because the packages conflict.
208  Otherwise, RPM will try to remove <application>Junkbuster</application>
209  automatically if found, before installing <application>Privoxy</application>.
210 </para>
211 </sect3>
212
213 <!--   ~~~~~       New section      ~~~~~     -->
214 <sect3 id="installation-deb"><title>Debian and Ubuntu</title>
215 <para>
216  DEBs can be installed with <literal>apt-get install privoxy</literal>,
217  and will use <filename>/etc/privoxy</filename> for the location of 
218  configuration files.
219 </para>
220 </sect3>
221
222 <!--   ~~~~~       New section      ~~~~~     -->
223 <sect3 id="installation-pack-win"><title>Windows</title>
224
225 <para>
226  Just double-click the installer, which will guide you through
227  the installation process. You will find the configuration files
228  in the same directory as you installed <application>Privoxy</application> in. 
229 </para>
230 <para>
231  Version 3.0.5 beta introduced full <application>Windows</application> service
232  functionality. On Windows only, the <application>Privoxy</application>
233  program has two new command line arguments to install and uninstall
234  <application>Privoxy</application> as a <emphasis>service</emphasis>.
235 </para>
236  <variablelist>
237   <varlistentry>
238    <term>Arguments:</term>
239    <listitem>
240     <para>
241      <replaceable class="parameter">--install</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
242     </para>
243     <para>
244      <replaceable class="parameter">--uninstall</replaceable>[:<replaceable class="parameter">service_name</replaceable>]
245     </para>
246    </listitem>
247   </varlistentry>
248  </variablelist>
249  <para>
250  After invoking <application>Privoxy</application> with
251  <command>--install</command>, you will need to bring up the
252  <application>Windows</application> service console to assign the user you
253  want <application>Privoxy</application> to run under, and whether or not you
254  want it to run whenever the system starts. You can start the
255  <application>Windows</application> services console with the following
256  command: <command>services.msc</command>.  If you do not take the manual step
257  of modifying <application>Privoxy's</application> service settings, it will
258  not start.  Note too that you will need to give Privoxy a user account that
259  actually exists, or it will not be permitted to 
260  write to its log and configuration files.
261 </para>
262
263 </sect3>
264
265 <!--   ~~~~~       New section      ~~~~~     -->
266 <sect3 id="installation-pack-bintgz"><title>Solaris <!--, NetBSD, HP-UX--></title>
267
268 <para>
269  Create a new directory, <literal>cd</literal> to it, then unzip and
270  untar the archive. For the most part, you'll have to figure out where
271  things go. <!-- FIXME, more info needed? -->
272 </para>
273 </sect3>
274
275 <!--   ~~~~~       New section      ~~~~~     -->
276 <sect3 id="installation-os2"><title>OS/2</title>
277
278 <para>
279  First, make sure that no previous installations of
280  <application>Junkbuster</application> and / or 
281  <application>Privoxy</application> are left on your
282  system. Check that no <application>Junkbuster</application>
283  or <application>Privoxy</application> objects are in
284  your startup folder.
285
286 </para>
287
288 <para>
289  Then, just double-click the WarpIN self-installing archive, which will
290  guide you through the installation process. A shadow of the
291  <application>Privoxy</application> executable will be placed in your
292  startup folder so it will start automatically whenever OS/2 starts.
293 </para>
294
295 <para>
296  The directory you choose to install <application>Privoxy</application>
297  into will contain all of the configuration files.
298 </para>
299 </sect3>
300
301 <!--   ~~~~~       New section      ~~~~~     -->
302 <sect3 id="installation-mac"><title>Mac OS X</title>
303 <para>
304  Unzip the downloaded file (you can either double-click on the zip file
305  icon from the Finder, or from the desktop if you downloaded it there).
306  Then, double-click on the package installer icon and follow the
307  installation process.
308 </para>
309 <para>
310  The privoxy service will automatically start after a successful
311  installation (in addition to every time your computer starts up).  To
312  prevent the privoxy service from automatically starting when your
313  computer starts up, remove or rename the folder named
314  <literal>/Library/StartupItems/Privoxy</literal>. 
315 </para>
316 <para>
317  To manually start or stop the privoxy service, use the Privoxy Utility
318  for Mac OS X.  This application controls the privoxy service (e.g.
319  starting and stopping the service as well as uninstalling the software).
320 </para>
321 </sect3>
322
323 <!--   ~~~~~       New section      ~~~~~     -->
324 <sect3 id="installation-amiga"><title>AmigaOS</title>
325 <para>
326  Copy and then unpack the <filename>lha</filename> archive to a suitable location. 
327  All necessary files will be installed into <application>Privoxy</application>
328  directory, including all configuration and log files. To uninstall, just 
329  remove this directory.
330 </para>
331 </sect3>
332
333 <!--   ~~~~~       New section      ~~~~~     -->
334 <sect3 id="installation-tbz"><title>FreeBSD</title>
335
336 <para>
337  Privoxy is part of FreeBSD's Ports Collection, you can build and install
338  it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
339 </para>
340 <para>
341  If you don't use the ports, you can fetch and install
342  the package with <literal>pkg_add -r privoxy</literal>.
343 </para>
344 <para>
345  The port skeleton and the package can also be downloaded from the
346  <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
347  Page</ulink>, but there's no reason to use them unless you're interested in the
348  beta releases which are only available there.
349 </para>
350 </sect3>
351
352 <!--   ~~~~~       New section      ~~~~~     -->
353 <sect3 id="installattion-gentoo"><title>Gentoo</title>
354 <para>
355  Gentoo source packages (Ebuilds) for <application>Privoxy</application> are 
356  contained in the Gentoo  Portage Tree (they are not on the download page, 
357  but there is a Gentoo section, where you can see when a new 
358  <application>Privoxy</application> Version is added to the  Portage Tree).
359 </para>
360 <para>
361  Before installing <application>Privoxy</application> under Gentoo just do 
362  first <literal>emerge --sync</literal> to get the latest changes from the 
363  Portage tree. With <literal>emerge privoxy</literal> you install the latest 
364  version.
365 </para>
366 <para>
367  Configuration files are in <filename>/etc/privoxy</filename>, the 
368  documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
369  and the Log directory is in <filename>/var/log/privoxy</filename>.
370 </para>
371 </sect3>
372
373 </sect2>
374
375 <!--   ~~~~~       New section      ~~~~~     -->
376 <sect2 id="installation-source"><title>Building from Source</title>
377
378 <para>
379  The most convenient way to obtain the <application>Privoxy</application> sources
380  is to download the source tarball from our 
381  <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;package_id=10571">project download
382  page</ulink>.
383 </para>
384
385 <para>
386  If you like to live on the bleeding edge and are not afraid of using
387  possibly unstable development versions, you can check out the up-to-the-minute
388  version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
389  CVS repository</ulink>. 
390 <!-- 
391  deprecated...out of business.
392  or simply download <ulink
393  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
394  tarball.</ulink>
395 -->
396 </para>
397
398 <!-- include buildsource.sgml boilerplate: -->
399 &buildsource;
400 <!-- end boilerplate -->
401
402 </sect2>
403 <!--   ~~~~~       New section      ~~~~~     --> 
404 <sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
405 <para>
406  As user feedback comes in and development continues, we will make updated versions
407  of both the main <link linkend="actions-file">actions file</link> (as a <ulink
408  url="http://sourceforge.net/project/showfiles.php?group_id=11118&amp;release_id=103670">separate
409  package</ulink>) and the software itself (including the actions file) available for
410  download.
411 </para>
412
413 <para>
414  If you wish to receive an email notification whenever we release updates of
415  <application>Privoxy</application> or the actions file, <ulink
416  url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
417  to our announce  mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
418 </para>
419
420 <para>
421  In order not to lose your personal changes and adjustments when updating
422  to the latest <literal>default.action</literal> file we <emphasis>strongly
423  recommend</emphasis> that you use <literal>user.action</literal> and 
424  <literal>user.filter</literal> for your local
425  customizations of <application>Privoxy</application>. See the <link
426  linkend="actions-file">Chapter on actions files</link> for details.
427 </para>
428
429 </sect2>
430
431
432 </sect1>
433
434 <!--  ~  End section  ~  -->
435
436 <!--   ~~~~~       New section      ~~~~~     -->
437 <sect1 id="whatsnew">
438 <title>What's New in this Release</title>
439 <para>
440  <application>Privoxy 3.0.14 Beta</application> is a bugfix-release
441  for the previous beta which introduced IPv6 support,  improved keep-alive
442  support and a bunch of minor improvements. The changes since 3.0.12:
443 </para>
444
445 <para>
446  <itemizedlist>
447   <listitem>
448    <para>
449     Added IPv6 support. Thanks to Petr Pisar who not only provided
450     the initial patch but also helped a lot with the integration.
451    </para>
452   </listitem>
453   <listitem>
454    <para>
455     Added client-side keep-alive support.
456    </para>
457   </listitem>
458   <listitem>
459    <para>
460     The connection sharing code is only used if the connection-sharing
461     option is enabled.
462    </para>
463   </listitem>
464   <listitem>
465    <para>
466     The latency is taken into account when evaluating whether or not to
467     reuse a connection. This should significantly reduce the number of
468     connections problems several users reported.
469    </para>
470   </listitem>
471   <listitem>
472    <para>
473     The max-client-connections option has been added to restrict
474     the number of client connections below a value enforced by
475     the operating system.
476    </para>
477   </listitem>
478   <listitem>
479    <para>
480     If the server doesn't specify how long the connection stays alive,
481     Privoxy errs on the safe side of caution and assumes it's only a second.
482    </para>
483   </listitem>
484   <listitem>
485    <para>
486     Setting keep-alive-timeout to 0 disables keep-alive support. Previously
487     Privoxy would claim to allow persistence but not reuse the connection.
488    </para>
489   </listitem>
490   <listitem>
491    <para>
492     Pipelined requests are less likely to be mistaken for the request
493     body of the previous request. Note that Privoxy still has no real
494     pipeline support and will either serialize pipelined requests or
495     drop them in which case the client has to resent them.
496    </para>
497   </listitem>
498   <listitem>
499    <para>
500     Fixed a crash on some Windows versions when header randomization
501     is enabled and the date couldn't be parsed.
502    </para>
503   </listitem>
504   <listitem>
505    <para>
506     Privoxy's keep-alive timeout for the current connection is reduced
507     to the one specified in the client's Keep-Alive header.
508    </para>
509   </listitem>
510   <listitem>
511    <para>
512     For HTTP/1.1 requests, Privoxy implies keep-alive support by not
513     setting any Connection header instead of using 'Connection: keep-alive'.
514    </para>
515   </listitem>
516   <listitem>
517    <para>
518     If the socket isn't reusable, Privoxy doesn't temporarily waste
519     a socket slot to remember the connection.
520    </para>
521   </listitem>
522   <listitem>
523    <para>
524     If keep-alive support is disabled but compiled in, the client's
525     Keep-Alive header is removed.
526    </para>
527   </listitem>
528   <listitem>
529    <para>
530     Fixed a bug on mingw32 where downloading large files failed if
531     keep-alive support was enabled.
532    </para>
533   </listitem>
534   <listitem>
535    <para>
536     Fixed a bug that (at least theoretically) could cause log
537     timestamps to be occasionally off by about a second.
538    </para>
539   </listitem>
540   <listitem>
541    <para>
542     The configure script respects the $PATH variable when searching
543     for groups and id.
544    </para>
545   </listitem>
546   <listitem>
547    <para>
548     Compressed content with extra fields couldn't be decompressed
549     and would get passed to the client unfiltered. This problem
550     has only be detected through statical analysis with clang as
551     nobody seems to be using extra fields anyway.
552    </para>
553   </listitem>
554   <listitem>
555    <para>
556     If the server resets the Connection after sending only the headers
557     Privoxy forwards what it got to the client. Previously Privoxy
558     would deliver an error message instead.
559    </para>
560   </listitem>
561   <listitem>
562    <para>
563     Error messages in case of connection timeouts use the right
564     HTTP status code.
565    </para>
566   </listitem>
567   <listitem>
568    <para>
569     If spawning a child to handle a request fails, the client
570     gets an error message and Privoxy continues to listen for
571     new requests right away.
572    </para>
573   </listitem>
574   <listitem>
575    <para>
576     The error messages in case of server-connection timeouts or
577     prematurely closed server connections are now template-based.
578    </para>
579   </listitem>
580   <listitem>
581    <para>
582     If zlib support isn't compiled in, Privoxy no longer tries to
583     filter compressed content unless explicitly asked to do so.
584    </para>
585   </listitem>
586   <listitem>
587    <para>
588     In case of connections that are denied based on ACL directives,
589     the memory used for the client IP is no longer leaked.
590    </para>
591   </listitem>
592   <listitem>
593    <para>
594     Fixed another small memory leak if the client request times out
595     while waiting for client headers other than the request line.
596    </para>
597   </listitem>
598   <listitem>
599    <para>
600     The client socket is kept open until the server socket has
601     been marked as unused. This should increase the chances that
602     the still-open connection will be reused for the client's next
603     request to the same destination. Note that this only matters
604     if connection-sharing is enabled.
605    </para>
606   </listitem>
607   <listitem>
608    <para>
609     A TODO list has been added to the source tarballs to give potential
610     volunteers a better idea of what the current goals are. Donations
611     are still welcome too: http://www.privoxy.org/faq/general.html#DONATE
612    </para>
613   </listitem>
614  </itemizedlist>
615 </para>
616
617
618 <!--   ~~~~~       New section      ~~~~~     -->
619
620 <sect2 id="upgradersnote">
621 <title>Note to Upgraders</title>
622
623 <para>
624  A quick list of things to be aware of before upgrading from earlier 
625  versions of <application>Privoxy</application>:
626 </para>
627
628 <para>
629  <itemizedlist>
630
631  <listitem>
632   <para>
633    The recommended way to upgrade &my-app; is to backup your old 
634    configuration files, install the new ones, verify that &my-app;
635    is working correctly and finally merge back your changes using
636    <application>diff</application> and maybe <application>patch</application>.
637   </para>
638   <para>
639    There are a number of new features in each &my-app; release and
640    most of them have to be explicitly enabled in the configuration
641    files. Old configuration files obviously don't do that and due
642    to syntax changes using old configuration files with a new
643    &my-app; isn't always possible anyway.
644   </para>
645  </listitem>
646  <listitem>
647   <para>  
648     Note that some installers remove earlier versions completely,
649     including configuration files, therefore you should really save
650     any important configuration files!
651   </para>
652  </listitem>
653  <listitem>
654   <para>  
655    On the other hand, other installers don't overwrite existing configuration 
656    files, thinking you will want to do that yourself.
657   </para>
658  </listitem>
659  <listitem>
660   <para>  
661    <filename>standard.action</filename> has been merged into
662    the <filename>default.action</filename> file.
663   </para>
664  </listitem>
665  <listitem>
666   <para>
667    In the default configuration only fatal errors are logged now.
668    You can change that in the <link linkend="DEBUG">debug section</link>
669    of the configuration file. You may also want to enable more verbose
670    logging until you verified that the new &my-app; version is working
671    as expected.
672   </para>
673  </listitem>
674
675  <listitem>
676     <para>
677      Three other config file settings are now off by default: 
678      <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
679      <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
680      and  <link linkend="enable-edit-actions">enable-edit-actions</link>. 
681      If you use or want these, you will need to explicitly enable them, and
682      be aware of the security issues involved. 
683     </para>
684   </listitem>
685
686 <!--
687  <listitem>
688   <para>  
689    What constitutes a <quote>default</quote> configuration has changed, 
690    and you may want to review which actions are <quote>on</quote> by 
691    default. This is primarily a matter of emphasis, but some features 
692    you may have been used to, may now be <quote>off</quote> by default.
693    There are also a number of new actions and filters you may want to
694    consider, most of which are not fully incorporated into the default
695    settings as yet (see above).
696   </para>
697  </listitem>
698 -->
699 <!--
700   <listitem>
701    <para>
702     The default actions setting is now <literal>Cautious</literal>. Previous
703     releases had a default setting of <literal>Medium</literal>. Experienced
704     users may want to adjust this, as it is fairly conservative by &my-app;
705     standards and past practices. See <ulink
706     url="http://config.privoxy.org/edit-actions-list?f=default">
707     http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
708     should try the default settings for a while before turning up the volume.
709    </para>
710   </listitem>
711
712   <listitem>
713    <para>
714     The default setting has filtering turned <emphasis>off</emphasis>, which
715     subsequently means that compression is <emphasis>on</emphasis>. Remember
716     that filtering does not work on compressed pages, so if you use, or want to
717     use, filtering, you will need to force compression off. Example:
718    </para>
719    <para>
720  <screen>
721   { +<link linkend="filter">filter</link>{google}  +<link linkend="prevent-compression">prevent-compression</link> }
722    .google.</screen>
723    </para>
724    <para>
725     Or if you use a number of filters, or filter many sites, you may just want
726     to turn off compression for all sites in
727     <filename>default.action</filename> (or
728     <filename>user.action</filename>). 
729    </para>
730
731   </listitem>
732
733   <listitem>
734   <para>
735    Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is 
736    off by default now. If you've liked this feature in the past, you may want 
737    to turn it back on in <filename>user.action</filename> now.
738   </para>
739   </listitem>
740
741
742   <listitem>
743   <para>
744    Some installers may not automatically start
745    <application>Privoxy</application> after installation.
746   </para>
747  </listitem> 
748 -->
749
750  </itemizedlist>
751 </para>
752
753 </sect2>
754 </sect1>
755
756 <!--   ~~~~~       New section      ~~~~~     -->
757 <sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
758 <para>
759  <itemizedlist>
760
761  <listitem>
762   <para>
763   Install <application>Privoxy</application>. See the <link
764   linkend="installation">Installation Section</link> below for platform specific
765   information. 
766  </para>
767  </listitem>  
768
769  <listitem>
770   <para>
771    Advanced users and those who want to offer <application>Privoxy</application>
772    service to more than just their local machine should check the <link
773    linkend="config">main config file</link>, especially the <link
774    linkend="access-control">security-relevant</link> options. These are 
775    off by default.
776   </para>
777  </listitem>  
778
779  <listitem>
780   <para>
781   Start <application>Privoxy</application>, if the installation program has
782   not done this already (may vary according to platform). See the section
783   <link linkend="startup">Starting <application>Privoxy</application></link>.
784   </para>
785  </listitem>
786
787  <listitem>
788   <para>
789    Set your browser to use <application>Privoxy</application> as HTTP and
790    HTTPS (SSL)  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>
791    by setting the proxy configuration for address of
792    <literal>127.0.0.1</literal> and port <literal>8118</literal>.
793    <emphasis>DO NOT</emphasis> activate proxying for <literal>FTP</literal> or 
794    any protocols besides HTTP and HTTPS (SSL) unless you intend to prevent your
795    browser from using these protocols.
796   </para>
797  </listitem>  
798
799  <listitem>
800   <para>
801     Flush your browser's disk and memory caches, to remove any cached ad images.
802     If using <application>Privoxy</application> to manage 
803     <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
804     you should remove any currently stored cookies too.
805   </para>
806  </listitem> 
807
808  <listitem>
809   <para>
810    A default installation should provide a reasonable starting point for 
811    most. There will undoubtedly be occasions where you will want to adjust the
812    configuration, but that can be dealt with as the need arises. Little 
813    to no initial configuration is required in most cases, you may want
814    to enable the
815    <ulink url="config.html#ENABLE-EDIT-ACTIONS">web-based action editor</ulink> though.
816    Be sure to read the warnings first.
817   </para>
818   <para>
819    See the <link linkend="configuration">Configuration section</link> for more
820    configuration options, and how to customize your installation.
821    You might also want to look at the <link
822    linkend="quickstart-ad-blocking">next section</link> for a quick
823    introduction to how <application>Privoxy</application> blocks ads and
824    banners.
825 </para>
826  </listitem> 
827
828  <listitem>
829   <para>
830     If you experience ads that slip through, innocent images that are
831     blocked, or otherwise feel the need to fine-tune
832     <application>Privoxy's</application> behavior, take a look at the <link
833     linkend="actions-file">actions files</link>. As a quick start, you might
834     find the <link linkend="act-examples">richly commented examples</link>
835     helpful. You can also view and edit the actions files through the <ulink
836     url="http://config.privoxy.org">web-based user interface</ulink>. The
837     Appendix <quote><link linkend="actionsanat">Troubleshooting: Anatomy of an
838     Action</link></quote> has hints on how to understand and debug actions that
839     <quote>misbehave</quote>.
840   </para>
841  </listitem> 
842
843 <!--
844  Did anyone test these lately?
845  fk 2007-11-10
846  <listitem>
847   <para>
848    For easy access to &my-app;'s most important controls, drag the provided
849    <link linkend="bookmarklets">Bookmarklets</link> into your browser's
850    personal toolbar.
851   </para>
852  </listitem> 
853 -->
854
855  <listitem>
856   <para>
857    Please see the section <link linkend="contact">Contacting the
858    Developers</link> on how to report bugs, problems with websites or to get
859    help. 
860   </para>
861  </listitem> 
862
863  <listitem>
864   <para>
865    Now enjoy surfing with enhanced control, comfort and privacy!
866   </para>
867  </listitem> 
868
869  </itemizedlist>
870 </para>
871
872
873 <!--   ~~~~~       New section      ~~~~~     -->
874
875 <sect2 id="quickstart-ad-blocking">
876 <title>Quickstart to Ad Blocking</title>
877 <!--
878  NOTE:  This section is deliberately redundant for those that don't 
879  want to read the whole thing (which is getting lengthy).
880 -->
881 <para>
882  Ad blocking is but one of <application>Privoxy's</application>
883  array of features. Many of these features are for the technically minded advanced 
884  user. But, ad and banner blocking is surely common ground for everybody.
885 </para>
886 <para> 
887  This section will provide a quick summary of ad blocking so 
888  you can get up to speed quickly without having to read the more extensive
889  information provided below, though this is highly recommended.
890 </para>
891 <para>
892  First a bit of a warning ... blocking ads is much like blocking SPAM: the
893  more aggressive you are about it, the more likely you are to block 
894  things that were not intended. And the more likely that some things 
895  may not work as intended. So there is a trade off here. If you want
896  extreme ad free browsing, be prepared to deal with more
897  <quote>problem</quote> sites, and to spend more time adjusting the
898  configuration to solve these unintended consequences. In short, there is 
899  not an easy way to eliminate <emphasis>all</emphasis> ads. Either take 
900  the easy way and settle for <emphasis>most</emphasis> ads blocked with the
901  default configuration, or jump in and tweak it for your personal surfing
902  habits and preferences.
903 </para>
904 <para>
905  Secondly, a brief explanation of <application>Privoxy's </application>
906  <quote>actions</quote>. <quote>Actions</quote> in this context, are 
907  the directives we use to tell <application>Privoxy</application> to perform
908  some task relating to HTTP transactions (i.e. web browsing). We tell
909  <application>Privoxy</application> to take some <quote>action</quote>. Each
910  action has a unique name and function. While there are many potential
911  <application>actions</application> in <application>Privoxy's</application>
912  arsenal, only a few are used for ad blocking. <link
913  linkend="actions">Actions</link>, and <link linkend="actions-file">action
914  configuration files</link>, are explained in depth below.
915 </para>
916 <para>
917  Actions are specified in <application>Privoxy's</application> configuration,
918  followed by one or more URLs to which the action should apply. URLs 
919  can actually be URL type <link linkend="af-patterns">patterns</link> that use
920  wildcards so they can apply potentially to a range of similar URLs. The
921  actions, together with the URL patterns are called a section.
922 </para>
923 <para>
924  When you connect to a website, the full URL will either match one or more
925  of the sections as defined in <application>Privoxy's</application> configuration,
926  or not. If so, then <application>Privoxy</application> will perform the
927  respective actions. If not, then nothing special happens. Furthermore, web
928  pages may contain embedded, secondary URLs that your web browser will
929  use to load additional components of the page, as it parses the
930  original page's HTML content. An ad image for instance, is just an URL
931  embedded in the page somewhere. The image itself may be on the same server,
932  or a server somewhere else on the Internet. Complex web pages will have many
933  such embedded URLs. &my-app; can deal with each URL individually, so, for
934  instance, the main page text is not touched, but images from such-and-such
935  server are blocked.
936 </para>
937
938 <para>
939  The most important actions for basic ad blocking are:  <literal><link
940  linkend="block">block</link></literal>, <literal><link
941  linkend="handle-as-image">handle-as-image</link></literal>, 
942  <literal><link
943  linkend="handle-as-empty-document">handle-as-empty-document</link></literal>,and
944  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
945 </para>
946
947 <para>
948  <itemizedlist>
949   
950  <listitem>
951   <para>
952    <literal><link linkend="block">block</link></literal> - this is perhaps 
953    the single most used action, and is particularly important for ad blocking.
954    This action stops any contact between your browser and any URL patterns
955    that match this action's configuration. It can be used for blocking ads,
956    but also anything that is determined to be unwanted. By itself, it simply
957    stops any communication with the remote server and sends
958    <application>Privoxy</application>'s own built-in BLOCKED page instead to
959    let you now what has happened (with some exceptions, see below).
960   </para>
961  </listitem> 
962
963  <listitem>
964   <para>
965    <literal><link linkend="handle-as-image">handle-as-image</link></literal> - 
966    tells <application>Privoxy</application> to treat this URL as an image.
967    <application>Privoxy</application>'s default configuration already does this
968    for all common image types (e.g. GIF), but there are many situations where this
969    is not so easy to determine. So we'll force it in these cases. This is particularly
970    important for ad blocking, since  only if we know that it's an image of
971    some kind, can we replace it with an image of our choosing, instead of the 
972    <application>Privoxy</application> BLOCKED page (which would only result in
973    a <quote>broken image</quote> icon). There are some limitations to this
974    though. For instance, you can't just brute-force an image substitution for
975    an entire HTML page in most situations.
976   </para>
977  </listitem> 
978
979  <listitem>
980   <para>
981    <literal><link linkend="handle-as-empty-document">handle-as-empty-document</link></literal> - 
982    sends an empty document instead of <application>Privoxy's</application> 
983    normal BLOCKED HTML page. This is useful for file types that are neither 
984    HTML nor images, such as blocking JavaScript files.
985   </para>
986  </listitem> 
987
988  <listitem>
989   <para>
990    <literal><link
991    linkend="set-image-blocker">set-image-blocker</link></literal> - tells
992    <application>Privoxy</application> what to display in place of an ad image that
993    has hit a block rule. For this to come into play, the URL must match a
994    <literal><link linkend="block">block</link></literal> action somewhere in the
995    configuration, <emphasis>and</emphasis>, it must also match an
996    <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
997   </para>
998   <para>
999    The configuration options on what to display instead of the ad are:
1000   </para>
1001   <simplelist>
1002    <member>
1003     &nbsp;&nbsp;&nbsp;<emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad 
1004     replacement is obvious. This is the default.
1005    </member>
1006   </simplelist>
1007   <simplelist>
1008    <member>
1009     &nbsp;&nbsp;&nbsp;<emphasis>blank</emphasis> - A very small empty GIF image is displayed.
1010     This is the so-called <quote>invisible</quote> configuration option.
1011    </member>
1012   </simplelist>
1013   <simplelist>
1014    <member>
1015     &nbsp;&nbsp;&nbsp;<emphasis>http://&lt;URL&gt;</emphasis> - A redirect to any image anywhere
1016     of the user's choosing (advanced usage).
1017    </member>
1018   </simplelist>
1019   </listitem> 
1020
1021 </itemizedlist>
1022 </para>
1023
1024 <para>
1025  Advanced users will eventually want to explore &my-app;
1026  <literal><link linkend="filter">filters</link></literal> as well. Filters 
1027  are very different from <literal><link
1028  linkend="block">blocks</link></literal>.
1029  A <quote>block</quote> blocks a site, page, or unwanted contented. Filters
1030  are a way of filtering or modifying what is actually on the page. An example
1031  filter usage: a text replacement of <quote>no-no</quote> for
1032  <quote>nasty-word</quote>. That is a very simple example. This process can be
1033  used for ad blocking, but it is more in the realm of advanced usage and has
1034  some pitfalls to be wary off.
1035 </para>
1036
1037 <para>
1038  The quickest way to adjust any of these settings is with your browser through
1039  the special <application>Privoxy</application> editor at <ulink
1040  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1041  (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This 
1042  is an internal page, and does not require Internet access.
1043 </para>
1044
1045 <para>
1046  Note that as of <application>Privoxy</application> 3.0.7 beta the
1047  action editor is disabled by default. Check the
1048  <ulink url="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions
1049   section in the configuration file</ulink> to learn why and in which
1050  cases it's safe to enable again.
1051 </para>
1052
1053 <para>
1054  If you decided to enable the action editor, select the appropriate
1055  <quote>actions</quote> file, and click
1056  <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
1057  local preferences in <filename>user.action</filename> since this is not
1058  meant to be overwritten during upgrades, and will over-ride the settings in
1059  other files. Here you can insert new <quote>actions</quote>, and URLs for ad
1060  blocking or other purposes, and make other adjustments to the configuration.
1061  <application>Privoxy</application> will detect these changes automatically.
1062 </para>
1063
1064 <para>
1065  A quick and simple step by step example:
1066 </para>
1067
1068 <para>
1069  <itemizedlist>
1070
1071   <listitem>
1072    <para>
1073      Right click on the ad image to be blocked, then select 
1074      <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
1075      pop-up menu. 
1076    </para>
1077   </listitem> 
1078   <listitem>
1079    <para>
1080     Set your browser to 
1081     <ulink
1082  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1083    </para>
1084   </listitem> 
1085   <listitem>
1086    <para>
1087     Find <filename>user.action</filename> in the top section, and click 
1088     on <quote><guibutton>Edit</guibutton></quote>:
1089    </para>
1090
1091  <!-- image of editor and actions files selections -->
1092  <para>
1093   <figure pgwide="0" float="0"><title>Actions Files in Use</title>
1094    <mediaobject>
1095      <imageobject>
1096       <imagedata  fileref="files-in-use.jpg" format="jpg">
1097        </imageobject> 
1098        <textobject>
1099         <phrase>[ Screenshot of Actions Files in Use ]</phrase>
1100       </textobject>
1101    </mediaobject>
1102   </figure>
1103  </para>
1104  </listitem> 
1105  
1106  <listitem>
1107   <para>
1108    You should have a section with only
1109    <literal><link linkend="block">block</link></literal> listed under 
1110    <quote>Actions:</quote>.
1111    If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
1112    button, and in the new section that just appeared, click the 
1113    <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
1114    This will bring up a list of all actions. Find
1115    <literal><link linkend="block">block</link></literal> near the top, and click
1116    in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
1117    just below the list.
1118   </para>
1119  </listitem> 
1120  <listitem>
1121   <para>
1122    Now, in the <literal><link linkend="block">block</link></literal> actions section,
1123    click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
1124    browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
1125    Remove the <literal>http://</literal> at the beginning of the URL. Then, click
1126    <quote><guibutton>Submit</guibutton></quote> (or
1127    <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
1128   </para>
1129  </listitem> 
1130  <listitem>
1131   <para>
1132    Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
1133    (or flush all browser caches). The image should be gone now.
1134   </para>
1135  </listitem> 
1136  
1137  </itemizedlist>
1138 </para>
1139
1140 <para>
1141  This is a very crude and simple example. There might be good reasons to use a 
1142  wildcard pattern match to include potentially similar images from the same
1143  site. For a more extensive explanation of <quote>patterns</quote>, and 
1144  the entire actions concept, see <link linkend="actions-file">the Actions
1145  section</link>.
1146 </para>
1147
1148 <para>
1149  For advanced users who want to hand edit their config files, you might want
1150  to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
1151  The ideas explained therein also apply to the web-based editor.
1152 </para>
1153 <para>
1154  There are also various 
1155  <link linkend="filter">filters</link> that can be used for ad blocking 
1156  (filters are a special subset of actions). These 
1157  fall into the <quote>advanced</quote> usage category, and are explained in
1158  depth in later sections. 
1159 </para>
1160
1161 </sect2>
1162
1163 </sect1>
1164
1165 <!--  ~  End section  ~  -->
1166
1167
1168 <!--   ~~~~~       New section      ~~~~~     -->
1169 <sect1 id="startup">
1170 <title>Starting Privoxy</title>
1171 <para>
1172  Before launching <application>Privoxy</application> for the first time, you
1173  will want to configure your browser(s) to use
1174  <application>Privoxy</application> as a HTTP and HTTPS (SSL) 
1175  <ulink url="http://en.wikipedia.org/wiki/Proxy_server">proxy</ulink>. The default is
1176  127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
1177  used port 8000). This is the one configuration step <emphasis>that must be done
1178 </emphasis>!
1179 </para>
1180 <para>
1181  Please note that <application>Privoxy</application> can only proxy HTTP and 
1182  HTTPS traffic. It will not work with FTP or other protocols.
1183 </para>
1184
1185  <!-- image of Mozilla Proxy configuration -->
1186  <para>
1187   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1188   Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
1189    <mediaobject>
1190      <imageobject>
1191       <imagedata  fileref="proxy_setup.jpg" format="jpg">
1192        </imageobject> 
1193        <textobject>
1194         <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
1195       </textobject>
1196    </mediaobject>
1197   </figure>
1198  </para>
1199  
1200
1201 <para> 
1202  With <application>Firefox</application>, this is typically set under:
1203 </para>
1204  
1205 <literallayout>
1206  <guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> ->  <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
1207
1208 </literallayout>
1209
1210 <para> 
1211  Or optionally on some platforms:
1212 </para>
1213  
1214 <literallayout>
1215  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
1216
1217 </literallayout>
1218
1219
1220 <para> 
1221  With <application>Netscape</application> (and
1222  <application>Mozilla</application>), this can be set under:
1223 </para>
1224
1225
1226 <literallayout>
1227 <!-- Mix ascii and gui art, something for everybody -->
1228 <!-- spacing on this is tricky -->
1229  <guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
1230
1231 </literallayout>
1232
1233 <para>
1234  For <application>Internet Explorer v.5-7</application>: 
1235 </para>
1236
1237 <literallayout>
1238  <guibutton>Tools</guibutton> -> <guibutton>Internet Options</guibutton> -> <guibutton>Connections</guibutton> -> <guibutton>LAN Settings</guibutton>
1239 </literallayout>
1240
1241 <para>
1242  Then, check <quote>Use Proxy</quote> and fill in the appropriate info
1243  (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
1244  proxy support too (sometimes labeled <quote>Secure</quote>). Make sure any
1245  checkboxes like <quote>Use the same proxy server for all protocols</quote> is
1246  <emphasis>UNCHECKED</emphasis>. You want only HTTP and HTTPS (SSL)!
1247 </para>
1248
1249  <!-- image of IE Proxy configuration -->
1250  <para>
1251   <figure pgwide="0" float="0"><title>Proxy Configuration Showing
1252   Internet Explorer HTTP and HTTPS (Secure) Settings</title>
1253    <mediaobject>
1254      <imageobject>
1255       <imagedata  fileref="proxy2.jpg" format="jpg">
1256        </imageobject> 
1257        <textobject>
1258         <phrase>[ Screenshot of IE Proxy Configuration ]</phrase>
1259       </textobject>
1260    </mediaobject>
1261   </figure>
1262  </para>
1263
1264
1265 <para>
1266  After doing this, flush your browser's disk and memory caches to force a
1267  re-reading of all pages and to get rid of any ads that may be cached. Remove 
1268  any <ulink url="http://en.wikipedia.org/wiki/Browser_cookie">cookies</ulink>,
1269  if you want <application>Privoxy</application> to manage that. You are now
1270  ready to start enjoying the benefits of using
1271  <application>Privoxy</application>!
1272 </para>
1273
1274 <para>
1275  <application>Privoxy</application> itself is typically started by specifying the
1276  main configuration file to be used on the command line. If no configuration
1277  file is specified on the command line, <application>Privoxy</application>
1278  will look for a file named <filename>config</filename> in the current
1279  directory. Except on Win32 where it will try <filename>config.txt</filename>.
1280 </para>
1281
1282 <sect2 id="start-redhat">
1283 <title>Red Hat and Fedora</title>
1284 <para>
1285  A default Red Hat installation may not start &my-app; upon boot. It will use
1286  the file <filename>/etc/privoxy/config</filename> as its main configuration
1287  file.
1288 </para>
1289 <para>
1290  <screen>
1291  # /etc/rc.d/init.d/privoxy start
1292 </screen>
1293 </para>
1294 <para>
1295  Or ...
1296 </para>
1297 <para>
1298  <screen>
1299  # service privoxy start
1300 </screen>
1301 </para>
1302 </sect2>
1303
1304 <sect2 id="start-debian">
1305 <title>Debian</title>
1306 <para>
1307  We use a script. Note that Debian typically starts &my-app; upon booting per
1308  default.  It will use the file
1309  <filename>/etc/privoxy/config</filename> as its main configuration
1310  file.
1311 </para>
1312 <para>
1313  <screen>
1314  # /etc/init.d/privoxy start
1315 </screen>
1316 </para>
1317 </sect2>
1318
1319 <sect2 id="start-windows">
1320 <title>Windows</title>
1321 <para>
1322 Click on the &my-app; Icon to start <application>Privoxy</application>. If no configuration file is
1323  specified on the command line, <application>Privoxy</application> will look
1324  for a file named <filename>config.txt</filename>. Note that Windows will
1325  automatically start &my-app; when the system starts if you chose that option
1326  when installing.
1327 </para>
1328 <para>
1329  <application>Privoxy</application> can run with full Windows service functionality.
1330  On Windows only, the &my-app; program has two new command line arguments
1331  to install and uninstall &my-app; as a service. See the 
1332  <link linkend="installation-pack-win">Windows Installation
1333  instructions</link> for details.
1334 </para>
1335 </sect2>
1336
1337 <sect2 id="start-unices">
1338 <title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
1339 <para>
1340 Example Unix startup command:
1341 </para>
1342 <para>
1343  <screen>
1344  # /usr/sbin/privoxy /etc/privoxy/config
1345 </screen>
1346 </para>
1347 </sect2>
1348
1349 <sect2 id="start-os2">
1350 <title>OS/2</title>
1351 <para>
1352  During installation, <application>Privoxy</application> is configured to
1353  start automatically when the system restarts. You can start it manually by
1354  double-clicking on the <application>Privoxy</application> icon in the
1355  <application>Privoxy</application> folder.
1356 </para>
1357 </sect2>
1358
1359 <sect2 id="start-macosx">
1360 <title>Mac OS X</title>
1361 <para>
1362   After downloading the privoxy software, unzip the downloaded file by
1363   double-clicking on the zip file icon.  Then, double-click on the
1364   installer package icon and follow the installation process.
1365 </para>
1366 <para>
1367   The privoxy service will automatically start after a successful
1368   installation.  In addition, the privoxy service will automatically
1369   start every time your computer starts up.
1370 </para>
1371 <para>
1372   To prevent the privoxy service from automatically starting when your
1373   computer starts up, remove or rename the folder named
1374   /Library/StartupItems/Privoxy.
1375 </para>
1376 <para>
1377   A simple application named Privoxy Utility has been created which
1378   enables administrators to easily start and stop the privoxy service.
1379 </para>
1380 <para>
1381   In addition, the Privoxy Utility presents a simple way for
1382   administrators to edit the various privoxy config files.  A method
1383   to uninstall the software is also available.
1384 </para>
1385 <para>
1386   An administrator username and password must be supplied in order for
1387   the Privoxy Utility to perform any of the tasks.
1388 </para>
1389 </sect2>
1390
1391
1392 <sect2 id="start-amigaos">
1393 <title>AmigaOS</title>
1394 <para>
1395  Start <application>Privoxy</application> (with RUN &lt;&gt;NIL:) in your
1396  <filename>startnet</filename> script (AmiTCP), in
1397  <filename>s:user-startup</filename> (RoadShow), as startup program in your
1398  startup script (Genesis), or as startup action (Miami and MiamiDx). 
1399  <application>Privoxy</application> will automatically quit when you quit your
1400  TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
1401  <application>Privoxy</application> is still running).
1402 </para>
1403 </sect2>
1404
1405 <sect2 id="start-gentoo">
1406 <title>Gentoo</title>
1407 <para>
1408  A script is again used. It will use the file <filename>/etc/privoxy/config 
1409  </filename> as its main configuration file.
1410 </para>
1411 <para>
1412  <screen>
1413  /etc/init.d/privoxy start
1414  </screen>
1415 </para>
1416 <para>
1417  Note that <application>Privoxy</application> is not automatically started at 
1418  boot time by default. You can change this with the <literal>rc-update</literal> 
1419  command.
1420 </para>
1421 <para> 
1422  <screen>
1423  rc-update add privoxy default
1424  </screen>
1425 </para>
1426 </sect2>
1427
1428 <!--
1429
1430 <para>
1431  See the section <link linkend="cmdoptions">Command line options</link> for
1432  further info.
1433 </para>
1434
1435 must find a better place for this paragraph
1436
1437 <para>
1438  The included default configuration files should give a reasonable starting
1439  point. Most of the per site configuration is done in the
1440  <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
1441  where various cookie actions are defined, ad and banner blocking, and other
1442  aspects of <application>Privoxy</application> configuration. There are several
1443  such files included, with varying levels of aggressiveness. 
1444 </para>
1445
1446 <para>
1447  You will probably want to keep an eye out for sites for which you may prefer
1448  persistent cookies, and add these to your actions configuration as needed. By
1449  default, most of these will be accepted only during the current browser
1450  session (aka <quote>session cookies</quote>), unless you add them to the
1451  configuration. If you want the browser to handle this instead, you will need
1452  to edit <filename>user.action</filename> (or through the web based interface)
1453  and disable this feature. If you use more than one browser, it would make
1454  more sense to let <application>Privoxy</application> handle this. In which
1455  case, the browser(s) should be set to accept all cookies.
1456 </para>
1457
1458 <para>
1459  Another feature where you will probably want to define exceptions for trusted
1460  sites is the popup-killing (through  <ulink
1461  url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>),
1462  because your favorite shopping, banking, or leisure site may need
1463  popups (explained below). 
1464 </para>
1465
1466 <para>
1467  <application>Privoxy</application> does not support all of the optional HTTP/1.1
1468  features yet. In the unlikely event that you experience inexplicable problems
1469  with browsers that use HTTP/1.1 per default
1470  (like <application>Mozilla</application> or recent versions of I.E.), you might
1471  try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit -&gt;
1472  Preferences -&gt; Debug -&gt; Networking</literal>.
1473  Alternatively, set the <quote>+downgrade-http-version</quote> config option in
1474  <filename>default.action</filename> which will downgrade your browser's HTTP
1475  requests from HTTP/1.1 to HTTP/1.0 before processing them.
1476 </para>
1477
1478 <para>
1479  After running <application>Privoxy</application> for a while, you can 
1480  start to fine tune the configuration to suit your personal, or site, 
1481  preferences and requirements. There are many, many aspects that can 
1482  be customized. <quote>Actions</quote> 
1483  can be adjusted by pointing your browser to 
1484  <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1485  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), 
1486  and then follow the link to <quote>View &#38; Change the Current Configuration</quote>. 
1487  (This is an internal page and does not require Internet access.)
1488 </para>
1489
1490 <para>
1491  In fact, various aspects of <application>Privoxy</application>
1492  configuration can be viewed from this page, including 
1493  current configuration parameters, source code version numbers, 
1494  the browser's request headers, and <quote>actions</quote> that apply 
1495  to a given URL. In addition to the actions file 
1496  editor mentioned above, <application>Privoxy</application> can also 
1497  be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
1498 </para>
1499
1500 <para>
1501  If you encounter problems, try loading the page without
1502  <application>Privoxy</application>. If that helps, enter the URL where
1503  you have the problems into <ulink url="http://p.p/show-url-info">the browser
1504  based rule tracing utility</ulink>. See which rules apply and why, and
1505  then try turning them off for that site one after the other, until the problem
1506  is gone. When you have found the culprit, you might want to turn the rest on
1507  again.
1508 </para>
1509
1510 <para>
1511  If the above paragraph sounds gibberish to you, you might want to <link
1512  linkend="actions-file">read more about the actions concept</link>
1513  or even dive deep into the <link linkend="actionsanat">Appendix
1514  on actions</link>.
1515 </para>
1516
1517 <para>
1518  If you can't get rid of the problem at all, think you've found a bug in
1519  Privoxy, want to propose a new feature or smarter rules, please see the 
1520  section <link linkend="contact"><quote>Contacting the
1521  Developers</quote></link> below. 
1522 </para>
1523
1524 -->
1525
1526 <!--   ~~~~~       New section      ~~~~~     -->
1527 <sect2 id="cmdoptions">
1528 <title>Command Line Options</title>
1529 <para>
1530  <application>Privoxy</application> may be invoked with the following
1531  command-line options:
1532 </para>
1533
1534 <para>
1535  <itemizedlist>
1536
1537  <listitem>
1538   <para>
1539     <emphasis>--version</emphasis>
1540   </para>
1541   <para>
1542      Print version info and exit. Unix only.
1543   </para>
1544  </listitem> 
1545  <listitem>
1546   <para>
1547     <emphasis>--help</emphasis>
1548   </para>
1549   <para>
1550    Print short usage info and exit. Unix only.
1551   </para>
1552  </listitem> 
1553  <listitem>
1554   <para>
1555    <emphasis>--no-daemon</emphasis>
1556   </para>
1557   <para>
1558    Don't become a daemon, i.e. don't fork and become process group
1559    leader, and don't detach from controlling tty. Unix only.
1560   </para>
1561  </listitem> 
1562  <listitem>
1563   <para>
1564    <emphasis>--pidfile FILE</emphasis>
1565   </para>
1566   <para>
1567    On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
1568    <emphasis>FILE</emphasis> on exit. Failure to create or delete the
1569    <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
1570    option is given, no PID file will be used. Unix only.
1571   </para>
1572  </listitem> 
1573  <listitem>
1574   <para>
1575    <emphasis>--user USER[.GROUP]</emphasis>
1576   </para>
1577   <para>
1578    After (optionally) writing the PID file, assume the user  ID  of
1579    <emphasis>USER</emphasis>, and if included the GID of GROUP.  Exit if the
1580    privileges are not sufficient to do so. Unix only.
1581   </para>
1582  </listitem>
1583  <listitem>
1584   <para>
1585    <emphasis>--chroot</emphasis>
1586   </para>
1587   <para>
1588    Before changing to the user ID given in the <emphasis>--user</emphasis> option, 
1589    chroot to that user's home directory, i.e. make the kernel pretend to the &my-app;
1590    process that the directory tree starts there. If set up carefully, this can limit 
1591    the impact of possible vulnerabilities in &my-app; to the files contained in that hierarchy.
1592    Unix only.
1593   </para>
1594  </listitem>
1595  <listitem>
1596   <para>
1597    <emphasis>--pre-chroot-nslookup hostname</emphasis>
1598   </para>
1599   <para>
1600    Specifies a hostname to look up before doing a chroot. On some systems, initializing the
1601    resolver library involves reading config files from /etc and/or loading additional shared
1602    libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
1603    the number of files that must be copied into the chroot tree.
1604   </para>
1605   <para>
1606    For fastest startup speed, a good value is a hostname that is not in /etc/hosts but that
1607    your local name server (listed in /etc/resolv.conf) can resolve without recursion
1608    (that is, without having to ask any other name servers). The hostname need not exist,
1609    but if it doesn't, an error message (which can be ignored) will be output.
1610   </para>
1611  </listitem>
1612
1613  <listitem>
1614   <para>
1615     <emphasis>configfile</emphasis>
1616   </para>
1617   <para>
1618     If no <emphasis>configfile</emphasis> is included on the command line, 
1619     <application>Privoxy</application> will look for a file named 
1620     <quote>config</quote> in the current directory (except on Win32 
1621     where it will look for <quote>config.txt</quote> instead). Specify 
1622     full path to avoid confusion. If no config file is found, 
1623     <application>Privoxy</application> will fail to start.
1624   </para>
1625  </listitem> 
1626
1627  </itemizedlist>
1628 </para>
1629
1630 <para>
1631  On <application>MS Windows</application> only there are two additional 
1632  command-line options to allow <application>Privoxy</application> to install and 
1633  run as a <emphasis>service</emphasis>. See the 
1634 <link linkend="installation-pack-win">Window Installation section</link> 
1635 for details.
1636 </para>
1637
1638 </sect2>
1639
1640 </sect1>
1641
1642 <!--  ~  End section  ~  -->
1643
1644
1645 <!--   ~~~~~       New section      ~~~~~     -->
1646 <sect1 id="configuration"><title>Privoxy Configuration</title>
1647  <para>
1648   All <application>Privoxy</application> configuration is stored  
1649   in text files. These files can be edited with a text editor.
1650   Many important aspects of <application>Privoxy</application> can 
1651   also be controlled easily with a web browser.
1652  </para>
1653
1654
1655 <!--   ~~~~~       New section      ~~~~~     -->
1656
1657 <sect2>
1658 <title>Controlling Privoxy with Your Web Browser</title>
1659 <para>
1660  <application>Privoxy</application>'s user interface can be reached through the special 
1661  URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1662  (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), 
1663  which is a built-in page and works without Internet access.
1664  You will see the following section:
1665
1666 </para>
1667
1668 <!-- Needs to be put in a table and colorized  -->
1669 <screen>
1670  <msgtext>
1671  <bridgehead renderas="sect2">&nbsp;&nbsp;&nbsp;&nbsp;Privoxy Menu</bridgehead>
1672
1673  <simplelist>
1674  <member>
1675   &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>
1676  </member>
1677  <member>
1678   &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>
1679  </member>
1680  <member>
1681   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
1682  </member>
1683  <member>
1684   &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>
1685  </member>
1686  <member>
1687   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
1688  </member>
1689  <member>
1690   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&squf;&nbsp;&nbsp;<ulink
1691   url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
1692  </member>
1693  </simplelist>
1694  </msgtext>
1695 </screen>
1696
1697
1698 <para>
1699  This should be self-explanatory. Note the first item leads to an editor for the
1700  <link linkend="actions-file">actions files</link>, which is where the ad, banner,
1701  cookie, and URL blocking magic is configured as well as other advanced features of
1702  <application>Privoxy</application>. This is an easy way to adjust various
1703  aspects of <application>Privoxy</application> configuration. The actions
1704  file, and other configuration files, are explained in detail below. 
1705 </para>
1706
1707 <para>
1708  <quote>Toggle Privoxy On or Off</quote> is handy for sites that might 
1709  have problems with your current actions and filters. You can in fact use
1710  it as a test to see whether it is <application>Privoxy</application> 
1711  causing the problem or not. <application>Privoxy</application> continues 
1712  to run as a proxy in this case, but all manipulation is disabled, i.e.
1713  <application>Privoxy</application> acts like a normal forwarding proxy. There
1714  is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
1715  that you can toggle <application>Privoxy</application> with one click from
1716  your browser.
1717 </para>
1718
1719 <para>
1720  Note that several of the features described above are disabled by default
1721  in <application>Privoxy</application> 3.0.7 beta and later.
1722  Check the
1723  <ulink url="config.html">configuration file</ulink> to learn why
1724  and in which cases it's safe to enable them again.
1725 </para>
1726
1727 </sect2>
1728
1729 <!--  ~  End section  ~  -->
1730
1731
1732
1733
1734 <!--   ~~~~~       New section      ~~~~~     -->
1735
1736 <sect2 id="confoverview">
1737 <title>Configuration Files Overview</title>
1738 <para>
1739  For Unix, *BSD and Linux, all configuration files are located in
1740  <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
1741  AmigaOS these are all in the same directory as the 
1742  <application>Privoxy</application> executable. <![%p-not-stable;[ The name
1743  and number of configuration files has changed from previous versions, and is
1744  subject to change as development progresses.]]>
1745 </para>
1746
1747 <para>
1748  The installed defaults provide a reasonable starting point, though 
1749  some settings may be aggressive by some standards. For the time being, the
1750  principle configuration files are:
1751 </para>
1752
1753 <para>
1754  <itemizedlist>
1755
1756   <listitem>
1757    <para>
1758      The <link linkend="config">main configuration file</link> is named <filename>config</filename>
1759      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
1760      on Windows. This is a required file.
1761    </para>
1762   </listitem> 
1763
1764   <listitem>
1765    <para>
1766     <filename>match-all.action</filename> is used to define which <quote>actions</quote>
1767     relating to banner-blocking, images, pop-ups, content modification, cookie handling
1768     etc should be applied by default. It should be the first actions file loaded.
1769    </para>
1770    <para>
1771     <filename>default.action</filename> defines many exceptions (both positive and negative)
1772     from the default set of actions that's configured in <filename>match-all.action</filename>.
1773     It should be the second actions file loaded and shouldn't be edited by the user.
1774    </para>
1775    <para>
1776     Multiple actions files may be defined in <filename>config</filename>. These 
1777     are processed in the order they are defined. Local customizations and locally 
1778     preferred exceptions to the default policies as defined in
1779     <filename>match-all.action</filename> (which you will most probably want
1780     to define sooner or later) are best applied in <filename>user.action</filename>,
1781     where you can preserve them across upgrades. The file isn't installed by all
1782     installers, but you can easily create it yourself with a text editor.
1783    </para>
1784    <para>    
1785     There is also a web based editor that can be accessed from
1786     <ulink
1787     url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1788     (Shortcut: <ulink
1789     url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
1790     various actions files. 
1791    </para>
1792   </listitem> 
1793
1794   <listitem>
1795    <para>
1796     <quote>Filter files</quote> (the <link linkend="filter-file">filter
1797     file</link>) can be used to re-write the raw page content, including
1798     viewable text as well as embedded HTML and JavaScript, and whatever else
1799     lurks on any given web page. The filtering jobs are only pre-defined here;
1800     whether to apply them or not is up to the actions files. 
1801     <filename>default.filter</filename> includes various filters made 
1802     available for use by the developers. Some are much more intrusive than 
1803     others, and all should be used with caution. You may define additional 
1804     filter files in <filename>config</filename> as you can with 
1805     actions files. We suggest <filename>user.filter</filename> for any 
1806     locally defined filters or customizations.
1807    </para>
1808   </listitem> 
1809
1810  </itemizedlist>
1811 </para>
1812
1813 <para>
1814  The syntax of the configuration and filter files may change between different
1815  Privoxy versions, unfortunately some enhancements cost backwards compatibility.
1816  <!-- Add link to documentation-->
1817 </para>
1818
1819 <para>
1820  All files use the <quote><literal>#</literal></quote> character to denote a
1821  comment (the rest of the line will be ignored) and understand line continuation
1822  through placing a backslash ("<literal>\</literal>") as the very last character
1823  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
1824  its special function. Placing a <literal>#</literal> in front of an otherwise
1825  valid configuration line to prevent it from being interpreted is called "commenting
1826  out" that line. Blank lines are ignored.
1827 </para>
1828
1829 <para>
1830  The actions files and filter files  
1831  can use Perl style <link linkend="regex">regular expressions</link> for
1832  maximum flexibility. 
1833 </para>
1834
1835 <para>
1836  After making any changes, there is no need to restart
1837  <application>Privoxy</application> in order for the changes to take
1838  effect. <application>Privoxy</application> detects such changes 
1839  automatically. Note, however, that it may take one or two additional
1840  requests for the change to take effect. When changing the listening address
1841  of <application>Privoxy</application>, these <quote>wake up</quote> requests
1842  must obviously be sent to the <emphasis>old</emphasis> listening address.
1843 </para>
1844
1845 <![%p-not-stable;[
1846 <para>
1847  While under development, the configuration content is subject to change. 
1848  The below documentation may not be accurate by the time you read this. 
1849  Also, what constitutes a <quote>default</quote> setting, may change, so 
1850  please check all your configuration files on important issues.
1851 </para>
1852 ]]>
1853
1854 </sect2>
1855 </sect1>
1856 <!--  ~  End section  ~  -->
1857
1858
1859 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1860
1861 <!-- **************************************************** -->
1862 <!-- Include config.sgml here -->
1863 <!-- This is where the entire config file is detailed. -->
1864  &config;
1865 <!-- end include  -->
1866
1867
1868 <!--  ~  End section  ~  -->
1869
1870
1871
1872 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
1873
1874 <sect1 id="actions-file"><title>Actions Files</title>
1875
1876
1877 <!--
1878   XXX: similar descriptions are in the Configuration Files sections.
1879   We should only describe them at one place.
1880 -->
1881 <para>
1882  The actions files are used to define what <emphasis>actions</emphasis>
1883  <application>Privoxy</application> takes for which URLs, and thus determines
1884  how ad images, cookies and various other aspects of HTTP content and
1885  transactions are handled, and on which sites (or even parts thereof). 
1886  There are a number of such actions, with a wide range of functionality.
1887  Each action does something a little different.
1888  These actions give us a veritable arsenal of tools with which to exert 
1889  our control, preferences and independence. Actions can be combined so that 
1890  their effects are aggregated when applied against a given set of URLs.
1891 </para> 
1892 <para>
1893  There 
1894  are three action files included with <application>Privoxy</application> with
1895  differing purposes:
1896 </para>
1897 <para>
1898  <itemizedlist>
1899   <listitem>
1900    <para>
1901     <filename>match-all.action</filename> - is used to define which
1902     <quote>actions</quote> relating to banner-blocking, images, pop-ups,
1903     content modification, cookie handling etc should be applied by default.
1904     It should be the first actions file loaded
1905    </para>
1906   </listitem> 
1907   <listitem>
1908    <para>
1909     <filename>default.action</filename> - defines many exceptions (both
1910     positive and negative) from the default set of actions that's configured
1911     in <filename>match-all.action</filename>. It is a set of rules that should
1912     work reasonably well as-is for most users. This file is only supposed to
1913     be edited by the developers. It should be the second actions file loaded.
1914    </para>
1915   </listitem> 
1916   <listitem>
1917    <para>
1918     <filename>user.action</filename> - is intended to be for local site 
1919     preferences and exceptions. As an example, if your ISP or your bank
1920     has specific requirements, and need special handling, this kind of 
1921     thing should go here. This file will not be upgraded.
1922    </para>
1923   </listitem> 
1924   <listitem>
1925    <para>
1926     <guibutton>Edit</guibutton>  <guibutton>Set to Cautious</guibutton> <guibutton>Set to Medium</guibutton>  <guibutton>Set to Advanced</guibutton>
1927    </para>
1928    <para>
1929     These have increasing levels of aggressiveness <emphasis>and have no
1930     influence on your browsing unless you select them explicitly in the
1931     editor</emphasis>. A default installation should be pre-set to 
1932     <literal>Cautious</literal>. New users should try this for a while before
1933     adjusting the settings to more aggressive levels. The more aggressive 
1934     the settings, then the more likelihood there is of problems such as sites 
1935     not working as they should.
1936    </para>
1937    <para>
1938     The <guibutton>Edit</guibutton> button allows you to turn each 
1939     action on/off individually for fine-tuning. The <guibutton>Cautious</guibutton>
1940     button changes the actions list to low/safe settings which will activate 
1941     ad blocking and a minimal set of &my-app;'s features, and subsequently
1942     there will be less of a chance for accidental problems. The
1943     <guibutton>Medium</guibutton> button sets the list to a medium level of
1944     other features and a low level set of privacy features. The
1945     <guibutton>Advanced</guibutton> button sets the list to a high level of
1946     ad blocking and medium level of privacy. See the chart below. The latter
1947     three buttons over-ride any changes via with the
1948     <guibutton>Edit</guibutton> button. More fine-tuning can be done in the
1949     lower sections of this internal page.
1950    </para>
1951    <para>
1952     While the actions file editor allows to enable these settings in all
1953     actions files, they are only supposed to be enabled in the first one
1954     to make sure you don't unintentionally overrule earlier rules.
1955    </para>
1956    <para>
1957     The default profiles, and their associated actions, as pre-defined in
1958     <filename>default.action</filename> are:
1959    </para>
1960    <para>
1961     <table frame=all><title>Default Configurations</title>
1962     <tgroup cols=4 align=left colsep=1 rowsep=1>
1963     <colspec colname=c1>
1964     <colspec colname=c2>
1965     <colspec colname=c3>
1966     <colspec colname=c4>
1967     <thead>
1968     <row>
1969       <entry>Feature</entry>
1970       <entry>Cautious</entry>
1971       <entry>Medium</entry>
1972       <entry>Advanced</entry>
1973     </row>
1974     </thead>
1975     <!--  <tfoot> -->
1976     <!--  <row> -->
1977     <!--    <entry>f1</entry> -->
1978     <!--    <entry>f2</entry> -->
1979     <!--    <entry>f3</entry> -->
1980     <!--    <entry>f4</entry> -->
1981     <!--  </row> -->
1982     <!--  </tfoot> -->
1983     <tbody>
1984
1985     <row>
1986       <entry>Ad-blocking Aggressiveness</entry>
1987       <entry>medium</entry>
1988       <entry>high</entry>
1989       <entry>high</entry>
1990     </row>
1991
1992     <row>
1993       <entry>Ad-filtering by size</entry>
1994       <entry>no</entry>
1995       <entry>yes</entry>
1996       <entry>yes</entry>
1997     </row>
1998
1999     <row>
2000       <entry>Ad-filtering by link</entry>
2001       <entry>no</entry>
2002       <entry>no</entry>
2003       <entry>yes</entry>
2004     </row>
2005     <row>
2006       <entry>Pop-up killing</entry>
2007       <entry>blocks only</entry>
2008       <entry>blocks only</entry>
2009       <entry>blocks only</entry>
2010     </row>
2011     
2012     <row>
2013       <entry>Privacy Features</entry>
2014       <entry>low</entry>
2015       <entry>medium</entry>
2016       <entry>medium/high</entry>
2017     </row>
2018
2019     <row>
2020       <entry>Cookie handling</entry>
2021       <entry>none</entry>
2022       <entry>session-only</entry>
2023       <entry>kill</entry>
2024     </row>
2025
2026     <row>
2027       <entry>Referer forging</entry>
2028       <entry>no</entry>
2029       <entry>yes</entry>
2030       <entry>yes</entry>
2031     </row>
2032
2033     <row>
2034       <entry>GIF de-animation</entry>
2035       <entry>no</entry>
2036       <entry>yes</entry>
2037       <entry>yes</entry>
2038     </row>
2039
2040     <row>
2041       <entry>Fast redirects</entry>
2042       <entry>no</entry>
2043       <entry>no</entry>
2044       <entry>yes</entry>
2045     </row>
2046
2047     <row>
2048       <entry>HTML taming</entry>
2049       <entry>no</entry>
2050       <entry>no</entry>
2051       <entry>yes</entry>
2052     </row>
2053
2054     <row>
2055       <entry>JavaScript taming</entry>
2056       <entry>no</entry>
2057       <entry>no</entry>
2058       <entry>yes</entry>
2059     </row>
2060
2061     <row>
2062       <entry>Web-bug killing</entry>
2063       <entry>no</entry>
2064       <entry>yes</entry>
2065       <entry>yes</entry>
2066     </row>
2067
2068     <row>
2069       <entry>Image tag reordering</entry>
2070       <entry>no</entry>
2071       <entry>yes</entry>
2072       <entry>yes</entry>
2073     </row>
2074
2075     </tbody>
2076     </tgroup>
2077     </table>
2078     </para>
2079
2080   </listitem> 
2081  </itemizedlist>
2082 </para> 
2083
2084 <para>
2085  The list of actions files to be used are defined in the main configuration 
2086  file, and are processed in the order they are defined (e.g.
2087  <filename>default.action</filename> is typically processed before
2088  <filename>user.action</filename>). The content of these can all be viewed and
2089  edited from <ulink
2090  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2091  The over-riding principle when applying actions, is that the last action that
2092  matches a given URL wins. The broadest, most general rules go first
2093  (defined in <filename>default.action</filename>),
2094  followed by any exceptions (typically also in
2095  <filename>default.action</filename>), which are then followed lastly by any
2096  local preferences (typically in <emphasis>user</emphasis><filename>.action</filename>). 
2097  Generally, <filename>user.action</filename> has the last word.
2098  </para>
2099
2100 <para>
2101  An actions file typically has multiple sections. If you want to use
2102  <quote>aliases</quote> in an actions file, you have to place the (optional)
2103  <link linkend="aliases">alias section</link> at the top of that file.
2104  Then comes the default set of rules which will apply universally to all
2105  sites and pages (be <emphasis>very careful</emphasis> with using such a
2106  universal set in <filename>user.action</filename> or any other actions file after 
2107  <filename>default.action</filename>, because it will override the result
2108  from consulting any previous file). And then below that,
2109  exceptions to the defined universal policies. You can regard
2110  <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
2111  with the advantage that it is a separate file, which makes preserving your
2112  personal settings across <application>Privoxy</application> upgrades easier.
2113 </para>
2114
2115 <para> 
2116  Actions can be used to block anything you want, including ads, banners, or
2117  just some obnoxious URL whose content you would rather not see. Cookies can be accepted
2118  or rejected, or accepted only during the current browser session (i.e. not
2119  written to disk), content can be modified, some JavaScripts tamed, user-tracking
2120  fooled, and much more. See below for a <link linkend="actions">complete list
2121  of actions</link>.
2122 </para>
2123
2124 <!--   ~~~~~       New section      ~~~~~     -->
2125 <sect2>
2126 <title>Finding the Right Mix</title>
2127 <para>
2128  Note that some <link linkend="actions">actions</link>, like cookie suppression
2129  or script disabling, may render some sites unusable that rely on these
2130  techniques to work properly. Finding the right mix of actions is not always easy and
2131  certainly a matter of personal taste. And, things can always change, requiring 
2132  refinements in the configuration. In general, it can be said that the more
2133  <quote>aggressive</quote> your default settings (in the top section of the
2134  actions file) are, the more exceptions for <quote>trusted</quote> sites you
2135  will have to make later. If, for example, you want to crunch all cookies per
2136  default, you'll have to make exceptions from that rule for sites that you
2137  regularly use and that require cookies for actually useful purposes, like maybe
2138  your bank, favorite shop, or newspaper.
2139 </para>
2140
2141 <para>
2142  We have tried to provide you with reasonable rules to start from in the
2143  distribution actions files. But there is no general rule of thumb on these
2144  things. There just are too many variables, and sites are constantly changing.
2145  Sooner or later you will want to change the rules (and read this chapter again :).
2146 </para>
2147 </sect2>
2148
2149 <!--   ~~~~~       New section      ~~~~~     -->
2150 <sect2>
2151 <title>How to Edit</title>
2152 <para>
2153  The easiest way to edit the actions files is with a browser by
2154  using our browser-based editor, which can be reached from <ulink
2155  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2156  Note: the config file option <link
2157  linkend="enable-edit-actions">enable-edit-actions</link> must be enabled for
2158  this to work. The editor allows both fine-grained control over every single
2159  feature on a per-URL basis, and easy choosing from wholesale sets of defaults
2160  like <quote>Cautious</quote>, <quote>Medium</quote> or
2161  <quote>Advanced</quote>. Warning: the <quote>Advanced</quote> setting is more
2162  aggressive, and will be more likely to cause problems for some sites.
2163  Experienced users only! 
2164  </para>
2165
2166 <para>
2167  If you prefer plain text editing to GUIs, you can of course also directly edit the
2168  the actions files with your favorite text editor. Look at
2169  <filename>default.action</filename> which is richly commented with many 
2170  good examples.
2171 </para>
2172 </sect2>
2173
2174
2175 <sect2 id="actions-apply">
2176 <title>How Actions are Applied to Requests</title>
2177 <para>
2178  Actions files are divided into sections. There are special sections,
2179  like the <quote><link linkend="aliases">alias</link></quote> sections which will
2180  be discussed later. For now let's concentrate on regular sections: They have a
2181  heading line (often split up to multiple lines for readability) which consist
2182  of a list of actions, separated by whitespace and enclosed in curly braces.
2183  Below that, there is a list of URL and tag patterns, each on a separate line.
2184 </para>
2185
2186 <para>
2187  To determine which actions apply to a request, the URL of the request is
2188  compared to all URL patterns in each <quote>action file</quote>.
2189  Every time it matches, the list of applicable actions for the request is
2190  incrementally updated, using the heading of the section in which the
2191  pattern is located. The same is done again for tags and tag patterns later on.
2192 </para>
2193
2194 <para>
2195  If multiple applying sections set the same action differently,
2196  the last match wins. If not, the effects are aggregated.
2197  E.g. a URL might match a regular section with a heading line of <literal>{ 
2198  +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
2199  then later another one with just <literal>{
2200  +<link linkend="block">block</link> }</literal>, resulting
2201  in <emphasis>both</emphasis> actions to apply. And there may well be 
2202  cases where you will want to combine actions together. Such a section then 
2203  might look like:
2204 </para>
2205
2206  <para>
2207  <screen>
2208   { +<literal>handle-as-image</literal>  +<literal>block{Banner ads.}</literal> }
2209   # Block these as if they were images. Send no block page.
2210    banners.example.com
2211    media.example.com/.*banners
2212    .example.com/images/ads/</screen>
2213  </para>
2214
2215 <para>
2216  You can trace this process for URL patterns and any given URL by visiting <ulink
2217  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2218 </para>
2219
2220 <para>
2221  Examples and more detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2222  Troubleshooting: Anatomy of an Action</link> section.
2223 </para>
2224 </sect2>
2225
2226 <!--   ~~~~~       New section      ~~~~~     -->
2227 <sect2 id="af-patterns">
2228 <title>Patterns</title>
2229 <para> 
2230  As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
2231  to determine what <emphasis>actions</emphasis> might apply to which sites and
2232  pages your browser attempts to access. These <quote>patterns</quote> use wild
2233  card type <emphasis>pattern</emphasis> matching to achieve a high degree of
2234  flexibility. This allows one expression to be expanded and potentially match
2235  against many similar patterns.
2236 </para>
2237  
2238 <para>
2239  Generally, an URL pattern has the form
2240  <literal>&lt;domain&gt;&lt;port&gt;/&lt;path&gt;</literal>, where the
2241  <literal>&lt;domain&gt;</literal>, the <literal>&lt;port&gt;</literal>
2242  and the <literal>&lt;path&gt;</literal> are optional. (This is why the special
2243  <literal>/</literal> pattern matches all URLs). Note that the protocol
2244  portion of the URL pattern (e.g. <literal>http://</literal>) should
2245  <emphasis>not</emphasis> be included in the pattern. This is assumed already!
2246 </para>
2247 <para>
2248  The pattern matching syntax is different for the domain and path parts of
2249  the URL. The domain part uses a simple globbing type matching technique, 
2250  while the path part uses more flexible 
2251  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2252   Expressions</quote></ulink> (POSIX 1003.2).
2253 </para>
2254 <para>
2255  The port part of a pattern is a decimal port number preceded by a colon
2256  (<literal>:</literal>). If the domain part contains a numerical IPv6 address,
2257  it has to be put into angle brackets
2258  (<literal>&lt;</literal>, <literal>&gt;</literal>).
2259 </para>
2260
2261 <variablelist>
2262  <varlistentry>
2263   <term><literal>www.example.com/</literal></term>
2264   <listitem>
2265    <para>
2266     is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2267     regardless of which document on that server is requested. So ALL pages in
2268     this domain would be covered by the scope of this action. Note that a 
2269     simple <literal>example.com</literal> is different and would NOT match.
2270    </para>
2271   </listitem>
2272  </varlistentry>
2273  <varlistentry>
2274   <term><literal>www.example.com</literal></term>
2275   <listitem>
2276    <para>
2277     means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2278     be omitted.
2279    </para>
2280   </listitem>
2281  </varlistentry>
2282  <varlistentry>
2283   <term><literal>www.example.com/index.html</literal></term>
2284   <listitem>
2285    <para>
2286     matches all the documents on <literal>www.example.com</literal>
2287     whose name starts with <literal>/index.html</literal>.
2288    </para>
2289   </listitem>
2290  </varlistentry>
2291  <varlistentry>
2292   <term><literal>www.example.com/index.html$</literal></term>
2293   <listitem>
2294    <para>
2295     matches only the single document <literal>/index.html</literal>
2296     on <literal>www.example.com</literal>.
2297    </para>
2298   </listitem>
2299  </varlistentry>
2300  <varlistentry>
2301   <term><literal>/index.html$</literal></term>
2302   <listitem>
2303    <para>
2304     matches the document <literal>/index.html</literal>, regardless of the domain,
2305     i.e. on <emphasis>any</emphasis> web server anywhere.
2306    </para>
2307   </listitem>
2308  </varlistentry>
2309  <varlistentry>
2310   <term><literal>:8000/</literal></term>
2311   <listitem>
2312    <para>
2313     Matches any URL pointing to TCP port 8000.
2314    </para>
2315   </listitem>
2316  </varlistentry>
2317  <varlistentry>
2318   <term><literal>&lt;2001:db8::1&gt;/</literal></term>
2319   <listitem>
2320    <para>
2321     Matches any URL with the host address <literal>2001:db8::1</literal>.
2322     (Note that the real URL uses plain brackets, not angle brackets.)
2323    </para>
2324   </listitem>
2325  </varlistentry>
2326  <varlistentry>
2327   <term><literal>index.html</literal></term>
2328   <listitem>
2329    <para>
2330     matches nothing, since it would be interpreted as a domain name and
2331     there is no top-level domain called <literal>.html</literal>. So its 
2332     a mistake.
2333    </para>
2334   </listitem>
2335  </varlistentry>
2336 </variablelist>
2337
2338
2339 <!--   ~~~~~       New section      ~~~~~     -->
2340 <sect3><title>The Domain Pattern</title>
2341
2342 <para>
2343  The matching of the domain part offers some flexible options: if the
2344  domain starts or ends with a dot, it becomes unanchored at that end. 
2345  For example:
2346 </para>
2347
2348 <variablelist>
2349  <varlistentry>
2350   <term><literal>.example.com</literal></term>
2351   <listitem>
2352    <para>
2353     matches any domain with first-level domain <literal>com</literal>
2354     and second-level domain <literal>example</literal>.
2355     For example <literal>www.example.com</literal>,
2356     <literal>example.com</literal> and <literal>foo.bar.baz.example.com</literal>.
2357     Note that it wouldn't match if the second-level domain was <literal>another-example</literal>.
2358    </para>
2359   </listitem>
2360  </varlistentry>
2361  <varlistentry>
2362   <term><literal>www.</literal></term>
2363   <listitem>
2364    <para>
2365     matches any domain that <emphasis>STARTS</emphasis> with
2366     <literal>www.</literal> (It also matches the domain
2367     <literal>www</literal> but most of the time that doesn't matter.)
2368    </para>
2369   </listitem>
2370  </varlistentry>
2371  <varlistentry>
2372   <term><literal>.example.</literal></term>
2373   <listitem>
2374    <para>
2375     matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>.
2376     And, by the way, also included would be any files or documents that exist
2377     within that domain since no path limitations are specified. (Correctly
2378     speaking: It matches any FQDN that contains <literal>example</literal> as
2379     a domain.) This might be <literal>www.example.com</literal>,
2380     <literal>news.example.de</literal>, or
2381     <literal>www.example.net/cgi/testing.pl</literal> for instance. All these
2382     cases are matched. 
2383    </para>
2384   </listitem>
2385  </varlistentry>
2386 </variablelist>
2387
2388 <para>
2389  Additionally, there are wild-cards that you can use in the domain names
2390  themselves. These work similarly to shell globbing type wild-cards:
2391  <quote>*</quote> represents zero or more arbitrary characters (this is
2392  equivalent to the 
2393  <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2394  Expression</quote></ulink> based syntax of <quote>.*</quote>),
2395  <quote>?</quote>  represents any single character (this is equivalent to the
2396  regular expression syntax of a simple <quote>.</quote>), and you can define
2397  <quote>character classes</quote> in square brackets which is similar to 
2398  the same regular expression technique. All of this can be freely mixed:
2399 </para>
2400
2401 <variablelist>
2402  <varlistentry>
2403   <term><literal>ad*.example.com</literal></term>
2404   <listitem>
2405    <para>
2406     matches <quote>adserver.example.com</quote>, 
2407     <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2408    </para>
2409   </listitem>
2410  </varlistentry>
2411  <varlistentry>
2412   <term><literal>*ad*.example.com</literal></term>
2413   <listitem>
2414    <para>
2415     matches all of the above, and then some.
2416    </para>
2417   </listitem>
2418  </varlistentry>
2419  <varlistentry>
2420   <term><literal>.?pix.com</literal></term>
2421   <listitem>
2422    <para>
2423     matches <literal>www.ipix.com</literal>,
2424     <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc. 
2425    </para>
2426   </listitem>
2427  </varlistentry>
2428  <varlistentry>
2429   <term><literal>www[1-9a-ez].example.c*</literal></term>
2430   <listitem>
2431    <para>
2432      matches <literal>www1.example.com</literal>, 
2433      <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>, 
2434      <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis> 
2435      <literal>wwww.example.com</literal>.
2436    </para>
2437   </listitem>
2438  </varlistentry>
2439 </variablelist>
2440
2441 <para>
2442  While flexible, this is not the sophistication of full regular expression based syntax.
2443 </para>
2444
2445 </sect3>
2446
2447 <!--  ~  End section  ~  -->
2448
2449
2450 <!--   ~~~~~       New section      ~~~~~     -->
2451 <sect3><title>The Path Pattern</title>
2452
2453 <para>
2454  <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
2455   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
2456   Expressions</quote></ulink> for matching the path portion (after the slash),
2457   and is thus more flexible.
2458 </para>
2459
2460 <para>
2461  There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2462  expressions, you also might want to have a look at your operating system's documentation
2463  on regular expressions (try <literal>man re_format</literal>).
2464 </para>
2465
2466 <para>
2467  Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2468  i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak 
2469  for the beginning of a line).
2470 </para>
2471
2472 <para>
2473  Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
2474  by default, but you can switch to case sensitive at any point in the pattern by using the 
2475  <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
2476  only documents whose path starts with <literal>PaTtErN</literal> in
2477  <emphasis>exactly</emphasis> this capitalization.
2478 </para>
2479
2480 <variablelist>
2481  <varlistentry>
2482   <term><literal>.example.com/.*</literal></term>
2483   <listitem>
2484    <para>
2485      Is equivalent to just <quote>.example.com</quote>, since any documents 
2486      within that domain are matched with or without the <quote>.*</quote>
2487      regular expression. This is redundant
2488    </para>
2489   </listitem>
2490  </varlistentry>
2491  <varlistentry>
2492   <term><literal>.example.com/.*/index.html$</literal></term>
2493   <listitem>
2494    <para>
2495     Will match any page in the domain of <quote>example.com</quote> that is
2496     named <quote>index.html</quote>, and that is part of some path. For
2497     example, it matches <quote>www.example.com/testing/index.html</quote> but
2498     NOT <quote>www.example.com/index.html</quote> because the regular
2499     expression called for at least two <quote>/'s</quote>, thus the path 
2500     requirement. It also would match 
2501     <quote>www.example.com/testing/index_html</quote>, because of the 
2502     special meta-character <quote>.</quote>.
2503    </para>
2504   </listitem>
2505  </varlistentry>
2506  <varlistentry>
2507   <term><literal>.example.com/(.*/)?index\.html$</literal></term>
2508   <listitem>
2509    <para>
2510     This regular expression is conditional so it will match any page 
2511     named <quote>index.html</quote> regardless of path which in this case can 
2512     have one or more <quote>/'s</quote>. And this one must contain exactly 
2513     <quote>.html</quote> (but does not have to end with that!).
2514    </para>
2515   </listitem>
2516  </varlistentry>
2517  <varlistentry>
2518   <term><literal>.example.com/(.*/)(ads|banners?|junk)</literal></term>
2519   <listitem>
2520    <para>
2521     This regular expression will match any path of <quote>example.com</quote>
2522     that contains any of the words <quote>ads</quote>, <quote>banner</quote>, 
2523     <quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
2524     The path does not have to end in these words, just contain them.
2525    </para>
2526   </listitem>
2527  </varlistentry>
2528  <varlistentry>
2529   <term><literal>.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$</literal></term>
2530   <listitem>
2531    <para>
2532     This is very much the same as above, except now it must end in either 
2533     <quote>.jpg</quote>, <quote>.jpeg</quote>, <quote>.gif</quote> or <quote>.png</quote>. So this 
2534     one is limited to common image formats.
2535    </para>
2536   </listitem>
2537  </varlistentry>
2538
2539 </variablelist>
2540 <para>
2541  There are many, many good examples to be found in <filename>default.action</filename>, 
2542  and more tutorials below in <link linkend="regex">Appendix on regular expressions</link>.
2543 </para>
2544
2545 </sect3>
2546
2547 <!--  ~  End section  ~  -->
2548
2549
2550 <!--   ~~~~~       New section      ~~~~~     -->
2551 <sect3 id="tag-pattern"><title>The Tag Pattern</title>
2552
2553 <para>
2554  Tag patterns are used to change the applying actions based on the
2555  request's tags. Tags can be created with either the
2556  <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
2557  or the  <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
2558 </para>
2559
2560 <para>
2561  Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
2562  can tell them apart from URL patterns. Everything after the colon
2563  including white space, is interpreted as a regular expression with
2564  path pattern syntax, except that tag patterns aren't left-anchored
2565  automatically (&my-app; doesn't silently add a <quote>^</quote>,
2566  you have to do it yourself if you need it).
2567 </para>
2568
2569 <para>
2570  To match all requests that are tagged with <quote>foo</quote>
2571  your pattern line should be <quote>TAG:^foo$</quote>,
2572  <quote>TAG:foo</quote> would work as well, but it would also
2573  match requests whose tags contain <quote>foo</quote> somewhere.
2574  <quote>TAG: foo</quote> wouldn't work as it requires white space.
2575 </para>
2576
2577 <para>
2578  Sections can contain URL and tag patterns at the same time,
2579  but tag patterns are checked after the URL patterns and thus
2580  always overrule them, even if they are located before the URL patterns.
2581 </para>
2582
2583 <para>
2584  Once a new tag is added, Privoxy checks right away if it's matched by one
2585  of the tag patterns and updates the action settings accordingly. As a result
2586  tags can be used to activate other tagger actions, as long as these other
2587  taggers look for headers that haven't already be parsed.
2588 </para>
2589
2590 <para>
2591  For example you could tag client requests which use the
2592  <literal>POST</literal> method,
2593  then use this tag to activate another tagger that adds a tag if cookies
2594  are sent, and then use a block action based on the cookie tag. This allows
2595  the outcome of one action, to be input into a subsequent action. However if
2596  you'd reverse the position of the described taggers, and activated the
2597  method tagger based on the cookie tagger, no method tags would be created.
2598  The method tagger would look for the request line, but at the time
2599  the cookie tag is created, the request line has already been parsed.
2600 </para>
2601
2602 <para>
2603  While this is a limitation you should be aware of, this kind of
2604  indirection is seldom needed anyway and even the example doesn't
2605  make too much sense.
2606 </para>
2607
2608 </sect3>
2609
2610 </sect2>
2611
2612 <!--  ~  End section  ~  -->
2613
2614
2615 <!--   ~~~~~       New section      ~~~~~     -->
2616
2617 <sect2 id="actions">
2618 <title>Actions</title>
2619 <para>
2620  All actions are disabled by default, until they are explicitly enabled
2621  somewhere in an actions file. Actions are turned on if preceded with a
2622  <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
2623  <literal>+action</literal> means <quote>do that action</quote>, e.g.
2624  <literal>+block</literal> means <quote>please block URLs that match the
2625  following patterns</quote>, and <literal>-block</literal> means <quote>don't
2626  block URLs that match the following patterns, even if <literal>+block</literal>
2627  previously applied.</quote>
2628
2629 </para>
2630
2631 <para> 
2632  Again, actions are invoked by placing them on a line, enclosed in curly braces and
2633  separated by whitespace, like in 
2634  <literal>{+some-action -some-other-action{some-parameter}}</literal>,
2635  followed by a list of URL patterns, one per line, to which they apply.
2636  Together, the actions line and the following pattern lines make up a section
2637  of the actions file. 
2638 </para>
2639
2640 <para> 
2641  Actions fall into three categories:
2642 </para>
2643
2644 <para>
2645  <itemizedlist>
2646  <listitem>
2647   <para>  
2648    Boolean, i.e the action can only be <quote>enabled</quote> or
2649    <quote>disabled</quote>. Syntax:
2650   </para>
2651   <para>
2652    <screen>
2653   +<replaceable class="function">name</replaceable>        # enable action <replaceable class="parameter">name</replaceable>
2654   -<replaceable class="function">name</replaceable>        # disable action <replaceable class="parameter">name</replaceable></screen>
2655   </para>
2656   <para>  
2657    Example: <literal>+handle-as-image</literal>
2658   </para>
2659  </listitem>
2660
2661
2662  <listitem>
2663   <para>  
2664    Parameterized, where some value is required in order to enable this type of action.
2665    Syntax:
2666   </para>
2667   <para>
2668    <screen>
2669   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}  # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
2670                # overwriting parameter from previous match if necessary
2671   -<replaceable class="function">name</replaceable>         # disable action. The parameter can be omitted</screen>
2672   </para>
2673   <para>
2674    Note that if the URL matches multiple positive forms of a parameterized action,
2675    the last match wins, i.e. the params from earlier matches are simply ignored.
2676   </para>
2677   <para>  
2678    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>
2679   </para>
2680  </listitem>
2681  
2682  <listitem>
2683   <para>  
2684    Multi-value. These look exactly like parameterized actions,
2685    but they behave differently: If the action applies multiple times to the
2686    same URL, but with different parameters, <emphasis>all</emphasis> the parameters
2687    from <emphasis>all</emphasis> matches are remembered. This is used for actions
2688    that can be executed for the same request repeatedly, like adding multiple
2689    headers, or filtering through multiple filters. Syntax:
2690   </para>
2691   <para>
2692    <screen>
2693   +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
2694   -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
2695                 # If it was the last one left, disable the action.
2696   <replaceable class="parameter">-name</replaceable>          # disable this action completely and remove all parameters from the list</screen>
2697   </para>
2698   <para>  
2699    Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
2700    <literal>+filter{html-annoyances}</literal>
2701   </para>
2702  </listitem>
2703
2704  </itemizedlist>
2705 </para>
2706
2707 <para>
2708  If nothing is specified in any actions file, no <quote>actions</quote> are
2709  taken. So in this case <application>Privoxy</application> would just be a
2710  normal, non-blocking, non-filtering proxy. You must specifically enable the
2711  privacy and blocking features you need (although the provided default actions
2712  files will give a good starting point).
2713 </para>
2714
2715 <para>
2716  Later defined action sections always over-ride earlier ones of the same type.
2717  So exceptions to any rules you make, should come in the latter part of the file (or 
2718  in a file that is processed later when using multiple actions files such 
2719  as <filename>user.action</filename>). For multi-valued actions, the actions
2720  are applied in the order they are specified. Actions files are processed in
2721  the order they are defined in <filename>config</filename> (the default
2722  installation has three actions files). It also quite possible for any given
2723  URL to match more than one <quote>pattern</quote> (because of wildcards and
2724  regular expressions), and thus to trigger more than one set of actions! Last
2725  match wins.
2726 </para>
2727
2728 <!-- start actions listing -->
2729 <para>
2730  The list of valid <application>Privoxy</application> actions are:
2731 </para>
2732
2733
2734 <!-- ********************************************************** -->
2735 <!-- Please note the below defined actions use id's that are    -->
2736 <!-- probably linked from other places, so please don't change. -->
2737 <!--                                                            -->
2738 <!-- ********************************************************** -->
2739
2740
2741 <!--   ~~~~~       New section      ~~~~~     -->
2742
2743 <sect3 renderas="sect4" id="add-header">
2744 <title>add-header</title>
2745
2746 <variablelist>
2747  <varlistentry>
2748   <term>Typical use:</term>
2749   <listitem>
2750    <para>Confuse log analysis, custom applications</para>
2751   </listitem>
2752  </varlistentry>
2753
2754  <varlistentry>
2755   <term>Effect:</term>
2756   <listitem>
2757    <para>
2758     Sends a user defined HTTP header to the web server.
2759    </para>
2760   </listitem>
2761  </varlistentry>
2762
2763  <varlistentry>
2764   <term>Type:</term>
2765   <!-- boolean, parameterized, Multi-value -->
2766   <listitem>
2767    <para>Multi-value.</para>
2768   </listitem>
2769  </varlistentry>
2770  
2771  <varlistentry>
2772   <term>Parameter:</term>
2773   <listitem>
2774    <para>
2775     Any string value is possible. Validity of the defined HTTP headers is not checked.
2776     It is recommended that you use the <quote><literal>X-</literal></quote> prefix
2777     for custom headers.
2778    </para>
2779   </listitem>
2780  </varlistentry>
2781  
2782 <varlistentry>
2783   <term>Notes:</term>
2784   <listitem>
2785    <para>
2786     This action may be specified multiple times, in order to define multiple 
2787     headers. This is rarely needed for the typical user. If you don't know what 
2788     <quote>HTTP headers</quote> are, you definitely don't need to worry about this 
2789     one.
2790    </para>
2791   </listitem>
2792  </varlistentry>
2793
2794  <varlistentry>
2795   <term>Example usage:</term>
2796   <listitem>
2797     <para>
2798      <screen>+add-header{X-User-Tracking: sucks}</screen>
2799    </para>
2800   </listitem>
2801  </varlistentry>
2802 </variablelist>
2803 </sect3>
2804
2805
2806 <!--   ~~~~~       New section      ~~~~~     -->
2807 <sect3 renderas="sect4" id="block">
2808 <title>block</title>
2809
2810 <variablelist>
2811  <varlistentry>
2812   <term>Typical use:</term>
2813   <listitem>
2814    <para>Block ads or other unwanted content</para>
2815   </listitem>
2816  </varlistentry>
2817
2818  <varlistentry>
2819   <term>Effect:</term>
2820   <listitem>
2821    <para>
2822     Requests for URLs to which this action applies are blocked, i.e. the
2823     requests are trapped by &my-app; and the requested URL is never retrieved,
2824     but is answered locally with a substitute page or image, as determined by
2825     the <literal><link
2826     linkend="handle-as-image">handle-as-image</link></literal>,
2827     <literal><link
2828     linkend="set-image-blocker">set-image-blocker</link></literal>, and 
2829     <literal><link
2830     linkend="handle-as-empty-document">handle-as-empty-document</link></literal> actions.
2831     
2832    </para>
2833   </listitem>
2834  </varlistentry>
2835
2836  <varlistentry>
2837   <term>Type:</term>
2838   <!-- boolean, parameterized, Multi-value -->
2839   <listitem>
2840    <para>Parameterized.</para>
2841   </listitem>
2842  </varlistentry>
2843
2844  <varlistentry>
2845   <term>Parameter:</term>
2846   <listitem>
2847    <para>A block reason that should be given to the user.</para>
2848   </listitem>
2849  </varlistentry>
2850  
2851 <varlistentry>
2852   <term>Notes:</term>
2853   <listitem>
2854    <para>
2855     <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
2856     for requests to blocked pages. This page contains the block reason given as
2857     parameter, a link to find out why the block action applies, and a click-through
2858     to the blocked content (the latter only if the force feature is available and
2859     enabled).
2860    </para>
2861    <para> 
2862     A very important exception occurs if <emphasis>both</emphasis> 
2863     <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
2864     apply to the same request: it will then be replaced by an image. If 
2865     <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
2866     (see below) also applies, the type of image will be determined by its parameter,
2867     if not, the standard checkerboard pattern is sent.
2868    </para>
2869    <para>
2870     It is important to understand this process, in order 
2871     to understand how <application>Privoxy</application> deals with 
2872     ads and other unwanted content. Blocking is a core feature, and one 
2873     upon which various other features depend.
2874    </para>
2875    <para>
2876     The <literal><link linkend="filter">filter</link></literal>
2877     action can perform a very similar task, by <quote>blocking</quote>
2878     banner images and other content through rewriting the relevant URLs in the
2879     document's HTML source, so they don't get requested in the first place.
2880     Note that this is a totally different technique, and it's easy to confuse the two.
2881    </para>
2882   </listitem>
2883  </varlistentry>
2884
2885  <varlistentry>
2886   <term>Example usage (section):</term>
2887   <listitem>
2888     <para>
2889      <screen>{+block{No nasty stuff for you.}}
2890 # Block and replace with "blocked" page
2891  .nasty-stuff.example.com
2892
2893 {+block{Doubleclick banners.} +handle-as-image} 
2894 # Block and replace with image
2895  .ad.doubleclick.net
2896  .ads.r.us/banners/
2897
2898 {+block{Layered ads.} +handle-as-empty-document} 
2899 # Block and then ignore
2900  adserver.example.net/.*\.js$</screen>
2901     </para>
2902   </listitem>
2903  </varlistentry>
2904
2905
2906 </variablelist>
2907 </sect3>
2908
2909
2910 <!--   ~~~~~       New section      ~~~~~     -->
2911 <sect3 renderas="sect4" id="change-x-forwarded-for">
2912 <title>change-x-forwarded-for</title>
2913
2914 <variablelist>
2915  <varlistentry>
2916   <term>Typical use:</term>
2917   <listitem>
2918    <para>Improve privacy by not forwarding the source of the request in the HTTP headers.</para>
2919   </listitem>
2920  </varlistentry>
2921
2922  <varlistentry>
2923   <term>Effect:</term>
2924   <listitem>
2925    <para>
2926     Deletes the <quote>X-Forwarded-For:</quote> HTTP header from the client request,
2927     or adds a new one.
2928    </para>
2929   </listitem>
2930  </varlistentry>
2931
2932  <varlistentry>
2933   <term>Type:</term>
2934   <!-- Boolean, Parameterized, Multi-value -->
2935   <listitem>
2936    <para>Parameterized.</para>
2937   </listitem>
2938  </varlistentry>
2939
2940  <varlistentry>
2941   <term>Parameter:</term>
2942   <listitem>
2943    <itemizedlist>
2944     <listitem>
2945      <para><quote>block</quote> to delete the header.</para>
2946     </listitem>
2947     <listitem>
2948      <para>
2949        <quote>add</quote> to create the header (or append
2950        the client's IP address to an already existing one).
2951      </para>
2952     </listitem>
2953    </itemizedlist>
2954   </listitem>
2955  </varlistentry>
2956  
2957  <varlistentry>
2958   <term>Notes:</term>
2959   <listitem>
2960    <para>
2961     It is safe and recommended to use <literal>block</literal>.
2962    </para>
2963    <para>
2964     Forwarding the source address of the request may make
2965     sense in some multi-user setups but is also a privacy risk.
2966    </para>
2967   </listitem>
2968  </varlistentry>
2969  <varlistentry>
2970   <term>Example usage:</term>
2971   <listitem>
2972     <para>
2973      <screen>+change-x-forwarded-for{block}</screen>
2974    </para>
2975   </listitem>
2976  </varlistentry>
2977 </variablelist>
2978 </sect3>
2979
2980 <!--   ~~~~~       New section      ~~~~~     -->
2981 <sect3 renderas="sect4" id="client-header-filter">
2982 <title>client-header-filter</title>
2983
2984 <variablelist>
2985  <varlistentry>
2986   <term>Typical use:</term>
2987   <listitem>
2988    <para>
2989    Rewrite or remove single client headers.
2990    </para>
2991   </listitem>
2992  </varlistentry>
2993
2994  <varlistentry>
2995   <term>Effect:</term>
2996   <listitem>
2997    <para>
2998     All client headers to which this action applies are filtered on-the-fly through
2999     the specified regular expression based substitutions.
3000    </para>
3001   </listitem>
3002  </varlistentry>
3003
3004  <varlistentry>
3005   <term>Type:</term>
3006   <!-- boolean, parameterized, Multi-value -->
3007   <listitem>
3008    <para>Parameterized.</para>
3009   </listitem>
3010  </varlistentry>
3011
3012  <varlistentry>
3013   <term>Parameter:</term>
3014   <listitem>
3015    <para>
3016     The name of a client-header filter, as defined in one of the
3017     <link linkend="filter-file">filter files</link>.
3018    </para>
3019   </listitem>
3020  </varlistentry>
3021  
3022  <varlistentry>
3023   <term>Notes:</term>
3024   <listitem>
3025    <para>
3026     Client-header filters are applied to each header on its own, not to
3027     all at once. This makes it easier to diagnose problems, but on the downside
3028     you can't write filters that only change header x if header y's value is z.
3029     You can do that by using tags though.
3030    </para>
3031    <para>
3032     Client-header filters are executed after the other header actions have finished
3033     and use their output as input.
3034    </para>
3035    <para>
3036     If the request URL gets changed, &my-app; will detect that and use the new
3037     one. This can be used to rewrite the request destination behind the client's
3038     back, for example to specify a Tor exit relay for certain requests.
3039    </para>
3040    <para>
3041     Please refer to the <link linkend="filter-file">filter file chapter</link>
3042     to learn which client-header filters are available by default, and how to
3043     create your own.
3044    </para>
3045
3046   </listitem>
3047  </varlistentry>
3048
3049  <varlistentry>
3050   <term>Example usage (section):</term>
3051   <listitem>
3052     <para>
3053      <screen>
3054 # Hide Tor exit notation in Host and Referer Headers
3055 {+client-header-filter{hide-tor-exit-notation}}
3056 /
3057     </screen>
3058     </para>
3059   </listitem>
3060  </varlistentry>
3061
3062 </variablelist>
3063 </sect3>
3064
3065
3066 <!--   ~~~~~       New section      ~~~~~     -->
3067 <sect3 renderas="sect4" id="client-header-tagger">
3068 <title>client-header-tagger</title>
3069
3070 <variablelist>
3071  <varlistentry>
3072   <term>Typical use:</term>
3073   <listitem>
3074    <para>
3075    Block requests based on their headers.
3076    </para>
3077   </listitem>
3078  </varlistentry>
3079
3080  <varlistentry>
3081   <term>Effect:</term>
3082   <listitem>
3083    <para>
3084     Client headers to which this action applies are filtered on-the-fly through
3085     the specified regular expression based substitutions, the result is used as
3086     tag. 
3087    </para>
3088   </listitem>
3089  </varlistentry>
3090
3091  <varlistentry>
3092   <term>Type:</term>
3093   <!-- boolean, parameterized, Multi-value -->
3094   <listitem>
3095    <para>Parameterized.</para>
3096   </listitem>
3097  </varlistentry>
3098
3099  <varlistentry>
3100   <term>Parameter:</term>
3101   <listitem>
3102    <para>
3103     The name of a client-header tagger, as defined in one of the
3104     <link linkend="filter-file">filter files</link>.
3105    </para>
3106   </listitem>
3107  </varlistentry>
3108  
3109  <varlistentry>
3110   <term>Notes:</term>
3111   <listitem>
3112    <para>
3113     Client-header taggers are applied to each header on its own,
3114     and as the header isn't modified, each tagger <quote>sees</quote>
3115     the original.
3116    </para>
3117    <para>
3118     Client-header taggers are the first actions that are executed
3119     and their tags can be used to control every other action.
3120    </para>
3121  </listitem>
3122  </varlistentry>
3123
3124  <varlistentry>
3125   <term>Example usage (section):</term>
3126   <listitem>
3127     <para>
3128      <screen>
3129 # Tag every request with the User-Agent header
3130 {+client-header-tagger{user-agent}}
3131 /
3132
3133 # Tagging itself doesn't change the action
3134 # settings, sections with TAG patterns do:
3135 #
3136 # If it's a download agent, use a different forwarding proxy,
3137 # show the real User-Agent and make sure resume works.
3138 {+forward-override{forward-socks5 10.0.0.2:2222 .} \
3139  -hide-if-modified-since      \
3140  -overwrite-last-modified     \
3141  -hide-user-agent             \
3142  -filter                      \
3143  -deanimate-gifs              \
3144 }
3145 TAG:^User-Agent: NetBSD-ftp/
3146 TAG:^User-Agent: Novell ZYPP Installer
3147 TAG:^User-Agent: RPM APT-HTTP/
3148 TAG:^User-Agent: fetch libfetch/
3149 TAG:^User-Agent: Ubuntu APT-HTTP/
3150 TAG:^User-Agent: MPlayer/
3151     </screen>
3152     </para>
3153   </listitem>
3154  </varlistentry>
3155
3156 </variablelist>
3157 </sect3>
3158
3159
3160 <!--   ~~~~~       New section      ~~~~~     -->
3161 <sect3 renderas="sect4" id="content-type-overwrite">
3162 <title>content-type-overwrite</title>
3163
3164 <variablelist>
3165  <varlistentry>
3166   <term>Typical use:</term>
3167   <listitem>
3168    <para>Stop useless download menus from popping up, or change the browser's rendering mode</para>
3169   </listitem>
3170  </varlistentry>
3171
3172  <varlistentry>
3173   <term>Effect:</term>
3174   <listitem>
3175    <para>
3176     Replaces the <quote>Content-Type:</quote> HTTP server header.
3177    </para>
3178   </listitem>
3179  </varlistentry>
3180
3181  <varlistentry>
3182   <term>Type:</term>
3183   <!-- Boolean, Parameterized, Multi-value -->
3184   <listitem>
3185    <para>Parameterized.</para>
3186   </listitem>
3187  </varlistentry>
3188
3189  <varlistentry>
3190   <term>Parameter:</term>
3191   <listitem>
3192    <para>
3193     Any string. 
3194    </para>    
3195   </listitem>
3196  </varlistentry>
3197  
3198  <varlistentry>
3199   <term>Notes:</term>
3200   <listitem>
3201    <para>
3202     The <quote>Content-Type:</quote> HTTP server header is used by the
3203     browser to decide what to do with the document. The value of this
3204     header can cause the browser to open a download menu instead of
3205     displaying the document by itself, even if the document's format is
3206     supported by the browser. 
3207    </para>
3208    <para>
3209     The declared content type can also affect which rendering mode
3210     the browser chooses. If XHTML is delivered as <quote>text/html</quote>,
3211     many browsers treat it as yet another broken HTML document.
3212     If it is send as <quote>application/xml</quote>, browsers with
3213     XHTML support will only display it, if the syntax is correct.
3214    </para>
3215    <para>
3216     If you see a web site that proudly uses XHTML buttons, but sets
3217     <quote>Content-Type: text/html</quote>, you can use &my-app;
3218     to overwrite it with <quote>application/xml</quote> and validate
3219     the web master's claim inside your XHTML-supporting browser.
3220     If the syntax is incorrect, the browser will complain loudly. 
3221    </para>
3222    <para>
3223     You can also go the opposite direction: if your browser prints
3224     error messages instead of rendering a document falsely declared
3225     as XHTML, you can overwrite the content type with
3226     <quote>text/html</quote> and have it rendered as broken HTML document. 
3227    </para>
3228    <para>
3229     By default <literal>content-type-overwrite</literal> only replaces
3230     <quote>Content-Type:</quote> headers that look like some kind of text.
3231     If you want to overwrite it unconditionally, you have to combine it with
3232     <literal><link linkend="force-text-mode">force-text-mode</link></literal>.
3233     This limitation exists for a reason, think twice before circumventing it.
3234    </para>
3235    <para>
3236     Most of the time it's easier to replace this action with a custom
3237     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3238     It allows you to activate it for every document of a certain site and it will still
3239     only replace the content types you aimed at.
3240    </para>
3241    <para>
3242     Of course you can apply <literal>content-type-overwrite</literal>
3243     to a whole site and then make URL based exceptions, but it's a lot
3244     more work to get the same precision. 
3245    </para>
3246   </listitem>
3247  </varlistentry>
3248
3249  <varlistentry>
3250   <term>Example usage (sections):</term>
3251   <listitem>
3252     <para>
3253      <screen># Check if www.example.net/ really uses valid XHTML
3254 { +content-type-overwrite{application/xml} }
3255 www.example.net/
3256
3257 # but leave the content type unmodified if the URL looks like a style sheet
3258 {-content-type-overwrite}
3259 www.example.net/.*\.css$
3260 www.example.net/.*style
3261 </screen>
3262    </para>
3263   </listitem>
3264  </varlistentry>
3265 </variablelist>
3266 </sect3>
3267
3268
3269 <!--   ~~~~~       New section      ~~~~~     -->
3270 <sect3 renderas="sect4" id="crunch-client-header">
3271 <!--
3272 new action
3273 -->
3274 <title>crunch-client-header</title>
3275
3276 <variablelist>
3277  <varlistentry>
3278   <term>Typical use:</term>
3279   <listitem>
3280    <para>Remove a client header <application>Privoxy</application> has no dedicated action for.</para>
3281   </listitem>
3282  </varlistentry>
3283
3284  <varlistentry>
3285   <term>Effect:</term>
3286   <listitem>
3287    <para>
3288     Deletes every header sent by the client that contains the string the user supplied as parameter.
3289    </para>
3290   </listitem>
3291  </varlistentry>
3292
3293  <varlistentry>
3294   <term>Type:</term>
3295   <!-- Boolean, Parameterized, Multi-value -->
3296   <listitem>
3297    <para>Parameterized.</para>
3298   </listitem>
3299  </varlistentry>
3300
3301  <varlistentry>
3302   <term>Parameter:</term>
3303   <listitem>
3304    <para>
3305     Any string.
3306    </para>    
3307   </listitem>
3308  </varlistentry>
3309  
3310  <varlistentry>
3311   <term>Notes:</term>
3312   <listitem>
3313    <para>
3314     This action allows you to block client headers for which no dedicated
3315     <application>Privoxy</application> action exists.
3316     <application>Privoxy</application> will remove every client header that
3317     contains the string you supplied as parameter.
3318    </para>
3319    <para>
3320     Regular expressions are <emphasis>not supported</emphasis> and you can't
3321     use this action to block different headers in the same request, unless
3322     they contain the same string.
3323    </para>
3324    <para>
3325     <literal>crunch-client-header</literal> is only meant for quick tests.
3326     If you have to block several different headers, or only want to modify
3327     parts of them, you should use a
3328     <literal><link linkend="client-header-filter">client-header filter</link></literal>.
3329    </para>
3330     <warning>
3331      <para>
3332       Don't block any header without understanding the consequences.
3333      </para>
3334     </warning>
3335   </listitem>
3336  </varlistentry>
3337
3338  <varlistentry>
3339   <term>Example usage (section):</term>
3340   <listitem>
3341     <para>
3342      <screen># Block the non-existent "Privacy-Violation:" client header 
3343 { +crunch-client-header{Privacy-Violation:} }
3344 /
3345     </screen>
3346    </para>
3347   </listitem>
3348  </varlistentry>
3349 </variablelist>
3350 </sect3>
3351
3352
3353 <!--   ~~~~~       New section      ~~~~~     -->
3354 <sect3 renderas="sect4" id="crunch-if-none-match">
3355 <title>crunch-if-none-match</title>
3356 <!--
3357 new action
3358 -->
3359 <variablelist>
3360  <varlistentry>
3361   <term>Typical use:</term>
3362   <listitem>
3363    <para>Prevent yet another way to track the user's steps between sessions.</para>
3364   </listitem>
3365  </varlistentry>
3366
3367  <varlistentry>
3368   <term>Effect:</term>
3369   <listitem>
3370    <para>
3371     Deletes the <quote>If-None-Match:</quote> HTTP client header.
3372    </para>
3373   </listitem>
3374  </varlistentry>
3375
3376  <varlistentry>
3377   <term>Type:</term>
3378   <!-- Boolean, Parameterized, Multi-value -->
3379   <listitem>
3380    <para>Boolean.</para>
3381   </listitem>
3382  </varlistentry>
3383
3384  <varlistentry>
3385   <term>Parameter:</term>
3386   <listitem>
3387    <para>
3388     N/A
3389    </para>    
3390   </listitem>
3391  </varlistentry>
3392  
3393  <varlistentry>
3394   <term>Notes:</term>
3395   <listitem>
3396    <para>
3397     Removing the <quote>If-None-Match:</quote> HTTP client header
3398     is useful for filter testing, where you want to force a real
3399     reload instead of getting status code <quote>304</quote> which
3400     would cause the browser to use a cached copy of the page.
3401    </para>
3402    <para>
3403     It is also useful to make sure the header isn't used as a cookie
3404     replacement (unlikely but possible).
3405    </para>
3406    <para>
3407     Blocking the <quote>If-None-Match:</quote> header shouldn't cause any
3408     caching problems, as long as the <quote>If-Modified-Since:</quote> header
3409     isn't blocked or missing as well.
3410    </para>
3411    <para>
3412     It is recommended to use this action together with
3413     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
3414     and
3415     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>.
3416    </para>
3417   </listitem>
3418  </varlistentry>
3419
3420  <varlistentry>
3421   <term>Example usage (section):</term>
3422   <listitem>
3423     <para>
3424      <screen># Let the browser revalidate cached documents but don't
3425 # allow the server to use the revalidation headers for user tracking.
3426 {+hide-if-modified-since{-60} \
3427  +overwrite-last-modified{randomize} \
3428  +crunch-if-none-match}
3429 /   </screen>
3430    </para>
3431   </listitem>
3432  </varlistentry>
3433 </variablelist>
3434 </sect3>
3435
3436
3437 <!--   ~~~~~       New section      ~~~~~     -->
3438 <sect3 renderas="sect4" id="crunch-incoming-cookies">
3439 <title>crunch-incoming-cookies</title>
3440
3441 <variablelist>
3442  <varlistentry>
3443   <term>Typical use:</term>
3444   <listitem>
3445    <para>
3446     Prevent the web server from setting HTTP cookies on your system
3447    </para>
3448   </listitem>
3449  </varlistentry>
3450
3451  <varlistentry>
3452   <term>Effect:</term>
3453   <listitem>
3454    <para>
3455     Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
3456    </para>
3457   </listitem>
3458  </varlistentry>
3459
3460  <varlistentry>
3461   <term>Type:</term>
3462   <!-- Boolean, Parameterized, Multi-value -->
3463   <listitem>
3464    <para>Boolean.</para>
3465   </listitem>
3466  </varlistentry>
3467
3468  <varlistentry>
3469   <term>Parameter:</term>
3470   <listitem>
3471    <para>
3472     N/A
3473    </para>
3474   </listitem>
3475  </varlistentry>
3476  
3477  <varlistentry>
3478   <term>Notes:</term>
3479   <listitem>
3480    <para>
3481     This action is only concerned with <emphasis>incoming</emphasis> HTTP cookies. For
3482     <emphasis>outgoing</emphasis> HTTP cookies, use
3483     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
3484     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3485    </para>
3486    <para>
3487     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3488     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3489     since it would prevent the session cookies from being set. See also 
3490     <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
3491    </para>
3492   </listitem>
3493  </varlistentry>
3494
3495  <varlistentry>
3496   <term>Example usage:</term>
3497   <listitem>
3498    <para>
3499     <screen>+crunch-incoming-cookies</screen>
3500    </para>
3501   </listitem>
3502  </varlistentry>
3503 </variablelist>
3504 </sect3>
3505
3506
3507 <!--   ~~~~~       New section      ~~~~~     -->
3508 <sect3 renderas="sect4" id="crunch-server-header">
3509 <title>crunch-server-header</title>
3510 <!--
3511 new action
3512 -->
3513 <variablelist>
3514  <varlistentry>
3515   <term>Typical use:</term>
3516   <listitem>
3517    <para>Remove a server header <application>Privoxy</application> has no dedicated action for.</para>
3518   </listitem>
3519  </varlistentry>
3520
3521  <varlistentry>
3522   <term>Effect:</term>
3523   <listitem>
3524    <para>
3525     Deletes every header sent by the server that contains the string the user supplied as parameter.
3526    </para>
3527   </listitem>
3528  </varlistentry>
3529
3530  <varlistentry>
3531   <term>Type:</term>
3532   <!-- Boolean, Parameterized, Multi-value -->
3533   <listitem>
3534    <para>Parameterized.</para>
3535   </listitem>
3536  </varlistentry>
3537
3538  <varlistentry>
3539   <term>Parameter:</term>
3540   <listitem>
3541    <para>
3542     Any string.
3543    </para>    
3544   </listitem>
3545  </varlistentry>
3546  
3547  <varlistentry>
3548   <term>Notes:</term>
3549   <listitem>
3550    <para>
3551     This action allows you to block server headers for which no dedicated
3552     <application>Privoxy</application> action exists. <application>Privoxy</application>
3553     will remove every server header that contains the string you supplied as parameter.
3554    </para>
3555    <para>
3556     Regular expressions are <emphasis>not supported</emphasis> and you can't
3557     use this action to block different headers in the same request, unless
3558     they contain the same string.
3559    </para>
3560    <para>
3561     <literal>crunch-server-header</literal> is only meant for quick tests.
3562     If you have to block several different headers, or only want to modify
3563     parts of them, you should use a custom
3564     <literal><link linkend="server-header-filter">server-header filter</link></literal>.
3565    </para>
3566     <warning>
3567      <para>
3568      Don't block any header without understanding the consequences.
3569      </para>
3570     </warning>
3571   </listitem>
3572  </varlistentry>
3573
3574  <varlistentry>
3575   <term>Example usage (section):</term>
3576   <listitem>
3577     <para>
3578      <screen># Crunch server headers that try to prevent caching
3579 { +crunch-server-header{no-cache} }
3580 /   </screen>
3581    </para>
3582   </listitem>
3583  </varlistentry>
3584 </variablelist>
3585 </sect3>
3586
3587
3588 <!--   ~~~~~       New section      ~~~~~     -->
3589 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
3590 <title>crunch-outgoing-cookies</title>
3591
3592 <variablelist>
3593  <varlistentry>
3594   <term>Typical use:</term>
3595   <listitem>
3596    <para>
3597     Prevent the web server from reading any HTTP cookies from your system
3598    </para>
3599   </listitem>
3600  </varlistentry>
3601
3602  <varlistentry>
3603   <term>Effect:</term>
3604   <listitem>
3605    <para>
3606     Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
3607    </para>
3608   </listitem>
3609  </varlistentry>
3610
3611  <varlistentry>
3612   <term>Type:</term>
3613   <!-- Boolean, Parameterized, Multi-value -->
3614   <listitem>
3615    <para>Boolean.</para>
3616   </listitem>
3617  </varlistentry>
3618
3619  <varlistentry>
3620   <term>Parameter:</term>
3621   <listitem>
3622    <para>
3623     N/A
3624    </para>
3625   </listitem>
3626  </varlistentry>
3627  
3628  <varlistentry>
3629   <term>Notes:</term>
3630   <listitem>
3631    <para>
3632     This action is only concerned with <emphasis>outgoing</emphasis> HTTP cookies. For
3633     <emphasis>incoming</emphasis> HTTP cookies, use
3634     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
3635     Use <emphasis>both</emphasis> to disable HTTP cookies completely.
3636    </para>
3637    <para>
3638     It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3639     with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3640     since it would prevent the session cookies from being read.
3641    </para>
3642   </listitem>
3643  </varlistentry>
3644
3645  <varlistentry>
3646   <term>Example usage:</term>
3647   <listitem>
3648    <para>
3649     <screen>+crunch-outgoing-cookies</screen>
3650    </para>
3651   </listitem>
3652  </varlistentry>
3653
3654 </variablelist>
3655 </sect3>
3656
3657
3658 <!--   ~~~~~       New section      ~~~~~     -->
3659 <sect3 renderas="sect4" id="deanimate-gifs">
3660 <title>deanimate-gifs</title>
3661
3662 <variablelist>
3663  <varlistentry>
3664   <term>Typical use:</term>
3665   <listitem>
3666    <para>Stop those annoying, distracting animated GIF images.</para>
3667   </listitem>
3668  </varlistentry>
3669
3670  <varlistentry>
3671   <term>Effect:</term>
3672   <listitem>
3673    <para>
3674     De-animate GIF animations, i.e. reduce them to their first or last image.
3675    </para>
3676   </listitem>
3677  </varlistentry>
3678
3679  <varlistentry>
3680   <term>Type:</term>
3681   <!-- boolean, parameterized, Multi-value -->
3682   <listitem>
3683    <para>Parameterized.</para>
3684   </listitem>
3685  </varlistentry>
3686
3687  <varlistentry>
3688   <term>Parameter:</term>
3689   <listitem>
3690    <para>
3691     <quote>last</quote> or <quote>first</quote>
3692    </para>
3693   </listitem>
3694  </varlistentry>
3695  
3696  <varlistentry>
3697   <term>Notes:</term>
3698   <listitem>
3699    <para>
3700     This will also shrink the images considerably (in bytes, not pixels!). If
3701     the option <quote>first</quote> is given, the first frame of the animation
3702     is used as the replacement. If <quote>last</quote> is given, the last
3703     frame of the animation is used instead, which probably makes more sense for
3704     most banner animations, but also has the risk of not showing the entire
3705     last frame (if it is only a delta to an earlier frame).
3706    </para>
3707    <para>
3708     You can safely use this action with patterns that will also match non-GIF
3709     objects, because no attempt will be made at anything that doesn't look like
3710     a GIF.
3711    </para>
3712   </listitem>
3713  </varlistentry>
3714
3715  <varlistentry>
3716   <term>Example usage:</term>
3717   <listitem>
3718     <para>
3719       <screen>+deanimate-gifs{last}</screen>
3720     </para>
3721   </listitem>
3722  </varlistentry>
3723 </variablelist>
3724 </sect3>
3725
3726 <!--   ~~~~~       New section      ~~~~~     -->
3727 <sect3 renderas="sect4" id="downgrade-http-version">
3728 <title>downgrade-http-version</title>
3729
3730 <variablelist>
3731  <varlistentry>
3732   <term>Typical use:</term>
3733   <listitem>
3734    <para>Work around (very rare) problems with HTTP/1.1</para>
3735   </listitem>
3736  </varlistentry>
3737
3738  <varlistentry>
3739   <term>Effect:</term>
3740   <listitem>
3741    <para>
3742     Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3743    </para>
3744   </listitem>
3745  </varlistentry>
3746
3747  <varlistentry>
3748   <term>Type:</term>
3749   <!-- boolean, parameterized, Multi-value -->
3750   <listitem>
3751    <para>Boolean.</para>
3752   </listitem>
3753  </varlistentry>
3754
3755  <varlistentry>
3756   <term>Parameter:</term>
3757   <listitem>
3758    <para>
3759     N/A
3760    </para>
3761   </listitem>
3762  </varlistentry>
3763  
3764 <varlistentry>
3765   <term>Notes:</term>
3766   <listitem>
3767    <para>
3768     This is a left-over from the time when <application>Privoxy</application>
3769     didn't support important HTTP/1.1 features well. It is left here for the
3770     unlikely case that you experience HTTP/1.1 related problems with some server
3771     out there. Not all HTTP/1.1 features and requirements are supported yet,
3772     so there is a chance you might need this action.
3773    </para>
3774   </listitem>
3775  </varlistentry>
3776
3777  <varlistentry>
3778   <term>Example usage (section):</term>
3779   <listitem>
3780     <para>
3781      <screen>{+downgrade-http-version}
3782 problem-host.example.com</screen>
3783     </para>
3784   </listitem>
3785  </varlistentry>
3786
3787 </variablelist>
3788 </sect3>
3789
3790 <!--   ~~~~~       New section      ~~~~~     -->
3791 <sect3 renderas="sect4" id="fast-redirects">
3792 <title>fast-redirects</title>
3793
3794 <variablelist>
3795  <varlistentry>
3796   <term>Typical use:</term>
3797   <listitem>
3798    <para>Fool some click-tracking scripts and speed up indirect links.</para>
3799   </listitem>
3800  </varlistentry>
3801
3802  <varlistentry>
3803   <term>Effect:</term>
3804   <listitem>
3805    <para>
3806     Detects redirection URLs and redirects the browser without contacting
3807     the redirection server first.
3808    </para>
3809   </listitem>
3810  </varlistentry>
3811
3812  <varlistentry>
3813   <term>Type:</term>
3814   <!-- boolean, parameterized, Multi-value -->
3815   <listitem>
3816    <para>Parameterized.</para>
3817   </listitem>
3818  </varlistentry>
3819
3820  <varlistentry>
3821   <term>Parameter:</term>
3822   <listitem>
3823    <itemizedlist>
3824     <listitem>
3825      <para>
3826       <quote>simple-check</quote> to just search for the string <quote>http://</quote>
3827       to detect redirection URLs.
3828      </para>
3829     </listitem>
3830     <listitem>
3831      <para>
3832       <quote>check-decoded-url</quote> to decode URLs (if necessary) before searching
3833       for redirection URLs.
3834      </para>
3835     </listitem>
3836    </itemizedlist>
3837   </listitem>
3838  </varlistentry>
3839
3840  <varlistentry>
3841   <term>Notes:</term>
3842   <listitem>
3843    <para>  
3844     Many sites, like yahoo.com, don't just link to other sites. Instead, they
3845     will link to some script on their own servers, giving the destination as a
3846     parameter, which will then redirect you to the final target. URLs
3847     resulting from this scheme typically look like:
3848     <quote>http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/</quote>.
3849   </para>
3850    <para>
3851     Sometimes, there are even multiple consecutive redirects encoded in the
3852     URL. These redirections via scripts make your web browsing more traceable,
3853     since the server from which you follow such a link can see where you go
3854     to. Apart from that, valuable bandwidth and time is wasted, while your
3855     browser asks the server for one redirect after the other. Plus, it feeds
3856     the advertisers.
3857    </para>
3858    <para>
3859     This feature is currently not very smart and is scheduled for improvement.
3860     If it is enabled by default, you will have to create some exceptions to
3861     this action. It can lead to failures in several ways: 
3862    </para>
3863    <para>
3864     Not every URLs with other URLs as parameters is evil.
3865     Some sites offer a real service that requires this information to work.
3866     For example a validation service needs to know, which document to validate.
3867     <literal>fast-redirects</literal> assumes that every URL parameter that
3868     looks like another URL is a redirection target, and will always redirect to
3869     the last one. Most of the time the assumption is correct, but if it isn't,
3870     the user gets redirected anyway.
3871    </para>
3872    <para>
3873     Another failure occurs if the URL contains other parameters after the URL parameter.
3874     The URL:
3875     <quote>http://www.example.org/?redirect=http%3a//www.example.net/&amp;foo=bar</quote>.
3876     contains the redirection URL <quote>http://www.example.net/</quote>,
3877     followed by another parameter. <literal>fast-redirects</literal> doesn't know that
3878     and will cause a redirect to <quote>http://www.example.net/&amp;foo=bar</quote>.
3879     Depending on the target server configuration, the parameter will be silently ignored
3880     or lead to a <quote>page not found</quote> error. You can prevent this problem by
3881     first using the <literal><link linkend="redirect">redirect</link></literal> action
3882     to remove the last part of the URL, but it requires a little effort.
3883    </para>
3884    <para>
3885     To detect a redirection URL, <literal>fast-redirects</literal> only
3886     looks for the string <quote>http://</quote>, either in plain text
3887     (invalid but often used) or encoded as <quote>http%3a//</quote>.
3888     Some sites use their own URL encoding scheme, encrypt the address
3889     of the target server or replace it with a database id. In theses cases
3890     <literal>fast-redirects</literal> is fooled and the request reaches the
3891     redirection server where it probably gets logged.
3892    </para>
3893   </listitem>
3894  </varlistentry>
3895
3896  <varlistentry>
3897   <term>Example usage:</term>
3898   <listitem>
3899     <para>
3900      <screen>
3901  { +fast-redirects{simple-check} }
3902    one.example.com 
3903
3904  { +fast-redirects{check-decoded-url} }
3905    another.example.com/testing</screen>
3906     </para>
3907   </listitem>
3908  </varlistentry>
3909
3910 </variablelist>
3911 </sect3>
3912
3913
3914 <!--   ~~~~~       New section      ~~~~~     -->
3915 <sect3 renderas="sect4" id="filter">
3916 <title>filter</title>
3917
3918 <variablelist>
3919  <varlistentry>
3920   <term>Typical use:</term>
3921   <listitem>
3922    <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), 
3923          do fun text replacements, add personalized effects, etc.</para>
3924   </listitem>
3925  </varlistentry>
3926
3927  <varlistentry>
3928   <term>Effect:</term>
3929   <listitem>
3930    <para>
3931     All instances of text-based type, most notably HTML and JavaScript, to which
3932     this action applies, can be filtered on-the-fly through the specified regular
3933     expression based substitutions. (Note: as of version 3.0.3 plain text documents
3934     are exempted from filtering, because web servers often use the
3935    <literal>text/plain</literal> MIME type for all files whose type they don't know.)
3936    </para>
3937   </listitem>
3938  </varlistentry>
3939
3940  <varlistentry>
3941   <term>Type:</term>
3942   <!-- boolean, parameterized, Multi-value -->
3943   <listitem>
3944    <para>Parameterized.</para>
3945   </listitem>
3946  </varlistentry>
3947  
3948  <varlistentry>
3949   <term>Parameter:</term>
3950   <listitem>
3951    <para>
3952     The name of a content filter, as defined in the <link linkend="filter-file">filter file</link>.
3953     Filters can be defined in one or more  files as defined by the 
3954     <literal><link linkend="filterfile">filterfile</link></literal>
3955     option in the <link linkend="config">config file</link>. 
3956     <filename>default.filter</filename> is the collection of filters 
3957     supplied by the developers. Locally defined filters should go 
3958     in their own file, such as <filename>user.filter</filename>.
3959    </para>
3960    <para>
3961      When used in its negative form,
3962      and without parameters, <emphasis>all</emphasis> filtering is completely disabled.
3963   </para>
3964   </listitem>
3965  </varlistentry>
3966  
3967  <varlistentry>
3968   <term>Notes:</term>
3969   <listitem>
3970    <para>
3971     For your convenience, there are a number of pre-defined filters available 
3972     in the distribution filter file that you can use. See the examples below for
3973     a list.
3974    </para>
3975    <para>
3976     Filtering requires buffering the page content, which may appear to
3977     slow down page rendering since nothing is displayed until all content has
3978     passed the filters. (It does not really take longer, but seems that way
3979     since the page is not incrementally displayed.) This effect will be more
3980     noticeable on slower connections.
3981    </para>
3982    <para>
3983    <quote>Rolling your own</quote>
3984     filters requires a knowledge of 
3985      <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
3986      Expressions</quote></ulink> and 
3987       <ulink url="http://en.wikipedia.org/wiki/Html"><quote>HTML</quote></ulink>.
3988     This is very powerful feature, and potentially very intrusive. 
3989     Filters should be used with caution, and where an equivalent
3990     <quote>action</quote> is not available.
3991    </para>
3992    <para>
3993     The amount of data that can be filtered is limited to the 
3994     <literal><link linkend="buffer-limit">buffer-limit</link></literal>
3995     option in the main <link linkend="config">config file</link>. The 
3996     default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
3997     data, and all pending data, is passed through unfiltered. 
3998    </para>
3999    <para>
4000     Inappropriate MIME types, such as zipped files, are not filtered at all.
4001     (Again, only text-based types except plain text). Encrypted SSL data
4002     (from HTTPS servers) cannot be filtered either, since this would violate
4003     the integrity of the secure transaction. In some situations it might
4004     be necessary to protect certain text, like source code, from filtering
4005     by defining appropriate <literal>-filter</literal> exceptions.
4006    </para>
4007    <para>
4008     Compressed content can't be filtered either, unless &my-app;
4009     is compiled with zlib support (requires at least &my-app; 3.0.7),
4010     in which case &my-app; will decompress the content before filtering
4011     it.
4012    </para>
4013    <para>
4014     If you use a &my-app; version without zlib support, but want filtering to work on
4015     as much documents as possible, even those that would normally be sent compressed,
4016     you must use the <literal><link linkend="prevent-compression">prevent-compression</link></literal>
4017     action in conjunction with <literal>filter</literal>.
4018    </para>
4019    <para>
4020     Content filtering can achieve some of the same effects as the 
4021     <literal><link linkend="block">block</link></literal>
4022     action, i.e. it can be used to block ads and banners. But the mechanism 
4023     works quite differently. One effective use, is to block ad banners 
4024     based on their size (see below), since many of these seem to be somewhat 
4025     standardized.
4026    </para>
4027    <para>
4028     <link linkend="contact">Feedback</link> with suggestions for new or
4029     improved filters is particularly welcome!
4030    </para>
4031    <para>
4032     The below list has only the names and a one-line description of each
4033     predefined filter. There are <link linkend="predefined-filters">more
4034     verbose explanations</link> of what these filters do in the <link
4035     linkend="filter-file">filter file chapter</link>.
4036    </para>
4037   </listitem>
4038  </varlistentry>
4039
4040  <varlistentry>
4041   <term>Example usage (with filters from the distribution <filename>default.filter</filename> file).
4042   See <link linkend="PREDEFINED-FILTERS">the Predefined Filters section</link> for 
4043   more explanation on each:</term>
4044   <listitem>
4045    <para>
4046     <anchor id="filter-js-annoyances">
4047     <screen>+filter{js-annoyances}       # Get rid of particularly annoying JavaScript abuse.</screen>
4048    </para>
4049    <para>
4050     <anchor id="filter-js-events">
4051     <screen>+filter{js-events}           # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
4052    </para>
4053    <para>
4054     <anchor id="filter-html-annoyances">
4055     <screen>+filter{html-annoyances}     # Get rid of particularly annoying HTML abuse.</screen>
4056    </para>
4057    <para>
4058     <anchor id="filter-content-cookies">
4059     <screen>+filter{content-cookies}     # Kill cookies that come in the HTML or JS content.</screen>
4060    </para>
4061    <para>
4062     <anchor id="filter-refresh-tags">
4063     <screen>+filter{refresh-tags}        # Kill automatic refresh tags (for dial-on-demand setups).</screen>
4064    </para>
4065    <para>
4066     <anchor id="filter-unsolicited-popups">
4067     <screen>+filter{unsolicited-popups}  # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</screen>
4068    </para>
4069    <para>
4070     <anchor id="filter-all-popups">
4071     <screen>+filter{all-popups}          # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</screen>
4072    </para>
4073    <para>
4074     <anchor id="filter-img-reorder">
4075     <screen>+filter{img-reorder}         # Reorder attributes in &lt;img&gt; tags to make the banners-by-* filters more effective.</screen>
4076    </para>
4077    <para>
4078     <anchor id="filter-banners-by-size">
4079     <screen>+filter{banners-by-size}     # Kill banners by size.</screen>
4080    </para>
4081    <para>
4082     <anchor id="filter-banners-by-link">
4083     <screen>+filter{banners-by-link}     # Kill banners by their links to known clicktrackers.</screen>
4084    </para>
4085    <para>
4086     <anchor id="filter-webbugs">
4087     <screen>+filter{webbugs}             # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
4088    </para>
4089    <para>
4090     <anchor id="filter-tiny-textforms">
4091     <screen>+filter{tiny-textforms}      # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
4092    </para>
4093    <para>
4094     <anchor id="filter-jumping-windows">
4095     <screen>+filter{jumping-windows}     # Prevent windows from resizing and moving themselves.</screen>
4096    </para>
4097    <para>
4098     <anchor id="filter-frameset-borders">
4099     <screen>+filter{frameset-borders}    # Give frames a border and make them resizable.</screen>
4100    </para>
4101    <para>
4102     <anchor id="filter-demoronizer">
4103     <screen>+filter{demoronizer}         # Fix MS's non-standard use of standard charsets.</screen>
4104    </para>
4105    <para>
4106     <anchor id="filter-shockwave-flash">
4107     <screen>+filter{shockwave-flash}     # Kill embedded Shockwave Flash objects.</screen>
4108    </para>
4109    <para>
4110     <anchor id="filter-quicktime-kioskmode">
4111     <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
4112    </para>
4113    <para>
4114     <anchor id="filter-fun">
4115     <screen>+filter{fun}                 # Text replacements for subversive browsing fun!</screen>
4116    </para>
4117    <para>
4118     <anchor id="filter-crude-parental">
4119     <screen>+filter{crude-parental}      # Crude parental filtering. Note that this filter doesn't work reliably.</screen>
4120    </para>
4121    <para>
4122     <anchor id="filter-ie-exploits">
4123     <screen>+filter{ie-exploits}         # Disable some known Internet Explorer bug exploits.</screen>
4124    </para>
4125    <para>
4126     <anchor id="filter-site-specifics">
4127     <screen>+filter{site-specifics}      # Cure for site-specific problems. Don't apply generally!</screen>
4128    </para>
4129    <para>
4130     <anchor id="filter-no-ping">
4131     <screen>+filter{no-ping}             # Removes non-standard ping attributes in &lt;a&gt; and &lt;area&gt; tags.</screen>
4132    </para>
4133    <para>
4134     <anchor id="filter-google">
4135     <screen>+filter{google}              # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
4136    </para>
4137    <para>
4138     <anchor id="filter-yahoo">
4139     <screen>+filter{yahoo}               # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
4140    </para>
4141    <para>
4142     <anchor id="filter-msn">
4143     <screen>+filter{msn}                 # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
4144    </para>
4145    <para>
4146     <anchor id="filter-blogspot">
4147     <screen>+filter{blogspot}            # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
4148    </para>
4149   </listitem>
4150  </varlistentry>
4151 </variablelist>
4152 </sect3>
4153
4154
4155 <!--   ~~~~~       New section      ~~~~~     -->
4156 <sect3 renderas="sect4" id="force-text-mode">
4157 <title>force-text-mode</title>
4158 <!--
4159 new action
4160 -->
4161 <variablelist>
4162  <varlistentry>
4163   <term>Typical use:</term>
4164   <listitem>
4165    <para>Force <application>Privoxy</application> to treat a document as if it was in some kind of <emphasis>text</emphasis> format.   </para>
4166   </listitem>
4167  </varlistentry>
4168
4169  <varlistentry>
4170   <term>Effect:</term>
4171   <listitem>
4172    <para>
4173     Declares a document as text, even if the <quote>Content-Type:</quote> isn't detected as such.
4174    </para>    
4175   </listitem>
4176  </varlistentry>
4177
4178  <varlistentry>
4179   <term>Type:</term>
4180   <!-- Boolean, Parameterized, Multi-value -->
4181   <listitem>
4182    <para>Boolean.</para>
4183   </listitem>
4184  </varlistentry>
4185
4186  <varlistentry>
4187   <term>Parameter:</term>
4188   <listitem>
4189    <para>
4190     N/A
4191    </para>
4192   </listitem>
4193  </varlistentry>
4194
4195  <varlistentry>
4196   <term>Notes:</term>
4197   <listitem>
4198    <para>
4199     As explained <literal><link linkend="filter">above</link></literal>,
4200     <application>Privoxy</application> tries to only filter files that are
4201     in some kind of text format. The same restrictions apply to
4202     <literal><link linkend="content-type-overwrite">content-type-overwrite</link></literal>.
4203     <literal>force-text-mode</literal> declares a document as text,
4204     without looking at the <quote>Content-Type:</quote> first.
4205    </para>
4206    <warning> 
4207     <para>
4208      Think twice before activating this action. Filtering binary data
4209      with regular expressions can cause file damage.
4210     </para>
4211    </warning>
4212   </listitem>
4213  </varlistentry>
4214  
4215  <varlistentry>
4216   <term>Example usage:</term>
4217   <listitem>
4218    <para>
4219      <screen>
4220 +force-text-mode
4221      </screen>
4222    </para>
4223   </listitem>
4224  </varlistentry>
4225 </variablelist>
4226 </sect3>
4227
4228
4229 <!--   ~~~~~       New section      ~~~~~     -->
4230 <sect3 renderas="sect4" id="forward-override">
4231 <title>forward-override</title>
4232 <!--
4233 new action
4234 -->
4235 <variablelist>
4236  <varlistentry>
4237   <term>Typical use:</term>
4238   <listitem>
4239    <para>Change the forwarding settings based on User-Agent or request origin</para>
4240   </listitem>
4241  </varlistentry>
4242
4243  <varlistentry>
4244   <term>Effect:</term>
4245   <listitem>
4246    <para>
4247     Overrules the forward directives in the configuration file.
4248    </para>    
4249   </listitem>
4250  </varlistentry>
4251
4252  <varlistentry>
4253   <term>Type:</term>
4254   <!-- Boolean, Parameterized, Multi-value -->
4255   <listitem>
4256    <para>Multi-value.</para>
4257   </listitem>
4258  </varlistentry>
4259
4260  <varlistentry>
4261   <term>Parameter:</term>
4262   <listitem>
4263    <itemizedlist>
4264     <listitem>
4265      <para><quote>forward .</quote> to use a direct connection without any additional proxies.</para>
4266     </listitem>
4267     <listitem>
4268      <para>
4269       <quote>forward 127.0.0.1:8123</quote> to use the HTTP proxy listening at 127.0.0.1 port 8123.
4270      </para>
4271     </listitem>
4272     <listitem>
4273      <para>
4274       <quote>forward-socks4a 127.0.0.1:9050 .</quote> to use the socks4a proxy listening at
4275       127.0.0.1 port 9050. Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote>
4276       to use a socks4 connection  (with local DNS resolution) instead, use <quote>forward-socks5</quote>
4277       for socks5 connections (with remote DNS resolution).
4278      </para>
4279     </listitem>
4280     <listitem>
4281      <para>
4282       <quote>forward-socks4a 127.0.0.1:9050 proxy.example.org:8000</quote> to use the socks4a proxy
4283       listening at 127.0.0.1 port 9050 to reach the HTTP proxy listening at proxy.example.org port 8000.
4284       Replace <quote>forward-socks4a</quote> with <quote>forward-socks4</quote> to use a socks4 connection
4285       (with local DNS resolution) instead, use <quote>forward-socks5</quote>
4286       for socks5 connections (with remote DNS resolution).
4287      </para>
4288     </listitem>
4289    </itemizedlist>
4290   </listitem>
4291  </varlistentry>
4292
4293  <varlistentry>
4294   <term>Notes:</term>
4295   <listitem>
4296    <para>
4297     This action takes parameters similar to the
4298     <link linkend="forwarding">forward</link> directives in the configuration
4299     file, but without the URL pattern. It can be used as replacement, but normally it's only
4300     used in cases where matching based on the request URL isn't sufficient.
4301    </para>
4302    <warning> 
4303     <para>
4304      Please read the description for the <link linkend="forwarding">forward</link> directives before
4305      using this action. Forwarding to the wrong people will reduce your privacy and increase the
4306      chances of man-in-the-middle attacks.
4307     </para>
4308     <para>
4309      If the ports are missing or invalid, default values will be used. This might change
4310      in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
4311      to exit.
4312     </para>
4313     <para>
4314      Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
4315      to verify that your forward settings do what you thought the do.
4316     </para>
4317    </warning>
4318   </listitem>
4319  </varlistentry>
4320  
4321  <varlistentry>
4322   <term>Example usage:</term>
4323   <listitem>
4324    <para>
4325      <screen>
4326 # Always use direct connections for requests previously tagged as
4327 # <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
4328 # resuming downloads continues to work.
4329 # This way you can continue to use Tor for your normal browsing,
4330 # without overloading the Tor network with your FreeBSD ports updates
4331 # or downloads of bigger files like ISOs.
4332 # Note that HTTP headers are easy to fake and therefore their
4333 # values are as (un)trustworthy as your clients and users.
4334 {+forward-override{forward .} \
4335  -hide-if-modified-since      \
4336  -overwrite-last-modified     \
4337 }
4338 TAG:^User-Agent: fetch libfetch/2\.0$
4339      </screen>
4340    </para>
4341   </listitem>
4342  </varlistentry>
4343 </variablelist>
4344 </sect3>
4345
4346
4347 <!--   ~~~~~       New section      ~~~~~     -->
4348 <sect3 renderas="sect4" id="handle-as-empty-document">
4349 <title>handle-as-empty-document</title>
4350 <!--
4351 new action
4352 -->
4353 <variablelist>
4354  <varlistentry>
4355   <term>Typical use:</term>
4356   <listitem>
4357    <para>Mark URLs that should be replaced by empty documents <emphasis>if they get blocked</emphasis></para>
4358   </listitem>
4359  </varlistentry>
4360
4361  <varlistentry>
4362   <term>Effect:</term>
4363   <listitem>
4364    <para>
4365     This action alone doesn't do anything noticeable. It just marks URLs.
4366     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4367     the presence or absence of this mark decides whether an HTML <quote>BLOCKED</quote>
4368     page, or an empty document will be sent to the client as a substitute for the blocked content.
4369     The <emphasis>empty</emphasis> document isn't literally empty, but actually contains a single space.
4370    </para>
4371   </listitem>
4372  </varlistentry>
4373
4374  <varlistentry>
4375   <term>Type:</term>
4376   <!-- Boolean, Parameterized, Multi-value -->
4377   <listitem>
4378    <para>Boolean.</para>
4379   </listitem>
4380  </varlistentry>
4381
4382  <varlistentry>
4383   <term>Parameter:</term>
4384   <listitem>
4385    <para>
4386     N/A
4387    </para>
4388   </listitem>
4389  </varlistentry>
4390
4391  <varlistentry>
4392   <term>Notes:</term>
4393   <listitem>
4394    <para>
4395     Some browsers complain about syntax errors if JavaScript documents
4396     are blocked with <application>Privoxy's</application>
4397     default HTML page; this option can be used to silence them.
4398     And of course this action can also be used to eliminate the &my-app;
4399     BLOCKED message in frames.
4400    </para>
4401    <para>
4402     The content type for the empty document can be specified with
4403     <literal><link linkend="content-type-overwrite">content-type-overwrite{}</link></literal>,
4404     but usually this isn't necessary.
4405    </para>
4406   </listitem>
4407  </varlistentry>
4408
4409  <varlistentry>
4410   <term>Example usage:</term>
4411   <listitem>
4412    <para>
4413      <screen># Block all documents on example.org that end with ".js",
4414 # but send an empty document instead of the usual HTML message. 
4415 {+block{Blocked JavaScript} +handle-as-empty-document}
4416 example.org/.*\.js$
4417      </screen>
4418    </para>
4419   </listitem>
4420  </varlistentry>
4421 </variablelist>
4422 </sect3>
4423
4424
4425 <!--   ~~~~~       New section      ~~~~~     -->
4426 <sect3 renderas="sect4" id="handle-as-image">
4427 <title>handle-as-image</title>
4428
4429 <variablelist>
4430  <varlistentry>
4431   <term>Typical use:</term>
4432   <listitem>
4433    <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they do get blocked</emphasis>, rather than HTML pages)</para>
4434   </listitem>
4435  </varlistentry>
4436
4437  <varlistentry>
4438   <term>Effect:</term>
4439   <listitem>
4440    <para>
4441     This action alone doesn't do anything noticeable. It just marks URLs as images.
4442     If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
4443     the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
4444     page, or a replacement image (as determined by the <literal><link
4445     linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
4446     client as a substitute for the blocked content.
4447    </para>
4448   </listitem>
4449  </varlistentry>
4450
4451  <varlistentry>
4452   <term>Type:</term>
4453   <!-- Boolean, Parameterized, Multi-value -->
4454   <listitem>
4455    <para>Boolean.</para>
4456   </listitem>
4457  </varlistentry>
4458
4459  <varlistentry>
4460   <term>Parameter:</term>
4461   <listitem>
4462    <para>
4463     N/A
4464    </para>
4465   </listitem>
4466  </varlistentry>
4467  
4468  <varlistentry>
4469   <term>Notes:</term>
4470   <listitem>
4471    <para>
4472     The below generic example section is actually part of <filename>default.action</filename>.
4473     It marks all URLs with well-known image file name extensions as images and should
4474     be left intact. 
4475    </para>
4476    <para>
4477     Users will probably only want to use the handle-as-image action in conjunction with
4478     <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
4479     reflect the file type, like in the second example section.
4480    </para>
4481    <para>
4482     Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
4483     frames require an HTML page to be sent, or they won't display properly.
4484     Forcing <literal>handle-as-image</literal> in this situation will not replace the
4485     ad frame with an image, but lead to error messages.
4486    </para>
4487   </listitem>
4488  </varlistentry>
4489
4490  <varlistentry>
4491   <term>Example usage (sections):</term>
4492   <listitem>
4493    <para>
4494      <screen># Generic image extensions:
4495 #
4496 {+handle-as-image}
4497 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
4498
4499 # These don't look like images, but they're banners and should be
4500 # blocked as images:
4501 #
4502 {+block{Nasty banners.} +handle-as-image}
4503 nasty-banner-server.example.com/junk.cgi\?output=trash
4504 </screen>
4505    </para>
4506   </listitem>
4507  </varlistentry>
4508 </variablelist>
4509 </sect3>
4510
4511
4512 <!--   ~~~~~       New section      ~~~~~     -->
4513 <sect3 renderas="sect4" id="hide-accept-language">
4514 <title>hide-accept-language</title>
4515 <!--
4516 new action
4517 -->
4518 <variablelist>
4519  <varlistentry>
4520   <term>Typical use:</term>
4521   <listitem>
4522    <para>Pretend to use different language settings.</para>
4523   </listitem>
4524  </varlistentry>
4525
4526  <varlistentry>
4527   <term>Effect:</term>
4528   <listitem>
4529    <para>
4530     Deletes or replaces the <quote>Accept-Language:</quote> HTTP header in client requests.
4531    </para>
4532   </listitem>
4533  </varlistentry>
4534
4535  <varlistentry>
4536   <term>Type:</term>
4537   <!-- Boolean, Parameterized, Multi-value -->
4538   <listitem>
4539    <para>Parameterized.</para>
4540   </listitem>
4541  </varlistentry>
4542
4543  <varlistentry>
4544   <term>Parameter:</term>
4545   <listitem>
4546    <para>
4547     Keyword: <quote>block</quote>, or any user defined value.
4548    </para>    
4549   </listitem>
4550  </varlistentry>
4551  
4552  <varlistentry>
4553   <term>Notes:</term>
4554   <listitem>
4555    <para>
4556     Faking the browser's language settings can be useful to make a
4557     foreign User-Agent set with
4558     <literal><link linkend="hide-user-agent">hide-user-agent</link></literal>
4559     more believable.
4560    </para>
4561    <para>
4562     However some sites with content in different languages check the
4563     <quote>Accept-Language:</quote> to decide which one to take by default.
4564     Sometimes it isn't possible to later switch to another language without
4565     changing the <quote>Accept-Language:</quote> header first.
4566    </para>
4567    <para>
4568     Therefore it's a good idea to either only change the
4569     <quote>Accept-Language:</quote> header to languages you understand,
4570     or to languages that aren't wide spread.
4571    </para>
4572    <para>
4573     Before setting the <quote>Accept-Language:</quote> header
4574     to a rare language, you should consider that it helps to
4575     make your requests unique and thus easier to trace.
4576     If you don't plan to change this header frequently,
4577     you should stick to a common language. 
4578    </para>
4579   </listitem>
4580  </varlistentry>
4581
4582  <varlistentry>
4583   <term>Example usage (section):</term>
4584   <listitem>
4585     <para>
4586      <screen># Pretend to use Canadian language settings.
4587 {+hide-accept-language{en-ca} \
4588 +hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
4589 }
4590 /   </screen>
4591    </para>
4592   </listitem>
4593  </varlistentry>
4594 </variablelist>
4595 </sect3>
4596
4597
4598 <!--   ~~~~~       New section      ~~~~~     -->
4599 <sect3 renderas="sect4" id="hide-content-disposition">
4600 <title>hide-content-disposition</title>
4601 <!--
4602 new action
4603 -->
4604 <variablelist>
4605  <varlistentry>
4606   <term>Typical use:</term>
4607   <listitem>
4608    <para>Prevent download menus for content you prefer to view inside the browser.</para>
4609   </listitem>
4610  </varlistentry>
4611
4612  <varlistentry>
4613   <term>Effect:</term>
4614   <listitem>
4615    <para>
4616     Deletes or replaces the <quote>Content-Disposition:</quote> HTTP header set by some servers.
4617    </para>
4618   </listitem>
4619  </varlistentry>
4620
4621  <varlistentry>
4622   <term>Type:</term>
4623   <!-- Boolean, Parameterized, Multi-value -->
4624   <listitem>
4625    <para>Parameterized.</para>
4626   </listitem>
4627  </varlistentry>
4628
4629  <varlistentry>
4630   <term>Parameter:</term>
4631   <listitem>
4632    <para>
4633     Keyword: <quote>block</quote>, or any user defined value.
4634    </para>    
4635   </listitem>
4636  </varlistentry>
4637  
4638  <varlistentry>
4639   <term>Notes:</term>
4640   <listitem>
4641    <para>
4642     Some servers set the <quote>Content-Disposition:</quote> HTTP header for
4643     documents they assume you want to save locally before viewing them.
4644     The <quote>Content-Disposition:</quote> header contains the file name
4645     the browser is supposed to use by default.
4646    </para>
4647    <para>
4648     In most browsers that understand this header, it makes it impossible to
4649     <emphasis>just view</emphasis> the document, without downloading it first,
4650     even if it's just a simple text file or an image.
4651    </para>
4652    <para>
4653     Removing the <quote>Content-Disposition:</quote> header helps
4654     to prevent this annoyance, but some browsers additionally check the
4655     <quote>Content-Type:</quote> header, before they decide if they can
4656     display a document without saving it first. In these cases, you have
4657     to change this header as well, before the browser stops displaying
4658     download menus.
4659    </para>
4660    <para>
4661     It is also possible to change the server's file name suggestion
4662     to another one, but in most cases it isn't worth the time to set
4663     it up.
4664    </para>
4665    <para>
4666     This action will probably be removed in the future,
4667     use server-header filters instead.
4668    </para>
4669   </listitem>
4670  </varlistentry>
4671
4672  <varlistentry>
4673   <term>Example usage:</term>
4674   <listitem>
4675     <para>
4676      <screen># Disarm the download link in Sourceforge's patch tracker
4677 { -filter \
4678  +content-type-overwrite{text/plain}\
4679  +hide-content-disposition{block} }
4680  .sourceforge.net/tracker/download\.php</screen>
4681    </para>
4682   </listitem>
4683  </varlistentry>
4684 </variablelist>
4685 </sect3>
4686
4687
4688 <!--   ~~~~~       New section      ~~~~~     -->
4689 <sect3 renderas="sect4" id="hide-if-modified-since">
4690 <title>hide-if-modified-since</title>
4691 <!--
4692 new action
4693 -->
4694 <variablelist>
4695  <varlistentry>
4696   <term>Typical use:</term>
4697   <listitem>
4698    <para>Prevent yet another way to track the user's steps between sessions.</para>
4699   </listitem>
4700  </varlistentry>
4701
4702  <varlistentry>
4703   <term>Effect:</term>
4704   <listitem>
4705    <para>
4706     Deletes the <quote>If-Modified-Since:</quote> HTTP client header or modifies its value. 
4707    </para>
4708   </listitem>
4709  </varlistentry>
4710
4711  <varlistentry>
4712   <term>Type:</term>
4713   <!-- Boolean, Parameterized, Multi-value -->
4714   <listitem>
4715    <para>Parameterized.</para>
4716   </listitem>
4717  </varlistentry>
4718
4719  <varlistentry>
4720   <term>Parameter:</term>
4721   <listitem>
4722    <para>
4723     Keyword: <quote>block</quote>, or a user defined value that specifies a range of hours.
4724    </para>    
4725   </listitem>
4726  </varlistentry>
4727  
4728  <varlistentry>
4729   <term>Notes:</term>
4730   <listitem>
4731    <para>
4732     Removing this header is useful for filter testing, where you want to force a real
4733     reload instead of getting status code <quote>304</quote>, which would cause the
4734     browser to use a cached copy of the page.
4735    </para>
4736    <para>
4737     Instead of removing the header, <literal>hide-if-modified-since</literal> can
4738     also add or subtract a random amount of time to/from the header's value.
4739     You specify a range of minutes where the random factor should be chosen from and
4740     <application>Privoxy</application> does the rest. A negative value means
4741     subtracting, a positive value adding.
4742    </para>
4743    <para>
4744     Randomizing the value of the <quote>If-Modified-Since:</quote> makes
4745     it less likely that the server can use the time as a cookie replacement,
4746     but you will run into caching problems if the random range is too high.
4747    </para>
4748    <para>
4749     It is a good idea to only use a small negative value and let
4750     <literal><link linkend="overwrite-last-modified">overwrite-last-modified</link></literal>
4751     handle the greater changes.
4752    </para>
4753    <para>
4754     It is also recommended to use this action together with
4755     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>,
4756     otherwise it's more or less pointless.
4757    </para>
4758   </listitem>
4759  </varlistentry>
4760
4761  <varlistentry>
4762   <term>Example usage (section):</term>
4763   <listitem>
4764     <para>
4765      <screen># Let the browser revalidate but make tracking based on the time less likely.
4766 {+hide-if-modified-since{-60} \
4767  +overwrite-last-modified{randomize} \
4768  +crunch-if-none-match}
4769 /</screen>
4770    </para>
4771   </listitem>
4772  </varlistentry>
4773 </variablelist>
4774 </sect3>
4775
4776
4777 <!--   ~~~~~       New section      ~~~~~     -->
4778 <sect3 renderas="sect4" id="hide-from-header">
4779 <title>hide-from-header</title>
4780
4781 <variablelist>
4782  <varlistentry>
4783   <term>Typical use:</term>
4784   <listitem>
4785    <para>Keep your (old and ill) browser from telling web servers your email address</para>
4786   </listitem>
4787  </varlistentry>
4788
4789  <varlistentry>
4790   <term>Effect:</term>
4791   <listitem>
4792    <para>
4793     Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
4794     specified string.
4795    </para>
4796   </listitem>
4797  </varlistentry>
4798
4799  <varlistentry>
4800   <term>Type:</term>
4801   <!-- Boolean, Parameterized, Multi-value -->
4802   <listitem>
4803    <para>Parameterized.</para>
4804   </listitem>
4805  </varlistentry>
4806
4807  <varlistentry>
4808   <term>Parameter:</term>
4809   <listitem>
4810    <para>
4811     Keyword: <quote>block</quote>, or any user defined value.
4812    </para>
4813   </listitem>
4814  </varlistentry>
4815  
4816  <varlistentry>
4817   <term>Notes:</term>
4818   <listitem>
4819    <para>
4820     The keyword <quote>block</quote> will completely remove the header 
4821     (not to be confused with the <literal><link linkend="block">block</link></literal>
4822     action).
4823    </para>
4824    <para>
4825     Alternately, you can specify any value you prefer to be sent to the web
4826     server. If you do, it is a matter of fairness not to use any address that
4827     is actually used by a real person.
4828    </para>
4829    <para>
4830     This action is rarely needed, as modern web browsers don't send
4831     <quote>From:</quote> headers anymore.
4832    </para>
4833   </listitem>
4834  </varlistentry>
4835
4836  <varlistentry>
4837   <term>Example usage:</term>
4838   <listitem>
4839    <para>
4840     <screen>+hide-from-header{block}</screen> or
4841     <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
4842    </para>
4843   </listitem>
4844  </varlistentry>
4845 </variablelist>
4846 </sect3>
4847
4848
4849 <!--   ~~~~~       New section      ~~~~~     -->
4850 <sect3 renderas="sect4" id="hide-referrer">
4851 <title>hide-referrer</title>
4852 <anchor id="hide-referer">
4853 <variablelist>
4854  <varlistentry>
4855   <term>Typical use:</term>
4856   <listitem>
4857    <para>Conceal which link you followed to get to a particular site</para>
4858   </listitem>
4859  </varlistentry>
4860
4861  <varlistentry>
4862   <term>Effect:</term>
4863   <listitem>
4864    <para>
4865     Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
4866     or replaces it with a forged one.
4867    </para>
4868   </listitem>
4869  </varlistentry>
4870
4871  <varlistentry>
4872   <term>Type:</term>
4873   <!-- Boolean, Parameterized, Multi-value -->
4874   <listitem>
4875    <para>Parameterized.</para>
4876   </listitem>
4877  </varlistentry>
4878
4879  <varlistentry>
4880   <term>Parameter:</term>
4881   <listitem>
4882    <itemizedlist>
4883     <listitem>
4884      <para><quote>conditional-block</quote> to delete the header completely if the host has changed.</para>
4885     </listitem>
4886     <listitem>
4887      <para><quote>conditional-forge</quote> to forge the header if the host has changed.</para>
4888     </listitem>
4889     <listitem>
4890      <para><quote>block</quote> to delete the header unconditionally.</para>
4891     </listitem>
4892     <listitem>
4893      <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
4894     </listitem>
4895     <listitem>
4896      <para>Any other string to set a user defined referrer.</para>
4897     </listitem>
4898    </itemizedlist>
4899   </listitem>
4900  </varlistentry>
4901  
4902  <varlistentry>
4903   <term>Notes:</term>
4904   <listitem>
4905    <para>
4906     <literal>conditional-block</literal> is the only parameter,
4907     that isn't easily detected in the server's log file. If it blocks the
4908     referrer, the request will look like the visitor used a bookmark or
4909     typed in the address directly.
4910    </para>
4911    <para>
4912     Leaving the referrer unmodified for requests on the same host
4913     allows the server owner to see the visitor's <quote>click path</quote>,
4914     but in most cases she could also get that information by comparing
4915     other parts of the log file: for example the User-Agent if it isn't
4916     a very common one, or the user's IP address if it doesn't change between
4917     different requests.
4918    </para>
4919    <para>
4920     Always blocking the referrer, or using a custom one, can lead to
4921     failures on servers that check the referrer before they answer any
4922     requests, in an attempt to prevent their content from being
4923     embedded or linked to elsewhere.
4924    </para>
4925    <para>
4926     Both <literal>conditional-block</literal> and <literal>forge</literal>
4927     will work with referrer checks, as long as content and valid referring page
4928     are on the same host. Most of the time that's the case.
4929    </para>
4930    <para>  
4931     <literal>hide-referer</literal> is an alternate spelling of
4932     <literal>hide-referrer</literal> and the two can be can be freely
4933     substituted with each other. (<quote>referrer</quote> is the
4934     correct English spelling, however the HTTP specification has a bug - it
4935     requires it to be spelled as <quote>referer</quote>.) 
4936    </para>
4937   </listitem>
4938  </varlistentry>
4939
4940  <varlistentry>
4941   <term>Example usage:</term>
4942   <listitem>
4943    <para>
4944      <screen>+hide-referrer{forge}</screen> or
4945      <screen>+hide-referrer{http://www.yahoo.com/}</screen>
4946    </para>
4947   </listitem>
4948  </varlistentry>
4949 </variablelist>
4950 </sect3>
4951
4952
4953 <!--   ~~~~~       New section      ~~~~~     -->
4954 <sect3 renderas="sect4" id="hide-user-agent">
4955 <title>hide-user-agent</title>
4956
4957 <variablelist>
4958  <varlistentry>
4959   <term>Typical use:</term>
4960   <listitem>
4961    <para>Try to conceal your type of browser and client operating system</para>
4962   </listitem>
4963  </varlistentry>
4964
4965  <varlistentry>
4966   <term>Effect:</term>
4967   <listitem>
4968    <para>
4969     Replaces the value of the <quote>User-Agent:</quote> HTTP header
4970     in client requests with the specified value.
4971    </para>
4972   </listitem>
4973  </varlistentry>
4974
4975  <varlistentry>
4976   <term>Type:</term>
4977   <!-- Boolean, Parameterized, Multi-value -->
4978   <listitem>
4979    <para>Parameterized.</para>
4980   </listitem>
4981  </varlistentry>
4982
4983  <varlistentry>
4984   <term>Parameter:</term>
4985   <listitem>
4986    <para>
4987     Any user-defined string.
4988    </para>
4989   </listitem>
4990  </varlistentry>
4991  
4992  <varlistentry>
4993   <term>Notes:</term>
4994   <listitem>
4995    <warning> 
4996     <para>
4997      This can lead to problems on web sites that depend on looking at this header in
4998      order to customize their content for different browsers (which, by the
4999      way, is <emphasis>NOT</emphasis> the right thing to do: good web sites
5000      work browser-independently). 
5001     </para>
5002    </warning>
5003    <para>
5004     Using this action in multi-user setups or wherever different types of
5005     browsers will access the same <application>Privoxy</application> is
5006     <emphasis>not recommended</emphasis>. In single-user, single-browser
5007     setups, you might use it to delete your OS version information from
5008     the headers, because it is an invitation to exploit known bugs for your
5009     OS. It is also occasionally useful to forge this in order to access 
5010     sites that won't let you in otherwise (though there may be a good 
5011     reason in some cases). Example of this: some MSN sites will not 
5012     let <application>Mozilla</application> enter, yet forging to a 
5013     <application>Netscape 6.1</application> user-agent works just fine.
5014     (Must be just a silly MS goof, I'm sure :-).
5015    </para>
5016    <para>
5017      More information on known user-agent strings can be found at 
5018      <ulink url="http://www.user-agents.org/">http://www.user-agents.org/</ulink>
5019      and 
5020      <ulink url="http://en.wikipedia.org/wiki/User_agent">http://en.wikipedia.org/wiki/User_agent</ulink>.
5021    </para>
5022    </listitem>
5023  </varlistentry>
5024
5025  <varlistentry>
5026   <term>Example usage:</term>
5027   <listitem>
5028    <para>
5029      <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
5030    </para>
5031   </listitem>
5032  </varlistentry>
5033 </variablelist>
5034 </sect3>
5035
5036
5037 <!--   ~~~~~       New section      ~~~~~     -->
5038 <sect3 renderas="sect4" id="limit-connect">
5039 <title>limit-connect</title>
5040
5041 <variablelist>
5042  <varlistentry>
5043   <term>Typical use:</term>
5044   <listitem>
5045    <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay or disable SSL for untrusted sites</para>
5046   </listitem>
5047  </varlistentry>
5048
5049  <varlistentry>
5050   <term>Effect:</term>
5051   <listitem>
5052    <para>
5053     Specifies to which ports HTTP CONNECT requests are allowable.
5054    </para>
5055   </listitem>
5056  </varlistentry>
5057
5058  <varlistentry>
5059   <term>Type:</term>
5060   <!-- Boolean, Parameterized, Multi-value -->
5061   <listitem>
5062    <para>Parameterized.</para>
5063   </listitem>
5064  </varlistentry>
5065
5066  <varlistentry>
5067   <term>Parameter:</term>
5068   <listitem>
5069    <para>
5070     A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
5071     defaulting to 0 and the maximum to 65K).
5072    </para>
5073   </listitem>
5074  </varlistentry>
5075  
5076  <varlistentry>
5077   <term>Notes:</term>
5078   <listitem>
5079    <para>
5080     By default, i.e. if no <literal>limit-connect</literal> action applies,
5081     <application>Privoxy</application> allows HTTP CONNECT requests to all
5082     ports. Use <literal>limit-connect</literal> if fine-grained control
5083     is desired for some or all destinations.
5084    </para>
5085    <para>
5086     The CONNECT methods exists in HTTP to allow access to secure websites
5087     (<quote>https://</quote> URLs) through proxies. It works very simply:
5088     the proxy connects to the server on the specified port, and then
5089     short-circuits its connections to the client and to the remote server.
5090     This means CONNECT-enabled proxies can be used as TCP relays very easily.
5091   </para>
5092   <para>
5093    <application>Privoxy</application> relays HTTPS traffic without seeing
5094    the decoded content. Websites can leverage this limitation to circumvent &my-app;'s
5095    filters. By specifying an invalid port range you can disable HTTPS entirely.
5096   </para>
5097   </listitem>
5098  </varlistentry>
5099
5100  <varlistentry>
5101   <term>Example usages:</term>
5102   <listitem>
5103    <!-- I had trouble getting the spacing to look right in my browser -->
5104    <!-- I probably have the wrong font setup, bollocks. -->
5105    <!-- Apparently the emphasis tag uses a proportional font no matter what -->
5106     <para>
5107      <screen>+limit-connect{443}                   # Port 443 is OK.
5108 +limit-connect{80,443}                # Ports 80 and 443 are OK.
5109 +limit-connect{-3, 7, 20-100, 500-}   # Ports less than 3, 7, 20 to 100 and above 500 are OK.
5110 +limit-connect{-}                     # All ports are OK
5111 +limit-connect{,}                     # No HTTPS/SSL traffic is allowed</screen>
5112    </para>
5113   </listitem>
5114  </varlistentry>
5115 </variablelist>
5116 </sect3>
5117
5118 <!--   ~~~~~       New section      ~~~~~     -->
5119 <sect3 renderas="sect4" id="prevent-compression">
5120 <title>prevent-compression</title>
5121
5122 <variablelist>
5123  <varlistentry>
5124   <term>Typical use:</term>
5125   <listitem>
5126    <para>
5127     Ensure that servers send the content uncompressed, so it can be
5128     passed through <literal><link linkend="filter">filter</link></literal>s.
5129    </para>
5130   </listitem>
5131  </varlistentry>
5132
5133  <varlistentry>
5134   <term>Effect:</term>
5135   <listitem>
5136    <para>
5137     Removes the Accept-Encoding header which can be used to ask for compressed transfer.
5138    </para>
5139   </listitem>
5140  </varlistentry>
5141
5142  <varlistentry>
5143   <term>Type:</term>
5144   <!-- Boolean, Parameterized, Multi-value -->
5145   <listitem>
5146    <para>Boolean.</para>
5147   </listitem>
5148  </varlistentry>
5149
5150  <varlistentry>
5151   <term>Parameter:</term>
5152   <listitem>
5153    <para>
5154     N/A
5155    </para>
5156   </listitem>
5157  </varlistentry>
5158  
5159  <varlistentry>
5160   <term>Notes:</term>
5161   <listitem>
5162    <para>
5163     More and more websites send their content compressed by default, which
5164     is generally a good idea and saves bandwidth. But the <literal><link
5165     linkend="filter">filter</link></literal> and
5166     <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
5167     actions need access to the uncompressed data.
5168    </para>
5169    <para>
5170     When compiled with zlib support (available since &my-app; 3.0.7), content that should be
5171     filtered is decompressed on-the-fly and you don't have to worry about this action.
5172     If you are using an older &my-app; version, or one that hasn't been compiled with zlib
5173     support, this action can be used to convince the server to send the content uncompressed.
5174    </para>
5175    <para>
5176     Most text-based instances compress very well, the size is seldom decreased by less than 50%,
5177     for markup-heavy instances like news feeds saving more than 90% of the original size isn't
5178     unusual. 
5179    </para>
5180    <para>
5181     Not using compression will therefore slow down the transfer, and you should only
5182     enable this action if you really need it. As of &my-app; 3.0.7 it's disabled in all
5183     predefined action settings.
5184    </para>
5185    <para>
5186     Note that some (rare) ill-configured sites don't handle requests for uncompressed
5187     documents correctly. Broken PHP applications tend to send an empty document body,
5188     some IIS versions only send the beginning of the content. If you enable
5189     <literal>prevent-compression</literal> per default, you might want to add
5190     exceptions for those sites. See the example for how to do that.
5191    </para>
5192   </listitem>
5193  </varlistentry>
5194
5195  <varlistentry>
5196   <term>Example usage (sections):</term>
5197   <listitem>
5198    <para>
5199     <screen>
5200 # Selectively turn off compression, and enable a filter
5201 #
5202 { +filter{tiny-textforms} +prevent-compression }
5203 # Match only these sites
5204  .google.
5205  sourceforge.net
5206  sf.net
5207
5208 # Or instead, we could set a universal default:
5209 #
5210 { +prevent-compression }
5211  / # Match all sites
5212
5213 # Then maybe make exceptions for broken sites:
5214 #
5215 { -prevent-compression }
5216 .compusa.com/</screen>
5217    </para>
5218   </listitem>
5219  </varlistentry>
5220
5221 </variablelist>
5222 </sect3>
5223
5224
5225 <!--   ~~~~~       New section      ~~~~~     -->
5226 <sect3 renderas="sect4" id="overwrite-last-modified">
5227 <title>overwrite-last-modified</title>
5228 <!--
5229 new action
5230 -->
5231 <variablelist>
5232  <varlistentry>
5233   <term>Typical use:</term>
5234   <listitem>
5235    <para>Prevent yet another way to track the user's steps between sessions.</para>
5236   </listitem>
5237  </varlistentry>
5238
5239  <varlistentry>
5240   <term>Effect:</term>
5241   <listitem>
5242    <para>
5243     Deletes the <quote>Last-Modified:</quote> HTTP server header or modifies its value. 
5244    </para>
5245   </listitem>
5246  </varlistentry>
5247
5248  <varlistentry>
5249   <term>Type:</term>
5250   <!-- Boolean, Parameterized, Multi-value -->
5251   <listitem>
5252    <para>Parameterized.</para>
5253   </listitem>
5254  </varlistentry>
5255
5256  <varlistentry>
5257   <term>Parameter:</term>
5258   <listitem>
5259    <para>
5260     One of the keywords: <quote>block</quote>, <quote>reset-to-request-time</quote>
5261     and <quote>randomize</quote>
5262    </para>    
5263   </listitem>
5264  </varlistentry>
5265  
5266  <varlistentry>
5267   <term>Notes:</term>
5268   <listitem>
5269    <para>
5270     Removing the <quote>Last-Modified:</quote> header is useful for filter
5271     testing, where you want to force a real reload instead of getting status
5272     code <quote>304</quote>, which would cause the browser to reuse the old
5273     version of the page.
5274    </para>
5275    <para>
5276     The <quote>randomize</quote> option overwrites the value of the
5277     <quote>Last-Modified:</quote> header with a randomly chosen time
5278     between the original value and the current time. In theory the server
5279     could send each document with a different <quote>Last-Modified:</quote>
5280     header to track visits without using cookies. <quote>Randomize</quote>
5281     makes it impossible and the browser can still revalidate cached documents. 
5282    </para>
5283    <para>
5284     <quote>reset-to-request-time</quote> overwrites the value of the
5285     <quote>Last-Modified:</quote> header with the current time. You could use
5286     this option together with
5287     <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
5288     to further customize your random range.
5289    </para>
5290    <para>
5291     The preferred parameter here is <quote>randomize</quote>. It is safe
5292     to use, as long as the time settings are more or less correct.
5293     If the server sets the <quote>Last-Modified:</quote> header to the time
5294     of the request, the random range becomes zero and the value stays the same.
5295     Therefore you should later randomize it a second time with
5296     <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>,
5297     just to be sure. 
5298    </para>
5299    <para>
5300     It is also recommended to use this action together with
5301     <literal><link linkend="crunch-if-none-match">crunch-if-none-match</link></literal>.
5302    </para>
5303   </listitem>
5304  </varlistentry>
5305
5306  <varlistentry>
5307   <term>Example usage:</term>
5308   <listitem>
5309     <para>
5310      <screen># Let the browser revalidate without being tracked across sessions
5311 { +hide-if-modified-since{-60} \
5312  +overwrite-last-modified{randomize} \
5313  +crunch-if-none-match}
5314 /</screen>
5315    </para>
5316   </listitem>
5317  </varlistentry>
5318 </variablelist>
5319 </sect3>
5320
5321
5322 <!--   ~~~~~       New section      ~~~~~     -->
5323 <sect3 renderas="sect4" id="redirect">
5324 <title>redirect</title>
5325 <!--
5326 new action
5327 -->
5328 <variablelist>
5329  <varlistentry>
5330   <term>Typical use:</term>
5331   <listitem>
5332    <para>
5333     Redirect requests to other sites.
5334    </para>
5335   </listitem>
5336  </varlistentry>
5337
5338  <varlistentry>
5339   <term>Effect:</term>
5340   <listitem>
5341    <para>
5342     Convinces the browser that the requested document has been moved
5343     to another location and the browser should get it from there.
5344    </para>
5345   </listitem>
5346  </varlistentry>
5347
5348  <varlistentry>
5349   <term>Type:</term>
5350   <!-- Boolean, Parameterized, Multi-value -->
5351   <listitem>
5352    <para>Parameterized</para>
5353   </listitem>
5354  </varlistentry>
5355
5356  <varlistentry>
5357   <term>Parameter:</term>
5358   <listitem>
5359    <para>
5360     An absolute URL or a single pcrs command.
5361    </para>
5362   </listitem>
5363  </varlistentry>
5364  
5365  <varlistentry>
5366   <term>Notes:</term>
5367   <listitem>
5368    <para>
5369     Requests to which this action applies are answered with a
5370     HTTP redirect to URLs of your choosing. The new URL is
5371     either provided as parameter, or derived by applying a
5372     single pcrs command to the original URL.
5373    </para>
5374    <para>
5375     This action will be ignored if you use it together with
5376     <literal><link linkend="block">block</link></literal>.
5377     It can be combined with
5378     <literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
5379     to redirect to a decoded version of a rewritten URL.
5380    </para>
5381    <para>
5382     Use this action carefully, make sure not to create redirection loops
5383     and be aware that using your own redirects might make it
5384     possible to fingerprint your requests.
5385    </para>
5386    <para>
5387     In case of problems with your redirects, or simply to watch
5388     them working, enable <link linkend="DEBUG">debug 128</link>.
5389    </para>
5390   </listitem>
5391  </varlistentry>
5392
5393  <varlistentry>
5394   <term>Example usages:</term>
5395   <listitem>
5396    <para>
5397     <screen># Replace example.com's style sheet with another one
5398 { +redirect{http://localhost/css-replacements/example.com.css} }
5399  example.com/stylesheet\.css
5400
5401 # Create a short, easy to remember nickname for a favorite site
5402 # (relies on the browser accept and forward invalid URLs to &my-app;)
5403 { +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
5404  a
5405
5406 # Always use the expanded view for Undeadly.org articles
5407 # (Note the $ at the end of the URL pattern to make sure
5408 # the request for the rewritten URL isn't redirected as well)
5409 {+redirect{s@$@&amp;mode=expanded@}}
5410 undeadly.org/cgi\?action=article&amp;sid=\d*$
5411
5412 # Redirect Google search requests to MSN
5413 {+redirect{s@^http://[^/]*/search\?q=([^&amp;]*).*@http://search.msn.com/results.aspx?q=$1@}}
5414 .google.com/search
5415
5416 # Redirect MSN search requests to Yahoo
5417 {+redirect{s@^http://[^/]*/results\.aspx\?q=([^&amp;]*).*@http://search.yahoo.com/search?p=$1@}}
5418 search.msn.com//results\.aspx\?q=
5419
5420 # Redirect remote requests for this manual
5421 # to the local version delivered by Privoxy
5422 {+redirect{s@^http://www@http://config@}}
5423 www.privoxy.org/user-manual/</screen>
5424    </para>
5425   </listitem>
5426  </varlistentry>
5427
5428 </variablelist>
5429 </sect3>
5430
5431
5432 <!--   ~~~~~       New section      ~~~~~     -->
5433 <sect3 renderas="sect4" id="server-header-filter">
5434 <title>server-header-filter</title>
5435
5436 <variablelist>
5437  <varlistentry>
5438   <term>Typical use:</term>
5439   <listitem>
5440    <para>
5441    Rewrite or remove single server headers.
5442    </para>
5443   </listitem>
5444  </varlistentry>
5445
5446  <varlistentry>
5447   <term>Effect:</term>
5448   <listitem>
5449    <para>
5450     All server headers to which this action applies are filtered on-the-fly
5451     through the specified regular expression based substitutions.
5452    </para>
5453   </listitem>
5454  </varlistentry>
5455
5456  <varlistentry>
5457   <term>Type:</term>
5458   <!-- boolean, parameterized, Multi-value -->
5459   <listitem>
5460    <para>Parameterized.</para>
5461   </listitem>
5462  </varlistentry>
5463
5464  <varlistentry>
5465   <term>Parameter:</term>
5466   <listitem>
5467    <para>
5468     The name of a server-header filter, as defined in one of the
5469     <link linkend="filter-file">filter files</link>.
5470    </para>
5471   </listitem>
5472  </varlistentry>
5473  
5474  <varlistentry>
5475   <term>Notes:</term>
5476   <listitem>
5477    <para>
5478     Server-header filters are applied to each header on its own, not to
5479     all at once. This makes it easier to diagnose problems, but on the downside
5480     you can't write filters that only change header x if header y's value is z.
5481     You can do that by using tags though.
5482    </para>
5483    <para>
5484     Server-header filters are executed after the other header actions have finished
5485     and use their output as input.
5486    </para>
5487    <para>
5488     Please refer to the <link linkend="filter-file">filter file chapter</link>
5489     to learn which server-header filters are available by default, and how to
5490     create your own.
5491    </para>
5492  </listitem>
5493  </varlistentry>
5494
5495  <varlistentry>
5496   <term>Example usage (section):</term>
5497   <listitem>
5498     <para>
5499      <screen>
5500 {+server-header-filter{html-to-xml}}
5501 example.org/xml-instance-that-is-delivered-as-html
5502
5503 {+server-header-filter{xml-to-html}}
5504 example.org/instance-that-is-delivered-as-xml-but-is-not
5505     </screen>
5506     </para>
5507   </listitem>
5508  </varlistentry>
5509
5510 </variablelist>
5511 </sect3>
5512
5513
5514 <!--   ~~~~~       New section      ~~~~~     -->
5515 <sect3 renderas="sect4" id="server-header-tagger">
5516 <title>server-header-tagger</title>
5517
5518 <variablelist>
5519  <varlistentry>
5520   <term>Typical use:</term>
5521   <listitem>
5522    <para>
5523    Enable or disable filters based on the Content-Type header.
5524    </para>
5525   </listitem>
5526  </varlistentry>
5527
5528  <varlistentry>
5529   <term>Effect:</term>
5530   <listitem>
5531    <para>
5532     Server headers to which this action applies are filtered on-the-fly through
5533     the specified regular expression based substitutions, the result is used as
5534     tag.
5535    </para>
5536   </listitem>
5537  </varlistentry>
5538
5539  <varlistentry>
5540   <term>Type:</term>
5541   <!-- boolean, parameterized, Multi-value -->
5542   <listitem>
5543    <para>Parameterized.</para>
5544   </listitem>
5545  </varlistentry>
5546
5547  <varlistentry>
5548   <term>Parameter:</term>
5549   <listitem>
5550    <para>
5551     The name of a server-header tagger, as defined in one of the
5552     <link linkend="filter-file">filter files</link>.
5553    </para>
5554   </listitem>
5555  </varlistentry>
5556  
5557  <varlistentry>
5558   <term>Notes:</term>
5559   <listitem>
5560    <para>
5561     Server-header taggers are applied to each header on its own,
5562     and as the header isn't modified, each tagger <quote>sees</quote>
5563     the original.
5564    </para>
5565    <para>
5566     Server-header taggers are executed before all other header actions
5567     that modify server headers. Their tags can be used to control
5568     all of the other server-header actions, the content filters
5569     and the crunch actions (<link linkend="redirect">redirect</link>
5570     and <link linkend="block">block</link>).
5571    </para>
5572    <para>
5573     Obviously crunching based on tags created by server-header taggers
5574     doesn't prevent the request from showing up in the server's log file.
5575    </para>
5576
5577  </listitem>
5578  </varlistentry>
5579
5580  <varlistentry>
5581   <term>Example usage (section):</term>
5582   <listitem>
5583     <para>
5584      <screen>
5585 # Tag every request with the content type declared by the server
5586 {+server-header-tagger{content-type}}
5587 /
5588     </screen>
5589     </para>
5590   </listitem>
5591  </varlistentry>
5592
5593 </variablelist>
5594 </sect3>
5595
5596
5597 <!--   ~~~~~       New section      ~~~~~     -->
5598 <sect3 renderas="sect4" id="session-cookies-only">
5599 <title>session-cookies-only</title>
5600
5601 <variablelist>
5602  <varlistentry>
5603   <term>Typical use:</term>
5604   <listitem>
5605    <para>
5606     Allow only temporary <quote>session</quote> cookies (for the current
5607     browser session <emphasis>only</emphasis>). 
5608    </para>
5609   </listitem>
5610  </varlistentry>
5611
5612  <varlistentry>
5613   <term>Effect:</term>
5614   <listitem>
5615    <para>
5616     Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote>
5617     server headers. Most browsers will not store such cookies permanently and
5618     forget them in between sessions.
5619    </para>
5620   </listitem>
5621  </varlistentry>
5622
5623 <varlistentry>
5624   <term>Type:</term>
5625   <!-- Boolean, Parameterized, Multi-value -->
5626   <listitem>
5627    <para>Boolean.</para>
5628   </listitem>
5629  </varlistentry>
5630
5631  <varlistentry>
5632   <term>Parameter:</term>
5633   <listitem>
5634    <para>
5635     N/A
5636    </para>
5637   </listitem>
5638  </varlistentry>
5639  
5640  <varlistentry>
5641   <term>Notes:</term>
5642   <listitem>
5643    <para>
5644     This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> / 
5645     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
5646     websites that insist or rely on setting cookies, without compromising your privacy too badly.
5647    </para>
5648    <para>
5649     Most browsers will not permanently store cookies that have been processed by
5650     <literal>session-cookies-only</literal> and will forget about them between sessions.
5651     This makes profiling cookies useless, but won't break sites which require cookies so
5652     that you can log in for transactions. This is generally turned on for all 
5653     sites, and is the recommended setting.
5654    </para>
5655    <para>
5656     It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
5657     together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
5658     <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
5659     will be plainly killed.
5660    </para>
5661    <para>
5662     Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
5663     field. If you use an exotic browser, you might want to try it out to be sure.
5664    </para>
5665    <para>
5666     This setting also has no effect on cookies that may have been stored
5667     previously by the browser before starting <application>Privoxy</application>.
5668     These would have to be removed manually.
5669    </para>
5670    <para>
5671      <application>Privoxy</application> also uses  
5672      the <link linkend="filter-content-cookies">content-cookies filter</link> 
5673      to block some types of cookies. Content cookies are not effected by 
5674      <literal>session-cookies-only</literal>.
5675    </para>
5676   </listitem>
5677  </varlistentry>
5678
5679  <varlistentry>
5680   <term>Example usage:</term>
5681   <listitem>
5682    <para>
5683      <screen>+session-cookies-only</screen>
5684    </para>
5685   </listitem>
5686  </varlistentry>
5687 </variablelist>
5688 </sect3>
5689
5690
5691 <!--   ~~~~~       New section      ~~~~~     -->
5692 <sect3 renderas="sect4" id="set-image-blocker">
5693 <title>set-image-blocker</title>
5694
5695 <variablelist>
5696  <varlistentry>
5697   <term>Typical use:</term>
5698   <listitem>
5699    <para>Choose the replacement for blocked images</para>
5700   </listitem>
5701  </varlistentry>
5702
5703  <varlistentry>
5704   <term>Effect:</term>
5705   <listitem>
5706    <para>
5707      This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
5708      <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
5709      linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
5710      apply, i.e. if the request is to be blocked as an image,
5711      <emphasis>then</emphasis> the parameter of this action decides what will be
5712      sent as a replacement.
5713    </para>
5714   </listitem>
5715  </varlistentry>
5716
5717  <varlistentry>
5718   <term>Type:</term>
5719   <!-- Boolean, Parameterized, Multi-value -->
5720   <listitem>
5721    <para>Parameterized.</para>
5722   </listitem>
5723  </varlistentry>
5724
5725  <varlistentry>
5726   <term>Parameter:</term>
5727   <listitem>
5728    <itemizedlist>
5729     <listitem>
5730      <para>
5731       <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
5732       decent, scales very well, and makes it obvious where banners were busted.
5733      </para>
5734     </listitem>
5735     <listitem>
5736      <para>
5737       <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
5738       completely, but makes it hard to detect where <application>Privoxy</application> has blocked
5739       images on a given page and complicates troubleshooting if <application>Privoxy</application>
5740       has blocked innocent images, like navigation icons.
5741      </para>
5742     </listitem>
5743     <listitem>
5744      <para>
5745       <quote><replaceable class="parameter">target-url</replaceable></quote> to
5746       send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
5747       to any image anywhere, even in your local filesystem via <quote>file:///</quote> URL. 
5748       (But note that not all browsers support redirecting to a local file system).
5749      </para>
5750      <para>
5751       A good application of redirects is to use special <application>Privoxy</application>-built-in
5752       URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
5753       This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
5754       the first place, but enables your browser to cache the replacement image, instead of requesting
5755       it over and over again.
5756      </para>
5757     </listitem>
5758    </itemizedlist>
5759   </listitem>
5760  </varlistentry>
5761
5762  <varlistentry>
5763   <term>Notes:</term>
5764   <listitem>
5765    <para>
5766     The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
5767     class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
5768     either <quote>blank</quote> or <quote>pattern</quote>.
5769    </para>
5770    <para>
5771     There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
5772     used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
5773     Auto will select the type of image that would have applied to the referring page, had it been an image.
5774    </para>
5775   </listitem>
5776  </varlistentry>
5777
5778  <varlistentry>
5779   <term>Example usage:</term>
5780   <listitem>
5781    <para>
5782     Built-in pattern:
5783    </para>
5784    <para>
5785     <screen>+set-image-blocker{pattern}</screen>
5786    </para>
5787    <para>
5788     Redirect to the BSD daemon:
5789    </para>
5790    <para>
5791     <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
5792    </para>
5793    <para>
5794     Redirect to the built-in pattern for better caching:
5795    </para>
5796    <para>
5797     <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
5798    </para>
5799   </listitem>
5800  </varlistentry>
5801 </variablelist>
5802 </sect3>
5803
5804
5805 <!--   ~~~~~       New section      ~~~~~     -->
5806 <sect3>
5807 <title>Summary</title>
5808 <para>
5809  Note that many of these actions have the potential to cause a page to
5810  misbehave, possibly even not to display at all. There are many ways 
5811  a site designer may choose to design his site, and what HTTP header 
5812  content, and other criteria, he may depend on. There is no way to have hard
5813  and fast rules for all sites. See the <link
5814  linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
5815  actions.
5816 </para>
5817 </sect3>
5818 </sect2>
5819
5820 <!--   ~~~~~       New section      ~~~~~     -->
5821 <sect2 id="aliases">
5822 <title>Aliases</title>
5823 <para>
5824  Custom <quote>actions</quote>, known to <application>Privoxy</application>
5825  as <quote>aliases</quote>, can be defined by combining other actions.
5826  These can in turn be invoked just like the built-in actions.
5827  Currently, an alias name can contain any character except space, tab,
5828  <quote>=</quote>,
5829  <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly 
5830  recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
5831  <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
5832  Alias names are not case sensitive, and are not required to start with a
5833  <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
5834  expanded.
5835 </para>
5836 <para>
5837  Aliases can be used throughout the actions file, but they <emphasis>must be
5838  defined in a special section at the top of the file!</emphasis>
5839  And there can only be one such section per actions file. Each actions file may
5840  have its own alias section, and the aliases defined in it are only visible
5841  within that file.
5842 </para>
5843 <para>
5844  There are two main reasons to use aliases: One is to save typing for frequently
5845  used combinations of actions, the other one is a gain in flexibility: If you
5846  decide once how you want to handle shops by defining an alias called
5847  <quote>shop</quote>, you can later change your policy on shops in
5848  <emphasis>one</emphasis> place, and your changes will take effect everywhere
5849  in the actions file where the <quote>shop</quote> alias is used. Calling aliases
5850  by their purpose also makes your actions files more readable.
5851 </para>
5852 <para>
5853  Currently, there is one big drawback to using aliases, though:
5854  <application>Privoxy</application>'s built-in web-based action file
5855  editor honors aliases when reading the actions files, but it expands
5856  them before writing. So the effects of your aliases are of course preserved,
5857  but the aliases themselves are lost when you edit sections that use aliases
5858  with it.
5859 </para>
5860
5861 <para>
5862  Now let's define some aliases...
5863 </para>
5864
5865 <para>
5866  <screen>
5867  # Useful custom aliases we can use later.
5868  #
5869  # Note the (required!) section header line and that this section
5870  # must be at the top of the actions file!
5871  #
5872  {{alias}}
5873
5874  # These aliases just save typing later:
5875  # (Note that some already use other aliases!)
5876  #
5877  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5878  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
5879  +block-as-image      = +block{Blocked image.} +handle-as-image
5880  allow-all-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
5881
5882  # These aliases define combinations of actions
5883  # that are useful for certain types of sites:
5884  #
5885  fragile     = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="PREVENT-COMPRESSION">prevent-compression</link>
5886
5887  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link>
5888
5889  # Short names for other aliases, for really lazy people ;-)
5890  #
5891  c0 = +crunch-all-cookies
5892  c1 = -crunch-all-cookies</screen>
5893 </para>
5894
5895 <para>
5896  ...and put them to use. These sections would appear in the lower part of an 
5897  actions file and define exceptions to the default actions (as specified further
5898  up for the <quote>/</quote> pattern):
5899 </para>
5900
5901 <para>
5902  <screen>
5903  # These sites are either very complex or very keen on
5904  # user data and require minimal interference to work:
5905  #
5906  {fragile}
5907  .office.microsoft.com
5908  .windowsupdate.microsoft.com
5909  # Gmail is really mail.google.com, not gmail.com
5910  mail.google.com
5911
5912  # Shopping sites:
5913  # Allow cookies (for setting and retrieving your customer data)
5914  #           
5915  {shop}
5916  .quietpc.com
5917  .worldpay.com   # for quietpc.com
5918  mybank.example.com
5919
5920  # These shops require pop-ups:
5921  #
5922  {-filter{all-popups} -filter{unsolicited-popups}}
5923   .dabs.com
5924   .overclockers.co.uk</screen>
5925 </para>
5926
5927 <para>
5928  Aliases like <quote>shop</quote> and <quote>fragile</quote> are typically used for 
5929  <quote>problem</quote> sites that require more than one action to be disabled 
5930  in order to function properly.
5931 </para>
5932 </sect2>
5933 <!--
5934 hal stop here
5935 -->
5936 <!--   ~~~~~       New section      ~~~~~     -->
5937 <sect2 id="act-examples">
5938 <title>Actions Files Tutorial</title>
5939 <para>
5940  The above chapters have shown <link linkend="actions-file">which actions files
5941  there are and how they are organized</link>, how actions are <link
5942  linkend="actions">specified</link> and <link linkend="actions-apply">applied
5943  to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
5944  define and use <link linkend="aliases">aliases</link>. Now, let's look at an
5945  example <filename>match-all.action</filename>, <filename>default.action</filename>
5946  and <filename>user.action</filename> file and see how all these pieces come together:
5947 </para>
5948
5949 <sect3>
5950 <title>match-all.action</title>
5951 <para>
5952  Remember <emphasis>all actions are disabled when matching starts</emphasis>,
5953  so we have to explicitly enable the ones we want.
5954 </para>
5955
5956 <para>
5957  While the <filename>match-all.action</filename> file only contains a
5958  single section, it is probably the most important one. It has only one
5959  pattern, <quote><literal>/</literal></quote>, but this pattern
5960  <link linkend="af-patterns">matches all URLs</link>. Therefore, the set of
5961  actions used in this <quote>default</quote> section <emphasis>will
5962  be applied to all requests as a start</emphasis>. It can  be partly or
5963  wholly overridden by other actions files like <filename>default.action</filename>
5964  and <filename>user.action</filename>, but it will still be largely responsible
5965  for your overall browsing experience.
5966 </para>
5967
5968 <para>
5969  Again, at the start of matching, all actions are disabled, so there is
5970  no need to disable any actions here. (Remember: a <quote>+</quote>
5971  preceding the action name enables the action, a <quote>-</quote> disables!).
5972  Also note how this long line has been made more readable by splitting it into
5973  multiple lines with line continuation.
5974 </para> 
5975
5976 <para>
5977  <screen>
5978 { \
5979  +<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
5980  +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
5981  +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
5982 }
5983 / # Match all URLs
5984  </screen>
5985 </para>
5986
5987 <para>
5988  The default behavior is now set.
5989 </para>
5990 </sect3>
5991
5992 <sect3>
5993 <title>default.action</title>
5994
5995 <para>
5996  If you aren't a developer, there's no need for you to edit the
5997  <filename>default.action</filename> file. It is maintained by
5998  the &my-app; developers and if you disagree with some of the
5999  sections, you should overrule them in your <filename>user.action</filename>.
6000 </para>
6001
6002 <para>
6003  Understanding the <filename>default.action</filename> file can
6004  help you with your <filename>user.action</filename>, though.
6005 </para>
6006
6007 <para>
6008  The first section in this file is a special section for internal use
6009  that prevents older &my-app; versions from reading the file:
6010 </para>
6011
6012 <para>
6013  <screen>
6014 ##########################################################################
6015 # Settings -- Don't change! For internal Privoxy use ONLY.
6016 ##########################################################################
6017 {{settings}}
6018 for-privoxy-version=3.0.11</screen>
6019 </para>
6020
6021 <para>
6022  After that comes the (optional) alias section. We'll use the example
6023  section from the above <link linkend="aliases">chapter on aliases</link>,
6024  that also explains why and how aliases are used:
6025 </para>
6026
6027 <para>
6028  <screen>
6029 ##########################################################################
6030 # Aliases
6031 ##########################################################################
6032 {{alias}}
6033
6034  # These aliases just save typing later:
6035  # (Note that some already use other aliases!)
6036  #
6037  +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
6038  -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
6039  +block-as-image      = +block{Blocked image.} +handle-as-image
6040  mercy-for-cookies   = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
6041
6042  # These aliases define combinations of actions
6043  # that are useful for certain types of sites:
6044  #
6045  fragile     = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link>
6046  shop        = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
6047 </para>
6048
6049 <para>
6050  The first of our specialized sections is concerned with <quote>fragile</quote>
6051  sites, i.e. sites that require minimum interference, because they are either
6052  very complex or very keen on tracking you (and have mechanisms in place that
6053  make them unusable for people who avoid being tracked). We will simply use
6054  our pre-defined <literal>fragile</literal> alias instead of stating the list
6055  of actions explicitly:
6056 </para>
6057
6058 <para>
6059  <screen>
6060 ##########################################################################
6061 # Exceptions for sites that'll break under the default action set:
6062 ##########################################################################
6063
6064 # "Fragile" Use a minimum set of actions for these sites (see alias above):
6065 #
6066 { fragile }
6067 .office.microsoft.com           # surprise, surprise!
6068 .windowsupdate.microsoft.com
6069 mail.google.com</screen>
6070 </para>
6071
6072 <para>
6073  Shopping sites are not as fragile, but they typically
6074  require cookies to log in, and pop-up windows for shopping
6075  carts or item details. Again, we'll use a pre-defined alias:
6076 </para>
6077  
6078 <para>
6079  <screen>
6080 # Shopping sites:
6081 #
6082 { shop }
6083 .quietpc.com 
6084 .worldpay.com   # for quietpc.com
6085 .jungle.com
6086 .scan.co.uk</screen>
6087 </para>
6088
6089 <para>
6090  The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
6091  action, which may have been enabled in <filename>match-all.action</filename>,
6092  breaks some sites. So disable it for popular sites where we know it misbehaves:
6093 </para>
6094
6095 <para>
6096  <screen>
6097 { -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
6098 login.yahoo.com
6099 edit.*.yahoo.com
6100 .google.com
6101 .altavista.com/.*(like|url|link):http
6102 .altavista.com/trans.*urltext=http
6103 .nytimes.com</screen>
6104 </para>
6105
6106 <para>
6107  It is important that <application>Privoxy</application> knows which
6108  URLs belong to images, so that <emphasis>if</emphasis> they are to
6109  be blocked, a substitute image can be sent, rather than an HTML page.
6110  Contacting the remote site to find out is not an option, since it
6111  would destroy the loading time advantage of banner blocking, and it
6112  would feed the advertisers information about you. We can mark any
6113  URL as an image with the <literal><link
6114  linkend="handle-as-image">handle-as-image</link></literal> action,
6115  and marking all URLs that end in a known image file extension is a
6116  good start:
6117 </para>
6118
6119 <para>
6120  <screen>
6121 ##########################################################################
6122 # Images:
6123 ##########################################################################
6124
6125 # Define which file types will be treated as images, in case they get
6126 # blocked further down this file:
6127 #
6128 { +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
6129 /.*\.(gif|jpe?g|png|bmp|ico)$</screen>
6130 </para>
6131
6132 <para>
6133  And then there are known banner sources. They often use scripts to
6134  generate the banners, so it won't be visible from the URL that the
6135  request is for an image. Hence we block them <emphasis>and</emphasis>
6136  mark them as images in one go, with the help of our
6137  <literal>+block-as-image</literal> alias defined above. (We could of
6138  course just as well use <literal>+<link linkend="block">block</link>
6139  +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
6140  Remember that the type of the replacement image is chosen by the
6141  <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
6142  action. Since all URLs have matched the default section with its
6143  <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
6144  action before, it still applies and needn't be repeated:
6145 </para>
6146
6147 <para>
6148  <screen>
6149 # Known ad generators:
6150 #
6151 { +block-as-image }
6152 ar.atwola.com 
6153 .ad.doubleclick.net
6154 .ad.*.doubleclick.net
6155 .a.yimg.com/(?:(?!/i/).)*$
6156 .a[0-9].yimg.com/(?:(?!/i/).)*$
6157 bs*.gsanet.com
6158 .qkimg.net</screen>
6159 </para>
6160
6161 <para>
6162  One of the most important jobs of <application>Privoxy</application>
6163  is to block banners. Many of these can be <quote>blocked</quote>
6164  by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
6165  action, which we enabled above, and which deletes the references to banner
6166  images from the pages while they are loaded, so the browser doesn't request
6167  them anymore, and hence they don't need to be blocked here. But this naturally
6168  doesn't catch all banners, and some people choose not to use filters, so we
6169  need a comprehensive list of patterns for banner URLs here, and apply the
6170  <literal><link linkend="block">block</link></literal> action to them.
6171 </para>
6172 <para>
6173  First comes many generic patterns, which do most of the work, by
6174  matching typical domain and path name components of banners. Then comes
6175  a list of individual patterns for specific sites, which is omitted here
6176  to keep the example short:
6177 </para>
6178
6179 <para>
6180  <screen>
6181 ##########################################################################
6182 # Block these fine banners:
6183 ##########################################################################
6184 { <link linkend="BLOCK">+block{Banner ads.}</link> }
6185
6186 # Generic patterns:
6187
6188 ad*.
6189 .*ads.
6190 banner?.
6191 count*.
6192 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
6193 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
6194
6195 # Site-specific patterns (abbreviated):
6196 #
6197 .hitbox.com</screen>
6198 </para>
6199
6200 <para>
6201  It's quite remarkable how many advertisers actually call their banner
6202  servers ads.<replaceable>company</replaceable>.com, or call the directory
6203  in which the banners are stored simply <quote>banners</quote>. So the above
6204  generic patterns are surprisingly effective.
6205 </para>
6206 <para>
6207  But being very generic, they necessarily also catch URLs that we don't want
6208  to block. The pattern <literal>.*ads.</literal> e.g. catches 
6209  <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
6210  but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
6211  <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
6212  well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
6213  section above.
6214 </para>
6215 <para>
6216  Note that these are exceptions to exceptions from the default! Consider the URL
6217  <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
6218  so it wouldn't get blocked. Then comes the defaults section, which matches the
6219  URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
6220  action once again. Then it matches <literal>.*ads.</literal>, an exception to the
6221  general non-blocking policy, and suddenly
6222  <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
6223  <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
6224  applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
6225  with no <literal><link linkend="BLOCK">block</link></literal> action applying.
6226 </para>
6227
6228 <para>
6229  <screen>
6230 ##########################################################################
6231 # Save some innocent victims of the above generic block patterns:
6232 ##########################################################################
6233
6234 # By domain:
6235
6236 { -<link linkend="BLOCK">block</link> }
6237 adv[io]*.  # (for advogato.org and advice.*)
6238 adsl.      # (has nothing to do with ads)
6239 adobe.     # (has nothing to do with ads either)
6240 ad[ud]*.   # (adult.* and add.*)
6241 .edu       # (universities don't host banners (yet!))
6242 .*loads.   # (downloads, uploads etc)
6243
6244 # By path:
6245 #
6246 /.*loads/
6247
6248 # Site-specific:
6249 #
6250 www.globalintersec.com/adv # (adv = advanced)
6251 www.ugu.com/sui/ugu/adv</screen>
6252 </para>
6253
6254 <para>
6255  Filtering source code can have nasty side effects,
6256  so make an exception for our friends at sourceforge.net,
6257  and all paths with <quote>cvs</quote> in them. Note that
6258  <literal>-<link linkend="FILTER">filter</link></literal>
6259  disables <emphasis>all</emphasis> filters in one fell swoop!
6260 </para>
6261
6262 <para>
6263  <screen>
6264 # Don't filter code!
6265 #
6266 { -<link linkend="FILTER">filter</link> }
6267 /(.*/)?cvs
6268 bugzilla.
6269 developer.
6270 wiki.
6271 .sourceforge.net</screen>
6272 </para>
6273
6274 <para>
6275  The actual <filename>default.action</filename> is of course much more
6276  comprehensive, but we hope this example made clear how it works.
6277 </para>
6278
6279 </sect3>
6280
6281 <sect3><title>user.action</title>
6282
6283 <para>
6284  So far we are painting with a broad brush by setting general policies,
6285  which would be a reasonable starting point for many people. Now, 
6286  you might want to be more specific and have customized rules that
6287  are more suitable to your personal habits and preferences. These would
6288  be for narrowly defined situations like your ISP or your bank, and should
6289  be placed in <filename>user.action</filename>, which is parsed after all other 
6290  actions files and hence has the last word, over-riding any previously
6291  defined actions. <filename>user.action</filename> is also a 
6292  <emphasis>safe</emphasis> place for your personal settings, since
6293  <filename>default.action</filename> is actively maintained by the
6294  <application>Privoxy</application> developers and you'll probably want
6295  to install updated versions from time to time.
6296 </para>
6297
6298 <para>
6299  So let's look at a few examples of things that one might typically do in
6300  <filename>user.action</filename>: 
6301 </para>
6302
6303
6304 <!-- brief sample user.action here -->
6305
6306 <para>
6307  <screen>
6308 # My user.action file. &lt;fred@example.com&gt;</screen>
6309 </para>
6310
6311 <para>
6312  As <link linkend="aliases">aliases</link> are local to the actions
6313  file that they are defined in, you can't use the ones from
6314  <filename>default.action</filename>, unless you repeat them here:
6315 </para>
6316
6317 <para>
6318  <screen>
6319 # Aliases are local to the file they are defined in.
6320 # (Re-)define aliases for this file:
6321 #
6322 {{alias}}
6323
6324 # These aliases just save typing later, and the alias names should 
6325 # be self explanatory.
6326 #
6327 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
6328 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
6329  allow-all-cookies  = -crunch-all-cookies -session-cookies-only
6330  allow-popups       = -filter{all-popups}
6331 +block-as-image     = +block{Blocked as image.} +handle-as-image
6332 -block-as-image     = -block
6333
6334 # These aliases define combinations of actions that are useful for
6335 # certain types of sites:
6336 #
6337 fragile     = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer
6338 shop        = -crunch-all-cookies allow-popups
6339
6340 # Allow ads for selected useful free sites:
6341 #
6342 allow-ads   = -block -filter{banners-by-size} -filter{banners-by-link}
6343
6344 # Alias for specific file types that are text, but might have conflicting
6345 # MIME types. We want the browser to force these to be text documents.
6346 handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
6347
6348 </para>
6349
6350 <para>
6351  Say you have accounts on some sites that you visit regularly, and
6352  you don't want to have to log in manually each time. So you'd like
6353  to allow persistent cookies for these sites. The
6354  <literal>allow-all-cookies</literal> alias defined above does exactly
6355  that, i.e. it disables crunching of cookies in any direction, and the 
6356  processing of cookies to make them only temporary.
6357 </para>
6358
6359 <para>
6360  <screen>
6361 { allow-all-cookies }
6362  sourceforge.net
6363  .yahoo.com
6364  .msdn.microsoft.com
6365  .redhat.com</screen>
6366 </para>
6367
6368 <para>
6369  Your bank is allergic to some filter, but you don't know which, so you disable them all:
6370 </para>
6371
6372 <para>
6373  <screen>
6374 { -<link linkend="FILTER">filter</link> }
6375  .your-home-banking-site.com</screen>
6376 </para>
6377
6378 <para>
6379  Some file types you may not want to filter for various reasons:
6380 </para>
6381
6382 <para>
6383  <screen>
6384 # Technical documentation is likely to contain strings that might
6385 # erroneously get altered by the JavaScript-oriented filters:
6386 #
6387 .tldp.org
6388 /(.*/)?selfhtml/
6389
6390 # And this stupid host sends streaming video with a wrong MIME type,
6391 # so that Privoxy thinks it is getting HTML and starts filtering:
6392 #
6393 stupid-server.example.com/</screen>
6394 </para>
6395
6396 <para>
6397  Example of a simple <link linkend="BLOCK">block</link> action. Say you've
6398  seen an ad on your favourite page on example.com that you want to get rid of.
6399  You have right-clicked the image, selected <quote>copy image location</quote>
6400  and pasted the URL below while removing the leading http://, into a 
6401  <literal>{ +block{} }</literal> section. Note that <literal>{ +handle-as-image
6402  }</literal> need not be specified, since all URLs ending in
6403  <literal>.gif</literal> will be tagged as images by the general rules as set
6404  in default.action anyway:
6405 </para>
6406
6407 <para>
6408  <screen>
6409 { +<link linkend="BLOCK">block</link>{Nasty ads.} }
6410  www.example.com/nasty-ads/sponsor\.gif
6411  another.example.net/more/junk/here/</screen>
6412 </para>
6413
6414 <para>
6415  The URLs of dynamically generated banners, especially from large banner
6416  farms, often don't use the well-known image file name extensions, which
6417  makes it impossible for <application>Privoxy</application> to guess
6418  the file type just by looking at the URL. 
6419  You can use the <literal>+block-as-image</literal> alias defined above for
6420  these cases.
6421  Note that objects which match this rule but then turn out NOT to be an
6422  image are typically rendered as a <quote>broken image</quote> icon by the
6423  browser. Use cautiously.
6424 </para>
6425
6426 <para>
6427  <screen>
6428 { +block-as-image }
6429  .doubleclick.net
6430  .fastclick.net
6431  /Realmedia/ads/
6432  ar.atwola.com/</screen>
6433 </para>
6434
6435 <para>
6436  Now you noticed that the default configuration breaks Forbes Magazine,
6437  but you were too lazy to find out which action is the culprit, and you
6438  were again too lazy to give <link linkend="contact">feedback</link>, so
6439  you just used the <literal>fragile</literal> alias on the site, and
6440  -- <emphasis>whoa!</emphasis> -- it worked. The <literal>fragile</literal>
6441  aliases disables those actions that are most likely to break a site. Also,
6442  good for testing purposes to see if it is <application>Privoxy</application>
6443  that is causing the problem or not. We later find other regular sites 
6444  that misbehave, and add those to our personalized list of troublemakers:
6445 </para>
6446
6447 <para>
6448 <screen>
6449 { fragile }
6450  .forbes.com
6451  webmail.example.com
6452  .mybank.com</screen>
6453 </para>
6454
6455 <para>
6456  You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
6457  but it is disabled in the distributed actions file.
6458  So you'd like to turn it on in your private,
6459  update-safe config, once and for all:
6460 </para>
6461
6462 <para>
6463 <screen>
6464 { +<link linkend="filter-fun">filter{fun}</link> }
6465  / # For ALL sites!</screen>
6466 </para>
6467
6468 <para>
6469  Note that the above is not really a good idea: There are exceptions
6470  to the filters in <filename>default.action</filename> for things that
6471  really shouldn't be filtered, like code on CVS->Web interfaces. Since
6472  <filename>user.action</filename> has the last word, these exceptions
6473  won't be valid for the <quote>fun</quote> filtering specified here.
6474 </para>
6475
6476 <para>
6477  You might also worry about how your favourite free websites are
6478  funded, and find that they rely on displaying banner advertisements
6479  to survive. So you might want to specifically allow banners for those
6480  sites that you feel provide value to you:
6481 </para>
6482
6483 <para>
6484 <screen>
6485 { allow-ads }
6486  .sourceforge.net
6487  .slashdot.org
6488  .osdn.net</screen>   
6489 </para>
6490
6491 <para>
6492  Note that <literal>allow-ads</literal> has been aliased to 
6493  <literal>-<link linkend="block">block</link></literal>, 
6494  <literal>-<link linkend="filter-banners-by-size">filter{banners-by-size}</link></literal>, and 
6495  <literal>-<link linkend="filter-banners-by-link">filter{banners-by-link}</link></literal> above.
6496 </para>
6497
6498 <para>
6499  Invoke another alias here to force an over-ride of the MIME type <literal>
6500  application/x-sh</literal> which typically would open a download type 
6501  dialog. In my case, I want to look at the shell script, and then I can save
6502  it should I choose to.
6503 </para>
6504
6505 <para>
6506 <screen>
6507 { handle-as-text }
6508  /.*\.sh$</screen>   
6509 </para>
6510
6511 <para>
6512  <filename>user.action</filename> is generally the best place to define
6513  exceptions and additions to the default policies of
6514  <filename>default.action</filename>. Some actions are safe to have their
6515  default policies set here though. So let's set a default policy to have a
6516  <quote>blank</quote> image as opposed to the checkerboard pattern for
6517  <emphasis>ALL</emphasis> sites. <quote>/</quote> of course matches all URL
6518  paths and patterns:
6519 </para>
6520
6521 <para>
6522 <screen>
6523 { +<link linkend="set-image-blocker">set-image-blocker{blank}</link> }
6524 / # ALL sites</screen>
6525 </para>
6526
6527 </sect3>
6528 </sect2>
6529
6530 <!--  ~  End section  ~  -->
6531
6532 </sect1>
6533
6534 <!--  ~  End section  ~  -->
6535
6536 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6537
6538 <sect1 id="filter-file">
6539 <title>Filter Files</title>
6540
6541 <para>
6542  On-the-fly text substitutions need
6543  to be defined in a <quote>filter file</quote>. Once defined, they 
6544  can then be invoked as an <quote>action</quote>.
6545 </para>
6546
6547 <para>
6548  &my-app; supports three different filter actions:
6549  <literal><link linkend="filter">filter</link></literal> to
6550  rewrite the content that is send to the client,
6551  <literal><link linkend="client-header-filter">client-header-filter</link></literal>
6552  to rewrite headers that are send by the client, and
6553  <literal><link linkend="server-header-filter">server-header-filter</link></literal>
6554  to rewrite headers that are send by the server.
6555 </para>
6556
6557 <para>
6558  &my-app; also supports two tagger actions:
6559  <literal><link linkend="client-header-tagger">client-header-tagger</link></literal>
6560  and
6561  <literal><link linkend="server-header-tagger">server-header-tagger</link></literal>.
6562  Taggers and filters use the same syntax in the filter files, the difference
6563  is that taggers don't modify the text they are filtering, but use a rewritten
6564  version of the filtered text as tag. The tags can then be used to change the
6565  applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
6566 </para>
6567
6568
6569 <para>
6570  Multiple filter files can be defined through the <literal> <link
6571  linkend="filterfile">filterfile</link></literal> config directive. The filters
6572  as supplied by the developers are located in
6573  <filename>default.filter</filename>. It is recommended that any locally
6574  defined or modified filters go in a separately defined file such as
6575  <filename>user.filter</filename>.
6576  </para>
6577
6578 <para>
6579  Common tasks for content filters are to eliminate common annoyances in
6580  HTML and JavaScript, such as pop-up windows,
6581  exit consoles, crippled windows without navigation tools, the
6582  infamous &lt;BLINK&gt; tag etc, to suppress images with certain
6583  width and height attributes (standard banner sizes or web-bugs),
6584  or just to have fun.
6585 </para>
6586
6587 <para>
6588  Enabled content filters are applied to any content whose
6589  <quote>Content Type</quote> header is recognised as a sign
6590  of text-based content, with the exception of <literal>text/plain</literal>.
6591  Use the <link linkend="FORCE-TEXT-MODE">force-text-mode</link> action
6592  to also filter other content.
6593 </para>
6594
6595 <para>
6596  Substitutions are made at the source level, so if you want to <quote>roll
6597  your own</quote> filters, you should first be familiar with HTML syntax, 
6598  and, of course, regular expressions.
6599 </para>
6600
6601 <para>
6602  Just like the <link linkend="actions-file">actions files</link>, the
6603  filter file is organized in sections, which are called <emphasis>filters</emphasis>
6604  here. Each filter consists of a heading line, that starts with one of the
6605  <emphasis>keywords</emphasis> <literal>FILTER:</literal>,
6606  <literal>CLIENT-HEADER-FILTER:</literal> or <literal>SERVER-HEADER-FILTER:</literal>
6607  followed by the filter's <emphasis>name</emphasis>, and a short (one line) 
6608  <emphasis>description</emphasis> of what it does. Below that line
6609  come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
6610  text substitutions. By convention, the name of a filter
6611  should describe what the filter <emphasis>eliminates</emphasis>. The
6612  comment is used in the <ulink url="http://config.privoxy.org/">web-based
6613  user interface</ulink>.
6614 </para>
6615
6616 <para>
6617  Once a filter called <replaceable>name</replaceable> has been defined
6618  in the filter file, it can be invoked by using an action of the form
6619  +<literal><link linkend="filter">filter</link>{<replaceable>name</replaceable>}</literal>
6620  in any <link linkend="actions-file">actions file</link>.
6621 </para>
6622  
6623 <para>
6624  Filter definitions start with a header line that contains the filter
6625  type, the filter name and the filter description.
6626  A content filter header line for a filter called <quote>foo</quote> could look
6627  like this:
6628 </para>
6629
6630 <para>
6631  <screen>FILTER: foo Replace all "foo" with "bar"</screen>
6632 </para>
6633
6634 <para>
6635  Below that line, and up to the next header line, come the jobs that
6636  define what text replacements the filter executes. They are specified
6637  in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
6638  <literal>s///</literal> operator. If you are familiar with Perl, you
6639  will find this to be quite intuitive, and may want to look at the
6640  PCRS documentation for the subtle differences to Perl behaviour. Most
6641  notably, the non-standard option letter <literal>U</literal> is supported,
6642  which turns the default to ungreedy matching.
6643 </para>
6644
6645 <para>
6646  If you are new to 
6647   <ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
6648   Expressions</quote></ulink>, you might want to take a look at
6649  the <link linkend="regex">Appendix on regular expressions</link>, and
6650  see the <ulink url="http://perldoc.perl.org/perlre.html">Perl
6651  manual</ulink> for
6652  <ulink url="http://perldoc.perl.org/perlop.html">the 
6653  <literal>s///</literal> operator's syntax</ulink> and <ulink
6654  url="http://perldoc.perl.org/perlre.html">Perl-style regular
6655  expressions</ulink> in general.
6656  The below examples might also help to get you started.
6657 </para>
6658
6659
6660 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6661
6662 <sect2><title>Filter File Tutorial</title>
6663 <para>
6664  Now, let's complete our <quote>foo</quote> content filter. We have already defined
6665  the heading, but the jobs are still missing. Since all it does is to replace
6666  <quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
6667  needed:
6668 </para>
6669
6670 <para>
6671  <screen>s/foo/bar/</screen>
6672 </para>
6673
6674 <para>
6675  But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
6676  of <quote>foo</quote> should be replaced? Our current job will only take
6677  care of the first <quote>foo</quote> on each page. For global substitution,
6678  we'll need to add the <literal>g</literal> option:
6679 </para>
6680
6681 <para>
6682  <screen>s/foo/bar/g</screen>
6683 </para>
6684
6685 <para>
6686  Our complete filter now looks like this:
6687 </para>
6688 <para>
6689  <screen>FILTER: foo Replace all "foo" with "bar"
6690 s/foo/bar/g</screen>
6691 </para>
6692
6693 <para>
6694  Let's look at some real filters for more interesting examples. Here you see
6695  a filter that protects against some common annoyances that arise from JavaScript
6696  abuse. Let's look at its jobs one after the other:
6697 </para>
6698
6699
6700 <para>
6701  <screen>
6702 FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
6703
6704 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
6705 #
6706 s|(&lt;script.*)document\.referrer(.*&lt;/script&gt;)|$1"Not Your Business!"$2|Usg</screen>
6707 </para>
6708
6709 <para>
6710  Following the header line and a comment, you see the job. Note that it uses
6711  <literal>|</literal> as the delimiter instead of <literal>/</literal>, because
6712  the pattern contains a forward slash, which would otherwise have to be escaped
6713  by a backslash (<literal>\</literal>).
6714 </para>
6715
6716 <para>
6717  Now, let's examine the pattern: it starts with the text <literal>&lt;script.*</literal>
6718  enclosed in parentheses. Since the dot matches any character, and <literal>*</literal>
6719  means: <quote>Match an arbitrary number of the element left of myself</quote>, this
6720  matches <quote>&lt;script</quote>, followed by <emphasis>any</emphasis> text, i.e.
6721  it matches the whole page, from the start of the first &lt;script&gt; tag.
6722 </para>
6723
6724 <para>
6725  That's more than we want, but the pattern continues: <literal>document\.referrer</literal>
6726  matches only the exact string <quote>document.referrer</quote>. The dot needed to
6727  be <emphasis>escaped</emphasis>, i.e. preceded by a backslash, to take away its
6728  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
6729  Match from the start of the first &lt;script&gt; tag in a the page, up to, and including,
6730  the text <quote>document.referrer</quote>, if <emphasis>both</emphasis> are present
6731  in the page (and appear in that order).
6732 </para>
6733
6734 <para>
6735  But there's still more pattern to go. The next element, again enclosed in parentheses,
6736  is <literal>.*&lt;/script&gt;</literal>. You already know what <literal>.*</literal>
6737  means, so the whole pattern translates to: Match from the start of the first  &lt;script&gt;
6738  tag in a page to the end of the last &lt;script&gt; tag, provided that the text
6739  <quote>document.referrer</quote> appears somewhere in between.
6740 </para>
6741
6742 <para>
6743  This is still not the whole story, since we have ignored the options and the parentheses:
6744  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
6745  remembered and be available through the variables <literal>$1, $2, ...</literal> in
6746  the substitute. The <literal>U</literal> option switches to ungreedy matching, which means
6747  that the first <literal>.*</literal> in the pattern will only <quote>eat up</quote> all
6748  text in between <quote>&lt;script</quote> and the <emphasis>first</emphasis> occurrence
6749  of <quote>document.referrer</quote>, and that the second <literal>.*</literal> will
6750  only span the text up to the <emphasis>first</emphasis> <quote>&lt;/script&gt;</quote>
6751  tag. Furthermore, the <literal>s</literal> option says that the match may span
6752  multiple lines in the page, and the <literal>g</literal> option again means that the
6753  substitution is global.
6754 </para>
6755
6756 <para>
6757  So, to summarize, the pattern means: Match all scripts that contain the text
6758  <quote>document.referrer</quote>. Remember the parts of the script from
6759  (and including) the start tag up to (and excluding) the string
6760  <quote>document.referrer</quote> as <literal>$1</literal>, and the part following
6761  that string, up to and including the closing tag, as <literal>$2</literal>.
6762 </para>
6763
6764 <para>
6765  Now the pattern is deciphered, but wasn't this about substituting things? So
6766  lets look at the substitute: <literal>$1"Not Your Business!"$2</literal> is
6767  easy to read: The text remembered as <literal>$1</literal>, followed by 
6768  <literal>"Not Your Business!"</literal> (<emphasis>including</emphasis>
6769  the quotation marks!), followed by the text remembered as <literal>$2</literal>.
6770  This produces an exact copy of the original string, with the middle part
6771  (the <quote>document.referrer</quote>) replaced by <literal>"Not Your
6772  Business!"</literal>.
6773 </para>
6774
6775 <para>
6776  The whole job now reads: Replace <quote>document.referrer</quote> by
6777  <literal>"Not Your Business!"</literal> wherever it appears inside a
6778  &lt;script&gt tag. Note that this job won't break JavaScript syntax,
6779  since both the original and the replacement are syntactically valid
6780  string objects. The script just won't have access to the referrer
6781  information anymore.
6782 </para>
6783
6784 <para>
6785  We'll show you two other jobs from the JavaScript taming department, but
6786  this time only point out the constructs of special interest:
6787 </para>
6788
6789 <para>
6790  <screen>
6791 # The status bar is for displaying link targets, not pointless blahblah
6792 #
6793 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
6794 </para>
6795
6796 <para>
6797  <literal>\s</literal> stands for whitespace characters (space, tab, newline,
6798  carriage return, form feed), so that <literal>\s*</literal> means: <quote>zero
6799  or more whitespace</quote>. The <literal>?</literal> in <literal>.*?</literal>
6800  makes this matching of arbitrary text ungreedy. (Note that the <literal>U</literal>
6801  option is not set). The <literal>['"]</literal> construct means: <quote>a single
6802  <emphasis>or</emphasis> a double quote</quote>. Finally, <literal>\1</literal> is
6803  a back-reference to the first parenthesis just like <literal>$1</literal> above,
6804  with the difference that in the <emphasis>pattern</emphasis>, a backslash indicates
6805  a back-reference, whereas in the <emphasis>substitute</emphasis>, it's the dollar.
6806 </para>
6807
6808 <para>
6809  So what does this job do? It replaces assignments of single- or double-quoted
6810  strings to the <quote>window.status</quote> object with a dummy assignment
6811  (using a variable name that is hopefully odd enough not to conflict with
6812  real variables in scripts). Thus, it catches many cases where e.g. pointless
6813  descriptions are displayed in the status bar instead of the link target when
6814  you move your mouse over links.
6815 </para>
6816
6817 <para>
6818  <screen>
6819 # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
6820 #
6821 s/(&lt;body [^&gt;]*)onunload(.*&gt;)/$1never$2/iU</screen>
6822 </para>
6823
6824 <para>
6825  Including the
6826  <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">OnUnload
6827  event binding</ulink> in the HTML DOM was a <emphasis>CRIME</emphasis>.
6828  When I close a browser window, I want it to close and die. Basta.
6829  This job replaces the <quote>onunload</quote> attribute in
6830  <quote>&lt;body&gt</quote> tags with the dummy word <literal>never</literal>.
6831  Note that the <literal>i</literal> option makes the pattern matching
6832  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
6833  a minimal match: In the first parenthesis, we had to use <literal>[^&gt;]*</literal>
6834  instead of <literal>.*</literal> to prevent the match from exceeding the 
6835  &lt;body&gt tag if it doesn't contain <quote>OnUnload</quote>, but the page's
6836  content does.
6837 </para>
6838
6839 <para>
6840  The last example is from the fun department:
6841 </para>
6842
6843 <para>
6844  <screen>
6845 FILTER: fun Fun text replacements
6846
6847 # Spice the daily news:
6848 #
6849 s/microsoft(?!\.com)/MicroSuck/ig</screen>
6850 </para>
6851
6852 <para>
6853  Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
6854  in the job's pattern, which means: Don't match, if the string 
6855  <quote>.com</quote> appears directly following <quote>microsoft</quote>
6856  in the page. This prevents links to microsoft.com from being trashed, while
6857  still replacing the word everywhere else.
6858 </para>
6859
6860 <para>
6861  <screen>
6862 # Buzzword Bingo (example for extended regex syntax)
6863 #
6864 s* industry[ -]leading \
6865 |  cutting[ -]edge \
6866 |  customer[ -]focused \
6867 |  market[ -]driven \
6868 |  award[ -]winning # Comments are OK, too! \
6869 |  high[ -]performance \
6870 |  solutions[ -]based \
6871 |  unmatched \
6872 |  unparalleled \
6873 |  unrivalled \
6874 *&lt;font color="red"&gt;&lt;b&gt;BINGO!&lt;/b&gt;&lt;/font&gt; \
6875 *igx</screen>
6876 </para>
6877
6878 <para>
6879  The <literal>x</literal> option in this job turns on extended syntax, and allows for
6880  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting. 
6881 </para>
6882
6883 <para>
6884  You get the idea?
6885 </para>
6886 </sect2>
6887
6888 <!--   ~~~~~~~~       New section Header    ~~~~~~~~~     -->
6889
6890 <sect2 id="predefined-filters"><title>The Pre-defined Filters</title>
6891
6892 <!-- 
6893
6894  Note each filter is also listed in the +filter action section above. Please
6895  keep these listings in sync.
6896  
6897 -->
6898
6899 <para>
6900 The distribution <filename>default.filter</filename> file contains a selection of
6901 pre-defined filters for your convenience:
6902 </para>
6903
6904 <variablelist>
6905  <varlistentry>
6906   <term><emphasis>js-annoyances</emphasis></term>
6907   <listitem>
6908    <para>
6909     The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
6910     To that end, it
6911    <itemizedlist>
6912     <listitem>
6913      <para>
6914       replaces JavaScript references to the browser's referrer information
6915       with the string "Not Your Business!". This compliments the <literal><link
6916       linkend="hide-referrer">hide-referrer</link></literal> action on the content level.
6917      </para>
6918     </listitem>
6919     <listitem>
6920      <para>
6921       removes the bindings to the DOM's
6922       <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">unload
6923       event</ulink> which we feel has no right to exist and is responsible for most <quote>exit consoles</quote>, i.e.
6924       nasty windows that pop up when you close another one.
6925      </para>
6926     </listitem>
6927     <listitem>
6928      <para>
6929       removes code that causes new windows to be opened with undesired properties, such as being
6930       full-screen, non-resizeable, without location, status or menu bar etc.
6931      </para>
6932     </listitem>
6933    </itemizedlist>
6934    </para>
6935    <para>
6936     Use with caution. This is an aggressive filter, and can break sites that 
6937     rely heavily on JavaScript.
6938    </para>
6939   </listitem>
6940  </varlistentry>
6941  
6942  <varlistentry>
6943   <term><emphasis>js-events</emphasis></term>
6944   <listitem>
6945    <para>
6946     This is a very radical measure. It removes virtually all JavaScript event bindings, which
6947     means that scripts can not react to user actions such as mouse movements or clicks, window
6948     resizing etc, anymore. Use with caution!
6949    </para>
6950    <para>
6951     We <emphasis>strongly discourage</emphasis> using this filter as a default since it breaks
6952     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
6953     need to go there).
6954    </para>
6955   </listitem>
6956  </varlistentry>
6957
6958 <varlistentry>
6959   <term><emphasis>html-annoyances</emphasis></term>
6960   <listitem>
6961    <para>
6962     This filter will undo many common instances of HTML based abuse.
6963    </para>
6964    <para>
6965     The <literal>BLINK</literal> and <literal>MARQUEE</literal> tags 
6966     are neutralized (yeah baby!), and browser windows will be created as
6967     resizeable (as of course they should be!), and will have location,
6968     scroll and menu bars -- even if specified otherwise.
6969    </para>
6970   </listitem>
6971  </varlistentry>
6972
6973  <varlistentry>
6974   <term><emphasis>content-cookies</emphasis></term>
6975   <listitem>
6976    <para>
6977     Most cookies are set in the HTTP dialog, where they can be intercepted
6978     by the
6979     <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>
6980     and <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>
6981     actions. But web sites increasingly make use of HTML meta tags and JavaScript
6982     to sneak cookies to the browser on the content level.
6983    </para>
6984    <para>
6985     This filter disables most HTML and JavaScript code that reads or sets
6986     cookies. It cannot detect all clever uses of these types of code, so it 
6987     should not be relied on as an absolute fix. Use it wherever you would also
6988     use the cookie crunch actions. 
6989    </para>
6990   </listitem>
6991  </varlistentry>
6992
6993  <varlistentry>
6994   <term><emphasis>refresh tags</emphasis></term>
6995   <listitem>
6996    <para>
6997     Disable any refresh tags if the interval is greater than nine seconds (so 
6998     that redirections done via refresh tags are not destroyed). This is useful 
6999     for dial-on-demand setups, or for those who find this HTML feature
7000     annoying.
7001    </para>
7002   </listitem>
7003  </varlistentry>
7004
7005  <varlistentry>
7006   <term><emphasis>unsolicited-popups</emphasis></term>
7007   <listitem>
7008    <para>
7009     This filter attempts to prevent only <quote>unsolicited</quote> pop-up 
7010     windows from opening, yet still allow pop-up windows that the user 
7011     has explicitly chosen to open. It was added in version 3.0.1, 
7012     as an improvement over earlier such filters.
7013    </para>
7014    <para>
7015     Technical note: The filter works by redefining the window.open JavaScript
7016     function to a dummy function, <literal>PrivoxyWindowOpen()</literal>,
7017     during the loading and rendering phase of each HTML page access, and
7018     restoring the function afterward.
7019    </para>
7020    <para>
7021     This is recommended only for browsers that cannot perform this function
7022     reliably themselves. And be aware that some sites require such windows 
7023     in order to function normally. Use with caution.
7024    </para>
7025   </listitem>
7026  </varlistentry>
7027
7028  <varlistentry>
7029   <term><emphasis>all-popups</emphasis></term>
7030   <listitem>
7031    <para>
7032     Attempt to prevent <emphasis>all</emphasis> pop-up windows from opening.
7033     Note this should be used with even more discretion than the above, since
7034     it is more likely to break some sites that require pop-ups for normal
7035     usage. Use with caution.
7036    </para>
7037   </listitem>
7038  </varlistentry>
7039
7040  <varlistentry>
7041   <term><emphasis>img-reorder</emphasis></term>
7042   <listitem>
7043    <para>
7044     This is a helper filter that has no value if used alone. It makes the
7045     <literal>banners-by-size</literal> and <literal>banners-by-link</literal>
7046     (see below) filters more effective and should be enabled together with them.
7047    </para>
7048   </listitem>
7049  </varlistentry>
7050
7051  <varlistentry>
7052   <term><emphasis>banners-by-size</emphasis></term>
7053   <listitem>
7054    <para>
7055     This filter removes image tags purely based on what size they are. Fortunately 
7056     for us, many ads and banner images tend to conform to certain standardized
7057     sizes, which makes this filter quite effective for ad stripping purposes.
7058    </para>
7059    <para>
7060     Occasionally this filter will cause false positives on images that are not ads,
7061     but just happen to be of one of the standard banner sizes.
7062    </para>
7063    <para>
7064     Recommended only for those who require extreme ad blocking. The default 
7065     block rules should catch 95+% of all ads <emphasis>without</emphasis> this filter enabled.
7066    </para>
7067   </listitem>
7068  </varlistentry>
7069
7070  <varlistentry>
7071   <term><emphasis>banners-by-link</emphasis></term>
7072   <listitem>
7073    <para>
7074     This is an experimental filter that attempts to kill any banners if 
7075     their URLs seem to point to known or suspected click trackers. It is currently
7076     not of much value and is not recommended for use by default.
7077    </para>
7078   </listitem>
7079  </varlistentry>
7080
7081  <varlistentry>
7082   <term><emphasis>webbugs</emphasis></term>
7083   <listitem>
7084    <para>
7085     Webbugs are small, invisible images (technically 1X1 GIF images), that 
7086     are used to track users across websites, and collect information on them.
7087     As an HTML page is loaded by the browser, an embedded image tag causes the
7088     browser to contact a third-party site, disclosing the tracking information
7089     through the requested URL and/or cookies for that third-party domain, without
7090     the user ever becoming aware of the interaction with the third-party site.
7091     HTML-ized spam also uses a similar technique to verify email addresses.
7092    </para>
7093    <para>
7094     This filter removes the HTML code that loads such <quote>webbugs</quote>.
7095    </para>
7096   </listitem>
7097  </varlistentry>
7098
7099  <varlistentry>
7100   <term><emphasis>tiny-textforms</emphasis></term>
7101   <listitem>
7102    <para>
7103     A rather special-purpose filter that can be used to enlarge textareas (those
7104     multi-line text boxes in web forms) and turn off hard word wrap in them. 
7105     It was written for the sourceforge.net tracker system where such boxes are
7106     a nuisance, but it can be handy on other sites, too.
7107    </para>
7108    <para>
7109     It is not recommended to use this filter as a default.
7110    </para>
7111   </listitem>
7112  </varlistentry>
7113
7114  <varlistentry>
7115   <term><emphasis>jumping-windows</emphasis></term>
7116   <listitem>
7117    <para>
7118     Many consider windows that move, or resize themselves to be abusive. This filter
7119     neutralizes the related JavaScript code. Note that some sites might not display
7120     or behave as intended when using this filter. Use with caution.
7121    </para>
7122   </listitem>
7123  </varlistentry>
7124
7125  <varlistentry>
7126   <term><emphasis>frameset-borders</emphasis></term>
7127   <listitem>
7128    <para>
7129     Some web designers seem to assume that everyone in the world will view their
7130     web sites using the same browser brand and version, screen resolution etc,
7131     because only that assumption could explain why they'd use static frame sizes,
7132     yet prevent their frames from being resized by the user, should they be too
7133     small to show their whole content.
7134    </para>
7135    <para>
7136     This filter removes the related HTML code. It should only be applied to sites
7137     which need it.
7138    </para>
7139   </listitem>
7140  </varlistentry>
7141
7142  <varlistentry>
7143   <term><emphasis>demoronizer</emphasis></term>
7144   <listitem>
7145    <para>
7146     Many Microsoft products that generate HTML use non-standard extensions (read:
7147     violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those
7148     HTML documents to display with errors on standard-compliant platforms. 
7149    </para>
7150    <para>
7151     This filter translates the MS-only characters into Latin-1 equivalents. 
7152     It is not necessary when using MS products, and will cause corruption of  
7153     all documents that use 8-bit character sets other than Latin-1. It's mostly
7154     worthwhile for Europeans on non-MS platforms, if weird garbage characters
7155     sometimes appear on some pages, or user agents that don't correct for this on 
7156     the fly.
7157 <!--
7158     My version of Mozilla (ancient) shows litte square boxes for quote
7159     characters, and apostrophes on moronized pages. So many pages have this, I
7160     can read them fine now. HB 08/27/06
7161 --> 
7162    </para>
7163   </listitem>
7164  </varlistentry>
7165
7166  <varlistentry>
7167   <term><emphasis>shockwave-flash</emphasis></term>
7168   <listitem>
7169    <para>
7170     A filter for shockwave haters. As the name suggests, this filter strips code
7171     out of web pages that is used to embed shockwave flash objects. 
7172    </para>
7173    <para>
7174    </para>
7175   </listitem>
7176  </varlistentry>
7177
7178  <varlistentry>
7179   <term><emphasis>quicktime-kioskmode</emphasis></term>
7180   <listitem>
7181    <para>
7182     Change HTML code that embeds Quicktime objects so that kioskmode, which
7183     prevents saving, is disabled.
7184    </para>
7185   </listitem>
7186  </varlistentry>
7187
7188  <varlistentry>
7189   <term><emphasis>fun</emphasis></term>
7190   <listitem>
7191    <para>
7192     Text replacements for subversive browsing fun. Make fun of your favorite
7193     Monopolist or play buzzword bingo.
7194    </para>
7195   </listitem>
7196  </varlistentry>
7197
7198  <varlistentry>
7199   <term><emphasis>crude-parental</emphasis></term>
7200   <listitem>
7201    <para>
7202     A demonstration-only filter that shows how <application>Privoxy</application>
7203     can be used to delete web content on a keyword basis.
7204    </para>
7205   </listitem>
7206  </varlistentry>
7207
7208  <varlistentry>
7209   <term><emphasis>ie-exploits</emphasis></term>
7210   <listitem>
7211    <para>
7212     An experimental collection of text replacements to disable malicious HTML and JavaScript
7213     code that exploits known security holes in Internet Explorer.
7214    </para>
7215    <para>
7216     Presently, it only protects against Nimda and a cross-site scripting bug, and
7217     would need active maintenance to provide more substantial protection.
7218    </para>
7219   </listitem>
7220  </varlistentry>
7221
7222  <varlistentry>
7223   <term><emphasis>site-specifics</emphasis></term>
7224   <listitem>
7225    <para>
7226     Some web sites have very specific problems, the cure for which doesn't apply
7227     anywhere else, or could even cause damage on other sites.
7228    </para>
7229    <para>
7230     This is a collection of such site-specific cures which should only be applied
7231     to the sites they were intended for, which is what the supplied
7232     <filename>default.action</filename> file does. Users shouldn't need to change
7233     anything regarding this filter.
7234    </para>
7235   </listitem>
7236  </varlistentry>
7237
7238  <varlistentry>
7239   <term><emphasis>google</emphasis></term>
7240   <listitem>
7241    <para>
7242     A CSS based block for Google text ads. Also removes a width limitation
7243     and the toolbar advertisement.
7244    </para>
7245   </listitem>
7246  </varlistentry>
7247  
7248   <varlistentry>
7249   <term><emphasis>yahoo</emphasis></term>
7250   <listitem>
7251    <para>
7252     Another CSS based block, this time for Yahoo text ads. And removes 
7253     a width limitation as well.
7254    </para>
7255   </listitem>
7256  </varlistentry>
7257
7258   <varlistentry>
7259   <term><emphasis>msn</emphasis></term>
7260   <listitem>
7261    <para>
7262     Another CSS based block, this time for MSN text ads. And removes 
7263     tracking URLs, as well as a width limitation.
7264    </para>
7265   </listitem>
7266  </varlistentry>
7267
7268  <varlistentry>
7269   <term><emphasis>blogspot</emphasis></term>
7270   <listitem>
7271    <para>
7272     Cleans up some Blogspot blogs. Read the fine print before using this one!
7273    </para>
7274    <para>
7275     This filter also intentionally removes some navigation stuff and sets the
7276     page width to 100%. As a result, some rounded <quote>corners</quote> would
7277     appear to early or not at all and as fixing this would require a browser
7278     that understands background-size (CSS3), they are removed instead.
7279    </para>
7280   </listitem>
7281  </varlistentry>
7282
7283   <varlistentry>
7284   <term><emphasis>xml-to-html</emphasis></term>
7285   <listitem>
7286    <para>
7287     Server-header filter to change the Content-Type from xml to html.
7288    </para>
7289   </listitem>
7290  </varlistentry>
7291  
7292   <varlistentry>
7293   <term><emphasis>html-to-xml</emphasis></term>
7294   <listitem>
7295    <para>
7296     Server-header filter to change the Content-Type from html to xml.
7297    </para>
7298   </listitem>
7299  </varlistentry>
7300
7301   <varlistentry>
7302   <term><emphasis>no-ping</emphasis></term>
7303   <listitem>
7304    <para>
7305     Removes the non-standard <literal>ping</literal> attribute from
7306     anchor and area HTML tags.
7307    </para>
7308   </listitem>
7309  </varlistentry>
7310
7311   <varlistentry>
7312   <term><emphasis>hide-tor-exit-notation</emphasis></term>
7313   <listitem>
7314    <para>
7315     Client-header filter to remove the <command>Tor</command> exit node notation
7316     found in Host and Referer headers.
7317    </para>
7318    <para>
7319     If &my-app; and <command>Tor</command> are chained and &my-app;
7320     is configured to use socks4a, one can use <quote>http://www.example.org.foobar.exit/</quote>
7321     to access the host <quote>www.example.org</quote> through the
7322     <command>Tor</command> exit node <quote>foobar</quote>.
7323    </para>
7324    <para>
7325     As the HTTP client isn't aware of this notation, it treats the
7326     whole string <quote>www.example.org.foobar.exit</quote> as host and uses it
7327     for the <quote>Host</quote> and <quote>Referer</quote> headers. From the
7328     server's point of view the resulting headers are invalid and can cause problems.
7329    </para>
7330    <para>
7331     An invalid <quote>Referer</quote> header can trigger <quote>hot-linking</quote>
7332     protections, an invalid <quote>Host</quote> header will make it impossible for
7333     the server to find the right vhost (several domains hosted on the same IP address).
7334    </para>
7335    <para>
7336     This client-header filter removes the <quote>foo.exit</quote> part in those headers
7337     to prevent the mentioned problems. Note that it only modifies
7338     the HTTP headers, it doesn't make it impossible for the server
7339     to detect your <command>Tor</command> exit node based on the IP address
7340     the request is coming from.
7341    </para>
7342   </listitem>
7343  </varlistentry>
7344
7345 <!--
7346  <varlistentry>
7347   <term><emphasis> </emphasis></term>
7348   <listitem>
7349    <para>
7350    </para>
7351    <para>
7352    </para>
7353   </listitem>
7354  </varlistentry>
7355 -->
7356 </variablelist>
7357
7358 </sect2>
7359 </sect1>
7360
7361 <!--  ~  End section  ~  -->
7362
7363
7364
7365 <!--   ~~~~~       New section      ~~~~~     -->
7366
7367 <sect1 id="templates">
7368 <title>Privoxy's Template Files</title>
7369 <para>
7370  All <application>Privoxy</application> built-in pages, i.e. error pages such as the 
7371  <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
7372  error page</ulink>, the <ulink
7373  url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
7374  page</ulink>
7375  and all pages of its <ulink url="http://config.privoxy.org/">web-based
7376  user interface</ulink>, are generated from <emphasis>templates</emphasis>. 
7377  (<application>Privoxy</application> must be running for the above links to work as
7378  intended.)
7379 </para>
7380
7381 <para>
7382  These templates are stored in a subdirectory of the <link linkend="confdir">configuration
7383  directory</link> called <filename>templates</filename>. On Unixish platforms,
7384  this is typically
7385  <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
7386 </para>
7387
7388 <para>
7389  The templates are basically normal HTML files, but with place-holders (called symbols
7390  or exports), which <application>Privoxy</application> fills at run time. It
7391  is possible to edit the templates with a normal text editor, should you want
7392  to customize them. (<emphasis>Not recommended for the casual
7393  user</emphasis>). Should you create your own custom templates, you should use 
7394  the <filename>config</filename> setting <link linkend="templdir">templdir</link>
7395  to specify an alternate location, so your templates do not get overwritten
7396  during upgrades. 
7397  </para>
7398  <para>
7399  Note that just like in configuration files, lines starting
7400  with <literal>#</literal> are ignored when the templates are filled in.
7401 </para>
7402
7403 <para>
7404  The place-holders are of the form <literal>@name@</literal>, and you will
7405  find a list of available symbols, which vary from template to template,
7406  in the comments at the start of each file. Note that these comments are not
7407  always accurate, and that it's probably best to look at the existing HTML
7408  code to find out which symbols are supported and what they are filled in with.
7409 </para>
7410
7411 <para>
7412  A special application of this substitution mechanism is to make whole
7413  blocks of HTML code disappear when a specific symbol is set. We use this
7414  for many purposes, one of them being to include the beta warning in all
7415  our user interface (CGI) pages when <application>Privoxy</application>
7416  is in an alpha or beta development stage:
7417 </para>
7418
7419 <para>
7420  <screen>
7421 &lt;!-- @if-unstable-start --&gt;
7422
7423   ... beta warning HTML code goes here ...
7424
7425 &lt;!-- if-unstable-end@ --&gt;</screen>
7426 </para>
7427
7428 <para>
7429  If the "unstable" symbol is set, everything in between and including
7430  <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
7431  will disappear, leaving nothing but an empty comment:
7432 </para>
7433
7434 <para>
7435  <screen>&lt;!--  --&gt;</screen>
7436 </para>
7437
7438 <para>
7439  There's also an if-then-else construct and an <literal>#include</literal>
7440  mechanism, but you'll sure find out if you are inclined to edit the
7441  templates ;-)
7442 </para>
7443
7444 <para>
7445  All templates refer to a style located at
7446  <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
7447  This is, of course, locally served by <application>Privoxy</application>
7448  and the source for it can be found and edited in the
7449  <filename>cgi-style.css</filename> template.
7450 </para>
7451
7452 </sect1>
7453
7454 <!--  ~  End section  ~  -->
7455
7456
7457
7458 <!--   ~~~~~       New section      ~~~~~     -->
7459
7460 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
7461 Requests</title>
7462
7463 <!-- Include contacting.sgml boilerplate: -->
7464  &contacting;
7465 <!-- end boilerplate -->
7466
7467 </sect1>
7468
7469 <!--  ~  End section  ~  -->
7470
7471
7472 <!--   ~~~~~       New section      ~~~~~     -->
7473 <sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
7474
7475 <!-- Include copyright.sgml: -->
7476  &copyright;
7477 <!-- end copyright -->
7478
7479 <!--   ~~~~~       New section      ~~~~~     -->
7480 <sect2><title>License</title>
7481 <!-- Include copyright.sgml: -->
7482  &license;
7483 <!-- end copyright -->
7484 </sect2>
7485 <!--  ~  End section  ~  -->
7486
7487
7488 <!--   ~~~~~       New section      ~~~~~     -->
7489
7490 <sect2 id="history"><title>History</title>
7491 <!-- Include history.sgml: -->
7492  &history;
7493 <!-- end history -->
7494 </sect2>
7495
7496 <sect2 id="authors"><title>Authors</title>
7497 <!-- Include p-authors.sgml: -->
7498  &p-authors;
7499 <!-- end authors -->
7500 </sect2>
7501
7502 </sect1>
7503
7504 <!--  ~  End section  ~  -->
7505
7506
7507 <!--   ~~~~~       New section      ~~~~~     -->
7508 <sect1 id="seealso"><title>See Also</title>
7509 <!-- Include seealso.sgml: -->
7510  &seealso;
7511 <!-- end seealso -->
7512 </sect1>
7513
7514
7515
7516 <!--   ~~~~~       New section      ~~~~~     -->
7517 <sect1 id="appendix"><title>Appendix</title>
7518
7519
7520 <!--   ~~~~~       New section      ~~~~~     -->
7521 <sect2 id="regex">
7522 <title>Regular Expressions</title>
7523 <para>
7524  <application>Privoxy</application> uses Perl-style <quote>regular
7525  expressions</quote> in its <link linkend="actions-file">actions
7526  files</link> and <link linkend="filter-file">filter file</link>,
7527  through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
7528 <!-- 
7529  dead 08/27/06
7530  <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
7531 -->
7532  <application>PCRS</application> libraries.
7533 </para>
7534
7535 <para>
7536  If you are reading this, you probably don't understand what <quote>regular
7537  expressions</quote> are, or what they can do. So this will be a very brief
7538  introduction only. A full explanation would require a <ulink
7539  url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
7540 </para>
7541
7542 <para>
7543  Regular expressions provide a language to describe patterns that can be
7544  run against strings of characters (letter, numbers, etc), to see if they
7545  match the string or not. The  patterns are themselves (sometimes complex)
7546  strings of literal characters, combined with  wild-cards, and other special
7547  characters, called meta-characters. The <quote>meta-characters</quote> have
7548  special meanings and are used to build complex patterns to be matched against.
7549  Perl Compatible Regular Expressions are an especially convenient
7550  <quote>dialect</quote> of the regular expression language.
7551 </para>
7552
7553 <para>
7554  To make a simple analogy, we do something similar when we use wild-card
7555  characters when listing files with the <command>dir</command> command in DOS. 
7556  <literal>*.*</literal> matches all filenames. The <quote>special</quote>
7557  character here is the asterisk which matches any and all characters. We can be
7558  more specific and use <literal>?</literal> to match just individual
7559  characters. So <quote>dir file?.text</quote> would match
7560  <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
7561  matching, using a similar technique to <quote>regular expressions</quote>!
7562 </para>
7563
7564 <para>
7565  Regular expressions do essentially the same thing, but are much, much more
7566  powerful. There are many more <quote>special characters</quote> and ways of 
7567  building complex patterns however. Let's look at a few of the common ones,
7568  and then some examples:
7569 </para>
7570
7571 <para><simplelist>
7572  <member>
7573   <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
7574   <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
7575  </member>
7576 </simplelist></para>
7577
7578 <para><simplelist>
7579  <member>
7580   <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
7581   times. Either/or.
7582  </member>
7583 </simplelist></para>
7584
7585 <para><simplelist>
7586  <member>
7587   <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
7588   times.
7589  </member>
7590 </simplelist></para>
7591
7592 <para><simplelist>
7593  <member>
7594   <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
7595   times.
7596  </member>
7597 </simplelist></para>
7598
7599 <para><simplelist>
7600  <member>
7601   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
7602   the following character should be taken literally. This is used where one of the 
7603   special characters (e.g. <quote>.</quote>) needs to be taken literally and
7604   not as a special meta-character. Example: <quote>example\.com</quote>, makes 
7605   sure the period is recognized only as a period (and not expanded to its 
7606   meta-character meaning of any single character).
7607  </member>
7608 </simplelist></para>
7609
7610 <para><simplelist>
7611  <member>
7612   <emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
7613   any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
7614   matches any numeric digit (zero through nine). As an example, we can combine 
7615   this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
7616  </member>
7617 </simplelist></para>
7618
7619 <para><simplelist>
7620  <member>
7621   <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
7622   or multiple sub-expressions.
7623  </member>
7624 </simplelist></para>
7625
7626 <para><simplelist>
7627  <member>
7628   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
7629   <quote>or</quote> conditional statement. A match is successful if the
7630   sub-expression on either side of <quote>|</quote> matches. As an example:
7631   <quote>/(this|that) example/</quote> uses grouping and the bar character 
7632   and would match either <quote>this example</quote> or <quote>that
7633   example</quote>, and nothing else.
7634  </member>
7635 </simplelist></para>
7636
7637 <para>
7638  These are just some of the ones you are likely to use when matching URLs with 
7639  <application>Privoxy</application>, and is a long way from a definitive
7640  list. This is enough to get us started with a few simple examples which may
7641  be more illuminating:
7642 </para>
7643
7644 <para>
7645  <emphasis><literal>/.*/banners/.*</literal></emphasis> - A  simple example
7646  that uses the common combination of <quote>.</quote> and <quote>*</quote> to 
7647  denote any character, zero or more times. In other words, any string at all.
7648  So we start with a literal forward slash, then our regular expression pattern 
7649  (<quote>.*</quote>) another literal forward slash, the string
7650  <quote>banners</quote>, another forward slash, and lastly another
7651  <quote>.*</quote>. We are building 
7652  a directory path here. This will match any file with the path that has a
7653  directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
7654  any characters, and this could conceivably be more forward slashes, so it
7655  might expand into a much longer looking path. For example, this could match:
7656  <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
7657  <quote>/banners/annoying.html</quote>, or almost an infinite number of other
7658  possible combinations, just so it has <quote>banners</quote> in the path
7659  somewhere.
7660 </para>
7661
7662 <para>
7663  And now something a little more complex:
7664 </para>
7665
7666 <para>
7667  <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> - 
7668  We have several literal forward slashes again (<quote>/</quote>), so we are
7669  building another expression that is a file path statement. We have another 
7670  <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
7671  it matches our expression. The only true literal that <emphasis>must
7672  match</emphasis> our pattern is <application>adv</application>, together with
7673  the forward slashes. What comes after the <quote>adv</quote> string is the
7674  interesting part. 
7675 </para>
7676
7677 <para>
7678  Remember the <quote>?</quote> means the preceding expression (either a
7679  literal character or anything grouped with <quote>(...)</quote> in this case)
7680  can exist or not, since this means either zero or one match. So
7681  <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
7682  individual sub-expressions: <quote>(er)</quote>,
7683  <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
7684  means <quote>or</quote>. We have two of those. For instance, 
7685  <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote> 
7686  <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
7687  attempt at matching as many variations of <quote>advertisement</quote>, and 
7688  similar, as possible. So this would expand to match just <quote>adv</quote>,
7689  or <quote>advert</quote>, or <quote>adverts</quote>, or
7690  <quote>advertising</quote>, or <quote>advertisement</quote>, or
7691  <quote>advertisements</quote>. You get the idea. But it would not match 
7692  <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
7693  changing our regular expression to: 
7694  <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
7695  either spelling.
7696 </para>
7697
7698 <para>
7699  <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again 
7700  another path statement with forward slashes. Anything in the square brackets 
7701  <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
7702  shorthand expression to mean any digit one through nine. It is the same as
7703  saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
7704  means one or more of the preceding expression must be included. The preceding 
7705  expression here is what is in the square brackets -- in this case, any digit 
7706  one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>. 
7707  This includes a <quote>|</quote>, so this needs to match the expression on
7708  either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
7709  side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
7710  since the <quote>?</quote> means the letter <quote>e</quote> is optional and
7711  can be matched once or not at all. So we are building an expression here to
7712  match image GIF or JPEG type image file. It must include the literal
7713  string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
7714  (which is now a literal, and not a special character, since it is escaped
7715  with <quote>\</quote>), and lastly either <quote>gif</quote>, or
7716  <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
7717  include: <quote>//advert1.jpg</quote>,
7718  <quote>/nasty/ads/advert1234.gif</quote>,
7719  <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
7720  <quote>advert1.gif</quote> (no leading slash), or
7721  <quote>/adverts232.jpg</quote> (the expression does not include an
7722  <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
7723  in the expression anywhere).
7724 </para>
7725
7726 <para>
7727  We are barely scratching the surface of regular expressions here so that you
7728  can understand the default <application>Privoxy</application>
7729  configuration files, and maybe use this knowledge to customize your own
7730  installation. There is much, much more that can be done with regular
7731  expressions. Now that you know enough to get started, you can learn more on
7732  your own :/
7733 </para>
7734
7735 <para>
7736  More reading on Perl Compatible Regular expressions: 
7737  <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
7738 </para>
7739
7740 <para>
7741  For information on regular expression based substitutions and their applications
7742  in filters, please see the <link linkend="filter-file">filter file tutorial</link>
7743  in this manual.
7744 </para>
7745 </sect2>
7746
7747 <!--  ~  End section  ~  -->
7748
7749
7750 <!--   ~~~~~       New section      ~~~~~     -->
7751 <sect2>
7752 <title>Privoxy's Internal Pages</title>
7753
7754 <para>
7755  Since <application>Privoxy</application> proxies each requested 
7756  web page, it is easy for <application>Privoxy</application> to 
7757  trap certain special URLs. In this way, we can talk directly to
7758  <application>Privoxy</application>, and see how it is 
7759  configured, see how our rules are being applied, change these 
7760  rules and other configuration options, and even turn
7761  <application>Privoxy's</application> filtering off, all with 
7762  a web browser.
7763
7764 </para>
7765
7766 <para>
7767  The URLs listed below are the special ones that allow direct access 
7768  to <application>Privoxy</application>. Of course,
7769  <application>Privoxy</application> must be running to access these. If 
7770  not, you will get a friendly error message. Internet access is not 
7771  necessary either.
7772 </para>
7773
7774 <para>
7775  <itemizedlist>
7776
7777  <listitem>
7778   <para>  
7779    Privoxy main page: 
7780   </para>
7781   <blockquote>
7782    <para> 
7783      <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
7784    </para>
7785   </blockquote>
7786   <para>
7787    There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
7788    doesn't provide a fall-back to a real page, in case the request is not
7789    sent through <application>Privoxy</application>)
7790   </para>
7791  </listitem>
7792
7793  <listitem>
7794   <para>  
7795     Show information about the current configuration, including viewing and 
7796     editing of actions files:
7797   </para>
7798    <blockquote>
7799    <para> 
7800     <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
7801    </para>
7802   </blockquote>
7803  </listitem>
7804  
7805  <listitem>
7806   <para>  
7807     Show the source code version numbers:
7808   </para>
7809   <blockquote>
7810    <para> 
7811     <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
7812    </para>
7813   </blockquote>
7814  </listitem>
7815  
7816  <listitem>
7817   <para>  
7818    Show the browser's request headers:
7819   </para>
7820   <blockquote>
7821    <para> 
7822     <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
7823    </para>
7824   </blockquote>
7825  </listitem>
7826  
7827  <listitem>
7828   <para>  
7829    Show which actions apply to a URL and why:
7830   </para>
7831    <blockquote>
7832    <para> 
7833     <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
7834    </para>
7835   </blockquote>
7836  </listitem>
7837  
7838  <listitem>
7839   <para>  
7840    Toggle Privoxy on or off. This feature can be turned off/on in the main 
7841    <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
7842    continues to run, but only as a pass-through proxy, with no actions taking
7843    place:
7844   </para>
7845    <blockquote>
7846    <para> 
7847     <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
7848    </para>
7849   </blockquote>
7850   <para>
7851    Short cuts. Turn off, then on: 
7852   </para>
7853    <blockquote>
7854    <para> 
7855      <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
7856    </para>
7857   </blockquote>
7858    <blockquote>
7859    <para> 
7860      <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
7861    </para>
7862   </blockquote>
7863  </listitem>
7864  
7865  </itemizedlist>
7866 </para>
7867
7868 <para>
7869  These may be bookmarked for quick reference. See next.
7870
7871 </para>
7872
7873 <sect3 id="bookmarklets">
7874 <title>Bookmarklets</title>
7875 <para>
7876  Below are some <quote>bookmarklets</quote> to allow you to easily access a
7877  <quote>mini</quote> version of some of <application>Privoxy's</application>
7878  special pages. They are designed for MS Internet Explorer, but should work
7879  equally well in Netscape, Mozilla, and other browsers which support
7880  JavaScript. They are designed to run directly from your bookmarks - not by
7881  clicking the links below (although that should work for testing).
7882 </para>
7883 <para>
7884  To save them, right-click the link and choose <quote>Add to Favorites</quote>
7885  (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
7886  the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
7887  Bookmarklet directly from your favorites/bookmarks. For even faster access,
7888  you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
7889  Toolbar</quote> (Netscape), and run them with a single click. 
7890 </para>
7891
7892 <para>
7893  <itemizedlist>
7894
7895   <listitem>
7896    <para>
7897     <ulink
7898     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
7899    </para>
7900   </listitem> 
7901
7902   <listitem>
7903    <para>
7904     <ulink
7905     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
7906    </para>
7907   </listitem> 
7908
7909   <listitem>
7910    <para>
7911     <ulink
7912     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&#38;set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
7913    </para>
7914   </listitem> 
7915
7916   <listitem>
7917    <para>
7918     <ulink
7919     url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
7920    </para>
7921   </listitem> 
7922 <!--
7923   <listitem>
7924    <para>
7925     <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
7926    </para>
7927   </listitem> 
7928  --> 
7929   <listitem>
7930    <para>
7931     <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
7932    </para>
7933   </listitem> 
7934  </itemizedlist>
7935 </para>
7936
7937 <para>
7938  Credit: The site which gave us the general idea for these bookmarklets is
7939  <ulink url="http://www.bookmarklets.com/">www.bookmarklets.com</ulink>. They
7940  have more information about bookmarklets. 
7941 </para>
7942
7943
7944 </sect3>
7945
7946 </sect2>
7947
7948
7949 <!--   ~~~~~       New section      ~~~~~     -->
7950 <sect2 id="chain">
7951 <title>Chain of Events</title>
7952 <para>
7953  Let's take a quick look at how some of <application>Privoxy's</application> 
7954  core features are triggered, and the ensuing sequence of events when a web
7955  page is requested by your browser:
7956 </para>
7957
7958 <para>
7959  <itemizedlist>
7960  <listitem>
7961   <para>
7962    First, your web browser requests a web page. The browser knows to send 
7963    the request to <application>Privoxy</application>, which will in turn, 
7964    relay the request to the remote web server after passing the following 
7965    tests: 
7966   </para>
7967  </listitem> 
7968  <listitem>
7969   <para>
7970    <application>Privoxy</application> traps any request for its own internal CGI 
7971    pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
7972   </para>
7973  </listitem> 
7974  <listitem>
7975   <para>
7976    Next, <application>Privoxy</application> checks to see if the URL 
7977    matches any <link
7978    linkend="BLOCK"><quote>+block</quote></link> patterns. If
7979    so, the URL is then blocked, and the remote web server will not be contacted.
7980    <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link> 
7981    and 
7982    <link linkend="HANDLE-AS-EMPTY-DOCUMENT"><quote>+handle-as-empty-document</quote></link>
7983    are then checked, and if there is no match, an 
7984    HTML <quote>BLOCKED</quote> page is sent back to the browser. Otherwise, if
7985    it does match, an image is returned for the former, and an empty text
7986    document for the latter. The type of image would depend on the setting of
7987    <link linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
7988    (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
7989   </para>
7990  </listitem> 
7991  <listitem>
7992   <para>
7993    Untrusted URLs are blocked. If URLs are being added to the
7994    <filename>trust</filename> file, then that is done.
7995   </para>
7996  </listitem> 
7997  <listitem>
7998   <para>
7999    If the URL pattern matches the <link
8000    linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
8001    it is then processed. Unwanted parts of the requested URL are stripped.
8002   </para>
8003  </listitem> 
8004  <listitem>
8005   <para>
8006    Now the rest of the client browser's request headers are processed. If any
8007    of these match any of the relevant actions (e.g. <link
8008    linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
8009    etc.), headers are suppressed or forged as determined by these actions and
8010    their parameters.
8011   </para>
8012  </listitem> 
8013  <listitem>
8014   <para>
8015    Now the web server starts sending its response back (i.e. typically a web
8016    page).
8017   </para>
8018  </listitem> 
8019  <listitem>
8020   <para>
8021    First, the server headers are read and processed to determine, among other
8022    things, the MIME type (document type) and encoding. The headers are then
8023    filtered as determined by the 
8024    <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
8025    <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
8026    and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
8027    actions.
8028   </para>
8029  </listitem> 
8030  <listitem>
8031   <para>
8032    If any <link linkend="FILTER"><quote>+filter</quote></link> action
8033    or <link
8034    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
8035    action applies (and the document type fits the action), the rest of the page is
8036    read into memory (up to a configurable limit). Then the filter rules (from
8037    <filename>default.filter</filename> and any other filter files) are
8038    processed against the buffered content. Filters are applied in the order
8039    they are specified in one of the filter files. Animated GIFs, if present,
8040    are reduced to either the first or last frame, depending on the action
8041    setting.The entire page, which is now filtered, is then sent by
8042    <application>Privoxy</application> back to your browser. 
8043   </para>
8044   <para>
8045    If neither a <link linkend="FILTER"><quote>+filter</quote></link> action
8046    or <link
8047    linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
8048    matches, then <application>Privoxy</application> passes the raw data through 
8049    to the client browser as it becomes available.
8050   </para>
8051  </listitem> 
8052  <listitem>
8053   <para>
8054    As the browser receives the now (possibly filtered) page content, it 
8055    reads and then requests any URLs that may be embedded within the page
8056    source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
8057    frames), sounds, etc. For each of these objects, the browser issues a
8058    separate request (this is easily viewable in <application>Privoxy's</application>
8059    logs). And each such request is in turn processed just as above. Note that a
8060    complex web page will have many, many such embedded URLs. If these 
8061    secondary requests are to a different server, then quite possibly a very 
8062    differing set of actions is triggered.
8063   </para>
8064  </listitem> 
8065  
8066  </itemizedlist>
8067 </para>
8068 <para>
8069  NOTE: This is somewhat of a simplistic overview of what happens with each URL
8070  request. For the sake of brevity and simplicity, we have focused on 
8071  <application>Privoxy's</application> core features only.
8072 </para>
8073
8074 </sect2>
8075
8076
8077 <!--   ~~~~~       New section      ~~~~~     -->
8078 <sect2 id="actionsanat">
8079 <title>Troubleshooting: Anatomy of an Action</title>
8080
8081 <para>
8082  The way <application>Privoxy</application> applies 
8083  <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
8084  to any given URL can be complex, and not always so
8085  easy to understand what is happening. And sometimes we need to be able to
8086  <emphasis>see</emphasis> just what <application>Privoxy</application> is
8087  doing. Especially, if something <application>Privoxy</application> is doing
8088  is causing us a problem inadvertently. It can be a little daunting to look at
8089  the actions and filters files themselves, since they tend to be filled with
8090  <link linkend="regex">regular expressions</link> whose consequences are not
8091  always so obvious. 
8092 </para>
8093
8094 <para>
8095  One quick test to see if <application>Privoxy</application> is causing a problem 
8096  or not, is to disable it temporarily. This should be the first troubleshooting 
8097  step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick 
8098  and easy way to do this (be sure to flush caches afterward!). Looking at the 
8099  logs is a good idea too. (Note that both the toggle feature and logging are 
8100  enabled via <filename>config</filename> file settings, and may need to be 
8101  turned <quote>on</quote>.)
8102 </para>
8103 <para>
8104  Another easy troubleshooting step to try is if you have done any
8105  customization of your installation, revert back to the installed
8106  defaults and see if that helps. There are times the developers get complaints
8107  about one thing or another, and the problem is more related to a customized
8108  configuration issue.
8109 </para>
8110
8111 <para>
8112  <application>Privoxy</application> also provides the 
8113  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
8114  page that can show us very specifically how <application>actions</application>
8115  are being applied to any given URL. This is a big help for troubleshooting.
8116 </para>
8117
8118 <para>
8119  First, enter one URL (or partial URL) at the prompt, and then
8120  <application>Privoxy</application> will tell us 
8121  how the current configuration will handle it. This will not
8122  help with filtering effects (i.e. the <link
8123  linkend="FILTER"><quote>+filter</quote></link> action) from
8124  one of the filter files since this is handled very
8125  differently and not so easy to trap! It also will not tell you about any other
8126  URLs that may be embedded within the URL you are testing. For instance, images
8127  such as ads are expressed as URLs within the raw page source of HTML pages. So
8128  you will only get info for the actual URL that is pasted into the prompt area
8129  -- not any sub-URLs. If you want to know about embedded URLs like ads, you
8130  will have to dig those out of the HTML source. Use your browser's <quote>View
8131  Page Source</quote> option for this. Or right click on the ad, and grab the
8132  URL.
8133 </para>
8134
8135 <para>
8136  Let's try an example, <ulink url="http://google.com">google.com</ulink>, 
8137  and look at it one section at a time in a sample configuration (your real 
8138  configuration may vary):
8139 </para>
8140
8141 <para>
8142  <screen>
8143  Matches for http://www.google.com:
8144
8145  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8146
8147  {+change-x-forwarded-for{block}
8148  +deanimate-gifs {last}
8149  +fast-redirects {check-decoded-url}
8150  +filter {refresh-tags}
8151  +filter {img-reorder}
8152  +filter {banners-by-size}
8153  +filter {webbugs}
8154  +filter {jumping-windows}
8155  +filter {ie-exploits}
8156  +hide-from-header {block}
8157  +hide-referrer {forge}
8158  +session-cookies-only
8159  +set-image-blocker {pattern}
8160 /
8161  
8162  { -session-cookies-only }
8163  .google.com
8164
8165  { -fast-redirects }
8166  .google.com
8167
8168 In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8169 (no matches in this file)  
8170 </screen>
8171 </para>
8172
8173 <para>
8174  This is telling us how we have defined our 
8175  <link linkend="ACTIONS"><quote>actions</quote></link>, and
8176  which ones match for our test case, <quote>google.com</quote>. 
8177  Displayed is all the actions that are available to us. Remember,
8178  the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
8179  denotes <quote>off</quote>. So some are <quote>on</quote> here, but many 
8180  are <quote>off</quote>. Each example we try may provide a slightly different
8181  end result, depending on our configuration directives.
8182 </para>
8183 <para>
8184  The first listing
8185   is for our <filename>default.action</filename> file. The large, multi-line
8186   listing, is how the actions are set to match for all URLs, i.e. our default
8187   settings. If you look at your <quote>actions</quote> file, this would be the
8188   section just below the <quote>aliases</quote> section near the top. This
8189   will apply to all URLs as signified by the single forward slash at the end
8190   of the listing -- <quote> / </quote>.
8191 </para>
8192
8193 <para>
8194  But we have defined additional actions that would be exceptions to these general
8195  rules, and then we list specific URLs (or patterns) that these exceptions
8196  would apply to. Last match wins. Just below this then are two explicit
8197  matches for <quote>.google.com</quote>. The first is negating our previous
8198  cookie setting, which was for <link
8199  linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
8200  (i.e. not persistent). So we will allow persistent cookies for google, at
8201  least that is how it is in this example. The second turns
8202  <emphasis>off</emphasis> any <link
8203  linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
8204  action, allowing this to take place unmolested. Note that there is a leading
8205  dot here -- <quote>.google.com</quote>. This will match any hosts and
8206  sub-domains, in the google.com domain also, such as
8207  <quote>www.google.com</quote> or <quote>mail.google.com</quote>. But it would not 
8208  match <quote>www.google.de</quote>! So, apparently, we have these two actions
8209  defined as exceptions to the general rules at the top somewhere in the lower
8210  part of our <filename>default.action</filename> file, and
8211  <quote>google.com</quote> is referenced somewhere in these latter sections.
8212 </para>
8213
8214 <para>
8215  Then, for our <filename>user.action</filename> file, we again have no hits.
8216  So there is nothing google-specific that we might have added to our own, local
8217  configuration. If there was, those actions would over-rule any actions from 
8218  previously processed files, such as <filename>default.action</filename>.
8219  <filename>user.action</filename> typically has the last word. This is the
8220  best place to put hard and fast exceptions,
8221 </para>
8222
8223 <para>
8224  And finally we pull it all together in the bottom section and summarize how
8225  <application>Privoxy</application> is applying all its <quote>actions</quote> 
8226  to <quote>google.com</quote>:
8227
8228 </para>
8229
8230 <para>
8231  <screen>
8232
8233  Final results:
8234  
8235  -add-header
8236  -block
8237  +change-x-forwarded-for{block} 
8238  -client-header-filter{hide-tor-exit-notation}
8239  -content-type-overwrite
8240  -crunch-client-header
8241  -crunch-if-none-match
8242  -crunch-incoming-cookies
8243  -crunch-outgoing-cookies
8244  -crunch-server-header
8245  +deanimate-gifs {last}
8246  -downgrade-http-version
8247  -fast-redirects
8248  -filter {js-events}
8249  -filter {content-cookies}
8250  -filter {all-popups}
8251  -filter {banners-by-link}
8252  -filter {tiny-textforms}
8253  -filter {frameset-borders}
8254  -filter {demoronizer}
8255  -filter {shockwave-flash}
8256  -filter {quicktime-kioskmode}
8257  -filter {fun}
8258  -filter {crude-parental}
8259  -filter {site-specifics}
8260  -filter {js-annoyances}
8261  -filter {html-annoyances}
8262  +filter {refresh-tags}
8263  -filter {unsolicited-popups}
8264  +filter {img-reorder}
8265  +filter {banners-by-size}
8266  +filter {webbugs}
8267  +filter {jumping-windows}
8268  +filter {ie-exploits}
8269  -filter {google}
8270  -filter {yahoo}
8271  -filter {msn}
8272  -filter {blogspot}
8273  -filter {no-ping}
8274  -force-text-mode
8275  -handle-as-empty-document
8276  -handle-as-image
8277  -hide-accept-language
8278  -hide-content-disposition
8279  +hide-from-header {block}
8280  -hide-if-modified-since
8281  +hide-referrer {forge}
8282  -hide-user-agent
8283  -limit-connect
8284  -overwrite-last-modified
8285  -prevent-compression
8286  -redirect
8287  -server-header-filter{xml-to-html}
8288  -server-header-filter{html-to-xml} 
8289  -session-cookies-only
8290  +set-image-blocker {pattern} </screen>
8291 </para>
8292
8293 <para>
8294  Notice the only difference here to the previous listing, is to 
8295  <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
8296  which are activated specifically for this site in our configuration, 
8297  and thus show in the <quote>Final Results</quote>.
8298 </para>
8299
8300 <para>
8301  Now another example, <quote>ad.doubleclick.net</quote>:
8302 </para>
8303
8304 <para>
8305  <screen>
8306
8307  { +block{Domains starts with "ad"} }
8308   ad*.
8309
8310  { +block{Domain contains "ad"} }
8311   .ad.
8312
8313  { +block{Doubleclick banner server} +handle-as-image }
8314   .[a-vx-z]*.doubleclick.net
8315 </screen>
8316 </para>
8317
8318 <para>
8319  We'll just show the interesting part here - the explicit matches. It is 
8320  matched three different times. Two <quote>+block{}</quote> sections, 
8321  and a <quote>+block{} +handle-as-image</quote>,
8322  which is the expanded form of one of our aliases that had been defined as: 
8323  <quote>+block-as-image</quote>. (<link
8324  linkend="ALIASES"><quote>Aliases</quote></link> are defined in
8325  the first section of the actions file and typically used to combine more 
8326  than one action.)
8327 </para>
8328
8329 <para>
8330  Any one of these would have done the trick and blocked this as an unwanted 
8331  image. This is unnecessarily redundant since the last case effectively 
8332  would also cover the first. No point in taking chances with these guys 
8333  though ;-) Note that if you want an ad or obnoxious 
8334  URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
8335  is done here -- as both a <link
8336  linkend="BLOCK"><quote>+block{}</quote></link>
8337  <emphasis>and</emphasis> an 
8338  <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
8339  The custom alias <quote><literal>+block-as-image</literal></quote> just
8340  simplifies the process and make it more readable.
8341 </para>
8342
8343 <para>
8344  One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
8345  This one is giving us problems. We are getting a blank page. Hmmm ...
8346 </para>
8347
8348 <para>
8349  <screen>
8350
8351  Matches for http://www.example.net/adsl/HOWTO/:
8352
8353  In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
8354
8355  {-add-header 
8356   -block
8357   +change-x-forwarded-for{block} 
8358   -client-header-filter{hide-tor-exit-notation}
8359   -content-type-overwrite
8360   -crunch-client-header
8361   -crunch-if-none-match
8362   -crunch-incoming-cookies
8363   -crunch-outgoing-cookies
8364   -crunch-server-header
8365   +deanimate-gifs 
8366   -downgrade-http-version 
8367   +fast-redirects {check-decoded-url}
8368   -filter {js-events}
8369   -filter {content-cookies}
8370   -filter {all-popups}
8371   -filter {banners-by-link}
8372   -filter {tiny-textforms}
8373   -filter {frameset-borders}
8374   -filter {demoronizer}
8375   -filter {shockwave-flash}
8376   -filter {quicktime-kioskmode}
8377   -filter {fun}
8378   -filter {crude-parental}
8379   -filter {site-specifics}
8380   -filter {js-annoyances}
8381   -filter {html-annoyances}
8382   +filter {refresh-tags}
8383   -filter {unsolicited-popups}
8384   +filter {img-reorder}
8385   +filter {banners-by-size}
8386   +filter {webbugs}
8387   +filter {jumping-windows}
8388   +filter {ie-exploits}
8389   -filter {google}
8390   -filter {yahoo}
8391   -filter {msn}
8392   -filter {blogspot}
8393   -filter {no-ping}
8394   -force-text-mode
8395   -handle-as-empty-document
8396   -handle-as-image 
8397   -hide-accept-language
8398   -hide-content-disposition  
8399   +hide-from-header{block} 
8400   +hide-referer{forge} 
8401   -hide-user-agent 
8402   -overwrite-last-modified
8403   +prevent-compression 
8404   -redirect
8405   -server-header-filter{xml-to-html}
8406   -server-header-filter{html-to-xml} 
8407   +session-cookies-only 
8408   +set-image-blocker{blank} }
8409    /
8410
8411  { +block{Path contains "ads".} +handle-as-image }
8412   /ads
8413 </screen>
8414 </para>
8415
8416 <para>
8417  Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our 
8418  configuration! But we did not want this at all! Now we see why we get the
8419  blank page. It is actually triggering two different actions here, and 
8420  the effects are aggregated so that the URL is blocked, and &my-app; is told 
8421  to treat the block as if it were an image. But this is, of course, all wrong.
8422   We could now add a new action below this (or better in our own
8423   <filename>user.action</filename> file) that explicitly
8424   <emphasis>un</emphasis> blocks (
8425   <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
8426   <quote>adsl</quote> in them (remember, last match in the configuration
8427   wins). There are various ways to handle such exceptions. Example:
8428 </para>
8429
8430 <para>
8431  <screen>
8432
8433  { -block }
8434   /adsl
8435 </screen>
8436 </para>
8437
8438 <para>
8439  Now the page displays ;-) 
8440  Remember to flush your browser's caches when making these kinds of changes to
8441  your configuration to insure that you get a freshly delivered page! Or, try
8442  using <literal>Shift+Reload</literal>.
8443 </para>
8444
8445 <para>
8446  But now what about a situation where we get no explicit matches like 
8447  we did with:
8448 </para>
8449
8450 <para>
8451  <screen>
8452
8453  { +block{Path starts with "ads".} +handle-as-image }
8454  /ads
8455 </screen>
8456 </para>
8457
8458 <para>
8459  That actually was very helpful and pointed us quickly to where the problem
8460  was. If you don't get this kind of match, then it means one of the default 
8461  rules in the first section of <filename>default.action</filename> is causing
8462  the problem. This would require some guesswork, and maybe a little trial and
8463  error to isolate the offending rule. One likely cause would be one of the
8464  <link linkend="FILTER"><quote>+filter</quote></link> actions.
8465  These tend to be harder to troubleshoot.
8466  Try adding the URL for the site to one of aliases that turn off
8467  <link linkend="FILTER"><quote>+filter</quote></link>:
8468 </para>
8469
8470 <para>
8471  <screen>
8472
8473  { shop }
8474  .quietpc.com
8475  .worldpay.com   # for quietpc.com
8476  .jungle.com
8477  .scan.co.uk
8478  .forbes.com
8479 </screen>
8480 </para>
8481
8482 <para>
8483  <quote><literal>{ shop }</literal></quote> is an <quote>alias</quote> that expands to 
8484  <quote><literal>{ -filter -session-cookies-only }</literal></quote>.
8485  Or you could do your own exception to negate filtering:
8486
8487 </para>
8488
8489 <para>
8490  <screen>
8491
8492  { -filter }
8493  # Disable ALL filter actions for sites in this section
8494  .forbes.com
8495  developer.ibm.com
8496  localhost
8497 </screen>
8498 </para>
8499
8500 <para>
8501  This would turn off all filtering for these sites. This is best
8502  put in <filename>user.action</filename>, for local site
8503  exceptions. Note that when a simple domain pattern is used by itself (without
8504  the subsequent path portion), all sub-pages within that domain are included 
8505  automatically in the scope of the action.
8506 </para>
8507
8508 <para>
8509  Images that are inexplicably being blocked, may well be hitting the 
8510 <link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
8511  rule, which assumes 
8512  that images of certain sizes are ad banners (works well 
8513  <emphasis>most of the time</emphasis>  since these tend to be standardized).
8514 </para>
8515
8516 <para>
8517  <quote><literal>{ fragile }</literal></quote> is an alias that disables most
8518  actions that are the most likely to cause trouble. This can be used as a
8519  last resort for problem sites. 
8520 </para> 
8521 <para>
8522  <screen>
8523
8524  { fragile }
8525  # Handle with care: easy to break
8526  mail.google.
8527  mybank.example.com</screen>
8528 </para>
8529  
8530
8531 <para>
8532  <emphasis>Remember to flush caches!</emphasis> Note that the 
8533  <literal>mail.google</literal> reference lacks the TLD portion (e.g. 
8534  <quote>.com</quote>). This will effectively match any TLD with 
8535  <literal>google</literal> in it, such as <literal>mail.google.de.</literal>, 
8536  just as an example.
8537 </para>
8538 <para> 
8539  If this still does not work, you will have to go through the remaining
8540  actions one by one to find which one(s) is causing the problem.
8541 </para>
8542
8543 </sect2>
8544
8545 </sect1>
8546
8547  <!--
8548
8549  This program is free software; you can redistribute it 
8550  and/or modify it under the terms of the GNU General
8551  Public License as published by the Free Software
8552  Foundation; either version 2 of the License, or (at
8553  your option) any later version.
8554
8555  This program is distributed in the hope that it will
8556  be useful, but WITHOUT ANY WARRANTY; without even the
8557  implied warranty of MERCHANTABILITY or FITNESS FOR A
8558  PARTICULAR PURPOSE.  See the GNU General Public
8559  License for more details.
8560
8561  The GNU General Public License should be included with
8562  this file.  If not, you can view it at
8563  http://www.gnu.org/copyleft/gpl.html
8564  or write to the Free Software Foundation, Inc., 
8565  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 
8566  USA
8567
8568  $Log: user-manual.sgml,v $
8569  Revision 2.110  2009/07/18 16:25:17  fabiankeil
8570  Fix trailing whitespace.
8571
8572  Revision 2.109  2009/07/18 16:24:39  fabiankeil
8573  Bump entities for 3.0.14 beta.
8574
8575  Revision 2.108  2009/07/18 15:49:23  fabiankeil
8576  Add most of the changes in 3.0.14 to the "What's New" section.
8577
8578  Revision 2.107  2009/06/12 14:30:58  fabiankeil
8579  Update entities for 3.0.13 beta.
8580
8581  Revision 2.106  2009/06/12 11:04:13  fabiankeil
8582  Import ChangeLog for 3.0.13 beta.
8583
8584  Revision 2.105  2009/04/17 11:32:57  fabiankeil
8585  Grammar and spelling fixes.
8586
8587  Revision 2.104  2009/04/17 11:27:49  fabiankeil
8588  Petr Pisar's privoxy-3.0.12-ipv6-3.diff.
8589
8590  Revision 2.103  2009/03/21 10:49:05  fabiankeil
8591  Merge updated ChangeLog.
8592
8593  Revision 2.102  2009/03/15 19:31:36  fabiankeil
8594  Update "What's New in this Release" section.
8595
8596  Revision 2.101  2009/02/25 19:01:56  fabiankeil
8597  Fix typo.
8598
8599  Revision 2.100  2009/02/19 17:14:11  fabiankeil
8600  - Copy the release cycle description from announce.txt into
8601    the "What's New" section.
8602  - Stop referring to the ChangeLog for a "complete list of changes".
8603    The "What's New" section already contains the complete list.
8604
8605  Revision 2.99  2009/02/19 02:20:22  hal9
8606  Make some links in seealso conditional. Man page is now privoxy only links.
8607
8608  Revision 2.98  2009/02/16 17:10:33  fabiankeil
8609  Fix entry about shortened log messages. Noticed by Lee.
8610
8611  Revision 2.97  2009/02/14 18:01:00  fabiankeil
8612  Import ChangeLog.
8613
8614  Revision 2.96  2009/02/14 13:14:03  fabiankeil
8615  Unbreak syntax.
8616
8617  Revision 2.95  2009/02/14 12:51:26  fabiankeil
8618  Mention match-all.action in the "Actions Files Tutorial" section.
8619
8620  Revision 2.94  2009/02/14 11:50:31  fabiankeil
8621  Some indentation fixes.
8622
8623  Revision 2.93  2009/02/14 10:14:42  fabiankeil
8624  Mention match-all.action in the action file descriptions.
8625
8626  Revision 2.92  2009/02/12 16:08:26  fabiankeil
8627  Declare the code stable.
8628
8629  Revision 2.91  2009/01/13 16:50:35  fabiankeil
8630  The standard.action file is gone.
8631
8632  Revision 2.90  2008/09/26 16:53:09  fabiankeil
8633  Update "What's new" section.
8634
8635  Revision 2.89  2008/09/21 15:38:56  fabiankeil
8636  Fix Portage tree sync instructions in Gentoo section.
8637  Anonymously reported at ijbswa-developers@.
8638
8639  Revision 2.88  2008/09/21 14:42:52  fabiankeil
8640  Add documentation for change-x-forwarded-for{},
8641  remove documentation for hide-forwarded-for-headers.
8642
8643  Revision 2.87  2008/08/30 15:37:35  fabiankeil
8644  Update entities.
8645
8646  Revision 2.86  2008/08/16 10:12:23  fabiankeil
8647  Merge two sentences and move the URL to the end of the item.
8648
8649  Revision 2.85  2008/08/16 10:04:59  fabiankeil
8650  Some more syntax fixes. This version actually builds.
8651
8652  Revision 2.84  2008/08/16 09:42:45  fabiankeil
8653  Turns out building docs works better if the syntax is valid.
8654
8655  Revision 2.83  2008/08/16 09:32:02  fabiankeil
8656  Mention changes since 3.0.9 beta.
8657
8658  Revision 2.82  2008/08/16 09:00:52  fabiankeil
8659  Fix example URL pattern (once more with feeling).
8660
8661  Revision 2.81  2008/08/16 08:51:28  fabiankeil
8662  Update version-related entities.
8663
8664  Revision 2.80  2008/07/18 16:54:30  fabiankeil
8665  Remove erroneous whitespace in documentation link.
8666  Reported by John Chronister in #2021611.
8667
8668  Revision 2.79  2008/06/27 18:00:53  markm68k
8669  remove outdated startup information for mac os x
8670
8671  Revision 2.78  2008/06/21 17:03:03  fabiankeil
8672  Fix typo.
8673
8674  Revision 2.77  2008/06/14 13:45:22  fabiankeil
8675  Re-add a colon I unintentionally removed a few revisions ago.
8676
8677  Revision 2.76  2008/06/14 13:21:28  fabiankeil
8678  Prepare for the upcoming 3.0.9 beta release.
8679
8680  Revision 2.75  2008/06/13 16:06:48  fabiankeil
8681  Update the "What's New in this Release" section with
8682  the ChangeLog entries changelog2doc.pl could handle.
8683
8684  Revision 2.74  2008/05/26 15:55:46  fabiankeil
8685  - Update "default profiles" table.
8686  - Add some more pcrs redirect examples and note that
8687    enabling debug 128 helps to get redirects working.
8688
8689  Revision 2.73  2008/05/23 14:43:18  fabiankeil
8690  Remove previously out-commented block that caused syntax problems.
8691
8692  Revision 2.72  2008/05/12 10:26:14  fabiankeil
8693  Synchronize content filter descriptions with the ones in default.filter.
8694
8695  Revision 2.71  2008/04/10 17:37:16  fabiankeil
8696  Actually we use "modern" POSIX 1003.2 regular
8697  expressions in path patterns, not PCRE.
8698
8699  Revision 2.70  2008/04/10 15:59:12  fabiankeil
8700  Add another section to the client-header-tagger example that shows
8701  how to actually change the action settings once the tag is created.
8702
8703  Revision 2.69  2008/03/29 12:14:25  fabiankeil
8704  Remove send-wafer and send-vanilla-wafer actions.
8705
8706  Revision 2.68  2008/03/28 15:13:43  fabiankeil
8707  Remove inspect-jpegs action.
8708
8709  Revision 2.67  2008/03/27 18:31:21  fabiankeil
8710  Remove kill-popups action.
8711
8712  Revision 2.66  2008/03/06 16:33:47  fabiankeil
8713  If limit-connect isn't used, don't limit CONNECT requests to port 443.
8714
8715  Revision 2.65  2008/03/04 18:30:40  fabiankeil
8716  Remove the treat-forbidden-connects-like-blocks action. We now
8717  use the "blocked" page for forbidden CONNECT requests by default.
8718
8719  Revision 2.64  2008/03/01 14:10:28  fabiankeil
8720  Use new block syntax. Still needs some polishing.
8721
8722  Revision 2.63  2008/02/22 05:50:37  markm68k
8723  fix merge problem
8724
8725  Revision 2.62  2008/02/11 11:52:23  hal9
8726  Fix entity ... s/&/&amp;
8727
8728  Revision 2.61  2008/02/11 03:41:47  markm68k
8729  more updates for mac os x
8730
8731  Revision 2.60  2008/02/11 03:40:25  markm68k
8732  more updates for mac os x
8733
8734  Revision 2.59  2008/02/11 00:52:34  markm68k
8735  reflect new changes for mac os x
8736
8737  Revision 2.58  2008/02/03 21:37:40  hal9
8738  Apply patch from Mark: s/OSX/OS X/
8739
8740  Revision 2.57  2008/02/03 19:10:14  fabiankeil
8741  Mention forward-socks5.
8742
8743  Revision 2.56  2008/01/31 19:11:35  fabiankeil
8744  Let the +client-header-filter{hide-tor-exit-notation} example apply
8745  to all requests as "tainted" Referers aren't limited to exit TLDs.
8746
8747  Revision 2.55  2008/01/19 21:26:37  hal9
8748  Add IE7 to configuration section per Gerry.
8749
8750  Revision 2.54  2008/01/19 17:52:39  hal9
8751  Re-commit to fix various minor issues for new release.
8752
8753  Revision 2.53  2008/01/19 15:03:05  hal9
8754  Doc sources tagged for 3.0.8 release.
8755
8756  Revision 2.52  2008/01/17 01:49:51  hal9
8757  Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon
8758  enough.
8759
8760  Revision 2.51  2007/12/23 16:48:24  fabiankeil
8761  Use more precise example descriptions for the mysterious domain patterns.
8762
8763  Revision 2.50  2007/12/08 12:44:36  fabiankeil
8764  - Remove already commented out pre-3.0.7 changes.
8765  - Update the "new log defaults" paragraph.
8766
8767  Revision 2.49  2007/12/06 18:21:55  fabiankeil
8768  Update hide-forwarded-for-headers description.
8769
8770  Revision 2.48  2007/11/24 19:07:17  fabiankeil
8771  - Mention request rewriting.
8772  - Enable the conditional-forge paragraph.
8773  - Minor rewordings.
8774
8775  Revision 2.47  2007/11/18 14:59:47  fabiankeil
8776  A few "Note to Upgraders" updates.
8777
8778  Revision 2.46  2007/11/17 17:24:44  fabiankeil
8779  - Use new action defaults.
8780  - Minor fixes and rewordings.
8781
8782  Revision 2.45  2007/11/16 11:48:46  hal9
8783  Fix one typo, and add a couple of small refinements.
8784
8785  Revision 2.44  2007/11/15 03:30:20  hal9
8786  Results of spell check.
8787
8788  Revision 2.43  2007/11/14 18:45:39  fabiankeil
8789  - Mention some more contributors in the "New in this Release" list.
8790  - Minor rewordings.
8791
8792  Revision 2.42  2007/11/12 03:32:40  hal9
8793  Updates for "What's New" and "Notes to Upgraders". Various other changes in
8794  preparation for new release. User Manual is almost ready.
8795
8796  Revision 2.41  2007/11/11 16:32:11  hal9
8797  This is primarily syncing What's New and Note to Upgraders sections with the many
8798  new features and changes (gleaned from memory but mostly from ChangeLog).
8799
8800  Revision 2.40  2007/11/10 17:10:59  fabiankeil
8801  In the first third of the file, mention several times that
8802  the action editor is disabled by default in 3.0.7 beta and later.
8803
8804  Revision 2.39  2007/11/05 02:34:49  hal9
8805  Various changes in preparation for the upcoming release. Much yet to be done.
8806
8807  Revision 2.38  2007/09/22 16:01:42  fabiankeil
8808  Update embedded show-url-info output.
8809
8810  Revision 2.37  2007/08/27 16:09:55  fabiankeil
8811  Fix pre-chroot-nslookup description which I failed to
8812  copy and paste properly. Reported by Stephen Gildea.
8813
8814  Revision 2.36  2007/08/26 16:47:14  fabiankeil
8815  Add Stephen Gildea's pre-chroot-nslookup patch [#1276666],
8816  extensive comments moved to user manual.
8817
8818  Revision 2.35  2007/08/26 14:59:49  fabiankeil
8819  Minor rewordings and fixes.
8820
8821  Revision 2.34  2007/08/05 15:19:50  fabiankeil
8822  - Don't claim HTTP/1.1 compliance.
8823  - Use $ in some of the path pattern examples.
8824  - Use a hide-user-agent example argument without
8825    leading and trailing space.
8826  - Make it clear that the cookie actions work with
8827    HTTP cookies only.
8828  - Rephrase the inspect-jpegs text to underline
8829    that it's only meant to protect against a single
8830    exploit.
8831
8832  Revision 2.33  2007/07/27 10:57:35  hal9
8833  Add references for user-agent strings for hide-user-agenet
8834
8835  Revision 2.32  2007/06/07 12:36:22  fabiankeil
8836  Apply Roland's 29_usermanual.dpatch to fix a bunch
8837  of syntax errors I collected over the last months.
8838
8839  Revision 2.31  2007/06/02 14:01:37  fabiankeil
8840  Start to document forward-override{}.
8841
8842  Revision 2.30  2007/04/25 15:10:36  fabiankeil
8843  - Describe installation for FreeBSD.
8844  - Start to document taggers and tag patterns.
8845  - Don't confuse devils and daemons.
8846
8847  Revision 2.29  2007/04/05 11:47:51  fabiankeil
8848  Some updates regarding header filtering,
8849  handling of compressed content and redirect's
8850  support for pcrs commands.
8851
8852  Revision 2.28  2006/12/10 23:42:48  hal9
8853  Fix various typos reported by Adam P. Thanks.
8854
8855  Revision 2.27  2006/11/14 01:57:47  hal9
8856  Dump all docs prior to 3.0.6 release. Various minor changes to faq and user
8857  manual.
8858
8859  Revision 2.26  2006/10/24 11:16:44  hal9
8860  Add new filters.
8861
8862  Revision 2.25  2006/10/18 10:50:33  hal9
8863  Add note that since filters are off in Cautious, compression is ON. Turn off
8864  compression to make filters work on all sites.
8865
8866  Revision 2.24  2006/10/03 11:13:54  hal9
8867  More references to the new filters. Include html this time around.
8868
8869  Revision 2.23  2006/10/02 22:43:53  hal9
8870  Contains new filter definitions from Fabian, and few other miscellaneous
8871  touch-ups.
8872
8873  Revision 2.22  2006/09/22 01:27:55  hal9
8874  Final commit of probably various minor changes here and there. Unless
8875  something changes this should be ready for pending release.
8876
8877  Revision 2.21  2006/09/20 03:21:36  david__schmidt
8878  Just the tiniest tweak.  Wafer thin!
8879
8880  Revision 2.20  2006/09/10 14:53:54  hal9
8881  Results of spell check. User manual has some updates to standard.actions file
8882  info.
8883
8884  Revision 2.19  2006/09/08 12:19:02  fabiankeil
8885  Adjust hide-if-modified-since example values
8886  to reflect the recent changes.
8887
8888  Revision 2.18  2006/09/08 02:38:57  hal9
8889  Various changes:
8890   -Fix a number of broken links.
8891   -Migrate the new Windows service command line options, and reference as
8892    needed.
8893   -Rebuild so that can be used with the new "user-manual" config capabilities.
8894   -Etc.
8895
8896  Revision 2.17  2006/09/05 13:25:12  david__schmidt
8897  Add Windows service invocation stuff (duplicated) in FAQ and in user manual under Windows startup.  One probably ought to reference the other.
8898
8899  Revision 2.16  2006/09/02 12:49:37  hal9
8900  Various small updates for new actions, filterfiles, etc.
8901
8902  Revision 2.15  2006/08/30 11:15:22  hal9
8903  More work on the new actions, especially filter-*-headers, and What's New
8904  section. User Manual is close to final form for 3.0.4 release. Some tinkering
8905  and proof reading left to do.
8906
8907  Revision 2.14  2006/08/29 10:59:36  hal9
8908  Add a "Whats New in this release" Section. Further work on multiple filter
8909  files, and assorted other minor changes.
8910
8911  Revision 2.13  2006/08/22 11:04:59  hal9
8912  Silence warnings and errors. This should build now. New filters were only
8913  stubbed in. More to be done.
8914
8915  Revision 2.12  2006/08/14 08:40:39  fabiankeil
8916  Documented new actions that were part of
8917  the "minor Privoxy improvements".
8918
8919  Revision 2.11  2006/07/18 14:48:51  david__schmidt
8920  Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch)
8921  with what was really the latest development (the v_3_0_branch branch)
8922
8923  Revision 1.123.2.43  2005/05/23 09:59:10  hal9
8924  Fix typo 'loose'
8925
8926  Revision 1.123.2.42  2004/12/04 14:39:57  hal9
8927  Fix two minor typos per bug SF report.
8928
8929  Revision 1.123.2.41  2004/03/23 12:58:42  oes
8930  Fixed an inaccuracy
8931
8932  Revision 1.123.2.40  2004/02/27 12:48:49  hal9
8933  Add comment re: redirecting to local file system for set-image-blocker may
8934  is dependent on browser.
8935
8936  Revision 1.123.2.39  2004/01/30 22:31:40  oes
8937  Added a hint re bookmarklets to Quickstart section
8938
8939  Revision 1.123.2.38  2004/01/30 16:47:51  oes
8940  Some minor clarifications
8941
8942  Revision 1.123.2.37  2004/01/29 22:36:11  hal9
8943  Updates for no longer filtering text/plain, and demoronizer default settings,
8944  and copyright notice dates.
8945
8946  Revision 1.123.2.36  2003/12/10 02:26:26  hal9
8947  Changed the demoronizer filter description.
8948
8949  Revision 1.123.2.35  2003/11/06 13:36:37  oes
8950  Updated link to nightly CVS tarball
8951
8952  Revision 1.123.2.34  2003/06/26 23:50:16  hal9
8953  Add a small bit on filtering and problems re: source code being corrupted.
8954
8955  Revision 1.123.2.33  2003/05/08 18:17:33  roro
8956  Use apt-get instead of dpkg to install Debian package, which is more
8957  solid, uses the correct and most recent Debian version automatically.
8958
8959  Revision 1.123.2.32  2003/04/11 03:13:57  hal9
8960  Add small note about only one filterfile (as opposed to multiple actions
8961  files).
8962
8963  Revision 1.123.2.31  2003/03/26 02:03:43  oes
8964  Updated hard-coded copyright dates
8965
8966  Revision 1.123.2.30  2003/03/24 12:58:56  hal9
8967  Add new section on Predefined Filters.
8968
8969  Revision 1.123.2.29  2003/03/20 02:45:29  hal9
8970  More problems with \-\-chroot causing markup problems :(
8971
8972  Revision 1.123.2.28  2003/03/19 00:35:24  hal9
8973  Manual edit of revision log because 'chroot' (even inside a comment) was
8974  causing Docbook to hang here (due to double hyphen and the processor thinking
8975  it was a comment).
8976
8977  Revision 1.123.2.27  2003/03/18 19:37:14  oes
8978  s/Advanced|Radical/Adventuresome/g to avoid complaints re fun filter
8979
8980  Revision 1.123.2.26  2003/03/17 16:50:53  oes
8981  Added documentation for new chroot option
8982
8983  Revision 1.123.2.25  2003/03/15 18:36:55  oes
8984  Adapted to the new filters
8985
8986  Revision 1.123.2.24  2002/11/17 06:41:06  hal9
8987  Move default profiles table from FAQ to U-M, and other minor related changes.
8988  Add faq on cookies.
8989
8990  Revision 1.123.2.23  2002/10/21 02:32:01  hal9
8991  Updates to the user.action examples section. A few new ones.
8992
8993  Revision 1.123.2.22  2002/10/12 00:51:53  hal9
8994  Add demoronizer to filter section.
8995
8996  Revision 1.123.2.21  2002/10/10 04:09:35  hal9
8997  s/Advanced/Radical/ and added very brief note.
8998
8999  Revision 1.123.2.20  2002/10/10 03:49:21  hal9
9000  Add notes to session-cookies-only and Quickstart about pre-existing
9001  cookies. Also, note content-cookies work differently.
9002
9003  Revision 1.123.2.19  2002/09/26 01:25:36  hal9
9004  More explanation on Privoxy patterns, more on content-cookies and SSL.
9005
9006  Revision 1.123.2.18  2002/08/22 23:47:58  hal9
9007  Add 'Documentation' to Privoxy Menu shot in Configuration section to match
9008  CGIs.
9009
9010  Revision 1.123.2.17  2002/08/18 01:13:05  hal9
9011  Spell checked (only one typo this time!).
9012
9013  Revision 1.123.2.16  2002/08/09 19:20:54  david__schmidt
9014  Update to Mac OS X startup script name
9015
9016  Revision 1.123.2.15  2002/08/07 17:32:11  oes
9017  Converted some internal links from ulink to link for PDF creation; no content changed
9018
9019  Revision 1.123.2.14  2002/08/06 09:16:13  oes
9020  Nits re: actions file download
9021
9022  Revision 1.123.2.13  2002/08/02 18:23:19  g_sauthoff
9023  Just 2 small corrections to the Gentoo sections
9024
9025  Revision 1.123.2.12  2002/08/02 18:17:21  g_sauthoff
9026  Added 2 Gentoo sections
9027
9028  Revision 1.123.2.11  2002/07/26 15:20:31  oes
9029  - Added version info to title
9030  - Added info on new filters
9031  - Revised parts of the filter file tutorial
9032  - Added info on where to get updated actions files
9033
9034  Revision 1.123.2.10  2002/07/25 21:42:29  hal9
9035  Add brief notes on not proxying non-HTTP protocols.
9036
9037  Revision 1.123.2.9  2002/07/11 03:40:28  david__schmidt
9038
9039  Updated Mac OS X sections due to installation location change
9040
9041  Revision 1.123.2.8  2002/06/09 16:36:32  hal9
9042  Clarifications on filtering and MIME. Hardcode 'latest release' in index.html.
9043
9044  Revision 1.123.2.7  2002/06/09 00:29:34  hal9
9045  Touch ups on filtering, in actions section and Anatomy.
9046
9047  Revision 1.123.2.6  2002/06/06 23:11:03  hal9
9048  Fix broken link. Linkchecked all docs.
9049
9050  Revision 1.123.2.5  2002/05/29 02:01:02  hal9
9051  This is break out of the entire config section from u-m, so it can
9052  eventually be used to generate the comments, etc in the main config file
9053  so that these are in sync with each other.
9054
9055  Revision 1.123.2.4  2002/05/27 03:28:45  hal9
9056  Ooops missed something from David.
9057
9058  Revision 1.123.2.3  2002/05/27 03:23:17  hal9
9059  Fix FIXMEs for OS2 and Mac OS X startup. Fix Redhat typos (should be Red Hat).
9060  That's a wrap, I think.
9061
9062  Revision 1.123.2.2  2002/05/26 19:02:09  hal9
9063  Move Amiga stuff around to take of FIXME in start up section.
9064
9065  Revision 1.123.2.1  2002/05/26 17:04:25  hal9
9066  -Spellcheck, very minor edits, and sync across branches
9067
9068  Revision 1.123  2002/05/24 23:19:23  hal9
9069  Include new image (Proxy setup). More fun with guibutton.
9070  Minor corrections/clarifications here and there.
9071
9072  Revision 1.122  2002/05/24 13:24:08  oes
9073  Added Bookmarklet for one-click pre-filled access to show-url-info
9074
9075  Revision 1.121  2002/05/23 23:20:17  oes
9076   - Changed more (all?) references to actions to the
9077     <literal><link> style.
9078   - Small fixes in the actions chapter
9079   - Small clarifications in the quickstart to ad blocking
9080   - Removed <emphasis> from <title>s since the new doc CSS
9081     renders them red (bad in TOC).
9082
9083  Revision 1.120  2002/05/23 19:16:43  roro
9084  Correct Debian specials (installation and startup).
9085
9086  Revision 1.119  2002/05/22 17:17:05  oes
9087  Added Security hint
9088
9089  Revision 1.118  2002/05/21 04:54:55  hal9
9090  -New Section: Quickstart to Ad Blocking
9091  -Reformat Actions Anatomy to match new CGI layout
9092
9093  Revision 1.117  2002/05/17 13:56:16  oes
9094   - Reworked & extended Templates chapter
9095   - Small changes to Regex appendix
9096   - #included authors.sgml into (C) and hist chapter
9097
9098  Revision 1.116  2002/05/17 03:23:46  hal9
9099  Fixing merge conflict in Quickstart section.
9100
9101  Revision 1.115  2002/05/16 16:25:00  oes
9102  Extended the Filter File chapter & minor fixes
9103
9104  Revision 1.114  2002/05/16 09:42:50  oes
9105  More ulink->link, added some hints to Quickstart section
9106
9107  Revision 1.113  2002/05/15 21:07:25  oes
9108  Extended and further commented the example actions files
9109
9110  Revision 1.112  2002/05/15 03:57:14  hal9
9111  Spell check. A few minor edits here and there for better syntax and
9112  clarification.
9113
9114  Revision 1.111  2002/05/14 23:01:36  oes
9115  Fixing the fixes   
9116
9117  Revision 1.110  2002/05/14 19:10:45  oes
9118  Restored alphabetical order of actions
9119
9120  Revision 1.109  2002/05/14 17:23:11  oes
9121  Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
9122
9123  Revision 1.108  2002/05/14 15:29:12  oes
9124  Completed proofreading the actions chapter
9125
9126  Revision 1.107  2002/05/12 03:20:41  hal9
9127  Small clarifications for 127.0.0.1 vs localhost for listen-address since this
9128  apparently an important distinction for some OS's.
9129
9130  Revision 1.106  2002/05/10 01:48:20  hal9
9131  This is mostly proposed copyright/licensing additions and changes. Docs
9132  are still GPL, but licensing and copyright are more visible. Also, copyright
9133  changed in doc header comments (eliminate references to JB except FAQ).
9134
9135  Revision 1.105  2002/05/05 20:26:02  hal9
9136  Sorting out license vs copyright in these docs.
9137
9138  Revision 1.104  2002/05/04 08:44:45  swa
9139  bumped version
9140
9141  Revision 1.103  2002/05/04 00:40:53  hal9
9142  -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
9143  -Some minor additions to Quickstart.
9144
9145  Revision 1.102  2002/05/03 17:46:00  oes
9146  Further proofread & reactivated short build instructions
9147
9148  Revision 1.101  2002/05/03 03:58:30  hal9
9149  Move the user-manual config directive to top of section. Add note about
9150  Privoxy needing read permissions for configs, and write for logs.
9151
9152  Revision 1.100  2002/04/29 03:05:55  hal9
9153  Add clarification on differences of new actions files.
9154
9155  Revision 1.99  2002/04/28 16:59:05  swa
9156  more structure in starting section
9157
9158  Revision 1.98  2002/04/28 05:43:59  hal9
9159  This is the break up of configuration.html into multiple files. This
9160  will probably break links elsewhere :(
9161
9162  Revision 1.97  2002/04/27 21:04:42  hal9
9163  -Rewrite of Actions File example.
9164  -Add section for user-manual directive in config.
9165
9166  Revision 1.96  2002/04/27 05:32:00  hal9
9167  -Add short section to Filter Files to tie in with +filter action.
9168  -Start rewrite of examples in Actions Examples (not finished).
9169
9170  Revision 1.95  2002/04/26 17:23:29  swa
9171  bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
9172
9173  Revision 1.94  2002/04/26 05:24:36  hal9
9174  -Add most of Andreas suggestions to Chain of Events section.
9175  -A few other minor corrections and touch up.
9176
9177  Revision 1.92  2002/04/25 18:55:13  hal9
9178  More catchups on new actions files, and new actions names.
9179  Other assorted cleanups, and minor modifications.
9180
9181  Revision 1.91  2002/04/24 02:39:31  hal9
9182  Add 'Chain of Events' section.
9183
9184  Revision 1.90  2002/04/23 21:41:25  hal9
9185  Linuxconf is deprecated on RH, substitute chkconfig.
9186
9187  Revision 1.89  2002/04/23 21:05:28  oes
9188  Added hint for startup on Red Hat
9189
9190  Revision 1.88  2002/04/23 05:37:54  hal9
9191  Add AmigaOS install stuff.
9192
9193  Revision 1.87  2002/04/23 02:53:15  david__schmidt
9194  Updated Mac OS X installation section
9195  Added a few English tweaks here an there
9196
9197  Revision 1.86  2002/04/21 01:46:32  hal9
9198  Re-write actions section.
9199
9200  Revision 1.85  2002/04/18 21:23:23  hal9
9201  Fix ugly typo (mine).
9202
9203  Revision 1.84  2002/04/18 21:17:13  hal9
9204  Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
9205
9206  Revision 1.83  2002/04/18 18:21:12  oes
9207  Added RPM install detail
9208
9209  Revision 1.82  2002/04/18 12:04:50  oes
9210  Cosmetics
9211
9212  Revision 1.81  2002/04/18 11:50:24  oes
9213  Extended Install section - needs fixing by packagers
9214
9215  Revision 1.80  2002/04/18 10:45:19  oes
9216  Moved text to buildsource.sgml, renamed some filters, details
9217
9218  Revision 1.79  2002/04/18 03:18:06  hal9
9219  Spellcheck, and minor touchups.
9220
9221  Revision 1.78  2002/04/17 18:04:16  oes
9222  Proofreading part 2
9223
9224  Revision 1.77  2002/04/17 13:51:23  oes
9225  Proofreading, part one
9226
9227  Revision 1.76  2002/04/16 04:25:51  hal9
9228  -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
9229  -Note about proxy may need requests to re-read config files.
9230
9231  Revision 1.75  2002/04/12 02:08:48  david__schmidt
9232  Remove OS/2 building info... it is already in the developer-manual
9233
9234  Revision 1.74  2002/04/11 00:54:38  hal9
9235  Add small section on submitting actions.
9236
9237  Revision 1.73  2002/04/10 18:45:15  swa
9238  generated
9239
9240  Revision 1.72  2002/04/10 04:06:19  hal9
9241  Added actions feedback  to Bookmarklets section
9242
9243  Revision 1.71  2002/04/08 22:59:26  hal9
9244  Version update. Spell chkconfig correctly :)
9245
9246  Revision 1.70  2002/04/08 20:53:56  swa
9247  ?
9248
9249  Revision 1.69  2002/04/06 05:07:29  hal9
9250  -Add privoxy-man-page.sgml, for man page.
9251  -Add authors.sgml for AUTHORS (and p-authors.sgml)
9252  -Reworked various aspects of various docs.
9253  -Added additional comments to sub-docs.
9254
9255  Revision 1.68  2002/04/04 18:46:47  swa
9256  consistent look. reuse of copyright, history et. al.
9257
9258  Revision 1.67  2002/04/04 17:27:57  swa
9259  more single file to be included at multiple points. make maintaining easier
9260
9261  Revision 1.66  2002/04/04 06:48:37  hal9
9262  Structural changes to allow for conditional inclusion/exclusion of content
9263  based on entity toggles, e.g. 'entity % p-not-stable  "INCLUDE"'. And
9264  definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
9265  eventually be set by Makefile.
9266  More boilerplate text for use across multiple docs.
9267
9268  Revision 1.65  2002/04/03 19:52:07  swa
9269  enhance squid section due to user suggestion
9270
9271  Revision 1.64  2002/04/03 03:53:43  hal9
9272  A few minor bug fixes, and touch ups. Ready for review.
9273
9274  Revision 1.63  2002/04/01 16:24:49  hal9
9275  Define entities to include boilerplate text. See doc/source/*.
9276
9277  Revision 1.62  2002/03/30 04:15:53  hal9
9278  - Fix privoxy.org/config links.
9279  - Paste in Bookmarklets from Toggle page.
9280  - Move Quickstart nearer top, and minor rework.
9281
9282  Revision 1.61  2002/03/29 01:31:08  hal9
9283  Minor update.
9284
9285  Revision 1.60  2002/03/27 01:57:34  hal9
9286  Added more to Anatomy section.
9287
9288  Revision 1.59  2002/03/27 00:54:33  hal9
9289  Touch up intro for new name.
9290
9291  Revision 1.58  2002/03/26 22:29:55  swa
9292  we have a new homepage!
9293
9294  Revision 1.57  2002/03/24 20:33:30  hal9
9295  A few minor catch ups with name change.
9296
9297  Revision 1.56  2002/03/24 16:17:06  swa
9298  configure needs to be generated.
9299
9300  Revision 1.55  2002/03/24 16:08:08  swa
9301  we are too lazy to make a block-built
9302  privoxy logo. hence removed the option.
9303
9304  Revision 1.54  2002/03/24 15:46:20  swa
9305  name change related issue.
9306
9307  Revision 1.53  2002/03/24 11:51:00  swa
9308  name change. changed filenames.
9309
9310  Revision 1.52  2002/03/24 11:01:06  swa
9311  name change
9312
9313  Revision 1.51  2002/03/23 15:13:11  swa
9314  renamed every reference to the old name with foobar.
9315  fixed "application foobar application" tag, fixed
9316  "the foobar" with "foobar". left junkbustser in cvs
9317  comments and remarks to history untouched.
9318
9319  Revision 1.50  2002/03/23 05:06:21  hal9
9320  Touch up.
9321
9322  Revision 1.49  2002/03/21 17:01:05  hal9
9323  New section in Appendix.
9324
9325  Revision 1.48  2002/03/12 06:33:01  hal9
9326  Catching up to Andreas and re_filterfile changes.
9327
9328  Revision 1.47  2002/03/11 13:13:27  swa
9329  correct feedback channels
9330
9331  Revision 1.46  2002/03/10 00:51:08  hal9
9332  Added section on JB internal pages in Appendix.
9333
9334  Revision 1.45  2002/03/09 17:43:53  swa
9335  more distros
9336
9337  Revision 1.44  2002/03/09 17:08:48  hal9
9338  New section on Jon's actions file editor, and move some stuff around.
9339
9340  Revision 1.43  2002/03/08 00:47:32  hal9
9341  Added imageblock{pattern}.
9342
9343  Revision 1.42  2002/03/07 18:16:55  swa
9344  looks better
9345
9346  Revision 1.41  2002/03/07 16:46:43  hal9
9347  Fix a few markup problems for jade.
9348
9349  Revision 1.40  2002/03/07 16:28:39  swa
9350  provide correct feedback channels
9351
9352  Revision 1.39  2002/03/06 16:19:28  hal9
9353  Note on perceived filtering slowdown per FR.
9354
9355  Revision 1.38  2002/03/05 23:55:14  hal9
9356  Stupid I did it again. Double hyphen in comment breaks jade.
9357
9358  Revision 1.37  2002/03/05 23:53:49  hal9
9359  jade barfs on '- -' embedded in comments. - -user option broke it.
9360
9361  Revision 1.36  2002/03/05 22:53:28  hal9
9362  Add new - - user option.
9363
9364  Revision 1.35  2002/03/05 00:17:27  hal9
9365  Added section on command line options.
9366
9367  Revision 1.34  2002/03/04 19:32:07  oes
9368  Changed default port to 8118
9369
9370  Revision 1.33  2002/03/03 19:46:13  hal9
9371  Emphasis on where/how to report bugs, etc
9372
9373  Revision 1.32  2002/03/03 09:26:06  joergs
9374  AmigaOS changes, config is now loaded from PROGDIR: instead of
9375  AmiTCP:db/junkbuster/ if no configuration file is specified on the
9376  command line.
9377
9378  Revision 1.31  2002/03/02 22:45:52  david__schmidt
9379  Just tweaking
9380
9381  Revision 1.30  2002/03/02 22:00:14  hal9
9382  Updated 'New Features' list. Ran through spell-checker.
9383
9384  Revision 1.29  2002/03/02 20:34:07  david__schmidt
9385  Update OS/2 build section
9386
9387  Revision 1.28  2002/02/24 14:34:24  jongfoster
9388  Formatting changes.  Now changing the doctype to DocBook XML 4.1
9389  will work - no other changes are needed.
9390
9391  Revision 1.27  2002/01/11 14:14:32  hal9
9392  Added a very short section on Templates
9393
9394  Revision 1.26  2002/01/09 20:02:50  hal9
9395  Fix bug re: auto-detect config file changes.
9396
9397  Revision 1.25  2002/01/09 18:20:30  hal9
9398  Touch ups for *.action files.
9399
9400  Revision 1.24  2001/12/02 01:13:42  hal9
9401  Fix typo.
9402
9403  Revision 1.23  2001/12/02 00:20:41  hal9
9404  Updates for recent changes.
9405
9406  Revision 1.22  2001/11/05 23:57:51  hal9
9407  Minor update for startup now daemon mode.
9408
9409  Revision 1.21  2001/10/31 21:11:03  hal9
9410  Correct 2 minor errors
9411
9412  Revision 1.18  2001/10/24 18:45:26  hal9
9413  *** empty log message ***
9414
9415  Revision 1.17  2001/10/24 17:10:55  hal9
9416  Catching up with Jon's recent work, and a few other things.
9417
9418  Revision 1.16  2001/10/21 17:19:21  swa
9419  wrong url in documentation
9420
9421  Revision 1.15  2001/10/14 23:46:24  hal9
9422  Various minor changes. Fleshed out SEE ALSO section.
9423
9424  Revision 1.13  2001/10/10 17:28:33  hal9
9425  Very minor changes.
9426
9427  Revision 1.12  2001/09/28 02:57:04  hal9
9428  Ditto :/
9429
9430  Revision 1.11  2001/09/28 02:25:20  hal9
9431  Ditto.
9432
9433  Revision 1.9  2001/09/27 23:50:29  hal9
9434  A few changes. A short section on regular expression in appendix.
9435
9436  Revision 1.8  2001/09/25 00:34:59  hal9
9437  Some additions, and re-arranging.
9438
9439  Revision 1.7  2001/09/24 14:31:36  hal9
9440  Diddling.
9441
9442  Revision 1.6  2001/09/24 14:10:32  hal9
9443  Including David's OS/2 installation instructions.
9444
9445  Revision 1.2  2001/09/13 15:27:40  swa
9446  cosmetics
9447
9448  Revision 1.1  2001/09/12 15:36:41  swa
9449  source files for junkbuster documentation
9450
9451  Revision 1.3  2001/09/10 17:43:59  swa
9452  first proposal of a structure.
9453
9454  Revision 1.2  2001/06/13 14:28:31  swa
9455  docs should have an author.
9456
9457  Revision 1.1  2001/06/13 14:20:37  swa
9458  first import of project's documentation for the webserver.
9459
9460  -->
9461
9462 </article>