X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=70979575fb88926678af78c778ecfdfc7464049f;hp=b719408c62d70d34bf933cbe1cfb3ab8d7c28c12;hb=d74ec2c8f9726f42df2ce1e45749d74dee43b781;hpb=dd4046ea96cf9ea4edbe96a49545e86bc3aa5f13 diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index b719408c..70979575 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -1,57 +1,105 @@ - + + + + + + + + + + + + + + + + + + + + + + + + + +]> - -
-Privoxy User Manual -$Id: user-manual.sgml,v 1.55 2002/03/24 16:08:08 swa Exp $ +Privoxy &p-version; User Manual + + + + + + Copyright &my-copy; 2001 - 2004 by + Privoxy Developers + + + +$Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $ + + - - - - By: Privoxy Developers - - - + + + + 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 + + +]]> + - 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. + 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://ijbswa.sourceforge.net/user-manual/. + 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,151 +109,40 @@ You can find the latest version of the user manual at Introduction +Introduction - Privoxy is a web proxy with advanced - filtering capabilities for protecting privacy, filtering and modifying 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 documentation is included with the current &p-status; version of + Privoxy, v.&p-version;soon ;-)]]>. + + - 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 ;-) - - - - 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). - - - - - - 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; + @@ -215,2981 +152,6368 @@ 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. - - tar xzvf ijb_source_* [.tgz or .tar.gz] - cd ijb_source_2.9.11_beta - + Note: If you have a previous Junkbuster or + Privoxy installation on your system, you + will need to remove it. On some platforms, this may be done for you as part + of their installation procedure. (See below for your platform). In any case + be sure to backup your old configuration if it is valuable to + you. See the note to + upgraders section below. + +Binary Packages - For retrieving the current CVS sources, you'll need the CVS - package installed first. To download CVS source: +How to install the binary packages depends on your operating system: - - - 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 - - + +Red Hat, SuSE and Conectiva RPMs - This will create a directory named current/, which will - contain the source tree. + RPMs can be installed with rpm -Uvh privoxy-&p-version;-1.rpm, + and will use /etc/privoxy for the location + of configuration files. - Then, in either case, to build from tarball/CVS source: + 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. - - ./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) - + 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. - For Redhat and SuSE Linux RPM packages, see below. + 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. - - - + -Red Hat +Debian - To build Redhat RPM packages, install source as above. Then: + DEBs can be installed with apt-get install privoxy, + and will use /etc/privoxy for the location of + configuration files. + - - - autoheader - autoconf - ./configure - make redhat-dist - - + +Windows - This will create both binary and src RPMs in the usual places. Example: + 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. + - -    /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm - - -    /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.rpm - + +Solaris, NetBSD, FreeBSD, HP-UX - To install, of course: + 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. + - - - rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm - - + +OS/2 - This will place the Privoxy configuration - files in /etc/privoxy/, and log files in - /var/log/privoxy/. - - - + First, make sure that no previous installations of + Junkbuster and / or + Privoxy are left on your + system. Check that no Junkbuster + or Privoxy objects are in + your startup folder. - -SuSE - - To build SuSE RPM packages, install source as above. Then: - - autoheader - autoconf - ./configure - make suse-dist - + 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. - This will create both binary and src RPMs in the usual places. Example: + The directory you choose to install Privoxy + into will contain all of the configuration files. + + +Mac OSX -    /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm - - -    /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.rpm + Unzip the downloaded file (you can either double-click on the file + from the finder, or from the desktop if you downloaded it there). + Then, double-click on the package installer icon named + Privoxy.pkg + and follow the installation process. + Privoxy will be installed in the folder + /Library/Privoxy. + It will start automatically whenever you start up. To prevent it from + starting automatically, remove or rename the folder + /Library/StartupItems/Privoxy. - - To install, of course: + To start Privoxy by hand, double-click on + StartPrivoxy.command in the + /Library/Privoxy folder. + Or, type this command in the Terminal: - - - rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm - + + /Library/Privoxy/StartPrivoxy.command + - - This will place the Privoxy configuration - files in /etc/privoxy/, and log files in - /var/log/privoxy/. + You will be prompted for the administrator password. - - - + -OS/2 - - - +AmigaOS - 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. + 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. + + +Gentoo - The directory you choose to install Privoxy - into will contain all of the configuration files. + Gentoo source packages (Ebuilds) for Privoxy are + contained in the Gentoo Portage Tree (they are not on the download page, + but there is a Gentoo section, where you can see when a new + Privoxy Version is added to the Portage Tree). - - 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. + Before installing Privoxy under Gentoo just do + first emerge rsync to get the latest changes from the + Portage tree. With emerge privoxy you install the latest + version. - - 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. + Configuration files are in /etc/privoxy, the + documentation is in /usr/share/doc/privoxy-&p-version; + and the Log directory is in /var/log/privoxy. + - -Windows -Click-click. (I need help on this. Not a clue here. Also for -configuration section below. HB.) - - +Building from Source - -Other - Some quick notes on other Operating Systems. + The most convenient way to obtain the Privoxy sources + is to download the source tarball from our project + page. - 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. + 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. + - - - - - - - - -<application>Privoxy</application> Configuration - - All Privoxy configuration is kept - 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. - - - - - - - -Controlling <application>Privoxy</application> with Your Web Browser - - Privoxy can be reached by the special - URL http://p.p/ (or alternately - http://ijbswa.sourceforge.net/config/), - which is an internal page. You will see the following section: - - + +&buildsource; + + + +Keeping your Installation Up-to-Date - - -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 - - + As user feedback comes in and development continues, we will make updated versions + of both the main actions file (as a separate + package) and the software itself (including the actions file) available for + download. - 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 - 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. + If you wish to receive an email notification whenever we release updates of + Privoxy or the actions file, subscribe + to our announce mailing list, ijbswa-announce@lists.sourceforge.net. - 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 - causing the problem or not. Privoxy continues - to run as a proxy in this case, but all filtering is disabled. - + In order not to lose your personal changes and adjustments when updating + to the latest default.action file we strongly + recommend that you use user.action for your + customization of Privoxy. See the Chapter on actions files for details. - - + + - - -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. - - + +What's New in this Release - 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): + There are many new features in Privoxy &p-version; + : - - The main configuration file is named config - on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt - on Windows. + Mulitiple filter files can now be specifed in config. - + + + + + There are a number of new actions: + + + + + + + + content-type-overwrite + + + + + crunch-client-header + + + + + crunch-if-none-match + + + + + crunch-server-header + + + + + fast-redirects + + + + + force-text-mode + + + + + handle-as-empty-document + + + + + hide-accept-language + + + + + hide-content-disposition + + + + + hide-if-modified-since + + + + + hide-referrer + + + + + inspect-jpegs + + + + + overwrite-last-modified + + + + + redirect + + + + + treat-forbidden-connects-like-blocks + + + + + + + - 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.) + MS-Windows versions can now be installed and + started as a service. - + - 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. + In addition, there are various bug fixes and enhancements, including + error pages are no longer cached, better DNS error handling, and logging + improvements. - + + - - 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 - Privoxy in order for the changes to take - effect. Privoxy should detect such changes - automatically. - + + + +Note to Upgraders - 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. + A quick list of things to be aware of before upgrading from earlier + versions of Privoxy: - + + - + + + Some installers may remove earlier versions completely, including + configuration files. Save any important configuration files! + + + + + What constitutes a default configuration has changed, + and you may want to review which actions are on by + default. This is primarily a matter of emphasis, but some features + you may have been used to, may now be off by default. + + + + + + + + Some installers may not automatically start + Privoxy after installation. + + - -The Main Configuration File - - Again, the main configuration file is named config on - Linux/Unix/BSD and OS/2, and config.txt on Windows. - Configuration lines consist of an initial keyword followed by a list of - values, all separated by whitespace (any number of spaces or tabs). For - example: + + + + +Quickstart to Using <application>Privoxy</application> - - - - blockfile blocklist.ini - - - - + - - Indicates that the blockfile is named blocklist.ini. (A - default installation does not use this.) - + + + Install Privoxy. See the Installation Section below for platform specific + information. + + - - A # indicates a comment. Any part of a - line following a # is ignored, except if - the # is preceded by a - \. - + + + Advanced users and those who want to offer Privoxy + service to more than just their local machine should check the main config file, especially the security-relevant options. These are + off by default. + + - - 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). - + + + Start Privoxy, if the installation program has + not done this already (may vary according to platform). See the section + Starting Privoxy. + + - - Long lines can be continued on the next line by using a - \ as the very last character. - + + + Set your browser to use Privoxy as HTTP and + HTTPS (SSL) proxy by setting the proxy configuration for address of + 127.0.0.1 and port 8118. + (Junkbuster and earlier versions of + Privoxy used port 8000.) See the section Starting Privoxy below + for more details on this. + + - - There are various aspects of Privoxy behavior - that can be tuned. - + + + Flush your browser's disk and memory caches, to remove any cached ad images. + If using Privoxy to manage cookies, you should + remove any currently stored cookies too. + + + + + A default installation should provide a reasonable starting point for + most. There will undoubtedly be occasions where you will want to adjust the + configuration, but that can be dealt with as the need arises. Little + to no initial configuration is required in most cases. + + + See the Configuration section for more + configuration options, and how to customize your installation. + next section for a quick + introduction to how Privoxy blocks ads and + banners.]]> + + - + + + If you experience ads that slipped through, innocent images that are + blocked, or otherwise feel the need to fine-tune + Privoxy's behaviour, take a look at the actions files. As a quick start, you might + find the richly commented examples + helpful. You can also view and edit the actions files through the web-based user interface. The + Appendix Anatomy of an + Action has hints how to debug actions that + misbehave. + + - -Defining Other Configuration Files + + + For easy access to Privoxy's most important controls, drag the provided + Bookmarklets into your browser's + personal toolbar. + + - - 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. - + + + Please see the section Contacting the + Developers on how to report bugs or problems with websites or to get + help. + + - - 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. + + + Now enjoy surfing with enhanced control, comfort and privacy! + + + + - - 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: - + + +Quickstart to Ad Blocking + - - - - confdir /etc/privoxy # No trailing /, please. - - - + Ad blocking is but one of Privoxy's + array of features. Many of these features are for the technically minded advanced + user. But, ad and banner blocking is surely common ground for everybody. - - - The directory where all logging (i.e. logfile and - jarfile) takes place. No trailing - /, please: + + This section will provide a quick summary of ad blocking so + you can get up to speed quickly without having to read the more extensive + information provided below, though this is highly recommended. - - - - - logdir /var/log/privoxy - - - + First a bit of a warning ... blocking ads is much like blocking SPAM: the + more aggressive you are about it, the more likely you are to block + things that were not intended. So there is a trade off here. If you want + extreme ad free browsing, be prepared to deal with more + problem sites, and to spend more time adjusting the + configuration to solve these unintended consequences. In short, there is + not an easy way to eliminate all ads. Either take + the easy way and settle for most ads blocked with the + default configuration, or jump in and tweak it for your personal surfing + habits and preferences. - - Note that all file specifications below are relative to - the above two directories! + Secondly, a brief explanation of Privoxy's + actions. Actions in this context, are + the directives we use to tell Privoxy to perform + some task relating to HTTP transactions (i.e. web browsing). We tell + Privoxy to take some action. Each + action has a unique name and function. While there are many potential + actions in Privoxy's + arsenal, only a few are used for ad blocking. Actions, and action + configuration files, are explained in depth below. - - 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. + Actions are specified in Privoxy's configuration, + followed by one or more URLs to which the action should apply. URLs + can actually be URL type patterns that use + wildcards so they can apply potentially to a range of similar URLs. The + actions, together with the URL patterns are called a section. - - - - - actionsfile default.action - - - + When you connect to a website, the full URL will either match one or more + of the sections as defined in Privoxy's configuration, + or not. If so, then Privoxy will perform the + respective actions. If not, then nothing special happens. Furthermore, web + pages may contain embedded, secondary URLs that your web browser will + use to load additional components of the page, as it parses the + original page's HTML content. An ad image for instance, is just an URL + embedded in the page somewhere. The image itself may be on the same server, + or a server somewhere else on the Internet. Complex web pages will have many + such embedded URLs. - 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 - :-/ + The actions we need to know about for ad blocking are: block, handle-as-image, and + set-image-blocker: - 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. - - + + + + + block - this action stops + any contact between your browser and any URL patterns that match this + action's configuration. It can be used for blocking ads, but also anything + that is determined to be unwanted. By itself, it simply stops any + communication with the remote server and sends Privoxy's + own built-in BLOCKED page instead to let you now what has happened. + + - - - - - filterfile default.filter - - - - + + + handle-as-image - + tells Privoxy to treat this URL as an image. + Privoxy's default configuration already does this + for all common image types (e.g. GIF), but there are many situations where this + is not so easy to determine. So we'll force it in these cases. This is particularly + important for ad blocking, since only if we know that it's an image of + some kind, can we replace it with an image of our choosing, instead of the + Privoxy BLOCKED page (which would only result in + a broken image icon). There are some limitations to this + though. For instance, you can't just brute-force an image substitution for + an entire HTML page in most situations. + + - - 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. - + + + set-image-blocker - tells + Privoxy what to display in place of an ad image that + has hit a block rule. For this to come into play, the URL must match a + block action somewhere in the + configuration, and, it must also match an + handle-as-image action. + + + The configuration options on what to display instead of the ad are: + + + +    pattern - a checkerboard pattern, so that an ad + replacement is obvious. This is the default. + + + + +    blank - A very small empty GIF image is displayed. + This is the so-called invisible configuration option. + + + + +    http://<URL> - A redirect to any image anywhere + of the user's choosing (advanced usage). + + + - - 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. + The quickest way to adjust any of these settings is with your browser through + the special Privoxy editor at http://config.privoxy.org/show-status + (shortcut: http://p.p/show-status). This + is an internal page, and does not require Internet access. Select the + appropriate actions file, and click + Edit. It is best to put personal or + local preferences in user.action since this is not + meant to be overwritten during upgrades, and will over-ride the settings in + other files. Here you can insert new actions, and URLs for ad + blocking or other purposes, and make other adjustments to the configuration. + Privoxy will detect these changes automatically. - Default: Log to the a file named logfile. - Comment out to disable logging. + A quick and simple step by step example: - - - - 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. - + + + Right click on the ad image to be blocked, then select + Copy Link Location from the + pop-up menu. + + + + + Set your browser to + http://config.privoxy.org/show-status + + + + + Find user.action in the top section, and click + on Edit: + - - - - - #jarfile jarfile - - - + + +
Actions Files in Use + + + + + + [ Screenshot of Actions Files in Use ] + + +
+ + + + + + You should have a section with only + block listed under + Actions:. + If not, click a Insert new section below + button, and in the new section that just appeared, click the + Edit button right under the word Actions:. + This will bring up a list of all actions. Find + block near the top, and click + in the Enabled column, then Submit + just below the list. + + + + + Now, in the block actions section, + click the Add button, and paste the URL the + browser got from Copy Link Location. + Remove the http:// at the beginning of the URL. Then, click + Submit (or + OK if in a pop-up window). + + + + + Now go back to the original page, and press SHIFT-Reload + (or flush all browser caches). The image should be gone now. + + + + - 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. + This is a very crude and simple example. There might be good reasons to use a + wildcard pattern match to include potentially similar images from the same + site. For a more extensive explanation of patterns, and + the entire actions concept, see the Actions + section. - - - - #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. + For advanced users who want to hand edit their config files, you might want + to now go to the Actions Files Tutorial. + The ideas explained therein also apply to the web-based editor. - - - - - trust-info-url http://www.your-site.com/why_we_block.html - trust-info-url http://www.your-site.com/what_we_allow.html - - - - + - + - - - -Other Configuration Options - + +Starting <application>Privoxy</application> - This part of the configuration file contains options that control how - Privoxy operates. + Before launching Privoxy for the first time, you + will want to configure your browser(s) to use + Privoxy as a HTTP and HTTPS proxy. The default is + 127.0.0.1 (or localhost) for the proxy address, and port 8118 (earlier versions + used port 8000). This is the one configuration step that must be done! - - 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. + Please note that Privoxy can only proxy HTTP and + HTTPS traffic. It will not work with FTP or other protocols. - - - - - #admin-address fill@me.in.please - - - - + + +
Proxy Configuration (Mozilla) + + + + + + [ Screenshot of Mozilla Proxy Configuration ] + + +
+ + - - 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. + + With Firefox, this can be set under: + + + + + Tools + |_ + Options + |_ + General + |_ + Connection Settings + |_ + Manual Proxy Configuration + - - - - - 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). + + With Netscape (and + Mozilla), this can be set under: - - 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: - + + + + Edit + |_ + Preferences + |_ + Advanced + |_ + Proxies + |_ + HTTP Proxy + - - - - listen-address 192.168.0.1:8118 - - - + For Internet Explorer: - - If you want it to listen on all addresses (including the outside - connection): - + + + + Tools + |_ + Internet Properties + |_ + Connections + |_ + LAN Settings + - - - - listen-address :8118 - - - + Then, check Use Proxy and fill in the appropriate info + (Address: 127.0.0.1, Port: 8118). Include HTTPS (SSL), if you want HTTPS + proxy support too. - 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). + After doing this, flush your browser's disk and memory caches to force a + 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! - 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. + Privoxy itself is typically started by specifying the + main configuration file to be used on the command line. If no configuration + file is specified on the command line, Privoxy + will look for a file named config in the current + directory. Except on Win32 where it will try config.txt. + +Red Hat and Conectiva - - - - 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 - - - + We use a script. Note that Red Hat does not start Privoxy upon booting per + default. It will use the file /etc/privoxy/config as + its main configuration file. - - It is highly recommended that you enable ERROR - reporting (debug 8192), at least until v3.0 is released. + + # /etc/rc.d/init.d/privoxy start + + + +Debian - The reporting of FATAL errors (i.e. ones which crash - Privoxy) is always on and cannot be disabled. + We use a script. Note that Debian starts Privoxy upon booting per + default. It will use the file + /etc/privoxy/config as its main configuration + file. - - If you want to use CLF (Common Log Format), you should set debug - 512 ONLY, do not enable anything else. + + # /etc/init.d/privoxy start + + + +SuSE - Multiple debug directives, are OK - they're logical-OR'd - together. +We use a script. It will use the file /etc/privoxy/config +as its main configuration file. Note that SuSE starts Privoxy upon booting +your PC. - - - - - debug 15 # same as setting the first 4 listed above - - - + + # rcprivoxy start + + + +Windows - Default: +Click on the Privoxy Icon to start Privoxy. If no configuration file is + specified on the command line, Privoxy will look + for a file named config.txt. Note that Windows will + automatically start Privoxy upon booting you PC. + + +Solaris, NetBSD, FreeBSD, HP-UX and others - - - - debug 1 # URLs - debug 4096 # Info - debug 8192 # Errors - *we highly recommended enabling this* - - - +Example Unix startup command: - - 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. + + # /usr/sbin/privoxy /etc/privoxy/config + + + +OS/2 - - - - #single-threaded - - - + During installation, Privoxy is configured to + start automatically when the system restarts. You can start it manually by + double-clicking on the Privoxy icon in the + Privoxy folder. + + +Mac OSX - toggle allows you to temporarily disable all - Privoxy's filtering. Just set toggle - 0. + During installation, Privoxy is configured to + start automatically when the system restarts. To start Privoxy by hand, + double-click on the StartPrivoxy.command icon in the + /Library/Privoxy folder. Or, type this command + in the Terminal: - - 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. + + /Library/Privoxy/StartPrivoxy.command + - - toggle 1 means Privoxy runs - normally, toggle 0 means that - Privoxy becomes a non-anonymizing non-blocking - proxy. Default: 1 (on). + You will be prompted for the administrator password. + + + +AmigaOS - - - - toggle 1 - - - + 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). + + +Gentoo - 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. + A script is again used. It will use the file /etc/privoxy/config + as its main configuration file. - - 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. + + /etc/init.d/privoxy start + - - - - - buffer-limit 4069 - - - + Note that Privoxy is not automatically started at + boot time by default. You can change this with the rc-update + command. + + + + rc-update add privoxy default + + - - 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. - + - - - - - -Access Control List (ACL) - 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. + 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. - 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. + 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 + can be adjusted by pointing your browser to + 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.) - Summary -- if using an ACL: + In fact, various aspects of Privoxy + 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 actions file + editor mentioned above, Privoxy can also + be turned on and off (toggled) from this page. - - - Client must have permission to receive service. - - - - - LAST match in ACL wins. - - - - - Default behavior is to deny service. - - - - The syntax for an entry in the Access Control List is: + 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. - - - - ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ] - - - + 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. - Where the individual fields are: + 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. - - - - - ACTION = permit-access or deny-access - - SRC_ADDR = client hostname or dotted IP address - SRC_MASKLEN = number of bits in the subnet mask for the source - - DST_ADDR = server or forwarder hostname or dotted IP address - DST_MASKLEN = number of bits in the subnet mask for the target - - - - - - - - The field separator (FS) is whitespace (space or tab). - +--> + + +Command Line Options - 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). + Privoxy may be invoked with the following + command-line options: - Here are a few examples to show how the ACL features work: - + - - localhost is OK -- no DST_ADDR implies that - ALL destination addresses are OK: - + + + --version + + + Print version info and exit. Unix only. + + + + + --help + + + Print short usage info and exit. Unix only. + + + + + --no-daemon + + + Don't become a daemon, i.e. don't fork and become process group + leader, and don't detach from controlling tty. Unix only. + + + + + --pidfile FILE + + + + On startup, write the process ID to FILE. 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. + + + + + --user USER[.GROUP] + + + + After (optionally) writing the PID file, assume the user ID of + USER, and if included the GID of GROUP. Exit if the + privileges are not sufficient to do so. Unix only. + + + + + --chroot + + + + Before changing to the user ID given in the --user option, + chroot to that user's home directory, i.e. make the kernel pretend to the Privoxy + process that the directory tree starts there. If set up carefully, this can limit + the impact of possible vulnerabilities in Privoxy to the files contained in that hierarchy. + Unix only. + + + + + configfile + + + If no configfile is included on the command line, + 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. If no config file is found, + Privoxy will fail to start. + + - - - - - permit-access localhost - - - + - - A silly example to illustrate permitting any host on the class-C subnet with - Privoxy to go anywhere: - + - - - - - permit-access www.privoxy.com/24 - - - - + - - Except deny one particular IP address from using it at all: - + - - - - - deny-access ident.privoxy.com - - - - - - You can also specify an explicit network address and subnet mask. - Explicit addresses do not have to be resolved to be used. - + +<application>Privoxy</application> Configuration + + 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. + - - - - - permit-access 207.153.200.0/24 - - - - - - A subnet mask of 0 matches anything, so the next line permits everyone. - + + +Controlling <application>Privoxy</application> with Your Web Browser - - - - permit-access 0.0.0.0/0 - - - - + 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: - - Note, you cannot say: - - - - - permit-access .org - - - - + + + +     Privoxy Menu - - to allow all *.org domains. Every IP address listed must resolve fully. - + + +         ▪  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 + + +         ▪  Documentation + + + + - - 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: - - - - - 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 - - - + This should be self-explanatory. Note the first item leads to an editor for the + actions files, 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. - 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. + Toggle Privoxy On or Off is handy for sites that might + 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 manipulation is disabled, i.e. + Privoxy acts like a normal forwarding proxy. There + is even a toggle Bookmarklet offered, so + that you can toggle Privoxy with one click from + your browser. - + - - -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. - + + +Configuration Files Overview - 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. + 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. - 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 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: - The syntax of each line is: - + - - - - - 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] - - - - + + + The main configuration file is named config + on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt + on Windows. This is a required file. + + - - If http_proxy_host is ., then requests are not forwarded to a - HTTP proxy but are made directly to the web servers. - + + + default.action (the main actions file) + is used to define which actions relating to banner-blocking, images, pop-ups, + content modification, cookie handling etc should be applied by default. It also defines many + exceptions (both positive and negative) from this default set of actions that enable + Privoxy to selectively eliminate the junk, and only the junk, on + as many websites as possible. + + + 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 (which you will most probably want + to define sooner or later) are probably best applied in + user.action, where you can preserve them across + upgrades. standard.action is 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. + + - - Lines are checked in sequence, and the last match wins. - + + + Filter files (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. + default.filter includes various filters made + available for use by the developers. Some are much more intrusive than + others, and all should be used with caution. You may define additional + filter files in config as you can with + actions files. We suggest user.filter for any + locally defined filters or customizations. + + - - 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: + - - - - forward .* . # implicit - - - + All files use the # character to denote a + comment (the rest of the line will be ignored) and 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. - In the following common configuration, everything goes to Lucent's LPWA, - except SSL on port 443 (which it doesn't handle): + The actions files and filter files + can use Perl style regular expressions for + maximum flexibility. - - - - forward .* lpwa.com:8000 - forward :443 . - - - + After making any changes, there is no need to restart + Privoxy in order for the changes to take + 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. + - - 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 - - - - - - - (NOTE: the syntax for specifying target_domain has changed since the - previous paragraph was written -- it will not work now. More information - is welcome.) + 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. +]]> - - 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: - + + + + + &config; + - - - - - forward .* proxy:8080 - - - - - - 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. - + - - 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. - - - - - - forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080 - forward my_company.com . - - - - - - This is how you could set up a site that always uses SOCKS but no forwarders: - + - - - - - forward-socks4a .* . firewall.my_company.com:1080 - - - - +Actions Files - An advanced example for network administrators: + The actions files are used to define what actions + Privoxy takes for which URLs, and thus determine + 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 differing purposes: + + + + + + + default.action - is the primary action file + that sets the initial values for all actions. It is intended to + provide a base level of functionality for + Privoxy's array of features. So it is + a set of broad rules that should work reasonably well for users everywhere. + This is the file that the developers are keeping updated, and making available to users. + + + + + user.action - is intended to be for local site + preferences and exceptions. As an example, if your ISP or your bank + has specific requirements, and need special handling, this kind of + thing should go here. This file will not be upgraded. + + + + + standard.action - is used by the web based editor, + to set various pre-defined sets of rules for the default actions section + in default.action. These have increasing levels of + aggressiveness and have no influence on your browsing unless + you select them explicitly in the editor. It is not recommend + to edit this file. + + + The default profiles, and their associated actions, as pre-defined in + standard.action are: + + + Default Configurations + + + + + + + + Feature + Cautious + Medium + Adventuresome + + + + + + + + + + + + + + Ad-blocking by URL + yes + yes + yes + + + + Ad-filtering by size + yes + yes + yes + + + + GIF de-animation + no + yes + yes + + + + Referer forging + no + yes + yes + + + + Cookie handling + none + session-only + kill + + + + Pop-up killing + unsolicited + unsolicited + all + + + + Fast redirects + no + no + yes + + + + HTML taming + yes + yes + yes + + + + JavaScript taming + yes + yes + yes + + + + Web-bug killing + yes + yes + yes + + + + Fun text replacements + no + no + yes + + + + Image tag reordering + no + no + yes + + + + Ad-filtering by link + no + no + yes + + + + Demoronizer + no + no + yes + + + + + +
+ + + + + + + + The list of actions files to be used are defined in the main configuration + file, and are processed in the order they are defined (e.g. + default.action is typically process before + user.action). The content of these can all be viewed and + edited from http://config.privoxy.org/show-status. + + + + An actions file typically has multiple sections. If you want to use + aliases in an actions file, you have to place the (optional) + alias section at the top of that file. + Then comes the default set of rules which will apply universally to all + sites and pages (be very careful with using such a + universal set in user.action or any other actions file after + default.action, because it will override the result + from consulting any previous file). And then below that, + exceptions to the defined universal policies. You can regard + user.action as an appendix to default.action, + with the advantage that is a separate file, which makes preserving your + personal settings across Privoxy upgrades easier. - - 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 can be used to block 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), content can be modified, JavaScripts tamed, user-tracking + fooled, and much more. See below for a complete list + of actions. + + +Finding the Right Mix - This is a bit tricky, but here's an example: + Note that some actions, like cookie suppression + or script disabling, may render some sites unusable that rely on these + techniques to work properly. Finding the right mix of actions is not always 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 crunch all cookies per + default, you'll have to make exceptions from that rule for sites that you + regularly use and that require cookies for actually useful puposes, like maybe + your bank, favorite shop, or newspaper. - - 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: + 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 - - - - forward .* . - forward isp-b.com host-b:8118 - - - + 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. + The editor allows both fine-grained control over every single feature on a + per-URL basis, and easy choosing from wholesale sets of defaults like + Cautious, Medium or Adventuresome. + Warning: the Adventuresome setting is not only more aggressive, + but includes settings that are fun and subversive, and which some may find of + dubious merit! - host-b can run a Privoxy proxy with forwarding - like this: + If you prefer plain text editing to GUIs, you can of course also directly edit the + the actions files. Look at default.action which is richly + commented. + - - - - - forward .* . - forward isp-a.com host-a:8118 - - - - + +How Actions are Applied to URLs - 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. + 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. - 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. + To determine which actions apply to a request, the URL of the request is + compared to all patterns in each action file 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 a regular section with + a heading line of { + +handle-as-image }, + then later another one with just { + +block }, resulting + in both actions to apply. - - - - 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 - - - + You can trace this process for any given URL by visiting http://config.privoxy.org/show-url-info. - If you intend to chain Privoxy and - squid locally, then chain as - browser -> squid -> privoxy is the recommended way. + More detail on this is provided in the Appendix, + Anatomy of an Action. + - - Your squid configuration could then look like this: + + +Patterns + + As mentioned, Privoxy uses patterns + to determine what actions might apply to which sites and pages your browser + attempts to access. These patterns use wild card type + pattern matching to achieve a high degree of + flexibility. This allows one expression to be expanded and potentially match + against many similar patterns. - + - - - - # 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 - - - + Generally, a Privoxy pattern has the form + <domain>/<path>, where both the + <domain> and <path> are + optional. (This is why the special / pattern matches all + URLs). Note that the protocol portion of the URL pattern (e.g. + http://) should not be included in + the pattern. This is assumed already! - - - + + + 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 - -Windows GUI Options - - Privoxy has a number of options specific to the - Windows GUI interface: - - - - If activity-animation is set to 1, the - Privoxy icon will animate when - Privoxy is active. To turn off, set to 0. + 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: - - - - - activity-animation 1 - - - - + + + .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.) + + + + - If log-messages is set to 1, - Privoxy will log messages to the console - window: + 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: - - - - - log-messages 1 - - - - + + + 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. + + + + - - 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). - + - - Warning: Setting this to 0 will result in the buffer to grow infinitely and - eat up all your memory! - + - - - - - log-buffer-size 1 - - - - - - log-max-lines is the maximum number of lines held - in the log buffer. See above. - + +The Path Pattern - - - - log-max-lines 200 - - - + Privoxy uses Perl compatible regular expressions + (through the PCRE library) for + matching the path. - If log-highlight-messages is set to 1, - Privoxy will highlight portions of the log - messages with a bold-faced font: + 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. - - - - log-highlight-messages 1 - - - + 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). - The font used in the console window: + 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. + - - - - - 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: - + + +Actions - - - - show-on-task-bar 0 - - - - + 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 URLs that match the + following patterns, and -block means don't + block URLs that match the following patterns, even if +block + previously applied. - - 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 - - - + + Again, actions are invoked by placing them on a line, enclosed in curly braces and + separated by whitespace, like in + {+some-action -some-other-action{some-parameter}}, + followed by a list of URL patterns, one per line, to which they apply. + Together, the actions line and the following pattern lines make up a section + of the actions file. - - 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. + + There are three classes of actions: - - - - #hide-console - - - - - - - - - + + + + Boolean, i.e the action can only be enabled or + disabled. Syntax: + + + + +name # enable action name + -name # disable action name + + + Example: +block + + - - -The Actions File + + + Parameterized, where some value is required in order to enable this type of action. + Syntax: + + + + +name{param} # enable action and set parameter to param, + # overwriting parameter from previous match if necessary + -name # disable action. The parameter can be omitted + + + Note that if the URL matches multiple positive forms of a parameterized action, + the last match wins, i.e. the params from earlier matches are simply ignored. + + + Example: +hide-user-agent{ Mozilla 1.0 } + + + + + + Multi-value. These look exactly like parameterized actions, + but they behave differently: If the action applies multiple times to the + same URL, but with different parameters, all the parameters + from all matches are remembered. This is used for actions + that can be executed for the same request repeatedly, like adding multiple + headers, or filtering through multiple filters. Syntax: + + + + +name{param} # enable action and add param to the list of parameters + -name{param} # remove the parameter param from the list of parameters + # If it was the last one left, disable the action. + -name # disable this action completely and remove all parameters from the list + + + Examples: +add-header{X-Fun-Header: Some text} and + +filter{html-annoyances} + + - - The default.action file (formerly - actionsfile) 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. + - 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. + 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). - 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. + 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 pattern and thus more than one set of actions! - + - 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. - + The list of valid Privoxy actions are: - - -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. - + - - /index.html - matches the document /index.html, regardless of - the domain. - + +add-header - - index.html - matches nothing, since it would be - interpreted as a domain name and there is no top-level domain called - .html. - + + + Typical use: + + Confuse log analysis, custom applications + + - - 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: - + + Effect: + + + Sends a user defined HTTP header to the web server. + + + - - .example.com - matches any domain that ENDS in - .example.com. - + + Type: + + + Multi-value. + + + + + Parameter: + + + Any string value is possible. Validity of the defined HTTP headers is not checked. + It is recommended that you use the X- prefix + for custom headers. + + + + + + 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. + + + - - www. - matches any domain that STARTS with - www. - + + Example usage: + + + +add-header{X-User-Tracking: sucks} + + + + + - - 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: - - - ad*.example.com - matches adserver.example.com, - ads.example.com, etc but not sfads.example.com. - + + +block - - *ad*.example.com - matches all of the above, and then some. - + + + Typical use: + + Block ads or other obnoxious content + + - - .?pix.com - matches www.ipix.com, - pictures.epix.com, a.b.c.d.e.upix.com, etc. - + + Effect: + + + Requests for URLs to which this action applies are blocked, i.e. the requests are not + forwarded to the remote server, but answered locally with a substitute page or image, + as determined by the handle-as-image + and set-image-blocker actions. + + + - - 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. - + + Type: + + + Boolean. + + - - 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: - + + Parameter: + + N/A + + + + + Notes: + + + Privoxy sends a special BLOCKED page + for requests to blocked pages. This page contains links to find out why the request + was blocked, and a click-through to the blocked content (the latter only if compiled with the + force feature enabled). The BLOCKED page adapts to the available + screen space -- it displays full-blown if space allows, or miniaturized and text-only + if loaded into a small frame or window. If you are using Privoxy + right now, you can take a look at the + BLOCKED + page. + + + A very important exception occurs if both + block and handle-as-image, + apply to the same request: it will then be replaced by an image. If + set-image-blocker + (see below) also applies, the type of image will be determined by its parameter, + if not, the standard checkerboard pattern is sent. + + + It is important to understand this process, in order + to understand how Privoxy deals with + ads and other unwanted content. + + + The filter + action can perform a very similar task, by blocking + banner images and other content through rewriting the relevant URLs in the + document's HTML source, so they don't get requested in the first place. + Note that this is a totally different technique, and it's easy to confuse the two. + + + - - /.*/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). - + + Example usage (section): + + + {+block} # Block and replace with "blocked" page +.nasty-stuff.example.com - - 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: - +{+block +handle-as-image} # Block and replace with image +.ad.doubleclick.net +.ads.r.us + + + - - www.example.com/(?-i)PaTtErN.* - will match only - documents whose path starts with PaTtErN in - exactly this capitalization. - + - - - + + +content-type-overwrite - -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: - - - - + + + Typical use: + + Stop useless download menus from popping up, or change the browser's rendering mode + + - - - Boolean (e.g. +/-block): - - - - - - {+name} # enable this action - {-name} # disable this action - - - - - + + Effect: + + + Replaces the Content-Type: HTTP server header. + + + + + Type: + + + Parameterized. + + - - - parameterized (e.g. +/-hide-user-agent): - - - - - - {+name{param}} # enable action and set parameter to param - {-name} # disable action - - - - - + + Parameter: + + + Any string. + + + - - - 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 - - - - - + + Notes: + + + The Content-Type: HTTP server header is used by the + browser to decide what to do with the document. The value of this + header can cause the browser to open a download menu instead of + displaying the document by itself, even if the document's format is + supported by the browser. + + + The declared content type can also affect which rendering mode + the browser chooses. If XHTML is delivered as text/html, + many browsers treat it as yet another broken HTML document. + If it is send as application/xml, browsers with + XHTML support will only display it, if the syntax is correct. + + + If you see a web site that proudly uses XHTML buttons, but sets + Content-Type: text/html, you can use Privoxy + to overwrite it with application/xml and validate + the web master's claim inside your XHTML-supporting browser. + If the syntax is incorrect, the browser will complain loudly. + + + You can also go the opposite direction: if your browser prints + error messages instead of rendering a document falsely declared + as XHTML, you can overwrite the content type with + text/html and have it rendered as broken HTML document. + + + By default content-type-overwrite only replaces + Content-Type: headers that look like some kind of text. + If you want to overwrite it unconditionally, you have to combine it with + force-text-mode. + This limitation exists for a reason, think twice before circumventing it. + + + Most of the time it's easier to enable + filter-server-headers + and replace this action with a custom regular expression. It allows you + to activate it for every document of a certain site and it will still + only replace the content types you aimed at. + + + Of course you can apply content-type-overwrite + to a whole site and then make URL based exceptions, but it's a lot + more work to get the same precision. + + + - - + + Example usage (sections): + + + # Check if www.example.net/ really uses valid XHTML +{+content-type-overwrite {application/xml}} +www.example.net/ +# but leave the content type unmodified if the URL looks like a style sheet +{-content-type-overwrite} +www.example.net/*.\.css$ +www.example.net/*.style + + + + + + - - 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. - + + + +crunch-server-header - - The list of valid Privoxy actions are: - + + + Typical use: + + Remove a client header Privoxy has no dedicated action for. + + - - - - - - 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} - - - - - + + Effect: + + + Deletes every header send by the client that contains the string the user supplied as parameter. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Any string. + + + + + Notes: + + + This action allows you to block client headers for which no dedicated + Privoxy action exists. + Privoxy will remove every client header that + contains the string you supplied as parameter. + + + Regular expressions are not supported and you can't + use this action to block different headers in the same request, unless + they contain the same string. + + + crunch-client-header is only meant for quick tests. + If you have to block several different headers, or only want to modify + parts of them, you should enable + filter-client-headers + and create your own filter. + + + + Don't block any header without understanding the consequences. + + + + + + + Example usage (section): + + + # Block the non-existent "Privacy-Violation:" client header +{+crunch-client-header {Privacy-Violation:}} +/ + + + + + + + + + + +crunch-if-none-match + + + + Typical use: + + Prevent yet another way to track the user's steps between sessions. + + + + + Effect: + + + Deletes the If-None-Match: HTTP client header. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + - - - 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 - - - - - + + Notes: + + + Removing the If-None-Match: HTTP client header + is useful for filter testing, where you want to force a real + reload instead of getting status code 304 which + would cause the browser to use a cached copy of the page. + + + It is also useful to make sure the header isn't used as a cookie + replacement. + + + Blocking the If-None-Match: header shouldn't cause any + caching problems, as long as the If-Modified-Since: header + isn't blocked as well. + + + It is recommended to use this action together with + hide-if-modified-since + and + overwrite-last-modified. + + + + + + Example usage (section): + + + # Let the browser revalidate cached documents without being tracked across sessions +{+hide-if-modified-since {-1} \ ++overwrite-last-modified {randomize} \ ++crunch-if-none-match} +/ + + + + + + + + + +crunch-incoming-cookies + + + + Typical use: + + + Prevent the web server from setting any cookies on your system + + + + + + Effect: + + + Deletes any Set-Cookie: HTTP headers from server replies. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + Notes: + + + This action is only concerned with incoming cookies. For + outgoing cookies, use + crunch-outgoing-cookies. + Use both to disable cookies completely. + + + It makes no sense at all to use this action in conjunction + with the session-cookies-only action, + since it would prevent the session cookies from being set. See also + filter-content-cookies. + + + + + + Example usage: + + + +crunch-incoming-cookies + + + + + + + + + +crunch-server-header + + + + Typical use: + + Remove a server header Privoxy has no dedicated action for. + + + + + Effect: + + + Deletes every header sent by the server that contains the string the user supplied as parameter. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Any string. + + + - - - 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} - - - - - + + Notes: + + + This action allows you to block server headers for which no dedicated + Privoxy action exists. Privoxy + will remove every server header that contains the string you supplied as parameter. + + + Regular expressions are not supported and you can't + use this action to block different headers in the same request, unless + they contain the same string. + + + crunch-server-header is only meant for quick tests. + If you have to block several different headers, or only want to modify + parts of them, you should enable + filter-server-headers + and create your own filter. + + + + Don't block any header without understanding the consequences. + + + + + + + Example usage (section): + + + # Crunch server headers that try to prevent caching +{+crunch-server-header {no-cache}} +/ + + + + + + + + + +crunch-outgoing-cookies + + + + Typical use: + + + Prevent the web server from reading any cookies from your system + + + + + + Effect: + + + Deletes any Cookie: HTTP headers from client requests. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + - - - +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 - - - - - + + Notes: + + + This action is only concerned with outgoing cookies. For + incoming cookies, use + crunch-incoming-cookies. + Use both to disable cookies completely. + + + It makes no sense at all to use this action in conjunction + with the session-cookies-only action, + since it would prevent the session cookies from being read. + + + + + + Example usage: + + + +crunch-outgoing-cookies + + + + + + + + + + +deanimate-gifs + + + + Typical use: + + Stop those annoying, distracting animated GIF images. + + + + + Effect: + + + De-animate GIF animations, i.e. reduce them to their first or last image. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + last or first + + + - - - 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 - 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 remote site. + + Notes: + + + 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). + + + You can safely use this action with patterns that will also match non-GIF + objects, because no attempt will be made at anything that doesn't look like + a GIF. + + + + + + Example usage: + + + +deanimate-gifs{last} + + + + + + + + +downgrade-http-version + + + + Typical use: + + Work around (very rare) problems with HTTP/1.1 + + + + + Effect: + + + Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + This is a left-over from the time when Privoxy + didn't support important HTTP/1.1 features well. It is left here for the + unlikely case that you experience HTTP/1.1 related problems with some server + out there. Not all (optional) HTTP/1.1 features are supported yet, so there + is a chance you might need this action. + + + + + + Example usage (section): + + + {+downgrade-http-version} +problem-host.example.com + + + + + + + + + +fast-redirects + + + + Typical use: + + Fool some click-tracking scripts and speed up indirect links. + + + + + Effect: + + + Detects redirection URLs and redirects the browser without contacting + the redirection server first. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + + + simple-check to just search for the string http:// + to detect redirection URLs. + + + + + check-decoded-url to decode URLs (if necessary) before searching + for redirection URLs. + + + + + + + + Notes: + + + Many sites, like yahoo.com, don't just link to other sites. Instead, they + will link to some script on their own servers, giving the destination as a + parameter, which will then redirect you to the final target. URLs + resulting from this scheme typically look like: + http://www.example.org/click-tracker.cgi?target=http%3a//www.example.net/. - - - - - +fast-redirects - - - + + 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 asks the server for one redirect after the other. Plus, it feeds + the advertisers. + + + This feature is currently not very smart and is scheduled for improvement. + If it is enabled by default, you will have to create some exceptions to + this action. It can lead to failures in several ways: + + + Not every URLs with other URLs as parameters is evil. + Some sites offer a real service that requires this information to work. + For example a validation service needs to know, which document to validate. + fast-redirects assumes that every URL parameter that + looks like another URL is a redirection target, and will always redirect to + the last one. Most of the time the assumption is correct, but if it isn't, + the user gets redirected anyway. + + + Another failure occurs if the URL contains other parameters after the URL parameter. + The URL: + http://www.example.org/?redirect=http%3a//www.example.net/&foo=bar. + contains the redirection URL http://www.example.net/, + followed by another parameter. fast-redirects doesn't know that + and will cause a redirect to http://www.example.net/&foo=bar. + Depending on the target server configuration, the parameter will be silently ignored + or lead to a page not found error. It is possible to fix these redirected + requests with filter-client-headers + but it requires a little effort. + + + To detect a redirection URL, fast-redirects only + looks for the string http://, either in plain text + (invalid but often used) or encoded as http%3a//. + Some sites use their own URL encoding scheme, encrypt the address + of the target server or replace it with a database id. In theses cases + fast-redirects is fooled and the request reaches the + redirection server where it probably gets logged. + + + + + + Example usage: + + + +fast-redirects{simple-check} + + + +fast-redirects{check-decoded-url} + + + + + + + + + + +filter + + + + Typical use: + + Get rid of HTML and JavaScript annoyances, banner advertisements (by size), do fun text replacements, etc. + + + + + Effect: + + + All files of text-based type, most notably HTML and JavaScript, to which this + action applies, are filtered on-the-fly through the specified regular expression + based substitutions. (Note: as of version 3.0.3 plain text documents + are exempted from filtering, because web servers often use the + text/plain MIME type for all files whose type they + don't know.) + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + The name of a filter, as defined in the filter file. + Filters can be defined in one or more files as defined by the + filterfile + option in the config file. + default.filter is the collection of filters + supplied by the developers. Locally defined filters should go + in their own file, such as user.filter. + + + When used in its negative form, + and without parameters, filtering is completely disabled. - + + + + + Notes: + + + For your convenience, there are a number of pre-defined filters available + in the distribution filter file that you can use. See the examples below for + a list. + + + 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. + + + This is very powerful feature, and rolling your own + filters requires a knowledge of regular expressions and HTML. + + + The amount of data that can be filtered is limited to the + buffer-limit + option in the main config file. The + default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered + data, and all pending data, is passed through unfiltered. + + + Inadequate MIME types, such as zipped files, are not filtered at all. + (Again, only text-based types except plain text). Encrypted SSL data + (from HTTPS servers) cannot be filtered either, since this would violate + the integrity of the secure transaction. In some situations it might + be necessary to protect certain text, like source code, from filtering + by defining appropriate -filter sections. + + + At this time, Privoxy cannot (yet!) uncompress compressed + documents. If you want filtering to work on all documents, even those that + would normally be sent compressed, use the + prevent-compression + action in conjunction with filter. + + + Filtering can achieve some of the same effects as the + block + action, i.e. it can be used to block ads and banners. But the mechanism + works quite differently. One effective use, is to block ad banners + based on their size (see below), since many of these seem to be somewhat + standardized. + + + Feedback with suggestions for new or + improved filters is particularly welcome! + + + The below list has only the names and a one-line description of each + predefined filter. There are more + verbose explanations of what these filters do in the filter file chapter. + + + + + + Example usage (with filters from the distribution default.filter file). + See the Predefined Filters section for + more explanation on each: + + + + +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse + + + + +filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites) + + + + +filter{html-annoyances} # Get rid of particularly annoying HTML abuse + + + + +filter{content-cookies} # Kill cookies that come in the HTML or JS content + + + + +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups) + + + + +filter{unsolicited-popups} # Disable only unsolicited pop-up windows + + + + +filter{all-popups} # Kill all popups in JavaScript and HTML + + + + +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective + + + + +filter{banners-by-size} # Kill banners by size + + + + +filter{banners-by-link} # Kill banners by their links to known clicktrackers + + + + +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking) + + + + +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap + + + + +filter{jumping-windows} # Prevent windows from resizing and moving themselves + + + + +filter{frameset-borders} # Give frames a border and make them resizable + + + + +filter{demoronizer} # Fix MS's non-standard use of standard charsets + + + + +filter{shockwave-flash} # Kill embedded Shockwave Flash objects + + + + +filter{quicktime-kioskmode} # Make Quicktime movies saveable + + + + +filter{fun} # Text replacements for subversive browsing fun! + + + + +filter{crude-parental} # Crude parental filtering (demo only) + + + + +filter{ie-exploits} # Disable some known Internet Explorer bug exploits + + + + + + + + + +force-text-mode + + + + Typical use: + + Force Privoxy to treat a document as if it was in some kind of text format. + + + + + Effect: + + + Declares a document as text, even if the Content-Type: isn't detected as such. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + As explained above, + Privoxy tries to only filter files that are + in some kind of text format. The same restrictions apply to + content-type-overwrite. + force-text-mode declares a document as text, + without looking at the Content-Type: first. + + + + Think twice before activating this action. Filtering binary data + with regular expressions can cause file damage. + + + + + + + Example usage: + + + ++force-text-mode + + + + + + + + + + +handle-as-empty-document + + + + Typical use: + + Mark URLs that should be replaced by empty documents if they get blocked + + + + + Effect: + + + This action alone doesn't do anything noticeable. It just marks URLs. + If the block action also applies, + the presence or absence of this mark decides whether an HTML blocked + page, or an empty document will be sent to the client as a substitute for the blocked content. + The empty document isn't literally empty, but actually contains a single space. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + Some browsers complain about syntax errors if JavaScript documents + are blocked with Privoxy's + default HTML page; this option can be used to silence them. + + + The content type for the empty document can be specified with + content-type-overwrite{}, + but usually this isn't necessary. + + + + + + Example usage: + + + # Block all documents on example.org that end with ".js", +# but send an empty document instead of the usual HTML message. +{+block +handle-as-empty-document} +example.org/.*\.js$ + + + + + + + + + + +handle-as-image + + + + Typical use: + + Mark URLs as belonging to images (so they'll be replaced by imagee if they get blocked) + + + + + Effect: + + + This action alone doesn't do anything noticeable. It just marks URLs as images. + If the block action also applies, + the presence or absence of this mark decides whether an HTML blocked + page, or a replacement image (as determined by the set-image-blocker action) will be sent to the + client as a substitute for the blocked content. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + The below generic example section is actually part of default.action. + It marks all URLs with well-known image file name extensions as images and should + be left intact. + + + Users will probably only want to use the handle-as-image action in conjunction with + block, to block sources of banners, whose URLs don't + reflect the file type, like in the second example section. + + + Note that you cannot treat HTML pages as images in most cases. For instance, (in-line) ad + frames require an HTML page to be sent, or they won't display properly. + Forcing handle-as-image in this situation will not replace the + ad frame with an image, but lead to error messages. + + + + + + Example usage (sections): + + + # Generic image extensions: +# +{+handle-as-image} +/.*\.(gif|jpg|jpeg|png|bmp|ico)$ + +# These don't look like images, but they're banners and should be +# blocked as images: +# +{+block +handle-as-image} +some.nasty-banner-server.com/junk.cgi?output=trash + +# Banner source! Who cares if they also have non-image content? +ad.doubleclick.net + + + + + + + + + + +hide-accept-language + + + + Typical use: + + Pretend to use different language settings. + + + + + Effect: + + + Deletes or replaces the Accept-Language: HTTP header in client requests. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Keyword: block, or any user defined value. + + + + + + Notes: + + + Faking the browser's language settings can be useful to make a + foreign User-Agent set with + hide-user-agent + more believable. + + + However some sites with content in different languages check the + Accept-Language: to decide which one to take by default. + Sometimes it isn't possible to later switch to another language without + changing the Accept-Language: header first. + + + Therefore it's a good idea to either only change the + Accept-Language: header to languages you understand, + or to languages that aren't wide spread. + + + Before setting the Accept-Language: header + to a rare language, you should consider that it helps to + make your requests unique and thus easier to trace. + If you don't plan to change this header frequently, + you should stick to a common language. + + + + + + Example usage (section): + + + # Pretend to use Canadian language settings. +{+hide-accept-language{en-ca} \ ++hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \ +} +/ + + + + + + + + + +hide-content-disposition + + + + Typical use: + + Prevent download menus for content you prefer to view inside the browser. + + + + + Effect: + + + Deletes or replaces the Content-Disposition: HTTP header set by some servers. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Keyword: block, or any user defined value. + + + + + + Notes: + + + Some servers set the Content-Disposition: HTTP header for + documents they assume you want to save locally before viewing them. + The Content-Disposition: header contains the file name + the browser is supposed to use by default. + + + In most browsers that understand this header, it makes it impossible to + just view the document, without downloading it first, + even if it's just a simple text file or an image. + + + Removing the Content-Disposition: header helps + to prevent this annoyance, but some browsers additionally check the + Content-Type: header, before they decide if they can + display a document without saving it first. In these cases, you have + to change this header as well, before the browser stops displaying + download menus. + + + It is also possible to change the server's file name suggestion + to another one, but in most cases it isn't worth the time to set + it up. + + + + + + Example usage: + + + # Disarm the download link in Sourceforge's patch tracker +{-filter\ ++content-type-overwrite {text/plain}\ ++hide-content-disposition {block} } +.sourceforge.net/tracker/download.php + + + + + + + + + +hide-if-modified-since + + + + Typical use: + + Prevent yet another way to track the user's steps between sessions. + + + + + Effect: + + + Deletes the If-Modified-Since: HTTP client header or modifies its value. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Keyword: block, or a user defined value that specifies a range of hours. + + + + + + Notes: + + + Removing this header is useful for filter testing, where you want to force a real + reload instead of getting status code 304, which would cause the + browser to use a cached copy of the page. + + + Instead of removing the header, hide-if-modified-since can + also add or substract a random amount of time to/from the headers value. + You specify a range of hours were the random factor should be chosen from and + Privoxy does the rest. A negative value means + subtracting, a positive value adding. + + + Randomizing the value of the If-Modified-Since: makes + sure it isn't used as a cookie replacement, but you will run into + caching problems if the random range is too high. + + + It is a good idea to only use a small negative value and let + overwrite-last-modified + handle the greater changes. + + + It is also recommended to use this action together with + crunch-if-none-match. + + + + + + Example usage (section): + + + # Let the browser revalidate without being tracked across sessions +{+hide-if-modified-since {-1}\ ++overwrite-last-modified {randomize}\ ++crunch-if-none-match} +/ + + + + + + + + + +hide-forwarded-for-headers + + + + Typical use: + + Improve privacy by hiding the true source of the request + + + + + Effect: + + + Deletes any existing X-Forwarded-for: HTTP header from client requests, + and prevents adding a new one. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + It is fairly safe to leave this on. + + + This action is scheduled for improvement: It should be able to generate forged + X-Forwarded-for: headers using random IP addresses from a specified network, + to make successive requests from the same client look like requests from a pool of different + users sharing the same proxy. + + + + + + Example usage: + + + +hide-forwarded-for-headers + + + + + + + + + +hide-from-header + + + + Typical use: + + Keep your (old and ill) browser from telling web servers your email address + + + + + Effect: + + + Deletes any existing From: HTTP header, or replaces it with the + specified string. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Keyword: block, or any user defined value. + + + + + + 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 be sent to the web + server. If you do, it is a matter of fairness not to use any address that + is actually used by a real person. + + + This action is rarely needed, as modern web browsers don't send + From: headers anymore. + + + + + + Example usage: + + + +hide-from-header{block} or + +hide-from-header{spam-me-senseless@sittingduck.example.com} + + + + + + + + + +hide-referrer + + + + Typical use: + + Conceal which link you followed to get to a particular site + + + + + Effect: + + + Deletes the Referer: (sic) HTTP header from the client request, + or replaces it with a forged one. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + + conditional-block to delete the header completely if the host has changed. + + + block to delete the header unconditionally. + + + forge to pretend to be coming from the homepage of the server we are talking to. + + + Any other string to set a user defined referrer. + + + + + + + Notes: + + + conditional-block is the only parameter, + that isn't easily detected in the server's log file. If it blocks the + referrer, the request will look like the visitor used a bookmark or + typed in the address directly. + + + Leaving the referrer unmodified for requests on the same host + allows the server owner to see the visitor's click path, + but in most cases she could also get that information by comparing + other parts of the log file: for example the User-Agent if it isn't + a very common one, or the user's IP address if it doesn't change between + different requests. + + + Always blocking the referrer, or using a custom one, can lead to + failures on servers that check the referrer before they answer any + requests, in an attempt to prevent their valuable content from being + embedded or linked to elsewhere. + + + Both conditional-block and forge + will work with referrer checks, as long as content and valid referring page + are on the same host. Most of the time that's the case. + + + hide-referer is an alternate spelling of + hide-referrer and the two can be can be freely + substituted with each other. (referrer is the + correct English spelling, however the HTTP specification has a bug - it + requires it to be spelled as referer.) + + + + + + Example usage: + + + +hide-referrer{forge} or + +hide-referrer{http://www.yahoo.com/} + + + + + + + + + +hide-user-agent + + + + Typical use: + + Conceal your type of browser and client operating system + + + + + Effect: + + + Replaces the value of the User-Agent: HTTP header + in client requests with the specified value. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + Any user-defined string. + + + + + + Notes: + + + + This can lead to problems on web sites that depend on looking at this header in + order to customize their content for different browsers (which, by the + way, is NOT the right thing to do: good web sites + work browser-independently). + + + + + Using this action in multi-user setups or wherever different types of + browsers will access the same Privoxy is + not recommended. In single-user, single-browser + setups, you might use it to delete your OS version information from + the headers, because it is an invitation to exploit known bugs for your + OS. It is also occasionally useful to forge this in order to access + sites that won't let you in otherwise (though there may be a good + reason in some cases). Example of this: some MSN sites will not + let Mozilla enter, yet forging to a + Netscape 6.1 user-agent works just fine. + (Must be just a silly MS goof, I'm sure :-). + + + This action is scheduled for improvement. + + + + + + Example usage: + + + +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + + + + + + + + + +inspect-jpegs + + + + Typical use: + + To protect against the MS buffer over-run in JPEG processing + + + + + Effect: + + + To protect against a known exploit + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + See Microsoft Security Bulletin MS04-028. JPEG images are one of the most + common image types found across the Internet. The exploit as described can + allow execution of code on the target system, giving an attacker access + to the system in question by merely planting an altered JPEG image, which + would have no obvious indications of what lurks inside. This action + prevents unwanted intrusion. + + + + + + + Example usage: + + +inspect-jpegs + + + + + + + + + + +kill-popups<anchor id="kill-popup"> + + + + Typical use: + + Eliminate those annoying pop-up windows (deprecated) + + + + + Effect: + + + While loading the document, replace JavaScript code that opens + pop-up windows with (syntactically neutral) dummy code on the fly. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + This action is basically a built-in, hardwired special-purpose filter + action, but there are important differences: For kill-popups, + the document need not be buffered, so it can be incrementally rendered while + downloading. But kill-popups doesn't catch as many pop-ups as + filter{all-popups} + does and is not as smart as filter{unsolicited-popups} + is. + + + Think of it as a fast and efficient replacement for a filter that you + can use if you don't want any filtering at all. Note that it doesn't make + sense to combine it with any filter action, + since as soon as one filter applies, + the whole document needs to be buffered anyway, which destroys the advantage of + the kill-popups action over its filter equivalent. + + + Killing all pop-ups unconditionally is problematic. Many shops and banks rely on + pop-ups to display forms, shopping carts etc, and the filter{unsolicited-popups} + does a fairly good job of catching only the unwanted ones. + + + If the only kind of pop-ups that you want to kill are exit consoles (those + really nasty windows that appear when you close an other + one), you might want to use + filter{js-annoyances} + instead. + + + + + + + + Example usage: + + +kill-popups + + + + + + + + +limit-connect + + + + Typical use: + + Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for untrusted sites + + + + + Effect: + + + Specifies to which ports HTTP CONNECT requests are allowable. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + A comma-separated list of ports or port ranges (the latter using dashes, with the minimum + defaulting to 0 and the maximum to 65K). + + + + + + Notes: + + + By default, i.e. if no limit-connect action applies, + Privoxy only allows HTTP CONNECT + requests to port 443 (the standard, secure HTTPS port). Use + limit-connect if more fine-grained control is desired + for some or all destinations. + + + 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 server. + This can be a big security hole, since CONNECT-enabled proxies can be + abused as TCP relays very easily. + + + Privoxy relays HTTPS traffic without seeing + the decoded content. Websites can leverage this limitation to circumvent Privoxy's + filters. By specifying an invalid port range you can disable HTTPS entirely. + If you plan to disable SSL by default, consider enabling + treat-forbidden-connects-like-blocks + as well, to be able to quickly create exceptions. + + + + + + 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-} # Ports less than 3, 7, 20 to 100 and above 500 are OK. ++limit-connect{-} # All ports are OK ++limit-connect{,} # No HTTPS traffic is allowed + + + + + + + + +prevent-compression + + + + Typical use: + + + Ensure that servers send the content uncompressed, so it can be + passed through filters. + + + + + + Effect: + + + Removes the Accept-Encoding header which can be used to ask for compressed transfer. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + More and more websites send their content compressed by default, which + is generally a good idea and saves bandwidth. But for the filter, deanimate-gifs + and kill-popups actions to work, + Privoxy needs access to the uncompressed data. + Unfortunately, Privoxy can't yet(!) uncompress, filter, and + re-compress the content on the fly. So if you want to ensure that all websites, including + those that normally compress, can be filtered, you need to use this action. + + + This will slow down transfers from those websites, though. If you use any of the above-mentioned + actions, you will typically want to use prevent-compression in conjunction + with them. + + + Note that some (rare) ill-configured sites don't handle requests for uncompressed + documents correctly (they send an empty document body). If you use prevent-compression + per default, you'll have to add exceptions for those sites. See the example for how to do that. + + + + + + Example usage (sections): + + + # Set default: +# +{+prevent-compression} +/ # Match all sites + +# Make exceptions for ill sites: +# +{-prevent-compression} +www.debianhelp.org +www.pclinuxonline.com + + + + + + + + + + +overwrite-last-modified + + + + Typical use: + + Prevent yet another way to track the user's steps between sessions. + + + + + Effect: + + + Deletes the Last-Modified: HTTP server header or modifies its value. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + One of the keywords: block, reset-to-request-time + and randomize + + + + + + Notes: + + + Removing the Last-Modified: header is useful for filter + testing, where you want to force a real reload instead of getting status + code 304, which would cause the browser to reuse the old + version of the page. + + + The randomize option overwrites the value of the + Last-Modified: header with a randomly chosen time + between the original value and the current time. In theory the server + could send each document with a different Last-Modified: + header to track visits without using cookies. Randomize + makes it impossible and the browser can still revalidate cached documents. + + + reset-to-request-time overwrites the value of the + Last-Modified: header with the current time. You could use + this option together with + hided-if-modified-since + to further customize your random range. + + + The preferred parameter here is randomize. It is safe + to use, as long as the time settings are more or less correct. + If the server sets the Last-Modified: header to the time + of the request, the random range becomes zero and the value stays the same. + Therefore you should later randomize it a second time with + hided-if-modified-since, + just to be sure. + + + It is also recommended to use this action together with + crunch-if-none-match. + + + + + + Example usage: + + + # Let the browser revalidate without being tracked across sessions +{+hide-if-modified-since {-1}\ ++overwrite-last-modified {randomize}\ ++crunch-if-none-match} +/ + + + + + + + + + +redirect + + + + Typical use: + + + Redirect requests to other sites. + + + + + + Effect: + + + Convinces the browser that the requested document has been moved + to another location and the browser should get it from there. + + + + + + Type: + + + Parameterized + + + + + Parameter: + + + Any URL. + + + + + + Notes: + + + This action is useful to replace whole documents with your own + ones. For that to work, they have to be available on another server. + + + You can do the same by combining the actions + block, + handle-as-image and + set-image-blocker{URL}. + It doesn't sound right for non-image documents, and that's why this action + was created. + + + This action will be ignored if you use it together with + block. + + + + + + Example usage: + + + # Replace example.com's style sheet with another one +{+redirect{http://localhost/css-replacements/example.com.css}} +example.com/stylesheet.css + + + + + + + + + + +send-vanilla-wafer + + + + Typical use: + + + Feed log analysis scripts with useless data. + + + + + + Effect: + + + Sends a cookie with each request stating that you do not accept any copyright + on cookies sent to you, and asking the site operator not to track you. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + The vanilla wafer is a (relatively) unique header and could conceivably be used to track you. + + + This action is rarely used and not enabled in the default configuration. + + + + + + Example usage: + + + +send-vanilla-wafer + + + + + + + + + + +send-wafer + + + + Typical use: + + + Send custom cookies or feed log analysis scripts with even more useless data. + + + + + + Effect: + + + Sends a custom, user-defined cookie with each request. + + + + + + Type: + + + Multi-value. + + + + + Parameter: + + + A string of the form name=value. + + + + + + Notes: + + + Being multi-valued, multiple instances of this action can apply to the same request, + resulting in multiple cookies being sent. + + + This action is rarely used and not enabled in the default configuration. + + + + + Example usage (section): + + + {+send-wafer{UsingPrivoxy=true}} +my-internal-testing-server.void + + + + + + + + + +session-cookies-only + + + + Typical use: + + + Allow only temporary session cookies (for the current + browser session only). + + + + + + Effect: + + + Deletes the expires field from Set-Cookie: + server headers. Most browsers will not store such cookies permanently and + forget them in between sessions. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + This is less strict than crunch-incoming-cookies / + crunch-outgoing-cookies and allows you to browse + websites that insist or rely on setting cookies, without compromising your privacy too badly. + + + Most browsers will not permanently store cookies that have been processed by + session-cookies-only and will forget about them between sessions. + 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. + + + It makes no sense at all to use session-cookies-only + together with crunch-incoming-cookies or + crunch-outgoing-cookies. If you do, cookies + will be plainly killed. + + + Note that it is up to the browser how it handles such cookies without an expires + field. If you use an exotic browser, you might want to try it out to be sure. + + + This setting also has no effect on cookies that may have been stored + previously by the browser before starting Privoxy. + These would have to be removed manually. + + + Privoxy also uses + the content-cookies filter + to block some types of cookies. Content cookies are not effected by + session-cookies-only. + + + + + + Example usage: + + + +session-cookies-only + + + + + + + + + +set-image-blocker + + + + Typical use: + + Choose the replacement for blocked images + + + + + Effect: + + + This action alone doesn't do anything noticeable. If both + block and handle-as-image also + apply, i.e. if the request is to be blocked as an image, + then the parameter of this action decides what will be + sent as a replacement. + + + + + + Type: + + + Parameterized. + + + + + Parameter: + + + + + pattern to send a built-in checkerboard pattern image. The image is visually + decent, scales very well, and makes it obvious where banners were busted. + + + + + blank to send a built-in transparent image. This makes banners disappear + completely, but makes it hard to detect where Privoxy has blocked + images on a given page and complicates troubleshooting if Privoxy + has blocked innocent images, like navigation icons. + + + + + target-url to + send a redirect to target-url. You can redirect + to any image anywhere, even in your local filesystem via file:/// URL. + (But note that not all browsers support redirecting to a local file system). + + + A good application of redirects is to use special Privoxy-built-in + URLs, which send the built-in images, as target-url. + This has the same visual effect as specifying blank or pattern in + the first place, but enables your browser to cache the replacement image, instead of requesting + it over and over again. + + + + + + + + Notes: + + + The URLs for the built-in images are http://config.privoxy.org/send-banner?type=type, where type is + either blank or pattern. + + + There is a third (advanced) type, called auto. It is NOT to be + used in set-image-blocker, but meant for use from filters. + Auto will select the type of image that would have applied to the referring page, had it been an image. + + + + + + Example usage: + + + Built-in pattern: + + + +set-image-blocker{pattern} + + + Redirect to the BSD devil: + + + +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} + + + Redirect to the built-in pattern for better caching: + + + +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern} + + + + + + + + + +treat-forbidden-connects-like-blocks + + + + Typical use: + + Block forbidden connects with an easy to find error message. + + + + + Effect: + + + If this action is enabled, Privoxy no longer + makes a difference between forbidden connects and ordinary blocks. + + + + + + Type: + + + Boolean + + + + + Parameter: + + N/A + + + + + Notes: + + + By default Privoxy answers + forbidden Connect requests + with a short error message inside the headers. If the browser doesn't display + headers (most don't), you just see an empty page. + + + With this action enabled, Privoxy displays + the message that is used for ordinary blocks instead. If you decide + to make an exception for the page in question, you can do so by + following the See why link. + + + For Connect requests the clients tell + Privoxy which host they are interested + in, but not which document they plan to get later. As a result, the + Go there anyway link becomes rather useless: + it lets the client request the home page of the forbidden host + through unencrypted HTTP, still using the port of the last request. + + + If you previously configured Privoxy to do the + request through a SSL tunnel, everything will work. Most likely you haven't + and the server will responds with an error message because it is expecting + HTTPS. + + + + + + Example usage: + + + +treat-forbidden-connects-like-blocks + + + + + + + + + +Summary + + 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, 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. + + + + + + +Aliases + + Custom actions, known to Privoxy + as aliases, can be defined by combining other actions. + These can in turn be invoked just like the built-in actions. + Currently, an alias name can contain any character except space, tab, + =, + { and }, but we strongly + recommend that you only use a to z, + 0 to 9, +, and -. + Alias names are not case sensitive, and are not required to start with a + + or - sign, since they are merely textually + expanded. + + + Aliases can be used throughout the actions file, but they must be + defined in a special section at the top of the file! + And there can only be one such section per actions file. Each actions file may + have its own alias section, and the aliases defined in it are only visible + within that file. + + + There are two main reasons to use aliases: One is to save typing for frequently + used combinations of actions, the other one is a gain in flexibility: If you + decide once how you want to handle shops by defining an alias called + shop, you can later change your policy on shops in + one place, and your changes will take effect everywhere + in the actions file where the shop alias is used. Calling aliases + by their purpose also makes your actions files more readable. + + + Currently, there is one big drawback to using aliases, though: + Privoxy's built-in web-based action file + editor honors aliases when reading the actions files, but it expands + them before writing. So the effects of your aliases are of course preserved, + but the aliases themselves are lost when you edit sections that use aliases + with it. + This is likely to change in future versions of Privoxy. + + + + Now let's define some aliases... + + + + + # Useful custom aliases we can use later. + # + # Note the (required!) section header line and that this section + # must be at the top of the actions file! + # + {{alias}} + + # These aliases just save typing later: + # (Note that some already use other aliases!) + # + +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies + -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies + block-as-image = +block +handle-as-image + mercy-for-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} + + # These aliases define combinations of actions + # that are useful for certain types of sites: + # + fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups + shop = -crunch-all-cookies -filter{all-popups} -kill-popups + + # Short names for other aliases, for really lazy people ;-) + # + c0 = +crunch-all-cookies + c1 = -crunch-all-cookies + + + + ...and put them to use. These sections would appear in the lower part of an + actions file and define exceptions to the default actions (as specified further + up for the / pattern): + + + + + # These sites are either very complex or very keen on + # user data and require minimal interference to work: + # + {fragile} + .office.microsoft.com + .windowsupdate.microsoft.com + .nytimes.com + + # Shopping sites: + # Allow cookies (for setting and retrieving your customer data) + # + {shop} + .quietpc.com + .worldpay.com # for quietpc.com + .scan.co.uk + + # These shops require pop-ups: + # + {shop -kill-popups -filter{all-popups}} + .dabs.com + .overclockers.co.uk + + + + Aliases like shop and fragile are often used for + problem sites that require some actions to be disabled + in order to function properly. + + + + + +Actions Files Tutorial + + The above chapters have shown which actions files + there are and how they are organized, how actions are specified and applied + to URLs, how patterns work, and how to + define and use aliases. Now, let's look at an + example default.action and user.action + file and see how all these pieces come together: + + +default.action + + +Every config file should start with a short comment stating its purpose: + + + + # Sample default.action file <ijbswa-developers@lists.sourceforge.net> + + + +Then, since this is the default.action file, the +first section is a special section for internal use that you needn't +change or worry about: + + + + +########################################################################## +# Settings -- Don't change! For internal Privoxy use ONLY. +########################################################################## + +{{settings}} +for-privoxy-version=3.0 + + + +After that comes the (optional) alias section. We'll use the example +section from the above chapter on aliases, +that also explains why and how aliases are used: + + + + +########################################################################## +# Aliases +########################################################################## +{{alias}} + + # These aliases just save typing later: + # (Note that some already use other aliases!) + # + +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies + -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies + block-as-image = +block +handle-as-image + mercy-for-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies} + + # These aliases define combinations of actions + # that are useful for certain types of sites: + # + fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups + shop = -crunch-all-cookies -filter{all-popups} -kill-popups + + + + Now come the regular sections, i.e. sets of actions, accompanied + by URL patterns to which they apply. Remember all actions + are disabled when matching starts, so we have to explicitly + enable the ones we want. + + + + The first regular section is probably the most important. It has only + one pattern, /, but this pattern + matches all URLs. Therefore, the + set of actions used in this default section will + be applied to all requests as a start. It can be partly or + wholly overridden by later matches further down this file, or in user.action, + but it will still be largely responsible for your overall browsing + experience. + + + + Again, at the start of matching, all actions are disabled, so there is + no real need to disable any actions here, but we will do that nonetheless, + to have a complete listing for your reference. (Remember: a + + preceding the action name enables the action, a - disables!). + Also note how this long line has been made more readable by splitting it into + multiple lines with line continuation. + + + + +########################################################################## +# "Defaults" section: +########################################################################## + { \ + -add-header \ + -block \ + -crunch-incoming-cookies \ + -crunch-outgoing-cookies \ + +deanimate-gifs \ + -downgrade-http-version \ + +fast-redirects \ + +filter{js-annoyances} \ + -filter{js-events} \ + +filter{html-annoyances} \ + -filter{content-cookies} \ + +filter{refresh-tags} \ + +filter{unsolicited-popups} \ + -filter{all-popups} \ + +filter{img-reorder} \ + +filter{banners-by-size} \ + -filter{banners-by-link} \ + +filter{webbugs} \ + -filter{tiny-textforms} \ + +filter{jumping-windows} \ + -filter{frameset-borders} \ + -filter{demoronizer} \ + -filter{shockwave-flash} \ + -filter{quicktime-kioskmode} \ + -filter{fun} \ + -filter{crude-parental} \ + +filter{ie-exploits} \ + -handle-as-image \ + +hide-forwarded-for-headers \ + +hide-from-header{block} \ + +hide-referrer{forge} \ + -hide-user-agent \ + -kill-popups \ + -limit-connect \ + +prevent-compression \ + -send-vanilla-wafer \ + -send-wafer \ + +session-cookies-only \ + +set-image-blocker{pattern} \ + } + / # forward slash will match *all* potential URL patterns. + + + + The default behavior is now set. Note that some actions, like not hiding + the user agent, are part of a general policy that applies + universally and won't get any exceptions defined later. Other choices, + like not blocking (which is understandably the + default!) need exceptions, i.e. we need to specify explicitly what we + want to block in later sections. + + + + The first of our specialized sections is concerned with fragile + sites, i.e. sites that require minimum interference, because they are either + very complex or very keen on tracking you (and have mechanisms in place that + make them unusable for people who avoid being tracked). We will simply use + our pre-defined fragile alias instead of stating the list + of actions explicitly: + + + + +########################################################################## +# Exceptions for sites that'll break under the default action set: +########################################################################## + +# "Fragile" Use a minimum set of actions for these sites (see alias above): +# +{ fragile } +.office.microsoft.com # surprise, surprise! +.windowsupdate.microsoft.com + + + + Shopping sites are not as fragile, but they typically + require cookies to log in, and pop-up windows for shopping + carts or item details. Again, we'll use a pre-defined alias: + + + + +# Shopping sites: +# +{ shop } +.quietpc.com +.worldpay.com # for quietpc.com +.jungle.com +.scan.co.uk + + + + + + The fast-redirects + action, which we enabled per default above, breaks some sites. So disable + it for popular sites where we know it misbehaves: + + + + +{ -fast-redirects } +login.yahoo.com +edit.*.yahoo.com +.google.com +.altavista.com/.*(like|url|link):http +.altavista.com/trans.*urltext=http +.nytimes.com + + + + It is important that Privoxy knows which + URLs belong to images, so that if they are to + be blocked, a substitute image can be sent, rather than an HTML page. + Contacting the remote site to find out is not an option, since it + would destroy the loading time advantage of banner blocking, and it + would feed the advertisers (in terms of money and + information). We can mark any URL as an image with the handle-as-image action, + and marking all URLs that end in a known image file extension is a + good start: + - - - 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} - - - - + + +########################################################################## +# Images: +########################################################################## - - Filter sections that are pre-defined in the supplied - default.filter include: - +# Define which file types will be treated as images, in case they get +# blocked further down this file: +# +{ +handle-as-image } +/.*\.(gif|jpe?g|png|bmp|ico)$ + -
- - - html-annoyances: Get rid of particularly annoying HTML abuse. - - - - - js-annoyances: Get rid of particularly annoying JavaScript abuse - - - - - no-poups: Kill all popups in JS and HTML - - - - - frameset-borders: Give frames a border - - - - - webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) - - - - - no-refresh: Automatic refresh sucks on auto-dialup lines - - - - - fun: Text replacements for subversive browsing fun! - - - - - nimda: Remove (virus) Nimda code. - - - - - banners-by-size: Kill banners by size - - - - - crude-parental: Kill all web pages that contain the words "sex" or "warez" - - -
+ + And then there are known banner sources. They often use scripts to + generate the banners, so it won't be visible from the URL that the + request is for an image. Hence we block them and + mark them as images in one go, with the help of our + block-as-image alias defined above. (We could of + course just as well use +block + +handle-as-image here.) + Remember that the type of the replacement image is chosen by the + set-image-blocker + action. Since all URLs have matched the default section with its + +set-image-blocker{pattern} + action before, it still applies and needn't be repeated: + - + + +# Known ad generators: +# +{ block-as-image } +ar.atwola.com +.ad.doubleclick.net +.ad.*.doubleclick.net +.a.yimg.com/(?:(?!/i/).)*$ +.a[0-9].yimg.com/(?:(?!/i/).)*$ +bs*.gsanet.com +bs*.einets.com +.qkimg.net + - - - Block any existing X-Forwarded-for header, and do not add a new one: - - - - - - +hide-forwarded - - - - - + + One of the most important jobs of Privoxy + is to block banners. A huge bunch of them are already blocked + by the filter{banners-by-size} + action, which we enabled above, and which deletes the references to banner + images from the pages while they are loaded, so the browser doesn't request + them anymore, and hence they don't need to be blocked here. But this naturally + doesn't catch all banners, and some people choose not to use filters, so we + need a comprehensive list of patterns for banner URLs here, and apply the + block action to them. + + + First comes a bunch of generic patterns, which do most of the work, by + matching typical domain and path name components of banners. Then comes + a list of individual patterns for specific sites, which is omitted here + to keep the example short: + - - - 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} - - - - - - - - - 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} - - - - - - - - - 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{...} - - - - - + + +########################################################################## +# Block these fine banners: +########################################################################## +{ +block } - - - 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-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)} - - - - - - +# Generic patterns: +# +ad*. +.*ads. +banner?. +count*. +/.*count(er)?\.(pl|cgi|exe|dll|asp|php[34]?) +/(?:.*/)?(publicite|werbung|rekla(ma|me|am)|annonse|maino(kset|nta|s)?)/ - - - 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 - - - - - - - - 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} - - - - - - - - - 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. - - - - 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): - +# Site-specific patterns (abbreviated): +# +.hitbox.com + - - - - - +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. - - - - + + You wouldn't believe how many advertisers actually call their banner + servers ads.company.com, or call the directory + in which the banners are stored simply banners. So the above + generic patterns are surprisingly effective. + + + But being very generic, they necessarily also catch URLs that we don't want + to block. The pattern .*ads. e.g. catches + nasty-ads.nasty-corp.com as intended, + but also downloads.sourcefroge.net or + adsl.some-provider.net. So here come some + well-known exceptions to the +block + section above. + + + Note that these are exceptions to exceptions from the default! Consider the URL + downloads.sourcefroge.net: Initially, all actions are deactivated, + so it wouldn't get blocked. Then comes the defaults section, which matches the + URL, but just deactivates the block + action once again. Then it matches .*ads., an exception to the + general non-blocking policy, and suddenly + +block applies. And now, it'll match + .*loads., where -block + applies, so (unless it matches again further down) it ends up + with no block action applying. + - - - - - +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. - + + +########################################################################## +# Save some innocent victims of the above generic block patterns: +########################################################################## + +# By domain: +# +{ -block } +adv[io]*. # (for advogato.org and advice.*) +adsl. # (has nothing to do with ads) +ad[ud]*. # (adult.* and add.*) +.edu # (universities don't host banners (yet!)) +.*loads. # (downloads, uploads etc) + +# By path: +# +/.*loads/ + +# Site-specific: +# +www.globalintersec.com/adv # (adv = advanced) +www.ugu.com/sui/ugu/adv + + + + Filtering source code can have nasty side effects, + so make an exception for our friends at sourceforge.net, + and all paths with cvs in them. Note that + -filter + disables all filters in one fell swoop! + + + + +# Don't filter code! +# +{ -filter } +/.*cvs +.sourceforge.net + + + + The actual default.action is of course more + comprehensive, but we hope this example made clear how it works. + + + + +user.action + + + So far we are painting with a broad brush by setting general policies, + which would be a reasonable starting point for many people. Now, + you might want to be more specific and have customized rules that + are more suitable to your personal habits and preferences. These would + be for narrowly defined situations like your ISP or your bank, and should + be placed in user.action, which is parsed after all other + actions files and hence has the last word, over-riding any previously + defined actions. user.action is also a + safe place for your personal settings, since + default.action is actively maintained by the + Privoxy developers and you'll probably want + to install updated versions from time to time. + + + + So let's look at a few examples of things that one might typically do in + user.action: + + + + + + + +# My user.action file. <fred@foobar.com> + + + + As aliases are local to the actions + file that they are defined in, you can't use the ones from + default.action, unless you repeat them here: + + + + +# Aliases are local to the file they are defined in. +# (Re-)define aliases for this file: +# +{{alias}} +# +# These aliases just save typing later, and the alias names should +# be self explanatory. +# ++crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies +-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies + allow-all-cookies = -crunch-all-cookies -session-cookies-only + allow-popups = -filter{all-popups} -kill-popups ++block-as-image = +block +handle-as-image +-block-as-image = -block + +# These aliases define combinations of actions that are useful for +# certain types of sites: +# +fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referrer -kill-popups +shop = -crunch-all-cookies allow-popups + +# Allow ads for selected useful free sites: +# +allow-ads = -block -filter{banners-by-size} -filter{banners-by-link} - - - - - +nocompression - - - - - - - - - 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 - - - - - - - - - Prevent the website from reading cookies: - - - - - - +no-cookies-read - - - - - - - - - Prevent the website from setting cookies: - - - - - - +no-cookies-set - - - - - - - - - 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 - - - - - - - - - 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 - - - - - - - - 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} - - - - - + - + + Say you have accounts on some sites that you visit regularly, and + you don't want to have to log in manually each time. So you'd like + to allow persistent cookies for these sites. The + allow-all-cookies alias defined above does exactly + that, i.e. it disables crunching of cookies in any direction, and the + processing of cookies to make them only temporary. - The meaning of any of the above is reversed by preceding the action with a - -, in place of the +. + +{ allow-all-cookies } +sourceforge.net +sunsolve.sun.com +.slashdot.org +.yahoo.com +.msdn.microsoft.com +.redhat.com - Some examples: + Your bank is allergic to some filter, but you don't know which, so you disable them all: - Turn off cookies by default, then allow a few through for specified sites: + +{ -filter } +.your-home-banking-site.com - + - - - - # Turn off all persistent cookies - { +no-cookies-read } - { +no-cookies-set } - # Allow cookies for this browser session ONLY - { +no-cookies-keep } + Some file types you may not want to filter for various reasons: + + + + +# Technical documentation is likely to contain strings that might +# erroneously get altered by the JavaScript-oriented filters: +# +.tldp.org +/(.*/)?selfhtml/ + +# And this stupid host sends streaming video with a wrong MIME type, +# so that Privoxy thinks it is getting HTML and starts filtering: +# +stupid-server.example.com/ + + + + Example of a simple block action. Say you've + seen an ad on your favourite page on example.com that you want to get rid of. + You have right-clicked the image, selected copy image location + and pasted the URL below while removing the leading http://, into a + { +block } section. Note that { +handle-as-image + } need not be specified, since all URLs ending in + .gif will be tagged as images by the general rules as set + in default.action anyway: + + + + +{ +block } +www.example.com/nasty-ads/sponsor.gif +another.popular.site.net/more/junk/here/ + + + + The URLs of dynamically generated banners, especially from large banner + farms, often don't use the well-known image file name extensions, which + makes it impossible for Privoxy to guess + the file type just by looking at the URL. + You can use the +block-as-image alias defined above for + these cases. + Note that objects which match this rule but then turn out NOT to be an + image are typically rendered as a broken image icon by the + browser. Use cautiously. + - # 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 + + +{ +block-as-image } +.doubleclick.net +/Realmedia/ads/ +ar.atwola.com/ + + + + Now you noticed that the default configuration breaks Forbes Magazine, + but you were too lazy to find out which action is the culprit, and you + were again too lazy to give feedback, so + you just used the fragile alias on the site, and + -- whoa! -- it worked. The fragile + aliases disables those actions that are most likely to break a site. Also, + good for testing purposes to see if it is Privoxy + that is causing the problem or not. + + + + +{ fragile } +.forbes.com + + + + You like the fun text replacements in default.filter, + but it is disabled in the distributed actions file. (My colleagues on the team just + don't have a sense of humour, that's why! ;-). So you'd like to turn it on in your private, + update-safe config, once and for all: + - # Alternative way of saying the same thing - {-no-cookies-set -no-cookies-read -no-cookies-keep} - .sourceforge.net - .sf.net - - - + + +{ +filter{fun} } +/ # For ALL sites! + + + + Note that the above is not really a good idea: There are exceptions + to the filters in default.action for things that + really shouldn't be filtered, like code on CVS->Web interfaces. Since + user.action has the last word, these exceptions + won't be valid for the fun filtering specified here. - Now turn off fast redirects, and then we allow two exceptions: + You might also worry about how your favourite free websites are + funded, and find that they rely on displaying banner advertisements + to survive. So you might want to specifically allow banners for those + sites that you feel provide value to you: - - - - # Turn them off! - {+fast-redirects} - - # 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 - - - + +{ allow-ads } +.sourceforge.net +.slashdot.org +.osdn.net - Turn on page filtering according to rules in the defined sections - of refilterfile, and make one exception for - sourceforge: - + Note that allow-ads has been aliased to + -block, + -filter{banners-by-size}, and + -filter{banners-by-link} above. + - - - - # Run everything through the filter file, using only the - # specified sections: - +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\ - +filter{webbugs} +filter{nimda} +filter{banners-by-size} - - # Then disable filtering of code from sourceforge! - {-filter} - .cvs.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: - - - - - - - # Blocklist: - {+block} - /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g)) - /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/]) - /.*/(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/ - - - + user.action is generally the best place to define + exceptions and additions to the default policies of + default.action. Some actions are safe to have their + default policies set here though. So let's set a default policy to have a + blank image as opposed to the checkerboard pattern for + ALL sites. / of course matches all URL + paths and patterns: - 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. - + +{ +set-image-blocker{blank} } +/ # ALL sites + + + + + + + + +Filter Files - - -Aliases - Custom actions, known to Privoxy - as aliases, can be defined by combining other actions. - These can in turn be invoked just like the built-in actions. - Currently, an alias can contain any character except space, tab, =, - { 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. + All text substitutions that can be invoked through the + filter action which + must first be defined in a filter file, such as + default.filter. Mulitple filter files can be + defined through the + filterfile config + option. The filters as supplied by the developers will be found in + default.filter. It is recommended that any locally + defined or modified filters go in a separately defined file such as + user.filter. + - Now let's define a few aliases: + Typical reasons for doing these kinds of substitutions are to eliminate + common annoyances in HTML and JavaScript, such as pop-up windows, + exit consoles, crippled windows without navigation tools, the + infamous <BLINK> tag etc, to suppress images with certain + width and height attributes (standard banner sizes or web-bugs), + or just to have fun. The possibilities are endless. - - - - # Useful customer 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 - #... etc. Customize to your heart's content. - - - + Filtering works on any text-based document type, including + HTML, JavaScript, CSS etc. (all text/* + MIME types, except text/plain). + Substitutions are made at the source level, so if you want to roll + your own filters, you should be familiar with HTML syntax. - Some examples using our shop and fragile - aliases from above: + Just like the actions files, the + filter file is organized in sections, which are called filters + here. Each filter consists of a heading line, that starts with the + keyword FILTER:, followed by + the filter's name, and a short (one line) + description of what it does. Below that line + come the jobs, i.e. lines that define the actual + text substitutions. By convention, the name of a filter + should describe what the filter eliminates. The + comment is used in the web-based + user interface. - - - - # These sites are very complex and require - # minimal interference. - {fragile} - .office.microsoft.com - .windowsupdate.microsoft.com - .nytimes.com + Once a filter called name has been defined + in the filter file, it can be invoked by using an action of the form + +filter{name} + in any actions file. + + + + A filter header line for a filter called foo could look + like this: + - # Shopping sites - still want to block ads. - {shop} - .quietpc.com - .worldpay.com # for quietpc.com - .jungle.com - .scan.co.uk + + FILTER: foo Replace all "foo" with "bar" + - # These shops require pop-ups - {shop -no-popups} - .dabs.com - .overclockers.co.uk - - - + + Below that line, and up to the next header line, come the jobs that + define what text replacements the filter executes. They are specified + in a syntax that imitates Perl's + s/// operator. If you are familiar with Perl, you + will find this to be quite intuitive, and may want to look at the + PCRS documentation for the subtle differences to Perl behaviour. Most + notably, the non-standard option letter U is supported, + which turns the default to ungreedy matching. - - + + If you are new to regular expressions, you might want to take a look at + the Appendix on regular expressions, and + see the Perl + manual for + the + s/// operator's syntax and Perl-style regular + expressions in general. + The below examples might also help to get you started. + - + - - -The Filter File +Filter File Tutorial - Any web page can be dynamically modified with the filter file. This - modification can be removal, or re-writing, of any web page content, - including tags and non-visible content. The default filter file is - default.filter, located in the config directory. + Now, let's complete our foo filter. We have already defined + the heading, but the jobs are still missing. Since all it does is to replace + foo with bar, there is only one (trivial) job + needed: - 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. + s/foo/bar/ + + + But wait! Didn't the comment say that all occurrences + of foo should be replaced? Our current job will only take + care of the first foo on each page. For global substitution, + we'll need to add the g option: - This file uses regular expressions to alter or remove any string in the - target page. The expressions can only operate on one line at a time. Some - examples from the included default default.filter: + s/foo/bar/g - Stop web pages from displaying annoying messages in the status bar by - deleting such references: + Our complete filter now looks like this: + + + FILTER: foo Replace all "foo" with "bar" +s/foo/bar/g - - - - FILTER: html-annoyances + Let's look at some real filters for more interesting examples. Here you see + a filter that protects against some common annoyances that arise from JavaScript + abuse. Let's look at its jobs one after the other: + - # New browser windows should be resizeable and have a location and status - # bar. Make it so. - # - s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig - s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig - s/scrolling="?(no|0|Auto)"?/scrolling=1/ig - s/menubar="?(no|0)"?/menubar=1/ig - # The <BLINK> tag was a crime! - # - s*<blink>|</blink>**ig + + +FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse - # Is this evil? - # - #s/framespacing="?(no|0)"?//ig - #s/margin(height|width)=[0-9]*//gi - - - +# Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm +# +s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg - Just for kicks, replace any occurrence of Microsoft with - MicroSuck, and have a little fun with topical buzzwords: + Following the header line and a comment, you see the job. Note that it uses + | as the delimiter instead of /, because + the pattern contains a forward slash, which would otherwise have to be escaped + by a backslash (\). - - - - FILTER: fun - - s/microsoft(?!.com)/MicroSuck/ig - - # Buzzword Bingo: - # - s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig - - - + Now, let's examine the pattern: it starts with the text <script.* + enclosed in parentheses. Since the dot matches any character, and * + means: Match an arbitrary number of the element left of myself, this + matches <script, followed by any text, i.e. + it matches the whole page, from the start of the first <script> tag. - Kill those pesky little web-bugs: + That's more than we want, but the pattern continues: document\.referrer + matches only the exact string document.referrer. The dot needed to + be escaped, i.e. preceded by a backslash, to take away its + special meaning as a joker, and make it just a regular dot. So far, the meaning is: + Match from the start of the first <script> tag in a the page, up to, and including, + the text document.referrer, if both are present + in the page (and appear in that order). - - - - # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) - FILTER: webbugs - - s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig - - - + But there's still more pattern to go. The next element, again enclosed in parentheses, + is .*</script>. You already know what .* + means, so the whole pattern translates to: Match from the start of the first <script> + tag in a page to the end of the last <script> tag, provided that the text + document.referrer appears somewhere in between. - - - - - - - - - -Templates - When Privoxy displays one of its internal - 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. - + This is still not the whole story, since we have ignored the options and the parentheses: + The portions of the page matched by sub-patterns that are enclosed in parentheses, will be + remembered and be available through the variables $1, $2, ... in + the substitute. The U option switches to ungreedy matching, which means + that the first .* in the pattern will only eat up all + text in between <script and the first occurrence + of document.referrer, and that the second .* will + only span the text up to the first </script> + tag. Furthermore, the s option says that the match may span + multiple lines in the page, and the g option again means that the + substitution is global. - - - - - - + + So, to summarize, the pattern means: Match all scripts that contain the text + document.referrer. Remember the parts of the script from + (and including) the start tag up to (and excluding) the string + document.referrer as $1, and the part following + that string, up to and including the closing tag, as $2. + - -Quickstart to Using <application>Privoxy</application> - Install package, then run and enjoy! Privoxy - is typically started by specifying the main configuration file to be - used on the command line. Example Unix startup command: + Now the pattern is deciphered, but wasn't this about substituting things? So + lets look at the substitute: $1"Not Your Business!"$2 is + easy to read: The text remembered as $1, followed by + "Not Your Business!" (including + the quotation marks!), followed by the text remembered as $2. + This produces an exact copy of the original string, with the middle part + (the document.referrer) replaced by "Not Your + Business!". - - - # /usr/sbin/privoxy /etc/privoxy/config - - + The whole job now reads: Replace document.referrer by + "Not Your Business!" wherever it appears inside a + <script> tag. Note that this job won't break JavaScript syntax, + since both the original and the replacement are syntactically valid + string objects. The script just won't have access to the referrer + information anymore. - An init script is provided for SuSE and Redhat. + We'll show you two other jobs from the JavaScript taming department, but + this time only point out the constructs of special interest: -For for SuSE: /etc/rc.d/privoxy start + +# The status bar is for displaying link targets, not pointless blahblah +# +s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig -For RedHat: /etc/rc.d/init.d/privoxy start + \s stands for whitespace characters (space, tab, newline, + carriage return, form feed), so that \s* means: zero + or more whitespace. The ? in .*? + makes this matching of arbitrary text ungreedy. (Note that the U + option is not set). The ['"] construct means: a single + or a double quote. Finally, \1 is + a backreference to the first parenthesis just like $1 above, + with the difference that in the pattern, a backslash indicates + a backreference, whereas in the substitute, it's the dollar. + + So what does this job do? It replaces assignments of single- or double-quoted + strings to the window.status object with a dummy assignment + (using a variable name that is hopefully odd enough not to conflict with + real variables in scripts). Thus, it catches many cases where e.g. pointless + descriptions are displayed in the status bar instead of the link target when + you move your mouse over links. + - If no configuration file is specified on the command line, - Privoxy will look for a file named - config in the current directory. Except on Win32 where - it will try config.txt. If no file is specified on the - command line and no default configuration file can be found, - Privoxy will fail to start. + +# Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html +# +s/(<body [^>]*)onunload(.*>)/$1never$2/iU - Be sure your browser is set to use the proxy which is by default at - localhost, port 8118. With Netscape (and - Mozilla), this can be set under Edit - -> Preferences -> Advanced -> Proxies -> HTTP Proxy. - 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. + Including the + OnUnload + event binding in the HTML DOM was a CRIME. + When I close a browser window, I want it to close and die. Basta. + This job replaces the onunload attribute in + <body> tags with the dummy word never. + Note that the i option makes the pattern matching + case-insensitive. Also note that ungreedy matching alone doesn't always guarantee + a minimal match: In the first parenthesis, we had to use [^>]* + instead of .* to prevent the match from exceeding the + <body> tag if it doesn't contain OnUnload, but the page's + content does. - The included default configuration files should give a reasonable starting - point, though may be somewhat aggressive in blocking junk. You will probably - want to keep an eye out for sites that require persistent cookies, and add these to - default.action 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. + The last example is from the fun department: - If a particular site shows problems loading properly, try adding it - to the {fragile} section of - default.action. This will turn off most actions for - this site. + +FILTER: fun Fun text replacements + +# Spice the daily news: +# +s/microsoft(?!\.com)/MicroSuck/ig - 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. + Note the (?!\.com) part (a so-called negative lookahead) + in the job's pattern, which means: Don't match, if the string + .com appears directly following microsoft + in the page. This prevents links to microsoft.com from being trashed, while + still replacing the word everywhere else. - 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) - can be adjusted by pointing your browser to - http://p.p/, - and then follow the link to edit the actions list. - (This is an internal page and does not require Internet access.) + +# Buzzword Bingo (example for extended regex syntax) +# +s* industry[ -]leading \ +| cutting[ -]edge \ +| customer[ -]focused \ +| market[ -]driven \ +| award[ -]winning # Comments are OK, too! \ +| high[ -]performance \ +| solutions[ -]based \ +| unmatched \ +| unparalleled \ +| unrivalled \ +*<font color="red"><b>BINGO!</b></font> \ +*igx - In fact, various aspects of Privoxy - 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 - editor mentioned above, Privoxy can also - be turned on and off from this page. + The x option in this job turns on extended syntax, and allows for + e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting. - 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. If a bug, please report it to - the developers (see below). + You get the idea? + + +The Pre-defined Filters - + - -Command Line Options - Privoxy may be invoked with the following - command-line options: +The distribution default.filter file contains a selection of +pre-defined filters for your convenience: - - + + + js-annoyances + + + The purpose of this filter is to get rid of particularly annoying JavaScript abuse. + To that end, it + + + + replaces JavaScript references to the browser's referrer information + with the string "Not Your Business!". This compliments the hide-referrer action on the content level. + + + + + removes the bindings to the DOM's + unload + event which we feel has no right to exist and is responsible for most exit consoles, i.e. + nasty windows that pop up when you close another one. + + + + + removes code that causes new windows to be opened with undesired properties, such as being + full-screen, non-resizable, without location, status or menu bar etc. + + + + + + + + + js-events + + + This is a very radical measure. It removes virtually all JavaScript event bindings, which + means that scripts can not react to user actions such as mouse movements or clicks, window + resizing etc, anymore. + + + We strongly discourage using this filter as a default since it breaks + many legitimate scripts. It is meant for use only on extra-nasty sites (should you really + need to go there). + + + - - - --version - - - Print version info and exit, Unix only. - - - - - --help - - - Print a short usage info and exit, Unix only. - - - - - --no-daemon - - - Don't become a daemon, i.e. don't fork and become process group - leader, don't detach from controlling tty. Unix only. - - - - - --pidfile FILE - - - - On startup, write the process ID to FILE. Delete the - FILE on exit. Failiure to create or delete the - FILE is non-fatal. If no FILE - option is given, no PID file will be used. Unix only. - - - - - --user USER[.GROUP] - - - - After (optionally) writing the PID file, assume the user ID of - USER, and if included the GID of GROUP. Exit if the - privileges are not sufficient to do so. Unix only. - - - - - configfile - - - If no configfile is included on the command line, - 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. - - + + html-annoyances + + + This filter will undo many common instances of HTML based abuse. + + + The BLINK and MARQUEE tags + are neutralized (yeah baby!), and browser windows will be created as + resizable (as of course they should be!), and will have location, + scroll and menu bars -- even if specified otherwise. + + + + + + content-cookies + + + Most cookies are set in the HTTP dialogue, where they can be intercepted + by the + crunch-incoming-cookies + and crunch-outgoing-cookies + actions. But web sites increasingly make use of HTML meta tags and JavaScript + to sneak cookies to the browser on the content level. + + + This filter disables HTML and JavaScript code that reads or sets cookies. Use + it wherever you would also use the cookie crunch actions. + + + + + + refresh tags + + + Disable any refresh tags if the interval is greater than nine seconds (so + that redirections done via refresh tags are not destroyed). This is useful + for dial-on-demand setups, or for those who find this HTML feature + annoying. + + + + + + unsolicited-popups + + + This filter attempts to prevent only unsolicited pop-up + windows from opening, yet still allow pop-up windows that the user + has explicitly chosen to open. It was added in version 3.0.1, + as an improvement over earlier such filters. + + + Technical note: The filter works by redefining the window.open JavaScript + function to a dummy function during the loading and rendering phase of each + HTML page access, and restoring the function afterwards. + + + + + + all-popups + + + Attempt to prevent all pop-up windows from opening. + Note this should be used with more discretion than the above, since it is + more likely to break some sites that require pop-ups for normal usage. Use + with caution. + + + + + + img-reorder + + + This is a helper filter that has no value if used alone. It makes the + banners-by-size and banners-by-link + (see below) filters more effective and should be enabled together with them. + + + + + + banners-by-size + + + This filter removes image tags purely based on what size they are. Fortunately + for us, many ads and banner images tend to conform to certain standardized + sizes, which makes this filter quite effective for ad stripping purposes. + + + Occasionally this filter will cause false positives on images that are not ads, + but just happen to be of one of the standard banner sizes. + + + + + + banners-by-link + + + This is an experimental filter that attempts to kill any banners if + their URLs seem to point to known or suspected click trackers. It is currently + not of much value and is not recommended for use by default. + + + + + + webbugs + + + Webbugs are small, invisible images (technically 1X1 GIF images), that + are used to track users across websites, and collect information on them. + As an HTML page is loaded by the browser, an embedded image tag causes the + browser to contact a third-party site, disclosing the tracking information + through the requested URL and/or cookies for that third-party domain, without + the use ever becoming aware of the interaction with the third-party site. + HTML-ized spam also uses a similar technique to verify email addresses. + + + This filter removes the HTML code that loads such webbugs. + + + + + + tiny-textforms + + + A rather special-purpose filter that can be used to enlarge textareas (those + multi-line text boxes in web forms) and turn off hard word wrap in them. + It was written for the sourceforge.net tracker system where such boxes are + a nuisance, but it can be handy on other sites, too. + + + It is not recommended to use this filter as a default. + + + + + + jumping-windows + + + Many consider windows that move, or resize themselves to be abusive. This filter + neutralizes the related JavaScript code. Note that some sites might not display + or behave as intended when using this filter. + + + + + + frameset-borders + + + Some web designers seem to assume that everyone in the world will view their + web sites using the same browser brand and version, screen resolution etc, + because only that assumption could explain why they'd use static frame sizes, + yet prevent their frames from being resized by the user, should they be too + small to show their whole content. + + + This filter removes the related HTML code. It should only be applied to sites + which need it. + + + + + + demoronizer + + + Many Microsoft products that generate HTML use non-standard extensions (read: + violations) of the ISO 8859-1 aka Latin-1 character set. This can cause those + HTML documents to display with errors on standard-compliant platforms. + + + This filter translates the MS-only characters into Latin-1 equivalents. + It is not necessary when using MS products, and will cause corruption of + all documents that use 8-bit character sets other than Latin-1. It's mostly + worthwhile for Europeans on non-MS platforms, if wierd garbage characters + sometimes appear on some pages, or user agents that don't correct for this on + the fly. + + + + + + + shockwave-flash + + + A filter for shockwave haters. As the name suggests, this filter strips code + out of web pages that is used to embed shockwave flash objects. + + + + + + + + quicktime-kioskmode + + + Change HTML code that embeds Quicktime objects so that kioskmode, which + prevents saving, is disabled. + + + + + + fun + + + Text replacements for subversive browsing fun. Make fun of your favorite + Monopolist or play buzzword bingo. + + + - - + + crude-parental + + + A demonstration-only filter that shows how Privoxy + can be used to delete web content on a keyword basis. + + + - + + ie-exploits + + + A collection of text replacements to disable malicious HTML and JavaScript + code that exploits known security holes in Internet Explorer. + + + Presently, it only protects against Nimda and a cross-site scripting bug, and + would need active maintenance to provide more substantial protection. + + + + + + site-specifics + + + Some web sites have very specific problems, the cure for which doesn't apply + anywhere else, or could even cause damage on other sites. + + + This is a collection of such site-specific cures which should only be applied + to the sites they were intended for, which is what the supplied + default.action file does. Users shouldn't need to change + anything regarding this filter. + + + + + + filter-server-headers + + + + + + + + filter-client-headers + + + + + + + + + @@ -3198,138 +6522,145 @@ For RedHat: /etc/rc.d/init.d/privoxy start -Contacting the Developers, Bug Reporting and Feature -Requests + +Templates -We value your feedback. However, to provide you with the best support, -please note: + All Privoxy built-in pages, i.e. error pages such as the + 404 - No Such Domain + error page, the BLOCKED + page + and all pages of its web-based + user interface, are generated from templates. + (Privoxy must be running for the above links to work as + intended.) + - + + These templates are stored in a subdirectory of the configuration + directory called templates. On Unixish platforms, + this is typically + /etc/privoxy/templates/. + - 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. - + + The templates are basically normal HTML files, but with place-holders (called symbols + or exports), which Privoxy fills at run time. You can + edit the templates with a normal text editor, should you want to customize them. + (Not recommended for the casual user). Note that + just like in configuration files, lines starting with # are + ignored when the templates are filled in. + - - Submit feature requests only thru our Sourceforge feature request forum. + + The place-holders are of the form @name@, and you will + find a list of available symbols, which vary from template to template, + in the comments at the start of each file. Note that these comments are not + always accurate, and that it's probably best to look at the existing HTML + code to find out which symbols are supported and what they are filled in with. + + + + A special application of this substitution mechanism is to make whole + blocks of HTML code disappear when a specific symbol is set. We use this + for many purposes, one of them being to include the beta warning in all + our user interface (CGI) pages when Privoxy + is in an alpha or beta development stage: + + + +<!-- @if-unstable-start --> - + ... beta warning HTML code goes here ... +<!-- if-unstable-end@ --> -For any other issues, feel free to use the mailing lists. + If the "unstable" symbol is set, everything in between and including + @if-unstable-start and if-unstable-end@ + will disappear, leaving nothing but an empty comment: - Anyone interested in actively participating in development and related - discussions can join the appropriate mailing list - here. - Archives are available here too. + <!-- --> + + + + There's also an if-then-else construct and an #include + mechanism, but you'll sure find out if you are inclined to edit the + templates ;-) + + + + All templates refer to a style located at + http://config.privoxy.org/send-stylesheet. + This is, of course, locally served by Privoxy + and the source for it can be found and edited in the + cgi-style.css template. + + + -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. - +Contacting the Developers, Bug Reporting and Feature +Requests - - 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. - + + &contacting; + - + +<application>Privoxy</application> Copyright, License and History - -History - - 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 was v2.0.2, which has now - grown whiskers ;-). - + + ©right; + + +License + + &license; + + - -See also - - - - -   http://sourceforge.net/projects/ijbswa - - - - -   http://ijbswa.sourceforge.net/ - - - - -   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/ - - - +History + + &history; + + + +Authors + + &p-authors; + + + + + + + + + +See Also + + &seealso; + @@ -3342,30 +6673,33 @@ For any other issues, feel free to use the Regular Expressions - Privoxy can use regular expressions - in various config files. Assuming support for pcre (Perl - Compatible Regular Expressions) is compiled in, which is the default. Such - configuration directives do not require regular expressions, but they can be - used to increase flexibility by matching a pattern with wild-cards against - URLs. + Privoxy uses Perl-style regular + expressions in its actions + files and filter file, + through the PCRE and + + PCRS libraries. If you are reading this, you probably don't understand what regular expressions are, or what they can do. So this will be a very brief - introduction only. A full explanation would require a book ;-) + introduction only. A full explanation would require a book ;-) - Regular expressions is a way of matching one character - expression against another to see if it matches or not. One of the - expressions is a literal string of readable characters - (letter, numbers, etc), and the other is a complex string of literal - characters combined with wild-cards, and other special characters, called - meta-characters. The meta-characters have special meanings and - are used to build the complex pattern to be matched against. Perl Compatible - Regular Expressions is an enhanced form of the regular expression language - with backward compatibility. + Regular expressions provide a language to describe patterns that can be + run against strings of characters (letter, numbers, etc), to see if they + match the string or not. The patterns are themselves (sometimes complex) + strings of literal characters, combined with wild-cards, and other special + characters, called meta-characters. The meta-characters have + special meanings and are used to build complex patterns to be matched against. + Perl Compatible Regular Expressions are an especially convenient + dialect of the regular expression language. @@ -3386,72 +6720,71 @@ For any other issues, feel free to use the - - s/microsoft(?!.com)/MicroSuck/i - This is - a substitution. MicroSuck will replace any occurrence of - microsoft. The i at the end of the expression - means ignore case. The (?!.com) means - the match should fail if microsoft is followed by - .com. In other words, this acts like a NOT - modifier. In case this is a hyperlink, we don't want to break it ;-). - - We are barely scratching the surface of regular expressions here so that you can understand the default Privoxy @@ -3566,6 +6889,11 @@ For any other issues, feel free to use the http://www.perldoc.com/perl5.6/pod/perlre.html + + For information on regular expression based substitutions and their applications + in filters, please see the filter file tutorial + in this manual. + @@ -3578,7 +6906,7 @@ For any other issues, feel free to use the
- http://ijbswa.sourceforge.net/config/ + http://config.privoxy.org/ + +
+ + There is a shortcut: http://p.p/ (But it + doesn't provide a fall-back to a real page, in case the request is not + sent through Privoxy) + + + + + + Show information about the current configuration, including viewing and + editing of actions files: + +
+ + http://config.privoxy.org/show-status + +
+ + + + + Show the source code version numbers: + +
+ + http://config.privoxy.org/show-version + +
+ + + + + Show the browser's request headers: + +
+ + http://config.privoxy.org/show-request + +
+ + + + + Show which actions apply to a URL and why: + +
+ + http://config.privoxy.org/show-url-info + +
+ + + + + Toggle Privoxy on or off. In this case, Privoxy continues + to run, but only as a pass-through proxy, with no actions taking place: + +
+ + http://config.privoxy.org/toggle + +
+ + Short cuts. Turn off, then on: + +
+ + http://config.privoxy.org/toggle?set=disable + +
+
+ + http://config.privoxy.org/toggle?set=enable
+ + + + + + + These may be bookmarked for quick reference. See next. + + + + +Bookmarklets + + 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 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. + + + + + + + + Privoxy - Enable + + + + + + Privoxy - Disable + + + + + + Privoxy - Toggle Privoxy (Toggles between enabled and disabled) + + + + + + Privoxy- View Status + + + + + + Privoxy - Why? + + + + + + + Credit: The site which gave us the general idea for these bookmarklets is + www.bookmarklets.com. They + have more information about bookmarklets. + + + + + + + + + + +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. + + + - Alternately, this may be reached at http://p.p/, but this - variation may not work as reliably as the above in some configurations. + If the URL pattern matches the +fast-redirects action, + it is then processed. Unwanted parts of the requested URL are stripped. - - + - - Show information about the current configuration: + + 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. -
- - http://ijbswa.sourceforge.net/config/show-status - -
- - + - - Show the source code version numbers: + + Now the web server starts sending its response back (i.e. typically a web page and related + data). -
- - http://ijbswa.sourceforge.net/config/show-version - -
- - + - - Show the client's request headers: + + 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 determined by the + +crunch-incoming-cookies, + +session-cookies-only, + and +downgrade-http-version + actions. -
- - http://ijbswa.sourceforge.net/config/show-request - -
- - + - - Show which actions apply to a URL and why: + + 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. -
- - http://ijbswa.sourceforge.net/config/show-url-info - -
- - + - - Toggle Privoxy on or off: + + 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 one of the + filter files. 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. -
- - http://ijbswa.sourceforge.net/config/toggle - -
- Short cuts. Turn off, then on: + If neither +filter + or +deanimate-gifs + matches, then Privoxy passes the raw data through + to the client browser as it becomes available. -
- - http://ijbswa.sourceforge.net/config/toggle?set=disable - -
-
- - http://ijbswa.sourceforge.net/config/toggle?set=enable - -
- - + - - Edit the actions list file: + + 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. -
- - http://ijbswa.sourceforge.net/config/edit-actions - -
- + - - These may be bookmarked for quick reference. - - - @@ -3709,111 +7224,145 @@ For any other issues, feel free to use the http://ijbswa.sourceforge.net/config/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. - + 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. + - First, enter one URL (or partial URL) at the prompt, and then - Privoxy will tell us - how current configuration will handle it. This will not - help with filtering effects from the default.filter! 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. + 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!). Looking at the + logs is a good idea too. - Let's look at an example, google.com, - one section at a time: + 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. - - 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 } - - + 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 (i.e. the +filter action) from + one of the filter files 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. - 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: + Let's try an example, google.com, + and look at it one section at a time: - Matches for http://google.com: - { -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 } - / - - { -no-cookies-keep -no-cookies-read -no-cookies-set } - .google.com + In file: default.action [ View ] [ Edit ] + +{-add-header + -block + -crunch-outgoing-cookies + -crunch-incoming-cookies + +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 + -kill-popups + -limit-connect + +prevent-compression + -send-vanilla-wafer + -send-wafer + +session-cookies-only + +set-image-blocker{pattern} } +/ + + { -session-cookies-only } + .google.com { -fast-redirects } - .google.com + .google.com - +In file: user.action [ View ] [ Edit ] +(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: @@ -3822,16 +7371,44 @@ 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.) @@ -3868,14 +7445,18 @@ 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. One last example. Let's try http://www.rhapsodyk.net/adsl/HOWTO/. - This one is giving us problems. We are getting a blank page. Hmmm... + This one is giving us problems. We are getting a blank page. Hmmm ... @@ -3883,27 +7464,47 @@ For any other issues, feel free to use the + + + + + 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 +handle-as-image } + /ads + + + + + That actually was very telling and pointed us quickly to where the problem + was. If you don't get this kind of match, then it means one of the default + rules in the first section is causing the problem. This would require some + guesswork, and maybe a little trial and error to isolate the offending rule. + One likely cause would be one of the {+filter} actions. These + tend to be harder to troubleshoot. Try adding the URL for the site to one of + aliases that turn off +filter: + + + + + + {shop} + .quietpc.com + .worldpay.com # for quietpc.com + .jungle.com + .scan.co.uk + .forbes.com + + + + + {shop} is an alias that expands to + { -filter -session-cookies-only }. + Or you could do your own exception to negate filtering: + + + + + + + {-filter} + .forbes.com + + + + + This would turn off all filtering for that site. This would probably be most + appropriately put in user.action, for local site + exceptions. - Now the page displays ;-) + Images that are inexplicably being blocked, may well be hitting the + +filter{banners-by-size} rule, which assumes + that images of certain sizes are ad banners (works well most of the time + since these tend to be standardized). + + + {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. @@ -3945,6 +7615,395 @@ For any other issues, feel free to use the style. + - Small fixes in the actions chapter + - Small clarifications in the quickstart to ad blocking + - Removed from s since the new doc CSS + renders them red (bad in TOC). + + Revision 1.120 2002/05/23 19:16:43 roro + Correct Debian specials (installation and startup). + + Revision 1.119 2002/05/22 17:17:05 oes + Added Security hint + + Revision 1.118 2002/05/21 04:54:55 hal9 + -New Section: Quickstart to Ad Blocking + -Reformat Actions Anatomy to match new CGI layout + + Revision 1.117 2002/05/17 13:56:16 oes + - Reworked & extended Templates chapter + - Small changes to Regex appendix + - #included authors.sgml into (C) and hist chapter + + Revision 1.116 2002/05/17 03:23:46 hal9 + Fixing merge conflict in Quickstart section. + + Revision 1.115 2002/05/16 16:25:00 oes + Extended the Filter File chapter & minor fixes + + Revision 1.114 2002/05/16 09:42:50 oes + More ulink->link, added some hints to Quickstart section + + Revision 1.113 2002/05/15 21:07:25 oes + Extended and further commented the example actions files + + Revision 1.112 2002/05/15 03:57:14 hal9 + Spell check. A few minor edits here and there for better syntax and + clarification. + + Revision 1.111 2002/05/14 23:01:36 oes + Fixing the fixes + + Revision 1.110 2002/05/14 19:10:45 oes + Restored alphabetical order of actions + + Revision 1.109 2002/05/14 17:23:11 oes + Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs + + Revision 1.108 2002/05/14 15:29:12 oes + Completed proofreading the actions chapter + + Revision 1.107 2002/05/12 03:20:41 hal9 + Small clarifications for 127.0.0.1 vs localhost for listen-address since this + apparently an important distinction for some OS's. + + Revision 1.106 2002/05/10 01:48:20 hal9 + This is mostly proposed copyright/licensing additions and changes. Docs + are still GPL, but licensing and copyright are more visible. Also, copyright + changed in doc header comments (eliminate references to JB except FAQ). + + Revision 1.105 2002/05/05 20:26:02 hal9 + Sorting out license vs copyright in these docs. + + Revision 1.104 2002/05/04 08:44:45 swa + bumped version + + Revision 1.103 2002/05/04 00:40:53 hal9 + -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in. + -Some minor additions to Quickstart. + + Revision 1.102 2002/05/03 17:46:00 oes + Further proofread & reactivated short build instructions + + Revision 1.101 2002/05/03 03:58:30 hal9 + Move the user-manual config directive to top of section. Add note about + Privoxy needing read permissions for configs, and write for logs. + + Revision 1.100 2002/04/29 03:05:55 hal9 + Add clarification on differences of new actions files. + + Revision 1.99 2002/04/28 16:59:05 swa + more structure in starting section + + Revision 1.98 2002/04/28 05:43:59 hal9 + This is the break up of configuration.html into multiple files. This + will probably break links elsewhere :( + + Revision 1.97 2002/04/27 21:04:42 hal9 + -Rewrite of Actions File example. + -Add section for user-manual directive in config. + + Revision 1.96 2002/04/27 05:32:00 hal9 + -Add short section to Filter Files to tie in with +filter action. + -Start rewrite of examples in Actions Examples (not finished). + + Revision 1.95 2002/04/26 17:23:29 swa + bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot + + Revision 1.94 2002/04/26 05:24:36 hal9 + -Add most of Andreas suggestions to Chain of Events section. + -A few other minor corrections and touch up. + + Revision 1.92 2002/04/25 18:55:13 hal9 + More catchups on new actions files, and new actions names. + Other assorted cleanups, and minor modifications. + + Revision 1.91 2002/04/24 02:39:31 hal9 + Add 'Chain of Events' section. + + Revision 1.90 2002/04/23 21:41:25 hal9 + Linuxconf is deprecated on RH, substitute chkconfig. + + Revision 1.89 2002/04/23 21:05:28 oes + Added hint for startup on Red Hat + + Revision 1.88 2002/04/23 05:37:54 hal9 + Add AmigaOS install stuff. + + Revision 1.87 2002/04/23 02:53:15 david__schmidt + Updated OSX installation section + Added a few English tweaks here an there + + Revision 1.86 2002/04/21 01:46:32 hal9 + Re-write actions section. + + Revision 1.85 2002/04/18 21:23:23 hal9 + Fix ugly typo (mine). + + Revision 1.84 2002/04/18 21:17:13 hal9 + Spell Redhat correctly (ie Red Hat). A few minor grammar corrections. + + Revision 1.83 2002/04/18 18:21:12 oes + Added RPM install detail + + Revision 1.82 2002/04/18 12:04:50 oes + Cosmetics + + Revision 1.81 2002/04/18 11:50:24 oes + Extended Install section - needs fixing by packagers + + Revision 1.80 2002/04/18 10:45:19 oes + Moved text to buildsource.sgml, renamed some filters, details + + Revision 1.79 2002/04/18 03:18:06 hal9 + Spellcheck, and minor touchups. + + Revision 1.78 2002/04/17 18:04:16 oes + Proofreading part 2 + + Revision 1.77 2002/04/17 13:51:23 oes + Proofreading, part one + + Revision 1.76 2002/04/16 04:25:51 hal9 + -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section. + -Note about proxy may need requests to re-read config files. + + Revision 1.75 2002/04/12 02:08:48 david__schmidt + Remove OS/2 building info... it is already in the developer-manual + + Revision 1.74 2002/04/11 00:54:38 hal9 + Add small section on submitting actions. + + Revision 1.73 2002/04/10 18:45:15 swa + generated + + Revision 1.72 2002/04/10 04:06:19 hal9 + Added actions feedback to Bookmarklets section + + Revision 1.71 2002/04/08 22:59:26 hal9 + Version update. Spell chkconfig correctly :) + + Revision 1.70 2002/04/08 20:53:56 swa + ? + + Revision 1.69 2002/04/06 05:07:29 hal9 + -Add privoxy-man-page.sgml, for man page. + -Add authors.sgml for AUTHORS (and p-authors.sgml) + -Reworked various aspects of various docs. + -Added additional comments to sub-docs. + + Revision 1.68 2002/04/04 18:46:47 swa + consistent look. reuse of copyright, history et. al. + + Revision 1.67 2002/04/04 17:27:57 swa + more single file to be included at multiple points. make maintaining easier + + Revision 1.66 2002/04/04 06:48:37 hal9 + Structural changes to allow for conditional inclusion/exclusion of content + based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And + definition of internal entities, e.g. 'entity p-version "2.9.13"' that will + eventually be set by Makefile. + More boilerplate text for use across multiple docs. + + Revision 1.65 2002/04/03 19:52:07 swa + enhance squid section due to user suggestion + + Revision 1.64 2002/04/03 03:53:43 hal9 + A few minor bug fixes, and touch ups. Ready for review. + + Revision 1.63 2002/04/01 16:24:49 hal9 + Define entities to include boilerplate text. See doc/source/*. + + Revision 1.62 2002/03/30 04:15:53 hal9 + - Fix privoxy.org/config links. + - Paste in Bookmarklets from Toggle page. + - Move Quickstart nearer top, and minor rework. + + Revision 1.61 2002/03/29 01:31:08 hal9 + Minor update. + + Revision 1.60 2002/03/27 01:57:34 hal9 + Added more to Anatomy section. + + Revision 1.59 2002/03/27 00:54:33 hal9 + Touch up intro for new name. + + Revision 1.58 2002/03/26 22:29:55 swa + we have a new homepage! + + Revision 1.57 2002/03/24 20:33:30 hal9 + A few minor catch ups with name change. + + Revision 1.56 2002/03/24 16:17:06 swa + configure needs to be generated. + Revision 1.55 2002/03/24 16:08:08 swa we are too lazy to make a block-built privoxy logo. hence removed the option.