1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2 <!entity % dummy "IGNORE">
3 <!entity supported SYSTEM "supported.sgml">
4 <!entity newfeatures SYSTEM "newfeatures.sgml">
5 <!entity p-intro SYSTEM "privoxy.sgml">
6 <!entity seealso SYSTEM "seealso.sgml">
7 <!entity buildsource SYSTEM "buildsource.sgml">
8 <!entity contacting SYSTEM "contacting.sgml">
9 <!entity history SYSTEM "history.sgml">
10 <!entity copyright SYSTEM "copyright.sgml">
11 <!entity license SYSTEM "license.sgml">
12 <!entity p-version "2.9.15">
13 <!entity p-status "beta">
14 <!entity % p-not-stable "INCLUDE">
15 <!entity % p-stable "IGNORE">
16 <!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
17 <!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
18 <!entity % p-readme "IGNORE">
19 <!entity % p-config "IGNORE">
20 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
21 <!entity my-copy "©"> <!-- kludge for docbook2man -->
24 File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
27 This file belongs into
28 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
30 $Id: user-manual.sgml,v 1.113 2002/05/15 21:07:25 oes Exp $
32 Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
35 ========================================================================
36 NOTE: Please read developer-manual/documentation.html before touching
37 anything in this, or other Privoxy documentation.
38 ========================================================================
45 <title>Privoxy User Manual</title>
49 <!-- Completely the wrong markup, but very little is allowed -->
50 <!-- in this part of an article. FIXME -->
51 <link linkend="copyright">Copyright</link> &my-copy; 2001, 2002 by
52 <ulink url="http://www.privoxy.org">Privoxy Developers</ulink>
56 <pubdate>$Id: user-manual.sgml,v 1.113 2002/05/15 21:07:25 oes Exp $</pubdate>
60 Note: the following should generate a separate page, and a live link to it,
61 all nicely done. But it doesn't for some mysterious reason. Please leave
62 commented unless it can be fixed proper. For the time being, the
63 copyright/license declarations will be in their own sgml.
70 <holder>Privoxy Developers</holder>
73 <legalnotice id="legalnotice">
75 text goes here ........
87 This is here to keep vim syntax file from breaking :/
88 If I knew enough to fix it, I would.
89 PLEASE DO NOT REMOVE! HB: hal@foobox.net
95 The user manual gives users information on how to install, configure and use
97 url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
100 <!-- Include privoxy.sgml boilerplate: -->
102 <!-- end privoxy.sgml -->
105 You can find the latest version of the user manual at <ulink
106 url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
107 Please see the <ulink url="contact.html">Contact section</ulink> on how to
108 contact the developers.
112 <!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
118 <!-- ~~~~~ New section ~~~~~ -->
119 <sect1 label="1" id="introduction"><title>Introduction</title>
121 This documentation is included with the current &p-status; version of
122 <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
123 and is mostly complete at this point. The most up to date reference for the
124 time being is still the comments in the source files and in the individual
125 configuration files. Development of version 3.0 is currently nearing
126 completion, and includes many significant changes and enhancements over
127 earlier versions. The target release date for
128 stable v3.0 is <quote>soon</quote> ;-)]]>.
131 <!-- include only in non-stable versions -->
134 Since this is a &p-status; version, not all new features are well tested. This
135 documentation may be slightly out of sync as a result (especially with
136 CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
141 <!-- ~~~~~ New section ~~~~~ -->
142 <sect2 id="features"><title>Features</title>
144 In addition to <application>Internet Junkbuster's</application> traditional
145 features of ad and banner blocking and cookie management,
146 <application>Privoxy</application> provides new features<![%p-not-stable;[,
147 some of them currently under development]]>:
149 <!-- Include newfeatures.sgml boilerplate here: -->
151 <!-- end boilerplate -->
156 <!-- ~ End section ~ -->
159 <!-- ~~~~~ New section ~~~~~ -->
160 <sect1 id="installation"><title>Installation</title>
163 <application>Privoxy</application> is available both in convenient pre-compiled
164 packages for a wide range of operating systems, and as raw source code.
165 For most users, we recommend using the packages, which can be downloaded from our
166 <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
171 Note: If you have a previous <application>Junkbuster</application> or
172 <application>Privoxy</application> installation on your system, you
173 will need to remove it. On some platforms, this may be done for you as part
174 of their installation procedure. (See below for your platform). In any case
175 <emphasis>be sure to backup your old configuration if it is valuable to
176 you.</emphasis> See the <link linkend="upgradersnote">note to
177 upgraders</link> section below.
180 <!-- ~~~~~ New section ~~~~~ -->
181 <sect2 id="installation-packages"><title>Binary Packages</title>
183 How to install the binary packages depends on your operating system:
186 <!-- ~~~~~ New section ~~~~~ -->
187 <sect3 id="installation-pack-rpm"><title>Red Hat, SuSE RPMs and Conectiva</title>
190 RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
191 and will use <filename>/etc/privoxy</filename> for the location
192 of configuration files.
196 Note that on Red Hat, <application>Privoxy</application> will
197 <emphasis>not</emphasis> be automatically started on system boot. You will
198 need to enable that using <command>chkconfig</command>,
199 <command>ntsysv</command>, or similar methods. Note that SuSE will
200 automatically start Privoxy in the boot process.
204 If you have problems with failed dependencies, try rebuilding the SRC RPM:
205 <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This
206 will use your locally installed libraries and RPM version.
210 Also note that if you have a <application>Junkbuster</application> RPM installed
211 on your system, you need to remove it first, because the packages conflict.
212 Otherwise, RPM will try to remove <application>Junkbuster</application>
213 automatically, before installing <application>Privoxy</application>.
217 <!-- ~~~~~ New section ~~~~~ -->
218 <sect3 id="installation-deb"><title>Debian</title>
224 <!-- ~~~~~ New section ~~~~~ -->
225 <sect3 id="installation-pack-win"><title>Windows</title>
228 Just double-click the installer, which will guide you through
229 the installation process. You will find the configuration files
230 in the same directory as you installed Privoxy in. We do not
231 use the registry of Windows.
235 <!-- ~~~~~ New section ~~~~~ -->
236 <sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
239 Create a new directory, <literal>cd</literal> to it, then unzip and
240 untar the archive. For the most part, you'll have to figure out where
245 <!-- ~~~~~ New section ~~~~~ -->
246 <sect3 id="installation-os2"><title>OS/2</title>
249 First, make sure that no previous installations of
250 <application>Junkbuster</application> and / or
251 <application>Privoxy</application> are left on your
252 system. You can do this by
256 Then, just double-click the WarpIN self-installing archive, which will
257 guide you through the installation process. A shadow of the
258 <application>Privoxy</application> executable will be placed in your
259 startup folder so it will start automatically whenever OS/2 starts.
263 The directory you choose to install <application>Privoxy</application>
264 into will contain all of the configuration files.
268 <!-- ~~~~~ New section ~~~~~ -->
269 <sect3 id="installation-mac"><title>Max OSX</title>
271 Unzip the downloaded package (you can either double-click on the file
272 in the finder, or on the desktop if you downloaded it there). Then,
273 double-click on the package installer icon and follow the installation
275 <application>Privoxy</application> will be installed in the subdirectory
276 <literal>/Applications/Privoxy.app</literal>.
277 <application>Privoxy</application> will set itself up to start
278 automatically on system bring-up via
279 <literal>/System/Library/StartupItems/Privoxy</literal>.
283 <!-- ~~~~~ New section ~~~~~ -->
284 <sect3 id="installation-amiga"><title>AmigaOS</title>
286 Copy and then unpack the <filename>lha</filename> archive to a suitable location.
287 All necessary files will be installed into <application>Privoxy</application>
288 directory, including all configuration and log files. To uninstall, just
289 remove this directory.
292 Start <application>Privoxy</application> (with RUN <>NIL:) in your
293 <filename>startnet</filename> script (AmiTCP), in
294 <filename>s:user-startup</filename> (RoadShow), as startup program in your
295 startup script (Genesis), or as startup action (Miami and MiamiDx).
296 <application>Privoxy</application> will automatically quit when you quit your
297 TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
298 <application>Privoxy</application> is still running).
303 <!-- ~~~~~ New section ~~~~~ -->
304 <sect2 id="installation-source"><title>Building from Source</title>
307 The most convenient way to obtain the <application>Privoxy</application> sources
308 is to download the source tarball from our <ulink url="http://sf.net/projects/ijbswa/">project
313 If you like to live on the bleeding edge and are not afraid of using
314 possibly unstable development versions, you can check out the up-to-the-minute
315 version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
316 CVS repository</ulink> or simply download <ulink
317 url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
321 <!-- include buildsource.sgml boilerplate: -->
323 <!-- end boilerplate -->
329 <!-- ~ End section ~ -->
331 <!-- ~~~~~ New section ~~~~~ -->
332 <sect1 id="upgradersnote">
333 <title>Note to Upgraders</title>
335 There are very significant changes from earlier
336 <application>Junkbuster</application> versions to the current
337 <application>Privoxy</application>. The number, names, syntax, and
338 purposes of configuration files have substantially changed.
339 <application>Junkbuster 2.0.x</application> configuration
340 files will not migrate, <application>Junkbuster 2.9.x</application>
341 and <application>Privoxy</application> configurations will need to be
342 ported. The functionalities of the old <filename>blockfile</filename>,
343 <filename>cookiefile</filename> and <filename>imagelist</filename>
344 are now combined into the <link linkend="actions-file"><quote>actions
345 files</quote></link>.
346 <filename>default.action</filename>, is the main actions file. Local
347 exceptions should best be put into <filename>user.action</filename>.
350 A <link linkend="filter-file"><quote>filter file</quote></link> (typically
351 <filename>default.filter</filename>) is new as of <application>Privoxy
352 2.9.x</application>, and provides some of the new sophistication (explained
353 below). <filename>config</filename> is much the same as before.
356 If upgrading from a 2.0.x version, you will have to use the new config
357 files, and possibly adapt any personal rules from your older files.
358 When porting personal rules over from the old <filename>blockfile</filename>
359 to the new actions files, please note that even the pattern syntax has
360 changed. If upgrading from 2.9.x development versions, it is still
361 recommended to use the new configuration files.
364 A quick list of things to be aware of before upgrading:
372 The default listening port is now 8118 due to a conflict with another
378 Some installers may remove earlier versions completely. Save any
379 important configuration files!
384 <application>Privoxy</application> is controllable with a web browser
385 at the special URL: <ulink
386 url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
387 (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
388 aspects of configuration can be done here, including temporarily disabling
389 <application>Privoxy</application>.
394 The primary configuration files for cookie management, ad and banner
395 blocking, and many other aspects of <application>Privoxy</application>
396 configuration are the <link linkend="actions-file">actions
397 files</link>. It is strongly recommended to become familiar with the new
398 actions concept below, before modifying these files. Locally defined rules
399 should go into <filename>user.action</filename>.
404 <!-- I think it is best to keep this somewhat vague, in case -->
405 <!-- the situation changes under our feet. -->
406 Some installers may not automatically start
407 <application>Privoxy</application> after installation.
415 <!-- ~~~~~ New section ~~~~~ -->
416 <sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
422 If upgrading, from versions before 2.9.16, please back up any configuration
423 files. See the <link linkend="upgradersnote">Note to Upgraders</link> Section.
429 Install <application>Privoxy</application>. See the <link
430 linkend="installation">Installation Section</link> for platform specific
437 Advanced users and those who want to offer <application>Privoxy</application>
438 service to more than just their local machine should check the <link
439 linkend="config">main config file</link>, especially the <link
440 linkend="access-control">security-relevant</link> options.
446 Start <application>Privoxy</application>, if the installation program has
447 not done this already. See the section <link linkend="startup">Starting
448 <application>Privoxy</application></link>.
454 Set your browser to use <application>Privoxy</application> as HTTP and HTTPS
455 proxy by setting the proxy configuration for address of
456 <literal>127.0.0.1</literal> and port <literal>8118</literal>.
457 (<application>Junkbuster</application> and earlier versions of
458 <application>Privoxy</application> used port 8000.) See the section <link
459 linkend="startup">Starting <application>Privoxy</application></link>.
465 Flush your browser's caches, to remove any cached ad images.
471 Enjoy surfing with enhanced comfort and privacy.
477 If you experience ads that slipped through, innocent images that are
478 blocked, or otherwise feel the need to fine-tune <application>Privoxy's</application>
479 behaviour, take a look at the <link linkend="actions-file">actions files</link>.
480 As a quick start, you might find the <link linkend="act-examples">richly
481 commented examples</link> helpful. You can also view and edit the actions
482 files through the <ulink url="http://config.privoxy.org">web-based
483 user interface</ulink>. The Appendix <quote><link linkend="actionsanat">Anatomy of
484 an Action</link></quote> has hints how to debug actions that <quote>misbehave</quote>.
490 Please see the section <link linkend="contact">Contacting the
491 Developers</link> on how to report bugs or problems with websites or to get
500 <!-- ~~~~~ New section ~~~~~ -->
502 <title>Starting <application>Privoxy</application></title>
504 Before launching <application>Privoxy</application> for the first time, you
505 will want to configure your browser(s) to use
506 <application>Privoxy</application> as a HTTP and HTTPS proxy. The default is
507 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions
508 used port 8000). This is the one configuration step that must be done!
512 With <application>Netscape</application> (and
513 <application>Mozilla</application>), this can be set under <literal>Edit
514 -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
515 For <application>Internet Explorer</application>: <literal>Tools ->
516 Internet Properties -> Connections -> LAN Setting</literal>. Then,
517 check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
518 127.0.0.1, Port: 8118). Include if HTTPS proxy support too.
522 After doing this, flush your browser's disk and memory caches to force a
523 re-reading of all pages and to get rid of any ads that may be cached. You
524 are now ready to start enjoying the benefits of using
525 <application>Privoxy</application>!
529 <application>Privoxy</application> is typically started by specifying the
530 main configuration file to be used on the command line. If no configuration
531 file is specified on the command line, <application>Privoxy</application>
532 will look for a file named <filename>config</filename> in the current
533 directory. Except on Win32 where it will try <filename>config.txt</filename>.
536 <sect2 id="start-redhatdebian">
537 <title>RedHat, Conectiva and Debian</title>
539 We use a script. Note that RedHat does not start Privoxy upon booting per
540 default. It will use the file <filename>/etc/privoxy/config</filename> as its
541 main configuration file. FIXME: Debian??
545 # /etc/rc.d/init.d/privoxy start
550 <sect2 id="start-suse">
553 We use a script. It will use the file <filename>/etc/privoxy/config</filename>
554 as its main configuration file. Note that SuSE starts Privoxy upon booting
564 <sect2 id="start-windows">
565 <title>Windows</title>
567 Click on the Privoxy Icon to start Privoxy. If no configuration file is
568 specified on the command line, <application>Privoxy</application> will look
569 for a file named <filename>config.txt</filename>. Note that Windows will
570 automatically start Privoxy upon booting you PC.
574 <sect2 id="start-unices">
575 <title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
577 Example Unix startup command:
581 # /usr/sbin/privoxy /etc/privoxy/config
586 <sect2 id="start-os2">
593 <sect2 id="start-macosx">
594 <title>MAX OSX</title>
601 <sect2 id="start-amigaos">
602 <title>AmigaOS</title>
611 See the section <link linkend="cmdoptions">Command line options</link> for
615 must find a better place for this paragraph
618 The included default configuration files should give a reasonable starting
619 point. Most of the per site configuration is done in the
620 <ulink url="actions-file.html"><quote>actions</quote></ulink> files. These are
621 where various cookie actions are defined, ad and banner blocking, and other
622 aspects of <application>Privoxy</application> configuration. There are several
623 such files included, with varying levels of aggressiveness.
627 You will probably want to keep an eye out for sites for which you may prefer
628 persistent cookies, and add these to your actions configuration as needed. By
629 default, most of these will be accepted only during the current browser
630 session (aka <quote>session cookies</quote>), unless you add them to the
631 configuration. If you want the browser to handle this instead, you will need
632 to edit <filename>user.action</filename> (or through the web based interface)
633 and disable this feature. If you use more than one browser, it would make
634 more sense to let <application>Privoxy</application> handle this. In which
635 case, the browser(s) should be set to accept all cookies.
639 Another feature where you will probably want to define exceptions for trusted
640 sites is the popup-killing (through the <ulink
641 url="actions-file.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink> and
643 url="actions-file.html#FILTER-POPUPS"><quote>+filter{popups}</quote></ulink>
644 actions), because your favorite shopping, banking, or leisure site may need
645 popups (explained below).
649 <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
650 the optional 1.1 features are as yet supported. In the unlikely event that
651 you experience inexplicable problems with browsers that use HTTP/1.1 per default
652 (like <application>Mozilla</application> or recent versions of I.E.), you might
653 try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
654 Preferences -> Debug -> Networking</literal>.
655 Alternatively, set the <quote>+downgrade-http-version</quote> config option in
656 <filename>default.action</filename> which will downgrade your browser's HTTP
657 requests from HTTP/1.1 to HTTP/1.0 before processing them.
661 After running <application>Privoxy</application> for a while, you can
662 start to fine tune the configuration to suit your personal, or site,
663 preferences and requirements. There are many, many aspects that can
664 be customized. <quote>Actions</quote>
665 can be adjusted by pointing your browser to
666 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
667 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
668 and then follow the link to <quote>View & Change the Current Configuration</quote>.
669 (This is an internal page and does not require Internet access.)
673 In fact, various aspects of <application>Privoxy</application>
674 configuration can be viewed from this page, including
675 current configuration parameters, source code version numbers,
676 the browser's request headers, and <quote>actions</quote> that apply
677 to a given URL. In addition to the actions file
678 editor mentioned above, <application>Privoxy</application> can also
679 be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
683 If you encounter problems, try loading the page without
684 <application>Privoxy</application>. If that helps, enter the URL where
685 you have the problems into <ulink url="http://p.p/show-url-info">the browser
686 based rule tracing utility</ulink>. See which rules apply and why, and
687 then try turning them off for that site one after the other, until the problem
688 is gone. When you have found the culprit, you might want to turn the rest on
693 If the above paragraph sounds gibberish to you, you might want to <ulink
694 url="actions-file.html#ACTIONSFILE">read more about the actions concept</ulink>
695 or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
700 If you can't get rid of the problem at all, think you've found a bug in
701 Privoxy, want to propose a new feature or smarter rules, please see the
702 section <ulink url="contact.html"><quote>Contacting the
703 Developers</quote></ulink> below.
708 <!-- ~~~~~ New section ~~~~~ -->
709 <sect2 id="cmdoptions">
710 <title>Command Line Options</title>
712 <application>Privoxy</application> may be invoked with the following
713 command-line options:
721 <emphasis>--version</emphasis>
724 Print version info and exit. Unix only.
729 <emphasis>--help</emphasis>
732 Print short usage info and exit. Unix only.
737 <emphasis>--no-daemon</emphasis>
740 Don't become a daemon, i.e. don't fork and become process group
741 leader, and don't detach from controlling tty. Unix only.
746 <emphasis>--pidfile FILE</emphasis>
750 On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
751 <emphasis>FILE</emphasis> on exit. Failure to create or delete the
752 <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
753 option is given, no PID file will be used. Unix only.
758 <emphasis>--user USER[.GROUP]</emphasis>
762 After (optionally) writing the PID file, assume the user ID of
763 <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
764 privileges are not sufficient to do so. Unix only.
769 <emphasis>configfile</emphasis>
772 If no <emphasis>configfile</emphasis> is included on the command line,
773 <application>Privoxy</application> will look for a file named
774 <quote>config</quote> in the current directory (except on Win32
775 where it will look for <quote>config.txt</quote> instead). Specify
776 full path to avoid confusion. If no config file is found,
777 <application>Privoxy</application> will fail to start.
788 <!-- ~ End section ~ -->
791 <!-- ~~~~~ New section ~~~~~ -->
792 <sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
794 All <application>Privoxy</application> configuration is stored
795 in text files. These files can be edited with a text editor.
796 Many important aspects of <application>Privoxy</application> can
797 also be controlled easily with a web browser.
801 <!-- ~~~~~ New section ~~~~~ -->
804 <title>Controlling <application>Privoxy</application> with Your Web Browser</title>
806 <application>Privoxy</application>'s user interface can be reached through the special
807 URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
808 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
809 which is a built-in page and works without Internet access.
810 You will see the following section:
814 <!-- Needs to be put in a table and colorized -->
817 <bridgehead renderas="sect2">Privoxy Menu</bridgehead>
821 ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
824 ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
827 ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
830 ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
833 ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
841 This should be self-explanatory. Note the first item leads to an editor for the
842 <link linkend="actions-file">actions files</link>, which is where the ad, banner,
843 cookie, and URL blocking magic is configured as well as other advanced features of
844 <application>Privoxy</application>. This is an easy way to adjust various
845 aspects of <application>Privoxy</application> configuration. The actions
846 file, and other configuration files, are explained in detail below.
850 <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
851 have problems with your current actions and filters. You can in fact use
852 it as a test to see whether it is <application>Privoxy</application>
853 causing the problem or not. <application>Privoxy</application> continues
854 to run as a proxy in this case, but all manipulation is disabled, i.e.
855 <application>Privoxy</application> acts like a normal forwarding proxy. There
856 is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
857 that you can toggle <application>Privoxy</application> with one click from
863 <!-- ~ End section ~ -->
868 <!-- ~~~~~ New section ~~~~~ -->
870 <sect2 id="confoverview">
871 <title>Configuration Files Overview</title>
873 For Unix, *BSD and Linux, all configuration files are located in
874 <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
875 AmigaOS these are all in the same directory as the
876 <application>Privoxy</application> executable. <![%p-not-stable;[ The name
877 and number of configuration files has changed from previous versions, and is
878 subject to change as development progresses.]]>
882 The installed defaults provide a reasonable starting point, though
883 some settings may be aggressive by some standards. For the time being, the
884 principle configuration files are:
892 The <link linkend="config">main configuration file</link> is named <filename>config</filename>
893 on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
894 on Windows. This is a required file.
900 <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
901 is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
902 content modification, cookie handling etc should be applied by default. It also defines many
903 exceptions (both positive and negative) from this default set of actions that enable
904 <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
905 as many websites as possible.
908 Multiple actions files may be defined in <filename>config</filename>. These
909 are processed in the order they are defined. Local customizations and locally
910 preferred exceptions to the default policies as defined in
911 <filename>default.action</filename> (which you will most probably want
912 to define sooner or later) are probably best applied in
913 <filename>user.action</filename>, where you can preserve them across
914 upgrades. <filename>standard.action</filename> is for
915 <application>Privoxy's</application> internal use.
918 There is also a web based editor that can be accessed from
920 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
922 url="http://p.p/show-status">http://p.p/show-status</ulink>) for the
923 various actions files.
929 <filename>default.filter</filename> (the <link linkend="filter-file">filter
930 file</link>) can be used to re-write the raw page content, including
931 viewable text as well as embedded HTML and JavaScript, and whatever else
932 lurks on any given web page. The filtering jobs are only pre-defined here;
933 whether to apply them or not is up to the actions files.
941 All files use the <quote><literal>#</literal></quote> character to denote a
942 comment (the rest of the line will be ignored) and understand line continuation
943 through placing a backslash ("<literal>\</literal>") as the very last character
944 in a line. If the <literal>#</literal> is preceded by a backslash, it looses
945 its special function. Placing a <literal>#</literal> in front of an otherwise
946 valid configuration line to prevent it from being interpreted is called "commenting
951 The actions files and <filename>default.filter</filename>
952 can use Perl style <link linkend="regex">regular expressions</link> for
957 After making any changes, there is no need to restart
958 <application>Privoxy</application> in order for the changes to take
959 effect. <application>Privoxy</application> detects such changes
960 automatically. Note, however, that it may take one or two additional
961 requests for the change to take effect. When changing the listening address
962 of <application>Privoxy</application>, these <quote>wake up</quote> requests
963 must obviously be sent to the <emphasis>old</emphasis> listening address.
968 While under development, the configuration content is subject to change.
969 The below documentation may not be accurate by the time you read this.
970 Also, what constitutes a <quote>default</quote> setting, may change, so
971 please check all your configuration files on important issues.
977 <!-- ~ End section ~ -->
980 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
983 <title>The Main Configuration File</title>
986 Again, the main configuration file is named <filename>config</filename> on
987 Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
988 Configuration lines consist of an initial keyword followed by a list of
989 values, all separated by whitespace (any number of spaces or tabs). For
997 <emphasis>confdir /etc/privoxy</emphasis></literallayout>
1003 Assigns the value <literal>/etc/privoxy</literal> to the option
1004 <literal>confdir</literal> and thus indicates that the configuration
1005 directory is named <quote>/etc/privoxy/</quote>.
1009 All options in the config file except for <literal>confdir</literal> and
1010 <literal>logdir</literal> are optional. Watch out in the below description
1011 for what happens if you leave them unset.
1015 The main config file controls all aspects of <application>Privoxy</application>'s
1016 operation that are not location dependent (i.e. they apply universally, no matter
1017 where you may be surfing).
1021 <!-- ~~~~~ New section ~~~~~ -->
1023 <sect2 id="conf-log-loc">
1024 <title>Configuration and Log File Locations</title>
1027 <application>Privoxy</application> can (and normally does) use a number of
1028 other files for additional configuration, help and logging.
1029 This section of the configuration file tells <application>Privoxy</application>
1030 where to find those other files.
1034 The user running Privoxy, must have read permission for all
1035 configuration files, and write permission to any files that would
1036 be modified, such as log files.
1039 <sect3 renderas="sect4" id="confdir"><title>confdir</title>
1043 <term>Specifies:</term>
1045 <para>The directory where the other configuration files are located</para>
1049 <term>Type of value:</term>
1051 <para>Path name</para>
1055 <term>Default value:</term>
1057 <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
1061 <term>Effect if unset:</term>
1063 <para><emphasis>Mandatory</emphasis></para>
1070 No trailing <quote><literal>/</literal></quote>, please
1073 When development goes modular and multi-user, the blocker, filter, and
1074 per-user config will be stored in subdirectories of <quote>confdir</quote>.
1075 For now, the configuration directory structure is flat, except for
1076 <filename>confdir/templates</filename>, where the HTML templates for CGI
1077 output reside (e.g. <application>Privoxy's</application> 404 error page).
1085 <sect3 renderas="sect4" id="logdir"><title>logdir</title>
1089 <term>Specifies:</term>
1092 The directory where all logging takes place (i.e. where <filename>logfile</filename> and
1093 <filename>jarfile</filename> are located)
1098 <term>Type of value:</term>
1100 <para>Path name</para>
1104 <term>Default value:</term>
1106 <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
1110 <term>Effect if unset:</term>
1112 <para><emphasis>Mandatory</emphasis></para>
1119 No trailing <quote><literal>/</literal></quote>, please
1126 <sect3 renderas="sect4" id="actionsfile"><title>
1129 <anchor id="default.action">
1130 <anchor id="standard.action">
1131 <anchor id="user.action">
1132 <!-- Note: slightly modified this section 04/28/02, hal. See NOTE. -->
1135 <term>Specifies:</term>
1138 The <link linkend="actions-file">actions file(s)</link> to use
1143 <term>Type of value:</term>
1145 <para>File name, relative to <literal>confdir</literal>, without the <literal>.action</literal> suffix</para>
1149 <term>Default value:</term>
1153 <msgtext><literallayout> standard # Internal purposes, no editing recommended</literallayout></msgtext>
1156 <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
1159 <msgtext><literallayout> user # User customizations</literallayout></msgtext>
1165 <term>Effect if unset:</term>
1168 No actions are taken at all. Simple neutral proxying.
1176 Multiple <literal>actionsfile</literal> lines are permitted, and are in fact recommended!
1179 The default values include standard.action, which is used for internal
1180 purposes and should be loaded, default.action, which is the
1181 <quote>main</quote> actions file maintained by the developers, and
1182 <filename>user.action</filename>, where you can make your personal additions.
1185 Actions files are where all the per site and per URL configuration is done for
1186 ad blocking, cookie management, privacy considerations, etc.
1187 There is no point in using <application>Privoxy</application> without at
1188 least one actions file.
1195 <sect3 renderas="sect4" id="filterfile"><title>filterfile</title>
1196 <anchor id="default.filter">
1199 <term>Specifies:</term>
1202 The <link linkend="filter">filter</link> file to use
1207 <term>Type of value:</term>
1209 <para>File name, relative to <literal>confdir</literal></para>
1213 <term>Default value:</term>
1215 <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
1219 <term>Effect if unset:</term>
1222 No textual content filtering takes place, i.e. all
1223 <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
1224 actions in the actions files are turned neutral.
1232 The <quote>default.filter</quote> file contains content modification rules
1233 that use <quote>regular expressions</quote>. These rules permit powerful
1234 changes on the content of Web pages, e.g., you could disable your favorite
1235 JavaScript annoyances, re-write the actual displayed text, or just have some
1236 fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
1237 it appears on a Web page.
1244 <sect3 renderas="sect4" id="logfile"><title>logfile</title>
1248 <term>Specifies:</term>
1256 <term>Type of value:</term>
1258 <para>File name, relative to <literal>logdir</literal></para>
1262 <term>Default value:</term>
1264 <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
1268 <term>Effect if unset:</term>
1271 No log file is used, all log messages go to the console (<literal>stderr</literal>).
1279 The windows version will additionally log to the console.
1282 The logfile is where all logging and error messages are written. The level
1283 of detail and number of messages are set with the <literal>debug</literal>
1284 option (see below). The logfile can be useful for tracking down a problem with
1285 <application>Privoxy</application> (e.g., it's not blocking an ad you
1286 think it should block) but in most cases you probably will never look at it.
1289 Your logfile will grow indefinitely, and you will probably want to
1290 periodically remove it. On Unix systems, you can do this with a cron job
1291 (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
1292 script has been included.
1295 On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
1296 +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
1297 the effect that cron.daily will automatically archive, gzip, and empty the
1298 log, when it exceeds 1M size.
1301 Any log files must be writable by whatever user <application>Privoxy</application>
1302 is being run as (default on UNIX, user id is <quote>privoxy</quote>).
1309 <sect3 renderas="sect4" id="jarfile"><title>jarfile</title>
1313 <term>Specifies:</term>
1316 The file to store intercepted cookies in
1321 <term>Type of value:</term>
1323 <para>File name, relative to <literal>logdir</literal></para>
1327 <term>Default value:</term>
1329 <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
1333 <term>Effect if unset:</term>
1336 Intercepted cookies are not stored at all.
1344 The jarfile may grow to ridiculous sizes over time.
1351 <sect3 renderas="sect4" id="trustfile"><title>trustfile</title>
1354 <term>Specifies:</term>
1357 The trust file to use
1362 <term>Type of value:</term>
1364 <para>File name, relative to <literal>confdir</literal></para>
1368 <term>Default value:</term>
1370 <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
1374 <term>Effect if unset:</term>
1377 The whole trust mechanism is turned off.
1385 The trust mechanism is an experimental feature for building white-lists and should
1386 be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
1389 If you specify a trust file, <application>Privoxy</application> will only allow
1390 access to sites that are named in the trustfile.
1391 You can also mark sites as trusted referrers (with <literal>+</literal>), with
1392 the effect that access to untrusted sites will be granted, if a link from a
1393 trusted referrer was used.
1394 The link target will then be added to the <quote>trustfile</quote>.
1395 Possible applications include limiting Internet access for children.
1398 If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
1406 <!-- ~ End section ~ -->
1410 <!-- ~~~~~ New section ~~~~~ -->
1412 <sect2 id="local-set-up">
1413 <title>Local Set-up Documentation</title>
1416 If you intend to operate <application>Privoxy</application> for more users
1417 than just yourself, it might be a good idea to let them know how to reach
1418 you, what you block and why you do that, your policies, etc.
1421 <sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
1424 <term>Specifies:</term>
1427 Location of the <application>Privoxy</application> User Manual.
1432 <term>Type of value:</term>
1434 <para>A fully qualified URI</para>
1438 <term>Default value:</term>
1440 <para><emphasis>Unset</emphasis></para>
1444 <term>Effect if unset:</term>
1447 <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
1448 will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
1456 The User Manual URI is used for help links from some of the internal CGI pages.
1457 The manual itself is normally packaged with the binary distributions, so you probably want
1458 to set this to a locally installed copy. For multi-user setups, you could provide a copy on
1459 a local webserver for all your users and use the corresponding URL here.
1465 Unix, in local filesystem:
1468 <screen>user-manual file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
1471 Any platform, on local webserver (called <quote>local-webserver</quote>):
1474 <screen>user-manual http://local-webserver/privoxy-user-manual/</screen>
1478 If set, this option should be <emphasis>the first option in the config file</emphasis>, because
1479 it is used while the config file is being read.
1487 <sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
1491 <term>Specifies:</term>
1494 A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
1499 <term>Type of value:</term>
1505 <term>Default value:</term>
1507 <para>Two example URL are provided</para>
1511 <term>Effect if unset:</term>
1514 No links are displayed on the "untrusted" error page.
1522 The value of this option only matters if the experimental trust mechanism has been
1523 activated. (See <link linkend="trustfile"><emphasis>trustfile</emphasis></link> above.)
1526 If you use the trust mechanism, it is a good idea to write up some on-line
1527 documentation about your trust policy and to specify the URL(s) here.
1528 Use multiple times for multiple URLs.
1531 The URL(s) should be added to the trustfile as well, so users don't end up
1532 locked out from the information on why they were locked out in the first place!
1539 <sect3 renderas="sect4" id="admin-address"><title>admin-address</title>
1543 <term>Specifies:</term>
1546 An email address to reach the proxy administrator.
1551 <term>Type of value:</term>
1553 <para>Email address</para>
1557 <term>Default value:</term>
1559 <para><emphasis>Unset</emphasis></para>
1563 <term>Effect if unset:</term>
1566 No email address is displayed on error pages and the CGI user interface.
1574 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1575 are unset, the whole "Local Privoxy Support" box on all generated pages will
1583 <sect3 renderas="sect4" id="proxy-info-url"><title>proxy-info-url</title>
1587 <term>Specifies:</term>
1590 A URL to documentation about the local <application>Privoxy</application> setup,
1591 configuration or policies.
1596 <term>Type of value:</term>
1602 <term>Default value:</term>
1604 <para><emphasis>Unset</emphasis></para>
1608 <term>Effect if unset:</term>
1611 No link to local documentation is displayed on error pages and the CGI user interface.
1619 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1620 are unset, the whole "Local Privoxy Support" box on all generated pages will
1624 This URL shouldn't be blocked ;-)
1632 <!-- ~ End section ~ -->
1634 <!-- ~~~~~ New section ~~~~~ -->
1636 <sect2 id="debugging">
1637 <title>Debugging</title>
1640 These options are mainly useful when tracing a problem.
1641 Note that you might also want to invoke
1642 <application>Privoxy</application> with the <literal>--no-daemon</literal>
1643 command line option when debugging.
1646 <sect3 renderas="sect4" id="debug"><title>debug</title>
1650 <term>Specifies:</term>
1653 Key values that determine what information gets logged to the
1654 <link linkend="logfile"><emphasis>logfile</emphasis></link>.
1659 <term>Type of value:</term>
1661 <para>Integer values</para>
1665 <term>Default value:</term>
1667 <para>12289 (i.e.: URLs plus informational and warning messages)</para>
1671 <term>Effect if unset:</term>
1674 Nothing gets logged.
1682 The available debug levels are:
1686 debug 1 # show each GET/POST/CONNECT request
1687 debug 2 # show each connection status
1688 debug 4 # show I/O status
1689 debug 8 # show header parsing
1690 debug 16 # log all data into the logfile
1691 debug 32 # debug force feature
1692 debug 64 # debug regular expression filter
1693 debug 128 # debug fast redirects
1694 debug 256 # debug GIF de-animation
1695 debug 512 # Common Log Format
1696 debug 1024 # debug kill pop-ups
1697 debug 4096 # Startup banner and warnings.
1698 debug 8192 # Non-fatal errors
1702 To select multiple debug levels, you can either add them or use
1703 multiple <literal>debug</literal> lines.
1706 A debug level of 1 is informative because it will show you each request
1707 as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
1708 so that you will notice when things go wrong. The other levels are probably
1709 only of interest if you are hunting down a specific problem. They can produce
1710 a hell of an output (especially 16).
1714 The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
1715 <application>Privoxy</application>) is always on and cannot be disabled.
1718 If you want to use CLF (Common Log Format), you should set <quote>debug
1719 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
1726 <sect3 renderas="sect4" id="single-threaded"><title>single-threaded</title>
1730 <term>Specifies:</term>
1733 Whether to run only one server thread
1738 <term>Type of value:</term>
1740 <para><emphasis>None</emphasis></para>
1744 <term>Default value:</term>
1746 <para><emphasis>Unset</emphasis></para>
1750 <term>Effect if unset:</term>
1753 Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1754 serve multiple requests simultaneously.
1762 This option is only there for debug purposes and you should never
1763 need to use it. <emphasis>It will drastically reduce performance.</emphasis>
1772 <!-- ~~~~~ New section ~~~~~ -->
1774 <sect2 id="access-control">
1775 <title>Access Control and Security</title>
1778 This section of the config file controls the security-relevant aspects
1779 of <application>Privoxy</application>'s configuration.
1782 <sect3 renderas="sect4" id="listen-address"><title>listen-address</title>
1786 <term>Specifies:</term>
1789 The IP address and TCP port on which <application>Privoxy</application> will
1790 listen for client requests.
1795 <term>Type of value:</term>
1797 <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
1802 <term>Default value:</term>
1804 <para>127.0.0.1:8118</para>
1808 <term>Effect if unset:</term>
1811 Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended for
1812 home users who run <application>Privoxy</application> on the same machine as
1821 You will need to configure your browser(s) to this proxy address and port.
1824 If you already have another service running on port 8118, or if you want to
1825 serve requests from other machines (e.g. on your local network) as well, you
1826 will need to override the default.
1829 If you leave out the IP address, <application>Privoxy</application> will
1830 bind to all interfaces (addresses) on your machine and may become reachable
1831 from the Internet. In that case, consider using access control lists (ACL's)
1832 (see <quote>ACLs</quote> below), or a firewall.
1837 <term>Example:</term>
1840 Suppose you are running <application>Privoxy</application> on
1841 a machine which has the address 192.168.0.1 on your local private network
1842 (192.168.0.0) and has another outside connection with a different address.
1843 You want it to serve requests from inside only:
1847 listen-address 192.168.0.1:8118
1855 <sect3 renderas="sect4" id="toggle"><title>toggle</title>
1859 <term>Specifies:</term>
1862 Initial state of "toggle" status
1867 <term>Type of value:</term>
1873 <term>Default value:</term>
1879 <term>Effect if unset:</term>
1882 Act as if toggled on
1890 If set to 0, <application>Privoxy</application> will start in
1891 <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
1892 proxy where all ad blocking, filtering, etc are disabled. See
1893 <literal>enable-remote-toggle</literal> below. This is not really useful
1894 anymore, since toggling is much easier via <ulink
1895 url="http://config.privoxy.org/toggle">the web interface</ulink> than via
1896 editing the <filename>conf</filename> file.
1899 The windows version will only display the toggle icon in the system tray
1900 if this option is present.
1908 <sect3 renderas="sect4" id="enable-remote-toggle"><title>enable-remote-toggle</title>
1911 <term>Specifies:</term>
1914 Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
1915 feature</ulink> may be used
1920 <term>Type of value:</term>
1926 <term>Default value:</term>
1932 <term>Effect if unset:</term>
1935 The web-based toggle feature is disabled.
1943 When toggled off, <application>Privoxy</application> acts like a normal,
1944 content-neutral proxy, i.e. it acts as if none of the actions applied to
1948 For the time being, access to the toggle feature can <emphasis>not</emphasis> be
1949 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1950 so that everybody who can access <application>Privoxy</application> (see
1951 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1952 toggle it for all users. So this option is <emphasis>not recommended</emphasis>
1953 for multi-user environments with untrusted users.
1956 Note that you must have compiled <application>Privoxy</application> with
1957 support for this feature, otherwise this option has no effect.
1965 <sect3 renderas="sect4" id="enable-edit-actions"><title>enable-edit-actions</title>
1968 <term>Specifies:</term>
1971 Whether or not the <ulink url="http://config.privoxy.org/show-status">web-based actions
1972 file editor</ulink> may be used
1977 <term>Type of value:</term>
1983 <term>Default value:</term>
1989 <term>Effect if unset:</term>
1992 The web-based actions file editor is disabled.
2000 For the time being, access to the editor can <emphasis>not</emphasis> be
2001 controlled separately by <quote>ACLs</quote> or HTTP authentication,
2002 so that everybody who can access <application>Privoxy</application> (see
2003 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
2004 modify its configuration for all users. So this option is <emphasis>not
2005 recommended</emphasis> for multi-user environments with untrusted users.
2008 Note that you must have compiled <application>Privoxy</application> with
2009 support for this feature, otherwise this option has no effect.
2016 <sect3 renderas="sect4" id="acls"><title>
2017 ACLs: permit-access and deny-access</title>
2018 <anchor id="permit-acces">
2019 <anchor id="deny-acces">
2023 <term>Specifies:</term>
2026 Who can access what.
2031 <term>Type of value:</term>
2034 <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
2035 [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
2038 Where <replaceable class="parameter">src_addr</replaceable> and
2039 <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
2040 DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
2041 <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
2042 values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
2043 destination part are optional.
2048 <term>Default value:</term>
2050 <para><emphasis>Unset</emphasis></para>
2054 <term>Effect if unset:</term>
2057 Don't restrict access further than implied by <literal>listen-address</literal>
2065 Access controls are included at the request of ISPs and systems
2066 administrators, and <emphasis>are not usually needed by individual users</emphasis>.
2067 For a typical home user, it will normally suffice to ensure that
2068 <application>Privoxy</application> only listens on the localhost
2069 (127.0.0.1) or internal (home) network address by means of the
2070 <link linkend="listen-address"><emphasis>listen-address</emphasis></link>
2074 Please see the warnings in the FAQ that this proxy is not intended to be a substitute
2075 for a firewall or to encourage anyone to defer addressing basic security
2079 Multiple ACL lines are OK.
2080 If any ACLs are specified, then the <application>Privoxy</application>
2081 talks only to IP addresses that match at least one <literal>permit-access</literal> line
2082 and don't match any subsequent <literal>deny-access</literal> line. In other words, the
2083 last match wins, with the default being <literal>deny-access</literal>.
2086 If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
2087 for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
2088 that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
2089 of the ultimate target. This is necessary because it may be impossible for the local
2090 <application>Privoxy</application> to determine the IP address of the
2091 ultimate target (that's often what gateways are used for).
2094 You should prefer using IP addresses over DNS names, because the address lookups take
2095 time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
2096 like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
2097 IP addresses, only the first one is used.
2100 Denying access to particular sites by ACL may have undesired side effects
2101 if the site in question is hosted on a machine which also hosts other sites.
2106 <term>Examples:</term>
2109 Explicitly define the default behavior if no ACL and
2110 <literal>listen-address</literal> are set: <quote>localhost</quote>
2111 is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
2112 <emphasis>all</emphasis> destination addresses are OK:
2116 permit-access localhost
2120 Allow any host on the same class C subnet as www.privoxy.org access to
2121 nothing but www.example.com:
2125 permit-access www.privoxy.org/24 www.example.com/32
2129 Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
2130 with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
2134 permit-access 192.168.45.64/26
2135 deny-access 192.168.45.73 www.dirty-stuff.example.com
2143 <sect3 renderas="sect4" id="buffer-limit"><title>buffer-limit</title>
2147 <term>Specifies:</term>
2150 Maximum size of the buffer for content filtering.
2155 <term>Type of value:</term>
2157 <para>Size in Kbytes</para>
2161 <term>Default value:</term>
2167 <term>Effect if unset:</term>
2170 Use a 4MB (4096 KB) limit.
2178 For content filtering, i.e. the <literal>+filter</literal> and
2179 <literal>+deanimate-gif</literal> actions, it is necessary that
2180 <application>Privoxy</application> buffers the entire document body.
2181 This can be potentially dangerous, since a server could just keep sending
2182 data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
2186 When a document buffer size reaches the <literal>buffer-limit</literal>, it is
2187 flushed to the client unfiltered and no further attempt to
2188 filter the rest of the document is made. Remember that there may be multiple threads
2189 running, which might require up to <literal>buffer-limit</literal> Kbytes
2190 <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
2200 <!-- ~ End section ~ -->
2203 <!-- ~~~~~ New section ~~~~~ -->
2205 <sect2 id="forwarding">
2206 <title>Forwarding</title>
2209 This feature allows routing of HTTP requests through a chain of
2211 It can be used to better protect privacy and confidentiality when
2212 accessing specific domains by routing requests to those domains
2213 through an anonymous public proxy (see e.g. <ulink
2214 url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
2215 Or to use a caching proxy to speed up browsing. Or chaining to a parent
2216 proxy may be necessary because the machine that <application>Privoxy</application>
2217 runs on has no direct Internet access.
2221 Also specified here are SOCKS proxies. <application>Privoxy</application>
2222 supports the SOCKS 4 and SOCKS 4A protocols.
2225 <sect3 renderas="sect4" id="forward"><title>forward</title>
2228 <term>Specifies:</term>
2231 To which parent HTTP proxy specific requests should be routed.
2236 <term>Type of value:</term>
2239 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2240 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2243 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2244 chapter on domain matching in the <filename>default.action</filename> file),
2245 <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
2246 as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
2247 <quote>no forwarding</quote>, and the optional
2248 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
2249 values from 1 to 64535
2254 <term>Default value:</term>
2256 <para><emphasis>Unset</emphasis></para>
2260 <term>Effect if unset:</term>
2263 Don't use parent HTTP proxies.
2271 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2272 forwarded to another HTTP proxy but are made directly to the web servers.
2275 Multiple lines are OK, they are checked in sequence, and the last match wins.
2280 <term>Examples:</term>
2283 Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
2287 forward .* anon-proxy.example.org:8080
2292 Everything goes to our example ISP's caching proxy, except for requests
2293 to that ISP's sites:
2297 forward .*. caching-proxy.example-isp.net:8000
2298 forward .example-isp.net .
2306 <sect3 renderas="sect4" id="socks"><title>
2307 forward-socks4 and forward-socks4a</title>
2308 <anchor id="forward-socks4">
2309 <anchor id="forward-socks4a">
2313 <term>Specifies:</term>
2316 Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
2321 <term>Type of value:</term>
2324 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2325 <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
2326 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2329 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2330 chapter on domain matching in the <filename>default.action</filename> file),
2331 <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
2332 are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
2333 may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
2334 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
2339 <term>Default value:</term>
2341 <para><emphasis>Unset</emphasis></para>
2345 <term>Effect if unset:</term>
2348 Don't use SOCKS proxies.
2356 Multiple lines are OK, they are checked in sequence, and the last match wins.
2359 The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
2360 is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
2361 server, while in SOCKS 4 it happens locally.
2364 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2365 forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
2371 <term>Examples:</term>
2374 From the company example.com, direct connections are made to all
2375 <quote>internal</quote> domains, but everything outbound goes through
2376 their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
2381 forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
2382 forward .example.com .
2386 A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
2390 forward-socks4 .*. socks-gw.example.com:1080 .
2398 <sect3 renderas="sect4" id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>
2401 If you have links to multiple ISPs that provide various special content
2402 only to their subscribers, you can configure multiple <application>Privoxies</application>
2403 which have connections to the respective ISPs to act as forwarders to each other, so that
2404 <emphasis>your</emphasis> users can see the internal content of all ISPs.
2408 Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
2409 isp-b.net. Both run <application>Privoxy</application>. Their forwarding
2410 configuration can look like this:
2420 forward .isp-b.net host-b:8118
2431 forward .isp-a.net host-a:8118
2436 Now, your users can set their browser's proxy to use either
2437 host-a or host-b and be able to browse the internal content
2438 of both isp-a and isp-b.
2442 If you intend to chain <application>Privoxy</application> and
2443 <application>squid</application> locally, then chain as
2444 <literal>browser -> squid -> privoxy</literal> is the recommended way.
2448 Assuming that <application>Privoxy</application> and <application>squid</application>
2449 run on the same box, your squid configuration could then look like this:
2454 # Define Privoxy as parent proxy (without ICP)
2455 cache_peer 127.0.0.1 parent 8118 7 no-query
2457 # Define ACL for protocol FTP
2460 # Do not forward FTP requests to Privoxy
2461 always_direct allow ftp
2463 # Forward all the rest to Privoxy
2464 never_direct allow all</screen>
2468 You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
2469 Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
2476 <!-- ~ End section ~ -->
2479 <!-- ~~~~~ New section ~~~~~ -->
2481 <sect2 id="windows-gui">
2482 <title>Windows GUI Options</title>
2484 <application>Privoxy</application> has a number of options specific to the
2485 Windows GUI interface:
2488 <anchor id="activity-animation">
2490 If <quote>activity-animation</quote> is set to 1, the
2491 <application>Privoxy</application> icon will animate when
2492 <quote>Privoxy</quote> is active. To turn off, set to 0.
2499 <emphasis>activity-animation 1</emphasis>
2505 <anchor id="log-messages">
2507 If <quote>log-messages</quote> is set to 1,
2508 <application>Privoxy</application> will log messages to the console
2516 <emphasis>log-messages 1</emphasis>
2522 <anchor id="log-buffer-size">
2524 If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
2525 i.e. the amount of memory used for the log messages displayed in the
2526 console window, will be limited to <quote>log-max-lines</quote> (see below).
2530 Warning: Setting this to 0 will result in the buffer to grow infinitely and
2531 eat up all your memory!
2538 <emphasis>log-buffer-size 1</emphasis>
2544 <anchor id="log-max-lines">
2546 <application>log-max-lines</application> is the maximum number of lines held
2547 in the log buffer. See above.
2554 <emphasis>log-max-lines 200</emphasis>
2560 <anchor id="log-highlight-messages">
2562 If <quote>log-highlight-messages</quote> is set to 1,
2563 <application>Privoxy</application> will highlight portions of the log
2564 messages with a bold-faced font:
2571 <emphasis>log-highlight-messages 1</emphasis>
2577 <anchor id="log-font-name">
2579 The font used in the console window:
2586 <emphasis>log-font-name Comic Sans MS</emphasis>
2592 <anchor id="log-font-size">
2594 Font size used in the console window:
2601 <emphasis>log-font-size 8</emphasis>
2607 <anchor id="show-on-task-bar">
2609 <quote>show-on-task-bar</quote> controls whether or not
2610 <application>Privoxy</application> will appear as a button on the Task bar
2618 <emphasis>show-on-task-bar 0</emphasis>
2624 <anchor id="close-button-minimizes">
2626 If <quote>close-button-minimizes</quote> is set to 1, the Windows close
2627 button will minimize <application>Privoxy</application> instead of closing
2628 the program (close with the exit option on the File menu).
2635 <emphasis>close-button-minimizes 1</emphasis>
2641 <anchor id="hide-console">
2643 The <quote>hide-console</quote> option is specific to the MS-Win console
2644 version of <application>Privoxy</application>. If this option is used,
2645 <application>Privoxy</application> will disconnect from and hide the
2653 #<emphasis>hide-console</emphasis>
2662 <!-- ~ End section ~ -->
2666 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
2668 <sect1 id="actions-file"><title>Actions Files</title>
2671 The actions files are used to define what actions
2672 <application>Privoxy</application> takes for which URLs, and thus determine
2673 how ad images, cookies and various other aspects of HTTP content and
2674 transactions are handled, and on which sites (or even parts thereof). There
2675 are three such files included with <application>Privoxy</application> (as of
2676 version 2.9.15), with differing purposes:
2683 <filename>default.action</filename> - is the primary action file
2684 that sets the initial values for all actions. It is intended to
2685 provide a base level of functionality for
2686 <application>Privoxy's</application> array of features. So it is
2687 a set of broad rules that should work reasonably well for users everywhere.
2688 This is the file that the developers are keeping updated, and making
2694 <filename>user.action</filename> - is intended to be for local site
2695 preferences and exceptions. As an example, if your ISP or your bank
2696 has specific requirements, and need special handling, this kind of
2697 thing should go here. This file will not be upgraded.
2702 <filename>standard.action</filename> - is used by the web based editor,
2703 to set various pre-defined sets of rules for the default actions section
2704 in <filename>default.action</filename>. These have increasing levels of
2705 aggressiveness <emphasis>and have no influence on your browsing unless
2706 you select them explicitly in the editor</emphasis>. It is not recommend
2714 The list of actions files to be used are defined in the main configuration
2715 file, and are processed in the order they are defined. The content of these
2716 can all be viewed and edited from <ulink
2717 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2721 An actions file typically has multiple sections. If you want to use
2722 <quote>aliases</quote> in an actions file, you have to place the (optional)
2723 <link linkend="aliases">alias section</link> at the top of that file.
2724 Then comes the default set of rules which will apply universally to all
2725 sites and pages (be <emphasis>very careful</emphasis> with using such a
2726 universal set in <filename>user.action</filename> or any other actions file after
2727 <filename>default.action</filename>, because it will override the result
2728 from consulting any previous file). And then below that,
2729 exceptions to the defined universal policies. You can regard
2730 <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
2731 with the advantage that is a separate file, which makes preserving your
2732 personal settings across <application>Privoxy</application> upgrades easier.
2736 Actions can be used to block anything you want, including ads, banners, or
2737 just some obnoxious URL that you would rather not see. Cookies can be accepted
2738 or rejected, or accepted only during the current browser session (i.e. not
2739 written to disk), content can be modified, JavaScripts tamed, user-tracking
2740 fooled, and much more. See below for a <link linkend="actions">complete list
2744 <!-- ~~~~~ New section ~~~~~ -->
2746 <title>Finding the Right Mix</title>
2748 Note that some <link linkend="actions">actions</link>, like cookie suppression
2749 or script disabling, may render some sites unusable that rely on these
2750 techniques to work properly. Finding the right mix of actions is not always easy and
2751 certainly a matter of personal taste. In general, it can be said that the more
2752 <quote>aggressive</quote> your default settings (in the top section of the
2753 actions file) are, the more exceptions for <quote>trusted</quote> sites you
2754 will have to make later. If, for example, you want to kill popup windows per
2755 default, you'll have to make exceptions from that rule for sites that you
2756 regularly use and that require popups for actually useful content, like maybe
2757 your bank, favorite shop, or newspaper.
2761 We have tried to provide you with reasonable rules to start from in the
2762 distribution actions files. But there is no general rule of thumb on these
2763 things. There just are too many variables, and sites are constantly changing.
2764 Sooner or later you will want to change the rules (and read this chapter again :).
2768 <!-- ~~~~~ New section ~~~~~ -->
2770 <title>How to Edit</title>
2772 The easiest way to edit the actions files is with a browser by
2773 using our browser-based editor, which can be reached from <ulink
2774 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2775 The editor allows both fine-grained control over every single feature on a
2776 per-URL basis, and easy choosing from wholesale sets of defaults like
2777 <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
2781 If you prefer plain text editing to GUIs, you can of course also directly edit the
2782 the actions files. Look at <filename>default.action</filename> which is richly
2788 <sect2 id="actions-apply">
2789 <title>How Actions are Applied to URLs</title>
2791 Actions files are divided into sections. There are special sections,
2792 like the <quote><link linkend="aliases">alias</link></quote> sections which will be discussed later. For now
2793 let's concentrate on regular sections: They have a heading line (often split
2794 up to multiple lines for readability) which consist of a list of actions,
2795 separated by whitespace and enclosed in curly braces. Below that, there
2796 is a list of URL patterns, each on a separate line.
2800 To determine which actions apply to a request, the URL of the request is
2801 compared to all patterns in each action file file. Every time it matches, the list of
2802 applicable actions for the URL is incrementally updated, using the heading
2803 of the section in which the pattern is located. If multiple matches for
2804 the same URL set the same action differently, the last match wins. If not,
2805 the effects are aggregated (e.g. a URL might match both the
2806 <ulink url="actions-file.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>
2807 and <ulink url="actions-file.html#BLOCK"><quote>+block</quote></ulink> actions).
2812 You can trace this process for any given URL by visiting <ulink
2813 url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2817 More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2818 Anatomy of an Action</link>.
2822 <!-- ~~~~~ New section ~~~~~ -->
2823 <sect2 id="af-patterns">
2824 <title>Patterns</title>
2826 Generally, a pattern has the form <literal><domain>/<path></literal>,
2827 where both the <literal><domain></literal> and <literal><path></literal>
2828 are optional. (This is why the pattern <literal>/</literal> matches all URLs).
2833 <term><literal>www.example.com/</literal></term>
2836 is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2837 regardless of which document on that server is requested.
2842 <term><literal>www.example.com</literal></term>
2845 means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2851 <term><literal>www.example.com/index.html</literal></term>
2854 matches only the single document <literal>/index.html</literal>
2855 on <literal>www.example.com</literal>.
2860 <term><literal>/index.html</literal></term>
2863 matches the document <literal>/index.html</literal>, regardless of the domain,
2864 i.e. on <emphasis>any</emphasis> web server.
2869 <term><literal>index.html</literal></term>
2872 matches nothing, since it would be interpreted as a domain name and
2873 there is no top-level domain called <literal>.html</literal>.
2880 <!-- ~~~~~ New section ~~~~~ -->
2881 <sect3><title>The Domain Pattern</title>
2884 The matching of the domain part offers some flexible options: if the
2885 domain starts or ends with a dot, it becomes unanchored at that end.
2891 <term><literal>.example.com</literal></term>
2894 matches any domain that <emphasis>ENDS</emphasis> in
2895 <literal>.example.com</literal>
2900 <term><literal>www.</literal></term>
2903 matches any domain that <emphasis>STARTS</emphasis> with
2904 <literal>www.</literal>
2909 <term><literal>.example.</literal></term>
2912 matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
2913 (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
2920 Additionally, there are wild-cards that you can use in the domain names
2921 themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
2922 stands for zero or more arbitrary characters, <quote>?</quote> stands for
2923 any single character, you can define character classes in square
2924 brackets and all of that can be freely mixed:
2929 <term><literal>ad*.example.com</literal></term>
2932 matches <quote>adserver.example.com</quote>,
2933 <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2938 <term><literal>*ad*.example.com</literal></term>
2941 matches all of the above, and then some.
2946 <term><literal>.?pix.com</literal></term>
2949 matches <literal>www.ipix.com</literal>,
2950 <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2955 <term><literal>www[1-9a-ez].example.c*</literal></term>
2958 matches <literal>www1.example.com</literal>,
2959 <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2960 <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2961 <literal>wwww.example.com</literal>.
2969 <!-- ~ End section ~ -->
2972 <!-- ~~~~~ New section ~~~~~ -->
2973 <sect3><title>The Path Pattern</title>
2976 <application>Privoxy</application> uses Perl compatible regular expressions
2977 (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2982 There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2983 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2984 at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2985 You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2986 useful, which is available on-line at <ulink
2987 url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
2991 Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2992 i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
2993 for the beginning of a line).
2997 Please also note that matching in the path is case
2998 <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
2999 sensitive at any point in the pattern by using the
3000 <quote>(?-i)</quote> switch:
3001 <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
3002 documents whose path starts with <literal>PaTtErN</literal> in
3003 <emphasis>exactly</emphasis> this capitalization.
3009 <!-- ~ End section ~ -->
3012 <!-- ~~~~~ New section ~~~~~ -->
3014 <sect2 id="actions">
3015 <title>Actions</title>
3017 All actions are disabled by default, until they are explicitly enabled
3018 somewhere in an actions file. Actions are turned on if preceded with a
3019 <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
3020 <literal>+action</literal> means <quote>do that action</quote>, e.g.
3021 <literal>+block</literal> means <quote>please block URLs that match the
3022 following patterns</quote>, and <literal>-block</literal> means <quote>don't
3023 block URLs that match the following patterns, even if <literal>+block</literal>
3024 previously applied.</quote>
3029 Again, actions are invoked by placing them on a line, enclosed in curly braces and
3030 separated by whitespace, like in
3031 <literal>{+some-action -some-other-action{some-parameter}}</literal>,
3032 followed by a list of URL patterns, one per line, to which they apply.
3033 Together, the actions line and the following pattern lines make up a section
3034 of the actions file.
3038 There are three classes of actions:
3045 Boolean, i.e the action can only be <quote>enabled</quote> or
3046 <quote>disabled</quote>. Syntax:
3050 +<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
3051 -<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
3054 Example: <literal>+block</literal>
3061 Parameterized, where some value is required in order to enable this type of action.
3066 +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
3067 # overwriting parameter from previous match if necessary
3068 -<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
3071 Note that if the URL matches multiple positive forms of a parameterized action,
3072 the last match wins, i.e. the params from earlier matches are simply ignored.
3075 Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>
3081 Multi-value. These look exactly like parameterized actions,
3082 but they behave differently: If the action applies multiple times to the
3083 same URL, but with different parameters, <emphasis>all</emphasis> the parameters
3084 from <emphasis>all</emphasis> matches are remembered. This is used for actions
3085 that can be executed for the same request repeatedly, like adding multiple
3086 headers, or filtering through multiple filters. Syntax:
3090 +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
3091 -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
3092 # If it was the last one left, disable the action.
3093 <replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
3096 Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
3097 <literal>+filter{html-annoyances}</literal>
3105 If nothing is specified in any actions file, no <quote>actions</quote> are
3106 taken. So in this case <application>Privoxy</application> would just be a
3107 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
3108 privacy and blocking features you need (although the provided default actions
3109 files will give a good starting point).
3113 Later defined actions always over-ride earlier ones. So exceptions
3114 to any rules you make, should come in the latter part of the file (or
3115 in a file that is processed later when using multiple actions files). For
3116 multi-valued actions, the actions are applied in the order they are specified.
3117 Actions files are processed in the order they are defined in
3118 <filename>config</filename> (the default installation has three actions
3119 files). It also quite possible for any given URL pattern to match more than
3120 one pattern and thus more than one set of actions!
3123 <!-- start actions listing -->
3125 The list of valid <application>Privoxy</application> actions are:
3129 <!-- ********************************************************** -->
3130 <!-- Please note the below defined actions use id's that are -->
3131 <!-- probably linked from other places, so please don't change. -->
3133 <!-- ********************************************************** -->
3136 <!-- ~~~~~ New section ~~~~~ -->
3138 <sect3 renderas="sect4" id="add-header">
3139 <title><emphasis>add-header</emphasis></title>
3143 <term>Typical use:</term>
3145 <para>Confuse log analysis, custom applications</para>
3150 <term>Effect:</term>
3153 Sends a user defined HTTP header to the web server.
3160 <!-- boolean, parameterized, Multi-value -->
3162 <para>Multi-value.</para>
3167 <term>Parameter:</term>
3170 Any string value is possible. Validity of the defined HTTP headers is not checked.
3171 It is recommended that you use the <quote><literal>X-</literal></quote> prefix
3181 This action may be specified multiple times, in order to define multiple
3182 headers. This is rarely needed for the typical user. If you don't know what
3183 <quote>HTTP headers</quote> are, you definitely don't need to worry about this
3190 <term>Example usage:</term>
3193 <screen>+add-header{X-User-Tracking: sucks}</screen>
3201 <!-- ~~~~~ New section ~~~~~ -->
3202 <sect3 renderas="sect4" id="block">
3203 <title><emphasis>block</emphasis></title>
3207 <term>Typical use:</term>
3209 <para>Block ads or other obnoxious content</para>
3214 <term>Effect:</term>
3217 Requests for URLs to which this action applies are blocked, i.e. the requests are not
3218 forwarded to the remote server, but answered locally with a substitute page or image,
3219 as determined by the <literal><link linkend="handle-as-image">handle-as-image</link></literal>
3220 and <literal><link linkend="set-image-blocker">set-image-blocker</link></literal> actions.
3227 <!-- boolean, parameterized, Multi-value -->
3229 <para>Boolean.</para>
3234 <term>Parameter:</term>
3244 <application>Privoxy</application> sends a special <quote>BLOCKED</quote> page
3245 for requests to blocked pages. This page contains links to find out why the request
3246 was blocked, and a click-through to the blocked content (the latter only if compiled with the
3247 force feature enabled). The <quote>BLOCKED</quote> page adapts to the available
3248 screen space -- it displays full-blown if space allows, or miniaturized and text-only
3249 if loaded into a small frame or window. If you are using <application>Privoxy</application>
3250 right now, you can take a look at the
3251 <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
3255 A very important exception occurs if <emphasis>both</emphasis>
3256 <literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
3257 apply to the same request: it will then be replaced by an image. If
3258 <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
3259 (see below) also applies, the type of image will be determined by its parameter,
3260 if not, the standard checkerboard pattern is sent.
3263 It is important to understand this process, in order
3264 to understand how <application>Privoxy</application> deals with
3265 ads and other unwanted content.
3268 The <literal><link linkend="filter">filter</link></literal>
3269 action can perform a very similar task, by <quote>blocking</quote>
3270 banner images and other content through rewriting the relevant URLs in the
3271 document's HTML source, so they don't get requested in the first place.
3272 Note that this is a totally different technique, and it's easy to confuse the two.
3278 <term>Example usage (section):</term>
3281 <screen>{+block} # Block and replace with "blocked" page
3282 .nasty-stuff.example.com
3284 {+block +handle-as-image} # Block and replace with image
3295 <!-- ~~~~~ New section ~~~~~ -->
3296 <sect3 renderas="sect4" id="crunch-incoming-cookies">
3297 <title><emphasis>crunch-incoming-cookies</emphasis></title>
3301 <term>Typical use:</term>
3304 Prevent the web server from setting any cookies on your system
3310 <term>Effect:</term>
3313 Deletes any <quote>Set-Cookie:</quote> HTTP headers from server replies.
3320 <!-- Boolean, Parameterized, Multi-value -->
3322 <para>Boolean.</para>
3327 <term>Parameter:</term>
3339 This action is only concerned with <emphasis>incoming</emphasis> cookies. For
3340 <emphasis>outgoing</emphasis> cookies, use
3341 <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>.
3342 Use <emphasis>both</emphasis> to disable cookies completely.
3345 It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3346 with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3347 since it would prevent the session cookies from being set.
3353 <term>Example usage:</term>
3356 <screen>+crunch-incoming-cookies</screen>
3364 <!-- ~~~~~ New section ~~~~~ -->
3365 <sect3 renderas="sect4" id="crunch-outgoing-cookies">
3366 <title><emphasis>crunch-outgoing-cookies</emphasis></title>
3370 <term>Typical use:</term>
3373 Prevent the web server from reading any cookies from your system
3379 <term>Effect:</term>
3382 Deletes any <quote>Cookie:</quote> HTTP headers from client requests.
3389 <!-- Boolean, Parameterized, Multi-value -->
3391 <para>Boolean.</para>
3396 <term>Parameter:</term>
3408 This action is only concerned with <emphasis>outgoing</emphasis> cookies. For
3409 <emphasis>incoming</emphasis> cookies, use
3410 <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal>.
3411 Use <emphasis>both</emphasis> to disable cookies completely.
3414 It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
3415 with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
3416 since it would prevent the session cookies from being read.
3422 <term>Example usage:</term>
3425 <screen>+crunch-outgoing-cookies</screen>
3434 <!-- ~~~~~ New section ~~~~~ -->
3435 <sect3 renderas="sect4" id="deanimate-gifs">
3436 <title><emphasis>deanimate-gifs</emphasis></title>
3440 <term>Typical use:</term>
3442 <para>Stop those annoying, distracting animated GIF images.</para>
3447 <term>Effect:</term>
3450 De-animate GIF animations, i.e. reduce them to their first or last image.
3457 <!-- boolean, parameterized, Multi-value -->
3459 <para>Parameterized.</para>
3464 <term>Parameter:</term>
3467 <quote>last</quote> or <quote>first</quote>
3476 This will also shrink the images considerably (in bytes, not pixels!). If
3477 the option <quote>first</quote> is given, the first frame of the animation
3478 is used as the replacement. If <quote>last</quote> is given, the last
3479 frame of the animation is used instead, which probably makes more sense for
3480 most banner animations, but also has the risk of not showing the entire
3481 last frame (if it is only a delta to an earlier frame).
3484 You can safely use this action with patterns that will also match non-GIF
3485 objects, because no attempt will be made at anything that doesn't look like
3492 <term>Example usage:</term>
3495 <screen>+deanimate-gifs{last}</screen>
3502 <!-- ~~~~~ New section ~~~~~ -->
3503 <sect3 renderas="sect4" id="downgrade-http-version">
3504 <title><emphasis>downgrade-http-version</emphasis></title>
3508 <term>Typical use:</term>
3510 <para>Work around (very rare) problems with HTTP/1.1</para>
3515 <term>Effect:</term>
3518 Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0.
3525 <!-- boolean, parameterized, Multi-value -->
3527 <para>Boolean.</para>
3532 <term>Parameter:</term>
3544 This is a left-over from the time when <application>Privoxy</application>
3545 didn't support important HTTP/1.1 features well. It is left here for the
3546 unlikely case that you experience HTTP/1.1 related problems with some server
3547 out there. Not all (optional) HTTP/1.1 features are supported yet, so there
3548 is a chance you might need this action.
3554 <term>Example usage (section):</term>
3557 <screen>{+downgrade-http-version}
3558 problem-host.example.com</screen>
3566 <!-- ~~~~~ New section ~~~~~ -->
3567 <sect3 renderas="sect4" id="fast-redirects">
3568 <title><emphasis>fast-redirects</emphasis></title>
3572 <term>Typical use:</term>
3574 <para>Fool some click-tracking scripts and speed up indirect links</para>
3579 <term>Effect:</term>
3582 Cut off all but the last valid URL from requests.
3589 <!-- boolean, parameterized, Multi-value -->
3591 <para>Boolean.</para>
3596 <term>Parameter:</term>
3608 Many sites, like yahoo.com, don't just link to other sites. Instead, they
3609 will link to some script on their own servers, giving the destination as a
3610 parameter, which will then redirect you to the final target. URLs
3611 resulting from this scheme typically look like:
3612 <emphasis>http://some.place/click-tracker.cgi?target=http://some.where.else</emphasis>.
3615 Sometimes, there are even multiple consecutive redirects encoded in the
3616 URL. These redirections via scripts make your web browsing more traceable,
3617 since the server from which you follow such a link can see where you go
3618 to. Apart from that, valuable bandwidth and time is wasted, while your
3619 browser ask the server for one redirect after the other. Plus, it feeds
3623 This feature is currently not very smart and is scheduled for improvement.
3624 It is likely to break some sites. You should expect to need possibly
3625 many exceptions to this action, if it is enabled by default in
3626 <filename>default.action</filename>. Some sites just don't work without
3633 <term>Example usage:</term>
3636 <screen>{+fast-redirects}</screen>
3645 <!-- ~~~~~ New section ~~~~~ -->
3646 <sect3 renderas="sect4" id="filter">
3647 <title><emphasis>filter</emphasis></title>
3651 <term>Typical use:</term>
3653 <para>Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc.</para>
3658 <term>Effect:</term>
3661 Text documents, including HTML and JavaScript, to which this action applies, are filtered on-the-fly
3662 through the specified regular expression based substitutions.
3669 <!-- boolean, parameterized, Multi-value -->
3671 <para>Parameterized.</para>
3676 <term>Parameter:</term>
3679 The name of a filter, as defined in the <link linkend="filter-file">filter file</link>
3680 (typically <filename>default.filter</filename>, set by the
3681 <literal><link linkend="filterfile">filterfile</link></literal>
3682 option in the <link linkend="config">config file</link>)
3691 For your convenience, there are a bunch of pre-defined filters available
3692 in the distribution filter file that you can use. See the example below for
3696 This is potentially a very powerful feature! But <quote>rolling your own</quote>
3697 filters requires a knowledge of regular expressions and HTML.
3700 Filtering requires buffering the page content, which may appear to
3701 slow down page rendering since nothing is displayed until all content has
3702 passed the filters. (It does not really take longer, but seems that way
3703 since the page is not incrementally displayed.) This effect will be more
3704 noticeable on slower connections.
3707 At this time, <application>Privoxy</application> cannot (yet!) uncompress compressed
3708 documents. If you want filtering to work on all documents, even those that
3709 would normally be sent compressed, use the
3710 <literal><link linkend="prevent-compression">prevent-compression</link></literal>
3711 action in conjunction with <literal>filter</literal>.
3714 Filtering can achieve some of the effects as the
3715 <literal><link linkend="block">block</link></literal>
3716 action, i.e. it can be used to block ads and banners.
3719 <link linkend="contact">Feedback</link> with suggestions for new or improved filters is particularly
3726 <term>Example usage (with filters from the distribution <filename>default.filter</filename> file):</term>
3729 <anchor id="filter-html-annoyances">
3730 <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
3733 <anchor id="filter-js-annoyances">
3734 <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
3737 <anchor id="filter-banners-by-size">
3738 <screen>+filter{banners-by-size} # Kill banners by size (<emphasis>very</emphasis> efficient!)</screen>
3741 <anchor id="filter-content-cookies">
3742 <screen>+filter{content-cookies} # Kill cookies that come sneaking in the HTML or JS content</screen>
3745 <anchor id="filter-popups">
3746 <screen>+filter{popups} # Kill all popups in JS and HTML</screen>
3749 <anchor id="filter-webbugs">
3750 <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
3753 <anchor id="filter-fun">
3754 <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
3757 <anchor id="filter-frameset-borders">
3758 <screen>+filter{frameset-borders} # Give frames a border and make them resizeable</screen>
3761 <anchor id="filter-refresh-tags">
3762 <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</screen>
3765 <anchor id="filter-nimda">
3766 <screen>+filter{nimda} # Remove Nimda (virus) code.</screen>
3769 <anchor id="filter-shockwave-flash">
3770 <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
3773 <anchor id="filter-crude-parental">
3774 <screen>+filter{crude-parental} # Kill all web pages that contain the words "sex" or "warez"</screen>
3782 <!-- ~~~~~ New section ~~~~~ -->
3783 <sect3 renderas="sect4" id="handle-as-image">
3784 <title><emphasis>handle-as-image</emphasis></title>
3788 <term>Typical use:</term>
3790 <para>Mark URLs as belonging to images (so they'll be replaced by images <emphasis>if they get blocked</emphasis>)</para>
3795 <term>Effect:</term>
3798 This action alone doesn't do anything noticeable. It just marks URLs as images.
3799 If the <literal><link linkend="block">block</link></literal> action <emphasis>also applies</emphasis>,
3800 the presence or absence of this mark decides whether an HTML <quote>blocked</quote>
3801 page, or a replacement image (as determined by the <literal><link
3802 linkend="set-image-blocker">set-image-blocker</link></literal> action) will be sent to the
3803 client as a substitute for the blocked content.
3810 <!-- Boolean, Parameterized, Multi-value -->
3812 <para>Boolean.</para>
3817 <term>Parameter:</term>
3829 The below generic example section is actually part of <filename>default.action</filename>.
3830 It marks all URLs with well-known image file name extensions as images and should
3834 Users will probably only want to use the handle-as-image action in conjunction with
3835 <literal><link linkend="block">block</link></literal>, to block sources of banners, whose URLs don't
3836 reflect the file type, like in the second example section.
3839 Note that you cannot treat HTML pages as images in most cases. For instance, (inline) ad
3840 frames require an HTML page to be sent, or they won't display properly.
3841 Forcing <literal>handle-as-image</literal> in this situation will not replace the
3842 ad frame with an image, but lead to error messages.
3848 <term>Example usage (sections):</term>
3851 <screen># Generic image extensions:
3854 /.*\.(gif|jpg|jpeg|png|bmp|ico)$
3856 # These don't look like images, but they're banners and should be
3857 # blocked as images:
3859 {+block +handle-as-image}
3860 some.nasty-banner-server.com/junk.cgi?output=trash
3862 # Banner source! Who cares if they also have non-image content?
3872 <!-- ~~~~~ New section ~~~~~ -->
3873 <sect3 renderas="sect4" id="hide-forwarded-for-headers">
3874 <title><emphasis>hide-forwarded-for-headers</emphasis></title>
3878 <term>Typical use:</term>
3880 <para>Improve privacy by hiding the true source of the request</para>
3885 <term>Effect:</term>
3888 Deletes any existing <quote>X-Forwarded-for:</quote> HTTP header from client requests,
3889 and prevents adding a new one.
3896 <!-- Boolean, Parameterized, Multi-value -->
3898 <para>Boolean.</para>
3903 <term>Parameter:</term>
3915 It is fairly safe to leave this on.
3918 This action is scheduled for improvement: It should be able to generate forged
3919 <quote>X-Forwarded-for:</quote> headers using random IP addresses from a specified network,
3920 to make successive requests from the same client look like requests from a pool of different
3921 users sharing the same proxy.
3927 <term>Example usage:</term>
3930 <screen>+hide-forwarded-for-headers</screen>
3938 <!-- ~~~~~ New section ~~~~~ -->
3939 <sect3 renderas="sect4" id="hide-from-header">
3940 <title><emphasis>hide-from-header</emphasis></title>
3944 <term>Typical use:</term>
3946 <para>Keep your (old and ill) browser from telling web servers your email address</para>
3951 <term>Effect:</term>
3954 Deletes any existing <quote>From:</quote> HTTP header, or replaces it with the
3962 <!-- Boolean, Parameterized, Multi-value -->
3964 <para>Parameterized.</para>
3969 <term>Parameter:</term>
3972 Keyword: <quote>block</quote>, or any user defined value.
3981 The keyword <quote>block</quote> will completely remove the header
3982 (not to be confused with the <literal><link linkend="block">block</link></literal>
3986 Alternately, you can specify any value you prefer to be sent to the web
3987 server. If you do, it is a matter of fairness not to use any address that
3988 is actually used by a real person.
3991 This action is rarely needed, as modern web browsers don't send
3992 <quote>From:</quote> headers anymore.
3998 <term>Example usage:</term>
4001 <screen>+hide-from-header{block}</screen> or
4002 <screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
4010 <!-- ~~~~~ New section ~~~~~ -->
4011 <sect3 renderas="sect4" id="hide-referrer">
4012 <title><emphasis>hide-referrer</emphasis></title>
4013 <anchor id="hide-referer">
4016 <term>Typical use:</term>
4018 <para>Conceal which link you followed to get to a particular site</para>
4023 <term>Effect:</term>
4026 Deletes the <quote>Referer:</quote> (sic) HTTP header from the client request,
4027 or replaces it with a forged one.
4034 <!-- Boolean, Parameterized, Multi-value -->
4036 <para>Parameterized.</para>
4041 <term>Parameter:</term>
4045 <para><quote>block</quote> to delete the header completely.</para>
4048 <para><quote>forge</quote> to pretend to be coming from the homepage of the server we are talking to.</para>
4051 <para>Any other string to set a user defined referrer.</para>
4061 <quote>forge</quote> is the preferred option here, since some servers will
4062 not send images back otherwise, in an attempt to prevent their valuable
4063 content from being embedded elsewhere (and hence, without being surrounded
4064 by <emphasis>their</emphasis> banners).
4067 <literal>hide-referer</literal> is an alternate spelling of
4068 <literal>hide-referrer</literal> and the two can be can be freely
4069 substituted with each other. (<quote>referrer</quote> is the
4070 correct English spelling, however the HTTP specification has a bug - it
4071 requires it to be spelled as <quote>referer</quote>.)
4077 <term>Example usage:</term>
4080 <screen>+hide-referrer{forge}</screen> or
4081 <screen>+hide-referrer{http://www.yahoo.com/}</screen>
4089 <!-- ~~~~~ New section ~~~~~ -->
4090 <sect3 renderas="sect4" id="hide-user-agent">
4091 <title><emphasis>hide-user-agent</emphasis></title>
4095 <term>Typical use:</term>
4097 <para>Conceal your type of browser and client operating system</para>
4102 <term>Effect:</term>
4105 Replaces the value of the <quote>User-Agent:</quote> HTTP header
4106 in client requests with the specified value.
4113 <!-- Boolean, Parameterized, Multi-value -->
4115 <para>Parameterized.</para>
4120 <term>Parameter:</term>
4123 Any user-defined string.
4133 This breaks many web sites that depend on looking at this header in order
4134 to customize their content for different browsers (which, by the
4135 way, is <emphasis>NOT</emphasis> a <ulink
4136 url="http://www.javascriptkit.com/javaindex.shtml">smart way to do
4141 Using this action in multi-user setups or wherever different types of
4142 browsers will access the same <application>Privoxy</application> is
4143 <emphasis>not recommended</emphasis>. In single-user, single-browser
4144 setups, you might use it to delete your OS version information from
4145 the headers, because it is an invitation to exploit known bugs for your
4146 OS. It is also occasionally useful to forge this in order to access
4147 sites that won't let you in otherwise (though there may be a good
4148 reason in some cases). Example of this: some MSN sites will not
4149 let <application>Mozilla</application> enter, yet forging to a
4150 <application>Netscape 6.1</application> user-agent works just fine.
4151 (Must be just a silly MS goof, I'm sure :-).
4154 This action is scheduled for improvement.
4160 <term>Example usage:</term>
4163 <screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
4171 <!-- ~~~~~ New section ~~~~~ -->
4172 <sect3 renderas="sect4" id="kill-popups">
4173 <title><emphasis>kill-popups<anchor id="kill-popup"></emphasis></title>
4177 <term>Typical use:</term>
4179 <para>Eliminate those annoying pop-up windows</para>
4184 <term>Effect:</term>
4187 While loading the document, replace JavaScript code that opens
4188 pop-up windows with (syntactically neutral) dummy code on the fly.
4195 <!-- Boolean, Parameterized, Multi-value -->
4197 <para>Boolean.</para>
4202 <term>Parameter:</term>
4214 This action is easily confused with the built-in, hardwired <literal><link linkend="filter">filter</link></literal>
4215 action, but there are important differences: For <literal>kill-popups</literal>,
4216 the document need not be buffered, so it can be incrementally rendered while
4217 downloading. But <literal>kill-popups</literal> doesn't catch as many pop-ups as
4219 linkend="filter">filter</link>{<replaceable>popups</replaceable>}</literal>
4223 Think of it as a fast and efficient replacement for a filter that you
4224 can use if you don't want any filtering at all. Note that it doesn't make
4225 sense to combine it with any <literal><link linkend="filter">filter</link></literal> action,
4226 since as soon as one <literal><link linkend="filter">filter</link></literal> applies,
4227 the whole document needs to be buffered anyway, which destroys the advantage of
4228 the <literal>kill-popups</literal> action over it's filter equivalent.
4231 Killing all pop-ups is a dangerous business. Many shops and banks rely on
4232 pop-ups to display forms, shopping carts etc, and killing only the unwanted pop-ups
4233 would require artificial intelligence in <application>Privoxy</application>.
4234 If the only kind of pop-ups that you want to kill are exit consoles (those
4235 <emphasis>really nasty</emphasis> windows that appear when you close an other
4236 one), you might want to use
4238 linkend="filter">filter</link>{<replaceable>js-annoyances</replaceable>}</literal>
4244 An alternate spelling is <literal>+kill-popup</literal>, which is
4252 <term>Example usage:</term>
4254 <para><screen>+kill-popups</screen></para>
4261 <!-- ~~~~~ New section ~~~~~ -->
4262 <sect3 renderas="sect4" id="limit-connect">
4263 <title><emphasis>limit-connect</emphasis></title>
4267 <term>Typical use:</term>
4269 <para>Prevent abuse of <application>Privoxy</application> as a TCP proxy relay</para>
4274 <term>Effect:</term>
4277 Specifies to which ports HTTP CONNECT requests are allowable.
4284 <!-- Boolean, Parameterized, Multi-value -->
4286 <para>Parameterized.</para>
4291 <term>Parameter:</term>
4294 A comma-separated list of ports or port ranges (the latter using dashes, with the minimum
4295 defaulting to 0 and the maximum to 65K).
4304 By default, i.e. if no <literal>limit-connect</literal> action applies,
4305 <application>Privoxy</application> only allows HTTP CONNECT
4306 requests to port 443 (the standard, secure HTTPS port). Use
4307 <literal>limit-connect</literal> if more fine-grained control is desired
4308 for some or all destinations.
4311 The CONNECT methods exists in HTTP to allow access to secure websites
4312 (<quote>https://</quote> URLs) through proxies. It works very simply:
4313 the proxy connects to the server on the specified port, and then
4314 short-circuits its connections to the client and to the remote server.
4315 This can be a big security hole, since CONNECT-enabled proxies can be
4316 abused as TCP relays very easily.
4319 If you don't know what any of this means, there probably is no reason to
4320 change this one, since the default is already very restrictive.
4326 <term>Example usages:</term>
4328 <!-- I had trouble getting the spacing to look right in my browser -->
4329 <!-- I probably have the wrong font setup, bollocks. -->
4330 <!-- Apparently the emphasis tag uses a proportional font no matter what -->
4332 <screen>+limit-connect{443} # This is the default and need not be specified.
4333 +limit-connect{80,443} # Ports 80 and 443 are OK.
4334 +limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
4335 +limit-connect{-} # All ports are OK (gaping security hole!)</screen>
4342 <!-- ~~~~~ New section ~~~~~ -->
4343 <sect3 renderas="sect4" id="prevent-compression">
4344 <title><emphasis>prevent-compression</emphasis></title>
4348 <term>Typical use:</term>
4351 Ensure that servers send the content uncompressed, so it can be
4352 passed through <literal><link linkend="filter">filter</link></literal>s
4358 <term>Effect:</term>
4361 Adds a header to the request that asks for uncompressed transfer.
4368 <!-- Boolean, Parameterized, Multi-value -->
4370 <para>Boolean.</para>
4375 <term>Parameter:</term>
4387 More and more websites send their content compressed by default, which
4388 is generally a good idea and saves bandwidth. But for the <literal><link
4389 linkend="filter">filter</link></literal>, <literal><link linkend="deanimate-gifs">deanimate-gifs</link></literal>
4390 and <literal><link linkend="kill-popups">kill-popups</link></literal> actions to work,
4391 <application>Privoxy</application> needs access to the uncompressed data.
4392 Unfortunately, <application>Privoxy</application> can't yet(!) uncompress, filter, and
4393 re-compress the content on the fly. So if you want to ensure that all websites, including
4394 those that normally compress, can be filtered, you need to use this action.
4397 This will slow down transfers from those websites, though. If you use any of the above-mentioned
4398 actions, you will typically want to use <literal>prevent-compression</literal> in conjunction
4402 Note that some (rare) ill-configured sites don't handle requests for uncompressed
4403 documents correctly (they send an empty document body). If you use <literal>prevent-compression</literal>
4404 per default, you'll have to add exceptions for those sites. See the example for how to do that.
4410 <term>Example usage (sections):</term>
4413 <screen># Set default:
4415 {+prevent-compression}
4418 # Make exceptions for ill sites:
4420 {-prevent-compression}
4422 www.pclinuxonline.com</screen>
4431 <!-- ~~~~~ New section ~~~~~ -->
4432 <sect3 renderas="sect4" id="send-vanilla-wafer">
4433 <title><emphasis>send-vanilla-wafer</emphasis></title>
4437 <term>Typical use:</term>
4440 Feed log analysis scripts with useless data.
4446 <term>Effect:</term>
4449 Sends a cookie with each request stating that you do not accept any copyright
4450 on cookies sent to you, and asking the site operator not to track you.
4457 <!-- Boolean, Parameterized, Multi-value -->
4459 <para>Boolean.</para>
4464 <term>Parameter:</term>
4476 The vanilla wafer is a (relatively) unique header and could conceivably be used to track you.
4479 This action is rarely used and not enabled in the default configuration.
4485 <term>Example usage:</term>
4488 <screen>+send-vanilla-wafer</screen>
4497 <!-- ~~~~~ New section ~~~~~ -->
4498 <sect3 renderas="sect4" id="send-wafer">
4499 <title><emphasis>send-wafer</emphasis></title>
4503 <term>Typical use:</term>
4506 Send custom cookies or feed log analysis scripts with even more useless data.
4512 <term>Effect:</term>
4515 Sends a custom, user-defined cookie with each request.
4522 <!-- Boolean, Parameterized, Multi-value -->
4524 <para>Multi-value.</para>
4529 <term>Parameter:</term>
4532 A string of the form <quote><replaceable class="option">name</replaceable>=<replaceable
4533 class="parameter">value</replaceable></quote>.
4542 Being multi-valued, multiple instances of this action can apply to the same request,
4543 resulting in multiple cookies being sent.
4546 This action is rarely used and not enabled in the default configuration.
4551 <term>Example usage (section):</term>
4554 <screen>{+send-wafer{UsingPrivoxy=true}}
4555 my-internal-testing-server.void</screen>
4563 <!-- ~~~~~ New section ~~~~~ -->
4564 <sect3 renderas="sect4" id="session-cookies-only">
4565 <title><emphasis>session-cookies-only</emphasis></title>
4569 <term>Typical use:</term>
4572 Allow only temporary <quote>session</quote> cookies (for the current browser session <emphasis>only</emphasis>).
4578 <term>Effect:</term>
4581 Deletes the <quote>expires</quote> field from <quote>Set-Cookie:</quote> server headers.
4582 Most browsers will not store such cookies permanently and forget them in between sessions.
4589 <!-- Boolean, Parameterized, Multi-value -->
4591 <para>Boolean.</para>
4596 <term>Parameter:</term>
4608 This is less strict than <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> /
4609 <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal> and allows you to browse
4610 websites that insist or rely on setting cookies, without compromising your privacy too badly.
4613 Most browsers will not permanently store cookies that have been processed by
4614 <literal>session-cookies-only</literal> and will forget about them between sessions.
4615 This makes profiling cookies useless, but won't break sites which require cookies so
4616 that you can log in for transactions. This is generally turned on for all
4617 sites, and is the recommended setting.
4620 It makes <emphasis>no sense at all</emphasis> to use <literal>session-cookies-only</literal>
4621 together with <literal><link linkend="crunch-incoming-cookies">crunch-incoming-cookies</link></literal> or
4622 <literal><link linkend="crunch-outgoing-cookies">crunch-outgoing-cookies</link></literal>. If you do, cookies
4623 will be plainly killed.
4626 Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
4627 field. If you use an exotic browser, you might want to try it out to be sure.
4633 <term>Example usage:</term>
4636 <screen>+session-cookies-only</screen>
4644 <!-- ~~~~~ New section ~~~~~ -->
4645 <sect3 renderas="sect4" id="set-image-blocker">
4646 <title><emphasis>set-image-blocker</emphasis></title>
4650 <term>Typical use:</term>
4652 <para>Choose the replacement for blocked images</para>
4657 <term>Effect:</term>
4660 This action alone doesn't do anything noticeable. If <emphasis>both</emphasis>
4661 <literal><link linkend="block">block</link></literal> <emphasis>and</emphasis> <literal><link
4662 linkend="handle-as-image">handle-as-image</link></literal> <emphasis>also</emphasis>
4663 apply, i.e. if the request is to be blocked as an image,
4664 <emphasis>then</emphasis> the parameter of this action decides what will be
4665 sent as a replacement.
4672 <!-- Boolean, Parameterized, Multi-value -->
4674 <para>Parameterized.</para>
4679 <term>Parameter:</term>
4684 <quote>pattern</quote> to send a built-in checkerboard pattern image. The image is visually
4685 decent, scales very well, and makes it obvious where banners were busted.
4690 <quote>blank</quote> to send a built-in transparent image. This makes banners disappear
4691 completely, but makes it hard to detect where <application>Privoxy</application> has blocked
4692 images on a given page and complicates troubleshooting if <application>Privoxy</application>
4693 has blocked innocent images, like navigation icons.
4698 <quote><replaceable class="parameter">target-url</replaceable></quote> to
4699 send a redirect to <replaceable class="parameter">target-url</replaceable>. You can redirect
4700 to any image anywhere, even in your local filesystem (via <quote>file:///</quote> URL).
4703 A good application of redirects is to use special <application>Privoxy</application>-built-in
4704 URLs, which send the built-in images, as <replaceable class="parameter">target-url</replaceable>.
4705 This has the same visual effect as specifying <quote>blank</quote> or <quote>pattern</quote> in
4706 the first place, but enables your browser to cache the replacement image, instead of requesting
4707 it over and over again.
4718 The URLs for the built-in images are <quote>http://config.privoxy.org/send-banner?type=<replaceable
4719 class="parameter">type</replaceable></quote>, where <replaceable class="parameter">type</replaceable> is
4720 either <quote>blank</quote> or <quote>pattern</quote>.
4723 There is a third (advanced) type, called <quote>auto</quote>. It is <emphasis>NOT</emphasis> to be
4724 used in <literal>set-image-blocker</literal>, but meant for use from <link linkend="filter-file">filters</link>.
4725 Auto will select the type of image that would have applied to the referring page, had it been an image.
4731 <term>Example usage:</term>
4737 <screen>+set-image-blocker{pattern}</screen>
4740 Redirect to the BSD devil:
4743 <screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
4746 Redirect to the built-in pattern for better caching:
4749 <screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
4757 <!-- ~~~~~ New section ~~~~~ -->
4759 <title>Summary</title>
4761 Note that many of these actions have the potential to cause a page to
4762 misbehave, possibly even not to display at all. There are many ways
4763 a site designer may choose to design his site, and what HTTP header
4764 content, and other criteria, he may depend on. There is no way to have hard
4765 and fast rules for all sites. See the <link
4766 linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
4772 <!-- ~~~~~ New section ~~~~~ -->
4773 <sect2 id="aliases">
4774 <title>Aliases</title>
4776 Custom <quote>actions</quote>, known to <application>Privoxy</application>
4777 as <quote>aliases</quote>, can be defined by combining other actions.
4778 These can in turn be invoked just like the built-in actions.
4779 Currently, an alias name can contain any character except space, tab,
4781 <quote>{</quote> and <quote>}</quote>, but we <emphasis>strongly
4782 recommend</emphasis> that you only use <quote>a</quote> to <quote>z</quote>,
4783 <quote>0</quote> to <quote>9</quote>, <quote>+</quote>, and <quote>-</quote>.
4784 Alias names are not case sensitive, and are not required to start with a
4785 <quote>+</quote> or <quote>-</quote> sign, since they are merely textually
4789 Aliases can be used throughout the actions file, but they <emphasis>must be
4790 defined in a special section at the top of the file!</emphasis>
4791 And there can only be one such section per actions file. Each actions file may
4792 have its own alias section, and the aliases defined in it are only visible
4796 There are two main reasons to use aliases: One is to save typing for frequently
4797 used combinations of actions, the other one is a gain in flexibility: If you
4798 decide once how you want to handle shops by defining an alias called
4799 <quote>shop</quote>, you can later change your policy on shops in
4800 <emphasis>one</emphasis> place, and your changes will take effect everywhere
4801 in the actions file where the <quote>shop</quote> alias is used. Calling aliases
4802 by their purpose also makes your actions files more readable.
4805 Currently, there is one big drawback to using aliases, though:
4806 <application>Privoxy</application>'s built-in web-based action file
4807 editor honors aliases when reading the actions files, but it expands
4808 them before writing. So the effects of your aliases are of course preserved,
4809 but the aliases themselves are lost when you edit sections that use aliases
4811 This is likely to change in future versions of <application>Privoxy</application>.
4815 Now let's define some aliases...
4820 # Useful custom aliases we can use later.
4822 # Note the (required!) section header line and that this section
4823 # must be at the top of the actions file!
4827 # These aliases just save typing later:
4828 # (Note that some already use other aliases!)
4830 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
4831 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
4832 block-as-image = +block +handle-as-image
4833 mercy-for-cookies = -crunch-all-cookies -session-cookies-only
4835 # These aliases define combinations of actions
4836 # that are useful for certain types of sites:
4838 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
4839 shop = -crunch-all-cookies -filter{popups} -kill-popups
4841 # Short names for other aliases, for really lazy people ;-)
4843 c0 = +crunch-all-cookies
4844 c1 = -crunch-all-cookies</screen>
4848 ...and put them to use. These sections would appear in the lower part of an
4849 actions file and define exceptions to the default actions (as specified further
4850 up for the <quote>/</quote> pattern):
4855 # These sites are either very complex or very keen on
4856 # user data and require minimal interference to work:
4859 .office.microsoft.com
4860 .windowsupdate.microsoft.com
4864 # Allow cookies (for setting and retrieving your customer data)
4868 .worldpay.com # for quietpc.com
4871 # These shops require pop-ups:
4873 {shop -kill-popups -filter{popups}}
4875 .overclockers.co.uk</screen>
4879 Aliases like <quote>shop</quote> and <quote>fragile</quote> are often used for
4880 <quote>problem</quote> sites that require some actions to be disabled
4881 in order to function properly.
4885 <!-- ~~~~~ New section ~~~~~ -->
4886 <sect2 id="act-examples">
4887 <title>Sample Actions Files</title>
4889 The above chapters have shown <link linkend="actions-file">which actions files
4890 there are and how they are organized</link>, how actions are <link
4891 linkend="actions">specified</link> and <link linkend="actions-apply">applied
4892 to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
4893 define and use <link linkend="aliases">aliases</link>. Now, let's look at an
4894 example <filename>default.action</filename> and <filename>user.action</filename>
4895 file and see how all these pieces come together:
4898 <sect3><title>default.action</title>
4901 Every config file should start with a short comment stating it's purpose:
4905 <screen># Sample default.action file <developers@privoxy.org></screen>
4909 Then, since this is the <filename>default.action</filename> file, the
4910 first section is a special section for internal use that you needn't
4911 change or worry about:
4916 ##########################################################################
4917 # Settings -- Don't change! For internal Privoxy use ONLY.
4918 ##########################################################################
4921 for-privoxy-version=3.0</screen>
4925 After that comes the (optional) alias section. We'll use the example
4926 section from the above <link linkend="aliases">chapter on aliases</link>,
4927 that also explains why and how aliases are used:
4932 ##########################################################################
4934 ##########################################################################
4937 # These aliases just save typing later:
4938 # (Note that some already use other aliases!)
4940 +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
4941 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
4942 block-as-image = +block +handle-as-image
4943 mercy-for-cookies = -crunch-all-cookies -session-cookies-only
4945 # These aliases define combinations of actions
4946 # that are useful for certain types of sites:
4948 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
4949 shop = mercy-for-cookies -filter{popups} -kill-popups</screen>
4953 Now come the regular sections, i.e. sets of actions, accompanied
4954 by URL patterns to which they apply. Remember <emphasis>all actions
4955 are disabled when matching starts</emphasis>, so we have to explicitly
4956 enable the ones we want.
4960 The first regular section is probably the most important. It has only
4961 one pattern, <quote><literal>/</literal></quote>, but this pattern
4962 <link linkend="af-patterns">matches all URLs.</link>. Therefore, the
4963 set of actions used in this <quote>default</quote> section <emphasis>will
4964 be applied to all requests as a start</emphasis>. It can be partly or
4965 wholly overridden by later matches further down this file, or in user.action,
4966 but it will still be largely responsible for your overall browsing
4971 Again, at the start of matching, all actions are disabled, so there is
4972 no real need to disable any actions here, but we will do that nonetheless,
4973 to have a complete listing for your reference. (Remember: A <quote>+</quote>
4974 preceding the action name enables the action, a <quote>-</quote> disables!).
4975 Also note how this long line has been made more readable by splitting it into
4976 multiple lines with line continuation.
4981 ##########################################################################
4982 # "Defaults" section:
4983 ##########################################################################
4985 -<link linkend="ADD-HEADER">add-header</link> \
4986 -<link linkend="BLOCK">block</link> \
4987 -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
4988 -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
4989 +<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
4990 -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
4991 +<link linkend="FAST-REDIRECTS">fast-redirects</link> \
4992 +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
4993 +<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
4994 -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
4995 +<link linkend="FILTER-POPUPS">filter{popups}</link> \
4996 +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
4997 -<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
4998 -<link linkend="FILTER-FUN">filter{fun}</link> \
4999 +<link linkend="FILTER-NIMDA">filter{nimda}</link> \
5000 +<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
5001 -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
5002 -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
5003 -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
5004 +<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
5005 +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
5006 +<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
5007 -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
5008 -<link linkend="KILL-POPUPS">kill-popups</link> \
5009 -<link linkend="LIMIT-CONNECT">limit-connect</link> \
5010 +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
5011 -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
5012 -<link linkend="SEND-WAFER">send-wafer</link> \
5013 +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
5014 +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
5016 / # forward slash will match *all* potential URL patterns.</screen>
5020 The default behavior is now set. Note that some actions, like not hiding
5021 the user agent, are part of a <quote>general policy</quote> that applies
5022 universally and won't get any exceptions defined later. Other choices,
5023 like not blocking (which is <emphasis>understandably</emphasis> the
5024 default!) need exceptions, i.e. we need to specify explicitly what we
5025 want to block in later sections.
5026 We will also want to make exceptions from our general pop-up-killing,
5027 and use our defined aliases for that.
5031 The first of our specialized sections is concerned with <quote>fragile</quote>
5032 sites, i.e. sites that require minimum interference, because they are either
5033 very complex or very keen on tracking you (and have mechanisms in place that
5034 make them unusable for people who avoid being tracked). We will simply use
5035 our pre-defined <literal>fragile</literal> alias instead of stating the list
5036 of actions explicitly:
5041 ##########################################################################
5042 # Exceptions for sites that'll break under the default action set:
5043 ##########################################################################
5045 # "Fragile" Use a minimum set of actions for these sites (see alias above):
5048 .office.microsoft.com # surprise, surprise!
5049 .windowsupdate.microsoft.com</screen>
5053 Shopping sites are not as fragile, but they typically
5054 require cookies to log in, and pop-up windows for shopping
5055 carts or item details. Again, we'll use a pre-defined alias:
5064 .worldpay.com # for quietpc.com
5066 .scan.co.uk</screen>
5070 Then, there are sites which rely on pop-up windows (yuck!) to work.
5071 Since we made pop-up-killing our default above, we need to make exceptions
5072 now. <ulink url="http://www.mozilla.org/">Mozilla</ulink> users, who
5073 can turn on smart handling of unwanted pop-ups in their browsers, can
5075 -<literal><link linkend="FILTER-POPUPS">filter{popups}</link></literal> (and
5076 -<literal><link linkend="KILL-POPUPS">kill-popups</link></literal>) above
5077 and hence don't need this section. Anyway, disabling an already disabled
5078 action doesn't hurt, so we'll define our exceptions regardless of what was
5079 chosen in the defaults section:
5084 # These sites require pop-ups too :(
5086 { -<link linkend="KILL-POPUPS">kill-popups</link> -<link linkend="FILTER-POPUPS">filter{popups}</link> }
5089 .deutsche-bank-24.de</screen>
5093 The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
5094 action, which we enabled per default above, breaks some sites. So disable
5095 it for popular sites where we know it misbehaves:
5100 { -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
5104 .altavista.com/.*(like|url|link):http
5105 .altavista.com/trans.*urltext=http
5106 .nytimes.com</screen>
5110 It is important that <application>Privoxy</application> knows which
5111 URLs belong to images, so that <emphasis>if</emphasis> they are to
5112 be blocked, a substitute image can be sent, rather than an HTML page.
5113 Contacting the remote site to find out is not an option, since it
5114 would destroy the loading time advantage of banner blocking, and it
5115 would feed the advertisers (in terms of money <emphasis>and</emphasis>
5116 information). We can mark any URL as an image with the <literal><link
5117 linkend="handle-as-image">handle-as-image</link></literal> action,
5118 and marking all URLs that end in a known image file extension is a
5124 ##########################################################################
5126 ##########################################################################
5128 # Define which file types will be treated as images, in case they get
5129 # blocked further down this file:
5131 { +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
5132 /.*\.(gif|jpe?g|png|bmp|ico)$</screen>
5136 And then there are known banner sources. They often use scripts to
5137 generate the banners, so it won't be visible from the URL that the
5138 request is for an image. Hence we block them <emphasis>and</emphasis>
5139 mark them as images in one go, with the help of our
5140 <literal>block-as-image</literal> alias defined above. (We could of
5141 course just as well use <literal>+<link linkend="block">block</link>
5142 +<link linkend="handle-as-image">handle-as-image</link></literal> here.)
5143 Remember that the type of the replacement image is chosen by the
5144 <literal><link linkend="set-image-blocker">set-image-blocker</link></literal>
5145 action. Since all URLs have matched the default section with its
5146 <literal>+<link linkend="set-image-blocker">set-image-blocker</link>{pattern}</literal>
5147 action before, it still applies and needn't be repeated:
5152 # Known ad generators:
5157 .ad.*.doubleclick.net
5158 .a.yimg.com/(?:(?!/i/).)*$
5159 .a[0-9].yimg.com/(?:(?!/i/).)*$
5166 One of the most important jobs of <application>Privoxy</application>
5167 is to block banners. A huge bunch of them are already <quote>blocked</quote>
5168 by the <literal><link linkend="filter">filter</link>{banners-by-size}</literal>
5169 action, which we enabled above, and which deletes the references to banner
5170 images from the pages while they are loaded, so the browser doesn't request
5171 them anymore, and hence they don't need to be blocked here. But this naturally
5172 doesn't catch all banners, and some people choose not to use filters, so we
5173 need a comprehensive list of patterns for banner URLs here, and apply the
5174 <literal><link linkend="block">block</link></literal> action to them.
5177 First comes a bunch of generic patterns, which do most of the work, by
5178 matching typical domain and path name components of banners. Then comes
5179 a list of individual patterns for specific sites, which is omitted here
5180 to keep the example short:
5185 ##########################################################################
5186 # Block these fine banners:
5187 ##########################################################################
5188 { <link linkend="BLOCK">+block</link> }
5196 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
5197 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
5199 # Site-specific patterns (abbreviated):
5201 .hitbox.com</screen>
5205 You wouldn't believe how many advertisers actually call their banner
5206 servers ads.<replaceable>company</replaceable>.com, or call the directory
5207 in which the banners are stored simply <quote>banners</quote>. So the above
5208 generic patterns are surprisingly effective.
5211 But being very generic, they necessarily also catch URLs that we don't want
5212 to block. The pattern <literal>.*ads.</literal> e.g. catches
5213 <quote>nasty-<emphasis>ads</emphasis>.nasty-corp.com</quote> as intended,
5214 but also <quote>downlo<emphasis>ads</emphasis>.sourcefroge.net</quote> or
5215 <quote><emphasis>ads</emphasis>l.some-provider.net.</quote> So here come some
5216 well-known exceptions to the <literal>+<link linkend="BLOCK">block</link></literal>
5220 Note that these are exceptions to exceptions from the default! Consider the URL
5221 <quote>downloads.sourcefroge.net</quote>: Initially, all actions are deactivated,
5222 so it wouldn't get blocked. Then comes the defaults section, which matches the
5223 URL, but just deactivates the <literal><link linkend="BLOCK">block</link></literal>
5224 action once again. Then it matches <literal>.*ads.</literal>, an exception to the
5225 general non-blocking policy, and suddenly
5226 <literal><link linkend="BLOCK">+block</link></literal> applies. And now, it'll match
5227 <literal>.*loads.</literal>, where <literal><link linkend="BLOCK">-block</link></literal>
5228 applies, so (unless it matches <emphasis>again</emphasis> further down) it ends up
5229 with no <literal><link linkend="BLOCK">block</link></literal> action applying.
5234 ##########################################################################
5235 # Save some innocent victims of the above generic block patterns:
5236 ##########################################################################
5240 { -<link linkend="BLOCK">block</link> }
5241 adv[io]*. # (for advogato.org and advice.*)
5243 ad[ud]*. # (adult.* and add.*)
5245 .*loads. # (downloads, uploads etc)
5253 www.globalintersec.com/adv # (adv = advanced)
5254 www.ugu.com/sui/ugu/adv</screen>
5258 Filtering source code can have nasty side effects,
5259 so make an exception for our friends at sourceforge.net,
5260 and all paths with <quote>cvs</quote> in them. Note that
5261 <literal>-<link linkend="FILTER">filter</link></literal>
5262 disables <emphasis>all</emphasis> filters in one fell swoop!
5267 # Don't filter code!
5269 { -<link linkend="FILTER">filter</link> }
5271 .sourceforge.net</screen>
5275 The actual <filename>default.action</filename> is of course more
5276 comprehensive, but we hope this example made clear how it works.
5281 <sect3><title>user.action</title>
5284 So far we are painting with a broad brush by setting general policies,
5285 which would be a reasonable starting point for many people. Now,
5286 you'd maybe want to be more specific and have customized rules that
5287 are more suitable to your personal habits and preferences. These would
5288 be for narrowly defined situations like your ISP or your bank, and should
5289 be placed in <filename>user.action</filename>, which is parsed after all other
5290 actions files and hence has the last word, over-riding any previously
5291 defined actions. <filename>user.action</filename> is also a
5292 <emphasis>safe</emphasis> place for your personal settings, since
5293 <filename>default.action</filename> is actively maintained by the
5294 <application>Privoxy</application> developers and you'll probably want
5295 to install updated versions from time to time.
5299 So let's look at a few examples of things that one might typically do in
5300 <filename>user.action</filename>:
5304 <!-- brief sample user.action here -->
5308 # My user.action file. <fred@foobar.com></screen>
5312 As <link linkend="aliases">aliases</link> are local to the actions
5313 file that they are defined in, you can't use the ones from
5314 <filename>default.action</filename>, unless you repeat them here:
5319 # (Re-)define aliases for this file:
5322 -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
5323 mercy-for-cookies = -crunch-all-cookies -session-cookies-only
5324 fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups
5325 shop = mercy-for-cookies -filter{popups} -kill-popups</screen>
5329 Say you have accounts on some sites that you visit regularly, and
5330 you don't want to have to log in manually each time. So you'd like
5331 to allow persistent cookies for these sites. The
5332 <literal>mercy-for-cookies</literal> alias defined above does exactly
5333 that, i.e. it disables crunching of cookies in any direction, and
5334 processing of cookies to make them temporary.
5339 { mercy-for-cookies }
5344 .redhat.com</screen>
5348 Your bank needs popups and is allergic to some filter, but you don't
5349 know which, so you disable them all:
5354 { -<link linkend="FILTER">filter</link> -<link linkend="KILL-POPUPS">kill-popups</link> }
5355 .your-home-banking-site.com</screen>
5359 While browsing the web with <application>Privoxy</application> you
5360 noticed some ads that sneaked through, but you were too lazy to
5361 report them through our fine and easy <link linkend="contact">feedback</link>
5362 system, so you have added them here:
5367 { +<link linkend="BLOCK">block</link> }
5368 www.a-popular-site.com/some/unobvious/path
5369 another.popular.site.net/more/junk/here/</screen>
5373 Note that, assuming the banners in the above example have regular image
5374 extensions (most do),
5375 <literal>+<link linkend="HANDLE-AS-IMAGE">handle-as-image</link></literal>
5376 need not be specified, since all URLs ending in these extensions will
5377 already have been tagged as images in the relevant section of
5378 <filename>default.action</filename> by now.
5382 Then you noticed that the default configuration breaks Forbes Magazine,
5383 but you were too lazy to find out which action is the culprit, and you
5384 were again too lazy to give <link linkend="contact">feedback</link>, so
5385 you just used the <literal>fragile</literal> alias on the site, and
5386 -- whoa! -- it worked:
5392 .forbes.com</screen>
5396 You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
5397 but it is disabled in the distributed actions file. (My colleagues on the team just
5398 don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private,
5399 update-safe config, once and for all:
5404 { +<link linkend="filter-fun">filter{fun}</link> }
5405 / # For ALL sites!</screen>
5409 Note that the above is not really a good idea: There are exceptions
5410 to the filters in <filename>default.action</filename> for things that
5411 really shouldn't be filtered, like code on CVS->Web interfaces. Since
5412 <filename>user.action</filename> has the last word, these exceptions
5413 won't be valid for the <quote>fun</quote> filtering specified here.
5414 But you're the boss.
5420 <!-- ~ End section ~ -->
5424 <!-- ~ End section ~ -->
5426 <!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
5428 <sect1 id="filter-file">
5429 <title>The Filter File</title>
5431 Any web page can be dynamically modified with the filter file. This
5432 modification can be removal, or re-writing, of any web page content,
5433 including tags and non-visible content. The default filter file is
5434 oddly enough <filename>default.filter</filename>, located in the config
5439 This is potentially a very powerful feature, and requires knowledge of both
5440 <quote>regular expression</quote> and HTML in order create custom
5441 filters. But, there are a number of useful filters included with
5442 <application>Privoxy</application> for many common situations.
5446 The included example file is divided into sections. Each section begins
5447 with the <literal>FILTER</literal> keyword, followed by the identifier
5448 for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
5449 a similar type of filtering, such as <quote>html-annoyances</quote>.
5453 This file uses regular expressions to alter or remove any string in the
5454 target page. The expressions can only operate on one line at a time. Some
5455 examples from the included default <filename>default.filter</filename>:
5459 Stop web pages from displaying annoying messages in the status bar by
5460 deleting such references:
5467 FILTER: html-annoyances
5469 # New browser windows should be resizeable and have a location and status
5472 s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
5473 s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
5474 s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
5475 s/menubar="?(no|0)"?/menubar=1/ig
5477 # The <BLINK> tag was a crime!
5479 s*<blink>|</blink>**ig
5483 #s/framespacing="?(no|0)"?//ig
5484 #s/margin(height|width)=[0-9]*//gi
5491 Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
5492 <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
5501 s/microsoft(?!.com)/MicroSuck/ig
5505 s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
5512 Kill those pesky little web-bugs:
5519 # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
5522 s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
5529 <!-- ~~~~~ New section ~~~~~ -->
5531 <title>The <emphasis>+filter</emphasis> Action</title>
5533 Filters are enabled with the <link
5534 linkend="FILTER"><quote>+filter</quote></link> action from within
5535 one of the actions files. <quote>+filter</quote> requires one parameter, which
5536 should match one of the section identifiers in the filter file itself. Example:
5540 +filter{html-annoyances}
5544 This would activate that particular filter. Similarly, <quote>+filter</quote>
5545 can be turned off for selected sites as:
5546 <quote>-filter{<replaceable>html-annoyances</replaceable>}</quote>. Remember
5547 too, all actions are off by default, unless they are explicitly enabled in one
5548 of the actions files.
5555 <!-- ~ End section ~ -->
5559 <!-- ~~~~~ New section ~~~~~ -->
5561 <sect1 id="templates">
5562 <title>Templates</title>
5564 When <application>Privoxy</application> displays one of its internal
5565 pages, such as a <ulink url="http://bogus_404_page.com">404 Not Found error page</ulink>
5566 (<application>Privoxy</application> must be running for link to work as
5567 intended), it uses the appropriate template. On Linux, BSD, and Unix, these
5568 are located in <filename>/etc/privoxy/templates</filename> by default. These
5569 may be customized, if desired. <filename>cgi-style.css</filename> is used to
5570 control the HTML attributes (fonts, etc).
5575 url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html">Blocked
5576 </ulink> (<application>Privoxy</application> needs to be running for page to
5577 display) banner page with the bright red top banner, is called just
5578 <quote><filename>blocked</filename></quote>. This may be customized or
5579 replaced with something else if desired (not recommended for the casual
5585 <!-- ~ End section ~ -->
5589 <!-- ~~~~~ New section ~~~~~ -->
5591 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
5594 <!-- Include contacting.sgml boilerplate: -->
5596 <!-- end boilerplate -->
5600 <!-- ~ End section ~ -->
5603 <!-- ~~~~~ New section ~~~~~ -->
5604 <sect1 id="copyright"><title><application>Privoxy</application> Copyright, License and History</title>
5606 <!-- Include copyright.sgml: -->
5608 <!-- end copyright -->
5610 <!-- ~~~~~ New section ~~~~~ -->
5611 <sect2><title>License</title>
5612 <!-- Include copyright.sgml: -->
5614 <!-- end copyright -->
5616 <!-- ~ End section ~ -->
5619 <!-- ~~~~~ New section ~~~~~ -->
5621 <sect2 id="history"><title>History</title>
5622 <!-- Include history.sgml: -->
5624 <!-- end history -->
5628 <!-- ~ End section ~ -->
5631 <!-- ~~~~~ New section ~~~~~ -->
5632 <sect1 id="seealso"><title>See Also</title>
5633 <!-- Include seealso.sgml: -->
5635 <!-- end seealso -->
5640 <!-- ~~~~~ New section ~~~~~ -->
5641 <sect1 id="appendix"><title>Appendix</title>
5644 <!-- ~~~~~ New section ~~~~~ -->
5646 <title>Regular Expressions</title>
5648 <application>Privoxy</application> can use <quote>regular expressions</quote>
5649 in various config files. Assuming support for <quote>pcre</quote> (Perl
5650 Compatible Regular Expressions) is compiled in, which is the default. Such
5651 configuration directives do not require regular expressions, but they can be
5652 used to increase flexibility by matching a pattern with wild-cards against
5657 If you are reading this, you probably don't understand what <quote>regular
5658 expressions</quote> are, or what they can do. So this will be a very brief
5659 introduction only. A full explanation would require a book ;-)
5663 <quote>Regular expressions</quote> is a way of matching one character
5664 expression against another to see if it matches or not. One of the
5665 <quote>expressions</quote> is a literal string of readable characters
5666 (letter, numbers, etc), and the other is a complex string of literal
5667 characters combined with wild-cards, and other special characters, called
5668 meta-characters. The <quote>meta-characters</quote> have special meanings and
5669 are used to build the complex pattern to be matched against. Perl Compatible
5670 Regular Expressions is an enhanced form of the regular expression language
5671 with backward compatibility.
5675 To make a simple analogy, we do something similar when we use wild-card
5676 characters when listing files with the <command>dir</command> command in DOS.
5677 <literal>*.*</literal> matches all filenames. The <quote>special</quote>
5678 character here is the asterisk which matches any and all characters. We can be
5679 more specific and use <literal>?</literal> to match just individual
5680 characters. So <quote>dir file?.text</quote> would match
5681 <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
5682 matching, using a similar technique to <quote>regular expressions</quote>!
5686 Regular expressions do essentially the same thing, but are much, much more
5687 powerful. There are many more <quote>special characters</quote> and ways of
5688 building complex patterns however. Let's look at a few of the common ones,
5689 and then some examples:
5694 <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
5695 <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
5697 </simplelist></para>
5701 <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
5704 </simplelist></para>
5708 <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
5711 </simplelist></para>
5715 <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
5718 </simplelist></para>
5722 <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
5723 the following character should be taken literally. This is used where one of the
5724 special characters (e.g. <quote>.</quote>) needs to be taken literally and
5725 not as a special meta-character. Example: <quote>example\.com</quote>, makes
5726 sure the period is recognized only as a period (and not expanded to its
5727 meta-character meaning of any single character).
5729 </simplelist></para>
5733 <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
5734 any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
5735 matches any numeric digit (zero through nine). As an example, we can combine
5736 this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
5738 </simplelist></para>
5742 <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
5743 or multiple sub-expressions.
5745 </simplelist></para>
5749 <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
5750 <quote>or</quote> conditional statement. A match is successful if the
5751 sub-expression on either side of <quote>|</quote> matches. As an example:
5752 <quote>/(this|that) example/</quote> uses grouping and the bar character
5753 and would match either <quote>this example</quote> or <quote>that
5754 example</quote>, and nothing else.
5756 </simplelist></para>
5760 <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
5761 <quote>string1</quote> is replaced by <quote>string2</quote> in this
5762 example. There must of course be a match on <quote>string1</quote> first.
5764 </simplelist></para>
5767 These are just some of the ones you are likely to use when matching URLs with
5768 <application>Privoxy</application>, and is a long way from a definitive
5769 list. This is enough to get us started with a few simple examples which may
5770 be more illuminating:
5774 <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
5775 that uses the common combination of <quote>.</quote> and <quote>*</quote> to
5776 denote any character, zero or more times. In other words, any string at all.
5777 So we start with a literal forward slash, then our regular expression pattern
5778 (<quote>.*</quote>) another literal forward slash, the string
5779 <quote>banners</quote>, another forward slash, and lastly another
5780 <quote>.*</quote>. We are building
5781 a directory path here. This will match any file with the path that has a
5782 directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
5783 any characters, and this could conceivably be more forward slashes, so it
5784 might expand into a much longer looking path. For example, this could match:
5785 <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
5786 <quote>/banners/annoying.html</quote>, or almost an infinite number of other
5787 possible combinations, just so it has <quote>banners</quote> in the path
5792 A now something a little more complex:
5796 <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
5797 We have several literal forward slashes again (<quote>/</quote>), so we are
5798 building another expression that is a file path statement. We have another
5799 <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
5800 it matches our expression. The only true literal that <emphasis>must
5801 match</emphasis> our pattern is <application>adv</application>, together with
5802 the forward slashes. What comes after the <quote>adv</quote> string is the
5807 Remember the <quote>?</quote> means the preceding expression (either a
5808 literal character or anything grouped with <quote>(...)</quote> in this case)
5809 can exist or not, since this means either zero or one match. So
5810 <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
5811 individual sub-expressions: <quote>(er)</quote>,
5812 <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
5813 means <quote>or</quote>. We have two of those. For instance,
5814 <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
5815 <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
5816 attempt at matching as many variations of <quote>advertisement</quote>, and
5817 similar, as possible. So this would expand to match just <quote>adv</quote>,
5818 or <quote>advert</quote>, or <quote>adverts</quote>, or
5819 <quote>advertising</quote>, or <quote>advertisement</quote>, or
5820 <quote>advertisements</quote>. You get the idea. But it would not match
5821 <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
5822 changing our regular expression to:
5823 <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
5828 <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
5829 another path statement with forward slashes. Anything in the square brackets
5830 <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
5831 shorthand expression to mean any digit one through nine. It is the same as
5832 saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
5833 means one or more of the preceding expression must be included. The preceding
5834 expression here is what is in the square brackets -- in this case, any digit
5835 one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
5836 This includes a <quote>|</quote>, so this needs to match the expression on
5837 either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
5838 side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
5839 since the <quote>?</quote> means the letter <quote>e</quote> is optional and
5840 can be matched once or not at all. So we are building an expression here to
5841 match image GIF or JPEG type image file. It must include the literal
5842 string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
5843 (which is now a literal, and not a special character, since it is escaped
5844 with <quote>\</quote>), and lastly either <quote>gif</quote>, or
5845 <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
5846 include: <quote>//advert1.jpg</quote>,
5847 <quote>/nasty/ads/advert1234.gif</quote>,
5848 <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
5849 <quote>advert1.gif</quote> (no leading slash), or
5850 <quote>/adverts232.jpg</quote> (the expression does not include an
5851 <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
5852 in the expression anywhere).
5856 <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
5857 a substitution. <quote>MicroSuck</quote> will replace any occurrence of
5858 <quote>microsoft</quote>. The <quote>i</quote> at the end of the expression
5859 means ignore case. The <quote>(?!.com)</quote> means
5860 the match should fail if <quote>microsoft</quote> is followed by
5861 <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
5862 modifier. In case this is a hyperlink, we don't want to break it ;-).
5866 We are barely scratching the surface of regular expressions here so that you
5867 can understand the default <application>Privoxy</application>
5868 configuration files, and maybe use this knowledge to customize your own
5869 installation. There is much, much more that can be done with regular
5870 expressions. Now that you know enough to get started, you can learn more on
5875 More reading on Perl Compatible Regular expressions:
5876 <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
5881 <!-- ~ End section ~ -->
5884 <!-- ~~~~~ New section ~~~~~ -->
5886 <title><application>Privoxy</application>'s Internal Pages</title>
5889 Since <application>Privoxy</application> proxies each requested
5890 web page, it is easy for <application>Privoxy</application> to
5891 trap certain special URLs. In this way, we can talk directly to
5892 <application>Privoxy</application>, and see how it is
5893 configured, see how our rules are being applied, change these
5894 rules and other configuration options, and even turn
5895 <application>Privoxy's</application> filtering off, all with
5901 The URLs listed below are the special ones that allow direct access
5902 to <application>Privoxy</application>. Of course,
5903 <application>Privoxy</application> must be running to access these. If
5904 not, you will get a friendly error message. Internet access is not
5917 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
5921 Alternately, this may be reached at <ulink
5922 url="http://p.p/">http://p.p/</ulink>, but this
5923 variation may not work as reliably as the above in some configurations.
5929 Show information about the current configuration, including viewing and
5930 editing of actions files:
5934 <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
5941 Show the source code version numbers:
5945 <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
5952 Show the browser's request headers:
5956 <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
5963 Show which actions apply to a URL and why:
5967 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
5974 Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
5975 to run, but only as a pass-through proxy, with no actions taking place:
5979 <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
5983 Short cuts. Turn off, then on:
5987 <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
5992 <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
6001 These may be bookmarked for quick reference. See next.
6005 <sect3 id="bookmarklets">
6006 <title>Bookmarklets</title>
6008 Below are some <quote>bookmarklets</quote> to allow you to easily access a
6009 <quote>mini</quote> version of some of <application>Privoxy's</application>
6010 special pages. They are designed for MS Internet Explorer, but should work
6011 equally well in Netscape, Mozilla, and other browsers which support
6012 JavaScript. They are designed to run directly from your bookmarks - not by
6013 clicking the links below (although that should work for testing).
6016 To save them, right-click the link and choose <quote>Add to Favorites</quote>
6017 (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
6018 the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
6019 Bookmarklet directly from your favorites/bookmarks. For even faster access,
6020 you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
6021 Toolbar</quote> (Netscape), and run them with a single click.
6030 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
6037 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
6044 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
6051 url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
6057 <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());">Privoxy - Submit Filter Feedback</ulink>
6067 Credit: The site which gave me the general idea for these bookmarklets is
6068 <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
6069 have more information about bookmarklets.
6078 <!-- ~~~~~ New section ~~~~~ -->
6080 <title>Chain of Events</title>
6082 Let's take a quick look at the basic sequence of events when a web page is
6083 requested by your browser and <application>Privoxy</application> is on duty:
6090 First, your web browser requests a web page. The browser knows to send
6091 the request to <application>Privoxy</application>, which will in turn,
6092 relay the request to the remote web server after passing the following
6098 <application>Privoxy</application> traps any request for its own internal CGI
6099 pages (e.g http://p.p/) and sends the CGI page back to the browser.
6104 Next, <application>Privoxy</application> checks to see if the URL
6106 linkend="BLOCK"><quote>+block</quote></link> patterns. If
6107 so, the URL is then blocked, and the remote web server will not be contacted.
6108 <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
6109 is then checked and if it does not match, an
6110 HTML <quote>BLOCKED</quote> page is sent back. Otherwise, if it does match,
6111 an image is returned. The type of image depends on the setting of <link
6112 linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
6113 (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
6118 Untrusted URLs are blocked. If URLs are being added to the
6119 <filename>trust</filename> file, then that is done.
6124 If the URL pattern matches the <link
6125 linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
6126 it is then processed. Unwanted parts of the requested URL are stripped.
6131 Now the rest of the client browser's request headers are processed. If any
6132 of these match any of the relevant actions (e.g. <link
6133 linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
6134 etc.), headers are suppressed or forged as determined by these actions and
6140 Now the web server starts sending its response back (i.e. typically a web page and related
6146 First, the server headers are read and processed to determine, among other
6147 things, the MIME type (document type) and encoding. The headers are then
6148 filtered as deterimed by the
6149 <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
6150 <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
6151 and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
6157 If the <link linkend="KILL-POPUPS"><quote>+kill-popups</quote></link>
6158 action applies, and it is an HTML or JavaScript document, the popup-code in the
6159 response is filtered on-the-fly as it is received.
6164 If a <link linkend="FILTER"><quote>+filter</quote></link>
6166 linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
6167 action applies (and the document type fits the action), the rest of the page is
6168 read into memory (up to a configurable limit). Then the filter rules (from
6169 <filename>default.filter</filename>) are processed against the buffered
6170 content. Filters are applied in the order they are specified in the
6171 <filename>default.filter</filename> file. Animated GIFs, if present, are
6172 reduced to either the first or last frame, depending on the action
6173 setting.The entire page, which is now filtered, is then sent by
6174 <application>Privoxy</application> back to your browser.
6177 If neither <link linkend="FILTER"><quote>+filter</quote></link>
6179 linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
6180 matches, then <application>Privoxy</application> passes the raw data through
6181 to the client browser as it becomes available.
6186 As the browser receives the now (probably filtered) page content, it
6187 reads and then requests any URLs that may be embedded within the page
6188 source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
6189 frames), sounds, etc. For each of these objects, the browser issues a new
6190 request. And each such request is in turn processed as above. Note that a
6191 complex web page may have many such embedded URLs.
6201 <!-- ~~~~~ New section ~~~~~ -->
6202 <sect2 id="actionsanat">
6203 <title>Anatomy of an Action</title>
6206 The way <application>Privoxy</application> applies
6207 <link linkend="ACTIONS"><quote>actions</quote></link>
6208 and <link linkend="FILTER"><quote>filters</quote></link>
6209 to any given URL can be complex, and not always so
6210 easy to understand what is happening. And sometimes we need to be able to
6211 <emphasis>see</emphasis> just what <application>Privoxy</application> is
6212 doing. Especially, if something <application>Privoxy</application> is doing
6213 is causing us a problem inadvertently. It can be a little daunting to look at
6214 the actions and filters files themselves, since they tend to be filled with
6215 <quote>regular expressions</quote> whose consequences are not always
6220 One quick test to see if <application>Privoxy</application> is causing a problem
6221 or not, is to disable it temporarily. This should be the first troubleshooting
6222 step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
6223 and easy way to do this (be sure to flush caches afterward!).
6227 <application>Privoxy</application> also provides the
6228 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
6229 page that can show us very specifically how <application>actions</application>
6230 are being applied to any given URL. This is a big help for troubleshooting.
6234 First, enter one URL (or partial URL) at the prompt, and then
6235 <application>Privoxy</application> will tell us
6236 how the current configuration will handle it. This will not
6237 help with filtering effects (i.e. the <link
6238 linkend="FILTER"><quote>+filter</quote></link> action) from
6239 the <filename>default.filter</filename> file since this is handled very
6240 differently and not so easy to trap! It also will not tell you about any other
6241 URLs that may be embedded within the URL you are testing. For instance, images
6242 such as ads are expressed as URLs within the raw page source of HTML pages. So
6243 you will only get info for the actual URL that is pasted into the prompt area
6244 -- not any sub-URLs. If you want to know about embedded URLs like ads, you
6245 will have to dig those out of the HTML source. Use your browser's <quote>View
6246 Page Source</quote> option for this. Or right click on the ad, and grab the
6251 Let's try an example, <ulink url="http://google.com">google.com</ulink>,
6252 and look at it one section at a time:
6257 Matches for http://google.com:
6259 --- File standard ---
6260 (no matches in this file)
6262 --- File default ---
6264 { -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects
6265 -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
6266 +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
6267 +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
6268 +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
6269 -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
6270 +prevent-compression +session-cookies-only -crunch-outgoing-cookies
6271 -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer }
6274 { -session-cookies-only }
6281 (no matches in this file)
6286 This tells us how we have defined our
6287 <link linkend="ACTIONS"><quote>actions</quote></link>, and
6288 which ones match for our example, <quote>google.com</quote>. The first listing
6289 is any matches for the <filename>standard.action</filename> file. No hits at
6290 all here on <quote>standard</quote>. Then next is <quote>default</quote>, or
6291 our <filename>default.action</filename> file. The large, multi-line listing,
6292 is how the actions are set to match for all URLs, i.e. our default settings.
6293 If you look at your <quote>actions</quote> file, this would be the section
6294 just below the <quote>aliases</quote> section near the top. This will apply to
6295 all URLs as signified by the single forward slash at the end of the listing
6296 -- <quote>/</quote>.
6300 But we can define additional actions that would be exceptions to these general
6301 rules, and then list specific URLs (or patterns) that these exceptions would
6302 apply to. Last match wins. Just below this then are two explicit matches for
6303 <quote>.google.com</quote>. The first is negating our previous cookie setting,
6305 linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
6306 (i.e. not persistent). So we will allow persistent cookies for google. The
6307 second turns <emphasis>off</emphasis> any
6309 linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
6310 action, allowing this to take place unmolested. Note that there is a leading
6311 dot here -- <quote>.google.com</quote>. This will match any hosts and
6312 sub-domains, in the google.com domain also, such as
6313 <quote>www.google.com</quote>. So, apparently, we have these two actions
6314 defined somewhere in the lower part of our <filename>default.action</filename>
6315 file, and <quote>google.com</quote> is referenced somewhere in these latter
6320 Then, for our <filename>user.action</filename> file, we again have no hits.
6324 And finally we pull it all together in the bottom section and summarize how
6325 <application>Privoxy</application> is applying all its <quote>actions</quote>
6326 to <quote>google.com</quote>:
6334 -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects
6335 -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
6336 +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
6337 +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
6338 +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
6339 -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
6340 +prevent-compression -session-cookies-only -crunch-outgoing-cookies
6341 -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer
6346 Notice the only difference here to the previous listing, is to
6347 <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>.
6351 Now another example, <quote>ad.doubleclick.net</quote>:
6357 { +block +handle-as-image }
6360 { +block +handle-as-image }
6363 { +block +handle-as-image }
6369 We'll just show the interesting part here, the explicit matches. It is
6370 matched three different times. Each as an <quote>+block +handle-as-image</quote>,
6371 which is the expanded form of one of our aliases that had been defined as:
6372 <quote>+imageblock</quote>. (<link
6373 linkend="ALIASES"><quote>Aliases</quote></link> are defined in
6374 the first section of the actions file and typically used to combine more
6379 Any one of these would have done the trick and blocked this as an unwanted
6380 image. This is unnecessarily redundant since the last case effectively
6381 would also cover the first. No point in taking chances with these guys
6382 though ;-) Note that if you want an ad or obnoxious
6383 URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
6384 is done here -- as both a <link
6385 linkend="BLOCK"><quote>+block</quote></link>
6386 <emphasis>and</emphasis> an
6388 linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
6389 The custom alias <quote>+imageblock</quote> just simplifies the process and make
6394 One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
6395 This one is giving us problems. We are getting a blank page. Hmmm...
6401 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
6403 { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects
6404 +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}
6405 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
6406 +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}
6407 +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}
6408 +prevent-compression +session-cookies-only -crunch-incoming-cookies
6409 -crunch-outgoing-cookies +kill-popups -send-vanilla-wafer -send-wafer }
6412 { +block +handle-as-image }
6418 Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
6419 we did not want this at all! Now we see why we get the blank page. We could
6420 now add a new action below this that explicitly does <emphasis>not</emphasis>
6421 block (<quote>{-block}</quote>) paths with <quote>adsl</quote>. There are
6422 various ways to handle such exceptions. Example:
6434 Now the page displays ;-) Be sure to flush your browser's caches when
6435 making such changes. Or, try using <literal>Shift+Reload</literal>.
6439 But now what about a situation where we get no explicit matches like
6446 { +block +handle-as-image }
6452 That actually was very telling and pointed us quickly to where the problem
6453 was. If you don't get this kind of match, then it means one of the default
6454 rules in the first section is causing the problem. This would require some
6455 guesswork, and maybe a little trial and error to isolate the offending rule.
6456 One likely cause would be one of the <quote>{+filter}</quote> actions. Try
6457 adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
6465 .worldpay.com # for quietpc.com
6473 <quote>{shop}</quote> is an <quote>alias</quote> that expands to
6474 <quote>{ -filter -session-cookies-only }</quote>.
6475 Or you could do your own exception to negate filtering:
6488 This would probably be most appropriately put in <filename>user.action</filename>,
6489 for local site exceptions.
6493 <quote>{fragile}</quote> is an alias that disables most actions. This can be
6494 used as a last resort for problem sites. Remember to flush caches! If this
6495 still does not work, you will have to go through the remaining actions one by
6496 one to find which one(s) is causing the problem.
6505 This program is free software; you can redistribute it
6506 and/or modify it under the terms of the GNU General
6507 Public License as published by the Free Software
6508 Foundation; either version 2 of the License, or (at
6509 your option) any later version.
6511 This program is distributed in the hope that it will
6512 be useful, but WITHOUT ANY WARRANTY; without even the
6513 implied warranty of MERCHANTABILITY or FITNESS FOR A
6514 PARTICULAR PURPOSE. See the GNU General Public
6515 License for more details.
6517 The GNU General Public License should be included with
6518 this file. If not, you can view it at
6519 http://www.gnu.org/copyleft/gpl.html
6520 or write to the Free Software Foundation, Inc., 59
6521 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
6523 $Log: user-manual.sgml,v $
6524 Revision 1.113 2002/05/15 21:07:25 oes
6525 Extended and further commented the example actions files
6527 Revision 1.112 2002/05/15 03:57:14 hal9
6528 Spell check. A few minor edits here and there for better syntax and
6531 Revision 1.111 2002/05/14 23:01:36 oes
6534 Revision 1.110 2002/05/14 19:10:45 oes
6535 Restored alphabetical order of actions
6537 Revision 1.109 2002/05/14 17:23:11 oes
6538 Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
6540 Revision 1.108 2002/05/14 15:29:12 oes
6541 Completed proofreading the actions chapter
6543 Revision 1.107 2002/05/12 03:20:41 hal9
6544 Small clarifications for 127.0.0.1 vs localhost for listen-address since this
6545 apparently an important distinction for some OS's.
6547 Revision 1.106 2002/05/10 01:48:20 hal9
6548 This is mostly proposed copyright/licensing additions and changes. Docs
6549 are still GPL, but licensing and copyright are more visible. Also, copyright
6550 changed in doc header comments (eliminate references to JB except FAQ).
6552 Revision 1.105 2002/05/05 20:26:02 hal9
6553 Sorting out license vs copyright in these docs.
6555 Revision 1.104 2002/05/04 08:44:45 swa
6558 Revision 1.103 2002/05/04 00:40:53 hal9
6559 -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
6560 -Some minor additions to Quickstart.
6562 Revision 1.102 2002/05/03 17:46:00 oes
6563 Further proofread & reactivated short build instructions
6565 Revision 1.101 2002/05/03 03:58:30 hal9
6566 Move the user-manual config directive to top of section. Add note about
6567 Privoxy needing read permissions for configs, and write for logs.
6569 Revision 1.100 2002/04/29 03:05:55 hal9
6570 Add clarification on differences of new actions files.
6572 Revision 1.99 2002/04/28 16:59:05 swa
6573 more structure in starting section
6575 Revision 1.98 2002/04/28 05:43:59 hal9
6576 This is the break up of configuration.html into multiple files. This
6577 will probably break links elsewhere :(
6579 Revision 1.97 2002/04/27 21:04:42 hal9
6580 -Rewrite of Actions File example.
6581 -Add section for user-manual directive in config.
6583 Revision 1.96 2002/04/27 05:32:00 hal9
6584 -Add short section to Filter Files to tie in with +filter action.
6585 -Start rewrite of examples in Actions Examples (not finished).
6587 Revision 1.95 2002/04/26 17:23:29 swa
6588 bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
6590 Revision 1.94 2002/04/26 05:24:36 hal9
6591 -Add most of Andreas suggestions to Chain of Events section.
6592 -A few other minor corrections and touch up.
6594 Revision 1.92 2002/04/25 18:55:13 hal9
6595 More catchups on new actions files, and new actions names.
6596 Other assorted cleanups, and minor modifications.
6598 Revision 1.91 2002/04/24 02:39:31 hal9
6599 Add 'Chain of Events' section.
6601 Revision 1.90 2002/04/23 21:41:25 hal9
6602 Linuxconf is deprecated on RH, substitute chkconfig.
6604 Revision 1.89 2002/04/23 21:05:28 oes
6605 Added hint for startup on Red Hat
6607 Revision 1.88 2002/04/23 05:37:54 hal9
6608 Add AmigaOS install stuff.
6610 Revision 1.87 2002/04/23 02:53:15 david__schmidt
6611 Updated OSX installation section
6612 Added a few English tweaks here an there
6614 Revision 1.86 2002/04/21 01:46:32 hal9
6615 Re-write actions section.
6617 Revision 1.85 2002/04/18 21:23:23 hal9
6618 Fix ugly typo (mine).
6620 Revision 1.84 2002/04/18 21:17:13 hal9
6621 Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
6623 Revision 1.83 2002/04/18 18:21:12 oes
6624 Added RPM install detail
6626 Revision 1.82 2002/04/18 12:04:50 oes
6629 Revision 1.81 2002/04/18 11:50:24 oes
6630 Extended Install section - needs fixing by packagers
6632 Revision 1.80 2002/04/18 10:45:19 oes
6633 Moved text to buildsource.sgml, renamed some filters, details
6635 Revision 1.79 2002/04/18 03:18:06 hal9
6636 Spellcheck, and minor touchups.
6638 Revision 1.78 2002/04/17 18:04:16 oes
6641 Revision 1.77 2002/04/17 13:51:23 oes
6642 Proofreading, part one
6644 Revision 1.76 2002/04/16 04:25:51 hal9
6645 -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
6646 -Note about proxy may need requests to re-read config files.
6648 Revision 1.75 2002/04/12 02:08:48 david__schmidt
6649 Remove OS/2 building info... it is already in the developer-manual
6651 Revision 1.74 2002/04/11 00:54:38 hal9
6652 Add small section on submitting actions.
6654 Revision 1.73 2002/04/10 18:45:15 swa
6657 Revision 1.72 2002/04/10 04:06:19 hal9
6658 Added actions feedback to Bookmarklets section
6660 Revision 1.71 2002/04/08 22:59:26 hal9
6661 Version update. Spell chkconfig correctly :)
6663 Revision 1.70 2002/04/08 20:53:56 swa
6666 Revision 1.69 2002/04/06 05:07:29 hal9
6667 -Add privoxy-man-page.sgml, for man page.
6668 -Add authors.sgml for AUTHORS (and p-authors.sgml)
6669 -Reworked various aspects of various docs.
6670 -Added additional comments to sub-docs.
6672 Revision 1.68 2002/04/04 18:46:47 swa
6673 consistent look. reuse of copyright, history et. al.
6675 Revision 1.67 2002/04/04 17:27:57 swa
6676 more single file to be included at multiple points. make maintaining easier
6678 Revision 1.66 2002/04/04 06:48:37 hal9
6679 Structural changes to allow for conditional inclusion/exclusion of content
6680 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
6681 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
6682 eventually be set by Makefile.
6683 More boilerplate text for use across multiple docs.
6685 Revision 1.65 2002/04/03 19:52:07 swa
6686 enhance squid section due to user suggestion
6688 Revision 1.64 2002/04/03 03:53:43 hal9
6689 A few minor bug fixes, and touch ups. Ready for review.
6691 Revision 1.63 2002/04/01 16:24:49 hal9
6692 Define entities to include boilerplate text. See doc/source/*.
6694 Revision 1.62 2002/03/30 04:15:53 hal9
6695 - Fix privoxy.org/config links.
6696 - Paste in Bookmarklets from Toggle page.
6697 - Move Quickstart nearer top, and minor rework.
6699 Revision 1.61 2002/03/29 01:31:08 hal9
6702 Revision 1.60 2002/03/27 01:57:34 hal9
6703 Added more to Anatomy section.
6705 Revision 1.59 2002/03/27 00:54:33 hal9
6706 Touch up intro for new name.
6708 Revision 1.58 2002/03/26 22:29:55 swa
6709 we have a new homepage!
6711 Revision 1.57 2002/03/24 20:33:30 hal9
6712 A few minor catch ups with name change.
6714 Revision 1.56 2002/03/24 16:17:06 swa
6715 configure needs to be generated.
6717 Revision 1.55 2002/03/24 16:08:08 swa
6718 we are too lazy to make a block-built
6719 privoxy logo. hence removed the option.
6721 Revision 1.54 2002/03/24 15:46:20 swa
6722 name change related issue.
6724 Revision 1.53 2002/03/24 11:51:00 swa
6725 name change. changed filenames.
6727 Revision 1.52 2002/03/24 11:01:06 swa
6730 Revision 1.51 2002/03/23 15:13:11 swa
6731 renamed every reference to the old name with foobar.
6732 fixed "application foobar application" tag, fixed
6733 "the foobar" with "foobar". left junkbustser in cvs
6734 comments and remarks to history untouched.
6736 Revision 1.50 2002/03/23 05:06:21 hal9
6739 Revision 1.49 2002/03/21 17:01:05 hal9
6740 New section in Appendix.
6742 Revision 1.48 2002/03/12 06:33:01 hal9
6743 Catching up to Andreas and re_filterfile changes.
6745 Revision 1.47 2002/03/11 13:13:27 swa
6746 correct feedback channels
6748 Revision 1.46 2002/03/10 00:51:08 hal9
6749 Added section on JB internal pages in Appendix.
6751 Revision 1.45 2002/03/09 17:43:53 swa
6754 Revision 1.44 2002/03/09 17:08:48 hal9
6755 New section on Jon's actions file editor, and move some stuff around.
6757 Revision 1.43 2002/03/08 00:47:32 hal9
6758 Added imageblock{pattern}.
6760 Revision 1.42 2002/03/07 18:16:55 swa
6763 Revision 1.41 2002/03/07 16:46:43 hal9
6764 Fix a few markup problems for jade.
6766 Revision 1.40 2002/03/07 16:28:39 swa
6767 provide correct feedback channels
6769 Revision 1.39 2002/03/06 16:19:28 hal9
6770 Note on perceived filtering slowdown per FR.
6772 Revision 1.38 2002/03/05 23:55:14 hal9
6773 Stupid I did it again. Double hyphen in comment breaks jade.
6775 Revision 1.37 2002/03/05 23:53:49 hal9
6776 jade barfs on '- -' embedded in comments. - -user option broke it.
6778 Revision 1.36 2002/03/05 22:53:28 hal9
6779 Add new - - user option.
6781 Revision 1.35 2002/03/05 00:17:27 hal9
6782 Added section on command line options.
6784 Revision 1.34 2002/03/04 19:32:07 oes
6785 Changed default port to 8118
6787 Revision 1.33 2002/03/03 19:46:13 hal9
6788 Emphasis on where/how to report bugs, etc
6790 Revision 1.32 2002/03/03 09:26:06 joergs
6791 AmigaOS changes, config is now loaded from PROGDIR: instead of
6792 AmiTCP:db/junkbuster/ if no configuration file is specified on the
6795 Revision 1.31 2002/03/02 22:45:52 david__schmidt
6798 Revision 1.30 2002/03/02 22:00:14 hal9
6799 Updated 'New Features' list. Ran through spell-checker.
6801 Revision 1.29 2002/03/02 20:34:07 david__schmidt
6802 Update OS/2 build section
6804 Revision 1.28 2002/02/24 14:34:24 jongfoster
6805 Formatting changes. Now changing the doctype to DocBook XML 4.1
6806 will work - no other changes are needed.
6808 Revision 1.27 2002/01/11 14:14:32 hal9
6809 Added a very short section on Templates
6811 Revision 1.26 2002/01/09 20:02:50 hal9
6812 Fix bug re: auto-detect config file changes.
6814 Revision 1.25 2002/01/09 18:20:30 hal9
6815 Touch ups for *.action files.
6817 Revision 1.24 2001/12/02 01:13:42 hal9
6820 Revision 1.23 2001/12/02 00:20:41 hal9
6821 Updates for recent changes.
6823 Revision 1.22 2001/11/05 23:57:51 hal9
6824 Minor update for startup now daemon mode.
6826 Revision 1.21 2001/10/31 21:11:03 hal9
6827 Correct 2 minor errors
6829 Revision 1.18 2001/10/24 18:45:26 hal9
6830 *** empty log message ***
6832 Revision 1.17 2001/10/24 17:10:55 hal9
6833 Catching up with Jon's recent work, and a few other things.
6835 Revision 1.16 2001/10/21 17:19:21 swa
6836 wrong url in documentation
6838 Revision 1.15 2001/10/14 23:46:24 hal9
6839 Various minor changes. Fleshed out SEE ALSO section.
6841 Revision 1.13 2001/10/10 17:28:33 hal9
6844 Revision 1.12 2001/09/28 02:57:04 hal9
6847 Revision 1.11 2001/09/28 02:25:20 hal9
6850 Revision 1.9 2001/09/27 23:50:29 hal9
6851 A few changes. A short section on regular expression in appendix.
6853 Revision 1.8 2001/09/25 00:34:59 hal9
6854 Some additions, and re-arranging.
6856 Revision 1.7 2001/09/24 14:31:36 hal9
6859 Revision 1.6 2001/09/24 14:10:32 hal9
6860 Including David's OS/2 installation instructions.
6862 Revision 1.2 2001/09/13 15:27:40 swa
6865 Revision 1.1 2001/09/12 15:36:41 swa
6866 source files for junkbuster documentation
6868 Revision 1.3 2001/09/10 17:43:59 swa
6869 first proposal of a structure.
6871 Revision 1.2 2001/06/13 14:28:31 swa
6872 docs should have an author.
6874 Revision 1.1 2001/06/13 14:20:37 swa
6875 first import of project's documentation for the webserver.
projects / privoxy.git / blob