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