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