1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2 <!entity % dummy "INCLUDE">
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 p-version "2.9.14">
12 <!entity p-status "beta">
13 <!entity % p-not-stable "INCLUDE">
14 <!entity % p-stable "IGNORE">
15 <!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
16 <!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
17 <!entity % p-readme "IGNORE">
18 <!entity % p-config "IGNORE">
19 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
22 File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
25 This file belongs into
26 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
28 $Id: user-manual.sgml,v 1.88 2002/04/23 05:37:54 hal9 Exp $
30 Written by and Copyright (C) 2001 the SourceForge
31 Privoxy team. http://www.privoxy.org/
33 Based on the Internet Junkbuster originally written
34 by and Copyright (C) 1997 Anonymous Coders and
35 Junkbusters Corporation. http://www.junkbusters.com
38 ========================================================================
39 NOTE: Please read developer-manual/documentation.html before touching
40 anything in this, or other Privoxy documentation.
41 ========================================================================
47 <title>Privoxy User Manual</title>
49 <pubdate>$Id: user-manual.sgml,v 1.88 2002/04/23 05:37:54 hal9 Exp $</pubdate>
54 <orgname>By: Privoxy Developers</orgname>
63 This is here to keep vim syntax file from breaking :/
64 If I knew enough to fix it, I would.
65 PLEASE DO NOT REMOVE! HB: hal@foobox.net
71 The user manual gives users information on how to install, configure and use
73 url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
76 <!-- Include privoxy.sgml boilerplate: -->
78 <!-- end privoxy.sgml -->
81 You can find the latest version of the user manual at <ulink
82 url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
83 Please see the <ulink url="contact.html">Contact section</ulink> on how to
84 contact the developers.
88 <!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
94 <!-- ~~~~~ New section ~~~~~ -->
95 <sect1 id="intro" label=""><title></title>
96 <!-- dummy section to force TOC on page by itself -->
97 <!-- DO NOT REMOVE! please ;) -->
101 <!-- ~~~~~ New section ~~~~~ -->
103 <sect1 label="1" id="introduction"><title>Introduction</title>
105 This documentation is included with the current &p-status; version of
106 <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
107 and is mostly complete at this point. The most up to date reference for the
108 time being is still the comments in the source files and in the individual
109 configuration files. Development of version 3.0 is currently nearing
110 completion, and includes many significant changes and enhancements over
111 earlier versions. The target release date for
112 stable v3.0 is <quote>soon</quote> ;-)]]>.
115 <!-- include only in non-stable versions -->
118 Since this is a &p-status; version, not all new features are well tested. This
119 documentation may be slightly out of sync as a result (especially with
120 CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
125 <!-- ~~~~~ New section ~~~~~ -->
126 <sect2 id="newfeatures">
127 <title>New Features</title>
129 In addition to <application>Internet Junkbuster's</application> traditional
130 features of ad and banner blocking and cookie management,
131 <application>Privoxy</application> provides new features<![%p-not-stable;[,
132 some of them currently under development]]>:
135 <!-- Include newfeatures.sgml boilerplate here: -->
137 <!-- end boilerplate -->
142 <!-- ~ End section ~ -->
145 <!-- ~~~~~ New section ~~~~~ -->
146 <sect1 id="installation"><title>Installation</title>
149 <application>Privoxy</application> is available both in convenient pre-compiled
150 packages for a wide range of operating systems, and as raw source code.
151 For most users, we recommend using the packages, which can be downloaded from our
152 <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
156 If you like to live on the bleeding edge and are not afraid of using
157 possibly unstable development versions, you can check out the up-to-the-minute
158 version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
159 CVS repository</ulink> or simply download <ulink
160 url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
164 <!-- Include supported.sgml boilerplate -->
166 <!-- end boilerplate -->
168 <!-- ~~~~~ New section ~~~~~ -->
169 <sect2 id="installation-packages"><title>Binary Packages</title>
172 Note: If you have a previous <application>Junkbuster</application> or
173 <application>Privoxy</application> installation on your system, you
174 will need to remove it. Some platforms do this for you as part
175 of their installation procedure. (See below for your platform).
179 In any case <emphasis>be sure to backup your old configuration
180 if it is valuable to you.</emphasis> See the
181 <link linkend="upgradersnote">note to upgraders</link>.
185 How to install the binary packages depends on your operating system:
188 <!-- ~~~~~ New section ~~~~~ -->
189 <sect3 id="installation-pack-rpm"><title>Red Hat and SuSE RPMs</title>
192 RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
193 and will use <filename>/etc/privoxy</filename> for the location
194 of configuration files.
198 Note that on Red Hat, Privoxy will not be automatically started on system
199 boot. You will need to enable that using linuxconf.
203 If you have problems with failed dependencies, try rebuilding the SRC RPM:
204 <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This
205 will use your locally installed libraries and RPM version.
209 Also note that if you have a <application>Junkbuster</application> RPM installed
210 on your system, you need to remove it first, because the packages conflict.
211 Otherwise, RPM will try to remove <application>Junkbuster</application>
212 automatically, before installing <application>Privoxy</application>.
216 <!-- ~~~~~ New section ~~~~~ -->
217 <sect3 id="installation-deb"><title>Debian</title>
223 <!-- ~~~~~ New section ~~~~~ -->
224 <sect3 id="installation-pack-win"><title>Windows</title>
227 Just double-click the installer, which will guide you through
228 the installation process.
232 <!-- ~~~~~ New section ~~~~~ -->
233 <sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
236 Create a new directory, <literal>cd</literal> to it, then unzip and
237 untar the archive. For the most part, you'll have to figure out where
242 <!-- ~~~~~ New section ~~~~~ -->
243 <sect3 id="installation-os2"><title>OS/2</title>
246 First, make sure that no previous installations of
247 <application>Junkbuster</application> and / or
248 <application>Privoxy</application> are left on your
249 system. You can do this by
253 Then, just double-click the WarpIN self-installing archive, which will
254 guide you through the installation process. A shadow of the
255 <application>Privoxy</application> executable will be placed in your
256 startup folder so it will start automatically whenever OS/2 starts.
260 The directory you choose to install <application>Privoxy</application>
261 into will contain all of the configuration files.
265 <!-- ~~~~~ New section ~~~~~ -->
266 <sect3 id="installation-mac"><title>Max OSX</title>
268 Unzip the downloaded package (you can either double-click on the file
269 in the finder, or on the desktop if you downloaded it there). Then,
270 double-click on the package installer icon and follow the installation
272 <application>Privoxy</application> will be installed in the subdirectory
273 <literal>/Applications/Privoxy.app</literal>.
274 <application>Privoxy</application> will set itself up to start
275 automatically on system bringup via
276 <literal>/System/Library/StartupItems/Privoxy</literal>.
280 <!-- ~~~~~ New section ~~~~~ -->
281 <sect3 id="installation-amiga"><title>AmigaOS</title>
283 Copy and then unpack the <filename>lha</filename> archive to a suitable location.
284 All necessary files will be installed into <application>Privoxy</application>
285 directory, including all configuration and log files. To uninstall, just
286 remove this directory.
289 Start <application>Privoxy</application> (with RUN <>NIL:) in your
290 <filename>startnet</filename> script (AmiTCP), in
291 <filename>s:user-startup</filename> (RoadShow), as startup program in your
292 startup script (Genesis), or as startup action (Miami and MiamiDx).
293 <application>Privoxy</application> will automatically quit when you quit your
294 TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
295 <application>Privoxy</application> is still running).
300 <!-- ~~~~~ New section ~~~~~ -->
301 <sect2 id="installation-source"><title>Building from Source</title>
303 <!-- include buildsource.sgml boilerplate: -->
305 <!-- end boilerplate -->
310 <!-- ~ End section ~ -->
313 <!-- ~~~~~ New section ~~~~~ -->
315 <sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
318 <!-- ~~~~~ New section ~~~~~ -->
319 <sect2 id="upgradersnote">
320 <title>Note to Upgraders</title>
322 There are very significant changes from older versions of
323 <application>Junkbuster</application> to the current
324 <application>Privoxy</application>. Configuration is substantially
325 changed. <application>Junkbuster 2.0.x</application> and earlier
326 configuration files will not migrate. The functionality of the old
327 <filename>blockfile</filename>, <filename>cookiefile</filename> and
328 <filename>imagelist</filename>, are now combined into the
329 <quote>actions file</quote> (<filename>default.action</filename>
330 for most installations).
333 A <quote>filter file</quote> (typically <filename>default.filter</filename>)
334 is new as of <application>Privoxy 2.9.x</application>, and provides some
335 of the new sophistication (explained below). <filename>config</filename> is
336 much the same as before.
339 If upgrading from a 2.0.x version, you will have to use the new config
340 files, and possibly adapt any personal rules from your older files.
341 When porting personal rules over from the old <filename>blockfile</filename>
342 to the new actions file, please note that even the pattern syntax has
343 changed. If upgrading from 2.9.x development versions, it is still
344 recommended to use the new configuration files.
347 A quick list of things to be aware of before upgrading:
355 The default listening port is now 8118 due to a conflict with another
361 Some installers may remove earlier versions completely. Save any
362 important configuration files!
367 <application>Privoxy</application> is controllable with a web browser
368 at the special URL: <ulink
369 url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
370 (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
371 aspects of configuration can be done here, including temporarily disabling
372 <application>Privoxy</application>.
377 The primary configuration file for cookie management, ad and banner
378 blocking, and many other aspects of <application>Privoxy</application>
379 configuration is <filename>default.action</filename>. It is strongly
380 recommended to become familiar with the new actions concept below,
381 before modifying this file.
386 <!-- I think it is best to keep this somewhat vague, in case -->
387 <!-- the situation changes under our feet. -->
388 Some installers may not automatically start
389 <application>Privoxy</application> after installation.
398 <!-- ~~~~~ New section ~~~~~ -->
400 <title>Starting <application>Privoxy</application></title>
402 Before launching <application>Privoxy</application> for the first time, you
403 will want to configure your browser(s) to use <application>Privoxy</application>
404 as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
405 and port 8118 (earlier versions used port 8000). This is the one
406 configuration step that must be done!
410 With <application>Netscape</application> (and
411 <application>Mozilla</application>), this can be set under <literal>Edit
412 -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
413 For <application>Internet Explorer</application>: <literal>Tools ->
414 Internet Properties -> Connections -> LAN Setting</literal>. Then,
415 check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
416 localhost, Port: 8118). Include if HTTPS proxy support too.
420 After doing this, flush your browser's disk and memory caches to force a
421 re-reading of all pages and to get rid of any ads that may be cached. You
422 are now ready to start enjoying the benefits of using
423 <application>Privoxy</application>!
428 <application>Privoxy</application> is typically started by specifying the
429 main configuration file to be used on the command line. Example Unix startup
436 # /usr/sbin/privoxy /etc/privoxy/config
442 See <link linkend="cmdoptions">below</link> for other command line options.
446 An init script is provided for SuSE and Red Hat.
450 For for SuSE: <command>rcprivoxy start</command>
454 For Red Hat and Debian: <command>/etc/rc.d/init.d/privoxy start</command>
459 If no configuration file is specified on the command line,
460 <application>Privoxy</application> will look for a file named
461 <filename>config</filename> in the current directory. Except on Win32 where
462 it will try <filename>config.txt</filename>. If no file is specified on the
463 command line and no default configuration file can be found,
464 <application>Privoxy</application> will fail to start.
469 The included default configuration files should give a reasonable starting
470 point. Most of the per site configuration is done in the
471 <quote>actions</quote> files. These are where various cookie actions are
472 defined, ad and banner blocking, and other aspects of
473 <application>Privoxy</application> configuration. There are several such
474 files included, with varying levels of aggressiveness.
478 You will probably want to keep an eye out for sites that require persistent
479 cookies, and add these to <filename>default.action</filename> as needed. By
480 default, most of these will be accepted only during the current browser
481 session (aka <quote>session cookies</quote>), until you add them to the
482 configuration. If you want the browser to handle this instead, you will need
483 to edit <filename>default.action</filename> and disable this feature. If you
484 use more than one browser, it would make more sense to let
485 <application>Privoxy</application> handle this. In which case, the
486 browser(s) should be set to accept all cookies.
490 Another feature where you will probably want to define exceptions for trusted
491 sites is the popup-killing (through the <literal>+popup</literal> and
492 <literal>+filter{popups}</literal> actions), because your favorite shopping,
493 banking, or leisure site may need popups.
497 <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
498 the optional 1.1 features are as yet supported. In the unlikely event that
499 you experience inexplicable problems with browsers that use HTTP/1.1 per default
500 (like <application>Mozilla</application> or recent versions of I.E.), you might
501 try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
502 Preferences -> Debug -> Networking</literal>.
503 Alternatively, set the <quote>+downgrade</quote> config option in
504 <filename>default.action</filename> which will downgrade your browser's HTTP
505 requests from HTTP/1.1 to HTTP/1.0 before processing them.
509 After running <application>Privoxy</application> for a while, you can
510 start to fine tune the configuration to suit your personal, or site,
511 preferences and requirements. There are many, many aspects that can
512 be customized. <quote>Actions</quote> (as specified in <filename>default.action</filename>)
513 can be adjusted by pointing your browser to
514 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
515 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
516 and then follow the link to <quote>edit the actions list</quote>.
517 (This is an internal page and does not require Internet access.)
521 In fact, various aspects of <application>Privoxy</application>
522 configuration can be viewed from this page, including
523 current configuration parameters, source code version numbers,
524 the browser's request headers, and <quote>actions</quote> that apply
525 to a given URL. In addition to the <filename>default.action</filename> file
526 editor mentioned above, <application>Privoxy</application> can also
527 be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
531 If you encounter problems, try loading the page without
532 <application>Privoxy</application>. If that helps, enter the URL where
533 you have the problems into <ulink url="http://p.p/show-url-info">the browser
534 based rule tracing utility</ulink>. See which rules apply and why, and
535 then try turning them off for that site one after the other, until the problem
536 is gone. When you have found the culprit, you might want to turn the rest on
541 If the above paragraph sounds gibberish to you, you might want to <ulink
542 url="configuration.html#ACTIONSFILE">read more about the actions concept</ulink>
543 or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
548 If you can't get rid of the problem at all, think you've found a bug in
549 Privoxy, want to propose a new feature or smarter rules, please see the
550 chapter "Contacting the Developers, .." below.
556 <!-- ~~~~~ New section ~~~~~ -->
557 <sect2 id="cmdoptions">
558 <title>Command Line Options</title>
560 <application>Privoxy</application> may be invoked with the following
561 command-line options:
569 <emphasis>--version</emphasis>
572 Print version info and exit. Unix only.
577 <emphasis>--help</emphasis>
580 Print short usage info and exit. Unix only.
585 <emphasis>--no-daemon</emphasis>
588 Don't become a daemon, i.e. don't fork and become process group
589 leader, and don't detach from controlling tty. Unix only.
594 <emphasis>--pidfile FILE</emphasis>
598 On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
599 <emphasis>FILE</emphasis> on exit. Failure to create or delete the
600 <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
601 option is given, no PID file will be used. Unix only.
606 <emphasis>--user USER[.GROUP]</emphasis>
610 After (optionally) writing the PID file, assume the user ID of
611 <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
612 privileges are not sufficient to do so. Unix only.
617 <emphasis>configfile</emphasis>
620 If no <emphasis>configfile</emphasis> is included on the command line,
621 <application>Privoxy</application> will look for a file named
622 <quote>config</quote> in the current directory (except on Win32
623 where it will look for <quote>config.txt</quote> instead). Specify
624 full path to avoid confusion. If no config file is found,
625 <application>Privoxy</application> will fail to start.
636 <!-- ~ End section ~ -->
639 <!-- ~~~~~ New section ~~~~~ -->
640 <sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
642 All <application>Privoxy</application> configuration is stored
643 in text files. These files can be edited with a text editor.
644 Many important aspects of <application>Privoxy</application> can
645 also be controlled easily with a web browser.
650 <!-- ~~~~~ New section ~~~~~ -->
653 <title>Controlling <application>Privoxy</application> with Your Web Browser</title>
655 <application>Privoxy</application>'s user interface can be reached through the special
656 URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
657 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
658 which is a built-in page and works without Internet access.
659 You will see the following section:
666 Please choose from the following options:
669 * Show information about the current configuration
670 * Show the source code version numbers
671 * Show the request headers.
672 * Show which actions apply to a URL and why
673 * Toggle Privoxy on or off
674 * Edit the actions list
680 This should be self-explanatory. Note the last item is an editor for the
681 <quote>actions list</quote>, which is where much of the ad, banner, cookie,
682 and URL blocking magic is configured as well as other advanced features of
683 <application>Privoxy</application>. This is an easy way to adjust various
684 aspects of <application>Privoxy</application> configuration. The actions
685 file, and other configuration files, are explained in detail below.
689 <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
690 have problems with your current actions and filters. You can in fact use
691 it as a test to see whether it is <application>Privoxy</application>
692 causing the problem or not. <application>Privoxy</application> continues
693 to run as a proxy in this case, but all filtering is disabled. There
694 is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
695 that you can toggle <application>Privoxy</application> with one click from
701 <!-- ~ End section ~ -->
706 <!-- ~~~~~ New section ~~~~~ -->
709 <title>Configuration Files Overview</title>
711 For Unix, *BSD and Linux, all configuration files are located in
712 <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
713 AmigaOS these are all in the same directory as the
714 <application>Privoxy</application> executable. <![%p-not-stable;[ The name
715 and number of configuration files has changed from previous versions, and is
716 subject to change as development progresses.]]>
720 The installed defaults provide a reasonable starting point, though possibly
721 aggressive by some standards. For the time being, there are only three
722 default configuration files (this may change in time):
730 The main configuration file is named <filename>config</filename>
731 on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
738 <filename>default.action</filename> (the actions file) is used to define
739 which of a set of various <quote>actions</quote> relating to images, banners,
740 pop-ups, access restrictions, banners and cookies are to be applied, and where.
741 There is a web based editor for this file that can be accessed at <ulink
742 url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
743 (Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).
744 (Other actions files are included as well with differing levels of filtering
745 and blocking, e.g. <filename>basic.action</filename>.)
751 <filename>default.filter</filename> (the filter file) can be used to re-write the raw
752 page content, including viewable text as well as embedded HTML and JavaScript,
753 and whatever else lurks on any given web page. The filtering jobs are only
754 pre-defined here; whether to apply them or not is up to the actions file.
762 All files use the <quote><literal>#</literal></quote> character to denote a
763 comment (the rest of the line will be ignored) and understand line continuation
764 through placing a backslash ("<literal>\</literal>") as the very last character
765 in a line. If the <literal>#</literal> is preceded by a backslash, it looses
766 its special function. Placing a <literal>#</literal> in front of an otherwise
767 valid configuration line to prevent it from being interpreted is called "commenting
772 <filename>default.action</filename> and <filename>default.filter</filename>
773 can use Perl style <link linkend="regex">regular expressions</link> for
778 After making any changes, there is no need to restart
779 <application>Privoxy</application> in order for the changes to take
780 effect. <application>Privoxy</application> detects such changes
781 automatically. Note, however, that it may take one or two additional
782 requests for the change to take effect. When changing the listening address
783 of <application>Privoxy</application>, these <quote>wake up</quote> requests
784 must obviously be sent to the <emphasis>old</emphasis> listening address.
789 While under development, the configuration content is subject to change.
790 The below documentation may not be accurate by the time you read this.
791 Also, what constitutes a <quote>default</quote> setting, may change, so
792 please check all your configuration files on important issues.
798 <!-- ~~~~~ New section ~~~~~ -->
801 <title>The Main Configuration File</title>
803 Again, the main configuration file is named <filename>config</filename> on
804 Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
805 Configuration lines consist of an initial keyword followed by a list of
806 values, all separated by whitespace (any number of spaces or tabs). For
814 <emphasis>confdir /etc/privoxy</emphasis>
821 Assigns the value <literal>/etc/privoxy</literal> to the option
822 <literal>confdir</literal> and thus indicates that the configuration
823 directory is named <quote>/etc/privoxy/</quote>.
827 All options in the config file except for <literal>confdir</literal> and
828 <literal>logdir</literal> are optional. Watch out in the below description
829 for what happens if you leave them unset.
833 The main config file controls all aspects of <application>Privoxy</application>'s
834 operation that are not location dependent (i.e. they apply universally, no matter
835 where you may be surfing).
839 <!-- ~~~~~ New section ~~~~~ -->
842 <title>Configuration and Log File Locations</title>
845 <application>Privoxy</application> can (and normally does) use a number of
846 other files for additional configuration and logging.
847 This section of the configuration file tells <application>Privoxy</application>
848 where to find those other files.
852 <sect4><title>confdir</title>
856 <term>Specifies:</term>
858 <para>The directory where the other configuration files are located</para>
862 <term>Type of value:</term>
864 <para>Path name</para>
868 <term>Default value:</term>
870 <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
874 <term>Effect if unset:</term>
876 <para><emphasis>Mandatory</emphasis></para>
883 No trailing <quote><literal>/</literal></quote>, please
886 When development goes modular and multi-user, the blocker, filter, and
887 per-user config will be stored in subdirectories of <quote>confdir</quote>.
888 For now, the configuration directory structure is flat, except for
889 <filename>confdir/templates</filename>, where the HTML templates for CGI
890 output reside (e.g. <application>Privoxy's</application> 404 error page).
898 <sect4><title>logdir</title>
902 <term>Specifies:</term>
905 The directory where all logging takes place (i.e. where <filename>logfile</filename> and
906 <filename>jarfile</filename> are located)
911 <term>Type of value:</term>
913 <para>Path name</para>
917 <term>Default value:</term>
919 <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
923 <term>Effect if unset:</term>
925 <para><emphasis>Mandatory</emphasis></para>
932 No trailing <quote><literal>/</literal></quote>, please
939 <sect4><title>actionsfile</title>
943 <term>Specifies:</term>
946 The actions file to use
951 <term>Type of value:</term>
953 <para>File name, relative to <literal>confdir</literal></para>
957 <term>Default value:</term>
959 <para>default.action (Unix) <emphasis>or</emphasis> default.action.txt (Windows)</para>
963 <term>Effect if unset:</term>
966 No action is taken at all. Simple neutral proxying.
974 There is no point in using <application>Privoxy</application> without
975 an actions file. There are three different actions files included in the
976 distribution, with varying degrees of aggressiveness:
977 <filename>default.action</filename>, <filename>intermediate.action</filename> and
978 <filename>advanced.action</filename>.
985 <sect4><title>filterfile</title>
989 <term>Specifies:</term>
992 The filter file to use
997 <term>Type of value:</term>
999 <para>File name, relative to <literal>confdir</literal></para>
1003 <term>Default value:</term>
1005 <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
1009 <term>Effect if unset:</term>
1012 No textual content filtering takes place, i.e. all
1013 <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
1014 actions in the actions file are turned off
1022 The <quote>default.filter</quote> file contains content modification rules
1023 that use <quote>regular expressions</quote>. These rules permit powerful
1024 changes on the content of Web pages, e.g., you could disable your favorite
1025 JavaScript annoyances, re-write the actual displayed text, or just have some
1026 fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
1027 it appears on a Web page.
1034 <sect4><title>logfile</title>
1038 <term>Specifies:</term>
1046 <term>Type of value:</term>
1048 <para>File name, relative to <literal>logdir</literal></para>
1052 <term>Default value:</term>
1054 <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
1058 <term>Effect if unset:</term>
1061 No log file is used, all log messages go to the console (<literal>stderr</literal>).
1069 The windows version will additionally log to the console.
1072 The logfile is where all logging and error messages are written. The level
1073 of detail and number of messages are set with the <literal>debug</literal>
1074 option (see below). The logfile can be useful for tracking down a problem with
1075 <application>Privoxy</application> (e.g., it's not blocking an ad you
1076 think it should block) but in most cases you probably will never look at it.
1079 Your logfile will grow indefinitely, and you will probably want to
1080 periodically remove it. On Unix systems, you can do this with a cron job
1081 (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
1082 script has been included.
1085 On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
1086 +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
1087 the effect that cron.daily will automatically archive, gzip, and empty the
1088 log, when it exceeds 1M size.
1095 <sect4><title>jarfile</title>
1099 <term>Specifies:</term>
1102 The file to store intercepted cookies in
1107 <term>Type of value:</term>
1109 <para>File name, relative to <literal>logdir</literal></para>
1113 <term>Default value:</term>
1115 <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
1119 <term>Effect if unset:</term>
1122 Intercepted cookies are not stored at all.
1130 The jarfile may grow to ridiculous sizes over time.
1137 <sect4><title>trustfile</title>
1141 <term>Specifies:</term>
1144 The trust file to use
1149 <term>Type of value:</term>
1151 <para>File name, relative to <literal>confdir</literal></para>
1155 <term>Default value:</term>
1157 <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
1161 <term>Effect if unset:</term>
1164 The whole trust mechanism is turned off.
1172 The trust mechanism is an experimental feature for building white-lists and should
1173 be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
1176 If you specify a trust file, <application>Privoxy</application> will only allow
1177 access to sites that are named in the trustfile.
1178 You can also mark sites as trusted referrers (with <literal>+</literal>), with
1179 the effect that access to untrusted sites will be granted, if a link from a
1180 trusted referrer was used.
1181 The link target will then be added to the <quote>trustfile</quote>.
1182 Possible applications include limiting Internet access for children.
1185 If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
1194 <!-- ~ End section ~ -->
1198 <!-- ~~~~~ New section ~~~~~ -->
1201 <title>Local Set-up Documentation</title>
1204 If you intend to operate <application>Privoxy</application> for more users
1205 that just yourself, it might be a good idea to let them know how to reach
1206 you, what you block and why you do that, your policies etc.
1209 <sect4><title>trust-info-url</title>
1213 <term>Specifies:</term>
1216 A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
1221 <term>Type of value:</term>
1227 <term>Default value:</term>
1229 <para>Two example URL are provided</para>
1233 <term>Effect if unset:</term>
1236 No links are displayed on the "untrusted" error page.
1244 The value of this option only matters if the experimental trust mechanism has been
1245 activated. (See <literal>trustfile</literal> above.)
1248 If you use the trust mechanism, it is a good idea to write up some on-line
1249 documentation about your trust policy and to specify the URL(s) here.
1250 Use multiple times for multiple URLs.
1253 The URL(s) should be added to the trustfile as well, so users don't end up
1254 locked out from the information on why they were locked out in the first place!
1261 <sect4><title>admin-address</title>
1265 <term>Specifies:</term>
1268 An email address to reach the proxy administrator.
1273 <term>Type of value:</term>
1275 <para>Email address</para>
1279 <term>Default value:</term>
1281 <para><emphasis>Unset</emphasis></para>
1285 <term>Effect if unset:</term>
1288 No email address is displayed on error pages and the CGI user interface.
1296 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1297 are unset, the whole "Local Privoxy Support" box on all generated pages will
1305 <sect4><title>proxy-info-url</title>
1309 <term>Specifies:</term>
1312 A URL to documentation about the local <application>Privoxy</application> setup,
1313 configuration or policies.
1318 <term>Type of value:</term>
1324 <term>Default value:</term>
1326 <para><emphasis>Unset</emphasis></para>
1330 <term>Effect if unset:</term>
1333 No link to local documentation is displayed on error pages and the CGI user interface.
1341 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1342 are unset, the whole "Local Privoxy Support" box on all generated pages will
1346 This URL shouldn't be blocked ;-)
1354 <!-- ~ End section ~ -->
1356 <!-- ~~~~~ New section ~~~~~ -->
1359 <title>Debugging</title>
1362 These options are mainly useful when tracing a problem.
1363 Note that you might also want to invoke
1364 <application>Privoxy</application> with the <literal>--no-daemon</literal>
1365 command line option when debugging.
1368 <sect4><title>debug</title>
1372 <term>Specifies:</term>
1375 Key values that determine what information gets logged.
1380 <term>Type of value:</term>
1382 <para>Integer values</para>
1386 <term>Default value:</term>
1388 <para>12289 (i.e.: URLs plus informational and warning messages)</para>
1392 <term>Effect if unset:</term>
1395 Nothing gets logged.
1403 The available debug levels are:
1407 debug 1 # show each GET/POST/CONNECT request
1408 debug 2 # show each connection status
1409 debug 4 # show I/O status
1410 debug 8 # show header parsing
1411 debug 16 # log all data into the logfile
1412 debug 32 # debug force feature
1413 debug 64 # debug regular expression filter
1414 debug 128 # debug fast redirects
1415 debug 256 # debug GIF de-animation
1416 debug 512 # Common Log Format
1417 debug 1024 # debug kill pop-ups
1418 debug 4096 # Startup banner and warnings.
1419 debug 8192 # Non-fatal errors
1423 To select multiple debug levels, you can either add them or use
1424 multiple <literal>debug</literal> lines.
1427 A debug level of 1 is informative because it will show you each request
1428 as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
1429 so that you will notice when things go wrong. The other levels are probably
1430 only of interest if you are hunting down a specific problem. They can produce
1431 a hell of an output (especially 16).
1435 The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
1436 <application>Privoxy</application>) is always on and cannot be disabled.
1439 If you want to use CLF (Common Log Format), you should set <quote>debug
1440 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
1447 <sect4><title>single-threaded</title>
1451 <term>Specifies:</term>
1454 Whether to run only one server thread
1459 <term>Type of value:</term>
1461 <para><emphasis>None</emphasis></para>
1465 <term>Default value:</term>
1467 <para><emphasis>Unset</emphasis></para>
1471 <term>Effect if unset:</term>
1474 Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1475 serve multiple requests simultaneously.
1483 This option is only there for debug purposes and you should never
1484 need to use it. <emphasis>It will drastically reduce performance.</emphasis>
1493 <!-- ~~~~~ New section ~~~~~ -->
1496 <title>Access Control and Security</title>
1499 This section of the config file controls the security-relevant aspects
1500 of <application>Privoxy</application>'s configuration.
1503 <sect4><title>listen-address</title>
1507 <term>Specifies:</term>
1510 The IP address and TCP port on which <application>Privoxy</application> will
1511 listen for client requests.
1516 <term>Type of value:</term>
1518 <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
1522 <term>Default value:</term>
1524 <para>localhost:8118</para>
1528 <term>Effect if unset:</term>
1531 Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
1532 home users who run <application>Privoxy</application> on the same machine as
1541 You will need to configure your browser(s) to this proxy address and port.
1544 If you already have another service running on port 8118, or if you want to
1545 serve requests from other machines (e.g. on your local network) as well, you
1546 will need to override the default.
1549 If you leave out the IP address, <application>Privoxy</application> will
1550 bind to all interfaces (addresses) on your machine and may become reachable
1551 from the Internet. In that case, consider using access control lists (acl's)
1552 (see <quote>ACLs</quote> below), or a firewall.
1557 <term>Example:</term>
1560 Suppose you are running <application>Privoxy</application> on
1561 a machine which has the address 192.168.0.1 on your local private network
1562 (192.168.0.0) and has another outside connection with a different address.
1563 You want it to serve requests from inside only:
1567 listen-address 192.168.0.1:8118
1575 <sect4><title>toggle</title>
1579 <term>Specifies:</term>
1582 Initial state of "toggle" status
1587 <term>Type of value:</term>
1593 <term>Default value:</term>
1599 <term>Effect if unset:</term>
1602 Act as if toggled on
1610 If set to 0, <application>Privoxy</application> will start in
1611 <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
1612 proxy. See <literal>enable-remote-toggle</literal>
1613 below. This is not really useful anymore, since toggling is much easier
1614 via <ulink url="http://config.privoxy.org/toggle">the web
1615 interface</ulink> then via editing the <filename>conf</filename> file.
1618 The windows version will only display the toggle icon in the system tray
1619 if this option is present.
1627 <sect4><title>enable-remote-toggle</title>
1630 <term>Specifies:</term>
1633 Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
1634 feature</ulink> may be used
1639 <term>Type of value:</term>
1645 <term>Default value:</term>
1651 <term>Effect if unset:</term>
1654 The web-based toggle feature is disabled.
1662 When toggled off, <application>Privoxy</application> acts like a normal,
1663 content-neutral proxy, i.e. it acts as if none of the actions applied to
1667 For the time being, access to the toggle feature can <emphasis>not</emphasis> be
1668 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1669 so that everybody who can access <application>Privoxy</application> (see
1670 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1671 toggle it for all users. So this option is <emphasis>not recommended</emphasis>
1672 for multi-user environments with untrusted users.
1675 Note that you must have compiled <application>Privoxy</application> with
1676 support for this feature, otherwise this option has no effect.
1684 <sect4><title>enable-edit-actions</title>
1687 <term>Specifies:</term>
1690 Whether or not the <ulink url="http://config.privoxy.org/edit-actions">web-based actions
1691 file editor</ulink> may be used
1696 <term>Type of value:</term>
1702 <term>Default value:</term>
1708 <term>Effect if unset:</term>
1711 The web-based actions file editor is disabled.
1719 For the time being, access to the editor can <emphasis>not</emphasis> be
1720 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1721 so that everybody who can access <application>Privoxy</application> (see
1722 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1723 modify its configuration for all users. So this option is <emphasis>not
1724 recommended</emphasis> for multi-user environments with untrusted users.
1727 Note that you must have compiled <application>Privoxy</application> with
1728 support for this feature, otherwise this option has no effect.
1735 <sect4><title>ACLs: permit-access and deny-access</title>
1738 <term>Specifies:</term>
1741 Who can access what.
1746 <term>Type of value:</term>
1749 <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
1750 [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
1753 Where <replaceable class="parameter">src_addr</replaceable> and
1754 <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
1755 DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
1756 <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
1757 values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
1758 destination part are optional.
1763 <term>Default value:</term>
1765 <para><emphasis>Unset</emphasis></para>
1769 <term>Effect if unset:</term>
1772 Don't restrict access further than implied by <literal>listen-address</literal>
1780 Access controls are included at the request of ISPs and systems
1781 administrators, and <emphasis>are not usually needed by individual users</emphasis>.
1782 For a typical home user, it will normally suffice to ensure that
1783 <application>Privoxy</application> only listens on the localhost or internal (home)
1784 network address by means of the <literal>listen-address</literal> option.
1787 Please see the warnings in the FAQ that this proxy is not intended to be a substitute
1788 for a firewall or to encourage anyone to defer addressing basic security
1792 Multiple ACL lines are OK.
1793 If any ACLs are specified, then the <application>Privoxy</application>
1794 talks only to IP addresses that match at least one <literal>permit-access</literal> line
1795 and don't match any subsequent <literal>deny-access</literal> line. In other words, the
1796 last match wins, with the default being <literal>deny-access</literal>.
1799 If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
1800 for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
1801 that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
1802 of the ultimate target. This is necessary because it may be impossible for the local
1803 <application>Privoxy</application> to determine the IP address of the
1804 ultimate target (that's often what gateways are used for).
1807 You should prefer using IP addresses over DNS names, because the address lookups take
1808 time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
1809 like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
1810 IP addresses, only the first one is used.
1813 Denying access to particular sites by ACL may have undesired side effects
1814 if the site in question is hosted on a machine which also hosts other sites.
1819 <term>Examples:</term>
1822 Explicitly define the default behavior if no ACL and
1823 <literal>listen-address</literal> are set: <quote>localhost</quote>
1824 is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
1825 <emphasis>all</emphasis> destination addresses are OK:
1829 permit-access localhost
1833 Allow any host on the same class C subnet as www.privoxy.org access to
1834 nothing but www.example.com:
1838 permit-access www.privoxy.org/24 www.example.com/32
1842 Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1843 with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
1847 permit-access 192.168.45.64/26
1848 deny-access 192.168.45.73 www.dirty-stuff.example.com
1856 <sect4><title>buffer-limit</title>
1860 <term>Specifies:</term>
1863 Maximum size of the buffer for content filtering.
1868 <term>Type of value:</term>
1870 <para>Size in Kbytes</para>
1874 <term>Default value:</term>
1880 <term>Effect if unset:</term>
1883 Use a 4MB (4096 KB) limit.
1891 For content filtering, i.e. the <literal>+filter</literal> and
1892 <literal>+deanimate-gif</literal> actions, it is necessary that
1893 <application>Privoxy</application> buffers the entire document body.
1894 This can be potentially dangerous, since a server could just keep sending
1895 data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1899 When a document buffer size reaches the <literal>buffer-limit</literal>, it is
1900 flushed to the client unfiltered and no further attempt to
1901 filter the rest of the document is made. Remember that there may be multiple threads
1902 running, which might require up to <literal>buffer-limit</literal> Kbytes
1903 <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
1913 <!-- ~ End section ~ -->
1916 <!-- ~~~~~ New section ~~~~~ -->
1918 <sect3 id="forwarding">
1919 <title>Forwarding</title>
1922 This feature allows routing of HTTP requests through a chain of
1924 It can be used to better protect privacy and confidentiality when
1925 accessing specific domains by routing requests to those domains
1926 through an anonymous public proxy (see e.g. <ulink
1927 url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
1928 Or to use a caching proxy to speed up browsing. Or chaining to a parent
1929 proxy may be necessary because the machine that <application>Privoxy</application>
1930 runs on has no direct Internet access.
1934 Also specified here are SOCKS proxies. <application>Privoxy</application>
1935 supports the SOCKS 4 and SOCKS 4A protocols.
1938 <sect4><title>forward</title>
1941 <term>Specifies:</term>
1944 To which parent HTTP proxy specific requests should be routed.
1949 <term>Type of value:</term>
1952 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
1953 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
1956 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
1957 chapter on domain matching in the actions file),
1958 <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
1959 as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
1960 <quote>no forwarding</quote>, and the optional
1961 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
1962 values from 1 to 64535
1967 <term>Default value:</term>
1969 <para><emphasis>Unset</emphasis></para>
1973 <term>Effect if unset:</term>
1976 Don't use parent HTTP proxies.
1984 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
1985 forwarded to another HTTP proxy but are made directly to the web servers.
1988 Multiple lines are OK, they are checked in sequence, and the last match wins.
1993 <term>Examples:</term>
1996 Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
2000 forward .* anon-proxy.example.org:8080
2005 Everything goes to our example ISP's caching proxy, except for requests
2006 to that ISP's sites:
2010 forward .*. caching-proxy.example-isp.net:8000
2011 forward .example-isp.net .
2019 <sect4><title>forward-socks4 and forward-socks4a</title>
2022 <term>Specifies:</term>
2025 Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
2030 <term>Type of value:</term>
2033 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2034 <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
2035 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2038 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2039 chapter on domain matching in the actions file),
2040 <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
2041 are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
2042 may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
2043 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
2048 <term>Default value:</term>
2050 <para><emphasis>Unset</emphasis></para>
2054 <term>Effect if unset:</term>
2057 Don't use SOCKS proxies.
2065 Multiple lines are OK, they are checked in sequence, and the last match wins.
2068 The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
2069 is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
2070 server, while in SOCKS 4 it happens locally.
2073 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2074 forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
2080 <term>Examples:</term>
2083 From the company example.com, direct connections are made to all
2084 <quote>internal</quote> domains, but everything outbound goes through
2085 their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
2090 forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
2091 forward .example.com .
2095 A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
2099 forward-socks4 .*. socks-gw.example.com:1080 .
2107 <sect4><title>Advanced Forwarding Examples</title>
2110 If you have links to multiple ISPs that provide various special content
2111 only to their subscribers, you can configure multiple <application>Privoxies</application>
2112 which have connections to the respective ISPs to act as forwarders to each other, so that
2113 <emphasis>your</emphasis> users can see the internal content of all ISPs.
2117 Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
2118 isp-b.net. Both run <application>Privoxy</application>. Their forwarding
2119 configuration can look like this:
2129 forward .isp-b.net host-b:8118
2140 forward .isp-a.net host-a:8118
2145 Now, your users can set their browser's proxy to use either
2146 host-a or host-b and be able to browse the internal content
2147 of both isp-a and isp-b.
2151 If you intend to chain <application>Privoxy</application> and
2152 <application>squid</application> locally, then chain as
2153 <literal>browser -> squid -> privoxy</literal> is the recommended way.
2157 Assuming that <application>Privoxy</application> and <application>squid</application>
2158 run on the same box, your squid configuration could then look like this:
2163 # Define Privoxy as parent proxy (without ICP)
2164 cache_peer 127.0.0.1 parent 8118 7 no-query
2166 # Define ACL for protocol FTP
2169 # Do not forward FTP requests to Privoxy
2170 always_direct allow ftp
2172 # Forward all the rest to Privoxy
2173 never_direct allow all
2178 You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
2179 Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
2186 <!-- ~ End section ~ -->
2189 <!-- ~~~~~ New section ~~~~~ -->
2192 <title>Windows GUI Options</title>
2194 <application>Privoxy</application> has a number of options specific to the
2195 Windows GUI interface:
2199 If <quote>activity-animation</quote> is set to 1, the
2200 <application>Privoxy</application> icon will animate when
2201 <quote>Privoxy</quote> is active. To turn off, set to 0.
2208 <emphasis>activity-animation 1</emphasis>
2215 If <quote>log-messages</quote> is set to 1,
2216 <application>Privoxy</application> will log messages to the console
2224 <emphasis>log-messages 1</emphasis>
2231 If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
2232 i.e. the amount of memory used for the log messages displayed in the
2233 console window, will be limited to <quote>log-max-lines</quote> (see below).
2237 Warning: Setting this to 0 will result in the buffer to grow infinitely and
2238 eat up all your memory!
2245 <emphasis>log-buffer-size 1</emphasis>
2252 <application>log-max-lines</application> is the maximum number of lines held
2253 in the log buffer. See above.
2260 <emphasis>log-max-lines 200</emphasis>
2267 If <quote>log-highlight-messages</quote> is set to 1,
2268 <application>Privoxy</application> will highlight portions of the log
2269 messages with a bold-faced font:
2276 <emphasis>log-highlight-messages 1</emphasis>
2283 The font used in the console window:
2290 <emphasis>log-font-name Comic Sans MS</emphasis>
2297 Font size used in the console window:
2304 <emphasis>log-font-size 8</emphasis>
2311 <quote>show-on-task-bar</quote> controls whether or not
2312 <application>Privoxy</application> will appear as a button on the Task bar
2320 <emphasis>show-on-task-bar 0</emphasis>
2327 If <quote>close-button-minimizes</quote> is set to 1, the Windows close
2328 button will minimize <application>Privoxy</application> instead of closing
2329 the program (close with the exit option on the File menu).
2336 <emphasis>close-button-minimizes 1</emphasis>
2343 The <quote>hide-console</quote> option is specific to the MS-Win console
2344 version of <application>Privoxy</application>. If this option is used,
2345 <application>Privoxy</application> will disconnect from and hide the
2362 <!-- ~ End section ~ -->
2365 <!-- ~~~~~ New section ~~~~~ -->
2366 <sect2 id="actionsfile">
2367 <title>The Actions File</title>
2370 The actions file (<filename>default.action</filename>, formerly:
2371 <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used
2372 to define what actions <application>Privoxy</application> takes for which
2373 URLs, and thus determines how ad images, cookies and various other aspects
2374 of HTTP content and transactions are handled on which sites (or even parts
2379 Anything you want can blocked, including ads, banners, or just some obnoxious
2380 URL that you would rather not see. Cookies can be accepted or rejected, or
2381 accepted only during the current browser session (i.e. not written to disk),
2382 content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
2383 See below for a complete list of available actions.
2387 An actions file typically has sections. At the top, <quote>aliases</quote> are
2388 defined (discussed below), then the default set of rules which will apply
2389 universally to all sites and pages. And then below that is generally a lengthy
2390 set of exceptions to the defined universal policies.
2393 <!-- ~~~~~ New section ~~~~~ -->
2395 <title>Finding the Right Mix</title>
2397 Note that some actions like cookie suppression or script disabling may
2398 render some sites unusable, which rely on these techniques to work properly.
2399 Finding the right mix of actions is not easy and certainly a matter of personal
2400 taste. In general, it can be said that the more <quote>aggressive</quote>
2401 your default settings (in the top section of the actions file) are,
2402 the more exceptions for <quote>trusted</quote> sites you will have to
2403 make later. If, for example, you want to kill popup windows per default, you'll
2404 have to make exceptions from that rule for sites that you regularly use
2405 and that require popups for actually useful content, like maybe your bank,
2406 favorite shop, or newspaper.
2410 We have tried to provide you with reasonable rules to start from in the
2411 distribution actions file. But there is no general rule of thumb on these
2412 things. There just are too many variables, and sites are constantly changing.
2413 Sooner or later you will want to change the rules (and read this chapter).
2417 <!-- ~~~~~ New section ~~~~~ -->
2419 <title>How to Edit</title>
2421 The easiest way to edit the <quote>actions</quote> file is with a browser by
2422 using our browser-based editor, which is available at <ulink
2423 url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>.
2427 If you prefer plain text editing to GUIs, you can of course also directly edit the
2428 <filename>default.action</filename> file.
2434 <title>How Actions are Applied to URLs</title>
2436 The actions file is divided into sections. There are special sections,
2437 like the alias sections which will be discussed later. For now let's
2438 concentrate on regular sections: They have a heading line (often split
2439 up to multiple lines for readability) which consist of a list of actions,
2440 separated by whitespace and enclosed in curly braces. Below that, there
2441 is a list of URL patterns, each on a separate line.
2445 To determine which actions apply to a request, the URL of the request is
2446 compared to all patterns in this file. Every time it matches, the list of
2447 applicable actions for the URL is incrementally updated, using the heading
2448 of the section in which the pattern is located. If multiple matches for
2449 the same URL set the same action differently, the last match wins.
2453 You can trace this process by visiting <ulink
2454 url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2458 More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2459 Anatomy of an Action</link>.
2463 <!-- ~~~~~ New section ~~~~~ -->
2465 <title>Patterns</title>
2467 Generally, a pattern has the form <literal><domain>/<path></literal>,
2468 where both the <literal><domain></literal> and <literal><path></literal>
2469 are optional. (This is why the pattern <literal>/</literal> matches all URLs).
2474 <term><literal>www.example.com/</literal></term>
2477 is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2478 regardless of which document on that server is requested.
2483 <term><literal>www.example.com</literal></term>
2486 means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2492 <term><literal>www.example.com/index.html</literal></term>
2495 matches only the single document <literal>/index.html</literal>
2496 on <literal>www.example.com</literal>.
2501 <term><literal>/index.html</literal></term>
2504 matches the document <literal>/index.html</literal>, regardless of the domain,
2505 i.e. on <emphasis>any</emphasis> web server.
2510 <term><literal>index.html</literal></term>
2513 matches nothing, since it would be interpreted as a domain name and
2514 there is no top-level domain called <literal>.html</literal>.
2520 <sect4><title>The Domain Pattern</title>
2523 The matching of the domain part offers some flexible options: if the
2524 domain starts or ends with a dot, it becomes unanchored at that end.
2530 <term><literal>.example.com</literal></term>
2533 matches any domain that <emphasis>ENDS</emphasis> in
2534 <literal>.example.com</literal>
2539 <term><literal>www.</literal></term>
2542 matches any domain that <emphasis>STARTS</emphasis> with
2543 <literal>www.</literal>
2548 <term><literal>.example.</literal></term>
2551 matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
2552 (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
2559 Additionally, there are wild-cards that you can use in the domain names
2560 themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
2561 stands for zero or more arbitrary characters, <quote>?</quote> stands for
2562 any single character, you can define character classes in square
2563 brackets and all of that can be freely mixed:
2568 <term><literal>ad*.example.com</literal></term>
2571 matches <quote>adserver.example.com</quote>,
2572 <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2577 <term><literal>*ad*.example.com</literal></term>
2580 matches all of the above, and then some.
2585 <term><literal>.?pix.com</literal></term>
2588 matches <literal>www.ipix.com</literal>,
2589 <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2594 <term><literal>www[1-9a-ez].example.c*</literal></term>
2597 matches <literal>www1.example.com</literal>,
2598 <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2599 <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2600 <literal>wwww.example.com</literal>.
2608 <sect4><title>The Path Pattern</title>
2611 <application>Privoxy</application> uses Perl compatible regular expressions
2612 (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2617 There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2618 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2619 at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2620 You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2621 useful, which is available on-line at <ulink
2622 url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
2626 Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2627 i.e. it matches as if it would start with a <quote>^</quote>.
2631 Please also note that matching in the path is case
2632 <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
2633 sensitive at any point in the pattern by using the
2634 <quote>(?-i)</quote> switch:
2635 <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
2636 documents whose path starts with <literal>PaTtErN</literal> in
2637 <emphasis>exactly</emphasis> this capitalization.
2643 <!-- ~ End section ~ -->
2646 <!-- ~~~~~ New section ~~~~~ -->
2648 <sect3 id="actions">
2649 <title>Actions</title>
2651 Actions are enabled if preceded with a <quote>+</quote>, and disabled if
2652 preceded with a <quote>-</quote>. Actions are invoked by enclosing the
2653 action name in curly braces (e.g. {+some_action}), followed by a list of
2654 URLs (or patterns that match URLs) to which the action applies. There are
2655 three classes of actions:
2663 Boolean, i.e the action can only be <quote>on</quote> or
2664 <quote>off</quote>. Examples:
2670 <emphasis>{+name}</emphasis> # enable this action
2671 <emphasis>{-name}</emphasis> # disable this action
2681 Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>,
2682 where some value is required in order to enable this type of action.
2689 <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
2690 <emphasis>{-name}</emphasis> # disable action (<quote>parameter</quote>) can be omitted
2699 <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
2700 Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> ot
2701 <quote>{+/-wafer{name=value}}</quote>), where some value needs to be defined
2702 in addition to simply enabling the actino. Examples:
2708 <emphasis>{+name{param=value}}</emphasis> # enable action and set <quote>param</quote> to <quote>value</quote>
2709 <emphasis>{-name{param=value}}</emphasis> # remove the parameter <quote>param</quote> completely
2710 <emphasis>{-name}</emphasis> # disable this action totally and remove <application>param</application> too
2721 If nothing is specified in this file, no <quote>actions</quote> are taken.
2722 So in this case <application>Privoxy</application> would just be a
2723 normal, non-blocking, non-anonymizing proxy. You must specifically
2724 enable the privacy and blocking features you need (although the
2725 provided default <filename>default.action</filename> file will
2726 give a good starting point).
2730 Later defined actions always over-ride earlier ones. So exceptions
2731 to any rules you make, should come in the latter part of the file. For
2732 multi-valued actions, the actions are applied in the order they are
2736 <!-- start actions listing -->
2738 The list of valid <application>Privoxy</application> <quote>actions</quote> are:
2742 <!-- ********************************************************** -->
2743 <!-- Please note the below defined actions use id's that are -->
2744 <!-- probably linked from other places, so please don't change. -->
2746 <!-- ********************************************************** -->
2749 <!-- ~~~~~ New section ~~~~~ -->
2751 <sect4 id="add-header">
2752 <title><emphasis>+add-header{Name: value}</emphasis></title>
2757 <!-- boolean, parameterized, Multi-value -->
2759 <para>Multi-value.</para>
2764 <term>Typical uses:</term>
2767 Send a user defined HTTP header to the web server.
2773 <term>Possible values:</term>
2776 Any value is possible. Validity of the defined HTTP headers is not checked.
2782 <term>Example usage:</term>
2785 <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
2786 <emphasis>.example.com</emphasis>
2795 This action may be specified multiple times, in order to define multiple
2796 headers. This is rarely needed for the typical user. If you don't know what
2797 <quote>HTTP headers</quote> are, you definitely don't need to worry about this
2806 <!-- ~~~~~ New section ~~~~~ -->
2808 <title><emphasis>+block</emphasis></title>
2813 <!-- boolean, parameterized, Multi-value -->
2815 <para>Boolean.</para>
2820 <term>Typical uses:</term>
2823 Used to block a URL from reaching your browser. The URL may be
2824 anything, but is typically used to block ads or other obnoxious
2831 <term>Possible values:</term>
2838 <term>Example usage:</term>
2841 <emphasis>{+block}</emphasis>
2842 <emphasis>.example.com</emphasis>
2843 <emphasis>.ads.r.us</emphasis>
2852 <application>Privoxy</application> will display its
2853 special <quote>BLOCKED</quote> page if a URL matches one of the
2854 blocked patterns. If there is sufficient space, a large red
2855 banner will appear with a friendly message about why the page
2856 was blocked, and a way to go there anyway. If there is insufficient
2857 space a smaller blocked page will appear without the red banner.
2858 One exception is if the URL matches both <quote>+block</quote>
2859 and <quote>+image</quote>, then it can be handled by
2860 <quote>+image-blocker</quote> (see below).
2869 <!-- ~~~~~ New section ~~~~~ -->
2870 <sect4 id="deanimate-gifs">
2871 <title><emphasis>+deanimate-gifs</emphasis></title>
2876 <!-- boolean, parameterized, Multi-value -->
2878 <para>Parameterized.</para>
2883 <term>Typical uses:</term>
2886 To stop those annoying, distracting animated GIF images.
2892 <term>Possible values:</term>
2895 <quote>last</quote> or <quote>first</quote>
2901 <term>Example usage:</term>
2904 <emphasis>{+deanimate-gifs{last}}</emphasis>
2905 <emphasis>.example.com</emphasis>
2914 De-animate all animated GIF images, i.e. reduce them to their last frame.
2915 This will also shrink the images considerably (in bytes, not pixels!). If
2916 the option <quote>first</quote> is given, the first frame of the animation
2917 is used as the replacement. If <quote>last</quote> is given, the last
2918 frame of the animation is used instead, which probably makes more sense for
2919 most banner animations, but also has the risk of not showing the entire
2920 last frame (if it is only a delta to an earlier frame).
2928 <!-- ~~~~~ New section ~~~~~ -->
2929 <sect4 id="downgrade">
2930 <title><emphasis>+downgrade</emphasis></title>
2935 <!-- boolean, parameterized, Multi-value -->
2937 <para>Boolean.</para>
2942 <term>Typical uses:</term>
2945 <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
2946 HTTP/1.0 and downgrade the responses as well.
2952 <term>Possible values:</term>
2961 <term>Example usage:</term>
2964 <emphasis>{+downgrade}</emphasis>
2965 <emphasis>.example.com</emphasis>
2974 Use this action for servers that use HTTP/1.1 protocol features that
2975 <application>Privoxy</application> doesn't handle well yet. HTTP/1.1 is
2976 only partially implemented. Default is not to downgrade requests. This is
2977 an infrequently needed action, and is used to help with problem sites only.
2985 <!-- ~~~~~ New section ~~~~~ -->
2986 <sect4 id="fast-redirects">
2987 <title><emphasis>+fast-redirects</emphasis></title>
2992 <!-- boolean, parameterized, Multi-value -->
2994 <para>Boolean.</para>
2999 <term>Typical uses:</term>
3002 The <quote>+fast-redirects</quote> action enables interception of
3003 <quote>redirect</quote> requests from one server to another, which
3004 are used to track users.<application>Privoxy</application> can cut off
3005 all but the last valid URL in redirect request and send a local redirect
3006 back to your browser without contacting the intermediate site(s).
3012 <term>Possible values:</term>
3021 <term>Example usage:</term>
3024 <emphasis>{+fast-redirects}</emphasis>
3025 <emphasis>.example.com</emphasis>
3034 Many sites, like yahoo.com, don't just link to other sites. Instead, they
3035 will link to some script on their own server, giving the destination as a
3036 parameter, which will then redirect you to the final target. URLs
3037 resulting from this scheme typically look like:
3038 <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
3041 Sometimes, there are even multiple consecutive redirects encoded in the
3042 URL. These redirections via scripts make your web browsing more traceable,
3043 since the server from which you follow such a link can see where you go
3044 to. Apart from that, valuable bandwidth and time is wasted, while your
3045 browser ask the server for one redirect after the other. Plus, it feeds
3049 This is a normally on feature, and often requires exceptions for sites that
3050 are sensitive to defeating this mechanism.
3059 <!-- ~~~~~ New section ~~~~~ -->
3061 <title><emphasis>+filter</emphasis></title>
3066 <!-- boolean, parameterized, Multi-value -->
3068 <para>Parameterized.</para>
3073 <term>Typical uses:</term>
3076 Apply page filtering as defined by named sections of the
3077 <filename>default.filter</filename> file to the specified site(s).
3078 <quote>Filtering</quote> can be any modification of the raw
3079 page content, including re-writing or deletion.
3085 <term>Possible values:</term>
3088 <quote>+filter</quote> must include the name of one of the section identifiers
3089 from <filename>default.filter</filename> (or whatever
3090 <emphasis>filterfile</emphasis> is specified in <filename>config</filename>).
3096 <term>Example usage (from the current <filename>default.filter</filename>):</term>
3100 <emphasis>+filter{html-annoyances}</emphasis>: Get rid of particularly annoying HTML abuse.
3105 <emphasis>+filter{js-annoyances}</emphasis>: Get rid of particularly annoying JavaScript abuse
3110 <emphasis>+filter{content-cookies}</emphasis>: Kill cookies that come in the HTML or JS content
3115 <emphasis>+filter{popups}</emphasis>: Kill all popups in JS and HTML
3120 <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable
3125 <emphasis>+filter{webbugs}</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
3130 <emphasis>+filter{refresh-tags}</emphasis>: Kill automatic refresh tags (for dial-on-demand setups)
3135 <emphasis>+filter{fun}</emphasis>: Text replacements for subversive browsing fun!
3140 <emphasis>+filter{nimda}</emphasis>: Remove Nimda (virus) code.
3145 <emphasis>+filter{banners-by-size}</emphasis>: Kill banners by size (<emphasis>very</emphasis> efficient!)
3150 <emphasis>+filter{shockwave-flash}</emphasis>: Kill embedded Shockwave Flash objects
3155 <emphasis>+filter{crude-parental}</emphasis>: Kill all web pages that contain the words "sex" or "warez"
3165 This is potentially a very powerful feature! And requires a knowledge
3166 of regular expressions if you want to <quote>roll your own</quote>.
3169 Filtering requires buffering the page content, which may appear to
3170 slow down page rendering since nothing is displayed until all content has
3171 passed the filters. (It does not really take longer, but seems that way
3172 since the page is not incrementally displayed.) This effect will be more
3173 noticeable on slower connections.
3182 <!-- ~~~~~ New section ~~~~~ -->
3183 <sect4 id="hide-forwarded">
3184 <title><emphasis>+hide-forwarded</emphasis></title>
3189 <!-- Boolean, Parameterized, Multi-value -->
3191 <para>Boolean.</para>
3196 <term>Typical uses:</term>
3199 Block any existing X-Forwarded-for HTTP header, and do not add a new one.
3205 <term>Possible values:</term>
3214 <term>Example usage:</term>
3217 <emphasis>{+hide-forwarded}</emphasis>
3218 <emphasis>.example.com</emphasis>
3227 It is fairly safe to leave this on. It does not seem to break many sites.
3236 <!-- ~~~~~ New section ~~~~~ -->
3237 <sect4 id="hide-from">
3238 <title><emphasis>+hide-from</emphasis></title>
3243 <!-- Boolean, Parameterized, Multi-value -->
3245 <para>Parameterized.</para>
3250 <term>Typical uses:</term>
3253 To block the browser from sending your email address in a <quote>From:</quote>
3260 <term>Possible values:</term>
3263 Keyword: <quote>block</quote>, or any user defined value.
3269 <term>Example usage:</term>
3272 <emphasis>{+hide-from{block}}</emphasis>
3273 <emphasis>.example.com</emphasis>
3282 The keyword <quote>block</quote> will completely remove the header.
3283 Alternately, you can specify any value you prefer to send to the web
3293 <!-- ~~~~~ New section ~~~~~ -->
3294 <sect4 id="hide-referer">
3295 <title><emphasis>+hide-referer</emphasis></title>
3296 <anchor id="hide-referrer">
3301 <!-- Boolean, Parameterized, Multi-value -->
3303 <para>Parameterized.</para>
3308 <term>Typical uses:</term>
3311 Don't send the <quote>Referer:</quote> (sic) HTTP header to the web site.
3312 Or, alternately send a forged header instead.
3318 <term>Possible values:</term>
3321 Prevent the header from being sent with the keyword, <quote>block</quote>.
3322 Or, <quote>forge</quote> a URL to one from the same server as the request.
3323 Or, set to user defined value of your choice.
3329 <term>Example usage:</term>
3332 <emphasis>{+hide-referer{forge}}</emphasis>
3333 <emphasis>.example.com</emphasis>
3342 <quote>forge</quote> is the preferred option here, since some servers will
3343 not send images back otherwise.
3346 <quote>+hide-referrer</quote> is an alternate spelling of
3347 <quote>+hide-referer</quote>. It has the exact same parameters, and can be freely
3348 mixed with, <quote>+hide-referer</quote>. (<quote>referrer</quote> is the
3349 correct English spelling, however the HTTP specification has a bug - it
3350 requires it to be spelled as <quote>referer</quote>.)
3359 <!-- ~~~~~ New section ~~~~~ -->
3360 <sect4 id="hide-user-agent">
3361 <title><emphasis>+hide-user-agent</emphasis></title>
3366 <!-- Boolean, Parameterized, Multi-value -->
3368 <para>Parameterized.</para>
3373 <term>Typical uses:</term>
3376 To change the <quote>User-Agent:</quote> header so web servers can't tell
3377 your browser type. Who's business is it anyway?
3383 <term>Possible values:</term>
3386 Any user defined string.
3392 <term>Example usage:</term>
3395 <emphasis>{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</emphasis>
3396 <emphasis>.msn.com</emphasis>
3405 Warning! This breaks many web sites that depend on this in order
3406 to determine how the target browser will respond to various
3407 requests. Use with caution.
3415 <!-- ~~~~~ New section ~~~~~ -->
3417 <title><emphasis>+image</emphasis></title>
3422 <!-- Boolean, Parameterized, Multi-value -->
3424 <para>Boolean.</para>
3429 <term>Typical uses:</term>
3432 To define what <application>Privoxy</application> should treat
3433 automatically as an image.
3439 <term>Possible values:</term>
3448 <term>Example usage:</term>
3451 <emphasis>{+image}</emphasis>
3452 <emphasis>/.*\.(gif|jpg|jpeg|png|bmp|ico)</emphasis>
3461 This only has meaning if the URL (or pattern) also is
3462 <quote>+block</quote>ed, in which case a <quote>blocked</quote> image can
3463 be sent rather than a HTML page. (See <quote>+image-blocker{}</quote> below
3464 for the control over what is actually sent.)
3467 There is little reason to change the default definition for this.
3476 <!-- ~~~~~ New section ~~~~~ -->
3477 <sect4 id="image-blocker">
3478 <title><emphasis>+image-blocker</emphasis></title>
3483 <!-- Boolean, Parameterized, Multi-value -->
3485 <para>Parameterized.</para>
3490 <term>Typical uses:</term>
3493 Decide what to do with URLs that end up tagged with both <quote>{+block}</quote>
3494 and <quote>{+image}</quote>, e.g an advertisement.
3500 <term>Possible values:</term>
3503 There are four available options: <quote>-image-blocker</quote> will send a HTML
3504 <quote>blocked</quote> page, usually resulting in a <quote>broken
3505 image</quote> icon. <quote>+image-blocker{blank}</quote> will send a 1x1
3506 transparent GIF image. <quote>+image-blocker{pattern}</quote> will send a
3507 checkerboard type pattern (the default). And finally,
3508 <quote>+image-blocker{http://xyz.com}</quote> will send a HTTP temporary
3509 redirect to the specified image. This has the advantage of the icon being
3510 being cached by the browser, which will speed up the display.
3516 <term>Example usage:</term>
3519 <emphasis>{+image-blocker{blank}}</emphasis>
3520 <emphasis>.example.com</emphasis>
3529 If you want <emphasis>invisible</emphasis> ads, they need to be both
3530 defined as <emphasis>images</emphasis> and <emphasis>blocked</emphasis>.
3531 And then, <quote>image-blocker</quote> should be set to
3532 <quote>blank</quote> for invisibility. Note you cannot treat HTML pages as
3533 images in most cases. For instance, frames require an HTML page to display.
3534 So a frame that is an ad, cannot be treated as an image. Forcing an
3535 <quote>image</quote> in this situation just will not work.
3543 <!-- ~~~~~ New section ~~~~~ -->
3544 <sect4 id="limit-connect">
3545 <title><emphasis>+limit-connect</emphasis></title>
3550 <!-- Boolean, Parameterized, Multi-value -->
3552 <para>Parameterized.</para>
3557 <term>Typical uses:</term>
3560 By default, <application>Privoxy</application> only allows HTTP CONNECT
3561 requests to port 443 (the standard, secure HTTPS port). Use
3562 <quote>+limit-connect</quote> to disable this altogether, or to allow
3569 <term>Possible values:</term>
3572 Any valid port number, or port number range.
3578 <term>Example usages:</term>
3580 <!-- I had trouble getting the spacing to look right in my browser -->
3581 <!-- I probably have the wrong font setup, bollocks. -->
3583 <emphasis>+limit-connect{443}</emphasis> # This is the default and need not be specified.
3584 <emphasis>+limit-connect{80,443}</emphasis> # Ports 80 and 443 are OK.
3585 <emphasis>+limit-connect{-3, 7, 20-100, 500-}</emphasis> # Port less than 3, 7, 20 to 100 and above 500 are OK.
3594 The CONNECT methods exists in HTTP to allow access to secure websites
3595 (https:// URLs) through proxies. It works very simply: the proxy connects
3596 to the server on the specified port, and then short-circuits its
3597 connections to the client <emphasis>and</emphasis> to the remote proxy.
3598 This can be a big security hole, since CONNECT-enabled proxies can be
3599 abused as TCP relays very easily.
3602 If you want to allow CONNECT for more ports than this, or want to forbid
3603 CONNECT altogether, you can specify a comma separated list of ports and
3604 port ranges (the latter using dashes, with the minimum defaulting to 0 and
3608 If you don't know what any of this means, there probably is no reason to
3617 <!-- ~~~~~ New section ~~~~~ -->
3618 <sect4 id="no-compression">
3619 <title><emphasis>+no-compression</emphasis></title>
3624 <!-- Boolean, Parameterized, Multi-value -->
3626 <para>Boolean.</para>
3631 <term>Typical uses:</term>
3634 Prevent the specified websites from compressing HTTP data.
3640 <term>Possible values:</term>
3649 <term>Example usage:</term>
3652 <emphasis>{+no-compression}</emphasis>
3653 <emphasis>.example.com</emphasis>
3662 Some websites do this, which can be a problem for
3663 <application>Privoxy</application>, since <quote>+filter</quote>,
3664 <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work
3665 on compressed data. This will slow down connections to those websites,
3666 though. Default typically is to turn <quote>no-compression</quote> on.
3674 <!-- ~~~~~ New section ~~~~~ -->
3675 <sect4 id="no-cookies-keep">
3676 <title><emphasis>+no-cookies-keep</emphasis></title>
3681 <!-- Boolean, Parameterized, Multi-value -->
3683 <para>Boolean.</para>
3688 <term>Typical uses:</term>
3691 Allow cookies for the current browser session only.
3697 <term>Possible values:</term>
3706 <term>Example usage:</term>
3709 <emphasis>{+no-cookies-keep}</emphasis>
3710 <emphasis>.example.com</emphasis>
3719 If websites set cookies, <quote>no-cookies-keep</quote> will make sure
3720 they are erased when you exit and restart your web browser. This makes
3721 profiling cookies useless, but won't break sites which require cookies so
3722 that you can log in for transactions. This is generally turned on for all
3723 sites. Sometimes referred to as <quote>session cookies</quote>.
3732 <!-- ~~~~~ New section ~~~~~ -->
3733 <sect4 id="no-cookies-read">
3734 <title><emphasis>+no-cookies-read</emphasis></title>
3739 <!-- Boolean, Parameterized, Multi-value -->
3741 <para>Boolean.</para>
3746 <term>Typical uses:</term>
3749 Explicitly prevent the web server from reading any cookies on your
3756 <term>Possible values:</term>
3765 <term>Example usage:</term>
3768 <emphasis>{+no-cookies-read}</emphasis>
3769 <emphasis>.example.com</emphasis>
3778 Often used in conjunction with <quote>+no-cookies-set</quote> to
3779 disable persistant cookies completely.
3788 <!-- ~~~~~ New section ~~~~~ -->
3789 <sect4 id="no-cookies-set">
3790 <title><emphasis>+no-cookies-set</emphasis></title>
3795 <!-- Boolean, Parameterized, Multi-value -->
3797 <para>Boolean.</para>
3802 <term>Typical uses:</term>
3805 Explicitly block the web server from sending cookies to your
3812 <term>Possible values:</term>
3821 <term>Example usage:</term>
3824 <emphasis>{+no-cookies-set}</emphasis>
3825 <emphasis>.example.com</emphasis>
3834 Often used in conjunction with <quote>+no-cookies-read</quote> to
3835 disable persistant cookies completely.
3844 <!-- ~~~~~ New section ~~~~~ -->
3845 <sect4 id="no-popup">
3846 <title><emphasis>+no-popup</emphasis></title>
3847 <anchor id="no-popups">
3852 <!-- Boolean, Parameterized, Multi-value -->
3854 <para>Boolean.</para>
3859 <term>Typical uses:</term>
3862 Stop those annoying JavaScript pop-up windows!
3868 <term>Possible values:</term>
3877 <term>Example usage:</term>
3880 <emphasis>{+no-popup}</emphasis>
3881 <emphasis>.example.com</emphasis>
3890 <quote>+no-popup</quote> uses a built in filter to disable pop-ups
3891 that use the <literal>window.open()</literal> function, etc.
3894 An alternate spelling is <quote>+no-popups</quote>, which is
3904 <!-- ~~~~~ New section ~~~~~ -->
3905 <sect4 id="vanilla-wafer">
3906 <title><emphasis>+vanilla-wafer</emphasis></title>
3911 <!-- Boolean, Parameterized, Multi-value -->
3913 <para>Boolean.</para>
3918 <term>Typical uses:</term>
3921 Sends a cookie for every site stating that you do not accept any copyright
3922 on cookies sent to you, and asking them not to track you.
3928 <term>Possible values:</term>
3937 <term>Example usage:</term>
3940 <emphasis>{+vanilla-wafer}</emphasis>
3941 <emphasis>.example.com</emphasis>
3950 This action only applies if you are using a <filename>jarfile</filename>
3951 for saving cookies. Of course, this is a (relatively) unique header and
3952 could be used to track you.
3961 <!-- ~~~~~ New section ~~~~~ -->
3963 <title><emphasis>+wafer</emphasis></title>
3968 <!-- Boolean, Parameterized, Multi-value -->
3970 <para>Multi-value.</para>
3975 <term>Typical uses:</term>
3978 This allows you to send an arbitrary, user definable cookie.
3984 <term>Possible values:</term>
3987 User specified cookie name and corresponding value.
3993 <term>Example usage:</term>
3996 <emphasis>{+wafer{name=value}}</emphasis>
3997 <emphasis>.example.com</emphasis>
4006 This can be specified multiple times in order to add as many cookies as you
4016 <!-- ~~~~~ New section ~~~~~ -->
4017 <sect4 id="act-examples" renderas="sect3">
4018 <title>Actions Examples</title>
4020 Note that the meaning of any of the above examples is reversed by preceding
4021 the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also,
4022 that some actions are turned on in the default section of the actions file,
4023 and require little to no additional configuration. These are just <quote>on</quote>.
4024 Some actions that are turned on the default section do typically require
4025 exceptions to be listed in the lower sections of actions file.
4033 Turn off cookies by default, then allow a few through for specified sites:
4040 # Turn off all persistent cookies
4041 { +no-cookies-read }
4044 # Allow cookies for this browser session ONLY
4045 { +no-cookies-keep }
4047 # Exceptions to the above, sites that benefit from persistent cookies
4048 # that saved from one browser session to the next.
4049 { -no-cookies-read }
4051 { -no-cookies-keep }
4058 # Alternative way of saying the same thing
4059 {-no-cookies-set -no-cookies-read -no-cookies-keep}
4068 Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
4078 # Reverse it for these two sites, which don't work right without it.
4080 www.ukc.ac.uk/cgi-bin/wac\.cgi\?
4088 Turn on page filtering according to rules in the defined sections
4089 of <filename>default.filter</filename>, and make one exception for
4097 # Run everything through the filter file, using only the
4098 # specified sections:
4099 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
4100 +filter{webbugs} +filter{nimda} +filter{banners-by-size}
4102 # Then disable filtering of code from sourceforge!
4104 .cvs.sourceforge.net
4111 Now some URLs that we want <quote>blocked</quote> (normally generates
4112 the <quote>blocked</quote> banner). Many of these use
4113 <link linkend="regex">regular expressions</link> that will expand to match
4114 multiple URLs: </para>
4122 /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
4123 /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
4124 /.*/(ng)?adclient\.cgi
4125 /.*/(plain|live|rotate)[-_.]?ads?/
4126 /.*/(sponsor)s?[0-9]?/
4127 /.*/_?(plain|live)?ads?(-banners)?/
4129 /.*/ad(sdna_image|gifs?)/
4130 /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
4134 /.*/adv((er)?ts?|ertis(ing|ements?))?/
4138 /.*/cgi-bin/centralad/getimage
4139 /.*/images/addver\.gif
4140 /.*/images/marketing/.*\.(gif|jpe?g)
4144 /.*/sponsors?[0-9]?/
4145 /.*/advert[0-9]+\.jpg
4152 /graphics/defaultAd/
4154 /image\.ng/transactionID
4155 /images/.*/.*_anim\.gif # alvin brattli
4156 /ip_img/.*\.(gif|jpe?g)
4160 /cgi-bin/nph-adclick.exe/
4161 /.*/Image/BannerAdvertising/
4163 /.*/adlib/server\.cgi
4171 Note that many of these actions have the potential to cause a page to
4172 misbehave, possibly even not to display at all. There are many ways
4173 a site designer may choose to design his site, and what HTTP header
4174 content he may depend on. There is no way to have hard and fast rules
4175 for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
4176 for a brief example on troubleshooting actions.
4182 <!-- ~ End section ~ -->
4185 <!-- ~~~~~ New section ~~~~~ -->
4187 <title>Aliases</title>
4189 Custom <quote>actions</quote>, known to <application>Privoxy</application>
4190 as <quote>aliases</quote>, can be defined by combining other <quote>actions</quote>.
4191 These can in turn be invoked just like the built-in <quote>actions</quote>.
4192 Currently, an alias can contain any character except space, tab, <quote>=</quote>,
4193 <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
4194 <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
4195 <quote>-</quote>. Alias names are not case sensitive, and
4196 <emphasis>must be defined before anything</emphasis> else in the
4197 <filename>default.action</filename>file! And there can only be one set of
4198 <quote>aliases</quote> defined.
4202 Now let's define a few aliases:
4209 # Useful custom aliases we can use later. These must come first!
4211 +no-cookies = +no-cookies-set +no-cookies-read
4212 -no-cookies = -no-cookies-set -no-cookies-read
4213 fragile = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
4214 shop = -no-cookies -filter -fast-redirects
4215 +imageblock = +block +image
4217 #For people who don't like to type too much: ;-)
4220 c2 = -no-cookies-set +no-cookies-read
4221 c3 = +no-cookies-set -no-cookies-read
4222 #... etc. Customize to your heart's content.
4229 Some examples using our <quote>shop</quote> and <quote>fragile</quote>
4237 # These sites are very complex and require
4238 # minimal interference.
4240 .office.microsoft.com
4241 .windowsupdate.microsoft.com
4244 # Shopping sites - but we still want to block ads.
4247 .worldpay.com # for quietpc.com
4251 # These shops require pop-ups also
4261 The <quote>shop</quote> and <quote>fragile</quote> aliases are often used for
4262 <quote>problem</quote> sites that require most actions to be disabled
4263 in order to function properly.
4270 <!-- ~ End section ~ -->
4273 <!-- ~~~~~ New section ~~~~~ -->
4274 <sect2 id="filterfile">
4275 <title>The Filter File</title>
4277 Any web page can be dynamically modified with the filter file. This
4278 modification can be removal, or re-writing, of any web page content,
4279 including tags and non-visible content. The default filter file is
4280 <filename>default.filter</filename>, located in the config directory.
4284 This is potentially a very powerful feature, and requires knowledge of both
4285 <quote>regular expression</quote> and HTML in order create custom
4286 filters. But, there are a number of useful filters included with
4287 <application>Privoxy</application> for many common situations.
4291 The included example file is divided into sections. Each section begins
4292 with the <literal>FILTER</literal> keyword, followed by the identifier
4293 for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
4294 a similar type of filtering, such as <quote>html-annoyances</quote>.
4298 This file uses regular expressions to alter or remove any string in the
4299 target page. The expressions can only operate on one line at a time. Some
4300 examples from the included default <filename>default.filter</filename>:
4304 Stop web pages from displaying annoying messages in the status bar by
4305 deleting such references:
4312 FILTER: html-annoyances
4314 # New browser windows should be resizeable and have a location and status
4317 s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
4318 s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
4319 s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
4320 s/menubar="?(no|0)"?/menubar=1/ig
4322 # The <BLINK> tag was a crime!
4324 s*<blink>|</blink>**ig
4328 #s/framespacing="?(no|0)"?//ig
4329 #s/margin(height|width)=[0-9]*//gi
4336 Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
4337 <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
4346 s/microsoft(?!.com)/MicroSuck/ig
4350 s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
4357 Kill those pesky little web-bugs:
4364 # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
4367 s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
4375 <!-- ~ End section ~ -->
4379 <!-- ~~~~~ New section ~~~~~ -->
4382 <title>Templates</title>
4384 When <application>Privoxy</application> displays one of its internal
4385 pages, such as a 404 Not Found error page, it uses the appropriate template.
4386 On Linux, BSD, and Unix, these are located in
4387 <filename>/etc/privoxy/templates</filename> by default. These may be
4388 customized, if desired. <filename>cgi-style.css</filename> is
4389 used to control the HTML attributes (fonts, etc).
4392 The default <quote>Blocked</quote> banner page with the bright red top
4393 banner, is called just <quote><filename>blocked</filename></quote>. This
4394 may be customized or replaced with something else if desired.
4401 <!-- ~ End section ~ -->
4405 <!-- ~~~~~ New section ~~~~~ -->
4407 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
4410 <!-- Include contacting.sgml boilerplate: -->
4412 <!-- end boilerplate -->
4415 <!-- ~~~~~ New section ~~~~~ -->
4416 <sect2 id="submitactions">
4417 <title>Submitting Ads and <quote>Action</quote> Problems</title>
4419 Ads and banners that are not stopped by <application>Privoxy</application>
4420 can be submitted to the developers by accessing a special page and filling
4421 out the brief, required form. Conversely, you can also report pages, images,
4422 etc. that <application>Privoxy</application> is blocking, but should not.
4423 The form itself does require Internet access.
4426 To do this, point your browser to <application>Privoxy</application>
4427 at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4428 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
4429 <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>,
4430 near the bottom of the page. Paste in the URL that is the cause of the
4431 unwanted behavior, and follow the prompts. The developers will
4432 try to incorporate a fix for the problem you reported into future versions.
4436 New <filename>default.actions</filename> files will occasionally be made
4437 available based on your feedback. These
4438 will be announced on the
4440 url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink>
4448 <!-- ~~~~~ New section ~~~~~ -->
4449 <sect1 id="copyright"><title>Copyright and History</title>
4451 <sect2><title>Copyright</title>
4452 <!-- Include copyright.sgml: -->
4454 <!-- end copyright -->
4457 <!-- ~ End section ~ -->
4460 <!-- ~~~~~ New section ~~~~~ -->
4462 <sect2 id="history"><title>History</title>
4463 <!-- Include history.sgml: -->
4465 <!-- end history -->
4469 <!-- ~~~~~ New section ~~~~~ -->
4470 <sect1 id="seealso"><title>See Also</title>
4471 <!-- Include seealso.sgml: -->
4473 <!-- end seealso -->
4478 <!-- ~~~~~ New section ~~~~~ -->
4479 <sect1 id="appendix"><title>Appendix</title>
4482 <!-- ~~~~~ New section ~~~~~ -->
4484 <title>Regular Expressions</title>
4486 <application>Privoxy</application> can use <quote>regular expressions</quote>
4487 in various config files. Assuming support for <quote>pcre</quote> (Perl
4488 Compatible Regular Expressions) is compiled in, which is the default. Such
4489 configuration directives do not require regular expressions, but they can be
4490 used to increase flexibility by matching a pattern with wild-cards against
4495 If you are reading this, you probably don't understand what <quote>regular
4496 expressions</quote> are, or what they can do. So this will be a very brief
4497 introduction only. A full explanation would require a book ;-)
4501 <quote>Regular expressions</quote> is a way of matching one character
4502 expression against another to see if it matches or not. One of the
4503 <quote>expressions</quote> is a literal string of readable characters
4504 (letter, numbers, etc), and the other is a complex string of literal
4505 characters combined with wild-cards, and other special characters, called
4506 meta-characters. The <quote>meta-characters</quote> have special meanings and
4507 are used to build the complex pattern to be matched against. Perl Compatible
4508 Regular Expressions is an enhanced form of the regular expression language
4509 with backward compatibility.
4513 To make a simple analogy, we do something similar when we use wild-card
4514 characters when listing files with the <command>dir</command> command in DOS.
4515 <literal>*.*</literal> matches all filenames. The <quote>special</quote>
4516 character here is the asterisk which matches any and all characters. We can be
4517 more specific and use <literal>?</literal> to match just individual
4518 characters. So <quote>dir file?.text</quote> would match
4519 <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
4520 matching, using a similar technique to <quote>regular expressions</quote>!
4524 Regular expressions do essentially the same thing, but are much, much more
4525 powerful. There are many more <quote>special characters</quote> and ways of
4526 building complex patterns however. Let's look at a few of the common ones,
4527 and then some examples:
4532 <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
4533 <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
4535 </simplelist></para>
4539 <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
4542 </simplelist></para>
4546 <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
4549 </simplelist></para>
4553 <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
4556 </simplelist></para>
4560 <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
4561 the following character should be taken literally. This is used where one of the
4562 special characters (e.g. <quote>.</quote>) needs to be taken literally and
4563 not as a special meta-character. Example: <quote>example\.com</quote>, makes
4564 sure the period is recognized only as a period (and not expanded to its
4565 metacharacter meaning of any single character).
4567 </simplelist></para>
4571 <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
4572 any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
4573 matches any numeric digit (zero through nine). As an example, we can combine
4574 this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
4576 </simplelist></para>
4580 <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
4581 or multiple sub-expressions.
4583 </simplelist></para>
4587 <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
4588 <quote>or</quote> conditional statement. A match is successful if the
4589 sub-expression on either side of <quote>|</quote> matches. As an example:
4590 <quote>/(this|that) example/</quote> uses grouping and the bar character
4591 and would match either <quote>this example</quote> or <quote>that
4592 example</quote>, and nothing else.
4594 </simplelist></para>
4598 <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
4599 <quote>string1</quote> is replaced by <quote>string2</quote> in this
4600 example. There must of course be a match on <quote>string1</quote> first.
4602 </simplelist></para>
4605 These are just some of the ones you are likely to use when matching URLs with
4606 <application>Privoxy</application>, and is a long way from a definitive
4607 list. This is enough to get us started with a few simple examples which may
4608 be more illuminating:
4612 <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
4613 that uses the common combination of <quote>.</quote> and <quote>*</quote> to
4614 denote any character, zero or more times. In other words, any string at all.
4615 So we start with a literal forward slash, then our regular expression pattern
4616 (<quote>.*</quote>) another literal forward slash, the string
4617 <quote>banners</quote>, another forward slash, and lastly another
4618 <quote>.*</quote>. We are building
4619 a directory path here. This will match any file with the path that has a
4620 directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
4621 any characters, and this could conceivably be more forward slashes, so it
4622 might expand into a much longer looking path. For example, this could match:
4623 <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
4624 <quote>/banners/annoying.html</quote>, or almost an infinite number of other
4625 possible combinations, just so it has <quote>banners</quote> in the path
4630 A now something a little more complex:
4634 <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
4635 We have several literal forward slashes again (<quote>/</quote>), so we are
4636 building another expression that is a file path statement. We have another
4637 <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
4638 it matches our expression. The only true literal that <emphasis>must
4639 match</emphasis> our pattern is <application>adv</application>, together with
4640 the forward slashes. What comes after the <quote>adv</quote> string is the
4645 Remember the <quote>?</quote> means the preceding expression (either a
4646 literal character or anything grouped with <quote>(...)</quote> in this case)
4647 can exist or not, since this means either zero or one match. So
4648 <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
4649 individual sub-expressions: <quote>(er)</quote>,
4650 <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
4651 means <quote>or</quote>. We have two of those. For instance,
4652 <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
4653 <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
4654 attempt at matching as many variations of <quote>advertisement</quote>, and
4655 similar, as possible. So this would expand to match just <quote>adv</quote>,
4656 or <quote>advert</quote>, or <quote>adverts</quote>, or
4657 <quote>advertising</quote>, or <quote>advertisement</quote>, or
4658 <quote>advertisements</quote>. You get the idea. But it would not match
4659 <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
4660 changing our regular expression to:
4661 <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
4666 <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
4667 another path statement with forward slashes. Anything in the square brackets
4668 <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
4669 shorthand expression to mean any digit one through nine. It is the same as
4670 saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
4671 means one or more of the preceding expression must be included. The preceding
4672 expression here is what is in the square brackets -- in this case, any digit
4673 one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
4674 This includes a <quote>|</quote>, so this needs to match the expression on
4675 either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
4676 side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
4677 since the <quote>?</quote> means the letter <quote>e</quote> is optional and
4678 can be matched once or not at all. So we are building an expression here to
4679 match image GIF or JPEG type image file. It must include the literal
4680 string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
4681 (which is now a literal, and not a special character, since it is escaped
4682 with <quote>\</quote>), and lastly either <quote>gif</quote>, or
4683 <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
4684 include: <quote>//advert1.jpg</quote>,
4685 <quote>/nasty/ads/advert1234.gif</quote>,
4686 <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
4687 <quote>advert1.gif</quote> (no leading slash), or
4688 <quote>/adverts232.jpg</quote> (the expression does not include an
4689 <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
4690 in the expression anywhere).
4694 <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
4695 a substitution. <quote>MicroSuck</quote> will replace any occurrence of
4696 <quote>microsoft</quote>. The <quote>i</quote> at the end of the expression
4697 means ignore case. The <quote>(?!.com)</quote> means
4698 the match should fail if <quote>microsoft</quote> is followed by
4699 <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
4700 modifier. In case this is a hyperlink, we don't want to break it ;-).
4704 We are barely scratching the surface of regular expressions here so that you
4705 can understand the default <application>Privoxy</application>
4706 configuration files, and maybe use this knowledge to customize your own
4707 installation. There is much, much more that can be done with regular
4708 expressions. Now that you know enough to get started, you can learn more on
4713 More reading on Perl Compatible Regular expressions:
4714 <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
4719 <!-- ~ End section ~ -->
4722 <!-- ~~~~~ New section ~~~~~ -->
4724 <title><application>Privoxy</application>'s Internal Pages</title>
4727 Since <application>Privoxy</application> proxies each requested
4728 web page, it is easy for <application>Privoxy</application> to
4729 trap certain special URLs. In this way, we can talk directly to
4730 <application>Privoxy</application>, and see how it is
4731 configured, see how our rules are being applied, change these
4732 rules and other configuration options, and even turn
4733 <application>Privoxy's</application> filtering off, all with
4739 The URLs listed below are the special ones that allow direct access
4740 to <application>Privoxy</application>. Of course,
4741 <application>Privoxy</application> must be running to access these. If
4742 not, you will get a friendly error message. Internet access is not
4755 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4759 Alternately, this may be reached at <ulink
4760 url="http://p.p/">http://p.p/</ulink>, but this
4761 variation may not work as reliably as the above in some configurations.
4767 Show information about the current configuration:
4771 <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
4778 Show the source code version numbers:
4782 <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
4789 Show the client's request headers:
4793 <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
4800 Show which actions apply to a URL and why:
4804 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
4811 Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
4812 to run, but only as a pass-through proxy, with no actions taking place:
4816 <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
4820 Short cuts. Turn off, then on:
4824 <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
4829 <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
4836 Edit the actions list file:
4840 <ulink url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>
4849 These may be bookmarked for quick reference. See next.
4853 <sect3 id="bookmarklets">
4854 <title>Bookmarklets</title>
4856 Below are some <quote>bookmarklets</quote> to allow you to easily access a
4857 <quote>mini</quote> version of some of <application>Privoxy's</application>
4858 special pages. They are designed for MS Internet Explorer, but should work
4859 equally well in Netscape, Mozilla, and other browsers which support
4860 JavaScript. They are designed to run directly from your bookmarks - not by
4861 clicking the links below (although that should work for testing).
4864 To save them, right-click the link and choose <quote>Add to Favorites</quote>
4865 (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
4866 the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
4867 Bookmarklet directly from your favorites/bookmarks. For even faster access,
4868 you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
4869 Toolbar</quote> (Netscape), and run them with a single click.
4877 <ulink 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());">Enable Privoxy</ulink>
4883 <ulink 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());">Disable Privoxy</ulink>
4889 <ulink 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());">Toggle Privoxy</ulink> (Toggles between enabled and disabled)
4895 <ulink 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());">View Privoxy Status</ulink>
4901 <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>
4911 Credit: The site which gave me the general idea for these bookmarklets is
4912 <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
4913 have more information about bookmarklets.
4922 <!-- ~~~~~ New section ~~~~~ -->
4923 <sect2 id="actionsanat">
4924 <title>Anatomy of an Action</title>
4927 The way <application>Privoxy</application> applies <quote>actions</quote>
4928 and <quote>filters</quote> to any given URL can be complex, and not always so
4929 easy to understand what is happening. And sometimes we need to be able to
4930 <emphasis>see</emphasis> just what <application>Privoxy</application> is
4931 doing. Especially, if something <application>Privoxy</application> is doing
4932 is causing us a problem inadvertently. It can be a little daunting to look at
4933 the actions and filters files themselves, since they tend to be filled with
4934 <quote>regular expressions</quote> whose consequences are not always
4939 One quick test to see if <application>Privoxy</application> is causing a problem
4940 or not, is to disable it temporarily. This should be the first troubleshooting
4941 step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
4942 and easy way to do this (be sure to flush caches afterwards!).
4946 <application>Privoxy</application> also provides the
4947 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
4948 page that can show us very specifically how <application>actions</application>
4949 are being applied to any given URL. This is a big help for troubleshooting.
4953 First, enter one URL (or partial URL) at the prompt, and then
4954 <application>Privoxy</application> will tell us
4955 how the current configuration will handle it. This will not
4956 help with filtering effects from the <filename>default.filter</filename> file! It
4957 also will not tell you about any other URLs that may be embedded within the
4958 URL you are testing (i.e. a web page). For instance, images such as ads are expressed as URLs
4959 within the raw page source of HTML pages. So you will only get info for the
4960 actual URL that is pasted into the prompt area -- not any sub-URLs. If you
4961 want to know about embedded URLs like ads, you will have to dig those out of
4962 the HTML source. Use your browser's <quote>View Page Source</quote> option
4963 for this. Or right click on the ad, and grab the URL.
4967 Let's look at an example, <ulink url="http://google.com">google.com</ulink>,
4968 one section at a time:
4973 System default actions:
4975 { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter
4976 -hide-forwarded -hide-from -hide-referer -hide-user-agent -image
4977 -image-blocker -limit-connect -no-compression -no-cookies-keep
4978 -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer }
4984 This is the top section, and only tells us of the compiled in defaults. This
4985 is basically what <application>Privoxy</application> would do if there
4986 were not any <quote>actions</quote> defined, i.e. it does nothing. Every action
4987 is disabled. This is not particularly informative for our purposes here. OK,
4994 Matches for http://google.com:
4996 { -add-header -block +deanimate-gifs -downgrade +fast-redirects
4997 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
4998 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
4999 +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
5000 -hide-user-agent -image +image-blocker{blank} +no-compression
5001 +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
5002 -vanilla-wafer -wafer }
5005 { -no-cookies-keep -no-cookies-read -no-cookies-set }
5015 This is much more informative, and tells us how we have defined our
5016 <quote>actions</quote>, and which ones match for our example,
5017 <quote>google.com</quote>. The first grouping shows our default
5018 settings, which would apply to all URLs. If you look at your <quote>actions</quote>
5019 file, this would be the section just below the <quote>aliases</quote> section
5020 near the top. This applies to all URLs as signified by the single forward
5021 slash -- <quote>/</quote>.
5026 These are the default actions we have enabled. But we can define additional
5027 actions that would be exceptions to these general rules, and then list
5028 specific URLs that these exceptions would apply to. Last match wins.
5029 Just below this then are two explicit matches for <quote>.google.com</quote>.
5030 The first is negating our various cookie blocking actions (i.e. we will allow
5031 cookies here). The second is allowing <quote>fast-redirects</quote>. Note
5032 that there is a leading dot here -- <quote>.google.com</quote>. This will
5033 match any hosts and sub-domains, in the google.com domain also, such as
5034 <quote>www.google.com</quote>. So, apparently, we have these actions defined
5035 somewhere in the lower part of our actions file, and
5036 <quote>google.com</quote> is referenced in these sections.
5041 And now we pull it altogether in the bottom section and summarize how
5042 <application>Privoxy</application> is applying all its <quote>actions</quote>
5043 to <quote>google.com</quote>:
5052 -add-header -block -deanimate-gifs -downgrade -fast-redirects
5053 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
5054 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
5055 +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
5056 -hide-user-agent -image +image-blocker{blank} -limit-connect +no-compression
5057 -no-cookies-keep -no-cookies-read -no-cookies-set +no-popups -vanilla-wafer
5064 Now another example, <quote>ad.doubleclick.net</quote>:
5083 We'll just show the interesting part here, the explicit matches. It is
5084 matched three different times. Each as an <quote>+block +image</quote>,
5085 which is the expanded form of one of our aliases that had been defined as:
5086 <quote>+imageblock</quote>. (<quote>Aliases</quote> are defined in the
5087 first section of the actions file and typically used to combine more
5092 Any one of these would have done the trick and blocked this as an unwanted
5093 image. This is unnecessarily redundant since the last case effectively
5094 would also cover the first. No point in taking chances with these guys
5095 though ;-) Note that if you want an ad or obnoxious
5096 URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
5097 is done here -- as both a <quote>+block</quote> <emphasis>and</emphasis> an
5098 <quote>+image</quote>. The custom alias <quote>+imageblock</quote> does this
5103 One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
5104 This one is giving us problems. We are getting a blank page. Hmmm...
5110 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
5112 { -add-header -block +deanimate-gifs -downgrade +fast-redirects
5113 +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
5114 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
5115 +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge}
5116 -hide-user-agent -image +image-blocker{blank} +no-compression
5117 +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups
5118 -vanilla-wafer -wafer }
5128 Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
5129 we did not want this at all! Now we see why we get the blank page. We could
5130 now add a new action below this that explicitly does <emphasis>not</emphasis>
5131 block (-block) pages with <quote>adsl</quote>. There are various ways to
5132 handle such exceptions. Example:
5145 Now the page displays ;-) Be sure to flush your browser's caches when
5146 making such changes. Or, try using <literal>Shift+Reload</literal>.
5150 But now what about a situation where we get no explicit matches like
5164 That actually was very telling and pointed us quickly to where the problem
5165 was. If you don't get this kind of match, then it means one of the default
5166 rules in the first section is causing the problem. This would require some
5167 guesswork, and maybe a little trial and error to isolate the offending rule.
5168 One likely cause would be one of the <quote>{+filter}</quote> actions. Try
5169 adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
5177 .worldpay.com # for quietpc.com
5186 <quote>{shop}</quote> is an <quote>alias</quote> that expands to
5187 <quote>{ -filter -no-cookies -no-cookies-keep }</quote>. Or you could do
5188 your own exception to negate filtering:
5202 <quote>{fragile}</quote> is an alias that disables most actions. This can be
5203 used as a last resort for problem sites. Remember to flush caches! If this
5204 still does not work, you will have to go through the remaining actions one by
5205 one to find which one(s) is causing the problem.
5214 This program is free software; you can redistribute it
5215 and/or modify it under the terms of the GNU General
5216 Public License as published by the Free Software
5217 Foundation; either version 2 of the License, or (at
5218 your option) any later version.
5220 This program is distributed in the hope that it will
5221 be useful, but WITHOUT ANY WARRANTY; without even the
5222 implied warranty of MERCHANTABILITY or FITNESS FOR A
5223 PARTICULAR PURPOSE. See the GNU General Public
5224 License for more details.
5226 The GNU General Public License should be included with
5227 this file. If not, you can view it at
5228 http://www.gnu.org/copyleft/gpl.html
5229 or write to the Free Software Foundation, Inc., 59
5230 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
5232 $Log: user-manual.sgml,v $
5233 Revision 1.88 2002/04/23 05:37:54 hal9
5234 Add AmigaOS install stuff.
5236 Revision 1.87 2002/04/23 02:53:15 david__schmidt
5237 Updated OSX installation section
5238 Added a few English tweaks here an there
5240 Revision 1.86 2002/04/21 01:46:32 hal9
5241 Re-write actions section.
5243 Revision 1.85 2002/04/18 21:23:23 hal9
5244 Fix ugly typo (mine).
5246 Revision 1.84 2002/04/18 21:17:13 hal9
5247 Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
5249 Revision 1.83 2002/04/18 18:21:12 oes
5250 Added RPM install detail
5252 Revision 1.82 2002/04/18 12:04:50 oes
5255 Revision 1.81 2002/04/18 11:50:24 oes
5256 Extended Install section - needs fixing by packagers
5258 Revision 1.80 2002/04/18 10:45:19 oes
5259 Moved text to buildsource.sgml, renamed some filters, details
5261 Revision 1.79 2002/04/18 03:18:06 hal9
5262 Spellcheck, and minor touchups.
5264 Revision 1.78 2002/04/17 18:04:16 oes
5267 Revision 1.77 2002/04/17 13:51:23 oes
5268 Proofreading, part one
5270 Revision 1.76 2002/04/16 04:25:51 hal9
5271 -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
5272 -Note about proxy may need requests to re-read config files.
5274 Revision 1.75 2002/04/12 02:08:48 david__schmidt
5275 Remove OS/2 building info... it is already in the developer-manual
5277 Revision 1.74 2002/04/11 00:54:38 hal9
5278 Add small section on submitting actions.
5280 Revision 1.73 2002/04/10 18:45:15 swa
5283 Revision 1.72 2002/04/10 04:06:19 hal9
5284 Added actions feedback to Bookmarklets section
5286 Revision 1.71 2002/04/08 22:59:26 hal9
5287 Version update. Spell chkconfig correctly :)
5289 Revision 1.70 2002/04/08 20:53:56 swa
5292 Revision 1.69 2002/04/06 05:07:29 hal9
5293 -Add privoxy-man-page.sgml, for man page.
5294 -Add authors.sgml for AUTHORS (and p-authors.sgml)
5295 -Reworked various aspects of various docs.
5296 -Added additional comments to sub-docs.
5298 Revision 1.68 2002/04/04 18:46:47 swa
5299 consistent look. reuse of copyright, history et. al.
5301 Revision 1.67 2002/04/04 17:27:57 swa
5302 more single file to be included at multiple points. make maintaining easier
5304 Revision 1.66 2002/04/04 06:48:37 hal9
5305 Structural changes to allow for conditional inclusion/exclusion of content
5306 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
5307 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
5308 eventually be set by Makefile.
5309 More boilerplate text for use across multiple docs.
5311 Revision 1.65 2002/04/03 19:52:07 swa
5312 enhance squid section due to user suggestion
5314 Revision 1.64 2002/04/03 03:53:43 hal9
5315 A few minor bug fixes, and touch ups. Ready for review.
5317 Revision 1.63 2002/04/01 16:24:49 hal9
5318 Define entities to include boilerplate text. See doc/source/*.
5320 Revision 1.62 2002/03/30 04:15:53 hal9
5321 - Fix privoxy.org/config links.
5322 - Paste in Bookmarklets from Toggle page.
5323 - Move Quickstart nearer top, and minor rework.
5325 Revision 1.61 2002/03/29 01:31:08 hal9
5328 Revision 1.60 2002/03/27 01:57:34 hal9
5329 Added more to Anatomy section.
5331 Revision 1.59 2002/03/27 00:54:33 hal9
5332 Touch up intro for new name.
5334 Revision 1.58 2002/03/26 22:29:55 swa
5335 we have a new homepage!
5337 Revision 1.57 2002/03/24 20:33:30 hal9
5338 A few minor catch ups with name change.
5340 Revision 1.56 2002/03/24 16:17:06 swa
5341 configure needs to be generated.
5343 Revision 1.55 2002/03/24 16:08:08 swa
5344 we are too lazy to make a block-built
5345 privoxy logo. hence removed the option.
5347 Revision 1.54 2002/03/24 15:46:20 swa
5348 name change related issue.
5350 Revision 1.53 2002/03/24 11:51:00 swa
5351 name change. changed filenames.
5353 Revision 1.52 2002/03/24 11:01:06 swa
5356 Revision 1.51 2002/03/23 15:13:11 swa
5357 renamed every reference to the old name with foobar.
5358 fixed "application foobar application" tag, fixed
5359 "the foobar" with "foobar". left junkbustser in cvs
5360 comments and remarks to history untouched.
5362 Revision 1.50 2002/03/23 05:06:21 hal9
5365 Revision 1.49 2002/03/21 17:01:05 hal9
5366 New section in Appendix.
5368 Revision 1.48 2002/03/12 06:33:01 hal9
5369 Catching up to Andreas and re_filterfile changes.
5371 Revision 1.47 2002/03/11 13:13:27 swa
5372 correct feedback channels
5374 Revision 1.46 2002/03/10 00:51:08 hal9
5375 Added section on JB internal pages in Appendix.
5377 Revision 1.45 2002/03/09 17:43:53 swa
5380 Revision 1.44 2002/03/09 17:08:48 hal9
5381 New section on Jon's actions file editor, and move some stuff around.
5383 Revision 1.43 2002/03/08 00:47:32 hal9
5384 Added imageblock{pattern}.
5386 Revision 1.42 2002/03/07 18:16:55 swa
5389 Revision 1.41 2002/03/07 16:46:43 hal9
5390 Fix a few markup problems for jade.
5392 Revision 1.40 2002/03/07 16:28:39 swa
5393 provide correct feedback channels
5395 Revision 1.39 2002/03/06 16:19:28 hal9
5396 Note on perceived filtering slowdown per FR.
5398 Revision 1.38 2002/03/05 23:55:14 hal9
5399 Stupid I did it again. Double hyphen in comment breaks jade.
5401 Revision 1.37 2002/03/05 23:53:49 hal9
5402 jade barfs on '- -' embedded in comments. - -user option broke it.
5404 Revision 1.36 2002/03/05 22:53:28 hal9
5405 Add new - - user option.
5407 Revision 1.35 2002/03/05 00:17:27 hal9
5408 Added section on command line options.
5410 Revision 1.34 2002/03/04 19:32:07 oes
5411 Changed default port to 8118
5413 Revision 1.33 2002/03/03 19:46:13 hal9
5414 Emphasis on where/how to report bugs, etc
5416 Revision 1.32 2002/03/03 09:26:06 joergs
5417 AmigaOS changes, config is now loaded from PROGDIR: instead of
5418 AmiTCP:db/junkbuster/ if no configuration file is specified on the
5421 Revision 1.31 2002/03/02 22:45:52 david__schmidt
5424 Revision 1.30 2002/03/02 22:00:14 hal9
5425 Updated 'New Features' list. Ran through spell-checker.
5427 Revision 1.29 2002/03/02 20:34:07 david__schmidt
5428 Update OS/2 build section
5430 Revision 1.28 2002/02/24 14:34:24 jongfoster
5431 Formatting changes. Now changing the doctype to DocBook XML 4.1
5432 will work - no other changes are needed.
5434 Revision 1.27 2002/01/11 14:14:32 hal9
5435 Added a very short section on Templates
5437 Revision 1.26 2002/01/09 20:02:50 hal9
5438 Fix bug re: auto-detect config file changes.
5440 Revision 1.25 2002/01/09 18:20:30 hal9
5441 Touch ups for *.action files.
5443 Revision 1.24 2001/12/02 01:13:42 hal9
5446 Revision 1.23 2001/12/02 00:20:41 hal9
5447 Updates for recent changes.
5449 Revision 1.22 2001/11/05 23:57:51 hal9
5450 Minor update for startup now daemon mode.
5452 Revision 1.21 2001/10/31 21:11:03 hal9
5453 Correct 2 minor errors
5455 Revision 1.18 2001/10/24 18:45:26 hal9
5456 *** empty log message ***
5458 Revision 1.17 2001/10/24 17:10:55 hal9
5459 Catching up with Jon's recent work, and a few other things.
5461 Revision 1.16 2001/10/21 17:19:21 swa
5462 wrong url in documentation
5464 Revision 1.15 2001/10/14 23:46:24 hal9
5465 Various minor changes. Fleshed out SEE ALSO section.
5467 Revision 1.13 2001/10/10 17:28:33 hal9
5470 Revision 1.12 2001/09/28 02:57:04 hal9
5473 Revision 1.11 2001/09/28 02:25:20 hal9
5476 Revision 1.9 2001/09/27 23:50:29 hal9
5477 A few changes. A short section on regular expression in appendix.
5479 Revision 1.8 2001/09/25 00:34:59 hal9
5480 Some additions, and re-arranging.
5482 Revision 1.7 2001/09/24 14:31:36 hal9
5485 Revision 1.6 2001/09/24 14:10:32 hal9
5486 Including David's OS/2 installation instructions.
5488 Revision 1.2 2001/09/13 15:27:40 swa
5491 Revision 1.1 2001/09/12 15:36:41 swa
5492 source files for junkbuster documentation
5494 Revision 1.3 2001/09/10 17:43:59 swa
5495 first proposal of a structure.
5497 Revision 1.2 2001/06/13 14:28:31 swa
5498 docs should have an author.
5500 Revision 1.1 2001/06/13 14:20:37 swa
5501 first import of project's documentation for the webserver.