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