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 p-version "2.9.14">
12 <!entity p-status "beta">
13 <!entity % p-not-stable "INCLUDE">
14 <!entity % p-stable "IGNORE">
15 <!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
16 <!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
17 <!entity % p-readme "IGNORE">
18 <!entity % p-config "IGNORE">
19 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
22 File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
25 This file belongs into
26 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
28 $Id: user-manual.sgml,v 1.92 2002/04/25 18:55:13 hal9 Exp $
30 Written by and Copyright (C) 2001 the SourceForge
31 Privoxy team. http://www.privoxy.org/
33 Based on the Internet Junkbuster originally written
34 by and Copyright (C) 1997 Anonymous Coders and
35 Junkbusters Corporation. http://www.junkbusters.com
38 ========================================================================
39 NOTE: Please read developer-manual/documentation.html before touching
40 anything in this, or other Privoxy documentation.
41 ========================================================================
47 <title>Privoxy User Manual</title>
49 <pubdate>$Id: user-manual.sgml,v 1.92 2002/04/25 18:55:13 hal9 Exp $</pubdate>
54 <orgname>By: Privoxy Developers</orgname>
63 This is here to keep vim syntax file from breaking :/
64 If I knew enough to fix it, I would.
65 PLEASE DO NOT REMOVE! HB: hal@foobox.net
71 The user manual gives users information on how to install, configure and use
73 url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
76 <!-- Include privoxy.sgml boilerplate: -->
78 <!-- end privoxy.sgml -->
81 You can find the latest version of the user manual at <ulink
82 url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
83 Please see the <ulink url="contact.html">Contact section</ulink> on how to
84 contact the developers.
88 <!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
94 <!-- ~~~~~ New section ~~~~~ -->
95 <sect1 id="intro" label=""><title></title>
96 <!-- dummy section to force TOC on page by itself -->
97 <!-- DO NOT REMOVE! please ;) -->
101 <!-- ~~~~~ New section ~~~~~ -->
103 <sect1 label="1" id="introduction"><title>Introduction</title>
105 This documentation is included with the current &p-status; version of
106 <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
107 and is mostly complete at this point. The most up to date reference for the
108 time being is still the comments in the source files and in the individual
109 configuration files. Development of version 3.0 is currently nearing
110 completion, and includes many significant changes and enhancements over
111 earlier versions. The target release date for
112 stable v3.0 is <quote>soon</quote> ;-)]]>.
115 <!-- include only in non-stable versions -->
118 Since this is a &p-status; version, not all new features are well tested. This
119 documentation may be slightly out of sync as a result (especially with
120 CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
125 <!-- ~~~~~ New section ~~~~~ -->
126 <sect2 id="newfeatures">
127 <title>New Features</title>
129 In addition to <application>Internet Junkbuster's</application> traditional
130 features of ad and banner blocking and cookie management,
131 <application>Privoxy</application> provides new features<![%p-not-stable;[,
132 some of them currently under development]]>:
135 <!-- Include newfeatures.sgml boilerplate here: -->
137 <!-- end boilerplate -->
142 <!-- ~ End section ~ -->
145 <!-- ~~~~~ New section ~~~~~ -->
146 <sect1 id="installation"><title>Installation</title>
149 <application>Privoxy</application> is available both in convenient pre-compiled
150 packages for a wide range of operating systems, and as raw source code.
151 For most users, we recommend using the packages, which can be downloaded from our
152 <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
156 If you like to live on the bleeding edge and are not afraid of using
157 possibly unstable development versions, you can check out the up-to-the-minute
158 version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
159 CVS repository</ulink> or simply download <ulink
160 url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
164 <!-- Include supported.sgml boilerplate -->
166 <!-- end boilerplate -->
168 <!-- ~~~~~ New section ~~~~~ -->
169 <sect2 id="installation-packages"><title>Binary Packages</title>
172 Note: If you have a previous <application>Junkbuster</application> or
173 <application>Privoxy</application> installation on your system, you
174 will need to remove it. Some platforms do this for you as part
175 of their installation procedure. (See below for your platform).
179 In any case <emphasis>be sure to backup your old configuration
180 if it is valuable to you.</emphasis> See the
181 <link linkend="upgradersnote">note to upgraders</link>.
185 How to install the binary packages depends on your operating system:
188 <!-- ~~~~~ New section ~~~~~ -->
189 <sect3 id="installation-pack-rpm"><title>Red Hat and SuSE RPMs</title>
192 RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
193 and will use <filename>/etc/privoxy</filename> for the location
194 of configuration files.
198 Note that on Red Hat, <application>Privoxy</application> will not be
199 automatically started on system boot. You will need to enable that using
200 <command>chkconfig</command>, <command>ntsysv</command>, or similar method.
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.
233 <!-- ~~~~~ New section ~~~~~ -->
234 <sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
237 Create a new directory, <literal>cd</literal> to it, then unzip and
238 untar the archive. For the most part, you'll have to figure out where
243 <!-- ~~~~~ New section ~~~~~ -->
244 <sect3 id="installation-os2"><title>OS/2</title>
247 First, make sure that no previous installations of
248 <application>Junkbuster</application> and / or
249 <application>Privoxy</application> are left on your
250 system. You can do this by
254 Then, just double-click the WarpIN self-installing archive, which will
255 guide you through the installation process. A shadow of the
256 <application>Privoxy</application> executable will be placed in your
257 startup folder so it will start automatically whenever OS/2 starts.
261 The directory you choose to install <application>Privoxy</application>
262 into will contain all of the configuration files.
266 <!-- ~~~~~ New section ~~~~~ -->
267 <sect3 id="installation-mac"><title>Max OSX</title>
269 Unzip the downloaded package (you can either double-click on the file
270 in the finder, or on the desktop if you downloaded it there). Then,
271 double-click on the package installer icon and follow the installation
273 <application>Privoxy</application> will be installed in the subdirectory
274 <literal>/Applications/Privoxy.app</literal>.
275 <application>Privoxy</application> will set itself up to start
276 automatically on system bring-up via
277 <literal>/System/Library/StartupItems/Privoxy</literal>.
281 <!-- ~~~~~ New section ~~~~~ -->
282 <sect3 id="installation-amiga"><title>AmigaOS</title>
284 Copy and then unpack the <filename>lha</filename> archive to a suitable location.
285 All necessary files will be installed into <application>Privoxy</application>
286 directory, including all configuration and log files. To uninstall, just
287 remove this directory.
290 Start <application>Privoxy</application> (with RUN <>NIL:) in your
291 <filename>startnet</filename> script (AmiTCP), in
292 <filename>s:user-startup</filename> (RoadShow), as startup program in your
293 startup script (Genesis), or as startup action (Miami and MiamiDx).
294 <application>Privoxy</application> will automatically quit when you quit your
295 TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
296 <application>Privoxy</application> is still running).
301 <!-- ~~~~~ New section ~~~~~ -->
302 <sect2 id="installation-source"><title>Building from Source</title>
304 <!-- include buildsource.sgml boilerplate: -->
306 <!-- end boilerplate -->
311 <!-- ~ End section ~ -->
314 <!-- ~~~~~ New section ~~~~~ -->
316 <sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
319 <!-- ~~~~~ New section ~~~~~ -->
320 <sect2 id="upgradersnote">
321 <title>Note to Upgraders</title>
323 There are very significant changes from older versions of
324 <application>Junkbuster</application> to the current
325 <application>Privoxy</application>. Configuration is substantially
326 changed. <application>Junkbuster 2.0.x</application> and earlier
327 configuration files will not migrate. The functionality of the old
328 <filename>blockfile</filename>, <filename>cookiefile</filename> and
329 <filename>imagelist</filename>, are now combined into the
330 <quote>actions files</quote>. <filename>default.action</filename>,
331 is the main actions file. Local exceptions should best be put into
332 <filename>user.action</filename>.
335 A <quote>filter file</quote> (typically <filename>default.filter</filename>)
336 is new as of <application>Privoxy 2.9.x</application>, and provides some
337 of the new sophistication (explained below). <filename>config</filename> is
338 much the same as before.
341 If upgrading from a 2.0.x version, you will have to use the new config
342 files, and possibly adapt any personal rules from your older files.
343 When porting personal rules over from the old <filename>blockfile</filename>
344 to the new actions files, please note that even the pattern syntax has
345 changed. If upgrading from 2.9.x development versions, it is still
346 recommended to use the new configuration files.
349 A quick list of things to be aware of before upgrading:
357 The default listening port is now 8118 due to a conflict with another
363 Some installers may remove earlier versions completely. Save any
364 important configuration files!
369 <application>Privoxy</application> is controllable with a web browser
370 at the special URL: <ulink
371 url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
372 (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
373 aspects of configuration can be done here, including temporarily disabling
374 <application>Privoxy</application>.
379 The primary configuration file for cookie management, ad and banner
380 blocking, and many other aspects of <application>Privoxy</application>
381 configuration is in the <quote>actions</quote> files. It is strongly
382 recommended to become familiar with the new actions concept below,
383 before modifying these files. Locally defined rules
384 should go into <filename>user.action</filename>.
389 <!-- I think it is best to keep this somewhat vague, in case -->
390 <!-- the situation changes under our feet. -->
391 Some installers may not automatically start
392 <application>Privoxy</application> after installation.
401 <!-- ~~~~~ New section ~~~~~ -->
403 <title>Starting <application>Privoxy</application></title>
405 Before launching <application>Privoxy</application> for the first time, you
406 will want to configure your browser(s) to use <application>Privoxy</application>
407 as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
408 and port 8118 (earlier versions used port 8000). This is the one
409 configuration step that must be done!
413 With <application>Netscape</application> (and
414 <application>Mozilla</application>), this can be set under <literal>Edit
415 -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
416 For <application>Internet Explorer</application>: <literal>Tools ->
417 Internet Properties -> Connections -> LAN Setting</literal>. Then,
418 check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
419 localhost, Port: 8118). Include if HTTPS proxy support too.
423 After doing this, flush your browser's disk and memory caches to force a
424 re-reading of all pages and to get rid of any ads that may be cached. You
425 are now ready to start enjoying the benefits of using
426 <application>Privoxy</application>!
431 <application>Privoxy</application> is typically started by specifying the
432 main configuration file to be used on the command line. Example Unix startup
439 # /usr/sbin/privoxy /etc/privoxy/config
445 See <link linkend="cmdoptions">below</link> for other command line options.
449 An init script is provided for SuSE and Red Hat.
453 For for SuSE: <command>rcprivoxy start</command>
457 For Red Hat and Debian: <command>/etc/rc.d/init.d/privoxy start</command>
462 If no configuration file is specified on the command line,
463 <application>Privoxy</application> will look for a file named
464 <filename>config</filename> in the current directory. Except on Win32 where
465 it will try <filename>config.txt</filename>. If no file is specified on the
466 command line and no default configuration file can be found,
467 <application>Privoxy</application> will fail to start.
472 The included default configuration files should give a reasonable starting
473 point. Most of the per site configuration is done in the
474 <quote>actions</quote> files. These are where various cookie actions are
475 defined, ad and banner blocking, and other aspects of
476 <application>Privoxy</application> configuration. There are several such
477 files included, with varying levels of aggressiveness.
481 You will probably want to keep an eye out for sites for which you may prefer
482 persistent cookies, and add these to your actions configuration as needed. By
483 default, most of these will be accepted only during the current browser
484 session (aka <quote>session cookies</quote>), unless you add them to the
485 configuration. If you want the browser to handle this instead, you will need
486 to edit <filename>user.action</filename> (or through the web based interface)
487 and disable this feature. If you use more than one browser, it would make
488 more sense to let <application>Privoxy</application> handle this. In which
489 case, the browser(s) should be set to accept all cookies.
493 Another feature where you will probably want to define exceptions for trusted
494 sites is the popup-killing (through the <literal>+popup</literal> and
495 <literal>+filter{popups}</literal> actions), because your favorite shopping,
496 banking, or leisure site may need popups (explained below).
500 <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
501 the optional 1.1 features are as yet supported. In the unlikely event that
502 you experience inexplicable problems with browsers that use HTTP/1.1 per default
503 (like <application>Mozilla</application> or recent versions of I.E.), you might
504 try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
505 Preferences -> Debug -> Networking</literal>.
506 Alternatively, set the <quote>+downgrade-http-version</quote> config option in
507 <filename>default.action</filename> which will downgrade your browser's HTTP
508 requests from HTTP/1.1 to HTTP/1.0 before processing them.
512 After running <application>Privoxy</application> for a while, you can
513 start to fine tune the configuration to suit your personal, or site,
514 preferences and requirements. There are many, many aspects that can
515 be customized. <quote>Actions</quote>
516 can be adjusted by pointing your browser to
517 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
518 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
519 and then follow the link to <quote>View & Change the Current Configuration</quote>.
520 (This is an internal page and does not require Internet access.)
524 In fact, various aspects of <application>Privoxy</application>
525 configuration can be viewed from this page, including
526 current configuration parameters, source code version numbers,
527 the browser's request headers, and <quote>actions</quote> that apply
528 to a given URL. In addition to the actions file
529 editor mentioned above, <application>Privoxy</application> can also
530 be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
534 If you encounter problems, try loading the page without
535 <application>Privoxy</application>. If that helps, enter the URL where
536 you have the problems into <ulink url="http://p.p/show-url-info">the browser
537 based rule tracing utility</ulink>. See which rules apply and why, and
538 then try turning them off for that site one after the other, until the problem
539 is gone. When you have found the culprit, you might want to turn the rest on
544 If the above paragraph sounds gibberish to you, you might want to <ulink
545 url="configuration.html#ACTIONSFILE">read more about the actions concept</ulink>
546 or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
551 If you can't get rid of the problem at all, think you've found a bug in
552 Privoxy, want to propose a new feature or smarter rules, please see the
553 section <ulink url="contact.html"><quote>Contacting the
554 Developers</quote></ulink> below.
560 <!-- ~~~~~ New section ~~~~~ -->
561 <sect2 id="cmdoptions">
562 <title>Command Line Options</title>
564 <application>Privoxy</application> may be invoked with the following
565 command-line options:
573 <emphasis>--version</emphasis>
576 Print version info and exit. Unix only.
581 <emphasis>--help</emphasis>
584 Print short usage info and exit. Unix only.
589 <emphasis>--no-daemon</emphasis>
592 Don't become a daemon, i.e. don't fork and become process group
593 leader, and don't detach from controlling tty. Unix only.
598 <emphasis>--pidfile FILE</emphasis>
602 On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
603 <emphasis>FILE</emphasis> on exit. Failure to create or delete the
604 <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
605 option is given, no PID file will be used. Unix only.
610 <emphasis>--user USER[.GROUP]</emphasis>
614 After (optionally) writing the PID file, assume the user ID of
615 <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
616 privileges are not sufficient to do so. Unix only.
621 <emphasis>configfile</emphasis>
624 If no <emphasis>configfile</emphasis> is included on the command line,
625 <application>Privoxy</application> will look for a file named
626 <quote>config</quote> in the current directory (except on Win32
627 where it will look for <quote>config.txt</quote> instead). Specify
628 full path to avoid confusion. If no config file is found,
629 <application>Privoxy</application> will fail to start.
640 <!-- ~ End section ~ -->
643 <!-- ~~~~~ New section ~~~~~ -->
644 <sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
646 All <application>Privoxy</application> configuration is stored
647 in text files. These files can be edited with a text editor.
648 Many important aspects of <application>Privoxy</application> can
649 also be controlled easily with a web browser.
653 <!-- ~~~~~ New section ~~~~~ -->
656 <title>Controlling <application>Privoxy</application> with Your Web Browser</title>
658 <application>Privoxy</application>'s user interface can be reached through the special
659 URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
660 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
661 which is a built-in page and works without Internet access.
662 You will see the following section:
666 <!-- Needs to be put in a table and colorized -->
669 <bridgehead renderas="sect2">Privoxy Menu</bridgehead>
673 ▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
676 ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
679 ▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
682 ▪ <ulink url="http://config.privoxy.org/show-url-info">Look up which actions apply to a URL and why</ulink>
685 ▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
693 This should be self-explanatory. Note the first item leads to an editor for the
694 <quote>actions list</quote>, which is where the ad, banner, cookie,
695 and URL blocking magic is configured as well as other advanced features of
696 <application>Privoxy</application>. This is an easy way to adjust various
697 aspects of <application>Privoxy</application> configuration. The actions
698 file, and other configuration files, are explained in detail below.
702 <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
703 have problems with your current actions and filters. You can in fact use
704 it as a test to see whether it is <application>Privoxy</application>
705 causing the problem or not. <application>Privoxy</application> continues
706 to run as a proxy in this case, but all filtering is disabled. There
707 is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
708 that you can toggle <application>Privoxy</application> with one click from
714 <!-- ~ End section ~ -->
719 <!-- ~~~~~ New section ~~~~~ -->
721 <sect2 id="confoverview">
722 <title>Configuration Files Overview</title>
724 For Unix, *BSD and Linux, all configuration files are located in
725 <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
726 AmigaOS these are all in the same directory as the
727 <application>Privoxy</application> executable. <![%p-not-stable;[ The name
728 and number of configuration files has changed from previous versions, and is
729 subject to change as development progresses.]]>
733 The installed defaults provide a reasonable starting point, though
734 some settings may be aggressive by some standards. For the time being, the
735 principle configuration files are:
743 The main configuration file is named <link linkend="config">config</link>
744 on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
745 on Windows. This is a required file.
751 <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>) is used to define
752 the default settings for various <quote>actions</quote> relating to images, banners,
753 pop-ups, access restrictions, banners and cookies.
756 Multiple actions files may be defined in <filename>config</filename>. These
757 are processed in the order they are defined. Local customizations and locally
758 preferred exceptions to the default policies as defined in
759 <filename>default.action</filename> are probably best applied in
760 <filename>user.action</filename>, which should be preserved across
761 upgrades. <filename>standard.action</filename> is also included. This is mostly
762 for <application>Privoxy's</application> internal use.
765 There is also a web based editor that can be accessed from
767 url="http://config.privoxy.org/show-status/">http://config.privoxy.org/show-status/</ulink>
769 url="http://p.p/show-status/">http://p.p/show-status/</ulink>) for the
770 various actions files.
776 <filename>default.filter</filename> (the <link linkend="filter-file">filter
777 file</link>) can be used to re-write the raw page content, including
778 viewable text as well as embedded HTML and JavaScript, and whatever else
779 lurks on any given web page. The filtering jobs are only pre-defined here;
780 whether to apply them or not is up to the actions files.
788 All files use the <quote><literal>#</literal></quote> character to denote a
789 comment (the rest of the line will be ignored) and understand line continuation
790 through placing a backslash ("<literal>\</literal>") as the very last character
791 in a line. If the <literal>#</literal> is preceded by a backslash, it looses
792 its special function. Placing a <literal>#</literal> in front of an otherwise
793 valid configuration line to prevent it from being interpreted is called "commenting
798 The actions files and <filename>default.filter</filename>
799 can use Perl style <link linkend="regex">regular expressions</link> for
804 After making any changes, there is no need to restart
805 <application>Privoxy</application> in order for the changes to take
806 effect. <application>Privoxy</application> detects such changes
807 automatically. Note, however, that it may take one or two additional
808 requests for the change to take effect. When changing the listening address
809 of <application>Privoxy</application>, these <quote>wake up</quote> requests
810 must obviously be sent to the <emphasis>old</emphasis> listening address.
815 While under development, the configuration content is subject to change.
816 The below documentation may not be accurate by the time you read this.
817 Also, what constitutes a <quote>default</quote> setting, may change, so
818 please check all your configuration files on important issues.
824 <!-- ~~~~~ New section ~~~~~ -->
827 <title>The Main Configuration File</title>
829 Again, the main configuration file is named <filename>config</filename> on
830 Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
831 Configuration lines consist of an initial keyword followed by a list of
832 values, all separated by whitespace (any number of spaces or tabs). For
840 <emphasis>confdir /etc/privoxy</emphasis>
847 Assigns the value <literal>/etc/privoxy</literal> to the option
848 <literal>confdir</literal> and thus indicates that the configuration
849 directory is named <quote>/etc/privoxy/</quote>.
853 All options in the config file except for <literal>confdir</literal> and
854 <literal>logdir</literal> are optional. Watch out in the below description
855 for what happens if you leave them unset.
859 The main config file controls all aspects of <application>Privoxy</application>'s
860 operation that are not location dependent (i.e. they apply universally, no matter
861 where you may be surfing).
865 <!-- ~~~~~ New section ~~~~~ -->
867 <sect3 id="conf-log-loc">
868 <title>Configuration and Log File Locations</title>
871 <application>Privoxy</application> can (and normally does) use a number of
872 other files for additional configuration and logging.
873 This section of the configuration file tells <application>Privoxy</application>
874 where to find those other files.
878 <sect4 id="confdir"><title>confdir</title>
882 <term>Specifies:</term>
884 <para>The directory where the other configuration files are located</para>
888 <term>Type of value:</term>
890 <para>Path name</para>
894 <term>Default value:</term>
896 <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
900 <term>Effect if unset:</term>
902 <para><emphasis>Mandatory</emphasis></para>
909 No trailing <quote><literal>/</literal></quote>, please
912 When development goes modular and multi-user, the blocker, filter, and
913 per-user config will be stored in subdirectories of <quote>confdir</quote>.
914 For now, the configuration directory structure is flat, except for
915 <filename>confdir/templates</filename>, where the HTML templates for CGI
916 output reside (e.g. <application>Privoxy's</application> 404 error page).
924 <sect4 id="logdir"><title>logdir</title>
928 <term>Specifies:</term>
931 The directory where all logging takes place (i.e. where <filename>logfile</filename> and
932 <filename>jarfile</filename> are located)
937 <term>Type of value:</term>
939 <para>Path name</para>
943 <term>Default value:</term>
945 <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
949 <term>Effect if unset:</term>
951 <para><emphasis>Mandatory</emphasis></para>
958 No trailing <quote><literal>/</literal></quote>, please
965 <sect4 id="actionsfile"><title>
966 <anchor id="default.action">
967 <anchor id="standard.action">
968 <anchor id="user.action">
974 <term>Specifies:</term>
977 The <link linkend="actions">actions</link> file(s) to use
982 <term>Type of value:</term>
984 <para>File name, relative to <literal>confdir</literal></para>
988 <term>Default value:</term>
992 <msgtext><literallayout> standard # Internal purposes, recommended not editing</literallayout></msgtext>
995 <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
998 <msgtext><literallayout> user # User customizations</literallayout></msgtext>
1004 <term>Effect if unset:</term>
1007 No actions are taken at all. Simple neutral proxying.
1015 Multiple <literal>actionsfile</literal> lines are OK and are in fact recommended!
1018 The default values include standard.action, which is used for internal
1019 purposes and should be loaded, default.action, which is the
1020 <quote>main</quote> actions file maintained by the developers, and
1021 user.action, where you can make your personal additions.
1024 There is no point in using <application>Privoxy</application> without an actions file.
1031 <sect4 id="filterfile"><title><anchor id="default.filter">filterfile</title>
1034 <term>Specifies:</term>
1037 The <link linkend="filter">filter</link> file to use
1042 <term>Type of value:</term>
1044 <para>File name, relative to <literal>confdir</literal></para>
1048 <term>Default value:</term>
1050 <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
1054 <term>Effect if unset:</term>
1057 No textual content filtering takes place, i.e. all
1058 <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
1059 actions in the actions files are turned off
1067 The <quote>default.filter</quote> file contains content modification rules
1068 that use <quote>regular expressions</quote>. These rules permit powerful
1069 changes on the content of Web pages, e.g., you could disable your favorite
1070 JavaScript annoyances, re-write the actual displayed text, or just have some
1071 fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
1072 it appears on a Web page.
1079 <sect4 id="logfile"><title>logfile</title>
1083 <term>Specifies:</term>
1091 <term>Type of value:</term>
1093 <para>File name, relative to <literal>logdir</literal></para>
1097 <term>Default value:</term>
1099 <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
1103 <term>Effect if unset:</term>
1106 No log file is used, all log messages go to the console (<literal>stderr</literal>).
1114 The windows version will additionally log to the console.
1117 The logfile is where all logging and error messages are written. The level
1118 of detail and number of messages are set with the <literal>debug</literal>
1119 option (see below). The logfile can be useful for tracking down a problem with
1120 <application>Privoxy</application> (e.g., it's not blocking an ad you
1121 think it should block) but in most cases you probably will never look at it.
1124 Your logfile will grow indefinitely, and you will probably want to
1125 periodically remove it. On Unix systems, you can do this with a cron job
1126 (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
1127 script has been included.
1130 On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
1131 +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
1132 the effect that cron.daily will automatically archive, gzip, and empty the
1133 log, when it exceeds 1M size.
1140 <sect4 id="jarfile"><title>jarfile</title>
1144 <term>Specifies:</term>
1147 The file to store intercepted cookies in
1152 <term>Type of value:</term>
1154 <para>File name, relative to <literal>logdir</literal></para>
1158 <term>Default value:</term>
1160 <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
1164 <term>Effect if unset:</term>
1167 Intercepted cookies are not stored at all.
1175 The jarfile may grow to ridiculous sizes over time.
1182 <sect4 id="trustfile"><title>trustfile</title>
1186 <term>Specifies:</term>
1189 The trust file to use
1194 <term>Type of value:</term>
1196 <para>File name, relative to <literal>confdir</literal></para>
1200 <term>Default value:</term>
1202 <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
1206 <term>Effect if unset:</term>
1209 The whole trust mechanism is turned off.
1217 The trust mechanism is an experimental feature for building white-lists and should
1218 be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
1221 If you specify a trust file, <application>Privoxy</application> will only allow
1222 access to sites that are named in the trustfile.
1223 You can also mark sites as trusted referrers (with <literal>+</literal>), with
1224 the effect that access to untrusted sites will be granted, if a link from a
1225 trusted referrer was used.
1226 The link target will then be added to the <quote>trustfile</quote>.
1227 Possible applications include limiting Internet access for children.
1230 If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
1239 <!-- ~ End section ~ -->
1243 <!-- ~~~~~ New section ~~~~~ -->
1245 <sect3 id="local-set-up">
1246 <title>Local Set-up Documentation</title>
1249 If you intend to operate <application>Privoxy</application> for more users
1250 that just yourself, it might be a good idea to let them know how to reach
1251 you, what you block and why you do that, your policies etc.
1254 <sect4 id="trust-info-url"><title>trust-info-url</title>
1258 <term>Specifies:</term>
1261 A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
1266 <term>Type of value:</term>
1272 <term>Default value:</term>
1274 <para>Two example URL are provided</para>
1278 <term>Effect if unset:</term>
1281 No links are displayed on the "untrusted" error page.
1289 The value of this option only matters if the experimental trust mechanism has been
1290 activated. (See <literal>trustfile</literal> above.)
1293 If you use the trust mechanism, it is a good idea to write up some on-line
1294 documentation about your trust policy and to specify the URL(s) here.
1295 Use multiple times for multiple URLs.
1298 The URL(s) should be added to the trustfile as well, so users don't end up
1299 locked out from the information on why they were locked out in the first place!
1306 <sect4 id="admin-address"><title>admin-address</title>
1310 <term>Specifies:</term>
1313 An email address to reach the proxy administrator.
1318 <term>Type of value:</term>
1320 <para>Email address</para>
1324 <term>Default value:</term>
1326 <para><emphasis>Unset</emphasis></para>
1330 <term>Effect if unset:</term>
1333 No email address is displayed on error pages and the CGI user interface.
1341 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1342 are unset, the whole "Local Privoxy Support" box on all generated pages will
1350 <sect4 id="proxy-info-url"><title>proxy-info-url</title>
1354 <term>Specifies:</term>
1357 A URL to documentation about the local <application>Privoxy</application> setup,
1358 configuration or policies.
1363 <term>Type of value:</term>
1369 <term>Default value:</term>
1371 <para><emphasis>Unset</emphasis></para>
1375 <term>Effect if unset:</term>
1378 No link to local documentation is displayed on error pages and the CGI user interface.
1386 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1387 are unset, the whole "Local Privoxy Support" box on all generated pages will
1391 This URL shouldn't be blocked ;-)
1399 <!-- ~ End section ~ -->
1401 <!-- ~~~~~ New section ~~~~~ -->
1403 <sect3 id="debugging">
1404 <title>Debugging</title>
1407 These options are mainly useful when tracing a problem.
1408 Note that you might also want to invoke
1409 <application>Privoxy</application> with the <literal>--no-daemon</literal>
1410 command line option when debugging.
1413 <sect4 id="debug"><title>debug</title>
1417 <term>Specifies:</term>
1420 Key values that determine what information gets logged.
1425 <term>Type of value:</term>
1427 <para>Integer values</para>
1431 <term>Default value:</term>
1433 <para>12289 (i.e.: URLs plus informational and warning messages)</para>
1437 <term>Effect if unset:</term>
1440 Nothing gets logged.
1448 The available debug levels are:
1452 debug 1 # show each GET/POST/CONNECT request
1453 debug 2 # show each connection status
1454 debug 4 # show I/O status
1455 debug 8 # show header parsing
1456 debug 16 # log all data into the logfile
1457 debug 32 # debug force feature
1458 debug 64 # debug regular expression filter
1459 debug 128 # debug fast redirects
1460 debug 256 # debug GIF de-animation
1461 debug 512 # Common Log Format
1462 debug 1024 # debug kill pop-ups
1463 debug 4096 # Startup banner and warnings.
1464 debug 8192 # Non-fatal errors
1468 To select multiple debug levels, you can either add them or use
1469 multiple <literal>debug</literal> lines.
1472 A debug level of 1 is informative because it will show you each request
1473 as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
1474 so that you will notice when things go wrong. The other levels are probably
1475 only of interest if you are hunting down a specific problem. They can produce
1476 a hell of an output (especially 16).
1480 The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
1481 <application>Privoxy</application>) is always on and cannot be disabled.
1484 If you want to use CLF (Common Log Format), you should set <quote>debug
1485 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
1492 <sect4 id="single-threaded"><title>single-threaded</title>
1496 <term>Specifies:</term>
1499 Whether to run only one server thread
1504 <term>Type of value:</term>
1506 <para><emphasis>None</emphasis></para>
1510 <term>Default value:</term>
1512 <para><emphasis>Unset</emphasis></para>
1516 <term>Effect if unset:</term>
1519 Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1520 serve multiple requests simultaneously.
1528 This option is only there for debug purposes and you should never
1529 need to use it. <emphasis>It will drastically reduce performance.</emphasis>
1538 <!-- ~~~~~ New section ~~~~~ -->
1540 <sect3 id="access-control">
1541 <title>Access Control and Security</title>
1544 This section of the config file controls the security-relevant aspects
1545 of <application>Privoxy</application>'s configuration.
1548 <sect4 id="listen-address"><title>listen-address</title>
1552 <term>Specifies:</term>
1555 The IP address and TCP port on which <application>Privoxy</application> will
1556 listen for client requests.
1561 <term>Type of value:</term>
1563 <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
1567 <term>Default value:</term>
1569 <para>localhost:8118</para>
1573 <term>Effect if unset:</term>
1576 Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
1577 home users who run <application>Privoxy</application> on the same machine as
1586 You will need to configure your browser(s) to this proxy address and port.
1589 If you already have another service running on port 8118, or if you want to
1590 serve requests from other machines (e.g. on your local network) as well, you
1591 will need to override the default.
1594 If you leave out the IP address, <application>Privoxy</application> will
1595 bind to all interfaces (addresses) on your machine and may become reachable
1596 from the Internet. In that case, consider using access control lists (ACL's)
1597 (see <quote>ACLs</quote> below), or a firewall.
1602 <term>Example:</term>
1605 Suppose you are running <application>Privoxy</application> on
1606 a machine which has the address 192.168.0.1 on your local private network
1607 (192.168.0.0) and has another outside connection with a different address.
1608 You want it to serve requests from inside only:
1612 listen-address 192.168.0.1:8118
1620 <sect4 id="toggle"><title>toggle</title>
1624 <term>Specifies:</term>
1627 Initial state of "toggle" status
1632 <term>Type of value:</term>
1638 <term>Default value:</term>
1644 <term>Effect if unset:</term>
1647 Act as if toggled on
1655 If set to 0, <application>Privoxy</application> will start in
1656 <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
1657 proxy. See <literal>enable-remote-toggle</literal>
1658 below. This is not really useful anymore, since toggling is much easier
1659 via <ulink url="http://config.privoxy.org/toggle">the web
1660 interface</ulink> then via editing the <filename>conf</filename> file.
1663 The windows version will only display the toggle icon in the system tray
1664 if this option is present.
1672 <sect4 id="enable-remote-toggle"><title>enable-remote-toggle</title>
1675 <term>Specifies:</term>
1678 Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
1679 feature</ulink> may be used
1684 <term>Type of value:</term>
1690 <term>Default value:</term>
1696 <term>Effect if unset:</term>
1699 The web-based toggle feature is disabled.
1707 When toggled off, <application>Privoxy</application> acts like a normal,
1708 content-neutral proxy, i.e. it acts as if none of the actions applied to
1712 For the time being, access to the toggle feature can <emphasis>not</emphasis> be
1713 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1714 so that everybody who can access <application>Privoxy</application> (see
1715 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1716 toggle it for all users. So this option is <emphasis>not recommended</emphasis>
1717 for multi-user environments with untrusted users.
1720 Note that you must have compiled <application>Privoxy</application> with
1721 support for this feature, otherwise this option has no effect.
1729 <sect4 id="enable-edit-actions"><title>enable-edit-actions</title>
1732 <term>Specifies:</term>
1735 Whether or not the <ulink url="http://config.privoxy.org/show-status">web-based actions
1736 file editor</ulink> may be used
1741 <term>Type of value:</term>
1747 <term>Default value:</term>
1753 <term>Effect if unset:</term>
1756 The web-based actions file editor is disabled.
1764 For the time being, access to the editor can <emphasis>not</emphasis> be
1765 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1766 so that everybody who can access <application>Privoxy</application> (see
1767 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1768 modify its configuration for all users. So this option is <emphasis>not
1769 recommended</emphasis> for multi-user environments with untrusted users.
1772 Note that you must have compiled <application>Privoxy</application> with
1773 support for this feature, otherwise this option has no effect.
1780 <sect4 id="acls"><title>
1781 <anchor id="permit-acces">
1782 <anchor id="deny-acces">
1783 ACLs: permit-access and deny-access</title>
1787 <term>Specifies:</term>
1790 Who can access what.
1795 <term>Type of value:</term>
1798 <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
1799 [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
1802 Where <replaceable class="parameter">src_addr</replaceable> and
1803 <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
1804 DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
1805 <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
1806 values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
1807 destination part are optional.
1812 <term>Default value:</term>
1814 <para><emphasis>Unset</emphasis></para>
1818 <term>Effect if unset:</term>
1821 Don't restrict access further than implied by <literal>listen-address</literal>
1829 Access controls are included at the request of ISPs and systems
1830 administrators, and <emphasis>are not usually needed by individual users</emphasis>.
1831 For a typical home user, it will normally suffice to ensure that
1832 <application>Privoxy</application> only listens on the localhost or internal (home)
1833 network address by means of the <literal>listen-address</literal> option.
1836 Please see the warnings in the FAQ that this proxy is not intended to be a substitute
1837 for a firewall or to encourage anyone to defer addressing basic security
1841 Multiple ACL lines are OK.
1842 If any ACLs are specified, then the <application>Privoxy</application>
1843 talks only to IP addresses that match at least one <literal>permit-access</literal> line
1844 and don't match any subsequent <literal>deny-access</literal> line. In other words, the
1845 last match wins, with the default being <literal>deny-access</literal>.
1848 If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
1849 for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
1850 that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
1851 of the ultimate target. This is necessary because it may be impossible for the local
1852 <application>Privoxy</application> to determine the IP address of the
1853 ultimate target (that's often what gateways are used for).
1856 You should prefer using IP addresses over DNS names, because the address lookups take
1857 time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
1858 like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
1859 IP addresses, only the first one is used.
1862 Denying access to particular sites by ACL may have undesired side effects
1863 if the site in question is hosted on a machine which also hosts other sites.
1868 <term>Examples:</term>
1871 Explicitly define the default behavior if no ACL and
1872 <literal>listen-address</literal> are set: <quote>localhost</quote>
1873 is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
1874 <emphasis>all</emphasis> destination addresses are OK:
1878 permit-access localhost
1882 Allow any host on the same class C subnet as www.privoxy.org access to
1883 nothing but www.example.com:
1887 permit-access www.privoxy.org/24 www.example.com/32
1891 Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1892 with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
1896 permit-access 192.168.45.64/26
1897 deny-access 192.168.45.73 www.dirty-stuff.example.com
1905 <sect4 id="buffer-limit"><title>buffer-limit</title>
1909 <term>Specifies:</term>
1912 Maximum size of the buffer for content filtering.
1917 <term>Type of value:</term>
1919 <para>Size in Kbytes</para>
1923 <term>Default value:</term>
1929 <term>Effect if unset:</term>
1932 Use a 4MB (4096 KB) limit.
1940 For content filtering, i.e. the <literal>+filter</literal> and
1941 <literal>+deanimate-gif</literal> actions, it is necessary that
1942 <application>Privoxy</application> buffers the entire document body.
1943 This can be potentially dangerous, since a server could just keep sending
1944 data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1948 When a document buffer size reaches the <literal>buffer-limit</literal>, it is
1949 flushed to the client unfiltered and no further attempt to
1950 filter the rest of the document is made. Remember that there may be multiple threads
1951 running, which might require up to <literal>buffer-limit</literal> Kbytes
1952 <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
1962 <!-- ~ End section ~ -->
1965 <!-- ~~~~~ New section ~~~~~ -->
1967 <sect3 id="forwarding">
1968 <title>Forwarding</title>
1971 This feature allows routing of HTTP requests through a chain of
1973 It can be used to better protect privacy and confidentiality when
1974 accessing specific domains by routing requests to those domains
1975 through an anonymous public proxy (see e.g. <ulink
1976 url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
1977 Or to use a caching proxy to speed up browsing. Or chaining to a parent
1978 proxy may be necessary because the machine that <application>Privoxy</application>
1979 runs on has no direct Internet access.
1983 Also specified here are SOCKS proxies. <application>Privoxy</application>
1984 supports the SOCKS 4 and SOCKS 4A protocols.
1987 <sect4 id="forward"><title>forward</title>
1990 <term>Specifies:</term>
1993 To which parent HTTP proxy specific requests should be routed.
1998 <term>Type of value:</term>
2001 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2002 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2005 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2006 chapter on domain matching in the <filename>default.action</filename> file),
2007 <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
2008 as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
2009 <quote>no forwarding</quote>, and the optional
2010 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
2011 values from 1 to 64535
2016 <term>Default value:</term>
2018 <para><emphasis>Unset</emphasis></para>
2022 <term>Effect if unset:</term>
2025 Don't use parent HTTP proxies.
2033 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2034 forwarded to another HTTP proxy but are made directly to the web servers.
2037 Multiple lines are OK, they are checked in sequence, and the last match wins.
2042 <term>Examples:</term>
2045 Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
2049 forward .* anon-proxy.example.org:8080
2054 Everything goes to our example ISP's caching proxy, except for requests
2055 to that ISP's sites:
2059 forward .*. caching-proxy.example-isp.net:8000
2060 forward .example-isp.net .
2068 <sect4 id="socks"><title>
2069 <anchor id="forward-socks4">
2070 <anchor id="forward-socks4a">
2071 forward-socks4 and forward-socks4a</title>
2075 <term>Specifies:</term>
2078 Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
2083 <term>Type of value:</term>
2086 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2087 <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
2088 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2091 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2092 chapter on domain matching in the <filename>default.action</filename> file),
2093 <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
2094 are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
2095 may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
2096 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
2101 <term>Default value:</term>
2103 <para><emphasis>Unset</emphasis></para>
2107 <term>Effect if unset:</term>
2110 Don't use SOCKS proxies.
2118 Multiple lines are OK, they are checked in sequence, and the last match wins.
2121 The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
2122 is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
2123 server, while in SOCKS 4 it happens locally.
2126 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2127 forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
2133 <term>Examples:</term>
2136 From the company example.com, direct connections are made to all
2137 <quote>internal</quote> domains, but everything outbound goes through
2138 their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
2143 forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
2144 forward .example.com .
2148 A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
2152 forward-socks4 .*. socks-gw.example.com:1080 .
2160 <sect4 id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>
2163 If you have links to multiple ISPs that provide various special content
2164 only to their subscribers, you can configure multiple <application>Privoxies</application>
2165 which have connections to the respective ISPs to act as forwarders to each other, so that
2166 <emphasis>your</emphasis> users can see the internal content of all ISPs.
2170 Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
2171 isp-b.net. Both run <application>Privoxy</application>. Their forwarding
2172 configuration can look like this:
2182 forward .isp-b.net host-b:8118
2193 forward .isp-a.net host-a:8118
2198 Now, your users can set their browser's proxy to use either
2199 host-a or host-b and be able to browse the internal content
2200 of both isp-a and isp-b.
2204 If you intend to chain <application>Privoxy</application> and
2205 <application>squid</application> locally, then chain as
2206 <literal>browser -> squid -> privoxy</literal> is the recommended way.
2210 Assuming that <application>Privoxy</application> and <application>squid</application>
2211 run on the same box, your squid configuration could then look like this:
2216 # Define Privoxy as parent proxy (without ICP)
2217 cache_peer 127.0.0.1 parent 8118 7 no-query
2219 # Define ACL for protocol FTP
2222 # Do not forward FTP requests to Privoxy
2223 always_direct allow ftp
2225 # Forward all the rest to Privoxy
2226 never_direct allow all
2231 You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
2232 Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
2239 <!-- ~ End section ~ -->
2242 <!-- ~~~~~ New section ~~~~~ -->
2244 <sect3 id="windows-gui">
2245 <title>Windows GUI Options</title>
2247 <application>Privoxy</application> has a number of options specific to the
2248 Windows GUI interface:
2251 <anchor id="activity-animation">
2253 If <quote>activity-animation</quote> is set to 1, the
2254 <application>Privoxy</application> icon will animate when
2255 <quote>Privoxy</quote> is active. To turn off, set to 0.
2262 <emphasis>activity-animation 1</emphasis>
2268 <anchor id="log-messages">
2270 If <quote>log-messages</quote> is set to 1,
2271 <application>Privoxy</application> will log messages to the console
2279 <emphasis>log-messages 1</emphasis>
2285 <anchor id="log-buffer-size">
2287 If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
2288 i.e. the amount of memory used for the log messages displayed in the
2289 console window, will be limited to <quote>log-max-lines</quote> (see below).
2293 Warning: Setting this to 0 will result in the buffer to grow infinitely and
2294 eat up all your memory!
2301 <emphasis>log-buffer-size 1</emphasis>
2307 <anchor id="log-max-lines">
2309 <application>log-max-lines</application> is the maximum number of lines held
2310 in the log buffer. See above.
2317 <emphasis>log-max-lines 200</emphasis>
2323 <anchor id="log-highlight-messages">
2325 If <quote>log-highlight-messages</quote> is set to 1,
2326 <application>Privoxy</application> will highlight portions of the log
2327 messages with a bold-faced font:
2334 <emphasis>log-highlight-messages 1</emphasis>
2340 <anchor id="log-font-name">
2342 The font used in the console window:
2349 <emphasis>log-font-name Comic Sans MS</emphasis>
2355 <anchor id="log-font-size">
2357 Font size used in the console window:
2364 <emphasis>log-font-size 8</emphasis>
2370 <anchor id="show-on-task-bar">
2372 <quote>show-on-task-bar</quote> controls whether or not
2373 <application>Privoxy</application> will appear as a button on the Task bar
2381 <emphasis>show-on-task-bar 0</emphasis>
2387 <anchor id="close-button-minimizes">
2389 If <quote>close-button-minimizes</quote> is set to 1, the Windows close
2390 button will minimize <application>Privoxy</application> instead of closing
2391 the program (close with the exit option on the File menu).
2398 <emphasis>close-button-minimizes 1</emphasis>
2404 <anchor id="hide-console">
2406 The <quote>hide-console</quote> option is specific to the MS-Win console
2407 version of <application>Privoxy</application>. If this option is used,
2408 <application>Privoxy</application> will disconnect from and hide the
2425 <!-- ~ End section ~ -->
2428 <!-- ~~~~~ New section ~~~~~ -->
2429 <sect2 id="actions-file">
2430 <title>Actions Files</title>
2433 The actions files are used to define what actions
2434 <application>Privoxy</application> takes for which URLs, and thus determines
2435 how ad images, cookies and various other aspects of HTTP content and
2436 transactions are handled, and on which sites (or even parts thereof). There
2437 are three such files included with <application>Privoxy</application>,
2438 with slightly different purposes. <filename>default.action</filename> sets
2439 the default policies. <filename>standard.action</filename> is used by
2440 <application>Privoxy</application> and the web based editor to set
2441 pre-defined values (and normally should not be edited). Local exceptions
2442 are best done in <filename>user.action</filename>. The content of these
2443 can all be viewed and edited from <ulink
2444 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2448 Anything you want can blocked, including ads, banners, or just some obnoxious
2449 URL that you would rather not see is done here. Cookies can be accepted or rejected, or
2450 accepted only during the current browser session (i.e. not written to disk),
2451 content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
2452 See below for a complete list of available actions.
2456 An actions file typically has sections. Near the top, <quote>aliases</quote> are
2457 optionally defined (discussed <ulink
2458 url="configuration.html#ALIASES">below</ulink>), then the default set of rules
2459 which will apply universally to all sites and pages. And then below that,
2460 exceptions to the defined universal policies.
2463 <!-- ~~~~~ New section ~~~~~ -->
2465 <title>Finding the Right Mix</title>
2467 Note that some <link linkend="actions">actions</link> like cookie suppression
2468 or script disabling may render some sites unusable, which rely on these
2469 techniques to work properly. Finding the right mix of actions is not easy and
2470 certainly a matter of personal taste. In general, it can be said that the more
2471 <quote>aggressive</quote> your default settings (in the top section of the
2472 actions file) are, the more exceptions for <quote>trusted</quote> sites you
2473 will have to make later. If, for example, you want to kill popup windows per
2474 default, you'll have to make exceptions from that rule for sites that you
2475 regularly use and that require popups for actually useful content, like maybe
2476 your bank, favorite shop, or newspaper.
2480 We have tried to provide you with reasonable rules to start from in the
2481 distribution actions files. But there is no general rule of thumb on these
2482 things. There just are too many variables, and sites are constantly changing.
2483 Sooner or later you will want to change the rules (and read this chapter again :).
2487 <!-- ~~~~~ New section ~~~~~ -->
2489 <title>How to Edit</title>
2491 The easiest way to edit the <quote>actions</quote> files is with a browser by
2492 using our browser-based editor, which can be reached from <ulink
2493 url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
2497 If you prefer plain text editing to GUIs, you can of course also directly edit the
2504 <title>How Actions are Applied to URLs</title>
2506 Actions files are divided into sections. There are special sections,
2507 like the <quote><link linkend="aliases">alias</link></quote> sections which will be discussed later. For now
2508 let's concentrate on regular sections: They have a heading line (often split
2509 up to multiple lines for readability) which consist of a list of actions,
2510 separated by whitespace and enclosed in curly braces. Below that, there
2511 is a list of URL patterns, each on a separate line.
2515 To determine which actions apply to a request, the URL of the request is
2516 compared to all patterns in this file. Every time it matches, the list of
2517 applicable actions for the URL is incrementally updated, using the heading
2518 of the section in which the pattern is located. If multiple matches for
2519 the same URL set the same action differently, the last match wins. If not,
2520 the effects are aggregated (e.g. a URL might match both the
2521 <ulink url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>
2522 and <ulink url="configuration.html#BLOCK"><quote>+block</quote></ulink> actions).
2527 You can trace this process by visiting <ulink
2528 url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2532 More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2533 Anatomy of an Action</link>.
2537 <!-- ~~~~~ New section ~~~~~ -->
2539 <title>Patterns</title>
2541 Generally, a pattern has the form <literal><domain>/<path></literal>,
2542 where both the <literal><domain></literal> and <literal><path></literal>
2543 are optional. (This is why the pattern <literal>/</literal> matches all URLs).
2548 <term><literal>www.example.com/</literal></term>
2551 is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2552 regardless of which document on that server is requested.
2557 <term><literal>www.example.com</literal></term>
2560 means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2566 <term><literal>www.example.com/index.html</literal></term>
2569 matches only the single document <literal>/index.html</literal>
2570 on <literal>www.example.com</literal>.
2575 <term><literal>/index.html</literal></term>
2578 matches the document <literal>/index.html</literal>, regardless of the domain,
2579 i.e. on <emphasis>any</emphasis> web server.
2584 <term><literal>index.html</literal></term>
2587 matches nothing, since it would be interpreted as a domain name and
2588 there is no top-level domain called <literal>.html</literal>.
2594 <sect4><title>The Domain Pattern</title>
2597 The matching of the domain part offers some flexible options: if the
2598 domain starts or ends with a dot, it becomes unanchored at that end.
2604 <term><literal>.example.com</literal></term>
2607 matches any domain that <emphasis>ENDS</emphasis> in
2608 <literal>.example.com</literal>
2613 <term><literal>www.</literal></term>
2616 matches any domain that <emphasis>STARTS</emphasis> with
2617 <literal>www.</literal>
2622 <term><literal>.example.</literal></term>
2625 matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
2626 (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
2633 Additionally, there are wild-cards that you can use in the domain names
2634 themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
2635 stands for zero or more arbitrary characters, <quote>?</quote> stands for
2636 any single character, you can define character classes in square
2637 brackets and all of that can be freely mixed:
2642 <term><literal>ad*.example.com</literal></term>
2645 matches <quote>adserver.example.com</quote>,
2646 <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2651 <term><literal>*ad*.example.com</literal></term>
2654 matches all of the above, and then some.
2659 <term><literal>.?pix.com</literal></term>
2662 matches <literal>www.ipix.com</literal>,
2663 <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2668 <term><literal>www[1-9a-ez].example.c*</literal></term>
2671 matches <literal>www1.example.com</literal>,
2672 <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2673 <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2674 <literal>wwww.example.com</literal>.
2682 <sect4><title>The Path Pattern</title>
2685 <application>Privoxy</application> uses Perl compatible regular expressions
2686 (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2691 There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2692 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2693 at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2694 You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2695 useful, which is available on-line at <ulink
2696 url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
2700 Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2701 i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
2702 for the beginning of a line).
2706 Please also note that matching in the path is case
2707 <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
2708 sensitive at any point in the pattern by using the
2709 <quote>(?-i)</quote> switch:
2710 <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
2711 documents whose path starts with <literal>PaTtErN</literal> in
2712 <emphasis>exactly</emphasis> this capitalization.
2718 <!-- ~ End section ~ -->
2721 <!-- ~~~~~ New section ~~~~~ -->
2723 <sect3 id="actions">
2724 <title>Actions</title>
2726 All actions are disabled by default, until they are explicitly enabled
2727 somewhere in an actions file. Actions are turned on if preceded with a
2728 <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
2729 <quote>+action</quote> means <quote>do that action</quote>, e.g.
2730 <quote>+block</quote> means please <quote>block the following URL
2735 Actions are invoked by enclosing the action name in curly braces (e.g.
2736 {+some_action}), followed by a list of URLs (or patterns that match URLs) to
2737 which the action applies. There are three classes of actions:
2745 Boolean, i.e the action can only be <quote>on</quote> or
2746 <quote>off</quote>. Examples:
2752 <emphasis>{+name}</emphasis> # enable this action
2753 <emphasis>{-name}</emphasis> # disable this action
2763 Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>,
2764 where some value is required in order to enable this type of action.
2771 <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
2772 <emphasis>{-name}</emphasis> # disable action (<quote>parameter</quote>) can be omitted
2781 <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
2782 Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> or
2783 <quote>{+/-send-wafer{name=value}}</quote>), where some value needs to be defined
2784 in addition to simply enabling the action. Examples:
2790 <emphasis>{+name{param=value}}</emphasis> # enable action and set <quote>param</quote> to <quote>value</quote>
2791 <emphasis>{-name{param=value}}</emphasis> # remove the parameter <quote>param</quote> completely
2792 <emphasis>{-name}</emphasis> # disable this action totally and remove <application>param</application> too
2803 If nothing is specified in any actions file, no <quote>actions</quote> are
2804 taken. So in this case <application>Privoxy</application> would just be a
2805 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
2806 privacy and blocking features you need (although the provided default actions
2807 files will give a good starting point).
2811 Later defined actions always over-ride earlier ones. So exceptions
2812 to any rules you make, should come in the latter part of the file. For
2813 multi-valued actions, the actions are applied in the order they are
2814 specified. Actions files are processed in the order they are defined
2815 in <filename>config</filename> (the default installation has three
2816 actions files). It also quite possible for any given URL pattern to
2817 match more than one action!
2820 <!-- start actions listing -->
2822 The list of valid <application>Privoxy</application> <quote>actions</quote> are:
2826 <!-- ********************************************************** -->
2827 <!-- Please note the below defined actions use id's that are -->
2828 <!-- probably linked from other places, so please don't change. -->
2830 <!-- ********************************************************** -->
2833 <!-- ~~~~~ New section ~~~~~ -->
2835 <sect4 id="add-header">
2836 <title><emphasis>+add-header{Name: value}</emphasis></title>
2841 <!-- boolean, parameterized, Multi-value -->
2843 <para>Multi-value.</para>
2848 <term>Typical uses:</term>
2851 Send a user defined HTTP header to the web server.
2857 <term>Possible values:</term>
2860 Any value is possible. Validity of the defined HTTP headers is not checked.
2866 <term>Example usage:</term>
2869 <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
2870 <emphasis>.example.com</emphasis>
2879 This action may be specified multiple times, in order to define multiple
2880 headers. This is rarely needed for the typical user. If you don't know what
2881 <quote>HTTP headers</quote> are, you definitely don't need to worry about this
2890 <!-- ~~~~~ New section ~~~~~ -->
2892 <title><emphasis>+block</emphasis></title>
2897 <!-- boolean, parameterized, Multi-value -->
2899 <para>Boolean.</para>
2904 <term>Typical uses:</term>
2907 Used to block a URL from reaching your browser. The URL may be
2908 anything, but is typically used to block ads or other obnoxious
2915 <term>Possible values:</term>
2922 <term>Example usage:</term>
2925 <emphasis>{+block}</emphasis>
2926 <emphasis>.banners.example.com</emphasis>
2927 <emphasis>.ads.r.us</emphasis>
2936 If a URL matches one of the blocked patterns, <application>Privoxy</application>
2937 will intercept the URL and display its special <quote>BLOCKED</quote> page
2938 instead. If there is sufficient space, a large red banner will appear with
2939 a friendly message about why the page was blocked, and a way to go there
2940 anyway. If there is insufficient space a smaller blocked page will appear
2941 without the red banner.
2942 <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html">Click here</ulink>
2943 to view the default blocked HTML page (<application>Privoxy</application> must be running
2944 for this to work as intended!).
2948 A very important exception is if the URL <emphasis>matches both</emphasis>
2949 <quote>+block</quote> and <ulink
2950 url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>,
2951 then it will be handled by
2952 <ulink url="configuration.html#SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></ulink>
2953 (see below). It is important to understand this process, in order
2954 to understand how <application>Privoxy</application> is able to deal with
2955 ads and other objectionable content.
2958 The <ulink url="configuration.html#FILTER"><quote>+filter</quote></ulink>
2959 action can also perform some of the
2960 same functionality as <quote>+block</quote>, but by virtue of very
2961 different programming techniques, and is most often used for different
2971 <!-- ~~~~~ New section ~~~~~ -->
2972 <sect4 id="deanimate-gifs">
2973 <title><emphasis>+deanimate-gifs</emphasis></title>
2978 <!-- boolean, parameterized, Multi-value -->
2980 <para>Parameterized.</para>
2985 <term>Typical uses:</term>
2988 To stop those annoying, distracting animated GIF images.
2994 <term>Possible values:</term>
2997 <quote>last</quote> or <quote>first</quote>
3003 <term>Example usage:</term>
3006 <emphasis>{+deanimate-gifs{last}}</emphasis>
3007 <emphasis>.example.com</emphasis>
3016 De-animate all animated GIF images, i.e. reduce them to their last frame.
3017 This will also shrink the images considerably (in bytes, not pixels!). If
3018 the option <quote>first</quote> is given, the first frame of the animation
3019 is used as the replacement. If <quote>last</quote> is given, the last
3020 frame of the animation is used instead, which probably makes more sense for
3021 most banner animations, but also has the risk of not showing the entire
3022 last frame (if it is only a delta to an earlier frame).
3030 <!-- ~~~~~ New section ~~~~~ -->
3031 <sect4 id="downgrade-http-version">
3032 <title><emphasis>+downgrade-http-version</emphasis></title>
3037 <!-- boolean, parameterized, Multi-value -->
3039 <para>Boolean.</para>
3044 <term>Typical uses:</term>
3047 <quote>+downgrade-http-version</quote> will downgrade HTTP/1.1 client requests to
3048 HTTP/1.0 and downgrade the responses as well.
3054 <term>Possible values:</term>
3063 <term>Example usage:</term>
3066 <emphasis>{+downgrade-http-version}</emphasis>
3067 <emphasis>.example.com</emphasis>
3076 Use this action for servers that use HTTP/1.1 protocol features that
3077 <application>Privoxy</application> doesn't handle well yet. HTTP/1.1 is
3078 only partially implemented. Default is not to downgrade requests. This is
3079 an infrequently needed action, and is used to help with rare problem sites only.
3087 <!-- ~~~~~ New section ~~~~~ -->
3088 <sect4 id="fast-redirects">
3089 <title><emphasis>+fast-redirects</emphasis></title>
3094 <!-- boolean, parameterized, Multi-value -->
3096 <para>Boolean.</para>
3101 <term>Typical uses:</term>
3104 The <quote>+fast-redirects</quote> action enables interception of
3105 <quote>redirect</quote> requests from one server to another, which
3106 are used to track users.<application>Privoxy</application> can cut off
3107 all but the last valid URL in a redirect request and send a local redirect
3108 back to your browser without contacting the intermediate site(s).
3114 <term>Possible values:</term>
3123 <term>Example usage:</term>
3126 <emphasis>{+fast-redirects}</emphasis>
3127 <emphasis>.example.com</emphasis>
3136 Many sites, like yahoo.com, don't just link to other sites. Instead, they
3137 will link to some script on their own server, giving the destination as a
3138 parameter, which will then redirect you to the final target. URLs
3139 resulting from this scheme typically look like:
3140 <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
3143 Sometimes, there are even multiple consecutive redirects encoded in the
3144 URL. These redirections via scripts make your web browsing more traceable,
3145 since the server from which you follow such a link can see where you go
3146 to. Apart from that, valuable bandwidth and time is wasted, while your
3147 browser ask the server for one redirect after the other. Plus, it feeds
3151 This is a normally <quote>on</quote> feature, and often requires exceptions
3152 for sites that are sensitive to defeating this mechanism.
3161 <!-- ~~~~~ New section ~~~~~ -->
3163 <title><emphasis>+filter</emphasis></title>
3168 <!-- boolean, parameterized, Multi-value -->
3170 <para>Parameterized.</para>
3175 <term>Typical uses:</term>
3178 Apply page filtering as defined by named sections of the
3179 <filename>default.filter</filename> file to the specified site(s).
3180 <quote>Filtering</quote> can be any modification of the raw
3181 page content, including re-writing or deletion of content.
3187 <term>Possible values:</term>
3190 <quote>+filter</quote> must include the name of one of the section identifiers
3191 from <filename>default.filter</filename> (or whatever
3192 <emphasis>filterfile</emphasis> is specified in <filename>config</filename>).
3198 <term>Example usage (from the current <filename>default.filter</filename>):</term>
3202 <emphasis>+filter{html-annoyances}</emphasis>: Get rid of particularly annoying HTML abuse.
3207 <emphasis>+filter{js-annoyances}</emphasis>: Get rid of particularly annoying JavaScript abuse
3212 <emphasis>+filter{content-cookies}</emphasis>: Kill cookies that come in the HTML or JS content
3217 <emphasis>+filter{popups}</emphasis>: Kill all popups in JS and HTML
3222 <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable
3227 <emphasis>+filter{webbugs}</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
3232 <emphasis>+filter{refresh-tags}</emphasis>: Kill automatic refresh tags (for dial-on-demand setups)
3237 <emphasis>+filter{fun}</emphasis>: Text replacements for subversive browsing fun!
3242 <emphasis>+filter{nimda}</emphasis>: Remove Nimda (virus) code.
3247 <emphasis>+filter{banners-by-size}</emphasis>: Kill banners by size (<emphasis>very</emphasis> efficient!)
3252 <emphasis>+filter{shockwave-flash}</emphasis>: Kill embedded Shockwave Flash objects
3257 <emphasis>+filter{crude-parental}</emphasis>: Kill all web pages that contain the words "sex" or "warez"
3267 This is potentially a very powerful feature! And requires a knowledge
3268 of regular expressions if you want to <quote>roll your own</quote>.
3269 Filtering operates on a line by line basis throughout the entire page.
3272 Filtering requires buffering the page content, which may appear to
3273 slow down page rendering since nothing is displayed until all content has
3274 passed the filters. (It does not really take longer, but seems that way
3275 since the page is not incrementally displayed.) This effect will be more
3276 noticeable on slower connections.
3279 Filtering can achieve some of the effects as the
3280 <ulink url="configuration.html#BLOCK"><quote>+block</quote></ulink>
3281 action, i.e. it can be used to block ads and banners. In the overall
3282 scheme of things, filtering is one of the first things <quote>Privoxy</quote>
3283 does with a web page. So other most other actions are applied to the
3284 already <quote>filtered</quote> page.
3293 <!-- ~~~~~ New section ~~~~~ -->
3294 <sect4 id="hide-forwarded-for-headers">
3295 <title><emphasis>+hide-forwarded-for-headers</emphasis></title>
3300 <!-- Boolean, Parameterized, Multi-value -->
3302 <para>Boolean.</para>
3307 <term>Typical uses:</term>
3310 Block any existing X-Forwarded-for HTTP header, and do not add a new one.
3316 <term>Possible values:</term>
3325 <term>Example usage:</term>
3328 <emphasis>{+hide-forwarded-for-headers}</emphasis>
3329 <emphasis>.example.com</emphasis>
3338 It is fairly safe to leave this on. It does not seem to break many sites.
3347 <!-- ~~~~~ New section ~~~~~ -->
3348 <sect4 id="hide-from-header">
3349 <title><emphasis>+hide-from-header</emphasis></title>
3354 <!-- Boolean, Parameterized, Multi-value -->
3356 <para>Parameterized.</para>
3361 <term>Typical uses:</term>
3364 To block the browser from sending your email address in a <quote>From:</quote>
3371 <term>Possible values:</term>
3374 Keyword: <quote>block</quote>, or any user defined value.
3380 <term>Example usage:</term>
3383 <emphasis>{+hide-from-header{block}}</emphasis>
3384 <emphasis>.example.com</emphasis>
3393 The keyword <quote>block</quote> will completely remove the header
3394 (not to be confused with the <ulink
3395 url="configuration.html#BLOCK"><quote>+block</quote></ulink> action).
3396 Alternately, you can specify any value you prefer to send to the web
3406 <!-- ~~~~~ New section ~~~~~ -->
3407 <sect4 id="hide-referer">
3408 <title><emphasis><anchor id="hide-referrer">+hide-referer</emphasis></title>
3414 <!-- Boolean, Parameterized, Multi-value -->
3416 <para>Parameterized.</para>
3421 <term>Typical uses:</term>
3424 Don't send the <quote>Referer:</quote> (sic) HTTP header to the web site.
3425 Or, alternately send a forged header instead.
3431 <term>Possible values:</term>
3434 Prevent the header from being sent with the keyword, <quote>block</quote>.
3435 Or, <quote>forge</quote> a URL to one from the same server as the request.
3436 Or, set to user defined value of your choice.
3442 <term>Example usage:</term>
3445 <emphasis>{+hide-referer{forge}}</emphasis>
3446 <emphasis>.example.com</emphasis>
3455 <quote>forge</quote> is the preferred option here, since some servers will
3456 not send images back otherwise.
3459 <quote>+hide-referrer</quote> is an alternate spelling of
3460 <quote>+hide-referer</quote>. It has the exact same parameters, and can be freely
3461 mixed with, <quote>+hide-referer</quote>. (<quote>referrer</quote> is the
3462 correct English spelling, however the HTTP specification has a bug - it
3463 requires it to be spelled as <quote>referer</quote>.)
3472 <!-- ~~~~~ New section ~~~~~ -->
3473 <sect4 id="hide-user-agent">
3474 <title><emphasis>+hide-user-agent</emphasis></title>
3479 <!-- Boolean, Parameterized, Multi-value -->
3481 <para>Parameterized.</para>
3486 <term>Typical uses:</term>
3489 To change the <quote>User-Agent:</quote> header so web servers can't tell
3490 your browser type. Who's business is it anyway?
3496 <term>Possible values:</term>
3499 Any user defined string.
3505 <term>Example usage:</term>
3508 <emphasis>{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</emphasis>
3509 <emphasis>.msn.com</emphasis>
3518 Warning! This breaks many web sites that depend on this in order
3519 to determine how the target browser will respond to various
3520 requests. Use with caution.
3528 <!-- ~~~~~ New section ~~~~~ -->
3529 <sect4 id="handle-as-image">
3530 <title><emphasis>+handle-as-image</emphasis></title>
3535 <!-- Boolean, Parameterized, Multi-value -->
3537 <para>Boolean.</para>
3542 <term>Typical uses:</term>
3545 To define what <application>Privoxy</application> should treat
3546 automatically as an image, and is an important ingredient of how
3553 <term>Possible values:</term>
3562 <term>Example usage:</term>
3565 <emphasis>{+handle-as-image}</emphasis>
3566 <emphasis>/.*\.(gif|jpg|jpeg|png|bmp|ico)</emphasis>
3575 This only has meaning if the URL (or pattern) also is
3576 <quote>+block</quote>ed, in which case a user definable image can
3577 be sent rather than a HTML page. This is integral to the whole concept of
3578 ad blocking: the URL must match <emphasis>both</emphasis> a <ulink
3579 url="configuration.html#BLOCK"><quote>+block</quote></ulink> rule,
3580 <emphasis>and</emphasis> <quote>+handle-as-image</quote>.
3582 url="configuration.html#SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></ulink>
3583 below for control over what will actually be displayed by the browser.)
3586 There is little reason to change the default definition for this action.
3595 <!-- ~~~~~ New section ~~~~~ -->
3596 <sect4 id="set-image-blocker">
3597 <title><emphasis>+set-image-blocker</emphasis></title>
3602 <!-- Boolean, Parameterized, Multi-value -->
3604 <para>Parameterized.</para>
3609 <term>Typical uses:</term>
3612 Decide what to do with URLs that end up tagged with <emphasis>both</emphasis>
3613 <ulink url="configuration.html#BLOCK"><quote>+block</quote></ulink>
3615 url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>,
3616 e.g an advertisement.
3622 <term>Possible values:</term>
3625 There are four available options: <quote>-set-image-blocker</quote> will send a HTML
3626 <quote>blocked</quote> page, usually resulting in a <quote>broken
3628 <quote>+set-image-blocker{<emphasis>blank</emphasis>}</quote> will send a
3629 1x1 transparent GIF image.
3630 <quote>+set-image-blocker{<emphasis>pattern</emphasis>}</quote> will send a
3631 checkerboard type pattern (the default). And finally,
3632 <quote>+set-image-blocker{<emphasis>http://xyz.com</emphasis>}</quote> will
3633 send a HTTP temporary redirect to the specified image. This has the
3634 advantage of the icon being being cached by the browser, which will speed
3641 <term>Example usage:</term>
3644 <emphasis>{+set-image-blocker{blank}}</emphasis>
3645 <emphasis>.example.com</emphasis>
3654 If you want <emphasis>invisible</emphasis> ads, they need to meet
3655 criteria as matching both <emphasis>images</emphasis> and <emphasis>blocked</emphasis>
3656 actions. And then, <quote>image-blocker</quote> should be set to
3657 <quote>blank</quote> for invisibility. Note you cannot treat HTML pages as
3658 images in most cases. For instance, frames require an HTML page to
3659 display. So a frame that is an ad, typically cannot be treated as an image.
3660 Forcing an <quote>image</quote> in this situation just will not work
3669 <!-- ~~~~~ New section ~~~~~ -->
3670 <sect4 id="limit-connect">
3671 <title><emphasis>+limit-connect</emphasis></title>
3676 <!-- Boolean, Parameterized, Multi-value -->
3678 <para>Parameterized.</para>
3683 <term>Typical uses:</term>
3686 By default, <application>Privoxy</application> only allows HTTP CONNECT
3687 requests to port 443 (the standard, secure HTTPS port). Use
3688 <quote>+limit-connect</quote> to disable this altogether, or to allow
3695 <term>Possible values:</term>
3698 Any valid port number, or port number range.
3704 <term>Example usages:</term>
3706 <!-- I had trouble getting the spacing to look right in my browser -->
3707 <!-- I probably have the wrong font setup, bollocks. -->
3708 <!-- Apparently the emphasis tag uses a proportional font no matter what -->
3710 <emphasis>+limit-connect{443}</emphasis> # This is the default and need not be specified.
3711 <emphasis>+limit-connect{80,443}</emphasis> # Ports 80 and 443 are OK.
3712 <emphasis>+limit-connect{-3, 7, 20-100, 500-}</emphasis> # Port less than 3, 7, 20 to 100 and above 500 are OK.
3721 The CONNECT methods exists in HTTP to allow access to secure websites
3722 (https:// URLs) through proxies. It works very simply: the proxy connects
3723 to the server on the specified port, and then short-circuits its
3724 connections to the client <emphasis>and</emphasis> to the remote proxy.
3725 This can be a big security hole, since CONNECT-enabled proxies can be
3726 abused as TCP relays very easily.
3729 If you want to allow CONNECT for more ports than this, or want to forbid
3730 CONNECT altogether, you can specify a comma separated list of ports and
3731 port ranges (the latter using dashes, with the minimum defaulting to 0 and
3735 If you don't know what any of this means, there probably is no reason to
3744 <!-- ~~~~~ New section ~~~~~ -->
3745 <sect4 id="prevent-compression">
3746 <title><emphasis>+prevent-compression</emphasis></title>
3751 <!-- Boolean, Parameterized, Multi-value -->
3753 <para>Boolean.</para>
3758 <term>Typical uses:</term>
3761 Prevent the specified websites from compressing HTTP data.
3767 <term>Possible values:</term>
3776 <term>Example usage:</term>
3779 <emphasis>{+prevent-compression}</emphasis>
3780 <emphasis>.example.com</emphasis>
3789 Some websites do this, which can be a problem for
3790 <application>Privoxy</application>, since
3791 <ulink url="configuration.html#FILTER"><quote>+filter</quote></ulink>,
3792 <ulink url="configuration.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink>
3794 url="configuration.html#GIF-DEANIMATE"><quote>+gif-deanimate</quote></ulink>
3795 will not work on compressed data. This will slow down connections to those
3796 websites, though. Default typically is to turn
3797 <quote>prevent-compression</quote> on.
3805 <!-- ~~~~~ New section ~~~~~ -->
3806 <sect4 id="session-cookies-only">
3807 <title><emphasis>+session-cookies-only</emphasis></title>
3812 <!-- Boolean, Parameterized, Multi-value -->
3814 <para>Boolean.</para>
3819 <term>Typical uses:</term>
3822 Allow cookies for the current browser session <emphasis>only</emphasis>.
3828 <term>Possible values:</term>
3837 <term>Example usage (disabling):</term>
3840 <emphasis>{-session-cookies-only}</emphasis>
3841 <emphasis>.example.com</emphasis>
3850 If websites set cookies, <quote>+session-cookies-only</quote> will make sure
3851 they are erased when you exit and restart your web browser. This makes
3852 profiling cookies useless, but won't break sites which require cookies so
3853 that you can log in for transactions. This is generally turned on for all
3854 sites, and is the recommended setting.
3857 <quote>+prevent-*-cookies</quote> actions should be turned off as well (see
3858 below), for <quote>+session-cookies-only</quote> to work. Or, else no cookies
3859 will get through at all. For, <quote>persistent</quote> cookies that survive
3860 across browser sessions, see below as well.
3869 <!-- ~~~~~ New section ~~~~~ -->
3870 <sect4 id="prevent-reading-cookies">
3871 <title><emphasis>+prevent-reading-cookies</emphasis></title>
3876 <!-- Boolean, Parameterized, Multi-value -->
3878 <para>Boolean.</para>
3883 <term>Typical uses:</term>
3886 Explicitly prevent the web server from reading any cookies on your
3893 <term>Possible values:</term>
3902 <term>Example usage:</term>
3905 <emphasis>{+prevent-reading-cookies}</emphasis>
3906 <emphasis>.example.com</emphasis>
3915 Often used in conjunction with <quote>+prevent-setting-cookies</quote> to
3916 disable cookies completely. Note that
3917 <ulink url="configuration.html#SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></ulink>
3918 requires these to both be disabled (or else it never gets any cookies to cache).
3921 For <quote>persistent</quote> cookies to work (i.e. they survive across browser
3922 sessions and reboots), all three cookie settings should be <quote>off</quote>
3923 for the specified sites.
3932 <!-- ~~~~~ New section ~~~~~ -->
3933 <sect4 id="prevent-setting-cookies">
3934 <title><emphasis>+prevent-setting-cookies</emphasis></title>
3939 <!-- Boolean, Parameterized, Multi-value -->
3941 <para>Boolean.</para>
3946 <term>Typical uses:</term>
3949 Explicitly block the web server from storing cookies on your
3956 <term>Possible values:</term>
3965 <term>Example usage:</term>
3968 <emphasis>{+prevent-setting-cookies}</emphasis>
3969 <emphasis>.example.com</emphasis>
3978 Often used in conjunction with <quote>+prevent-reading-cookies</quote> to
3979 disable cookies completely (see above).
3988 <!-- ~~~~~ Nvarlistentryew section ~~~~~ -->
3989 <sect4 id="kill-popup">
3990 <title><emphasis>+kill-popups<anchor id="kill-popups"></emphasis></title>
3994 <!-- Boolean, Parameterized, Multi-value -->
3996 <para>Boolean.</para>
4001 <term>Typical uses:</term>
4004 Stop those annoying JavaScript pop-up windows!
4010 <term>Possible values:</term>
4019 <term>Example usage:</term>
4022 <emphasis>{+kill-popups}</emphasis>
4023 <emphasis>.example.com</emphasis>
4032 <quote>+kill-popups</quote> uses a built in filter to disable pop-ups
4033 that use the <literal>window.open()</literal> function, etc. This is
4034 one of the first actions processed by <application>Privoxy</application>
4035 as it contacts the remote web server. This action is not always 100% reliable,
4036 and is supplemented by <quote>+filter{<emphasis>popups</emphasis>}</quote>.
4040 An alternate spelling is <quote>+kill-popup</quote>, which is
4051 <!-- ~~~~~ New section ~~~~~ -->
4052 <sect4 id="send-vanilla-wafer">
4053 <title><emphasis>+send-vanilla-wafer</emphasis></title>
4058 <!-- Boolean, Parameterized, Multi-value -->
4060 <para>Boolean.</para>
4065 <term>Typical uses:</term>
4068 Sends a cookie for every site stating that you do not accept any copyright
4069 on cookies sent to you, and asking them not to track you.
4075 <term>Possible values:</term>
4084 <term>Example usage:</term>
4087 <emphasis>{+send-vanilla-wafer}</emphasis>
4088 <emphasis>.example.com</emphasis>
4097 This action only applies if you are using a <filename>jarfile</filename>
4098 for saving cookies. Of course, this is a (relatively) unique header and
4099 could conceivably be used to track you.
4108 <!-- ~~~~~ New section ~~~~~ -->
4109 <sect4 id="send-wafer">
4110 <title><emphasis>+send-wafer</emphasis></title>
4115 <!-- Boolean, Parameterized, Multi-value -->
4117 <para>Multi-value.</para>
4122 <term>Typical uses:</term>
4125 This allows you to send an arbitrary, user definable cookie.
4131 <term>Possible values:</term>
4134 User specified cookie name and corresponding value.
4140 <term>Example usage:</term>
4143 <emphasis>{+send-wafer{name=value}}</emphasis>
4144 <emphasis>.example.com</emphasis>
4153 This can be specified multiple times in order to add as many cookies as you
4163 <!-- ~~~~~ New section ~~~~~ -->
4164 <sect4 id="act-examples" renderas="sect3">
4165 <title>Actions Examples</title>
4167 Note that the meaning of any of the above examples is reversed by preceding
4168 the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also,
4169 that some actions are turned on in the default section of the actions file,
4170 and require little to no additional configuration. These are just <quote>on</quote>.
4171 But, other actions that are turned on the default section <emphasis>do
4172 typically require</emphasis> exceptions to be listed in the lower sections of
4173 actions file. E.g. by default no URLs are <quote>blocked</quote> (i.e. in
4174 the default definitions of <filename>default.action</filename>). We need
4175 exceptions to this in order to enable ad blocking.
4183 Turn off cookies by default, then allow a few through for specified sites
4184 (showing an excerpt from the <quote>default</quote> section of an actions
4193 # Allow cookies to and from the server, but
4194 # for this browser session ONLY
4196 # other actions normally listed here...
4197 -prevent-setting-cookies \
4198 -prevent-reading-cookies \
4199 +session-cookies-only \
4203 # Exceptions to the above, sites that benefit from persistent cookies
4204 # that are saved from one browser session to the next.
4205 { -session-cookies-only }
4218 Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
4225 # Turn them off (excerpt only)!
4227 # other actions normally listed here...
4232 # Reverse it for these two sites, which don't work right without it.
4234 www.ukc.ac.uk/cgi-bin/wac\.cgi\?
4242 Turn on page filtering according to rules in the defined sections
4243 of <filename>default.filter</filename>, and make one exception for
4251 # Run everything through the filter file, using only certain
4252 # specified sections:
4254 # other actions normally listed here...
4255 +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}\
4256 +filter{webbugs} +filter{nimda} +filter{banners-by-size}
4260 # Then disable filtering of code from all sourceforge domains!
4269 Now some URLs that we want <quote>blocked</quote> (normally generates
4270 the <quote>blocked</quote> banner). Typically, the <quote>block</quote>
4271 action is off by default in the upper section of an actions file, then enabled
4272 against certain URLs and patterns in the lower part of the file. Many of these use <link
4273 linkend="regex">regular expressions</link> that will expand to match multiple
4286 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
4287 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
4289 /.*/(ng)?adclient\.cgi
4290 /.*/(plain|live|rotate)[-_.]?ads?/
4299 Note that many of these actions have the potential to cause a page to
4300 misbehave, possibly even not to display at all. There are many ways
4301 a site designer may choose to design his site, and what HTTP header
4302 content, and other criteria, he may depend on. There is no way to have hard
4303 and fast rules for all sites. See the <link
4304 linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
4311 <!-- ~ End section ~ -->
4314 <!-- ~~~~~ New section ~~~~~ -->
4315 <sect3 id="aliases">
4316 <title>Aliases</title>
4318 Custom <quote>actions</quote>, known to <application>Privoxy</application>
4319 as <quote>aliases</quote>, can be defined by combining other <quote>actions</quote>.
4320 These can in turn be invoked just like the built-in <quote>actions</quote>.
4321 Currently, an alias can contain any character except space, tab, <quote>=</quote>,
4322 <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
4323 <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
4324 <quote>-</quote>. Alias names are not case sensitive, and
4325 <emphasis>must be defined before other actions</emphasis> in the
4326 actions file! And there can only be one set of <quote>aliases</quote>
4327 defined per file. Each actions file may have its own aliases, but they are
4328 only visible within that file.
4332 Now let's define a few aliases:
4339 # Useful custom aliases we can use later. These must come first!
4341 +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies
4342 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies
4343 fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups
4344 shop = -prevent-cookies -filter -fast-redirects
4345 +imageblock = +block +handle-as-image
4347 # Aliases defined from other aliases, for people who don't like to type
4349 c0 = +prevent-cookies
4350 c1 = -prevent-cookies
4351 #... etc. Customize to your heart's content.
4358 Some examples using our <quote>shop</quote> and <quote>fragile</quote>
4359 aliases from above. These would appear in the lower sections of an
4360 actions file as exceptions to the default actions (as defined in the
4368 # These sites are very complex and require
4369 # minimal interference.
4371 .office.microsoft.com
4372 .windowsupdate.microsoft.com
4375 # Shopping sites - but we still want to block ads.
4378 .worldpay.com # for quietpc.com
4381 # These shops require pop-ups also
4391 The <quote>shop</quote> and <quote>fragile</quote> aliases are often used for
4392 <quote>problem</quote> sites that require most actions to be disabled
4393 in order to function properly.
4400 <!-- ~ End section ~ -->
4403 <!-- ~~~~~ New section ~~~~~ -->
4404 <sect2 id="filter-file">
4405 <title>The Filter File</title>
4407 Any web page can be dynamically modified with the filter file. This
4408 modification can be removal, or re-writing, of any web page content,
4409 including tags and non-visible content. The default filter file is
4410 <filename>default.filter</filename>, located in the config directory.
4414 This is potentially a very powerful feature, and requires knowledge of both
4415 <quote>regular expression</quote> and HTML in order create custom
4416 filters. But, there are a number of useful filters included with
4417 <application>Privoxy</application> for many common situations.
4421 The included example file is divided into sections. Each section begins
4422 with the <literal>FILTER</literal> keyword, followed by the identifier
4423 for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
4424 a similar type of filtering, such as <quote>html-annoyances</quote>.
4428 This file uses regular expressions to alter or remove any string in the
4429 target page. The expressions can only operate on one line at a time. Some
4430 examples from the included default <filename>default.filter</filename>:
4434 Stop web pages from displaying annoying messages in the status bar by
4435 deleting such references:
4442 FILTER: html-annoyances
4444 # New browser windows should be resizeable and have a location and status
4447 s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
4448 s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
4449 s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
4450 s/menubar="?(no|0)"?/menubar=1/ig
4452 # The <BLINK> tag was a crime!
4454 s*<blink>|</blink>**ig
4458 #s/framespacing="?(no|0)"?//ig
4459 #s/margin(height|width)=[0-9]*//gi
4466 Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
4467 <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
4476 s/microsoft(?!.com)/MicroSuck/ig
4480 s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
4487 Kill those pesky little web-bugs:
4494 # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
4497 s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
4505 <!-- ~ End section ~ -->
4509 <!-- ~~~~~ New section ~~~~~ -->
4512 <title>Templates</title>
4514 When <application>Privoxy</application> displays one of its internal
4515 pages, such as a 404 Not Found error page, it uses the appropriate template.
4516 On Linux, BSD, and Unix, these are located in
4517 <filename>/etc/privoxy/templates</filename> by default. These may be
4518 customized, if desired. <filename>cgi-style.css</filename> is
4519 used to control the HTML attributes (fonts, etc).
4522 The default <quote>Blocked</quote> banner page with the bright red top
4523 banner, is called just <quote><filename>blocked</filename></quote>. This
4524 may be customized or replaced with something else if desired.
4531 <!-- ~ End section ~ -->
4535 <!-- ~~~~~ New section ~~~~~ -->
4537 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
4540 <!-- Include contacting.sgml boilerplate: -->
4542 <!-- end boilerplate -->
4545 <!-- ~~~~~ New section ~~~~~ -->
4546 <sect2 id="submitactions">
4547 <title>Submitting Ads and <quote>Action</quote> Problems</title>
4549 Ads and banners that are not stopped by <application>Privoxy</application>
4550 can be submitted to the developers by accessing a special page and filling
4551 out the brief, required form. Conversely, you can also report pages, images,
4552 etc. that <application>Privoxy</application> is blocking, but should not.
4553 The form itself does require Internet access.
4556 To do this, point your browser to <application>Privoxy</application>
4557 at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4558 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
4559 <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>,
4560 near the bottom of the page. Paste in the URL that is the cause of the
4561 unwanted behavior, and follow the prompts. The developers will
4562 try to incorporate a fix for the problem you reported into future versions.
4566 New, improved <filename>default.action</filename> files will occasionally be made
4567 available based on your feedback. These will be announced on the <ulink
4568 url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink>
4576 <!-- ~~~~~ New section ~~~~~ -->
4577 <sect1 id="copyright"><title>Copyright and History</title>
4579 <sect2><title>Copyright</title>
4580 <!-- Include copyright.sgml: -->
4582 <!-- end copyright -->
4585 <!-- ~ End section ~ -->
4588 <!-- ~~~~~ New section ~~~~~ -->
4590 <sect2 id="history"><title>History</title>
4591 <!-- Include history.sgml: -->
4593 <!-- end history -->
4597 <!-- ~~~~~ New section ~~~~~ -->
4598 <sect1 id="seealso"><title>See Also</title>
4599 <!-- Include seealso.sgml: -->
4601 <!-- end seealso -->
4606 <!-- ~~~~~ New section ~~~~~ -->
4607 <sect1 id="appendix"><title>Appendix</title>
4610 <!-- ~~~~~ New section ~~~~~ -->
4612 <title>Regular Expressions</title>
4614 <application>Privoxy</application> can use <quote>regular expressions</quote>
4615 in various config files. Assuming support for <quote>pcre</quote> (Perl
4616 Compatible Regular Expressions) is compiled in, which is the default. Such
4617 configuration directives do not require regular expressions, but they can be
4618 used to increase flexibility by matching a pattern with wild-cards against
4623 If you are reading this, you probably don't understand what <quote>regular
4624 expressions</quote> are, or what they can do. So this will be a very brief
4625 introduction only. A full explanation would require a book ;-)
4629 <quote>Regular expressions</quote> is a way of matching one character
4630 expression against another to see if it matches or not. One of the
4631 <quote>expressions</quote> is a literal string of readable characters
4632 (letter, numbers, etc), and the other is a complex string of literal
4633 characters combined with wild-cards, and other special characters, called
4634 meta-characters. The <quote>meta-characters</quote> have special meanings and
4635 are used to build the complex pattern to be matched against. Perl Compatible
4636 Regular Expressions is an enhanced form of the regular expression language
4637 with backward compatibility.
4641 To make a simple analogy, we do something similar when we use wild-card
4642 characters when listing files with the <command>dir</command> command in DOS.
4643 <literal>*.*</literal> matches all filenames. The <quote>special</quote>
4644 character here is the asterisk which matches any and all characters. We can be
4645 more specific and use <literal>?</literal> to match just individual
4646 characters. So <quote>dir file?.text</quote> would match
4647 <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
4648 matching, using a similar technique to <quote>regular expressions</quote>!
4652 Regular expressions do essentially the same thing, but are much, much more
4653 powerful. There are many more <quote>special characters</quote> and ways of
4654 building complex patterns however. Let's look at a few of the common ones,
4655 and then some examples:
4660 <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
4661 <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
4663 </simplelist></para>
4667 <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
4670 </simplelist></para>
4674 <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
4677 </simplelist></para>
4681 <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
4684 </simplelist></para>
4688 <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
4689 the following character should be taken literally. This is used where one of the
4690 special characters (e.g. <quote>.</quote>) needs to be taken literally and
4691 not as a special meta-character. Example: <quote>example\.com</quote>, makes
4692 sure the period is recognized only as a period (and not expanded to its
4693 meta-character meaning of any single character).
4695 </simplelist></para>
4699 <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
4700 any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
4701 matches any numeric digit (zero through nine). As an example, we can combine
4702 this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
4704 </simplelist></para>
4708 <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
4709 or multiple sub-expressions.
4711 </simplelist></para>
4715 <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
4716 <quote>or</quote> conditional statement. A match is successful if the
4717 sub-expression on either side of <quote>|</quote> matches. As an example:
4718 <quote>/(this|that) example/</quote> uses grouping and the bar character
4719 and would match either <quote>this example</quote> or <quote>that
4720 example</quote>, and nothing else.
4722 </simplelist></para>
4726 <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
4727 <quote>string1</quote> is replaced by <quote>string2</quote> in this
4728 example. There must of course be a match on <quote>string1</quote> first.
4730 </simplelist></para>
4733 These are just some of the ones you are likely to use when matching URLs with
4734 <application>Privoxy</application>, and is a long way from a definitive
4735 list. This is enough to get us started with a few simple examples which may
4736 be more illuminating:
4740 <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
4741 that uses the common combination of <quote>.</quote> and <quote>*</quote> to
4742 denote any character, zero or more times. In other words, any string at all.
4743 So we start with a literal forward slash, then our regular expression pattern
4744 (<quote>.*</quote>) another literal forward slash, the string
4745 <quote>banners</quote>, another forward slash, and lastly another
4746 <quote>.*</quote>. We are building
4747 a directory path here. This will match any file with the path that has a
4748 directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
4749 any characters, and this could conceivably be more forward slashes, so it
4750 might expand into a much longer looking path. For example, this could match:
4751 <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
4752 <quote>/banners/annoying.html</quote>, or almost an infinite number of other
4753 possible combinations, just so it has <quote>banners</quote> in the path
4758 A now something a little more complex:
4762 <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
4763 We have several literal forward slashes again (<quote>/</quote>), so we are
4764 building another expression that is a file path statement. We have another
4765 <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
4766 it matches our expression. The only true literal that <emphasis>must
4767 match</emphasis> our pattern is <application>adv</application>, together with
4768 the forward slashes. What comes after the <quote>adv</quote> string is the
4773 Remember the <quote>?</quote> means the preceding expression (either a
4774 literal character or anything grouped with <quote>(...)</quote> in this case)
4775 can exist or not, since this means either zero or one match. So
4776 <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
4777 individual sub-expressions: <quote>(er)</quote>,
4778 <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
4779 means <quote>or</quote>. We have two of those. For instance,
4780 <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
4781 <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
4782 attempt at matching as many variations of <quote>advertisement</quote>, and
4783 similar, as possible. So this would expand to match just <quote>adv</quote>,
4784 or <quote>advert</quote>, or <quote>adverts</quote>, or
4785 <quote>advertising</quote>, or <quote>advertisement</quote>, or
4786 <quote>advertisements</quote>. You get the idea. But it would not match
4787 <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
4788 changing our regular expression to:
4789 <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
4794 <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
4795 another path statement with forward slashes. Anything in the square brackets
4796 <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
4797 shorthand expression to mean any digit one through nine. It is the same as
4798 saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
4799 means one or more of the preceding expression must be included. The preceding
4800 expression here is what is in the square brackets -- in this case, any digit
4801 one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
4802 This includes a <quote>|</quote>, so this needs to match the expression on
4803 either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
4804 side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
4805 since the <quote>?</quote> means the letter <quote>e</quote> is optional and
4806 can be matched once or not at all. So we are building an expression here to
4807 match image GIF or JPEG type image file. It must include the literal
4808 string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
4809 (which is now a literal, and not a special character, since it is escaped
4810 with <quote>\</quote>), and lastly either <quote>gif</quote>, or
4811 <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
4812 include: <quote>//advert1.jpg</quote>,
4813 <quote>/nasty/ads/advert1234.gif</quote>,
4814 <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
4815 <quote>advert1.gif</quote> (no leading slash), or
4816 <quote>/adverts232.jpg</quote> (the expression does not include an
4817 <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
4818 in the expression anywhere).
4822 <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
4823 a substitution. <quote>MicroSuck</quote> will replace any occurrence of
4824 <quote>microsoft</quote>. The <quote>i</quote> at the end of the expression
4825 means ignore case. The <quote>(?!.com)</quote> means
4826 the match should fail if <quote>microsoft</quote> is followed by
4827 <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
4828 modifier. In case this is a hyperlink, we don't want to break it ;-).
4832 We are barely scratching the surface of regular expressions here so that you
4833 can understand the default <application>Privoxy</application>
4834 configuration files, and maybe use this knowledge to customize your own
4835 installation. There is much, much more that can be done with regular
4836 expressions. Now that you know enough to get started, you can learn more on
4841 More reading on Perl Compatible Regular expressions:
4842 <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
4847 <!-- ~ End section ~ -->
4850 <!-- ~~~~~ New section ~~~~~ -->
4852 <title><application>Privoxy</application>'s Internal Pages</title>
4855 Since <application>Privoxy</application> proxies each requested
4856 web page, it is easy for <application>Privoxy</application> to
4857 trap certain special URLs. In this way, we can talk directly to
4858 <application>Privoxy</application>, and see how it is
4859 configured, see how our rules are being applied, change these
4860 rules and other configuration options, and even turn
4861 <application>Privoxy's</application> filtering off, all with
4867 The URLs listed below are the special ones that allow direct access
4868 to <application>Privoxy</application>. Of course,
4869 <application>Privoxy</application> must be running to access these. If
4870 not, you will get a friendly error message. Internet access is not
4883 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4887 Alternately, this may be reached at <ulink
4888 url="http://p.p/">http://p.p/</ulink>, but this
4889 variation may not work as reliably as the above in some configurations.
4895 Show information about the current configuration, including viewing and
4896 editing of actions files:
4900 <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
4907 Show the source code version numbers:
4911 <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
4918 Show the browser's request headers:
4922 <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
4929 Show which actions apply to a URL and why:
4933 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
4940 Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
4941 to run, but only as a pass-through proxy, with no actions taking place:
4945 <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
4949 Short cuts. Turn off, then on:
4953 <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
4958 <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
4967 These may be bookmarked for quick reference. See next.
4971 <sect3 id="bookmarklets">
4972 <title>Bookmarklets</title>
4974 Below are some <quote>bookmarklets</quote> to allow you to easily access a
4975 <quote>mini</quote> version of some of <application>Privoxy's</application>
4976 special pages. They are designed for MS Internet Explorer, but should work
4977 equally well in Netscape, Mozilla, and other browsers which support
4978 JavaScript. They are designed to run directly from your bookmarks - not by
4979 clicking the links below (although that should work for testing).
4982 To save them, right-click the link and choose <quote>Add to Favorites</quote>
4983 (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
4984 the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
4985 Bookmarklet directly from your favorites/bookmarks. For even faster access,
4986 you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
4987 Toolbar</quote> (Netscape), and run them with a single click.
4995 <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Enable Privoxy</ulink>
5001 <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Disable Privoxy</ulink>
5007 <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Toggle Privoxy</ulink> (Toggles between enabled and disabled)
5013 <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">View Privoxy Status</ulink>
5019 <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>
5029 Credit: The site which gave me the general idea for these bookmarklets is
5030 <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
5031 have more information about bookmarklets.
5040 <!-- ~~~~~ New section ~~~~~ -->
5042 <title>Chain of Events</title>
5044 Let's take a quick look at the basic sequence of events when a web page is
5045 requested by your browser and <application>Privoxy</application> is on duty:
5052 First, your web browser requests a web page. The browser knows to send
5053 the request to <application>Privoxy</application>, which will in turn,
5054 relay the request to the remote web server after passing the following
5060 <application>Privoxy</application> traps any request for its own internal CGI
5061 pages (e.g http://p.p/) and sends the CGI page back to the browser.
5066 Next, <application>Privoxy</application> checks to see if the URL
5068 url="configuration.html#BLOCK"><quote>+block</quote></ulink> patterns. If
5069 so, the URL is then blocked, and the remote web server will not be contacted.
5070 <ulink url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>
5071 is then checked and if it does not match, an
5072 HTML <quote>BLOCKED</quote> page is sent back. Otherwise, if it does match,
5073 an image is returned. The type of image depends on the setting of <ulink
5074 url="configuration.html#SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></ulink>
5075 (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
5080 Untrusted URLs are blocked. If URLs are being added to the
5081 <filename>trust</filename> file, then that is done.
5086 If the URL pattern matches the <ulink
5087 url="configuration.html#FAST-REDIRECTS"><quote>+fast-redirects</quote></ulink> action,
5088 it is then processed. Unwanted parts of the requested URL are stripped.
5093 Now the rest of the client browser's request headers are processed. If any
5094 of these match any of the relevant actions (e.g. <ulink
5095 url="configuration.html#HIDE-USER-AGENT"><quote>+hide-user-agent</quote></ulink>,
5096 etc.), headers are suppressed or forged as determined by these actions and
5102 Now the web server starts sending its response back (i.e. typically a web page and related
5108 First, the server headers are read and processed to determine, among other
5109 things, the MIME type (document type) and encoding. The headers are then
5110 filtered as deterimed by the
5111 <ulink url="configuration.html#PREVENT-SETTING-COOKIES"><quote>+prevent-setting-cookies</quote></ulink>,
5112 <ulink url="configuration.html#SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></ulink>,
5113 and <ulink url="configuration.html#DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></ulink>
5119 If the <ulink url="configuration.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink>
5120 action applies, and it is an HTML or JavaScript document, the popup-code in the
5121 response is filtered on-the-fly as it is received.
5126 If a <ulink url="configuration.html#FILTER"><quote>+filter</quote></ulink>
5128 url="configuration.html#DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></ulink>
5129 action applies (and the document type fits the action), the rest of the page is
5130 read into memory (up to a configurable limit). Then the filter rules (from
5131 <filename>default.filter</filename>) are processed against the buffered
5132 content. Filters are applied in the order they are specified in the
5133 <filename>default.filter</filename> file. Animated GIFs, if present, are
5134 reduced to either the first or last frame, depending on the action
5135 setting.The entire page, which is now filtered, is then sent by
5136 <application>Privoxy</application> back to your browser.
5139 If neither <ulink url="configuration.html#FILTER"><quote>+filter</quote></ulink>
5141 url="configuration.html#DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></ulink>
5142 matches, then <application>Privoxy</application> passes the raw data through
5143 to the client browser as it becomes available.
5148 As the browser receives the now (probably filtered) page content, it
5149 reads and then requests any URLs that may be embedded within the page
5150 source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
5151 frames), sounds, etc. For each of these objects, the browser issues a new
5152 request. And each such request is in turn processed as above. Note that a
5153 complex web page may have many such embedded URLs.
5163 <!-- ~~~~~ New section ~~~~~ -->
5164 <sect2 id="actionsanat">
5165 <title>Anatomy of an Action</title>
5168 The way <application>Privoxy</application> applies
5169 <ulink url="configuration.html#ACTIONS"><quote>actions</quote></ulink>
5170 and <ulink url="configuration.html#FILTER"><quote>filters</quote></ulink>
5171 to any given URL can be complex, and not always so
5172 easy to understand what is happening. And sometimes we need to be able to
5173 <emphasis>see</emphasis> just what <application>Privoxy</application> is
5174 doing. Especially, if something <application>Privoxy</application> is doing
5175 is causing us a problem inadvertently. It can be a little daunting to look at
5176 the actions and filters files themselves, since they tend to be filled with
5177 <quote>regular expressions</quote> whose consequences are not always
5182 One quick test to see if <application>Privoxy</application> is causing a problem
5183 or not, is to disable it temporarily. This should be the first troubleshooting
5184 step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
5185 and easy way to do this (be sure to flush caches afterward!).
5189 <application>Privoxy</application> also provides the
5190 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
5191 page that can show us very specifically how <application>actions</application>
5192 are being applied to any given URL. This is a big help for troubleshooting.
5196 First, enter one URL (or partial URL) at the prompt, and then
5197 <application>Privoxy</application> will tell us
5198 how the current configuration will handle it. This will not
5199 help with filtering effects (i.e. the <ulink
5200 url="configuration.html#FILTER"><quote>+filter</quote></ulink> action) from
5201 the <filename>default.filter</filename> file since this is handled very
5202 differently and not so easy to trap! It also will not tell you about any other
5203 URLs that may be embedded within the URL you are testing. For instance, images
5204 such as ads are expressed as URLs within the raw page source of HTML pages. So
5205 you will only get info for the actual URL that is pasted into the prompt area
5206 -- not any sub-URLs. If you want to know about embedded URLs like ads, you
5207 will have to dig those out of the HTML source. Use your browser's <quote>View
5208 Page Source</quote> option for this. Or right click on the ad, and grab the
5213 Let's try an example, <ulink url="http://google.com">google.com</ulink>,
5214 and look at it one section at a time:
5219 Matches for http://google.com:
5221 --- File standard ---
5222 (no matches in this file)
5224 --- File default ---
5226 { -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects
5227 -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
5228 +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
5229 +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
5230 +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
5231 -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
5232 +prevent-compression +session-cookies-only -prevent-reading-cookies
5233 -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer }
5236 { -session-cookies-only }
5243 (no matches in this file)
5249 This tells us how we have defined our
5250 <ulink url="configuration.html#ACTIONS"><quote>actions</quote></ulink>, and
5251 which ones match for our example, <quote>google.com</quote>. The first listing
5252 is any matches for the <filename>standard.action</filename> file. No hits at
5253 all here on <quote>standard</quote>. Then next is <quote>default</quote>, or
5254 our <filename>default.action</filename> file. The large, multi-line listing,
5255 is how the actions are set to match for all URLs, i.e. our default settings.
5256 If you look at your <quote>actions</quote> file, this would be the section
5257 just below the <quote>aliases</quote> section near the top. This will apply to
5258 all URLs as signified by the single forward slash at the end of the listing
5259 -- <quote>/</quote>.
5263 But we can define additional actions that would be exceptions to these general
5264 rules, and then list specific URLs (or patterns) that these exceptions would
5265 apply to. Last match wins. Just below this then are two explicit matches for
5266 <quote>.google.com</quote>. The first is negating our previous cookie setting,
5267 which was for <ulink
5268 url="configuration.html#SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></ulink>
5269 (i.e. not persistent). So we will allow persistent cookies for google. The
5270 second turns <emphasis>off</emphasis> any
5272 url="configuration.html#FAST-REDIRECTS"><quote>+fast-redirects</quote></ulink>
5273 action, allowing this to take place unmolested. Note that there is a leading
5274 dot here -- <quote>.google.com</quote>. This will match any hosts and
5275 sub-domains, in the google.com domain also, such as
5276 <quote>www.google.com</quote>. So, apparently, we have these two actions
5277 defined somewhere in the lower part of our <filename>default.action</filename>
5278 file, and <quote>google.com</quote> is referenced somewhere in these latter
5283 Then, for our <filename>user.action</filename> file, we again have no hits.
5287 And finally we pull it all together in the bottom section and summarize how
5288 <application>Privoxy</application> is applying all its <quote>actions</quote>
5289 to <quote>google.com</quote>:
5297 -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects
5298 -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
5299 +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
5300 +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
5301 +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
5302 -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
5303 +prevent-compression -session-cookies-only -prevent-reading-cookies
5304 -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer
5310 Notice the only difference here to the previous listing, is to
5311 <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>.
5315 Now another example, <quote>ad.doubleclick.net</quote>:
5321 { +block +handle-as-image }
5324 { +block +handle-as-image }
5327 { +block +handle-as-image }
5334 We'll just show the interesting part here, the explicit matches. It is
5335 matched three different times. Each as an <quote>+block +handle-as-image</quote>,
5336 which is the expanded form of one of our aliases that had been defined as:
5337 <quote>+imageblock</quote>. (<ulink
5338 url="configuration.html#ALIASES"><quote>Aliases</quote></ulink> are defined in
5339 the first section of the actions file and typically used to combine more
5344 Any one of these would have done the trick and blocked this as an unwanted
5345 image. This is unnecessarily redundant since the last case effectively
5346 would also cover the first. No point in taking chances with these guys
5347 though ;-) Note that if you want an ad or obnoxious
5348 URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
5349 is done here -- as both a <ulink
5350 url="configuration.html#BLOCK"><quote>+block</quote></ulink>
5351 <emphasis>and</emphasis> an
5353 url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>.
5354 The custom alias <quote>+imageblock</quote> just simplifies the process and make
5359 One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
5360 This one is giving us problems. We are getting a blank page. Hmmm...
5366 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
5368 { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects
5369 +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}
5370 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
5371 +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}
5372 +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}
5373 +prevent-compression +session-cookies-only -prevent-setting-cookies
5374 -prevent-reading-cookies +kill-popups -send-vanilla-wafer -send-wafer }
5377 { +block +handle-as-image }
5384 Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
5385 we did not want this at all! Now we see why we get the blank page. We could
5386 now add a new action below this that explicitly does <emphasis>not</emphasis>
5387 block (<quote>{-block}</quote>) paths with <quote>adsl</quote>. There are
5388 various ways to handle such exceptions. Example:
5401 Now the page displays ;-) Be sure to flush your browser's caches when
5402 making such changes. Or, try using <literal>Shift+Reload</literal>.
5406 But now what about a situation where we get no explicit matches like
5413 { +block +handle-as-image }
5420 That actually was very telling and pointed us quickly to where the problem
5421 was. If you don't get this kind of match, then it means one of the default
5422 rules in the first section is causing the problem. This would require some
5423 guesswork, and maybe a little trial and error to isolate the offending rule.
5424 One likely cause would be one of the <quote>{+filter}</quote> actions. Try
5425 adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
5433 .worldpay.com # for quietpc.com
5442 <quote>{shop}</quote> is an <quote>alias</quote> that expands to
5443 <quote>{ -filter -session-cookies-only }</quote>.
5444 Or you could do your own exception to negate filtering:
5458 This would probably be most appropriately put in <filename>user.action</filename>,
5459 for local site exceptions.
5463 <quote>{fragile}</quote> is an alias that disables most actions. This can be
5464 used as a last resort for problem sites. Remember to flush caches! If this
5465 still does not work, you will have to go through the remaining actions one by
5466 one to find which one(s) is causing the problem.
5475 This program is free software; you can redistribute it
5476 and/or modify it under the terms of the GNU General
5477 Public License as published by the Free Software
5478 Foundation; either version 2 of the License, or (at
5479 your option) any later version.
5481 This program is distributed in the hope that it will
5482 be useful, but WITHOUT ANY WARRANTY; without even the
5483 implied warranty of MERCHANTABILITY or FITNESS FOR A
5484 PARTICULAR PURPOSE. See the GNU General Public
5485 License for more details.
5487 The GNU General Public License should be included with
5488 this file. If not, you can view it at
5489 http://www.gnu.org/copyleft/gpl.html
5490 or write to the Free Software Foundation, Inc., 59
5491 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
5493 $Log: user-manual.sgml,v $
5494 Revision 1.92 2002/04/25 18:55:13 hal9
5495 More catchups on new actions files, and new actions names.
5496 Other assorted cleanups, and minor modifications.
5498 Revision 1.91 2002/04/24 02:39:31 hal9
5499 Add 'Chain of Events' section.
5501 Revision 1.90 2002/04/23 21:41:25 hal9
5502 Linuxconf is deprecated on RH, substitute chkconfig.
5504 Revision 1.89 2002/04/23 21:05:28 oes
5505 Added hint for startup on Red Hat
5507 Revision 1.88 2002/04/23 05:37:54 hal9
5508 Add AmigaOS install stuff.
5510 Revision 1.87 2002/04/23 02:53:15 david__schmidt
5511 Updated OSX installation section
5512 Added a few English tweaks here an there
5514 Revision 1.86 2002/04/21 01:46:32 hal9
5515 Re-write actions section.
5517 Revision 1.85 2002/04/18 21:23:23 hal9
5518 Fix ugly typo (mine).
5520 Revision 1.84 2002/04/18 21:17:13 hal9
5521 Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
5523 Revision 1.83 2002/04/18 18:21:12 oes
5524 Added RPM install detail
5526 Revision 1.82 2002/04/18 12:04:50 oes
5529 Revision 1.81 2002/04/18 11:50:24 oes
5530 Extended Install section - needs fixing by packagers
5532 Revision 1.80 2002/04/18 10:45:19 oes
5533 Moved text to buildsource.sgml, renamed some filters, details
5535 Revision 1.79 2002/04/18 03:18:06 hal9
5536 Spellcheck, and minor touchups.
5538 Revision 1.78 2002/04/17 18:04:16 oes
5541 Revision 1.77 2002/04/17 13:51:23 oes
5542 Proofreading, part one
5544 Revision 1.76 2002/04/16 04:25:51 hal9
5545 -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
5546 -Note about proxy may need requests to re-read config files.
5548 Revision 1.75 2002/04/12 02:08:48 david__schmidt
5549 Remove OS/2 building info... it is already in the developer-manual
5551 Revision 1.74 2002/04/11 00:54:38 hal9
5552 Add small section on submitting actions.
5554 Revision 1.73 2002/04/10 18:45:15 swa
5557 Revision 1.72 2002/04/10 04:06:19 hal9
5558 Added actions feedback to Bookmarklets section
5560 Revision 1.71 2002/04/08 22:59:26 hal9
5561 Version update. Spell chkconfig correctly :)
5563 Revision 1.70 2002/04/08 20:53:56 swa
5566 Revision 1.69 2002/04/06 05:07:29 hal9
5567 -Add privoxy-man-page.sgml, for man page.
5568 -Add authors.sgml for AUTHORS (and p-authors.sgml)
5569 -Reworked various aspects of various docs.
5570 -Added additional comments to sub-docs.
5572 Revision 1.68 2002/04/04 18:46:47 swa
5573 consistent look. reuse of copyright, history et. al.
5575 Revision 1.67 2002/04/04 17:27:57 swa
5576 more single file to be included at multiple points. make maintaining easier
5578 Revision 1.66 2002/04/04 06:48:37 hal9
5579 Structural changes to allow for conditional inclusion/exclusion of content
5580 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
5581 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
5582 eventually be set by Makefile.
5583 More boilerplate text for use across multiple docs.
5585 Revision 1.65 2002/04/03 19:52:07 swa
5586 enhance squid section due to user suggestion
5588 Revision 1.64 2002/04/03 03:53:43 hal9
5589 A few minor bug fixes, and touch ups. Ready for review.
5591 Revision 1.63 2002/04/01 16:24:49 hal9
5592 Define entities to include boilerplate text. See doc/source/*.
5594 Revision 1.62 2002/03/30 04:15:53 hal9
5595 - Fix privoxy.org/config links.
5596 - Paste in Bookmarklets from Toggle page.
5597 - Move Quickstart nearer top, and minor rework.
5599 Revision 1.61 2002/03/29 01:31:08 hal9
5602 Revision 1.60 2002/03/27 01:57:34 hal9
5603 Added more to Anatomy section.
5605 Revision 1.59 2002/03/27 00:54:33 hal9
5606 Touch up intro for new name.
5608 Revision 1.58 2002/03/26 22:29:55 swa
5609 we have a new homepage!
5611 Revision 1.57 2002/03/24 20:33:30 hal9
5612 A few minor catch ups with name change.
5614 Revision 1.56 2002/03/24 16:17:06 swa
5615 configure needs to be generated.
5617 Revision 1.55 2002/03/24 16:08:08 swa
5618 we are too lazy to make a block-built
5619 privoxy logo. hence removed the option.
5621 Revision 1.54 2002/03/24 15:46:20 swa
5622 name change related issue.
5624 Revision 1.53 2002/03/24 11:51:00 swa
5625 name change. changed filenames.
5627 Revision 1.52 2002/03/24 11:01:06 swa
5630 Revision 1.51 2002/03/23 15:13:11 swa
5631 renamed every reference to the old name with foobar.
5632 fixed "application foobar application" tag, fixed
5633 "the foobar" with "foobar". left junkbustser in cvs
5634 comments and remarks to history untouched.
5636 Revision 1.50 2002/03/23 05:06:21 hal9
5639 Revision 1.49 2002/03/21 17:01:05 hal9
5640 New section in Appendix.
5642 Revision 1.48 2002/03/12 06:33:01 hal9
5643 Catching up to Andreas and re_filterfile changes.
5645 Revision 1.47 2002/03/11 13:13:27 swa
5646 correct feedback channels
5648 Revision 1.46 2002/03/10 00:51:08 hal9
5649 Added section on JB internal pages in Appendix.
5651 Revision 1.45 2002/03/09 17:43:53 swa
5654 Revision 1.44 2002/03/09 17:08:48 hal9
5655 New section on Jon's actions file editor, and move some stuff around.
5657 Revision 1.43 2002/03/08 00:47:32 hal9
5658 Added imageblock{pattern}.
5660 Revision 1.42 2002/03/07 18:16:55 swa
5663 Revision 1.41 2002/03/07 16:46:43 hal9
5664 Fix a few markup problems for jade.
5666 Revision 1.40 2002/03/07 16:28:39 swa
5667 provide correct feedback channels
5669 Revision 1.39 2002/03/06 16:19:28 hal9
5670 Note on perceived filtering slowdown per FR.
5672 Revision 1.38 2002/03/05 23:55:14 hal9
5673 Stupid I did it again. Double hyphen in comment breaks jade.
5675 Revision 1.37 2002/03/05 23:53:49 hal9
5676 jade barfs on '- -' embedded in comments. - -user option broke it.
5678 Revision 1.36 2002/03/05 22:53:28 hal9
5679 Add new - - user option.
5681 Revision 1.35 2002/03/05 00:17:27 hal9
5682 Added section on command line options.
5684 Revision 1.34 2002/03/04 19:32:07 oes
5685 Changed default port to 8118
5687 Revision 1.33 2002/03/03 19:46:13 hal9
5688 Emphasis on where/how to report bugs, etc
5690 Revision 1.32 2002/03/03 09:26:06 joergs
5691 AmigaOS changes, config is now loaded from PROGDIR: instead of
5692 AmiTCP:db/junkbuster/ if no configuration file is specified on the
5695 Revision 1.31 2002/03/02 22:45:52 david__schmidt
5698 Revision 1.30 2002/03/02 22:00:14 hal9
5699 Updated 'New Features' list. Ran through spell-checker.
5701 Revision 1.29 2002/03/02 20:34:07 david__schmidt
5702 Update OS/2 build section
5704 Revision 1.28 2002/02/24 14:34:24 jongfoster
5705 Formatting changes. Now changing the doctype to DocBook XML 4.1
5706 will work - no other changes are needed.
5708 Revision 1.27 2002/01/11 14:14:32 hal9
5709 Added a very short section on Templates
5711 Revision 1.26 2002/01/09 20:02:50 hal9
5712 Fix bug re: auto-detect config file changes.
5714 Revision 1.25 2002/01/09 18:20:30 hal9
5715 Touch ups for *.action files.
5717 Revision 1.24 2001/12/02 01:13:42 hal9
5720 Revision 1.23 2001/12/02 00:20:41 hal9
5721 Updates for recent changes.
5723 Revision 1.22 2001/11/05 23:57:51 hal9
5724 Minor update for startup now daemon mode.
5726 Revision 1.21 2001/10/31 21:11:03 hal9
5727 Correct 2 minor errors
5729 Revision 1.18 2001/10/24 18:45:26 hal9
5730 *** empty log message ***
5732 Revision 1.17 2001/10/24 17:10:55 hal9
5733 Catching up with Jon's recent work, and a few other things.
5735 Revision 1.16 2001/10/21 17:19:21 swa
5736 wrong url in documentation
5738 Revision 1.15 2001/10/14 23:46:24 hal9
5739 Various minor changes. Fleshed out SEE ALSO section.
5741 Revision 1.13 2001/10/10 17:28:33 hal9
5744 Revision 1.12 2001/09/28 02:57:04 hal9
5747 Revision 1.11 2001/09/28 02:25:20 hal9
5750 Revision 1.9 2001/09/27 23:50:29 hal9
5751 A few changes. A short section on regular expression in appendix.
5753 Revision 1.8 2001/09/25 00:34:59 hal9
5754 Some additions, and re-arranging.
5756 Revision 1.7 2001/09/24 14:31:36 hal9
5759 Revision 1.6 2001/09/24 14:10:32 hal9
5760 Including David's OS/2 installation instructions.
5762 Revision 1.2 2001/09/13 15:27:40 swa
5765 Revision 1.1 2001/09/12 15:36:41 swa
5766 source files for junkbuster documentation
5768 Revision 1.3 2001/09/10 17:43:59 swa
5769 first proposal of a structure.
5771 Revision 1.2 2001/06/13 14:28:31 swa
5772 docs should have an author.
5774 Revision 1.1 2001/06/13 14:20:37 swa
5775 first import of project's documentation for the webserver.
projects / privoxy.git / blob