X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=15ac7f60602025b5e1635b9bd62ac3f64662825a;hp=8f6ab5fbca0bc1b9a276b1b80423cda1aff96f0b;hb=ed70e742f22c7a2eff07f2509e74080190271796;hpb=dcb6d2261f6cc345036a0054be5904667754a2ab diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 8f6ab5fb..15ac7f60 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -1,4 +1,23 @@ - + + + + + + + + + + + + + + + + + + +]> -
Privoxy User Manual -$Id: user-manual.sgml,v 1.61 2002/03/29 01:31:08 hal9 Exp $ +$Id: user-manual.sgml,v 1.95 2002/04/26 17:23:29 swa Exp $ @@ -39,20 +57,32 @@ Hal Burgiss + - The user manual gives users information on how to install, configure and use - Privoxy. Privoxy is a - web proxy with advanced filtering capabilities for protecting privacy, - filtering web page content, managing cookies, controlling access, and - removing ads, banners, pop-ups and other obnoxious Internet - Junk. Privoxy has a very flexible configuration - and can be customized to suit individual needs and - tastes. Privoxy has application for both - stand-alone systems and multi-user networks. + + This is here to keep vim syntax file from breaking :/ + If I knew enough to fix it, I would. + PLEASE DO NOT REMOVE! HB: hal@foobox.net + +]]> + -You can find the latest version of the user manual at http://www.privoxy.org/user-manual/. - + The user manual gives users information on how to install, configure and use + Privoxy. + + + + &p-intro; + + + + You can find the latest version of the user manual at http://www.privoxy.org/user-manual/. + Please see the Contact section on how to + contact the developers. + @@ -61,172 +91,47 @@ You can find the latest version of the user manual at + + + + -Introduction - - Privoxy is a web proxy with advanced filtering - capabilities for protecting privacy, filtering web page content, managing - cookies, controlling access, and removing ads, banners, pop-ups and other - obnoxious Internet junk. Privoxy has a very - flexible configuration and can be customized to suit individual needs and - tastes. Privoxy has application for both - stand-alone systems and multi-user networks. - - - - Privoxy is based on the code of the - Internet Junkbuster. - Junkbuster was originally written by JunkBusters - Corporation, and was released as free open-source software under the GNU GPL. - Stefan Waldherr made many improvements, and started the SourceForge project - to continue development. - - - - Privoxy continues the - Junkbuster tradition, but adds many - refinements and enhancements. - - + +Introduction - This documentation is included with the current BETA version of - Privoxy and is mostly complete at this - point. The most up to date reference for the time being is still the comments - in the source files and in the individual configuration files. Development - of version 3.0 is currently nearing completion, and includes many significant - changes and enhancements over earlier versions. The target release date for - stable v3.0 is soon ;-) + This documentation is included with the current &p-status; version of + Privoxy, v.&p-version;soon ;-)]]>. + + - Since this is a BETA version, not all new features are well tested. This + Since this is a &p-status; version, not all new features are well tested. This documentation may be slightly out of sync as a result (especially with CVS sources). And there may be bugs, though hopefully not many! - +]]> - -New Features +Features In addition to Internet Junkbuster's traditional - feature of ad and banner blocking and cookie management, - Privoxy provides new features, some of them - currently under development: - - - - - - - - - Integrated browser based configuration and control utility (http://p.p). Browser-based tracing of rule - and filter effects. - - - - - - Blocking of annoying pop-up browser windows. - - - - - - HTTP/1.1 compliant (most, but not all 1.1 features are supported). - - - - - - Support for Perl Compatible Regular Expressions in the configuration files, and - generally a more sophisticated and flexible configuration syntax over - previous versions. - - - - - - GIF de-animation. - - - - - - Web page content filtering (removes banners based on size, - invisible web-bugs, JavaScript, pop-ups, status bar abuse, - etc.) - - - - - - Bypass many click-tracking scripts (avoids script redirection). - - - - - - - Multi-threaded (POSIX and native threads). - - - - - - Auto-detection and re-reading of config file changes. - - - - - - User-customizable HTML templates (e.g. 404 error page). - - - - - - Improved cookie management features (e.g. session based cookies). - - - - - - Improved signal handling, and a true daemon mode (Unix). - - - - - - Builds from source on most UNIX-like systems. Packages available for: Linux - (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11 and AmigaOS. - - - - - - - In addition, the configuration is much more powerful and versatile over-all. - - - - + features of ad and banner blocking and cookie management, + Privoxy provides new features: - + + &newfeatures; + @@ -236,261 +141,298 @@ You can find the latest version of the user manual at Installation - - Privoxy is available as raw source code, or - pre-compiled binaries. See the Privoxy Home Page - for binaries and current release info. Privoxy - is also available via CVS. - This is the recommended approach at this time. But please be aware that CVS - is constantly changing, and it may break in mysterious ways. - - -Source - For gzipped tar archives, unpack the source: + Privoxy is available both in convenient pre-compiled + packages for a wide range of operating systems, and as raw source code. + For most users, we recommend using the packages, which can be downloaded from our + Privoxy Project + Page. For installing and compiling the source code, please look + into our Developer Manual. - - tar xzvf privoxy-2.9.13-beta-src* [.tgz or .tar.gz] - cd privoxy-2.9.13-beta - + If you like to live on the bleeding edge and are not afraid of using + possibly unstable development versions, you can check out the up-to-the-minute + version directly from the + CVS repository or simply download the nightly CVS + tarball. Again, we refer you to the Developer Manual. - - For retrieving the current CVS sources, you'll need the CVS - package installed first. To download CVS source: - + + &supported; + - - cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current - cd current - + Note: If you have a previous Junkbuster or + Privoxy installation on your system, you + will need to remove it. Some platforms do this for you as part + of their installation procedure. (See below for your platform). - This will create a directory named current/, which will - contain the source tree. + In any case be sure to backup your old configuration + if it is valuable to you. See the + note to upgraders section + below. - - Then, in either case, to build from tarball/CVS source: - + +Red Hat and SuSE RPMs - - ./configure (--help to see options) - make (the make from gnu, gmake for *BSD) - su - make -n install (to see where all the files will go) - make install (to really install) - + RPMs can be installed with rpm -Uvh privoxy-&p-version;-1.rpm, + and will use /etc/privoxy for the location + of configuration files. - For Redhat and SuSE Linux RPM packages, see below. + Note that on Red Hat, Privoxy will + not be automatically started on system boot. You will + need to enable that using chkconfig, + ntsysv, or similar methods. Note that SuSE will +automatically start Privoxy in the boot process. - - - - -Red Hat - To build Redhat RPM packages, install source as above. Then: + If you have problems with failed dependencies, try rebuilding the SRC RPM: + rpm --rebuild privoxy-&p-version;-1.src.rpm;. This + will use your locally installed libraries and RPM version. - - autoheader - autoconf - ./configure - make redhat-dist - + Also note that if you have a Junkbuster RPM installed + on your system, you need to remove it first, because the packages conflict. + Otherwise, RPM will try to remove Junkbuster + automatically, before installing Privoxy. + + +Debian - This will create both binary and src RPMs in the usual places. Example: + FIXME. + - -    /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm - - -    /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.rpm - + +Windows - To install, of course: + Just double-click the installer, which will guide you through + the installation process. You will find the configuration files + in the same directory as you installed Privoxy in. We do not + use the registry of Windows. + - - - rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm - - + +Solaris, NetBSD, FreeBSD, HP-UX - This will place the Privoxy configuration - files in /etc/privoxy/, and log files in - /var/log/privoxy/. + Create a new directory, cd to it, then unzip and + untar the archive. For the most part, you'll have to figure out where + things go. FIXME. - -SuSE - - To build SuSE RPM packages, install source as above. Then: - +OS/2 - - autoheader - autoconf - ./configure - make suse-dist - + First, make sure that no previous installations of + Junkbuster and / or + Privoxy are left on your + system. You can do this by - This will create both binary and src RPMs in the usual places. Example: + Then, just double-click the WarpIN self-installing archive, which will + guide you through the installation process. A shadow of the + Privoxy executable will be placed in your + startup folder so it will start automatically whenever OS/2 starts. -    /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm - - -    /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.rpm + The directory you choose to install Privoxy + into will contain all of the configuration files. + - - To install, of course: + +Max OSX + + Unzip the downloaded package (you can either double-click on the file + in the finder, or on the desktop if you downloaded it there). Then, + double-click on the package installer icon and follow the installation + process. + Privoxy will be installed in the subdirectory + /Applications/Privoxy.app. + Privoxy will set itself up to start + automatically on system bring-up via + /System/Library/StartupItems/Privoxy. + + +AmigaOS - - rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm - + Copy and then unpack the lha archive to a suitable location. + All necessary files will be installed into Privoxy + directory, including all configuration and log files. To uninstall, just + remove this directory. - - This will place the Privoxy configuration - files in /etc/privoxy/, and log files in - /var/log/privoxy/. + Start Privoxy (with RUN <>NIL:) in your + startnet script (AmiTCP), in + s:user-startup (RoadShow), as startup program in your + startup script (Genesis), or as startup action (Miami and MiamiDx). + Privoxy will automatically quit when you quit your + TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that + Privoxy is still running). - + + -OS/2 - - - + +Note to Upgraders - Privoxy is packaged in a WarpIN self- - installing archive. The self-installing program will be named depending - on the release version, something like: - ijbos2_setup_1.2.3.exe. In order to install it, simply - run this executable or double-click on its icon and follow the WarpIN - installation panels. A shadow of the Privoxy - executable will be placed in your startup folder so it will start - automatically whenever OS/2 starts. + There are very significant changes from older versions of + Junkbuster to the current + Privoxy. Configuration is substantially + changed. Junkbuster 2.0.x and earlier + configuration files will not migrate. The functionality of the old + blockfile, cookiefile and + imagelist, are now combined into the + actions files. default.action, + is the main actions file. Local exceptions should best be put into + user.action. - - The directory you choose to install Privoxy - into will contain all of the configuration files. + A filter file (typically default.filter) + is new as of Privoxy 2.9.x, and provides some + of the new sophistication (explained below). config is + much the same as before. - - If you would like to build binary images on OS/2 yourself, you will need - a few Unix-like tools: autoconf, autoheader and sh. These tools will be - used to create the required config.h file, which is not part of the - source distribution because it differs based on platform. You will also - need a compiler. - The distribution has been created using IBM VisualAge compilers, but you - can use any compiler you like. GCC/EMX has the disadvantage of needing - to be single-threaded due to a limitation of EMX's implementation of the - select() socket call. + If upgrading from a 2.0.x version, you will have to use the new config + files, and possibly adapt any personal rules from your older files. + When porting personal rules over from the old blockfile + to the new actions files, please note that even the pattern syntax has + changed. If upgrading from 2.9.x development versions, it is still + recommended to use the new configuration files. - - In addition to needing the source code distribution as outlined earlier, - you will want to extract the os2seutp directory from CVS: - - cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup - - This will create a directory named os2setup/, which will contain the - Makefile.vac makefile and os2build.cmd - which is used to completely create the binary distribution. The sequence - of events for building the executable for yourself goes something like this: - - cd current - autoheader - autoconf - sh configure - cd ..\os2setup - nmake -f Makefile.vac - - You will see this sequence laid out in os2build.cmd. + A quick list of things to be aware of before upgrading: - + + + + + The default listening port is now 8118 due to a conflict with another + service (NAS). + + + + + Some installers may remove earlier versions completely. Save any + important configuration files! + + + + + Privoxy is controllable with a web browser + at the special URL: http://config.privoxy.org/ + (Shortcut: http://p.p/). Many + aspects of configuration can be done here, including temporarily disabling + Privoxy. + + + + + The primary configuration file for cookie management, ad and banner + blocking, and many other aspects of Privoxy + configuration is in the actions files. It is strongly + recommended to become familiar with the new actions concept below, + before modifying these files. Locally defined rules + should go into user.action. + + + + + + + Some installers may not automatically start + Privoxy after installation. + + - -Windows -Click-click. (I need help on this. Not a clue here. Also for -configuration section below. HB.) + - + -Other +Quickstart to Using <application>Privoxy</application> - Some quick notes on other Operating Systems. - + - - For FreeBSD (and other *BSDs?), the build will require gmake - instead of the included make. gmake is - available from http://www.gnu.org. - The rest should be the same as above for Linux/Unix. - + + + Install Privoxy. See the section Installing. + + - + + + Start Privoxy. See the section Starting Privoxy. + + - + + + Change your browser's configuration to use the proxy localhost on port + 8118. See the section Starting Privoxy. + + - + + + Enjoy surfing with enhanced comfort and privacy. Please see the section + Contacting the Developers on how to report + bugs or problems with websites or to get help. You may want to change the + file user.action to further tweak your new browsing + experience. + + + + + + - -Quickstart to Using <application>Privoxy</application> + +Starting <application>Privoxy</application> Before launching Privoxy for the first time, you will want to configure your browser(s) to use Privoxy - and the HTTP and HTTPS proxy. The default is localhost for the proxy address, - and port 8118 (earlier versions used port 800). This is the one required - configuration that must be done! + as a HTTP and HTTPS proxy. The default is localhost for the proxy address, + and port 8118 (earlier versions used port 8000). This is the one + configuration step that must be done! With Netscape (and Mozilla), this can be set under Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy. - For Internet Explorer: Tools > + For Internet Explorer: Tools -> Internet Properties -> Connections -> LAN Setting. Then, check Use Proxy and fill in the appropriate info (Address: localhost, Port: 8118). Include if HTTPS proxy support too. @@ -498,9 +440,9 @@ configuration section below. HB.) After doing this, flush your browser's disk and memory caches to force a - re-reading of all pages and get rid of any ads that may be cached. You + re-reading of all pages and to get rid of any ads that may be cached. You are now ready to start enjoying the benefits of using - Privoxy. + Privoxy! @@ -512,22 +454,24 @@ configuration section below. HB.) - # /usr/sbin/privoxy /etc/privoxy/config - - + - An init script is provided for SuSE and Redhat. + See below for other command line options. -For for SuSE: /etc/rc.d/privoxy start + An init script is provided for SuSE and Red Hat. -For RedHat: /etc/rc.d/init.d/privoxy start + For for SuSE: rcprivoxy start + + + + For Red Hat and Debian: /etc/rc.d/init.d/privoxy start @@ -543,43 +487,53 @@ For RedHat: /etc/rc.d/init.d/privoxy start The included default configuration files should give a reasonable starting - point, though may be somewhat aggressive in blocking junk. Most of the - per site configuration is done in the actions files. These - are where various cookie actions are defined, ad and banner blocking, - and other aspects of Privoxy configuration. There - are several such files included, with varying levels of aggressiveness. + point. Most of the per site configuration is done in the + actions files. These are where various cookie actions are + defined, ad and banner blocking, and other aspects of + Privoxy configuration. There are several such + files included, with varying levels of aggressiveness. - You will probably want to keep an eye out for sites that require persistent - cookies, and add these to default.action as needed. By + You will probably want to keep an eye out for sites for which you may prefer + persistent cookies, and add these to your actions configuration as needed. By default, most of these will be accepted only during the current browser - session, until you add them to the configuration. If you want the browser to - handle this instead, you will need to edit - default.action and disable this feature. If you use more - than one browser, it would make more sense to let - Privoxy handle this. In which case, the browser(s) - should be set to accept all cookies. + session (aka session cookies), unless you add them to the + configuration. If you want the browser to handle this instead, you will need + to edit user.action (or through the web based interface) + and disable this feature. If you use more than one browser, it would make + more sense to let Privoxy handle this. In which + case, the browser(s) should be set to accept all cookies. + + + + Another feature where you will probably want to define exceptions for trusted + sites is the popup-killing (through the +popup and + +filter{popups} actions), because your favorite shopping, + banking, or leisure site may need popups (explained below). - Privoxy is HTTP/1.1 compliant, but not all 1.1 - features are as yet implemented. If browsers that support HTTP/1.1 (like - Mozilla or recent versions of I.E.) experience - problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look - under Edit -> Preferences -> Debug -> Networking. - Or set the +downgrade config option in - default.action. + Privoxy is HTTP/1.1 compliant, but not all of + the optional 1.1 features are as yet supported. In the unlikely event that + you experience inexplicable problems with browsers that use HTTP/1.1 per default + (like Mozilla or recent versions of I.E.), you might + try to force HTTP/1.0 compatibility. For Mozilla, look under Edit -> + Preferences -> Debug -> Networking. + Alternatively, set the +downgrade-http-version config option in + default.action which will downgrade your browser's HTTP + requests from HTTP/1.1 to HTTP/1.0 before processing them. After running Privoxy for a while, you can start to fine tune the configuration to suit your personal, or site, preferences and requirements. There are many, many aspects that can - be customized. Actions (as specified in default.action) + be customized. Actions can be adjusted by pointing your browser to - http://p.p/, - and then follow the link to edit the actions list. + http://config.privoxy.org/ + (shortcut: http://p.p/), + and then follow the link to View & Change the Current Configuration. (This is an internal page and does not require Internet access.) @@ -588,30 +542,37 @@ For RedHat: /etc/rc.d/init.d/privoxy start configuration can be viewed from this page, including current configuration parameters, source code version numbers, the browser's request headers, and actions that apply - to a given URL. In addition to the default.action file + to a given URL. In addition to the actions file editor mentioned above, Privoxy can also - be turned on and off from this page. + be turned on and off (toggled) from this page. + + + + If you encounter problems, try loading the page without + Privoxy. If that helps, enter the URL where + you have the problems into the browser + based rule tracing utility. See which rules apply and why, and + then try turning them off for that site one after the other, until the problem + is gone. When you have found the culprit, you might want to turn the rest on + again. - If you encounter problems, please verify it is a - Privoxy bug, by disabling - Privoxy, and then trying the same page. - Also, try another browser if possible to eliminate browser or site - problems. Before reporting it as a bug, see if there is not a configuration - option that is enabled that is causing the page not to load. You can then add - an exception for that page or site. For instance, try adding it to the - {fragile} section of default.action. - This will turn off most actions for this site. For more on troubleshooting - problem sites, see the Appendix. If a bug, please report it - to the developers (see below). + If the above paragraph sounds gibberish to you, you might want to read more about the actions concept + or even dive deep into the Appendix + on actions. + + If you can't get rid of the problem at all, think you've found a bug in + Privoxy, want to propose a new feature or smarter rules, please see the + section Contacting the + Developers below. + - - + Command Line Options Privoxy may be invoked with the following @@ -626,7 +587,7 @@ For RedHat: /etc/rc.d/init.d/privoxy start --version - Print version info and exit, Unix only. + Print version info and exit. Unix only. @@ -634,7 +595,7 @@ For RedHat: /etc/rc.d/init.d/privoxy start --help - Print a short usage info and exit, Unix only. + Print short usage info and exit. Unix only. @@ -643,7 +604,7 @@ For RedHat: /etc/rc.d/init.d/privoxy start Don't become a daemon, i.e. don't fork and become process group - leader, don't detach from controlling tty. Unix only. + leader, and don't detach from controlling tty. Unix only. @@ -653,7 +614,7 @@ For RedHat: /etc/rc.d/init.d/privoxy start On startup, write the process ID to FILE. Delete the - FILE on exit. Failiure to create or delete the + FILE on exit. Failure to create or delete the FILE is non-fatal. If no FILE option is given, no PID file will be used. Unix only. @@ -678,7 +639,8 @@ For RedHat: /etc/rc.d/init.d/privoxy start Privoxy will look for a file named config in the current directory (except on Win32 where it will look for config.txt instead). Specify - full path to avoid confusion. + full path to avoid confusion. If no config file is found, + Privoxy will fail to start. @@ -695,11 +657,10 @@ For RedHat: /etc/rc.d/init.d/privoxy start <application>Privoxy</application> Configuration - All Privoxy configuration is kept + All Privoxy configuration is stored in text files. These files can be edited with a text editor. Many important aspects of Privoxy can also be controlled easily with a web browser. - @@ -708,46 +669,58 @@ For RedHat: /etc/rc.d/init.d/privoxy start Controlling <application>Privoxy</application> with Your Web Browser - Privoxy can be reached by the special - URL http://p.p/ (or alternately - http://config.privoxy.org/), - which is an internal page. You will see the following section: + Privoxy's user interface can be reached through the special + URL http://config.privoxy.org/ + (shortcut: http://p.p/), + which is a built-in page and works without Internet access. + You will see the following section: - - - -Please choose from the following options: - - * Show information about the current configuration - * Show the source code version numbers - * Show the client's request headers. - * Show which actions apply to a URL and why - * Toggle Privoxy on or off - * Edit the actions list - - - + + + + Privoxy Menu - - This should be self-explanatory. Note the last item is an editor for the - actions list, which is where much of the ad, banner, cookie, - and URL blocking magic is configured as well as other advanced features of - Privoxy. This is an easy way to adjust various + + +         ▪  View & change the current configuration + + +         ▪  View the source code version numbers + + +         ▪  View the request headers. + + +         ▪  Look up which actions apply to a URL and why + + +         ▪  Toggle Privoxy on or off + + + + + + + + This should be self-explanatory. Note the first item leads to an editor for the + actions list, which is where the ad, banner, cookie, + and URL blocking magic is configured as well as other advanced features of + Privoxy. This is an easy way to adjust various aspects of Privoxy configuration. The actions file, and other configuration files, are explained in detail below. - Privoxy will automatically detect any changes - to these files. Toggle Privoxy On or Off is handy for sites that might - have problems with your current actions and filters, or just to test if - a site misbehaves, whether it is Privoxy + have problems with your current actions and filters. You can in fact use + it as a test to see whether it is Privoxy causing the problem or not. Privoxy continues - to run as a proxy in this case, but all filtering is disabled. - + to run as a proxy in this case, but all filtering is disabled. There + is even a toggle Bookmarklet offered, so + that you can toggle Privoxy with one click from + your browser. @@ -759,21 +732,21 @@ Please choose from the following options: - + Configuration Files Overview For Unix, *BSD and Linux, all configuration files are located in /etc/privoxy/ by default. For MS Windows, OS/2, and AmigaOS these are all in the same directory as the - Privoxy executable. The name and number of - configuration files has changed from previous versions, and is subject to - change as development progresses. + Privoxy executable. - The installed defaults provide a reasonable starting point, though possibly - aggressive by some standards. For the time being, there are only three - default configuration files (this will change in time): + The installed defaults provide a reasonable starting point, though + some settings may be aggressive by some standards. For the time being, the + principle configuration files are: @@ -781,29 +754,44 @@ Please choose from the following options: - The main configuration file is named config + The main configuration file is named config on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt - on Windows. + on Windows. This is a required file. - The default.action file is used to define various - actions relating to images, banners, pop-ups, access - restrictions, banners and cookies. There is a CGI based editor for this - file that can be accessed via http://p.p. (Other actions - files are included as well with differing levels of filtering - and blocking, e.g. ijb-basic.action.) + default.action (the main actions file) is used to define + the default settings for various actions relating to images, banners, + pop-ups, access restrictions, banners and cookies. + + + Multiple actions files may be defined in config. These + are processed in the order they are defined. Local customizations and locally + preferred exceptions to the default policies as defined in + default.action are probably best applied in + user.action, which should be preserved across + upgrades. standard.action is also included. This is mostly + for Privoxy's internal use. + + + There is also a web based editor that can be accessed from + http://config.privoxy.org/show-status/ + (Shortcut: http://p.p/show-status/) for the + various actions files. - The default.filter file can be used to re-write the raw - page content, including viewable text as well as embedded HTML and JavaScript, - and whatever else lurks on any given web page. + default.filter (the filter + file) can be used to re-write the raw page content, including + viewable text as well as embedded HTML and JavaScript, and whatever else + lurks on any given web page. The filtering jobs are only pre-defined here; + whether to apply them or not is up to the actions files. @@ -811,28 +799,45 @@ Please choose from the following options: - default.action and default.filter - can use Perl style regular expressions for maximum flexibility. All files use - the # character to denote a comment. Such - lines are not processed by Privoxy. After - making any changes, there is no need to restart + All files use the # character to denote a + comment (the rest of the line will be ignored) angd understand line continuation + through placing a backslash ("\") as the very last character + in a line. If the # is preceded by a backslash, it looses + its special function. Placing a # in front of an otherwise + valid configuration line to prevent it from being interpreted is called "commenting + out" that line. + + + + The actions files and default.filter + can use Perl style regular expressions for + maximum flexibility. + + + + After making any changes, there is no need to restart Privoxy in order for the changes to take - effect. Privoxy should detect such changes - automatically. + effect. Privoxy detects such changes + automatically. Note, however, that it may take one or two additional + requests for the change to take effect. When changing the listening address + of Privoxy, these wake up requests + must obviously be sent to the old listening address. + While under development, the configuration content is subject to change. The below documentation may not be accurate by the time you read this. Also, what constitutes a default setting, may change, so please check all your configuration files on important issues. +]]> - + The Main Configuration File Again, the main configuration file is named config on @@ -846,253 +851,403 @@ Please choose from the following options: - blockfile blocklist.ini + confdir /etc/privoxy - - - - - - Indicates that the blockfile is named blocklist.ini. (A - default installation does not use this.) - - - - A # indicates a comment. Any part of a - line following a # is ignored, except if - the # is preceded by a - \. + + - Thus, by placing a # at the start of an - existing configuration line, you can make it a comment and it will be treated - as if it weren't there. This is called commenting out an - option and can be useful to turn off features: If you comment out the - logfile line, Privoxy will not - log to a file at all. Watch for the default: section in each - explanation to see what happens if the option is left unset (or commented - out). + Assigns the value /etc/privoxy to the option + confdir and thus indicates that the configuration + directory is named /etc/privoxy/. - Long lines can be continued on the next line by using a - \ as the very last character. + All options in the config file except for confdir and + logdir are optional. Watch out in the below description + for what happens if you leave them unset. - There are various aspects of Privoxy behavior - that can be tuned. + The main config file controls all aspects of Privoxy's + operation that are not location dependent (i.e. they apply universally, no matter + where you may be surfing). - -Defining Other Configuration Files - - - Privoxy can use a number of other files to tell it - what ads to block, what cookies to accept, etc. This section of the - configuration file tells Privoxy where to find - all those other files. - - - - On Windows and AmigaOS, - Privoxy looks for these files in the same - directory as the executable. On Unix and OS/2, - Privoxy looks for these files in the current - working directory. In either case, an absolute path name can be used to - avoid problems. - - - - When development goes modular and multi-user, the blocker, filter, and - per-user config will be stored in subdirectories of confdir. - For now, only confdir/templates is used for storing HTML - templates for CGI results. - - - - The location of the configuration files: - - - - - - - confdir /etc/privoxy # No trailing /, please. - - - - - - - The directory where all logging (i.e. logfile and - jarfile) takes place. No trailing - /, please: - - - - - - - logdir /var/log/privoxy - - - - - - - Note that all file specifications below are relative to - the above two directories! - - - - The default.action file contains patterns to specify the - actions to apply to requests for each site. Default: Cookies to and from all - destinations are kept only during the current browser session (i.e. they are - not saved to disk). Pop-ups are disabled for all sites. All sites are - filtered through selected sections of default.filter. No sites - are blocked. Privoxy displays a checkboard type - pattern for filtered ads and other images. The syntax of this file is - explained in detail below. Other - actions files are included, and you are free to use any of - them. They have varying degrees of aggressiveness. - - - - - - - actionsfile default.action - - - - + +Configuration and Log File Locations - The default.filter file contains content modification rules - that use regular expressions. These rules permit powerful - changes on the content of Web pages, e.g., you could disable your favorite - JavaScript annoyances, re-write the actual displayed text, or just have some - fun replacing Microsoft with MicroSuck wherever - it appears on a Web page. Default: whatever the developers are playing with - :-/ + Privoxy can (and normally does) use a number of + other files for additional configuration and logging. + This section of the configuration file tells Privoxy + where to find those other files. - - Filtering requires buffering the page content, which may appear to slow down - page rendering since nothing is displayed until all content has passed - the filters. (It does not really take longer, but seems that way since - the page is not incrementally displayed.) This effect will be more noticeable - on slower connections. - - - - - - - filterfile default.filter - - - - +confdir - - The logfile is where all logging and error messages are written. The logfile - can be useful for tracking down a problem with - Privoxy (e.g., it's not blocking an ad you - think it should block) but in most cases you probably will never look at it. - + + + Specifies: + + The directory where the other configuration files are located + + + + Type of value: + + Path name + + + + Default value: + + /etc/privoxy (Unix) or Privoxy installation dir (Windows) + + + + Effect if unset: + + Mandatory + + + + Notes: + + + No trailing /, please + + + When development goes modular and multi-user, the blocker, filter, and + per-user config will be stored in subdirectories of confdir. + For now, the configuration directory structure is flat, except for + confdir/templates, where the HTML templates for CGI + output reside (e.g. Privoxy's 404 error page). + + + + + - - Your logfile will grow indefinitely, and you will probably want to - periodically remove it. On Unix systems, you can do this with a cron job - (see man cron). For Redhat, a logrotate - script has been included. - - - On SuSE Linux systems, you can place a line like /var/log/privoxy.* - +1024k 644 nobody.nogroup in /etc/logfiles, with - the effect that cron.daily will automatically archive, gzip, and empty the - log, when it exceeds 1M size. - +logdir - - Default: Log to the a file named logfile. - Comment out to disable logging. - + + + Specifies: + + + The directory where all logging takes place (i.e. where logfile and + jarfile are located) + + + + + Type of value: + + Path name + + + + Default value: + + /var/log/privoxy (Unix) or Privoxy installation dir (Windows) + + + + Effect if unset: + + Mandatory + + + + Notes: + + + No trailing /, please + + + + + + + +actionsfile + + + + + + + + Specifies: + + + The actions file(s) to use + + + + + Type of value: + + File name, relative to confdir + + + + Default value: + + + + standard # Internal purposes, recommended not editing + + + default # Main actions file + + + user # User customizations + + + + + + Effect if unset: + + + No actions are taken at all. Simple neutral proxying. + + + + + Notes: + + + Multiple actionsfile lines are OK and are in fact recommended! + + + The default values include standard.action, which is used for internal + purposes and should be loaded, default.action, which is the + main actions file maintained by the developers, and + user.action, where you can make your personal additions. + + + There is no point in using Privoxy without an actions file. + + + + + + +filterfile + + + + Specifies: + + + The filter file to use + + + + + Type of value: + + File name, relative to confdir + + + + Default value: + + default.filter (Unix) or default.filter.txt (Windows) + + + + Effect if unset: + + + No textual content filtering takes place, i.e. all + +filter{name} + actions in the actions files are turned off + + + + + Notes: + + + The default.filter file contains content modification rules + that use regular expressions. These rules permit powerful + changes on the content of Web pages, e.g., you could disable your favorite + JavaScript annoyances, re-write the actual displayed text, or just have some + fun replacing Microsoft with MicroSuck wherever + it appears on a Web page. + + + + + - - - - - logfile logfile - - - - +logfile - - The jarfile defines where - Privoxy stores the cookies it intercepts. Note - that if you use a jarfile, it may grow quite large. Default: - Don't store intercepted cookies. - + + + Specifies: + + + The log file to use + + + + + Type of value: + + File name, relative to logdir + + + + Default value: + + logfile (Unix) or privoxy.log (Windows) + + + + Effect if unset: + + + No log file is used, all log messages go to the console (stderr). + + + + + Notes: + + + The windows version will additionally log to the console. + + + The logfile is where all logging and error messages are written. The level + of detail and number of messages are set with the debug + option (see below). The logfile can be useful for tracking down a problem with + Privoxy (e.g., it's not blocking an ad you + think it should block) but in most cases you probably will never look at it. + + + Your logfile will grow indefinitely, and you will probably want to + periodically remove it. On Unix systems, you can do this with a cron job + (see man cron). For Red Hat, a logrotate + script has been included. + + + On SuSE Linux systems, you can place a line like /var/log/privoxy.* + +1024k 644 nobody.nogroup in /etc/logfiles, with + the effect that cron.daily will automatically archive, gzip, and empty the + log, when it exceeds 1M size. + + + + + - - - - - #jarfile jarfile - - - - +jarfile - - If you specify a trustfile, - Privoxy will only allow access to sites that - are named in the trustfile. You can also mark sites as trusted referrers, - with the effect that access to untrusted sites will be granted, if a link - from a trusted referrer was used. The link target will then be added to the - trustfile. This is a very restrictive feature that typical - users most probably want to leave disabled. Default: Disabled, don't use the - trust mechanism. - + + + Specifies: + + + The file to store intercepted cookies in + + + + + Type of value: + + File name, relative to logdir + + + + Default value: + + jarfile (Unix) or privoxy.jar (Windows) + + + + Effect if unset: + + + Intercepted cookies are not stored at all. + + + + + Notes: + + + The jarfile may grow to ridiculous sizes over time. + + + + + - - - - - #trustfile trust - - - - - - - If you use the trust mechanism, it is a good idea to write up some on-line - documentation about your blocking policy and to specify the URL(s) here. They - will appear on the page that your users receive when they try to access - untrusted content. Use multiple times for multiple URLs. Default: Don't - display links on the untrusted info page. - +trustfile - - - - - trust-info-url http://www.your-site.com/why_we_block.html - trust-info-url http://www.your-site.com/what_we_allow.html - - - - + + + Specifies: + + + The trust file to use + + + + + Type of value: + + File name, relative to confdir + + + + Default value: + + Unset (commented out). When activated: trust (Unix) or trust.txt (Windows) + + + + Effect if unset: + + + The whole trust mechanism is turned off. + + + + + Notes: + + + The trust mechanism is an experimental feature for building white-lists and should + be used with care. It is NOT recommended for the casual user. + + + If you specify a trust file, Privoxy will only allow + access to sites that are named in the trustfile. + You can also mark sites as trusted referrers (with +), with + the effect that access to untrusted sites will be granted, if a link from a + trusted referrer was used. + The link target will then be added to the trustfile. + Possible applications include limiting Internet access for children. + + + If you use + operator in the trust file, it may grow considerably over time. + + + + + @@ -1102,315 +1257,720 @@ Please choose from the following options: - -Other Configuration Options - - - This part of the configuration file contains options that control how - Privoxy operates. - - - - Admin-address should be set to the email address of the proxy - administrator. It is used in many of the proxy-generated pages. Default: - fill@me.in.please. - + +Local Set-up Documentation - - - - - #admin-address fill@me.in.please - - - - + + If you intend to operate Privoxy for more users + that just yourself, it might be a good idea to let them know how to reach + you, what you block and why you do that, your policies etc. + - - Proxy-info-url can be set to a URL that contains more info - about this Privoxy installation, it's - configuration and policies. It is used in many of the proxy-generated pages - and its use is highly recommended in multi-user installations, since your - users will want to know why certain content is blocked or modified. Default: - Don't show a link to on-line documentation. - +trust-info-url - - - - - proxy-info-url http://www.your-site.com/proxy.html - - - - - - - Listen-address specifies the address and port where - Privoxy will listen for connections from your - Web browser. The default is to listen on the localhost port 8118, and - this is suitable for most users. (In your web browser, under proxy - configuration, list the proxy server as localhost and the - port as 8118). - - - - If you already have another service running on port 8118, or if you want to - serve requests from other machines (e.g. on your local network) as well, you - will need to override the default. The syntax is - listen-address [<ip-address>]:<port>. If you leave - out the IP address, Privoxy will bind to all - interfaces (addresses) on your machine and may become reachable from the - Internet. In that case, consider using access control lists (acl's) (see - aclfile above), or a firewall. - - - - For example, suppose you are running Privoxy on - a machine which has the address 192.168.0.1 on your local private network - (192.168.0.0) and has another outside connection with a different address. - You want it to serve requests from inside only: - - - - - - - listen-address 192.168.0.1:8118 - - - - - - - If you want it to listen on all addresses (including the outside - connection): - - - - - - - listen-address :8118 - - - - - - - If you do this, consider using ACLs (see aclfile above). Note: - you will need to point your browser(s) to the address and port that you have - configured here. Default: localhost:8118 (127.0.0.1:8118). - - - - The debug option sets the level of debugging information to log in the - logfile (and to the console in the Windows version). A debug level of 1 is - informative because it will show you each request as it happens. Higher - levels of debug are probably only of interest to developers. - - - - - - - debug 1 # GPC = show each GET/POST/CONNECT request - debug 2 # CONN = show each connection status - debug 4 # IO = show I/O status - debug 8 # HDR = show header parsing - debug 16 # LOG = log all data into the logfile - debug 32 # FRC = debug force feature - debug 64 # REF = debug regular expression filter - debug 128 # = debug fast redirects - debug 256 # = debug GIF de-animation - debug 512 # CLF = Common Log Format - debug 1024 # = debug kill pop-ups - debug 4096 # INFO = Startup banner and warnings. - debug 8192 # ERROR = Non-fatal errors - - - - + + + Specifies: + + + A URL to be displayed in the error page that users will see if access to an untrusted page is denied. + + + + + Type of value: + + URL + + + + Default value: + + Two example URL are provided + + + + Effect if unset: + + + No links are displayed on the "untrusted" error page. + + + + + Notes: + + + The value of this option only matters if the experimental trust mechanism has been + activated. (See trustfile above.) + + + If you use the trust mechanism, it is a good idea to write up some on-line + documentation about your trust policy and to specify the URL(s) here. + Use multiple times for multiple URLs. + + + The URL(s) should be added to the trustfile as well, so users don't end up + locked out from the information on why they were locked out in the first place! + + + + + - - It is highly recommended that you enable ERROR - reporting (debug 8192), at least until v3.0 is released. - +admin-address - - The reporting of FATAL errors (i.e. ones which crash - Privoxy) is always on and cannot be disabled. - + + + Specifies: + + + An email address to reach the proxy administrator. + + + + + Type of value: + + Email address + + + + Default value: + + Unset + + + + Effect if unset: + + + No email address is displayed on error pages and the CGI user interface. + + + + + Notes: + + + If both admin-address and proxy-info-url + are unset, the whole "Local Privoxy Support" box on all generated pages will + not be shown. + + + + + + +proxy-info-url + + + + Specifies: + + + A URL to documentation about the local Privoxy setup, + configuration or policies. + + + + + Type of value: + + URL + + + + Default value: + + Unset + + + + Effect if unset: + + + No link to local documentation is displayed on error pages and the CGI user interface. + + + + + Notes: + + + If both admin-address and proxy-info-url + are unset, the whole "Local Privoxy Support" box on all generated pages will + not be shown. + + + This URL shouldn't be blocked ;-) + + + + + - - If you want to use CLF (Common Log Format), you should set debug - 512 ONLY, do not enable anything else. - + + - - Multiple debug directives, are OK - they're logical-OR'd - together. - + - - - - - debug 15 # same as setting the first 4 listed above - - - - + +Debugging - - Default: - + + These options are mainly useful when tracing a problem. + Note that you might also want to invoke + Privoxy with the --no-daemon + command line option when debugging. + - - - - - debug 1 # URLs - debug 4096 # Info - debug 8192 # Errors - *we highly recommended enabling this* - - - - +debug - - Privoxy normally uses - multi-threading, a software technique that permits it to - handle many different requests simultaneously. In some cases you may wish to - disable this -- particularly if you're trying to debug a problem. The - single-threaded option forces - Privoxy to handle requests sequentially. - Default: Multi-threaded mode. - + + + Specifies: + + + Key values that determine what information gets logged. + + + + + Type of value: + + Integer values + + + + Default value: + + 12289 (i.e.: URLs plus informational and warning messages) + + + + Effect if unset: + + + Nothing gets logged. + + + + + Notes: + + + The available debug levels are: + + + + debug 1 # show each GET/POST/CONNECT request + debug 2 # show each connection status + debug 4 # show I/O status + debug 8 # show header parsing + debug 16 # log all data into the logfile + debug 32 # debug force feature + debug 64 # debug regular expression filter + debug 128 # debug fast redirects + debug 256 # debug GIF de-animation + debug 512 # Common Log Format + debug 1024 # debug kill pop-ups + debug 4096 # Startup banner and warnings. + debug 8192 # Non-fatal errors + + + + To select multiple debug levels, you can either add them or use + multiple debug lines. + + + A debug level of 1 is informative because it will show you each request + as it happens. 1, 4096 and 8192 are highly recommended + so that you will notice when things go wrong. The other levels are probably + only of interest if you are hunting down a specific problem. They can produce + a hell of an output (especially 16). + + + + The reporting of fatal errors (i.e. ones which crash + Privoxy) is always on and cannot be disabled. + + + If you want to use CLF (Common Log Format), you should set debug + 512 ONLY and not enable anything else. + + + + + - - - - - #single-threaded - - - - +single-threaded - - toggle allows you to temporarily disable all - Privoxy's filtering. Just set toggle - 0. - + + + Specifies: + + + Whether to run only one server thread + + + + + Type of value: + + None + + + + Default value: + + Unset + + + + Effect if unset: + + + Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to + serve multiple requests simultaneously. + + + + + Notes: + + + This option is only there for debug purposes and you should never + need to use it. It will drastically reduce performance. + + + + + - - The Windows version of Privoxy puts an icon in - the system tray, which also allows you to change this option. If you - right-click on that icon (or select the Options menu), one - choice is Enable. Clicking on enable toggles - Privoxy on and off. This is useful if you want - to temporarily disable Privoxy, e.g., to access - a site that requires cookies which you would otherwise have blocked. This can also - be toggled via a web browser at the Privoxy - internal address of http://p.p on - any platform. - + - - toggle 1 means Privoxy runs - normally, toggle 0 means that - Privoxy becomes a non-anonymizing non-blocking - proxy. Default: 1 (on). - + - - - - - toggle 1 - - - - + +Access Control and Security - - For content filtering, i.e. the +filter and - +deanimate-gif actions, it is necessary that - Privoxy buffers the entire document body. - This can be potentially dangerous, since a server could just keep sending - data indefinitely and wait for your RAM to exhaust. With nasty consequences. - + + This section of the config file controls the security-relevant aspects + of Privoxy's configuration. + - - The buffer-limit option lets you set the maximum - size in Kbytes that each buffer may use. When the documents buffer exceeds - this size, it is flushed to the client unfiltered and no further attempt to - filter the rest of it is made. Remember that there may multiple threads - running, which might require increasing the buffer-limit - Kbytes each, unless you have enabled - single-threaded above. - +listen-address - - - - - buffer-limit 4069 - - - - + + + Specifies: + + + The IP address and TCP port on which Privoxy will + listen for client requests. + + + + + Type of value: + + [IP-Address]:Port + + + + Default value: + + localhost:8118 + + + + Effect if unset: + + + Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for + home users who run Privoxy on the same machine as + their browser. + + + + + Notes: + + + You will need to configure your browser(s) to this proxy address and port. + + + If you already have another service running on port 8118, or if you want to + serve requests from other machines (e.g. on your local network) as well, you + will need to override the default. + + + If you leave out the IP address, Privoxy will + bind to all interfaces (addresses) on your machine and may become reachable + from the Internet. In that case, consider using access control lists (ACL's) + (see ACLs below), or a firewall. + + + + + Example: + + + Suppose you are running Privoxy on + a machine which has the address 192.168.0.1 on your local private network + (192.168.0.0) and has another outside connection with a different address. + You want it to serve requests from inside only: + + + + listen-address 192.168.0.1:8118 + + + + + + - - To enable the web-based default.action file editor set - enable-edit-actions to 1, or 0 to disable. Note - that you must have compiled Privoxy with - support for this feature, otherwise this option has no effect. This - internal page can be reached at http://p.p. - +toggle - - Security note: If this is enabled, anyone who can use the proxy - can edit the actions file, and their changes will affect all users. - For shared proxies, you probably want to disable this. Default: enabled. - + + + Specifies: + + + Initial state of "toggle" status + + + + + Type of value: + + 1 or 0 + + + + Default value: + + 1 + + + + Effect if unset: + + + Act as if toggled on + + + + + Notes: + + + If set to 0, Privoxy will start in + toggled off mode, i.e. behave like a normal, content-neutral + proxy. See enable-remote-toggle + below. This is not really useful anymore, since toggling is much easier + via the web + interface then via editing the conf file. + + + The windows version will only display the toggle icon in the system tray + if this option is present. + + + + + - - - - - enable-edit-actions 1 - - - - - - Allow Privoxy to be toggled on and off - remotely, using your web browser. Set enable-remote-toggleto - 1 to enable, and 0 to disable. Note that you must have compiled - Privoxy with support for this feature, - otherwise this option has no effect. - +enable-remote-toggle + + + Specifies: + + + Whether or not the web-based toggle + feature may be used + + + + + Type of value: + + 0 or 1 + + + + Default value: + + 1 + + + + Effect if unset: + + + The web-based toggle feature is disabled. + + + + + Notes: + + + When toggled off, Privoxy acts like a normal, + content-neutral proxy, i.e. it acts as if none of the actions applied to + any URL. + + + For the time being, access to the toggle feature can not be + controlled separately by ACLs or HTTP authentication, + so that everybody who can access Privoxy (see + ACLs and listen-address above) can + toggle it for all users. So this option is not recommended + for multi-user environments with untrusted users. + + + Note that you must have compiled Privoxy with + support for this feature, otherwise this option has no effect. + + + + + - - Security note: If this is enabled, anyone who can use the proxy can toggle - it on or off (see http://p.p), and - their changes will affect all users. For shared proxies, you probably want to - disable this. Default: enabled. - - - - - - enable-remote-toggle 1 - - - - +enable-edit-actions + + + Specifies: + + + Whether or not the web-based actions + file editor may be used + + + + + Type of value: + + 0 or 1 + + + + Default value: + + 1 + + + + Effect if unset: + + + The web-based actions file editor is disabled. + + + + + Notes: + + + For the time being, access to the editor can not be + controlled separately by ACLs or HTTP authentication, + so that everybody who can access Privoxy (see + ACLs and listen-address above) can + modify its configuration for all users. So this option is not + recommended for multi-user environments with untrusted users. + + + Note that you must have compiled Privoxy with + support for this feature, otherwise this option has no effect. + + + + + + + +ACLs: permit-access and deny-access + + + + + + Specifies: + + + Who can access what. + + + + + Type of value: + + + src_addr[/src_masklen] + [dst_addr[/dst_masklen]] + + + Where src_addr and + dst_addr are IP addresses in dotted decimal notation or valid + DNS names, and src_masklen and + dst_masklen are subnet masks in CIDR notation, i.e. integer + values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole + destination part are optional. + + + + + Default value: + + Unset + + + + Effect if unset: + + + Don't restrict access further than implied by listen-address + + + + + Notes: + + + Access controls are included at the request of ISPs and systems + administrators, and are not usually needed by individual users. + For a typical home user, it will normally suffice to ensure that + Privoxy only listens on the localhost or internal (home) + network address by means of the listen-address option. + + + Please see the warnings in the FAQ that this proxy is not intended to be a substitute + for a firewall or to encourage anyone to defer addressing basic security + weaknesses. + + + Multiple ACL lines are OK. + If any ACLs are specified, then the Privoxy + talks only to IP addresses that match at least one permit-access line + and don't match any subsequent deny-access line. In other words, the + last match wins, with the default being deny-access. + + + If Privoxy is using a forwarder (see forward below) + for a particular destination URL, the dst_addr + that is examined is the address of the forwarder and NOT the address + of the ultimate target. This is necessary because it may be impossible for the local + Privoxy to determine the IP address of the + ultimate target (that's often what gateways are used for). + + + You should prefer using IP addresses over DNS names, because the address lookups take + time. All DNS names must resolve! You can not use domain patterns + like *.org or partial domain names. If a DNS name resolves to multiple + IP addresses, only the first one is used. + + + Denying access to particular sites by ACL may have undesired side effects + if the site in question is hosted on a machine which also hosts other sites. + + + + + Examples: + + + Explicitly define the default behavior if no ACL and + listen-address are set: localhost + is OK. The absence of a dst_addr implies that + all destination addresses are OK: + + + + permit-access localhost + + + + Allow any host on the same class C subnet as www.privoxy.org access to + nothing but www.example.com: + + + + permit-access www.privoxy.org/24 www.example.com/32 + + + + Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere, + with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com: + + + + permit-access 192.168.45.64/26 + deny-access 192.168.45.73 www.dirty-stuff.example.com + + + + + + + +buffer-limit + + + + Specifies: + + + Maximum size of the buffer for content filtering. + + + + + Type of value: + + Size in Kbytes + + + + Default value: + + 4096 + + + + Effect if unset: + + + Use a 4MB (4096 KB) limit. + + + + + Notes: + + + For content filtering, i.e. the +filter and + +deanimate-gif actions, it is necessary that + Privoxy buffers the entire document body. + This can be potentially dangerous, since a server could just keep sending + data indefinitely and wait for your RAM to exhaust -- with nasty consequences. + Hence this option. + + + When a document buffer size reaches the buffer-limit, it is + flushed to the client unfiltered and no further attempt to + filter the rest of the document is made. Remember that there may be multiple threads + running, which might require up to buffer-limit Kbytes + each, unless you have enabled single-threaded + above. + + + + + @@ -1419,513 +1979,752 @@ Please choose from the following options: - -Access Control List (ACL) + +Forwarding + + + This feature allows routing of HTTP requests through a chain of + multiple proxies. + It can be used to better protect privacy and confidentiality when + accessing specific domains by routing requests to those domains + through an anonymous public proxy (see e.g. http://www.multiproxy.org/anon_list.htm) + Or to use a caching proxy to speed up browsing. Or chaining to a parent + proxy may be necessary because the machine that Privoxy + runs on has no direct Internet access. + + - Access controls are included at the request of some ISPs and systems - administrators, and are not usually needed by individual users. Please note - the warnings in the FAQ that this proxy is not intended to be a substitute - for a firewall or to encourage anyone to defer addressing basic security - weaknesses. + Also specified here are SOCKS proxies. Privoxy + supports the SOCKS 4 and SOCKS 4A protocols. +forward + + + Specifies: + + + To which parent HTTP proxy specific requests should be routed. + + + + + Type of value: + + + target_domain[:port] + http_parent[/port] + + + Where target_domain is a domain name pattern (see the + chapter on domain matching in the default.action file), + http_parent is the address of the parent HTTP proxy + as an IP addresses in dotted decimal notation or as a valid DNS name (or . to denote + no forwarding, and the optional + port parameters are TCP ports, i.e. integer + values from 1 to 64535 + + + + + Default value: + + Unset + + + + Effect if unset: + + + Don't use parent HTTP proxies. + + + + + Notes: + + + If http_parent is ., then requests are not + forwarded to another HTTP proxy but are made directly to the web servers. + + + Multiple lines are OK, they are checked in sequence, and the last match wins. + + + + + Examples: + + + Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle): + + + + forward .* anon-proxy.example.org:8080 + forward :443 . + + + + Everything goes to our example ISP's caching proxy, except for requests + to that ISP's sites: + + + + forward .*. caching-proxy.example-isp.net:8000 + forward .example-isp.net . + + + + + + + + +forward-socks4 and forward-socks4a + + + + + + Specifies: + + + Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed. + + + + + Type of value: + + + target_domain[:port] + socks_proxy[/port] + http_parent[/port] + + + Where target_domain is a domain name pattern (see the + chapter on domain matching in the default.action file), + http_parent and socks_proxy + are IP addresses in dotted decimal notation or valid DNS names (http_parent + may be . to denote no HTTP forwarding), and the optional + port parameters are TCP ports, i.e. integer values from 1 to 64535 + + + + + Default value: + + Unset + + + + Effect if unset: + + + Don't use SOCKS proxies. + + + + + Notes: + + + Multiple lines are OK, they are checked in sequence, and the last match wins. + + + The difference between forward-socks4 and forward-socks4a + is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS + server, while in SOCKS 4 it happens locally. + + + If http_parent is ., then requests are not + forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through + a SOCKS proxy. + + + + + Examples: + + + From the company example.com, direct connections are made to all + internal domains, but everything outbound goes through + their ISP's proxy by way of example.com's corporate SOCKS 4A gateway to + the Internet. + + + + forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080 + forward .example.com . + + + + A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this: + + + + forward-socks4 .*. socks-gw.example.com:1080 . + + + + + + + +Advanced Forwarding Examples + - If no access settings are specified, the proxy talks to anyone that - connects. If any access settings file are specified, then the proxy - talks only to IP addresses permitted somewhere in this file and not - denied later in this file. + If you have links to multiple ISPs that provide various special content + only to their subscribers, you can configure multiple Privoxies + which have connections to the respective ISPs to act as forwarders to each other, so that + your users can see the internal content of all ISPs. - Summary -- if using an ACL: + Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to + isp-b.net. Both run Privoxy. Their forwarding + configuration can look like this: - - - Client must have permission to receive service. - - - - - LAST match in ACL wins. - - - - - Default behavior is to deny service. - - + + host-a: + - The syntax for an entry in the Access Control List is: + + forward .*. . + forward .isp-b.net host-b:8118 + - - - - ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ] - - - + host-b: - Where the individual fields are: + + forward .*. . + forward .isp-a.net host-a:8118 + - - - - ACTION = permit-access or deny-access + Now, your users can set their browser's proxy to use either + host-a or host-b and be able to browse the internal content + of both isp-a and isp-b. + - SRC_ADDR = client hostname or dotted IP address - SRC_MASKLEN = number of bits in the subnet mask for the source + + If you intend to chain Privoxy and + squid locally, then chain as + browser -> squid -> privoxy is the recommended way. + - DST_ADDR = server or forwarder hostname or dotted IP address - DST_MASKLEN = number of bits in the subnet mask for the target - - - + + Assuming that Privoxy and squid + run on the same box, your squid configuration could then look like this: + + + # Define Privoxy as parent proxy (without ICP) + cache_peer 127.0.0.1 parent 8118 7 no-query + + # Define ACL for protocol FTP + acl ftp proto FTP + + # Do not forward FTP requests to Privoxy + always_direct allow ftp - - The field separator (FS) is whitespace (space or tab). + # Forward all the rest to Privoxy + never_direct allow all - IMPORTANT NOTE: If Privoxy is using a - forwarder (see below) or a gateway for a particular destination URL, the - DST_ADDR that is examined is the address of the forwarder - or the gateway and NOT the address of the ultimate - target. This is necessary because it may be impossible for the local - Privoxy to determine the address of the - ultimate target (that's often what gateways are used for). + You would then need to change your browser's proxy settings to squid's address and port. + Squid normally uses port 3128. If unsure consult http_port in squid.conf. + + + + + + + + + + +Windows GUI Options - Here are a few examples to show how the ACL features work: + Privoxy has a number of options specific to the + Windows GUI interface: + - localhost is OK -- no DST_ADDR implies that - ALL destination addresses are OK: + If activity-animation is set to 1, the + Privoxy icon will animate when + Privoxy is active. To turn off, set to 0. - permit-access localhost + activity-animation 1 + - A silly example to illustrate permitting any host on the class-C subnet with - Privoxy to go anywhere: + If log-messages is set to 1, + Privoxy will log messages to the console + window: - permit-access www.privoxy.com/24 + log-messages 1 + + + If log-buffer-size is set to 1, the size of the log buffer, + i.e. the amount of memory used for the log messages displayed in the + console window, will be limited to log-max-lines (see below). + + - Except deny one particular IP address from using it at all: + Warning: Setting this to 0 will result in the buffer to grow infinitely and + eat up all your memory! - deny-access ident.privoxy.com + log-buffer-size 1 + - You can also specify an explicit network address and subnet mask. - Explicit addresses do not have to be resolved to be used. + log-max-lines is the maximum number of lines held + in the log buffer. See above. - permit-access 207.153.200.0/24 + log-max-lines 200 + - A subnet mask of 0 matches anything, so the next line permits everyone. + If log-highlight-messages is set to 1, + Privoxy will highlight portions of the log + messages with a bold-faced font: - permit-access 0.0.0.0/0 + log-highlight-messages 1 + - Note, you cannot say: + The font used in the console window: - permit-access .org + log-font-name Comic Sans MS + - to allow all *.org domains. Every IP address listed must resolve fully. - - - - An ISP may want to provide a Privoxy that is - accessible by the world and yet restrict use of some of their - private content to hosts on its internal network (i.e. its own subscribers). - Say, for instance the ISP owns the Class-B IP address block 123.124.0.0 (a 16 - bit netmask). This is how they could do it: + Font size used in the console window: - permit-access 0.0.0.0/0 0.0.0.0/0 # other clients can go anywhere - # with the following exceptions: - - deny-access 0.0.0.0/0 123.124.0.0/16 # block all external requests for - # sites on the ISP's network - - permit 0.0.0.0/0 www.my_isp.com # except for the ISP's main - # web site - - permit 123.124.0.0/16 0.0.0.0/0 # the ISP's clients can go - # anywhere + log-font-size 8 - - Note that if some hostnames are listed with multiple IP addresses, - the primary value returned by DNS (via gethostbyname()) is used. Default: - Anyone can access the proxy. - - - - - - - - - - -Forwarding - - - This feature allows chaining of HTTP requests via multiple proxies. - It can be used to better protect privacy and confidentiality when - accessing specific domains by routing requests to those domains - to a special purpose filtering proxy such as lpwa.com. Or to use - a caching proxy to speed up browsing. - - - - It can also be used in an environment with multiple networks to route - requests via multiple gateways allowing transparent access to multiple - networks without having to modify browser configurations. - - - - Also specified here are SOCKS proxies. Privoxy - SOCKS 4 and SOCKS 4A. The difference is that SOCKS 4A will resolve the target - hostname using DNS on the SOCKS server, not our local DNS client. - - - - The syntax of each line is: + + + show-on-task-bar controls whether or not + Privoxy will appear as a button on the Task bar + when minimized: - forward target_domain[:port] http_proxy_host[:port] - forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port] - forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port] + show-on-task-bar 0 + - If http_proxy_host is ., then requests are not forwarded to a - HTTP proxy but are made directly to the web servers. - - - - Lines are checked in sequence, and the last match wins. - - - - There is an implicit line equivalent to the following, which specifies that - anything not finding a match on the list is to go out without forwarding - or gateway protocol, like so: + If close-button-minimizes is set to 1, the Windows close + button will minimize Privoxy instead of closing + the program (close with the exit option on the File menu). - forward .* . # implicit + close-button-minimizes 1 + - In the following common configuration, everything goes to Lucent's LPWA, - except SSL on port 443 (which it doesn't handle): - - - - - - - forward .* lpwa.com:8000 - forward :443 . - - - + The hide-console option is specific to the MS-Win console + version of Privoxy. If this option is used, + Privoxy will disconnect from and hide the + command console. - - - Some users have reported difficulties related to LPWA's use of - . as the last element of the domain, and have said that this - can be fixed with this: - - - forward lpwa. lpwa.com:8000 + #hide-console - - - (NOTE: the syntax for specifying target_domain has changed since the - previous paragraph was written -- it will not work now. More information - is welcome.) - - - In this fictitious example, everything goes via an ISP's caching proxy, - except requests to that ISP: - + + - - - - - forward .* caching.myisp.net:8000 - forward myisp.net . - - - - + - - For the @home network, we're told the forwarding configuration is this: - + +Actions Files + + + The actions files are used to define what actions + Privoxy takes for which URLs, and thus determines + how ad images, cookies and various other aspects of HTTP content and + transactions are handled, and on which sites (or even parts thereof). There + are three such files included with Privoxy, + with slightly different purposes. default.action sets + the default policies. standard.action is used by + Privoxy and the web based editor to set + pre-defined values (and normally should not be edited). Local exceptions + are best done in user.action. The content of these + can all be viewed and edited from http://config.privoxy.org/show-status. + - - - - - forward .* proxy:8080 - - - + + Anything you want can be blocked, including ads, banners, or just some obnoxious + URL that you would rather not see is done here. Cookies can be accepted or rejected, or + accepted only during the current browser session (i.e. not written to disk), + content can be modified, JavaScripts tamed, user-tracking fooled, and much more. + See below for a complete list of available actions. - Also, we're told they insist on getting cookies and JavaScript, so you should - allow cookies from home.com. We consider JavaScript a potential security risk. - Java need not be enabled. + An actions file typically has sections. Near the top, aliases are + optionally defined (discussed below), then the default set of rules + which will apply universally to all sites and pages. And then below that, + exceptions to the defined universal policies. + + +Finding the Right Mix - In this example direct connections are made to all internal - domains, but everything else goes through Lucent's LPWA by way of the - company's SOCKS gateway to the Internet. + Note that some actions like cookie suppression + or script disabling may render some sites unusable, which rely on these + techniques to work properly. Finding the right mix of actions is not easy and + certainly a matter of personal taste. In general, it can be said that the more + aggressive your default settings (in the top section of the + actions file) are, the more exceptions for trusted sites you + will have to make later. If, for example, you want to kill popup windows per + default, you'll have to make exceptions from that rule for sites that you + regularly use and that require popups for actually useful content, like maybe + your bank, favorite shop, or newspaper. - - - - forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080 - forward my_company.com . - - - + We have tried to provide you with reasonable rules to start from in the + distribution actions files. But there is no general rule of thumb on these + things. There just are too many variables, and sites are constantly changing. + Sooner or later you will want to change the rules (and read this chapter again :). + + + +How to Edit - This is how you could set up a site that always uses SOCKS but no forwarders: + The easiest way to edit the actions files is with a browser by + using our browser-based editor, which can be reached from http://config.privoxy.org/show-status. - - - - forward-socks4a .* . firewall.my_company.com:1080 - - - + If you prefer plain text editing to GUIs, you can of course also directly edit the + the actions files. + - - An advanced example for network administrators: - + +How Actions are Applied to URLs - If you have links to multiple ISPs that provide various special content to - their subscribers, you can configure forwarding to pass requests to the - specific host that's connected to that ISP so that everybody can see all - of the content on all of the ISPs. + Actions files are divided into sections. There are special sections, + like the alias sections which will be discussed later. For now + let's concentrate on regular sections: They have a heading line (often split + up to multiple lines for readability) which consist of a list of actions, + separated by whitespace and enclosed in curly braces. Below that, there + is a list of URL patterns, each on a separate line. - This is a bit tricky, but here's an example: + To determine which actions apply to a request, the URL of the request is + compared to all patterns in this file. Every time it matches, the list of + applicable actions for the URL is incrementally updated, using the heading + of the section in which the pattern is located. If multiple matches for + the same URL set the same action differently, the last match wins. If not, + the effects are aggregated (e.g. a URL might match both the + +handle-as-image + and +block actions). + - - host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to - isp-b.com. host-a can run a Privoxy proxy with - forwarding like this: + You can trace this process by visiting http://config.privoxy.org/show-url-info. - - - - forward .* . - forward isp-b.com host-b:8118 - - - + More detail on this is provided in the Appendix, + Anatomy of an Action. + + + +Patterns - host-b can run a Privoxy proxy with forwarding - like this: + Generally, a pattern has the form <domain>/<path>, + where both the <domain> and <path> + are optional. (This is why the pattern / matches all URLs). - - - - - forward .* . - forward isp-a.com host-a:8118 - - - - + + + www.example.com/ + + + is a domain-only pattern and will match any request to www.example.com, + regardless of which document on that server is requested. + + + + + www.example.com + + + means exactly the same. For domain-only patterns, the trailing / may + be omitted. + + + + + www.example.com/index.html + + + matches only the single document /index.html + on www.example.com. + + + + + /index.html + + + matches the document /index.html, regardless of the domain, + i.e. on any web server. + + + + + index.html + + + matches nothing, since it would be interpreted as a domain name and + there is no top-level domain called .html. + + + + + +The Domain Pattern - Now, anyone on the Internet (including users on host-a - and host-b) can set their browser's proxy to either - host-a or host-b and be able to browse the content on isp-a or isp-b. + The matching of the domain part offers some flexible options: if the + domain starts or ends with a dot, it becomes unanchored at that end. + For example: + + + .example.com + + + matches any domain that ENDS in + .example.com + + + + + www. + + + matches any domain that STARTS with + www. + + + + + .example. + + + matches any domain that CONTAINS .example. + (Correctly speaking: It matches any FQDN that contains example as a domain.) + + + + + - Here's another practical example, for University of Kent at - Canterbury students with a network connection in their room, who - need to use the University's Squid web cache. + Additionally, there are wild-cards that you can use in the domain names + themselves. They work pretty similar to shell wild-cards: * + stands for zero or more arbitrary characters, ? stands for + any single character, you can define character classes in square + brackets and all of that can be freely mixed: + + + ad*.example.com + + + matches adserver.example.com, + ads.example.com, etc but not sfads.example.com + + + + + *ad*.example.com + + + matches all of the above, and then some. + + + + + .?pix.com + + + matches www.ipix.com, + pictures.epix.com, a.b.c.d.e.upix.com etc. + + + + + www[1-9a-ez].example.c* + + + matches www1.example.com, + www4.example.cc, wwwd.example.cy, + wwwz.example.com etc., but not + wwww.example.com. + + + + + + + +The Path Pattern + - - - - forward *. ssbcache.ukc.ac.uk:3128 # Use the proxy, except for: - forward .ukc.ac.uk . # Anything on the same domain as us - forward * . # Host with no domain specified - forward 129.12.*.* . # A dotted IP on our /16 network. - forward 127.*.*.* . # Loopback address - forward localhost.localdomain . # Loopback address - forward www.ukc.mirror.ac.uk . # Specific host - - - + Privoxy uses Perl compatible regular expressions + (through the PCRE library) for + matching the path. - If you intend to chain Privoxy and - squid locally, then chain as - browser -> squid -> privoxy is the recommended way. + There is an Appendix with a brief quick-start into regular + expressions, and full (very technical) documentation on PCRE regex syntax is available on-line + at http://www.pcre.org/man.txt. + You might also find the Perl man page on regular expressions (man perlre) + useful, which is available on-line at http://www.perldoc.com/perl5.6/pod/perlre.html. - Your squid configuration could then look like this: + Note that the path pattern is automatically left-anchored at the /, + i.e. it matches as if it would start with a ^ (regular expression speak + for the beginning of a line). - - - - # Define Privoxy as parent cache - - cache_peer 127.0.0.1 parent 8118 0 no-query - - # Define ACL for protocol FTP - acl FTP proto FTP - - # Do not forward ACL FTP to privoxy - always_direct allow FTP - - # Do not forward ACL CONNECT (https) to privoxy - always_direct allow CONNECT - - # Forward the rest to privoxy - never_direct allow all - - - + Please also note that matching in the path is case + INSENSITIVE by default, but you can switch to case + sensitive at any point in the pattern by using the + (?-i) switch: + www.example.com/(?-i)PaTtErN.* will match only + documents whose path starts with PaTtErN in + exactly this capitalization. + @@ -1934,985 +2733,1698 @@ Please choose from the following options: - -Windows GUI Options - + +Actions - Privoxy has a number of options specific to the - Windows GUI interface: + All actions are disabled by default, until they are explicitly enabled + somewhere in an actions file. Actions are turned on if preceded with a + +, and turned off if preceded with a -. So a + +action means do that action, e.g. + +block means please block the following URL + patterns. - - If activity-animation is set to 1, the - Privoxy icon will animate when - Privoxy is active. To turn off, set to 0. + + Actions are invoked by enclosing the action name in curly braces (e.g. + {+some_action}), followed by a list of URLs (or patterns that match URLs) to + which the action applies. There are three classes of actions: - - - - activity-animation 1 - - - - + - - If log-messages is set to 1, - Privoxy will log messages to the console - window: - + + + Boolean, i.e the action can only be on or + off. Examples: + + + + + + {+name} # enable this action + {-name} # disable this action + + + + + - - - - - log-messages 1 - - - - - - If log-buffer-size is set to 1, the size of the log buffer, - i.e. the amount of memory used for the log messages displayed in the - console window, will be limited to log-max-lines (see below). + + + Parameterized, e.g. +/-hide-user-agent{ Mozilla 1.0 }, + where some value is required in order to enable this type of action. + Examples: + + + + + + {+name{param}} # enable action and set parameter to param + {-name} # disable action (parameter) can be omitted + + + + + + + + + + Multi-value, e.g. {+/-add-header{Name: value}} or + {+/-send-wafer{name=value}}), where some value needs to be defined + in addition to simply enabling the action. Examples: + + + + + + {+name{param=value}} # enable action and set param to value + {-name{param=value}} # remove the parameter param completely + {-name} # disable this action totally and remove param too + + + + + + + - Warning: Setting this to 0 will result in the buffer to grow infinitely and - eat up all your memory! + If nothing is specified in any actions file, no actions are + taken. So in this case Privoxy would just be a + normal, non-blocking, non-anonymizing proxy. You must specifically enable the + privacy and blocking features you need (although the provided default actions + files will give a good starting point). - - - - log-buffer-size 1 - - - + Later defined actions always over-ride earlier ones. So exceptions + to any rules you make, should come in the latter part of the file (or + in a file that is processed later when using multiple actions files). For + multi-valued actions, the actions are applied in the order they are specified. + Actions files are processed in the order they are defined in + config (the default installation has three actions + files). It also quite possible for any given URL pattern to match more than + one action! + - log-max-lines is the maximum number of lines held - in the log buffer. See above. + The list of valid Privoxy actions are: - - - - - log-max-lines 200 - - - - - - - If log-highlight-messages is set to 1, - Privoxy will highlight portions of the log - messages with a bold-faced font: - - - - - - - log-highlight-messages 1 - - - - - - - The font used in the console window: - - - - - - - log-font-name Comic Sans MS - - - - - - - Font size used in the console window: - - - - - - - log-font-size 8 - - - - - - - show-on-task-bar controls whether or not - Privoxy will appear as a button on the Task bar - when minimized: - - - - - - show-on-task-bar 0 - - - - + + + + + - - If close-button-minimizes is set to 1, the Windows close - button will minimize Privoxy instead of closing - the program (close with the exit option on the File menu). - - - - - - close-button-minimizes 1 - - - - + - - The hide-console option is specific to the MS-Win console - version of Privoxy. If this option is used, - Privoxy will disconnect from and hide the - command console. - + +<emphasis>+add-header</emphasis> - - - - - #hide-console - - - - + + + Type: + + + Multi-value. + + + + + Typical uses: + + + Send a user defined HTTP header to the web server. + + + - - + + Possible values: + + + Any value is possible. Validity of the defined HTTP headers is not checked. + + + + + + Example usage: + + + {+add-header{X-User-Tracking: sucks}} + .example.com + + + - + + Notes: + + + This action may be specified multiple times, in order to define multiple + headers. This is rarely needed for the typical user. If you don't know what + HTTP headers are, you definitely don't need to worry about this + one. + + + + + - -The Actions File + +<emphasis>+block</emphasis> - - The default.action file (formerly - actionsfile or ijb.action) is used to define what actions - Privoxy takes, and thus determines how images, - cookies and various other aspects of HTTP content and transactions are - handled. Images can be anything you want, including ads, banners, or just - some obnoxious URL that you would rather not see. Cookies can be accepted - or rejected, or accepted only during the current browser session (i.e. - not written to disk). Changes to default.action should - be immediately visible to Privoxy without - the need to restart. - + + + Type: + + + Boolean. + + - - The easiest way to edit actions file is with a browser by - loading http://p.p/, and then select - Edit Actions List. A text editor can also be used. - + + Typical uses: + + + Used to block a URL from reaching your browser. The URL may be + anything, but is typically used to block ads or other obnoxious + content. + + + - - To determine which actions apply to a request, the URL of the request is - compared to all patterns in this file. Every time it matches, the list of - applicable actions for the URL is incrementally updated. You can trace - this process by visiting http://p.p/show-url-info. - + + Possible values: + + N/A + + + + + Example usage: + + + {+block} + .banners.example.com + .ads.r.us + + + + + Notes: + + + If a URL matches one of the blocked patterns, Privoxy + will intercept the URL and display its special BLOCKED page + instead. If there is sufficient space, a large red banner will appear with + a friendly message about why the page was blocked, and a way to go there + anyway. If there is insufficient space a smaller BLOCKED + page will appear without the red banner. + Click here + to view the default blocked HTML page (Privoxy must be running + for this to work as intended!). + - - There are four types of lines in this file: comments (begin with a - # character), actions, aliases and patterns, all of which are - explained below, as well as the configuration file syntax that - Privoxy understands. + + A very important exception is if the URL matches both + +block and +handle-as-image, + then it will be handled by + +set-image-blocker + (see below). It is important to understand this process, in order + to understand how Privoxy is able to deal with + ads and other objectionable content. + + + The +filter + action can also perform some of the + same functionality as +block, but by virtue of very + different programming techniques, and is most often used for different + reasons. + + + - + + - -URL Domain and Path Syntax - - Generally, a pattern has the form <domain>/<path>, where both the - <domain> and <path> part are optional. If you only specify a - domain part, the / can be left out: - - - - www.example.com - is a domain only pattern and will match any request to - www.example.com. - - - - www.example.com/ - means exactly the same. - - - - www.example.com/index.html - matches only the single - document /index.html on www.example.com. - + +<emphasis>+deanimate-gifs</emphasis> - - /index.html - matches the document /index.html, regardless of - the domain. - + + + Type: + + + Parameterized. + + - - index.html - matches nothing, since it would be - interpreted as a domain name and there is no top-level domain called - .html. - + + Typical uses: + + + To stop those annoying, distracting animated GIF images. + + + - - The matching of the domain part offers some flexible options: if the - domain starts or ends with a dot, it becomes unanchored at that end. - For example: - + + Possible values: + + + last or first + + + + + + Example usage: + + + {+deanimate-gifs{last}} + .example.com + + + - - .example.com - matches any domain that ENDS in - .example.com. - + + Notes: + + + De-animate all animated GIF images, i.e. reduce them to their last frame. + This will also shrink the images considerably (in bytes, not pixels!). If + the option first is given, the first frame of the animation + is used as the replacement. If last is given, the last + frame of the animation is used instead, which probably makes more sense for + most banner animations, but also has the risk of not showing the entire + last frame (if it is only a delta to an earlier frame). + + + - - www. - matches any domain that STARTS with - www. - + + - - Additionally, there are wild-cards that you can use in the domain names - themselves. They work pretty similar to shell wild-cards: * - stands for zero or more arbitrary characters, ? stands for - any single character. And you can define character classes in square - brackets and they can be freely mixed: - + + +<emphasis>+downgrade-http-version</emphasis> - - ad*.example.com - matches adserver.example.com, - ads.example.com, etc but not sfads.example.com. - + + + Type: + + + Boolean. + + - - *ad*.example.com - matches all of the above, and then some. - + + Typical uses: + + + +downgrade-http-version will downgrade HTTP/1.1 client requests to + HTTP/1.0 and downgrade the responses as well. + + + - - .?pix.com - matches www.ipix.com, - pictures.epix.com, a.b.c.d.e.upix.com, etc. - + + Possible values: + + + N/A + + + + + + Example usage: + + + {+downgrade-http-version} + .example.com + + + - - www[1-9a-ez].example.com - matches www1.example.com, - www4.example.com, wwwd.example.com, - wwwz.example.com, etc., but not - wwww.example.com. - + + Notes: + + + Use this action for servers that use HTTP/1.1 protocol features that + Privoxy doesn't handle well yet. HTTP/1.1 is + only partially implemented. Default is not to downgrade requests. This is + an infrequently needed action, and is used to help with rare problem sites only. + + + - - If Privoxy was compiled with - pcre support (default), Perl compatible regular expressions - can be used. See the pcre/docs/ directory or man - perlre (also available on http://www.perldoc.com/perl5.6/pod/perlre.html) - for details. A brief discussion of regular expressions is in the - Appendix. For instance: - + + - - /.*/advert[0-9]+\.jpe?g - would match a URL from any - domain, with any path that includes advert followed - immediately by one or more digits, then a . and ending in - either jpeg or jpg. So we match - example.com/ads/advert2.jpg, and - www.example.com/ads/banners/advert39.jpeg, but not - www.example.com/ads/banners/advert39.gif (no gifs in the - example pattern). - + + +<emphasis>+fast-redirects</emphasis> - - Please note that matching in the path is case - INSENSITIVE by default, but you can switch to case - sensitive at any point in the pattern by using the - (?-i) switch: - + + + Type: + + + Boolean. + + - - www.example.com/(?-i)PaTtErN.* - will match only - documents whose path starts with PaTtErN in - exactly this capitalization. - + + Typical uses: + + + The +fast-redirects action enables interception of + redirect requests from one server to another, which + are used to track users.Privoxy can cut off + all but the last valid URL in a redirect request and send a local redirect + back to your browser without contacting the intermediate site(s). + + + - + + Possible values: + + + N/A + + + + + + Example usage: + + + {+fast-redirects} + .example.com + + + - + + Notes: + + + Many sites, like yahoo.com, don't just link to other sites. Instead, they + will link to some script on their own server, giving the destination as a + parameter, which will then redirect you to the final target. URLs + resulting from this scheme typically look like: + http://some.place/some_script?http://some.where-else. + + + Sometimes, there are even multiple consecutive redirects encoded in the + URL. These redirections via scripts make your web browsing more traceable, + since the server from which you follow such a link can see where you go + to. Apart from that, valuable bandwidth and time is wasted, while your + browser ask the server for one redirect after the other. Plus, it feeds + the advertisers. + + + This is a normally on feature, and often requires exceptions + for sites that are sensitive to defeating this mechanism. + + + + + + +<emphasis>+filter</emphasis> - -Actions - - Actions are enabled if preceded with a +, and disabled if - preceded with a -. Actions are invoked by enclosing the - action name in curly braces (e.g. {+some_action}), followed by a list of - URLs to which the action applies. There are three classes of actions: - - - - - - - - Boolean (e.g. +/-block): - - - - - - {+name} # enable this action - {-name} # disable this action - - - - - + + + Type: + + + Parameterized. + + + + Typical uses: + + + Apply page filtering as defined by named sections of the + default.filter file to the specified site(s). + Filtering can be any modification of the raw + page content, including re-writing or deletion of content. + + + - - - parameterized (e.g. +/-hide-user-agent): - - - - - - {+name{param}} # enable action and set parameter to param - {-name} # disable action - - - - - - - - - Multi-value (e.g. {+/-add-header{Name: value}}, {+/-wafer{name=value}}): - - - - - - {+name{param}} # enable action and add parameter param - {-name{param}} # remove the parameter param - {-name} # disable this action totally - - - - - - - - - - - If nothing is specified in this file, no actions are taken. - So in this case Privoxy would just be a - normal, non-blocking, non-anonymizing proxy. You must specifically - enable the privacy and blocking features you need (although the - provided default default.action file will - give a good starting point). - - - - Later defined actions always over-ride earlier ones. For multi-valued - actions, the actions are applied in the order they are specified. - - - - The list of valid Privoxy actions are: - - - - - - - - Add the specified HTTP header, which is not checked for validity. - You may specify this many times to specify many different headers: - - - - - - +add-header{Name: value} - - - - - - - - - - Block this URL totally. In a default installation, a blocked - URL will result in bright red banner that says BLOCKED, - with a reason why it is being blocked. - - - - - - +block - - - - - - - - - - De-animate all animated GIF images, i.e. reduce them to their last frame. - This will also shrink the images considerably (in bytes, not pixels!). If - the option first is given, the first frame of the animation - is used as the replacement. If last is given, the last frame - of the animation is used instead, which probably makes more sense for most - banner animations, but also has the risk of not showing the entire last - frame (if it is only a delta to an earlier frame). - - - - - - +deanimate-gifs{last} - +deanimate-gifs{first} - - - - - - - - - +downgrade will downgrade HTTP/1.1 client requests to - HTTP/1.0 and downgrade the responses as well. Use this action for servers - that use HTTP/1.1 protocol features that - Privoxy doesn't handle well yet. HTTP/1.1 - is only partially implemented. Default is not to downgrade requests. - - - - - - +downgrade - - - - - + + Possible values: + + + +filter must include the name of one of the section identifiers + from default.filter (or whatever + filterfile is specified in config). + + + - - - Many sites, like yahoo.com, don't just link to other sites. Instead, they - will link to some script on their own server, giving the destination as a - parameter, which will then redirect you to the final target. URLs resulting - from this scheme typically look like: - http://some.place/some_script?http://some.where-else. - - - Sometimes, there are even multiple consecutive redirects encoded in the - URL. These redirections via scripts make your web browsing more traceable, - since the server from which you follow such a link can see where you go to. - Apart from that, valuable bandwidth and time is wasted, while your browser - ask the server for one redirect after the other. Plus, it feeds the - advertisers. - - - The +fast-redirects option enables interception of these - types of requests by Privoxy, who will cut off - all but the last valid URL in the request and send a local redirect back to - your browser without contacting the intermediate site(s). - - - - - - +fast-redirects - - - - - - - - - Apply the filters in the section_header - section of the default.filter file to the site(s). - default.filter sections are grouped according to like - functionality. - - - - - - - +filter{section_header} - - - - - - - Filter sections that are pre-defined in the supplied - default.filter include: - - -
+ + Example usage (from the current default.filter): + + + + +filter{html-annoyances}: Get rid of particularly annoying HTML abuse. + + + + + +filter{js-annoyances}: Get rid of particularly annoying JavaScript abuse + + - html-annoyances: Get rid of particularly annoying HTML abuse. + +filter{content-cookies}: Kill cookies that come in the HTML or JS content - js-annoyances: Get rid of particularly annoying JavaScript abuse + +filter{popups}: Kill all popups in JS and HTML - no-poups: Kill all popups in JS and HTML + +filter{frameset-borders}: Give frames a border and make them resizable - frameset-borders: Give frames a border + +filter{webbugs}: Squish WebBugs (1x1 invisible GIFs used for user tracking) - webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) + +filter{refresh-tags}: Kill automatic refresh tags (for dial-on-demand setups) - no-refresh: Automatic refresh sucks on auto-dialup lines + +filter{fun}: Text replacements for subversive browsing fun! - fun: Text replacements for subversive browsing fun! + +filter{nimda}: Remove Nimda (virus) code. - nimda: Remove (virus) Nimda code. + +filter{banners-by-size}: Kill banners by size (very efficient!) - banners-by-size: Kill banners by size + +filter{shockwave-flash}: Kill embedded Shockwave Flash objects - crude-parental: Kill all web pages that contain the words "sex" or "warez" + +filter{crude-parental}: Kill all web pages that contain the words "sex" or "warez" -
+ + - + + Notes: + + + This is potentially a very powerful feature! And requires a knowledge + of regular expressions if you want to roll your own. + Filtering operates on a line by line basis throughout the entire page. + + + Filtering requires buffering the page content, which may appear to + slow down page rendering since nothing is displayed until all content has + passed the filters. (It does not really take longer, but seems that way + since the page is not incrementally displayed.) This effect will be more + noticeable on slower connections. + + + Filtering can achieve some of the effects as the + +block + action, i.e. it can be used to block ads and banners. In the overall + scheme of things, filtering is one of the first things Privoxy + does with a web page. So other most other actions are applied to the + already filtered page. + + + - - - Block any existing X-Forwarded-for header, and do not add a new one: - - - - - - +hide-forwarded - - - - - + + - - - If the browser sends a From: header containing your e-mail - address, this either completely removes the header (block), or - changes it to the specified e-mail address. - - - - - - +hide-from{block} - +hide-from{spam@sittingduck.xqq} - - - - - + + + +<emphasis>+hide-forwarded-for-headers</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Block any existing X-Forwarded-for HTTP header, and do not add a new one. + + + + + + Possible values: + + + N/A + + + - - - Don't send the Referer: (sic) header to the web site. You - can block it, forge a URL to the same server as the request (which is - preferred because some sites will not send images otherwise) or set it to a - constant string of your choice. - - - - - - +hide-referer{block} - +hide-referer{forge} - +hide-referer{http://nowhere.com} - - - - - + + Example usage: + + + {+hide-forwarded-for-headers} + .example.com + + + + + + Notes: + + + It is fairly safe to leave this on. It does not seem to break many sites. + + + + + + + + + + +<emphasis>+hide-from-header</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + To block the browser from sending your email address in a From: + header. + + + + + + Possible values: + + + Keyword: block, or any user defined value. + + + - - - Alternative spelling of +hide-referer. It has the same - parameters, and can be freely mixed with, +hide-referer. - (referrer is the correct English spelling, however the HTTP - specification has a bug - it requires it to be spelled referer.) - - - - - - +hide-referrer{...} - - - - - + + Example usage: + + + {+hide-from-header{block}} + .example.com + + + - + + Notes: + + + The keyword block will completely remove the header + (not to be confused with the +block action). + Alternately, you can specify any value you prefer to send to the web + server. + + + + + + + + + + +<emphasis>+hide-referer</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + Don't send the Referer: (sic) HTTP header to the web site. + Or, alternately send a forged header instead. + + + + + + Possible values: + + + Prevent the header from being sent with the keyword, block. + Or, forge a URL to one from the same server as the request. + Or, set to user defined value of your choice. + + + + + + Example usage: + + + {+hide-referer{forge}} + .example.com + + + + + + Notes: + + + forge is the preferred option here, since some servers will + not send images back otherwise. + - Change the User-Agent: header so web servers can't tell your - browser type. Warning! This breaks many web sites. Specify the - user-agent value you want. Example, pretend to be using Netscape on - Linux: + +hide-referrer is an alternate spelling of + +hide-referer. It has the exact same parameters, and can be freely + mixed with, +hide-referer. (referrer is the + correct English spelling, however the HTTP specification has a bug - it + requires it to be spelled as referer.) - - - - - +hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)} - - - - - - + + - - - Treat this URL as an image. This only matters if it's also +blocked, - in which case a blocked image can be sent rather than a HTML page. - See +image-blocker{} below for the control over what is actually sent. - If you want invisible ads, they should be defined as - images and blocked. And also, - image-blocker should be set to blank. - - - - - - +image - - - - - + + + + + + +<emphasis>+hide-user-agent</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + To change the User-Agent: header so web servers can't tell + your browser type. Who's business is it anyway? + + + + + + Possible values: + + + Any user defined string. + + + - - Decides what to do with URLs that end up tagged with {+block - +image}, e.g an advertizement. There are five options. - -image-blocker will send a HTML blocked page, - usually resulting in a broken image icon. - - - -+image-blocker{blank} will send a 1x1 transparent GIF -image. And finally, +image-blocker{http://xyz.com} will send a -HTTP temporary redirect to the specified image. This has the advantage of the -icon being being cached by the browser, which will speed up the display. -+image-blocker{pattern} will send a checkboard type pattern - - - - - - - - - - +image-blocker{blank} - +image-blocker{pattern} - +image-blocker{http://p.p/send-banner} - - - - - + + Example usage: + + + {+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}} + .msn.com + + + + + + Notes: + + + Warning! This breaks many web sites that depend on this in order + to determine how the target browser will respond to various + requests. Use with caution. + + + + + + + + + +<emphasis>+handle-as-image</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + To define what Privoxy should treat + automatically as an image, and is an important ingredient of how + ads are handled. + + + + + + Possible values: + + + N/A + + + - - - By default (i.e. in the absence of a +limit-connect - action), Privoxy will only allow CONNECT - requests to port 443, which is the standard port for https as a - precaution. - + + Example usage: + + + {+handle-as-image} + /.*\.(gif|jpg|jpeg|png|bmp|ico) + + + + + + Notes: + + + This only has meaning if the URL (or pattern) also is + +blocked, in which case a user definable image can + be sent rather than a HTML page. This is integral to the whole concept of + ad blocking: the URL must match both a +block rule, + and +handle-as-image. + (See +set-image-blocker + below for control over what will actually be displayed by the browser.) + + + There is little reason to change the default definition for this action. + + + + + + + + + + +<emphasis>+set-image-blocker</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + Decide what to do with URLs that end up tagged with both + +block + and +handle-as-image, + e.g an advertisement. + + + + + + Possible values: + + + There are four available options: -set-image-blocker will send a HTML + blocked page, usually resulting in a broken + image icon. + +set-image-blocker{blank} will send a + 1x1 transparent GIF image. + +set-image-blocker{pattern} will send a + checkerboard type pattern (the default). And finally, + +set-image-blocker{http://xyz.com} will + send a HTTP temporary redirect to the specified image. This has the + advantage of the icon being being cached by the browser, which will speed + up the display. + + + - - The CONNECT methods exists in HTTP to allow access to secure websites - (https:// URLs) through proxies. It works very simply: the proxy - connects to the server on the specified port, and then short-circuits - its connections to the client and to the remote proxy. - This can be a big security hole, since CONNECT-enabled proxies can - be abused as TCP relays very easily. + + Example usage: + + + {+set-image-blocker{blank}} + .example.com + + + + + + Notes: + + + If you want invisible ads, they need to meet + criteria as matching both images and blocked + actions. And then, image-blocker should be set to + blank for invisibility. Note you cannot treat HTML pages as + images in most cases. For instance, frames require an HTML page to + display. So a frame that is an ad, typically cannot be treated as an image. + Forcing an image in this situation just will not work + reliably. + + + + + + + + + +<emphasis>+limit-connect</emphasis> + + + + Type: + + + Parameterized. + + + + + Typical uses: + + + By default, Privoxy only allows HTTP CONNECT + requests to port 443 (the standard, secure HTTPS port). Use + +limit-connect to disable this altogether, or to allow + more ports. + + + + + + Possible values: + + + Any valid port number, or port number range. + + + + + + Example usages: + + + + + + +limit-connect{443} # This is the default and need not be specified. + +limit-connect{80,443} # Ports 80 and 443 are OK. + +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100 and above 500 are OK. + + + + + + Notes: + + + The CONNECT methods exists in HTTP to allow access to secure websites + (https:// URLs) through proxies. It works very simply: the proxy connects + to the server on the specified port, and then short-circuits its + connections to the client and to the remote proxy. + This can be a big security hole, since CONNECT-enabled proxies can be + abused as TCP relays very easily. - If you want to allow CONNECT for more ports than this, or want to forbid CONNECT altogether, you can specify a comma separated list of ports and port ranges (the latter using dashes, with the minimum defaulting to 0 and - max to 65K): + max to 65K). - - - - - +limit-connect{443} # This is the default and need no be specified. - +limit-connect{80,443} # Ports 80 and 443 are OK. - +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100 - #and above 500 are OK. - - - + If you don't know what any of this means, there probably is no reason to + change this one. + + - + + + + + +<emphasis>+prevent-compression</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Prevent the specified websites from compressing HTTP data. + + + + + + Possible values: + + + N/A + + + - - - +no-compression prevents the website from compressing the - data. Some websites do this, which can be a problem for - Privoxy, since +filter, - +no-popup and +gif-deanimate will not work on - compressed data. This will slow down connections to those websites, - though. Default is nocompression is turned on. - + + Example usage: + + + {+prevent-compression} + .example.com + + + - - - - - +nocompression - - - - - + + Notes: + + + Some websites do this, which can be a problem for + Privoxy, since + +filter, + +kill-popups + and +gif-deanimate + will not work on compressed data. This will slow down connections to those + websites, though. Default typically is to turn + prevent-compression on. + + + + + + + + + +<emphasis>+session-cookies-only</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Allow cookies for the current browser session only. + + + + + + Possible values: + + + N/A + + + - - - If the website sets cookies, no-cookies-keep will make sure - they are erased when you exit and restart your web browser. This makes - profiling cookies useless, but won't break sites which require cookies so - that you can log in for transactions. Default: on. - - - - - - +no-cookies-keep - - - - - + + Example usage (disabling): + + + {-session-cookies-only} + .example.com + + + + + + Notes: + + + If websites set cookies, +session-cookies-only will make sure + they are erased when you exit and restart your web browser. This makes + profiling cookies useless, but won't break sites which require cookies so + that you can log in for transactions. This is generally turned on for all + sites, and is the recommended setting. + + + +prevent-*-cookies actions should be turned off as well (see + below), for +session-cookies-only to work. Or, else no cookies + will get through at all. For, persistent cookies that survive + across browser sessions, see below as well. + + + + + + + + + + +<emphasis>+prevent-reading-cookies</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Explicitly prevent the web server from reading any cookies on your + system. + + + + + + Possible values: + + + N/A + + + - - - Prevent the website from reading cookies: - - - - - - +no-cookies-read - - - - - + + Example usage: + + + {+prevent-reading-cookies} + .example.com + + + + + + Notes: + + + Often used in conjunction with +prevent-setting-cookies to + disable cookies completely. Note that + +session-cookies-only + requires these to both be disabled (or else it never gets any cookies to cache). + + + For persistent cookies to work (i.e. they survive across browser + sessions and reboots), all three cookie settings should be off + for the specified sites. + + + + + + + + + + +<emphasis>+prevent-setting-cookies</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Explicitly block the web server from storing cookies on your + system. + + + + + + Possible values: + + + N/A + + + - - - Prevent the website from setting cookies: - - - - - - +no-cookies-set - - - - - + + Example usage: + + + {+prevent-setting-cookies} + .example.com + + + + + + Notes: + + + Often used in conjunction with +prevent-reading-cookies to + disable cookies completely (see above). + + + + + + + + + + +<emphasis>+kill-popups<anchor id="kill-popups"></emphasis> + + + Type: + + + Boolean. + + + + + Typical uses: + + + Stop those annoying JavaScript pop-up windows! + + + + + + Possible values: + + + N/A + + + - - - Filter the website through a built-in filter to disable those obnoxious - JavaScript pop-up windows via window.open(), etc. The two alternative - spellings are equivalent. - - - - - - +no-popup - +no-popups - - - - - + + Example usage: + + + {+kill-popups} + .example.com + + + + + + Notes: + + + +kill-popups uses a built in filter to disable pop-ups + that use the window.open() function, etc. This is + one of the first actions processed by Privoxy + as it contacts the remote web server. This action is not always 100% reliable, + and is supplemented by +filter{popups}. + + + + + + + + + + + +<emphasis>+send-vanilla-wafer</emphasis> + + + + Type: + + + Boolean. + + + + + Typical uses: + + + Sends a cookie for every site stating that you do not accept any copyright + on cookies sent to you, and asking them not to track you. + + + + + + Possible values: + + + N/A + + + - - - This action only applies if you are using a jarfile - for saving cookies. It sends a cookie to every site stating that you do not - accept any copyright on cookies sent to you, and asking them not to track - you. Of course, this is a (relatively) unique header they could use to - track you. - - - - - - +vanilla-wafer - - - - - + + Example usage: + + + {+send-vanilla-wafer} + .example.com + + + + + + Notes: + + + This action only applies if you are using a jarfile + for saving cookies. Of course, this is a (relatively) unique header and + could conceivably be used to track you. + + + + + + + + + + +<emphasis>+send-wafer</emphasis> + + + + Type: + + + Multi-value. + + + + + Typical uses: + + + This allows you to send an arbitrary, user definable cookie. + + + + + + Possible values: + + + User specified cookie name and corresponding value. + + + - - - This allows you to add an arbitrary cookie. It can be specified multiple - times in order to add as many cookies as you like. - - - - - - +wafer{name=value} - - - - - + + Example usage: + + + {+send-wafer{name=value}} + .example.com + + + + + + Notes: + + + This can be specified multiple times in order to add as many cookies as you + like. + + + + + + + + + + +Actions Examples + + Note that the meaning of any of the above examples is reversed by preceding + the action with a -, in place of the +. Also, + that some actions are turned on in the default section of the actions file, + and require little to no additional configuration. These are just on. + But, other actions that are turned on the default section do + typically require exceptions to be listed in the latter sections of + one of our actions file. For instance, by default no URLs are + blocked (i.e. in the default definitions of + default.action). We need exceptions to this in order to + enable ad blocking in the lower sections. But we need to be very selective + about what we do block. + + + + Below is a liberally commented default.action file to + demonstrate how all the pieces come together. And to show how exceptions to + the default policies can be handled. This is followed by a + user.action with similar examples. + + + + + + + +# Settings -- Don't change! For internal Privoxy use ONLY. +{{settings}} +for-privoxy-version=3.0 + + +########################################################################## +# Aliases must be defined *before* they are used. These are +# easier to remember, and combine several actions into one. Once defined +# they can be used just like any built-in action. +########################################################################## + +# Some useful aliases. + -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies + +imageblock = +block +handle-as-image + +# Fragile sites should have the minimum changes: + fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ + -prevent-cookies -kill-popups + +# Shops should be allowed to set persistent cookies + shop = -filter -prevent-cookies -session-cookies-only + + +########################################################################## +# Begin default action settings. Anything in this section will match +# all URLs -- UNLESS we have exceptions that match defined below this +# section. We will show all potential actions here whether they are on +# or off. We could omit any disabled action if we wanted, since all +# actions are 'off' by default anyway. Shown for completeness only. +# Actions are enabled if preceded by a '+', otherwise they are disabled. +########################################################################## + { \ + -add-header \ + -block \ + -deanimate-gifs \ + -downgrade-http-version \ + +fast-redirects \ + +filter{html-annoyances} \ + +filter{js-annoyances} \ + -filter{content-cookies} \ + -filter{popups} \ + +filter{webbugs} \ + -filter{refresh-tags} \ + -filter{fun} \ + +filter{nimda} \ + +filter{banners-by-size} \ + -filter{shockwave-flash} \ + -filter{crude-prental} \ + +hide-forwarded-for-headers \ + +hide-from-header{block} \ + -hide-referrer \ + -hide-user-agent \ + -handle-as-image \ + +set-image-blocker{pattern} \ + -limit-connect \ + +prevent-compression \ + -session-cookies-only \ + -prevent-reading-cookies \ + -prevent-setting-cookies \ + -kill-popups \ + -send-vanilla-wafer \ + -send-wafer \ + } + / # forward slash will match *all* potential URL patterns. + +########################################################################## +# Default behavior is now set. Time for some exceptions to our +# default actions. +########################################################################## + +# These sites are very complex and require very minimal interference. +# We'll disable most actions with our 'fragile' alias. + {fragile} + .office.microsoft.com # surprise, surprise! + .windowsupdate.microsoft.com + + +# Shopping sites - not as fragile but require some special +# handling. We still want to block ads, and we will allow +# persistant cookies via the 'shop' alias. + {shop} + .quietpc.com + .worldpay.com # for quietpc.com + .jungle.com + .scan.co.uk + + +# These sites require pop-ups too :( We'll combine our 'shop' +# alias with two other actions into one rule to allow all popups. + {shop -no-popups -filter{popups}} + .dabs.com + .overclockers.co.uk + + +# The 'Fast-redirects' action breaks some sites. Disable this action +# for these known sensitive sites. + {-fast-redirects} + www.ukc.ac.uk/cgi-bin/wac\.cgi\? + login.yahoo.com + edit.europe.yahoo.com + .google.com + .altavista.com/.*(like|url|link):http + .altavista.com/trans.*urltext=http + .nytimes.com + + +# Define which file types will be treated as images. Important +# for ad blocking. + {+handle-as-image} + /.*\.(gif|jpe?g|png|bmp|ico) + + +# Now lets list some domains that are known ad generators. And +# our alias here will block these as well as force them to be +# treated as images. This combination of actions is important +# for ad blocking. What the browser will show instead is +# determined by the setting of +set-image-blocker + {+imageblock} + ar.atwola.com + .ad.doubleclick.net + .a.yimg.com/(?:(?!/i/).)*$ + .a[0-9].yimg.com/(?:(?!/i/).)*$ + bs*.gsanet.com + bs*.einets.com + .qkimg.net + ad.*.doubleclick.net + + +# These will just simply be blocked. They will generate the BLOCKED +# banner page, if matched. Heavy use of wildcards and regular +# expressions in this example. + {+block} + ad*. + .*ads. + banner?. + count*. + /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?) + /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/ + .hitbox.com + + +# The above block section will catch some sites we DO NOT want +# blocked via the wildcards and regular expressions. Now let's set +# exceptions to the exceptions so the good guys get better treatment. + {-block} + advogato.org + adsl. + ad[ud]*. + advice. +# Let's just trust all .edu top level domains. + .edu + www.ugu.com/sui/ugu/adv +# We'll need to access to path names containing 'download' + .*downloads. + /downloads/ +# 'adv' is for globalintersec and means advanced, not advertisement + www.globalintersec.com/adv + + +# Don't filter *anything* from our friends at sourceforge. +# Notice we don't have to name the individual filter +# identifiers -- we just turn them all off in one fell swoop. + {-filter} + .sourceforge.net + + + + + - + + So far we are painting with a broad brush by setting general policies. + The above would be a reasonable starting point for many situations. Now, + we want to be more specific and have customized rules that are more suitable + to our personal habits and preferences. These should be placed in + user.action, which is parsed after all other + actions files. So any settings here, will have the last word. - The meaning of any of the above is reversed by preceding the action with a - -, in place of the +. + Now an example of a few things that one might do with a user.action + file. This is where user preferences are defined. + + + + + Some examples: - Turn off cookies by default, then allow a few through for specified sites: + Turn off cookies by default, then allow a few through for specified sites + (showing an excerpt from the default section of an actions + file ONLY): - # Turn off all persistent cookies - { +no-cookies-read } - { +no-cookies-set } - # Allow cookies for this browser session ONLY - { +no-cookies-keep } + # Excerpt only: + # Allow cookies to and from the server, but + # for this browser session ONLY + { + # other actions normally listed here... + -prevent-setting-cookies \ + -prevent-reading-cookies \ + +session-cookies-only \ + } + / # match all URLs # Exceptions to the above, sites that benefit from persistent cookies - { -no-cookies-read } - { -no-cookies-set } - { -no-cookies-keep } - .javasoft.com - .sun.com - .yahoo.com - .msdn.microsoft.com - .redhat.com - - # Alternative way of saying the same thing - {-no-cookies-set -no-cookies-read -no-cookies-keep} - .sourceforge.net - .sf.net + # that are saved from one browser session to the next. + { -session-cookies-only } + .javasoft.com + .sun.com + .yahoo.com + .msdn.microsoft.com + .redhat.com + @@ -2926,13 +4438,17 @@ icon being being cached by the browser, which will speed up the display. - # Turn them off! - {+fast-redirects} + # Turn them off (excerpt only)! + { + # other actions normally listed here... + +fast-redirects + } + / # match all URLs # Reverse it for these two sites, which don't work right without it. {-fast-redirects} - www.ukc.ac.uk/cgi-bin/wac\.cgi\? - login.yahoo.com + www.ukc.ac.uk/cgi-bin/wac\.cgi\? + login.yahoo.com @@ -2940,32 +4456,38 @@ icon being being cached by the browser, which will speed up the display. Turn on page filtering according to rules in the defined sections - of refilterfile, and make one exception for - sourceforge: + of default.filter, and make one exception for + Sourceforge: - # Run everything through the filter file, using only the + # Run everything through the filter file, using only certain # specified sections: - +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\ - +filter{webbugs} +filter{nimda} +filter{banners-by-size} + { + # other actions normally listed here... + +filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}\ + +filter{webbugs} +filter{nimda} +filter{banners-by-size} + } + / #match all URLs - # Then disable filtering of code from sourceforge! + # Then disable filtering of code from all sourceforge domains! {-filter} - .cvs.sourceforge.net + .sourceforge.net - Now some URLs that we want blocked, ie we won't see them. - Many of these use regular expressions that will expand to match multiple - URLs: - + Now some URLs that we want blocked (normally generates + the blocked banner). Typically, the block + action is off by default in the upper section of an actions file, then enabled + against certain URLs and patterns in the lower part of the file. Many of these use regular expressions that will expand to match multiple + URLs: @@ -2973,48 +4495,16 @@ icon being being cached by the browser, which will speed up the display. # Blocklist: {+block} - /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g)) - /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/]) + ad*. + .*ads. + banner?. + count*. + /.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?) + /(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/ + .hitbox.com /.*/(ng)?adclient\.cgi /.*/(plain|live|rotate)[-_.]?ads?/ - /.*/(sponsor)s?[0-9]?/ - /.*/_?(plain|live)?ads?(-banners)?/ /.*/abanners/ - /.*/ad(sdna_image|gifs?)/ - /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe) - /.*/adbanners/ - /.*/adserver - /.*/adstream\.cgi - /.*/adv((er)?ts?|ertis(ing|ements?))?/ - /.*/banner_?ads/ - /.*/banners?/ - /.*/banners?\.cgi/ - /.*/cgi-bin/centralad/getimage - /.*/images/addver\.gif - /.*/images/marketing/.*\.(gif|jpe?g) - /.*/popupads/ - /.*/siteads/ - /.*/sponsor.*\.gif - /.*/sponsors?[0-9]?/ - /.*/advert[0-9]+\.jpg - /Media/Images/Adds/ - /ad_images/ - /adimages/ - /.*/ads/ - /bannerfarm/ - /grafikk/annonse/ - /graphics/defaultAd/ - /image\.ng/AdType - /image\.ng/transactionID - /images/.*/.*_anim\.gif # alvin brattli - /ip_img/.*\.(gif|jpe?g) - /rotateads/ - /rotations/ - /worldnet/ad\.cgi - /cgi-bin/nph-adclick.exe/ - /.*/Image/BannerAdvertising/ - /.*/ad-bin/ - /.*/adlib/server\.cgi /autoads/ @@ -3025,11 +4515,12 @@ icon being being cached by the browser, which will speed up the display. Note that many of these actions have the potential to cause a page to misbehave, possibly even not to display at all. There are many ways a site designer may choose to design his site, and what HTTP header - content he may depend on. There is no way to have hard and fast rules - for all sites. See the Appendix - for a brief example on troubleshooting actions. - + content, and other criteria, he may depend on. There is no way to have hard + and fast rules for all sites. See the Appendix for a brief example on troubleshooting + actions. + @@ -3037,7 +4528,7 @@ icon being being cached by the browser, which will speed up the display. - + Aliases Custom actions, known to Privoxy @@ -3047,9 +4538,10 @@ icon being being cached by the browser, which will speed up the display. { or }. But please use only a- z, 0-9, +, and -. Alias names are not case sensitive, and - must be defined before anything else in the - default.actionfile ! And there can only be one set of - aliases defined. + must be defined before other actions in the + actions file! And there can only be one set of aliases + defined per file. Each actions file may have its own aliases, but they are + only visible within that file. @@ -3060,19 +4552,18 @@ icon being being cached by the browser, which will speed up the display. - # Useful customer aliases we can use later. These must come first! + # Useful custom aliases we can use later. These must come first! {{alias}} - +no-cookies = +no-cookies-set +no-cookies-read - -no-cookies = -no-cookies-set -no-cookies-read - fragile = -block -no-cookies -filter -fast-redirects -hide-referer -no-popups - shop = -no-cookies -filter -fast-redirects - +imageblock = +block +image - - #For people who don't like to type too much: ;-) - c0 = +no-cookies - c1 = -no-cookies - c2 = -no-cookies-set +no-cookies-read - c3 = +no-cookies-set -no-cookies-read + +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies + -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies + fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups + shop = -prevent-cookies -filter -fast-redirects + +imageblock = +block +handle-as-image + + # Aliases defined from other aliases, for people who don't like to type + # too much: ;-) + c0 = +prevent-cookies + c1 = -prevent-cookies #... etc. Customize to your heart's content. @@ -3081,7 +4572,9 @@ icon being being cached by the browser, which will speed up the display. Some examples using our shop and fragile - aliases from above: + aliases from above. These would appear in the lower sections of an + actions file as exceptions to the default actions (as defined in the + upper section): @@ -3091,26 +4584,32 @@ icon being being cached by the browser, which will speed up the display. # These sites are very complex and require # minimal interference. {fragile} - .office.microsoft.com - .windowsupdate.microsoft.com - .nytimes.com + .office.microsoft.com + .windowsupdate.microsoft.com + .nytimes.com - # Shopping sites - still want to block ads. + # Shopping sites - but we still want to block ads. {shop} - .quietpc.com - .worldpay.com # for quietpc.com - .jungle.com - .scan.co.uk - - # These shops require pop-ups - {shop -no-popups} - .dabs.com - .overclockers.co.uk + .quietpc.com + .worldpay.com # for quietpc.com + .scan.co.uk + + # These shops require pop-ups also + {shop -kill-popups} + .dabs.com + .overclockers.co.uk + + The shop and fragile aliases are often used for + problem sites that require most actions to be disabled + in order to function properly. + + + @@ -3118,7 +4617,7 @@ icon being being cached by the browser, which will speed up the display. - + The Filter File Any web page can be dynamically modified with the filter file. This @@ -3127,12 +4626,18 @@ icon being being cached by the browser, which will speed up the display. default.filter, located in the config directory. + + This is potentially a very powerful feature, and requires knowledge of both + regular expression and HTML in order create custom + filters. But, there are a number of useful filters included with + Privoxy for many common situations. + + The included example file is divided into sections. Each section begins with the FILTER keyword, followed by the identifier for that section, e.g. FILTER: webbugs. Each section performs a similar type of filtering, such as html-annoyances. - @@ -3211,6 +4716,32 @@ icon being being cached by the browser, which will speed up the display. + + + +The +filter Action + + Filters are enabled with the +filter action from within + one of the actions files. +filter requires one parameter, which + should match one of the section identifiers in the filter file itself. Example: + + + + + +filter{html-annoyances} + + + + + This would activate that particular filter. Similarly, +filter + can be turned off for selected sites as: + -filter{html-annoyances}. Remember, all actions are off by + default, unless they are explicity enabled in one of the actions files. + + + + @@ -3226,7 +4757,13 @@ icon being being cached by the browser, which will speed up the display. pages, such as a 404 Not Found error page, it uses the appropriate template. On Linux, BSD, and Unix, these are located in /etc/privoxy/templates by default. These may be - customized, if desired. + customized, if desired. cgi-style.css is + used to control the HTML attributes (fonts, etc). + + + The default Blocked banner page with the bright red top + banner, is called just blocked. This + may be customized or replaced with something else if desired. @@ -3241,44 +4778,10 @@ icon being being cached by the browser, which will speed up the display. Contacting the Developers, Bug Reporting and Feature Requests - -We value your feedback. However, to provide you with the best support, -please note: - - - - Use the Sourceforge support forum to get - help. - - Submit bugs only thru our Sourceforge bug - forum. -Make sure that the bug has not already been submitted. Please try to -verify that it is a Privoxy bug, and not -a browser or site bug first. If you are using your own custom configuration, -please try the stock configs to see if the problem is a configuration -related bug. And if not using the latest development snapshot, please -try the latest one. Or even better, CVS sources. - - - - Submit feature requests only thru our Sourceforge feature request forum. - - - - - - -For any other issues, feel free to use the mailing lists. - - - - Anyone interested in actively participating in development and related - discussions can join the appropriate mailing list - here. - Archives are available here too. - + + &contacting; + @@ -3286,24 +4789,10 @@ For any other issues, feel free to use the Copyright and History - -License - - Privoxy is free software; you can - redistribute it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - - - This program is distributed in the hope that it will be useful, but WITHOUT - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS - FOR A PARTICULAR PURPOSE. See the GNU General Public License for more - details, which is available from the Free Software Foundation, - Inc, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - +Copyright + + ©right; + @@ -3311,74 +4800,18 @@ For any other issues, feel free to use the -History - - Privoxy is evolved, and derived from, - the Internet Junkbuster, with many - improvments and enhancements over the original. - - - - Junkbuster was originally written by Anonymous - Coders and Junkbuster's - Corporation, and was released as free open-source software under the - GNU GPL. Stefan - Waldherr made many improvements, and started the SourceForge project - Privoxy to rekindle development. There are now several active - developers contributing. The last stable release of - Junkbuster was v2.0.2, which has now - grown whiskers ;-). - - +History + + &history; + - -See also - - - - -   http://sourceforge.net/projects/ijbswa, - the Project Page for Privoxy. - - - - -   http://www.privoxy.org/ - - - - -   http://p.p/ - - - - -   http://www.junkbusters.com/ht/en/cookies.html - - - - -   http://www.waldherr.org/junkbuster/ - - - - -   http://privacy.net/analyze/ - - - - -  http://www.squid-cache.org/ - - - - +See Also + + &seealso; + @@ -3435,72 +4868,79 @@ For any other issues, feel free to use the - Show information about the current configuration: + Show information about the current configuration, including viewing and + editing of actions files:
@@ -3687,7 +5128,7 @@ For any other issues, feel free to use the
- - - - Edit the actions list file: - -
- - http://config.privoxy.org/edit-actions - -
- - These may be bookmarked for quick reference. + These may be bookmarked for quick reference. See next. Bookmarklets - Here are some bookmarklets to allow you to easily access a - mini version of this page. They are designed for MS Internet - Explorer, but should work equally well in Netscape, Mozilla, and other - browsers which support JavaScript. They are designed to run directly from - your bookmarks - not by clicking the links below (although that will work for - testing). + Below are some bookmarklets to allow you to easily access a + mini version of some of Privoxy's + special pages. They are designed for MS Internet Explorer, but should work + equally well in Netscape, Mozilla, and other browsers which support + JavaScript. They are designed to run directly from your bookmarks - not by + clicking the links below (although that should work for testing). To save them, right-click the link and choose Add to Favorites (IE) or Add Bookmark (Netscape). You will get a warning that the bookmark may not be safe - just click OK. Then you can run the - Bookmarklet directly from your favourites/bookmarks. For even faster access, + Bookmarklet directly from your favorites/bookmarks. For even faster access, you can put them on the Links bar (IE) or the Personal Toolbar (Netscape), and run them with a single click. @@ -3775,31 +5205,43 @@ For any other issues, feel free to use the Enable Privoxy + Privoxy - Enable + + + + + + Privoxy - Disable - Disable Privoxy + Privoxy - Toggle Privoxy (Toggles between enabled and disabled) - Toggle Privoxy (Toggles between enabled and disabled) + Privoxy- View Status - View Privoxy Status + Privoxy - Submit Filter Feedback + + Credit: The site which gave me the general idea for these bookmarklets is www.bookmarklets.com. They @@ -3812,116 +5254,254 @@ For any other issues, feel free to use the +Chain of Events + + Let's take a quick look at the basic sequence of events when a web page is + requested by your browser and Privoxy is on duty: + + + + + + + First, your web browser requests a web page. The browser knows to send + the request to Privoxy, which will in turn, + relay the request to the remote web server after passing the following + tests: + + + + + Privoxy traps any request for its own internal CGI + pages (e.g http://p.p/) and sends the CGI page back to the browser. + + + + + Next, Privoxy checks to see if the URL + matches any +block patterns. If + so, the URL is then blocked, and the remote web server will not be contacted. + +handle-as-image + is then checked and if it does not match, an + HTML BLOCKED page is sent back. Otherwise, if it does match, + an image is returned. The type of image depends on the setting of +set-image-blocker + (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere). + + + + + Untrusted URLs are blocked. If URLs are being added to the + trust file, then that is done. + + + + + If the URL pattern matches the +fast-redirects action, + it is then processed. Unwanted parts of the requested URL are stripped. + + + + + Now the rest of the client browser's request headers are processed. If any + of these match any of the relevant actions (e.g. +hide-user-agent, + etc.), headers are suppressed or forged as determined by these actions and + their parameters. + + + + + Now the web server starts sending its response back (i.e. typically a web page and related + data). + + + + + First, the server headers are read and processed to determine, among other + things, the MIME type (document type) and encoding. The headers are then + filtered as deterimed by the + +prevent-setting-cookies, + +session-cookies-only, + and +downgrade-http-version + actions. + + + + + If the +kill-popups + action applies, and it is an HTML or JavaScript document, the popup-code in the + response is filtered on-the-fly as it is received. + + + + + If a +filter + or +deanimate-gifs + action applies (and the document type fits the action), the rest of the page is + read into memory (up to a configurable limit). Then the filter rules (from + default.filter) are processed against the buffered + content. Filters are applied in the order they are specified in the + default.filter file. Animated GIFs, if present, are + reduced to either the first or last frame, depending on the action + setting.The entire page, which is now filtered, is then sent by + Privoxy back to your browser. + + + If neither +filter + or +deanimate-gifs + matches, then Privoxy passes the raw data through + to the client browser as it becomes available. + + + + + As the browser receives the now (probably filtered) page content, it + reads and then requests any URLs that may be embedded within the page + source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g. + frames), sounds, etc. For each of these objects, the browser issues a new + request. And each such request is in turn processed as above. Note that a + complex web page may have many such embedded URLs. + + + + + + + + + Anatomy of an Action - The way Privoxy applies actions - to any given URL can be complex, and not always so easy to understand what - is happening. And sometimes we need to be able to see - just what Privoxy is doing. Especially, - if something Privoxy is doing is causing - us a problem inadvertantly. It can be a little daunting to look at - the actions files themselves, since they tend to be filled with + The way Privoxy applies + actions + and filters + to any given URL can be complex, and not always so + easy to understand what is happening. And sometimes we need to be able to + see just what Privoxy is + doing. Especially, if something Privoxy is doing + is causing us a problem inadvertently. It can be a little daunting to look at + the actions and filters files themselves, since they tend to be filled with regular expressions whose consequences are not always - so obvious. Privoxy provides the + so obvious. + + + + One quick test to see if Privoxy is causing a problem + or not, is to disable it temporarily. This should be the first troubleshooting + step. See the Bookmarklets section on a quick + and easy way to do this (be sure to flush caches afterward!). + + + + Privoxy also provides the http://config.privoxy.org/show-url-info page that can show us very specifically how actions are being applied to any given URL. This is a big help for troubleshooting. - + First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell us how the current configuration will handle it. This will not - help with filtering effects from the default.filter file! It - also will not tell you about any other URLs that may be embedded within the - URL you are testing. For instance, images such as ads are expressed as URLs - within the raw page source of HTML pages. So you will only get info for the - actual URL that is pasted into the prompt area -- not any sub-URLs. If you - want to know about embedded URLs like ads, you will have to dig those out of - the HTML source. Use your browser's View Page Source option - for this. + help with filtering effects (i.e. the +filter action) from + the default.filter file since this is handled very + differently and not so easy to trap! It also will not tell you about any other + URLs that may be embedded within the URL you are testing. For instance, images + such as ads are expressed as URLs within the raw page source of HTML pages. So + you will only get info for the actual URL that is pasted into the prompt area + -- not any sub-URLs. If you want to know about embedded URLs like ads, you + will have to dig those out of the HTML source. Use your browser's View + Page Source option for this. Or right click on the ad, and grab the + URL. - Let's look at an example, google.com, - one section at a time: + Let's try an example, google.com, + and look at it one section at a time: - System default actions: - - { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter - -hide-forwarded -hide-from -hide-referer -hide-user-agent -image - -image-blocker -limit-connect -no-compression -no-cookies-keep - -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer } - - - - - - This is the top section, and only tells us of the compiled in defaults. This - is basically what Privoxy would do if there - were not any actions defined, i.e. it does nothing. Every action - is disabled. This is not particularly informative for our purposes here. OK, - next section: - + Matches for http://google.com: - - +--- File standard --- +(no matches in this file) - Matches for http://google.com: +--- File default --- - { -add-header -block +deanimate-gifs -downgrade +fast-redirects - +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} - +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} - +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} - -hide-user-agent -image +image-blocker{blank} +no-compression - +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups - -vanilla-wafer -wafer } - / +{ -add-header -block +deanimate-gifs{last} -downgrade-http-version +fast-redirects + -filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental} + +filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies} + +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size} + +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge} + -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect + +prevent-compression +session-cookies-only -prevent-reading-cookies + -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer } +/ - { -no-cookies-keep -no-cookies-read -no-cookies-set } - .google.com + { -session-cookies-only } + .google.com { -fast-redirects } - .google.com + .google.com - +--- File user --- +(no matches in this file) + - This is much more informative, and tells us how we have defined our - actions, and which ones match for our example, - google.com. The first grouping shows our default - settings, which would apply to all URLs. If you look at your actions - file, this would be the section just below the aliases section - near the top. This applies to all URLs as signified by the single forward - slash -- /. - + This tells us how we have defined our + actions, and + which ones match for our example, google.com. The first listing + is any matches for the standard.action file. No hits at + all here on standard. Then next is default, or + our default.action file. The large, multi-line listing, + is how the actions are set to match for all URLs, i.e. our default settings. + If you look at your actions file, this would be the section + just below the aliases section near the top. This will apply to + all URLs as signified by the single forward slash at the end of the listing + -- /. - These are the default actions we have enabled. But we can define additional - actions that would be exceptions to these general rules, and then list - specific URLs that these exceptions would apply to. Last match wins. - Just below this then are two explict matches for .google.com. - The first is negating our various cookie blocking actions (i.e. we will allow - cookies here). The second is allowing fast-redirects. Note - that there is a leading dot here -- .google.com. This will - match any hosts and sub-domains, in the google.com domain also, such as - www.google.com. So, apparently, we have these actions defined - somewhere in the lower part of our actions file, and - google.com is referenced in these sections. + But we can define additional actions that would be exceptions to these general + rules, and then list specific URLs (or patterns) that these exceptions would + apply to. Last match wins. Just below this then are two explicit matches for + .google.com. The first is negating our previous cookie setting, + which was for +session-cookies-only + (i.e. not persistent). So we will allow persistent cookies for google. The + second turns off any + +fast-redirects + action, allowing this to take place unmolested. Note that there is a leading + dot here -- .google.com. This will match any hosts and + sub-domains, in the google.com domain also, such as + www.google.com. So, apparently, we have these two actions + defined somewhere in the lower part of our default.action + file, and google.com is referenced somewhere in these latter + sections. + + + Then, for our user.action file, we again have no hits. - And now we pull it altogether in the bottom section and summarize how - Privoxy is appying all its actions + And finally we pull it all together in the bottom section and summarize how + Privoxy is applying all its actions to google.com: @@ -3930,16 +5510,20 @@ For any other issues, feel free to use the - { +block +image } + { +block +handle-as-image } .ad.doubleclick.net - { +block +image } + { +block +handle-as-image } ad*. - { +block +image } + { +block +handle-as-image } .doubleclick.net - - + We'll just show the interesting part here, the explicit matches. It is - matched three different times. Each as an +block +image, + matched three different times. Each as an +block +handle-as-image, which is the expanded form of one of our aliases that had been defined as: - +imageblock. (Aliases are defined in the - first section of the actions file and typically used to combine more + +imageblock. (Aliases are defined in + the first section of the actions file and typically used to combine more than one action.) @@ -3976,9 +5560,13 @@ For any other issues, feel free to use the +block + and an + +handle-as-image. + The custom alias +imageblock just simplifies the process and make + it more readable. @@ -3991,27 +5579,26 @@ For any other issues, feel free to use the + - Now the page displays ;-) - + Now the page displays ;-) Be sure to flush your browser's caches when + making such changes. Or, try using Shift+Reload. But now what about a situation where we get no explicit matches like we did with: - - { -block } - /adsl - - + { +block +handle-as-image } + /ads + @@ -4061,14 +5645,13 @@ For any other issues, feel free to use the + + + + + This would probably be most appropriately put in user.action, + for local site exceptions. + + + + {fragile} is an alias that disables most actions. This can be + used as a last resort for problem sites. Remember to flush caches! If this + still does not work, you will have to go through the remaining actions one by + one to find which one(s) is causing the problem. @@ -4106,6 +5700,118 @@ For any other issues, feel free to use the