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 "2.9.18">
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 "©"> <!-- kludge for docbook2man -->
26 <!entity % draft "IGNORE"> <!-- WIP stuff -->
29 File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
32 This file belongs into
33 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
35 $Id: user-manual.sgml,v 1.123.2.13 2002/08/02 18:23:19 g_sauthoff Exp $
37 Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
40 ========================================================================
41 NOTE: Please read developer-manual/documentation.html before touching
42 anything in this, or other Privoxy documentation.
43 ========================================================================
50 <title>Privoxy &p-version; User Manual</title>
54 <!-- Completely the wrong markup, but very little is allowed -->
55 <!-- in this part of an article. FIXME -->
56 <link linkend="copyright">Copyright</link> &my-copy; 2001, 2002 by
57 <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
61 <pubdate>$Id: user-manual.sgml,v 1.123.2.13 2002/08/02 18:23:19 g_sauthoff Exp $</pubdate>
65 Note: the following should generate a separate page, and a live link to it,
66 all nicely done. But it doesn't for some mysterious reason. Please leave
67 commented unless it can be fixed proper. For the time being, the
68 copyright/license declarations will be in their own sgml.
75 <holder>Privoxy Developers</holder>
78 <legalnotice id="legalnotice">
80 text goes here ........
92 This is here to keep vim syntax file from breaking :/
93 If I knew enough to fix it, I would.
94 PLEASE DO NOT REMOVE! HB: hal@foobox.net
100 The <citetitle>User Manual</citetitle> gives users information on how to
101 install, configure and use <ulink
102 url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
105 <!-- Include privoxy.sgml boilerplate: -->
107 <!-- end privoxy.sgml -->
110 You can find the latest version of the <citetitle>User Manual</citetitle> at <ulink
111 url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
112 Please see the <ulink url="contact.html">Contact section</ulink> on how to
113 contact the developers.
117 <!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
123 <!-- ~~~~~ New section ~~~~~ -->
124 <sect1 label="1" id="introduction"><title>Introduction</title>
126 This documentation is included with the current &p-status; version of
127 <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
128 and is mostly complete at this point. The most up to date reference for the
129 time being is still the comments in the source files and in the individual
130 configuration files. Development of version 3.0 is currently nearing
131 completion, and includes many significant changes and enhancements over
132 earlier versions. The target release date for
133 stable v3.0 is <quote>soon</quote> ;-)]]>.
136 <!-- include only in non-stable versions -->
139 Since this is a &p-status; version, not all new features are well tested. This
140 documentation may be slightly out of sync as a result (especially with
141 CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
146 <!-- ~~~~~ New section ~~~~~ -->
147 <sect2 id="features"><title>Features</title>
149 In addition to <application>Internet Junkbuster's</application> traditional
150 features of ad and banner blocking and cookie management,
151 <application>Privoxy</application> provides new features<![%p-not-stable;[,
152 some of them currently under development]]>:
154 <!-- Include newfeatures.sgml boilerplate here: -->
156 <!-- end boilerplate -->
161 <!-- ~ End section ~ -->
164 <!-- ~~~~~ New section ~~~~~ -->
165 <sect1 id="installation"><title>Installation</title>
168 <application>Privoxy</application> is available both in convenient pre-compiled
169 packages for a wide range of operating systems, and as raw source code.
170 For most users, we recommend using the packages, which can be downloaded from our
171 <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
176 Note: If you have a previous <application>Junkbuster</application> or
177 <application>Privoxy</application> installation on your system, you
178 will need to remove it. On some platforms, this may be done for you as part
179 of their installation procedure. (See below for your platform). In any case
180 <emphasis>be sure to backup your old configuration if it is valuable to
181 you.</emphasis> See the <link linkend="upgradersnote">note to
182 upgraders</link> section below.
185 <!-- ~~~~~ New section ~~~~~ -->
186 <sect2 id="installation-packages"><title>Binary Packages</title>
188 How to install the binary packages depends on your operating system:
191 <!-- ~~~~~ New section ~~~~~ -->
192 <sect3 id="installation-pack-rpm"><title>Red Hat, SuSE and Conectiva RPMs</title>
195 RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
196 and will use <filename>/etc/privoxy</filename> for the location
197 of configuration files.
201 Note that on Red Hat, <application>Privoxy</application> will
202 <emphasis>not</emphasis> be automatically started on system boot. You will
203 need to enable that using <command>chkconfig</command>,
204 <command>ntsysv</command>, or similar methods. Note that SuSE will
205 automatically start Privoxy in the boot process.
209 If you have problems with failed dependencies, try rebuilding the SRC RPM:
210 <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm</literal>. This
211 will use your locally installed libraries and RPM version.
215 Also note that if you have a <application>Junkbuster</application> RPM installed
216 on your system, you need to remove it first, because the packages conflict.
217 Otherwise, RPM will try to remove <application>Junkbuster</application>
218 automatically, before installing <application>Privoxy</application>.
222 <!-- ~~~~~ New section ~~~~~ -->
223 <sect3 id="installation-deb"><title>Debian</title>
225 DEBs can be installed with <literal>dpkg -i
226 privoxy_&p-version;-1.deb</literal>, and will use
227 <filename>/etc/privoxy</filename> for the location of configuration
232 <!-- ~~~~~ New section ~~~~~ -->
233 <sect3 id="installation-pack-win"><title>Windows</title>
236 Just double-click the installer, which will guide you through
237 the installation process. You will find the configuration files
238 in the same directory as you installed Privoxy in. We do not
239 use the registry of Windows.
243 <!-- ~~~~~ New section ~~~~~ -->
244 <sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
247 Create a new directory, <literal>cd</literal> to it, then unzip and
248 untar the archive. For the most part, you'll have to figure out where
249 things go. <!-- FIXME, more info needed? -->
253 <!-- ~~~~~ New section ~~~~~ -->
254 <sect3 id="installation-os2"><title>OS/2</title>
257 First, make sure that no previous installations of
258 <application>Junkbuster</application> and / or
259 <application>Privoxy</application> are left on your
260 system. Check that no <application>Junkbuster</application>
261 or <application>Privoxy</application> objects are in
267 Then, just double-click the WarpIN self-installing archive, which will
268 guide you through the installation process. A shadow of the
269 <application>Privoxy</application> executable will be placed in your
270 startup folder so it will start automatically whenever OS/2 starts.
274 The directory you choose to install <application>Privoxy</application>
275 into will contain all of the configuration files.
279 <!-- ~~~~~ New section ~~~~~ -->
280 <sect3 id="installation-mac"><title>Mac OSX</title>
282 Unzip the downloaded package (you can either double-click on the file
283 in the finder, or on the desktop if you downloaded it there). The
284 Privoxy.pkg package should appear after unzipping. Then,
285 double-click on that Privoxy.pkg package installer icon and follow
286 the installation process.
287 <application>Privoxy</application> will be installed in the folder
288 <literal>/Library/Privoxy</literal>.
289 It will run automatically whenever you start up. To prevent it from
290 running automatically, remove or rename the folder
291 <literal>/Library/StartupItems/Privoxy</literal>.
294 To run Privoxy by hand, double-click on
295 <literal>RunPrivoxy.command</literal>.
296 To run Privoxy from Terminal, execute
297 <literal>/Library/Privoxy/RunPrivoxy.command</literal>.
301 <!-- ~~~~~ New section ~~~~~ -->
302 <sect3 id="installation-amiga"><title>AmigaOS</title>
304 Copy and then unpack the <filename>lha</filename> archive to a suitable location.
305 All necessary files will be installed into <application>Privoxy</application>
306 directory, including all configuration and log files. To uninstall, just
307 remove this directory.
311 <!-- ~~~~~ New section ~~~~~ -->
312 <sect3 id="installattion-gentoo"><title>Gentoo</title>
314 Gentoo source packages (Ebuilds) for <application>Privoxy</application> are
315 contained in the Gentoo Portage Tree (they are not on the download page,
316 but there is a Gentoo section, where you can see when a new
317 <application>Privoxy</application> Version is added to the Portage Tree).
320 Before installing <application>Privoxy</application> under Gentoo just do
321 first <literal>emerge rsync</literal> to get the latest changes from the
322 Portage tree. With <literal>emerge privoxy</literal> you install the latest
326 Configuration files are in <filename>/etc/privoxy</filename>, the
327 documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
328 and the Log directory is in <filename>/var/log/privoxy</filename>.
334 <!-- ~~~~~ New section ~~~~~ -->
335 <sect2 id="installation-source"><title>Building from Source</title>
338 The most convenient way to obtain the <application>Privoxy</application> sources
339 is to download the source tarball from our <ulink url="http://sf.net/projects/ijbswa/">project
344 If you like to live on the bleeding edge and are not afraid of using
345 possibly unstable development versions, you can check out the up-to-the-minute
346 version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
347 CVS repository</ulink> or simply download <ulink
348 url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
352 <!-- include buildsource.sgml boilerplate: -->
354 <!-- end boilerplate -->
357 <!-- ~~~~~ New section ~~~~~ -->
358 <sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
360 As user feedback comes in and development continues, we will make updated versions
361 of both the main <link linkend="actions-file">actions file</link> (as a <ulink
362 url="http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670">separate
363 package</ulink>) and the software itself (including the actions file) available for
368 If you wish to receive an email notification whenever we release updates of
369 <application>Privoxy</application> or the actions file, <ulink
370 url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
371 to our announce mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
375 In order not to loose your personal changes and adjustments when updating
376 to the latest <literal>default.action</literal> file we <emphasis>strongly
377 recommend</emphasis> that you use <literal>user.action</literal> for your
378 customization of <application>Privoxy</application>. See the <link
379 linkend="actions-file">Chapter on actions files</link> for details.
387 <!-- ~ End section ~ -->
389 <!-- ~~~~~ New section ~~~~~ -->
390 <sect1 id="upgradersnote">
391 <title>Note to Upgraders</title>
393 There are very significant changes from earlier
394 <application>Junkbuster</application> versions to the current
395 <application>Privoxy</application>. The number, names, syntax, and
396 purposes of configuration files have substantially changed.
397 <application>Junkbuster 2.0.x</application> configuration
398 files will not migrate, <application>Junkbuster 2.9.x</application>
399 and <application>Privoxy</application> configurations will need to be
400 ported. The functionalities of the old <filename>blockfile</filename>,
401 <filename>cookiefile</filename> and <filename>imagelist</filename>
402 are now combined into the <link linkend="actions-file"><quote>actions
403 files</quote></link>.
404 <filename>default.action</filename>, is the main actions file. Local
405 exceptions should best be put into <filename>user.action</filename>.
408 A <link linkend="filter-file"><quote>filter file</quote></link> (typically
409 <filename>default.filter</filename>) is new as of <application>Privoxy
410 2.9.x</application>, and provides some of the new sophistication (explained
411 below). <filename>config</filename> is much the same as before.
414 If upgrading from a 2.0.x version, you will have to use the new config
415 files, and possibly adapt any personal rules from your older files.
416 When porting personal rules over from the old <filename>blockfile</filename>
417 to the new actions files, please note that even the pattern syntax has
418 changed. If upgrading from 2.9.x development versions, it is still
419 recommended to use the new configuration files.
422 A quick list of things to be aware of before upgrading:
430 The default listening port is now 8118 due to a conflict with another
436 Some installers may remove earlier versions completely. Save any
437 important configuration files!
442 <application>Privoxy</application> is controllable with a web browser
443 at the special URL: <ulink
444 url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
445 (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
446 aspects of configuration can be done here, including temporarily disabling
447 <application>Privoxy</application>.
452 The primary configuration files for cookie management, ad and banner
453 blocking, and many other aspects of <application>Privoxy</application>
454 configuration are the <link linkend="actions-file">actions
455 files</link>. It is strongly recommended to become familiar with the new
456 actions concept below, before modifying these files. Locally defined rules
457 should go into <filename>user.action</filename>.
462 <!-- I think it is best to keep this somewhat vague, in case -->
463 <!-- the situation changes under our feet. -->
464 Some installers may not automatically start
465 <application>Privoxy</application> after installation.
473 <!-- ~~~~~ New section ~~~~~ -->
474 <sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
480 If upgrading, from versions before 2.9.16, please back up any configuration
481 files. See the <link linkend="upgradersnote">Note to Upgraders</link> Section.
487 Install <application>Privoxy</application>. See the <link
488 linkend="installation">Installation Section</link> below for platform specific
495 Advanced users and those who want to offer <application>Privoxy</application>
496 service to more than just their local machine should check the <link
497 linkend="config">main config file</link>, especially the <link
498 linkend="access-control">security-relevant</link> options. These are
505 Start <application>Privoxy</application>, if the installation program has
506 not done this already (may vary according to platform). See the section
507 <link linkend="startup">Starting <application>Privoxy</application></link>.
513 Set your browser to use <application>Privoxy</application> as HTTP and
514 HTTPS proxy by setting the proxy configuration for address of
515 <literal>127.0.0.1</literal> and port <literal>8118</literal>.
516 (<application>Junkbuster</application> and earlier versions of
517 <application>Privoxy</application> used port 8000.) See the section <link
518 linkend="startup">Starting <application>Privoxy</application></link> below
519 for more details on this.
525 Flush your browser's disk and memory caches, to remove any cached ad images.
531 A default installation should provide a reasonable starting point for
532 most. There will undoubtedly be occasions where you will want to adjust the
533 configuration, but that can be dealt with as the need arises. Little
534 to no initial configuration is required in most cases.
537 See the <link linkend="configuration">Configuration section</link> for more
538 configuration options, and how to customize your installation.
539 <![%draft;[ You might also want to look at the <link
540 linkend="quickstart-ad-blocking">next section</link> for a quick
541 introduction to how <application>Privoxy</application> blocks ads and
548 If you experience ads that slipped through, innocent images that are
549 blocked, or otherwise feel the need to fine-tune
550 <application>Privoxy's</application> behaviour, take a look at the <link
551 linkend="actions-file">actions files</link>. As a quick start, you might
552 find the <link linkend="act-examples">richly commented examples</link>
553 helpful. You can also view and edit the actions files through the <ulink
554 url="http://config.privoxy.org">web-based user interface</ulink>. The
555 Appendix <quote><link linkend="actionsanat">Anatomy of an
556 Action</link></quote> has hints how to debug actions that
557 <quote>misbehave</quote>.
563 Please see the section <link linkend="contact">Contacting the
564 Developers</link> on how to report bugs or problems with websites or to get
571 Now enjoy surfing with enhanced comfort and privacy!
579 <!-- ~~~~~ New section ~~~~~ -->
581 <sect2 id="quickstart-ad-blocking">
582 <title>Quickstart to Ad Blocking</title>
584 NOTE: This section is deliberately redundant for those that don't
585 want to read the whole thing (which is getting lengthy).
588 Ad blocking is but one of <application>Privoxy's</application>
589 array of features. Many of these features are for the technically minded advanced
590 user. But, ad and banner blocking is surely common ground for everybody.
593 This section will provide a quick summary of ad blocking so
594 you can get up to speed quickly without having to read the more extensive
595 information provided below, though this is highly recommended.
598 First a bit of a warning ... blocking ads is much like blocking SPAM: the
599 more aggressive you are about it, the more likely you are to block
600 things that were not intended. So there is a trade off here. If you want
601 extreme ad free browsing, be prepared to deal with more
602 <quote>problem</quote> sites, and to spend more time adjusting the
603 configuration to solve these unintended consequences. In short, there is
604 not an easy way to eliminate <emphasis>all</emphasis> ads. Either take
605 the easy way and settle for <emphasis>most</emphasis> ads blocked with the
606 default configuration, or jump in and tweak it for your personal surfing
607 habits and preferences.
610 Secondly, a brief explanation of <application>Privoxy's </application>
611 <quote>actions</quote>. <quote>Actions</quote> in this context, are
612 the directives we use to tell <application>Privoxy</application> to perform
613 some task relating to HTTP transactions (i.e. web browsing). We tell
614 <application>Privoxy</application> to take some <quote>action</quote>. Each
615 action has a unique name and function. While there are many potential
616 <application>actions</application> in <application>Privoxy's</application>
617 arsenal, only a few are used for ad blocking. <link
618 linkend="actions">Actions</link>, and <link linkend="actions-file">action
619 configuration files</link>, are explained in depth below.
622 Actions are specified in <application>Privoxy's</application> configuration,
623 followed by one or more URLs to which the action should apply. URLs
624 can actually be URL type <link linkend="af-patterns">patterns</link> that use
625 wildcards so they can apply potentially to a range of similar URLs. The
626 actions, together with the URL patterns are called a section.
629 When you connect to a website, the full URL will either match one or more
630 of the sections as defined in <application>Privoxy's</application> configuration,
631 or not. If so, then <application>Privoxy</application> will perform the
632 respective actions. If not, then nothing special happens. Furthermore, web
633 pages may contain embedded, secondary URLs that your web browser will
634 use to load additional components of the page, as it parses the
635 original page's HTML content. An ad image for instance, is just an URL
636 embedded in the page somewhere. The image itself may be on the same server,
637 or a server somewhere else on the Internet. Complex web pages will have many
642 The actions we need to know about for ad blocking are: <literal><link
643 linkend="block">block</link></literal>, <literal><link
644 linkend="handle-as-image">handle-as-image</link></literal>, and
645 <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
653 <literal><link linkend="block">block</link></literal> - this action stops
654 any contact between your browser and any URL patterns that match this
655 action's configuration. It can be used for blocking ads, but also anything
656 that is determined to be unwanted. By itself, it simply stops any
657 communication with the remote server and sends <application>Privoxy</application>'s
658 own built-in BLOCKED page instead to let you now what has happened.
664 <literal><link linkend="handle-as-image">handle-as-image</link></literal> -
665 tells <application>Privoxy</application> to treat this URL as an image.
666 <application>Privoxy</application>'s default configuration already does this
667 for all common image types (e.g. GIF), but there are many situations where this
668 is not so easy to determine. So we'll force it in these cases. This is particularly
669 important for ad blocking, since only if we know that it's an image of
670 some kind, can we replace it with an image of our choosing, instead of the
671 <application>Privoxy</application> BLOCKED page (which would only result in
672 a <quote>broken image</quote> icon). There are some limitations to this
673 though. For instance, you can't just brute-force an image substitution for
674 an entire HTML page in most situations.
681 linkend="set-image-blocker">set-image-blocker</link></literal> - tells
682 <application>Privoxy</application> what to display in place of an ad image that
683 has hit a block rule. For this to come into play, the URL must match a
684 <literal><link linkend="block">block</link></literal> action somewhere in the
685 configuration, <emphasis>and</emphasis>, it must also match an
686 <literal><link linkend="handle-as-image">handle-as-image</link></literal> action.
689 The configuration options on what to display instead of the ad are:
693 <emphasis>pattern</emphasis> - a checkerboard pattern, so that an ad
694 replacement is obvious. This is the default.
699 <emphasis>blank</emphasis> - A very small empty GIF image is displayed.
700 This is the so-called <quote>invisible</quote> configuration option.
705 <emphasis>http://<URL></emphasis> - A redirect to any image anywhere
706 of the user's choosing (advanced usage).
715 The quickest way to adjust any of these settings is with your browser through
716 the special <application>Privoxy</application> editor at <ulink
717 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
718 (shortcut: <ulink url="http://p.p/">http://p.p/show-status</ulink>). This
719 is an internal page, and does not require Internet access. Select the
720 appropriate <quote>actions</quote> file, and click
721 <quote><guibutton>Edit</guibutton></quote>. It is best to put personal or
722 local preferences in <filename>user.action</filename> since this is not
723 meant to be overwritten during upgrades, and will over-ride the settings in
724 other files. Here you can insert new <quote>actions</quote>, and URLs for ad
725 blocking or other purposes, and make other adjustments to the configuration.
726 <application>Privoxy</application> will detect these changes automatically.
730 A quick and simple step by step example:
738 Right click on the ad image to be blocked, then select
739 <quote><guimenuitem>Copy Link Location</guimenuitem></quote> from the
747 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
752 Find <filename>user.action</filename> in the top section, and click
753 on <quote><guibutton>Edit</guibutton></quote>:
756 <!-- image of editor and actions files selections -->
758 <figure pgwide="0" float="0"><title>Actions Files in Use</title>
761 <imagedata fileref="../images/files-in-use.jpg" format="jpg">
764 <phrase>[ Screenshot of Actions Files in Use ]</phrase>
773 You should have a section with only
774 <literal><link linkend="block">block</link></literal> listed under
775 <quote>Actions:</quote>.
776 If not, click a <quote><guibutton>Insert new section below</guibutton></quote>
777 button, and in the new section that just appeared, click the
778 <guibutton>Edit</guibutton> button right under the word <quote>Actions:</quote>.
779 This will bring up a list of all actions. Find
780 <literal><link linkend="block">block</link></literal> near the top, and click
781 in the <quote>Enabled</quote> column, then <quote><guibutton>Submit</guibutton></quote>
787 Now, in the <literal><link linkend="block">block</link></literal> actions section,
788 click the <quote><guibutton>Add</guibutton></quote> button, and paste the URL the
789 browser got from <quote><guimenuitem>Copy Link Location</guimenuitem></quote>.
790 Remove the <literal>http://</literal> at the beginning of the URL. Then, click
791 <quote><guibutton>Submit</guibutton></quote> (or
792 <quote><guibutton>OK</guibutton></quote> if in a pop-up window).
797 Now go back to the original page, and press <keycap>SHIFT-Reload</keycap>
798 (or flush all browser caches). The image should be gone now.
806 This is a very crude and simple example. There might be good reasons to use a
807 wildcard pattern match to include potentially similar images from the same
808 site. For a more extensive explanation of <quote>patterns</quote>, and
809 the entire actions concept, see <link linkend="actions-file">the Actions
814 For advanced users who want to hand edit their config files, you might want
815 to now go to the <link linkend="act-examples">Actions Files Tutorial</link>.
816 The ideas explained therein also apply to the web-based editor.
823 <!-- ~ End section ~ -->
826 <!-- ~~~~~ New section ~~~~~ -->
828 <title>Starting <application>Privoxy</application></title>
830 Before launching <application>Privoxy</application> for the first time, you
831 will want to configure your browser(s) to use
832 <application>Privoxy</application> as a HTTP and HTTPS proxy. The default is
833 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
834 used port 8000). This is the one configuration step that must be done!
837 Please note that <application>Privoxy</application> can only proxy HTTP and
838 HTTPS traffic. It will not work with FTP or other protocols.
841 <!-- image of Mozilla Proxy configuration -->
843 <figure pgwide="0" float="0"><title>Proxy Configuration (Mozilla)</title>
846 <imagedata fileref="../images/proxy_setup.jpg" format="jpg">
849 <phrase>[ Screenshot of Mozilla Proxy Configuration ]</phrase>
856 With <application>Netscape</application> (and
857 <application>Mozilla</application>), this can be set under:
861 <!-- Mix ascii and gui art, something for everybody -->
862 <!-- spacing on this is tricky -->
863 <guibutton>Edit</guibutton>
865 <guibutton>Preferences</guibutton>
867 <guibutton>Advanced</guibutton>
869 <guibutton>Proxies</guibutton>
871 <guibutton>HTTP Proxy</guibutton>
875 For <application>Internet Explorer</application>:
879 <!-- Mix ascii and gui art, something for everybody -->
880 <!-- spacing on this is tricky -->
881 <guibutton>Tools</guibutton>
883 <guibutton>Internet Properties</guibutton>
885 <guibutton>Connections</guibutton>
887 <guibutton>LAN Settings</guibutton>
891 Then, check <quote>Use Proxy</quote> and fill in the appropriate info
892 (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS
897 After doing this, flush your browser's disk and memory caches to force a
898 re-reading of all pages and to get rid of any ads that may be cached. You
899 are now ready to start enjoying the benefits of using
900 <application>Privoxy</application>!
904 <application>Privoxy</application> is typically started by specifying the
905 main configuration file to be used on the command line. If no configuration
906 file is specified on the command line, <application>Privoxy</application>
907 will look for a file named <filename>config</filename> in the current
908 directory. Except on Win32 where it will try <filename>config.txt</filename>.
911 <sect2 id="start-redhat">
912 <title>Red Hat and Conectiva</title>
914 We use a script. Note that Red Hat does not start Privoxy upon booting per
915 default. It will use the file <filename>/etc/privoxy/config</filename> as
916 its main configuration file.
920 # /etc/rc.d/init.d/privoxy start
925 <sect2 id="start-debian">
926 <title>Debian</title>
928 We use a script. Note that Debian starts Privoxy upon booting per
929 default. It will use the file
930 <filename>/etc/privoxy/config</filename> as its main configuration
935 # /etc/init.d/privoxy start
940 <sect2 id="start-suse">
943 We use a script. It will use the file <filename>/etc/privoxy/config</filename>
944 as its main configuration file. Note that SuSE starts Privoxy upon booting
954 <sect2 id="start-windows">
955 <title>Windows</title>
957 Click on the Privoxy Icon to start Privoxy. If no configuration file is
958 specified on the command line, <application>Privoxy</application> will look
959 for a file named <filename>config.txt</filename>. Note that Windows will
960 automatically start Privoxy upon booting you PC.
964 <sect2 id="start-unices">
965 <title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
967 Example Unix startup command:
971 # /usr/sbin/privoxy /etc/privoxy/config
976 <sect2 id="start-os2">
979 During installation, <application>Privoxy</application> is configured to
980 start automatically when the system restarts. You can start it manually by
981 double-clicking on the <application>Privoxy</application> icon in the
982 <application>Privoxy</application> folder.
986 <sect2 id="start-macosx">
987 <title>Mac OSX</title>
989 During installation, <application>Privoxy</application> is configured to
990 start automatically when the system restarts. To run Privoxy by hand,
991 double-click on the <literal>RunPrivoxy.command</literal> icon in the
992 <literal>/Library/Privoxy</literal> folder. Or, type this command
997 /Library/Privoxy/RunPrivoxy.command
1001 If you are not logged in as an administrator, you will be asked for the
1002 administrator password when starting <application>Privoxy</application>
1008 <sect2 id="start-amigaos">
1009 <title>AmigaOS</title>
1011 Start <application>Privoxy</application> (with RUN <>NIL:) in your
1012 <filename>startnet</filename> script (AmiTCP), in
1013 <filename>s:user-startup</filename> (RoadShow), as startup program in your
1014 startup script (Genesis), or as startup action (Miami and MiamiDx).
1015 <application>Privoxy</application> will automatically quit when you quit your
1016 TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
1017 <application>Privoxy</application> is still running).
1021 <sect2 id="start-gentoo">
1022 <title>Gentoo</title>
1024 A script is again used. It will use the file <filename>/etc/privoxy/config
1025 </filename> as its main configuration file.
1029 /etc/init.d/privoxy start
1033 Note that <application>Privoxy</application> is not automatically started at
1034 boot time by default. You can change this with the <literal>rc-update</literal>
1039 rc-update add privoxy default
1047 See the section <link linkend="cmdoptions">Command line options</link> for
1051 must find a better place for this paragraph
1054 The included default configuration files should give a reasonable starting
1055 point. Most of the per site configuration is done in the
1056 <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
1057 where various cookie actions are defined, ad and banner blocking, and other
1058 aspects of <application>Privoxy</application> configuration. There are several
1059 such files included, with varying levels of aggressiveness.
1063 You will probably want to keep an eye out for sites for which you may prefer
1064 persistent cookies, and add these to your actions configuration as needed. By
1065 default, most of these will be accepted only during the current browser
1066 session (aka <quote>session cookies</quote>), unless you add them to the
1067 configuration. If you want the browser to handle this instead, you will need
1068 to edit <filename>user.action</filename> (or through the web based interface)
1069 and disable this feature. If you use more than one browser, it would make
1070 more sense to let <application>Privoxy</application> handle this. In which
1071 case, the browser(s) should be set to accept all cookies.
1075 Another feature where you will probably want to define exceptions for trusted
1076 sites is the popup-killing (through the <ulink
1077 url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink> and
1079 url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>
1080 actions), because your favorite shopping, banking, or leisure site may need
1081 popups (explained below).
1085 <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
1086 the optional 1.1 features are as yet supported. In the unlikely event that
1087 you experience inexplicable problems with browsers that use HTTP/1.1 per default
1088 (like <application>Mozilla</application> or recent versions of I.E.), you might
1089 try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
1090 Preferences -> Debug -> Networking</literal>.
1091 Alternatively, set the <quote>+downgrade-http-version</quote> config option in
1092 <filename>default.action</filename> which will downgrade your browser's HTTP
1093 requests from HTTP/1.1 to HTTP/1.0 before processing them.
1097 After running <application>Privoxy</application> for a while, you can
1098 start to fine tune the configuration to suit your personal, or site,
1099 preferences and requirements. There are many, many aspects that can
1100 be customized. <quote>Actions</quote>
1101 can be adjusted by pointing your browser to
1102 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1103 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
1104 and then follow the link to <quote>View & Change the Current Configuration</quote>.
1105 (This is an internal page and does not require Internet access.)
1109 In fact, various aspects of <application>Privoxy</application>
1110 configuration can be viewed from this page, including
1111 current configuration parameters, source code version numbers,
1112 the browser's request headers, and <quote>actions</quote> that apply
1113 to a given URL. In addition to the actions file
1114 editor mentioned above, <application>Privoxy</application> can also
1115 be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
1119 If you encounter problems, try loading the page without
1120 <application>Privoxy</application>. If that helps, enter the URL where
1121 you have the problems into <ulink url="http://p.p/show-url-info">the browser
1122 based rule tracing utility</ulink>. See which rules apply and why, and
1123 then try turning them off for that site one after the other, until the problem
1124 is gone. When you have found the culprit, you might want to turn the rest on
1129 If the above paragraph sounds gibberish to you, you might want to <ulink
1130 url="actions-file.html#ACTIONSFILE">read more about the actions concept</ulink>
1131 or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
1136 If you can't get rid of the problem at all, think you've found a bug in
1137 Privoxy, want to propose a new feature or smarter rules, please see the
1138 section <ulink url="contact.html"><quote>Contacting the
1139 Developers</quote></ulink> below.
1144 <!-- ~~~~~ New section ~~~~~ -->
1145 <sect2 id="cmdoptions">
1146 <title>Command Line Options</title>
1148 <application>Privoxy</application> may be invoked with the following
1149 command-line options:
1157 <emphasis>--version</emphasis>
1160 Print version info and exit. Unix only.
1165 <emphasis>--help</emphasis>
1168 Print short usage info and exit. Unix only.
1173 <emphasis>--no-daemon</emphasis>
1176 Don't become a daemon, i.e. don't fork and become process group
1177 leader, and don't detach from controlling tty. Unix only.
1182 <emphasis>--pidfile FILE</emphasis>
1186 On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
1187 <emphasis>FILE</emphasis> on exit. Failure to create or delete the
1188 <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
1189 option is given, no PID file will be used. Unix only.
1194 <emphasis>--user USER[.GROUP]</emphasis>
1198 After (optionally) writing the PID file, assume the user ID of
1199 <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
1200 privileges are not sufficient to do so. Unix only.
1205 <emphasis>configfile</emphasis>
1208 If no <emphasis>configfile</emphasis> is included on the command line,
1209 <application>Privoxy</application> will look for a file named
1210 <quote>config</quote> in the current directory (except on Win32
1211 where it will look for <quote>config.txt</quote> instead). Specify
1212 full path to avoid confusion. If no config file is found,
1213 <application>Privoxy</application> will fail to start.
1224 <!-- ~ End section ~ -->
1227 <!-- ~~~~~ New section ~~~~~ -->
1228 <sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
1230 All <application>Privoxy</application> configuration is stored
1231 in text files. These files can be edited with a text editor.
1232 Many important aspects of <application>Privoxy</application> can
1233 also be controlled easily with a web browser.
1237 <!-- ~~~~~ New section ~~~~~ -->
1240 <title>Controlling <application>Privoxy</application> with Your Web Browser</title>
1242 <application>Privoxy</application>'s user interface can be reached through the special
1243 URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
1244 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
1245 which is a built-in page and works without Internet access.
1246 You will see the following section:
1250 <!-- Needs to be put in a table and colorized -->
1253 <bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
1257 ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
1260 ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
1263 ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
1266 ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
1269 ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
1277 This should be self-explanatory. Note the first item leads to an editor for the
1278 <link linkend="actions-file">actions files</link>, which is where the ad, banner,
1279 cookie, and URL blocking magic is configured as well as other advanced features of
1280 <application>Privoxy</application>. This is an easy way to adjust various
1281 aspects of <application>Privoxy</application> configuration. The actions
1282 file, and other configuration files, are explained in detail below.
1286 <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
1287 have problems with your current actions and filters. You can in fact use
1288 it as a test to see whether it is <application>Privoxy</application>
1289 causing the problem or not. <application>Privoxy</application> continues
1290 to run as a proxy in this case, but all manipulation is disabled, i.e.
1291 <application>Privoxy</application> acts like a normal forwarding proxy. There
1292 is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
1293 that you can toggle <application>Privoxy</application> with one click from
1299 <!-- ~ End section ~ -->
1304 <!-- ~~~~~ New section ~~~~~ -->
1306 <sect2 id="confoverview">
1307 <title>Configuration Files Overview</title>
1309 For Unix, *BSD and Linux, all configuration files are located in
1310 <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
1311 AmigaOS these are all in the same directory as the
1312 <application>Privoxy</application> executable. <![%p-not-stable;[ The name
1313 and number of configuration files has changed from previous versions, and is
1314 subject to change as development progresses.]]>
1318 The installed defaults provide a reasonable starting point, though
1319 some settings may be aggressive by some standards. For the time being, the
1320 principle configuration files are:
1328 The <link linkend="config">main configuration file</link> is named <filename>config</filename>
1329 on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
1330 on Windows. This is a required file.
1336 <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
1337 is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
1338 content modification, cookie handling etc should be applied by default. It also defines many
1339 exceptions (both positive and negative) from this default set of actions that enable
1340 <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
1341 as many websites as possible.
1344 Multiple actions files may be defined in <filename>config</filename>. These
1345 are processed in the order they are defined. Local customizations and locally
1346 preferred exceptions to the default policies as defined in
1347 <filename>default.action</filename> (which you will most probably want
1348 to define sooner or later) are probably best applied in
1349 <filename>user.action</filename>, where you can preserve them across
1350 upgrades. <filename>standard.action</filename> is for
1351 <application>Privoxy's</application> internal use.
1354 There is also a web based editor that can be accessed from
1356 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
1358 url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
1359 various actions files.
1365 <filename>default.filter</filename> (the <link linkend="filter-file">filter
1366 file</link>) can be used to re-write the raw page content, including
1367 viewable text as well as embedded HTML and JavaScript, and whatever else
1368 lurks on any given web page. The filtering jobs are only pre-defined here;
1369 whether to apply them or not is up to the actions files.
1377 All files use the <quote><literal>#</literal></quote> character to denote a
1378 comment (the rest of the line will be ignored) and understand line continuation
1379 through placing a backslash ("<literal>\</literal>") as the very last character
1380 in a line. If the <literal>#</literal> is preceded by a backslash, it looses
1381 its special function. Placing a <literal>#</literal> in front of an otherwise
1382 valid configuration line to prevent it from being interpreted is called "commenting
1387 The actions files and <filename>default.filter</filename>
1388 can use Perl style <link linkend="regex">regular expressions</link> for
1389 maximum flexibility.
1393 After making any changes, there is no need to restart
1394 <application>Privoxy</application> in order for the changes to take
1395 effect. <application>Privoxy</application> detects such changes
1396 automatically. Note, however, that it may take one or two additional
1397 requests for the change to take effect. When changing the listening address
1398 of <application>Privoxy</application>, these <quote>wake up</quote> requests
1399 must obviously be sent to the <emphasis>old</emphasis> listening address.
1404 While under development, the configuration content is subject to change.
1405 The below documentation may not be accurate by the time you read this.
1406 Also, what constitutes a <quote>default</quote> setting, may change, so
1407 please check all your configuration files on important issues.
1413 <!-- ~ End section ~ -->
1416 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
1418 <!-- **************************************************** -->
1419 <!-- Include config.sgml here -->
1420 <!-- This is where the entire config file is detailed. -->
1422 <!-- end include -->
1425 <!-- ~ End section ~ -->
1429 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
1431 <sect1 id="actions-file"><title>Actions Files</title>
1434 The actions files are used to define what actions
1435 <application>Privoxy</application> takes for which URLs, and thus determine
1436 how ad images, cookies and various other aspects of HTTP content and
1437 transactions are handled, and on which sites (or even parts thereof). There
1438 are three such files included with <application>Privoxy</application> (as of
1439 version 2.9.15), with differing purposes:
1446 <filename>default.action</filename> - is the primary action file
1447 that sets the initial values for all actions. It is intended to
1448 provide a base level of functionality for
1449 <application>Privoxy's</application> array of features. So it is
1450 a set of broad rules that should work reasonably well for users everywhere.
1451 This is the file that the developers are keeping updated, and <link
1452 linkend="installation-keepupdated">making available to users</link>.
1457 <filename>user.action</filename> - is intended to be for local site
1458 preferences and exceptions. As an example, if your ISP or your bank
1459 has specific requirements, and need special handling, this kind of
1460 thing should go here. This file will not be upgraded.
1465 <filename>standard.action</filename> - is used by the web based editor,
1466 to set various pre-defined sets of rules for the default actions section
1467 in <filename>default.action</filename>. These have increasing levels of
1468 aggressiveness <emphasis>and have no influence on your browsing unless
1469 you select them explicitly in the editor</emphasis>. It is not recommend
1477 The list of actions files to be used are defined in the main configuration
1478 file, and are processed in the order they are defined. The content of these
1479 can all be viewed and edited from <ulink
1480 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
1484 An actions file typically has multiple sections. If you want to use
1485 <quote>aliases</quote> in an actions file, you have to place the (optional)
1486 <link linkend="aliases">alias section</link> at the top of that file.
1487 Then comes the default set of rules which will apply universally to all
1488 sites and pages (be <emphasis>very careful</emphasis> with using such a
1489 universal set in <filename>user.action</filename> or any other actions file after
1490 <filename>default.action</filename>, because it will override the result
1491 from consulting any previous file). And then below that,
1492 exceptions to the defined universal policies. You can regard
1493 <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
1494 with the advantage that is a separate file, which makes preserving your
1495 personal settings across <application>Privoxy</application> upgrades easier.
1499 Actions can be used to block anything you want, including ads, banners, or
1500 just some obnoxious URL that you would rather not see. Cookies can be accepted
1501 or rejected, or accepted only during the current browser session (i.e. not
1502 written to disk), content can be modified, JavaScripts tamed, user-tracking
1503 fooled, and much more. See below for a <link linkend="actions">complete list
1507 <!-- ~~~~~ New section ~~~~~ -->
1509 <title>Finding the Right Mix</title>
1511 Note that some <link linkend="actions">actions</link>, like cookie suppression
1512 or script disabling, may render some sites unusable that rely on these
1513 techniques to work properly. Finding the right mix of actions is not always easy and
1514 certainly a matter of personal taste. In general, it can be said that the more
1515 <quote>aggressive</quote> your default settings (in the top section of the
1516 actions file) are, the more exceptions for <quote>trusted</quote> sites you
1517 will have to make later. If, for example, you want to kill popup windows per
1518 default, you'll have to make exceptions from that rule for sites that you
1519 regularly use and that require popups for actually useful content, like maybe
1520 your bank, favorite shop, or newspaper.
1524 We have tried to provide you with reasonable rules to start from in the
1525 distribution actions files. But there is no general rule of thumb on these
1526 things. There just are too many variables, and sites are constantly changing.
1527 Sooner or later you will want to change the rules (and read this chapter again :).
1531 <!-- ~~~~~ New section ~~~~~ -->
1533 <title>How to Edit</title>
1535 The easiest way to edit the actions files is with a browser by
1536 using our browser-based editor, which can be reached from <ulink
1537 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
1538 The editor allows both fine-grained control over every single feature on a
1539 per-URL basis, and easy choosing from wholesale sets of defaults like
1540 <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
1544 If you prefer plain text editing to GUIs, you can of course also directly edit the
1545 the actions files. Look at <filename>default.action</filename> which is richly
1551 <sect2 id="actions-apply">
1552 <title>How Actions are Applied to URLs</title>
1554 Actions files are divided into sections. There are special sections,
1555 like the <quote><link linkend="aliases">alias</link></quote> sections which will
1556 be discussed later. For now let's concentrate on regular sections: They have a
1557 heading line (often split up to multiple lines for readability) which consist
1558 of a list of actions, separated by whitespace and enclosed in curly braces.
1559 Below that, there is a list of URL patterns, each on a separate line.
1563 To determine which actions apply to a request, the URL of the request is
1564 compared to all patterns in each action file file. Every time it matches, the list of
1565 applicable actions for the URL is incrementally updated, using the heading
1566 of the section in which the pattern is located. If multiple matches for
1567 the same URL set the same action differently, the last match wins. If not,
1568 the effects are aggregated. E.g. a URL might match a regular section with
1569 a heading line of <literal>{
1570 +<ulink url="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</ulink> }</literal>,
1571 then later another one with just <literal>{
1572 +<ulink url="actions-file.html#BLOCK">block</ulink> }</literal>, resulting
1573 in <emphasis>both</emphasis> actions to apply.
1577 You can trace this process for any given URL by visiting <ulink
1578 url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
1582 More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
1583 Anatomy of an Action</link>.
1587 <!-- ~~~~~ New section ~~~~~ -->
1588 <sect2 id="af-patterns">
1589 <title>Patterns</title>
1591 Generally, a pattern has the form <literal><domain>/<path></literal>,
1592 where both the <literal><domain></literal> and <literal><path></literal>
1593 are optional. (This is why the pattern <literal>/</literal> matches all URLs).
1598 <term><literal>www.example.com/</literal></term>
1601 is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
1602 regardless of which document on that server is requested.
1607 <term><literal>www.example.com</literal></term>
1610 means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
1616 <term><literal>www.example.com/index.html</literal></term>
1619 matches only the single document <literal>/index.html</literal>
1620 on <literal>www.example.com</literal>.
1625 <term><literal>/index.html</literal></term>
1628 matches the document <literal>/index.html</literal>, regardless of the domain,
1629 i.e. on <emphasis>any</emphasis> web server.
1634 <term><literal>index.html</literal></term>
1637 matches nothing, since it would be interpreted as a domain name and
1638 there is no top-level domain called <literal>.html</literal>.
1645 <!-- ~~~~~ New section ~~~~~ -->
1646 <sect3><title>The Domain Pattern</title>
1649 The matching of the domain part offers some flexible options: if the
1650 domain starts or ends with a dot, it becomes unanchored at that end.
1656 <term><literal>.example.com</literal></term>
1659 matches any domain that <emphasis>ENDS</emphasis> in
1660 <literal>.example.com</literal>
1665 <term><literal>www.</literal></term>
1668 matches any domain that <emphasis>STARTS</emphasis> with
1669 <literal>www.</literal>
1674 <term><literal>.example.</literal></term>
1677 matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
1678 (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
1685 Additionally, there are wild-cards that you can use in the domain names
1686 themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
1687 stands for zero or more arbitrary characters, <quote>?</quote> stands for
1688 any single character, you can define character classes in square
1689 brackets and all of that can be freely mixed:
1694 <term><literal>ad*.example.com</literal></term>
1697 matches <quote>adserver.example.com</quote>,
1698 <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
1703 <term><literal>*ad*.example.com</literal></term>
1706 matches all of the above, and then some.
1711 <term><literal>.?pix.com</literal></term>
1714 matches <literal>www.ipix.com</literal>,
1715 <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
1720 <term><literal>www[1-9a-ez].example.c*</literal></term>
1723 matches <literal>www1.example.com</literal>,
1724 <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
1725 <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
1726 <literal>wwww.example.com</literal>.
1734 <!-- ~ End section ~ -->
1737 <!-- ~~~~~ New section ~~~~~ -->
1738 <sect3><title>The Path Pattern</title>
1741 <application>Privoxy</application> uses Perl compatible regular expressions
1742 (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
1747 There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
1748 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
1749 at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
1750 You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
1751 useful, which is available on-line at <ulink
1752 url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
1756 Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
1757 i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
1758 for the beginning of a line).
1762 Please also note that matching in the path is <emphasis>CASE INSENSITIVE</emphasis>
1763 by default, but you can switch to case sensitive at any point in the pattern by using the
1764 <quote>(?-i)</quote> switch: <literal>www.example.com/(?-i)PaTtErN.*</literal> will match
1765 only documents whose path starts with <literal>PaTtErN</literal> in
1766 <emphasis>exactly</emphasis> this capitalization.
1772 <!-- ~ End section ~ -->
1775 <!-- ~~~~~ New section ~~~~~ -->
1777 <sect2 id="actions">
1778 <title>Actions</title>
1780 All actions are disabled by default, until they are explicitly enabled
1781 somewhere in an actions file. Actions are turned on if preceded with a
1782 <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
1783 <literal>+action</literal> means <quote>do that action</quote>, e.g.
1784 <literal>+block</literal> means <quote>please block URLs that match the
1785 following patterns</quote>, and <literal>-block</literal> means <quote>don't
1786 block URLs that match the following patterns, even if <literal>+block</literal>
1787 previously applied.</quote>
1792 Again, actions are invoked by placing them on a line, enclosed in curly braces and
1793 separated by whitespace, like in
1794 <literal>{+some-action -some-other-action{some-parameter}}</literal>,
1795 followed by a list of URL patterns, one per line, to which they apply.
1796 Together, the actions line and the following pattern lines make up a section
1797 of the actions file.
1801 There are three classes of actions:
1808 Boolean, i.e the action can only be <quote>enabled</quote> or
1809 <quote>disabled</quote>. Syntax:
1813 +<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
1814 -<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
1817 Example: <literal>+block</literal>
1824 Parameterized, where some value is required in order to enable this type of action.
1829 +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
1830 # overwriting parameter from previous match if necessary
1831 -<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
1834 Note that if the URL matches multiple positive forms of a parameterized action,
1835 the last match wins, i.e. the params from earlier matches are simply ignored.
1838 Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
1844 Multi-value. These look exactly like parameterized actions,
1845 but they behave differently: If the action applies multiple times to the
1846 same URL, but with different parameters, <emphasis>all</emphasis> the parameters
1847 from <emphasis>all</emphasis> matches are remembered. This is used for actions
1848 that can be executed for the same request repeatedly, like adding multiple
1849 headers, or filtering through multiple filters. Syntax:
1853 +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
1854 -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
1855 # If it was the last one left, disable the action.
1856 <replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
1859 Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
1860 <literal>+filter{html-annoyances}</literal>
1868 If nothing is specified in any actions file, no <quote>actions</quote> are
1869 taken. So in this case <application>Privoxy</application> would just be a
1870 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
1871 privacy and blocking features you need (although the provided default actions
1872 files will give a good starting point).
1876 Later defined actions always over-ride earlier ones. So exceptions
1877 to any rules you make, should come in the latter part of the file (or
1878 in a file that is processed later when using multiple actions files). For
1879 multi-valued actions, the actions are applied in the order they are specified.
1880 Actions files are processed in the order they are defined in
1881 <filename>config</filename> (the default installation has three actions
1882 files). It also quite possible for any given URL pattern to match more than
1883 one pattern and thus more than one set of actions!
1886 <!-- start actions listing -->
1888 The list of valid <application>Privoxy</application> actions are:
1892 <!-- ********************************************************** -->
1893 <!-- Please note the below defined actions use id's that are -->
1894 <!-- probably linked from other places, so please don't change. -->
1896 <!-- ********************************************************** -->
1899 <!-- ~~~~~ New section ~~~~~ -->
1901 <sect3 renderas="sect4" id="add-header">
1902 <title>add-header</title>
1906 <term>Typical use:</term>
1908 <para>Confuse log analysis, custom applications</para>
1913 <term>Effect:</term>
1916 Sends a user defined HTTP header to the web server.
1923 <!-- boolean, parameterized, Multi-value -->
1925 <para>Multi-value.</para>
1930 <term>Parameter:</term>
1933 Any string value is possible. Validity of the defined HTTP headers is not checked.
1934 It is recommended that you use the <quote><literal>X-</literal></quote> prefix
1944 This action may be specified multiple times, in order to define multiple
1945 headers. This is rarely needed for the typical user. If you don't know what
1946 <quote>HTTP headers</quote> are, you definitely don't need to worry about this
1953 <term>Example usage:</term>
1956 <screen>+add-header{X-User-Tracking: sucks}</screen>
1964 <!-- ~~~~~ New section ~~~~~ -->
1965 <sect3 renderas="sect4" id="block">
1966 <title>block</title>
1970 <term>Typical use:</term>
1972 <para>Block ads or other obnoxious content</para>
1977 <term>Effect:</term>
1980 Requests for URLs to which this action applies are blocked, i.e. the requests are not
1981 forwarded to the remote server, but answered locally with a substitute page or image,
1982 as determined by the <literal><link linkend="handle-as-image">handle-as-image</link></literal>
1983 and <literal><link linkend="set-image-blocker">set-image-blocker</link></literal> actions.
1990 <!-- boolean, parameterized, Multi-value -->
1992 <para>Boolean.</para>
1997 <term>Parameter:</term>
2007 <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
2008 for requests to blocked pages. This page contains links to find out why the request
2009 was blocked, and a click-through to the blocked content (the latter only if compiled with the
2010 force feature enabled). The <quote>BLOCKED</quote> page adapts to the available
2011 screen space -- it displays full-blown if space allows, or miniaturized and text-only
2012 if loaded into a small frame or window. If you are using <application>Privoxy</application>
2013 right now, you can take a look at the
2014 <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
2018 A very important exception occurs if <emphasis>both</emphasis>
2019 <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
2020 apply to the same request: it will then be replaced by an image. If
2021 <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
2022 (see below) also applies, the type of image will be determined by its parameter,
2023 if not, the standard checkerboard pattern is sent.
2026 It is important to understand this process, in order
2027 to understand how <application>Privoxy</application> deals with
2028 ads and other unwanted content.
2031 The <literal><link linkend="filter">filter</link></literal>
2032 action can perform a very similar task, by <quote>blocking</quote>
2033 banner images and other content through rewriting the relevant URLs in the
2034 document's HTML source, so they don't get requested in the first place.
2035 Note that this is a totally different technique, and it's easy to confuse the two.
2041 <term>Example usage (section):</term>
2044 <screen>{+block} # Block and replace with "blocked" page
2045 .nasty-stuff.example.com
2047 {+block +handle-as-image} # Block and replace with image
2058 <!-- ~~~~~ New section ~~~~~ -->
2059 <sect3 renderas="sect4" id="crunch-incoming-cookies">
2060 <title>crunch-incoming-cookies</title>
2064 <term>Typical use:</term>
2067 Prevent the web server from setting any cookies on your system
2073 <term>Effect:</term>
2076 Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
2083 <!-- Boolean, Parameterized, Multi-value -->
2085 <para>Boolean.</para>
2090 <term>Parameter:</term>
2102 This action is only concerned with <emphasis>incoming</emphasis> cookies. For
2103 <emphasis>outgoing</emphasis> cookies, use
2104 <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
2105 Use <emphasis>both</emphasis> to disable cookies completely.
2108 It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
2109 with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
2110 since it would prevent the session cookies from being set.
2116 <term>Example usage:</term>
2119 <screen>+crunch-incoming-cookies</screen>
2127 <!-- ~~~~~ New section ~~~~~ -->
2128 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
2129 <title>crunch-outgoing-cookies</title>
2133 <term>Typical use:</term>
2136 Prevent the web server from reading any cookies from your system
2142 <term>Effect:</term>
2145 Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
2152 <!-- Boolean, Parameterized, Multi-value -->
2154 <para>Boolean.</para>
2159 <term>Parameter:</term>
2171 This action is only concerned with <emphasis>outgoing</emphasis> cookies. For
2172 <emphasis>incoming</emphasis> cookies, use
2173 <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
2174 Use <emphasis>both</emphasis> to disable cookies completely.
2177 It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
2178 with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
2179 since it would prevent the session cookies from being read.
2185 <term>Example usage:</term>
2188 <screen>+crunch-outgoing-cookies</screen>
2197 <!-- ~~~~~ New section ~~~~~ -->
2198 <sect3 renderas="sect4" id="deanimate-gifs">
2199 <title>deanimate-gifs</title>
2203 <term>Typical use:</term>
2205 <para>Stop those annoying, distracting animated GIF images.</para>
2210 <term>Effect:</term>
2213 De-animate GIF animations, i.e. reduce them to their first or last image.
2220 <!-- boolean, parameterized, Multi-value -->
2222 <para>Parameterized.</para>
2227 <term>Parameter:</term>
2230 <quote>last</quote> or <quote>first</quote>
2239 This will also shrink the images considerably (in bytes, not pixels!). If
2240 the option <quote>first</quote> is given, the first frame of the animation
2241 is used as the replacement. If <quote>last</quote> is given, the last
2242 frame of the animation is used instead, which probably makes more sense for
2243 most banner animations, but also has the risk of not showing the entire
2244 last frame (if it is only a delta to an earlier frame).
2247 You can safely use this action with patterns that will also match non-GIF
2248 objects, because no attempt will be made at anything that doesn't look like
2255 <term>Example usage:</term>
2258 <screen>+deanimate-gifs{last}</screen>
2265 <!-- ~~~~~ New section ~~~~~ -->
2266 <sect3 renderas="sect4" id="downgrade-http-version">
2267 <title>downgrade-http-version</title>
2271 <term>Typical use:</term>
2273 <para>Work around (very rare) problems with HTTP/1.1</para>
2278 <term>Effect:</term>
2281 Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
2288 <!-- boolean, parameterized, Multi-value -->
2290 <para>Boolean.</para>
2295 <term>Parameter:</term>
2307 This is a left-over from the time when <application>Privoxy</application>
2308 didn't support important HTTP/1.1 features well. It is left here for the
2309 unlikely case that you experience HTTP/1.1 related problems with some server
2310 out there. Not all (optional) HTTP/1.1 features are supported yet, so there
2311 is a chance you might need this action.
2317 <term>Example usage (section):</term>
2320 <screen>{+downgrade-http-version}
2321 problem-host.example.com</screen>
2329 <!-- ~~~~~ New section ~~~~~ -->
2330 <sect3 renderas="sect4" id="fast-redirects">
2331 <title>fast-redirects</title>
2335 <term>Typical use:</term>
2337 <para>Fool some click-tracking scripts and speed up indirect links</para>
2342 <term>Effect:</term>
2345 Cut off all but the last valid URL from requests.
2352 <!-- boolean, parameterized, Multi-value -->
2354 <para>Boolean.</para>
2359 <term>Parameter:</term>
2371 Many sites, like yahoo.com, don't just link to other sites. Instead, they
2372 will link to some script on their own servers, giving the destination as a
2373 parameter, which will then redirect you to the final target. URLs
2374 resulting from this scheme typically look like:
2375 <emphasis>http://some.place/click-tracker.cgi?target=http://some.where.else</emphasis>.
2378 Sometimes, there are even multiple consecutive redirects encoded in the
2379 URL. These redirections via scripts make your web browsing more traceable,
2380 since the server from which you follow such a link can see where you go
2381 to. Apart from that, valuable bandwidth and time is wasted, while your
2382 browser ask the server for one redirect after the other. Plus, it feeds
2386 This feature is currently not very smart and is scheduled for improvement.
2387 It is likely to break some sites. You should expect to need possibly
2388 many exceptions to this action, if it is enabled by default in
2389 <filename>default.action</filename>. Some sites just don't work without
2396 <term>Example usage:</term>
2399 <screen>{+fast-redirects}</screen>
2408 <!-- ~~~~~ New section ~~~~~ -->
2409 <sect3 renderas="sect4" id="filter">
2410 <title>filter</title>
2414 <term>Typical use:</term>
2416 <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc.</para>
2421 <term>Effect:</term>
2424 Text documents, including HTML and JavaScript, to which this action
2425 applies, are filtered on-the-fly through the specified regular expression
2426 based substitutions.
2433 <!-- boolean, parameterized, Multi-value -->
2435 <para>Parameterized.</para>
2440 <term>Parameter:</term>
2443 The name of a filter, as defined in the <link linkend="filter-file">filter file</link>
2444 (typically <filename>default.filter</filename>, set by the
2445 <literal><link linkend="filterfile">filterfile</link></literal>
2446 option in the <link linkend="config">config file</link>). Filtering
2447 can be completely disabled without the use of parameters.
2456 For your convenience, there are a number of pre-defined filters available
2457 in the distribution filter file that you can use. See the examples below for
2461 This is potentially a very powerful feature! But <quote>rolling your own</quote>
2462 filters requires a knowledge of regular expressions and HTML.
2465 Filtering requires buffering the page content, which may appear to
2466 slow down page rendering since nothing is displayed until all content has
2467 passed the filters. (It does not really take longer, but seems that way
2468 since the page is not incrementally displayed.) This effect will be more
2469 noticeable on slower connections.
2472 The amount of data that can be filtered is limited to the
2473 <literal><link linkend="buffer-limit">buffer-limit</link></literal>
2474 option in the main <link linkend="config">config file</link>. The
2475 default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
2476 data, and all pending data, is passed through unfiltered. Inappropriate
2477 MIME types are not filtered.
2480 At this time, <application>Privoxy</application> cannot (yet!) uncompress compressed
2481 documents. If you want filtering to work on all documents, even those that
2482 would normally be sent compressed, use the
2483 <literal><link linkend="prevent-compression">prevent-compression</link></literal>
2484 action in conjunction with <literal>filter</literal>.
2487 Filtering can achieve some of the same effects as the
2488 <literal><link linkend="block">block</link></literal>
2489 action, i.e. it can be used to block ads and banners. But the mechanism
2490 works quite differently. One effective use, is to block ad banners
2491 based on their size (see below), since many of these seem to be somewhat
2495 <link linkend="contact">Feedback</link> with suggestions for new or
2496 improved filters is particularly welcome!
2502 <term>Example usage (with filters from the distribution <filename>default.filter</filename> file):</term>
2505 <anchor id="filter-html-annoyances">
2506 <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
2509 <anchor id="filter-js-annoyances">
2510 <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
2513 <anchor id="filter-banners-by-size">
2514 <screen>+filter{banners-by-size} # Kill banners based on their size for this page (<emphasis>very</emphasis> efficient!)</screen>
2517 <anchor id="filter-banners-by-link">
2518 <screen>+filter{banners-by-link} # Kill banners based on the link they are contained in (experimental)</screen>
2521 <anchor id="filter-img-reorder">
2522 <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective</screen>
2525 <anchor id="filter-content-cookies">
2526 <screen>+filter{content-cookies} # Kill cookies that come sneaking in the HTML or JS content</screen>
2529 <anchor id="filter-popups">
2530 <screen>+filter{popups} # Kill all popups in JS and HTML</screen>
2533 <anchor id="filter-webbugs">
2534 <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
2537 <anchor id="filter-fun">
2538 <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
2541 <anchor id="filter-frameset-borders">
2542 <screen>+filter{frameset-borders} # Give frames a border and make them resizeable</screen>
2545 <anchor id="filter-refresh-tags">
2546 <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</screen>
2549 <anchor id="filter-nimda">
2550 <screen>+filter{nimda} # Remove Nimda (virus) code.</screen>
2553 <anchor id="filter-shockwave-flash">
2554 <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
2557 <anchor id="filter-crude-parental">
2558 <screen>+filter{crude-parental} # Kill all web pages that contain the words "sex" or "warez"</screen>
2561 <anchor id="filter-js-events">
2562 <screen>+filter{js-events} # Kill all JS event bindings (<emphasis>Radically destructive!</emphasis> Only for extra nasty sites) </screen>
2570 <!-- ~~~~~ New section ~~~~~ -->
2571 <sect3 renderas="sect4" id="handle-as-image">
2572 <title>handle-as-image</title>
2576 <term>Typical use:</term>
2578 <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they get blocked</emphasis>)</para>
2583 <term>Effect:</term>
2586 This action alone doesn't do anything noticeable. It just marks URLs as images.
2587 If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
2588 the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
2589 page, or a replacement image (as determined by the <literal><link
2590 linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
2591 client as a substitute for the blocked content.
2598 <!-- Boolean, Parameterized, Multi-value -->
2600 <para>Boolean.</para>
2605 <term>Parameter:</term>
2617 The below generic example section is actually part of <filename>default.action</filename>.
2618 It marks all URLs with well-known image file name extensions as images and should
2622 Users will probably only want to use the handle-as-image action in conjunction with
2623 <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
2624 reflect the file type, like in the second example section.
2627 Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad
2628 frames require an HTML page to be sent, or they won't display properly.
2629 Forcing <literal>handle-as-image</literal> in this situation will not replace the
2630 ad frame with an image, but lead to error messages.
2636 <term>Example usage (sections):</term>
2639 <screen># Generic image extensions:
2642 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
2644 # These don't look like images, but they're banners and should be
2645 # blocked as images:
2647 {+block +handle-as-image}
2648 some.nasty-banner-server.com/junk.cgi?output=trash
2650 # Banner source! Who cares if they also have non-image content?
2660 <!-- ~~~~~ New section ~~~~~ -->
2661 <sect3 renderas="sect4" id="hide-forwarded-for-headers">
2662 <title>hide-forwarded-for-headers</title>
2666 <term>Typical use:</term>
2668 <para>Improve privacy by hiding the true source of the request</para>
2673 <term>Effect:</term>
2676 Deletes any existing <quote>X-Forwarded-for:</quote> HTTP header from client requests,
2677 and prevents adding a new one.
2684 <!-- Boolean, Parameterized, Multi-value -->
2686 <para>Boolean.</para>
2691 <term>Parameter:</term>
2703 It is fairly safe to leave this on.
2706 This action is scheduled for improvement: It should be able to generate forged
2707 <quote>X-Forwarded-for:</quote> headers using random IP addresses from a specified network,
2708 to make successive requests from the same client look like requests from a pool of different
2709 users sharing the same proxy.
2715 <term>Example usage:</term>
2718 <screen>+hide-forwarded-for-headers</screen>
2726 <!-- ~~~~~ New section ~~~~~ -->
2727 <sect3 renderas="sect4" id="hide-from-header">
2728 <title>hide-from-header</title>
2732 <term>Typical use:</term>
2734 <para>Keep your (old and ill) browser from telling web servers your email address</para>
2739 <term>Effect:</term>
2742 Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
2750 <!-- Boolean, Parameterized, Multi-value -->
2752 <para>Parameterized.</para>
2757 <term>Parameter:</term>
2760 Keyword: <quote>block</quote>, or any user defined value.
2769 The keyword <quote>block</quote> will completely remove the header
2770 (not to be confused with the <literal><link linkend="block">block</link></literal>
2774 Alternately, you can specify any value you prefer to be sent to the web
2775 server. If you do, it is a matter of fairness not to use any address that
2776 is actually used by a real person.
2779 This action is rarely needed, as modern web browsers don't send
2780 <quote>From:</quote> headers anymore.
2786 <term>Example usage:</term>
2789 <screen>+hide-from-header{block}</screen> or
2790 <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
2798 <!-- ~~~~~ New section ~~~~~ -->
2799 <sect3 renderas="sect4" id="hide-referrer">
2800 <title>hide-referrer</title>
2801 <anchor id="hide-referer">
2804 <term>Typical use:</term>
2806 <para>Conceal which link you followed to get to a particular site</para>
2811 <term>Effect:</term>
2814 Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
2815 or replaces it with a forged one.
2822 <!-- Boolean, Parameterized, Multi-value -->
2824 <para>Parameterized.</para>
2829 <term>Parameter:</term>
2833 <para><quote>block</quote> to delete the header completely.</para>
2836 <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
2839 <para>Any other string to set a user defined referrer.</para>
2849 <quote>forge</quote> is the preferred option here, since some servers will
2850 not send images back otherwise, in an attempt to prevent their valuable
2851 content from being embedded elsewhere (and hence, without being surrounded
2852 by <emphasis>their</emphasis> banners).
2855 <literal>hide-referer</literal> is an alternate spelling of
2856 <literal>hide-referrer</literal> and the two can be can be freely
2857 substituted with each other. (<quote>referrer</quote> is the
2858 correct English spelling, however the HTTP specification has a bug - it
2859 requires it to be spelled as <quote>referer</quote>.)
2865 <term>Example usage:</term>
2868 <screen>+hide-referrer{forge}</screen> or
2869 <screen>+hide-referrer{http://www.yahoo.com/}</screen>
2877 <!-- ~~~~~ New section ~~~~~ -->
2878 <sect3 renderas="sect4" id="hide-user-agent">
2879 <title>hide-user-agent</title>
2883 <term>Typical use:</term>
2885 <para>Conceal your type of browser and client operating system</para>
2890 <term>Effect:</term>
2893 Replaces the value of the <quote>User-Agent:</quote> HTTP header
2894 in client requests with the specified value.
2901 <!-- Boolean, Parameterized, Multi-value -->
2903 <para>Parameterized.</para>
2908 <term>Parameter:</term>
2911 Any user-defined string.
2921 This breaks many web sites that depend on looking at this header in order
2922 to customize their content for different browsers (which, by the
2923 way, is <emphasis>NOT</emphasis> a <ulink
2924 url="http://www.javascriptkit.com/javaindex.shtml">smart way to do
2929 Using this action in multi-user setups or wherever different types of
2930 browsers will access the same <application>Privoxy</application> is
2931 <emphasis>not recommended</emphasis>. In single-user, single-browser
2932 setups, you might use it to delete your OS version information from
2933 the headers, because it is an invitation to exploit known bugs for your
2934 OS. It is also occasionally useful to forge this in order to access
2935 sites that won't let you in otherwise (though there may be a good
2936 reason in some cases). Example of this: some MSN sites will not
2937 let <application>Mozilla</application> enter, yet forging to a
2938 <application>Netscape 6.1</application> user-agent works just fine.
2939 (Must be just a silly MS goof, I'm sure :-).
2942 This action is scheduled for improvement.
2948 <term>Example usage:</term>
2951 <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
2959 <!-- ~~~~~ New section ~~~~~ -->
2960 <sect3 renderas="sect4" id="kill-popups">
2961 <title>kill-popups<anchor id="kill-popup"></title>
2965 <term>Typical use:</term>
2967 <para>Eliminate those annoying pop-up windows</para>
2972 <term>Effect:</term>
2975 While loading the document, replace JavaScript code that opens
2976 pop-up windows with (syntactically neutral) dummy code on the fly.
2983 <!-- Boolean, Parameterized, Multi-value -->
2985 <para>Boolean.</para>
2990 <term>Parameter:</term>
3002 This action is easily confused with the built-in, hardwired <literal><link linkend="filter">filter</link></literal>
3003 action, but there are important differences: For <literal>kill-popups</literal>,
3004 the document need not be buffered, so it can be incrementally rendered while
3005 downloading. But <literal>kill-popups</literal> doesn't catch as many pop-ups as
3007 linkend="filter">filter</link>{<replaceable>popups</replaceable>}</literal>
3011 Think of it as a fast and efficient replacement for a filter that you
3012 can use if you don't want any filtering at all. Note that it doesn't make
3013 sense to combine it with any <literal><link linkend="filter">filter</link></literal> action,
3014 since as soon as one <literal><link linkend="filter">filter</link></literal> applies,
3015 the whole document needs to be buffered anyway, which destroys the advantage of
3016 the <literal>kill-popups</literal> action over its filter equivalent.
3019 Killing all pop-ups is a dangerous business. Many shops and banks rely on
3020 pop-ups to display forms, shopping carts etc, and killing only the unwanted pop-ups
3021 would require artificial intelligence in <application>Privoxy</application>.
3022 If the only kind of pop-ups that you want to kill are exit consoles (those
3023 <emphasis>really nasty</emphasis> windows that appear when you close an other
3024 one), you might want to use
3026 linkend="filter">filter</link>{<replaceable>js-annoyances</replaceable>}</literal>
3032 An alternate spelling is <literal>+kill-popup</literal>, which is
3040 <term>Example usage:</term>
3042 <para><screen>+kill-popups</screen></para>
3049 <!-- ~~~~~ New section ~~~~~ -->
3050 <sect3 renderas="sect4" id="limit-connect">
3051 <title>limit-connect</title>
3055 <term>Typical use:</term>
3057 <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay</para>
3062 <term>Effect:</term>
3065 Specifies to which ports HTTP CONNECT requests are allowable.
3072 <!-- Boolean, Parameterized, Multi-value -->
3074 <para>Parameterized.</para>
3079 <term>Parameter:</term>
3082 A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
3083 defaulting to 0 and the maximum to 65K).
3092 By default, i.e. if no <literal>limit-connect</literal> action applies,
3093 <application>Privoxy</application> only allows HTTP CONNECT
3094 requests to port 443 (the standard, secure HTTPS port). Use
3095 <literal>limit-connect</literal> if more fine-grained control is desired
3096 for some or all destinations.
3099 The CONNECT methods exists in HTTP to allow access to secure websites
3100 (<quote>https://</quote> URLs) through proxies. It works very simply:
3101 the proxy connects to the server on the specified port, and then
3102 short-circuits its connections to the client and to the remote server.
3103 This can be a big security hole, since CONNECT-enabled proxies can be
3104 abused as TCP relays very easily.
3107 If you don't know what any of this means, there probably is no reason to
3108 change this one, since the default is already very restrictive.
3114 <term>Example usages:</term>
3116 <!-- I had trouble getting the spacing to look right in my browser -->
3117 <!-- I probably have the wrong font setup, bollocks. -->
3118 <!-- Apparently the emphasis tag uses a proportional font no matter what -->
3120 <screen>+limit-connect{443} # This is the default and need not be specified.
3121 +limit-connect{80,443} # Ports 80 and 443 are OK.
3122 +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
3123 +limit-connect{-} # All ports are OK (gaping security hole!)</screen>
3130 <!-- ~~~~~ New section ~~~~~ -->
3131 <sect3 renderas="sect4" id="prevent-compression">
3132 <title>prevent-compression</title>
3136 <term>Typical use:</term>
3139 Ensure that servers send the content uncompressed, so it can be
3140 passed through <literal><link linkend="filter">filter</link></literal>s
3146 <term>Effect:</term>
3149 Adds a header to the request that asks for uncompressed transfer.
3156 <!-- Boolean, Parameterized, Multi-value -->
3158 <para>Boolean.</para>
3163 <term>Parameter:</term>
3175 More and more websites send their content compressed by default, which
3176 is generally a good idea and saves bandwidth. But for the <literal><link
3177 linkend="filter">filter</link></literal>, <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
3178 and <literal><link linkend="kill-popups">kill-popups</link></literal> actions to work,
3179 <application>Privoxy</application> needs access to the uncompressed data.
3180 Unfortunately, <application>Privoxy</application> can't yet(!) uncompress, filter, and
3181 re-compress the content on the fly. So if you want to ensure that all websites, including
3182 those that normally compress, can be filtered, you need to use this action.
3185 This will slow down transfers from those websites, though. If you use any of the above-mentioned
3186 actions, you will typically want to use <literal>prevent-compression</literal> in conjunction
3190 Note that some (rare) ill-configured sites don't handle requests for uncompressed
3191 documents correctly (they send an empty document body). If you use <literal>prevent-compression</literal>
3192 per default, you'll have to add exceptions for those sites. See the example for how to do that.
3198 <term>Example usage (sections):</term>
3201 <screen># Set default:
3203 {+prevent-compression}
3206 # Make exceptions for ill sites:
3208 {-prevent-compression}
3210 www.pclinuxonline.com</screen>
3219 <!-- ~~~~~ New section ~~~~~ -->
3220 <sect3 renderas="sect4" id="send-vanilla-wafer">
3221 <title>send-vanilla-wafer</title>
3225 <term>Typical use:</term>
3228 Feed log analysis scripts with useless data.
3234 <term>Effect:</term>
3237 Sends a cookie with each request stating that you do not accept any copyright
3238 on cookies sent to you, and asking the site operator not to track you.
3245 <!-- Boolean, Parameterized, Multi-value -->
3247 <para>Boolean.</para>
3252 <term>Parameter:</term>
3264 The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
3267 This action is rarely used and not enabled in the default configuration.
3273 <term>Example usage:</term>
3276 <screen>+send-vanilla-wafer</screen>
3285 <!-- ~~~~~ New section ~~~~~ -->
3286 <sect3 renderas="sect4" id="send-wafer">
3287 <title>send-wafer</title>
3291 <term>Typical use:</term>
3294 Send custom cookies or feed log analysis scripts with even more useless data.
3300 <term>Effect:</term>
3303 Sends a custom, user-defined cookie with each request.
3310 <!-- Boolean, Parameterized, Multi-value -->
3312 <para>Multi-value.</para>
3317 <term>Parameter:</term>
3320 A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
3321 class="parameter">value</replaceable></quote>.
3330 Being multi-valued, multiple instances of this action can apply to the same request,
3331 resulting in multiple cookies being sent.
3334 This action is rarely used and not enabled in the default configuration.
3339 <term>Example usage (section):</term>
3342 <screen>{+send-wafer{UsingPrivoxy=true}}
3343 my-internal-testing-server.void</screen>
3351 <!-- ~~~~~ New section ~~~~~ -->
3352 <sect3 renderas="sect4" id="session-cookies-only">
3353 <title>session-cookies-only</title>
3357 <term>Typical use:</term>
3360 Allow only temporary <quote>session</quote> cookies (for the current browser session <emphasis>only</emphasis>).
3366 <term>Effect:</term>
3369 Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote> server headers.
3370 Most browsers will not store such cookies permanently and forget them in between sessions.
3377 <!-- Boolean, Parameterized, Multi-value -->
3379 <para>Boolean.</para>
3384 <term>Parameter:</term>
3396 This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
3397 <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
3398 websites that insist or rely on setting cookies, without compromising your privacy too badly.
3401 Most browsers will not permanently store cookies that have been processed by
3402 <literal>session-cookies-only</literal> and will forget about them between sessions.
3403 This makes profiling cookies useless, but won't break sites which require cookies so
3404 that you can log in for transactions. This is generally turned on for all
3405 sites, and is the recommended setting.
3408 It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
3409 together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
3410 <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
3411 will be plainly killed.
3414 Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
3415 field. If you use an exotic browser, you might want to try it out to be sure.
3421 <term>Example usage:</term>
3424 <screen>+session-cookies-only</screen>
3432 <!-- ~~~~~ New section ~~~~~ -->
3433 <sect3 renderas="sect4" id="set-image-blocker">
3434 <title>set-image-blocker</title>
3438 <term>Typical use:</term>
3440 <para>Choose the replacement for blocked images</para>
3445 <term>Effect:</term>
3448 This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
3449 <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
3450 linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
3451 apply, i.e. if the request is to be blocked as an image,
3452 <emphasis>then</emphasis> the parameter of this action decides what will be
3453 sent as a replacement.
3460 <!-- Boolean, Parameterized, Multi-value -->
3462 <para>Parameterized.</para>
3467 <term>Parameter:</term>
3472 <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
3473 decent, scales very well, and makes it obvious where banners were busted.
3478 <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
3479 completely, but makes it hard to detect where <application>Privoxy</application> has blocked
3480 images on a given page and complicates troubleshooting if <application>Privoxy</application>
3481 has blocked innocent images, like navigation icons.
3486 <quote><replaceable class="parameter">target-url</replaceable></quote> to
3487 send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
3488 to any image anywhere, even in your local filesystem (via <quote>file:///</quote> URL).
3491 A good application of redirects is to use special <application>Privoxy</application>-built-in
3492 URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
3493 This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
3494 the first place, but enables your browser to cache the replacement image, instead of requesting
3495 it over and over again.
3506 The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
3507 class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
3508 either <quote>blank</quote> or <quote>pattern</quote>.
3511 There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
3512 used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
3513 Auto will select the type of image that would have applied to the referring page, had it been an image.
3519 <term>Example usage:</term>
3525 <screen>+set-image-blocker{pattern}</screen>
3528 Redirect to the BSD devil:
3531 <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
3534 Redirect to the built-in pattern for better caching:
3537 <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
3545 <!-- ~~~~~ New section ~~~~~ -->
3547 <title>Summary</title>
3549 Note that many of these actions have the potential to cause a page to
3550 misbehave, possibly even not to display at all. There are many ways
3551 a site designer may choose to design his site, and what HTTP header
3552 content, and other criteria, he may depend on. There is no way to have hard
3553 and fast rules for all sites. See the <link
3554 linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
3560 <!-- ~~~~~ New section ~~~~~ -->
3561 <sect2 id="aliases">
3562 <title>Aliases</title>
3564 Custom <quote>actions</quote>, known to <application>Privoxy</application>
3565 as <quote>aliases</quote>, can be defined by combining other actions.
3566 These can in turn be invoked just like the built-in actions.
3567 Currently, an alias name can contain any character except space, tab,
3569 <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
3570 recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
3571 <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
3572 Alias names are not case sensitive, and are not required to start with a
3573 <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
3577 Aliases can be used throughout the actions file, but they <emphasis>must be
3578 defined in a special section at the top of the file!</emphasis>
3579 And there can only be one such section per actions file. Each actions file may
3580 have its own alias section, and the aliases defined in it are only visible
3584 There are two main reasons to use aliases: One is to save typing for frequently
3585 used combinations of actions, the other one is a gain in flexibility: If you
3586 decide once how you want to handle shops by defining an alias called
3587 <quote>shop</quote>, you can later change your policy on shops in
3588 <emphasis>one</emphasis> place, and your changes will take effect everywhere
3589 in the actions file where the <quote>shop</quote> alias is used. Calling aliases
3590 by their purpose also makes your actions files more readable.
3593 Currently, there is one big drawback to using aliases, though:
3594 <application>Privoxy</application>'s built-in web-based action file
3595 editor honors aliases when reading the actions files, but it expands
3596 them before writing. So the effects of your aliases are of course preserved,
3597 but the aliases themselves are lost when you edit sections that use aliases
3599 This is likely to change in future versions of <application>Privoxy</application>.
3603 Now let's define some aliases...
3608 # Useful custom aliases we can use later.
3610 # Note the (required!) section header line and that this section
3611 # must be at the top of the actions file!
3615 # These aliases just save typing later:
3616 # (Note that some already use other aliases!)
3618 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
3619 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
3620 block-as-image = +block +handle-as-image
3621 mercy-for-cookies = -crunch-all-cookies -session-cookies-only
3623 # These aliases define combinations of actions
3624 # that are useful for certain types of sites:
3626 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
3627 shop = -crunch-all-cookies -filter{popups} -kill-popups
3629 # Short names for other aliases, for really lazy people ;-)
3631 c0 = +crunch-all-cookies
3632 c1 = -crunch-all-cookies</screen>
3636 ...and put them to use. These sections would appear in the lower part of an
3637 actions file and define exceptions to the default actions (as specified further
3638 up for the <quote>/</quote> pattern):
3643 # These sites are either very complex or very keen on
3644 # user data and require minimal interference to work:
3647 .office.microsoft.com
3648 .windowsupdate.microsoft.com
3652 # Allow cookies (for setting and retrieving your customer data)
3656 .worldpay.com # for quietpc.com
3659 # These shops require pop-ups:
3661 {shop -kill-popups -filter{popups}}
3663 .overclockers.co.uk</screen>
3667 Aliases like <quote>shop</quote> and <quote>fragile</quote> are often used for
3668 <quote>problem</quote> sites that require some actions to be disabled
3669 in order to function properly.
3673 <!-- ~~~~~ New section ~~~~~ -->
3674 <sect2 id="act-examples">
3675 <title>Actions Files Tutorial</title>
3677 The above chapters have shown <link linkend="actions-file">which actions files
3678 there are and how they are organized</link>, how actions are <link
3679 linkend="actions">specified</link> and <link linkend="actions-apply">applied
3680 to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
3681 define and use <link linkend="aliases">aliases</link>. Now, let's look at an
3682 example <filename>default.action</filename> and <filename>user.action</filename>
3683 file and see how all these pieces come together:
3686 <sect3><title>default.action</title>
3689 Every config file should start with a short comment stating its purpose:
3693 <screen># Sample default.action file <developers@privoxy.org></screen>
3697 Then, since this is the <filename>default.action</filename> file, the
3698 first section is a special section for internal use that you needn't
3699 change or worry about:
3704 ##########################################################################
3705 # Settings -- Don't change! For internal Privoxy use ONLY.
3706 ##########################################################################
3709 for-privoxy-version=3.0</screen>
3713 After that comes the (optional) alias section. We'll use the example
3714 section from the above <link linkend="aliases">chapter on aliases</link>,
3715 that also explains why and how aliases are used:
3720 ##########################################################################
3722 ##########################################################################
3725 # These aliases just save typing later:
3726 # (Note that some already use other aliases!)
3728 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
3729 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
3730 block-as-image = +block +handle-as-image
3731 mercy-for-cookies = -crunch-all-cookies -session-cookies-only
3733 # These aliases define combinations of actions
3734 # that are useful for certain types of sites:
3736 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
3737 shop = mercy-for-cookies -filter{popups} -kill-popups</screen>
3741 Now come the regular sections, i.e. sets of actions, accompanied
3742 by URL patterns to which they apply. Remember <emphasis>all actions
3743 are disabled when matching starts</emphasis>, so we have to explicitly
3744 enable the ones we want.
3748 The first regular section is probably the most important. It has only
3749 one pattern, <quote><literal>/</literal></quote>, but this pattern
3750 <link linkend="af-patterns">matches all URLs</link>. Therefore, the
3751 set of actions used in this <quote>default</quote> section <emphasis>will
3752 be applied to all requests as a start</emphasis>. It can be partly or
3753 wholly overridden by later matches further down this file, or in user.action,
3754 but it will still be largely responsible for your overall browsing
3759 Again, at the start of matching, all actions are disabled, so there is
3760 no real need to disable any actions here, but we will do that nonetheless,
3761 to have a complete listing for your reference. (Remember: a <quote>+</quote>
3762 preceding the action name enables the action, a <quote>-</quote> disables!).
3763 Also note how this long line has been made more readable by splitting it into
3764 multiple lines with line continuation.
3769 ##########################################################################
3770 # "Defaults" section:
3771 ##########################################################################
3773 -<link linkend="ADD-HEADER">add-header</link> \
3774 -<link linkend="BLOCK">block</link> \
3775 -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
3776 -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
3777 +<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
3778 -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
3779 +<link linkend="FAST-REDIRECTS">fast-redirects</link> \
3780 +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
3781 +<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
3782 -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
3783 +<link linkend="FILTER-POPUPS">filter{popups}</link> \
3784 +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
3785 -<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
3786 -<link linkend="FILTER-FUN">filter{fun}</link> \
3787 +<link linkend="FILTER-NIMDA">filter{nimda}</link> \
3788 +<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
3789 -<link linkend="FILTER-BANNERS-BY-LINK">filter{banners-by-link}</link> \
3790 -<link linkend="FILTER-IMG-REORDER">filter{img-reorder}</link> \
3791 -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
3792 -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
3793 -<link linkend="FILTER-JS-EVENTS">filter{js-events}</link> \
3794 -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
3795 +<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
3796 +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
3797 +<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
3798 -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
3799 -<link linkend="KILL-POPUPS">kill-popups</link> \
3800 -<link linkend="LIMIT-CONNECT">limit-connect</link> \
3801 +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
3802 -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
3803 -<link linkend="SEND-WAFER">send-wafer</link> \
3804 +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
3805 +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
3807 / # forward slash will match *all* potential URL patterns.</screen>
3811 The default behavior is now set. Note that some actions, like not hiding
3812 the user agent, are part of a <quote>general policy</quote> that applies
3813 universally and won't get any exceptions defined later. Other choices,
3814 like not blocking (which is <emphasis>understandably</emphasis> the
3815 default!) need exceptions, i.e. we need to specify explicitly what we
3816 want to block in later sections.
3817 We will also want to make exceptions from our general pop-up-killing,
3818 and use our defined aliases for that.
3822 The first of our specialized sections is concerned with <quote>fragile</quote>
3823 sites, i.e. sites that require minimum interference, because they are either
3824 very complex or very keen on tracking you (and have mechanisms in place that
3825 make them unusable for people who avoid being tracked). We will simply use
3826 our pre-defined <literal>fragile</literal> alias instead of stating the list
3827 of actions explicitly:
3832 ##########################################################################
3833 # Exceptions for sites that'll break under the default action set:
3834 ##########################################################################
3836 # "Fragile" Use a minimum set of actions for these sites (see alias above):
3839 .office.microsoft.com # surprise, surprise!
3840 .windowsupdate.microsoft.com</screen>
3844 Shopping sites are not as fragile, but they typically
3845 require cookies to log in, and pop-up windows for shopping
3846 carts or item details. Again, we'll use a pre-defined alias:
3855 .worldpay.com # for quietpc.com
3857 .scan.co.uk</screen>
3861 Then, there are sites which rely on pop-up windows (yuck!) to work.
3862 Since we made pop-up-killing our default above, we need to make exceptions
3863 now. <ulink url="http://www.mozilla.org/">Mozilla</ulink> users, who
3864 can turn on smart handling of unwanted pop-ups in their browsers, can
3866 -<literal><link linkend="FILTER-POPUPS">filter{popups}</link></literal> (and
3867 -<literal><link linkend="KILL-POPUPS">kill-popups</link></literal>) above
3868 and hence don't need this section. Anyway, disabling an already disabled
3869 action doesn't hurt, so we'll define our exceptions regardless of what was
3870 chosen in the defaults section:
3875 # These sites require pop-ups too :(
3877 { -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="FILTER-POPUPS">filter{popups}</link> }
3880 .deutsche-bank-24.de</screen>
3884 The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
3885 action, which we enabled per default above, breaks some sites. So disable
3886 it for popular sites where we know it misbehaves:
3891 { -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
3895 .altavista.com/.*(like|url|link):http
3896 .altavista.com/trans.*urltext=http
3897 .nytimes.com</screen>
3901 It is important that <application>Privoxy</application> knows which
3902 URLs belong to images, so that <emphasis>if</emphasis> they are to
3903 be blocked, a substitute image can be sent, rather than an HTML page.
3904 Contacting the remote site to find out is not an option, since it
3905 would destroy the loading time advantage of banner blocking, and it
3906 would feed the advertisers (in terms of money <emphasis>and</emphasis>
3907 information). We can mark any URL as an image with the <literal><link
3908 linkend="handle-as-image">handle-as-image</link></literal> action,
3909 and marking all URLs that end in a known image file extension is a
3915 ##########################################################################
3917 ##########################################################################
3919 # Define which file types will be treated as images, in case they get
3920 # blocked further down this file:
3922 { +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
3923 /.*\.(gif|jpe?g|png|bmp|ico)$</screen>
3927 And then there are known banner sources. They often use scripts to
3928 generate the banners, so it won't be visible from the URL that the
3929 request is for an image. Hence we block them <emphasis>and</emphasis>
3930 mark them as images in one go, with the help of our
3931 <literal>block-as-image</literal> alias defined above. (We could of
3932 course just as well use <literal>+<link linkend="block">block</link>
3933 +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
3934 Remember that the type of the replacement image is chosen by the
3935 <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
3936 action. Since all URLs have matched the default section with its
3937 <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
3938 action before, it still applies and needn't be repeated:
3943 # Known ad generators:
3948 .ad.*.doubleclick.net
3949 .a.yimg.com/(?:(?!/i/).)*$
3950 .a[0-9].yimg.com/(?:(?!/i/).)*$
3957 One of the most important jobs of <application>Privoxy</application>
3958 is to block banners. A huge bunch of them are already <quote>blocked</quote>
3959 by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
3960 action, which we enabled above, and which deletes the references to banner
3961 images from the pages while they are loaded, so the browser doesn't request
3962 them anymore, and hence they don't need to be blocked here. But this naturally
3963 doesn't catch all banners, and some people choose not to use filters, so we
3964 need a comprehensive list of patterns for banner URLs here, and apply the
3965 <literal><link linkend="block">block</link></literal> action to them.
3968 First comes a bunch of generic patterns, which do most of the work, by
3969 matching typical domain and path name components of banners. Then comes
3970 a list of individual patterns for specific sites, which is omitted here
3971 to keep the example short:
3976 ##########################################################################
3977 # Block these fine banners:
3978 ##########################################################################
3979 { <link linkend="BLOCK">+block</link> }
3987 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
3988 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
3990 # Site-specific patterns (abbreviated):
3992 .hitbox.com</screen>
3996 You wouldn't believe how many advertisers actually call their banner
3997 servers ads.<replaceable>company</replaceable>.com, or call the directory
3998 in which the banners are stored simply <quote>banners</quote>. So the above
3999 generic patterns are surprisingly effective.
4002 But being very generic, they necessarily also catch URLs that we don't want
4003 to block. The pattern <literal>.*ads.</literal> e.g. catches
4004 <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
4005 but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
4006 <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
4007 well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
4011 Note that these are exceptions to exceptions from the default! Consider the URL
4012 <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
4013 so it wouldn't get blocked. Then comes the defaults section, which matches the
4014 URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
4015 action once again. Then it matches <literal>.*ads.</literal>, an exception to the
4016 general non-blocking policy, and suddenly
4017 <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
4018 <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
4019 applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
4020 with no <literal><link linkend="BLOCK">block</link></literal> action applying.
4025 ##########################################################################
4026 # Save some innocent victims of the above generic block patterns:
4027 ##########################################################################
4031 { -<link linkend="BLOCK">block</link> }
4032 adv[io]*. # (for advogato.org and advice.*)
4033 adsl. # (has nothing to do with ads)
4034 ad[ud]*. # (adult.* and add.*)
4035 .edu # (universities don't host banners (yet!))
4036 .*loads. # (downloads, uploads etc)
4044 www.globalintersec.com/adv # (adv = advanced)
4045 www.ugu.com/sui/ugu/adv</screen>
4049 Filtering source code can have nasty side effects,
4050 so make an exception for our friends at sourceforge.net,
4051 and all paths with <quote>cvs</quote> in them. Note that
4052 <literal>-<link linkend="FILTER">filter</link></literal>
4053 disables <emphasis>all</emphasis> filters in one fell swoop!
4058 # Don't filter code!
4060 { -<link linkend="FILTER">filter</link> }
4062 .sourceforge.net</screen>
4066 The actual <filename>default.action</filename> is of course more
4067 comprehensive, but we hope this example made clear how it works.
4072 <sect3><title>user.action</title>
4075 So far we are painting with a broad brush by setting general policies,
4076 which would be a reasonable starting point for many people. Now,
4077 you might want to be more specific and have customized rules that
4078 are more suitable to your personal habits and preferences. These would
4079 be for narrowly defined situations like your ISP or your bank, and should
4080 be placed in <filename>user.action</filename>, which is parsed after all other
4081 actions files and hence has the last word, over-riding any previously
4082 defined actions. <filename>user.action</filename> is also a
4083 <emphasis>safe</emphasis> place for your personal settings, since
4084 <filename>default.action</filename> is actively maintained by the
4085 <application>Privoxy</application> developers and you'll probably want
4086 to install updated versions from time to time.
4090 So let's look at a few examples of things that one might typically do in
4091 <filename>user.action</filename>:
4095 <!-- brief sample user.action here -->
4099 # My user.action file. <fred@foobar.com></screen>
4103 As <link linkend="aliases">aliases</link> are local to the actions
4104 file that they are defined in, you can't use the ones from
4105 <filename>default.action</filename>, unless you repeat them here:
4110 # (Re-)define aliases for this file:
4113 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
4114 mercy-for-cookies = -crunch-all-cookies -session-cookies-only
4115 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
4116 shop = mercy-for-cookies -filter{popups} -kill-popups
4117 allow-ads = -block -filter{banners-by-size} # (see below)</screen>
4122 Say you have accounts on some sites that you visit regularly, and
4123 you don't want to have to log in manually each time. So you'd like
4124 to allow persistent cookies for these sites. The
4125 <literal>mercy-for-cookies</literal> alias defined above does exactly
4126 that, i.e. it disables crunching of cookies in any direction, and
4127 processing of cookies to make them temporary.
4132 { mercy-for-cookies }
4137 .redhat.com</screen>
4141 Your bank needs popups and is allergic to some filter, but you don't
4142 know which, so you disable them all:
4147 { -<link linkend="FILTER">filter</link> -<link linkend="KILL-POPUPS">kill-popups</link> }
4148 .your-home-banking-site.com</screen>
4152 While browsing the web with <application>Privoxy</application> you
4153 noticed some ads that sneaked through, but you were too lazy to
4154 report them through our fine and easy <link linkend="contact">feedback</link>
4155 system, so you have added them here:
4160 { +<link linkend="BLOCK">block</link> }
4161 www.a-popular-site.com/some/unobvious/path
4162 another.popular.site.net/more/junk/here/</screen>
4166 Note that, assuming the banners in the above example have regular image
4167 extensions (most do),
4168 <literal>+<link linkend="HANDLE-AS-IMAGE">handle-as-image</link></literal>
4169 need not be specified, since all URLs ending in these extensions will
4170 already have been tagged as images in the relevant section of
4171 <filename>default.action</filename> by now.
4175 Then you noticed that the default configuration breaks Forbes Magazine,
4176 but you were too lazy to find out which action is the culprit, and you
4177 were again too lazy to give <link linkend="contact">feedback</link>, so
4178 you just used the <literal>fragile</literal> alias on the site, and
4179 -- whoa! -- it worked:
4185 .forbes.com</screen>
4189 You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
4190 but it is disabled in the distributed actions file. (My colleagues on the team just
4191 don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
4192 update-safe config, once and for all:
4197 { +<link linkend="filter-fun">filter{fun}</link> }
4198 / # For ALL sites!</screen>
4202 Note that the above is not really a good idea: There are exceptions
4203 to the filters in <filename>default.action</filename> for things that
4204 really shouldn't be filtered, like code on CVS->Web interfaces. Since
4205 <filename>user.action</filename> has the last word, these exceptions
4206 won't be valid for the <quote>fun</quote> filtering specified here.
4210 Finally, you might think about how your favourite free websites are
4211 funded, and find that they rely on displaying banner advertisements
4212 to survive. So you might want to specifically allow banners for those
4213 sites that you feel provide value to you:
4225 Note that <literal>allow-ads</literal> has been aliased to
4226 <literal>-<link linkend="block">block</link></literal>
4227 <literal>-<link linkend="filter-banners-by-size">filter{banners-by-size}</link></literal>
4233 <!-- ~ End section ~ -->
4237 <!-- ~ End section ~ -->
4239 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
4241 <sect1 id="filter-file">
4242 <title>The Filter File</title>
4245 All text substitutions that can be invoked through the
4246 <literal><link linkend="filter">filter</link></literal> action
4247 must first be defined in the filter file, which is typically
4248 called <filename>default.filter</filename> and which can be
4249 selected through the <literal>
4250 <link linkend="filterfile">filterfile</link></literal> config
4255 Typical reasons for doing such substitutions are to eliminate
4256 common annoyances in HTML and JavaScript, such as pop-up windows,
4257 exit consoles, crippled windows without navigation tools, the
4258 infamous <BLINK> tag etc, to suppress images with certain
4259 width and height attributes (standard banner sizes or web-bugs),
4260 or just to have fun. The possibilities are endless.
4264 Filtering works on any text-based document type, including plain
4265 text, HTML, JavaScript, CSS etc. (all <literal>text/*</literal>
4266 MIME types). Substitutions are made at the source level, so if
4267 you want to <quote>roll your own</quote> filters, you should be
4268 familiar with HTML syntax.
4272 Just like the <link linkend="actions-file">actions files</link>, the
4273 filter file is organized in sections, which are called <emphasis>filters</emphasis>
4274 here. Each filter consists of a heading line, that starts with the
4275 <emphasis>keyword</emphasis> <literal>FILTER:</literal>, followed by
4276 the filter's <emphasis>name</emphasis>, and a short (one line)
4277 <emphasis>description</emphasis> of what it does. Below that line
4278 come the <emphasis>jobs</emphasis>, i.e. lines that define the actual
4279 text substitutions. By convention, the name of a filter
4280 should describe what the filter <emphasis>eliminates</emphasis>. The
4281 comment is used in the <ulink url="http://config.privoxy.org/">web-based
4282 user interface</ulink>.
4286 Once a filter called <replaceable>name</replaceable> has been defined
4287 in the filter file, it can be invoked by using an action of the form
4288 +<literal><link linkend="filter">filter</link>{<replaceable>name</replaceable>}</literal>
4289 in any <link linkend="actions-file">actions file</link>.
4293 A filter header line for a filter called <quote>foo</quote> could look
4298 <screen>FILTER: foo Replace all "foo" with "bar"</screen>
4302 Below that line, and up to the next header line, come the jobs that
4303 define what text replacements the filter executes. They are specified
4304 in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
4305 <literal>s///</literal> operator. If you are familiar with Perl, you
4306 will find this to be quite intuitive, and may want to look at the
4307 <ulink url="http://www.oesterhelt.org/pcrs/pcrs.3.html">PCRS man page</ulink>
4308 for the subtle differences to Perl behaviour. Most notably, the non-standard
4309 option letter <literal>U</literal> is supported, which turns the default
4310 to ungreedy matching.
4314 If you are new to regular expressions, you might want to take a look at
4315 the <link linkend="regex">Appendix on regular expressions</link>, and
4316 see the <ulink url="http://perldoc.com/perl5.6.1/pod/perl.html">Perl
4318 <ulink url="http://perldoc.com/perl5.6.1/pod/perlop.html#s-PATTERN-REPLACEMENT-egimosx">the
4319 <literal>s///</literal> operator's syntax</ulink> and <ulink
4320 url="http://perldoc.com/perl5.6.1/pod/perlre.html">Perl-style regular
4321 expressions</ulink> in general.
4322 The below examples might also help to get you started.
4325 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
4327 <sect2><title>Filter File Tutorial</title>
4329 Now, let's complete our <quote>foo</quote> filter. We have already defined
4330 the heading, but the jobs are still missing. Since all it does is to replace
4331 <quote>foo</quote> with <quote>bar</quote>, there is only one (trivial) job
4336 <screen>s/foo/bar/</screen>
4340 But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
4341 of <quote>foo</quote> should be replaced? Our current job will only take
4342 care of the first <quote>foo</quote> on each page. For global substitution,
4343 we'll need to add the <literal>g</literal> option:
4347 <screen>s/foo/bar/g</screen>
4351 Our complete filter now looks like this:
4354 <screen>FILTER: foo Replace all "foo" with "bar"
4355 s/foo/bar/g</screen>
4359 Let's look at some real filters for more interesting examples. Here you see
4360 a filter that protects against some common annoyances that arise from JavaScript
4361 abuse. Let's look at its jobs one after the other:
4367 FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
4369 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
4371 s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg</screen>
4375 Following the header line and a comment, you see the job. Note that it uses
4376 <literal>|</literal> as the delimiter instead of <literal>/</literal>, because
4377 the pattern contains a forward slash, which would otherwise have to be escaped
4378 by a backslash (<literal>\</literal>).
4382 Now, let's examine the pattern: it starts with the text <literal><script.*</literal>
4383 enclosed in parentheses. Since the dot matches any character, and <literal>*</literal>
4384 means: <quote>Match an arbitrary number of the element left of myself</quote>, this
4385 matches <quote><script</quote>, followed by <emphasis>any</emphasis> text, i.e.
4386 it matches the whole page, from the start of the first <script> tag.
4390 That's more than we want, but the pattern continues: <literal>document\.referrer</literal>
4391 matches only the exact string <quote>document.referrer</quote>. The dot needed to
4392 be <emphasis>escaped</emphasis>, i.e. preceded by a backslash, to take away its
4393 special meaning as a joker, and make it just a regular dot. So far, the meaning is:
4394 Match from the start of the first <script> tag in a the page, up to, and including,
4395 the text <quote>document.referrer</quote>, if <emphasis>both</emphasis> are present
4396 in the page (and appear in that order).
4400 But there's still more pattern to go. The next element, again enclosed in parentheses,
4401 is <literal>.*</script></literal>. You already know what <literal>.*</literal>
4402 means, so the whole pattern translates to: Match from the start of the first <script>
4403 tag in a page to the end of the last <script> tag, provided that the text
4404 <quote>document.referrer</quote> appears somewhere in between.
4408 This is still not the whole story, since we have ignored the options and the parentheses:
4409 The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
4410 remembered and be available through the variables <literal>$1, $2, ...</literal> in
4411 the substitute. The <literal>U</literal> option switches to ungreedy matching, which means
4412 that the first <literal>.*</literal> in the pattern will only <quote>eat up</quote> all
4413 text in between <quote><script</quote> and the <emphasis>first</emphasis> occurrence
4414 of <quote>document.referrer</quote>, and that the second <literal>.*</literal> will
4415 only span the text up to the <emphasis>first</emphasis> <quote></script></quote>
4416 tag. Furthermore, the <literal>s</literal> option says that the match may span
4417 multiple lines in the page, and the <literal>g</literal> option again means that the
4418 substitution is global.
4422 So, to summarize, the pattern means: Match all scripts that contain the text
4423 <quote>document.referrer</quote>. Remember the parts of the script from
4424 (and including) the start tag up to (and excluding) the string
4425 <quote>document.referrer</quote> as <literal>$1</literal>, and the part following
4426 that string, up to and including the closing tag, as <literal>$2</literal>.
4430 Now the pattern is deciphered, but wasn't this about substituting things? So
4431 lets look at the substitute: <literal>$1"Not Your Business!"$2</literal> is
4432 easy to read: The text remembered as <literal>$1</literal>, followed by
4433 <literal>"Not Your Business!"</literal> (<emphasis>including</emphasis>
4434 the quotation marks!), followed by the text remembered as <literal>$2</literal>.
4435 This produces an exact copy of the original string, with the middle part
4436 (the <quote>document.referrer</quote>) replaced by <literal>"Not Your
4437 Business!"</literal>.
4441 The whole job now reads: Replace <quote>document.referrer</quote> by
4442 <literal>"Not Your Business!"</literal> wherever it appears inside a
4443 <script> tag. Note that this job won't break JavaScript syntax,
4444 since both the original and the replacement are syntactically valid
4445 string objects. The script just won't have access to the referrer
4446 information anymore.
4450 We'll show you two other jobs from the JavaScript taming department, but
4451 this time only point out the constructs of special interest:
4456 # The status bar is for displaying link targets, not pointless blahblah
4458 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
4462 <literal>\s</literal> stands for whitespace characters (space, tab, newline,
4463 carriage return, form feed), so that <literal>\s*</literal> means: <quote>zero
4464 or more whitespace</quote>. The <literal>?</literal> in <literal>.*?</literal>
4465 makes this matching of arbitrary text ungreedy. (Note that the <literal>U</literal>
4466 option is not set). The <literal>['"]</literal> construct means: <quote>a single
4467 <emphasis>or</emphasis> a double quote</quote>. Finally, <literal>\1</literal> is
4468 a backreference to the first parenthesis just like <literal>$1</literal> above,
4469 with the difference that in the <emphasis>pattern</emphasis>, a backslash indicates
4470 a backreference, whereas in the <emphasis>substitute</emphasis>, it's the dollar.
4474 So what does this job do? It replaces assignments of single- or double-quoted
4475 strings to the <quote>window.status</quote> object with a dummy assignment
4476 (using a variable name that is hopefully odd enough not to conflict with
4477 real variables in scripts). Thus, it catches many cases where e.g. pointless
4478 descriptions are displayed in the status bar instead of the link target when
4479 you move your mouse over links.
4484 # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
4486 s/(<body [^>]*)onunload(.*>)/$1never$2/iU</screen>
4491 <ulink url="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents">OnUnload
4492 event binding</ulink> in the HTML DOM was a <emphasis>CRIME</emphasis>.
4493 When I close a browser window, I want it to close and die. Basta.
4494 This job replaces the <quote>onunload</quote> attribute in
4495 <quote><body></quote> tags with the dummy word <literal>never</literal>.
4496 Note that the <literal>i</literal> option makes the pattern matching
4497 case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
4498 a minimal match: In the first parenthesis, we had to use <literal>[^>]*</literal>
4499 instead of <literal>.*</literal> to prevent the match from exceeding the
4500 <body> tag if it doesn't contain <quote>OnUnload</quote>, but the page's
4505 The last example is from the fun department:
4510 FILTER: fun Fun text replacements
4512 # Spice the daily news:
4514 s/microsoft(?!\.com)/MicroSuck/ig</screen>
4518 Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
4519 in the job's pattern, which means: Don't match, if the string
4520 <quote>.com</quote> appears directly following <quote>microsoft</quote>
4521 in the page. This prevents links to microsoft.com from being trashed, while
4522 still replacing the word everywhere else.
4527 # Buzzword Bingo (example for extended regex syntax)
4529 s* industry[ -]leading \
4531 | customer[ -]focused \
4532 | market[ -]driven \
4533 | award[ -]winning # Comments are OK, too! \
4534 | high[ -]performance \
4535 | solutions[ -]based \
4539 *<font color="red"><b>BINGO!</b></font> \
4544 The <literal>x</literal> option in this job turns on extended syntax, and allows for
4545 e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting.
4554 <!-- ~ End section ~ -->
4558 <!-- ~~~~~ New section ~~~~~ -->
4560 <sect1 id="templates">
4561 <title>Templates</title>
4563 All <application>Privoxy</application> built-in pages, i.e. error pages such as the
4564 <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
4565 error page</ulink>, the <ulink
4566 url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
4568 and all pages of its <ulink url="http://config.privoxy.org/">web-based
4569 user interface</ulink>, are generated from <emphasis>templates</emphasis>.
4570 (<application>Privoxy</application> must be running for the above links to work as
4575 These templates are stored in a subdirectory of the <link linkend="confdir">configuration
4576 directory</link> called <filename>templates</filename>. On Unixish platforms,
4578 <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
4582 The templates are basically normal HTML files, but with place-holders (called symbols
4583 or exports), which <application>Privoxy</application> fills at run time. You can
4584 edit the templates with a normal text editor, should you want to customize them.
4585 (<emphasis>Not recommended for the casual user</emphasis>). Note that
4586 just like in configuration files, lines starting with <literal>#</literal> are
4587 ignored when the templates are filled in.
4591 The place-holders are of the form <literal>@name@</literal>, and you will
4592 find a list of available symbols, which vary from template to template,
4593 in the comments at the start of each file. Note that these comments are not
4594 always accurate, and that it's probably best to look at the existing HTML
4595 code to find out which symbols are supported and what they are filled in with.
4599 A special application of this substitution mechanism is to make whole
4600 blocks of HTML code disappear when a specific symbol is set. We use this
4601 for many purposes, one of them being to include the beta warning in all
4602 our user interface (CGI) pages when <application>Privoxy</application>
4603 in in an alpha or beta development stage:
4608 <!-- @if-unstable-start -->
4610 ... beta warning HTML code goes here ...
4612 <!-- if-unstable-end@ --></screen>
4616 If the "unstable" symbol is set, everything in between and including
4617 <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
4618 will disappear, leaving nothing but an empty comment:
4622 <screen><!-- --></screen>
4626 There's also an if-then-else construct and an <literal>#include</literal>
4627 mechanism, but you'll sure find out if you are inclined to edit the
4632 All templates refer to a style located at
4633 <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
4634 This is, of course, locally served by <application>Privoxy</application>
4635 and the source for it can be found and edited in the
4636 <filename>cgi-style.css</filename> template.
4641 <!-- ~ End section ~ -->
4645 <!-- ~~~~~ New section ~~~~~ -->
4647 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
4650 <!-- Include contacting.sgml boilerplate: -->
4652 <!-- end boilerplate -->
4656 <!-- ~ End section ~ -->
4659 <!-- ~~~~~ New section ~~~~~ -->
4660 <sect1 id="copyright"><title><application>Privoxy</application> Copyright, License and History</title>
4662 <!-- Include copyright.sgml: -->
4664 <!-- end copyright -->
4666 <!-- ~~~~~ New section ~~~~~ -->
4667 <sect2><title>License</title>
4668 <!-- Include copyright.sgml: -->
4670 <!-- end copyright -->
4672 <!-- ~ End section ~ -->
4675 <!-- ~~~~~ New section ~~~~~ -->
4677 <sect2 id="history"><title>History</title>
4678 <!-- Include history.sgml: -->
4680 <!-- end history -->
4683 <sect2 id="authors"><title>Authors</title>
4684 <!-- Include p-authors.sgml: -->
4686 <!-- end authors -->
4691 <!-- ~ End section ~ -->
4694 <!-- ~~~~~ New section ~~~~~ -->
4695 <sect1 id="seealso"><title>See Also</title>
4696 <!-- Include seealso.sgml: -->
4698 <!-- end seealso -->
4703 <!-- ~~~~~ New section ~~~~~ -->
4704 <sect1 id="appendix"><title>Appendix</title>
4707 <!-- ~~~~~ New section ~~~~~ -->
4709 <title>Regular Expressions</title>
4711 <application>Privoxy</application> uses Perl-style <quote>regular
4712 expressions</quote> in its <link linkend="actions-file">actions
4713 files</link> and <link linkend="filter-file">filter file</link>,
4714 through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
4715 <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
4719 If you are reading this, you probably don't understand what <quote>regular
4720 expressions</quote> are, or what they can do. So this will be a very brief
4721 introduction only. A full explanation would require a <ulink
4722 url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
4726 Regular expressions provide a language to describe patterns that can be
4727 run against strings of characters (letter, numbers, etc), to see if they
4728 match the string or not. The patterns are themselves (sometimes complex)
4729 strings of literal characters, combined with wild-cards, and other special
4730 characters, called meta-characters. The <quote>meta-characters</quote> have
4731 special meanings and are used to build complex patterns to be matched against.
4732 Perl Compatible Regular Expressions are an especially convenient
4733 <quote>dialect</quote> of the regular expression language.
4737 To make a simple analogy, we do something similar when we use wild-card
4738 characters when listing files with the <command>dir</command> command in DOS.
4739 <literal>*.*</literal> matches all filenames. The <quote>special</quote>
4740 character here is the asterisk which matches any and all characters. We can be
4741 more specific and use <literal>?</literal> to match just individual
4742 characters. So <quote>dir file?.text</quote> would match
4743 <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
4744 matching, using a similar technique to <quote>regular expressions</quote>!
4748 Regular expressions do essentially the same thing, but are much, much more
4749 powerful. There are many more <quote>special characters</quote> and ways of
4750 building complex patterns however. Let's look at a few of the common ones,
4751 and then some examples:
4756 <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
4757 <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
4759 </simplelist></para>
4763 <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
4766 </simplelist></para>
4770 <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
4773 </simplelist></para>
4777 <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
4780 </simplelist></para>
4784 <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
4785 the following character should be taken literally. This is used where one of the
4786 special characters (e.g. <quote>.</quote>) needs to be taken literally and
4787 not as a special meta-character. Example: <quote>example\.com</quote>, makes
4788 sure the period is recognized only as a period (and not expanded to its
4789 meta-character meaning of any single character).
4791 </simplelist></para>
4795 <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
4796 any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
4797 matches any numeric digit (zero through nine). As an example, we can combine
4798 this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
4800 </simplelist></para>
4804 <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
4805 or multiple sub-expressions.
4807 </simplelist></para>
4811 <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
4812 <quote>or</quote> conditional statement. A match is successful if the
4813 sub-expression on either side of <quote>|</quote> matches. As an example:
4814 <quote>/(this|that) example/</quote> uses grouping and the bar character
4815 and would match either <quote>this example</quote> or <quote>that
4816 example</quote>, and nothing else.
4818 </simplelist></para>
4821 These are just some of the ones you are likely to use when matching URLs with
4822 <application>Privoxy</application>, and is a long way from a definitive
4823 list. This is enough to get us started with a few simple examples which may
4824 be more illuminating:
4828 <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
4829 that uses the common combination of <quote>.</quote> and <quote>*</quote> to
4830 denote any character, zero or more times. In other words, any string at all.
4831 So we start with a literal forward slash, then our regular expression pattern
4832 (<quote>.*</quote>) another literal forward slash, the string
4833 <quote>banners</quote>, another forward slash, and lastly another
4834 <quote>.*</quote>. We are building
4835 a directory path here. This will match any file with the path that has a
4836 directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
4837 any characters, and this could conceivably be more forward slashes, so it
4838 might expand into a much longer looking path. For example, this could match:
4839 <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
4840 <quote>/banners/annoying.html</quote>, or almost an infinite number of other
4841 possible combinations, just so it has <quote>banners</quote> in the path
4846 A now something a little more complex:
4850 <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
4851 We have several literal forward slashes again (<quote>/</quote>), so we are
4852 building another expression that is a file path statement. We have another
4853 <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
4854 it matches our expression. The only true literal that <emphasis>must
4855 match</emphasis> our pattern is <application>adv</application>, together with
4856 the forward slashes. What comes after the <quote>adv</quote> string is the
4861 Remember the <quote>?</quote> means the preceding expression (either a
4862 literal character or anything grouped with <quote>(...)</quote> in this case)
4863 can exist or not, since this means either zero or one match. So
4864 <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
4865 individual sub-expressions: <quote>(er)</quote>,
4866 <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
4867 means <quote>or</quote>. We have two of those. For instance,
4868 <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
4869 <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
4870 attempt at matching as many variations of <quote>advertisement</quote>, and
4871 similar, as possible. So this would expand to match just <quote>adv</quote>,
4872 or <quote>advert</quote>, or <quote>adverts</quote>, or
4873 <quote>advertising</quote>, or <quote>advertisement</quote>, or
4874 <quote>advertisements</quote>. You get the idea. But it would not match
4875 <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
4876 changing our regular expression to:
4877 <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
4882 <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
4883 another path statement with forward slashes. Anything in the square brackets
4884 <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
4885 shorthand expression to mean any digit one through nine. It is the same as
4886 saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
4887 means one or more of the preceding expression must be included. The preceding
4888 expression here is what is in the square brackets -- in this case, any digit
4889 one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
4890 This includes a <quote>|</quote>, so this needs to match the expression on
4891 either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
4892 side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
4893 since the <quote>?</quote> means the letter <quote>e</quote> is optional and
4894 can be matched once or not at all. So we are building an expression here to
4895 match image GIF or JPEG type image file. It must include the literal
4896 string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
4897 (which is now a literal, and not a special character, since it is escaped
4898 with <quote>\</quote>), and lastly either <quote>gif</quote>, or
4899 <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
4900 include: <quote>//advert1.jpg</quote>,
4901 <quote>/nasty/ads/advert1234.gif</quote>,
4902 <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
4903 <quote>advert1.gif</quote> (no leading slash), or
4904 <quote>/adverts232.jpg</quote> (the expression does not include an
4905 <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
4906 in the expression anywhere).
4910 We are barely scratching the surface of regular expressions here so that you
4911 can understand the default <application>Privoxy</application>
4912 configuration files, and maybe use this knowledge to customize your own
4913 installation. There is much, much more that can be done with regular
4914 expressions. Now that you know enough to get started, you can learn more on
4919 More reading on Perl Compatible Regular expressions:
4920 <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
4924 For information on regular expression based substitutions and their applications
4925 in filters, please see the <link linkend="filter-file">filter file tutorial</link>
4930 <!-- ~ End section ~ -->
4933 <!-- ~~~~~ New section ~~~~~ -->
4935 <title><application>Privoxy</application>'s Internal Pages</title>
4938 Since <application>Privoxy</application> proxies each requested
4939 web page, it is easy for <application>Privoxy</application> to
4940 trap certain special URLs. In this way, we can talk directly to
4941 <application>Privoxy</application>, and see how it is
4942 configured, see how our rules are being applied, change these
4943 rules and other configuration options, and even turn
4944 <application>Privoxy's</application> filtering off, all with
4950 The URLs listed below are the special ones that allow direct access
4951 to <application>Privoxy</application>. Of course,
4952 <application>Privoxy</application> must be running to access these. If
4953 not, you will get a friendly error message. Internet access is not
4966 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4970 There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
4971 doesn't provide a fall-back to a real page, in case the request is not
4972 sent through <application>Privoxy</application>)
4978 Show information about the current configuration, including viewing and
4979 editing of actions files:
4983 <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
4990 Show the source code version numbers:
4994 <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
5001 Show the browser's request headers:
5005 <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
5012 Show which actions apply to a URL and why:
5016 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
5023 Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
5024 to run, but only as a pass-through proxy, with no actions taking place:
5028 <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
5032 Short cuts. Turn off, then on:
5036 <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
5041 <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
5050 These may be bookmarked for quick reference. See next.
5054 <sect3 id="bookmarklets">
5055 <title>Bookmarklets</title>
5057 Below are some <quote>bookmarklets</quote> to allow you to easily access a
5058 <quote>mini</quote> version of some of <application>Privoxy's</application>
5059 special pages. They are designed for MS Internet Explorer, but should work
5060 equally well in Netscape, Mozilla, and other browsers which support
5061 JavaScript. They are designed to run directly from your bookmarks - not by
5062 clicking the links below (although that should work for testing).
5065 To save them, right-click the link and choose <quote>Add to Favorites</quote>
5066 (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
5067 the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
5068 Bookmarklet directly from your favorites/bookmarks. For even faster access,
5069 you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
5070 Toolbar</quote> (Netscape), and run them with a single click.
5079 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
5086 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
5093 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
5100 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
5106 <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
5111 <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
5118 Credit: The site which gave us the general idea for these bookmarklets is
5119 <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
5120 have more information about bookmarklets.
5129 <!-- ~~~~~ New section ~~~~~ -->
5131 <title>Chain of Events</title>
5133 Let's take a quick look at the basic sequence of events when a web page is
5134 requested by your browser and <application>Privoxy</application> is on duty:
5141 First, your web browser requests a web page. The browser knows to send
5142 the request to <application>Privoxy</application>, which will in turn,
5143 relay the request to the remote web server after passing the following
5149 <application>Privoxy</application> traps any request for its own internal CGI
5150 pages (e.g http://p.p/) and sends the CGI page back to the browser.
5155 Next, <application>Privoxy</application> checks to see if the URL
5157 linkend="BLOCK"><quote>+block</quote></link> patterns. If
5158 so, the URL is then blocked, and the remote web server will not be contacted.
5159 <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
5160 is then checked and if it does not match, an
5161 HTML <quote>BLOCKED</quote> page is sent back. Otherwise, if it does match,
5162 an image is returned. The type of image depends on the setting of <link
5163 linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
5164 (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
5169 Untrusted URLs are blocked. If URLs are being added to the
5170 <filename>trust</filename> file, then that is done.
5175 If the URL pattern matches the <link
5176 linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
5177 it is then processed. Unwanted parts of the requested URL are stripped.
5182 Now the rest of the client browser's request headers are processed. If any
5183 of these match any of the relevant actions (e.g. <link
5184 linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
5185 etc.), headers are suppressed or forged as determined by these actions and
5191 Now the web server starts sending its response back (i.e. typically a web page and related
5197 First, the server headers are read and processed to determine, among other
5198 things, the MIME type (document type) and encoding. The headers are then
5199 filtered as deterimined by the
5200 <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
5201 <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
5202 and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
5208 If the <link linkend="KILL-POPUPS"><quote>+kill-popups</quote></link>
5209 action applies, and it is an HTML or JavaScript document, the popup-code in the
5210 response is filtered on-the-fly as it is received.
5215 If a <link linkend="FILTER"><quote>+filter</quote></link>
5217 linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
5218 action applies (and the document type fits the action), the rest of the page is
5219 read into memory (up to a configurable limit). Then the filter rules (from
5220 <filename>default.filter</filename>) are processed against the buffered
5221 content. Filters are applied in the order they are specified in the
5222 <filename>default.filter</filename> file. Animated GIFs, if present, are
5223 reduced to either the first or last frame, depending on the action
5224 setting.The entire page, which is now filtered, is then sent by
5225 <application>Privoxy</application> back to your browser.
5228 If neither <link linkend="FILTER"><quote>+filter</quote></link>
5230 linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
5231 matches, then <application>Privoxy</application> passes the raw data through
5232 to the client browser as it becomes available.
5237 As the browser receives the now (probably filtered) page content, it
5238 reads and then requests any URLs that may be embedded within the page
5239 source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
5240 frames), sounds, etc. For each of these objects, the browser issues a new
5241 request. And each such request is in turn processed as above. Note that a
5242 complex web page may have many such embedded URLs.
5252 <!-- ~~~~~ New section ~~~~~ -->
5253 <sect2 id="actionsanat">
5254 <title>Anatomy of an Action</title>
5257 The way <application>Privoxy</application> applies
5258 <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
5259 to any given URL can be complex, and not always so
5260 easy to understand what is happening. And sometimes we need to be able to
5261 <emphasis>see</emphasis> just what <application>Privoxy</application> is
5262 doing. Especially, if something <application>Privoxy</application> is doing
5263 is causing us a problem inadvertently. It can be a little daunting to look at
5264 the actions and filters files themselves, since they tend to be filled with
5265 <link linkend="regex">regular expressions</link> whose consequences are not
5270 One quick test to see if <application>Privoxy</application> is causing a problem
5271 or not, is to disable it temporarily. This should be the first troubleshooting
5272 step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
5273 and easy way to do this (be sure to flush caches afterward!). Looking at the
5274 logs is a good idea too.
5278 <application>Privoxy</application> also provides the
5279 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
5280 page that can show us very specifically how <application>actions</application>
5281 are being applied to any given URL. This is a big help for troubleshooting.
5285 First, enter one URL (or partial URL) at the prompt, and then
5286 <application>Privoxy</application> will tell us
5287 how the current configuration will handle it. This will not
5288 help with filtering effects (i.e. the <link
5289 linkend="FILTER"><quote>+filter</quote></link> action) from
5290 the <filename>default.filter</filename> file since this is handled very
5291 differently and not so easy to trap! It also will not tell you about any other
5292 URLs that may be embedded within the URL you are testing. For instance, images
5293 such as ads are expressed as URLs within the raw page source of HTML pages. So
5294 you will only get info for the actual URL that is pasted into the prompt area
5295 -- not any sub-URLs. If you want to know about embedded URLs like ads, you
5296 will have to dig those out of the HTML source. Use your browser's <quote>View
5297 Page Source</quote> option for this. Or right click on the ad, and grab the
5302 Let's try an example, <ulink url="http://google.com">google.com</ulink>,
5303 and look at it one section at a time:
5308 Matches for http://google.com:
5310 In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
5314 -crunch-outgoing-cookies
5315 -crunch-incoming-cookies
5316 +deanimate-gifs{last}
5317 -downgrade-http-version
5321 -filter{shockwave-flash}
5322 -filter{crude-parental}
5323 +filter{html-annoyances}
5324 +filter{js-annoyances}
5325 +filter{content-cookies}
5327 +filter{refresh-tags}
5329 +filter{banners-by-size}
5330 +hide-forwarded-for-headers
5331 +hide-from-header{block}
5332 +hide-referer{forge}
5337 +prevent-compression
5340 +session-cookies-only
5341 +set-image-blocker{pattern} }
5344 { -session-cookies-only }
5350 In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
5351 (no matches in this file)
5356 This tells us how we have defined our
5357 <link linkend="ACTIONS"><quote>actions</quote></link>, and
5358 which ones match for our example, <quote>google.com</quote>. The first listing
5359 is any matches for the <filename>standard.action</filename> file. No hits at
5360 all here on <quote>standard</quote>. Then next is <quote>default</quote>, or
5361 our <filename>default.action</filename> file. The large, multi-line listing,
5362 is how the actions are set to match for all URLs, i.e. our default settings.
5363 If you look at your <quote>actions</quote> file, this would be the section
5364 just below the <quote>aliases</quote> section near the top. This will apply to
5365 all URLs as signified by the single forward slash at the end of the listing
5366 -- <quote>/</quote>.
5370 But we can define additional actions that would be exceptions to these general
5371 rules, and then list specific URLs (or patterns) that these exceptions would
5372 apply to. Last match wins. Just below this then are two explicit matches for
5373 <quote>.google.com</quote>. The first is negating our previous cookie setting,
5375 linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
5376 (i.e. not persistent). So we will allow persistent cookies for google. The
5377 second turns <emphasis>off</emphasis> any
5379 linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
5380 action, allowing this to take place unmolested. Note that there is a leading
5381 dot here -- <quote>.google.com</quote>. This will match any hosts and
5382 sub-domains, in the google.com domain also, such as
5383 <quote>www.google.com</quote>. So, apparently, we have these two actions
5384 defined somewhere in the lower part of our <filename>default.action</filename>
5385 file, and <quote>google.com</quote> is referenced somewhere in these latter
5390 Then, for our <filename>user.action</filename> file, we again have no hits.
5394 And finally we pull it all together in the bottom section and summarize how
5395 <application>Privoxy</application> is applying all its <quote>actions</quote>
5396 to <quote>google.com</quote>:
5407 -crunch-outgoing-cookies
5408 -crunch-incoming-cookies
5409 +deanimate-gifs{last}
5410 -downgrade-http-version
5414 -filter{shockwave-flash}
5415 -filter{crude-parental}
5416 +filter{html-annoyances}
5417 +filter{js-annoyances}
5418 +filter{content-cookies}
5420 +filter{refresh-tags}
5422 +filter{banners-by-size}
5423 +hide-forwarded-for-headers
5424 +hide-from-header{block}
5425 +hide-referer{forge}
5430 +prevent-compression
5433 -session-cookies-only
5434 +set-image-blocker{pattern}
5439 Notice the only difference here to the previous listing, is to
5440 <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>.
5444 Now another example, <quote>ad.doubleclick.net</quote>:
5450 { +block +handle-as-image }
5453 { +block +handle-as-image }
5456 { +block +handle-as-image }
5462 We'll just show the interesting part here, the explicit matches. It is
5463 matched three different times. Each as an <quote>+block +handle-as-image</quote>,
5464 which is the expanded form of one of our aliases that had been defined as:
5465 <quote>+imageblock</quote>. (<link
5466 linkend="ALIASES"><quote>Aliases</quote></link> are defined in
5467 the first section of the actions file and typically used to combine more
5472 Any one of these would have done the trick and blocked this as an unwanted
5473 image. This is unnecessarily redundant since the last case effectively
5474 would also cover the first. No point in taking chances with these guys
5475 though ;-) Note that if you want an ad or obnoxious
5476 URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
5477 is done here -- as both a <link
5478 linkend="BLOCK"><quote>+block</quote></link>
5479 <emphasis>and</emphasis> an
5481 linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
5482 The custom alias <quote>+imageblock</quote> just simplifies the process and make
5487 One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
5488 This one is giving us problems. We are getting a blank page. Hmmm ...
5494 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
5496 In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
5500 -crunch-incoming-cookies
5501 -crunch-outgoing-cookies
5503 -downgrade-http-version
5505 +filter{html-annoyances}
5506 +filter{js-annoyances}
5507 +filter{kill-popups}
5510 +filter{banners-by-size}
5513 +hide-forwarded-for-headers
5514 +hide-from-header{block}
5515 +hide-referer{forge}
5519 +prevent-compression
5522 +session-cookies-only
5523 +set-image-blocker{blank} }
5526 { +block +handle-as-image }
5532 Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
5533 we did not want this at all! Now we see why we get the blank page. We could
5534 now add a new action below this that explicitly does <emphasis>not</emphasis>
5535 block (<quote>{-block}</quote>) paths with <quote>adsl</quote>. There are
5536 various ways to handle such exceptions. Example:
5548 Now the page displays ;-) Be sure to flush your browser's caches when
5549 making such changes. Or, try using <literal>Shift+Reload</literal>.
5553 But now what about a situation where we get no explicit matches like
5560 { +block +handle-as-image }
5566 That actually was very telling and pointed us quickly to where the problem
5567 was. If you don't get this kind of match, then it means one of the default
5568 rules in the first section is causing the problem. This would require some
5569 guesswork, and maybe a little trial and error to isolate the offending rule.
5570 One likely cause would be one of the <quote>{+filter}</quote> actions. These
5571 tend to be harder to troubleshoot. Try adding the URL for the site to one of
5572 aliases that turn off <quote>+filter</quote>:
5580 .worldpay.com # for quietpc.com
5588 <quote>{shop}</quote> is an <quote>alias</quote> that expands to
5589 <quote>{ -filter -session-cookies-only }</quote>.
5590 Or you could do your own exception to negate filtering:
5603 This would turn off all filtering for that site. This would probably be most
5604 appropriately put in <filename>user.action</filename>, for local site
5609 Images that are inexplicably being blocked, may well be hitting the
5610 <quote>+filter{banners-by-size}</quote> rule, which assumes
5611 that images of certain sizes are ad banners (works well most of the time
5612 since these tend to be standardized).
5616 <quote>{fragile}</quote> is an alias that disables most actions. This can be
5617 used as a last resort for problem sites. Remember to flush caches! If this
5618 still does not work, you will have to go through the remaining actions one by
5619 one to find which one(s) is causing the problem.
5628 This program is free software; you can redistribute it
5629 and/or modify it under the terms of the GNU General
5630 Public License as published by the Free Software
5631 Foundation; either version 2 of the License, or (at
5632 your option) any later version.
5634 This program is distributed in the hope that it will
5635 be useful, but WITHOUT ANY WARRANTY; without even the
5636 implied warranty of MERCHANTABILITY or FITNESS FOR A
5637 PARTICULAR PURPOSE. See the GNU General Public
5638 License for more details.
5640 The GNU General Public License should be included with
5641 this file. If not, you can view it at
5642 http://www.gnu.org/copyleft/gpl.html
5643 or write to the Free Software Foundation, Inc., 59
5644 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
5646 $Log: user-manual.sgml,v $
5647 Revision 1.123.2.13 2002/08/02 18:23:19 g_sauthoff
5648 Just 2 small corrections to the Gentoo sections
5650 Revision 1.123.2.12 2002/08/02 18:17:21 g_sauthoff
5651 Added 2 Gentoo sections
5653 Revision 1.123.2.11 2002/07/26 15:20:31 oes
5654 - Added version info to title
5655 - Added info on new filters
5656 - Revised parts of the filter file tutorial
5657 - Added info on where to get updated actions files
5659 Revision 1.123.2.10 2002/07/25 21:42:29 hal9
5660 Add brief notes on not proxying non-HTTP protocols.
5662 Revision 1.123.2.9 2002/07/11 03:40:28 david__schmidt
5664 Updated Mac OSX sections due to installation location change
5666 Revision 1.123.2.8 2002/06/09 16:36:32 hal9
5667 Clarifications on filtering and MIME. Hardcode 'latest release' in index.html.
5669 Revision 1.123.2.7 2002/06/09 00:29:34 hal9
5670 Touch ups on filtering, in actions section and Anatomy.
5672 Revision 1.123.2.6 2002/06/06 23:11:03 hal9
5673 Fix broken link. Linkchecked all docs.
5675 Revision 1.123.2.5 2002/05/29 02:01:02 hal9
5676 This is break out of the entire config section from u-m, so it can
5677 eventually be used to generate the comments, etc in the main config file
5678 so that these are in sync with each other.
5680 Revision 1.123.2.4 2002/05/27 03:28:45 hal9
5681 Ooops missed something from David.
5683 Revision 1.123.2.3 2002/05/27 03:23:17 hal9
5684 Fix FIXMEs for OS2 and OSX startup. Fix Redhat typos (should be Red Hat).
5685 That's a wrap, I think.
5687 Revision 1.123.2.2 2002/05/26 19:02:09 hal9
5688 Move Amiga stuff around to take of FIXME in start up section.
5690 Revision 1.123.2.1 2002/05/26 17:04:25 hal9
5691 -Spellcheck, very minor edits, and sync across branches
5693 Revision 1.123 2002/05/24 23:19:23 hal9
5694 Include new image (Proxy setup). More fun with guibutton.
5695 Minor corrections/clarifications here and there.
5697 Revision 1.122 2002/05/24 13:24:08 oes
5698 Added Bookmarklet for one-click pre-filled access to show-url-info
5700 Revision 1.121 2002/05/23 23:20:17 oes
5701 - Changed more (all?) references to actions to the
5702 <literal><link> style.
5703 - Small fixes in the actions chapter
5704 - Small clarifications in the quickstart to ad blocking
5705 - Removed <emphasis> from <title>s since the new doc CSS
5706 renders them red (bad in TOC).
5708 Revision 1.120 2002/05/23 19:16:43 roro
5709 Correct Debian specials (installation and startup).
5711 Revision 1.119 2002/05/22 17:17:05 oes
5714 Revision 1.118 2002/05/21 04:54:55 hal9
5715 -New Section: Quickstart to Ad Blocking
5716 -Reformat Actions Anatomy to match new CGI layout
5718 Revision 1.117 2002/05/17 13:56:16 oes
5719 - Reworked & extended Templates chapter
5720 - Small changes to Regex appendix
5721 - #included authors.sgml into (C) and hist chapter
5723 Revision 1.116 2002/05/17 03:23:46 hal9
5724 Fixing merge conflict in Quickstart section.
5726 Revision 1.115 2002/05/16 16:25:00 oes
5727 Extended the Filter File chapter & minor fixes
5729 Revision 1.114 2002/05/16 09:42:50 oes
5730 More ulink->link, added some hints to Quickstart section
5732 Revision 1.113 2002/05/15 21:07:25 oes
5733 Extended and further commented the example actions files
5735 Revision 1.112 2002/05/15 03:57:14 hal9
5736 Spell check. A few minor edits here and there for better syntax and
5739 Revision 1.111 2002/05/14 23:01:36 oes
5742 Revision 1.110 2002/05/14 19:10:45 oes
5743 Restored alphabetical order of actions
5745 Revision 1.109 2002/05/14 17:23:11 oes
5746 Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
5748 Revision 1.108 2002/05/14 15:29:12 oes
5749 Completed proofreading the actions chapter
5751 Revision 1.107 2002/05/12 03:20:41 hal9
5752 Small clarifications for 127.0.0.1 vs localhost for listen-address since this
5753 apparently an important distinction for some OS's.
5755 Revision 1.106 2002/05/10 01:48:20 hal9
5756 This is mostly proposed copyright/licensing additions and changes. Docs
5757 are still GPL, but licensing and copyright are more visible. Also, copyright
5758 changed in doc header comments (eliminate references to JB except FAQ).
5760 Revision 1.105 2002/05/05 20:26:02 hal9
5761 Sorting out license vs copyright in these docs.
5763 Revision 1.104 2002/05/04 08:44:45 swa
5766 Revision 1.103 2002/05/04 00:40:53 hal9
5767 -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
5768 -Some minor additions to Quickstart.
5770 Revision 1.102 2002/05/03 17:46:00 oes
5771 Further proofread & reactivated short build instructions
5773 Revision 1.101 2002/05/03 03:58:30 hal9
5774 Move the user-manual config directive to top of section. Add note about
5775 Privoxy needing read permissions for configs, and write for logs.
5777 Revision 1.100 2002/04/29 03:05:55 hal9
5778 Add clarification on differences of new actions files.
5780 Revision 1.99 2002/04/28 16:59:05 swa
5781 more structure in starting section
5783 Revision 1.98 2002/04/28 05:43:59 hal9
5784 This is the break up of configuration.html into multiple files. This
5785 will probably break links elsewhere :(
5787 Revision 1.97 2002/04/27 21:04:42 hal9
5788 -Rewrite of Actions File example.
5789 -Add section for user-manual directive in config.
5791 Revision 1.96 2002/04/27 05:32:00 hal9
5792 -Add short section to Filter Files to tie in with +filter action.
5793 -Start rewrite of examples in Actions Examples (not finished).
5795 Revision 1.95 2002/04/26 17:23:29 swa
5796 bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
5798 Revision 1.94 2002/04/26 05:24:36 hal9
5799 -Add most of Andreas suggestions to Chain of Events section.
5800 -A few other minor corrections and touch up.
5802 Revision 1.92 2002/04/25 18:55:13 hal9
5803 More catchups on new actions files, and new actions names.
5804 Other assorted cleanups, and minor modifications.
5806 Revision 1.91 2002/04/24 02:39:31 hal9
5807 Add 'Chain of Events' section.
5809 Revision 1.90 2002/04/23 21:41:25 hal9
5810 Linuxconf is deprecated on RH, substitute chkconfig.
5812 Revision 1.89 2002/04/23 21:05:28 oes
5813 Added hint for startup on Red Hat
5815 Revision 1.88 2002/04/23 05:37:54 hal9
5816 Add AmigaOS install stuff.
5818 Revision 1.87 2002/04/23 02:53:15 david__schmidt
5819 Updated OSX installation section
5820 Added a few English tweaks here an there
5822 Revision 1.86 2002/04/21 01:46:32 hal9
5823 Re-write actions section.
5825 Revision 1.85 2002/04/18 21:23:23 hal9
5826 Fix ugly typo (mine).
5828 Revision 1.84 2002/04/18 21:17:13 hal9
5829 Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
5831 Revision 1.83 2002/04/18 18:21:12 oes
5832 Added RPM install detail
5834 Revision 1.82 2002/04/18 12:04:50 oes
5837 Revision 1.81 2002/04/18 11:50:24 oes
5838 Extended Install section - needs fixing by packagers
5840 Revision 1.80 2002/04/18 10:45:19 oes
5841 Moved text to buildsource.sgml, renamed some filters, details
5843 Revision 1.79 2002/04/18 03:18:06 hal9
5844 Spellcheck, and minor touchups.
5846 Revision 1.78 2002/04/17 18:04:16 oes
5849 Revision 1.77 2002/04/17 13:51:23 oes
5850 Proofreading, part one
5852 Revision 1.76 2002/04/16 04:25:51 hal9
5853 -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
5854 -Note about proxy may need requests to re-read config files.
5856 Revision 1.75 2002/04/12 02:08:48 david__schmidt
5857 Remove OS/2 building info... it is already in the developer-manual
5859 Revision 1.74 2002/04/11 00:54:38 hal9
5860 Add small section on submitting actions.
5862 Revision 1.73 2002/04/10 18:45:15 swa
5865 Revision 1.72 2002/04/10 04:06:19 hal9
5866 Added actions feedback to Bookmarklets section
5868 Revision 1.71 2002/04/08 22:59:26 hal9
5869 Version update. Spell chkconfig correctly :)
5871 Revision 1.70 2002/04/08 20:53:56 swa
5874 Revision 1.69 2002/04/06 05:07:29 hal9
5875 -Add privoxy-man-page.sgml, for man page.
5876 -Add authors.sgml for AUTHORS (and p-authors.sgml)
5877 -Reworked various aspects of various docs.
5878 -Added additional comments to sub-docs.
5880 Revision 1.68 2002/04/04 18:46:47 swa
5881 consistent look. reuse of copyright, history et. al.
5883 Revision 1.67 2002/04/04 17:27:57 swa
5884 more single file to be included at multiple points. make maintaining easier
5886 Revision 1.66 2002/04/04 06:48:37 hal9
5887 Structural changes to allow for conditional inclusion/exclusion of content
5888 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
5889 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
5890 eventually be set by Makefile.
5891 More boilerplate text for use across multiple docs.
5893 Revision 1.65 2002/04/03 19:52:07 swa
5894 enhance squid section due to user suggestion
5896 Revision 1.64 2002/04/03 03:53:43 hal9
5897 A few minor bug fixes, and touch ups. Ready for review.
5899 Revision 1.63 2002/04/01 16:24:49 hal9
5900 Define entities to include boilerplate text. See doc/source/*.
5902 Revision 1.62 2002/03/30 04:15:53 hal9
5903 - Fix privoxy.org/config links.
5904 - Paste in Bookmarklets from Toggle page.
5905 - Move Quickstart nearer top, and minor rework.
5907 Revision 1.61 2002/03/29 01:31:08 hal9
5910 Revision 1.60 2002/03/27 01:57:34 hal9
5911 Added more to Anatomy section.
5913 Revision 1.59 2002/03/27 00:54:33 hal9
5914 Touch up intro for new name.
5916 Revision 1.58 2002/03/26 22:29:55 swa
5917 we have a new homepage!
5919 Revision 1.57 2002/03/24 20:33:30 hal9
5920 A few minor catch ups with name change.
5922 Revision 1.56 2002/03/24 16:17:06 swa
5923 configure needs to be generated.
5925 Revision 1.55 2002/03/24 16:08:08 swa
5926 we are too lazy to make a block-built
5927 privoxy logo. hence removed the option.
5929 Revision 1.54 2002/03/24 15:46:20 swa
5930 name change related issue.
5932 Revision 1.53 2002/03/24 11:51:00 swa
5933 name change. changed filenames.
5935 Revision 1.52 2002/03/24 11:01:06 swa
5938 Revision 1.51 2002/03/23 15:13:11 swa
5939 renamed every reference to the old name with foobar.
5940 fixed "application foobar application" tag, fixed
5941 "the foobar" with "foobar". left junkbustser in cvs
5942 comments and remarks to history untouched.
5944 Revision 1.50 2002/03/23 05:06:21 hal9
5947 Revision 1.49 2002/03/21 17:01:05 hal9
5948 New section in Appendix.
5950 Revision 1.48 2002/03/12 06:33:01 hal9
5951 Catching up to Andreas and re_filterfile changes.
5953 Revision 1.47 2002/03/11 13:13:27 swa
5954 correct feedback channels
5956 Revision 1.46 2002/03/10 00:51:08 hal9
5957 Added section on JB internal pages in Appendix.
5959 Revision 1.45 2002/03/09 17:43:53 swa
5962 Revision 1.44 2002/03/09 17:08:48 hal9
5963 New section on Jon's actions file editor, and move some stuff around.
5965 Revision 1.43 2002/03/08 00:47:32 hal9
5966 Added imageblock{pattern}.
5968 Revision 1.42 2002/03/07 18:16:55 swa
5971 Revision 1.41 2002/03/07 16:46:43 hal9
5972 Fix a few markup problems for jade.
5974 Revision 1.40 2002/03/07 16:28:39 swa
5975 provide correct feedback channels
5977 Revision 1.39 2002/03/06 16:19:28 hal9
5978 Note on perceived filtering slowdown per FR.
5980 Revision 1.38 2002/03/05 23:55:14 hal9
5981 Stupid I did it again. Double hyphen in comment breaks jade.
5983 Revision 1.37 2002/03/05 23:53:49 hal9
5984 jade barfs on '- -' embedded in comments. - -user option broke it.
5986 Revision 1.36 2002/03/05 22:53:28 hal9
5987 Add new - - user option.
5989 Revision 1.35 2002/03/05 00:17:27 hal9
5990 Added section on command line options.
5992 Revision 1.34 2002/03/04 19:32:07 oes
5993 Changed default port to 8118
5995 Revision 1.33 2002/03/03 19:46:13 hal9
5996 Emphasis on where/how to report bugs, etc
5998 Revision 1.32 2002/03/03 09:26:06 joergs
5999 AmigaOS changes, config is now loaded from PROGDIR: instead of
6000 AmiTCP:db/junkbuster/ if no configuration file is specified on the
6003 Revision 1.31 2002/03/02 22:45:52 david__schmidt
6006 Revision 1.30 2002/03/02 22:00:14 hal9
6007 Updated 'New Features' list. Ran through spell-checker.
6009 Revision 1.29 2002/03/02 20:34:07 david__schmidt
6010 Update OS/2 build section
6012 Revision 1.28 2002/02/24 14:34:24 jongfoster
6013 Formatting changes. Now changing the doctype to DocBook XML 4.1
6014 will work - no other changes are needed.
6016 Revision 1.27 2002/01/11 14:14:32 hal9
6017 Added a very short section on Templates
6019 Revision 1.26 2002/01/09 20:02:50 hal9
6020 Fix bug re: auto-detect config file changes.
6022 Revision 1.25 2002/01/09 18:20:30 hal9
6023 Touch ups for *.action files.
6025 Revision 1.24 2001/12/02 01:13:42 hal9
6028 Revision 1.23 2001/12/02 00:20:41 hal9
6029 Updates for recent changes.
6031 Revision 1.22 2001/11/05 23:57:51 hal9
6032 Minor update for startup now daemon mode.
6034 Revision 1.21 2001/10/31 21:11:03 hal9
6035 Correct 2 minor errors
6037 Revision 1.18 2001/10/24 18:45:26 hal9
6038 *** empty log message ***
6040 Revision 1.17 2001/10/24 17:10:55 hal9
6041 Catching up with Jon's recent work, and a few other things.
6043 Revision 1.16 2001/10/21 17:19:21 swa
6044 wrong url in documentation
6046 Revision 1.15 2001/10/14 23:46:24 hal9
6047 Various minor changes. Fleshed out SEE ALSO section.
6049 Revision 1.13 2001/10/10 17:28:33 hal9
6052 Revision 1.12 2001/09/28 02:57:04 hal9
6055 Revision 1.11 2001/09/28 02:25:20 hal9
6058 Revision 1.9 2001/09/27 23:50:29 hal9
6059 A few changes. A short section on regular expression in appendix.
6061 Revision 1.8 2001/09/25 00:34:59 hal9
6062 Some additions, and re-arranging.
6064 Revision 1.7 2001/09/24 14:31:36 hal9
6067 Revision 1.6 2001/09/24 14:10:32 hal9
6068 Including David's OS/2 installation instructions.
6070 Revision 1.2 2001/09/13 15:27:40 swa
6073 Revision 1.1 2001/09/12 15:36:41 swa
6074 source files for junkbuster documentation
6076 Revision 1.3 2001/09/10 17:43:59 swa
6077 first proposal of a structure.
6079 Revision 1.2 2001/06/13 14:28:31 swa
6080 docs should have an author.
6082 Revision 1.1 2001/06/13 14:20:37 swa
6083 first import of project's documentation for the webserver.