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.91 2002/04/24 02:39:31 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.91 2002/04/24 02:39:31 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 that require persistent
482 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>), until 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 more
488 sense to let <application>Privoxy</application> handle this. In which case,
489 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.
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 chapter <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.
654 <!-- ~~~~~ New section ~~~~~ -->
657 <title>Controlling <application>Privoxy</application> with Your Web Browser</title>
659 <application>Privoxy</application>'s user interface can be reached through the special
660 URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
661 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
662 which is a built-in page and works without Internet access.
663 You will see the following section:
672 * View & change the current configuration
673 * View the source code version numbers
674 * View the request headers.
675 * Look up which actions apply to a URL and why
676 * Toggle Privoxy on or off
682 This should be self-explanatory. Note the first item leads to an editor for the
683 <quote>actions list</quote>, which is where the ad, banner, cookie,
684 and URL blocking magic is configured as well as other advanced features of
685 <application>Privoxy</application>. This is an easy way to adjust various
686 aspects of <application>Privoxy</application> configuration. The actions
687 file, and other configuration files, are explained in detail below.
691 <quote>Toggle Privoxy On or Off</quote> is handy for sites that might
692 have problems with your current actions and filters. You can in fact use
693 it as a test to see whether it is <application>Privoxy</application>
694 causing the problem or not. <application>Privoxy</application> continues
695 to run as a proxy in this case, but all filtering is disabled. There
696 is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
697 that you can toggle <application>Privoxy</application> with one click from
703 <!-- ~ End section ~ -->
708 <!-- ~~~~~ New section ~~~~~ -->
710 <sect2 id="confoverview">
711 <title>Configuration Files Overview</title>
713 For Unix, *BSD and Linux, all configuration files are located in
714 <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
715 AmigaOS these are all in the same directory as the
716 <application>Privoxy</application> executable. <![%p-not-stable;[ The name
717 and number of configuration files has changed from previous versions, and is
718 subject to change as development progresses.]]>
722 The installed defaults provide a reasonable starting point, though
723 some settings may be aggressive by some standards. For the time being, the
724 principle configuration files are:
732 The main configuration file is named <filename>config</filename>
733 on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
734 on Windows. This is a required file.
740 <filename>default.action</filename> (the main actions file) is used to define
741 the default settings for various <quote>actions</quote> relating to images, banners,
742 pop-ups, access restrictions, banners and cookies.
745 Multiple actions files may be defined in <filename>config</filename>. These
746 are processed in the order they are defined. Local customizations and locally
747 preferred exceptions to the default policies as defined in
748 <filename>default.action</filename> are probably best applied in
749 <filename>user.action</filename>, which should be preserved across
750 upgrades. <filename>standard.action</filename> is also included. This is mostly
751 for <application>Privoxy's</application> internal use.
754 There is also a web based editor for this file that can be accessed at
756 url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
758 url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>) for the
759 various actions files.
765 <filename>default.filter</filename> (the filter file) can be used to re-write the raw
766 page content, including viewable text as well as embedded HTML and JavaScript,
767 and whatever else lurks on any given web page. The filtering jobs are only
768 pre-defined here; whether to apply them or not is up to the actions files.
776 All files use the <quote><literal>#</literal></quote> character to denote a
777 comment (the rest of the line will be ignored) and understand line continuation
778 through placing a backslash ("<literal>\</literal>") as the very last character
779 in a line. If the <literal>#</literal> is preceded by a backslash, it looses
780 its special function. Placing a <literal>#</literal> in front of an otherwise
781 valid configuration line to prevent it from being interpreted is called "commenting
786 The actions files and <filename>default.filter</filename>
787 can use Perl style <link linkend="regex">regular expressions</link> for
792 After making any changes, there is no need to restart
793 <application>Privoxy</application> in order for the changes to take
794 effect. <application>Privoxy</application> detects such changes
795 automatically. Note, however, that it may take one or two additional
796 requests for the change to take effect. When changing the listening address
797 of <application>Privoxy</application>, these <quote>wake up</quote> requests
798 must obviously be sent to the <emphasis>old</emphasis> listening address.
803 While under development, the configuration content is subject to change.
804 The below documentation may not be accurate by the time you read this.
805 Also, what constitutes a <quote>default</quote> setting, may change, so
806 please check all your configuration files on important issues.
812 <!-- ~~~~~ New section ~~~~~ -->
815 <title>The Main Configuration File</title>
817 Again, the main configuration file is named <filename>config</filename> on
818 Linux/Unix/BSD and OS/2, and <filename>config.txt</filename> on Windows.
819 Configuration lines consist of an initial keyword followed by a list of
820 values, all separated by whitespace (any number of spaces or tabs). For
828 <emphasis>confdir /etc/privoxy</emphasis>
835 Assigns the value <literal>/etc/privoxy</literal> to the option
836 <literal>confdir</literal> and thus indicates that the configuration
837 directory is named <quote>/etc/privoxy/</quote>.
841 All options in the config file except for <literal>confdir</literal> and
842 <literal>logdir</literal> are optional. Watch out in the below description
843 for what happens if you leave them unset.
847 The main config file controls all aspects of <application>Privoxy</application>'s
848 operation that are not location dependent (i.e. they apply universally, no matter
849 where you may be surfing).
853 <!-- ~~~~~ New section ~~~~~ -->
855 <sect3 id="conf-log-loc">
856 <title>Configuration and Log File Locations</title>
859 <application>Privoxy</application> can (and normally does) use a number of
860 other files for additional configuration and logging.
861 This section of the configuration file tells <application>Privoxy</application>
862 where to find those other files.
866 <sect4 id="confdir"><title>confdir</title>
870 <term>Specifies:</term>
872 <para>The directory where the other configuration files are located</para>
876 <term>Type of value:</term>
878 <para>Path name</para>
882 <term>Default value:</term>
884 <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
888 <term>Effect if unset:</term>
890 <para><emphasis>Mandatory</emphasis></para>
897 No trailing <quote><literal>/</literal></quote>, please
900 When development goes modular and multi-user, the blocker, filter, and
901 per-user config will be stored in subdirectories of <quote>confdir</quote>.
902 For now, the configuration directory structure is flat, except for
903 <filename>confdir/templates</filename>, where the HTML templates for CGI
904 output reside (e.g. <application>Privoxy's</application> 404 error page).
912 <sect4 id="logdir"><title>logdir</title>
916 <term>Specifies:</term>
919 The directory where all logging takes place (i.e. where <filename>logfile</filename> and
920 <filename>jarfile</filename> are located)
925 <term>Type of value:</term>
927 <para>Path name</para>
931 <term>Default value:</term>
933 <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
937 <term>Effect if unset:</term>
939 <para><emphasis>Mandatory</emphasis></para>
946 No trailing <quote><literal>/</literal></quote>, please
953 <sect4 id="actionsfile"><title>
954 <anchor id="default.action">
955 <anchor id="standard.action">
956 <anchor id="user.action">
962 <term>Specifies:</term>
965 The actions file(s) to use
970 <term>Type of value:</term>
972 <para>File name, relative to <literal>confdir</literal></para>
976 <term>Default value:</term>
980 <msgtext><literallayout> standard # Internal purposes, recommended not editing</literallayout></msgtext>
983 <msgtext><literallayout> default # Main actions file</literallayout></msgtext>
986 <msgtext><literallayout> user # User customizations</literallayout></msgtext>
992 <term>Effect if unset:</term>
995 No actions are taken at all. Simple neutral proxying.
1003 Multiple <literal>actionsfile</literal> lines are OK and are in fact recommended!
1006 The default values include standard.action, which is used for internal
1007 purposes and should be loaded, default.action, which is the
1008 <quote>main</quote> actions file maintained by the developers, and
1009 user.action, where you can make your personal additions.
1012 There is no point in using <application>Privoxy</application> without an actions file.
1019 <sect4 id="filterfile"><title><anchor id="default.filter">filterfile</title>
1022 <term>Specifies:</term>
1025 The filter file to use
1030 <term>Type of value:</term>
1032 <para>File name, relative to <literal>confdir</literal></para>
1036 <term>Default value:</term>
1038 <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
1042 <term>Effect if unset:</term>
1045 No textual content filtering takes place, i.e. all
1046 <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
1047 actions in the actions files are turned off
1055 The <quote>default.filter</quote> file contains content modification rules
1056 that use <quote>regular expressions</quote>. These rules permit powerful
1057 changes on the content of Web pages, e.g., you could disable your favorite
1058 JavaScript annoyances, re-write the actual displayed text, or just have some
1059 fun replacing <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
1060 it appears on a Web page.
1067 <sect4 id="logfile"><title>logfile</title>
1071 <term>Specifies:</term>
1079 <term>Type of value:</term>
1081 <para>File name, relative to <literal>logdir</literal></para>
1085 <term>Default value:</term>
1087 <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
1091 <term>Effect if unset:</term>
1094 No log file is used, all log messages go to the console (<literal>stderr</literal>).
1102 The windows version will additionally log to the console.
1105 The logfile is where all logging and error messages are written. The level
1106 of detail and number of messages are set with the <literal>debug</literal>
1107 option (see below). The logfile can be useful for tracking down a problem with
1108 <application>Privoxy</application> (e.g., it's not blocking an ad you
1109 think it should block) but in most cases you probably will never look at it.
1112 Your logfile will grow indefinitely, and you will probably want to
1113 periodically remove it. On Unix systems, you can do this with a cron job
1114 (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command>
1115 script has been included.
1118 On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
1119 +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
1120 the effect that cron.daily will automatically archive, gzip, and empty the
1121 log, when it exceeds 1M size.
1128 <sect4 id="jarfile"><title>jarfile</title>
1132 <term>Specifies:</term>
1135 The file to store intercepted cookies in
1140 <term>Type of value:</term>
1142 <para>File name, relative to <literal>logdir</literal></para>
1146 <term>Default value:</term>
1148 <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
1152 <term>Effect if unset:</term>
1155 Intercepted cookies are not stored at all.
1163 The jarfile may grow to ridiculous sizes over time.
1170 <sect4 id="trustfile"><title>trustfile</title>
1174 <term>Specifies:</term>
1177 The trust file to use
1182 <term>Type of value:</term>
1184 <para>File name, relative to <literal>confdir</literal></para>
1188 <term>Default value:</term>
1190 <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
1194 <term>Effect if unset:</term>
1197 The whole trust mechanism is turned off.
1205 The trust mechanism is an experimental feature for building white-lists and should
1206 be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
1209 If you specify a trust file, <application>Privoxy</application> will only allow
1210 access to sites that are named in the trustfile.
1211 You can also mark sites as trusted referrers (with <literal>+</literal>), with
1212 the effect that access to untrusted sites will be granted, if a link from a
1213 trusted referrer was used.
1214 The link target will then be added to the <quote>trustfile</quote>.
1215 Possible applications include limiting Internet access for children.
1218 If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
1227 <!-- ~ End section ~ -->
1231 <!-- ~~~~~ New section ~~~~~ -->
1233 <sect3 id="local-set-up">
1234 <title>Local Set-up Documentation</title>
1237 If you intend to operate <application>Privoxy</application> for more users
1238 that just yourself, it might be a good idea to let them know how to reach
1239 you, what you block and why you do that, your policies etc.
1242 <sect4 id="trust-info-url"><title>trust-info-url</title>
1246 <term>Specifies:</term>
1249 A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
1254 <term>Type of value:</term>
1260 <term>Default value:</term>
1262 <para>Two example URL are provided</para>
1266 <term>Effect if unset:</term>
1269 No links are displayed on the "untrusted" error page.
1277 The value of this option only matters if the experimental trust mechanism has been
1278 activated. (See <literal>trustfile</literal> above.)
1281 If you use the trust mechanism, it is a good idea to write up some on-line
1282 documentation about your trust policy and to specify the URL(s) here.
1283 Use multiple times for multiple URLs.
1286 The URL(s) should be added to the trustfile as well, so users don't end up
1287 locked out from the information on why they were locked out in the first place!
1294 <sect4 id="admin-address"><title>admin-address</title>
1298 <term>Specifies:</term>
1301 An email address to reach the proxy administrator.
1306 <term>Type of value:</term>
1308 <para>Email address</para>
1312 <term>Default value:</term>
1314 <para><emphasis>Unset</emphasis></para>
1318 <term>Effect if unset:</term>
1321 No email address is displayed on error pages and the CGI user interface.
1329 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1330 are unset, the whole "Local Privoxy Support" box on all generated pages will
1338 <sect4 id="proxy-info-url"><title>proxy-info-url</title>
1342 <term>Specifies:</term>
1345 A URL to documentation about the local <application>Privoxy</application> setup,
1346 configuration or policies.
1351 <term>Type of value:</term>
1357 <term>Default value:</term>
1359 <para><emphasis>Unset</emphasis></para>
1363 <term>Effect if unset:</term>
1366 No link to local documentation is displayed on error pages and the CGI user interface.
1374 If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
1375 are unset, the whole "Local Privoxy Support" box on all generated pages will
1379 This URL shouldn't be blocked ;-)
1387 <!-- ~ End section ~ -->
1389 <!-- ~~~~~ New section ~~~~~ -->
1391 <sect3 id="debugging">
1392 <title>Debugging</title>
1395 These options are mainly useful when tracing a problem.
1396 Note that you might also want to invoke
1397 <application>Privoxy</application> with the <literal>--no-daemon</literal>
1398 command line option when debugging.
1401 <sect4 id="debug"><title>debug</title>
1405 <term>Specifies:</term>
1408 Key values that determine what information gets logged.
1413 <term>Type of value:</term>
1415 <para>Integer values</para>
1419 <term>Default value:</term>
1421 <para>12289 (i.e.: URLs plus informational and warning messages)</para>
1425 <term>Effect if unset:</term>
1428 Nothing gets logged.
1436 The available debug levels are:
1440 debug 1 # show each GET/POST/CONNECT request
1441 debug 2 # show each connection status
1442 debug 4 # show I/O status
1443 debug 8 # show header parsing
1444 debug 16 # log all data into the logfile
1445 debug 32 # debug force feature
1446 debug 64 # debug regular expression filter
1447 debug 128 # debug fast redirects
1448 debug 256 # debug GIF de-animation
1449 debug 512 # Common Log Format
1450 debug 1024 # debug kill pop-ups
1451 debug 4096 # Startup banner and warnings.
1452 debug 8192 # Non-fatal errors
1456 To select multiple debug levels, you can either add them or use
1457 multiple <literal>debug</literal> lines.
1460 A debug level of 1 is informative because it will show you each request
1461 as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
1462 so that you will notice when things go wrong. The other levels are probably
1463 only of interest if you are hunting down a specific problem. They can produce
1464 a hell of an output (especially 16).
1468 The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
1469 <application>Privoxy</application>) is always on and cannot be disabled.
1472 If you want to use CLF (Common Log Format), you should set <quote>debug
1473 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
1480 <sect4 id="single-threaded"><title>single-threaded</title>
1484 <term>Specifies:</term>
1487 Whether to run only one server thread
1492 <term>Type of value:</term>
1494 <para><emphasis>None</emphasis></para>
1498 <term>Default value:</term>
1500 <para><emphasis>Unset</emphasis></para>
1504 <term>Effect if unset:</term>
1507 Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
1508 serve multiple requests simultaneously.
1516 This option is only there for debug purposes and you should never
1517 need to use it. <emphasis>It will drastically reduce performance.</emphasis>
1526 <!-- ~~~~~ New section ~~~~~ -->
1528 <sect3 id="access-control">
1529 <title>Access Control and Security</title>
1532 This section of the config file controls the security-relevant aspects
1533 of <application>Privoxy</application>'s configuration.
1536 <sect4 id="listen-address"><title>listen-address</title>
1540 <term>Specifies:</term>
1543 The IP address and TCP port on which <application>Privoxy</application> will
1544 listen for client requests.
1549 <term>Type of value:</term>
1551 <para>[<replaceable class="parameter">IP-Address</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
1555 <term>Default value:</term>
1557 <para>localhost:8118</para>
1561 <term>Effect if unset:</term>
1564 Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
1565 home users who run <application>Privoxy</application> on the same machine as
1574 You will need to configure your browser(s) to this proxy address and port.
1577 If you already have another service running on port 8118, or if you want to
1578 serve requests from other machines (e.g. on your local network) as well, you
1579 will need to override the default.
1582 If you leave out the IP address, <application>Privoxy</application> will
1583 bind to all interfaces (addresses) on your machine and may become reachable
1584 from the Internet. In that case, consider using access control lists (ACL's)
1585 (see <quote>ACLs</quote> below), or a firewall.
1590 <term>Example:</term>
1593 Suppose you are running <application>Privoxy</application> on
1594 a machine which has the address 192.168.0.1 on your local private network
1595 (192.168.0.0) and has another outside connection with a different address.
1596 You want it to serve requests from inside only:
1600 listen-address 192.168.0.1:8118
1608 <sect4 id="toggle"><title>toggle</title>
1612 <term>Specifies:</term>
1615 Initial state of "toggle" status
1620 <term>Type of value:</term>
1626 <term>Default value:</term>
1632 <term>Effect if unset:</term>
1635 Act as if toggled on
1643 If set to 0, <application>Privoxy</application> will start in
1644 <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
1645 proxy. See <literal>enable-remote-toggle</literal>
1646 below. This is not really useful anymore, since toggling is much easier
1647 via <ulink url="http://config.privoxy.org/toggle">the web
1648 interface</ulink> then via editing the <filename>conf</filename> file.
1651 The windows version will only display the toggle icon in the system tray
1652 if this option is present.
1660 <sect4 id="enable-remote-toggle"><title>enable-remote-toggle</title>
1663 <term>Specifies:</term>
1666 Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
1667 feature</ulink> may be used
1672 <term>Type of value:</term>
1678 <term>Default value:</term>
1684 <term>Effect if unset:</term>
1687 The web-based toggle feature is disabled.
1695 When toggled off, <application>Privoxy</application> acts like a normal,
1696 content-neutral proxy, i.e. it acts as if none of the actions applied to
1700 For the time being, access to the toggle feature can <emphasis>not</emphasis> be
1701 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1702 so that everybody who can access <application>Privoxy</application> (see
1703 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1704 toggle it for all users. So this option is <emphasis>not recommended</emphasis>
1705 for multi-user environments with untrusted users.
1708 Note that you must have compiled <application>Privoxy</application> with
1709 support for this feature, otherwise this option has no effect.
1717 <sect4 id="enable-edit-actions"><title>enable-edit-actions</title>
1720 <term>Specifies:</term>
1723 Whether or not the <ulink url="http://config.privoxy.org/edit-actions">web-based actions
1724 file editor</ulink> may be used
1729 <term>Type of value:</term>
1735 <term>Default value:</term>
1741 <term>Effect if unset:</term>
1744 The web-based actions file editor is disabled.
1752 For the time being, access to the editor can <emphasis>not</emphasis> be
1753 controlled separately by <quote>ACLs</quote> or HTTP authentication,
1754 so that everybody who can access <application>Privoxy</application> (see
1755 <quote>ACLs</quote> and <literal>listen-address</literal> above) can
1756 modify its configuration for all users. So this option is <emphasis>not
1757 recommended</emphasis> for multi-user environments with untrusted users.
1760 Note that you must have compiled <application>Privoxy</application> with
1761 support for this feature, otherwise this option has no effect.
1768 <sect4 id="acls"><title>
1769 <anchor id="permit-acces">
1770 <anchor id="deny-acces">
1771 ACLs: permit-access and deny-access</title>
1775 <term>Specifies:</term>
1778 Who can access what.
1783 <term>Type of value:</term>
1786 <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
1787 [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
1790 Where <replaceable class="parameter">src_addr</replaceable> and
1791 <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
1792 DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
1793 <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
1794 values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
1795 destination part are optional.
1800 <term>Default value:</term>
1802 <para><emphasis>Unset</emphasis></para>
1806 <term>Effect if unset:</term>
1809 Don't restrict access further than implied by <literal>listen-address</literal>
1817 Access controls are included at the request of ISPs and systems
1818 administrators, and <emphasis>are not usually needed by individual users</emphasis>.
1819 For a typical home user, it will normally suffice to ensure that
1820 <application>Privoxy</application> only listens on the localhost or internal (home)
1821 network address by means of the <literal>listen-address</literal> option.
1824 Please see the warnings in the FAQ that this proxy is not intended to be a substitute
1825 for a firewall or to encourage anyone to defer addressing basic security
1829 Multiple ACL lines are OK.
1830 If any ACLs are specified, then the <application>Privoxy</application>
1831 talks only to IP addresses that match at least one <literal>permit-access</literal> line
1832 and don't match any subsequent <literal>deny-access</literal> line. In other words, the
1833 last match wins, with the default being <literal>deny-access</literal>.
1836 If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
1837 for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
1838 that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
1839 of the ultimate target. This is necessary because it may be impossible for the local
1840 <application>Privoxy</application> to determine the IP address of the
1841 ultimate target (that's often what gateways are used for).
1844 You should prefer using IP addresses over DNS names, because the address lookups take
1845 time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
1846 like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
1847 IP addresses, only the first one is used.
1850 Denying access to particular sites by ACL may have undesired side effects
1851 if the site in question is hosted on a machine which also hosts other sites.
1856 <term>Examples:</term>
1859 Explicitly define the default behavior if no ACL and
1860 <literal>listen-address</literal> are set: <quote>localhost</quote>
1861 is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
1862 <emphasis>all</emphasis> destination addresses are OK:
1866 permit-access localhost
1870 Allow any host on the same class C subnet as www.privoxy.org access to
1871 nothing but www.example.com:
1875 permit-access www.privoxy.org/24 www.example.com/32
1879 Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
1880 with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
1884 permit-access 192.168.45.64/26
1885 deny-access 192.168.45.73 www.dirty-stuff.example.com
1893 <sect4 id="buffer-limit"><title>buffer-limit</title>
1897 <term>Specifies:</term>
1900 Maximum size of the buffer for content filtering.
1905 <term>Type of value:</term>
1907 <para>Size in Kbytes</para>
1911 <term>Default value:</term>
1917 <term>Effect if unset:</term>
1920 Use a 4MB (4096 KB) limit.
1928 For content filtering, i.e. the <literal>+filter</literal> and
1929 <literal>+deanimate-gif</literal> actions, it is necessary that
1930 <application>Privoxy</application> buffers the entire document body.
1931 This can be potentially dangerous, since a server could just keep sending
1932 data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
1936 When a document buffer size reaches the <literal>buffer-limit</literal>, it is
1937 flushed to the client unfiltered and no further attempt to
1938 filter the rest of the document is made. Remember that there may be multiple threads
1939 running, which might require up to <literal>buffer-limit</literal> Kbytes
1940 <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
1950 <!-- ~ End section ~ -->
1953 <!-- ~~~~~ New section ~~~~~ -->
1955 <sect3 id="forwarding">
1956 <title>Forwarding</title>
1959 This feature allows routing of HTTP requests through a chain of
1961 It can be used to better protect privacy and confidentiality when
1962 accessing specific domains by routing requests to those domains
1963 through an anonymous public proxy (see e.g. <ulink
1964 url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
1965 Or to use a caching proxy to speed up browsing. Or chaining to a parent
1966 proxy may be necessary because the machine that <application>Privoxy</application>
1967 runs on has no direct Internet access.
1971 Also specified here are SOCKS proxies. <application>Privoxy</application>
1972 supports the SOCKS 4 and SOCKS 4A protocols.
1975 <sect4 id="forward"><title>forward</title>
1978 <term>Specifies:</term>
1981 To which parent HTTP proxy specific requests should be routed.
1986 <term>Type of value:</term>
1989 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
1990 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
1993 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
1994 chapter on domain matching in the <filename>default.action</filename> file),
1995 <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
1996 as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
1997 <quote>no forwarding</quote>, and the optional
1998 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
1999 values from 1 to 64535
2004 <term>Default value:</term>
2006 <para><emphasis>Unset</emphasis></para>
2010 <term>Effect if unset:</term>
2013 Don't use parent HTTP proxies.
2021 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2022 forwarded to another HTTP proxy but are made directly to the web servers.
2025 Multiple lines are OK, they are checked in sequence, and the last match wins.
2030 <term>Examples:</term>
2033 Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
2037 forward .* anon-proxy.example.org:8080
2042 Everything goes to our example ISP's caching proxy, except for requests
2043 to that ISP's sites:
2047 forward .*. caching-proxy.example-isp.net:8000
2048 forward .example-isp.net .
2056 <sect4 id="socks"><title>
2057 <anchor id="forward-socks4">
2058 <anchor id="forward-socks4a">
2059 forward-socks4 and forward-socks4a</title>
2063 <term>Specifies:</term>
2066 Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
2071 <term>Type of value:</term>
2074 <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
2075 <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
2076 <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
2079 Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
2080 chapter on domain matching in the <filename>default.action</filename> file),
2081 <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
2082 are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
2083 may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
2084 <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
2089 <term>Default value:</term>
2091 <para><emphasis>Unset</emphasis></para>
2095 <term>Effect if unset:</term>
2098 Don't use SOCKS proxies.
2106 Multiple lines are OK, they are checked in sequence, and the last match wins.
2109 The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
2110 is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
2111 server, while in SOCKS 4 it happens locally.
2114 If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
2115 forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
2121 <term>Examples:</term>
2124 From the company example.com, direct connections are made to all
2125 <quote>internal</quote> domains, but everything outbound goes through
2126 their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to
2131 forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
2132 forward .example.com .
2136 A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
2140 forward-socks4 .*. socks-gw.example.com:1080 .
2148 <sect4 id="advanced-forwarding-examples"><title>Advanced Forwarding Examples</title>
2151 If you have links to multiple ISPs that provide various special content
2152 only to their subscribers, you can configure multiple <application>Privoxies</application>
2153 which have connections to the respective ISPs to act as forwarders to each other, so that
2154 <emphasis>your</emphasis> users can see the internal content of all ISPs.
2158 Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
2159 isp-b.net. Both run <application>Privoxy</application>. Their forwarding
2160 configuration can look like this:
2170 forward .isp-b.net host-b:8118
2181 forward .isp-a.net host-a:8118
2186 Now, your users can set their browser's proxy to use either
2187 host-a or host-b and be able to browse the internal content
2188 of both isp-a and isp-b.
2192 If you intend to chain <application>Privoxy</application> and
2193 <application>squid</application> locally, then chain as
2194 <literal>browser -> squid -> privoxy</literal> is the recommended way.
2198 Assuming that <application>Privoxy</application> and <application>squid</application>
2199 run on the same box, your squid configuration could then look like this:
2204 # Define Privoxy as parent proxy (without ICP)
2205 cache_peer 127.0.0.1 parent 8118 7 no-query
2207 # Define ACL for protocol FTP
2210 # Do not forward FTP requests to Privoxy
2211 always_direct allow ftp
2213 # Forward all the rest to Privoxy
2214 never_direct allow all
2219 You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
2220 Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
2227 <!-- ~ End section ~ -->
2230 <!-- ~~~~~ New section ~~~~~ -->
2232 <sect3 id="windows-gui">
2233 <title>Windows GUI Options</title>
2235 <application>Privoxy</application> has a number of options specific to the
2236 Windows GUI interface:
2239 <anchor id="activity-animation">
2241 If <quote>activity-animation</quote> is set to 1, the
2242 <application>Privoxy</application> icon will animate when
2243 <quote>Privoxy</quote> is active. To turn off, set to 0.
2250 <emphasis>activity-animation 1</emphasis>
2256 <anchor id="log-messages">
2258 If <quote>log-messages</quote> is set to 1,
2259 <application>Privoxy</application> will log messages to the console
2267 <emphasis>log-messages 1</emphasis>
2273 <anchor id="log-buffer-size">
2275 If <quote>log-buffer-size</quote> is set to 1, the size of the log buffer,
2276 i.e. the amount of memory used for the log messages displayed in the
2277 console window, will be limited to <quote>log-max-lines</quote> (see below).
2281 Warning: Setting this to 0 will result in the buffer to grow infinitely and
2282 eat up all your memory!
2289 <emphasis>log-buffer-size 1</emphasis>
2295 <anchor id="log-max-lines">
2297 <application>log-max-lines</application> is the maximum number of lines held
2298 in the log buffer. See above.
2305 <emphasis>log-max-lines 200</emphasis>
2311 <anchor id="log-highlight-messages">
2313 If <quote>log-highlight-messages</quote> is set to 1,
2314 <application>Privoxy</application> will highlight portions of the log
2315 messages with a bold-faced font:
2322 <emphasis>log-highlight-messages 1</emphasis>
2328 <anchor id="log-font-name">
2330 The font used in the console window:
2337 <emphasis>log-font-name Comic Sans MS</emphasis>
2343 <anchor id="log-font-size">
2345 Font size used in the console window:
2352 <emphasis>log-font-size 8</emphasis>
2358 <anchor id="show-on-task-bar">
2360 <quote>show-on-task-bar</quote> controls whether or not
2361 <application>Privoxy</application> will appear as a button on the Task bar
2369 <emphasis>show-on-task-bar 0</emphasis>
2375 <anchor id="close-button-minimizes">
2377 If <quote>close-button-minimizes</quote> is set to 1, the Windows close
2378 button will minimize <application>Privoxy</application> instead of closing
2379 the program (close with the exit option on the File menu).
2386 <emphasis>close-button-minimizes 1</emphasis>
2392 <anchor id="hide-console">
2394 The <quote>hide-console</quote> option is specific to the MS-Win console
2395 version of <application>Privoxy</application>. If this option is used,
2396 <application>Privoxy</application> will disconnect from and hide the
2413 <!-- ~ End section ~ -->
2416 <!-- ~~~~~ New section ~~~~~ -->
2417 <sect2 id="actions-file">
2418 <title>Actions Files</title>
2421 The actions files are used to define what actions
2422 <application>Privoxy</application> takes for which URLs, and thus determines
2423 how ad images, cookies and various other aspects of HTTP content and
2424 transactions are handled, and on which sites (or even parts thereof). There
2425 are three such files included with <application>Privoxy</application>,
2426 with slightly different purposes. <filename>default.action</filename> sets
2427 the default policies. <filename>standard.action</filename> is used by
2428 <application>Privoxy</application> and the web based editor to set
2429 pre-defined values (and normally should not be edited). Local exceptions
2430 are best done in <filename>user.action</filename>.
2434 Anything you want can blocked, including ads, banners, or just some obnoxious
2435 URL that you would rather not see. Cookies can be accepted or rejected, or
2436 accepted only during the current browser session (i.e. not written to disk),
2437 content can be modified, JavaScripts tamed, user-tracking fooled, and much more.
2438 See below for a complete list of available actions.
2442 An actions file typically has sections. Near the top, <quote>aliases</quote> are
2443 optionally defined (discussed <ulink
2444 url="configuration.html#ALIASES">below</ulink>), then the default set of rules
2445 which will apply universally to all sites and pages. And then below that,
2446 exceptions to the defined universal policies.
2449 <!-- ~~~~~ New section ~~~~~ -->
2451 <title>Finding the Right Mix</title>
2453 Note that some actions like cookie suppression or script disabling may
2454 render some sites unusable, which rely on these techniques to work properly.
2455 Finding the right mix of actions is not easy and certainly a matter of personal
2456 taste. In general, it can be said that the more <quote>aggressive</quote>
2457 your default settings (in the top section of the actions file) are,
2458 the more exceptions for <quote>trusted</quote> sites you will have to
2459 make later. If, for example, you want to kill popup windows per default, you'll
2460 have to make exceptions from that rule for sites that you regularly use
2461 and that require popups for actually useful content, like maybe your bank,
2462 favorite shop, or newspaper.
2466 We have tried to provide you with reasonable rules to start from in the
2467 distribution actions files. But there is no general rule of thumb on these
2468 things. There just are too many variables, and sites are constantly changing.
2469 Sooner or later you will want to change the rules (and read this chapter again :).
2473 <!-- ~~~~~ New section ~~~~~ -->
2475 <title>How to Edit</title>
2477 The easiest way to edit the <quote>actions</quote> files is with a browser by
2478 using our browser-based editor, which is available at <ulink
2479 url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>.
2483 If you prefer plain text editing to GUIs, you can of course also directly edit the
2490 <title>How Actions are Applied to URLs</title>
2492 Actions files are divided into sections. There are special sections,
2493 like the <quote>alias</quote> sections which will be discussed later. For now
2494 let's concentrate on regular sections: They have a heading line (often split
2495 up to multiple lines for readability) which consist of a list of actions,
2496 separated by whitespace and enclosed in curly braces. Below that, there
2497 is a list of URL patterns, each on a separate line.
2501 To determine which actions apply to a request, the URL of the request is
2502 compared to all patterns in this file. Every time it matches, the list of
2503 applicable actions for the URL is incrementally updated, using the heading
2504 of the section in which the pattern is located. If multiple matches for
2505 the same URL set the same action differently, the last match wins.
2509 You can trace this process by visiting <ulink
2510 url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
2514 More detail on this is provided in the Appendix, <link linkend="ACTIONSANAT">
2515 Anatomy of an Action</link>.
2519 <!-- ~~~~~ New section ~~~~~ -->
2521 <title>Patterns</title>
2523 Generally, a pattern has the form <literal><domain>/<path></literal>,
2524 where both the <literal><domain></literal> and <literal><path></literal>
2525 are optional. (This is why the pattern <literal>/</literal> matches all URLs).
2530 <term><literal>www.example.com/</literal></term>
2533 is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
2534 regardless of which document on that server is requested.
2539 <term><literal>www.example.com</literal></term>
2542 means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
2548 <term><literal>www.example.com/index.html</literal></term>
2551 matches only the single document <literal>/index.html</literal>
2552 on <literal>www.example.com</literal>.
2557 <term><literal>/index.html</literal></term>
2560 matches the document <literal>/index.html</literal>, regardless of the domain,
2561 i.e. on <emphasis>any</emphasis> web server.
2566 <term><literal>index.html</literal></term>
2569 matches nothing, since it would be interpreted as a domain name and
2570 there is no top-level domain called <literal>.html</literal>.
2576 <sect4><title>The Domain Pattern</title>
2579 The matching of the domain part offers some flexible options: if the
2580 domain starts or ends with a dot, it becomes unanchored at that end.
2586 <term><literal>.example.com</literal></term>
2589 matches any domain that <emphasis>ENDS</emphasis> in
2590 <literal>.example.com</literal>
2595 <term><literal>www.</literal></term>
2598 matches any domain that <emphasis>STARTS</emphasis> with
2599 <literal>www.</literal>
2604 <term><literal>.example.</literal></term>
2607 matches any domain that <emphasis>CONTAINS</emphasis> <literal>.example.</literal>
2608 (Correctly speaking: It matches any FQDN that contains <literal>example</literal> as a domain.)
2615 Additionally, there are wild-cards that you can use in the domain names
2616 themselves. They work pretty similar to shell wild-cards: <quote>*</quote>
2617 stands for zero or more arbitrary characters, <quote>?</quote> stands for
2618 any single character, you can define character classes in square
2619 brackets and all of that can be freely mixed:
2624 <term><literal>ad*.example.com</literal></term>
2627 matches <quote>adserver.example.com</quote>,
2628 <quote>ads.example.com</quote>, etc but not <quote>sfads.example.com</quote>
2633 <term><literal>*ad*.example.com</literal></term>
2636 matches all of the above, and then some.
2641 <term><literal>.?pix.com</literal></term>
2644 matches <literal>www.ipix.com</literal>,
2645 <literal>pictures.epix.com</literal>, <literal>a.b.c.d.e.upix.com</literal> etc.
2650 <term><literal>www[1-9a-ez].example.c*</literal></term>
2653 matches <literal>www1.example.com</literal>,
2654 <literal>www4.example.cc</literal>, <literal>wwwd.example.cy</literal>,
2655 <literal>wwwz.example.com</literal> etc., but <emphasis>not</emphasis>
2656 <literal>wwww.example.com</literal>.
2664 <sect4><title>The Path Pattern</title>
2667 <application>Privoxy</application> uses Perl compatible regular expressions
2668 (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
2673 There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
2674 expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
2675 at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
2676 You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
2677 useful, which is available on-line at <ulink
2678 url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>.
2682 Note that the path pattern is automatically left-anchored at the <quote>/</quote>,
2683 i.e. it matches as if it would start with a <quote>^</quote> (regular expression speak
2684 for the beginning of a line).
2688 Please also note that matching in the path is case
2689 <emphasis>INSENSITIVE</emphasis> by default, but you can switch to case
2690 sensitive at any point in the pattern by using the
2691 <quote>(?-i)</quote> switch:
2692 <literal>www.example.com/(?-i)PaTtErN.*</literal> will match only
2693 documents whose path starts with <literal>PaTtErN</literal> in
2694 <emphasis>exactly</emphasis> this capitalization.
2700 <!-- ~ End section ~ -->
2703 <!-- ~~~~~ New section ~~~~~ -->
2705 <sect3 id="actions">
2706 <title>Actions</title>
2708 All actions are disabled by default, until they are explicitly enabled
2709 somewhere in an actions file. Actions are turned on if preceded with a
2710 <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
2711 <quote>+action</quote> means <quote>do that action</quote>, e.g.
2712 <quote>+block</quote> means please <quote>block the following URL
2717 Actions are invoked by enclosing the action name in curly braces (e.g.
2718 {+some_action}), followed by a list of URLs (or patterns that match URLs) to
2719 which the action applies. There are three classes of actions:
2727 Boolean, i.e the action can only be <quote>on</quote> or
2728 <quote>off</quote>. Examples:
2734 <emphasis>{+name}</emphasis> # enable this action
2735 <emphasis>{-name}</emphasis> # disable this action
2745 Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>,
2746 where some value is required in order to enable this type of action.
2753 <emphasis>{+name{param}}</emphasis> # enable action and set parameter to <quote>param</quote>
2754 <emphasis>{-name}</emphasis> # disable action (<quote>parameter</quote>) can be omitted
2763 <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
2764 Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> or
2765 <quote>{+/-send-wafer{name=value}}</quote>), where some value needs to be defined
2766 in addition to simply enabling the action. Examples:
2772 <emphasis>{+name{param=value}}</emphasis> # enable action and set <quote>param</quote> to <quote>value</quote>
2773 <emphasis>{-name{param=value}}</emphasis> # remove the parameter <quote>param</quote> completely
2774 <emphasis>{-name}</emphasis> # disable this action totally and remove <application>param</application> too
2785 If nothing is specified in any actions file, no <quote>actions</quote> are
2786 taken. So in this case <application>Privoxy</application> would just be a
2787 normal, non-blocking, non-anonymizing proxy. You must specifically enable the
2788 privacy and blocking features you need (although the provided default actions
2789 files will give a good starting point).
2793 Later defined actions always over-ride earlier ones. So exceptions
2794 to any rules you make, should come in the latter part of the file. For
2795 multi-valued actions, the actions are applied in the order they are
2796 specified. Actions files are processed in the order they are defined
2797 in <filename>config</filename> (the default installation has three
2798 actions files). It also quite possible for any given URL pattern to
2799 match more than one action!
2802 <!-- start actions listing -->
2804 The list of valid <application>Privoxy</application> <quote>actions</quote> are:
2808 <!-- ********************************************************** -->
2809 <!-- Please note the below defined actions use id's that are -->
2810 <!-- probably linked from other places, so please don't change. -->
2812 <!-- ********************************************************** -->
2815 <!-- ~~~~~ New section ~~~~~ -->
2817 <sect4 id="add-header">
2818 <title><emphasis>+add-header{Name: value}</emphasis></title>
2823 <!-- boolean, parameterized, Multi-value -->
2825 <para>Multi-value.</para>
2830 <term>Typical uses:</term>
2833 Send a user defined HTTP header to the web server.
2839 <term>Possible values:</term>
2842 Any value is possible. Validity of the defined HTTP headers is not checked.
2848 <term>Example usage:</term>
2851 <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
2852 <emphasis>.example.com</emphasis>
2861 This action may be specified multiple times, in order to define multiple
2862 headers. This is rarely needed for the typical user. If you don't know what
2863 <quote>HTTP headers</quote> are, you definitely don't need to worry about this
2872 <!-- ~~~~~ New section ~~~~~ -->
2874 <title><emphasis>+block</emphasis></title>
2879 <!-- boolean, parameterized, Multi-value -->
2881 <para>Boolean.</para>
2886 <term>Typical uses:</term>
2889 Used to block a URL from reaching your browser. The URL may be
2890 anything, but is typically used to block ads or other obnoxious
2897 <term>Possible values:</term>
2904 <term>Example usage:</term>
2907 <emphasis>{+block}</emphasis>
2908 <emphasis>.banners.example.com</emphasis>
2909 <emphasis>.ads.r.us</emphasis>
2918 If a URL matches one of the blocked patterns, <application>Privoxy</application>
2919 will intercept the URL and display its special <quote>BLOCKED</quote> page
2920 instead. If there is sufficient space, a large red banner will appear with
2921 a friendly message about why the page was blocked, and a way to go there
2922 anyway. If there is insufficient space a smaller blocked page will appear
2923 without the red banner.
2927 A very important exception is if the URL <emphasis>matches both</emphasis> <quote>+block</quote>
2929 url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>,
2930 then it will be handled by
2931 <ulink url="configuration.html#SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></ulink>
2932 (see below). It is important to understand this process, in order
2933 to understand how <application>Privoxy</application> is able to deal with
2934 ads and other objectionable content.
2937 The <quote>+filter</quote> action can also perform some of the
2938 same functionality as <quote>+block</quote>, but by virtue of very
2939 different programming techniques, and is most often used for different
2949 <!-- ~~~~~ New section ~~~~~ -->
2950 <sect4 id="deanimate-gifs">
2951 <title><emphasis>+deanimate-gifs</emphasis></title>
2956 <!-- boolean, parameterized, Multi-value -->
2958 <para>Parameterized.</para>
2963 <term>Typical uses:</term>
2966 To stop those annoying, distracting animated GIF images.
2972 <term>Possible values:</term>
2975 <quote>last</quote> or <quote>first</quote>
2981 <term>Example usage:</term>
2984 <emphasis>{+deanimate-gifs{last}}</emphasis>
2985 <emphasis>.example.com</emphasis>
2994 De-animate all animated GIF images, i.e. reduce them to their last frame.
2995 This will also shrink the images considerably (in bytes, not pixels!). If
2996 the option <quote>first</quote> is given, the first frame of the animation
2997 is used as the replacement. If <quote>last</quote> is given, the last
2998 frame of the animation is used instead, which probably makes more sense for
2999 most banner animations, but also has the risk of not showing the entire
3000 last frame (if it is only a delta to an earlier frame).
3008 <!-- ~~~~~ New section ~~~~~ -->
3009 <sect4 id="downgrade-http-version">
3010 <title><emphasis>+downgrade-http-version</emphasis></title>
3015 <!-- boolean, parameterized, Multi-value -->
3017 <para>Boolean.</para>
3022 <term>Typical uses:</term>
3025 <quote>+downgrade-http-version</quote> will downgrade HTTP/1.1 client requests to
3026 HTTP/1.0 and downgrade the responses as well.
3032 <term>Possible values:</term>
3041 <term>Example usage:</term>
3044 <emphasis>{+downgrade-http-version}</emphasis>
3045 <emphasis>.example.com</emphasis>
3054 Use this action for servers that use HTTP/1.1 protocol features that
3055 <application>Privoxy</application> doesn't handle well yet. HTTP/1.1 is
3056 only partially implemented. Default is not to downgrade requests. This is
3057 an infrequently needed action, and is used to help with rare problem sites only.
3065 <!-- ~~~~~ New section ~~~~~ -->
3066 <sect4 id="fast-redirects">
3067 <title><emphasis>+fast-redirects</emphasis></title>
3072 <!-- boolean, parameterized, Multi-value -->
3074 <para>Boolean.</para>
3079 <term>Typical uses:</term>
3082 The <quote>+fast-redirects</quote> action enables interception of
3083 <quote>redirect</quote> requests from one server to another, which
3084 are used to track users.<application>Privoxy</application> can cut off
3085 all but the last valid URL in a redirect request and send a local redirect
3086 back to your browser without contacting the intermediate site(s).
3092 <term>Possible values:</term>
3101 <term>Example usage:</term>
3104 <emphasis>{+fast-redirects}</emphasis>
3105 <emphasis>.example.com</emphasis>
3114 Many sites, like yahoo.com, don't just link to other sites. Instead, they
3115 will link to some script on their own server, giving the destination as a
3116 parameter, which will then redirect you to the final target. URLs
3117 resulting from this scheme typically look like:
3118 <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
3121 Sometimes, there are even multiple consecutive redirects encoded in the
3122 URL. These redirections via scripts make your web browsing more traceable,
3123 since the server from which you follow such a link can see where you go
3124 to. Apart from that, valuable bandwidth and time is wasted, while your
3125 browser ask the server for one redirect after the other. Plus, it feeds
3129 This is a normally <quote>on</quote> feature, and often requires exceptions
3130 for sites that are sensitive to defeating this mechanism.
3139 <!-- ~~~~~ New section ~~~~~ -->
3141 <title><emphasis>+filter</emphasis></title>
3146 <!-- boolean, parameterized, Multi-value -->
3148 <para>Parameterized.</para>
3153 <term>Typical uses:</term>
3156 Apply page filtering as defined by named sections of the
3157 <filename>default.filter</filename> file to the specified site(s).
3158 <quote>Filtering</quote> can be any modification of the raw
3159 page content, including re-writing or deletion of content.
3165 <term>Possible values:</term>
3168 <quote>+filter</quote> must include the name of one of the section identifiers
3169 from <filename>default.filter</filename> (or whatever
3170 <emphasis>filterfile</emphasis> is specified in <filename>config</filename>).
3176 <term>Example usage (from the current <filename>default.filter</filename>):</term>
3180 <emphasis>+filter{html-annoyances}</emphasis>: Get rid of particularly annoying HTML abuse.
3185 <emphasis>+filter{js-annoyances}</emphasis>: Get rid of particularly annoying JavaScript abuse
3190 <emphasis>+filter{content-cookies}</emphasis>: Kill cookies that come in the HTML or JS content
3195 <emphasis>+filter{popups}</emphasis>: Kill all popups in JS and HTML
3200 <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable
3205 <emphasis>+filter{webbugs}</emphasis>: Squish WebBugs (1x1 invisible GIFs used for user tracking)
3210 <emphasis>+filter{refresh-tags}</emphasis>: Kill automatic refresh tags (for dial-on-demand setups)
3215 <emphasis>+filter{fun}</emphasis>: Text replacements for subversive browsing fun!
3220 <emphasis>+filter{nimda}</emphasis>: Remove Nimda (virus) code.
3225 <emphasis>+filter{banners-by-size}</emphasis>: Kill banners by size (<emphasis>very</emphasis> efficient!)
3230 <emphasis>+filter{shockwave-flash}</emphasis>: Kill embedded Shockwave Flash objects
3235 <emphasis>+filter{crude-parental}</emphasis>: Kill all web pages that contain the words "sex" or "warez"
3245 This is potentially a very powerful feature! And requires a knowledge
3246 of regular expressions if you want to <quote>roll your own</quote>.
3247 Filtering operates on a line by line basis throughout the entire page.
3250 Filtering requires buffering the page content, which may appear to
3251 slow down page rendering since nothing is displayed until all content has
3252 passed the filters. (It does not really take longer, but seems that way
3253 since the page is not incrementally displayed.) This effect will be more
3254 noticeable on slower connections.
3257 Filtering can achieve some of the effects as the
3258 <ulink url="configuration.html#BLOCK"><quote>+block</quote></ulink>
3259 action, i.e. it can be used to block ads and banners. In the overall
3260 scheme of things, filtering is one of the last things <quote>Privoxy</quote>
3261 does with a web page. So other actions are applied first.
3270 <!-- ~~~~~ New section ~~~~~ -->
3271 <sect4 id="hide-forwarded-for-headers">
3272 <title><emphasis>+hide-forwarded-for-headers</emphasis></title>
3277 <!-- Boolean, Parameterized, Multi-value -->
3279 <para>Boolean.</para>
3284 <term>Typical uses:</term>
3287 Block any existing X-Forwarded-for HTTP header, and do not add a new one.
3293 <term>Possible values:</term>
3302 <term>Example usage:</term>
3305 <emphasis>{+hide-forwarded-for-headers}</emphasis>
3306 <emphasis>.example.com</emphasis>
3315 It is fairly safe to leave this on. It does not seem to break many sites.
3324 <!-- ~~~~~ New section ~~~~~ -->
3325 <sect4 id="hide-from-header">
3326 <title><emphasis>+hide-from-header</emphasis></title>
3331 <!-- Boolean, Parameterized, Multi-value -->
3333 <para>Parameterized.</para>
3338 <term>Typical uses:</term>
3341 To block the browser from sending your email address in a <quote>From:</quote>
3348 <term>Possible values:</term>
3351 Keyword: <quote>block</quote>, or any user defined value.
3357 <term>Example usage:</term>
3360 <emphasis>{+hide-from-header{block}}</emphasis>
3361 <emphasis>.example.com</emphasis>
3370 The keyword <quote>block</quote> will completely remove the header
3371 (not to be confused with the <quote>+block</quote> action).
3372 Alternately, you can specify any value you prefer to send to the web
3382 <!-- ~~~~~ New section ~~~~~ -->
3383 <sect4 id="hide-referer">
3384 <title><emphasis><anchor id="hide-referrer">+hide-referer</emphasis></title>
3390 <!-- Boolean, Parameterized, Multi-value -->
3392 <para>Parameterized.</para>
3397 <term>Typical uses:</term>
3400 Don't send the <quote>Referer:</quote> (sic) HTTP header to the web site.
3401 Or, alternately send a forged header instead.
3407 <term>Possible values:</term>
3410 Prevent the header from being sent with the keyword, <quote>block</quote>.
3411 Or, <quote>forge</quote> a URL to one from the same server as the request.
3412 Or, set to user defined value of your choice.
3418 <term>Example usage:</term>
3421 <emphasis>{+hide-referer{forge}}</emphasis>
3422 <emphasis>.example.com</emphasis>
3431 <quote>forge</quote> is the preferred option here, since some servers will
3432 not send images back otherwise.
3435 <quote>+hide-referrer</quote> is an alternate spelling of
3436 <quote>+hide-referer</quote>. It has the exact same parameters, and can be freely
3437 mixed with, <quote>+hide-referer</quote>. (<quote>referrer</quote> is the
3438 correct English spelling, however the HTTP specification has a bug - it
3439 requires it to be spelled as <quote>referer</quote>.)
3448 <!-- ~~~~~ New section ~~~~~ -->
3449 <sect4 id="hide-user-agent">
3450 <title><emphasis>+hide-user-agent</emphasis></title>
3455 <!-- Boolean, Parameterized, Multi-value -->
3457 <para>Parameterized.</para>
3462 <term>Typical uses:</term>
3465 To change the <quote>User-Agent:</quote> header so web servers can't tell
3466 your browser type. Who's business is it anyway?
3472 <term>Possible values:</term>
3475 Any user defined string.
3481 <term>Example usage:</term>
3484 <emphasis>{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</emphasis>
3485 <emphasis>.msn.com</emphasis>
3494 Warning! This breaks many web sites that depend on this in order
3495 to determine how the target browser will respond to various
3496 requests. Use with caution.
3504 <!-- ~~~~~ New section ~~~~~ -->
3505 <sect4 id="handle-as-image">
3506 <title><emphasis>+handle-as-image</emphasis></title>
3511 <!-- Boolean, Parameterized, Multi-value -->
3513 <para>Boolean.</para>
3518 <term>Typical uses:</term>
3521 To define what <application>Privoxy</application> should treat
3522 automatically as an image, and is an important ingredient of how
3529 <term>Possible values:</term>
3538 <term>Example usage:</term>
3541 <emphasis>{+handle-as-image}</emphasis>
3542 <emphasis>/.*\.(gif|jpg|jpeg|png|bmp|ico)</emphasis>
3551 This only has meaning if the URL (or pattern) also is
3552 <quote>+block</quote>ed, in which case a <quote>blocked</quote> image can
3553 be sent rather than a HTML page. (See
3554 <ulink url="configuration.html#SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></ulink>
3555 below for control over what will actually be displayed by the browser.)
3558 There is little reason to change the default definition for this.
3567 <!-- ~~~~~ New section ~~~~~ -->
3568 <sect4 id="set-image-blocker">
3569 <title><emphasis>+set-image-blocker</emphasis></title>
3574 <!-- Boolean, Parameterized, Multi-value -->
3576 <para>Parameterized.</para>
3581 <term>Typical uses:</term>
3584 Decide what to do with URLs that end up tagged with <emphasis>both</emphasis>
3585 <ulink url="configuration.html#BLOCK"><quote>+block</quote></ulink>
3587 url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>,
3588 e.g an advertisement.
3594 <term>Possible values:</term>
3597 There are four available options: <quote>-set-image-blocker</quote> will send a HTML
3598 <quote>blocked</quote> page, usually resulting in a <quote>broken
3600 <quote>+set-image-blocker{<emphasis>blank</emphasis>}</quote> will send a
3601 1x1 transparent GIF image.
3602 <quote>+set-image-blocker{<emphasis>pattern</emphasis>}</quote> will send a
3603 checkerboard type pattern (the default). And finally,
3604 <quote>+set-image-blocker{<emphasis>http://xyz.com</emphasis>}</quote> will
3605 send a HTTP temporary redirect to the specified image. This has the
3606 advantage of the icon being being cached by the browser, which will speed
3613 <term>Example usage:</term>
3616 <emphasis>{+set-image-blocker{blank}}</emphasis>
3617 <emphasis>.example.com</emphasis>
3626 If you want <emphasis>invisible</emphasis> ads, they need to meet
3627 criteria as matching both <emphasis>images</emphasis> and <emphasis>blocked</emphasis>
3628 actions. And then, <quote>image-blocker</quote> should be set to
3629 <quote>blank</quote> for invisibility. Note you cannot treat HTML pages as
3630 images in most cases. For instance, frames require an HTML page to
3631 display. So a frame that is an ad, typically cannot be treated as an image.
3632 Forcing an <quote>image</quote> in this situation just will not work
3641 <!-- ~~~~~ New section ~~~~~ -->
3642 <sect4 id="limit-connect">
3643 <title><emphasis>+limit-connect</emphasis></title>
3648 <!-- Boolean, Parameterized, Multi-value -->
3650 <para>Parameterized.</para>
3655 <term>Typical uses:</term>
3658 By default, <application>Privoxy</application> only allows HTTP CONNECT
3659 requests to port 443 (the standard, secure HTTPS port). Use
3660 <quote>+limit-connect</quote> to disable this altogether, or to allow
3667 <term>Possible values:</term>
3670 Any valid port number, or port number range.
3676 <term>Example usages:</term>
3678 <!-- I had trouble getting the spacing to look right in my browser -->
3679 <!-- I probably have the wrong font setup, bollocks. -->
3680 <!-- Apparently the emphasis tag uses a proportional font no matter what -->
3682 <emphasis>+limit-connect{443}</emphasis> # This is the default and need not be specified.
3683 <emphasis>+limit-connect{80,443}</emphasis> # Ports 80 and 443 are OK.
3684 <emphasis>+limit-connect{-3, 7, 20-100, 500-}</emphasis> # Port less than 3, 7, 20 to 100 and above 500 are OK.
3693 The CONNECT methods exists in HTTP to allow access to secure websites
3694 (https:// URLs) through proxies. It works very simply: the proxy connects
3695 to the server on the specified port, and then short-circuits its
3696 connections to the client <emphasis>and</emphasis> to the remote proxy.
3697 This can be a big security hole, since CONNECT-enabled proxies can be
3698 abused as TCP relays very easily.
3701 If you want to allow CONNECT for more ports than this, or want to forbid
3702 CONNECT altogether, you can specify a comma separated list of ports and
3703 port ranges (the latter using dashes, with the minimum defaulting to 0 and
3707 If you don't know what any of this means, there probably is no reason to
3716 <!-- ~~~~~ New section ~~~~~ -->
3717 <sect4 id="prevent-compression">
3718 <title><emphasis>+prevent-compression</emphasis></title>
3723 <!-- Boolean, Parameterized, Multi-value -->
3725 <para>Boolean.</para>
3730 <term>Typical uses:</term>
3733 Prevent the specified websites from compressing HTTP data.
3739 <term>Possible values:</term>
3748 <term>Example usage:</term>
3751 <emphasis>{+prevent-compression}</emphasis>
3752 <emphasis>.example.com</emphasis>
3761 Some websites do this, which can be a problem for
3762 <application>Privoxy</application>, since
3763 <ulink url="configuration.html#FILTER"><quote>+filter</quote></ulink>,
3764 <ulink url="configuration.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink>
3766 url="configuration.html#GIF-DEANIMATE"><quote>+gif-deanimate</quote></ulink>
3767 will not work on compressed data. This will slow down connections to those
3768 websites, though. Default typically is to turn
3769 <quote>prevent-compression</quote> on.
3777 <!-- ~~~~~ New section ~~~~~ -->
3778 <sect4 id="session-cookies-only">
3779 <title><emphasis>+session-cookies-only</emphasis></title>
3784 <!-- Boolean, Parameterized, Multi-value -->
3786 <para>Boolean.</para>
3791 <term>Typical uses:</term>
3794 Allow cookies for the current browser session <emphasis>only</emphasis>.
3800 <term>Possible values:</term>
3809 <term>Example usage (disabling):</term>
3812 <emphasis>{-session-cookies-only}</emphasis>
3813 <emphasis>.example.com</emphasis>
3822 If websites set cookies, <quote>+session-cookies-only</quote> will make sure
3823 they are erased when you exit and restart your web browser. This makes
3824 profiling cookies useless, but won't break sites which require cookies so
3825 that you can log in for transactions. This is generally turned on for all
3826 sites, and is the recommended setting.
3829 <quote>+prevent-*-cookies</quote> actions should be turned off as well (see
3830 below), for <quote>+session-cookies-only</quote> to work. Or, else no cookies
3831 will get through at all. For, <quote>persistent</quote> cookies that survive
3832 across browser sessions, see below as well.
3841 <!-- ~~~~~ New section ~~~~~ -->
3842 <sect4 id="prevent-reading-cookies">
3843 <title><emphasis>+prevent-reading-cookies</emphasis></title>
3848 <!-- Boolean, Parameterized, Multi-value -->
3850 <para>Boolean.</para>
3855 <term>Typical uses:</term>
3858 Explicitly prevent the web server from reading any cookies on your
3865 <term>Possible values:</term>
3874 <term>Example usage:</term>
3877 <emphasis>{+prevent-reading-cookies}</emphasis>
3878 <emphasis>.example.com</emphasis>
3887 Often used in conjunction with <quote>+prevent-setting-cookies</quote> to
3888 disable cookies completely. Note that
3889 <ulink url="configuration.html#SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></ulink>
3890 requires these to both be disabled (or else it never gets any cookies to cache).
3893 For <quote>persistent</quote> cookies to work (i.e. they survive across browser
3894 sessions and reboots), all three cookie settings should be <quote>off</quote>
3895 for the specified sites.
3904 <!-- ~~~~~ New section ~~~~~ -->
3905 <sect4 id="prevent-setting-cookies">
3906 <title><emphasis>+prevent-setting-cookies</emphasis></title>
3911 <!-- Boolean, Parameterized, Multi-value -->
3913 <para>Boolean.</para>
3918 <term>Typical uses:</term>
3921 Explicitly block the web server from storing cookies on your
3928 <term>Possible values:</term>
3937 <term>Example usage:</term>
3940 <emphasis>{+prevent-setting-cookies}</emphasis>
3941 <emphasis>.example.com</emphasis>
3950 Often used in conjunction with <quote>+prevent-reading-cookies</quote> to
3951 disable cookies completely (see above).
3960 <!-- ~~~~~ Nvarlistentryew section ~~~~~ -->
3961 <sect4 id="kill-popup">
3962 <title><emphasis>+kill-popups<anchor id="kill-popups"></emphasis></title>
3966 <!-- Boolean, Parameterized, Multi-value -->
3968 <para>Boolean.</para>
3973 <term>Typical uses:</term>
3976 Stop those annoying JavaScript pop-up windows!
3982 <term>Possible values:</term>
3991 <term>Example usage:</term>
3994 <emphasis>{+kill-popups}</emphasis>
3995 <emphasis>.example.com</emphasis>
4004 <quote>+kill-popups</quote> uses a built in filter to disable pop-ups
4005 that use the <literal>window.open()</literal> function, etc. This is
4006 one of the first actions processed by <application>Privoxy</application>
4007 as it contacts the remote web server. This action is not always 100% reliable,
4008 and is supplemented by <quote>+filter{<emphasis>popups</emphasis>}</quote>.
4012 An alternate spelling is <quote>+kill-popup</quote>, which is
4023 <!-- ~~~~~ New section ~~~~~ -->
4024 <sect4 id="send-vanilla-wafer">
4025 <title><emphasis>+send-vanilla-wafer</emphasis></title>
4030 <!-- Boolean, Parameterized, Multi-value -->
4032 <para>Boolean.</para>
4037 <term>Typical uses:</term>
4040 Sends a cookie for every site stating that you do not accept any copyright
4041 on cookies sent to you, and asking them not to track you.
4047 <term>Possible values:</term>
4056 <term>Example usage:</term>
4059 <emphasis>{+send-vanilla-wafer}</emphasis>
4060 <emphasis>.example.com</emphasis>
4069 This action only applies if you are using a <filename>jarfile</filename>
4070 for saving cookies. Of course, this is a (relatively) unique header and
4071 could conceivably be used to track you.
4080 <!-- ~~~~~ New section ~~~~~ -->
4081 <sect4 id="send-wafer">
4082 <title><emphasis>+send-wafer</emphasis></title>
4087 <!-- Boolean, Parameterized, Multi-value -->
4089 <para>Multi-value.</para>
4094 <term>Typical uses:</term>
4097 This allows you to send an arbitrary, user definable cookie.
4103 <term>Possible values:</term>
4106 User specified cookie name and corresponding value.
4112 <term>Example usage:</term>
4115 <emphasis>{+send-wafer{name=value}}</emphasis>
4116 <emphasis>.example.com</emphasis>
4125 This can be specified multiple times in order to add as many cookies as you
4135 <!-- ~~~~~ New section ~~~~~ -->
4136 <sect4 id="act-examples" renderas="sect3">
4137 <title>Actions Examples</title>
4139 Note that the meaning of any of the above examples is reversed by preceding
4140 the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also,
4141 that some actions are turned on in the default section of the actions file,
4142 and require little to no additional configuration. These are just <quote>on</quote>.
4143 But, other actions that are turned on the default section <emphasis>do
4144 typically require</emphasis> exceptions to be listed in the lower sections of
4145 actions file. E.g. by default no URLs are <quote>blocked</quote> (i.e. in
4146 the default definitions of <filename>default.action</filename>). We need
4147 exceptions to this in order to enable ad blocking.
4155 Turn off cookies by default, then allow a few through for specified sites
4156 (showing an excerpt from the <quote>default</quote> section of an actions
4165 # Allow cookies to and from the server, but
4166 # for this browser session ONLY
4168 # other actions normally listed here...
4169 -prevent-setting-cookies \
4170 -prevent-reading-cookies \
4171 +session-cookies-only \
4175 # Exceptions to the above, sites that benefit from persistent cookies
4176 # that are saved from one browser session to the next.
4177 { -session-cookies-only }
4190 Now turn off <quote>fast redirects</quote>, and then we allow two exceptions:
4197 # Turn them off (excerpt only)!
4199 # other actions normally listed here...
4204 # Reverse it for these two sites, which don't work right without it.
4206 www.ukc.ac.uk/cgi-bin/wac\.cgi\?
4214 Turn on page filtering according to rules in the defined sections
4215 of <filename>default.filter</filename>, and make one exception for
4223 # Run everything through the filter file, using only certain
4224 # specified sections:
4226 # other actions normally listed here...
4227 +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}\
4228 +filter{webbugs} +filter{nimda} +filter{banners-by-size}
4232 # Then disable filtering of code from all sourceforge domains!
4241 Now some URLs that we want <quote>blocked</quote> (normally generates
4242 the <quote>blocked</quote> banner). Typically, the <quote>block</quote>
4243 action is off by default in the upper section of an actions file, then enabled
4244 against certain URLs and patterns in the lower part of the file. Many of these use <link
4245 linkend="regex">regular expressions</link> that will expand to match multiple
4258 /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?)
4259 /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/
4261 /.*/(ng)?adclient\.cgi
4262 /.*/(plain|live|rotate)[-_.]?ads?/
4271 Note that many of these actions have the potential to cause a page to
4272 misbehave, possibly even not to display at all. There are many ways
4273 a site designer may choose to design his site, and what HTTP header
4274 content, and other criteria, he may depend on. There is no way to have hard
4275 and fast rules for all sites. See the <link
4276 linkend="ACTIONSANAT">Appendix</link> for a brief example on troubleshooting
4283 <!-- ~ End section ~ -->
4286 <!-- ~~~~~ New section ~~~~~ -->
4287 <sect3 id="aliases">
4288 <title>Aliases</title>
4290 Custom <quote>actions</quote>, known to <application>Privoxy</application>
4291 as <quote>aliases</quote>, can be defined by combining other <quote>actions</quote>.
4292 These can in turn be invoked just like the built-in <quote>actions</quote>.
4293 Currently, an alias can contain any character except space, tab, <quote>=</quote>,
4294 <quote>{</quote> or <quote>}</quote>. But please use only <quote>a</quote>-
4295 <quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
4296 <quote>-</quote>. Alias names are not case sensitive, and
4297 <emphasis>must be defined before other actions</emphasis> in the
4298 actions file! And there can only be one set of <quote>aliases</quote>
4299 defined per file. Each actions file may have its own aliases, but they are
4300 only visible within that file.
4304 Now let's define a few aliases:
4311 # Useful custom aliases we can use later. These must come first!
4313 +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies
4314 -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies
4315 fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups
4316 shop = -prevent-cookies -filter -fast-redirects
4317 +imageblock = +block +handle-as-image
4319 # Aliases defined from other aliases, for people who don't like to type
4321 c0 = +prevent-cookies
4322 c1 = -prevent-cookies
4323 #... etc. Customize to your heart's content.
4330 Some examples using our <quote>shop</quote> and <quote>fragile</quote>
4331 aliases from above. These would appear in the lower sections of an
4332 actions file as exceptions to the default actions (as defined in the
4340 # These sites are very complex and require
4341 # minimal interference.
4343 .office.microsoft.com
4344 .windowsupdate.microsoft.com
4347 # Shopping sites - but we still want to block ads.
4350 .worldpay.com # for quietpc.com
4353 # These shops require pop-ups also
4363 The <quote>shop</quote> and <quote>fragile</quote> aliases are often used for
4364 <quote>problem</quote> sites that require most actions to be disabled
4365 in order to function properly.
4372 <!-- ~ End section ~ -->
4375 <!-- ~~~~~ New section ~~~~~ -->
4376 <sect2 id="filter-file">
4377 <title>The Filter File</title>
4379 Any web page can be dynamically modified with the filter file. This
4380 modification can be removal, or re-writing, of any web page content,
4381 including tags and non-visible content. The default filter file is
4382 <filename>default.filter</filename>, located in the config directory.
4386 This is potentially a very powerful feature, and requires knowledge of both
4387 <quote>regular expression</quote> and HTML in order create custom
4388 filters. But, there are a number of useful filters included with
4389 <application>Privoxy</application> for many common situations.
4393 The included example file is divided into sections. Each section begins
4394 with the <literal>FILTER</literal> keyword, followed by the identifier
4395 for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
4396 a similar type of filtering, such as <quote>html-annoyances</quote>.
4400 This file uses regular expressions to alter or remove any string in the
4401 target page. The expressions can only operate on one line at a time. Some
4402 examples from the included default <filename>default.filter</filename>:
4406 Stop web pages from displaying annoying messages in the status bar by
4407 deleting such references:
4414 FILTER: html-annoyances
4416 # New browser windows should be resizeable and have a location and status
4419 s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
4420 s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
4421 s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
4422 s/menubar="?(no|0)"?/menubar=1/ig
4424 # The <BLINK> tag was a crime!
4426 s*<blink>|</blink>**ig
4430 #s/framespacing="?(no|0)"?//ig
4431 #s/margin(height|width)=[0-9]*//gi
4438 Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
4439 <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
4448 s/microsoft(?!.com)/MicroSuck/ig
4452 s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
4459 Kill those pesky little web-bugs:
4466 # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
4469 s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
4477 <!-- ~ End section ~ -->
4481 <!-- ~~~~~ New section ~~~~~ -->
4484 <title>Templates</title>
4486 When <application>Privoxy</application> displays one of its internal
4487 pages, such as a 404 Not Found error page, it uses the appropriate template.
4488 On Linux, BSD, and Unix, these are located in
4489 <filename>/etc/privoxy/templates</filename> by default. These may be
4490 customized, if desired. <filename>cgi-style.css</filename> is
4491 used to control the HTML attributes (fonts, etc).
4494 The default <quote>Blocked</quote> banner page with the bright red top
4495 banner, is called just <quote><filename>blocked</filename></quote>. This
4496 may be customized or replaced with something else if desired.
4503 <!-- ~ End section ~ -->
4507 <!-- ~~~~~ New section ~~~~~ -->
4509 <sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
4512 <!-- Include contacting.sgml boilerplate: -->
4514 <!-- end boilerplate -->
4517 <!-- ~~~~~ New section ~~~~~ -->
4518 <sect2 id="submitactions">
4519 <title>Submitting Ads and <quote>Action</quote> Problems</title>
4521 Ads and banners that are not stopped by <application>Privoxy</application>
4522 can be submitted to the developers by accessing a special page and filling
4523 out the brief, required form. Conversely, you can also report pages, images,
4524 etc. that <application>Privoxy</application> is blocking, but should not.
4525 The form itself does require Internet access.
4528 To do this, point your browser to <application>Privoxy</application>
4529 at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4530 (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
4531 <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>,
4532 near the bottom of the page. Paste in the URL that is the cause of the
4533 unwanted behavior, and follow the prompts. The developers will
4534 try to incorporate a fix for the problem you reported into future versions.
4538 New, improved <filename>default.action</filename> files will occasionally be made
4539 available based on your feedback. These will be announced on the <ulink
4540 url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink>
4548 <!-- ~~~~~ New section ~~~~~ -->
4549 <sect1 id="copyright"><title>Copyright and History</title>
4551 <sect2><title>Copyright</title>
4552 <!-- Include copyright.sgml: -->
4554 <!-- end copyright -->
4557 <!-- ~ End section ~ -->
4560 <!-- ~~~~~ New section ~~~~~ -->
4562 <sect2 id="history"><title>History</title>
4563 <!-- Include history.sgml: -->
4565 <!-- end history -->
4569 <!-- ~~~~~ New section ~~~~~ -->
4570 <sect1 id="seealso"><title>See Also</title>
4571 <!-- Include seealso.sgml: -->
4573 <!-- end seealso -->
4578 <!-- ~~~~~ New section ~~~~~ -->
4579 <sect1 id="appendix"><title>Appendix</title>
4582 <!-- ~~~~~ New section ~~~~~ -->
4584 <title>Regular Expressions</title>
4586 <application>Privoxy</application> can use <quote>regular expressions</quote>
4587 in various config files. Assuming support for <quote>pcre</quote> (Perl
4588 Compatible Regular Expressions) is compiled in, which is the default. Such
4589 configuration directives do not require regular expressions, but they can be
4590 used to increase flexibility by matching a pattern with wild-cards against
4595 If you are reading this, you probably don't understand what <quote>regular
4596 expressions</quote> are, or what they can do. So this will be a very brief
4597 introduction only. A full explanation would require a book ;-)
4601 <quote>Regular expressions</quote> is a way of matching one character
4602 expression against another to see if it matches or not. One of the
4603 <quote>expressions</quote> is a literal string of readable characters
4604 (letter, numbers, etc), and the other is a complex string of literal
4605 characters combined with wild-cards, and other special characters, called
4606 meta-characters. The <quote>meta-characters</quote> have special meanings and
4607 are used to build the complex pattern to be matched against. Perl Compatible
4608 Regular Expressions is an enhanced form of the regular expression language
4609 with backward compatibility.
4613 To make a simple analogy, we do something similar when we use wild-card
4614 characters when listing files with the <command>dir</command> command in DOS.
4615 <literal>*.*</literal> matches all filenames. The <quote>special</quote>
4616 character here is the asterisk which matches any and all characters. We can be
4617 more specific and use <literal>?</literal> to match just individual
4618 characters. So <quote>dir file?.text</quote> would match
4619 <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
4620 matching, using a similar technique to <quote>regular expressions</quote>!
4624 Regular expressions do essentially the same thing, but are much, much more
4625 powerful. There are many more <quote>special characters</quote> and ways of
4626 building complex patterns however. Let's look at a few of the common ones,
4627 and then some examples:
4632 <emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
4633 <quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
4635 </simplelist></para>
4639 <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
4642 </simplelist></para>
4646 <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
4649 </simplelist></para>
4653 <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
4656 </simplelist></para>
4660 <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
4661 the following character should be taken literally. This is used where one of the
4662 special characters (e.g. <quote>.</quote>) needs to be taken literally and
4663 not as a special meta-character. Example: <quote>example\.com</quote>, makes
4664 sure the period is recognized only as a period (and not expanded to its
4665 meta-character meaning of any single character).
4667 </simplelist></para>
4671 <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
4672 any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
4673 matches any numeric digit (zero through nine). As an example, we can combine
4674 this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
4676 </simplelist></para>
4680 <emphasis>()</emphasis> - parentheses are used to group a sub-expression,
4681 or multiple sub-expressions.
4683 </simplelist></para>
4687 <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
4688 <quote>or</quote> conditional statement. A match is successful if the
4689 sub-expression on either side of <quote>|</quote> matches. As an example:
4690 <quote>/(this|that) example/</quote> uses grouping and the bar character
4691 and would match either <quote>this example</quote> or <quote>that
4692 example</quote>, and nothing else.
4694 </simplelist></para>
4698 <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
4699 <quote>string1</quote> is replaced by <quote>string2</quote> in this
4700 example. There must of course be a match on <quote>string1</quote> first.
4702 </simplelist></para>
4705 These are just some of the ones you are likely to use when matching URLs with
4706 <application>Privoxy</application>, and is a long way from a definitive
4707 list. This is enough to get us started with a few simple examples which may
4708 be more illuminating:
4712 <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
4713 that uses the common combination of <quote>.</quote> and <quote>*</quote> to
4714 denote any character, zero or more times. In other words, any string at all.
4715 So we start with a literal forward slash, then our regular expression pattern
4716 (<quote>.*</quote>) another literal forward slash, the string
4717 <quote>banners</quote>, another forward slash, and lastly another
4718 <quote>.*</quote>. We are building
4719 a directory path here. This will match any file with the path that has a
4720 directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
4721 any characters, and this could conceivably be more forward slashes, so it
4722 might expand into a much longer looking path. For example, this could match:
4723 <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
4724 <quote>/banners/annoying.html</quote>, or almost an infinite number of other
4725 possible combinations, just so it has <quote>banners</quote> in the path
4730 A now something a little more complex:
4734 <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
4735 We have several literal forward slashes again (<quote>/</quote>), so we are
4736 building another expression that is a file path statement. We have another
4737 <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
4738 it matches our expression. The only true literal that <emphasis>must
4739 match</emphasis> our pattern is <application>adv</application>, together with
4740 the forward slashes. What comes after the <quote>adv</quote> string is the
4745 Remember the <quote>?</quote> means the preceding expression (either a
4746 literal character or anything grouped with <quote>(...)</quote> in this case)
4747 can exist or not, since this means either zero or one match. So
4748 <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
4749 individual sub-expressions: <quote>(er)</quote>,
4750 <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
4751 means <quote>or</quote>. We have two of those. For instance,
4752 <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
4753 <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
4754 attempt at matching as many variations of <quote>advertisement</quote>, and
4755 similar, as possible. So this would expand to match just <quote>adv</quote>,
4756 or <quote>advert</quote>, or <quote>adverts</quote>, or
4757 <quote>advertising</quote>, or <quote>advertisement</quote>, or
4758 <quote>advertisements</quote>. You get the idea. But it would not match
4759 <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
4760 changing our regular expression to:
4761 <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
4766 <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
4767 another path statement with forward slashes. Anything in the square brackets
4768 <quote>[]</quote> can be matched. This is using <quote>0-9</quote> as a
4769 shorthand expression to mean any digit one through nine. It is the same as
4770 saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
4771 means one or more of the preceding expression must be included. The preceding
4772 expression here is what is in the square brackets -- in this case, any digit
4773 one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
4774 This includes a <quote>|</quote>, so this needs to match the expression on
4775 either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
4776 side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
4777 since the <quote>?</quote> means the letter <quote>e</quote> is optional and
4778 can be matched once or not at all. So we are building an expression here to
4779 match image GIF or JPEG type image file. It must include the literal
4780 string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
4781 (which is now a literal, and not a special character, since it is escaped
4782 with <quote>\</quote>), and lastly either <quote>gif</quote>, or
4783 <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
4784 include: <quote>//advert1.jpg</quote>,
4785 <quote>/nasty/ads/advert1234.gif</quote>,
4786 <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
4787 <quote>advert1.gif</quote> (no leading slash), or
4788 <quote>/adverts232.jpg</quote> (the expression does not include an
4789 <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
4790 in the expression anywhere).
4794 <emphasis><literal>s/microsoft(?!.com)/MicroSuck/i</literal></emphasis> - This is
4795 a substitution. <quote>MicroSuck</quote> will replace any occurrence of
4796 <quote>microsoft</quote>. The <quote>i</quote> at the end of the expression
4797 means ignore case. The <quote>(?!.com)</quote> means
4798 the match should fail if <quote>microsoft</quote> is followed by
4799 <quote>.com</quote>. In other words, this acts like a <quote>NOT</quote>
4800 modifier. In case this is a hyperlink, we don't want to break it ;-).
4804 We are barely scratching the surface of regular expressions here so that you
4805 can understand the default <application>Privoxy</application>
4806 configuration files, and maybe use this knowledge to customize your own
4807 installation. There is much, much more that can be done with regular
4808 expressions. Now that you know enough to get started, you can learn more on
4813 More reading on Perl Compatible Regular expressions:
4814 <ulink url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>
4819 <!-- ~ End section ~ -->
4822 <!-- ~~~~~ New section ~~~~~ -->
4824 <title><application>Privoxy</application>'s Internal Pages</title>
4827 Since <application>Privoxy</application> proxies each requested
4828 web page, it is easy for <application>Privoxy</application> to
4829 trap certain special URLs. In this way, we can talk directly to
4830 <application>Privoxy</application>, and see how it is
4831 configured, see how our rules are being applied, change these
4832 rules and other configuration options, and even turn
4833 <application>Privoxy's</application> filtering off, all with
4839 The URLs listed below are the special ones that allow direct access
4840 to <application>Privoxy</application>. Of course,
4841 <application>Privoxy</application> must be running to access these. If
4842 not, you will get a friendly error message. Internet access is not
4855 <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
4859 Alternately, this may be reached at <ulink
4860 url="http://p.p/">http://p.p/</ulink>, but this
4861 variation may not work as reliably as the above in some configurations.
4867 Show information about the current configuration:
4871 <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
4878 Show the source code version numbers:
4882 <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
4889 Show the client's request headers:
4893 <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
4900 Show which actions apply to a URL and why:
4904 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
4911 Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
4912 to run, but only as a pass-through proxy, with no actions taking place:
4916 <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
4920 Short cuts. Turn off, then on:
4924 <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
4929 <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
4936 Edit the actions list file:
4940 <ulink url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>
4949 These may be bookmarked for quick reference. See next.
4953 <sect3 id="bookmarklets">
4954 <title>Bookmarklets</title>
4956 Below are some <quote>bookmarklets</quote> to allow you to easily access a
4957 <quote>mini</quote> version of some of <application>Privoxy's</application>
4958 special pages. They are designed for MS Internet Explorer, but should work
4959 equally well in Netscape, Mozilla, and other browsers which support
4960 JavaScript. They are designed to run directly from your bookmarks - not by
4961 clicking the links below (although that should work for testing).
4964 To save them, right-click the link and choose <quote>Add to Favorites</quote>
4965 (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
4966 the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
4967 Bookmarklet directly from your favorites/bookmarks. For even faster access,
4968 you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
4969 Toolbar</quote> (Netscape), and run them with a single click.
4977 <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>
4983 <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>
4989 <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)
4995 <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>
5001 <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>
5011 Credit: The site which gave me the general idea for these bookmarklets is
5012 <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
5013 have more information about bookmarklets.
5022 <!-- ~~~~~ New section ~~~~~ -->
5024 <title>Chain of Events</title>
5026 Let's take a quick look at the basic sequence of events when a web page is
5027 requested by your browser and <application>Privoxy</application> is on duty:
5034 First, your web browser requests a web page. The browser knows to send
5035 the request to <application>Privoxy</application>, who in turn,
5036 will relay the request to the remote web server after passing a few quick
5042 <application>Privoxy</application> traps any request for its own internal CGI
5043 pages (e.g http://p.p/) and sends these back to the browser.
5048 Next, <application>Privoxy</application> checks to see if the URL
5050 url="configuration.html#BLOCK"><quote>+block</quote></ulink> patterns. If
5051 so, the remote web server is not contacted, and the URL is then further
5052 checked against <quote>+handle-as-image</quote>. If both match, then the
5053 setting of <ulink url="configuration.html#SET-IMAGE-BLOCKER">
5054 <quote>+set-image-blocker</quote></ulink> is used to display whichever
5055 option is appropriate. If <ulink
5056 url="configuration.html#HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></ulink>
5057 does not match, then the <quote>BLOCKED</quote> banner page is displayed.
5062 Untrusted URLs are blocked. If URLs are being added to the
5063 <filename>trust</filename> file, then that is done.
5069 url="configuration.html#FAST-REDIRECTS"><quote>+fast-redirects</quote></ulink>
5070 is processed, stripping unwanted parts of the requested web page URL.
5075 At this point, <application>Privoxy</application> now relays the URL to the
5076 web server, requesting the page (assuming nothing up to this point has
5077 prevented getting us from this far).
5082 The first few hundred bytes are read from the web server and
5083 <ulink url="configuration.html#KILL-POPUPS"><quote>+kill-popups</quote></ulink>
5084 is processed, if enabled.
5089 If <ulink url="configuration.html#FILTER"><quote>+filter</quote></ulink>
5090 applies, the rest of the page is read into memory and then the filter rules
5091 (from <filename>default.filter</filename>) are processed. Filters are
5092 applied in the order they are specified in the
5093 <filename>default.filter</filename> file. The entire page, which is now
5094 filtered, is then sent by <application>Privoxy</application> back to your
5100 As the browser receives the now filtered page content, it will read and request any
5101 embedded URLs on the page, e.g. ad images. As the browser requests these
5102 secondary URLs from whatever server they may be on,
5103 <application>Privoxy</application> handles these same as above, and the process
5104 is repeated all over again for each such URL. Note that a fancy web page may
5105 have many, many such embedded URLs for graphics, frames, etc.
5115 <!-- ~~~~~ New section ~~~~~ -->
5116 <sect2 id="actionsanat">
5117 <title>Anatomy of an Action</title>
5120 The way <application>Privoxy</application> applies <quote>actions</quote>
5121 and <quote>filters</quote> to any given URL can be complex, and not always so
5122 easy to understand what is happening. And sometimes we need to be able to
5123 <emphasis>see</emphasis> just what <application>Privoxy</application> is
5124 doing. Especially, if something <application>Privoxy</application> is doing
5125 is causing us a problem inadvertently. It can be a little daunting to look at
5126 the actions and filters files themselves, since they tend to be filled with
5127 <quote>regular expressions</quote> whose consequences are not always
5132 One quick test to see if <application>Privoxy</application> is causing a problem
5133 or not, is to disable it temporarily. This should be the first troubleshooting
5134 step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
5135 and easy way to do this (be sure to flush caches afterward!).
5139 <application>Privoxy</application> also provides the
5140 <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
5141 page that can show us very specifically how <application>actions</application>
5142 are being applied to any given URL. This is a big help for troubleshooting.
5146 First, enter one URL (or partial URL) at the prompt, and then
5147 <application>Privoxy</application> will tell us
5148 how the current configuration will handle it. This will not
5149 help with filtering effects (i.e. the <quote>+filter</quote> action) from the
5150 <filename>default.filter</filename> file since this is handled very differently
5151 and not so easy to trap! It also will not tell you about any other URLs that
5152 may be embedded within the URL you are testing (i.e. a web page). For
5153 instance, images such as ads are expressed as URLs within the raw page source
5154 of HTML pages. So you will only get info for the actual URL that is pasted
5155 into the prompt area -- not any sub-URLs. If you want to know about embedded
5156 URLs like ads, you will have to dig those out of the HTML source. Use your
5157 browser's <quote>View Page Source</quote> option for this. Or right click on
5158 the ad, and grab the URL.
5162 Let's try an example, <ulink url="http://google.com">google.com</ulink>,
5163 and look at it one section at a time:
5168 Matches for http://google.com:
5170 --- File standard ---
5171 (no matches in this file)
5173 --- File default ---
5175 { -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects
5176 -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
5177 +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
5178 +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
5179 +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
5180 -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
5181 +prevent-compression +session-cookies-only +prevent-reading-cookies
5182 +prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer }
5185 { -prevent-setting-cookies -prevent-reading-cookies }
5192 (no matches in this file)
5198 This tells us how we have defined our <quote>actions</quote>, and which ones
5199 match for our example, <quote>google.com</quote>. The first listing is
5200 for the <filename>standard.action</filename>. No hits at all here on
5201 <quote>standard</quote>. Then next is <quote>default</quote>, or our
5202 <filename>default.action</filename> file. The large, multi-line listing, is
5203 how the actions are set to match for all URLs, i.e. our default settings. If
5204 you look at your <quote>actions</quote> file, this would be the section just
5205 below the <quote>aliases</quote> section near the top. This will apply to all
5206 URLs as signified by the single forward slash at the end of the listing --
5212 But we can define additional actions that would be exceptions to these general
5213 rules, and then list specific URLs (or patterns) that these exceptions would
5214 apply to. Last match wins. Just below this then are two explicit matches for
5215 <quote>.google.com</quote>. The first is negating our various cookie blocking
5216 actions (i.e. we will allow cookies here). The second is allowing
5217 <quote>fast-redirects</quote> to take place. Note that there is a leading dot
5218 here -- <quote>.google.com</quote>. This will match any hosts and sub-domains,
5219 in the google.com domain also, such as <quote>www.google.com</quote>. So,
5220 apparently, we have these two actions defined somewhere in the lower part of our
5221 actions file, and <quote>google.com</quote> is referenced somewhere in these
5226 Then, for our <filename>user.action</filename> file, we again have no hits, as
5227 signified by <quote>File user</quote>.
5231 And finally we pull it altogether in the bottom section and summarize how
5232 <application>Privoxy</application> is applying all its <quote>actions</quote>
5233 to <quote>google.com</quote>:
5241 -add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects
5242 -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
5243 +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
5244 +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size}
5245 +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge}
5246 -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect
5247 +prevent-compression +session-cookies-only -prevent-reading-cookies
5248 -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer
5254 Notice the only difference here to the previous listing, is to
5255 <quote>fast-redirects</quote> and the two cookie settings.
5259 Now another example, <quote>ad.doubleclick.net</quote>:
5265 { +block +handle-as-image }
5268 { +block +handle-as-image }
5271 { +block +handle-as-image }
5278 We'll just show the interesting part here, the explicit matches. It is
5279 matched three different times. Each as an <quote>+block +handle-as-image</quote>,
5280 which is the expanded form of one of our aliases that had been defined as:
5281 <quote>+imageblock</quote>. (<quote>Aliases</quote> are defined in the
5282 first section of the actions file and typically used to combine more
5287 Any one of these would have done the trick and blocked this as an unwanted
5288 image. This is unnecessarily redundant since the last case effectively
5289 would also cover the first. No point in taking chances with these guys
5290 though ;-) Note that if you want an ad or obnoxious
5291 URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
5292 is done here -- as both a <quote>+block</quote> <emphasis>and</emphasis> an
5293 <quote>+handle-as-image</quote>. The custom alias <quote>+imageblock</quote> does this
5298 One last example. Let's try <quote>http://www.rhapsodyk.net/adsl/HOWTO/</quote>.
5299 This one is giving us problems. We are getting a blank page. Hmmm...
5305 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
5307 { -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects
5308 +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}
5309 +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal}
5310 +filter{fun} +hide-forwarded-for-headers +hide-from-header{block}
5311 +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank}
5312 +prevent-compression +session-cookies-only +prevent-setting-cookies
5313 +prevent-reading-cookies +kill-popups -send-vanilla-wafer -send-wafer }
5316 { +block +handle-as-image }
5323 Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote>! But
5324 we did not want this at all! Now we see why we get the blank page. We could
5325 now add a new action below this that explicitly does <emphasis>not</emphasis>
5326 block (-block) pages with <quote>adsl</quote>. There are various ways to
5327 handle such exceptions. Example:
5340 Now the page displays ;-) Be sure to flush your browser's caches when
5341 making such changes. Or, try using <literal>Shift+Reload</literal>.
5345 But now what about a situation where we get no explicit matches like
5359 That actually was very telling and pointed us quickly to where the problem
5360 was. If you don't get this kind of match, then it means one of the default
5361 rules in the first section is causing the problem. This would require some
5362 guesswork, and maybe a little trial and error to isolate the offending rule.
5363 One likely cause would be one of the <quote>{+filter}</quote> actions. Try
5364 adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
5372 .worldpay.com # for quietpc.com
5381 <quote>{shop}</quote> is an <quote>alias</quote> that expands to
5382 <quote>{ -filter -prevent-setting-cookies -prevent-reading-cookies }</quote>.
5383 Or you could do your own exception to negate filtering:
5397 This would probably be most appropriately put in <filename>user.action</filename>,
5398 for personal user exceptions.
5402 <quote>{fragile}</quote> is an alias that disables most actions. This can be
5403 used as a last resort for problem sites. Remember to flush caches! If this
5404 still does not work, you will have to go through the remaining actions one by
5405 one to find which one(s) is causing the problem.
5414 This program is free software; you can redistribute it
5415 and/or modify it under the terms of the GNU General
5416 Public License as published by the Free Software
5417 Foundation; either version 2 of the License, or (at
5418 your option) any later version.
5420 This program is distributed in the hope that it will
5421 be useful, but WITHOUT ANY WARRANTY; without even the
5422 implied warranty of MERCHANTABILITY or FITNESS FOR A
5423 PARTICULAR PURPOSE. See the GNU General Public
5424 License for more details.
5426 The GNU General Public License should be included with
5427 this file. If not, you can view it at
5428 http://www.gnu.org/copyleft/gpl.html
5429 or write to the Free Software Foundation, Inc., 59
5430 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
5432 $Log: user-manual.sgml,v $
5433 Revision 1.91 2002/04/24 02:39:31 hal9
5434 Add 'Chain of Events' section.
5436 Revision 1.90 2002/04/23 21:41:25 hal9
5437 Linuxconf is deprecated on RH, substitute chkconfig.
5439 Revision 1.89 2002/04/23 21:05:28 oes
5440 Added hint for startup on Red Hat
5442 Revision 1.88 2002/04/23 05:37:54 hal9
5443 Add AmigaOS install stuff.
5445 Revision 1.87 2002/04/23 02:53:15 david__schmidt
5446 Updated OSX installation section
5447 Added a few English tweaks here an there
5449 Revision 1.86 2002/04/21 01:46:32 hal9
5450 Re-write actions section.
5452 Revision 1.85 2002/04/18 21:23:23 hal9
5453 Fix ugly typo (mine).
5455 Revision 1.84 2002/04/18 21:17:13 hal9
5456 Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
5458 Revision 1.83 2002/04/18 18:21:12 oes
5459 Added RPM install detail
5461 Revision 1.82 2002/04/18 12:04:50 oes
5464 Revision 1.81 2002/04/18 11:50:24 oes
5465 Extended Install section - needs fixing by packagers
5467 Revision 1.80 2002/04/18 10:45:19 oes
5468 Moved text to buildsource.sgml, renamed some filters, details
5470 Revision 1.79 2002/04/18 03:18:06 hal9
5471 Spellcheck, and minor touchups.
5473 Revision 1.78 2002/04/17 18:04:16 oes
5476 Revision 1.77 2002/04/17 13:51:23 oes
5477 Proofreading, part one
5479 Revision 1.76 2002/04/16 04:25:51 hal9
5480 -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
5481 -Note about proxy may need requests to re-read config files.
5483 Revision 1.75 2002/04/12 02:08:48 david__schmidt
5484 Remove OS/2 building info... it is already in the developer-manual
5486 Revision 1.74 2002/04/11 00:54:38 hal9
5487 Add small section on submitting actions.
5489 Revision 1.73 2002/04/10 18:45:15 swa
5492 Revision 1.72 2002/04/10 04:06:19 hal9
5493 Added actions feedback to Bookmarklets section
5495 Revision 1.71 2002/04/08 22:59:26 hal9
5496 Version update. Spell chkconfig correctly :)
5498 Revision 1.70 2002/04/08 20:53:56 swa
5501 Revision 1.69 2002/04/06 05:07:29 hal9
5502 -Add privoxy-man-page.sgml, for man page.
5503 -Add authors.sgml for AUTHORS (and p-authors.sgml)
5504 -Reworked various aspects of various docs.
5505 -Added additional comments to sub-docs.
5507 Revision 1.68 2002/04/04 18:46:47 swa
5508 consistent look. reuse of copyright, history et. al.
5510 Revision 1.67 2002/04/04 17:27:57 swa
5511 more single file to be included at multiple points. make maintaining easier
5513 Revision 1.66 2002/04/04 06:48:37 hal9
5514 Structural changes to allow for conditional inclusion/exclusion of content
5515 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
5516 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
5517 eventually be set by Makefile.
5518 More boilerplate text for use across multiple docs.
5520 Revision 1.65 2002/04/03 19:52:07 swa
5521 enhance squid section due to user suggestion
5523 Revision 1.64 2002/04/03 03:53:43 hal9
5524 A few minor bug fixes, and touch ups. Ready for review.
5526 Revision 1.63 2002/04/01 16:24:49 hal9
5527 Define entities to include boilerplate text. See doc/source/*.
5529 Revision 1.62 2002/03/30 04:15:53 hal9
5530 - Fix privoxy.org/config links.
5531 - Paste in Bookmarklets from Toggle page.
5532 - Move Quickstart nearer top, and minor rework.
5534 Revision 1.61 2002/03/29 01:31:08 hal9
5537 Revision 1.60 2002/03/27 01:57:34 hal9
5538 Added more to Anatomy section.
5540 Revision 1.59 2002/03/27 00:54:33 hal9
5541 Touch up intro for new name.
5543 Revision 1.58 2002/03/26 22:29:55 swa
5544 we have a new homepage!
5546 Revision 1.57 2002/03/24 20:33:30 hal9
5547 A few minor catch ups with name change.
5549 Revision 1.56 2002/03/24 16:17:06 swa
5550 configure needs to be generated.
5552 Revision 1.55 2002/03/24 16:08:08 swa
5553 we are too lazy to make a block-built
5554 privoxy logo. hence removed the option.
5556 Revision 1.54 2002/03/24 15:46:20 swa
5557 name change related issue.
5559 Revision 1.53 2002/03/24 11:51:00 swa
5560 name change. changed filenames.
5562 Revision 1.52 2002/03/24 11:01:06 swa
5565 Revision 1.51 2002/03/23 15:13:11 swa
5566 renamed every reference to the old name with foobar.
5567 fixed "application foobar application" tag, fixed
5568 "the foobar" with "foobar". left junkbustser in cvs
5569 comments and remarks to history untouched.
5571 Revision 1.50 2002/03/23 05:06:21 hal9
5574 Revision 1.49 2002/03/21 17:01:05 hal9
5575 New section in Appendix.
5577 Revision 1.48 2002/03/12 06:33:01 hal9
5578 Catching up to Andreas and re_filterfile changes.
5580 Revision 1.47 2002/03/11 13:13:27 swa
5581 correct feedback channels
5583 Revision 1.46 2002/03/10 00:51:08 hal9
5584 Added section on JB internal pages in Appendix.
5586 Revision 1.45 2002/03/09 17:43:53 swa
5589 Revision 1.44 2002/03/09 17:08:48 hal9
5590 New section on Jon's actions file editor, and move some stuff around.
5592 Revision 1.43 2002/03/08 00:47:32 hal9
5593 Added imageblock{pattern}.
5595 Revision 1.42 2002/03/07 18:16:55 swa
5598 Revision 1.41 2002/03/07 16:46:43 hal9
5599 Fix a few markup problems for jade.
5601 Revision 1.40 2002/03/07 16:28:39 swa
5602 provide correct feedback channels
5604 Revision 1.39 2002/03/06 16:19:28 hal9
5605 Note on perceived filtering slowdown per FR.
5607 Revision 1.38 2002/03/05 23:55:14 hal9
5608 Stupid I did it again. Double hyphen in comment breaks jade.
5610 Revision 1.37 2002/03/05 23:53:49 hal9
5611 jade barfs on '- -' embedded in comments. - -user option broke it.
5613 Revision 1.36 2002/03/05 22:53:28 hal9
5614 Add new - - user option.
5616 Revision 1.35 2002/03/05 00:17:27 hal9
5617 Added section on command line options.
5619 Revision 1.34 2002/03/04 19:32:07 oes
5620 Changed default port to 8118
5622 Revision 1.33 2002/03/03 19:46:13 hal9
5623 Emphasis on where/how to report bugs, etc
5625 Revision 1.32 2002/03/03 09:26:06 joergs
5626 AmigaOS changes, config is now loaded from PROGDIR: instead of
5627 AmiTCP:db/junkbuster/ if no configuration file is specified on the
5630 Revision 1.31 2002/03/02 22:45:52 david__schmidt
5633 Revision 1.30 2002/03/02 22:00:14 hal9
5634 Updated 'New Features' list. Ran through spell-checker.
5636 Revision 1.29 2002/03/02 20:34:07 david__schmidt
5637 Update OS/2 build section
5639 Revision 1.28 2002/02/24 14:34:24 jongfoster
5640 Formatting changes. Now changing the doctype to DocBook XML 4.1
5641 will work - no other changes are needed.
5643 Revision 1.27 2002/01/11 14:14:32 hal9
5644 Added a very short section on Templates
5646 Revision 1.26 2002/01/09 20:02:50 hal9
5647 Fix bug re: auto-detect config file changes.
5649 Revision 1.25 2002/01/09 18:20:30 hal9
5650 Touch ups for *.action files.
5652 Revision 1.24 2001/12/02 01:13:42 hal9
5655 Revision 1.23 2001/12/02 00:20:41 hal9
5656 Updates for recent changes.
5658 Revision 1.22 2001/11/05 23:57:51 hal9
5659 Minor update for startup now daemon mode.
5661 Revision 1.21 2001/10/31 21:11:03 hal9
5662 Correct 2 minor errors
5664 Revision 1.18 2001/10/24 18:45:26 hal9
5665 *** empty log message ***
5667 Revision 1.17 2001/10/24 17:10:55 hal9
5668 Catching up with Jon's recent work, and a few other things.
5670 Revision 1.16 2001/10/21 17:19:21 swa
5671 wrong url in documentation
5673 Revision 1.15 2001/10/14 23:46:24 hal9
5674 Various minor changes. Fleshed out SEE ALSO section.
5676 Revision 1.13 2001/10/10 17:28:33 hal9
5679 Revision 1.12 2001/09/28 02:57:04 hal9
5682 Revision 1.11 2001/09/28 02:25:20 hal9
5685 Revision 1.9 2001/09/27 23:50:29 hal9
5686 A few changes. A short section on regular expression in appendix.
5688 Revision 1.8 2001/09/25 00:34:59 hal9
5689 Some additions, and re-arranging.
5691 Revision 1.7 2001/09/24 14:31:36 hal9
5694 Revision 1.6 2001/09/24 14:10:32 hal9
5695 Including David's OS/2 installation instructions.
5697 Revision 1.2 2001/09/13 15:27:40 swa
5700 Revision 1.1 2001/09/12 15:36:41 swa
5701 source files for junkbuster documentation
5703 Revision 1.3 2001/09/10 17:43:59 swa
5704 first proposal of a structure.
5706 Revision 1.2 2001/06/13 14:28:31 swa
5707 docs should have an author.
5709 Revision 1.1 2001/06/13 14:20:37 swa
5710 first import of project's documentation for the webserver.
projects / privoxy.git / blob