From c27e23a43e40973e170cf901c729b14da6d3b9e8 Mon Sep 17 00:00:00 2001 From: hal9 Date: Sat, 19 Jan 2008 21:41:39 +0000 Subject: [PATCH] Re-commit to solve various last minute issues for charsets, etc. --- AUTHORS | 12 +- doc/text/developer-manual.txt | 3380 ++--- doc/text/faq.txt | 3625 +++--- doc/text/user-manual.txt | 10287 ++++++++-------- doc/webserver/developer-manual/coding.html | 9 +- doc/webserver/developer-manual/contact.html | 5 +- doc/webserver/developer-manual/copyright.html | 5 +- doc/webserver/developer-manual/cvs.html | 5 +- .../developer-manual/documentation.html | 5 +- doc/webserver/developer-manual/index.html | 7 +- .../developer-manual/introduction.html | 5 +- .../developer-manual/newrelease.html | 5 +- doc/webserver/developer-manual/seealso.html | 5 +- doc/webserver/developer-manual/testing.html | 5 +- .../developer-manual/webserver-update.html | 5 +- doc/webserver/faq/configuration.html | 5 +- doc/webserver/faq/contact.html | 5 +- doc/webserver/faq/copyright.html | 5 +- doc/webserver/faq/general.html | 5 +- doc/webserver/faq/index.html | 7 +- doc/webserver/faq/installation.html | 5 +- doc/webserver/faq/misc.html | 5 +- doc/webserver/faq/trouble.html | 5 +- doc/webserver/index.html | 5 +- doc/webserver/privoxy-index.html | 5 +- doc/webserver/user-manual/actions-file.html | 5 +- doc/webserver/user-manual/appendix.html | 5 +- doc/webserver/user-manual/config.html | 5 +- doc/webserver/user-manual/configuration.html | 5 +- doc/webserver/user-manual/contact.html | 5 +- doc/webserver/user-manual/copyright.html | 5 +- doc/webserver/user-manual/filter-file.html | 5 +- doc/webserver/user-manual/index.html | 7 +- doc/webserver/user-manual/installation.html | 5 +- doc/webserver/user-manual/introduction.html | 5 +- doc/webserver/user-manual/quickstart.html | 5 +- doc/webserver/user-manual/seealso.html | 5 +- doc/webserver/user-manual/startup.html | 7 +- doc/webserver/user-manual/templates.html | 5 +- doc/webserver/user-manual/whatsnew.html | 5 +- privoxy.1 | 2 +- 41 files changed, 9023 insertions(+), 8475 deletions(-) diff --git a/AUTHORS b/AUTHORS index d295723d..2393ab08 100644 --- a/AUTHORS +++ b/AUTHORS @@ -9,7 +9,7 @@ Hal Burgiss Gerry Murphy Roland Rosenfeld - Jörg Strohmayer + Jörg Strohmayer Former Privoxy Team Members: @@ -22,7 +22,7 @@ Karsten Hopp Alexander Lazic Daniel Leite - Gábor Lipták + Gábor Lipták Adam Lock Guy Laroche Mark Martinec @@ -46,7 +46,7 @@ Reiner Buehl Andrew J. Caines Clifford Caoile - Frédéric Crozat + Frédéric Crozat Michael T. Davis Mattes Dolak Peter E. @@ -55,7 +55,7 @@ Dean Gaudet Stephen Gildea Daniel Griscom - Felix Gröbert + Felix Gröbert Aaron Hamid Darel Henman Magnus Holmgren @@ -78,7 +78,7 @@ Dan Price Lee R. Roberto Ragusa - Félix Rauch + Félix Rauch Maynard Riley Chung-chieh Shan Spinor S. @@ -87,7 +87,7 @@ Peter Thoenen Martin Thomas Song Weijia - Jörg Weinmann + Jörg Weinmann Darren Wiebe Bobby G. Vinyard Anduin Withers diff --git a/doc/text/developer-manual.txt b/doc/text/developer-manual.txt index eeb17e30..31a5faf8 100644 --- a/doc/text/developer-manual.txt +++ b/doc/text/developer-manual.txt @@ -1,1450 +1,1507 @@ -Privoxy Developer Manual + Privoxy Developer Manual -[ Copyright 2001-2008 by Privoxy Developers ] + [Copyright[ © 2001-2008 by Privoxy Developers]] -$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $ + $Id: developer-manual.sgml,v 2.16 2008/01/19 17:52:38 hal9 Exp $ -The developer manual provides guidance on coding, testing, packaging, -documentation and other issues of importance to those involved with Privoxy -development. It is mandatory (and helpful!) reading for anyone who wants to -join the team. Note that it's currently out of date and may not be entirely -correct. As always, patches are welcome. + The developer manual provides guidance on coding, testing, packaging, + documentation and other issues of importance to those involved with + Privoxy development. It is mandatory (and helpful!) reading for anyone who + wants to join the team. Note that it's currently out of date and may not + be entirely correct. As always, patches are welcome. -Please note that this document is constantly evolving. This copy represents the -state at the release of version 3.0.8. You can find the latest version of the -this manual at http://www.privoxy.org/developer-manual/. Please see the Contact -section on how to contact the developers. + Please note that this document is constantly evolving. This copy + represents the state at the release of version 3.0.8. You can find the + latest version of the this manual at + http://www.privoxy.org/developer-manual/. Please see the Contact section + on how to contact the developers. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -Table of Contents -1. Introduction + Table of Contents - 1.1. Quickstart to Privoxy Development + 1. Introduction -2. The CVS Repository + 1.1. Quickstart to Privoxy Development - 2.1. Access to CVS - 2.2. Branches - 2.3. CVS Commit Guidelines + 2. The CVS Repository -3. Documentation Guidelines + 2.1. Access to CVS - 3.1. Quickstart to Docbook and SGML - 3.2. Privoxy Documentation Style - 3.3. Privoxy Custom Entities + 2.2. Branches -4. Coding Guidelines + 2.3. CVS Commit Guidelines - 4.1. Introduction - 4.2. Using Comments - - 4.2.1. Comment, Comment, Comment - 4.2.2. Use blocks for comments - 4.2.3. Keep Comments on their own line - 4.2.4. Comment each logical step - 4.2.5. Comment All Functions Thoroughly - 4.2.6. Comment at the end of braces if the content is more than one - screen length - - 4.3. Naming Conventions - - 4.3.1. Variable Names - 4.3.2. Function Names - 4.3.3. Header file prototypes - 4.3.4. Enumerations, and #defines - 4.3.5. Constants - - 4.4. Using Space - - 4.4.1. Put braces on a line by themselves. - 4.4.2. ALL control statements should have a block - 4.4.3. Do not belabor/blow-up boolean expressions - 4.4.4. Use white space freely because it is free - 4.4.5. Don't use white space around structure operators - 4.4.6. Make the last brace of a function stand out - 4.4.7. Use 3 character indentions - - 4.5. Initializing - - 4.5.1. Initialize all variables - - 4.6. Functions - - 4.6.1. Name functions that return a boolean as a question. - 4.6.2. Always specify a return type for a function. - 4.6.3. Minimize function calls when iterating by using variables - 4.6.4. Pass and Return by Const Reference - 4.6.5. Pass and Return by Value - 4.6.6. Names of include files - 4.6.7. Provide multiple inclusion protection - 4.6.8. Use `extern "C"` when appropriate - 4.6.9. Where Possible, Use Forward Struct Declaration Instead of - Includes - - 4.7. General Coding Practices - - 4.7.1. Turn on warnings - 4.7.2. Provide a default case for all switch statements - 4.7.3. Try to avoid falling through cases in a switch statement. - 4.7.4. Use 'long' or 'short' Instead of 'int' - 4.7.5. Don't mix size_t and other types - 4.7.6. Declare each variable and struct on its own line. - 4.7.7. Use malloc/zalloc sparingly - 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring - 'free' - 4.7.9. Add loaders to the `file_list' structure and in order - 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME - or XXX - - 4.8. Addendum: Template for files and function comment blocks: + 3. Documentation Guidelines -5. Testing Guidelines + 3.1. Quickstart to Docbook and SGML - 5.1. Testplan for releases - 5.2. Test reports + 3.2. Privoxy Documentation Style -6. Releasing a New Version + 3.3. Privoxy Custom Entities - 6.1. Version numbers - 6.2. Before the Release: Freeze - 6.3. Building and Releasing the Packages - - 6.3.1. Note on Privoxy Packaging - 6.3.2. Source Tarball - 6.3.3. SuSE, Conectiva or Red Hat RPM - 6.3.4. OS/2 - 6.3.5. Solaris - 6.3.6. Windows - 6.3.7. Debian - 6.3.8. Mac OSX - 6.3.9. FreeBSD - 6.3.10. HP-UX 11 - 6.3.11. Amiga OS - 6.3.12. AIX - - 6.4. Uploading and Releasing Your Package - 6.5. After the Release + 4. Coding Guidelines -7. Update the Webserver -8. Contacting the developers, Bug Reporting and Feature Requests + 4.1. Introduction - 8.1. Get Support - 8.2. Reporting Problems + 4.2. Using Comments - 8.2.1. Reporting Ads or Other Configuration Problems - 8.2.2. Reporting Bugs + 4.2.1. Comment, Comment, Comment - 8.3. Request New Features - 8.4. Other + 4.2.2. Use blocks for comments -9. Privoxy Copyright, License and History + 4.2.3. Keep Comments on their own line - 9.1. License - 9.2. History + 4.2.4. Comment each logical step -10. See also + 4.2.5. Comment All Functions Thoroughly -1. Introduction + 4.2.6. Comment at the end of braces if the + content is more than one screen length -Privoxy, as an heir to Junkbuster, is a Free Software project and the code is -licensed under the GPL. As such, Privoxy development is potentially open to -anyone who has the time, knowledge, and desire to contribute in any capacity. -Our goals are simply to continue the mission, to improve Privoxy, and to make -it available to as wide an audience as possible. + 4.3. Naming Conventions -One does not have to be a programmer to contribute. Packaging, testing, -documenting and porting, are all important jobs as well. + 4.3.1. Variable Names -------------------------------------------------------------------------------- + 4.3.2. Function Names -1.1. Quickstart to Privoxy Development + 4.3.3. Header file prototypes -The first step is to join the developer's mailing list. You can submit your -ideas, or even better patches. Patches are best submitted to the Sourceforge -tracker set up for this purpose, but can be sent to the list for review too. + 4.3.4. Enumerations, and #defines -You will also need to have a cvs package installed, which will entail having -ssh installed as well (which seems to be a requirement of SourceForge), in -order to access the cvs repository. Having the GNU build tools is also going to -be important (particularly, autoconf and gmake). + 4.3.5. Constants -For the time being (read, this section is under construction), you can also -refer to the extensive comments in the source code. In fact, reading the code -is recommended in any case. + 4.4. Using Space -------------------------------------------------------------------------------- + 4.4.1. Put braces on a line by themselves. -2. The CVS Repository + 4.4.2. ALL control statements should have a + block -If you become part of the active development team, you will eventually need -write access to our holy grail, the CVS repository. One of the team members -will need to set this up for you. Please read this chapter completely before -accessing via CVS. + 4.4.3. Do not belabor/blow-up boolean + expressions -------------------------------------------------------------------------------- + 4.4.4. Use white space freely because it is free -2.1. Access to CVS + 4.4.5. Don't use white space around structure + operators -The project's CVS repository is hosted on SourceForge. Please refer to the -chapters 6 and 7 in SF's site documentation for the technical access details -for your operating system. For historical reasons, the CVS server is called -ijbswa.cvs.sourceforge.net, the repository is called ijbswa, and the source -tree module is called current. + 4.4.6. Make the last brace of a function stand + out -------------------------------------------------------------------------------- + 4.4.7. Use 3 character indentions -2.2. Branches + 4.5. Initializing -Within the CVS repository, there are modules and branches. As mentioned, the -sources are in the current "module". Other modules are present for platform -specific issues. There is a webview of the CVS hierarchy at http:// -ijbswa.cvs.sourceforge.net/ijbswa/, which might help with visualizing how these -pieces fit together. + 4.5.1. Initialize all variables -Branches are used to fork a sub-development path from the main trunk. Within -the current module where the sources are, there is always at least one "branch" -from the main trunk devoted to a stable release series. The main trunk is where -active development takes place for the next stable series (e.g. 3.2.x). So just -prior to each stable series (e.g. 3.0.x), a branch is created just for stable -series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). Once the initial stable -release of any stable branch has taken place, this branch is only used for -bugfixes, which have had prior testing before being committed to CVS. (See -Version Numbers below for details on versioning.) + 4.6. Functions -At one time there were two distinct branches: stable and unstable. The more -drastic changes were to be in the unstable branch. These branches have now been -merged to minimize time and effort of maintaining two branches. + 4.6.1. Name functions that return a boolean as a + question. -------------------------------------------------------------------------------- + 4.6.2. Always specify a return type for a + function. -2.3. CVS Commit Guidelines + 4.6.3. Minimize function calls when iterating by + using variables -The source tree is the heart of every software project. Every effort must be -made to ensure that it is readable, compilable and consistent at all times. -There are differing guidelines for the stable branch and the main development -trunk, and we ask anyone with CVS access to strictly adhere to the following -guidelines: + 4.6.4. Pass and Return by Const Reference -Basic Guidelines, for all branches: + 4.6.5. Pass and Return by Value - * Please don't commit even a small change without testing it thoroughly - first. When we're close to a public release, ask a fellow developer to - review your changes. + 4.6.6. Names of include files - * Your commit message should give a concise overview of what you changed (no - big details) and why you changed it Just check previous messages for good - examples. + 4.6.7. Provide multiple inclusion protection - * Don't use the same message on multiple files, unless it equally applies to - all those files. + 4.6.8. Use `extern "C"` when appropriate - * If your changes span multiple files, and the code won't recompile unless - all changes are committed (e.g. when changing the signature of a function), - then commit all files one after another, without long delays in between. If - necessary, prepare the commit messages in advance. + 4.6.9. Where Possible, Use Forward Struct + Declaration Instead of Includes - * Before changing things on CVS, make sure that your changes are in line with - the team's general consensus on what should be done. + 4.7. General Coding Practices - * Note that near a major public release, we get more cautious. There is - always the possibility to submit a patch to the patch tracker instead. + 4.7.1. Turn on warnings -------------------------------------------------------------------------------- + 4.7.2. Provide a default case for all switch + statements -3. Documentation Guidelines + 4.7.3. Try to avoid falling through cases in a + switch statement. -All formal documents are maintained in Docbook SGML and located in the doc/ -source/* directory. You will need Docbook, the Docbook DTD's and the Docbook -modular stylesheets (or comparable alternatives), and either jade or openjade -(recommended) installed in order to build docs from source. Currently there is -user-manual, FAQ, and, of course this, the developer-manual in this format. The -README, AUTHORS, INSTALL, privoxy.1 (man page), and config files are also now -maintained as Docbook SGML. These files, when built, in the top-level source -directory are generated files! Also, the Privoxy index.html (and a variation on -this file, privoxy-index.html, meant for inclusion with doc packages), are -maintained as SGML as well. DO NOT edit these directly. Edit the SGML source, -or contact someone involved in the documentation. - -config requires some special handling. The reason it is maintained this way is -so that the extensive comments in the file mirror those in user-manual. But the -conversion process requires going from SGML to HTML to text to special -formatting required for the embedded comments. Some of this does not survive so -well. Especially some of the examples that are longer than 80 characters. The -build process for this file outputs to config.new, which should be reviewed for -errors and mis-formatting. Once satisfied that it is correct, then it should be -hand copied to config. - -Other, less formal documents (e.g. LICENSE) are maintained as plain text files -in the top-level source directory. - -Packagers are encouraged to include this documentation. For those without the -ability to build the docs locally, text versions of each are kept in CVS. HTML -versions are also being kept in CVS under doc/webserver/*. And PDF version are -kept in doc/pdf/*. - -Formal documents are built with the Makefile targets of make dok, or -alternately make redhat-dok. If you have problems, try both. The build process -uses the document SGML sources in doc/source/*/* to update all text files in -doc/text/ and to update all HTML documents in doc/webserver/. - -Documentation writers should please make sure documents build successfully -before committing to CVS, if possible. - -How do you update the webserver (i.e. the pages on privoxy.org)? - - 1. First, build the docs by running make dok (or alternately make redhat-dok). - For PDF docs, do make dok-pdf. - - 2. Run make webserver which copies all files from doc/webserver to the - sourceforge webserver via scp. - -Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html) -so that those without the ability to build them locally, have access to them if -needed. This is especially important just prior to a new release! Please do -this after the $VERSION and other release specific data in configure.in has -been updated (this is done just prior to a new release). - -------------------------------------------------------------------------------- - -3.1. Quickstart to Docbook and SGML - -If you are not familiar with SGML, it is a markup language similar to HTML. -Actually, not a mark up language per se, but a language used to define markup -languages. In fact, HTML is an SGML application. Both will use "tags" to format -text and other content. SGML tags can be much more varied, and flexible, but do -much of the same kinds of things. The tags, or "elements", are definable in -SGML. There is no set "standards". Since we are using Docbook, our tags are -those that are defined by Docbook. Much of how the finish document is rendered -is determined by the "stylesheets". The stylesheets determine how each tag gets -translated to HTML, or other formats. - -Tags in Docbook SGML need to be always "closed". If not, you will likely -generate errors. Example: My Title. They are also -case-insensitive, but we strongly suggest using all lower case. This keeps -compatibility with [Docbook] XML. + 4.7.4. Use 'long' or 'short' Instead of 'int' -Our documents use "sections" for the most part. Sections will be processed into -HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to -also generate the Table of Contents for each doc. Our TOC's are set to a depth -of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will -not. Each section requires a element, and at least one <para>. There is -a limit of five section levels in Docbook, but generally three should be -sufficient for our purposes. + 4.7.5. Don't mix size_t and other types -Some common elements that you likely will use: - -<para></para>, paragraph delimiter. Most text needs to be within paragraph -elements (there are some exceptions). -<emphasis></emphasis>, the stylesheets make this italics. -<filename></filename>, files and directories. -<command></command>, command examples. -<literallayout></literallayout>, like <pre>, more or less. -<itemizedlist></itemizedlist>, list with bullets. -<listitem></listitem>, member of the above. -<screen></screen>, screen output, implies <literallayout>. -<ulink url="example.com"></ulink>, like HTML <a> tag. -<quote></quote>, for, doh, quoting text. + 4.7.6. Declare each variable and struct on its + own line. -Look at any of the existing docs for examples of all these and more. + 4.7.7. Use malloc/zalloc sparingly -You might also find "Writing Documentation Using DocBook - A Crash Course" -useful. - -------------------------------------------------------------------------------- - -3.2. Privoxy Documentation Style - -It will be easier if everyone follows a similar writing style. This just makes -it easier to read what someone else has written if it is all done in a similar -fashion. - -Here it is: + 4.7.8. The Programmer Who Uses 'malloc' is + Responsible for Ensuring 'free' - * All tags should be lower case. + 4.7.9. Add loaders to the `file_list' structure + and in order - * Tags delimiting a block of text (even small blocks) should be on their own - line. Like: + 4.7.10. "Uncertain" new code and/or changes to + existing code, use FIXME or XXX - <para> - Some text goes here. - </para> - + 4.8. Addendum: Template for files and function comment + blocks: - Tags marking individual words, or few words, should be in-line: + 5. Testing Guidelines - Just to <emphasis>emphasize</emphasis>, some text goes here. - + 5.1. Testplan for releases - * Tags should be nested and step indented for block text like: (except - in-line tags) + 5.2. Test reports - <para> - <itemizedlist> - <para> - <listitem> - Some text goes here in our list example. - </listitem> - </para> - </itemizedlist> - </para> - + 6. Releasing a New Version - This makes it easier to find the text amongst the tags ;-) + 6.1. Version numbers - * Use white space to separate logical divisions within a document, like - between sections. Running everything together consistently makes it harder - to read and work on. + 6.2. Before the Release: Freeze - * Do not hesitate to make comments. Comments can either use the <comment> - element, or the <!-- --> style comment familiar from HTML. (Note in Docbook - v4.x <comment> is replaced by <remark>.) + 6.3. Building and Releasing the Packages - * We have an international audience. Refrain from slang, or English - idiosyncrasies (too many to list :). Humor also does not translate well - sometimes. + 6.3.1. Note on Privoxy Packaging - * Try to keep overall line lengths in source files to 80 characters or less - for obvious reasons. This is not always possible, with lengthy URLs for - instance. + 6.3.2. Source Tarball - * Our documents are available in differing formats. Right now, they are just - plain text, HTML, and PDF, but others are always a future possibility. Be - careful with URLs (<ulink>), and avoid this mistake: + 6.3.3. SuSE, Conectiva or Red Hat RPM - My favorite site is <ulink url="http://example.com">here</ulink>. + 6.3.4. OS/2 - This will render as "My favorite site is here", which is not real helpful - in a text doc. Better like this: + 6.3.5. Solaris - My favorite site is <ulink url="http://example.com">example.com</ulink>. + 6.3.6. Windows - * All documents should be spell checked occasionally. aspell can check SGML - with the -H option. (ispell I think too.) + 6.3.7. Debian -------------------------------------------------------------------------------- + 6.3.8. Mac OSX -3.3. Privoxy Custom Entities + 6.3.9. FreeBSD -Privoxy documentation is using a number of customized "entities" to facilitate -documentation maintenance. + 6.3.10. HP-UX 11 -We are using a set of "boilerplate" files with generic text, that is used by -multiple docs. This way we can write something once, and use it repeatedly -without having to re-write the same content over and over again. If editing -such a file, keep in mind that it should be generic. That is the purpose; so it -can be used in varying contexts without additional modifications. + 6.3.11. Amiga OS -We are also using what Docbook calls "internal entities". These are like -variables in programming. Well, sort of. For instance, we have the p-version -entity that contains the current Privoxy version string. You are strongly -encouraged to use these where possible. Some of these obviously require -re-setting with each release (done by the Makefile). A sampling of custom -entities are listed below. See any of the main docs for examples. + 6.3.12. AIX - * Re- "boilerplate" text entities are defined like: + 6.4. Uploading and Releasing Your Package - <!entity supported SYSTEM "supported.sgml"> + 6.5. After the Release - In this example, the contents of the file, supported.sgml is available for - inclusion anywhere in the doc. To make this happen, just reference the now - defined entity: &supported; (starts with an ampersand and ends with a - semi-colon), and the contents will be dumped into the finished doc at that - point. + 7. Update the Webserver - * Commonly used "internal entities": + 8. Contacting the developers, Bug Reporting and Feature Requests - p-version: the Privoxy version string, e.g. "3.0.8". - p-status: the project status, either "alpha", "beta", or "stable". - p-not-stable: use to conditionally include text in "not stable" releases - (e.g. "beta"). - p-stable: just the opposite. - p-text: this doc is only generated as text. + 8.1. Get Support -There are others in various places that are defined for a specific purpose. -Read the source! + 8.2. Reporting Problems -------------------------------------------------------------------------------- + 8.2.1. Reporting Ads or Other Configuration + Problems -4. Coding Guidelines + 8.2.2. Reporting Bugs -4.1. Introduction + 8.3. Request New Features -This set of standards is designed to make our lives easier. It is developed -with the simple goal of helping us keep the "new and improved Privoxy" -consistent and reliable. Thus making maintenance easier and increasing chances -of success of the project. + 8.4. Other -And that of course comes back to us as individuals. If we can increase our -development and product efficiencies then we can solve more of the request for -changes/improvements and in general feel good about ourselves. ;-> + 9. Privoxy Copyright, License and History -------------------------------------------------------------------------------- + 9.1. License -4.2. Using Comments + 9.2. History -4.2.1. Comment, Comment, Comment + 10. See also -Explanation: +1. Introduction -Comment as much as possible without commenting the obvious. For example do not -comment "variable_a is equal to variable_b". Instead explain why variable_a -should be equal to the variable_b. Just because a person can read code does not -mean they will understand why or what is being done. A reader may spend a lot -more time figuring out what is going on when a simple comment or explanation -would have prevented the extra research. Please help your brother IJB'ers out! + Privoxy, as an heir to Junkbuster, is a Free Software project and the code + is licensed under the GPL. As such, Privoxy development is potentially + open to anyone who has the time, knowledge, and desire to contribute in + any capacity. Our goals are simply to continue the mission, to improve + Privoxy, and to make it available to as wide an audience as possible. -The comments will also help justify the intent of the code. If the comment -describes something different than what the code is doing then maybe a -programming error is occurring. + One does not have to be a programmer to contribute. Packaging, testing, + documenting and porting, are all important jobs as well. -Example: + -------------------------------------------------------------------------- -/* if page size greater than 1k ... */ -if ( page_length() > 1024 ) -{ - ... "block" the page up ... -} + 1.1. Quickstart to Privoxy Development -/* if page size is small, send it in blocks */ -if ( page_length() > 1024 ) -{ - ... "block" the page up ... -} + The first step is to join the developer's mailing list. You can submit + your ideas, or even better patches. Patches are best submitted to the + Sourceforge tracker set up for this purpose, but can be sent to the list + for review too. -This demonstrates 2 cases of "what not to do". The first is a -"syntax comment". The second is a comment that does not fit what -is actually being done. + You will also need to have a cvs package installed, which will entail + having ssh installed as well (which seems to be a requirement of + SourceForge), in order to access the cvs repository. Having the GNU build + tools is also going to be important (particularly, autoconf and gmake). + For the time being (read, this section is under construction), you can + also refer to the extensive comments in the source code. In fact, reading + the code is recommended in any case. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -4.2.2. Use blocks for comments +2. The CVS Repository -Explanation: + If you become part of the active development team, you will eventually + need write access to our holy grail, the CVS repository. One of the team + members will need to set this up for you. Please read this chapter + completely before accessing via CVS. -Comments can help or they can clutter. They help when they are differentiated -from the code they describe. One line comments do not offer effective -separation between the comment and the code. Block identifiers do, by -surrounding the code with a clear, definable pattern. + -------------------------------------------------------------------------- -Example: + 2.1. Access to CVS -/********************************************************************* - * This will stand out clearly in your code! - *********************************************************************/ -if ( this_variable == that_variable ) -{ - do_something_very_important(); -} + The project's CVS repository is hosted on SourceForge. Please refer to the + chapters 6 and 7 in SF's site documentation for the technical access + details for your operating system. For historical reasons, the CVS server + is called ijbswa.cvs.sourceforge.net, the repository is called ijbswa, and + the source tree module is called current. + -------------------------------------------------------------------------- -/* unfortunately, this may not */ -if ( this_variable == that_variable ) -{ - do_something_very_important(); -} + 2.2. Branches + Within the CVS repository, there are modules and branches. As mentioned, + the sources are in the current "module". Other modules are present for + platform specific issues. There is a webview of the CVS hierarchy at + http://ijbswa.cvs.sourceforge.net/ijbswa/, which might help with + visualizing how these pieces fit together. -if ( this_variable == that_variable ) /* this may not either */ -{ - do_something_very_important(); -} + Branches are used to fork a sub-development path from the main trunk. + Within the current module where the sources are, there is always at least + one "branch" from the main trunk devoted to a stable release series. The + main trunk is where active development takes place for the next stable + series (e.g. 3.2.x). So just prior to each stable series (e.g. 3.0.x), a + branch is created just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> + 3.0.2, etc). Once the initial stable release of any stable branch has + taken place, this branch is only used for bugfixes, which have had prior + testing before being committed to CVS. (See Version Numbers below for + details on versioning.) + At one time there were two distinct branches: stable and unstable. The + more drastic changes were to be in the unstable branch. These branches + have now been merged to minimize time and effort of maintaining two + branches. -Exception: + -------------------------------------------------------------------------- -If you are trying to add a small logic comment and do not wish to "disrupt" the -flow of the code, feel free to use a 1 line comment which is NOT on the same -line as the code. + 2.3. CVS Commit Guidelines -------------------------------------------------------------------------------- + The source tree is the heart of every software project. Every effort must + be made to ensure that it is readable, compilable and consistent at all + times. There are differing guidelines for the stable branch and the main + development trunk, and we ask anyone with CVS access to strictly adhere to + the following guidelines: -4.2.3. Keep Comments on their own line + Basic Guidelines, for all branches: -Explanation: + * Please don't commit even a small change without testing it thoroughly + first. When we're close to a public release, ask a fellow developer to + review your changes. -It goes back to the question of readability. If the comment is on the same line -as the code it will be harder to read than the comment that is on its own line. + * Your commit message should give a concise overview of what you changed + (no big details) and why you changed it Just check previous messages + for good examples. -There are three exceptions to this rule, which should be violated freely and -often: during the definition of variables, at the end of closing braces, when -used to comment parameters. + * Don't use the same message on multiple files, unless it equally + applies to all those files. -Example: + * If your changes span multiple files, and the code won't recompile + unless all changes are committed (e.g. when changing the signature of + a function), then commit all files one after another, without long + delays in between. If necessary, prepare the commit messages in + advance. -/********************************************************************* - * This will stand out clearly in your code, - * But the second example won't. - *********************************************************************/ -if ( this_variable == this_variable ) -{ - do_something_very_important(); -} + * Before changing things on CVS, make sure that your changes are in line + with the team's general consensus on what should be done. -if ( this_variable == this_variable ) /*can you see me?*/ -{ - do_something_very_important(); /*not easily*/ -} + * Note that near a major public release, we get more cautious. There is + always the possibility to submit a patch to the patch tracker instead. + -------------------------------------------------------------------------- -/********************************************************************* - * But, the encouraged exceptions: - *********************************************************************/ -int urls_read = 0; /* # of urls read + rejected */ -int urls_rejected = 0; /* # of urls rejected */ +3. Documentation Guidelines + + All formal documents are maintained in Docbook SGML and located in the + doc/source/* directory. You will need Docbook, the Docbook DTD's and the + Docbook modular stylesheets (or comparable alternatives), and either jade + or openjade (recommended) installed in order to build docs from source. + Currently there is user-manual, FAQ, and, of course this, the + developer-manual in this format. The README, AUTHORS, INSTALL, privoxy.1 + (man page), and config files are also now maintained as Docbook SGML. + These files, when built, in the top-level source directory are generated + files! Also, the Privoxy index.html (and a variation on this file, + privoxy-index.html, meant for inclusion with doc packages), are maintained + as SGML as well. DO NOT edit these directly. Edit the SGML source, or + contact someone involved in the documentation. + + config requires some special handling. The reason it is maintained this + way is so that the extensive comments in the file mirror those in + user-manual. But the conversion process requires going from SGML to HTML + to text to special formatting required for the embedded comments. Some of + this does not survive so well. Especially some of the examples that are + longer than 80 characters. The build process for this file outputs to + config.new, which should be reviewed for errors and mis-formatting. Once + satisfied that it is correct, then it should be hand copied to config. + + Other, less formal documents (e.g. LICENSE) are maintained as plain text + files in the top-level source directory. + + Packagers are encouraged to include this documentation. For those without + the ability to build the docs locally, text versions of each are kept in + CVS. HTML versions are also being kept in CVS under doc/webserver/*. And + PDF version are kept in doc/pdf/*. -if ( 1 == X ) -{ - do_something_very_important(); -} + Formal documents are built with the Makefile targets of make dok, or + alternately make redhat-dok. If you have problems, try both. The build + process uses the document SGML sources in doc/source/*/* to update all + text files in doc/text/ and to update all HTML documents in + doc/webserver/. + + Documentation writers should please make sure documents build successfully + before committing to CVS, if possible. + + How do you update the webserver (i.e. the pages on privoxy.org)? + + 1. First, build the docs by running make dok (or alternately make + redhat-dok). For PDF docs, do make dok-pdf. + + 2. Run make webserver which copies all files from doc/webserver to the + sourceforge webserver via scp. + + Finished docs should be occasionally submitted to CVS + (doc/webserver/*/*.html) so that those without the ability to build them + locally, have access to them if needed. This is especially important just + prior to a new release! Please do this after the $VERSION and other + release specific data in configure.in has been updated (this is done just + prior to a new release). + + -------------------------------------------------------------------------- + + 3.1. Quickstart to Docbook and SGML + + If you are not familiar with SGML, it is a markup language similar to + HTML. Actually, not a mark up language per se, but a language used to + define markup languages. In fact, HTML is an SGML application. Both will + use "tags" to format text and other content. SGML tags can be much more + varied, and flexible, but do much of the same kinds of things. The tags, + or "elements", are definable in SGML. There is no set "standards". Since + we are using Docbook, our tags are those that are defined by Docbook. Much + of how the finish document is rendered is determined by the "stylesheets". + The stylesheets determine how each tag gets translated to HTML, or other + formats. + Tags in Docbook SGML need to be always "closed". If not, you will likely + generate errors. Example: <title>My Title. They are also + case-insensitive, but we strongly suggest using all lower case. This keeps + compatibility with [Docbook] XML. -short do_something_very_important( - short firstparam, /* represents something */ - short nextparam /* represents something else */ ) -{ - ...code here... + Our documents use "sections" for the most part. Sections will be processed + into HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use + these to also generate the Table of Contents for each doc. Our TOC's are + set to a depth of three. Meaning sect1, sect2, and sect3 will have TOC + entries, but sect4 will not. Each section requires a element, and + at least one <para>. There is a limit of five section levels in Docbook, + but generally three should be sufficient for our purposes. -} /* -END- do_something_very_important */ + Some common elements that you likely will use: + <para></para>, paragraph delimiter. Most text needs to be within paragraph + elements (there are some exceptions). + <emphasis></emphasis>, the stylesheets make this italics. + <filename></filename>, files and directories. + <command></command>, command examples. + <literallayout></literallayout>, like <pre>, more or less. + <itemizedlist></itemizedlist>, list with bullets. + <listitem></listitem>, member of the above. + <screen></screen>, screen output, implies <literallayout>. + <ulink url="example.com"></ulink>, like HTML <a> tag. + <quote></quote>, for, doh, quoting text. -------------------------------------------------------------------------------- + Look at any of the existing docs for examples of all these and more. -4.2.4. Comment each logical step + You might also find "Writing Documentation Using DocBook - A Crash Course" + useful. + + -------------------------------------------------------------------------- -Explanation: + 3.2. Privoxy Documentation Style -Logical steps should be commented to help others follow the intent of the -written code and comments will make the code more readable. + It will be easier if everyone follows a similar writing style. This just + makes it easier to read what someone else has written if it is all done in + a similar fashion. -If you have 25 lines of code without a comment, you should probably go back -into it to see where you forgot to put one. + Here it is: -Most "for", "while", "do", etc... loops _probably_ need a comment. After all, -these are usually major logic containers. + * All tags should be lower case. -------------------------------------------------------------------------------- + * Tags delimiting a block of text (even small blocks) should be on their + own line. Like: -4.2.5. Comment All Functions Thoroughly + <para> + Some text goes here. + </para> -Explanation: -A reader of the code should be able to look at the comments just prior to the -beginning of a function and discern the reason for its existence and the -consequences of using it. The reader should not have to read through the code -to determine if a given function is safe for a desired use. The proper -information thoroughly presented at the introduction of a function not only -saves time for subsequent maintenance or debugging, it more importantly aids in -code reuse by allowing a user to determine the safety and applicability of any -function for the problem at hand. As a result of such benefits, all functions -should contain the information presented in the addendum section of this -document. + Tags marking individual words, or few words, should be in-line: -------------------------------------------------------------------------------- + Just to <emphasis>emphasize</emphasis>, some text goes here. -4.2.6. Comment at the end of braces if the content is more than one screen -length -Explanation: + * Tags should be nested and step indented for block text like: (except + in-line tags) -Each closing brace should be followed on the same line by a comment that -describes the origination of the brace if the original brace is off of the -screen, or otherwise far away from the closing brace. This will simplify the -debugging, maintenance, and readability of the code. + <para> + <itemizedlist> + <para> + <listitem> + Some text goes here in our list example. + </listitem> + </para> + </itemizedlist> + </para> -As a suggestion , use the following flags to make the comment and its brace -more readable: -use following a closing brace: } /* -END- if() or while () or etc... */ + This makes it easier to find the text amongst the tags ;-) + * Use white space to separate logical divisions within a document, like + between sections. Running everything together consistently makes it + harder to read and work on. -Example: + * Do not hesitate to make comments. Comments can either use the + <comment> element, or the <!-- --> style comment familiar from HTML. + (Note in Docbook v4.x <comment> is replaced by <remark>.) -if ( 1 == X ) -{ - do_something_very_important(); - ...some long list of commands... -} /* -END- if x is 1 */ + * We have an international audience. Refrain from slang, or English + idiosyncrasies (too many to list :). Humor also does not translate + well sometimes. -or: + * Try to keep overall line lengths in source files to 80 characters or + less for obvious reasons. This is not always possible, with lengthy + URLs for instance. -if ( 1 == X ) -{ - do_something_very_important(); - ...some long list of commands... -} /* -END- if ( 1 == X ) */ + * Our documents are available in differing formats. Right now, they are + just plain text, HTML, and PDF, but others are always a future + possibility. Be careful with URLs (<ulink>), and avoid this mistake: + My favorite site is <ulink url="http://example.com">here</ulink>. -------------------------------------------------------------------------------- + This will render as "My favorite site is here", which is not real + helpful in a text doc. Better like this: -4.3. Naming Conventions + My favorite site is <ulink + url="http://example.com">example.com</ulink>. -4.3.1. Variable Names + * All documents should be spell checked occasionally. aspell can check + SGML with the -H option. (ispell I think too.) -Explanation: + -------------------------------------------------------------------------- -Use all lowercase, and separate words via an underscore ('_'). Do not start an -identifier with an underscore. (ANSI C reserves these for use by the compiler -and system headers.) Do not use identifiers which are reserved in ANSI C++. -(E.g. template, class, true, false, ...). This is in case we ever decide to -port Privoxy to C++. + 3.3. Privoxy Custom Entities -Example: + Privoxy documentation is using a number of customized "entities" to + facilitate documentation maintenance. -int ms_iis5_hack = 0; + We are using a set of "boilerplate" files with generic text, that is used + by multiple docs. This way we can write something once, and use it + repeatedly without having to re-write the same content over and over + again. If editing such a file, keep in mind that it should be generic. + That is the purpose; so it can be used in varying contexts without + additional modifications. + We are also using what Docbook calls "internal entities". These are like + variables in programming. Well, sort of. For instance, we have the + p-version entity that contains the current Privoxy version string. You are + strongly encouraged to use these where possible. Some of these obviously + require re-setting with each release (done by the Makefile). A sampling of + custom entities are listed below. See any of the main docs for examples. -Instead of: + * Re- "boilerplate" text entities are defined like: -int msiis5hack = 0; int msIis5Hack = 0; + <!entity supported SYSTEM "supported.sgml"> + In this example, the contents of the file, supported.sgml is available + for inclusion anywhere in the doc. To make this happen, just reference + the now defined entity: &supported; (starts with an ampersand and ends + with a semi-colon), and the contents will be dumped into the finished + doc at that point. -------------------------------------------------------------------------------- + * Commonly used "internal entities": -4.3.2. Function Names + p-version: the Privoxy version string, e.g. "3.0.8". + p-status: the project status, either "alpha", "beta", or "stable". + p-not-stable: use to conditionally include text in "not stable" + releases (e.g. "beta"). + p-stable: just the opposite. + p-text: this doc is only generated as text. -Explanation: + There are others in various places that are defined for a specific + purpose. Read the source! -Use all lowercase, and separate words via an underscore ('_'). Do not start an -identifier with an underscore. (ANSI C reserves these for use by the compiler -and system headers.) Do not use identifiers which are reserved in ANSI C++. -(E.g. template, class, true, false, ...). This is in case we ever decide to -port Privoxy to C++. + -------------------------------------------------------------------------- -Example: +4. Coding Guidelines -int load_some_file( struct client_state *csp ) + 4.1. Introduction + This set of standards is designed to make our lives easier. It is + developed with the simple goal of helping us keep the "new and improved + Privoxy" consistent and reliable. Thus making maintenance easier and + increasing chances of success of the project. -Instead of: + And that of course comes back to us as individuals. If we can increase our + development and product efficiencies then we can solve more of the request + for changes/improvements and in general feel good about ourselves. ;-> -int loadsomefile( struct client_state *csp ) -int loadSomeFile( struct client_state *csp ) + -------------------------------------------------------------------------- + 4.2. Using Comments -------------------------------------------------------------------------------- + 4.2.1. Comment, Comment, Comment -4.3.3. Header file prototypes + Explanation: -Explanation: + Comment as much as possible without commenting the obvious. For example do + not comment "variable_a is equal to variable_b". Instead explain why + variable_a should be equal to the variable_b. Just because a person can + read code does not mean they will understand why or what is being done. A + reader may spend a lot more time figuring out what is going on when a + simple comment or explanation would have prevented the extra research. + Please help your brother IJB'ers out! -Use a descriptive parameter name in the function prototype in header files. Use -the same parameter name in the header file that you use in the c file. + The comments will also help justify the intent of the code. If the comment + describes something different than what the code is doing then maybe a + programming error is occurring. -Example: + Example: -(.h) extern int load_aclfile( struct client_state *csp ); -(.c) int load_aclfile( struct client_state *csp ) + /* if page size greater than 1k ... */ + if ( page_length() > 1024 ) + { + ... "block" the page up ... + } + /* if page size is small, send it in blocks */ + if ( page_length() > 1024 ) + { + ... "block" the page up ... + } -Instead of: + This demonstrates 2 cases of "what not to do". The first is a + "syntax comment". The second is a comment that does not fit what + is actually being done. -(.h) extern int load_aclfile( struct client_state * ); or -(.h) extern int load_aclfile(); -(.c) int load_aclfile( struct client_state *csp ) + -------------------------------------------------------------------------- + 4.2.2. Use blocks for comments -------------------------------------------------------------------------------- + Explanation: -4.3.4. Enumerations, and #defines + Comments can help or they can clutter. They help when they are + differentiated from the code they describe. One line comments do not offer + effective separation between the comment and the code. Block identifiers + do, by surrounding the code with a clear, definable pattern. -Explanation: + Example: -Use all capital letters, with underscores between words. Do not start an -identifier with an underscore. (ANSI C reserves these for use by the compiler -and system headers.) + /********************************************************************* + * This will stand out clearly in your code! + *********************************************************************/ + if ( this_variable == that_variable ) + { + do_something_very_important(); + } + + + /* unfortunately, this may not */ + if ( this_variable == that_variable ) + { + do_something_very_important(); + } + + + if ( this_variable == that_variable ) /* this may not either */ + { + do_something_very_important(); + } -Example: + Exception: -(enumeration) : enum Boolean { FALSE, TRUE }; -(#define) : #define DEFAULT_SIZE 100; + If you are trying to add a small logic comment and do not wish to + "disrupt" the flow of the code, feel free to use a 1 line comment which is + NOT on the same line as the code. + -------------------------------------------------------------------------- -Note: We have a standard naming scheme for #defines that toggle a feature in -the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word) -description. + 4.2.3. Keep Comments on their own line -Example: + Explanation: -#define FEATURE_FORCE 1 + It goes back to the question of readability. If the comment is on the same + line as the code it will be harder to read than the comment that is on its + own line. -#ifdef FEATURE_FORCE -#define FORCE_PREFIX blah -#endif /* def FEATURE_FORCE */ + There are three exceptions to this rule, which should be violated freely + and often: during the definition of variables, at the end of closing + braces, when used to comment parameters. + Example: -------------------------------------------------------------------------------- + /********************************************************************* + * This will stand out clearly in your code, + * But the second example won't. + *********************************************************************/ + if ( this_variable == this_variable ) + { + do_something_very_important(); + } -4.3.5. Constants + if ( this_variable == this_variable ) /*can you see me?*/ + { + do_something_very_important(); /*not easily*/ + } -Explanation: -Spell common words out entirely (do not remove vowels). + /********************************************************************* + * But, the encouraged exceptions: + *********************************************************************/ + int urls_read = 0; /* # of urls read + rejected */ + int urls_rejected = 0; /* # of urls rejected */ -Use only widely-known domain acronyms and abbreviations. Capitalize all letters -of an acronym. + if ( 1 == X ) + { + do_something_very_important(); + } -Use underscore (_) to separate adjacent acronyms and abbreviations. Never -terminate a name with an underscore. -Example: + short do_something_very_important( + short firstparam, /* represents something */ + short nextparam /* represents something else */ ) + { + ...code here... -#define USE_IMAGE_LIST 1 + } /* -END- do_something_very_important */ + -------------------------------------------------------------------------- -Instead of: + 4.2.4. Comment each logical step -#define USE_IMG_LST 1 or -#define _USE_IMAGE_LIST 1 or -#define USE_IMAGE_LIST_ 1 or -#define use_image_list 1 or -#define UseImageList 1 + Explanation: + Logical steps should be commented to help others follow the intent of the + written code and comments will make the code more readable. -------------------------------------------------------------------------------- + If you have 25 lines of code without a comment, you should probably go + back into it to see where you forgot to put one. -4.4. Using Space + Most "for", "while", "do", etc... loops _probably_ need a comment. After + all, these are usually major logic containers. -4.4.1. Put braces on a line by themselves. + -------------------------------------------------------------------------- -Explanation: + 4.2.5. Comment All Functions Thoroughly -The brace needs to be on a line all by itself, not at the end of the statement. -Curly braces should line up with the construct that they're associated with. -This practice makes it easier to identify the opening and closing braces for a -block. + Explanation: -Example: + A reader of the code should be able to look at the comments just prior to + the beginning of a function and discern the reason for its existence and + the consequences of using it. The reader should not have to read through + the code to determine if a given function is safe for a desired use. The + proper information thoroughly presented at the introduction of a function + not only saves time for subsequent maintenance or debugging, it more + importantly aids in code reuse by allowing a user to determine the safety + and applicability of any function for the problem at hand. As a result of + such benefits, all functions should contain the information presented in + the addendum section of this document. -if ( this == that ) -{ - ... -} + -------------------------------------------------------------------------- + 4.2.6. Comment at the end of braces if the content is more than one screen + length -Instead of: + Explanation: -if ( this == that ) { ... } + Each closing brace should be followed on the same line by a comment that + describes the origination of the brace if the original brace is off of the + screen, or otherwise far away from the closing brace. This will simplify + the debugging, maintenance, and readability of the code. -or + As a suggestion , use the following flags to make the comment and its + brace more readable: -if ( this == that ) { ... } + use following a closing brace: } /* -END- if() or while () or etc... */ -Note: In the special case that the if-statement is inside a loop, and it is -trivial, i.e. it tests for a condition that is obvious from the purpose of the -block, one-liners as above may optically preserve the loop structure and make -it easier to read. + Example: -Status: developer-discretion. + if ( 1 == X ) + { + do_something_very_important(); + ...some long list of commands... + } /* -END- if x is 1 */ -Example exception: + or: -while ( more lines are read ) -{ - /* Please document what is/is not a comment line here */ - if ( it's a comment ) continue; + if ( 1 == X ) + { + do_something_very_important(); + ...some long list of commands... + } /* -END- if ( 1 == X ) */ - do_something( line ); -} + -------------------------------------------------------------------------- + 4.3. Naming Conventions -------------------------------------------------------------------------------- + 4.3.1. Variable Names -4.4.2. ALL control statements should have a block + Explanation: -Explanation: + Use all lowercase, and separate words via an underscore ('_'). Do not + start an identifier with an underscore. (ANSI C reserves these for use by + the compiler and system headers.) Do not use identifiers which are + reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in + case we ever decide to port Privoxy to C++. -Using braces to make a block will make your code more readable and less prone -to error. All control statements should have a block defined. + Example: -Example: + int ms_iis5_hack = 0; -if ( this == that ) -{ - do_something(); - do_something_else(); -} + Instead of: + int msiis5hack = 0; int msIis5Hack = 0; -Instead of: + -------------------------------------------------------------------------- -if ( this == that ) do_something(); do_something_else(); + 4.3.2. Function Names -or + Explanation: -if ( this == that ) do_something(); + Use all lowercase, and separate words via an underscore ('_'). Do not + start an identifier with an underscore. (ANSI C reserves these for use by + the compiler and system headers.) Do not use identifiers which are + reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in + case we ever decide to port Privoxy to C++. -Note: The first example in "Instead of" will execute in a manner other than -that which the developer desired (per indentation). Using code braces would -have prevented this "feature". The "explanation" and "exception" from the point -above also applies. + Example: -------------------------------------------------------------------------------- + int load_some_file( struct client_state *csp ) -4.4.3. Do not belabor/blow-up boolean expressions + Instead of: -Example: + int loadsomefile( struct client_state *csp ) + int loadSomeFile( struct client_state *csp ) -structure->flag = ( condition ); + -------------------------------------------------------------------------- + 4.3.3. Header file prototypes -Instead of: + Explanation: -if ( condition ) { structure->flag = 1; } else { structure->flag = 0; } + Use a descriptive parameter name in the function prototype in header + files. Use the same parameter name in the header file that you use in the + c file. -Note: The former is readable and concise. The later is wordy and inefficient. -Please assume that any developer new to the project has at least a "good" -knowledge of C/C++. (Hope I do not offend by that last comment ... 8-) + Example: -------------------------------------------------------------------------------- + (.h) extern int load_aclfile( struct client_state *csp ); + (.c) int load_aclfile( struct client_state *csp ) -4.4.4. Use white space freely because it is free + Instead of: -Explanation: + (.h) extern int load_aclfile( struct client_state * ); or + (.h) extern int load_aclfile(); + (.c) int load_aclfile( struct client_state *csp ) -Make it readable. The notable exception to using white space freely is listed -in the next guideline. + -------------------------------------------------------------------------- -Example: + 4.3.4. Enumerations, and #defines -int first_value = 0; -int some_value = 0; -int another_value = 0; -int this_variable = 0; + Explanation: -if ( this_variable == this_variable ) + Use all capital letters, with underscores between words. Do not start an + identifier with an underscore. (ANSI C reserves these for use by the + compiler and system headers.) -first_value = old_value + ( ( some_value - another_value ) - whatever ) + Example: + (enumeration) : enum Boolean { FALSE, TRUE }; + (#define) : #define DEFAULT_SIZE 100; -------------------------------------------------------------------------------- + Note: We have a standard naming scheme for #defines that toggle a feature + in the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 + word) description. -4.4.5. Don't use white space around structure operators + Example: -Explanation: + #define FEATURE_FORCE 1 -- structure pointer operator ( "->" ) - member operator ( "." ) - functions and -parentheses + #ifdef FEATURE_FORCE + #define FORCE_PREFIX blah + #endif /* def FEATURE_FORCE */ -It is a general coding practice to put pointers, references, and function -parentheses next to names. With spaces, the connection between the object and -variable/function name is not as clear. + -------------------------------------------------------------------------- -Example: + 4.3.5. Constants -a_struct->a_member; -a_struct.a_member; -function_name(); + Explanation: + Spell common words out entirely (do not remove vowels). -Instead of: a_struct -> a_member; a_struct . a_member; function_name (); + Use only widely-known domain acronyms and abbreviations. Capitalize all + letters of an acronym. -------------------------------------------------------------------------------- + Use underscore (_) to separate adjacent acronyms and abbreviations. Never + terminate a name with an underscore. -4.4.6. Make the last brace of a function stand out + Example: -Example: + #define USE_IMAGE_LIST 1 -int function1( ... ) -{ - ...code... - return( ret_code ); + Instead of: -} /* -END- function1 */ + #define USE_IMG_LST 1 or + #define _USE_IMAGE_LIST 1 or + #define USE_IMAGE_LIST_ 1 or + #define use_image_list 1 or + #define UseImageList 1 + -------------------------------------------------------------------------- -int function2( ... ) -{ -} /* -END- function2 */ + 4.4. Using Space + 4.4.1. Put braces on a line by themselves. -Instead of: + Explanation: -int function1( ... ) { ...code... return( ret_code ); } int function2( ... ) { -} + The brace needs to be on a line all by itself, not at the end of the + statement. Curly braces should line up with the construct that they're + associated with. This practice makes it easier to identify the opening and + closing braces for a block. -Note: Use 1 blank line before the closing brace and 2 lines afterward. This -makes the end of function standout to the most casual viewer. Although function -comments help separate functions, this is still a good coding practice. In -fact, I follow these rules when using blocks in "for", "while", "do" loops, and -long if {} statements too. After all whitespace is free! + Example: -Status: developer-discretion on the number of blank lines. Enforced is the end -of function comments. + if ( this == that ) + { + ... + } -------------------------------------------------------------------------------- + Instead of: -4.4.7. Use 3 character indentions + if ( this == that ) { ... } -Explanation: + or -If some use 8 character TABs and some use 3 character TABs, the code can look -*very* ragged. So use 3 character indentions only. If you like to use TABs, -pass your code through a filter such as "expand -t3" before checking in your -code. + if ( this == that ) { ... } -Example: + Note: In the special case that the if-statement is inside a loop, and it + is trivial, i.e. it tests for a condition that is obvious from the purpose + of the block, one-liners as above may optically preserve the loop + structure and make it easier to read. -static const char * const url_code_map[256] = -{ - NULL, ... -}; + Status: developer-discretion. + Example exception: -int function1( ... ) -{ - if ( 1 ) + while ( more lines are read ) { - return( ALWAYS_TRUE ); + /* Please document what is/is not a comment line here */ + if ( it's a comment ) continue; + + do_something( line ); } - else + + -------------------------------------------------------------------------- + + 4.4.2. ALL control statements should have a block + + Explanation: + + Using braces to make a block will make your code more readable and less + prone to error. All control statements should have a block defined. + + Example: + + if ( this == that ) { - return( HOW_DID_YOU_GET_HERE ); + do_something(); + do_something_else(); } - return( NEVER_GETS_HERE ); + Instead of: -} + if ( this == that ) do_something(); do_something_else(); + or -------------------------------------------------------------------------------- + if ( this == that ) do_something(); -4.5. Initializing + Note: The first example in "Instead of" will execute in a manner other + than that which the developer desired (per indentation). Using code braces + would have prevented this "feature". The "explanation" and "exception" + from the point above also applies. -4.5.1. Initialize all variables + -------------------------------------------------------------------------- -Explanation: + 4.4.3. Do not belabor/blow-up boolean expressions -Do not assume that the variables declared will not be used until after they -have been assigned a value somewhere else in the code. Remove the chance of -accidentally using an unassigned variable. + Example: -Example: + structure->flag = ( condition ); -short a_short = 0; -float a_float = 0; -struct *ptr = NULL; + Instead of: + if ( condition ) { structure->flag = 1; } else { structure->flag = 0; } -Note: It is much easier to debug a SIGSEGV if the message says you are trying -to access memory address 00000000 and not 129FA012; or array_ptr[20] causes a -SIGSEV vs. array_ptr[0]. + Note: The former is readable and concise. The later is wordy and + inefficient. Please assume that any developer new to the project has at + least a "good" knowledge of C/C++. (Hope I do not offend by that last + comment ... 8-) -Status: developer-discretion if and only if the variable is assigned a value -"shortly after" declaration. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.4.4. Use white space freely because it is free -4.6. Functions + Explanation: -4.6.1. Name functions that return a boolean as a question. + Make it readable. The notable exception to using white space freely is + listed in the next guideline. -Explanation: + Example: -Value should be phrased as a question that would logically be answered as a -true or false statement + int first_value = 0; + int some_value = 0; + int another_value = 0; + int this_variable = 0; -Example: + if ( this_variable == this_variable ) -should_we_block_this(); -contains_an_image(); -is_web_page_blank(); + first_value = old_value + ( ( some_value - another_value ) - whatever ) + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.4.5. Don't use white space around structure operators -4.6.2. Always specify a return type for a function. + Explanation: -Explanation: + - structure pointer operator ( "->" ) - member operator ( "." ) - + functions and parentheses -The default return for a function is an int. To avoid ambiguity, create a -return for a function when the return has a purpose, and create a void return -type if the function does not need to return anything. + It is a general coding practice to put pointers, references, and function + parentheses next to names. With spaces, the connection between the object + and variable/function name is not as clear. -------------------------------------------------------------------------------- + Example: -4.6.3. Minimize function calls when iterating by using variables + a_struct->a_member; + a_struct.a_member; + function_name(); -Explanation: + Instead of: a_struct -> a_member; a_struct . a_member; function_name (); -It is easy to write the following code, and a clear argument can be made that -the code is easy to understand: + -------------------------------------------------------------------------- -Example: + 4.4.6. Make the last brace of a function stand out -for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) -{ - .... -} + Example: + int function1( ... ) + { + ...code... + return( ret_code ); -Note: Unfortunately, this makes a function call for each and every iteration. -This increases the overhead in the program, because the compiler has to look up -the function each time, call it, and return a value. Depending on what occurs -in the block_list_length() call, it might even be creating and destroying -structures with each iteration, even though in each case it is comparing "cnt" -to the same value, over and over. Remember too - even a call to -block_list_length() is a function call, with the same overhead. + } /* -END- function1 */ -Instead of using a function call during the iterations, assign the value to a -variable, and evaluate using the variable. -Example: + int function2( ... ) + { + } /* -END- function2 */ -size_t len = block_list_length(); + Instead of: -for ( size_t cnt = 0; cnt < len; cnt++ ) -{ - .... -} + int function1( ... ) { ...code... return( ret_code ); } int function2( ... + ) { } + Note: Use 1 blank line before the closing brace and 2 lines afterward. + This makes the end of function standout to the most casual viewer. + Although function comments help separate functions, this is still a good + coding practice. In fact, I follow these rules when using blocks in "for", + "while", "do" loops, and long if {} statements too. After all whitespace + is free! -Exceptions: if the value of block_list_length() *may* change or could -*potentially* change, then you must code the function call in the for/while -loop. + Status: developer-discretion on the number of blank lines. Enforced is the + end of function comments. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -4.6.4. Pass and Return by Const Reference + 4.4.7. Use 3 character indentions -Explanation: + Explanation: -This allows a developer to define a const pointer and call your function. If -your function does not have the const keyword, we may not be able to use your -function. Consider strcmp, if it were defined as: extern int strcmp( char *s1, -char *s2 ); + If some use 8 character TABs and some use 3 character TABs, the code can + look *very* ragged. So use 3 character indentions only. If you like to use + TABs, pass your code through a filter such as "expand -t3" before checking + in your code. -I could then not use it to compare argv's in main: int main( int argc, const -char *argv[] ) { strcmp( argv[0], "privoxy" ); } + Example: -Both these pointers are *const*! If the c runtime library maintainers do it, we -should too. + static const char * const url_code_map[256] = + { + NULL, ... + }; -------------------------------------------------------------------------------- -4.6.5. Pass and Return by Value + int function1( ... ) + { + if ( 1 ) + { + return( ALWAYS_TRUE ); + } + else + { + return( HOW_DID_YOU_GET_HERE ); + } -Explanation: + return( NEVER_GETS_HERE ); -Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes -or less). Aka, a function declaration like: int load_aclfile( struct -client_state csp ) + } -would not work. So, to be consistent, we should declare all prototypes with -"pass by value": int load_aclfile( struct client_state *csp ) + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.5. Initializing -4.6.6. Names of include files + 4.5.1. Initialize all variables -Explanation: + Explanation: -Your include statements should contain the file name without a path. The path -should be listed in the Makefile, using -I as processor directive to search the -indicated paths. An exception to this would be for some proprietary software -that utilizes a partial path to distinguish their header files from system or -other header files. + Do not assume that the variables declared will not be used until after + they have been assigned a value somewhere else in the code. Remove the + chance of accidentally using an unassigned variable. -Example: + Example: -#include <iostream.h> /* This is not a local include */ -#include "config.h" /* This IS a local include */ + short a_short = 0; + float a_float = 0; + struct *ptr = NULL; + Note: It is much easier to debug a SIGSEGV if the message says you are + trying to access memory address 00000000 and not 129FA012; or + array_ptr[20] causes a SIGSEV vs. array_ptr[0]. -Exception: + Status: developer-discretion if and only if the variable is assigned a + value "shortly after" declaration. -/* This is not a local include, but requires a path element. */ -#include <sys/fileName.h> + -------------------------------------------------------------------------- + 4.6. Functions -Note: Please! do not add "-I." to the Makefile without a _very_ good reason. -This duplicates the #include "file.h" behavior. + 4.6.1. Name functions that return a boolean as a question. -------------------------------------------------------------------------------- + Explanation: -4.6.7. Provide multiple inclusion protection + Value should be phrased as a question that would logically be answered as + a true or false statement -Explanation: + Example: -Prevents compiler and linker errors resulting from redefinition of items. + should_we_block_this(); + contains_an_image(); + is_web_page_blank(); -Wrap each header file with the following syntax to prevent multiple inclusions -of the file. Of course, replace PROJECT_H with your file name, with "." Changed -to "_", and make it uppercase. + -------------------------------------------------------------------------- -Example: + 4.6.2. Always specify a return type for a function. -#ifndef PROJECT_H_INCLUDED -#define PROJECT_H_INCLUDED - ... -#endif /* ndef PROJECT_H_INCLUDED */ + Explanation: + The default return for a function is an int. To avoid ambiguity, create a + return for a function when the return has a purpose, and create a void + return type if the function does not need to return anything. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -4.6.8. Use `extern "C"` when appropriate + 4.6.3. Minimize function calls when iterating by using variables -Explanation: + Explanation: -If our headers are included from C++, they must declare our functions as -`extern "C"`. This has no cost in C, but increases the potential re-usability -of our code. + It is easy to write the following code, and a clear argument can be made + that the code is easy to understand: -Example: + Example: -#ifdef __cplusplus -extern "C" -{ -#endif /* def __cplusplus */ + for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) + { + .... + } -... function definitions here ... + Note: Unfortunately, this makes a function call for each and every + iteration. This increases the overhead in the program, because the + compiler has to look up the function each time, call it, and return a + value. Depending on what occurs in the block_list_length() call, it might + even be creating and destroying structures with each iteration, even + though in each case it is comparing "cnt" to the same value, over and + over. Remember too - even a call to block_list_length() is a function + call, with the same overhead. -#ifdef __cplusplus -} -#endif /* def __cplusplus */ + Instead of using a function call during the iterations, assign the value + to a variable, and evaluate using the variable. + Example: -------------------------------------------------------------------------------- + size_t len = block_list_length(); -4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes + for ( size_t cnt = 0; cnt < len; cnt++ ) + { + .... + } -Explanation: + Exceptions: if the value of block_list_length() *may* change or could + *potentially* change, then you must code the function call in the + for/while loop. -Useful in headers that include pointers to other struct's. Modifications to -excess header files may cause needless compiles. + -------------------------------------------------------------------------- -Example: + 4.6.4. Pass and Return by Const Reference -/********************************************************************* - * We're avoiding an include statement here! - *********************************************************************/ -struct file_list; -extern file_list *xyz; + Explanation: + + This allows a developer to define a const pointer and call your function. + If your function does not have the const keyword, we may not be able to + use your function. Consider strcmp, if it were defined as: extern int + strcmp( char *s1, char *s2 ); + + I could then not use it to compare argv's in main: int main( int argc, + const char *argv[] ) { strcmp( argv[0], "privoxy" ); } + + Both these pointers are *const*! If the c runtime library maintainers do + it, we should too. + + -------------------------------------------------------------------------- + + 4.6.5. Pass and Return by Value + + Explanation: + Most structures cannot fit onto a normal stack entry (i.e. they are not 4 + bytes or less). Aka, a function declaration like: int load_aclfile( struct + client_state csp ) -Note: If you declare "file_list xyz;" (without the pointer), then including the -proper header file is necessary. If you only want to prototype a pointer, -however, the header file is unnecessary. + would not work. So, to be consistent, we should declare all prototypes + with "pass by value": int load_aclfile( struct client_state *csp ) -Status: Use with discretion. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.6.6. Names of include files -4.7. General Coding Practices + Explanation: -4.7.1. Turn on warnings + Your include statements should contain the file name without a path. The + path should be listed in the Makefile, using -I as processor directive to + search the indicated paths. An exception to this would be for some + proprietary software that utilizes a partial path to distinguish their + header files from system or other header files. -Explanation + Example: -Compiler warnings are meant to help you find bugs. You should turn on as many -as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as -possible. + #include <iostream.h> /* This is not a local include */ + #include "config.h" /* This IS a local include */ -------------------------------------------------------------------------------- + Exception: -4.7.2. Provide a default case for all switch statements + /* This is not a local include, but requires a path element. */ + #include <sys/fileName.h> -Explanation: + Note: Please! do not add "-I." to the Makefile without a _very_ good + reason. This duplicates the #include "file.h" behavior. -What you think is guaranteed is never really guaranteed. The value that you -don't think you need to check is the one that someday will be passed. So, to -protect yourself from the unknown, always have a default step in a switch -statement. + -------------------------------------------------------------------------- -Example: + 4.6.7. Provide multiple inclusion protection -switch( hash_string( cmd ) ) -{ - case hash_actions_file : - ... code ... - break; + Explanation: - case hash_confdir : - ... code ... - break; + Prevents compiler and linker errors resulting from redefinition of items. - default : - log_error( ... ); - ... anomaly code goes here ... - continue; / break; / exit( 1 ); / etc ... + Wrap each header file with the following syntax to prevent multiple + inclusions of the file. Of course, replace PROJECT_H with your file name, + with "." Changed to "_", and make it uppercase. -} /* end switch( hash_string( cmd ) ) */ + Example: + #ifndef PROJECT_H_INCLUDED + #define PROJECT_H_INCLUDED + ... + #endif /* ndef PROJECT_H_INCLUDED */ -Note: If you already have a default condition, you are obviously exempt from -this point. Of note, most of the WIN32 code calls `DefWindowProc' after the -switch statement. This API call *should* be included in a default statement. + -------------------------------------------------------------------------- -Another Note: This is not so much a readability issue as a robust programming -issue. The "anomaly code goes here" may be no more than a print to the STDERR -stream (as in load_config). Or it may really be an abort condition. + 4.6.8. Use `extern "C"` when appropriate -Status: Programmer discretion is advised. + Explanation: -------------------------------------------------------------------------------- + If our headers are included from C++, they must declare our functions as + `extern "C"`. This has no cost in C, but increases the potential + re-usability of our code. -4.7.3. Try to avoid falling through cases in a switch statement. + Example: -Explanation: + #ifdef __cplusplus + extern "C" + { + #endif /* def __cplusplus */ + + ... function definitions here ... + + #ifdef __cplusplus + } + #endif /* def __cplusplus */ + + -------------------------------------------------------------------------- + + 4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes + + Explanation: + + Useful in headers that include pointers to other struct's. Modifications + to excess header files may cause needless compiles. + + Example: + + /********************************************************************* + * We're avoiding an include statement here! + *********************************************************************/ + struct file_list; + extern file_list *xyz; + + Note: If you declare "file_list xyz;" (without the pointer), then + including the proper header file is necessary. If you only want to + prototype a pointer, however, the header file is unnecessary. + + Status: Use with discretion. + + -------------------------------------------------------------------------- + + 4.7. General Coding Practices + + 4.7.1. Turn on warnings + + Explanation + + Compiler warnings are meant to help you find bugs. You should turn on as + many as possible. With GCC, the switch is "-Wall". Try and fix as many + warnings as possible. + + -------------------------------------------------------------------------- + + 4.7.2. Provide a default case for all switch statements -In general, you will want to have a 'break' statement within each 'case' of a -switch statement. This allows for the code to be more readable and -understandable, and furthermore can prevent unwanted surprises if someone else -later gets creative and moves the code around. + Explanation: -The language allows you to plan the fall through from one case statement to -another simply by omitting the break statement within the case statement. This -feature does have benefits, but should only be used in rare cases. In general, -use a break statement for each case statement. + What you think is guaranteed is never really guaranteed. The value that + you don't think you need to check is the one that someday will be passed. + So, to protect yourself from the unknown, always have a default step in a + switch statement. -If you choose to allow fall through, you should comment both the fact of the -fall through and reason why you felt it was necessary. + Example: -------------------------------------------------------------------------------- + switch( hash_string( cmd ) ) + { + case hash_actions_file : + ... code ... + break; + + case hash_confdir : + ... code ... + break; + + default : + log_error( ... ); + ... anomaly code goes here ... + continue; / break; / exit( 1 ); / etc ... + + } /* end switch( hash_string( cmd ) ) */ + + Note: If you already have a default condition, you are obviously exempt + from this point. Of note, most of the WIN32 code calls `DefWindowProc' + after the switch statement. This API call *should* be included in a + default statement. + + Another Note: This is not so much a readability issue as a robust + programming issue. The "anomaly code goes here" may be no more than a + print to the STDERR stream (as in load_config). Or it may really be an + abort condition. + + Status: Programmer discretion is advised. + + -------------------------------------------------------------------------- + + 4.7.3. Try to avoid falling through cases in a switch statement. + + Explanation: -4.7.4. Use 'long' or 'short' Instead of 'int' + In general, you will want to have a 'break' statement within each 'case' + of a switch statement. This allows for the code to be more readable and + understandable, and furthermore can prevent unwanted surprises if someone + else later gets creative and moves the code around. -Explanation: + The language allows you to plan the fall through from one case statement + to another simply by omitting the break statement within the case + statement. This feature does have benefits, but should only be used in + rare cases. In general, use a break statement for each case statement. -On 32-bit platforms, int usually has the range of long. On 16-bit platforms, -int has the range of short. + If you choose to allow fall through, you should comment both the fact of + the fall through and reason why you felt it was necessary. -Status: open-to-debate. In the case of most FSF projects (including X/ -GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I -forget the exact typedefs now). Should we add these to IJB now that we have a -"configure" script? + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.7.4. Use 'long' or 'short' Instead of 'int' -4.7.5. Don't mix size_t and other types + Explanation: -Explanation: + On 32-bit platforms, int usually has the range of long. On 16-bit + platforms, int has the range of short. -The type of size_t varies across platforms. Do not make assumptions about -whether it is signed or unsigned, or about how long it is. Do not compare a -size_t against another variable of a different type (or even against a -constant) without casting one of the values. + Status: open-to-debate. In the case of most FSF projects (including + X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... + I forget the exact typedefs now). Should we add these to IJB now that we + have a "configure" script? -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -4.7.6. Declare each variable and struct on its own line. + 4.7.5. Don't mix size_t and other types -Explanation: + Explanation: -It can be tempting to declare a series of variables all on one line. Don't. + The type of size_t varies across platforms. Do not make assumptions about + whether it is signed or unsigned, or about how long it is. Do not compare + a size_t against another variable of a different type (or even against a + constant) without casting one of the values. -Example: + -------------------------------------------------------------------------- -long a = 0; -long b = 0; -long c = 0; + 4.7.6. Declare each variable and struct on its own line. + Explanation: -Instead of: + It can be tempting to declare a series of variables all on one line. + Don't. -long a, b, c; + Example: -Explanation: - there is more room for comments on the individual variables - -easier to add new variables without messing up the original ones - when -searching on a variable to find its type, there is less clutter to "visually" -eliminate + long a = 0; + long b = 0; + long c = 0; -Exceptions: when you want to declare a bunch of loop variables or other trivial -variables; feel free to declare them on one line. You should, although, provide -a good comment on their functions. + Instead of: -Status: developer-discretion. + long a, b, c; -------------------------------------------------------------------------------- + Explanation: - there is more room for comments on the individual variables + - easier to add new variables without messing up the original ones - when + searching on a variable to find its type, there is less clutter to + "visually" eliminate -4.7.7. Use malloc/zalloc sparingly + Exceptions: when you want to declare a bunch of loop variables or other + trivial variables; feel free to declare them on one line. You should, + although, provide a good comment on their functions. -Explanation: + Status: developer-discretion. -Create a local struct (on the stack) if the variable will live and die within -the context of one function call. + -------------------------------------------------------------------------- -Only "malloc" a struct (on the heap) if the variable's life will extend beyond -the context of one function call. + 4.7.7. Use malloc/zalloc sparingly -Example: + Explanation: -If a function creates a struct and stores a pointer to it in a -list, then it should definitely be allocated via `malloc'. + Create a local struct (on the stack) if the variable will live and die + within the context of one function call. + Only "malloc" a struct (on the heap) if the variable's life will extend + beyond the context of one function call. -------------------------------------------------------------------------------- + Example: -4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free' + If a function creates a struct and stores a pointer to it in a + list, then it should definitely be allocated via `malloc'. -Explanation: + -------------------------------------------------------------------------- -If you have to "malloc" an instance, you are responsible for insuring that the -instance is `free'd, even if the deallocation event falls within some other -programmer's code. You are also responsible for ensuring that deletion is -timely (i.e. not too soon, not too late). This is known as "low-coupling" and -is a "good thing (tm)". You may need to offer a free/unload/destructor type -function to accommodate this. + 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free' -Example: + Explanation: -int load_re_filterfile( struct client_state *csp ) { ... } -static void unload_re_filterfile( void *f ) { ... } + If you have to "malloc" an instance, you are responsible for insuring that + the instance is `free'd, even if the deallocation event falls within some + other programmer's code. You are also responsible for ensuring that + deletion is timely (i.e. not too soon, not too late). This is known as + "low-coupling" and is a "good thing (tm)". You may need to offer a + free/unload/destructor type function to accommodate this. + Example: -Exceptions: + int load_re_filterfile( struct client_state *csp ) { ... } + static void unload_re_filterfile( void *f ) { ... } -The developer cannot be expected to provide `free'ing functions for C run-time -library functions ... such as `strdup'. + Exceptions: -Status: developer-discretion. The "main" use of this standard is for allocating -and freeing data structures (complex or nested). + The developer cannot be expected to provide `free'ing functions for C + run-time library functions ... such as `strdup'. -------------------------------------------------------------------------------- + Status: developer-discretion. The "main" use of this standard is for + allocating and freeing data structures (complex or nested). -4.7.9. Add loaders to the `file_list' structure and in order + -------------------------------------------------------------------------- -Explanation: + 4.7.9. Add loaders to the `file_list' structure and in order -I have ordered all of the "blocker" file code to be in alpha order. It is -easier to add/read new blockers when you expect a certain order. + Explanation: -Note: It may appear that the alpha order is broken in places by POPUP tests -coming before PCRS tests. But since POPUPs can also be referred to as -KILLPOPUPs, it is clear that it should come first. + I have ordered all of the "blocker" file code to be in alpha order. It is + easier to add/read new blockers when you expect a certain order. -------------------------------------------------------------------------------- + Note: It may appear that the alpha order is broken in places by POPUP + tests coming before PCRS tests. But since POPUPs can also be referred to + as KILLPOPUPs, it is clear that it should come first. -4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME or XXX + -------------------------------------------------------------------------- -Explanation: + 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME or + XXX -If you have enough confidence in new code or confidence in your changes, but -are not *quite* sure of the repercussions, add this: + Explanation: -/* FIXME: this code has a logic error on platform XYZ, * attempting to fix */ # -ifdef PLATFORM ...changed code here... #endif + If you have enough confidence in new code or confidence in your changes, + but are not *quite* sure of the repercussions, add this: -or: + /* FIXME: this code has a logic error on platform XYZ, * attempting to fix + */ #ifdef PLATFORM ...changed code here... #endif -/* FIXME: I think the original author really meant this... */ ...changed code -here... + or: -or: + /* FIXME: I think the original author really meant this... */ ...changed + code here... -/* FIXME: new code that *may* break something else... */ ...new code here... + or: -Note: If you make it clear that this may or may not be a "good thing (tm)", it -will be easier to identify and include in the project (or conversely exclude -from the project). + /* FIXME: new code that *may* break something else... */ ...new code + here... -------------------------------------------------------------------------------- + Note: If you make it clear that this may or may not be a "good thing + (tm)", it will be easier to identify and include in the project (or + conversely exclude from the project). -4.8. Addendum: Template for files and function comment blocks: + -------------------------------------------------------------------------- -Example for file comments: + 4.8. Addendum: Template for files and function comment blocks: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $"; + Example for file comments: + +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.16 2008/01/19 17:52:38 hal9 Exp $"; /********************************************************************* * * File : $Source$ @@ -1489,21 +1546,21 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03: const char FILENAME_h_rcs[] = FILENAME_H_VERSION; + Note: This declares the rcs variables that should be added to the + "show-proxy-args" page. If this is a brand new creation by you, you are + free to change the "Copyright" section to represent the rights you wish to + maintain. -Note: This declares the rcs variables that should be added to the -"show-proxy-args" page. If this is a brand new creation by you, you are free to -change the "Copyright" section to represent the rights you wish to maintain. - -Note: The formfeed character that is present right after the comment flower box -is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of -the code (via `forward-page' and `backward-page'). Please include it if you -can. + Note: The formfeed character that is present right after the comment + flower box is handy for (X|GNU)Emacs users to skip the verbiage and get to + the heart of the code (via `forward-page' and `backward-page'). Please + include it if you can. -Example for file header comments: + Example for file header comments: #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.16 2008/01/19 17:52:38 hal9 Exp $" /********************************************************************* * * File : $Source$ @@ -1568,928 +1625,921 @@ extern const char FILENAME_h_rcs[]; end: */ + Example for function comments: + + /********************************************************************* + * + * Function : FUNCTION_NAME + * + * Description : (Fill me in with a good description!) + * + * parameters : + * 1 : param1 = pointer to an important thing + * 2 : x = pointer to something else + * + * Returns : 0 => Ok, everything else is an error. + * + *********************************************************************/ + int FUNCTION_NAME( void *param1, const char *x ) + { + ... + return( 0 ); -Example for function comments: - -/********************************************************************* - * - * Function : FUNCTION_NAME - * - * Description : (Fill me in with a good description!) - * - * parameters : - * 1 : param1 = pointer to an important thing - * 2 : x = pointer to something else - * - * Returns : 0 => Ok, everything else is an error. - * - *********************************************************************/ -int FUNCTION_NAME( void *param1, const char *x ) -{ - ... - return( 0 ); - -} - + } -Note: If we all follow this practice, we should be able to parse our code to -create a "self-documenting" web page. + Note: If we all follow this practice, we should be able to parse our code + to create a "self-documenting" web page. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 5. Testing Guidelines -To be filled. + To be filled. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.1. Testplan for releases + 5.1. Testplan for releases -Explain release numbers. major, minor. developer releases. etc. + Explain release numbers. major, minor. developer releases. etc. - 1. Remove any existing rpm with rpm -e + 1. Remove any existing rpm with rpm -e - 2. Remove any file that was left over. This includes (but is not limited to) + 2. Remove any file that was left over. This includes (but is not limited + to) - + /var/log/privoxy + * /var/log/privoxy - + /etc/privoxy + * /etc/privoxy - + /usr/sbin/privoxy + * /usr/sbin/privoxy - + /etc/init.d/privoxy + * /etc/init.d/privoxy - + /usr/doc/privoxy* + * /usr/doc/privoxy* - 3. Install the rpm. Any error messages? + 3. Install the rpm. Any error messages? - 4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/ - privoxy stop). Reboot your machine. Does autostart work? + 4. start,stop,status Privoxy with the specific script (e.g. + /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart + work? - 5. Start browsing. Does Privoxy work? Logfile written? + 5. Start browsing. Does Privoxy work? Logfile written? - 6. Remove the rpm. Any error messages? All files removed? + 6. Remove the rpm. Any error messages? All files removed? -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.2. Test reports + 5.2. Test reports -Please submit test reports only with the test form at sourceforge. Three simple -steps: + Please submit test reports only with the test form at sourceforge. Three + simple steps: - * Select category: the distribution you test on. + * Select category: the distribution you test on. - * Select group: the version of Privoxy that we are about to release. + * Select group: the version of Privoxy that we are about to release. - * Fill the Summary and Detailed Description with something intelligent (keep - it short and precise). + * Fill the Summary and Detailed Description with something intelligent + (keep it short and precise). -Do not mail to the mailing list (we cannot keep track on issues there). + Do not mail to the mailing list (we cannot keep track on issues there). -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 6. Releasing a New Version -When we release versions of Privoxy, our work leaves our cozy secret lab and -has to work in the cold RealWorld[tm]. Once it is released, there is no way to -call it back, so it is very important that great care is taken to ensure that -everything runs fine, and not to introduce problems in the very last minute. - -So when releasing a new version, please adhere exactly to the procedure -outlined in this chapter. - -The following programs are required to follow this process: ncftpput (ncftp), -scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs. - -------------------------------------------------------------------------------- - -6.1. Version numbers - -First you need to determine which version number the release will have. Privoxy -version numbers consist of three numbers, separated by dots, like in X.Y.Z -(e.g. 3.0.0), where: - - * X, the version major, is rarely ever changed. It is increased by one if - turning a development branch into stable substantially changes the - functionality, user interface or configuration syntax. Majors 1 and 2 were - Junkbuster, and 3 will be the first stable Privoxy release. - - * Y, the version minor, represents the branch within the major version. At - any point in time, there are two branches being maintained: The stable - branch, with an even minor, say, 2N, in which no functionality is being - added and only bug-fixes are made, and 2N+1, the development branch, in - which the further development of Privoxy takes place. This enables us to - turn the code upside down and inside out, while at the same time providing - and maintaining a stable version. The minor is reset to zero (and one) when - the major is incremented. When a development branch has matured to the - point where it can be turned into stable, the old stable branch 2N is given - up (i.e. no longer maintained), the former development branch 2N+1 becomes - the new stable branch 2N+2, and a new development branch 2N+3 is opened. - - * Z, the point or sub version, represents a release of the software within a - branch. It is therefore incremented immediately before each code freeze. In - development branches, only the even point versions correspond to actual - releases, while the odd ones denote the evolving state of the sources on - CVS in between. It follows that Z is odd on CVS in development branches - most of the time. There, it gets increased to an even number immediately - before a code freeze, and is increased to an odd number again immediately - thereafter. This ensures that builds from CVS snapshots are easily - distinguished from released versions. The point version is reset to zero - when the minor changes. - - Stable branches work a little differently, since there should be little to - no development happening in such branches. Remember, only bugfixes, which - presumably should have had some testing before being committed. Stable - branches will then have their version reported as 0.0.0, during that period - between releases when changes are being added. This is to denote that this - code is not for release. Then as the release nears, the version is bumped - according: e.g. 3.0.1 -> 0.0.0 -> 3.0.2. - -In summary, the main CVS trunk is the development branch where new features are -being worked on for the next stable series. This should almost always be where -the most activity takes place. There is always at least one stable branch from -the trunk, e.g now it is 3.0, which is only used to release stable versions. -Once the initial *.0 release of the stable branch has been done, then as a -rule, only bugfixes that have had prior testing should be committed to the -stable branch. Once there are enough bugfixes to justify a new release, the -version of this branch is again incremented Example: 3.0.0 -> 3.0.1 -> 3.0.2, -etc are all stable releases from within the stable branch. 3.1.x is currently -the main trunk, and where work on 3.2.x is taking place. If any questions, -please post to the devel list before committing to a stable branch! - -Developers should remember too that if they commit a bugfix to the stable -branch, this will more than likely require a separate submission to the main -trunk, since these are separate development trees within CVS. If you are -working on both, then this would require at least two separate check outs (i.e -main trunk, and the stable release branch, which is v_3_0_branch at the -moment). - -------------------------------------------------------------------------------- - -6.2. Before the Release: Freeze - -The following must be done by one of the developers prior to each new release. - - * Make sure that everybody who has worked on the code in the last couple of - days has had a chance to yell "no!" in case they have pending changes/fixes - in their pipelines. Announce the freeze so that nobody will interfere with - last minute changes. - - * Increment the version number (point from odd to even in development - branches!) in configure.in. (RPM spec files will need to be incremented as - well.) - - * If default.action has changed since last release (i.e. software release or - standalone actions file release), bump up its version info to A.B in this - line: - - {+add-header{X-Actions-File-Version: A.B} -filter -no-popups} - - - Then change the version info in doc/webserver/actions/index.php, line: - '$required_actions_file_version = "A.B";' - - * All documentation should be rebuild after the version bump. Finished docs - should be then be committed to CVS (for those without the ability to build - these). Some docs may require rather obscure processing tools. config, the - man page (and the html version of the man page), and the PDF docs fall in - this category. REAMDE, the man page, AUTHORS, and config should all also be - committed to CVS for other packagers. The formal docs should be uploaded to - the webserver. See the Section "Updating the webserver" in this manual for - details. - - * The User Manual is also used for context sensitive help for the CGI editor. - This is version sensitive, so that the user will get appropriate help for - his/her release. So with each release a fresh version should be uploaded to - the webserver (this is in addition to the main User Manual link from the - main page since we need to keep manuals for various versions available). - The CGI pages will link to something like http://privoxy.org/$(VERSION)/ - user-manual/. This will need to be updated for each new release. There is - no Makefile target for this at this time!!! It needs to be done manually. - - * All developers should look at the ChangeLog and make sure noteworthy - changes are referenced. - - * Commit all files that were changed in the above steps! - - * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't - use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. - - * If the release was in a development branch, increase the point version from - even to odd (X.Y.(Z+1)) again in configure.in and commit your change. - - * On the webserver, copy the user manual to a new top-level directory called - X.Y.Z. This ensures that help links from the CGI pages, which have the - version as a prefix, will go into the right version of the manual. If this - is a development branch release, also symlink X.Y.(Z-1) to X.Y.Z and X.Y. - (Z+1) to . (i.e. dot). - -------------------------------------------------------------------------------- - -6.3. Building and Releasing the Packages - -Now the individual packages can be built and released. Note that for GPL -reasons the first package to be released is always the source tarball. - -For all types of packages, including the source tarball, you must make sure -that you build from clean sources by exporting the right version from CVS into -an empty directory (just press return when asked for a password): + When we release versions of Privoxy, our work leaves our cozy secret lab + and has to work in the cold RealWorld[tm]. Once it is released, there is + no way to call it back, so it is very important that great care is taken + to ensure that everything runs fine, and not to introduce problems in the + very last minute. + + So when releasing a new version, please adhere exactly to the procedure + outlined in this chapter. + + The following programs are required to follow this process: ncftpput + (ncftp), scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs. + + -------------------------------------------------------------------------- + + 6.1. Version numbers + + First you need to determine which version number the release will have. + Privoxy version numbers consist of three numbers, separated by dots, like + in X.Y.Z (e.g. 3.0.0), where: + + * X, the version major, is rarely ever changed. It is increased by one + if turning a development branch into stable substantially changes the + functionality, user interface or configuration syntax. Majors 1 and 2 + were Junkbuster, and 3 will be the first stable Privoxy release. + + * Y, the version minor, represents the branch within the major version. + At any point in time, there are two branches being maintained: The + stable branch, with an even minor, say, 2N, in which no functionality + is being added and only bug-fixes are made, and 2N+1, the development + branch, in which the further development of Privoxy takes place. This + enables us to turn the code upside down and inside out, while at the + same time providing and maintaining a stable version. The minor is + reset to zero (and one) when the major is incremented. When a + development branch has matured to the point where it can be turned + into stable, the old stable branch 2N is given up (i.e. no longer + maintained), the former development branch 2N+1 becomes the new stable + branch 2N+2, and a new development branch 2N+3 is opened. + + * Z, the point or sub version, represents a release of the software + within a branch. It is therefore incremented immediately before each + code freeze. In development branches, only the even point versions + correspond to actual releases, while the odd ones denote the evolving + state of the sources on CVS in between. It follows that Z is odd on + CVS in development branches most of the time. There, it gets increased + to an even number immediately before a code freeze, and is increased + to an odd number again immediately thereafter. This ensures that + builds from CVS snapshots are easily distinguished from released + versions. The point version is reset to zero when the minor changes. + + Stable branches work a little differently, since there should be + little to no development happening in such branches. Remember, only + bugfixes, which presumably should have had some testing before being + committed. Stable branches will then have their version reported as + 0.0.0, during that period between releases when changes are being + added. This is to denote that this code is not for release. Then as + the release nears, the version is bumped according: e.g. 3.0.1 -> + 0.0.0 -> 3.0.2. + + In summary, the main CVS trunk is the development branch where new + features are being worked on for the next stable series. This should + almost always be where the most activity takes place. There is always at + least one stable branch from the trunk, e.g now it is 3.0, which is only + used to release stable versions. Once the initial *.0 release of the + stable branch has been done, then as a rule, only bugfixes that have had + prior testing should be committed to the stable branch. Once there are + enough bugfixes to justify a new release, the version of this branch is + again incremented Example: 3.0.0 -> 3.0.1 -> 3.0.2, etc are all stable + releases from within the stable branch. 3.1.x is currently the main trunk, + and where work on 3.2.x is taking place. If any questions, please post to + the devel list before committing to a stable branch! + + Developers should remember too that if they commit a bugfix to the stable + branch, this will more than likely require a separate submission to the + main trunk, since these are separate development trees within CVS. If you + are working on both, then this would require at least two separate check + outs (i.e main trunk, and the stable release branch, which is v_3_0_branch + at the moment). + + -------------------------------------------------------------------------- + + 6.2. Before the Release: Freeze + + The following must be done by one of the developers prior to each new + release. + + * Make sure that everybody who has worked on the code in the last couple + of days has had a chance to yell "no!" in case they have pending + changes/fixes in their pipelines. Announce the freeze so that nobody + will interfere with last minute changes. + + * Increment the version number (point from odd to even in development + branches!) in configure.in. (RPM spec files will need to be + incremented as well.) + + * If default.action has changed since last release (i.e. software + release or standalone actions file release), bump up its version info + to A.B in this line: + + {+add-header{X-Actions-File-Version: A.B} -filter -no-popups} + + Then change the version info in doc/webserver/actions/index.php, line: + '$required_actions_file_version = "A.B";' + + * All documentation should be rebuild after the version bump. Finished + docs should be then be committed to CVS (for those without the ability + to build these). Some docs may require rather obscure processing + tools. config, the man page (and the html version of the man page), + and the PDF docs fall in this category. REAMDE, the man page, AUTHORS, + and config should all also be committed to CVS for other packagers. + The formal docs should be uploaded to the webserver. See the Section + "Updating the webserver" in this manual for details. + + * The User Manual is also used for context sensitive help for the CGI + editor. This is version sensitive, so that the user will get + appropriate help for his/her release. So with each release a fresh + version should be uploaded to the webserver (this is in addition to + the main User Manual link from the main page since we need to keep + manuals for various versions available). The CGI pages will link to + something like http://privoxy.org/$(VERSION)/user-manual/. This will + need to be updated for each new release. There is no Makefile target + for this at this time!!! It needs to be done manually. + + * All developers should look at the ChangeLog and make sure noteworthy + changes are referenced. + + * Commit all files that were changed in the above steps! + + * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". + Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. + + * If the release was in a development branch, increase the point version + from even to odd (X.Y.(Z+1)) again in configure.in and commit your + change. + + * On the webserver, copy the user manual to a new top-level directory + called X.Y.Z. This ensures that help links from the CGI pages, which + have the version as a prefix, will go into the right version of the + manual. If this is a development branch release, also symlink + X.Y.(Z-1) to X.Y.Z and X.Y.(Z+1) to . (i.e. dot). + + -------------------------------------------------------------------------- + + 6.3. Building and Releasing the Packages + + Now the individual packages can be built and released. Note that for GPL + reasons the first package to be released is always the source tarball. + + For all types of packages, including the source tarball, you must make + sure that you build from clean sources by exporting the right version from + CVS into an empty directory (just press return when asked for a password): mkdir dist # delete or choose different name if it already exists cd dist cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current + Do NOT change a single bit, including, but not limited to version + information after export from CVS. This is to make sure that all release + packages, and with them, all future bug reports, are based on exactly the + same code. -Do NOT change a single bit, including, but not limited to version information -after export from CVS. This is to make sure that all release packages, and with -them, all future bug reports, are based on exactly the same code. - -+-----------------------------------------------------------------------------+ -| Warning | -|-----------------------------------------------------------------------------| -|Every significant release of Privoxy has included at least one package that | -|either had incorrect versions of files, missing files, or incidental | -|leftovers from a previous build process that gave unknown numbers of users | -|headaches to try to figure out what was wrong. PLEASE, make sure you are | -|using pristene sources, and are following the prescribed process! | -+-----------------------------------------------------------------------------+ - -Please find additional instructions for the source tarball and the individual -platform dependent binary packages below. And details on the Sourceforge -release process below that. - -------------------------------------------------------------------------------- - -6.3.1. Note on Privoxy Packaging - -Please keep these general guidelines in mind when putting together your -package. These apply to all platforms! + +------------------------------------------------------------------------+ + | Warning | + |------------------------------------------------------------------------| + | Every significant release of Privoxy has included at least one package | + | that either had incorrect versions of files, missing files, or | + | incidental leftovers from a previous build process that gave unknown | + | numbers of users headaches to try to figure out what was wrong. | + | PLEASE, make sure you are using pristene sources, and are following | + | the prescribed process! | + +------------------------------------------------------------------------+ - * Privoxy requires write access to: all *.action files, all logfiles, and the - trust file. You will need to determine the best way to do this for your - platform. + Please find additional instructions for the source tarball and the + individual platform dependent binary packages below. And details on the + Sourceforge release process below that. - * Please include up to date documentation. At a bare minimum: + -------------------------------------------------------------------------- - LICENSE (top-level directory) + 6.3.1. Note on Privoxy Packaging - README (top-level directory) + Please keep these general guidelines in mind when putting together your + package. These apply to all platforms! - AUTHORS (top-level directory) + * Privoxy requires write access to: all *.action files, all logfiles, + and the trust file. You will need to determine the best way to do this + for your platform. - man page (top-level directory, Unix-like platforms only) + * Please include up to date documentation. At a bare minimum: - The User Manual (doc/webserver/user-manual/) + LICENSE (top-level directory) - FAQ (doc/webserver/faq/) + README (top-level directory) - Also suggested: Developer Manual (doc/webserver/developer-manual) and - ChangeLog (top-level directory). FAQ and the manuals are HTML docs. There - are also text versions in doc/text/ which could conceivably also be - included. + AUTHORS (top-level directory) - The documentation has been designed such that the manuals are linked to - each other from parallel directories, and should be packaged that way. - privoxy-index.html can also be included and can serve as a focal point for - docs and other links of interest (and possibly renamed to index.html). This - should be one level up from the manuals. There is a link also on this page - to an HTMLized version of the man page. To avoid 404 for this, it is in CVS - as doc/webserver/man-page/privoxy-man-page.html, and should be included - along with the manuals. There is also a css stylesheets that can be - included for better presentation: p_doc.css. This should be in the same - directory with privoxy-index.html, (i.e. one level up from the manual - directories). + man page (top-level directory, Unix-like platforms only) - * user.action and user.filter are designed for local preferences. Make sure - these do not get overwritten! config should not be overwritten either. This - has especially important configuration data in it. trust should be left in - tact as well. + The User Manual (doc/webserver/user-manual/) - * Other configuration files (default.action, default.filter and - standard.action) should be installed as the new defaults, but all - previously installed configuration files should be preserved as backups. - This is just good manners :-) These files are likely to change between - releases and contain important new features and bug fixes. + FAQ (doc/webserver/faq/) - * Please check platform specific notes in this doc, if you haven't done - "Privoxy" packaging before for other platform specific issues. Conversely, - please add any notes that you know are important for your platform (or - contact one of the doc maintainers to do this if you can't). + Also suggested: Developer Manual (doc/webserver/developer-manual) and + ChangeLog (top-level directory). FAQ and the manuals are HTML docs. + There are also text versions in doc/text/ which could conceivably also + be included. - * Packagers should do a "clean" install of their package after building it. - So any previous installs should be removed first to ensure the integrity of - the newly built package. Then run the package for a while to make sure - there are no obvious problems, before uploading. + The documentation has been designed such that the manuals are linked + to each other from parallel directories, and should be packaged that + way. privoxy-index.html can also be included and can serve as a focal + point for docs and other links of interest (and possibly renamed to + index.html). This should be one level up from the manuals. There is a + link also on this page to an HTMLized version of the man page. To + avoid 404 for this, it is in CVS as + doc/webserver/man-page/privoxy-man-page.html, and should be included + along with the manuals. There is also a css stylesheets that can be + included for better presentation: p_doc.css. This should be in the + same directory with privoxy-index.html, (i.e. one level up from the + manual directories). -------------------------------------------------------------------------------- + * user.action and user.filter are designed for local preferences. Make + sure these do not get overwritten! config should not be overwritten + either. This has especially important configuration data in it. trust + should be left in tact as well. -6.3.2. Source Tarball + * Other configuration files (default.action, default.filter and + standard.action) should be installed as the new defaults, but all + previously installed configuration files should be preserved as + backups. This is just good manners :-) These files are likely to + change between releases and contain important new features and bug + fixes. -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then run: + * Please check platform specific notes in this doc, if you haven't done + "Privoxy" packaging before for other platform specific issues. + Conversely, please add any notes that you know are important for your + platform (or contact one of the doc maintainers to do this if you + can't). - cd current - autoheader && autoconf && ./configure + * Packagers should do a "clean" install of their package after building + it. So any previous installs should be removed first to ensure the + integrity of the newly built package. Then run the package for a while + to make sure there are no obvious problems, before uploading. + -------------------------------------------------------------------------- -Then do: + 6.3.2. Source Tarball - make tarball-dist + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then run: + cd current + autoheader && autoconf && ./configure -To upload the package to Sourceforge, simply issue + Then do: - make tarball-upload + make tarball-dist + To upload the package to Sourceforge, simply issue -Go to the displayed URL and release the file publicly on Sourceforge. For the -change log field, use the relevant section of the ChangeLog file. + make tarball-upload -------------------------------------------------------------------------------- + Go to the displayed URL and release the file publicly on Sourceforge. For + the change log field, use the relevant section of the ChangeLog file. -6.3.3. SuSE, Conectiva or Red Hat RPM + -------------------------------------------------------------------------- -In following text, replace dist with either "rh" for Red Hat or "suse" for -SuSE. + 6.3.3. SuSE, Conectiva or Red Hat RPM -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). + In following text, replace dist with either "rh" for Red Hat or "suse" for + SuSE. -As the only exception to not changing anything after export from CVS, now -examine the file privoxy-dist.spec and make sure that the version information -and the RPM release number are correct. The RPM release numbers for each -version start at one. Hence it must be reset to one if this is the first RPM -for dist which is built from version X.Y.Z. Check the file list if unsure. -Else, it must be set to the highest already available RPM release number for -that version plus one. + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). -Then run: + As the only exception to not changing anything after export from CVS, now + examine the file privoxy-dist.spec and make sure that the version + information and the RPM release number are correct. The RPM release + numbers for each version start at one. Hence it must be reset to one if + this is the first RPM for dist which is built from version X.Y.Z. Check + the file list if unsure. Else, it must be set to the highest already + available RPM release number for that version plus one. - cd current - autoheader && autoconf && ./configure + Then run: + cd current + autoheader && autoconf && ./configure -Then do + Then do - make dist-dist + make dist-dist + To upload the package to Sourceforge, simply issue -To upload the package to Sourceforge, simply issue + make dist-upload rpm_packagerev - make dist-upload rpm_packagerev + where rpm_packagerev is the RPM release number as determined above. Go to + the displayed URL and release the file publicly on Sourceforge. Use the + release notes and change log from the source tarball package. + -------------------------------------------------------------------------- -where rpm_packagerev is the RPM release number as determined above. Go to the -displayed URL and release the file publicly on Sourceforge. Use the release -notes and change log from the source tarball package. + 6.3.4. OS/2 -------------------------------------------------------------------------------- - -6.3.4. OS/2 - -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then get the OS/2 -Setup module: + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then get + the OS/2 Setup module: cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup + You will need a mix of development tools. The main compilation takes place + with IBM Visual Age C++. Some ancillary work takes place with GNU tools, + available from various sources like hobbes.nmsu.edu. Specificially, you + will need autoheader, autoconf and sh tools. The packaging takes place + with WarpIN, available from various sources, including its home page: + xworkplace. -You will need a mix of development tools. The main compilation takes place with -IBM Visual Age C++. Some ancillary work takes place with GNU tools, available -from various sources like hobbes.nmsu.edu. Specificially, you will need -autoheader, autoconf and sh tools. The packaging takes place with WarpIN, -available from various sources, including its home page: xworkplace. - -Change directory to the os2setup directory. Edit the os2build.cmd file to set -the final executable filename. For example, - - installExeName='privoxyos2_setup_X.Y.Z.exe' - - -Next, edit the IJB.wis file so the release number matches in the PACKAGEID -section: - - PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z" - - -You're now ready to build. Run: + Change directory to the os2setup directory. Edit the os2build.cmd file to + set the final executable filename. For example, - os2build + installExeName='privoxyos2_setup_X.Y.Z.exe' + Next, edit the IJB.wis file so the release number matches in the PACKAGEID + section: -You will find the WarpIN-installable executable in the ./files directory. -Upload this anonymously to uploads.sourceforge.net/incoming, create a release -for it, and you're done. Use the release notes and Change Log from the source -tarball package. + PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z" -------------------------------------------------------------------------------- + You're now ready to build. Run: -6.3.5. Solaris + os2build -Login to Sourceforge's compilefarm via ssh: + You will find the WarpIN-installable executable in the ./files directory. + Upload this anonymously to uploads.sourceforge.net/incoming, create a + release for it, and you're done. Use the release notes and Change Log from + the source tarball package. - ssh cf.sourceforge.net + -------------------------------------------------------------------------- + 6.3.5. Solaris -Choose the right operating system (not the Debian one). When logged in, make -sure that you have freshly exported the right version into an empty directory. -(See "Building and releasing packages" above). Then run: + Login to Sourceforge's compilefarm via ssh: - cd current - autoheader && autoconf && ./configure + ssh cf.sourceforge.net + Choose the right operating system (not the Debian one). When logged in, + make sure that you have freshly exported the right version into an empty + directory. (See "Building and releasing packages" above). Then run: -Then run + cd current + autoheader && autoconf && ./configure - gmake solaris-dist + Then run + gmake solaris-dist -which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload -on the Sourceforge machine (no ncftpput). You now have to manually upload the -archive to Sourceforge's ftp server and release the file publicly. Use the -release notes and Change Log from the source tarball package. + which creates a gzip'ed tar archive. Sadly, you cannot use make + solaris-upload on the Sourceforge machine (no ncftpput). You now have to + manually upload the archive to Sourceforge's ftp server and release the + file publicly. Use the release notes and Change Log from the source + tarball package. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.3.6. Windows + 6.3.6. Windows -You should ensure you have the latest version of Cygwin (from http:// -www.cygwin.com/). Run the following commands from within a Cygwin bash shell. + You should ensure you have the latest version of Cygwin (from + http://www.cygwin.com/). Run the following commands from within a Cygwin + bash shell. -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then get the Windows -setup module: + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then get + the Windows setup module: cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup + Then you can build the package. This is fully automated, and is controlled + by winsetup/GNUmakefile. All you need to do is: -Then you can build the package. This is fully automated, and is controlled by -winsetup/GNUmakefile. All you need to do is: + cd winsetup + make - cd winsetup - make + Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, + and upload it to SourceForge. When releasing the package on SourceForge, + use the release notes and Change Log from the source tarball package. + -------------------------------------------------------------------------- -Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and -upload it to SourceForge. When releasing the package on SourceForge, use the -release notes and Change Log from the source tarball package. + 6.3.7. Debian -------------------------------------------------------------------------------- + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then add a + log entry to debian/changelog, if it is not already there, for example by + running: -6.3.7. Debian + debchange -v 3.0.8-stable-1 "New upstream version" -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then add a log entry -to debian/changelog, if it is not already there, for example by running: + Then, run: - debchange -v 3.0.8-stable-1 "New upstream version" + dpkg-buildpackage -rfakeroot -us -uc -b + This will create ../privoxy_3.0.8-stable-1_i386.deb which can be uploaded. + To upload the package to Sourceforge, simply issue -Then, run: + make debian-upload - dpkg-buildpackage -rfakeroot -us -uc -b + -------------------------------------------------------------------------- + 6.3.8. Mac OSX -This will create ../privoxy_3.0.8-stable-1_i386.deb which can be uploaded. To -upload the package to Sourceforge, simply issue - - make debian-upload - - -------------------------------------------------------------------------------- - -6.3.8. Mac OSX - -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then get the Mac OSX -setup module: + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then get + the Mac OSX setup module: cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup + Then run: -Then run: - - cd osxsetup - build - - -This will run autoheader, autoconf and configure as well as make. Finally, it -will copy over the necessary files to the ./osxsetup/files directory for -further processing by PackageMaker. - -Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the -package name to match the release, and hit the "Create package" button. If you -specify ./Privoxy.pkg as the output package name, you can then create the -distributable zip file with the command: - - zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg + cd osxsetup + build + This will run autoheader, autoconf and configure as well as make. Finally, + it will copy over the necessary files to the ./osxsetup/files directory + for further processing by PackageMaker. -You can then upload privoxyosx_setup_x.y.z.zip anonymously to -uploads.sourceforge.net/incoming, create a release for it, and you're done. Use -the release notes and Change Log from the source tarball package. + Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify + the package name to match the release, and hit the "Create package" + button. If you specify ./Privoxy.pkg as the output package name, you can + then create the distributable zip file with the command: -------------------------------------------------------------------------------- + zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg -6.3.9. FreeBSD + You can then upload privoxyosx_setup_x.y.z.zip anonymously to + uploads.sourceforge.net/incoming, create a release for it, and you're + done. Use the release notes and Change Log from the source tarball + package. -Login to Sourceforge's compile-farm via ssh: + -------------------------------------------------------------------------- - ssh cf.sourceforge.net + 6.3.9. FreeBSD + Login to Sourceforge's compile-farm via ssh: -Choose the right operating system. When logged in, make sure that you have -freshly exported the right version into an empty directory. (See "Building and -releasing packages" above). Then run: + ssh cf.sourceforge.net - cd current - autoheader && autoconf && ./configure + Choose the right operating system. When logged in, make sure that you have + freshly exported the right version into an empty directory. (See "Building + and releasing packages" above). Then run: + cd current + autoheader && autoconf && ./configure -Then run: + Then run: - gmake freebsd-dist + gmake freebsd-dist + which creates a gzip'ed tar archive. Sadly, you cannot use make + freebsd-upload on the Sourceforge machine (no ncftpput). You now have to + manually upload the archive to Sourceforge's ftp server and release the + file publicly. Use the release notes and Change Log from the source + tarball package. -which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload -on the Sourceforge machine (no ncftpput). You now have to manually upload the -archive to Sourceforge's ftp server and release the file publicly. Use the -release notes and Change Log from the source tarball package. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 6.3.10. HP-UX 11 -6.3.10. HP-UX 11 + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then run: -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then run: + cd current + autoheader && autoconf && ./configure - cd current - autoheader && autoconf && ./configure + Then do FIXME. + -------------------------------------------------------------------------- -Then do FIXME. + 6.3.11. Amiga OS -------------------------------------------------------------------------------- + First, make sure that you have freshly exported the right version into an + empty directory. (See "Building and releasing packages" above). Then run: -6.3.11. Amiga OS + cd current + autoheader && autoconf && ./configure -First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then run: + Then do FIXME. - cd current - autoheader && autoconf && ./configure + -------------------------------------------------------------------------- + 6.3.12. AIX -Then do FIXME. + Login to Sourceforge's compilefarm via ssh: -------------------------------------------------------------------------------- + ssh cf.sourceforge.net -6.3.12. AIX + Choose the right operating system. When logged in, make sure that you have + freshly exported the right version into an empty directory. (See "Building + and releasing packages" above). Then run: -Login to Sourceforge's compilefarm via ssh: + cd current + autoheader && autoconf && ./configure - ssh cf.sourceforge.net + Then run: + make aix-dist -Choose the right operating system. When logged in, make sure that you have -freshly exported the right version into an empty directory. (See "Building and -releasing packages" above). Then run: + which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload + on the Sourceforge machine (no ncftpput). You now have to manually upload + the archive to Sourceforge's ftp server and release the file publicly. Use + the release notes and Change Log from the source tarball package. - cd current - autoheader && autoconf && ./configure + -------------------------------------------------------------------------- + 6.4. Uploading and Releasing Your Package -Then run: + After the package is ready, it is time to upload it to SourceForge, and go + through the release steps. The upload is done via FTP: - make aix-dist + * Upload to: ftp://upload.sourceforge.net/incoming + * user: anonymous -which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on -the Sourceforge machine (no ncftpput). You now have to manually upload the -archive to Sourceforge's ftp server and release the file publicly. Use the -release notes and Change Log from the source tarball package. + * password: ijbswa-developers@lists.sourceforge.net -------------------------------------------------------------------------------- + Or use the make targets as described above. -6.4. Uploading and Releasing Your Package + Once this done go to + http://sourceforge.net/project/admin/editpackages.php?group_id=11118, + making sure you are logged in. Find your target platform in the second + column, and click Add Release. You will then need to create a new release + for your package, using the format of $VERSION ($CODE_STATUS), e.g. 3.0.8 + (beta). -After the package is ready, it is time to upload it to SourceForge, and go -through the release steps. The upload is done via FTP: + Now just follow the prompts. Be sure to add any appropriate Release notes. + You should see your freshly uploaded packages in "Step 2. Add Files To + This Release". Check the appropriate box(es). Remember at each step to hit + the "Refresh/Submit" buttons! You should now see your file(s) listed in + Step 3. Fill out the forms with the appropriate information for your + platform, being sure to hit "Update" for each file. If anyone is + monitoring your platform, check the "email" box at the very bottom to + notify them of the new package. This should do it! - * Upload to: ftp://upload.sourceforge.net/incoming + If you have made errors, or need to make changes, you can go through + essentially the same steps, but select Edit Release, instead of Add + Release. - * user: anonymous + -------------------------------------------------------------------------- - * password: ijbswa-developers@lists.sourceforge.net + 6.5. After the Release -Or use the make targets as described above. + When all (or: most of the) packages have been uploaded and made available, + send an email to the announce mailing list, Subject: "Version X.Y.Z + available for download". Be sure to include the download location, the + release notes and the Changelog. Also, post an updated News item on the + project page Sourceforge, and update the Home page and docs linked from + the Home page (see below). Other news sites and release oriented sites, + such as Freshmeat, should also be notified. -Once this done go to http://sourceforge.net/project/admin/editpackages.php? -group_id=11118, making sure you are logged in. Find your target platform in the -second column, and click Add Release. You will then need to create a new -release for your package, using the format of $VERSION ($CODE_STATUS), e.g. -3.0.8 (beta). - -Now just follow the prompts. Be sure to add any appropriate Release notes. You -should see your freshly uploaded packages in "Step 2. Add Files To This -Release". Check the appropriate box(es). Remember at each step to hit the -"Refresh/Submit" buttons! You should now see your file(s) listed in Step 3. -Fill out the forms with the appropriate information for your platform, being -sure to hit "Update" for each file. If anyone is monitoring your platform, -check the "email" box at the very bottom to notify them of the new package. -This should do it! - -If you have made errors, or need to make changes, you can go through -essentially the same steps, but select Edit Release, instead of Add Release. - -------------------------------------------------------------------------------- - -6.5. After the Release - -When all (or: most of the) packages have been uploaded and made available, send -an email to the announce mailing list, Subject: "Version X.Y.Z available for -download". Be sure to include the download location, the release notes and the -Changelog. Also, post an updated News item on the project page Sourceforge, and -update the Home page and docs linked from the Home page (see below). Other news -sites and release oriented sites, such as Freshmeat, should also be notified. - -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 7. Update the Webserver -The webserver should be updated at least with each stable release. When -updating, please follow these steps to make sure that no broken links, -inconsistent contents or permission problems will occur (as it has many times -in the past!): + The webserver should be updated at least with each stable release. When + updating, please follow these steps to make sure that no broken links, + inconsistent contents or permission problems will occur (as it has many + times in the past!): -If you have changed anything in the stable-branch documentation source SGML -files, do: + If you have changed anything in the stable-branch documentation source + SGML files, do: make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you) + That will generate doc/webserver/user-manual, + doc/webserver/developer-manual, doc/webserver/faq, doc/pdf/*.pdf and + doc/webserver/index.html automatically. -That will generate doc/webserver/user-manual, doc/webserver/developer-manual, -doc/webserver/faq, doc/pdf/*.pdf and doc/webserver/index.html automatically. - -If you changed the manual page sources, generate doc/webserver/man-page/ -privoxy-man-page.html by running "make man". (This is a separate target due to -dependencies on some obscure perl scripts [now in CVS, but not well tested]. -See comments in GNUmakefile.) + If you changed the manual page sources, generate + doc/webserver/man-page/privoxy-man-page.html by running "make man". (This + is a separate target due to dependencies on some obscure perl scripts [now + in CVS, but not well tested]. See comments in GNUmakefile.) -If you want to add new files to the webserver, create them locally in the doc/ -webserver/* directory (or create new directories under doc/webserver). + If you want to add new files to the webserver, create them locally in the + doc/webserver/* directory (or create new directories under doc/webserver). -Next, commit any changes from the above steps to CVS. All set? If these are -docs in the stable branch, then do: + Next, commit any changes from the above steps to CVS. All set? If these + are docs in the stable branch, then do: - make webserver + make webserver + This will do the upload to the webserver (www.privoxy.org) and ensure all + files and directories there are group writable. -This will do the upload to the webserver (www.privoxy.org) and ensure all files -and directories there are group writable. + Please do NOT use any other means of transferring files to the webserver + to avoid permission problems. Also, please do not upload docs from + development branches or versions. The publicly posted docs should be in + sync with the last official release. -Please do NOT use any other means of transferring files to the webserver to -avoid permission problems. Also, please do not upload docs from development -branches or versions. The publicly posted docs should be in sync with the last -official release. - -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 8. Contacting the developers, Bug Reporting and Feature Requests -We value your feedback. In fact, we rely on it to improve Privoxy and its -configuration. However, please note the following hints, so we can provide you -with the best support: + We value your feedback. In fact, we rely on it to improve Privoxy and its + configuration. However, please note the following hints, so we can provide + you with the best support: -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.1. Get Support + 8.1. Get Support -For casual users, our support forum at SourceForge is probably best suited: -http://sourceforge.net/tracker/?group_id=11118&atid=211118 + For casual users, our support forum at SourceForge is probably best + suited: http://sourceforge.net/tracker/?group_id=11118&atid=211118 -All users are of course welcome to discuss their issues on the users mailing -list, where the developers also hang around. + All users are of course welcome to discuss their issues on the users + mailing list, where the developers also hang around. -Note that the Privoxy mailing lists are moderated. Posts from unsubscribed -addresses have to be accepted manually by a moderator. This may cause a delay -of several days and if you use a subject that doesn't clearly mention Privoxy -or one of its features, your message may be accidentally discarded as spam. + Note that the Privoxy mailing lists are moderated. Posts from unsubscribed + addresses have to be accepted manually by a moderator. This may cause a + delay of several days and if you use a subject that doesn't clearly + mention Privoxy or one of its features, your message may be accidentally + discarded as spam. -If you aren't subscribed, you should therefore spend a few seconds to come up -with a proper subject. Additionally you should make it clear that you want to -get CC'd. Otherwise some responses will be directed to the mailing list only, -and you won't see them. + If you aren't subscribed, you should therefore spend a few seconds to come + up with a proper subject. Additionally you should make it clear that you + want to get CC'd. Otherwise some responses will be directed to the mailing + list only, and you won't see them. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.2. Reporting Problems + 8.2. Reporting Problems -"Problems" for our purposes, come in two forms: + "Problems" for our purposes, come in two forms: - * Configuration issues, such as ads that slip through, or sites that don't - function properly due to one Privoxy "action" or another being turned "on". + * Configuration issues, such as ads that slip through, or sites that + don't function properly due to one Privoxy "action" or another being + turned "on". - * "Bugs" in the programming code that makes up Privoxy, such as that might - cause a crash. + * "Bugs" in the programming code that makes up Privoxy, such as that + might cause a crash. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.2.1. Reporting Ads or Other Configuration Problems + 8.2.1. Reporting Ads or Other Configuration Problems -Please send feedback on ads that slipped through, innocent images that were -blocked, sites that don't work properly, and other configuration related -problem of default.action file, to http://sourceforge.net/tracker/?group_id= -11118&atid=460288, the Actions File Tracker. + Please send feedback on ads that slipped through, innocent images that + were blocked, sites that don't work properly, and other configuration + related problem of default.action file, to + http://sourceforge.net/tracker/?group_id=11118&atid=460288, the Actions + File Tracker. -New, improved default.action files may occasionally be made available based on -your feedback. These will be announced on the ijbswa-announce list and -available from our the files section of our project page. + New, improved default.action files may occasionally be made available + based on your feedback. These will be announced on the ijbswa-announce + list and available from our the files section of our project page. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.2.2. Reporting Bugs + 8.2.2. Reporting Bugs -Please report all bugs through our bug tracker: http://sourceforge.net/tracker -/?group_id=11118&atid=111118. + Please report all bugs through our bug tracker: + http://sourceforge.net/tracker/?group_id=11118&atid=111118. -Before doing so, please make sure that the bug has not already been submitted -and observe the additional hints at the top of the submit form. If already -submitted, please feel free to add any info to the original report that might -help to solve the issue. + Before doing so, please make sure that the bug has not already been + submitted and observe the additional hints at the top of the submit form. + If already submitted, please feel free to add any info to the original + report that might help to solve the issue. -Please try to verify that it is a Privoxy bug, and not a browser or site bug or -documented behaviour that just happens to be different than what you expected. -If unsure, try toggling off Privoxy, and see if the problem persists. + Please try to verify that it is a Privoxy bug, and not a browser or site + bug or documented behaviour that just happens to be different than what + you expected. If unsure, try toggling off Privoxy, and see if the problem + persists. -If you are using your own custom configuration, please try the stock configs to -see if the problem is configuration related. If you're having problems with a -feature that is disabled by default, please ask around on the mailing list if -others can reproduce the problem. + If you are using your own custom configuration, please try the stock + configs to see if the problem is configuration related. If you're having + problems with a feature that is disabled by default, please ask around on + the mailing list if others can reproduce the problem. -If you aren't using the latest Privoxy version, the bug may have been found and -fixed in the meantime. We would appreciate if you could take the time to -upgrade to the latest version (or even the latest CVS snapshot) and verify that -your bug still exists. + If you aren't using the latest Privoxy version, the bug may have been + found and fixed in the meantime. We would appreciate if you could take the + time to upgrade to the latest version (or even the latest CVS snapshot) + and verify that your bug still exists. -Please be sure to provide the following information: + Please be sure to provide the following information: - * The exact Privoxy version you are using (if you got the source from CVS, - please also provide the source code revisions as shown in http:// - config.privoxy.org/show-version). + * The exact Privoxy version you are using (if you got the source from + CVS, please also provide the source code revisions as shown in + http://config.privoxy.org/show-version). - * The operating system and versions you run Privoxy on, (e.g. Windows XP - SP2), if you are using a Unix flavor, sending the output of "uname -a" - should do, in case of GNU/Linux, please also name the distribution. + * The operating system and versions you run Privoxy on, (e.g. Windows XP + SP2), if you are using a Unix flavor, sending the output of "uname -a" + should do, in case of GNU/Linux, please also name the distribution. - * The name, platform, and version of the browser you were using (e.g. - Internet Explorer v5.5 for Mac). + * The name, platform, and version of the browser you were using (e.g. + Internet Explorer v5.5 for Mac). - * The URL where the problem occurred, or some way for us to duplicate the - problem (e.g. http://somesite.example.com/?somethingelse=123). + * The URL where the problem occurred, or some way for us to duplicate + the problem (e.g. http://somesite.example.com/?somethingelse=123). - * Whether your version of Privoxy is one supplied by the Privoxy developers - via SourceForge, or if you got your copy somewhere else. + * Whether your version of Privoxy is one supplied by the Privoxy + developers via SourceForge, or if you got your copy somewhere else. - * Whether you are using Privoxy in tandem with another proxy such as Tor. If - so, please temporary disable the other proxy to see if the symptoms change. + * Whether you are using Privoxy in tandem with another proxy such as + Tor. If so, please temporary disable the other proxy to see if the + symptoms change. - * Whether you are using a personal firewall product. If so, does Privoxy work - without it? + * Whether you are using a personal firewall product. If so, does Privoxy + work without it? - * Any other pertinent information to help identify the problem such as config - or log file excerpts (yes, you should have log file entries for each action - taken). + * Any other pertinent information to help identify the problem such as + config or log file excerpts (yes, you should have log file entries for + each action taken). -You don't have to tell us your actual name when filing a problem report, but -please use a nickname so we can differentiate between your messages and the -ones entered by other "anonymous" users that may respond to your request if -they have the same problem or already found a solution. + You don't have to tell us your actual name when filing a problem report, + but please use a nickname so we can differentiate between your messages + and the ones entered by other "anonymous" users that may respond to your + request if they have the same problem or already found a solution. -Please also check the status of your request a few days after submitting it, as -we may request additional information. If you use a SF id, you should -automatically get a mail when someone responds to your request. + Please also check the status of your request a few days after submitting + it, as we may request additional information. If you use a SF id, you + should automatically get a mail when someone responds to your request. -The appendix of the Privoxy User Manual also has helpful information on -understanding actions, and action debugging. + The appendix of the Privoxy User Manual also has helpful information on + understanding actions, and action debugging. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.3. Request New Features + 8.3. Request New Features -You are welcome to submit ideas on new features or other proposals for -improvement through our feature request tracker at http://sourceforge.net/ -tracker/?atid=361118&group_id=11118. + You are welcome to submit ideas on new features or other proposals for + improvement through our feature request tracker at + http://sourceforge.net/tracker/?atid=361118&group_id=11118. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.4. Other + 8.4. Other -For any other issues, feel free to use the mailing lists. Technically -interested users and people who wish to contribute to the project are also -welcome on the developers list! You can find an overview of all Privoxy-related -mailing lists, including list archives, at: http://sourceforge.net/mail/? -group_id=11118. + For any other issues, feel free to use the mailing lists. Technically + interested users and people who wish to contribute to the project are also + welcome on the developers list! You can find an overview of all + Privoxy-related mailing lists, including list archives, at: + http://sourceforge.net/mail/?group_id=11118. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 9. Privoxy Copyright, License and History -Copyright 2001-2008 by Privoxy Developers < -ijbswa-developers@lists.sourceforge.net> + Copyright © 2001-2008 by Privoxy Developers + <ijbswa-developers@lists.sourceforge.net> -Some source code is based on code Copyright 1997 by Anonymous Coders and -Junkbusters, Inc. and licensed under the GNU General Public License. + Some source code is based on code Copyright © 1997 by Anonymous Coders + and Junkbusters, Inc. and licensed under the GNU General Public License. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -9.1. License + 9.1. License -Privoxy is free software; you can redistribute it and/or modify it under the -terms of the GNU General Public License, version 2, as published by the Free -Software Foundation. + Privoxy is free software; you can redistribute it and/or modify it under + the terms of the GNU General Public License, version 2, as published by + the Free Software Foundation. -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, 51 Franklin Street, Fifth -Floor, Boston, MA 02110-1301, USA + 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, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA -You should have received a copy of the GNU General Public License along with -this program; if not, write to the + You should have received a copy of the GNU General Public License along + with this program; if not, write to the - Free Software - Foundation, Inc. 51 Franklin Street, Fifth Floor - Boston, MA 02110-1301 - USA + Free Software + Foundation, Inc. 51 Franklin Street, Fifth Floor + Boston, MA 02110-1301 + USA -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -9.2. History + 9.2. History -A long time ago, there was the Internet Junkbuster, by Anonymous Coders and -Junkbusters Corporation. This saved many users a lot of pain in the early days -of web advertising and user tracking. + A long time ago, there was the Internet Junkbuster, by Anonymous Coders + and Junkbusters Corporation. This saved many users a lot of pain in the + early days of web advertising and user tracking. -But the web, its protocols and standards, and with it, the techniques for -forcing ads on users, give up autonomy over their browsing, and for tracking -them, keeps evolving. Unfortunately, the Internet Junkbuster did not. Version -2.0.2, published in 1998, was (and is) the last official release available from -Junkbusters Corporation. Fortunately, it had been released under the GNU GPL, -which allowed further development by others. + But the web, its protocols and standards, and with it, the techniques for + forcing ads on users, give up autonomy over their browsing, and for + tracking them, keeps evolving. Unfortunately, the Internet Junkbuster did + not. Version 2.0.2, published in 1998, was (and is) the last official + release available from Junkbusters Corporation. Fortunately, it had been + released under the GNU GPL, which allowed further development by others. -So Stefan Waldherr started maintaining an improved version of the software, to -which eventually a number of people contributed patches. It could already -replace banners with a transparent image, and had a first version of pop-up -killing, but it was still very closely based on the original, with all its -limitations, such as the lack of HTTP/1.1 support, flexible per-site -configuration, or content modification. The last release from this effort was -version 2.0.2-10, published in 2000. + So Stefan Waldherr started maintaining an improved version of the + software, to which eventually a number of people contributed patches. It + could already replace banners with a transparent image, and had a first + version of pop-up killing, but it was still very closely based on the + original, with all its limitations, such as the lack of HTTP/1.1 support, + flexible per-site configuration, or content modification. The last release + from this effort was version 2.0.2-10, published in 2000. -Then, some developers picked up the thread, and started turning the software -inside out, upside down, and then reassembled it, adding many new features -along the way. + Then, some developers picked up the thread, and started turning the + software inside out, upside down, and then reassembled it, adding many new + features along the way. -The result of this is Privoxy, whose first stable version, 3.0, was released -August, 2002. + The result of this is Privoxy, whose first stable version, 3.0, was + released August, 2002. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 10. See also -Other references and sites of interest to Privoxy users: - -http://www.privoxy.org/, the Privoxy Home page. + Other references and sites of interest to Privoxy users: -http://www.privoxy.org/faq/, the Privoxy FAQ. + http://www.privoxy.org/, the Privoxy Home page. -http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on -SourceForge. + http://www.privoxy.org/faq/, the Privoxy FAQ. -http://config.privoxy.org/, the web-based user interface. Privoxy must be -running for this to work. Shortcut: http://p.p/ + http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on + SourceForge. -http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit "misses" -and other configuration related suggestions to the developers. + http://config.privoxy.org/, the web-based user interface. Privoxy must be + running for this to work. Shortcut: http://p.p/ -http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies are -used to track web users. + http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit + "misses" and other configuration related suggestions to the developers. -http://www.junkbusters.com/ijb.html, the original Internet Junkbuster. + http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies + are used to track web users. -http://privacy.net/, a useful site to check what information about you is -leaked while you browse the web. + http://www.junkbusters.com/ijb.html, the original Internet Junkbuster. -http://www.squid-cache.org/, a popular caching proxy, which is often used -together with Privoxy. + http://privacy.net/, a useful site to check what information about you is + leaked while you browse the web. -http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy with -advanced features like pipelining, multiplexing and caching of partial -instances. In many setups it can be used as Squid replacement. + http://www.squid-cache.org/, a popular caching proxy, which is often used + together with Privoxy. -http://tor.eff.org/, Tor can help anonymize web browsing, web publishing, -instant messaging, IRC, SSH, and other applications. + http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy + with advanced features like pipelining, multiplexing and caching of + partial instances. In many setups it can be used as Squid replacement. -http://www.privoxy.org/developer-manual/, the Privoxy developer manual. + http://tor.eff.org/, Tor can help anonymize web browsing, web publishing, + instant messaging, IRC, SSH, and other applications. + http://www.privoxy.org/developer-manual/, the Privoxy developer manual. diff --git a/doc/text/faq.txt b/doc/text/faq.txt index e263cc27..b5ae7328 100644 --- a/doc/text/faq.txt +++ b/doc/text/faq.txt @@ -1,1787 +1,1956 @@ -Privoxy Frequently Asked Questions + Privoxy Frequently Asked Questions -[ Copyright 2001-2008 by Privoxy Developers ] + [Copyright[ © 2001-2008 by Privoxy Developers]] -$Id: faq.sgml,v 2.37 2008/01/19 15:03:05 hal9 Exp $ + $Id: faq.sgml,v 2.38 2008/01/19 17:52:39 hal9 Exp $ -This FAQ gives quick answers to frequently asked questions about Privoxy. It is -not a substitute for the Privoxy User Manual. + This FAQ gives quick answers to frequently asked questions about Privoxy. + It is not a substitute for the Privoxy User Manual. -What is Privoxy? + What is Privoxy? -Privoxy is a non-caching web proxy with advanced filtering capabilities for -enhancing privacy, modifying web page data, managing HTTP cookies, controlling -access, and removing ads, banners, pop-ups and other obnoxious Internet junk. -Privoxy has a flexible configuration and can be customized to suit individual -needs and tastes. Privoxy has application for both stand-alone systems and -multi-user networks. + Privoxy is a non-caching web proxy with advanced filtering capabilities + for enhancing privacy, modifying web page data, managing HTTP cookies, + controlling access, and removing ads, banners, pop-ups and other obnoxious + Internet junk. Privoxy has a flexible configuration and can be customized + to suit individual needs and tastes. Privoxy has application for both + stand-alone systems and multi-user networks. -Privoxy is based on Internet Junkbuster (tm). + Privoxy is based on Internet Junkbuster (tm). -Please note that this document is a work in progress. This copy represents the -state at the release of version 3.0.8. You can find the latest version of the -document at http://www.privoxy.org/faq/. Please see the Contact section if you -want to contact the developers. + Please note that this document is a work in progress. This copy represents + the state at the release of version 3.0.8. You can find the latest version + of the document at http://www.privoxy.org/faq/. Please see the Contact + section if you want to contact the developers. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -Table of Contents -1. General Information + Table of Contents - 1.1. Who should give Privoxy a try? - 1.2. Is Privoxy the best choice for me? - 1.3. What is a "proxy"? How does Privoxy work? - 1.4. Does Privoxy do anything more than ad blocking? - 1.5. What is this new version of "Junkbuster"? - 1.6. Why "Privoxy"? Why change the name from Junkbuster at all? - 1.7. How does Privoxy differ from the old Junkbuster? - 1.8. How does Privoxy know what is an ad, and what is not? - 1.9. Can Privoxy make mistakes? This does not sound very scientific. - 1.10. Will I have to configure Privoxy before I can use it? - 1.11. Can Privoxy run as a server on a network? - 1.12. My browser does the same things as Privoxy. Why should I use Privoxy - at all? - 1.13. Why should I trust Privoxy? - 1.14. Is there is a license or fee? What about a warranty? Registration? - 1.15. Can Privoxy remove spyware? Adware? Viruses? - 1.16. Can I use Privoxy with other ad-blocking software? - 1.17. I would like to help you, what can I do? + 1. General Information - 1.17.1. Would you like to participate? - 1.17.2. Contribute! - 1.17.3. Software + 1.1. Who should give Privoxy a try? -2. Installation + 1.2. Is Privoxy the best choice for me? - 2.1. Which browsers are supported by Privoxy? - 2.2. Which operating systems are supported? - 2.3. Can I use Privoxy with my email client? - 2.4. I just installed Privoxy. Is there anything special I have to do now? - 2.5. What is the proxy address of Privoxy? - 2.6. I just installed Privoxy, and nothing is happening. All the ads are - there. What's wrong? - 2.7. I get a "Privoxy is not being used" dummy page although Privoxy is - running and being used. + 1.3. What is a "proxy"? How does Privoxy work? -3. Configuration + 1.4. Does Privoxy do anything more than ad blocking? - 3.1. What exactly is an "actions" file? - 3.2. The "actions" concept confuses me. Please list some of these - "actions". - 3.3. How are actions files configured? What is the easiest way to do this? - 3.4. There are several different "actions" files. What are the differences? - 3.5. Where can I get updated Actions Files? - 3.6. Can I use my old config files? - 3.7. Why is the configuration so complicated? - 3.8. How can I make my Yahoo/Hotmail/Gmail account work? - 3.9. What's the difference between the "Cautious", "Medium" and "Advanced" - defaults? - 3.10. Why can I change the configuration with a browser? Does that not - raise security issues? - 3.11. What is the default.filter file? What is a "filter"? - 3.12. How can I set up Privoxy to act as a proxy for my LAN? - 3.13. Instead of ads, now I get a checkerboard pattern. I don't want to see - anything. - 3.14. Why would anybody want to see a checkerboard pattern? - 3.15. I see some images being replaced with text instead of the - checkerboard image. Why and how do I get rid of this? - 3.16. Can Privoxy run as a service on Win2K/NT/XP? - 3.17. How can I make Privoxy work with other proxies like Squid or Tor? - 3.18. Can I just set Privoxy to use port 80 and thus avoid individual - browser configuration? - 3.19. Can Privoxy run as a "transparent" proxy? - 3.20. Can Privoxy run as a "intercepting" proxy? - 3.21. How can I configure Privoxy for use with Outlook Express? - 3.22. How can I have separate rules just for HTML mail? - 3.23. I sometimes notice cookies sneaking through. How? - 3.24. Are all cookies bad? Why? - 3.25. How can I allow permanent cookies for my trusted sites? - 3.26. Can I have separate configurations for different users? - 3.27. Can I set-up Privoxy as a whitelist of "good" sites? - 3.28. How can I turn off ad-blocking? - 3.29. How can I have custom template pages, like the BLOCKED page? - 3.30. How can I remove the "Go There Anyway" link from the BLOCKED page? + 1.5. What is this new version of "Junkbuster"? -4. Miscellaneous + 1.6. Why "Privoxy"? Why change the name from Junkbuster at + all? - 4.1. How much does Privoxy slow my browsing down? This has to add extra - time to browsing. - 4.2. I notice considerable delays in page requests. What's wrong? - 4.3. What are "http://config.privoxy.org/" and "http://p.p/"? - 4.4. How can I submit new ads, or report problems? - 4.5. If I do submit missed ads, will they be included in future updates? - 4.6. Why doesn't anyone answer my support request? - 4.7. How can I hide my IP address? - 4.8. Can Privoxy guarantee I am anonymous? - 4.9. A test site says I am not using a Proxy. - 4.10. How do I use Privoxy together with Tor? - 4.11. Might some things break because header information or content is - being altered? - 4.12. Can Privoxy act as a "caching" proxy to speed up web browsing? - 4.13. What about as a firewall? Can Privoxy protect me? - 4.14. I have large empty spaces / a checkerboard pattern now where ads used - to be. Why? - 4.15. How can Privoxy filter Secure (HTTPS) URLs? - 4.16. Privoxy runs as a "server". How secure is it? Do I need to take any - special precautions? - 4.17. Can I temporarily disable Privoxy? - 4.18. When "disabled" is Privoxy totally out of the picture? - 4.19. How can I tell Privoxy to totally ignore certain sites? - 4.20. My logs show Privoxy "crunches" ads, but also its own internal CGI - pages. What is a "crunch"? - 4.21. Can Privoxy effect files that I download from a webserver? FTP - server? - 4.22. I just downloaded a Perl script, and Privoxy altered it! Yikes, what - is wrong! - 4.23. Should I continue to use a "HOSTS" file for ad-blocking? - 4.24. Where can I find more information about Privoxy and related issues? - 4.25. I've noticed that Privoxy changes "Microsoft" to "MicroSuck"! Why are - you manipulating my browsing? - 4.26. Does Privoxy produce "valid" HTML (or XHTML)? + 1.7. How does Privoxy differ from the old Junkbuster? -5. Troubleshooting + 1.8. How does Privoxy know what is an ad, and what is not? - 5.1. I cannot connect to any websites. Or, I am getting "connection - refused" message with every web page. Why? - 5.2. Why am I getting a 503 Error (WSAECONNREFUSED) on every page? - 5.3. I just added a new rule, but the steenkin ad is still getting through. - How? - 5.4. One of my favorite sites does not work with Privoxy. What can I do? - 5.5. After installing Privoxy, I have to log in every time I start IE. What - gives? - 5.6. I cannot connect to any FTP sites. Privoxy is blocking me. - 5.7. In Mac OSX, I can't configure Microsoft Internet Explorer to use - Privoxy as the HTTP proxy. - 5.8. In Mac OSX, I dragged the Privoxy folder to the trash in order to - uninstall it. Now the finder tells me I don't have sufficient - privileges to empty the trash. - 5.9. In Mac OSX Panther (10.3), images often fail to load and/or I - experience random delays in page loading. I'm using localhost as my - browser's proxy setting. - 5.10. I get a completely blank page at one site. "View Source" shows only: - <html><body></body></html>. Without Privoxy the page loads fine. - 5.11. My logs show many "Unable to get my own hostname" lines. Why? - 5.12. When I try to launch Privoxy, I get an error message "port 8118 is - already in use" (or similar wording). Why? - 5.13. Pages with UTF-8 fonts are garbled. - 5.14. Why are binary files (such as images) corrupted when Privoxy is used? - 5.15. What is the "demoronizer" and why is it there? - 5.16. Why do I keep seeing "PrivoxyWindowOpen()" in raw source code? - 5.17. I am getting too many DNS errors like "404 No Such Domain". Why can't - Privoxy do this better? - 5.18. At one site Privoxy just hangs, and starts taking all CPU. Why is - this? - 5.19. I just installed Privoxy, and all my browsing has slowed to a crawl. - What gives? - 5.20. Why do my filters work on some sites but not on others? + 1.9. Can Privoxy make mistakes? This does not sound very + scientific. -6. Contacting the developers, Bug Reporting and Feature Requests + 1.10. Will I have to configure Privoxy before I can use it? - 6.1. Get Support - 6.2. Reporting Problems + 1.11. Can Privoxy run as a server on a network? - 6.2.1. Reporting Ads or Other Configuration Problems - 6.2.2. Reporting Bugs + 1.12. My browser does the same things as Privoxy. Why should + I use Privoxy at all? - 6.3. Request New Features - 6.4. Other + 1.13. Why should I trust Privoxy? -7. Privoxy Copyright, License and History + 1.14. Is there is a license or fee? What about a warranty? + Registration? - 7.1. License - 7.2. History + 1.15. Can Privoxy remove spyware? Adware? Viruses? -1. General Information + 1.16. Can I use Privoxy with other ad-blocking software? -1.1. Who should give Privoxy a try? + 1.17. I would like to help you, what can I do? -Anyone who is interested in security, privacy, or in finer-grained control over -their web and Internet experience. + 1.17.1. Would you like to participate? -------------------------------------------------------------------------------- + 1.17.2. Contribute! -1.2. Is Privoxy the best choice for me? + 1.17.3. Software -Privoxy is certainly a good choice, especially for those who want more control -and security. Those with the willingness to read the documentation and the -ability to fine-tune their installation will benefit the most. + 2. Installation -One of Privoxy's strengths is that it is highly configurable giving you the -ability to completely personalize your installation. Being familiar with, or at -least having an interest in learning about HTTP and other networking protocols, -HTML, and "Regular Expressions" will be a big plus and will help you get the -most out of Privoxy. A new installation just includes a very basic -configuration. The user should take this as a starting point only, and enhance -it as he or she sees fit. In fact, the user is encouraged, and expected to, -fine-tune the configuration. + 2.1. Which browsers are supported by Privoxy? -Much of Privoxy's configuration can be done with a Web browser. But there are -areas where configuration is done using a text editor to edit configuration -files. Also note that the web-based action editor doesn't use authentication -and should only be enabled in environments where all clients with access to -Privoxy listening port can be trusted. + 2.2. Which operating systems are supported? -------------------------------------------------------------------------------- + 2.3. Can I use Privoxy with my email client? -1.3. What is a "proxy"? How does Privoxy work? + 2.4. I just installed Privoxy. Is there anything special I + have to do now? -A web proxy is a service, based on a software such as Privoxy, that clients -(i.e. browsers) can use instead of connecting directly to web servers on the -Internet. The clients then ask the proxy to fetch the objects they need (web -pages, images, movies etc) on their behalf, and when the proxy has done so, it -hands the results back to the client. It is a "go-between". See the Wikipedia -proxy definition for more. + 2.5. What is the proxy address of Privoxy? -There are many reasons to use web proxies, such as security (firewalling), -efficiency (caching) and others, and there are any number of proxies to -accommodate those needs. + 2.6. I just installed Privoxy, and nothing is happening. All + the ads are there. What's wrong? -Privoxy is a proxy that is primarily focused on privacy protection, ad and junk -elimination and freeing the user from restrictions placed on his activities. -Sitting between your browser(s) and the Internet, it is in a perfect position -to filter outbound personal information that your browser is leaking, as well -as inbound junk. It uses a variety of techniques to do this, all of which are -under your complete control via the various configuration files and options. -Being a proxy also makes it easier to share configurations among multiple -browsers and/or users. + 2.7. I get a "Privoxy is not being used" dummy page although + Privoxy is running and being used. -------------------------------------------------------------------------------- + 3. Configuration -1.4. Does Privoxy do anything more than ad blocking? + 3.1. What exactly is an "actions" file? -Yes, ad blocking is but one possible use. There are many, many ways Privoxy can -be used to sanitize and customize web browsing. + 3.2. The "actions" concept confuses me. Please list some of + these "actions". -------------------------------------------------------------------------------- + 3.3. How are actions files configured? What is the easiest + way to do this? -1.5. What is this new version of "Junkbuster"? + 3.4. There are several different "actions" files. What are + the differences? -A long time ago, there was the Internet Junkbuster, by Anonymous Coders and -Junkbusters Corporation. This saved many users a lot of pain in the early days -of web advertising and user tracking. + 3.5. Where can I get updated Actions Files? -But the web, its protocols and standards, and with it, the techniques for -forcing ads on users, give up autonomy over their browsing, and for tracking -them, keeps evolving. Unfortunately, the Internet Junkbuster did not. Version -2.0.2, published in 1998, was (and is) the last official release available from -Junkbusters Corporation. Fortunately, it had been released under the GNU GPL, -which allowed further development by others. + 3.6. Can I use my old config files? -So Stefan Waldherr started maintaining an improved version of the software, to -which eventually a number of people contributed patches. It could already -replace banners with a transparent image, and had a first version of pop-up -killing, but it was still very closely based on the original, with all its -limitations, such as the lack of HTTP/1.1 support, flexible per-site -configuration, or content modification. The last release from this effort was -version 2.0.2-10, published in 2000. + 3.7. Why is the configuration so complicated? -Then, some developers picked up the thread, and started turning the software -inside out, upside down, and then reassembled it, adding many new features -along the way. + 3.8. How can I make my Yahoo/Hotmail/Gmail account work? -The result of this is Privoxy, whose first stable version, 3.0, was released -August, 2002. + 3.9. What's the difference between the "Cautious", "Medium" + and "Advanced" defaults? -------------------------------------------------------------------------------- + 3.10. Why can I change the configuration with a browser? Does + that not raise security issues? -1.6. Why "Privoxy"? Why change the name from Junkbuster at all? + 3.11. What is the default.filter file? What is a "filter"? -Though outdated, Junkbusters Corporation continues to offer their original -version of the Internet Junkbuster, so publishing our Junkbuster-derived -software under the same name led to confusion. + 3.12. How can I set up Privoxy to act as a proxy for my LAN? -There are also potential legal complications from our use of the Junkbuster -name, which is a registered trademark of Junkbusters Corporation. There are, -however, no objections from Junkbusters Corporation to the Privoxy project -itself, and they, in fact, still share our ideals and goals. + 3.13. Instead of ads, now I get a checkerboard pattern. I + don't want to see anything. -The developers also believed that there are so many improvements over the -original code, that it was time to make a clean break from the past and make a -name in their own right. + 3.14. Why would anybody want to see a checkerboard pattern? -Privoxy is the "Privacy Enhancing Proxy". Also, its content modification and -junk suppression gives you, the user, more control, more freedom, and allows -you to browse your personal and "private edition" of the web. + 3.15. I see some images being replaced with text instead of + the checkerboard image. Why and how do I get rid of this? -------------------------------------------------------------------------------- + 3.16. Can Privoxy run as a service on Win2K/NT/XP? -1.7. How does Privoxy differ from the old Junkbuster? + 3.17. How can I make Privoxy work with other proxies like + Squid or Tor? -Privoxy picks up where Junkbuster left off. All the old features remain. The -new Privoxy still blocks ads and banners, still manages cookies, and still -helps protect your privacy. But, most of these features have been enhanced, and -many new ones have been added, all in the same vein. + 3.18. Can I just set Privoxy to use port 80 and thus avoid + individual browser configuration? -Privoxy's new features include: + 3.19. Can Privoxy run as a "transparent" proxy? - * Can be run as an "intercepting" proxy, which obviates the need to configure - browsers individually. + 3.20. Can Privoxy run as a "intercepting" proxy? - * Sophisticated actions and filters for manipulating both server and client - headers. + 3.21. How can I configure Privoxy for use with Outlook + Express? - * Can be chained with other proxies. + 3.22. How can I have separate rules just for HTML mail? - * Integrated browser based configuration and control utility at http:// - config.privoxy.org/ (shortcut: http://p.p/). Browser-based tracing of rule - and filter effects. Remote toggling. + 3.23. I sometimes notice cookies sneaking through. How? - * Web page filtering (text replacements, removes banners based on size, - invisible "web-bugs", JavaScript and HTML annoyances, pop-up windows, etc.) + 3.24. Are all cookies bad? Why? - * Modularized configuration that allows for standard settings and user - settings to reside in separate files, so that installing updated actions - files won't overwrite individual user settings. + 3.25. How can I allow permanent cookies for my trusted sites? - * Support for Perl Compatible Regular Expressions in the configuration files, - and a more sophisticated and flexible configuration syntax. + 3.26. Can I have separate configurations for different users? - * Improved cookie management features (e.g. session based cookies). + 3.27. Can I set-up Privoxy as a whitelist of "good" sites? - * GIF de-animation. + 3.28. How can I turn off ad-blocking? - * Bypass many click-tracking scripts (avoids script redirection). + 3.29. How can I have custom template pages, like the BLOCKED + page? - * Multi-threaded (POSIX and native threads). + 3.30. How can I remove the "Go There Anyway" link from the + BLOCKED page? - * User-customizable HTML templates for all proxy-generated pages (e.g. - "blocked" page). + 4. Miscellaneous - * Auto-detection and re-reading of config file changes. + 4.1. How much does Privoxy slow my browsing down? This has to + add extra time to browsing. - * Improved signal handling, and a true daemon mode (Unix). + 4.2. I notice considerable delays in page requests. What's + wrong? - * Every feature now controllable on a per-site or per-location basis, - configuration more powerful and versatile over-all. + 4.3. What are "http://config.privoxy.org/" and "http://p.p/"? - * Many smaller new features added, limitations and bugs removed, and security - holes fixed. + 4.4. How can I submit new ads, or report problems? -------------------------------------------------------------------------------- + 4.5. If I do submit missed ads, will they be included in + future updates? -1.8. How does Privoxy know what is an ad, and what is not? + 4.6. Why doesn't anyone answer my support request? -Privoxy's approach to blocking ads is twofold: + 4.7. How can I hide my IP address? -First, there are certain patterns in the locations (URLs) of banner images. -This applies to both the path (you wouldn't guess how many web sites serve -their banners from a directory called "banners"!) and the host (blocking the -big banner hosting services like doublecklick.net already helps a lot). Privoxy -takes advantage of this fact by using URL patterns to sort out and block the -requests for things that sound like they would be ads or banners. + 4.8. Can Privoxy guarantee I am anonymous? -Second, banners tend to come in certain sizes. But you can't tell the size of -an image by its URL without downloading it, and if you do, it's too late to -save bandwidth. Therefore, Privoxy also inspects the HTML sources of web pages -while they are loaded, and replaces references to images with standard banner -sizes by dummy references, so that your browser doesn't request them anymore in -the first place. + 4.9. A test site says I am not using a Proxy. -Both of this involves a certain amount of guesswork and is, of course, freely -and readily configurable. + 4.10. How do I use Privoxy together with Tor? -------------------------------------------------------------------------------- + 4.11. Might some things break because header information or + content is being altered? -1.9. Can Privoxy make mistakes? This does not sound very scientific. + 4.12. Can Privoxy act as a "caching" proxy to speed up web + browsing? -Actually, it's a black art ;-) And yes, it is always possible to have a broad -rule accidentally block or change something by mistake. You will almost surely -run into such situations at some point. It is tricky writing rules to cover -every conceivable possibility, and not occasionally get false positives. + 4.13. What about as a firewall? Can Privoxy protect me? -But this should not be a big concern since the Privoxy configuration is very -flexible, and includes tools to help identify these types of situations so they -can be addressed as needed, allowing you to customize your installation. (See -the Troubleshooting section below.) + 4.14. I have large empty spaces / a checkerboard pattern now + where ads used to be. Why? -------------------------------------------------------------------------------- + 4.15. How can Privoxy filter Secure (HTTPS) URLs? -1.10. Will I have to configure Privoxy before I can use it? + 4.16. Privoxy runs as a "server". How secure is it? Do I need + to take any special precautions? -That depends on your expectations. The default installation should give you a -good starting point, and block most ads and unwanted content, but many of the -more advanced features are off by default, and require you to activate them. + 4.17. Can I temporarily disable Privoxy? -You do have to set up your browser to use Privoxy (see the Installation section -below). + 4.18. When "disabled" is Privoxy totally out of the picture? -And you will certainly run into situations where there are false positives, or -ads not being blocked that you may not want to see. In these cases, you would -certainly benefit by customizing Privoxy's configuration to more closely match -your individual situation. And we encourage you to do this. This is where the -real power of Privoxy lies! + 4.19. How can I tell Privoxy to totally ignore certain sites? -------------------------------------------------------------------------------- + 4.20. My logs show Privoxy "crunches" ads, but also its own + internal CGI pages. What is a "crunch"? -1.11. Can Privoxy run as a server on a network? + 4.21. Can Privoxy effect files that I download from a + webserver? FTP server? -Yes, Privoxy runs as a server already, and can easily be configured to "serve" -more than one client. See How can I set up Privoxy to act as a proxy for my LAN -below. + 4.22. I just downloaded a Perl script, and Privoxy altered + it! Yikes, what is wrong! -------------------------------------------------------------------------------- + 4.23. Should I continue to use a "HOSTS" file for + ad-blocking? -1.12. My browser does the same things as Privoxy. Why should I use Privoxy at -all? + 4.24. Where can I find more information about Privoxy and + related issues? -Modern browsers do indeed have some of the same functionality as Privoxy. Maybe -this is adequate for you. But Privoxy is very versatile and powerful, and can -probably do a number of things your browser just can't. + 4.25. I've noticed that Privoxy changes "Microsoft" to + "MicroSuck"! Why are you manipulating my browsing? -In addition, a proxy is good choice if you use multiple browsers, or have a LAN -with multiple computers since Privoxy can run as a server application. This way -all the configuration is in one place, and you don't have to maintain a similar -configuration for possibly many browsers or users. + 4.26. Does Privoxy produce "valid" HTML (or XHTML)? -Note, however, that it's recommended to leverage both your browser's and -Privoxy's privacy enhancing features at the same time. While your browser -probably lacks some features Privoxy offers, it should also be able to do some -things more reliable, for example restricting and suppressing JavaScript. + 5. Troubleshooting -------------------------------------------------------------------------------- + 5.1. I cannot connect to any websites. Or, I am getting + "connection refused" message with every web page. Why? -1.13. Why should I trust Privoxy? + 5.2. Why am I getting a 503 Error (WSAECONNREFUSED) on every + page? -The most important reason is because you have access to everything, and you can -control everything. You can check every line of every configuration file -yourself. You can check every last bit of source code should you desire. And -even if you can't read code, there should be some comfort in knowing that other -people can, and do read it. You can build the software from scratch, if you -want, so that you know the executable is clean, and that it is yours. In fact, -we encourage this level of scrutiny. It is one reason we use Privoxy ourselves. + 5.3. I just added a new rule, but the steenkin ad is still + getting through. How? -------------------------------------------------------------------------------- + 5.4. One of my favorite sites does not work with Privoxy. + What can I do? -1.14. Is there is a license or fee? What about a warranty? Registration? + 5.5. After installing Privoxy, I have to log in every time I + start IE. What gives? -Privoxy is free software and licensed under the GNU General Public License -(GPL) version 2. It is free to use, copy, modify or distribute as you wish -under the terms of this license. Please see the Copyright section for more -information on the license and copyright. Or the LICENSE file that should be -included. + 5.6. I cannot connect to any FTP sites. Privoxy is blocking + me. -There is no warranty of any kind, expressed, implied or otherwise. That is -something that would cost real money ;-) There is no registration either. + 5.7. In Mac OSX, I can't configure Microsoft Internet + Explorer to use Privoxy as the HTTP proxy. -------------------------------------------------------------------------------- + 5.8. In Mac OSX, I dragged the Privoxy folder to the trash in + order to uninstall it. Now the finder tells me I don't have + sufficient privileges to empty the trash. -1.15. Can Privoxy remove spyware? Adware? Viruses? + 5.9. In Mac OSX Panther (10.3), images often fail to load + and/or I experience random delays in page loading. I'm using + localhost as my browser's proxy setting. -No, at least not reliably enough to trust it. Privoxy is not designed to be a -malware removal tool and the default configuration doesn't even try to filter -out any malware. + 5.10. I get a completely blank page at one site. "View + Source" shows only: <html><body></body></html>. Without + Privoxy the page loads fine. -Privoxy could help prevent contact from (known) sites that use such tactics -with appropriate configuration rules, and thus could conceivably prevent -contamination from such sites. However, keeping such a configuration up to date -would require a lot of time and effort that would be better spend on keeping -your software itself up to date so it doesn't have known vulnerabilities. + 5.11. My logs show many "Unable to get my own hostname" + lines. Why? -------------------------------------------------------------------------------- + 5.12. When I try to launch Privoxy, I get an error message + "port 8118 is already in use" (or similar wording). Why? -1.16. Can I use Privoxy with other ad-blocking software? + 5.13. Pages with UTF-8 fonts are garbled. -Privoxy should work fine with other proxies and other software in general. + 5.14. Why are binary files (such as images) corrupted when + Privoxy is used? -But it is probably not necessary to use Privoxy in conjunction with other -ad-blocking products, and this could conceivably cause undesirable results. It -might be better to choose one software or the other and work a little to tweak -its configuration to your liking. + 5.15. What is the "demoronizer" and why is it there? -Note that this is an advice specific to ad blocking. + 5.16. Why do I keep seeing "PrivoxyWindowOpen()" in raw + source code? -------------------------------------------------------------------------------- + 5.17. I am getting too many DNS errors like "404 No Such + Domain". Why can't Privoxy do this better? -1.17. I would like to help you, what can I do? + 5.18. At one site Privoxy just hangs, and starts taking all + CPU. Why is this? -1.17.1. Would you like to participate? + 5.19. I just installed Privoxy, and all my browsing has + slowed to a crawl. What gives? -Well, we always need help. There is something for everybody who wants to help -us. We welcome new developers, packagers, testers, documentation writers or -really anyone with a desire to help in any way. You DO NOT need to be a -"programmer". There are many other tasks available. In fact, the programmers -often can't spend as much time programming because of some of the other, more -mundane things that need to be done, like checking the Tracker feedback -sections. + 5.20. Why do my filters work on some sites but not on others? -So first thing, get an account on SourceForge.net and mail your id to the -developers mailing list. Then, please read the Developer's Manual, at least the -pertinent sections. + 6. Contacting the developers, Bug Reporting and Feature Requests -You can also start helping out without SourceForge.net account, simply by -showing up on the mailing list, helping out other users, providing general -feedback or reporting problems you noticed. + 6.1. Get Support -------------------------------------------------------------------------------- + 6.2. Reporting Problems -1.17.2. Contribute! + 6.2.1. Reporting Ads or Other Configuration + Problems -We, of course, welcome donations and could use money for domain registering, -buying software to test Privoxy with, and, of course, for regular world-wide -get-togethers (hahaha). If you enjoy the software and feel like helping us with -a donation, just drop us a note and get your name on the list of contributors. + 6.2.2. Reporting Bugs -------------------------------------------------------------------------------- + 6.3. Request New Features -1.17.3. Software + 6.4. Other -If you are a vendor of a web-related software like a browser, web server or -proxy, and would like us to ensure that Privoxy runs smoothly with your -product, you might consider supplying us with a copy or license. We can't, -however, guarantee that we will fix all potential compatibility issues as a -result. + 7. Privoxy Copyright, License and History -------------------------------------------------------------------------------- + 7.1. License -2. Installation + 7.2. History -2.1. Which browsers are supported by Privoxy? +1. General Information -Any browser that can be configured to use a proxy, which should be virtually -all browsers, including Firefox, Internet Explorer, Opera, and Safari among -others. Direct browser support is not an absolute requirement since Privoxy -runs as a separate application and talks to the browser in the standardized -HTTP protocol, just like a web server does. + 1.1. Who should give Privoxy a try? -------------------------------------------------------------------------------- + Anyone who is interested in security, privacy, or in finer-grained control + over their web and Internet experience. -2.2. Which operating systems are supported? + -------------------------------------------------------------------------- -At present, Privoxy is known to run on Windows(95, 98, ME, 2000, XP, Vista), -GNU/Linux (RedHat, SuSE, Debian, Fedora, Gentoo, Slackware and others), Mac -OSX, OS/2, AmigaOS, FreeBSD, NetBSD, OpenBSD, Solaris, and various other -flavors of Unix. + 1.2. Is Privoxy the best choice for me? -But any operating system that runs TCP/IP, can conceivably take advantage of -Privoxy in a networked situation where Privoxy would run as a server on a LAN -gateway. Then only the "gateway" needs to be running one of the above operating -systems. + Privoxy is certainly a good choice, especially for those who want more + control and security. Those with the willingness to read the documentation + and the ability to fine-tune their installation will benefit the most. -Source code is freely available, so porting to other operating systems is -always a possibility. + One of Privoxy's strengths is that it is highly configurable giving you + the ability to completely personalize your installation. Being familiar + with, or at least having an interest in learning about HTTP and other + networking protocols, HTML, and "Regular Expressions" will be a big plus + and will help you get the most out of Privoxy. A new installation just + includes a very basic configuration. The user should take this as a + starting point only, and enhance it as he or she sees fit. In fact, the + user is encouraged, and expected to, fine-tune the configuration. -------------------------------------------------------------------------------- + Much of Privoxy's configuration can be done with a Web browser. But there + are areas where configuration is done using a text editor to edit + configuration files. Also note that the web-based action editor doesn't + use authentication and should only be enabled in environments where all + clients with access to Privoxy listening port can be trusted. -2.3. Can I use Privoxy with my email client? + -------------------------------------------------------------------------- -As long as there is some way to set a HTTP proxy for the client, then yes, any -application can be used, whether it is strictly speaking a "browser" or not. -Though this may not be the best approach for dealing with some of the common -abuses of HTML in email. See How can I configure Privoxy with Outlook Express? -below for more on this. + 1.3. What is a "proxy"? How does Privoxy work? -Be aware that HTML email presents a number of unique security and privacy -related issues, that can require advanced skills to overcome. The developers -recommend using email clients that can be configured to convert HTML to plain -text for these reasons. + A web proxy is a service, based on a software such as Privoxy, that + clients (i.e. browsers) can use instead of connecting directly to web + servers on the Internet. The clients then ask the proxy to fetch the + objects they need (web pages, images, movies etc) on their behalf, and + when the proxy has done so, it hands the results back to the client. It is + a "go-between". See the Wikipedia proxy definition for more. -------------------------------------------------------------------------------- + There are many reasons to use web proxies, such as security (firewalling), + efficiency (caching) and others, and there are any number of proxies to + accommodate those needs. -2.4. I just installed Privoxy. Is there anything special I have to do now? + Privoxy is a proxy that is primarily focused on privacy protection, ad and + junk elimination and freeing the user from restrictions placed on his + activities. Sitting between your browser(s) and the Internet, it is in a + perfect position to filter outbound personal information that your browser + is leaking, as well as inbound junk. It uses a variety of techniques to do + this, all of which are under your complete control via the various + configuration files and options. Being a proxy also makes it easier to + share configurations among multiple browsers and/or users. -All browsers should be told to use Privoxy as a proxy by specifying the correct -proxy address and port number in the appropriate configuration area for the -browser. It's possible to combine Privoxy with a packet filter to intercept -HTTP requests even if the client isn't explicitly configured to use Privoxy, -but where possible, configuring the client is recommended. See the User Manual -for more details. You should also flush your browser's memory and disk cache to -get rid of any cached junk items, and remove any stored cookies. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 1.4. Does Privoxy do anything more than ad blocking? -2.5. What is the proxy address of Privoxy? + Yes, ad blocking is but one possible use. There are many, many ways + Privoxy can be used to sanitize and customize web browsing. -If you set up the Privoxy to run on the computer you browse from (rather than -your ISP's server or some networked computer on a LAN), the proxy will be on -127.0.0.1 (sometimes referred to as "localhost", which is the special name used -by every computer on the Internet to refer to itself) and the port will be 8118 -(unless you used the listen-address config option to tell Privoxy to run on a -different port). + -------------------------------------------------------------------------- -When configuring your browser's proxy settings you typically enter the word -"localhost" or the IP address "127.0.0.1" in the boxes next to "HTTP" and -"Secure" (HTTPS) and then the number "8118" for "port". This tells your browser -to send all web requests to Privoxy instead of directly to the Internet. + 1.5. What is this new version of "Junkbuster"? -Privoxy can also be used to proxy for a Local Area Network. In this case, your -would enter either the IP address of the LAN host where Privoxy is running, or -the equivalent hostname, e.g. 192.168.1.1. Port assignment would be same as -above. Note that Privoxy doesn't listen on any LAN interfaces by default. + A long time ago, there was the Internet Junkbuster, by Anonymous Coders + and Junkbusters Corporation. This saved many users a lot of pain in the + early days of web advertising and user tracking. -Privoxy does not currently handle any other protocols such as FTP, SMTP, IM, -IRC, ICQ, etc. + But the web, its protocols and standards, and with it, the techniques for + forcing ads on users, give up autonomy over their browsing, and for + tracking them, keeps evolving. Unfortunately, the Internet Junkbuster did + not. Version 2.0.2, published in 1998, was (and is) the last official + release available from Junkbusters Corporation. Fortunately, it had been + released under the GNU GPL, which allowed further development by others. -------------------------------------------------------------------------------- + So Stefan Waldherr started maintaining an improved version of the + software, to which eventually a number of people contributed patches. It + could already replace banners with a transparent image, and had a first + version of pop-up killing, but it was still very closely based on the + original, with all its limitations, such as the lack of HTTP/1.1 support, + flexible per-site configuration, or content modification. The last release + from this effort was version 2.0.2-10, published in 2000. -2.6. I just installed Privoxy, and nothing is happening. All the ads are there. -What's wrong? + Then, some developers picked up the thread, and started turning the + software inside out, upside down, and then reassembled it, adding many new + features along the way. -Did you configure your browser to use Privoxy as a proxy? It does not sound -like it. See above. You might also try flushing the browser's caches to force a -full re-reading of pages. You can verify that Privoxy is running, and your -browser is correctly configured by entering the special URL: http://p.p/. This -should take you to a page titled "This is Privoxy.." with access to Privoxy's -internal configuration. If you see this, then you are good to go. If you -receive a page saying "Privoxy is not running", then the browser is not set up -to use your Privoxy installation. If you receive anything else (probably -nothing at all), it could either be that the browser is not set up correctly, -or that Privoxy is not running at all. Check the log file. For instructions on -starting Privoxy and browser configuration, see the chapter on starting Privoxy -in the User Manual. + The result of this is Privoxy, whose first stable version, 3.0, was + released August, 2002. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -2.7. I get a "Privoxy is not being used" dummy page although Privoxy is running -and being used. + 1.6. Why "Privoxy"? Why change the name from Junkbuster at all? -First, make sure that Privoxy is really running and being used by visiting -http://p.p/. You should see the Privoxy main page. If not, see the chapter on -starting Privoxy in the User Manual. + Though outdated, Junkbusters Corporation continues to offer their original + version of the Internet Junkbuster, so publishing our Junkbuster-derived + software under the same name led to confusion. -Now if http://p.p/ works for you, but other parts of Privoxy's web interface -show the dummy page, your browser has cached a redirection it encountered -before Privoxy was being used. You need to clear your browser's cache. Note -that shift-reloading the dummy page won't help, since that'll only refresh the -dummy page, not the redirection that lead you there. + There are also potential legal complications from our use of the + Junkbuster name, which is a registered trademark of Junkbusters + Corporation. There are, however, no objections from Junkbusters + Corporation to the Privoxy project itself, and they, in fact, still share + our ideals and goals. -The procedure for clearing the cache varies from browser to browser. For -example, Mozilla/Netscape users would click Edit --> Preferences --> Advanced ---> Cache and then click both "Clear Memory Cache" and "Clear Disk Cache". In -some Firefox versions it's Tools --> Options --> Privacy --> Cache and then -click "Clear Cache Now". + The developers also believed that there are so many improvements over the + original code, that it was time to make a clean break from the past and + make a name in their own right. -------------------------------------------------------------------------------- + Privoxy is the "Privacy Enhancing Proxy". Also, its content modification + and junk suppression gives you, the user, more control, more freedom, and + allows you to browse your personal and "private edition" of the web. -3. Configuration + -------------------------------------------------------------------------- -3.1. What exactly is an "actions" file? + 1.7. How does Privoxy differ from the old Junkbuster? -Privoxy utilizes the concept of " actions" that are used to manipulate and -control web page data. Actions files are where these actions that Privoxy could -take while processing a certain request, are configured. Typically, you would -define a set of default actions that apply globally to all URLs, then add -exceptions to these defaults where needed. There is a wide array of actions -available that give the user a high degree of control and flexibility on how to -process each and every web page. + Privoxy picks up where Junkbuster left off. All the old features remain. + The new Privoxy still blocks ads and banners, still manages cookies, and + still helps protect your privacy. But, most of these features have been + enhanced, and many new ones have been added, all in the same vein. -Actions can be defined on a URL pattern basis, i.e. for single URLs, whole web -sites, groups or parts thereof etc. Actions can also be grouped together and -then applied to requests matching one or more patterns. There are many possible -actions that might apply to any given site. As an example, if you are blocking -cookies as one of your default actions, but need to accept cookies from a given -site, you would need to define an exception for this site in one of your -actions files, preferably in user.action. + Privoxy's new features include: -------------------------------------------------------------------------------- + * Can be run as an "intercepting" proxy, which obviates the need to + configure browsers individually. -3.2. The "actions" concept confuses me. Please list some of these "actions". + * Sophisticated actions and filters for manipulating both server and + client headers. -For a comprehensive discussion of the actions concept, please refer to the -actions file chapter in the User Manual. It includes a list of all actions and -an actions file tutorial to get you started. + * Can be chained with other proxies. -------------------------------------------------------------------------------- + * Integrated browser based configuration and control utility at + http://config.privoxy.org/ (shortcut: http://p.p/). Browser-based + tracing of rule and filter effects. Remote toggling. -3.3. How are actions files configured? What is the easiest way to do this? + * Web page filtering (text replacements, removes banners based on size, + invisible "web-bugs", JavaScript and HTML annoyances, pop-up windows, + etc.) -Actions files are just text files in a special syntax and can be edited with a -text editor. But probably the easiest way is to access Privoxy's user interface -with your web browser at http://config.privoxy.org/ (Shortcut: http://p.p/) and -then select "View & change the current configuration" from the menu. Note that -this feature must be explicitly enabled in the main config file (see -enable-edit-actions). + * Modularized configuration that allows for standard settings and user + settings to reside in separate files, so that installing updated + actions files won't overwrite individual user settings. -------------------------------------------------------------------------------- + * Support for Perl Compatible Regular Expressions in the configuration + files, and a more sophisticated and flexible configuration syntax. -3.4. There are several different "actions" files. What are the differences? + * Improved cookie management features (e.g. session based cookies). -Three actions files are being included by the developers, to be used for -different purposes: These are default.action, the "main" actions file which is -actively maintained by the Privoxy developers and typically sets the default -policies, user.action, where users are encouraged to make their private -customizations, and standard.action, which is for internal Privoxy use only. -Please see the actions chapter in the User Manual for a more detailed -explanation. + * GIF de-animation. -Earlier versions included three different versions of the default.action file. -The new scheme allows for greater flexibility of local configuration, and for -browser based selection of pre-defined "aggressiveness" levels. + * Bypass many click-tracking scripts (avoids script redirection). -------------------------------------------------------------------------------- + * Multi-threaded (POSIX and native threads). -3.5. Where can I get updated Actions Files? + * User-customizable HTML templates for all proxy-generated pages (e.g. + "blocked" page). -Based on your feedback and the continuing development, updates of -default.action will be made available from time to time on the files section of -our project page. + * Auto-detection and re-reading of config file changes. -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. + * Improved signal handling, and a true daemon mode (Unix). -------------------------------------------------------------------------------- + * Every feature now controllable on a per-site or per-location basis, + configuration more powerful and versatile over-all. -3.6. Can I use my old config files? + * Many smaller new features added, limitations and bugs removed, and + security holes fixed. -The syntax and purpose of configuration files has remained roughly the same -throughout the 3.x series, but backwards compatibility is not guaranteed. Also -each release contains updated, "improved" versions and it is therefore strongly -recommended to install the newer configuration files and merge back your -modifications. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 1.8. How does Privoxy know what is an ad, and what is not? -3.7. Why is the configuration so complicated? + Privoxy's approach to blocking ads is twofold: -"Complicated" is in the eye of the beholder. Those that are familiar with some -of the underlying concepts, such as regular expression syntax, take to it like -a fish takes to water. Also, software that tries hard to be "user friendly", -often lacks sophistication and flexibility. There is always that trade-off -there between power vs. easy-of-use. Furthermore, anyone is welcome to -contribute ideas and implementations to enhance Privoxy. + First, there are certain patterns in the locations (URLs) of banner + images. This applies to both the path (you wouldn't guess how many web + sites serve their banners from a directory called "banners"!) and the host + (blocking the big banner hosting services like doublecklick.net already + helps a lot). Privoxy takes advantage of this fact by using URL patterns + to sort out and block the requests for things that sound like they would + be ads or banners. -------------------------------------------------------------------------------- + Second, banners tend to come in certain sizes. But you can't tell the size + of an image by its URL without downloading it, and if you do, it's too + late to save bandwidth. Therefore, Privoxy also inspects the HTML sources + of web pages while they are loaded, and replaces references to images with + standard banner sizes by dummy references, so that your browser doesn't + request them anymore in the first place. -3.8. How can I make my Yahoo/Hotmail/Gmail account work? + Both of this involves a certain amount of guesswork and is, of course, + freely and readily configurable. -The default configuration shouldn't impact the usability of any of these -services. It may, however, make all cookies temporary, so that your browser -will forget your login credentials in between browser sessions. If you would -like not to have to log in manually each time you access those websites, simply -turn off all cookie handling for them in the user.action file. An example for -yahoo might look like: + -------------------------------------------------------------------------- -# Allow all cookies for Yahoo login: -# -{ -crunch-incoming-cookies -crunch-outgoing-cookies -session-cookies-only } -.login.yahoo.com + 1.9. Can Privoxy make mistakes? This does not sound very scientific. + Actually, it's a black art ;-) And yes, it is always possible to have a + broad rule accidentally block or change something by mistake. You will + almost surely run into such situations at some point. It is tricky writing + rules to cover every conceivable possibility, and not occasionally get + false positives. -These kinds of sites are often quite complex and heavy with Javascript and thus -"fragile". So if still a problem, we have an alias just for such sticky -situations: + But this should not be a big concern since the Privoxy configuration is + very flexible, and includes tools to help identify these types of + situations so they can be addressed as needed, allowing you to customize + your installation. (See the Troubleshooting section below.) -# Gmail is a _fragile_ site: -# -{ fragile } - # Gmail is ... - mail.google.com + -------------------------------------------------------------------------- + 1.10. Will I have to configure Privoxy before I can use it? -Be sure to flush your browser's caches whenever making these kinds of changes, -just to make sure the changes "take". + That depends on your expectations. The default installation should give + you a good starting point, and block most ads and unwanted content, but + many of the more advanced features are off by default, and require you to + activate them. -Make sure the domain, host and path are appropriate as well. Your browser can -tell you where you are specifically and you should use that information for -your configuration settings. Note that above it is not referenced as gmail.com, -which is a valid domain name. + You do have to set up your browser to use Privoxy (see the Installation + section below). -------------------------------------------------------------------------------- + And you will certainly run into situations where there are false + positives, or ads not being blocked that you may not want to see. In these + cases, you would certainly benefit by customizing Privoxy's configuration + to more closely match your individual situation. And we encourage you to + do this. This is where the real power of Privoxy lies! -3.9. What's the difference between the "Cautious", "Medium" and "Advanced" -defaults? + -------------------------------------------------------------------------- -Configuring Privoxy is not entirely trivial. To help you get started, we -provide you with three different default action "profiles" in the web based -actions file editor at http://config.privoxy.org/show-status. See the User -Manual for a list of actions, and how the default profiles are set. + 1.11. Can Privoxy run as a server on a network? -Where the defaults are likely to break some sites, exceptions for known popular -"problem" sites are included, but in general, the more aggressive your default -settings are, the more exceptions you will have to make later. New users are -best to start off in "Cautious" setting. This is safest and will have the -fewest problems. See the User Manual for a more detailed discussion. + Yes, Privoxy runs as a server already, and can easily be configured to + "serve" more than one client. See How can I set up Privoxy to act as a + proxy for my LAN below. -It should be noted that the "Advanced" profile (formerly known as the -"Adventuresome" profile) is more aggressive, and will make use of some of -Privoxy's advanced features. Use at your own risk! + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 1.12. My browser does the same things as Privoxy. Why should I use Privoxy + at all? -3.10. Why can I change the configuration with a browser? Does that not raise -security issues? + Modern browsers do indeed have some of the same functionality as Privoxy. + Maybe this is adequate for you. But Privoxy is very versatile and + powerful, and can probably do a number of things your browser just can't. -It may seem strange that regular users can edit the config files with their -browsers, although the whole /etc/privoxy hierarchy belongs to the user -"privoxy", with only 644 permissions. + In addition, a proxy is good choice if you use multiple browsers, or have + a LAN with multiple computers since Privoxy can run as a server + application. This way all the configuration is in one place, and you don't + have to maintain a similar configuration for possibly many browsers or + users. -When you use the browser-based editor, Privoxy itself is writing to the config -files. Because Privoxy is running as the user "privoxy", it can update its own -config files. + Note, however, that it's recommended to leverage both your browser's and + Privoxy's privacy enhancing features at the same time. While your browser + probably lacks some features Privoxy offers, it should also be able to do + some things more reliable, for example restricting and suppressing + JavaScript. -If you run Privoxy for multiple untrusted users (e.g. in a LAN) or aren't -entirely in control of your own browser, you will probably want to make sure -that the the web-based editor and remote toggle features are "off" by setting " -enable-edit-actions 0" and "enable-remote-toggle 0" in the main configuration -file. + -------------------------------------------------------------------------- -As of Privoxy 3.0.7 these options are disabled by default. + 1.13. Why should I trust Privoxy? + + The most important reason is because you have access to everything, and + you can control everything. You can check every line of every + configuration file yourself. You can check every last bit of source code + should you desire. And even if you can't read code, there should be some + comfort in knowing that other people can, and do read it. You can build + the software from scratch, if you want, so that you know the executable is + clean, and that it is yours. In fact, we encourage this level of scrutiny. + It is one reason we use Privoxy ourselves. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- + + 1.14. Is there is a license or fee? What about a warranty? Registration? -3.11. What is the default.filter file? What is a "filter"? + Privoxy is free software and licensed under the GNU General Public License + (GPL) version 2. It is free to use, copy, modify or distribute as you wish + under the terms of this license. Please see the Copyright section for more + information on the license and copyright. Or the LICENSE file that should + be included. -The default.filter file is where filters as supplied by the developers are -defined. Filters are a special subset of actions that can be used to modify or -remove web page content or headers on the fly. Content filters can be applied -to anything in the page source, header filters can be applied to either server -or client headers. Regular expressions are used to accomplish this. + There is no warranty of any kind, expressed, implied or otherwise. That is + something that would cost real money ;-) There is no registration either. -There are a number of pre-defined filters to deal with common annoyances. The -filters are only defined here, to invoke them, you need to use the filter -action in one of the actions files. Content filtering is automatically disabled -for inappropriate MIME types, but if you now better than Privoxy what should or -should not be filtered you can filter any content you like. + -------------------------------------------------------------------------- -Filters should not be confused with blocks, which is a completely different -action, and is more typically used to block ads and unwanted sites. + 1.15. Can Privoxy remove spyware? Adware? Viruses? -If you are familiar with regular expressions, and HTML, you can look at the -provided default.filter with a text editor and define your own filters. This is -potentially a very powerful feature, but requires some expertise in both -regular expressions and HTML/HTTP. You should place any modifications to the -default filters, or any new ones you create in a separate file, such as -user.filter, so they won't be overwritten during upgrades. The ability to -define multiple filter files in config is a new feature as of v. 3.0.5. + No, at least not reliably enough to trust it. Privoxy is not designed to + be a malware removal tool and the default configuration doesn't even try + to filter out any malware. -There is no GUI editor option for this part of the configuration, but you can -disable/enable the various pre-defined filters of the included default.filter -file with the web-based actions file editor. Note that the custom actions -editor must be explicitly enabled in the main config file (see -enable-edit-actions). + Privoxy could help prevent contact from (known) sites that use such + tactics with appropriate configuration rules, and thus could conceivably + prevent contamination from such sites. However, keeping such a + configuration up to date would require a lot of time and effort that would + be better spend on keeping your software itself up to date so it doesn't + have known vulnerabilities. -If you intend to develop your own filters, you might want to have a look at -Privoxy-Filter-Test. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 1.16. Can I use Privoxy with other ad-blocking software? -3.12. How can I set up Privoxy to act as a proxy for my LAN? + Privoxy should work fine with other proxies and other software in general. -By default, Privoxy only responds to requests from 127.0.0.1 (localhost). To -have it act as a server for a network, this needs to be changed in the main -configuration file. Look for the listen-address option, which may be commented -out with a "#" symbol. Make sure it is uncommented, and assign it the address -of the LAN gateway interface, and port number to use. Assuming your LAN address -is 192.168.1.1 and you wish to run Privoxy on port 8118, this line should look -like: + But it is probably not necessary to use Privoxy in conjunction with other + ad-blocking products, and this could conceivably cause undesirable + results. It might be better to choose one software or the other and work a + little to tweak its configuration to your liking. - listen-address 192.168.1.1:8118 + Note that this is an advice specific to ad blocking. + -------------------------------------------------------------------------- -Save the file, and restart Privoxy. Configure all browsers on the network then -to use this address and port number. + 1.17. I would like to help you, what can I do? -Alternately, you can have Privoxy listen on all available interfaces: + 1.17.1. Would you like to participate? - listen-address :8118 + Well, we always need help. There is something for everybody who wants to + help us. We welcome new developers, packagers, testers, documentation + writers or really anyone with a desire to help in any way. You DO NOT need + to be a "programmer". There are many other tasks available. In fact, the + programmers often can't spend as much time programming because of some of + the other, more mundane things that need to be done, like checking the + Tracker feedback sections. + So first thing, get an account on SourceForge.net and mail your id to the + developers mailing list. Then, please read the Developer's Manual, at + least the pertinent sections. -And then use Privoxy's permit-access feature to limit connections. A firewall -in this situation is recommended as well. + You can also start helping out without SourceForge.net account, simply by + showing up on the mailing list, helping out other users, providing general + feedback or reporting problems you noticed. -The above steps should be the same for any TCP network, regardless of operating -system. + -------------------------------------------------------------------------- -If you run Privoxy on a LAN with untrusted users, we recommend that you -double-check the access control and security options! + 1.17.2. Contribute! -------------------------------------------------------------------------------- + We, of course, welcome donations and could use money for domain + registering, buying software to test Privoxy with, and, of course, for + regular world-wide get-togethers (hahaha). If you enjoy the software and + feel like helping us with a donation, just drop us a note and get your + name on the list of contributors. -3.13. Instead of ads, now I get a checkerboard pattern. I don't want to see -anything. + -------------------------------------------------------------------------- -The replacement for blocked images can be controlled with the set-image-blocker -action. You have the choice of a checkerboard pattern, a transparent 1x1 GIF -image (aka "blank"), or a redirect to a custom image of your choice. Note that -this choice only has effect for images which are blocked as images, i.e. whose -URLs match both a handle-as-image and block action. + 1.17.3. Software -If you want to see nothing, then change the set-image-blocker action to -"blank". This can be done by editing the user.action file, or through the -web-based actions file editor. + If you are a vendor of a web-related software like a browser, web server + or proxy, and would like us to ensure that Privoxy runs smoothly with your + product, you might consider supplying us with a copy or license. We can't, + however, guarantee that we will fix all potential compatibility issues as + a result. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -3.14. Why would anybody want to see a checkerboard pattern? +2. Installation -Remember that telling which image is an ad and which isn't, is an educated -guess. While we hope that the standard configuration is rather smart, it will -make occasional mistakes. The checkerboard image is visually decent, and it -shows you where images have been blocked, which can be very helpful in case -some navigation aid or otherwise innocent image was erroneously blocked. It is -recommended for new users so they can "see" what is happening. Some people -might also enjoy seeing how many banners they don't have to see. + 2.1. Which browsers are supported by Privoxy? -------------------------------------------------------------------------------- + Any browser that can be configured to use a proxy, which should be + virtually all browsers, including Firefox, Internet Explorer, Opera, and + Safari among others. Direct browser support is not an absolute requirement + since Privoxy runs as a separate application and talks to the browser in + the standardized HTTP protocol, just like a web server does. -3.15. I see some images being replaced with text instead of the checkerboard -image. Why and how do I get rid of this? + -------------------------------------------------------------------------- -This happens when the banners are not embedded in the HTML code of the page -itself, but in separate HTML (sub)documents that are loaded into (i)frames or -(i)layers, and these external HTML documents are blocked. Being non-images they -get replaced by a substitute HTML page rather than a substitute image, which -wouldn't work out technically, since the browser expects and accepts only HTML -when it has requested an HTML document. + 2.2. Which operating systems are supported? -The substitute page adapts to the available space and shows itself as a -miniature two-liner if loaded into small frames, or full-blown with a large red -"BLOCKED" banner if space allows. + At present, Privoxy is known to run on Windows(95, 98, ME, 2000, XP, + Vista), GNU/Linux (RedHat, SuSE, Debian, Fedora, Gentoo, Slackware and + others), Mac OSX, OS/2, AmigaOS, FreeBSD, NetBSD, OpenBSD, Solaris, and + various other flavors of Unix. -If you prefer the banners to be blocked by images, you must see to it that the -HTML documents in which they are embedded are not blocked. Clicking the "See -why" link offered in the substitute page will show you which rule blocked the -page. After changing the rule and un-blocking the HTML documents, the browser -will try to load the actual banner images and the usual image blocking will -(hopefully!) kick in. + But any operating system that runs TCP/IP, can conceivably take advantage + of Privoxy in a networked situation where Privoxy would run as a server on + a LAN gateway. Then only the "gateway" needs to be running one of the + above operating systems. -------------------------------------------------------------------------------- + Source code is freely available, so porting to other operating systems is + always a possibility. -3.16. Can Privoxy run as a service on Win2K/NT/XP? + -------------------------------------------------------------------------- -Yes. Version 3.0.5 introduces full Windows service functionality. See the User -Manual for details on how to install and configure Privoxy as a service. + 2.3. Can I use Privoxy with my email client? -Earlier 3.x versions could run as a system service using srvany.exe. See the -discussion at http://sourceforge.net/tracker/?func=detail&atid=361118&aid= -485617&group_id=11118, for details, and a sample configuration. + As long as there is some way to set a HTTP proxy for the client, then yes, + any application can be used, whether it is strictly speaking a "browser" + or not. Though this may not be the best approach for dealing with some of + the common abuses of HTML in email. See How can I configure Privoxy with + Outlook Express? below for more on this. -------------------------------------------------------------------------------- + Be aware that HTML email presents a number of unique security and privacy + related issues, that can require advanced skills to overcome. The + developers recommend using email clients that can be configured to convert + HTML to plain text for these reasons. -3.17. How can I make Privoxy work with other proxies like Squid or Tor? + -------------------------------------------------------------------------- -This can be done and is often useful to combine the benefits of Privoxy with -those of a another proxy. See the forwarding chapter in the User Manual which -describes how to do this, and the How do I use Privoxy together with Tor -section below. + 2.4. I just installed Privoxy. Is there anything special I have to do now? -------------------------------------------------------------------------------- + All browsers should be told to use Privoxy as a proxy by specifying the + correct proxy address and port number in the appropriate configuration + area for the browser. It's possible to combine Privoxy with a packet + filter to intercept HTTP requests even if the client isn't explicitly + configured to use Privoxy, but where possible, configuring the client is + recommended. See the User Manual for more details. You should also flush + your browser's memory and disk cache to get rid of any cached junk items, + and remove any stored cookies. -3.18. Can I just set Privoxy to use port 80 and thus avoid individual browser -configuration? + -------------------------------------------------------------------------- -No, its more complicated than that. This only works with special kinds of -proxies known as "intercepting" proxies (see below). + 2.5. What is the proxy address of Privoxy? -------------------------------------------------------------------------------- + If you set up the Privoxy to run on the computer you browse from (rather + than your ISP's server or some networked computer on a LAN), the proxy + will be on 127.0.0.1 (sometimes referred to as "localhost", which is the + special name used by every computer on the Internet to refer to itself) + and the port will be 8118 (unless you used the listen-address config + option to tell Privoxy to run on a different port). -3.19. Can Privoxy run as a "transparent" proxy? + When configuring your browser's proxy settings you typically enter the + word "localhost" or the IP address "127.0.0.1" in the boxes next to "HTTP" + and "Secure" (HTTPS) and then the number "8118" for "port". This tells + your browser to send all web requests to Privoxy instead of directly to + the Internet. -The whole idea of Privoxy is to modify client requests and server responses in -all sorts of ways and therefore it's not a transparent proxy as described in -RFC 2616. + Privoxy can also be used to proxy for a Local Area Network. In this case, + your would enter either the IP address of the LAN host where Privoxy is + running, or the equivalent hostname, e.g. 192.168.1.1. Port assignment + would be same as above. Note that Privoxy doesn't listen on any LAN + interfaces by default. -However, some people say "transparent proxy" when they mean "intercepting -proxy". If you are one of them, please read the next entry. + Privoxy does not currently handle any other protocols such as FTP, SMTP, + IM, IRC, ICQ, etc. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -3.20. Can Privoxy run as a "intercepting" proxy? + 2.6. I just installed Privoxy, and nothing is happening. All the ads are + there. What's wrong? + + Did you configure your browser to use Privoxy as a proxy? It does not + sound like it. See above. You might also try flushing the browser's caches + to force a full re-reading of pages. You can verify that Privoxy is + running, and your browser is correctly configured by entering the special + URL: http://p.p/. This should take you to a page titled "This is + Privoxy.." with access to Privoxy's internal configuration. If you see + this, then you are good to go. If you receive a page saying "Privoxy is + not running", then the browser is not set up to use your Privoxy + installation. If you receive anything else (probably nothing at all), it + could either be that the browser is not set up correctly, or that Privoxy + is not running at all. Check the log file. For instructions on starting + Privoxy and browser configuration, see the chapter on starting Privoxy in + the User Manual. + + -------------------------------------------------------------------------- -Privoxy can't intercept traffic itself, but it can handle requests that where -intercepted and redirected with a packet filter (like PF or iptables), as long -as the Host header is present. + 2.7. I get a "Privoxy is not being used" dummy page although Privoxy is + running and being used. -As the Host header is required by HTTP/1.1 and as most web sites rely on it -anyway, this limitation shouldn't be a problem. + First, make sure that Privoxy is really running and being used by visiting + http://p.p/. You should see the Privoxy main page. If not, see the chapter + on starting Privoxy in the User Manual. -Please refer to your packet filter's documentation to learn how to intercept -and redirect traffic into Privoxy. Afterward you just have to configure Privoxy -to accept intercepted requests. + Now if http://p.p/ works for you, but other parts of Privoxy's web + interface show the dummy page, your browser has cached a redirection it + encountered before Privoxy was being used. You need to clear your + browser's cache. Note that shift-reloading the dummy page won't help, + since that'll only refresh the dummy page, not the redirection that lead + you there. -------------------------------------------------------------------------------- + The procedure for clearing the cache varies from browser to browser. For + example, Mozilla/Netscape users would click Edit --> Preferences --> + Advanced --> Cache and then click both "Clear Memory Cache" and "Clear + Disk Cache". In some Firefox versions it's Tools --> Options --> Privacy + --> Cache and then click "Clear Cache Now". -3.21. How can I configure Privoxy for use with Outlook Express? + -------------------------------------------------------------------------- -Outlook Express uses Internet Explorer components to both render HTML, and -fetch any HTTP requests that may be embedded in an HTML email. So however you -have Privoxy configured to work with IE, this configuration should -automatically be shared. +3. Configuration -------------------------------------------------------------------------------- + 3.1. What exactly is an "actions" file? -3.22. How can I have separate rules just for HTML mail? + Privoxy utilizes the concept of " actions" that are used to manipulate and + control web page data. Actions files are where these actions that Privoxy + could take while processing a certain request, are configured. Typically, + you would define a set of default actions that apply globally to all URLs, + then add exceptions to these defaults where needed. There is a wide array + of actions available that give the user a high degree of control and + flexibility on how to process each and every web page. -The short answer is, you can't. Privoxy has no way of knowing which particular -application makes a request, so there is no way to distinguish between web -pages and HTML mail. Privoxy just blindly proxies all requests. In the case of -Outlook Express (see above), OE uses IE anyway, and there is no way for Privoxy -to ever be able to distinguish between them (nor could any other proxy type -application for that matter). + Actions can be defined on a URL pattern basis, i.e. for single URLs, whole + web sites, groups or parts thereof etc. Actions can also be grouped + together and then applied to requests matching one or more patterns. There + are many possible actions that might apply to any given site. As an + example, if you are blocking cookies as one of your default actions, but + need to accept cookies from a given site, you would need to define an + exception for this site in one of your actions files, preferably in + user.action. -For a good discussion of some of the issues involved (including privacy and -security issues), see http://sourceforge.net/tracker/?func=detail&atid=211118& -aid=629518&group_id=11118. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 3.2. The "actions" concept confuses me. Please list some of these "actions". -3.23. I sometimes notice cookies sneaking through. How? + For a comprehensive discussion of the actions concept, please refer to the + actions file chapter in the User Manual. It includes a list of all actions + and an actions file tutorial to get you started. -Cookies can be set in several ways. The classic method is via the Set-Cookie -HTTP header. This is straightforward, and an easy one to manipulate, such as -the Privoxy concept of session-cookies-only. There is also the possibility of -using Javascript to set cookies (Privoxy calls these content-cookies). This is -trickier because the syntax can vary widely, and thus requires a certain amount -of guesswork. It is not realistic to catch all of these short of disabling -Javascript, which would break many sites. And lastly, if the cookies are -embedded in a HTTPS/SSL secure session via Javascript, they are beyond -Privoxy's reach. + -------------------------------------------------------------------------- -All in all, Privoxy can help manage cookies in general, can help minimize the -loss of privacy posed by cookies, but can't realistically stop all cookies. + 3.3. How are actions files configured? What is the easiest way to do this? -------------------------------------------------------------------------------- + Actions files are just text files in a special syntax and can be edited + with a text editor. But probably the easiest way is to access Privoxy's + user interface with your web browser at http://config.privoxy.org/ + (Shortcut: http://p.p/) and then select "View & change the current + configuration" from the menu. Note that this feature must be explicitly + enabled in the main config file (see enable-edit-actions). -3.24. Are all cookies bad? Why? + -------------------------------------------------------------------------- -No, in fact there are many beneficial uses of cookies. Cookies are just a -method that browsers can use to store data between pages, or between browser -sessions. Sometimes there is a good reason for this, and the user's life is a -bit easier as a result. But there is a long history of some websites taking -advantage of this layer of trust, and using the data they glean from you and -your browsing habits for their own purposes, and maybe to your potential -detriment. Such sites are using you and storing their data on your system. That -is why the privacy conscious watch from whom those cookies come, and why they -really need to be there. + 3.4. There are several different "actions" files. What are the differences? -See the Wikipedia cookie definition for more. + Three actions files are being included by the developers, to be used for + different purposes: These are default.action, the "main" actions file + which is actively maintained by the Privoxy developers and typically sets + the default policies, user.action, where users are encouraged to make + their private customizations, and standard.action, which is for internal + Privoxy use only. Please see the actions chapter in the User Manual for a + more detailed explanation. -------------------------------------------------------------------------------- + Earlier versions included three different versions of the default.action + file. The new scheme allows for greater flexibility of local + configuration, and for browser based selection of pre-defined + "aggressiveness" levels. -3.25. How can I allow permanent cookies for my trusted sites? + -------------------------------------------------------------------------- -There are several actions that relate to cookies. The default behavior is to -allow only "session cookies", which means the cookies only last for the current -browser session. This eliminates most kinds of abuse related to cookies. But -there may be cases where you want cookies to last. + 3.5. Where can I get updated Actions Files? -To disable all cookie actions, so that cookies are allowed unrestricted, both -in and out, for example.com: + Based on your feedback and the continuing development, updates of + default.action will be made available from time to time on the files + section of our project page. - { -crunch-incoming-cookies -crunch-outgoing-cookies -session-cookies-only -filter{content-cookies} } - .example.com + 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. + -------------------------------------------------------------------------- -Place the above in user.action. Note that some of these may be off by default -anyway, so this might be redundant, but there is no harm being explicit in what -you want to happen. user.action includes an alias for this situation, called -allow-all-cookies. + 3.6. Can I use my old config files? -------------------------------------------------------------------------------- + The syntax and purpose of configuration files has remained roughly the + same throughout the 3.x series, but backwards compatibility is not + guaranteed. Also each release contains updated, "improved" versions and it + is therefore strongly recommended to install the newer configuration files + and merge back your modifications. -3.26. Can I have separate configurations for different users? + -------------------------------------------------------------------------- -Each instance of Privoxy has its own configuration, including such attributes -as the TCP port that it listens on. What you can do is run multiple instances -of Privoxy, each with a unique listen-address configuration setting, and -configuration path, and then each of these can have their own configurations. -Think of it as per-port configuration. + 3.7. Why is the configuration so complicated? -Simple enough for a few users, but for large installations, consider having -groups of users that might share like configurations. + "Complicated" is in the eye of the beholder. Those that are familiar with + some of the underlying concepts, such as regular expression syntax, take + to it like a fish takes to water. Also, software that tries hard to be + "user friendly", often lacks sophistication and flexibility. There is + always that trade-off there between power vs. easy-of-use. Furthermore, + anyone is welcome to contribute ideas and implementations to enhance + Privoxy. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -3.27. Can I set-up Privoxy as a whitelist of "good" sites? + 3.8. How can I make my Yahoo/Hotmail/Gmail account work? -Sure. There are a couple of things you can do for simple white-listing. Here's -one real easy one: + The default configuration shouldn't impact the usability of any of these + services. It may, however, make all cookies temporary, so that your + browser will forget your login credentials in between browser sessions. If + you would like not to have to log in manually each time you access those + websites, simply turn off all cookie handling for them in the user.action + file. An example for yahoo might look like: - ############################################################ - # Blacklist - ############################################################ - { +block } - / # Block *all* URLs + # Allow all cookies for Yahoo login: + # + { -crunch-incoming-cookies -crunch-outgoing-cookies -session-cookies-only } + .login.yahoo.com - ############################################################ - # Whitelist - ############################################################ - { -block } - kids.example.com - toys.example.com - games.example.com + These kinds of sites are often quite complex and heavy with Javascript and + thus "fragile". So if still a problem, we have an alias just for such + sticky situations: + # Gmail is a _fragile_ site: + # + { fragile } + # Gmail is ... + mail.google.com -This allows access to only those three sites by first blocking all URLs, and -then subsequently allowing three specific exceptions. + Be sure to flush your browser's caches whenever making these kinds of + changes, just to make sure the changes "take". -Another approach is Privoxy's trustfile concept, which incorporates the notion -of "trusted referrers". See the Trust documentation for details. + Make sure the domain, host and path are appropriate as well. Your browser + can tell you where you are specifically and you should use that + information for your configuration settings. Note that above it is not + referenced as gmail.com, which is a valid domain name. -These are fairly simple approaches and are not completely foolproof. There are -various other configuration options that should be disabled (described -elsewhere here and in the User Manual) so that users can't modify their own -configuration and easily circumvent the whitelist. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 3.9. What's the difference between the "Cautious", "Medium" and "Advanced" + defaults? -3.28. How can I turn off ad-blocking? + Configuring Privoxy is not entirely trivial. To help you get started, we + provide you with three different default action "profiles" in the web + based actions file editor at http://config.privoxy.org/show-status. See + the User Manual for a list of actions, and how the default profiles are + set. -Ad blocking is achieved through a complex application of various Privoxy -actions. These actions are deployed against simple images, banners, flash -animations, text pages, JavaScript, pop-ups and pop-unders, etc., so its not as -simple as just turning one or two actions off. The various actions that make up -Privoxy ad blocking are hard-coded into the default configuration files. It has -been assumed that everyone using Privoxy is interested in this particular -feature. + Where the defaults are likely to break some sites, exceptions for known + popular "problem" sites are included, but in general, the more aggressive + your default settings are, the more exceptions you will have to make + later. New users are best to start off in "Cautious" setting. This is + safest and will have the fewest problems. See the User Manual for a more + detailed discussion. -If you want to do without this, there are several approaches you can take: You -can manually undo the many block rules in default.action. Or even easier, just -create your own default.action file from scratch without the many ad blocking -rules, and corresponding exceptions. Or lastly, if you are not concerned about -the additional blocks that are done for privacy reasons, you can very easily -over-ride all blocking with the following very simple rule in your user.action: + It should be noted that the "Advanced" profile (formerly known as the + "Adventuresome" profile) is more aggressive, and will make use of some of + Privoxy's advanced features. Use at your own risk! - # Unblock everybody, everywhere - { -block } - / # UN-Block *all* URLs + -------------------------------------------------------------------------- + 3.10. Why can I change the configuration with a browser? Does that not raise + security issues? -Or even a more comprehensive reversing of various ad related actions: + It may seem strange that regular users can edit the config files with + their browsers, although the whole /etc/privoxy hierarchy belongs to the + user "privoxy", with only 644 permissions. - # Unblock everybody, everywhere, and turn off appropriate filtering, etc - { -block \ - -filter{banners-by-size} \ - -filter{banners-by-link} \ - allow-popups \ - } - / # UN-Block *all* URLs and allow ads + When you use the browser-based editor, Privoxy itself is writing to the + config files. Because Privoxy is running as the user "privoxy", it can + update its own config files. + If you run Privoxy for multiple untrusted users (e.g. in a LAN) or aren't + entirely in control of your own browser, you will probably want to make + sure that the the web-based editor and remote toggle features are "off" by + setting "enable-edit-actions 0" and "enable-remote-toggle 0" in the main + configuration file. -This last "action" in this compound statement, allow-popups, is an alias that -disables various pop-up blocking features. + As of Privoxy 3.0.7 these options are disabled by default. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -3.29. How can I have custom template pages, like the BLOCKED page? + 3.11. What is the default.filter file? What is a "filter"? -Privoxy "templates" are specialized text files utilized by Privoxy for various -purposes and can easily be modified using any text editor. All the template -pages are installed in a sub-directory appropriately named: templates. Knowing -something about HTML syntax will of course be helpful. + The default.filter file is where filters as supplied by the developers are + defined. Filters are a special subset of actions that can be used to + modify or remove web page content or headers on the fly. Content filters + can be applied to anything in the page source, header filters can be + applied to either server or client headers. Regular expressions are used + to accomplish this. + + There are a number of pre-defined filters to deal with common annoyances. + The filters are only defined here, to invoke them, you need to use the + filter action in one of the actions files. Content filtering is + automatically disabled for inappropriate MIME types, but if you now better + than Privoxy what should or should not be filtered you can filter any + content you like. + + Filters should not be confused with blocks, which is a completely + different action, and is more typically used to block ads and unwanted + sites. + + If you are familiar with regular expressions, and HTML, you can look at + the provided default.filter with a text editor and define your own + filters. This is potentially a very powerful feature, but requires some + expertise in both regular expressions and HTML/HTTP. You should place any + modifications to the default filters, or any new ones you create in a + separate file, such as user.filter, so they won't be overwritten during + upgrades. The ability to define multiple filter files in config is a new + feature as of v. 3.0.5. + + There is no GUI editor option for this part of the configuration, but you + can disable/enable the various pre-defined filters of the included + default.filter file with the web-based actions file editor. Note that the + custom actions editor must be explicitly enabled in the main config file + (see enable-edit-actions). + + If you intend to develop your own filters, you might want to have a look + at Privoxy-Filter-Test. + + -------------------------------------------------------------------------- -Be forewarned that the default templates are subject to being overwritten -during upgrades. You can, however, create completely new templates, place them -in another directory and specify the alternate path in the main config. For -details, have a look at the templdir option. + 3.12. How can I set up Privoxy to act as a proxy for my LAN? -------------------------------------------------------------------------------- + By default, Privoxy only responds to requests from 127.0.0.1 (localhost). + To have it act as a server for a network, this needs to be changed in the + main configuration file. Look for the listen-address option, which may be + commented out with a "#" symbol. Make sure it is uncommented, and assign + it the address of the LAN gateway interface, and port number to use. + Assuming your LAN address is 192.168.1.1 and you wish to run Privoxy on + port 8118, this line should look like: -3.30. How can I remove the "Go There Anyway" link from the BLOCKED page? + listen-address 192.168.1.1:8118 -There is more than one way to do it (although Perl is not involved). + Save the file, and restart Privoxy. Configure all browsers on the network + then to use this address and port number. -Editing the BLOCKED template page (see above) may dissuade some users, but this -method is easily circumvented. Where you need this level of control, you might -want to build Privoxy from source, and disable various features that are -available as compile-time options. You should configure the sources as follows: + Alternately, you can have Privoxy listen on all available interfaces: - ./configure --disable-toggle --disable-editor --disable-force + listen-address :8118 + And then use Privoxy's permit-access feature to limit connections. A + firewall in this situation is recommended as well. -This will create an executable with hard-coded security features so that -Privoxy does not allow easy bypassing of blocked sites, or changing the current -configuration via any connected user's web browser. + The above steps should be the same for any TCP network, regardless of + operating system. -Finally, all of these features can also be toggled on/off via options in -Privoxy's main config file which means you don't have to recompile anything. + If you run Privoxy on a LAN with untrusted users, we recommend that you + double-check the access control and security options! -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -4. Miscellaneous + 3.13. Instead of ads, now I get a checkerboard pattern. I don't want to see + anything. + + The replacement for blocked images can be controlled with the + set-image-blocker action. You have the choice of a checkerboard pattern, a + transparent 1x1 GIF image (aka "blank"), or a redirect to a custom image + of your choice. Note that this choice only has effect for images which are + blocked as images, i.e. whose URLs match both a handle-as-image and block + action. + + If you want to see nothing, then change the set-image-blocker action to + "blank". This can be done by editing the user.action file, or through the + web-based actions file editor. + + -------------------------------------------------------------------------- + + 3.14. Why would anybody want to see a checkerboard pattern? + + Remember that telling which image is an ad and which isn't, is an educated + guess. While we hope that the standard configuration is rather smart, it + will make occasional mistakes. The checkerboard image is visually decent, + and it shows you where images have been blocked, which can be very helpful + in case some navigation aid or otherwise innocent image was erroneously + blocked. It is recommended for new users so they can "see" what is + happening. Some people might also enjoy seeing how many banners they don't + have to see. + + -------------------------------------------------------------------------- + + 3.15. I see some images being replaced with text instead of the checkerboard + image. Why and how do I get rid of this? + + This happens when the banners are not embedded in the HTML code of the + page itself, but in separate HTML (sub)documents that are loaded into + (i)frames or (i)layers, and these external HTML documents are blocked. + Being non-images they get replaced by a substitute HTML page rather than a + substitute image, which wouldn't work out technically, since the browser + expects and accepts only HTML when it has requested an HTML document. + + The substitute page adapts to the available space and shows itself as a + miniature two-liner if loaded into small frames, or full-blown with a + large red "BLOCKED" banner if space allows. + + If you prefer the banners to be blocked by images, you must see to it that + the HTML documents in which they are embedded are not blocked. Clicking + the "See why" link offered in the substitute page will show you which rule + blocked the page. After changing the rule and un-blocking the HTML + documents, the browser will try to load the actual banner images and the + usual image blocking will (hopefully!) kick in. + + -------------------------------------------------------------------------- + + 3.16. Can Privoxy run as a service on Win2K/NT/XP? + + Yes. Version 3.0.5 introduces full Windows service functionality. See the + User Manual for details on how to install and configure Privoxy as a + service. + + Earlier 3.x versions could run as a system service using srvany.exe. See + the discussion at + http://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118, + for details, and a sample configuration. + + -------------------------------------------------------------------------- + + 3.17. How can I make Privoxy work with other proxies like Squid or Tor? + + This can be done and is often useful to combine the benefits of Privoxy + with those of a another proxy. See the forwarding chapter in the User + Manual which describes how to do this, and the How do I use Privoxy + together with Tor section below. + + -------------------------------------------------------------------------- + + 3.18. Can I just set Privoxy to use port 80 and thus avoid individual + browser configuration? + + No, its more complicated than that. This only works with special kinds of + proxies known as "intercepting" proxies (see below). + + -------------------------------------------------------------------------- + + 3.19. Can Privoxy run as a "transparent" proxy? + + The whole idea of Privoxy is to modify client requests and server + responses in all sorts of ways and therefore it's not a transparent proxy + as described in RFC 2616. + + However, some people say "transparent proxy" when they mean "intercepting + proxy". If you are one of them, please read the next entry. + + -------------------------------------------------------------------------- + + 3.20. Can Privoxy run as a "intercepting" proxy? + + Privoxy can't intercept traffic itself, but it can handle requests that + where intercepted and redirected with a packet filter (like PF or + iptables), as long as the Host header is present. + + As the Host header is required by HTTP/1.1 and as most web sites rely on + it anyway, this limitation shouldn't be a problem. + + Please refer to your packet filter's documentation to learn how to + intercept and redirect traffic into Privoxy. Afterward you just have to + configure Privoxy to accept intercepted requests. + + -------------------------------------------------------------------------- -4.1. How much does Privoxy slow my browsing down? This has to add extra time to -browsing. + 3.21. How can I configure Privoxy for use with Outlook Express? -How much of an impact depends on many things, including the CPU of the host -system, how aggressive the configuration is, which specific actions are being -triggered, the size of the page, the bandwidth of the connection, etc. + Outlook Express uses Internet Explorer components to both render HTML, and + fetch any HTTP requests that may be embedded in an HTML email. So however + you have Privoxy configured to work with IE, this configuration should + automatically be shared. -Overall, it should not slow you down any in real terms, and may actually help -speed things up since ads, banners and other junk are not typically being -retrieved and displayed. The actual processing time required by Privoxy itself -for each page, is relatively small in the overall scheme of things, and happens -very quickly. This is typically more than offset by time saved not downloading -and rendering ad images and other junk content (if ad blocking is being used). + -------------------------------------------------------------------------- -"Filtering" content via the filter or deanimate-gifs actions may cause a -perceived slowdown, since the entire document needs to be buffered before -displaying. And on very large documents, filtering may have some measurable -impact. How much depends on the page size, the actual definition of the filter -(s), etc. See below. Most other actions have little to no impact on speed. + 3.22. How can I have separate rules just for HTML mail? -Also, when filtering is enabled but zlib support isn't available, compression -is often disabled (see prevent-compression). This can have an impact on speed -as well, although it's probably smaller than you might think. Again, the page -size, etc. will determine how much of an impact. + The short answer is, you can't. Privoxy has no way of knowing which + particular application makes a request, so there is no way to distinguish + between web pages and HTML mail. Privoxy just blindly proxies all + requests. In the case of Outlook Express (see above), OE uses IE anyway, + and there is no way for Privoxy to ever be able to distinguish between + them (nor could any other proxy type application for that matter). -------------------------------------------------------------------------------- + For a good discussion of some of the issues involved (including privacy + and security issues), see + http://sourceforge.net/tracker/?func=detail&atid=211118&aid=629518&group_id=11118. -4.2. I notice considerable delays in page requests. What's wrong? + -------------------------------------------------------------------------- -If you use any filter action, such as filtering banners by size, web-bugs etc, -or the deanimate-gifs action, the entire document must be loaded into memory in -order for the filtering mechanism to work, and nothing is sent to the browser -during this time. + 3.23. I sometimes notice cookies sneaking through. How? -The loading time typically does not really change much in real numbers, but the -feeling is different, because most browsers are able to start rendering -incomplete content, giving the user a feeling of "it works". This effect is -more noticeable on slower dialup connections. Extremely large documents may -have some impact on the time to load the page where there is filtering being -done. But overall, the difference should be very minimal. If there is a big -impact, then probably some other situation is contributing (like anti-virus -software). + Cookies can be set in several ways. The classic method is via the + Set-Cookie HTTP header. This is straightforward, and an easy one to + manipulate, such as the Privoxy concept of session-cookies-only. There is + also the possibility of using Javascript to set cookies (Privoxy calls + these content-cookies). This is trickier because the syntax can vary + widely, and thus requires a certain amount of guesswork. It is not + realistic to catch all of these short of disabling Javascript, which would + break many sites. And lastly, if the cookies are embedded in a HTTPS/SSL + secure session via Javascript, they are beyond Privoxy's reach. -Filtering is automatically disabled for inappropriate MIME types. But note that -if the web server mis-reports the MIME type, then content that should not be -filtered, could be. Privoxy only knows how to differentiate filterable content -because of the MIME type as reported by the server, or because of some -configuration setting that enables/disables filtering. + All in all, Privoxy can help manage cookies in general, can help minimize + the loss of privacy posed by cookies, but can't realistically stop all + cookies. -------------------------------------------------------------------------------- - -4.3. What are "http://config.privoxy.org/" and "http://p.p/"? - -http://config.privoxy.org/ is the address of Privoxy's built-in user interface, -and http://p.p/ is a shortcut for it. + -------------------------------------------------------------------------- -Since Privoxy sits between your web browser and the Internet, it can simply -intercept requests for these addresses and answer them with its built-in "web -server". + 3.24. Are all cookies bad? Why? -This also makes for a good test for your browser configuration: If entering the -URL http://config.privoxy.org/ takes you to a page saying "This is Privoxy -...", everything is OK. If you get a page saying "Privoxy is not working" -instead, then your browser didn't use Privoxy for the request, hence it could -not be intercepted, and you have accessed the real web site at -config.privoxy.org. + No, in fact there are many beneficial uses of cookies. Cookies are just a + method that browsers can use to store data between pages, or between + browser sessions. Sometimes there is a good reason for this, and the + user's life is a bit easier as a result. But there is a long history of + some websites taking advantage of this layer of trust, and using the data + they glean from you and your browsing habits for their own purposes, and + maybe to your potential detriment. Such sites are using you and storing + their data on your system. That is why the privacy conscious watch from + whom those cookies come, and why they really need to be there. -------------------------------------------------------------------------------- + See the Wikipedia cookie definition for more. -4.4. How can I submit new ads, or report problems? + -------------------------------------------------------------------------- -Please see the Contact section for various ways to interact with the -developers. + 3.25. How can I allow permanent cookies for my trusted sites? -------------------------------------------------------------------------------- + There are several actions that relate to cookies. The default behavior is + to allow only "session cookies", which means the cookies only last for the + current browser session. This eliminates most kinds of abuse related to + cookies. But there may be cases where you want cookies to last. -4.5. If I do submit missed ads, will they be included in future updates? + To disable all cookie actions, so that cookies are allowed unrestricted, + both in and out, for example.com: -Whether such submissions are eventually included in the default.action -configuration file depends on how significant the issue is. We of course want -to address any potential problem with major, high-profile sites such as Google, -Yahoo, etc. Any site with global or regional reach, has a good chance of being -a candidate. But at the other end of the spectrum are any number of smaller, -low-profile sites such as for local clubs or schools. Since their reach and -impact are much less, they are best handled by inclusion in the user's -user.action, and thus would be unlikely to be included. + { -crunch-incoming-cookies -crunch-outgoing-cookies -session-cookies-only -filter{content-cookies} } + .example.com -------------------------------------------------------------------------------- + Place the above in user.action. Note that some of these may be off by + default anyway, so this might be redundant, but there is no harm being + explicit in what you want to happen. user.action includes an alias for + this situation, called allow-all-cookies. -4.6. Why doesn't anyone answer my support request? + -------------------------------------------------------------------------- -Rest assured that it has been read and considered. Why it is not answered, -could be for various reasons, including no one has a good answer for it, no one -has had time to yet investigate it thoroughly, it has been reported numerous -times already, or because not enough information was provided to help us help -you. Your efforts are not wasted, and we do appreciate them. + 3.26. Can I have separate configurations for different users? -------------------------------------------------------------------------------- + Each instance of Privoxy has its own configuration, including such + attributes as the TCP port that it listens on. What you can do is run + multiple instances of Privoxy, each with a unique listen-address + configuration setting, and configuration path, and then each of these can + have their own configurations. Think of it as per-port configuration. -4.7. How can I hide my IP address? + Simple enough for a few users, but for large installations, consider + having groups of users that might share like configurations. -If you run both the browser and Privoxy locally, you cannot hide your IP -address with Privoxy or ultimately any other software alone. The server needs -to know your IP address so that it knows where to send the responses back. + -------------------------------------------------------------------------- -There are many publicly usable "anonymous" proxies out there, which provide a -further level of indirection between you and the web server. + 3.27. Can I set-up Privoxy as a whitelist of "good" sites? -However, these proxies are called "anonymous" because you don't need to -authenticate, not because they would offer any real anonymity. Most of them -will log your IP address and make it available to the authorities in case you -violate the law of the country they run in. In fact you can't even rule out -that some of them only exist to *collect* information on (those suspicious) -people with a more than average preference for privacy. + Sure. There are a couple of things you can do for simple white-listing. + Here's one real easy one: -If you want to hide your IP address from most adversaries, you should consider -chaining Privoxy with Tor. The configuration details can be found in How do I -use Privoxy together with Tor section just below. + ############################################################ + # Blacklist + ############################################################ + { +block } + / # Block *all* URLs -------------------------------------------------------------------------------- + ############################################################ + # Whitelist + ############################################################ + { -block } + kids.example.com + toys.example.com + games.example.com -4.8. Can Privoxy guarantee I am anonymous? + This allows access to only those three sites by first blocking all URLs, + and then subsequently allowing three specific exceptions. -No. Your chances of remaining anonymous are improved, but unless you chain -Privoxy with Tor or a similar proxy and know what you're doing when it comes to -configuring the rest of your system, you should assume that everything you do -on the Web can be traced back to you. + Another approach is Privoxy's trustfile concept, which incorporates the + notion of "trusted referrers". See the Trust documentation for details. -Privoxy can remove various information about you, and allows you more freedom -to decide which sites you can trust, and what details you want to reveal. But -it neither hides your IP address, nor can it guarantee that the rest of the -system behaves correctly. There are several possibilities how a web sites can -find out who you are, even if you are using a strict Privoxy configuration and -chained it with Tor. + These are fairly simple approaches and are not completely foolproof. There + are various other configuration options that should be disabled (described + elsewhere here and in the User Manual) so that users can't modify their + own configuration and easily circumvent the whitelist. -Most of Privoxy's privacy-enhancing features can be easily subverted by an -insecure browser configuration, therefore you should use a browser that can be -configured to only execute code from trusted sites, and be careful which sites -you trust. For example there is no point in having Privoxy modify the -User-Agent header, if websites can get all the information they want through -JavaScript, ActiveX, Flash, Java etc. + -------------------------------------------------------------------------- -A few browsers disclose the user's email address in certain situations, such as -when transferring a file by FTP. Privoxy does not filter FTP. If you need this -feature, or are concerned about the mail handler of your browser disclosing -your email address, you might consider products such as NSClean. + 3.28. How can I turn off ad-blocking? -Browsers available only as binaries could use non-standard headers to give out -any information they can have access to: see the manufacturer's license -agreement. It's impossible to anticipate and prevent every breach of privacy -that might occur. The professionally paranoid prefer browsers available as -source code, because anticipating their behavior is easier. Trust the source, -Luke! + Ad blocking is achieved through a complex application of various Privoxy + actions. These actions are deployed against simple images, banners, flash + animations, text pages, JavaScript, pop-ups and pop-unders, etc., so its + not as simple as just turning one or two actions off. The various actions + that make up Privoxy ad blocking are hard-coded into the default + configuration files. It has been assumed that everyone using Privoxy is + interested in this particular feature. + + If you want to do without this, there are several approaches you can take: + You can manually undo the many block rules in default.action. Or even + easier, just create your own default.action file from scratch without the + many ad blocking rules, and corresponding exceptions. Or lastly, if you + are not concerned about the additional blocks that are done for privacy + reasons, you can very easily over-ride all blocking with the following + very simple rule in your user.action: + + # Unblock everybody, everywhere + { -block } + / # UN-Block *all* URLs + + Or even a more comprehensive reversing of various ad related actions: + + # Unblock everybody, everywhere, and turn off appropriate filtering, etc + { -block \ + -filter{banners-by-size} \ + -filter{banners-by-link} \ + allow-popups \ + } + / # UN-Block *all* URLs and allow ads + + This last "action" in this compound statement, allow-popups, is an alias + that disables various pop-up blocking features. + + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 3.29. How can I have custom template pages, like the BLOCKED page? -4.9. A test site says I am not using a Proxy. + Privoxy "templates" are specialized text files utilized by Privoxy for + various purposes and can easily be modified using any text editor. All the + template pages are installed in a sub-directory appropriately named: + templates. Knowing something about HTML syntax will of course be helpful. -Good! Actually, they are probably testing for some other kinds of proxies. -Hiding yourself completely would require additional steps. + Be forewarned that the default templates are subject to being overwritten + during upgrades. You can, however, create completely new templates, place + them in another directory and specify the alternate path in the main + config. For details, have a look at the templdir option. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -4.10. How do I use Privoxy together with Tor? + 3.30. How can I remove the "Go There Anyway" link from the BLOCKED page? -Before you configure Privoxy to use Tor, please follow the User Manual chapters -2. Installation and 5. Startup to make sure Privoxy itself is setup correctly. + There is more than one way to do it (although Perl is not involved). -If it is, refer to Tor's extensive documentation to learn how to install Tor, -and make sure Tor's logfile says that "Tor has successfully opened a circuit" -and it "looks like client functionality is working". + Editing the BLOCKED template page (see above) may dissuade some users, but + this method is easily circumvented. Where you need this level of control, + you might want to build Privoxy from source, and disable various features + that are available as compile-time options. You should configure the + sources as follows: -If either Tor or Privoxy isn't working, their combination most likely will -neither. Testing them on their own will also help you to direct problem reports -to the right audience. If Privoxy isn't working, don't bother the Tor -developers. If Tor isn't working, don't send bug reports to the Privoxy Team. + ./configure --disable-toggle --disable-editor --disable-force -If you verified that Privoxy and Tor are working, it is time to connect them. -As far as Privoxy is concerned, Tor is just another proxy that can be reached -by socks4 or socks4a. Most likely you are interested in Tor to increase your -anonymity level, therefore you should use socks4a, to make sure DNS requests -are done through Tor and thus invisible to your local network. + This will create an executable with hard-coded security features so that + Privoxy does not allow easy bypassing of blocked sites, or changing the + current configuration via any connected user's web browser. -Since Privoxy 3.0.5, its main configuration file is already prepared for Tor, -if you are using a default Tor configuration and run it on the same system as -Privoxy, you just have to edit the forwarding section and uncomment the line: + Finally, all of these features can also be toggled on/off via options in + Privoxy's main config file which means you don't have to recompile + anything. -# forward-socks4a / 127.0.0.1:9050 . + -------------------------------------------------------------------------- +4. Miscellaneous + 4.1. How much does Privoxy slow my browsing down? This has to add extra time + to browsing. -This is enough to reach the Internet, but additionally you might want to -uncomment the following forward rules, to make sure your local network is still -reachable through Privoxy: + How much of an impact depends on many things, including the CPU of the + host system, how aggressive the configuration is, which specific actions + are being triggered, the size of the page, the bandwidth of the + connection, etc. -# forward 192.168.*.*/ . -# forward 10.*.*.*/ . -# forward 127.*.*.*/ . + Overall, it should not slow you down any in real terms, and may actually + help speed things up since ads, banners and other junk are not typically + being retrieved and displayed. The actual processing time required by + Privoxy itself for each page, is relatively small in the overall scheme of + things, and happens very quickly. This is typically more than offset by + time saved not downloading and rendering ad images and other junk content + (if ad blocking is being used). + "Filtering" content via the filter or deanimate-gifs actions may cause a + perceived slowdown, since the entire document needs to be buffered before + displaying. And on very large documents, filtering may have some + measurable impact. How much depends on the page size, the actual + definition of the filter(s), etc. See below. Most other actions have + little to no impact on speed. + Also, when filtering is enabled but zlib support isn't available, + compression is often disabled (see prevent-compression). This can have an + impact on speed as well, although it's probably smaller than you might + think. Again, the page size, etc. will determine how much of an impact. -Unencrypted connections to systems in these address ranges will be as (un) -secure as the local network is, but the alternative is that your browser can't -reach the network at all. Then again, that may actually be desired and if you -don't know for sure that your browser has to be able to reach the local -network, there's no reason to allow it. + -------------------------------------------------------------------------- -If you want your browser to be able to reach servers in your local network by -using their names, you will need additional exceptions that look like this: + 4.2. I notice considerable delays in page requests. What's wrong? -# forward localhost/ . + If you use any filter action, such as filtering banners by size, web-bugs + etc, or the deanimate-gifs action, the entire document must be loaded into + memory in order for the filtering mechanism to work, and nothing is sent + to the browser during this time. + The loading time typically does not really change much in real numbers, + but the feeling is different, because most browsers are able to start + rendering incomplete content, giving the user a feeling of "it works". + This effect is more noticeable on slower dialup connections. Extremely + large documents may have some impact on the time to load the page where + there is filtering being done. But overall, the difference should be very + minimal. If there is a big impact, then probably some other situation is + contributing (like anti-virus software). + Filtering is automatically disabled for inappropriate MIME types. But note + that if the web server mis-reports the MIME type, then content that should + not be filtered, could be. Privoxy only knows how to differentiate + filterable content because of the MIME type as reported by the server, or + because of some configuration setting that enables/disables filtering. -Save the modified configuration file and open http://config.privoxy.org/ -show-status/ in your browser, confirm that Privoxy has reloaded its -configuration and that there are no other forward lines, unless you know that -you need them. If everything looks good, refer to Tor Faq 4.2 to learn how to -verify that you are really using Tor. + -------------------------------------------------------------------------- -Afterward, please take the time to at least skim through the rest of Tor's -documentation. Make sure you understand what Tor does, why it is no replacement -for application level security, and why you probably don't want to use it for -unencrypted logins. + 4.3. What are "http://config.privoxy.org/" and "http://p.p/"? -------------------------------------------------------------------------------- + http://config.privoxy.org/ is the address of Privoxy's built-in user + interface, and http://p.p/ is a shortcut for it. -4.11. Might some things break because header information or content is being -altered? + Since Privoxy sits between your web browser and the Internet, it can + simply intercept requests for these addresses and answer them with its + built-in "web server". -Definitely. It is common for sites to use browser type, browser version, HTTP -header content, and various other techniques in order to dynamically decide -what to display and how to display it. What you see, and what I see, might be -very different. There are many, many ways that this can be handled, so having -hard and fast rules, is tricky. + This also makes for a good test for your browser configuration: If + entering the URL http://config.privoxy.org/ takes you to a page saying + "This is Privoxy ...", everything is OK. If you get a page saying "Privoxy + is not working" instead, then your browser didn't use Privoxy for the + request, hence it could not be intercepted, and you have accessed the real + web site at config.privoxy.org. -The "User-Agent" is sometimes used in this way to identify the browser, and -adjust content accordingly. + -------------------------------------------------------------------------- -Also, different browsers use different encodings of non-English characters, -certain web servers convert pages on-the-fly according to the User Agent -header. Giving a "User Agent" with the wrong operating system or browser -manufacturer causes some sites in these languages to be garbled; Surfers to -Eastern European sites should change it to something closer. And then some page -access counters work by looking at the "Referer" header; they may fail or break -if unavailable. The weather maps of Intellicast have been blocked by their -server when no "Referer" or cookie is provided, is another example. (But you -can forge both headers without giving information away). There are many other -ways things can go wrong when trying to fool a web server. The results of which -could inadvertently cause pages to load incorrectly, partially, or even not at -all. And there may be no obvious clues as to just what went wrong, or why. -Nowhere will there be a message that says "Turn off fast-redirects or else! " + 4.4. How can I submit new ads, or report problems? -Similar thoughts apply to modifying JavaScript, and, to a lesser degree, HTML -elements. + Please see the Contact section for various ways to interact with the + developers. -If you have problems with a site, you will have to adjust your configuration -accordingly. Cookies are probably the most likely adjustment that may be -required, but by no means the only one. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.5. If I do submit missed ads, will they be included in future updates? -4.12. Can Privoxy act as a "caching" proxy to speed up web browsing? + Whether such submissions are eventually included in the default.action + configuration file depends on how significant the issue is. We of course + want to address any potential problem with major, high-profile sites such + as Google, Yahoo, etc. Any site with global or regional reach, has a good + chance of being a candidate. But at the other end of the spectrum are any + number of smaller, low-profile sites such as for local clubs or schools. + Since their reach and impact are much less, they are best handled by + inclusion in the user's user.action, and thus would be unlikely to be + included. -No, it does not have this ability at all. You want something like Squid or -Polipo for this. And, yes, before you ask, Privoxy can co-exist with other -kinds of proxies like Squid. See the forwarding chapter in the user manual for -details. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.6. Why doesn't anyone answer my support request? -4.13. What about as a firewall? Can Privoxy protect me? + Rest assured that it has been read and considered. Why it is not answered, + could be for various reasons, including no one has a good answer for it, + no one has had time to yet investigate it thoroughly, it has been reported + numerous times already, or because not enough information was provided to + help us help you. Your efforts are not wasted, and we do appreciate them. -Not in the way you mean, or in the way some firewall vendors claim they can. -Privoxy can help protect your privacy, but can't protect your system from -intrusion attempts. It is, of course, perfectly possible to use both. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.7. How can I hide my IP address? -4.14. I have large empty spaces / a checkerboard pattern now where ads used to -be. Why? + If you run both the browser and Privoxy locally, you cannot hide your IP + address with Privoxy or ultimately any other software alone. The server + needs to know your IP address so that it knows where to send the responses + back. -It is technically possible to eliminate banners and ads in a way that frees -their allocated page space. This could easily be done by blocking with -Privoxy's filters, and eliminating the entire image references from the HTML -page source. + There are many publicly usable "anonymous" proxies out there, which + provide a further level of indirection between you and the web server. -But, this would consume considerably more CPU resources (IOW, slow things -down), would likely destroy the layout of some web pages which rely on the -banners utilizing a certain amount of page space, and might fail in other -cases, where the screen space is reserved (e.g. by HTML tables for instance). -Also, making ads and banners disappear without any trace complicates -troubleshooting, and would sooner or later be problematic. + However, these proxies are called "anonymous" because you don't need to + authenticate, not because they would offer any real anonymity. Most of + them will log your IP address and make it available to the authorities in + case you violate the law of the country they run in. In fact you can't + even rule out that some of them only exist to *collect* information on + (those suspicious) people with a more than average preference for privacy. -The better alternative is to instead let them stay, and block the resulting -requests for the banners themselves as is now the case. This leaves either -empty space, or the familiar checkerboard pattern. + If you want to hide your IP address from most adversaries, you should + consider chaining Privoxy with Tor. The configuration details can be found + in How do I use Privoxy together with Tor section just below. -So the developers won't support this in the default configuration, but you can -of course define appropriate filters yourself to achieve this. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.8. Can Privoxy guarantee I am anonymous? -4.15. How can Privoxy filter Secure (HTTPS) URLs? + No. Your chances of remaining anonymous are improved, but unless you chain + Privoxy with Tor or a similar proxy and know what you're doing when it + comes to configuring the rest of your system, you should assume that + everything you do on the Web can be traced back to you. + + Privoxy can remove various information about you, and allows you more + freedom to decide which sites you can trust, and what details you want to + reveal. But it neither hides your IP address, nor can it guarantee that + the rest of the system behaves correctly. There are several possibilities + how a web sites can find out who you are, even if you are using a strict + Privoxy configuration and chained it with Tor. + + Most of Privoxy's privacy-enhancing features can be easily subverted by an + insecure browser configuration, therefore you should use a browser that + can be configured to only execute code from trusted sites, and be careful + which sites you trust. For example there is no point in having Privoxy + modify the User-Agent header, if websites can get all the information they + want through JavaScript, ActiveX, Flash, Java etc. + + A few browsers disclose the user's email address in certain situations, + such as when transferring a file by FTP. Privoxy does not filter FTP. If + you need this feature, or are concerned about the mail handler of your + browser disclosing your email address, you might consider products such as + NSClean. + + Browsers available only as binaries could use non-standard headers to give + out any information they can have access to: see the manufacturer's + license agreement. It's impossible to anticipate and prevent every breach + of privacy that might occur. The professionally paranoid prefer browsers + available as source code, because anticipating their behavior is easier. + Trust the source, Luke! + + -------------------------------------------------------------------------- -Since secure HTTP connections are encrypted SSL sessions between your browser -and the secure site, and are meant to be reliably secure, there is little that -Privoxy can do but hand the raw gibberish data though from one end to the other -unprocessed. + 4.9. A test site says I am not using a Proxy. -The only exception to this is blocking by host patterns, as the client needs to -tell Privoxy the name of the remote server, so that Privoxy can establish the -connection. If that name matches a host-only pattern, the connection will be -blocked. + Good! Actually, they are probably testing for some other kinds of proxies. + Hiding yourself completely would require additional steps. -As far as ad blocking is concerned, this is less of a restriction than it may -seem, since ad sources are often identifiable by the host name, and often the -banners to be placed in an encrypted page come unencrypted nonetheless for -efficiency reasons, which exposes them to the full power of Privoxy's ad -blocking. + -------------------------------------------------------------------------- -"Content cookies" (those that are embedded in the actual HTML or JS page -content, see filter{content-cookies}), in an SSL transaction will be impossible -to block under these conditions. Fortunately, this does not seem to be a very -common scenario since most cookies come by traditional means. + 4.10. How do I use Privoxy together with Tor? -------------------------------------------------------------------------------- + Before you configure Privoxy to use Tor, please follow the User Manual + chapters 2. Installation and 5. Startup to make sure Privoxy itself is + setup correctly. -4.16. Privoxy runs as a "server". How secure is it? Do I need to take any -special precautions? - -On Unix-like systems, Privoxy can run as a non-privileged user, which is how we -recommend it be run. Also, by default Privoxy listens to requests from -"localhost" only. + If it is, refer to Tor's extensive documentation to learn how to install + Tor, and make sure Tor's logfile says that "Tor has successfully opened a + circuit" and it "looks like client functionality is working". -The server aspect of Privoxy is not itself directly exposed to the Internet in -this configuration. If you want to have Privoxy serve as a LAN proxy, this will -have to be opened up to allow for LAN requests. In this case, we'd recommend -you specify only the LAN gateway address, e.g. 192.168.1.1, in the main Privoxy -configuration file and check all access control and security options. All LAN -hosts can then use this as their proxy address in the browser proxy -configuration, but Privoxy will not listen on any external interfaces. ACLs can -be defined in addition, and using a firewall is always good too. Better safe -than sorry. + If either Tor or Privoxy isn't working, their combination most likely will + neither. Testing them on their own will also help you to direct problem + reports to the right audience. If Privoxy isn't working, don't bother the + Tor developers. If Tor isn't working, don't send bug reports to the + Privoxy Team. -------------------------------------------------------------------------------- + If you verified that Privoxy and Tor are working, it is time to connect + them. As far as Privoxy is concerned, Tor is just another proxy that can + be reached by socks4 or socks4a. Most likely you are interested in Tor to + increase your anonymity level, therefore you should use socks4a, to make + sure DNS requests are done through Tor and thus invisible to your local + network. -4.17. Can I temporarily disable Privoxy? + Since Privoxy 3.0.5, its main configuration file is already prepared for + Tor, if you are using a default Tor configuration and run it on the same + system as Privoxy, you just have to edit the forwarding section and + uncomment the line: -Privoxy doesn't have a transparent proxy mode, but you can toggle off blocking -and content filtering. + # forward-socks4a / 127.0.0.1:9050 . -The easiest way to do that is to point your browser to the remote toggle URL: -http://config.privoxy.org/toggle. -See the Bookmarklets section of the User Manual for an easy way to access this -feature. Note that this is a feature that may need to be enabled in the main -config file. + This is enough to reach the Internet, but additionally you might want to + uncomment the following forward rules, to make sure your local network is + still reachable through Privoxy: -------------------------------------------------------------------------------- + # forward 192.168.*.*/ . + # forward 10.*.*.*/ . + # forward 127.*.*.*/ . -4.18. When "disabled" is Privoxy totally out of the picture? -No, this just means all optional filtering and actions are disabled. Privoxy is -still acting as a proxy, but just doing less of the things that Privoxy would -normally be expected to do. It is still a "middle-man" in the interaction -between your browser and web sites. See below to bypass the proxy. + Unencrypted connections to systems in these address ranges will be as + (un)secure as the local network is, but the alternative is that your + browser can't reach the network at all. Then again, that may actually be + desired and if you don't know for sure that your browser has to be able to + reach the local network, there's no reason to allow it. -------------------------------------------------------------------------------- + If you want your browser to be able to reach servers in your local network + by using their names, you will need additional exceptions that look like + this: -4.19. How can I tell Privoxy to totally ignore certain sites? + # forward localhost/ . -Bypassing a proxy, or proxying based on arbitrary criteria, is purely a browser -configuration issue, not a Privoxy issue. Modern browsers typically do have -settings for not proxying certain sites. Check your browser's help files. -------------------------------------------------------------------------------- + Save the modified configuration file and open + http://config.privoxy.org/show-status/ in your browser, confirm that + Privoxy has reloaded its configuration and that there are no other forward + lines, unless you know that you need them. If everything looks good, refer + to Tor Faq 4.2 to learn how to verify that you are really using Tor. -4.20. My logs show Privoxy "crunches" ads, but also its own internal CGI pages. -What is a "crunch"? + Afterward, please take the time to at least skim through the rest of Tor's + documentation. Make sure you understand what Tor does, why it is no + replacement for application level security, and why you probably don't + want to use it for unencrypted logins. -A "crunch" simply means Privoxy intercepted something, nothing more. Often this -is indeed ads or banners, but Privoxy uses the same mechanism for trapping -requests for its own internal pages. For instance, a request for Privoxy's -configuration page at: http://config.privoxy.org, is intercepted (i.e. it does -not go out to the 'net), and the familiar CGI configuration is returned to the -browser, and the log consequently will show a "crunch". + -------------------------------------------------------------------------- -Since version 3.0.7, Privoxy will also log the crunch reason. If you are using -an older version you might want to upgrade. + 4.11. Might some things break because header information or content is being + altered? -------------------------------------------------------------------------------- + Definitely. It is common for sites to use browser type, browser version, + HTTP header content, and various other techniques in order to dynamically + decide what to display and how to display it. What you see, and what I + see, might be very different. There are many, many ways that this can be + handled, so having hard and fast rules, is tricky. -4.21. Can Privoxy effect files that I download from a webserver? FTP server? + The "User-Agent" is sometimes used in this way to identify the browser, + and adjust content accordingly. -From the webserver's perspective, there is no difference between viewing a -document (i.e. a page), and downloading a file. The same is true of Privoxy. If -there is a match for a block pattern, it will still be blocked, and of course -this is obvious. + Also, different browsers use different encodings of non-English + characters, certain web servers convert pages on-the-fly according to the + User Agent header. Giving a "User Agent" with the wrong operating system + or browser manufacturer causes some sites in these languages to be + garbled; Surfers to Eastern European sites should change it to something + closer. And then some page access counters work by looking at the + "Referer" header; they may fail or break if unavailable. The weather maps + of Intellicast have been blocked by their server when no "Referer" or + cookie is provided, is another example. (But you can forge both headers + without giving information away). There are many other ways things can go + wrong when trying to fool a web server. The results of which could + inadvertently cause pages to load incorrectly, partially, or even not at + all. And there may be no obvious clues as to just what went wrong, or why. + Nowhere will there be a message that says "Turn off fast-redirects or + else! " -Filtering is potentially more of a concern since the results are not always so -obvious, and the effects of filtering are there whether the file is simply -viewed, or downloaded. And potentially whether the content is some obnoxious -advertisement, or Mr. Jimmy's latest/greatest source code jewel. Of course, one -of these presumably is "bad" content that we don't want, and the other is -"good" content that we do want. Privoxy is blind to the differences, and can -only distinguish "good from bad" by the configuration parameters we give it. + Similar thoughts apply to modifying JavaScript, and, to a lesser degree, + HTML elements. -Privoxy knows the differences in files according to the "Content Type" as -reported by the webserver. If this is reported accurately (e.g. "application/ -zip" for a zip archive), then Privoxy knows to ignore these where appropriate. -Privoxy potentially can filter HTML as well as plain text documents, subject to -configuration parameters of course. Also, documents that are of an unknown type -(generally assumed to be "text/plain") can be filtered, as will those that -might be incorrectly reported by the webserver. If such a file is a downloaded -file that is intended to be saved to disk, then any content that might have -been altered by filtering, will be saved too, for these (probably rare) cases. + If you have problems with a site, you will have to adjust your + configuration accordingly. Cookies are probably the most likely adjustment + that may be required, but by no means the only one. -Note that versions later than 3.0.2 do NOT filter document types reported as -"text/plain". Prior to this, Privoxy did filter this document type. + -------------------------------------------------------------------------- + + 4.12. Can Privoxy act as a "caching" proxy to speed up web browsing? + + No, it does not have this ability at all. You want something like Squid or + Polipo for this. And, yes, before you ask, Privoxy can co-exist with other + kinds of proxies like Squid. See the forwarding chapter in the user manual + for details. + + -------------------------------------------------------------------------- + + 4.13. What about as a firewall? Can Privoxy protect me? -In short, filtering is "ON" if a) the content type as reported by the webserver -is appropriate and b) the configuration allows it (or at least does not -disallow it). That's it. There is no magic cookie anywhere to say this is -"good" and this is "bad". It's the configuration that lets it all happen or -not. + Not in the way you mean, or in the way some firewall vendors claim they + can. Privoxy can help protect your privacy, but can't protect your system + from intrusion attempts. It is, of course, perfectly possible to use both. -If you download text files, you probably do not want these to be filtered, -particularly if the content is source code, or other critical content. Source -code sometimes might be mistaken for Javascript (i.e. the kind that might open -a pop-up window). It is recommended to turn off filtering for download sites -(particularly if the content may be plain text files and you are using version -3.0.2 or earlier) in your user.action file. And also, for any site or page -where making any changes at all to the content is to be avoided. + -------------------------------------------------------------------------- -Privoxy does not do FTP at all, only HTTP and HTTPS (SSL) protocols, so please -don't try. + 4.14. I have large empty spaces / a checkerboard pattern now where ads used + to be. Why? -------------------------------------------------------------------------------- + It is technically possible to eliminate banners and ads in a way that + frees their allocated page space. This could easily be done by blocking + with Privoxy's filters, and eliminating the entire image references from + the HTML page source. -4.22. I just downloaded a Perl script, and Privoxy altered it! Yikes, what is -wrong! + But, this would consume considerably more CPU resources (IOW, slow things + down), would likely destroy the layout of some web pages which rely on the + banners utilizing a certain amount of page space, and might fail in other + cases, where the screen space is reserved (e.g. by HTML tables for + instance). Also, making ads and banners disappear without any trace + complicates troubleshooting, and would sooner or later be problematic. -Please read above. + The better alternative is to instead let them stay, and block the + resulting requests for the banners themselves as is now the case. This + leaves either empty space, or the familiar checkerboard pattern. -------------------------------------------------------------------------------- + So the developers won't support this in the default configuration, but you + can of course define appropriate filters yourself to achieve this. -4.23. Should I continue to use a "HOSTS" file for ad-blocking? + -------------------------------------------------------------------------- -One time-tested technique to defeat common ads is to trick the local DNS system -by giving a phony IP address for the ad generator in the local HOSTS file, -typically using 127.0.0.1, aka localhost. This effectively blocks the ad. + 4.15. How can Privoxy filter Secure (HTTPS) URLs? -There is no reason to use this technique in conjunction with Privoxy. Privoxy -does essentially the same thing, much more elegantly and with much more -flexibility. A large HOSTS file, in fact, not only duplicates effort, but may -get in the way and seriously slow down your system. It is recommended to remove -such entries from your HOSTS file. If you think your hosts list is neglected by -Privoxy's configuration, consider adding your list to your user.action file: + Since secure HTTP connections are encrypted SSL sessions between your + browser and the secure site, and are meant to be reliably secure, there is + little that Privoxy can do but hand the raw gibberish data though from one + end to the other unprocessed. - { +block } - www.ad.example1.com - ad.example2.com - ads.galore.example.com - etc.example.com + The only exception to this is blocking by host patterns, as the client + needs to tell Privoxy the name of the remote server, so that Privoxy can + establish the connection. If that name matches a host-only pattern, the + connection will be blocked. + As far as ad blocking is concerned, this is less of a restriction than it + may seem, since ad sources are often identifiable by the host name, and + often the banners to be placed in an encrypted page come unencrypted + nonetheless for efficiency reasons, which exposes them to the full power + of Privoxy's ad blocking. -------------------------------------------------------------------------------- + "Content cookies" (those that are embedded in the actual HTML or JS page + content, see filter{content-cookies}), in an SSL transaction will be + impossible to block under these conditions. Fortunately, this does not + seem to be a very common scenario since most cookies come by traditional + means. -4.24. Where can I find more information about Privoxy and related issues? + -------------------------------------------------------------------------- -Other references and sites of interest to Privoxy users: + 4.16. Privoxy runs as a "server". How secure is it? Do I need to take any + special precautions? -http://www.privoxy.org/, the Privoxy Home page. + On Unix-like systems, Privoxy can run as a non-privileged user, which is + how we recommend it be run. Also, by default Privoxy listens to requests + from "localhost" only. -http://www.privoxy.org/faq/, the Privoxy FAQ. + The server aspect of Privoxy is not itself directly exposed to the + Internet in this configuration. If you want to have Privoxy serve as a LAN + proxy, this will have to be opened up to allow for LAN requests. In this + case, we'd recommend you specify only the LAN gateway address, e.g. + 192.168.1.1, in the main Privoxy configuration file and check all access + control and security options. All LAN hosts can then use this as their + proxy address in the browser proxy configuration, but Privoxy will not + listen on any external interfaces. ACLs can be defined in addition, and + using a firewall is always good too. Better safe than sorry. -http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on -SourceForge. + -------------------------------------------------------------------------- -http://config.privoxy.org/, the web-based user interface. Privoxy must be -running for this to work. Shortcut: http://p.p/ + 4.17. Can I temporarily disable Privoxy? -http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit "misses" -and other configuration related suggestions to the developers. + Privoxy doesn't have a transparent proxy mode, but you can toggle off + blocking and content filtering. -http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies are -used to track web users. + The easiest way to do that is to point your browser to the remote toggle + URL: http://config.privoxy.org/toggle. -http://www.junkbusters.com/ijb.html, the original Internet Junkbuster. + See the Bookmarklets section of the User Manual for an easy way to access + this feature. Note that this is a feature that may need to be enabled in + the main config file. -http://privacy.net/, a useful site to check what information about you is -leaked while you browse the web. + -------------------------------------------------------------------------- -http://www.squid-cache.org/, a popular caching proxy, which is often used -together with Privoxy. + 4.18. When "disabled" is Privoxy totally out of the picture? -http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy with -advanced features like pipelining, multiplexing and caching of partial -instances. In many setups it can be used as Squid replacement. + No, this just means all optional filtering and actions are disabled. + Privoxy is still acting as a proxy, but just doing less of the things that + Privoxy would normally be expected to do. It is still a "middle-man" in + the interaction between your browser and web sites. See below to bypass + the proxy. -http://tor.eff.org/, Tor can help anonymize web browsing, web publishing, -instant messaging, IRC, SSH, and other applications. + -------------------------------------------------------------------------- -http://www.privoxy.org/developer-manual/, the Privoxy developer manual. + 4.19. How can I tell Privoxy to totally ignore certain sites? -------------------------------------------------------------------------------- + Bypassing a proxy, or proxying based on arbitrary criteria, is purely a + browser configuration issue, not a Privoxy issue. Modern browsers + typically do have settings for not proxying certain sites. Check your + browser's help files. -4.25. I've noticed that Privoxy changes "Microsoft" to "MicroSuck"! Why are you -manipulating my browsing? + -------------------------------------------------------------------------- -We're not. The text substitutions that you are seeing are disabled in the -default configuration as shipped. You have either manually activated the "fun" -filter which is clearly labeled "Text replacements for subversive browsing fun! -" or you are using an older Privoxy version and have implicitly activated it by -choosing the "Adventuresome" profile in the web-based editor. Please upgrade. + 4.20. My logs show Privoxy "crunches" ads, but also its own internal CGI + pages. What is a "crunch"? + + A "crunch" simply means Privoxy intercepted something, nothing more. Often + this is indeed ads or banners, but Privoxy uses the same mechanism for + trapping requests for its own internal pages. For instance, a request for + Privoxy's configuration page at: http://config.privoxy.org, is intercepted + (i.e. it does not go out to the 'net), and the familiar CGI configuration + is returned to the browser, and the log consequently will show a "crunch". + + Since version 3.0.7, Privoxy will also log the crunch reason. If you are + using an older version you might want to upgrade. + + -------------------------------------------------------------------------- + + 4.21. Can Privoxy effect files that I download from a webserver? FTP server? + + From the webserver's perspective, there is no difference between viewing a + document (i.e. a page), and downloading a file. The same is true of + Privoxy. If there is a match for a block pattern, it will still be + blocked, and of course this is obvious. + + Filtering is potentially more of a concern since the results are not + always so obvious, and the effects of filtering are there whether the file + is simply viewed, or downloaded. And potentially whether the content is + some obnoxious advertisement, or Mr. Jimmy's latest/greatest source code + jewel. Of course, one of these presumably is "bad" content that we don't + want, and the other is "good" content that we do want. Privoxy is blind to + the differences, and can only distinguish "good from bad" by the + configuration parameters we give it. + + Privoxy knows the differences in files according to the "Content Type" as + reported by the webserver. If this is reported accurately (e.g. + "application/zip" for a zip archive), then Privoxy knows to ignore these + where appropriate. Privoxy potentially can filter HTML as well as plain + text documents, subject to configuration parameters of course. Also, + documents that are of an unknown type (generally assumed to be + "text/plain") can be filtered, as will those that might be incorrectly + reported by the webserver. If such a file is a downloaded file that is + intended to be saved to disk, then any content that might have been + altered by filtering, will be saved too, for these (probably rare) cases. + + Note that versions later than 3.0.2 do NOT filter document types reported + as "text/plain". Prior to this, Privoxy did filter this document type. + + In short, filtering is "ON" if a) the content type as reported by the + webserver is appropriate and b) the configuration allows it (or at least + does not disallow it). That's it. There is no magic cookie anywhere to say + this is "good" and this is "bad". It's the configuration that lets it all + happen or not. + + If you download text files, you probably do not want these to be filtered, + particularly if the content is source code, or other critical content. + Source code sometimes might be mistaken for Javascript (i.e. the kind that + might open a pop-up window). It is recommended to turn off filtering for + download sites (particularly if the content may be plain text files and + you are using version 3.0.2 or earlier) in your user.action file. And + also, for any site or page where making any changes at all to the content + is to be avoided. + + Privoxy does not do FTP at all, only HTTP and HTTPS (SSL) protocols, so + please don't try. + + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.22. I just downloaded a Perl script, and Privoxy altered it! Yikes, what + is wrong! -4.26. Does Privoxy produce "valid" HTML (or XHTML)? + Please read above. -Privoxy generates HTML in both its own "templates", and possibly whenever there -are text substitutions via a Privoxy filter. While this should always conform -to the HTML 4.01 specifications, it has not been validated against this or any -other standard. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 4.23. Should I continue to use a "HOSTS" file for ad-blocking? + + One time-tested technique to defeat common ads is to trick the local DNS + system by giving a phony IP address for the ad generator in the local + HOSTS file, typically using 127.0.0.1, aka localhost. This effectively + blocks the ad. + + There is no reason to use this technique in conjunction with Privoxy. + Privoxy does essentially the same thing, much more elegantly and with much + more flexibility. A large HOSTS file, in fact, not only duplicates effort, + but may get in the way and seriously slow down your system. It is + recommended to remove such entries from your HOSTS file. If you think your + hosts list is neglected by Privoxy's configuration, consider adding your + list to your user.action file: + + { +block } + www.ad.example1.com + ad.example2.com + ads.galore.example.com + etc.example.com + + -------------------------------------------------------------------------- + + 4.24. Where can I find more information about Privoxy and related issues? + + Other references and sites of interest to Privoxy users: + + http://www.privoxy.org/, the Privoxy Home page. + + http://www.privoxy.org/faq/, the Privoxy FAQ. + + http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on + SourceForge. + + http://config.privoxy.org/, the web-based user interface. Privoxy must be + running for this to work. Shortcut: http://p.p/ + + http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit + "misses" and other configuration related suggestions to the developers. + + http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies + are used to track web users. + + http://www.junkbusters.com/ijb.html, the original Internet Junkbuster. + + http://privacy.net/, a useful site to check what information about you is + leaked while you browse the web. + + http://www.squid-cache.org/, a popular caching proxy, which is often used + together with Privoxy. + + http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy + with advanced features like pipelining, multiplexing and caching of + partial instances. In many setups it can be used as Squid replacement. + + http://tor.eff.org/, Tor can help anonymize web browsing, web publishing, + instant messaging, IRC, SSH, and other applications. + + http://www.privoxy.org/developer-manual/, the Privoxy developer manual. + + -------------------------------------------------------------------------- + + 4.25. I've noticed that Privoxy changes "Microsoft" to "MicroSuck"! Why are + you manipulating my browsing? + + We're not. The text substitutions that you are seeing are disabled in the + default configuration as shipped. You have either manually activated the + "fun" filter which is clearly labeled "Text replacements for subversive + browsing fun!" or you are using an older Privoxy version and have + implicitly activated it by choosing the "Adventuresome" profile in the + web-based editor. Please upgrade. + + -------------------------------------------------------------------------- + + 4.26. Does Privoxy produce "valid" HTML (or XHTML)? + + Privoxy generates HTML in both its own "templates", and possibly whenever + there are text substitutions via a Privoxy filter. While this should + always conform to the HTML 4.01 specifications, it has not been validated + against this or any other standard. + + -------------------------------------------------------------------------- 5. Troubleshooting -5.1. I cannot connect to any websites. Or, I am getting "connection refused" -message with every web page. Why? - -There are several possibilities: - - * Privoxy is not running. Solution: verify that Privoxy is installed - correctly, has not crashed, and is indeed running. Turn on Privoxy's - logging, and look at the logs to see what they say. - - * Or your browser is configured for a different port than what Privoxy is - using. Solution: verify that Privoxy and your browser are set to the same - port (listen-address). - - * Or if using a forwarding rule, you have a configuration problem or a - problem with a host in the forwarding chain. Solution: temporarily alter - your configuration and take the forwarders out of the equation. - - * Or you have a firewall that is interfering and blocking you. Solution: try - disabling or removing the firewall as a simple test. - -------------------------------------------------------------------------------- - -5.2. Why am I getting a 503 Error (WSAECONNREFUSED) on every page? - -More than likely this is a problem with your TCP/IP networking. ZoneAlarm has -been reported to cause this symptom -- even if not running! The solution is to -either fight the ZA configuration, or uninstall ZoneAlarm, and then find -something better behaved in its place. Other personal firewall type products -may cause similar type problems if not configured correctly. - -------------------------------------------------------------------------------- - -5.3. I just added a new rule, but the steenkin ad is still getting through. -How? - -If the ad had been displayed before you added its URL, it will probably be held -in the browser's cache for some time, so it will be displayed without the need -for any request to the server, and Privoxy will not be involved. Flush the -browser's caches, and then try again. - -If this doesn't help, you probably have an error in the rule you applied. Try -pasting the full URL of the offending ad into http://config.privoxy.org/ -show-url-info and see if it really matches your new rule. Blocking ads is like -blocking spam: a lot of tinkering is required to stay ahead of the game. And -remember you need to block the URL of the ad in question, which may be entirely -different from the site URL itself. Most ads are hosted on different servers -than the main site itself. If you right-click on the ad, you should be able to -get all the relevant information you need. Alternately, you can find the -correct URL by looking at Privoxy's logs (you may need to enable logging in the -main config file if its disabled). - -Below is a slightly modified real-life log snippet that originates with one -requested URL: www.example.com (name of site was changed for this example, the -number of requests is real). You can see in this the complexity of what goes -into making up this one "page". There are eight different domains involved -here, with thirty two separate URLs requested in all, making up all manner of -images, Shockwave Flash, JavaScript, CSS stylesheets, scripts, and other -related content. Some of this content is obviously "good" or "bad", but not -all. Many of the more questionable looking requests, are going to outside -domains that seem to be identifying themselves with suspicious looking names, -making our job a little easier. Privoxy has "crunched" (meaning caught and -BLOCKED) quite a few items in this example, but perhaps missed a few as well. + 5.1. I cannot connect to any websites. Or, I am getting "connection refused" + message with every web page. Why? + + There are several possibilities: + + * Privoxy is not running. Solution: verify that Privoxy is installed + correctly, has not crashed, and is indeed running. Turn on Privoxy's + logging, and look at the logs to see what they say. + + * Or your browser is configured for a different port than what Privoxy + is using. Solution: verify that Privoxy and your browser are set to + the same port (listen-address). + + * Or if using a forwarding rule, you have a configuration problem or a + problem with a host in the forwarding chain. Solution: temporarily + alter your configuration and take the forwarders out of the equation. + + * Or you have a firewall that is interfering and blocking you. Solution: + try disabling or removing the firewall as a simple test. + + -------------------------------------------------------------------------- + + 5.2. Why am I getting a 503 Error (WSAECONNREFUSED) on every page? + + More than likely this is a problem with your TCP/IP networking. ZoneAlarm + has been reported to cause this symptom -- even if not running! The + solution is to either fight the ZA configuration, or uninstall ZoneAlarm, + and then find something better behaved in its place. Other personal + firewall type products may cause similar type problems if not configured + correctly. + + -------------------------------------------------------------------------- + + 5.3. I just added a new rule, but the steenkin ad is still getting through. + How? + + If the ad had been displayed before you added its URL, it will probably be + held in the browser's cache for some time, so it will be displayed without + the need for any request to the server, and Privoxy will not be involved. + Flush the browser's caches, and then try again. + + If this doesn't help, you probably have an error in the rule you applied. + Try pasting the full URL of the offending ad into + http://config.privoxy.org/show-url-info and see if it really matches your + new rule. Blocking ads is like blocking spam: a lot of tinkering is + required to stay ahead of the game. And remember you need to block the URL + of the ad in question, which may be entirely different from the site URL + itself. Most ads are hosted on different servers than the main site + itself. If you right-click on the ad, you should be able to get all the + relevant information you need. Alternately, you can find the correct URL + by looking at Privoxy's logs (you may need to enable logging in the main + config file if its disabled). + + Below is a slightly modified real-life log snippet that originates with + one requested URL: www.example.com (name of site was changed for this + example, the number of requests is real). You can see in this the + complexity of what goes into making up this one "page". There are eight + different domains involved here, with thirty two separate URLs requested + in all, making up all manner of images, Shockwave Flash, JavaScript, CSS + stylesheets, scripts, and other related content. Some of this content is + obviously "good" or "bad", but not all. Many of the more questionable + looking requests, are going to outside domains that seem to be identifying + themselves with suspicious looking names, making our job a little easier. + Privoxy has "crunched" (meaning caught and BLOCKED) quite a few items in + this example, but perhaps missed a few as well. Request: www.example.com/ Request: www.example.com/favicon.ico @@ -1817,513 +1986,525 @@ Request: 66.70.21.80/img/pixel.gif Request: www.adtrak.net/adlog.php?bannerid=1309&clientid=439&zoneid=58&source=Ua&block=86400 crunch! (Blocked) Request: 66.70.21.80/scripts/click.php?hid=a71b9f6504b0c5681fa5&si=Ua + Despite 12 out of 32 requests being blocked, the page looked, and seemed + to behave perfectly "normal" (minus some ads, of course). + + -------------------------------------------------------------------------- + + 5.4. One of my favorite sites does not work with Privoxy. What can I do? + + First verify that it is indeed a Privoxy problem, by toggling off Privoxy + through http://config.privoxy.org/toggle (the toggle feature may need to + be enabled in the main config), and then shift-reloading the problem page + (i.e. holding down the shift key while clicking reload. Alternatively, + flush your browser's disk and memory caches). + + If the problem went away, we know we have a configuration related problem. + Now go to http://config.privoxy.org/show-url-info and paste the full URL + of the page in question into the prompt. See which actions are being + applied to the URL, and which matches in which actions files are + responsible for that. It might be helpful also to look at your logs for + this site too, to see what else might be happening (note: logging may need + to be enabled in the main config file). Many sites are complex and require + a number of related pages to help present their content. Look at what else + might be used by the page in question, and what of that might be required. + Now, armed with this information, go to + http://config.privoxy.org/show-status and select the appropriate actions + files for editing. + + You can now either look for a section which disables the actions that you + suspect to cause the problem and add a pattern for your site there, or + make up a completely new section for your site. In any case, the + recommended way is to disable only the prime suspect, reload the problem + page, and only if the problem persists, disable more and more actions + until you have identified the culprit. You may or may not want to turn the + other actions on again. Remember to flush your browser's caches in between + any such changes! + + Alternately, if you are comfortable with a text editor, you can accomplish + the same thing by editing the appropriate actions file. Probably the + easiest way to deal with such problems when editing by hand is to add your + site to a { fragile } section in user.action, which is an alias that turns + off most "dangerous" actions, but is also likely to turn off more actions + then needed, and thus lower your privacy and protection more than + necessary, + + Troubleshooting actions is discussed in more detail in the User Manual + appendix, Troubleshooting: the Anatomy of an Action. There is also an + actions tutorial with general configuration information and examples. + + As a last resort, you can always see if your browser has a setting that + will bypass the proxy setting for selective sites. Modern browsers can do + this. + + -------------------------------------------------------------------------- + + 5.5. After installing Privoxy, I have to log in every time I start IE. What + gives? + + This is a quirk that effects the installation of Privoxy, in conjunction + with Internet Explorer and Internet Connection Sharing on Windows 2000 and + Windows XP. The symptoms may appear to be corrupted or invalid DUN + settings, or passwords. + + When setting up an NT based Windows system with Privoxy you may find that + things do not seem to be doing what you expect. When you set your system + up you will probably have set up Internet Connection Sharing (ICS) with + Dial up Networking (DUN) when logged in with administrator privileges. You + will probably have made this DUN connection available to other accounts + that you may have set-up on your system. E.g. Mum or Dad sets up the + system and makes accounts suitably configured for the kids. + + When setting up Privoxy in this environment you will have to alter the + proxy set-up of Internet Explorer (IE) for the specific DUN connection on + which you wish to use Privoxy. When you do this the ICS DUN set-up becomes + user specific. In this instance you will see no difference if you change + the DUN connection under the account used to set-up the connection. + However when you do this from another user you will notice that the DUN + connection changes to make available to "Me only". You will also find that + you have to store the password under each different user! + + The reason for this is that each user's set-up for IE is user specific. + Each set-up DUN connection and each LAN connection in IE store the + settings for each user individually. As such this enforces individual + configurations rather than common ones. Hence the first time you use a DUN + connection after re-booting your system it may not perform as you expect, + and prompt you for the password. Just set and save the password again and + all should be OK. + + [Thanks to Ray Griffith for this submission.] + + -------------------------------------------------------------------------- + + 5.6. I cannot connect to any FTP sites. Privoxy is blocking me. + + Privoxy cannot act as a proxy for FTP traffic, so do not configure your + browser to use Privoxy as an FTP proxy. The same is true for any protocol + other than HTTP or HTTPS (SSL). + + Most browsers understand FTP as well as HTTP. If you connect to a site, + with a URL like ftp://ftp.example.com, your browser is making an FTP + connection, and not a HTTP connection. So while your browser may speak + FTP, Privoxy does not, and cannot proxy such traffic. + + To complicate matters, some systems may have a generic "proxy" setting, + which will enable various protocols, including both HTTP and FTP proxying! + So it is possible to accidentally enable FTP proxying in these cases. And + of course, if this happens, Privoxy will indeed cause problems since it + does not know FTP. Newer version will give a sane error message if a FTP + connection is attempted. Just disable the FTP setting and all will be well + again. + + Will Privoxy ever proxy FTP traffic? Unlikely. There just is not much + reason, and the work to make this happen is more than it may seem. + + -------------------------------------------------------------------------- + + 5.7. In Mac OSX, I can't configure Microsoft Internet Explorer to use + Privoxy as the HTTP proxy. + + Microsoft Internet Explorer (in versions like 5.1) respects system-wide + network settings. In order to change the HTTP proxy, open System + Preferences, and click on the Network icon. In the settings pane that + comes up, click on the Proxies tab. Ensure the "Web Proxy (HTTP)" checkbox + is checked and enter 127.0.0.1 in the entry field. Enter 8118 in the Port + field. The next time you start IE, it should reflect these values. -Despite 12 out of 32 requests being blocked, the page looked, and seemed to -behave perfectly "normal" (minus some ads, of course). - -------------------------------------------------------------------------------- - -5.4. One of my favorite sites does not work with Privoxy. What can I do? - -First verify that it is indeed a Privoxy problem, by toggling off Privoxy -through http://config.privoxy.org/toggle (the toggle feature may need to be -enabled in the main config), and then shift-reloading the problem page (i.e. -holding down the shift key while clicking reload. Alternatively, flush your -browser's disk and memory caches). - -If the problem went away, we know we have a configuration related problem. Now -go to http://config.privoxy.org/show-url-info and paste the full URL of the -page in question into the prompt. See which actions are being applied to the -URL, and which matches in which actions files are responsible for that. It -might be helpful also to look at your logs for this site too, to see what else -might be happening (note: logging may need to be enabled in the main config -file). Many sites are complex and require a number of related pages to help -present their content. Look at what else might be used by the page in question, -and what of that might be required. Now, armed with this information, go to -http://config.privoxy.org/show-status and select the appropriate actions files -for editing. - -You can now either look for a section which disables the actions that you -suspect to cause the problem and add a pattern for your site there, or make up -a completely new section for your site. In any case, the recommended way is to -disable only the prime suspect, reload the problem page, and only if the -problem persists, disable more and more actions until you have identified the -culprit. You may or may not want to turn the other actions on again. Remember -to flush your browser's caches in between any such changes! - -Alternately, if you are comfortable with a text editor, you can accomplish the -same thing by editing the appropriate actions file. Probably the easiest way to -deal with such problems when editing by hand is to add your site to a { fragile -} section in user.action, which is an alias that turns off most "dangerous" -actions, but is also likely to turn off more actions then needed, and thus -lower your privacy and protection more than necessary, - -Troubleshooting actions is discussed in more detail in the User Manual -appendix, Troubleshooting: the Anatomy of an Action. There is also an actions -tutorial with general configuration information and examples. - -As a last resort, you can always see if your browser has a setting that will -bypass the proxy setting for selective sites. Modern browsers can do this. - -------------------------------------------------------------------------------- - -5.5. After installing Privoxy, I have to log in every time I start IE. What -gives? - -This is a quirk that effects the installation of Privoxy, in conjunction with -Internet Explorer and Internet Connection Sharing on Windows 2000 and Windows -XP. The symptoms may appear to be corrupted or invalid DUN settings, or -passwords. - -When setting up an NT based Windows system with Privoxy you may find that -things do not seem to be doing what you expect. When you set your system up you -will probably have set up Internet Connection Sharing (ICS) with Dial up -Networking (DUN) when logged in with administrator privileges. You will -probably have made this DUN connection available to other accounts that you may -have set-up on your system. E.g. Mum or Dad sets up the system and makes -accounts suitably configured for the kids. - -When setting up Privoxy in this environment you will have to alter the proxy -set-up of Internet Explorer (IE) for the specific DUN connection on which you -wish to use Privoxy. When you do this the ICS DUN set-up becomes user specific. -In this instance you will see no difference if you change the DUN connection -under the account used to set-up the connection. However when you do this from -another user you will notice that the DUN connection changes to make available -to "Me only". You will also find that you have to store the password under each -different user! - -The reason for this is that each user's set-up for IE is user specific. Each -set-up DUN connection and each LAN connection in IE store the settings for each -user individually. As such this enforces individual configurations rather than -common ones. Hence the first time you use a DUN connection after re-booting -your system it may not perform as you expect, and prompt you for the password. -Just set and save the password again and all should be OK. - -[Thanks to Ray Griffith for this submission.] - -------------------------------------------------------------------------------- - -5.6. I cannot connect to any FTP sites. Privoxy is blocking me. - -Privoxy cannot act as a proxy for FTP traffic, so do not configure your browser -to use Privoxy as an FTP proxy. The same is true for any protocol other than -HTTP or HTTPS (SSL). - -Most browsers understand FTP as well as HTTP. If you connect to a site, with a -URL like ftp://ftp.example.com, your browser is making an FTP connection, and -not a HTTP connection. So while your browser may speak FTP, Privoxy does not, -and cannot proxy such traffic. - -To complicate matters, some systems may have a generic "proxy" setting, which -will enable various protocols, including both HTTP and FTP proxying! So it is -possible to accidentally enable FTP proxying in these cases. And of course, if -this happens, Privoxy will indeed cause problems since it does not know FTP. -Newer version will give a sane error message if a FTP connection is attempted. -Just disable the FTP setting and all will be well again. - -Will Privoxy ever proxy FTP traffic? Unlikely. There just is not much reason, -and the work to make this happen is more than it may seem. - -------------------------------------------------------------------------------- - -5.7. In Mac OSX, I can't configure Microsoft Internet Explorer to use Privoxy -as the HTTP proxy. - -Microsoft Internet Explorer (in versions like 5.1) respects system-wide network -settings. In order to change the HTTP proxy, open System Preferences, and click -on the Network icon. In the settings pane that comes up, click on the Proxies -tab. Ensure the "Web Proxy (HTTP)" checkbox is checked and enter 127.0.0.1 in -the entry field. Enter 8118 in the Port field. The next time you start IE, it -should reflect these values. - -------------------------------------------------------------------------------- - -5.8. In Mac OSX, I dragged the Privoxy folder to the trash in order to -uninstall it. Now the finder tells me I don't have sufficient privileges to -empty the trash. - -Just dragging the Privoxy folder to the trash is not enough to delete it. -Privoxy supplies an uninstall.command file that takes care of these details. -Open the trash, drag the uninstall.command file out of the trash and -double-click on it. You will be prompted for confirmation and the -administration password. + -------------------------------------------------------------------------- -The trash may still appear full after this command; emptying the trash from the -desktop should make it appear empty again. + 5.8. In Mac OSX, I dragged the Privoxy folder to the trash in order to + uninstall it. Now the finder tells me I don't have sufficient privileges to + empty the trash. -------------------------------------------------------------------------------- + Just dragging the Privoxy folder to the trash is not enough to delete it. + Privoxy supplies an uninstall.command file that takes care of these + details. Open the trash, drag the uninstall.command file out of the trash + and double-click on it. You will be prompted for confirmation and the + administration password. -5.9. In Mac OSX Panther (10.3), images often fail to load and/or I experience -random delays in page loading. I'm using localhost as my browser's proxy -setting. + The trash may still appear full after this command; emptying the trash + from the desktop should make it appear empty again. -We believe this is due to an IPv6-related bug in OSX, but don't fully -understand the issue yet. In any case, changing the proxy setting to 127.0.0.1 -instead of localhost works around the problem. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 5.9. In Mac OSX Panther (10.3), images often fail to load and/or I + experience random delays in page loading. I'm using localhost as my + browser's proxy setting. -5.10. I get a completely blank page at one site. "View Source" shows only: -<html><body></body></html>. Without Privoxy the page loads fine. + We believe this is due to an IPv6-related bug in OSX, but don't fully + understand the issue yet. In any case, changing the proxy setting to + 127.0.0.1 instead of localhost works around the problem. -Chances are that the site suffers from a bug in PHP, which results in empty -pages being sent if the client explicitly requests an uncompressed page, like -Privoxy does. This bug has been fixed in PHP 4.2.3. + -------------------------------------------------------------------------- + + 5.10. I get a completely blank page at one site. "View Source" shows only: + <html><body></body></html>. Without Privoxy the page loads fine. -To find out if this is in fact the source of the problem, try adding the site -to a -prevent-compression section in user.action: + Chances are that the site suffers from a bug in PHP, which results in + empty pages being sent if the client explicitly requests an uncompressed + page, like Privoxy does. This bug has been fixed in PHP 4.2.3. + + To find out if this is in fact the source of the problem, try adding the + site to a -prevent-compression section in user.action: # Make exceptions for ill-behaved sites: # {-prevent-compression} .example.com + If that works, you may also want to report the problem to the site's + webmasters, telling them to use zlib.output_compression instead of + ob_gzhandler in their PHP applications (workaround) or upgrade to PHP + 4.2.3 or later (fix). -If that works, you may also want to report the problem to the site's -webmasters, telling them to use zlib.output_compression instead of ob_gzhandler -in their PHP applications (workaround) or upgrade to PHP 4.2.3 or later (fix). - -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.11. My logs show many "Unable to get my own hostname" lines. Why? + 5.11. My logs show many "Unable to get my own hostname" lines. Why? -Privoxy tries to get the hostname of the system its running on from the IP -address of the system interface it is bound to (from the config file -listen-address setting). If the system cannot supply this information, Privoxy -logs this condition. + Privoxy tries to get the hostname of the system its running on from the IP + address of the system interface it is bound to (from the config file + listen-address setting). If the system cannot supply this information, + Privoxy logs this condition. -Typically, this would be considered a minor system configuration error. It is -not a fatal error to Privoxy however, but may result in a much slower response -from Privoxy on some platforms due to DNS timeouts. + Typically, this would be considered a minor system configuration error. It + is not a fatal error to Privoxy however, but may result in a much slower + response from Privoxy on some platforms due to DNS timeouts. -This can be caused by a problem with the local HOSTS file. If this file has -been changed from the original, try reverting it to see if that helps. Make -sure whatever name(s) are used for the local system, that they resolve both -ways. + This can be caused by a problem with the local HOSTS file. If this file + has been changed from the original, try reverting it to see if that helps. + Make sure whatever name(s) are used for the local system, that they + resolve both ways. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.12. When I try to launch Privoxy, I get an error message "port 8118 is -already in use" (or similar wording). Why? + 5.12. When I try to launch Privoxy, I get an error message "port 8118 is + already in use" (or similar wording). Why? -Port 8118 is Privoxy's default TCP "listening" port. Typically this message -would mean that there is already one instance of Privoxy running, and your -system is actually trying to start a second Privoxy on the same port, which -will not work. (You can have multiple instances but they must be assigned -different ports.) How and why this might happen varies from platform to -platform, but you need to check your installation and start-up procedures. + Port 8118 is Privoxy's default TCP "listening" port. Typically this + message would mean that there is already one instance of Privoxy running, + and your system is actually trying to start a second Privoxy on the same + port, which will not work. (You can have multiple instances but they must + be assigned different ports.) How and why this might happen varies from + platform to platform, but you need to check your installation and start-up + procedures. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.13. Pages with UTF-8 fonts are garbled. + 5.13. Pages with UTF-8 fonts are garbled. -This is caused by the "demoronizer" filter. You should either upgrade Privoxy, -or at least upgrade to the most recent default.action file available from -SourceForge. Or you can simply disable the demoronizer filter. + This is caused by the "demoronizer" filter. You should either upgrade + Privoxy, or at least upgrade to the most recent default.action file + available from SourceForge. Or you can simply disable the demoronizer + filter. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.14. Why are binary files (such as images) corrupted when Privoxy is used? + 5.14. Why are binary files (such as images) corrupted when Privoxy is used? -This may also be caused by the "demoronizer" filter, in conjunction with a web -server that is misreporting the content type. Binary files are exempted from -Privoxy's filtering (unless the web server by mistake says the file is -something else). Either upgrade Privoxy, or go to the most recent -default.action file available from SourceForge. + This may also be caused by the "demoronizer" filter, in conjunction with a + web server that is misreporting the content type. Binary files are + exempted from Privoxy's filtering (unless the web server by mistake says + the file is something else). Either upgrade Privoxy, or go to the most + recent default.action file available from SourceForge. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.15. What is the "demoronizer" and why is it there? + 5.15. What is the "demoronizer" and why is it there? -The original demoronizer was a Perl script that cleaned up HTML pages which -were created with certain Microsoft products. MS has used proprietary -extensions to standardized font encodings (ISO 8859-1), which has caused -problems for pages that are viewed with non-Microsoft products (and are -expecting to see a standard set of fonts). The demoronizer corrected these -errors so the pages displayed correctly. Privoxy borrowed from this script, -introducing a filter based on the original demoronizer, which in turn could -correct these errors on the fly. + The original demoronizer was a Perl script that cleaned up HTML pages + which were created with certain Microsoft products. MS has used + proprietary extensions to standardized font encodings (ISO 8859-1), which + has caused problems for pages that are viewed with non-Microsoft products + (and are expecting to see a standard set of fonts). The demoronizer + corrected these errors so the pages displayed correctly. Privoxy borrowed + from this script, introducing a filter based on the original demoronizer, + which in turn could correct these errors on the fly. -But this is only needed in some situations, and will cause serious problems in -some other situations. + But this is only needed in some situations, and will cause serious + problems in some other situations. -If you are using Microsoft products, you do not need it. If you need to view -pages with UTF-8 characters (such as Cyrillic or Chinese), then it will cause -corruption of the fonts, and thus should not be on. + If you are using Microsoft products, you do not need it. If you need to + view pages with UTF-8 characters (such as Cyrillic or Chinese), then it + will cause corruption of the fonts, and thus should not be on. -On the other hand, if you use non-Microsoft products, and you occasionally -notice weird characters on pages, you might want to try it. + On the other hand, if you use non-Microsoft products, and you occasionally + notice weird characters on pages, you might want to try it. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.16. Why do I keep seeing "PrivoxyWindowOpen()" in raw source code? + 5.16. Why do I keep seeing "PrivoxyWindowOpen()" in raw source code? -Privoxy is attempting to disable malicious Javascript in this case, with the -unsolicited-popups filter. Privoxy cannot tell very well "good" code snippets -from "bad" code snippets. + Privoxy is attempting to disable malicious Javascript in this case, with + the unsolicited-popups filter. Privoxy cannot tell very well "good" code + snippets from "bad" code snippets. -If you see this in HTML source, and the page displays without problems, then -this is good, and likely some pop-up window was disabled. If you see this where -it is causing a problem, such as a downloaded program source code file, then -you should set an exception for this site or page such that the integrity of -the page stays in tact by disabling all filtering. + If you see this in HTML source, and the page displays without problems, + then this is good, and likely some pop-up window was disabled. If you see + this where it is causing a problem, such as a downloaded program source + code file, then you should set an exception for this site or page such + that the integrity of the page stays in tact by disabling all filtering. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.17. I am getting too many DNS errors like "404 No Such Domain". Why can't -Privoxy do this better? + 5.17. I am getting too many DNS errors like "404 No Such Domain". Why can't + Privoxy do this better? -There are potentially several factors here. First of all, the DNS resolution is -done by the underlying operating system -- not Privoxy itself. Privoxy merely -initiates the process and hands it off, and then later reports whatever the -outcome was. And tries to give a coherent message if there seems to be a -problem. In some cases, this might otherwise be mitigated by the browser itself -which might try some work-arounds and alternate approaches (e.g adding "www." -to the URL). + There are potentially several factors here. First of all, the DNS + resolution is done by the underlying operating system -- not Privoxy + itself. Privoxy merely initiates the process and hands it off, and then + later reports whatever the outcome was. And tries to give a coherent + message if there seems to be a problem. In some cases, this might + otherwise be mitigated by the browser itself which might try some + work-arounds and alternate approaches (e.g adding "www." to the URL). -In other cases, if Privoxy is being chained with another proxy, this could -complicate the issue, and cause undue delays and timeouts. In the case of a -"socks4a" proxy, the socks server handles all the DNS. Privoxy would just be -the "messenger" which is reporting whatever problem occurred downstream, and -not the root cause of the error. + In other cases, if Privoxy is being chained with another proxy, this could + complicate the issue, and cause undue delays and timeouts. In the case of + a "socks4a" proxy, the socks server handles all the DNS. Privoxy would + just be the "messenger" which is reporting whatever problem occurred + downstream, and not the root cause of the error. -In any case, versions newer than 3.0.3 include various improvements to help -Privoxy better handle these cases. + In any case, versions newer than 3.0.3 include various improvements to + help Privoxy better handle these cases. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.18. At one site Privoxy just hangs, and starts taking all CPU. Why is this? + 5.18. At one site Privoxy just hangs, and starts taking all CPU. Why is + this? -This is probably a manifestation of the "100% cpu" problem that occurs on pages -containing many (thousands upon thousands) of blank lines. The blank lines are -in the raw HTML source of the page, and the browser just ignores them. But the -pattern matching in Privoxy's page filtering mechanism is trying to match -against absurdly long strings and this becomes very CPU-intensive, taking a -long, long time to complete. Until a better solution comes along, disable -filtering on these pages, particularly the js-annoyances and unsolicited-popups -filters. + This is probably a manifestation of the "100% cpu" problem that occurs on + pages containing many (thousands upon thousands) of blank lines. The blank + lines are in the raw HTML source of the page, and the browser just ignores + them. But the pattern matching in Privoxy's page filtering mechanism is + trying to match against absurdly long strings and this becomes very + CPU-intensive, taking a long, long time to complete. Until a better + solution comes along, disable filtering on these pages, particularly the + js-annoyances and unsolicited-popups filters. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.19. I just installed Privoxy, and all my browsing has slowed to a crawl. What -gives? + 5.19. I just installed Privoxy, and all my browsing has slowed to a crawl. + What gives? -This should not happen, and for the overwhelming number of users world-wide, it -does not happen. I would suspect some inadvertent interaction of software -components such as anti-virus software, spyware protectors, personal firewalls -or similar components. Try disabling (or uninstalling) these one at a time and -see if that helps. + This should not happen, and for the overwhelming number of users + world-wide, it does not happen. I would suspect some inadvertent + interaction of software components such as anti-virus software, spyware + protectors, personal firewalls or similar components. Try disabling (or + uninstalling) these one at a time and see if that helps. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -5.20. Why do my filters work on some sites but not on others? + 5.20. Why do my filters work on some sites but not on others? -It's probably due to compression. It is a common practice for web servers to -send their content "compressed" in order to speed things up, and then let the -browser "uncompress" them. When compiled with zlib support Privoxy can -decompress content before filtering, otherwise you may want to enable -prevent-compression. + It's probably due to compression. It is a common practice for web servers + to send their content "compressed" in order to speed things up, and then + let the browser "uncompress" them. When compiled with zlib support Privoxy + can decompress content before filtering, otherwise you may want to enable + prevent-compression. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 6. Contacting the developers, Bug Reporting and Feature Requests -We value your feedback. In fact, we rely on it to improve Privoxy and its -configuration. However, please note the following hints, so we can provide you -with the best support: + We value your feedback. In fact, we rely on it to improve Privoxy and its + configuration. However, please note the following hints, so we can provide + you with the best support: -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.1. Get Support + 6.1. Get Support -For casual users, our support forum at SourceForge is probably best suited: -http://sourceforge.net/tracker/?group_id=11118&atid=211118 + For casual users, our support forum at SourceForge is probably best + suited: http://sourceforge.net/tracker/?group_id=11118&atid=211118 -All users are of course welcome to discuss their issues on the users mailing -list, where the developers also hang around. + All users are of course welcome to discuss their issues on the users + mailing list, where the developers also hang around. -Note that the Privoxy mailing lists are moderated. Posts from unsubscribed -addresses have to be accepted manually by a moderator. This may cause a delay -of several days and if you use a subject that doesn't clearly mention Privoxy -or one of its features, your message may be accidentally discarded as spam. + Note that the Privoxy mailing lists are moderated. Posts from unsubscribed + addresses have to be accepted manually by a moderator. This may cause a + delay of several days and if you use a subject that doesn't clearly + mention Privoxy or one of its features, your message may be accidentally + discarded as spam. -If you aren't subscribed, you should therefore spend a few seconds to come up -with a proper subject. Additionally you should make it clear that you want to -get CC'd. Otherwise some responses will be directed to the mailing list only, -and you won't see them. + If you aren't subscribed, you should therefore spend a few seconds to come + up with a proper subject. Additionally you should make it clear that you + want to get CC'd. Otherwise some responses will be directed to the mailing + list only, and you won't see them. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.2. Reporting Problems + 6.2. Reporting Problems -"Problems" for our purposes, come in two forms: + "Problems" for our purposes, come in two forms: - * Configuration issues, such as ads that slip through, or sites that don't - function properly due to one Privoxy "action" or another being turned "on". + * Configuration issues, such as ads that slip through, or sites that + don't function properly due to one Privoxy "action" or another being + turned "on". - * "Bugs" in the programming code that makes up Privoxy, such as that might - cause a crash. + * "Bugs" in the programming code that makes up Privoxy, such as that + might cause a crash. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.2.1. Reporting Ads or Other Configuration Problems + 6.2.1. Reporting Ads or Other Configuration Problems -Please send feedback on ads that slipped through, innocent images that were -blocked, sites that don't work properly, and other configuration related -problem of default.action file, to http://sourceforge.net/tracker/?group_id= -11118&atid=460288, the Actions File Tracker. + Please send feedback on ads that slipped through, innocent images that + were blocked, sites that don't work properly, and other configuration + related problem of default.action file, to + http://sourceforge.net/tracker/?group_id=11118&atid=460288, the Actions + File Tracker. -New, improved default.action files may occasionally be made available based on -your feedback. These will be announced on the ijbswa-announce list and -available from our the files section of our project page. + New, improved default.action files may occasionally be made available + based on your feedback. These will be announced on the ijbswa-announce + list and available from our the files section of our project page. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.2.2. Reporting Bugs + 6.2.2. Reporting Bugs -Please report all bugs through our bug tracker: http://sourceforge.net/tracker -/?group_id=11118&atid=111118. + Please report all bugs through our bug tracker: + http://sourceforge.net/tracker/?group_id=11118&atid=111118. -Before doing so, please make sure that the bug has not already been submitted -and observe the additional hints at the top of the submit form. If already -submitted, please feel free to add any info to the original report that might -help to solve the issue. + Before doing so, please make sure that the bug has not already been + submitted and observe the additional hints at the top of the submit form. + If already submitted, please feel free to add any info to the original + report that might help to solve the issue. -Please try to verify that it is a Privoxy bug, and not a browser or site bug or -documented behaviour that just happens to be different than what you expected. -If unsure, try toggling off Privoxy, and see if the problem persists. + Please try to verify that it is a Privoxy bug, and not a browser or site + bug or documented behaviour that just happens to be different than what + you expected. If unsure, try toggling off Privoxy, and see if the problem + persists. -If you are using your own custom configuration, please try the stock configs to -see if the problem is configuration related. If you're having problems with a -feature that is disabled by default, please ask around on the mailing list if -others can reproduce the problem. + If you are using your own custom configuration, please try the stock + configs to see if the problem is configuration related. If you're having + problems with a feature that is disabled by default, please ask around on + the mailing list if others can reproduce the problem. -If you aren't using the latest Privoxy version, the bug may have been found and -fixed in the meantime. We would appreciate if you could take the time to -upgrade to the latest version (or even the latest CVS snapshot) and verify that -your bug still exists. + If you aren't using the latest Privoxy version, the bug may have been + found and fixed in the meantime. We would appreciate if you could take the + time to upgrade to the latest version (or even the latest CVS snapshot) + and verify that your bug still exists. -Please be sure to provide the following information: + Please be sure to provide the following information: - * The exact Privoxy version you are using (if you got the source from CVS, - please also provide the source code revisions as shown in http:// - config.privoxy.org/show-version). + * The exact Privoxy version you are using (if you got the source from + CVS, please also provide the source code revisions as shown in + http://config.privoxy.org/show-version). - * The operating system and versions you run Privoxy on, (e.g. Windows XP - SP2), if you are using a Unix flavor, sending the output of "uname -a" - should do, in case of GNU/Linux, please also name the distribution. + * The operating system and versions you run Privoxy on, (e.g. Windows XP + SP2), if you are using a Unix flavor, sending the output of "uname -a" + should do, in case of GNU/Linux, please also name the distribution. - * The name, platform, and version of the browser you were using (e.g. - Internet Explorer v5.5 for Mac). + * The name, platform, and version of the browser you were using (e.g. + Internet Explorer v5.5 for Mac). - * The URL where the problem occurred, or some way for us to duplicate the - problem (e.g. http://somesite.example.com/?somethingelse=123). + * The URL where the problem occurred, or some way for us to duplicate + the problem (e.g. http://somesite.example.com/?somethingelse=123). - * Whether your version of Privoxy is one supplied by the Privoxy developers - via SourceForge, or if you got your copy somewhere else. + * Whether your version of Privoxy is one supplied by the Privoxy + developers via SourceForge, or if you got your copy somewhere else. - * Whether you are using Privoxy in tandem with another proxy such as Tor. If - so, please temporary disable the other proxy to see if the symptoms change. + * Whether you are using Privoxy in tandem with another proxy such as + Tor. If so, please temporary disable the other proxy to see if the + symptoms change. - * Whether you are using a personal firewall product. If so, does Privoxy work - without it? + * Whether you are using a personal firewall product. If so, does Privoxy + work without it? - * Any other pertinent information to help identify the problem such as config - or log file excerpts (yes, you should have log file entries for each action - taken). + * Any other pertinent information to help identify the problem such as + config or log file excerpts (yes, you should have log file entries for + each action taken). -You don't have to tell us your actual name when filing a problem report, but -please use a nickname so we can differentiate between your messages and the -ones entered by other "anonymous" users that may respond to your request if -they have the same problem or already found a solution. + You don't have to tell us your actual name when filing a problem report, + but please use a nickname so we can differentiate between your messages + and the ones entered by other "anonymous" users that may respond to your + request if they have the same problem or already found a solution. -Please also check the status of your request a few days after submitting it, as -we may request additional information. If you use a SF id, you should -automatically get a mail when someone responds to your request. + Please also check the status of your request a few days after submitting + it, as we may request additional information. If you use a SF id, you + should automatically get a mail when someone responds to your request. -The appendix of the Privoxy User Manual also has helpful information on -understanding actions, and action debugging. + The appendix of the Privoxy User Manual also has helpful information on + understanding actions, and action debugging. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.3. Request New Features + 6.3. Request New Features -You are welcome to submit ideas on new features or other proposals for -improvement through our feature request tracker at http://sourceforge.net/ -tracker/?atid=361118&group_id=11118. + You are welcome to submit ideas on new features or other proposals for + improvement through our feature request tracker at + http://sourceforge.net/tracker/?atid=361118&group_id=11118. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6.4. Other + 6.4. Other -For any other issues, feel free to use the mailing lists. Technically -interested users and people who wish to contribute to the project are also -welcome on the developers list! You can find an overview of all Privoxy-related -mailing lists, including list archives, at: http://sourceforge.net/mail/? -group_id=11118. + For any other issues, feel free to use the mailing lists. Technically + interested users and people who wish to contribute to the project are also + welcome on the developers list! You can find an overview of all + Privoxy-related mailing lists, including list archives, at: + http://sourceforge.net/mail/?group_id=11118. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 7. Privoxy Copyright, License and History -Copyright 2001-2008 by Privoxy Developers < -ijbswa-developers@lists.sourceforge.net> - -Some source code is based on code Copyright 1997 by Anonymous Coders and -Junkbusters, Inc. and licensed under the GNU General Public License. + Copyright © 2001-2008 by Privoxy Developers + <ijbswa-developers@lists.sourceforge.net> -Portions of this document are "borrowed" from the original Junkbuster (tm) FAQ, -and modified as appropriate for Privoxy. + Some source code is based on code Copyright © 1997 by Anonymous Coders + and Junkbusters, Inc. and licensed under the GNU General Public License. -------------------------------------------------------------------------------- + Portions of this document are "borrowed" from the original Junkbuster (tm) + FAQ, and modified as appropriate for Privoxy. -7.1. License + -------------------------------------------------------------------------- -Privoxy is free software; you can redistribute it and/or modify it under the -terms of the GNU General Public License, version 2, as published by the Free -Software Foundation. + 7.1. License -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, 51 Franklin Street, Fifth -Floor, Boston, MA 02110-1301, USA + Privoxy is free software; you can redistribute it and/or modify it under + the terms of the GNU General Public License, version 2, as published by + the Free Software Foundation. -You should have received a copy of the GNU General Public License along with -this program; if not, write to the + 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, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - Free Software - Foundation, Inc. 51 Franklin Street, Fifth Floor - Boston, MA 02110-1301 - USA + You should have received a copy of the GNU General Public License along + with this program; if not, write to the -------------------------------------------------------------------------------- + Free Software + Foundation, Inc. 51 Franklin Street, Fifth Floor + Boston, MA 02110-1301 + USA -7.2. History + -------------------------------------------------------------------------- -A long time ago, there was the Internet Junkbuster, by Anonymous Coders and -Junkbusters Corporation. This saved many users a lot of pain in the early days -of web advertising and user tracking. + 7.2. History -But the web, its protocols and standards, and with it, the techniques for -forcing ads on users, give up autonomy over their browsing, and for tracking -them, keeps evolving. Unfortunately, the Internet Junkbuster did not. Version -2.0.2, published in 1998, was (and is) the last official release available from -Junkbusters Corporation. Fortunately, it had been released under the GNU GPL, -which allowed further development by others. + A long time ago, there was the Internet Junkbuster, by Anonymous Coders + and Junkbusters Corporation. This saved many users a lot of pain in the + early days of web advertising and user tracking. -So Stefan Waldherr started maintaining an improved version of the software, to -which eventually a number of people contributed patches. It could already -replace banners with a transparent image, and had a first version of pop-up -killing, but it was still very closely based on the original, with all its -limitations, such as the lack of HTTP/1.1 support, flexible per-site -configuration, or content modification. The last release from this effort was -version 2.0.2-10, published in 2000. + But the web, its protocols and standards, and with it, the techniques for + forcing ads on users, give up autonomy over their browsing, and for + tracking them, keeps evolving. Unfortunately, the Internet Junkbuster did + not. Version 2.0.2, published in 1998, was (and is) the last official + release available from Junkbusters Corporation. Fortunately, it had been + released under the GNU GPL, which allowed further development by others. -Then, some developers picked up the thread, and started turning the software -inside out, upside down, and then reassembled it, adding many new features -along the way. + So Stefan Waldherr started maintaining an improved version of the + software, to which eventually a number of people contributed patches. It + could already replace banners with a transparent image, and had a first + version of pop-up killing, but it was still very closely based on the + original, with all its limitations, such as the lack of HTTP/1.1 support, + flexible per-site configuration, or content modification. The last release + from this effort was version 2.0.2-10, published in 2000. -The result of this is Privoxy, whose first stable version, 3.0, was released -August, 2002. + Then, some developers picked up the thread, and started turning the + software inside out, upside down, and then reassembled it, adding many new + features along the way. + The result of this is Privoxy, whose first stable version, 3.0, was + released August, 2002. diff --git a/doc/text/user-manual.txt b/doc/text/user-manual.txt index a5058e45..0fb563c3 100644 --- a/doc/text/user-manual.txt +++ b/doc/text/user-manual.txt @@ -1,5047 +1,5233 @@ -Privoxy 3.0.8 User Manual + Privoxy 3.0.8 User Manual -[ Copyright 2001 - 2008 by Privoxy Developers ] + [Copyright[ © 2001 - 2008 by Privoxy Developers]] -$Id: user-manual.sgml,v 2.53 2008/01/19 15:03:05 hal9 Exp $ + $Id: user-manual.sgml,v 2.55 2008/01/19 21:26:37 hal9 Exp $ -The Privoxy User Manual gives users information on how to install, configure -and use Privoxy. + The Privoxy User Manual gives users information on how to install, + configure and use Privoxy. -Privoxy is a non-caching web proxy with advanced filtering capabilities for -enhancing privacy, modifying web page data, managing HTTP cookies, controlling -access, and removing ads, banners, pop-ups and other obnoxious Internet junk. -Privoxy has a flexible configuration and can be customized to suit individual -needs and tastes. Privoxy has application for both stand-alone systems and -multi-user networks. + Privoxy is a non-caching web proxy with advanced filtering capabilities + for enhancing privacy, modifying web page data, managing HTTP cookies, + controlling access, and removing ads, banners, pop-ups and other obnoxious + Internet junk. Privoxy has a flexible configuration and can be customized + to suit individual needs and tastes. Privoxy has application for both + stand-alone systems and multi-user networks. -Privoxy is based on Internet Junkbuster (tm). + Privoxy is based on Internet Junkbuster (tm). -You can find the latest version of the Privoxy User Manual at http:// -www.privoxy.org/user-manual/. Please see the Contact section on how to contact -the developers. + You can find the latest version of the Privoxy User Manual at + http://www.privoxy.org/user-manual/. Please see the Contact section on how + to contact the developers. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -Table of Contents -1. Introduction + Table of Contents - 1.1. Features + 1. Introduction -2. Installation + 1.1. Features - 2.1. Binary Packages + 2. Installation - 2.1.1. Red Hat and Fedora RPMs - 2.1.2. Debian and Ubuntu - 2.1.3. Windows - 2.1.4. Solaris - 2.1.5. OS/2 - 2.1.6. Mac OSX - 2.1.7. AmigaOS - 2.1.8. FreeBSD - 2.1.9. Gentoo + 2.1. Binary Packages - 2.2. Building from Source - 2.3. Keeping your Installation Up-to-Date + 2.1.1. Red Hat and Fedora RPMs -3. What's New in this Release + 2.1.2. Debian and Ubuntu - 3.1. Note to Upgraders + 2.1.3. Windows -4. Quickstart to Using Privoxy + 2.1.4. Solaris - 4.1. Quickstart to Ad Blocking + 2.1.5. OS/2 -5. Starting Privoxy + 2.1.6. Mac OSX - 5.1. Red Hat and Fedora - 5.2. Debian - 5.3. Windows - 5.4. Solaris, NetBSD, FreeBSD, HP-UX and others - 5.5. OS/2 - 5.6. Mac OSX - 5.7. AmigaOS - 5.8. Gentoo - 5.9. Command Line Options + 2.1.7. AmigaOS -6. Privoxy Configuration + 2.1.8. FreeBSD - 6.1. Controlling Privoxy with Your Web Browser - 6.2. Configuration Files Overview + 2.1.9. Gentoo -7. The Main Configuration File + 2.2. Building from Source - 7.1. Local Set-up Documentation + 2.3. Keeping your Installation Up-to-Date - 7.1.1. user-manual - 7.1.2. trust-info-url - 7.1.3. admin-address - 7.1.4. proxy-info-url + 3. What's New in this Release - 7.2. Configuration and Log File Locations + 3.1. Note to Upgraders - 7.2.1. confdir - 7.2.2. templdir - 7.2.3. logdir - 7.2.4. actionsfile - 7.2.5. filterfile - 7.2.6. logfile - 7.2.7. jarfile - 7.2.8. trustfile + 4. Quickstart to Using Privoxy - 7.3. Debugging + 4.1. Quickstart to Ad Blocking - 7.3.1. debug - 7.3.2. single-threaded + 5. Starting Privoxy - 7.4. Access Control and Security + 5.1. Red Hat and Fedora - 7.4.1. listen-address - 7.4.2. toggle - 7.4.3. enable-remote-toggle - 7.4.4. enable-remote-http-toggle - 7.4.5. enable-edit-actions - 7.4.6. enforce-blocks - 7.4.7. ACLs: permit-access and deny-access - 7.4.8. buffer-limit + 5.2. Debian - 7.5. Forwarding + 5.3. Windows - 7.5.1. forward - 7.5.2. forward-socks4 and forward-socks4a - 7.5.3. Advanced Forwarding Examples - 7.5.4. forwarded-connect-retries - 7.5.5. accept-intercepted-requests - 7.5.6. allow-cgi-request-crunching - 7.5.7. split-large-forms + 5.4. Solaris, NetBSD, FreeBSD, HP-UX and others - 7.6. Windows GUI Options + 5.5. OS/2 -8. Actions Files + 5.6. Mac OSX - 8.1. Finding the Right Mix - 8.2. How to Edit - 8.3. How Actions are Applied to Requests - 8.4. Patterns - - 8.4.1. The Domain Pattern - 8.4.2. The Path Pattern - 8.4.3. The Tag Pattern - - 8.5. Actions - - 8.5.1. add-header - 8.5.2. block - 8.5.3. client-header-filter - 8.5.4. client-header-tagger - 8.5.5. content-type-overwrite - 8.5.6. crunch-client-header - 8.5.7. crunch-if-none-match - 8.5.8. crunch-incoming-cookies - 8.5.9. crunch-server-header - 8.5.10. crunch-outgoing-cookies - 8.5.11. deanimate-gifs - 8.5.12. downgrade-http-version - 8.5.13. fast-redirects - 8.5.14. filter - 8.5.15. force-text-mode - 8.5.16. forward-override - 8.5.17. handle-as-empty-document - 8.5.18. handle-as-image - 8.5.19. hide-accept-language - 8.5.20. hide-content-disposition - 8.5.21. hide-if-modified-since - 8.5.22. hide-forwarded-for-headers - 8.5.23. hide-from-header - 8.5.24. hide-referrer - 8.5.25. hide-user-agent - 8.5.26. inspect-jpegs - 8.5.27. kill-popups - 8.5.28. limit-connect - 8.5.29. prevent-compression - 8.5.30. overwrite-last-modified - 8.5.31. redirect - 8.5.32. send-vanilla-wafer - 8.5.33. send-wafer - 8.5.34. server-header-filter - 8.5.35. server-header-tagger - 8.5.36. session-cookies-only - 8.5.37. set-image-blocker - 8.5.38. treat-forbidden-connects-like-blocks - 8.5.39. Summary - - 8.6. Aliases - 8.7. Actions Files Tutorial - - 8.7.1. default.action - 8.7.2. user.action + 5.7. AmigaOS -9. Filter Files + 5.8. Gentoo - 9.1. Filter File Tutorial - 9.2. The Pre-defined Filters + 5.9. Command Line Options -10. Privoxy's Template Files -11. Contacting the Developers, Bug Reporting and Feature Requests + 6. Privoxy Configuration - 11.1. Get Support - 11.2. Reporting Problems + 6.1. Controlling Privoxy with Your Web Browser - 11.2.1. Reporting Ads or Other Configuration Problems - 11.2.2. Reporting Bugs + 6.2. Configuration Files Overview - 11.3. Request New Features - 11.4. Other + 7. The Main Configuration File -12. Privoxy Copyright, License and History + 7.1. Local Set-up Documentation - 12.1. License - 12.2. History - 12.3. Authors + 7.1.1. user-manual -13. See Also -14. Appendix + 7.1.2. trust-info-url - 14.1. Regular Expressions - 14.2. Privoxy's Internal Pages + 7.1.3. admin-address - 14.2.1. Bookmarklets + 7.1.4. proxy-info-url - 14.3. Chain of Events - 14.4. Troubleshooting: Anatomy of an Action + 7.2. Configuration and Log File Locations -1. Introduction + 7.2.1. confdir -This documentation is included with the current stable version of Privoxy, -v.3.0.8. + 7.2.2. templdir -------------------------------------------------------------------------------- + 7.2.3. logdir -1.1. Features + 7.2.4. actionsfile -In addition to the core features of ad blocking and cookie management, Privoxy -provides many supplemental features, that give the end-user more control, more -privacy and more freedom: + 7.2.5. filterfile - * Can be run as an "intercepting" proxy, which obviates the need to configure - browsers individually. + 7.2.6. logfile - * Sophisticated actions and filters for manipulating both server and client - headers. + 7.2.7. jarfile - * Can be chained with other proxies. + 7.2.8. trustfile - * Integrated browser based configuration and control utility at http:// - config.privoxy.org/ (shortcut: http://p.p/). Browser-based tracing of rule - and filter effects. Remote toggling. + 7.3. Debugging - * Web page filtering (text replacements, removes banners based on size, - invisible "web-bugs", JavaScript and HTML annoyances, pop-up windows, etc.) + 7.3.1. debug - * Modularized configuration that allows for standard settings and user - settings to reside in separate files, so that installing updated actions - files won't overwrite individual user settings. + 7.3.2. single-threaded - * Support for Perl Compatible Regular Expressions in the configuration files, - and a more sophisticated and flexible configuration syntax. + 7.4. Access Control and Security - * Improved cookie management features (e.g. session based cookies). + 7.4.1. listen-address - * GIF de-animation. + 7.4.2. toggle - * Bypass many click-tracking scripts (avoids script redirection). + 7.4.3. enable-remote-toggle - * Multi-threaded (POSIX and native threads). + 7.4.4. enable-remote-http-toggle - * User-customizable HTML templates for all proxy-generated pages (e.g. - "blocked" page). + 7.4.5. enable-edit-actions - * Auto-detection and re-reading of config file changes. + 7.4.6. enforce-blocks - * Improved signal handling, and a true daemon mode (Unix). + 7.4.7. ACLs: permit-access and deny-access - * Every feature now controllable on a per-site or per-location basis, - configuration more powerful and versatile over-all. + 7.4.8. buffer-limit - * Many smaller new features added, limitations and bugs removed, and security - holes fixed. + 7.5. Forwarding -------------------------------------------------------------------------------- + 7.5.1. forward -2. Installation + 7.5.2. forward-socks4 and forward-socks4a -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. + 7.5.3. Advanced Forwarding Examples -Note: On some platforms, the installer may remove previously installed -versions, if found. (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. + 7.5.4. forwarded-connect-retries -------------------------------------------------------------------------------- + 7.5.5. accept-intercepted-requests -2.1. Binary Packages + 7.5.6. allow-cgi-request-crunching -How to install the binary packages depends on your operating system: + 7.5.7. split-large-forms -------------------------------------------------------------------------------- + 7.6. Windows GUI Options -2.1.1. Red Hat and Fedora RPMs + 8. Actions Files -RPMs can be installed with rpm -Uvh privoxy-3.0.8-1.rpm, and will use /etc/ -privoxy for the location of configuration files. + 8.1. Finding the Right Mix -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. + 8.2. How to Edit -If you have problems with failed dependencies, try rebuilding the SRC RPM: rpm ---rebuild privoxy-3.0.8-1.src.rpm. This will use your locally installed -libraries and RPM version. + 8.3. How Actions are Applied to Requests -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 if found, before installing Privoxy. + 8.4. Patterns -------------------------------------------------------------------------------- + 8.4.1. The Domain Pattern -2.1.2. Debian and Ubuntu + 8.4.2. The Path Pattern -DEBs can be installed with apt-get install privoxy, and will use /etc/privoxy -for the location of configuration files. + 8.4.3. The Tag Pattern -------------------------------------------------------------------------------- + 8.5. Actions -2.1.3. Windows + 8.5.1. add-header -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. + 8.5.2. block -Version 3.0.5 beta introduced full Windows service functionality. On Windows -only, the Privoxy program has two new command line arguments to install and -uninstall Privoxy as a service. + 8.5.3. client-header-filter -Arguments: + 8.5.4. client-header-tagger - --install[:service_name] + 8.5.5. content-type-overwrite - --uninstall[:service_name] + 8.5.6. crunch-client-header -After invoking Privoxy with --install, you will need to bring up the Windows -service console to assign the user you want Privoxy to run under, and whether -or not you want it to run whenever the system starts. You can start the Windows -services console with the following command: services.msc. If you do not take -the manual step of modifying Privoxy's service settings, it will not start. -Note too that you will need to give Privoxy a user account that actually -exists, or it will not be permitted to write to its log and configuration -files. + 8.5.7. crunch-if-none-match -------------------------------------------------------------------------------- + 8.5.8. crunch-incoming-cookies -2.1.4. Solaris + 8.5.9. crunch-server-header -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. + 8.5.10. crunch-outgoing-cookies -------------------------------------------------------------------------------- + 8.5.11. deanimate-gifs -2.1.5. OS/2 + 8.5.12. downgrade-http-version -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. + 8.5.13. fast-redirects -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. + 8.5.14. filter -The directory you choose to install Privoxy into will contain all of the -configuration files. + 8.5.15. force-text-mode -------------------------------------------------------------------------------- + 8.5.16. forward-override -2.1.6. Mac OSX + 8.5.17. handle-as-empty-document -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. + 8.5.18. handle-as-image -To start Privoxy by hand, double-click on StartPrivoxy.command in the /Library/ -Privoxy folder. Or, type this command in the Terminal: + 8.5.19. hide-accept-language - /Library/Privoxy/StartPrivoxy.command + 8.5.20. hide-content-disposition + 8.5.21. hide-if-modified-since + 8.5.22. hide-forwarded-for-headers -You will be prompted for the administrator password. + 8.5.23. hide-from-header -------------------------------------------------------------------------------- + 8.5.24. hide-referrer -2.1.7. AmigaOS + 8.5.25. hide-user-agent -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. + 8.5.26. inspect-jpegs -------------------------------------------------------------------------------- + 8.5.27. kill-popups -2.1.8. FreeBSD + 8.5.28. limit-connect -Privoxy is part of FreeBSD's Ports Collection, you can build and install it -with cd /usr/ports/www/privoxy; make install clean. + 8.5.29. prevent-compression -If you don't use the ports, you can fetch and install the package with pkg_add --r privoxy. + 8.5.30. overwrite-last-modified -The port skeleton and the package can also be downloaded from the File Release -Page, but there's no reason to use them unless you're interested in the beta -releases which are only available there. + 8.5.31. redirect -------------------------------------------------------------------------------- + 8.5.32. send-vanilla-wafer -2.1.9. Gentoo + 8.5.33. send-wafer -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). + 8.5.34. server-header-filter -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. + 8.5.35. server-header-tagger -Configuration files are in /etc/privoxy, the documentation is in /usr/share/doc -/privoxy-3.0.8 and the Log directory is in /var/log/privoxy. + 8.5.36. session-cookies-only -------------------------------------------------------------------------------- + 8.5.37. set-image-blocker -2.2. Building from Source + 8.5.38. treat-forbidden-connects-like-blocks -The most convenient way to obtain the Privoxy sources is to download the source -tarball from our project download page. + 8.5.39. Summary -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. + 8.6. Aliases -To build Privoxy from source, autoconf, GNU make (gmake), and, of course, a C -compiler like gcc are required. + 8.7. Actions Files Tutorial -When building from a source tarball, first unpack the source: + 8.7.1. default.action - tar xzvf privoxy-3.0.8-src* [.tgz or .tar.gz] - cd privoxy-3.0.8 + 8.7.2. user.action + 9. Filter Files -For retrieving the current CVS sources, you'll need a CVS client installed. -Note that sources from CVS are typically development quality, and may not be -stable, or well tested. To download CVS source, check the Sourceforge -documentation, which might give commands like: + 9.1. Filter File Tutorial - cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current - cd current + 9.2. The Pre-defined Filters + 10. Privoxy's Template Files -This will create a directory named current/, which will contain the source -tree. + 11. Contacting the Developers, Bug Reporting and Feature Requests -You can also check out any Privoxy "branch", just exchange the current name -with the wanted branch name (Example: v_3_0_branch for the 3.0 cvs tree). + 11.1. Get Support -It is also strongly recommended to not run Privoxy as root. You should -configure/install/run Privoxy as an unprivileged user, preferably by creating a -"privoxy" user and group just for this purpose. See your local documentation -for the correct command line to do add new users and groups (something like -adduser, but the command syntax may vary from platform to platform). + 11.2. Reporting Problems -/etc/passwd might then look like: + 11.2.1. Reporting Ads or Other Configuration + Problems - privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell + 11.2.2. Reporting Bugs + 11.3. Request New Features -And then /etc/group, like: + 11.4. Other - privoxy:*:7777: + 12. Privoxy Copyright, License and History + 12.1. License -Some binary packages may do this for you. + 12.2. History -Then, to build from either unpacked tarball or CVS source: + 12.3. Authors - autoheader - autoconf - ./configure # (--help to see options) - make # (the make from GNU, sometimes called gmake) - su # Possibly required - make -n install # (to see where all the files will go) - make -s install # (to really install, -s to silence output) + 13. See Also + 14. Appendix -Using GNU make, you can have the first four steps automatically done for you by -just typing: + 14.1. Regular Expressions - make + 14.2. Privoxy's Internal Pages + 14.2.1. Bookmarklets -in the freshly downloaded or unpacked source directory. + 14.3. Chain of Events -To build an executable with security enhanced features so that users cannot -easily bypass the proxy (e.g. "Go There Anyway"), or alter their own -configurations, configure like this: + 14.4. Troubleshooting: Anatomy of an Action - ./configure --disable-toggle --disable-editor --disable-force +1. Introduction + This documentation is included with the current stable version of Privoxy, + v.3.0.8. -Then build as above. In Privoxy 3.0.7 and later, all of these options can also -be disabled through the configuration file. + -------------------------------------------------------------------------- -WARNING: If installing as root, the install will fail unless a non-root user or -group is specified, or a privoxy user and group already exist on the system. If -a non-root user is specified, and no group, then the installation will try to -also use a group of the same name as "user". If a group is specified (and no -user), then the support files will be installed as writable by that group, and -owned by the user running the installation. + 1.1. Features -configure accepts --with-user and --with-group options for setting user and -group ownership of the configuration files (which need to be writable by the -daemon). The specified user must already exist. When starting Privoxy, it must -be run as this same user to insure write access to configuration and log files! + In addition to the core features of ad blocking and cookie management, + Privoxy provides many supplemental features, that give the end-user more + control, more privacy and more freedom: -Alternately, you can specify user and group on the make command line, but be -sure both already exist: + * Can be run as an "intercepting" proxy, which obviates the need to + configure browsers individually. - make -s install USER=privoxy GROUP=privoxy + * Sophisticated actions and filters for manipulating both server and + client headers. + * Can be chained with other proxies. -The default installation path for make install is /usr/local. This may of -course be customized with the various ./configure path options. If you are -doing an install to anywhere besides /usr/local, be sure to set the appropriate -paths with the correct configure options (./configure --help). Non-privileged -users must of course have write access permissions to wherever the target -installation is going. + * Integrated browser based configuration and control utility at + http://config.privoxy.org/ (shortcut: http://p.p/). Browser-based + tracing of rule and filter effects. Remote toggling. -If you do install to /usr/local, the install will use sysconfdir=$prefix/etc/ -privoxy by default. All other destinations, and the direct usage of ---sysconfdir flag behave like normal, i.e. will not add the extra privoxy -directory. This is for a safer install, as there may already exist another -program that uses a file with the "config" name, and thus makes /usr/local/etc -cleaner. + * Web page filtering (text replacements, removes banners based on size, + invisible "web-bugs", JavaScript and HTML annoyances, pop-up windows, + etc.) -If installing to /usr/local, the documentation will go by default to $prefix/ -share/doc. But if this directory doesn't exist, it will then try $prefix/doc -and install there before creating a new $prefix/share/doc just for Privoxy. + * Modularized configuration that allows for standard settings and user + settings to reside in separate files, so that installing updated + actions files won't overwrite individual user settings. -Again, if the installs goes to /usr/local, the localstatedir (ie: var/) will -default to /var instead of $prefix/var so the logs will go to /var/log/privoxy -/, and the pid file will be created in /var/run/privoxy.pid. + * Support for Perl Compatible Regular Expressions in the configuration + files, and a more sophisticated and flexible configuration syntax. -make install will attempt to set the correct values in config (main -configuration file). You should check this to make sure all values are correct. -If appropriate, an init script will be installed, but it is up to the user to -determine how and where to start Privoxy. The init script should be checked for -correct paths and values, if anything other than a default install is done. + * Improved cookie management features (e.g. session based cookies). -If install finds previous versions of local configuration files, most of these -will not be overwritten, and the new ones will be installed with a "new" -extension. default.action, default.filter, and standard.action will be -overwritten. You will then need to manually update the other installed -configuration files as needed. The default template files will be overwritten. -If you have customized, local templates, these should be stored safely in a -separate directory and defined in config by the "templdir" directive. It is of -course wise to always back-up any important configuration files "just in case". -If a previous version of Privoxy is already running, you will have to restart -it manually. + * GIF de-animation. -For more detailed instructions on how to build Redhat RPMs, Windows -self-extracting installers, building on platforms with special requirements -etc, please consult the developer manual. + * Bypass many click-tracking scripts (avoids script redirection). -------------------------------------------------------------------------------- + * Multi-threaded (POSIX and native threads). -2.3. Keeping your Installation Up-to-Date + * User-customizable HTML templates for all proxy-generated pages (e.g. + "blocked" page). -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. + * Auto-detection and re-reading of config file changes. -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. + * Improved signal handling, and a true daemon mode (Unix). -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 and -user.filter for your local customizations of Privoxy. See the Chapter on -actions files for details. + * Every feature now controllable on a per-site or per-location basis, + configuration more powerful and versatile over-all. -------------------------------------------------------------------------------- + * Many smaller new features added, limitations and bugs removed, and + security holes fixed. -3. What's New in this Release + -------------------------------------------------------------------------- -There are many improvements and new features since Privoxy 3.0.6, the last -stable release: +2. Installation - * Two new actions server-header-tagger and client-header-tagger that can be - used to create arbitrary "tags" based on client and server headers. These - "tags" can then subsequently be used to control the other actions used for - the current request, greatly increasing Privoxy's flexibility and - selectivity. See tag patterns for more information on tags. + 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. - * Header filtering is done with dedicated header filters now. As a result the - actions "filter-client-headers" and "filter-server-headers" that were - introduced with Privoxy 3.0.5 to apply content filters to the headers have - been removed. See the new actions server-header-filter and - client-header-filter for details. + Note: On some platforms, the installer may remove previously installed + versions, if found. (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. - * There are four new options for the main config file: + -------------------------------------------------------------------------- - + allow-cgi-request-crunching which allows requests for Privoxy's - internal CGI pages to be blocked, redirected or (un)trusted like - ordinary requests. + 2.1. Binary Packages - + split-large-forms that will work around a browser bug that caused IE6 - and IE7 to ignore the Submit button on the Privoxy's - edit-actions-for-url CGI page. + How to install the binary packages depends on your operating system: - + accept-intercepted-requests which allows to combine Privoxy with any - packet filter to create an intercepting proxy for HTTP/1.1 requests - (and for HTTP/1.0 requests with Host header set). This means clients - can be forced to use Privoxy even if their proxy settings are - configured differently. + -------------------------------------------------------------------------- - + templdir to designate an alternate location for Privoxy's locally - customized CGI templates so that these are not overwritten during - upgrades. + 2.1.1. Red Hat and Fedora RPMs - * A new command line option --pre-chroot-nslookup hostname to initialize the - resolver library before chroot'ing. On some systems this reduces the number - of files that must be copied into the chroot tree. (Patch provided by - Stephen Gildea) + RPMs can be installed with rpm -Uvh privoxy-3.0.8-1.rpm, and will use + /etc/privoxy for the location of configuration files. - * The forward-override action allows changing of the forwarding settings - through the actions files. Combined with tags, this allows to choose the - forwarder based on client headers like the User-Agent, or the request - origin. + 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. - * The redirect action can now use regular expression substitutions against - the original URL. + If you have problems with failed dependencies, try rebuilding the SRC RPM: + rpm --rebuild privoxy-3.0.8-1.src.rpm. This will use your locally + installed libraries and RPM version. - * zlib support is now available as a compile time option to filter compressed - content. Patch provided by Wil Mahan. + 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 if found, before installing + Privoxy. - * Improve various filters, and add new ones. + -------------------------------------------------------------------------- - * Include support for RFC 3253 so that Subversion works with Privoxy. Patch - provided by Petr Kadlec. + 2.1.2. Debian and Ubuntu - * Logging can be completely turned off by not specifying a logfile directive. + DEBs can be installed with apt-get install privoxy, and will use + /etc/privoxy for the location of configuration files. - * A number of improvements to Privoxy's internal CGI pages, including the use - of favicons for error and control pages. + -------------------------------------------------------------------------- - * Many bugfixes, memory leaks addressed, code improvements, and logging - improvements. + 2.1.3. Windows -For a more detailed list of changes please have a look at the ChangeLog. + 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. -------------------------------------------------------------------------------- + Version 3.0.5 beta introduced full Windows service functionality. On + Windows only, the Privoxy program has two new command line arguments to + install and uninstall Privoxy as a service. -3.1. Note to Upgraders + Arguments: -A quick list of things to be aware of before upgrading from earlier versions of -Privoxy: + --install[:service_name] - * The recommended way to upgrade Privoxy is to backup your old configuration - files, install the new ones, verify that Privoxy is working correctly and - finally merge back your changes using diff and maybe patch. + --uninstall[:service_name] - There are a number of new features in each Privoxy release and most of them - have to be explicitly enabled in the configuration files. Old configuration - files obviously don't do that and due to syntax changes using old - configuration files with a new Privoxy isn't always possible anyway. + After invoking Privoxy with --install, you will need to bring up the + Windows service console to assign the user you want Privoxy to run under, + and whether or not you want it to run whenever the system starts. You can + start the Windows services console with the following command: + services.msc. If you do not take the manual step of modifying Privoxy's + service settings, it will not start. Note too that you will need to give + Privoxy a user account that actually exists, or it will not be permitted + to write to its log and configuration files. - * Note that some installers remove earlier versions completely, including - configuration files, therefore you should really save any important - configuration files! + -------------------------------------------------------------------------- - * On the other hand, other installers don't overwrite existing configuration - files, thinking you will want to do that yourself. + 2.1.4. Solaris - * standard.action now only includes the enabled actions. Not all actions as - before. + 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. - * In the default configuration only fatal errors are logged now. You can - change that in the debug section of the configuration file. You may also - want to enable more verbose logging until you verified that the new Privoxy - version is working as expected. + -------------------------------------------------------------------------- - * Three other config file settings are now off by default: - enable-remote-toggle, enable-remote-http-toggle, and enable-edit-actions. - If you use or want these, you will need to explicitly enable them, and be - aware of the security issues involved. + 2.1.5. OS/2 - * The "filter-client-headers" and "filter-server-headers" actions that were - introduced with Privoxy 3.0.5 to apply content filters to the headers have - been removed and replaced with new actions. See the What's New section - above. + 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. -------------------------------------------------------------------------------- + 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. -4. Quickstart to Using Privoxy + The directory you choose to install Privoxy into will contain all of the + configuration files. - * Install Privoxy. See the Installation Section below for platform specific - information. - - * 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. - - * Start Privoxy, if the installation program has not done this already (may - vary according to platform). See the section Starting Privoxy. - - * 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. DO NOT - activate proxying for FTP or any protocols besides HTTP and HTTPS (SSL) - unless you intend to prevent your browser from using these protocols. - - * 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, you may want to enable the - web-based action editor though. Be sure to read the warnings first. - - See the Configuration section for more configuration options, and how to - customize your installation. You might also want to look at the next - section for a quick introduction to how Privoxy blocks ads and banners. - - * If you experience ads that slip through, innocent images that are blocked, - or otherwise feel the need to fine-tune Privoxy's behavior, 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 "Troubleshooting: Anatomy of an - Action" has hints on how to understand and debug actions that "misbehave". - - * Please see the section Contacting the Developers on how to report bugs, - problems with websites or to get help. - - * Now enjoy surfing with enhanced control, comfort and privacy! - -------------------------------------------------------------------------------- - -4.1. Quickstart to Ad Blocking - -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. - -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. - -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. And the more likely that some things may not work as 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. - -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. - -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. - -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. Privoxy can deal with each URL individually, so, for instance, the main -page text is not touched, but images from such-and-such server are blocked. - -The most important actions for basic ad blocking are: block, handle-as-image, -handle-as-empty-document,and set-image-blocker: - - * block - this is perhaps the single most used action, and is particularly - important for ad blocking. 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 (with some exceptions, see below). - - * 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. - - * handle-as-empty-document - sends an empty document instead of Privoxy's - normal BLOCKED HTML page. This is useful for file types that are neither - HTML nor images, such as blocking JavaScript files. - - * 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). - -Advanced users will eventually want to explore Privoxy filters as well. Filters -are very different from blocks. A "block" blocks a site, page, or unwanted -contented. Filters are a way of filtering or modifying what is actually on the -page. An example filter usage: a text replacement of "no-no" for "nasty-word". -That is a very simple example. This process can be used for ad blocking, but it -is more in the realm of advanced usage and has some pitfalls to be wary off. - -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. - -Note that as of Privoxy 3.0.7 beta the action editor is disabled by default. -Check the enable-edit-actions section in the configuration file to learn why -and in which cases it's safe to enable again. - -If you decided to enable the action editor, 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. - -A quick and simple step by step example: - - * 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": - - Figure 1. Actions Files in Use - - [files-in-u] - - * 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. - -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. + -------------------------------------------------------------------------- -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. + 2.1.6. Mac OSX -There are also various filters that can be used for ad blocking (filters are a -special subset of actions). These fall into the "advanced" usage category, and -are explained in depth in later sections. + 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 start Privoxy by hand, double-click on StartPrivoxy.command in the + /Library/Privoxy folder. Or, type this command in the Terminal: -5. Starting Privoxy + /Library/Privoxy/StartPrivoxy.command -Before launching Privoxy for the first time, you will want to configure your -browser(s) to use Privoxy as a HTTP and HTTPS (SSL) 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! -Please note that Privoxy can only proxy HTTP and HTTPS traffic. It will not -work with FTP or other protocols. + You will be prompted for the administrator password. -Figure 2. Proxy Configuration Showing Mozilla/Netscape HTTP and HTTPS (SSL) -Settings + -------------------------------------------------------------------------- -[proxy_setu] + 2.1.7. AmigaOS -With Firefox, this is typically set under: + 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. - Tools -> Options -> Advanced -> Network ->Connection -> Settings - + -------------------------------------------------------------------------- -Or optionally on some platforms: + 2.1.8. FreeBSD - Edit -> Preferences -> General -> Connection Settings -> Manual Proxy -Configuration - + Privoxy is part of FreeBSD's Ports Collection, you can build and install + it with cd /usr/ports/www/privoxy; make install clean. -With Netscape (and Mozilla), this can be set under: + If you don't use the ports, you can fetch and install the package with + pkg_add -r privoxy. - Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy - + The port skeleton and the package can also be downloaded from the File + Release Page, but there's no reason to use them unless you're interested + in the beta releases which are only available there. -For Internet Explorer v.5-6: + -------------------------------------------------------------------------- - Tools -> Internet Options -> Connections -> LAN Settings + 2.1.9. Gentoo -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 -(sometimes labeled "Secure"). Make sure any checkboxes like "Use the same proxy -server for all protocols" is UNCHECKED. You want only HTTP and HTTPS (SSL)! + 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). -Figure 3. Proxy Configuration Showing Internet Explorer HTTP and HTTPS (Secure) -Settings + 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. -[proxy2] + Configuration files are in /etc/privoxy, the documentation is in + /usr/share/doc/privoxy-3.0.8 and the Log directory is in /var/log/privoxy. -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. Remove -any cookies, if you want Privoxy to manage that. You are now ready to start -enjoying the benefits of using Privoxy! + -------------------------------------------------------------------------- -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. + 2.2. Building from Source -------------------------------------------------------------------------------- + The most convenient way to obtain the Privoxy sources is to download the + source tarball from our project download page. -5.1. Red Hat and Fedora + 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. -A default Red Hat installation may not start Privoxy upon boot. It will use the -file /etc/privoxy/config as its main configuration file. + To build Privoxy from source, autoconf, GNU make (gmake), and, of course, + a C compiler like gcc are required. - # /etc/rc.d/init.d/privoxy start + When building from a source tarball, first unpack the source: + tar xzvf privoxy-3.0.8-src* [.tgz or .tar.gz] + cd privoxy-3.0.8 -Or ... + For retrieving the current CVS sources, you'll need a CVS client + installed. Note that sources from CVS are typically development quality, + and may not be stable, or well tested. To download CVS source, check the + Sourceforge documentation, which might give commands like: - # service privoxy start + cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login + cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current + cd current + This will create a directory named current/, which will contain the source + tree. -------------------------------------------------------------------------------- + You can also check out any Privoxy "branch", just exchange the current + name with the wanted branch name (Example: v_3_0_branch for the 3.0 cvs + tree). + + It is also strongly recommended to not run Privoxy as root. You should + configure/install/run Privoxy as an unprivileged user, preferably by + creating a "privoxy" user and group just for this purpose. See your local + documentation for the correct command line to do add new users and groups + (something like adduser, but the command syntax may vary from platform to + platform). -5.2. Debian + /etc/passwd might then look like: -We use a script. Note that Debian typically starts Privoxy upon booting per -default. It will use the file /etc/privoxy/config as its main configuration -file. + privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell - # /etc/init.d/privoxy start + And then /etc/group, like: + privoxy:*:7777: -------------------------------------------------------------------------------- + Some binary packages may do this for you. -5.3. Windows + Then, to build from either unpacked tarball or CVS source: -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 when the system starts if -you chose that option when installing. + autoheader + autoconf + ./configure # (--help to see options) + make # (the make from GNU, sometimes called gmake) + su # Possibly required + make -n install # (to see where all the files will go) + make -s install # (to really install, -s to silence output) -Privoxy can run with full Windows service functionality. On Windows only, the -Privoxy program has two new command line arguments to install and uninstall -Privoxy as a service. See the Windows Installation instructions for details. + Using GNU make, you can have the first four steps automatically done for + you by just typing: -------------------------------------------------------------------------------- + make -5.4. Solaris, NetBSD, FreeBSD, HP-UX and others + in the freshly downloaded or unpacked source directory. -Example Unix startup command: + To build an executable with security enhanced features so that users + cannot easily bypass the proxy (e.g. "Go There Anyway"), or alter their + own configurations, configure like this: - # /usr/sbin/privoxy /etc/privoxy/config + ./configure --disable-toggle --disable-editor --disable-force + Then build as above. In Privoxy 3.0.7 and later, all of these options can + also be disabled through the configuration file. -------------------------------------------------------------------------------- + WARNING: If installing as root, the install will fail unless a non-root + user or group is specified, or a privoxy user and group already exist on + the system. If a non-root user is specified, and no group, then the + installation will try to also use a group of the same name as "user". If a + group is specified (and no user), then the support files will be installed + as writable by that group, and owned by the user running the installation. -5.5. OS/2 + configure accepts --with-user and --with-group options for setting user + and group ownership of the configuration files (which need to be writable + by the daemon). The specified user must already exist. When starting + Privoxy, it must be run as this same user to insure write access to + configuration and log files! -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. + Alternately, you can specify user and group on the make command line, but + be sure both already exist: -------------------------------------------------------------------------------- + make -s install USER=privoxy GROUP=privoxy -5.6. Mac OSX + The default installation path for make install is /usr/local. This may of + course be customized with the various ./configure path options. If you are + doing an install to anywhere besides /usr/local, be sure to set the + appropriate paths with the correct configure options (./configure --help). + Non-privileged users must of course have write access permissions to + wherever the target installation is going. -During installation, Privoxy is configured to start automatically when the -system restarts. To start Privoxy manually, double-click on the -StartPrivoxy.command icon in the /Library/Privoxy folder. Or, type this command -in the Terminal: + If you do install to /usr/local, the install will use + sysconfdir=$prefix/etc/privoxy by default. All other destinations, and the + direct usage of --sysconfdir flag behave like normal, i.e. will not add + the extra privoxy directory. This is for a safer install, as there may + already exist another program that uses a file with the "config" name, and + thus makes /usr/local/etc cleaner. - /Library/Privoxy/StartPrivoxy.command + If installing to /usr/local, the documentation will go by default to + $prefix/share/doc. But if this directory doesn't exist, it will then try + $prefix/doc and install there before creating a new $prefix/share/doc just + for Privoxy. + Again, if the installs goes to /usr/local, the localstatedir (ie: var/) + will default to /var instead of $prefix/var so the logs will go to + /var/log/privoxy/, and the pid file will be created in + /var/run/privoxy.pid. + make install will attempt to set the correct values in config (main + configuration file). You should check this to make sure all values are + correct. If appropriate, an init script will be installed, but it is up to + the user to determine how and where to start Privoxy. The init script + should be checked for correct paths and values, if anything other than a + default install is done. -You will be prompted for the administrator password. + If install finds previous versions of local configuration files, most of + these will not be overwritten, and the new ones will be installed with a + "new" extension. default.action, default.filter, and standard.action will + be overwritten. You will then need to manually update the other installed + configuration files as needed. The default template files will be + overwritten. If you have customized, local templates, these should be + stored safely in a separate directory and defined in config by the + "templdir" directive. It is of course wise to always back-up any important + configuration files "just in case". If a previous version of Privoxy is + already running, you will have to restart it manually. -------------------------------------------------------------------------------- + For more detailed instructions on how to build Redhat RPMs, Windows + self-extracting installers, building on platforms with special + requirements etc, please consult the developer manual. -5.7. AmigaOS + -------------------------------------------------------------------------- -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). + 2.3. Keeping your Installation Up-to-Date -------------------------------------------------------------------------------- + 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. + + 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. + + 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 and user.filter for your local customizations of Privoxy. See + the Chapter on actions files for details. + + -------------------------------------------------------------------------- -5.8. Gentoo +3. What's New in this Release -A script is again used. It will use the file /etc/privoxy/config as its main -configuration file. + There are many improvements and new features since Privoxy 3.0.6, the last + stable release: - /etc/init.d/privoxy start + * Two new actions server-header-tagger and client-header-tagger that can + be used to create arbitrary "tags" based on client and server headers. + These "tags" can then subsequently be used to control the other + actions used for the current request, greatly increasing Privoxy's + flexibility and selectivity. See tag patterns for more information on + tags. + * Header filtering is done with dedicated header filters now. As a + result the actions "filter-client-headers" and "filter-server-headers" + that were introduced with Privoxy 3.0.5 to apply content filters to + the headers have been removed. See the new actions + server-header-filter and client-header-filter for details. + * There are four new options for the main config file: -Note that Privoxy is not automatically started at boot time by default. You can -change this with the rc-update command. + * allow-cgi-request-crunching which allows requests for Privoxy's + internal CGI pages to be blocked, redirected or (un)trusted like + ordinary requests. - rc-update add privoxy default + * split-large-forms that will work around a browser bug that caused + IE6 and IE7 to ignore the Submit button on the Privoxy's + edit-actions-for-url CGI page. + * accept-intercepted-requests which allows to combine Privoxy with + any packet filter to create an intercepting proxy for HTTP/1.1 + requests (and for HTTP/1.0 requests with Host header set). This + means clients can be forced to use Privoxy even if their proxy + settings are configured differently. + * templdir to designate an alternate location for Privoxy's locally + customized CGI templates so that these are not overwritten during + upgrades. -------------------------------------------------------------------------------- + * A new command line option --pre-chroot-nslookup hostname to initialize + the resolver library before chroot'ing. On some systems this reduces + the number of files that must be copied into the chroot tree. (Patch + provided by Stephen Gildea) -5.9. Command Line Options + * The forward-override action allows changing of the forwarding settings + through the actions files. Combined with tags, this allows to choose + the forwarder based on client headers like the User-Agent, or the + request origin. -Privoxy may be invoked with the following command-line options: + * The redirect action can now use regular expression substitutions + against the original URL. - * --version + * zlib support is now available as a compile time option to filter + compressed content. Patch provided by Wil Mahan. - Print version info and exit. Unix only. + * Improve various filters, and add new ones. - * --help + * Include support for RFC 3253 so that Subversion works with Privoxy. + Patch provided by Petr Kadlec. - Print short usage info and exit. Unix only. + * Logging can be completely turned off by not specifying a logfile + directive. - * --no-daemon + * A number of improvements to Privoxy's internal CGI pages, including + the use of favicons for error and control pages. - Don't become a daemon, i.e. don't fork and become process group leader, and - don't detach from controlling tty. Unix only. + * Many bugfixes, memory leaks addressed, code improvements, and logging + improvements. - * --pidfile FILE + For a more detailed list of changes please have a look at the ChangeLog. - 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] + 3.1. Note to Upgraders - 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. + A quick list of things to be aware of before upgrading from earlier + versions of Privoxy: - * --chroot + * The recommended way to upgrade Privoxy is to backup your old + configuration files, install the new ones, verify that Privoxy is + working correctly and finally merge back your changes using diff and + maybe patch. - 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. + There are a number of new features in each Privoxy release and most of + them have to be explicitly enabled in the configuration files. Old + configuration files obviously don't do that and due to syntax changes + using old configuration files with a new Privoxy isn't always possible + anyway. - * --pre-chroot-nslookup hostname + * Note that some installers remove earlier versions completely, + including configuration files, therefore you should really save any + important configuration files! - Specifies a hostname to look up before doing a chroot. On some systems, - initializing the resolver library involves reading config files from /etc - and/or loading additional shared libraries from /lib. On these systems, - doing a hostname lookup before the chroot reduces the number of files that - must be copied into the chroot tree. + * On the other hand, other installers don't overwrite existing + configuration files, thinking you will want to do that yourself. - For fastest startup speed, a good value is a hostname that is not in /etc/ - hosts but that your local name server (listed in /etc/resolv.conf) can - resolve without recursion (that is, without having to ask any other name - servers). The hostname need not exist, but if it doesn't, an error message - (which can be ignored) will be output. + * standard.action now only includes the enabled actions. Not all actions + as before. - * configfile + * In the default configuration only fatal errors are logged now. You can + change that in the debug section of the configuration file. You may + also want to enable more verbose logging until you verified that the + new Privoxy version is working as expected. - 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. + * Three other config file settings are now off by default: + enable-remote-toggle, enable-remote-http-toggle, and + enable-edit-actions. If you use or want these, you will need to + explicitly enable them, and be aware of the security issues involved. -On MS Windows only there are two additional command-line options to allow -Privoxy to install and run as a service. See the Window Installation section -for details. + * The "filter-client-headers" and "filter-server-headers" actions that + were introduced with Privoxy 3.0.5 to apply content filters to the + headers have been removed and replaced with new actions. See the + What's New section above. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -6. Privoxy Configuration +4. Quickstart to Using Privoxy -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. - -------------------------------------------------------------------------------- - -6.1. Controlling Privoxy with Your Web Browser - -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: - - Privoxy Menu - ? 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 - - -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. - -"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. - -Note that several of the features described above are disabled by default in -Privoxy 3.0.7 beta and later. Check the configuration file to learn why and in -which cases it's safe to enable them again. - -------------------------------------------------------------------------------- - -6.2. 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 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 main configuration file is named config on Linux, Unix, BSD, OS/2, and - AmigaOS and config.txt on Windows. This is a required file. - - * 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 only 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. - - * "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. - -The syntax of the configuration and filter files may change between different -Privoxy versions, unfortunately some enhancements cost backwards compatibility. - -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. Blank lines are ignored. - -The actions files and filter files can use Perl style regular expressions for -maximum flexibility. - -After making any changes, there is no need to restart Privoxy in order for the -changes to take effect. Privoxy 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. - -------------------------------------------------------------------------------- + * Install Privoxy. See the Installation Section below for platform + specific information. + + * 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. + + * Start Privoxy, if the installation program has not done this already + (may vary according to platform). See the section Starting Privoxy. + + * 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. DO NOT activate proxying for FTP or any protocols besides HTTP + and HTTPS (SSL) unless you intend to prevent your browser from using + these protocols. + + * 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, + you may want to enable the web-based action editor though. Be sure to + read the warnings first. + + See the Configuration section for more configuration options, and how + to customize your installation. You might also want to look at the + next section for a quick introduction to how Privoxy blocks ads and + banners. + + * If you experience ads that slip through, innocent images that are + blocked, or otherwise feel the need to fine-tune Privoxy's behavior, + 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 + "Troubleshooting: Anatomy of an Action" has hints on how to understand + and debug actions that "misbehave". + + * Please see the section Contacting the Developers on how to report + bugs, problems with websites or to get help. + + * Now enjoy surfing with enhanced control, comfort and privacy! + + -------------------------------------------------------------------------- + + 4.1. Quickstart to Ad Blocking + + 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. + + 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. + + 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. And the more likely that some things may not work + as 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. + + 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. + + 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. + + 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. Privoxy can deal with each URL individually, + so, for instance, the main page text is not touched, but images from + such-and-such server are blocked. + + The most important actions for basic ad blocking are: block, + handle-as-image, handle-as-empty-document,and set-image-blocker: + + * block - this is perhaps the single most used action, and is + particularly important for ad blocking. 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 (with some + exceptions, see below). + + * 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. + + * handle-as-empty-document - sends an empty document instead of + Privoxy's normal BLOCKED HTML page. This is useful for file types that + are neither HTML nor images, such as blocking JavaScript files. + + * 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). + + Advanced users will eventually want to explore Privoxy filters as well. + Filters are very different from blocks. A "block" blocks a site, page, or + unwanted contented. Filters are a way of filtering or modifying what is + actually on the page. An example filter usage: a text replacement of + "no-no" for "nasty-word". That is a very simple example. This process can + be used for ad blocking, but it is more in the realm of advanced usage and + has some pitfalls to be wary off. + + 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. + + Note that as of Privoxy 3.0.7 beta the action editor is disabled by + default. Check the enable-edit-actions section in the configuration file + to learn why and in which cases it's safe to enable again. + + If you decided to enable the action editor, 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. + + A quick and simple step by step example: + + * 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": + + Figure 1. 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. + + 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. + + 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. + + There are also various filters that can be used for ad blocking (filters + are a special subset of actions). These fall into the "advanced" usage + category, and are explained in depth in later sections. + + -------------------------------------------------------------------------- -7. The Main Configuration File +5. Starting Privoxy -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: + Before launching Privoxy for the first time, you will want to configure + your browser(s) to use Privoxy as a HTTP and HTTPS (SSL) 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! - confdir /etc/privoxy + Please note that Privoxy can only proxy HTTP and HTTPS traffic. It will + not work with FTP or other protocols. -Assigns the value /etc/privoxy to the option confdir and thus indicates that -the configuration directory is named "/etc/privoxy/". + Figure 2. Proxy Configuration Showing Mozilla/Netscape HTTP and HTTPS + (SSL) Settings -All options in the config file except for confdir and logdir are optional. -Watch out in the below description for what happens if you leave them unset. + With Firefox, this is typically set under: -The main config file controls all aspects of Privoxy's operation that are not -location dependent (i.e. they apply universally, no matter where you may be -surfing). + Tools -> Options -> Advanced -> Network ->Connection -> Settings -------------------------------------------------------------------------------- -7.1. Local Set-up Documentation + Or optionally on some platforms: -If you intend to operate Privoxy for more users than just yourself, it might be -a good idea to let them know how to reach you, what you block and why you do -that, your policies, etc. + Edit -> Preferences -> General -> Connection Settings -> Manual Proxy + Configuration -------------------------------------------------------------------------------- -7.1.1. user-manual + With Netscape (and Mozilla), this can be set under: -Specifies: + Edit -> Preferences -> Advanced -> Proxies -> HTTP Proxy - Location of the Privoxy User Manual. -Type of value: + For Internet Explorer v.5-7: - A fully qualified URI + Tools -> Internet Options -> Connections -> LAN Settings -Default value: + 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 (sometimes labeled "Secure"). Make sure any checkboxes like + "Use the same proxy server for all protocols" is UNCHECKED. You want only + HTTP and HTTPS (SSL)! - Unset + Figure 3. Proxy Configuration Showing Internet Explorer HTTP and HTTPS + (Secure) Settings -Effect if unset: + 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. + Remove any cookies, if you want Privoxy to manage that. You are now ready + to start enjoying the benefits of using Privoxy! - http://www.privoxy.org/version/user-manual/ will be used, where version is - the Privoxy version. + 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. -Notes: + -------------------------------------------------------------------------- - The User Manual URI is the single best source of information on Privoxy, - and is used for help links from some of the internal CGI pages. The manual - itself is normally packaged with the binary distributions, so you probably - want to set this to a locally installed copy. + 5.1. Red Hat and Fedora - Examples: + A default Red Hat installation may not start Privoxy upon boot. It will + use the file /etc/privoxy/config as its main configuration file. - The best all purpose solution is simply to put the full local PATH to where - the User Manual is located: + # /etc/rc.d/init.d/privoxy start - user-manual /usr/share/doc/privoxy/user-manual + Or ... + # service privoxy start - The User Manual is then available to anyone with access to Privoxy, by - following the built-in URL: http://config.privoxy.org/user-manual/ (or the - shortcut: http://p.p/user-manual/). + -------------------------------------------------------------------------- - If the documentation is not on the local system, it can be accessed from a - remote server, as: + 5.2. Debian - user-manual http://example.com/privoxy/user-manual/ + We use a script. Note that Debian typically starts Privoxy upon booting + per default. It will use the file /etc/privoxy/config as its main + configuration file. + # /etc/init.d/privoxy start - +-----------------------------------------------------------------+ - | Warning | - |-----------------------------------------------------------------| - |If set, this option should be the first option in the config | - |file, because it is used while the config file is being read on | - |start-up. | - +-----------------------------------------------------------------+ + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 5.3. Windows -7.1.2. trust-info-url + 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 when the + system starts if you chose that option when installing. -Specifies: + Privoxy can run with full Windows service functionality. On Windows only, + the Privoxy program has two new command line arguments to install and + uninstall Privoxy as a service. See the Windows Installation instructions + for details. - A URL to be displayed in the error page that users will see if access to an - untrusted page is denied. + -------------------------------------------------------------------------- -Type of value: + 5.4. Solaris, NetBSD, FreeBSD, HP-UX and others - URL + Example Unix startup command: -Default value: + # /usr/sbin/privoxy /etc/privoxy/config - Two example URLs are provided + -------------------------------------------------------------------------- -Effect if unset: + 5.5. OS/2 - No links are displayed on the "untrusted" error page. + 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. -Notes: + -------------------------------------------------------------------------- - The value of this option only matters if the experimental trust mechanism - has been activated. (See trustfile below.) + 5.6. Mac OSX - If you use the trust mechanism, it is a good idea to write up some on-line - documentation about your trust policy and to specify the URL(s) here. Use - multiple times for multiple URLs. + During installation, Privoxy is configured to start automatically when the + system restarts. To start Privoxy manually, double-click on the + StartPrivoxy.command icon in the /Library/Privoxy folder. Or, type this + command in the Terminal: - The URL(s) should be added to the trustfile as well, so users don't end up - locked out from the information on why they were locked out in the first - place! + /Library/Privoxy/StartPrivoxy.command -------------------------------------------------------------------------------- -7.1.3. admin-address + You will be prompted for the administrator password. -Specifies: + -------------------------------------------------------------------------- - An email address to reach the Privoxy administrator. + 5.7. AmigaOS -Type of value: + 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). - Email address + -------------------------------------------------------------------------- -Default value: + 5.8. Gentoo - Unset + A script is again used. It will use the file /etc/privoxy/config as its + main configuration file. -Effect if unset: + /etc/init.d/privoxy start - No email address is displayed on error pages and the CGI user interface. -Notes: + Note that Privoxy is not automatically started at boot time by default. + You can change this with the rc-update command. - If both admin-address and proxy-info-url are unset, the whole "Local - Privoxy Support" box on all generated pages will not be shown. + rc-update add privoxy default -------------------------------------------------------------------------------- -7.1.4. proxy-info-url + -------------------------------------------------------------------------- -Specifies: + 5.9. Command Line Options - A URL to documentation about the local Privoxy setup, configuration or - policies. + Privoxy may be invoked with the following command-line options: -Type of value: + * --version - URL + Print version info and exit. Unix only. -Default value: + * --help - Unset + Print short usage info and exit. Unix only. -Effect if unset: + * --no-daemon - No link to local documentation is displayed on error pages and the CGI user - interface. + Don't become a daemon, i.e. don't fork and become process group + leader, and don't detach from controlling tty. Unix only. -Notes: + * --pidfile FILE - If both admin-address and proxy-info-url are unset, the whole "Local - Privoxy Support" box on all generated pages will not be shown. + 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. - This URL shouldn't be blocked ;-) + * --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. -7.2. Configuration and Log File Locations + * --chroot -Privoxy can (and normally does) use a number of other files for additional -configuration, help and logging. This section of the configuration file tells -Privoxy where to find those other files. + 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. -The user running Privoxy, must have read permission for all configuration -files, and write permission to any files that would be modified, such as log -files and actions files. + * --pre-chroot-nslookup hostname -------------------------------------------------------------------------------- + Specifies a hostname to look up before doing a chroot. On some + systems, initializing the resolver library involves reading config + files from /etc and/or loading additional shared libraries from /lib. + On these systems, doing a hostname lookup before the chroot reduces + the number of files that must be copied into the chroot tree. -7.2.1. confdir + For fastest startup speed, a good value is a hostname that is not in + /etc/hosts but that your local name server (listed in + /etc/resolv.conf) can resolve without recursion (that is, without + having to ask any other name servers). The hostname need not exist, + but if it doesn't, an error message (which can be ignored) will be + output. -Specifies: + * configfile - The directory where the other configuration files are located. + 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. -Type of value: + On MS Windows only there are two additional command-line options to allow + Privoxy to install and run as a service. See the Window Installation + section for details. - Path name + -------------------------------------------------------------------------- -Default value: +6. Privoxy Configuration - /etc/privoxy (Unix) or Privoxy installation dir (Windows) + 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. -Effect if unset: + -------------------------------------------------------------------------- - Mandatory + 6.1. Controlling Privoxy with Your Web Browser -Notes: + 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: - No trailing "/", please. -------------------------------------------------------------------------------- -7.2.2. templdir +     Privoxy Menu -Specifies: +         sB  View & change the current configuration - An alternative directory where the templates are loaded from. +         sB  View the source code version numbers -Type of value: +         sB  View the request headers. - Path name +         sB  Look up which actions apply to a URL and why -Default value: +         sB  Toggle Privoxy on or off - unset +         sB  Documentation -Effect if unset: - The templates are assumed to be located in confdir/template. + 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. -Notes: + "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. - Privoxy's original templates are usually overwritten with each update. Use - this option to relocate customized templates that should be kept. As - template variables might change between updates, you shouldn't expect - templates to work with Privoxy releases other than the one they were part - of, though. + Note that several of the features described above are disabled by default + in Privoxy 3.0.7 beta and later. Check the configuration file to learn why + and in which cases it's safe to enable them again. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -7.2.3. logdir + 6.2. Configuration Files Overview -Specifies: + 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 directory where all logging takes place (i.e. where logfile and jarfile - are located). + 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: -Type of value: + * 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. - Path name + * 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. -Default value: + 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 only for Privoxy's + internal use. - /var/log/privoxy (Unix) or Privoxy installation dir (Windows) + 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. -Effect if unset: + * "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. - Mandatory + The syntax of the configuration and filter files may change between + different Privoxy versions, unfortunately some enhancements cost backwards + compatibility. -Notes: + 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. Blank lines are ignored. - No trailing "/", please. + The actions files and filter files can use Perl style regular expressions + for maximum flexibility. -------------------------------------------------------------------------------- + After making any changes, there is no need to restart Privoxy in order for + the changes to take effect. Privoxy 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. -7.2.4. actionsfile + -------------------------------------------------------------------------- -Specifies: +7. The Main Configuration File - The actions file(s) to use + 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: -Type of value: + confdir /etc/privoxy - Complete file name, relative to confdir + Assigns the value /etc/privoxy to the option confdir and thus indicates + that the configuration directory is named "/etc/privoxy/". -Default values: + All options in the config file except for confdir and logdir are optional. + Watch out in the below description for what happens if you leave them + unset. - standard.action # Internal purposes, no editing recommended + The main config file controls all aspects of Privoxy's operation that are + not location dependent (i.e. they apply universally, no matter where you + may be surfing). - default.action # Main actions file + -------------------------------------------------------------------------- - user.action # User customizations + 7.1. Local Set-up Documentation -Effect if unset: + If you intend to operate Privoxy for more users than just yourself, it + might be a good idea to let them know how to reach you, what you block and + why you do that, your policies, etc. - No actions are taken at all. More or less neutral proxying. + -------------------------------------------------------------------------- -Notes: + 7.1.1. user-manual - Multiple actionsfile lines are permitted, and are in fact recommended! + Specifies: - The default values include standard.action, which is used for internal - purposes and should be loaded, default.action, which is the "main" actions - file maintained by the developers, and user.action, where you can make your - personal additions. + Location of the Privoxy User Manual. - Actions files contain all the per site and per URL configuration for ad - blocking, cookie management, privacy considerations, etc. There is no point - in using Privoxy without at least one actions file. + Type of value: - Note that since Privoxy 3.0.7, the complete filename, including the - ".action" extension has to be specified. The syntax change was necessary to - be consistent with the other file options and to allow previously forbidden - characters. + A fully qualified URI -------------------------------------------------------------------------------- + Default value: -7.2.5. filterfile + Unset -Specifies: + Effect if unset: - The filter file(s) to use + http://www.privoxy.org/version/user-manual/ will be used, where + version is the Privoxy version. -Type of value: + Notes: - File name, relative to confdir + The User Manual URI is the single best source of information on + Privoxy, and is used for help links from some of the internal CGI + pages. The manual itself is normally packaged with the binary + distributions, so you probably want to set this to a locally + installed copy. -Default value: + Examples: - default.filter (Unix) or default.filter.txt (Windows) + The best all purpose solution is simply to put the full local PATH + to where the User Manual is located: -Effect if unset: +   user-manual  /usr/share/doc/privoxy/user-manual - No textual content filtering takes place, i.e. all +filter{name} actions in - the actions files are turned neutral. + The User Manual is then available to anyone with access to + Privoxy, by following the built-in URL: + http://config.privoxy.org/user-manual/ (or the shortcut: + http://p.p/user-manual/). -Notes: + If the documentation is not on the local system, it can be + accessed from a remote server, as: - Multiple filterfile lines are permitted. +   user-manual  http://example.com/privoxy/user-manual/ - The filter files contain content modification rules that use regular - expressions. These rules permit powerful changes on the content of Web - pages, and optionally the headers as well, e.g., you could try to disable - your favorite JavaScript annoyances, re-write the actual displayed text, or - just have some fun playing buzzword bingo with web pages. + +---------------------------------------------------------+ + | Warning | + |---------------------------------------------------------| + | If set, this option should be the first option in the | + | config file, because it is used while the config file | + | is being read on start-up. | + +---------------------------------------------------------+ - The +filter{name} actions rely on the relevant filter (name) to be defined - in a filter file! + -------------------------------------------------------------------------- - A pre-defined filter file called default.filter that contains a number of - useful filters for common problems is included in the distribution. See the - section on the filter action for a list. + 7.1.2. trust-info-url - It is recommended to place any locally adapted filters into a separate - file, such as user.filter. + Specifies: -------------------------------------------------------------------------------- + A URL to be displayed in the error page that users will see if + access to an untrusted page is denied. -7.2.6. logfile + Type of value: -Specifies: + URL - The log file to use + Default value: -Type of value: + Two example URLs are provided - File name, relative to logdir + Effect if unset: -Default value: + No links are displayed on the "untrusted" error page. - Unset (commented out). When activated: logfile (Unix) or privoxy.log - (Windows). + Notes: -Effect if unset: + The value of this option only matters if the experimental trust + mechanism has been activated. (See trustfile below.) - No logfile is written. + If you use the trust mechanism, it is a good idea to write up some + on-line documentation about your trust policy and to specify the + URL(s) here. Use multiple times for multiple URLs. -Notes: + The URL(s) should be added to the trustfile as well, so users + don't end up locked out from the information on why they were + locked out in the first place! - The logfile is where all logging and error messages are written. The level - of detail and number of messages are set with the debug option (see below). - The logfile can be useful for tracking down a problem with Privoxy (e.g., - it's not blocking an ad you think it should block) and it can help you to - monitor what your browser is doing. + -------------------------------------------------------------------------- - Depending on the debug options below, the logfile may be a privacy risk if - third parties can get access to it. As most users will never look at it, - Privoxy 3.0.7 and later only log fatal errors by default. + 7.1.3. admin-address - For most troubleshooting purposes, you will have to change that, please - refer to the debugging section for details. + Specifies: - Your logfile will grow indefinitely, and you will probably want to - periodically remove it. On Unix systems, you can do this with a cron job - (see "man cron"). For Red Hat based Linux distributions, a logrotate script - has been included. + An email address to reach the Privoxy administrator. - Any log files must be writable by whatever user Privoxy is being run as (on - Unix, default user id is "privoxy"). + Type of value: -------------------------------------------------------------------------------- + Email address -7.2.7. jarfile + Default value: -Specifies: + Unset - The file to store intercepted cookies in + Effect if unset: -Type of value: + No email address is displayed on error pages and the CGI user + interface. - File name, relative to logdir + Notes: -Default value: + If both admin-address and proxy-info-url are unset, the whole + "Local Privoxy Support" box on all generated pages will not be + shown. - Unset (commented out). When activated: jarfile (Unix) or privoxy.jar - (Windows). + -------------------------------------------------------------------------- -Effect if unset: + 7.1.4. proxy-info-url - Intercepted cookies are not stored in a dedicated log file. + Specifies: -Notes: + A URL to documentation about the local Privoxy setup, + configuration or policies. - The jarfile may grow to ridiculous sizes over time. + Type of value: - If debug 8 (show header parsing) is enabled, cookies are also written to - the logfile with the rest of the headers. Therefore this option isn't very - useful and may be removed in future releases. Please report to the - developers if you are still using it. + URL -------------------------------------------------------------------------------- + Default value: -7.2.8. trustfile + Unset -Specifies: + Effect if unset: - The name of the trust file to use + No link to local documentation is displayed on error pages and the + CGI user interface. -Type of value: + Notes: - File name, relative to confdir + If both admin-address and proxy-info-url are unset, the whole + "Local Privoxy Support" box on all generated pages will not be + shown. -Default value: + This URL shouldn't be blocked ;-) - Unset (commented out). When activated: trust (Unix) or trust.txt (Windows) + -------------------------------------------------------------------------- -Effect if unset: + 7.2. Configuration and Log File Locations - The entire trust mechanism is disabled. + Privoxy can (and normally does) use a number of other files for additional + configuration, help and logging. This section of the configuration file + tells Privoxy where to find those other files. -Notes: + The user running Privoxy, must have read permission for all configuration + files, and write permission to any files that would be modified, such as + log files and actions files. - The trust mechanism is an experimental feature for building white-lists and - should be used with care. It is NOT recommended for the casual user. + -------------------------------------------------------------------------- - If you specify a trust file, Privoxy will only allow access to sites that - are specified in the trustfile. Sites can be listed in one of two ways: + 7.2.1. confdir - Prepending a ~ character limits access to this site only (and any sub-paths - within this site), e.g. ~www.example.com allows access to ~www.example.com/ - features/news.html, etc. + Specifies: - Or, you can designate sites as trusted referrers, by prepending the name - with a + character. The effect is that access to untrusted sites will be - granted -- but only if a link from this trusted referrer was used to get - there. The link target will then be added to the "trustfile" so that - future, direct accesses will be granted. Sites added via this mechanism do - not become trusted referrers themselves (i.e. they are added with a ~ - designation). There is a limit of 512 such entries, after which new entries - will not be made. + The directory where the other configuration files are located. - If you use the + operator in the trust file, it may grow considerably over - time. + Type of value: - It is recommended that Privoxy be compiled with the --disable-force, - --disable-toggle and --disable-editor options, if this feature is to be - used. + Path name - Possible applications include limiting Internet access for children. + Default value: -------------------------------------------------------------------------------- + /etc/privoxy (Unix) or Privoxy installation dir (Windows) -7.3. Debugging + Effect if unset: -These options are mainly useful when tracing a problem. Note that you might -also want to invoke Privoxy with the --no-daemon command line option when -debugging. + Mandatory -------------------------------------------------------------------------------- + Notes: -7.3.1. debug + No trailing "/", please. -Specifies: + -------------------------------------------------------------------------- - Key values that determine what information gets logged. + 7.2.2. templdir -Type of value: + Specifies: - Integer values + An alternative directory where the templates are loaded from. -Default value: + Type of value: - 0 (i.e.: only fatal errors (that cause Privoxy to exit) are logged) + Path name -Effect if unset: + Default value: - Default value is used (see above). + unset -Notes: + Effect if unset: - The available debug levels are: + The templates are assumed to be located in confdir/template. - debug 1 # log each request destination (and the crunch reason if Privoxy intercepted the request) - debug 2 # show each connection status - debug 4 # show I/O status - debug 8 # show header parsing - debug 16 # log all data written to the network into the logfile - debug 32 # debug force feature - debug 64 # debug regular expression filters - debug 128 # debug redirects - debug 256 # debug GIF de-animation - debug 512 # Common Log Format - debug 1024 # debug kill pop-ups - debug 2048 # CGI user interface - debug 4096 # Startup banner and warnings. - debug 8192 # Non-fatal errors + Notes: + Privoxy's original templates are usually overwritten with each + update. Use this option to relocate customized templates that + should be kept. As template variables might change between + updates, you shouldn't expect templates to work with Privoxy + releases other than the one they were part of, though. - To select multiple debug levels, you can either add them or use multiple - debug lines. + -------------------------------------------------------------------------- - A debug level of 1 is informative because it will show you each request as - it happens. 1, 4096 and 8192 are recommended so that you will notice when - things go wrong. The other levels are probably only of interest if you are - hunting down a specific problem. They can produce a hell of an output - (especially 16). + 7.2.3. logdir - Privoxy used to ship with the debug levels recommended above enabled by - default, but due to privacy concerns 3.0.7 and later are configured to only - log fatal errors. + Specifies: - If you are used to the more verbose settings, simply enable the debug lines - below again. + The directory where all logging takes place (i.e. where logfile + and jarfile are located). - If you want to use pure CLF (Common Log Format), you should set "debug 512" - ONLY and not enable anything else. + Type of value: - Privoxy has a hard-coded limit for the length of log messages. If it's - reached, messages are logged truncated and marked with "... [too long, - truncated]". + Path name - Please don't file any support requests without trying to reproduce the - problem with increased debug level first. Once you read the log messages, - you may even be able to solve the problem on your own. + Default value: -------------------------------------------------------------------------------- + /var/log/privoxy (Unix) or Privoxy installation dir (Windows) -7.3.2. single-threaded + Effect if unset: -Specifies: + Mandatory - Whether to run only one server thread. + Notes: -Type of value: + No trailing "/", please. - None + -------------------------------------------------------------------------- -Default value: + 7.2.4. actionsfile - Unset + Specifies: -Effect if unset: + The actions file(s) to use - Multi-threaded (or, where unavailable: forked) operation, i.e. the ability - to serve multiple requests simultaneously. + Type of value: -Notes: + Complete file name, relative to confdir - This option is only there for debugging purposes. It will drastically - reduce performance. + Default values: -------------------------------------------------------------------------------- + standard.action # Internal purposes, no editing recommended + default.action # Main actions file + user.action # User customizations -7.4. Access Control and Security + Effect if unset: -This section of the config file controls the security-relevant aspects of -Privoxy's configuration. + No actions are taken at all. More or less neutral proxying. -------------------------------------------------------------------------------- + Notes: -7.4.1. listen-address + Multiple actionsfile lines are permitted, and are in fact + recommended! -Specifies: + The default values include standard.action, which is used for + internal purposes and should be loaded, default.action, which is + the "main" actions file maintained by the developers, and + user.action, where you can make your personal additions. - The IP address and TCP port on which Privoxy will listen for client - requests. + Actions files contain all the per site and per URL configuration + for ad blocking, cookie management, privacy considerations, etc. + There is no point in using Privoxy without at least one actions + file. -Type of value: + Note that since Privoxy 3.0.7, the complete filename, including + the ".action" extension has to be specified. The syntax change was + necessary to be consistent with the other file options and to + allow previously forbidden characters. - [IP-Address]:Port + -------------------------------------------------------------------------- -Default value: + 7.2.5. filterfile - 127.0.0.1:8118 + Specifies: -Effect if unset: + The filter file(s) to use - Bind to 127.0.0.1 (localhost), port 8118. This is suitable and recommended - for home users who run Privoxy on the same machine as their browser. + Type of value: -Notes: + File name, relative to confdir - You will need to configure your browser(s) to this proxy address and port. + Default value: - 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. + default.filter (Unix) or default.filter.txt (Windows) - 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 below), and/or a - firewall. + Effect if unset: - If you open Privoxy to untrusted users, you will also want to make sure - that the following actions are disabled: enable-edit-actions and - enable-remote-toggle + No textual content filtering takes place, i.e. all +filter{name} + actions in the actions files are turned neutral. -Example: + Notes: - 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: + Multiple filterfile lines are permitted. - listen-address 192.168.0.1:8118 + The filter files contain content modification rules that use + regular expressions. These rules permit powerful changes on the + content of Web pages, and optionally the headers as well, e.g., + you could try to disable your favorite JavaScript annoyances, + re-write the actual displayed text, or just have some fun playing + buzzword bingo with web pages. + The +filter{name} actions rely on the relevant filter (name) to be + defined in a filter file! -------------------------------------------------------------------------------- + A pre-defined filter file called default.filter that contains a + number of useful filters for common problems is included in the + distribution. See the section on the filter action for a list. -7.4.2. toggle + It is recommended to place any locally adapted filters into a + separate file, such as user.filter. -Specifies: + -------------------------------------------------------------------------- - Initial state of "toggle" status + 7.2.6. logfile -Type of value: + Specifies: - 1 or 0 + The log file to use -Default value: + Type of value: - 1 + File name, relative to logdir -Effect if unset: + Default value: - Act as if toggled on + Unset (commented out). When activated: logfile (Unix) or + privoxy.log (Windows). -Notes: + Effect if unset: - If set to 0, Privoxy will start in "toggled off" mode, i.e. mostly behave - like a normal, content-neutral proxy with both ad blocking and content - filtering disabled. See enable-remote-toggle below. + No logfile is written. - The windows version will only display the toggle icon in the system tray if - this option is present. + Notes: -------------------------------------------------------------------------------- + The logfile is where all logging and error messages are written. + The level of detail and number of messages are set with the debug + option (see below). The logfile can be useful for tracking down a + problem with Privoxy (e.g., it's not blocking an ad you think it + should block) and it can help you to monitor what your browser is + doing. -7.4.3. enable-remote-toggle + Depending on the debug options below, the logfile may be a privacy + risk if third parties can get access to it. As most users will + never look at it, Privoxy 3.0.7 and later only log fatal errors by + default. -Specifies: + For most troubleshooting purposes, you will have to change that, + please refer to the debugging section for details. - Whether or not the web-based toggle feature may be used + Your logfile will grow indefinitely, and you will probably want to + periodically remove it. On Unix systems, you can do this with a + cron job (see "man cron"). For Red Hat based Linux distributions, + a logrotate script has been included. -Type of value: + Any log files must be writable by whatever user Privoxy is being + run as (on Unix, default user id is "privoxy"). - 0 or 1 + -------------------------------------------------------------------------- -Default value: + 7.2.7. jarfile - 0 + Specifies: -Effect if unset: + The file to store intercepted cookies in - The web-based toggle feature is disabled. + Type of value: -Notes: + File name, relative to logdir - When toggled off, Privoxy mostly acts like a normal, content-neutral proxy, - i.e. doesn't block ads or filter content. + Default value: - Access to the toggle feature can not be controlled separately by "ACLs" or - HTTP authentication, so that everybody who can access Privoxy (see "ACLs" - and listen-address above) can toggle it for all users. So this option is - not recommended for multi-user environments with untrusted users. + Unset (commented out). When activated: jarfile (Unix) or + privoxy.jar (Windows). - Note that malicious client side code (e.g Java) is also capable of using - this option. + Effect if unset: - As a lot of Privoxy users don't read documentation, this feature is - disabled by default. + Intercepted cookies are not stored in a dedicated log file. - Note that you must have compiled Privoxy with support for this feature, - otherwise this option has no effect. + Notes: -------------------------------------------------------------------------------- + The jarfile may grow to ridiculous sizes over time. -7.4.4. enable-remote-http-toggle + If debug 8 (show header parsing) is enabled, cookies are also + written to the logfile with the rest of the headers. Therefore + this option isn't very useful and may be removed in future + releases. Please report to the developers if you are still using + it. -Specifies: + -------------------------------------------------------------------------- - Whether or not Privoxy recognizes special HTTP headers to change its - behaviour. + 7.2.8. trustfile -Type of value: + Specifies: - 0 or 1 + The name of the trust file to use -Default value: + Type of value: - 0 + File name, relative to confdir -Effect if unset: + Default value: - Privoxy ignores special HTTP headers. + Unset (commented out). When activated: trust (Unix) or trust.txt + (Windows) -Notes: + Effect if unset: - When toggled on, the client can change Privoxy's behaviour by setting - special HTTP headers. Currently the only supported special header is - "X-Filter: No", to disable filtering for the ongoing request, even if it is - enabled in one of the action files. + The entire trust mechanism is disabled. - This feature is disabled by default. If you are using Privoxy in a - environment with trusted clients, you may enable this feature at your - discretion. Note that malicious client side code (e.g Java) is also capable - of using this feature. + Notes: - This option will be removed in future releases as it has been obsoleted by - the more general header taggers. + The trust mechanism is an experimental feature for building + white-lists and should be used with care. It is NOT recommended + for the casual user. -------------------------------------------------------------------------------- + If you specify a trust file, Privoxy will only allow access to + sites that are specified in the trustfile. Sites can be listed in + one of two ways: -7.4.5. enable-edit-actions + Prepending a ~ character limits access to this site only (and any + sub-paths within this site), e.g. ~www.example.com allows access + to ~www.example.com/features/news.html, etc. -Specifies: + Or, you can designate sites as trusted referrers, by prepending + the name with a + character. The effect is that access to + untrusted sites will be granted -- but only if a link from this + trusted referrer was used to get there. The link target will then + be added to the "trustfile" so that future, direct accesses will + be granted. Sites added via this mechanism do not become trusted + referrers themselves (i.e. they are added with a ~ designation). + There is a limit of 512 such entries, after which new entries will + not be made. - Whether or not the web-based actions file editor may be used + If you use the + operator in the trust file, it may grow + considerably over time. -Type of value: + It is recommended that Privoxy be compiled with the + --disable-force, --disable-toggle and --disable-editor options, if + this feature is to be used. - 0 or 1 + Possible applications include limiting Internet access for + children. -Default value: + -------------------------------------------------------------------------- - 0 + 7.3. Debugging -Effect if unset: + These options are mainly useful when tracing a problem. Note that you + might also want to invoke Privoxy with the --no-daemon command line option + when debugging. - The web-based actions file editor is disabled. + -------------------------------------------------------------------------- -Notes: + 7.3.1. debug - Access to the editor can not be controlled separately by "ACLs" or HTTP - authentication, so that everybody who can access Privoxy (see "ACLs" and - listen-address above) can modify its configuration for all users. + Specifies: - This option is not recommended for environments with untrusted users and as - a lot of Privoxy users don't read documentation, this feature is disabled - by default. + Key values that determine what information gets logged. - Note that malicious client side code (e.g Java) is also capable of using - the actions editor and you shouldn't enable this options unless you - understand the consequences and are sure your browser is configured - correctly. + Type of value: - Note that you must have compiled Privoxy with support for this feature, - otherwise this option has no effect. + Integer values -------------------------------------------------------------------------------- + Default value: -7.4.6. enforce-blocks + 0 (i.e.: only fatal errors (that cause Privoxy to exit) are + logged) -Specifies: + Effect if unset: - Whether the user is allowed to ignore blocks and can "go there anyway". + Default value is used (see above). -Type of value: + Notes: - 0 or 1 + The available debug levels are: -Default value: + debug 1 # log each request destination (and the crunch reason if Privoxy intercepted the request) + debug 2 # show each connection status + debug 4 # show I/O status + debug 8 # show header parsing + debug 16 # log all data written to the network into the logfile + debug 32 # debug force feature + debug 64 # debug regular expression filters + debug 128 # debug redirects + debug 256 # debug GIF de-animation + debug 512 # Common Log Format + debug 1024 # debug kill pop-ups + debug 2048 # CGI user interface + debug 4096 # Startup banner and warnings. + debug 8192 # Non-fatal errors - 0 + To select multiple debug levels, you can either add them or use + multiple debug lines. -Effect if unset: + A debug level of 1 is informative because it will show you each + request as it happens. 1, 4096 and 8192 are recommended so that + you will notice when things go wrong. The other levels are + probably only of interest if you are hunting down a specific + problem. They can produce a hell of an output (especially 16). - Blocks are not enforced. + Privoxy used to ship with the debug levels recommended above + enabled by default, but due to privacy concerns 3.0.7 and later + are configured to only log fatal errors. -Notes: + If you are used to the more verbose settings, simply enable the + debug lines below again. - Privoxy is mainly used to block and filter requests as a service to the - user, for example to block ads and other junk that clogs the pipes. - Privoxy's configuration isn't perfect and sometimes innocent pages are - blocked. In this situation it makes sense to allow the user to enforce the - request and have Privoxy ignore the block. + If you want to use pure CLF (Common Log Format), you should set + "debug 512" ONLY and not enable anything else. - In the default configuration Privoxy's "Blocked" page contains a "go there - anyway" link to adds a special string (the force prefix) to the request - URL. If that link is used, Privoxy will detect the force prefix, remove it - again and let the request pass. + Privoxy has a hard-coded limit for the length of log messages. If + it's reached, messages are logged truncated and marked with "... + [too long, truncated]". - Of course Privoxy can also be used to enforce a network policy. In that - case the user obviously should not be able to bypass any blocks, and that's - what the "enforce-blocks" option is for. If it's enabled, Privoxy hides the - "go there anyway" link. If the user adds the force prefix by hand, it will - not be accepted and the circumvention attempt is logged. + Please don't file any support requests without trying to reproduce + the problem with increased debug level first. Once you read the + log messages, you may even be able to solve the problem on your + own. -Examples: + -------------------------------------------------------------------------- - enforce-blocks 1 + 7.3.2. single-threaded -------------------------------------------------------------------------------- + Specifies: -7.4.7. ACLs: permit-access and deny-access + Whether to run only one server thread. -Specifies: + Type of value: - Who can access what. + None -Type of value: + Default value: - src_addr[/src_masklen] [dst_addr[/dst_masklen]] + Unset - Where src_addr and dst_addr are IP addresses in dotted decimal notation or - valid DNS names, and src_masklen and dst_masklen are subnet masks in CIDR - notation, i.e. integer values from 2 to 30 representing the length (in - bits) of the network address. The masks and the whole destination part are - optional. + Effect if unset: -Default value: + Multi-threaded (or, where unavailable: forked) operation, i.e. the + ability to serve multiple requests simultaneously. - Unset + Notes: -Effect if unset: + This option is only there for debugging purposes. It will + drastically reduce performance. - Don't restrict access further than implied by listen-address + -------------------------------------------------------------------------- -Notes: + 7.4. Access Control and Security - Access controls are included at the request of ISPs and systems - administrators, and are not usually needed by individual users. For a - typical home user, it will normally suffice to ensure that Privoxy only - listens on the localhost (127.0.0.1) or internal (home) network address by - means of the listen-address option. + This section of the config file controls the security-relevant aspects of + Privoxy's configuration. - Please see the warnings in the FAQ that Privoxy is not intended to be a - substitute for a firewall or to encourage anyone to defer addressing basic - security weaknesses. + -------------------------------------------------------------------------- - Multiple ACL lines are OK. If any ACLs are specified, Privoxy only talks to - IP addresses that match at least one permit-access line and don't match any - subsequent deny-access line. In other words, the last match wins, with the - default being deny-access. + 7.4.1. listen-address - If Privoxy is using a forwarder (see forward below) for a particular - destination URL, the dst_addr that is examined is the address of the - forwarder and NOT the address of the ultimate target. This is necessary - because it may be impossible for the local Privoxy to determine the IP - address of the ultimate target (that's often what gateways are used for). + Specifies: - You should prefer using IP addresses over DNS names, because the address - lookups take time. All DNS names must resolve! You can not use domain - patterns like "*.org" or partial domain names. If a DNS name resolves to - multiple IP addresses, only the first one is used. + The IP address and TCP port on which Privoxy will listen for + client requests. - Denying access to particular sites by ACL may have undesired side effects - if the site in question is hosted on a machine which also hosts other sites - (most sites are). + Type of value: -Examples: + [IP-Address]:Port - Explicitly define the default behavior if no ACL and listen-address are - set: "localhost" is OK. The absence of a dst_addr implies that all - destination addresses are OK: + Default value: - permit-access localhost + 127.0.0.1:8118 + Effect if unset: - Allow any host on the same class C subnet as www.privoxy.org access to - nothing but www.example.com (or other domains hosted on the same system): + Bind to 127.0.0.1 (localhost), port 8118. This is suitable and + recommended for home users who run Privoxy on the same machine as + their browser. - permit-access www.privoxy.org/24 www.example.com/32 + Notes: + You will need to configure your browser(s) to this proxy address + and port. - Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere, - with the exception that 192.168.45.73 may not access the IP address behind - www.dirty-stuff.example.com: + 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. - permit-access 192.168.45.64/26 - deny-access 192.168.45.73 www.dirty-stuff.example.com + 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 below), and/or a firewall. + If you open Privoxy to untrusted users, you will also want to make + sure that the following actions are disabled: enable-edit-actions + and enable-remote-toggle -------------------------------------------------------------------------------- + Example: -7.4.8. buffer-limit + 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: -Specifies: + listen-address 192.168.0.1:8118 - Maximum size of the buffer for content filtering. + -------------------------------------------------------------------------- -Type of value: + 7.4.2. toggle - Size in Kbytes + Specifies: -Default value: + Initial state of "toggle" status - 4096 + Type of value: -Effect if unset: + 1 or 0 - Use a 4MB (4096 KB) limit. + Default value: -Notes: + 1 - For content filtering, i.e. the +filter and +deanimate-gif actions, it is - necessary that Privoxy buffers the entire document body. This can be - potentially dangerous, since a server could just keep sending data - indefinitely and wait for your RAM to exhaust -- with nasty consequences. - Hence this option. + Effect if unset: - When a document buffer size reaches the buffer-limit, it is flushed to the - client unfiltered and no further attempt to filter the rest of the document - is made. Remember that there may be multiple threads running, which might - require up to buffer-limit Kbytes each, unless you have enabled - "single-threaded" above. + Act as if toggled on -------------------------------------------------------------------------------- + Notes: -7.5. Forwarding + If set to 0, Privoxy will start in "toggled off" mode, i.e. mostly + behave like a normal, content-neutral proxy with both ad blocking + and content filtering disabled. See enable-remote-toggle below. -This feature allows routing of HTTP requests through a chain of multiple -proxies. + The windows version will only display the toggle icon in the + system tray if this option is present. -Forwarding can be used to chain Privoxy with a caching proxy to speed up -browsing. Using a parent proxy may also be necessary if the machine that -Privoxy runs on has no direct Internet access. + -------------------------------------------------------------------------- -Note that parent proxies can severely decrease your privacy level. For example -a parent proxy could add your IP address to the request headers and if it's a -caching proxy it may add the "Etag" header to revalidation requests again, even -though you configured Privoxy to remove it. It may also ignore Privoxy's header -time randomization and use the original values which could be used by the -server as cookie replacement to track your steps between visits. + 7.4.3. enable-remote-toggle -Also specified here are SOCKS proxies. Privoxy supports the SOCKS 4 and SOCKS -4A protocols. + Specifies: -------------------------------------------------------------------------------- + Whether or not the web-based toggle feature may be used -7.5.1. forward + Type of value: -Specifies: + 0 or 1 - To which parent HTTP proxy specific requests should be routed. + Default value: -Type of value: + 0 - target_pattern http_parent[:port] + Effect if unset: - where target_pattern is a URL pattern that specifies to which requests - (i.e. URLs) this forward rule shall apply. Use / to denote "all URLs". - http_parent[:port] is the DNS name or IP address of the parent HTTP proxy - through which the requests should be forwarded, optionally followed by its - listening port (default: 8080). Use a single dot (.) to denote "no - forwarding". + The web-based toggle feature is disabled. -Default value: + Notes: - Unset + When toggled off, Privoxy mostly acts like a normal, + content-neutral proxy, i.e. doesn't block ads or filter content. -Effect if unset: + Access to the toggle feature can not be controlled separately by + "ACLs" or HTTP authentication, so that everybody who can access + Privoxy (see "ACLs" and listen-address above) can toggle it for + all users. So this option is not recommended for multi-user + environments with untrusted users. - Don't use parent HTTP proxies. + Note that malicious client side code (e.g Java) is also capable of + using this option. -Notes: + As a lot of Privoxy users don't read documentation, this feature + is disabled by default. - If http_parent is ".", then requests are not forwarded to another HTTP - proxy but are made directly to the web servers. + Note that you must have compiled Privoxy with support for this + feature, otherwise this option has no effect. - Multiple lines are OK, they are checked in sequence, and the last match - wins. + -------------------------------------------------------------------------- -Examples: + 7.4.4. enable-remote-http-toggle - Everything goes to an example parent proxy, except SSL on port 443 (which - it doesn't handle): + Specifies: - forward / parent-proxy.example.org:8080 - forward :443 . + Whether or not Privoxy recognizes special HTTP headers to change + its behaviour. + Type of value: - Everything goes to our example ISP's caching proxy, except for requests to - that ISP's sites: + 0 or 1 - forward / caching-proxy.isp.example.net:8000 - forward .isp.example.net . + Default value: + 0 -------------------------------------------------------------------------------- + Effect if unset: -7.5.2. forward-socks4 and forward-socks4a + Privoxy ignores special HTTP headers. -Specifies: + Notes: - Through which SOCKS proxy (and optionally to which parent HTTP proxy) - specific requests should be routed. + When toggled on, the client can change Privoxy's behaviour by + setting special HTTP headers. Currently the only supported special + header is "X-Filter: No", to disable filtering for the ongoing + request, even if it is enabled in one of the action files. -Type of value: + This feature is disabled by default. If you are using Privoxy in a + environment with trusted clients, you may enable this feature at + your discretion. Note that malicious client side code (e.g Java) + is also capable of using this feature. - target_pattern socks_proxy[:port] http_parent[:port] + This option will be removed in future releases as it has been + obsoleted by the more general header taggers. - where target_pattern is a URL pattern that specifies to which requests - (i.e. URLs) this forward rule shall apply. Use / to denote "all URLs". - http_parent and socks_proxy are IP addresses in dotted decimal notation or - valid DNS names (http_parent may be "." to denote "no HTTP forwarding"), - and the optional port parameters are TCP ports, i.e. integer values from 1 - to 64535 + -------------------------------------------------------------------------- -Default value: + 7.4.5. enable-edit-actions - Unset + Specifies: -Effect if unset: + Whether or not the web-based actions file editor may be used - Don't use SOCKS proxies. + Type of value: -Notes: + 0 or 1 - Multiple lines are OK, they are checked in sequence, and the last match - wins. + Default value: - The difference between forward-socks4 and forward-socks4a is that in the - SOCKS 4A protocol, the DNS resolution of the target hostname happens on the - SOCKS server, while in SOCKS 4 it happens locally. + 0 - If http_parent is ".", then requests are not forwarded to another HTTP - proxy but are made (HTTP-wise) directly to the web servers, albeit through - a SOCKS proxy. + Effect if unset: -Examples: + The web-based actions file editor is disabled. - From the company example.com, direct connections are made to all "internal" - domains, but everything outbound goes through their ISP's proxy by way of - example.com's corporate SOCKS 4A gateway to the Internet. + Notes: - forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080 - forward .example.com . + Access to the editor can not be controlled separately by "ACLs" or + HTTP authentication, so that everybody who can access Privoxy (see + "ACLs" and listen-address above) can modify its configuration for + all users. + This option is not recommended for environments with untrusted + users and as a lot of Privoxy users don't read documentation, this + feature is disabled by default. - A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent - looks like this: + Note that malicious client side code (e.g Java) is also capable of + using the actions editor and you shouldn't enable this options + unless you understand the consequences and are sure your browser + is configured correctly. - forward-socks4 / socks-gw.example.com:1080 . + Note that you must have compiled Privoxy with support for this + feature, otherwise this option has no effect. + -------------------------------------------------------------------------- - To chain Privoxy and Tor, both running on the same system, you would use - something like: + 7.4.6. enforce-blocks - forward-socks4a / 127.0.0.1:9050 . + Specifies: + Whether the user is allowed to ignore blocks and can "go there + anyway". - The public Tor network can't be used to reach your local network, if you - need to access local servers you therefore might want to make some - exceptions: + Type of value: - forward 192.168.*.*/ . - forward 10.*.*.*/ . - forward 127.*.*.*/ . + 0 or 1 + Default value: - Unencrypted connections to systems in these address ranges will be as (un) - secure as the local network is, but the alternative is that you can't reach - the local network through Privoxy at all. Of course this may actually be - desired and there is no reason to make these exceptions if you aren't sure - you need them. + 0 - If you also want to be able to reach servers in your local network by using - their names, you will need additional exceptions that look like this: + Effect if unset: - forward localhost/ . + Blocks are not enforced. + Notes: -------------------------------------------------------------------------------- + Privoxy is mainly used to block and filter requests as a service + to the user, for example to block ads and other junk that clogs + the pipes. Privoxy's configuration isn't perfect and sometimes + innocent pages are blocked. In this situation it makes sense to + allow the user to enforce the request and have Privoxy ignore the + block. -7.5.3. Advanced Forwarding Examples + In the default configuration Privoxy's "Blocked" page contains a + "go there anyway" link to adds a special string (the force prefix) + to the request URL. If that link is used, Privoxy will detect the + force prefix, remove it again and let the request pass. -If you have links to multiple ISPs that provide various special content only to -their subscribers, you can configure multiple Privoxies which have connections -to the respective ISPs to act as forwarders to each other, so that your users -can see the internal content of all ISPs. + Of course Privoxy can also be used to enforce a network policy. In + that case the user obviously should not be able to bypass any + blocks, and that's what the "enforce-blocks" option is for. If + it's enabled, Privoxy hides the "go there anyway" link. If the + user adds the force prefix by hand, it will not be accepted and + the circumvention attempt is logged. -Assume that host-a has a PPP connection to isp-a.example.net. And host-b has a -PPP connection to isp-b.example.org. Both run Privoxy. Their forwarding -configuration can look like this: + Examples: -host-a: + enforce-blocks 1 - forward / . - forward .isp-b.example.net host-b:8118 + -------------------------------------------------------------------------- + 7.4.7. ACLs: permit-access and deny-access -host-b: + Specifies: - forward / . - forward .isp-a.example.org host-a:8118 + Who can access what. + Type of value: -Now, your users can set their browser's proxy to use either host-a or host-b -and be able to browse the internal content of both isp-a and isp-b. + src_addr[/src_masklen] [dst_addr[/dst_masklen]] -If you intend to chain Privoxy and squid locally, then chaining as browser -> -squid -> privoxy is the recommended way. + Where src_addr and dst_addr are IP addresses in dotted decimal + notation or valid DNS names, and src_masklen and dst_masklen are + subnet masks in CIDR notation, i.e. integer values from 2 to 30 + representing the length (in bits) of the network address. The + masks and the whole destination part are optional. -Assuming that Privoxy and squid run on the same box, your squid configuration -could then look like this: + Default value: - # Define Privoxy as parent proxy (without ICP) - cache_peer 127.0.0.1 parent 8118 7 no-query + Unset - # Define ACL for protocol FTP - acl ftp proto FTP + Effect if unset: - # Do not forward FTP requests to Privoxy - always_direct allow ftp + Don't restrict access further than implied by listen-address - # Forward all the rest to Privoxy - never_direct allow all + Notes: + Access controls are included at the request of ISPs and systems + administrators, and are not usually needed by individual users. + For a typical home user, it will normally suffice to ensure that + Privoxy only listens on the localhost (127.0.0.1) or internal + (home) network address by means of the listen-address option. -You would then need to change your browser's proxy settings to squid's address -and port. Squid normally uses port 3128. If unsure consult http_port in -squid.conf. + Please see the warnings in the FAQ that Privoxy is not intended to + be a substitute for a firewall or to encourage anyone to defer + addressing basic security weaknesses. -You could just as well decide to only forward requests you suspect of leading -to Windows executables through a virus-scanning parent proxy, say, on -antivir.example.com, port 8010: + Multiple ACL lines are OK. If any ACLs are specified, Privoxy only + talks to IP addresses that match at least one permit-access line + and don't match any subsequent deny-access line. In other words, + the last match wins, with the default being deny-access. - forward / . - forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010 + If Privoxy is using a forwarder (see forward below) for a + particular destination URL, the dst_addr that is examined is the + address of the forwarder and NOT the address of the ultimate + target. This is necessary because it may be impossible for the + local Privoxy to determine the IP address of the ultimate target + (that's often what gateways are used for). + You should prefer using IP addresses over DNS names, because the + address lookups take time. All DNS names must resolve! You can not + use domain patterns like "*.org" or partial domain names. If a DNS + name resolves to multiple IP addresses, only the first one is + used. -------------------------------------------------------------------------------- + Denying access to particular sites by ACL may have undesired side + effects if the site in question is hosted on a machine which also + hosts other sites (most sites are). -7.5.4. forwarded-connect-retries + Examples: -Specifies: + Explicitly define the default behavior if no ACL and + listen-address are set: "localhost" is OK. The absence of a + dst_addr implies that all destination addresses are OK: - How often Privoxy retries if a forwarded connection request fails. + permit-access localhost -Type of value: + Allow any host on the same class C subnet as www.privoxy.org + access to nothing but www.example.com (or other domains hosted on + the same system): - Number of retries. + permit-access www.privoxy.org/24 www.example.com/32 -Default value: + Allow access from any host on the 26-bit subnet 192.168.45.64 to + anywhere, with the exception that 192.168.45.73 may not access the + IP address behind www.dirty-stuff.example.com: - 0 + permit-access 192.168.45.64/26 + deny-access 192.168.45.73 www.dirty-stuff.example.com -Effect if unset: + -------------------------------------------------------------------------- - Connections forwarded through other proxies are treated like direct - connections and no retry attempts are made. + 7.4.8. buffer-limit -Notes: + Specifies: - forwarded-connect-retries is mainly interesting for socks4a connections, - where Privoxy can't detect why the connections failed. The connection might - have failed because of a DNS timeout in which case a retry makes sense, but - it might also have failed because the server doesn't exist or isn't - reachable. In this case the retry will just delay the appearance of - Privoxy's error message. + Maximum size of the buffer for content filtering. - Note that in the context of this option, "forwarded connections" includes - all connections that Privoxy forwards through other proxies. This option is - not limited to the HTTP CONNECT method. + Type of value: - Only use this option, if you are getting lots of forwarding-related error - messages that go away when you try again manually. Start with a small value - and check Privoxy's logfile from time to time, to see how many retries are - usually needed. + Size in Kbytes -Examples: + Default value: - forwarded-connect-retries 1 + 4096 -------------------------------------------------------------------------------- + Effect if unset: -7.5.5. accept-intercepted-requests + Use a 4MB (4096 KB) limit. -Specifies: + Notes: - Whether intercepted requests should be treated as valid. + For content filtering, i.e. the +filter and +deanimate-gif + actions, it is necessary that Privoxy buffers the entire document + body. This can be potentially dangerous, since a server could just + keep sending data indefinitely and wait for your RAM to exhaust -- + with nasty consequences. Hence this option. -Type of value: + When a document buffer size reaches the buffer-limit, it is + flushed to the client unfiltered and no further attempt to filter + the rest of the document is made. Remember that there may be + multiple threads running, which might require up to buffer-limit + Kbytes each, unless you have enabled "single-threaded" above. - 0 or 1 + -------------------------------------------------------------------------- -Default value: + 7.5. Forwarding - 0 + This feature allows routing of HTTP requests through a chain of multiple + proxies. -Effect if unset: + Forwarding can be used to chain Privoxy with a caching proxy to speed up + browsing. Using a parent proxy may also be necessary if the machine that + Privoxy runs on has no direct Internet access. - Only proxy requests are accepted, intercepted requests are treated as - invalid. + Note that parent proxies can severely decrease your privacy level. For + example a parent proxy could add your IP address to the request headers + and if it's a caching proxy it may add the "Etag" header to revalidation + requests again, even though you configured Privoxy to remove it. It may + also ignore Privoxy's header time randomization and use the original + values which could be used by the server as cookie replacement to track + your steps between visits. -Notes: + Also specified here are SOCKS proxies. Privoxy supports the SOCKS 4 and + SOCKS 4A protocols. - If you don't trust your clients and want to force them to use Privoxy, - enable this option and configure your packet filter to redirect outgoing - HTTP connections into Privoxy. + -------------------------------------------------------------------------- - Make sure that Privoxy's own requests aren't redirected as well. - Additionally take care that Privoxy can't intentionally connect to itself, - otherwise you could run into redirection loops if Privoxy's listening port - is reachable by the outside or an attacker has access to the pages you - visit. + 7.5.1. forward -Examples: + Specifies: - accept-intercepted-requests 1 + To which parent HTTP proxy specific requests should be routed. -------------------------------------------------------------------------------- + Type of value: -7.5.6. allow-cgi-request-crunching + target_pattern http_parent[:port] -Specifies: + where target_pattern is a URL pattern that specifies to which + requests (i.e. URLs) this forward rule shall apply. Use / to + denote "all URLs". http_parent[:port] is the DNS name or IP + address of the parent HTTP proxy through which the requests should + be forwarded, optionally followed by its listening port (default: + 8080). Use a single dot (.) to denote "no forwarding". - Whether requests to Privoxy's CGI pages can be blocked or redirected. + Default value: -Type of value: + Unset - 0 or 1 + Effect if unset: -Default value: + Don't use parent HTTP proxies. - 0 + Notes: -Effect if unset: + If http_parent is ".", then requests are not forwarded to another + HTTP proxy but are made directly to the web servers. - Privoxy ignores block and redirect actions for its CGI pages. + Multiple lines are OK, they are checked in sequence, and the last + match wins. -Notes: + Examples: - By default Privoxy ignores block or redirect actions for its CGI pages. - Intercepting these requests can be useful in multi-user setups to implement - fine-grained access control, but it can also render the complete web - interface useless and make debugging problems painful if done without care. + Everything goes to an example parent proxy, except SSL on port 443 + (which it doesn't handle): - Don't enable this option unless you're sure that you really need it. + forward / parent-proxy.example.org:8080 + forward :443 . -Examples: + Everything goes to our example ISP's caching proxy, except for + requests to that ISP's sites: - allow-cgi-request-crunching 1 + forward / caching-proxy.isp.example.net:8000 + forward .isp.example.net . -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -7.5.7. split-large-forms + 7.5.2. forward-socks4 and forward-socks4a -Specifies: + Specifies: - Whether the CGI interface should stay compatible with broken HTTP clients. + Through which SOCKS proxy (and optionally to which parent HTTP + proxy) specific requests should be routed. -Type of value: + Type of value: - 0 or 1 + target_pattern socks_proxy[:port] http_parent[:port] -Default value: + where target_pattern is a URL pattern that specifies to which + requests (i.e. URLs) this forward rule shall apply. Use / to + denote "all URLs". http_parent and socks_proxy are IP addresses in + dotted decimal notation or valid DNS names (http_parent may be "." + to denote "no HTTP forwarding"), and the optional port parameters + are TCP ports, i.e. integer values from 1 to 64535 - 0 + Default value: -Effect if unset: + Unset - The CGI form generate long GET URLs. + Effect if unset: -Notes: + Don't use SOCKS proxies. - Privoxy's CGI forms can lead to rather long URLs. This isn't a problem as - far as the HTTP standard is concerned, but it can confuse clients with - arbitrary URL length limitations. + Notes: - Enabling split-large-forms causes Privoxy to divide big forms into smaller - ones to keep the URL length down. It makes editing a lot less convenient - and you can no longer submit all changes at once, but at least it works - around this browser bug. + Multiple lines are OK, they are checked in sequence, and the last + match wins. - If you don't notice any editing problems, there is no reason to enable this - option, but if one of the submit buttons appears to be broken, you should - give it a try. + The difference between forward-socks4 and forward-socks4a is that + in the SOCKS 4A protocol, the DNS resolution of the target + hostname happens on the SOCKS server, while in SOCKS 4 it happens + locally. -Examples: + If http_parent is ".", then requests are not forwarded to another + HTTP proxy but are made (HTTP-wise) directly to the web servers, + albeit through a SOCKS proxy. - split-large-forms 1 + Examples: -------------------------------------------------------------------------------- + From the company example.com, direct connections are made to all + "internal" domains, but everything outbound goes through their + ISP's proxy by way of example.com's corporate SOCKS 4A gateway to + the Internet. -7.6. Windows GUI Options + forward-socks4a / socks-gw.example.com:1080 www-cache.isp.example.net:8080 + forward .example.com . -Privoxy has a number of options specific to the Windows GUI interface: + A rule that uses a SOCKS 4 gateway for all destinations but no + HTTP parent looks like this: -If "activity-animation" is set to 1, the Privoxy icon will animate when -"Privoxy" is active. To turn off, set to 0. + forward-socks4 / socks-gw.example.com:1080 . - activity-animation 1 - + To chain Privoxy and Tor, both running on the same system, you + would use something like: -If "log-messages" is set to 1, Privoxy will log messages to the console window: + forward-socks4a / 127.0.0.1:9050 . - log-messages 1 - + The public Tor network can't be used to reach your local network, + if you need to access local servers you therefore might want to + make some exceptions: -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). + forward 192.168.*.*/ . + forward 10.*.*.*/ . + forward 127.*.*.*/ . -Warning: Setting this to 0 will result in the buffer to grow infinitely and eat -up all your memory! + Unencrypted connections to systems in these address ranges will be + as (un)secure as the local network is, but the alternative is that + you can't reach the local network through Privoxy at all. Of + course this may actually be desired and there is no reason to make + these exceptions if you aren't sure you need them. - log-buffer-size 1 - + If you also want to be able to reach servers in your local network + by using their names, you will need additional exceptions that + look like this: -log-max-lines is the maximum number of lines held in the log buffer. See above. + forward localhost/ . - log-max-lines 200 - + -------------------------------------------------------------------------- -If "log-highlight-messages" is set to 1, Privoxy will highlight portions of the -log messages with a bold-faced font: + 7.5.3. Advanced Forwarding Examples - log-highlight-messages 1 - + If you have links to multiple ISPs that provide various special content + only to their subscribers, you can configure multiple Privoxies which have + connections to the respective ISPs to act as forwarders to each other, so + that your users can see the internal content of all ISPs. -The font used in the console window: + Assume that host-a has a PPP connection to isp-a.example.net. And host-b + has a PPP connection to isp-b.example.org. Both run Privoxy. Their + forwarding configuration can look like this: - log-font-name Comic Sans MS - + host-a: -Font size used in the console window: + forward / . + forward .isp-b.example.net host-b:8118 - log-font-size 8 - + host-b: -"show-on-task-bar" controls whether or not Privoxy will appear as a button on -the Task bar when minimized: + forward / . + forward .isp-a.example.org host-a:8118 - show-on-task-bar 0 - + Now, your users can set their browser's proxy to use either host-a or + host-b and be able to browse the internal content of both isp-a and isp-b. -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). + If you intend to chain Privoxy and squid locally, then chaining as browser + -> squid -> privoxy is the recommended way. - close-button-minimizes 1 - + Assuming that Privoxy and squid run on the same box, your squid + configuration could then look like this: -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. + # Define Privoxy as parent proxy (without ICP) + cache_peer 127.0.0.1 parent 8118 7 no-query - #hide-console - + # Define ACL for protocol FTP + acl ftp proto FTP -------------------------------------------------------------------------------- + # Do not forward FTP requests to Privoxy + always_direct allow ftp -8. Actions Files + # Forward all the rest to Privoxy + never_direct allow all -The actions files are used to define what actions Privoxy takes for which URLs, -and thus determines how ad images, cookies and various other aspects of HTTP -content and transactions are handled, and on which sites (or even parts -thereof). There are a number of such actions, with a wide range of -functionality. Each action does something a little different. These actions -give us a veritable arsenal of tools with which to exert our control, -preferences and independence. Actions can be combined so that their effects are -aggregated when applied against a given set of URLs. - -There are three action 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 as-is for most users. This is the file that the - developers are keeping updated, and making available to users. The user's - preferences as set in standard.action, e.g. either Cautious (the default), - Medium, or Advanced (see below). - - * 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 only by the web based editor at http:// - config.privoxy.org/edit-actions-list?f=default, to set various pre-defined - sets of rules for the default actions section in default.action. - - Edit Set to Cautious Set to Medium Set to Advanced - - These have increasing levels of aggressiveness and have no influence on - your browsing unless you select them explicitly in the editor. A default - installation should be pre-set to Cautious (versions prior to 3.0.5 were - set to Medium). New users should try this for a while before adjusting the - settings to more aggressive levels. The more aggressive the settings, then - the more likelihood there is of problems such as sites not working as they - should. - - The Edit button allows you to turn each action on/off individually for - fine-tuning. The Cautious button changes the actions list to low/safe - settings which will activate ad blocking and a minimal set of Privoxy's - features, and subsequently there will be less of a chance for accidental - problems. The Medium button sets the list to a medium level of other - features and a low level set of privacy features. The Advanced button sets - the list to a high level of ad blocking and medium level of privacy. See - the chart below. The latter three buttons over-ride any changes via with - the Edit button. More fine-tuning can be done in the lower sections of this - internal page. - - It is not recommend to edit the standard.action file itself. - - The default profiles, and their associated actions, as pre-defined in - standard.action are: - - Table 1. Default Configurations - - +---------------------------------------------------------------+ - | Feature | Cautious | Medium | Advanced | - |--------------------------+-----------+------------+-----------| - |Ad-blocking Aggressiveness|medium |high |high | - |--------------------------+-----------+------------+-----------| - |Ad-filtering by size |no |yes |yes | - |--------------------------+-----------+------------+-----------| - |Ad-filtering by link |no |no |yes | - |--------------------------+-----------+------------+-----------| - |Pop-up killing |blocks only|blocks only |blocks only| - |--------------------------+-----------+------------+-----------| - |Privacy Features |low |medium |medium/high| - |--------------------------+-----------+------------+-----------| - |Cookie handling |none |session-only|kill | - |--------------------------+-----------+------------+-----------| - |Referer forging |no |yes |yes | - |--------------------------+-----------+------------+-----------| - |GIF de-animation |no |yes |yes | - |--------------------------+-----------+------------+-----------| - |Fast redirects |no |no |yes | - |--------------------------+-----------+------------+-----------| - |HTML taming |no |no |yes | - |--------------------------+-----------+------------+-----------| - |JavaScript taming |no |no |yes | - |--------------------------+-----------+------------+-----------| - |Web-bug killing |no |yes |yes | - |--------------------------+-----------+------------+-----------| - |Image tag reordering |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 processed before user.action). The content of these can all be viewed -and edited from http://config.privoxy.org/show-status. The over-riding -principle when applying actions, is that the last action that matches a given -URL wins. The broadest, most general rules go first (defined in -default.action), followed by any exceptions (typically also in default.action), -which are then followed lastly by any local preferences (typically in -user.action). Generally, user.action has the last word. - -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 it is a separate file, -which makes preserving your personal settings across Privoxy upgrades easier. - -Actions can be used to block anything you want, including ads, banners, or just -some obnoxious URL whose content 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, some JavaScripts tamed, -user-tracking fooled, and much more. See below for a complete list of actions. - -------------------------------------------------------------------------------- - -8.1. Finding the Right Mix - -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. And, things can always change, requiring refinements in the -configuration. 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 purposes, like maybe your bank, favorite shop, or newspaper. - -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 -:). - -------------------------------------------------------------------------------- - -8.2. How to Edit - -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. Note: the config file option enable-edit-actions must be enabled -for this to work. 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 "Advanced". Warning: the "Advanced" setting is -more aggressive, and will be more likely to cause problems for some sites. -Experienced users only! - -If you prefer plain text editing to GUIs, you can of course also directly edit -the the actions files with your favorite text editor. Look at default.action -which is richly commented with many good examples. - -------------------------------------------------------------------------------- - -8.3. How Actions are Applied to Requests - -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 and tag -patterns, each on a separate line. - -To determine which actions apply to a request, the URL of the request is -compared to all URL patterns in each "action file". Every time it matches, the -list of applicable actions for the request is incrementally updated, using the -heading of the section in which the pattern is located. The same is done again -for tags and tag patterns later on. - -If multiple applying sections 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. And there may well be -cases where you will want to combine actions together. Such a section then -might look like: - - { +handle-as-image +block } - # Block these as if they were images. Send no block page. - banners.example.com - media.example.com/.*banners - .example.com/images/ads/ + You would then need to change your browser's proxy settings to squid's + address and port. Squid normally uses port 3128. If unsure consult + http_port in squid.conf. + You could just as well decide to only forward requests you suspect of + leading to Windows executables through a virus-scanning parent proxy, say, + on antivir.example.com, port 8010: -You can trace this process for URL patterns and any given URL by visiting http: -//config.privoxy.org/show-url-info. + forward / . + forward /.*\.(exe|com|dll|zip)$ antivir.example.com:8010 -Examples and more detail on this is provided in the Appendix, Troubleshooting: -Anatomy of an Action section. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 7.5.4. forwarded-connect-retries -8.4. Patterns + Specifies: -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. + How often Privoxy retries if a forwarded connection request fails. -Generally, an URL 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! + Type of value: -The pattern matching syntax is different for the domain and path parts of the -URL. The domain part uses a simple globbing type matching technique, while the -path part uses a more flexible "Regular Expressions (PCRE)" based syntax. + Number of retries. -www.example.com/ + Default value: - is a domain-only pattern and will match any request to www.example.com, - regardless of which document on that server is requested. So ALL pages in - this domain would be covered by the scope of this action. Note that a - simple example.com is different and would NOT match. + 0 -www.example.com + Effect if unset: - means exactly the same. For domain-only patterns, the trailing / may be - omitted. + Connections forwarded through other proxies are treated like + direct connections and no retry attempts are made. -www.example.com/index.html$ + Notes: - matches all the documents on www.example.com whose name starts with / - index.html. + forwarded-connect-retries is mainly interesting for socks4a + connections, where Privoxy can't detect why the connections + failed. The connection might have failed because of a DNS timeout + in which case a retry makes sense, but it might also have failed + because the server doesn't exist or isn't reachable. In this case + the retry will just delay the appearance of Privoxy's error + message. -www.example.com/index.html$ + Note that in the context of this option, "forwarded connections" + includes all connections that Privoxy forwards through other + proxies. This option is not limited to the HTTP CONNECT method. - matches only the single document /index.html on www.example.com. + Only use this option, if you are getting lots of + forwarding-related error messages that go away when you try again + manually. Start with a small value and check Privoxy's logfile + from time to time, to see how many retries are usually needed. -/index.html$ + Examples: - matches the document /index.html, regardless of the domain, i.e. on any web - server anywhere. + forwarded-connect-retries 1 -index.html + -------------------------------------------------------------------------- - matches nothing, since it would be interpreted as a domain name and there - is no top-level domain called .html. So its a mistake. + 7.5.5. accept-intercepted-requests -------------------------------------------------------------------------------- + Specifies: -8.4.1. The Domain Pattern + Whether intercepted requests should be treated as valid. -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: + Type of value: -.example.com + 0 or 1 - matches any domain with first-level domain com and second-level domain - example. For example www.example.com, example.com and - foo.bar.baz.example.com. Note that it wouldn't match if the second-level - domain was another-example. + Default value: -www. + 0 - matches any domain that STARTS with www. (It also matches the domain www - but most of the time that doesn't matter.) + Effect if unset: -.example. + Only proxy requests are accepted, intercepted requests are treated + as invalid. - matches any domain that CONTAINS .example.. And, by the way, also included - would be any files or documents that exist within that domain since no path - limitations are specified. (Correctly speaking: It matches any FQDN that - contains example as a domain.) This might be www.example.com, - news.example.de, or www.example.net/cgi/testing.pl for instance. All these - cases are matched. + Notes: -Additionally, there are wild-cards that you can use in the domain names -themselves. These work similarly to shell globbing type wild-cards: "*" -represents zero or more arbitrary characters (this is equivalent to the -"Regular Expression" based syntax of ".*"), "?" represents any single character -(this is equivalent to the regular expression syntax of a simple "."), and you -can define "character classes" in square brackets which is similar to the same -regular expression technique. All of this can be freely mixed: + If you don't trust your clients and want to force them to use + Privoxy, enable this option and configure your packet filter to + redirect outgoing HTTP connections into Privoxy. -ad*.example.com + Make sure that Privoxy's own requests aren't redirected as well. + Additionally take care that Privoxy can't intentionally connect to + itself, otherwise you could run into redirection loops if + Privoxy's listening port is reachable by the outside or an + attacker has access to the pages you visit. - matches "adserver.example.com", "ads.example.com", etc but not - "sfads.example.com" + Examples: -*ad*.example.com + accept-intercepted-requests 1 - matches all of the above, and then some. + -------------------------------------------------------------------------- -.?pix.com + 7.5.6. allow-cgi-request-crunching - matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc. + Specifies: -www[1-9a-ez].example.c* + Whether requests to Privoxy's CGI pages can be blocked or + redirected. - matches www1.example.com, www4.example.cc, wwwd.example.cy, - wwwz.example.com etc., but not wwww.example.com. + Type of value: -While flexible, this is not the sophistication of full regular expression based -syntax. + 0 or 1 -------------------------------------------------------------------------------- + Default value: -8.4.2. The Path Pattern + 0 -Privoxy uses Perl compatible (PCRE) "Regular Expression" based syntax (through -the PCRE library) for matching the path portion (after the slash), and is thus -more flexible. + Effect if unset: -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:// -perldoc.perl.org/perlre.html. + Privoxy ignores block and redirect actions for its CGI pages. -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). + Notes: -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. + By default Privoxy ignores block or redirect actions for its CGI + pages. Intercepting these requests can be useful in multi-user + setups to implement fine-grained access control, but it can also + render the complete web interface useless and make debugging + problems painful if done without care. -.example.com/.* + Don't enable this option unless you're sure that you really need + it. - Is equivalent to just ".example.com", since any documents within that - domain are matched with or without the ".*" regular expression. This is - redundant + Examples: -.example.com/.*/index.html$ + allow-cgi-request-crunching 1 - Will match any page in the domain of "example.com" that is named - "index.html", and that is part of some path. For example, it matches - "www.example.com/testing/index.html" but NOT "www.example.com/index.html" - because the regular expression called for at least two "/'s", thus the path - requirement. It also would match "www.example.com/testing/index_html", - because of the special meta-character ".". + -------------------------------------------------------------------------- -.example.com/(.*/)?index\.html$ + 7.5.7. split-large-forms - This regular expression is conditional so it will match any page named - "index.html" regardless of path which in this case can have one or more "/ - 's". And this one must contain exactly ".html" (but does not have to end - with that!). + Specifies: -.example.com/(.*/)(ads|banners?|junk) + Whether the CGI interface should stay compatible with broken HTTP + clients. - This regular expression will match any path of "example.com" that contains - any of the words "ads", "banner", "banners" (because of the "?") or "junk". - The path does not have to end in these words, just contain them. + Type of value: -.example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$ + 0 or 1 - This is very much the same as above, except now it must end in either - ".jpg", ".jpeg", ".gif" or ".png". So this one is limited to common image - formats. + Default value: -There are many, many good examples to be found in default.action, and more -tutorials below in Appendix on regular expressions. + 0 -------------------------------------------------------------------------------- + Effect if unset: -8.4.3. The Tag Pattern + The CGI form generate long GET URLs. -Tag patterns are used to change the applying actions based on the request's -tags. Tags can be created with either the client-header-tagger or the -server-header-tagger action. + Notes: -Tag patterns have to start with "TAG:", so Privoxy can tell them apart from URL -patterns. Everything after the colon including white space, is interpreted as a -regular expression with path pattern syntax, except that tag patterns aren't -left-anchored automatically (Privoxy doesn't silently add a "^", you have to do -it yourself if you need it). + Privoxy's CGI forms can lead to rather long URLs. This isn't a + problem as far as the HTTP standard is concerned, but it can + confuse clients with arbitrary URL length limitations. -To match all requests that are tagged with "foo" your pattern line should be -"TAG:^foo$", "TAG:foo" would work as well, but it would also match requests -whose tags contain "foo" somewhere. "TAG: foo" wouldn't work as it requires -white space. + Enabling split-large-forms causes Privoxy to divide big forms into + smaller ones to keep the URL length down. It makes editing a lot + less convenient and you can no longer submit all changes at once, + but at least it works around this browser bug. -Sections can contain URL and tag patterns at the same time, but tag patterns -are checked after the URL patterns and thus always overrule them, even if they -are located before the URL patterns. + If you don't notice any editing problems, there is no reason to + enable this option, but if one of the submit buttons appears to be + broken, you should give it a try. -Once a new tag is added, Privoxy checks right away if it's matched by one of -the tag patterns and updates the action settings accordingly. As a result tags -can be used to activate other tagger actions, as long as these other taggers -look for headers that haven't already be parsed. + Examples: -For example you could tag client requests which use the POST method, then use -this tag to activate another tagger that adds a tag if cookies are sent, and -then use a block action based on the cookie tag. This allows the outcome of one -action, to be input into a subsequent action. However if you'd reverse the -position of the described taggers, and activated the method tagger based on the -cookie tagger, no method tags would be created. The method tagger would look -for the request line, but at the time the cookie tag is created, the request -line has already been parsed. + split-large-forms 1 -While this is a limitation you should be aware of, this kind of indirection is -seldom needed anyway and even the example doesn't make too much sense. + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 7.6. Windows GUI Options -8.5. Actions + Privoxy has a number of options specific to the Windows GUI interface: -All actions are disabled by default, until they are explicitly enabled -somewhere in an actions file. Actions are turned on if preceded with a "+", and -turned off if preceded with a "-". So a +action means "do that action", e.g. -+block means "please block URLs that match the following patterns", and -block -means "don't block URLs that match the following patterns, even if +block -previously applied." + If "activity-animation" is set to 1, the Privoxy icon will animate when + "Privoxy" is active. To turn off, set to 0. -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. + activity-animation 1 -Actions fall into three categories: - * Boolean, i.e the action can only be "enabled" or "disabled". Syntax: + If "log-messages" is set to 1, Privoxy will log messages to the console + window: - +name # enable action name - -name # disable action name + log-messages 1 - Example: +block + If "log-buffer-size" is set to 1, the size of the log buffer, i.e. the + amount of memory used for the log messages displayed in the console + window, will be limited to "log-max-lines" (see below). - * Parameterized, where some value is required in order to enable this type of - action. Syntax: + Warning: Setting this to 0 will result in the buffer to grow infinitely + and eat up all your memory! - +name{param} # enable action and set parameter to param, - # overwriting parameter from previous match if necessary - -name # disable action. The parameter can be omitted + log-buffer-size 1 - 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. + log-max-lines is the maximum number of lines held in the log buffer. See + above. - Example: +hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; - rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4} + log-max-lines 200 - * 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 + If "log-highlight-messages" is set to 1, Privoxy will highlight portions + of the log messages with a bold-faced font: + log-highlight-messages 1 - Examples: +add-header{X-Fun-Header: Some text} and +filter{html-annoyances} -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-filtering proxy. You -must specifically enable the privacy and blocking features you need (although -the provided default actions files will give a good starting point). + The font used in the console window: -Later defined action sections always over-ride earlier ones of the same type. -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 such as -user.action). 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 to match more than one "pattern" (because of -wildcards and regular expressions), and thus to trigger more than one set of -actions! Last match wins. + log-font-name Comic Sans MS -The list of valid Privoxy actions are: -------------------------------------------------------------------------------- + Font size used in the console window: -8.5.1. add-header + log-font-size 8 -Typical use: - Confuse log analysis, custom applications + "show-on-task-bar" controls whether or not Privoxy will appear as a button + on the Task bar when minimized: -Effect: + show-on-task-bar 0 - Sends a user defined HTTP header to the web server. -Type: + 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). - Multi-value. + close-button-minimizes 1 -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. + 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. -Notes: + #hide-console - 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. -Example usage: + -------------------------------------------------------------------------- - +add-header{X-User-Tracking: sucks} +8. Actions Files + The actions files are used to define what actions Privoxy takes for which + URLs, and thus determines how ad images, cookies and various other aspects + of HTTP content and transactions are handled, and on which sites (or even + parts thereof). There are a number of such actions, with a wide range of + functionality. Each action does something a little different. These + actions give us a veritable arsenal of tools with which to exert our + control, preferences and independence. Actions can be combined so that + their effects are aggregated when applied against a given set of URLs. + + There are three action 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 as-is for most users. This is + the file that the developers are keeping updated, and making available + to users. The user's preferences as set in standard.action, e.g. + either Cautious (the default), Medium, or Advanced (see below). + + * 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 only by the web based editor at + http://config.privoxy.org/edit-actions-list?f=default, to set various + pre-defined sets of rules for the default actions section in + default.action. + + Edit Set to Cautious Set to Medium Set to Advanced + + These have increasing levels of aggressiveness and have no influence + on your browsing unless you select them explicitly in the editor. A + default installation should be pre-set to Cautious (versions prior to + 3.0.5 were set to Medium). New users should try this for a while + before adjusting the settings to more aggressive levels. The more + aggressive the settings, then the more likelihood there is of problems + such as sites not working as they should. + + The Edit button allows you to turn each action on/off individually for + fine-tuning. The Cautious button changes the actions list to low/safe + settings which will activate ad blocking and a minimal set of + Privoxy's features, and subsequently there will be less of a chance + for accidental problems. The Medium button sets the list to a medium + level of other features and a low level set of privacy features. The + Advanced button sets the list to a high level of ad blocking and + medium level of privacy. See the chart below. The latter three buttons + over-ride any changes via with the Edit button. More fine-tuning can + be done in the lower sections of this internal page. + + It is not recommend to edit the standard.action file itself. + + The default profiles, and their associated actions, as pre-defined in + standard.action are: + + Table 1. Default Configurations + + +--------------------------------------------------------------------+ + | Feature | Cautious | Medium | Advanced | + |-------------------------+-------------+--------------+-------------| + | Ad-blocking | medium | high | high | + | Aggressiveness | | | | + |-------------------------+-------------+--------------+-------------| + | Ad-filtering by size | no | yes | yes | + |-------------------------+-------------+--------------+-------------| + | Ad-filtering by link | no | no | yes | + |-------------------------+-------------+--------------+-------------| + | Pop-up killing | blocks only | blocks only | blocks only | + |-------------------------+-------------+--------------+-------------| + | Privacy Features | low | medium | medium/high | + |-------------------------+-------------+--------------+-------------| + | Cookie handling | none | session-only | kill | + |-------------------------+-------------+--------------+-------------| + | Referer forging | no | yes | yes | + |-------------------------+-------------+--------------+-------------| + | GIF de-animation | no | yes | yes | + |-------------------------+-------------+--------------+-------------| + | Fast redirects | no | no | yes | + |-------------------------+-------------+--------------+-------------| + | HTML taming | no | no | yes | + |-------------------------+-------------+--------------+-------------| + | JavaScript taming | no | no | yes | + |-------------------------+-------------+--------------+-------------| + | Web-bug killing | no | yes | yes | + |-------------------------+-------------+--------------+-------------| + | Image tag reordering | 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 processed before user.action). The content of these can all + be viewed and edited from http://config.privoxy.org/show-status. The + over-riding principle when applying actions, is that the last action that + matches a given URL wins. The broadest, most general rules go first + (defined in default.action), followed by any exceptions (typically also in + default.action), which are then followed lastly by any local preferences + (typically in user.action). Generally, user.action has the last word. + + 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 it is a separate file, which makes preserving your + personal settings across Privoxy upgrades easier. + + Actions can be used to block anything you want, including ads, banners, or + just some obnoxious URL whose content 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, some + JavaScripts tamed, user-tracking fooled, and much more. See below for a + complete list of actions. + + -------------------------------------------------------------------------- + + 8.1. Finding the Right Mix + + 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. And, things can always change, requiring refinements in + the configuration. 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 purposes, like maybe your bank, + favorite shop, or newspaper. + + 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 :). + + -------------------------------------------------------------------------- + + 8.2. How to Edit + + 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. Note: the config file option + enable-edit-actions must be enabled for this to work. 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 "Advanced". Warning: the "Advanced" setting is more + aggressive, and will be more likely to cause problems for some sites. + Experienced users only! + + If you prefer plain text editing to GUIs, you can of course also directly + edit the the actions files with your favorite text editor. Look at + default.action which is richly commented with many good examples. + + -------------------------------------------------------------------------- + + 8.3. How Actions are Applied to Requests + + 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 and tag patterns, each on a separate line. + + To determine which actions apply to a request, the URL of the request is + compared to all URL patterns in each "action file". Every time it matches, + the list of applicable actions for the request is incrementally updated, + using the heading of the section in which the pattern is located. The same + is done again for tags and tag patterns later on. + + If multiple applying sections 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. And + there may well be cases where you will want to combine actions together. + Such a section then might look like: + + { +handle-as-image +block } + # Block these as if they were images. Send no block page. + banners.example.com + media.example.com/.*banners + .example.com/images/ads/ + + You can trace this process for URL patterns and any given URL by visiting + http://config.privoxy.org/show-url-info. + + Examples and more detail on this is provided in the Appendix, + Troubleshooting: Anatomy of an Action section. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.5.2. block + 8.4. Patterns -Typical use: + 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. - Block ads or other unwanted content + Generally, an URL 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! -Effect: + The pattern matching syntax is different for the domain and path parts of + the URL. The domain part uses a simple globbing type matching technique, + while the path part uses a more flexible "Regular Expressions (PCRE)" + based syntax. - Requests for URLs to which this action applies are blocked, i.e. the - requests are trapped by Privoxy and the requested URL is never retrieved, - but is answered locally with a substitute page or image, as determined by - the handle-as-image, set-image-blocker, and handle-as-empty-document - actions. + www.example.com/ -Type: + is a domain-only pattern and will match any request to + www.example.com, regardless of which document on that server is + requested. So ALL pages in this domain would be covered by the + scope of this action. Note that a simple example.com is different + and would NOT match. - Boolean. + www.example.com -Parameter: + means exactly the same. For domain-only patterns, the trailing / + may be omitted. - N/A + www.example.com/index.html$ -Notes: + matches all the documents on www.example.com whose name starts + with /index.html. - 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. + www.example.com/index.html$ - 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. + matches only the single document /index.html on www.example.com. - It is important to understand this process, in order to understand how - Privoxy deals with ads and other unwanted content. Blocking is a core - feature, and one upon which various other features depend. + /index.html$ - 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. + matches the document /index.html, regardless of the domain, i.e. + on any web server anywhere. -Example usage (section): + index.html - {+block} - # Block and replace with "blocked" page - .nasty-stuff.example.com + matches nothing, since it would be interpreted as a domain name + and there is no top-level domain called .html. So its a mistake. - {+block +handle-as-image} - # Block and replace with image - .ad.doubleclick.net - .ads.r.us/banners/ + -------------------------------------------------------------------------- - {+block +handle-as-empty-document} - # Block and then ignore - adserver.exampleclick.net/.*\.js$ + 8.4.1. The Domain Pattern + The matching of the domain part offers some flexible options: if the + domain starts or ends with a dot, it becomes unanchored at that end. For + example: -------------------------------------------------------------------------------- + .example.com -8.5.3. client-header-filter + matches any domain with first-level domain com and second-level + domain example. For example www.example.com, example.com and + foo.bar.baz.example.com. Note that it wouldn't match if the + second-level domain was another-example. -Typical use: + www. - Rewrite or remove single client headers. + matches any domain that STARTS with www. (It also matches the + domain www but most of the time that doesn't matter.) -Effect: + .example. - All client headers to which this action applies are filtered on-the-fly - through the specified regular expression based substitutions. + matches any domain that CONTAINS .example.. And, by the way, also + included would be any files or documents that exist within that + domain since no path limitations are specified. (Correctly + speaking: It matches any FQDN that contains example as a domain.) + This might be www.example.com, news.example.de, or + www.example.net/cgi/testing.pl for instance. All these cases are + matched. -Type: + Additionally, there are wild-cards that you can use in the domain names + themselves. These work similarly to shell globbing type wild-cards: "*" + represents zero or more arbitrary characters (this is equivalent to the + "Regular Expression" based syntax of ".*"), "?" represents any single + character (this is equivalent to the regular expression syntax of a simple + "."), and you can define "character classes" in square brackets which is + similar to the same regular expression technique. All of this can be + freely mixed: - Parameterized. + ad*.example.com -Parameter: + matches "adserver.example.com", "ads.example.com", etc but not + "sfads.example.com" - The name of a client-header filter, as defined in one of the filter files. + *ad*.example.com -Notes: + matches all of the above, and then some. - Client-header filters are applied to each header on its own, not to all at - once. This makes it easier to diagnose problems, but on the downside you - can't write filters that only change header x if header y's value is z. You - can do that by using tags though. + .?pix.com - Client-header filters are executed after the other header actions have - finished and use their output as input. + matches www.ipix.com, pictures.epix.com, a.b.c.d.e.upix.com etc. - If the request URL gets changed, Privoxy will detect that and use the new - one. This can be used to rewrite the request destination behind the - client's back, for example to specify a Tor exit relay for certain - requests. + www[1-9a-ez].example.c* - Please refer to the filter file chapter to learn which client-header - filters are available by default, and how to create your own. + matches www1.example.com, www4.example.cc, wwwd.example.cy, + wwwz.example.com etc., but not wwww.example.com. -Example usage (section): + While flexible, this is not the sophistication of full regular expression + based syntax. - {+client-header-filter{hide-tor-exit-notation}} - .exit/ + -------------------------------------------------------------------------- + 8.4.2. The Path Pattern + Privoxy uses Perl compatible (PCRE) "Regular Expression" based syntax + (through the PCRE library) for matching the path portion (after the + slash), and is thus more flexible. -------------------------------------------------------------------------------- + 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://perldoc.perl.org/perlre.html. -8.5.4. client-header-tagger + 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). -Typical use: + 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. - Block requests based on their headers. + .example.com/.* -Effect: + Is equivalent to just ".example.com", since any documents within + that domain are matched with or without the ".*" regular + expression. This is redundant - Client headers to which this action applies are filtered on-the-fly through - the specified regular expression based substitutions, the result is used as - tag. + .example.com/.*/index.html$ -Type: + Will match any page in the domain of "example.com" that is named + "index.html", and that is part of some path. For example, it + matches "www.example.com/testing/index.html" but NOT + "www.example.com/index.html" because the regular expression called + for at least two "/'s", thus the path requirement. It also would + match "www.example.com/testing/index_html", because of the special + meta-character ".". - Parameterized. + .example.com/(.*/)?index\.html$ -Parameter: + This regular expression is conditional so it will match any page + named "index.html" regardless of path which in this case can have + one or more "/'s". And this one must contain exactly ".html" (but + does not have to end with that!). - The name of a client-header tagger, as defined in one of the filter files. + .example.com/(.*/)(ads|banners?|junk) -Notes: + This regular expression will match any path of "example.com" that + contains any of the words "ads", "banner", "banners" (because of + the "?") or "junk". The path does not have to end in these words, + just contain them. - Client-header taggers are applied to each header on its own, and as the - header isn't modified, each tagger "sees" the original. + .example.com/(.*/)(ads|banners?|junk)/.*\.(jpe?g|gif|png)$ - Client-header taggers are the first actions that are executed and their - tags can be used to control every other action. + This is very much the same as above, except now it must end in + either ".jpg", ".jpeg", ".gif" or ".png". So this one is limited + to common image formats. -Example usage (section): + There are many, many good examples to be found in default.action, and more + tutorials below in Appendix on regular expressions. - # Tag every request with the User-Agent header - {+client-header-tagger{user-agent}} - / + -------------------------------------------------------------------------- + 8.4.3. The Tag Pattern + Tag patterns are used to change the applying actions based on the + request's tags. Tags can be created with either the client-header-tagger + or the server-header-tagger action. -------------------------------------------------------------------------------- + Tag patterns have to start with "TAG:", so Privoxy can tell them apart + from URL patterns. Everything after the colon including white space, is + interpreted as a regular expression with path pattern syntax, except that + tag patterns aren't left-anchored automatically (Privoxy doesn't silently + add a "^", you have to do it yourself if you need it). -8.5.5. content-type-overwrite + To match all requests that are tagged with "foo" your pattern line should + be "TAG:^foo$", "TAG:foo" would work as well, but it would also match + requests whose tags contain "foo" somewhere. "TAG: foo" wouldn't work as + it requires white space. -Typical use: + Sections can contain URL and tag patterns at the same time, but tag + patterns are checked after the URL patterns and thus always overrule them, + even if they are located before the URL patterns. - Stop useless download menus from popping up, or change the browser's - rendering mode + Once a new tag is added, Privoxy checks right away if it's matched by one + of the tag patterns and updates the action settings accordingly. As a + result tags can be used to activate other tagger actions, as long as these + other taggers look for headers that haven't already be parsed. -Effect: + For example you could tag client requests which use the POST method, then + use this tag to activate another tagger that adds a tag if cookies are + sent, and then use a block action based on the cookie tag. This allows the + outcome of one action, to be input into a subsequent action. However if + you'd reverse the position of the described taggers, and activated the + method tagger based on the cookie tagger, no method tags would be created. + The method tagger would look for the request line, but at the time the + cookie tag is created, the request line has already been parsed. - Replaces the "Content-Type:" HTTP server header. + While this is a limitation you should be aware of, this kind of + indirection is seldom needed anyway and even the example doesn't make too + much sense. -Type: + -------------------------------------------------------------------------- - Parameterized. + 8.5. Actions -Parameter: + 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." - Any string. + 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. -Notes: + Actions fall into three categories: - 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. + * Boolean, i.e the action can only be "enabled" or "disabled". Syntax: - 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. + +name # enable action name + -name # disable action name - 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. + Example: +block - 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. + * Parameterized, where some value is required in order to enable this + type of action. Syntax: - 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. + +name{param} # enable action and set parameter to param, + # overwriting parameter from previous match if necessary + -name # disable action. The parameter can be omitted - Most of the time it's easier to replace this action with a custom - server-header filter. 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. + 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. - 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: +hide-user-agent{Mozilla/5.0 (X11; U; FreeBSD i386; en-US; + rv:1.8.1.4) Gecko/20070602 Firefox/2.0.0.4} -Example usage (sections): + * 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: - # Check if www.example.net/ really uses valid XHTML - { +content-type-overwrite{application/xml} } - www.example.net/ + +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 - # 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 + Examples: +add-header{X-Fun-Header: Some text} and + +filter{html-annoyances} + 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-filtering + proxy. You must specifically enable the privacy and blocking features you + need (although the provided default actions files will give a good + starting point). -------------------------------------------------------------------------------- + Later defined action sections always over-ride earlier ones of the same + type. 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 such as user.action). 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 to match + more than one "pattern" (because of wildcards and regular expressions), + and thus to trigger more than one set of actions! Last match wins. -8.5.6. crunch-client-header + The list of valid Privoxy actions are: -Typical use: + -------------------------------------------------------------------------- - Remove a client header Privoxy has no dedicated action for. + 8.5.1. add-header -Effect: + Typical use: - Deletes every header sent by the client that contains the string the user - supplied as parameter. + Confuse log analysis, custom applications -Type: + Effect: - Parameterized. + Sends a user defined HTTP header to the web server. -Parameter: + Type: - Any string. + Multi-value. -Notes: + Parameter: - 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. + 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. - 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. + Notes: - 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 - use a client-header filter. + 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. - +-----------------------------------------------------------------+ - | Warning | - |-----------------------------------------------------------------| - |Don't block any header without understanding the consequences. | - +-----------------------------------------------------------------+ -Example usage (section): + Example usage: - # Block the non-existent "Privacy-Violation:" client header - { +crunch-client-header{Privacy-Violation:} } - / + +add-header{X-User-Tracking: sucks} + -------------------------------------------------------------------------- + 8.5.2. block -------------------------------------------------------------------------------- + Typical use: -8.5.7. crunch-if-none-match + Block ads or other unwanted content -Typical use: + Effect: - Prevent yet another way to track the user's steps between sessions. + Requests for URLs to which this action applies are blocked, i.e. + the requests are trapped by Privoxy and the requested URL is never + retrieved, but is answered locally with a substitute page or + image, as determined by the handle-as-image, set-image-blocker, + and handle-as-empty-document actions. -Effect: + Type: - Deletes the "If-None-Match:" HTTP client header. + Boolean. -Type: + Parameter: - Boolean. + N/A -Parameter: + Notes: - N/A + 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. -Notes: + 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. - 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 important to understand this process, in order to understand + how Privoxy deals with ads and other unwanted content. Blocking is + a core feature, and one upon which various other features depend. - It is also useful to make sure the header isn't used as a cookie - replacement (unlikely but possible). + 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. - Blocking the "If-None-Match:" header shouldn't cause any caching problems, - as long as the "If-Modified-Since:" header isn't blocked or missing as - well. + Example usage (section): - It is recommended to use this action together with hide-if-modified-since - and overwrite-last-modified. + {+block} + # Block and replace with "blocked" page + .nasty-stuff.example.com -Example usage (section): + {+block +handle-as-image} + # Block and replace with image + .ad.doubleclick.net + .ads.r.us/banners/ - # Let the browser revalidate cached documents but don't - # allow the server to use the revalidation headers for user tracking. - {+hide-if-modified-since{-60} \ - +overwrite-last-modified{randomize} \ - +crunch-if-none-match} - / + {+block +handle-as-empty-document} + # Block and then ignore + adserver.exampleclick.net/.*\.js$ + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 8.5.3. client-header-filter -8.5.8. crunch-incoming-cookies + Typical use: -Typical use: + Rewrite or remove single client headers. - Prevent the web server from setting HTTP cookies on your system + Effect: -Effect: + All client headers to which this action applies are filtered + on-the-fly through the specified regular expression based + substitutions. - Deletes any "Set-Cookie:" HTTP headers from server replies. + Type: -Type: + Parameterized. - Boolean. + Parameter: -Parameter: + The name of a client-header filter, as defined in one of the + filter files. - N/A + Notes: -Notes: + Client-header filters are applied to each header on its own, not + to all at once. This makes it easier to diagnose problems, but on + the downside you can't write filters that only change header x if + header y's value is z. You can do that by using tags though. - This action is only concerned with incoming HTTP cookies. For outgoing HTTP - cookies, use crunch-outgoing-cookies. Use both to disable HTTP cookies - completely. + Client-header filters are executed after the other header actions + have finished and use their output as input. - 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. + If the request URL gets changed, Privoxy will detect that and use + the new one. This can be used to rewrite the request destination + behind the client's back, for example to specify a Tor exit relay + for certain requests. -Example usage: + Please refer to the filter file chapter to learn which + client-header filters are available by default, and how to create + your own. - +crunch-incoming-cookies + Example usage (section): + {+client-header-filter{hide-tor-exit-notation}} + .exit/ -------------------------------------------------------------------------------- -8.5.9. crunch-server-header + -------------------------------------------------------------------------- -Typical use: + 8.5.4. client-header-tagger - Remove a server header Privoxy has no dedicated action for. + Typical use: -Effect: + Block requests based on their headers. - Deletes every header sent by the server that contains the string the user - supplied as parameter. + Effect: -Type: + Client headers to which this action applies are filtered + on-the-fly through the specified regular expression based + substitutions, the result is used as tag. - Parameterized. + Type: -Parameter: + Parameterized. - Any string. + Parameter: -Notes: + The name of a client-header tagger, as defined in one of the + filter files. - 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. + Notes: - 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. + Client-header taggers are applied to each header on its own, and + as the header isn't modified, each tagger "sees" the original. - 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 - use a custom server-header filter. + Client-header taggers are the first actions that are executed and + their tags can be used to control every other action. - +-----------------------------------------------------------------+ - | Warning | - |-----------------------------------------------------------------| - |Don't block any header without understanding the consequences. | - +-----------------------------------------------------------------+ -Example usage (section): + Example usage (section): - # Crunch server headers that try to prevent caching - { +crunch-server-header{no-cache} } - / + # Tag every request with the User-Agent header + {+client-header-tagger{user-agent}} + / -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.5.10. crunch-outgoing-cookies + 8.5.5. content-type-overwrite -Typical use: + Typical use: - Prevent the web server from reading any HTTP cookies from your system + Stop useless download menus from popping up, or change the + browser's rendering mode -Effect: + Effect: - Deletes any "Cookie:" HTTP headers from client requests. + Replaces the "Content-Type:" HTTP server header. -Type: + Type: - Boolean. + Parameterized. -Parameter: + Parameter: - N/A + Any string. -Notes: + Notes: - This action is only concerned with outgoing HTTP cookies. For incoming HTTP - cookies, use crunch-incoming-cookies. Use both to disable HTTP cookies - completely. + 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. - 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. + 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. -Example usage: + 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. - +crunch-outgoing-cookies + 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 replace this action with a custom + server-header filter. 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. -8.5.11. deanimate-gifs + 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. -Typical use: + Example usage (sections): - Stop those annoying, distracting animated GIF images. + # Check if www.example.net/ really uses valid XHTML + { +content-type-overwrite{application/xml} } + www.example.net/ -Effect: + # 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 - De-animate GIF animations, i.e. reduce them to their first or last image. + -------------------------------------------------------------------------- -Type: + 8.5.6. crunch-client-header - Parameterized. + Typical use: -Parameter: + Remove a client header Privoxy has no dedicated action for. - "last" or "first" + Effect: -Notes: + Deletes every header sent by the client that contains the string + the user supplied as parameter. - 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). + Type: - 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. + Parameterized. -Example usage: + Parameter: - +deanimate-gifs{last} + 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. -8.5.12. downgrade-http-version + 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. -Typical use: + 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 use a client-header filter. - Work around (very rare) problems with HTTP/1.1 + +---------------------------------------------------------+ + | Warning | + |---------------------------------------------------------| + | Don't block any header without understanding the | + | consequences. | + +---------------------------------------------------------+ -Effect: + Example usage (section): - Downgrades HTTP/1.1 client requests and server replies to HTTP/1.0. + # Block the non-existent "Privacy-Violation:" client header + { +crunch-client-header{Privacy-Violation:} } + / -Type: - Boolean. + -------------------------------------------------------------------------- -Parameter: + 8.5.7. crunch-if-none-match - N/A + Typical use: -Notes: + Prevent yet another way to track the user's steps between + sessions. - 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 - HTTP/1.1 features and requirements are supported yet, so there is a chance - you might need this action. + Effect: -Example usage (section): + Deletes the "If-None-Match:" HTTP client header. - {+downgrade-http-version} - problem-host.example.com + Type: + Boolean. -------------------------------------------------------------------------------- + Parameter: -8.5.13. fast-redirects + N/A -Typical use: + Notes: - Fool some click-tracking scripts and speed up indirect links. + 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. -Effect: + It is also useful to make sure the header isn't used as a cookie + replacement (unlikely but possible). - Detects redirection URLs and redirects the browser without contacting the - redirection server first. + Blocking the "If-None-Match:" header shouldn't cause any caching + problems, as long as the "If-Modified-Since:" header isn't blocked + or missing as well. -Type: + It is recommended to use this action together with + hide-if-modified-since and overwrite-last-modified. - Parameterized. + Example usage (section): -Parameter: + # Let the browser revalidate cached documents but don't + # allow the server to use the revalidation headers for user tracking. + {+hide-if-modified-since{-60} \ + +overwrite-last-modified{randomize} \ + +crunch-if-none-match} + / - + "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. + 8.5.8. crunch-incoming-cookies -Notes: + Typical use: - 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/". + Prevent the web server from setting HTTP cookies on your system - 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. + Effect: - 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: + Deletes any "Set-Cookie:" HTTP headers from server replies. - 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. + Type: - 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. You can prevent this - problem by first using the redirect action to remove the last part of the - URL, but it requires a little effort. + Boolean. - 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. + Parameter: -Example usage: + N/A - { +fast-redirects{simple-check} } - one.example.com + Notes: - { +fast-redirects{check-decoded-url} } - another.example.com/testing + This action is only concerned with incoming HTTP cookies. For + outgoing HTTP cookies, use crunch-outgoing-cookies. Use both to + disable HTTP 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: -8.5.14. filter + +crunch-incoming-cookies -Typical use: + -------------------------------------------------------------------------- - Get rid of HTML and JavaScript annoyances, banner advertisements (by size), - do fun text replacements, add personalized effects, etc. + 8.5.9. crunch-server-header -Effect: + Typical use: - All instances of text-based type, most notably HTML and JavaScript, to - which this action applies, can be 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.) + Remove a server header Privoxy has no dedicated action for. -Type: + Effect: - Parameterized. + Deletes every header sent by the server that contains the string + the user supplied as parameter. -Parameter: + Type: - The name of a content 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. + Parameterized. - When used in its negative form, and without parameters, all filtering is - completely disabled. + Parameter: -Notes: + Any string. - 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. + Notes: - 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 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. - "Rolling your own" filters requires a knowledge of "Regular Expressions" - and "HTML". This is very powerful feature, and potentially very intrusive. - Filters should be used with caution, and where an equivalent "action" is - not available. + 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. - 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. + 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 use a custom server-header filter. - Inappropriate 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 exceptions. + +---------------------------------------------------------+ + | Warning | + |---------------------------------------------------------| + | Don't block any header without understanding the | + | consequences. | + +---------------------------------------------------------+ - Compressed content can't be filtered either, unless Privoxy is compiled - with zlib support (requires at least Privoxy 3.0.7), in which case Privoxy - will decompress the content before filtering it. + Example usage (section): - If you use a Privoxy version without zlib support, but want filtering to - work on as much documents as possible, even those that would normally be - sent compressed, you must use the prevent-compression action in conjunction - with filter. + # Crunch server headers that try to prevent caching + { +crunch-server-header{no-cache} } + / - Content 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! + 8.5.10. crunch-outgoing-cookies - 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. + Typical use: -Example usage (with filters from the distribution default.filter file). See the - Predefined Filters section for more explanation on each: + Prevent the web server from reading any HTTP cookies from your + system - +filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse + Effect: + Deletes any "Cookie:" HTTP headers from client requests. - +filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites) + Type: + Boolean. - +filter{html-annoyances} # Get rid of particularly annoying HTML abuse + Parameter: + N/A - +filter{content-cookies} # Kill cookies that come in the HTML or JS content + Notes: + This action is only concerned with outgoing HTTP cookies. For + incoming HTTP cookies, use crunch-incoming-cookies. Use both to + disable HTTP cookies completely. - +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups) + 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: - +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability. + +crunch-outgoing-cookies + -------------------------------------------------------------------------- - +filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability. + 8.5.11. deanimate-gifs + Typical use: - +filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective + Stop those annoying, distracting animated GIF images. + Effect: - +filter{banners-by-size} # Kill banners by size + De-animate GIF animations, i.e. reduce them to their first or last + image. + Type: - +filter{banners-by-link} # Kill banners by their links to known clicktrackers + Parameterized. + Parameter: - +filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking) + "last" or "first" + Notes: - +filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap + 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. - +filter{jumping-windows} # Prevent windows from resizing and moving themselves + Example usage: + +deanimate-gifs{last} - +filter{frameset-borders} # Give frames a border and make them resizeable + -------------------------------------------------------------------------- + 8.5.12. downgrade-http-version - +filter{demoronizer} # Fix MS's non-standard use of standard charsets + Typical use: + Work around (very rare) problems with HTTP/1.1 - +filter{shockwave-flash} # Kill embedded Shockwave Flash objects + Effect: + Downgrades HTTP/1.1 client requests and server replies to + HTTP/1.0. - +filter{quicktime-kioskmode} # Make Quicktime movies savable + Type: + Boolean. - +filter{fun} # Text replacements for subversive browsing fun! + Parameter: + N/A - +filter{crude-parental} # Crude parental filtering (demo only) + 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 HTTP/1.1 features and requirements are + supported yet, so there is a chance you might need this action. - +filter{ie-exploits} # Disable a known Internet Explorer bug exploits + Example usage (section): + {+downgrade-http-version} + problem-host.example.com - +filter{site-specifics} # Custom filters for specific site related problems + -------------------------------------------------------------------------- + 8.5.13. fast-redirects - +filter{google} # Removes text ads and other Google specific improvements + Typical use: + Fool some click-tracking scripts and speed up indirect links. - +filter{yahoo} # Removes text ads and other Yahoo specific improvements + Effect: + Detects redirection URLs and redirects the browser without + contacting the redirection server first. - +filter{msn} # Removes text ads and other MSN specific improvements + Type: + Parameterized. - +filter{blogspot} # Cleans up Blogspot blogs + Parameter: + * "simple-check" to just search for the string "http://" to + detect redirection URLs. - +filter{no-ping} # Removes non-standard ping attributes from anchor and area tags + * "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/". -8.5.15. force-text-mode + 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. -Typical use: + 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: - Force Privoxy to treat a document as if it was in some kind of text format. + 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. -Effect: + 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. You can prevent this + problem by first using the redirect action to remove the last part + of the URL, but it requires a little effort. - Declares a document as text, even if the "Content-Type:" isn't detected as - such. + 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. -Type: + Example usage: - Boolean. + { +fast-redirects{simple-check} } + one.example.com -Parameter: + { +fast-redirects{check-decoded-url} } + another.example.com/testing - N/A + -------------------------------------------------------------------------- -Notes: + 8.5.14. filter - 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. + Typical use: - +-----------------------------------------------------------------+ - | Warning | - |-----------------------------------------------------------------| - |Think twice before activating this action. Filtering binary data | - |with regular expressions can cause file damage. | - +-----------------------------------------------------------------+ -Example usage: + Get rid of HTML and JavaScript annoyances, banner advertisements + (by size), do fun text replacements, add personalized effects, + etc. - +force-text-mode + Effect: + All instances of text-based type, most notably HTML and + JavaScript, to which this action applies, can be 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. -8.5.16. forward-override + Parameter: -Typical use: + The name of a content 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. - Change the forwarding settings based on User-Agent or request origin + When used in its negative form, and without parameters, all + filtering is completely disabled. -Effect: + Notes: - Overrules the forward directives in the configuration file. + 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. -Type: + 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. - Multi-value. + "Rolling your own" filters requires a knowledge of "Regular + Expressions" and "HTML". This is very powerful feature, and + potentially very intrusive. Filters should be used with caution, + and where an equivalent "action" is not available. -Parameter: + 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. - + "forward ." to use a direct connection without any additional proxies. + Inappropriate 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 + exceptions. - + "forward 127.0.0.1:8123" to use the HTTP proxy listening at 127.0.0.1 - port 8123. + Compressed content can't be filtered either, unless Privoxy is + compiled with zlib support (requires at least Privoxy 3.0.7), in + which case Privoxy will decompress the content before filtering + it. - + "forward-socks4a 127.0.0.1:9050 ." to use the socks4a proxy listening - at 127.0.0.1 port 9050. Replace "forward-socks4a" with "forward-socks4" - to use a socks4 connection (with local DNS resolution) instead. + If you use a Privoxy version without zlib support, but want + filtering to work on as much documents as possible, even those + that would normally be sent compressed, you must use the + prevent-compression action in conjunction with filter. - + "forward-socks4a 127.0.0.1:9050 proxy.example.org:8000" to use the - socks4a proxy listening at 127.0.0.1 port 9050 to reach the HTTP proxy - listening at proxy.example.org port 8000. Replace "forward-socks4a" - with "forward-socks4" to use a socks4 connection (with local DNS - resolution) instead. + Content 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. -Notes: + Feedback with suggestions for new or improved filters is + particularly welcome! - This action takes parameters similar to the forward directives in the - configuration file, but without the URL pattern. It can be used as - replacement, but normally it's only used in cases where matching based on - the request URL isn't sufficient. + 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. - +-----------------------------------------------------------------+ - | Warning | - |-----------------------------------------------------------------| - |Please read the description for the forward directives before | - |using this action. Forwarding to the wrong people will reduce | - |your privacy and increase the chances of man-in-the-middle | - |attacks. | - | | - |If the ports are missing or invalid, default values will be used.| - |This might change in the future and you shouldn't rely on it. | - |Otherwise incorrect syntax causes Privoxy to exit. | - | | - |Use the show-url-info CGI page to verify that your forward | - |settings do what you thought the do. | - +-----------------------------------------------------------------+ -Example usage: + Example usage (with filters from the distribution default.filter file). + See the Predefined Filters section for more explanation on each: - # Always use direct connections for requests previously tagged as - # "User-Agent: fetch libfetch/2.0" and make sure - # resuming downloads continues to work. - # This way you can continue to use Tor for your normal browsing, - # without overloading the Tor network with your FreeBSD ports updates - # or downloads of bigger files like ISOs. - # Note that HTTP headers are easy to fake and therefore their - # values are as (un)trustworthy as your clients and users. - {+forward-override{forward .} \ - -hide-if-modified-since \ - -overwrite-last-modified \ - } - TAG:^User-Agent: fetch libfetch/2\.0$ ++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 -8.5.17. handle-as-empty-document ++filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups) -Typical use: ++filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability. - Mark URLs that should be replaced by empty documents if they get blocked ++filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability. -Effect: ++filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective - 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. + +filter{banners-by-size} # Kill banners by size -Type: ++filter{banners-by-link} # Kill banners by their links to known clicktrackers - Boolean. ++filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking) -Parameter: ++filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap - N/A ++filter{jumping-windows} # Prevent windows from resizing and moving themselves -Notes: + +filter{frameset-borders} # Give frames a border and make them resizeable - 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. And of course this action can also be used to eliminate the - Privoxy BLOCKED message in frames. + +filter{demoronizer} # Fix MS's non-standard use of standard charsets - The content type for the empty document can be specified with - content-type-overwrite{}, but usually this isn't necessary. + +filter{shockwave-flash} # Kill embedded Shockwave Flash objects -Example usage: + +filter{quicktime-kioskmode} # Make Quicktime movies savable - # 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$ + +filter{fun} # Text replacements for subversive browsing fun! + +filter{crude-parental} # Crude parental filtering (demo only) + +filter{ie-exploits} # Disable a known Internet Explorer bug exploits -------------------------------------------------------------------------------- ++filter{site-specifics} # Custom filters for specific site related problems -8.5.18. handle-as-image ++filter{google} # Removes text ads and other Google specific improvements -Typical use: ++filter{yahoo} # Removes text ads and other Yahoo specific improvements - Mark URLs as belonging to images (so they'll be replaced by images if they - do get blocked, rather than HTML pages) ++filter{msn} # Removes text ads and other MSN specific improvements -Effect: + +filter{blogspot} # Cleans up Blogspot blogs - 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. ++filter{no-ping} # Removes non-standard ping attributes from anchor and area tags -Type: + -------------------------------------------------------------------------- - Boolean. + 8.5.15. force-text-mode -Parameter: + Typical use: - N/A + Force Privoxy to treat a document as if it was in some kind of + text format. -Notes: + Effect: - 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. + Declares a document as text, even if the "Content-Type:" isn't + detected as such. - 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. + Type: - 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. + Boolean. -Example usage (sections): + Parameter: - # Generic image extensions: - # - {+handle-as-image} - /.*\.(gif|jpg|jpeg|png|bmp|ico)$ + N/A - # 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 + Notes: - # Banner source! Who cares if they also have non-image content? - ad.doubleclick.net + 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. + +---------------------------------------------------------+ + | Warning | + |---------------------------------------------------------| + | Think twice before activating this action. Filtering | + | binary data with regular expressions can cause file | + | damage. | + +---------------------------------------------------------+ -------------------------------------------------------------------------------- + Example usage: -8.5.19. hide-accept-language + +force-text-mode -Typical use: - Pretend to use different language settings. + -------------------------------------------------------------------------- -Effect: + 8.5.16. forward-override - Deletes or replaces the "Accept-Language:" HTTP header in client requests. + Typical use: -Type: + Change the forwarding settings based on User-Agent or request + origin - Parameterized. + Effect: -Parameter: + Overrules the forward directives in the configuration file. - Keyword: "block", or any user defined value. + Type: -Notes: + Multi-value. - Faking the browser's language settings can be useful to make a foreign - User-Agent set with hide-user-agent more believable. + Parameter: - 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. + * "forward ." to use a direct connection without any additional + proxies. - 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. + * "forward 127.0.0.1:8123" to use the HTTP proxy listening at + 127.0.0.1 port 8123. - 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. + * "forward-socks4a 127.0.0.1:9050 ." to use the socks4a proxy + listening at 127.0.0.1 port 9050. Replace "forward-socks4a" + with "forward-socks4" to use a socks4 connection (with local + DNS resolution) instead. -Example usage (section): + * "forward-socks4a 127.0.0.1:9050 proxy.example.org:8000" to + use the socks4a proxy listening at 127.0.0.1 port 9050 to + reach the HTTP proxy listening at proxy.example.org port + 8000. Replace "forward-socks4a" with "forward-socks4" to use + a socks4 connection (with local DNS resolution) instead. - # 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} \ - } - / + Notes: + This action takes parameters similar to the forward directives in + the configuration file, but without the URL pattern. It can be + used as replacement, but normally it's only used in cases where + matching based on the request URL isn't sufficient. -------------------------------------------------------------------------------- + +---------------------------------------------------------+ + | Warning | + |---------------------------------------------------------| + | Please read the description for the forward directives | + | before using this action. Forwarding to the wrong | + | people will reduce your privacy and increase the | + | chances of man-in-the-middle attacks. | + | | + | If the ports are missing or invalid, default values | + | will be used. This might change in the future and you | + | shouldn't rely on it. Otherwise incorrect syntax causes | + | Privoxy to exit. | + | | + | Use the show-url-info CGI page to verify that your | + | forward settings do what you thought the do. | + +---------------------------------------------------------+ -8.5.20. hide-content-disposition + Example usage: -Typical use: + # Always use direct connections for requests previously tagged as + # "User-Agent: fetch libfetch/2.0" and make sure + # resuming downloads continues to work. + # This way you can continue to use Tor for your normal browsing, + # without overloading the Tor network with your FreeBSD ports updates + # or downloads of bigger files like ISOs. + # Note that HTTP headers are easy to fake and therefore their + # values are as (un)trustworthy as your clients and users. + {+forward-override{forward .} \ + -hide-if-modified-since \ + -overwrite-last-modified \ + } + TAG:^User-Agent: fetch libfetch/2\.0$ - 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. + 8.5.17. handle-as-empty-document -Type: + Typical use: - Parameterized. + Mark URLs that should be replaced by empty documents if they get + blocked -Parameter: + Effect: - Keyword: "block", or any user defined value. + 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. -Notes: + Type: - 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. + Boolean. - 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. + Parameter: - 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. + N/A - 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. + Notes: - This action will probably be removed in the future, use server-header - filters instead. + 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. And of course this action can also be used + to eliminate the Privoxy BLOCKED message in frames. -Example usage: + The content type for the empty document can be specified with + content-type-overwrite{}, but usually this isn't necessary. - # Disarm the download link in Sourceforge's patch tracker - { -filter \ - +content-type-overwrite{text/plain}\ - +hide-content-disposition{block} } - .sourceforge.net/tracker/download\.php + 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$ -------------------------------------------------------------------------------- -8.5.21. hide-if-modified-since + -------------------------------------------------------------------------- -Typical use: + 8.5.18. handle-as-image - Prevent yet another way to track the user's steps between sessions. + Typical use: -Effect: + Mark URLs as belonging to images (so they'll be replaced by images + if they do get blocked, rather than HTML pages) - Deletes the "If-Modified-Since:" HTTP client header or modifies its value. + Effect: -Type: + 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. - Parameterized. + Type: -Parameter: + Boolean. - Keyword: "block", or a user defined value that specifies a range of hours. + Parameter: -Notes: + N/A - 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. + Notes: - Instead of removing the header, hide-if-modified-since can also add or - subtract a random amount of time to/from the header's value. You specify a - range of minutes where the random factor should be chosen from and Privoxy - does the rest. A negative value means subtracting, a positive value adding. + 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. - Randomizing the value of the "If-Modified-Since:" makes it less likely that - the server can use the time as a cookie replacement, but you will run into - caching problems if the random range is too high. + 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. - It is a good idea to only use a small negative value and let - overwrite-last-modified handle the greater changes. + 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. - It is also recommended to use this action together with - crunch-if-none-match, otherwise it's more or less pointless. + Example usage (sections): -Example usage (section): + # Generic image extensions: + # + {+handle-as-image} + /.*\.(gif|jpg|jpeg|png|bmp|ico)$ - # Let the browser revalidate but make tracking based on the time less likely. - {+hide-if-modified-since{-60} \ - +overwrite-last-modified{randomize} \ - +crunch-if-none-match} - / + # 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 -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.5.22. hide-forwarded-for-headers + 8.5.19. hide-accept-language -Typical use: + Typical use: - Improve privacy by not forwarding the source of the request in the HTTP - headers. + Pretend to use different language settings. -Effect: + Effect: - Deletes any existing "X-Forwarded-for:" HTTP header from client requests. + Deletes or replaces the "Accept-Language:" HTTP header in client + requests. -Type: + Type: - Boolean. + Parameterized. -Parameter: + Parameter: - N/A + Keyword: "block", or any user defined value. -Notes: + Notes: - It is safe and recommended to leave this on. + Faking the browser's language settings can be useful to make a + foreign User-Agent set with hide-user-agent more believable. -Example usage: + 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. - +hide-forwarded-for-headers + 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): -8.5.23. hide-from-header +# 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} \ +} +/ -Typical use: + -------------------------------------------------------------------------- - Keep your (old and ill) browser from telling web servers your email address + 8.5.20. hide-content-disposition -Effect: + Typical use: - Deletes any existing "From:" HTTP header, or replaces it with the specified - string. + Prevent download menus for content you prefer to view inside the + browser. -Type: + Effect: - Parameterized. + Deletes or replaces the "Content-Disposition:" HTTP header set by + some servers. -Parameter: + Type: - Keyword: "block", or any user defined value. + Parameterized. -Notes: + Parameter: - The keyword "block" will completely remove the header (not to be confused - with the block action). + Keyword: "block", or any user defined value. - 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. + Notes: - This action is rarely needed, as modern web browsers don't send "From:" - headers anymore. + 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. -Example usage: + 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. - +hide-from-header{block} + 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. - or + This action will probably be removed in the future, use + server-header filters instead. - +hide-from-header{spam-me-senseless@sittingduck.example.com} + 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 -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.5.24. hide-referrer + 8.5.21. hide-if-modified-since -Typical use: + Typical use: - Conceal which link you followed to get to a particular site + Prevent yet another way to track the user's steps between + sessions. -Effect: + Effect: - Deletes the "Referer:" (sic) HTTP header from the client request, or - replaces it with a forged one. + Deletes the "If-Modified-Since:" HTTP client header or modifies + its value. -Type: + Type: - Parameterized. + Parameterized. -Parameter: + Parameter: - + "conditional-block" to delete the header completely if the host has - changed. + Keyword: "block", or a user defined value that specifies a range + of hours. - + "conditional-forge" to forge the header if the host has changed. + Notes: - + "block" to delete the header unconditionally. + 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. - + "forge" to pretend to be coming from the homepage of the server we are - talking to. + Instead of removing the header, hide-if-modified-since can also + add or subtract a random amount of time to/from the header's + value. You specify a range of minutes where the random factor + should be chosen from and Privoxy does the rest. A negative value + means subtracting, a positive value adding. - + Any other string to set a user defined referrer. + Randomizing the value of the "If-Modified-Since:" makes it less + likely that the server can use the time as a cookie replacement, + but you will run into caching problems if the random range is too + high. -Notes: + It is a good idea to only use a small negative value and let + overwrite-last-modified handle the greater changes. - 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. + It is also recommended to use this action together with + crunch-if-none-match, otherwise it's more or less pointless. - 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. + Example usage (section): - 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 content from being embedded or linked to - elsewhere. + # Let the browser revalidate but make tracking based on the time less likely. + {+hide-if-modified-since{-60} \ + +overwrite-last-modified{randomize} \ + +crunch-if-none-match} + / - 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".) + 8.5.22. hide-forwarded-for-headers -Example usage: + Typical use: - +hide-referrer{forge} + Improve privacy by not forwarding the source of the request in the + HTTP headers. + Effect: - or + Deletes any existing "X-Forwarded-for:" HTTP header from client + requests. - +hide-referrer{http://www.yahoo.com/} + Type: + Boolean. -------------------------------------------------------------------------------- + Parameter: -8.5.25. hide-user-agent + N/A -Typical use: + Notes: - Try to conceal your type of browser and client operating system + It is safe and recommended to leave this on. -Effect: + Example usage: - Replaces the value of the "User-Agent:" HTTP header in client requests with - the specified value. + +hide-forwarded-for-headers -Type: + -------------------------------------------------------------------------- - Parameterized. + 8.5.23. hide-from-header -Parameter: + Typical use: - Any user-defined string. + Keep your (old and ill) browser from telling web servers your + email address -Notes: + Effect: - +-----------------------------------------------------------------+ - | Warning | - |-----------------------------------------------------------------| - |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). | - +-----------------------------------------------------------------+ + Deletes any existing "From:" HTTP header, or replaces it with the + specified string. - 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 :-). + Type: - More information on known user-agent strings can be found at http:// - www.user-agents.org/ and http://en.wikipedia.org/wiki/User_agent. + Parameterized. -Example usage: + Parameter: - +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} + Keyword: "block", or any user defined value. + Notes: -------------------------------------------------------------------------------- + The keyword "block" will completely remove the header (not to be + confused with the block action). -8.5.26. inspect-jpegs + 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. -Typical use: + This action is rarely needed, as modern web browsers don't send + "From:" headers anymore. - Try to protect against a MS buffer over-run in JPEG processing + Example usage: -Effect: + +hide-from-header{block} - Protect against a known exploit + or -Type: + +hide-from-header{spam-me-senseless@sittingduck.example.com} - Boolean. + -------------------------------------------------------------------------- -Parameter: + 8.5.24. hide-referrer - N/A + Typical use: -Notes: + Conceal which link you followed to get to a particular site - 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 tries - to prevent this exploit if delivered through unencrypted HTTP. + Effect: - Note that the exploit mentioned is several years old and it's unlikely that - your client is still vulnerable against it. This action may be removed in - one of the next releases. + Deletes the "Referer:" (sic) HTTP header from the client request, + or replaces it with a forged one. -Example usage: + Type: - +inspect-jpegs + Parameterized. + Parameter: -------------------------------------------------------------------------------- + * "conditional-block" to delete the header completely if the + host has changed. -8.5.27. kill-popups + * "conditional-forge" to forge the header if the host has + changed. -Typical use: + * "block" to delete the header unconditionally. - Eliminate those annoying pop-up windows (deprecated) + * "forge" to pretend to be coming from the homepage of the + server we are talking to. -Effect: + * Any other string to set a user defined referrer. - While loading the document, replace JavaScript code that opens pop-up - windows with (syntactically neutral) dummy code on the fly. + Notes: -Type: + 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. - Boolean. + 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. -Parameter: + 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 content from being + embedded or linked to elsewhere. - N/A + 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. -Notes: + 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".) - 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. + Example usage: - 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. + +hide-referrer{forge} - 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 better job of catching only the unwanted ones. + or - 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. + +hide-referrer{http://www.yahoo.com/} - This action is most appropriate for browsers that don't have any controls - for unwanted pop-ups. Not recommended for general usage. + -------------------------------------------------------------------------- - This action doesn't work very reliable and may be removed in future - releases. + 8.5.25. hide-user-agent -Example usage: + Typical use: - +kill-popups + Try to 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. -8.5.28. limit-connect + Type: -Typical use: + Parameterized. - Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for untrusted - sites + Parameter: -Effect: + Any user-defined string. - Specifies to which ports HTTP CONNECT requests are allowable. + Notes: -Type: + +---------------------------------------------------------+ + | Warning | + |---------------------------------------------------------| + | 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). | + +---------------------------------------------------------+ - Parameterized. + 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 :-). -Parameter: + More information on known user-agent strings can be found at + http://www.user-agents.org/ and + http://en.wikipedia.org/wiki/User_agent. - A comma-separated list of ports or port ranges (the latter using dashes, - with the minimum defaulting to 0 and the maximum to 65K). + Example usage: -Notes: + +hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)} - 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 means - CONNECT-enabled proxies can be used as TCP relays very easily. + 8.5.26. inspect-jpegs - 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. + Typical use: -Example usages: + Try to protect against a MS buffer over-run in JPEG processing - +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/SSL traffic is allowed + Effect: + Protect against a known exploit -------------------------------------------------------------------------------- + Type: -8.5.29. prevent-compression + Boolean. -Typical use: + Parameter: - Ensure that servers send the content uncompressed, so it can be passed - through filters. + N/A -Effect: + Notes: - Removes the Accept-Encoding header which can be used to ask for compressed - transfer. + 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 tries to prevent + this exploit if delivered through unencrypted HTTP. -Type: + Note that the exploit mentioned is several years old and it's + unlikely that your client is still vulnerable against it. This + action may be removed in one of the next releases. - Boolean. + Example usage: -Parameter: + +inspect-jpegs - N/A + -------------------------------------------------------------------------- -Notes: + 8.5.27. kill-popups - More and more websites send their content compressed by default, which is - generally a good idea and saves bandwidth. But the filter, deanimate-gifs - and kill-popups actions need access to the uncompressed data. + Typical use: - When compiled with zlib support (available since Privoxy 3.0.7), content - that should be filtered is decompressed on-the-fly and you don't have to - worry about this action. If you are using an older Privoxy version, or one - that hasn't been compiled with zlib support, this action can be used to - convince the server to send the content uncompressed. + Eliminate those annoying pop-up windows (deprecated) - Most text-based instances compress very well, the size is seldom decreased - by less than 50%, for markup-heavy instances like news feeds saving more - than 90% of the original size isn't unusual. + Effect: - Not using compression will therefore slow down the transfer, and you should - only enable this action if you really need it. As of Privoxy 3.0.7 it's - disabled in all predefined action settings. + While loading the document, replace JavaScript code that opens + pop-up windows with (syntactically neutral) dummy code on the fly. - Note that some (rare) ill-configured sites don't handle requests for - uncompressed documents correctly. Broken PHP applications tend to send an - empty document body, some IIS versions only send the beginning of the - content. If you enable prevent-compression per default, you might want to - add exceptions for those sites. See the example for how to do that. + Type: -Example usage (sections): + Boolean. - # Selectively turn off compression, and enable a filter - # - { +filter{tiny-textforms} +prevent-compression } - # Match only these sites - .google. - sourceforge.net - sf.net + Parameter: - # Or instead, we could set a universal default: - # - { +prevent-compression } - / # Match all sites + N/A - # Then maybe make exceptions for broken sites: - # - { -prevent-compression } - .compusa.com/ + 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. -8.5.30. overwrite-last-modified + 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 better job of catching only + the unwanted ones. -Typical use: + 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. - Prevent yet another way to track the user's steps between sessions. + This action is most appropriate for browsers that don't have any + controls for unwanted pop-ups. Not recommended for general usage. -Effect: + This action doesn't work very reliable and may be removed in + future releases. - Deletes the "Last-Modified:" HTTP server header or modifies its value. + Example usage: -Type: + +kill-popups - Parameterized. + -------------------------------------------------------------------------- -Parameter: + 8.5.28. limit-connect - One of the keywords: "block", "reset-to-request-time" and "randomize" + Typical use: -Notes: + Prevent abuse of Privoxy as a TCP proxy relay or disable SSL for + untrusted sites - 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. + Effect: - 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. + Specifies to which ports HTTP CONNECT requests are allowable. - "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. + Type: - 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. + Parameterized. - It is also recommended to use this action together with - crunch-if-none-match. + Parameter: -Example usage: + A comma-separated list of ports or port ranges (the latter using + dashes, with the minimum defaulting to 0 and the maximum to 65K). - # Let the browser revalidate without being tracked across sessions - { +hide-if-modified-since{-60} \ - +overwrite-last-modified{randomize} \ - +crunch-if-none-match} - / + 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 means CONNECT-enabled proxies can be used as TCP + relays very easily. -8.5.31. redirect + 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. -Typical use: + Example usages: - Redirect requests to other sites. ++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/SSL traffic is allowed -Effect: + -------------------------------------------------------------------------- - Convinces the browser that the requested document has been moved to another - location and the browser should get it from there. + 8.5.29. prevent-compression -Type: + Typical use: - Parameterized + Ensure that servers send the content uncompressed, so it can be + passed through filters. -Parameter: + Effect: - An absolute URL or a single pcrs command. + Removes the Accept-Encoding header which can be used to ask for + compressed transfer. -Notes: + Type: - Requests to which this action applies are answered with a HTTP redirect to - URLs of your choosing. The new URL is either provided as parameter, or - derived by applying a single pcrs command to the original URL. + Boolean. - This action will be ignored if you use it together with block. It can be - combined with fast-redirects{check-decoded-url} to redirect to a decoded - version of a rewritten URL. + Parameter: - Use this action carefully, make sure not to create redirection loops and be - aware that using your own redirects might make it possible to fingerprint - your requests. + N/A -Example usages: + Notes: - # Replace example.com's style sheet with another one - { +redirect{http://localhost/css-replacements/example.com.css} } - example.com/stylesheet\.css + More and more websites send their content compressed by default, + which is generally a good idea and saves bandwidth. But the + filter, deanimate-gifs and kill-popups actions need access to the + uncompressed data. - # Create a short, easy to remember nickname for a favorite site - # (relies on the browser accept and forward invalid URLs to Privoxy) - { +redirect{http://www.privoxy.org/user-manual/actions-file.html} } - a + When compiled with zlib support (available since Privoxy 3.0.7), + content that should be filtered is decompressed on-the-fly and you + don't have to worry about this action. If you are using an older + Privoxy version, or one that hasn't been compiled with zlib + support, this action can be used to convince the server to send + the content uncompressed. - # Always use the expanded view for Undeadly.org articles - # (Note the $ at the end of the URL pattern to make sure - # the request for the rewritten URL isn't redirected as well) - {+redirect{s@$@&mode=expanded@}} - undeadly.org/cgi\?action=article&sid=\d*$ + Most text-based instances compress very well, the size is seldom + decreased by less than 50%, for markup-heavy instances like news + feeds saving more than 90% of the original size isn't unusual. + Not using compression will therefore slow down the transfer, and + you should only enable this action if you really need it. As of + Privoxy 3.0.7 it's disabled in all predefined action settings. -------------------------------------------------------------------------------- + Note that some (rare) ill-configured sites don't handle requests + for uncompressed documents correctly. Broken PHP applications tend + to send an empty document body, some IIS versions only send the + beginning of the content. If you enable prevent-compression per + default, you might want to add exceptions for those sites. See the + example for how to do that. -8.5.32. send-vanilla-wafer + Example usage (sections): -Typical use: + # Selectively turn off compression, and enable a filter + # + { +filter{tiny-textforms} +prevent-compression } + # Match only these sites + .google. + sourceforge.net + sf.net - Feed log analysis scripts with useless data. + # Or instead, we could set a universal default: + # + { +prevent-compression } + / # Match all sites -Effect: + # Then maybe make exceptions for broken sites: + # + { -prevent-compression } + .compusa.com/ - 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: + 8.5.30. overwrite-last-modified - Boolean. + Typical use: -Parameter: + Prevent yet another way to track the user's steps between + sessions. - N/A + Effect: -Notes: + Deletes the "Last-Modified:" HTTP server header or modifies its + value. - The vanilla wafer is a (relatively) unique header and could conceivably be - used to track you. + Type: - This action is rarely used and not enabled in the default configuration. + Parameterized. -Example usage: + Parameter: - +send-vanilla-wafer + 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. -8.5.33. send-wafer + 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. -Typical use: + "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. - Send custom cookies or feed log analysis scripts with even more useless - data. + 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. -Effect: + It is also recommended to use this action together with + crunch-if-none-match. - Sends a custom, user-defined cookie with each request. + Example usage: -Type: + # Let the browser revalidate without being tracked across sessions + { +hide-if-modified-since{-60} \ + +overwrite-last-modified{randomize} \ + +crunch-if-none-match} + / - Multi-value. + -------------------------------------------------------------------------- -Parameter: + 8.5.31. redirect - A string of the form "name=value". + Typical use: -Notes: + Redirect requests to other sites. - Being multi-valued, multiple instances of this action can apply to the same - request, resulting in multiple cookies being sent. + Effect: - This action is rarely used and not enabled in the default configuration. + Convinces the browser that the requested document has been moved + to another location and the browser should get it from there. -Example usage (section): + Type: - {+send-wafer{UsingPrivoxy=true}} - my-internal-testing-server.void + Parameterized + Parameter: -------------------------------------------------------------------------------- + An absolute URL or a single pcrs command. -8.5.34. server-header-filter + Notes: -Typical use: + Requests to which this action applies are answered with a HTTP + redirect to URLs of your choosing. The new URL is either provided + as parameter, or derived by applying a single pcrs command to the + original URL. - Rewrite or remove single server headers. + This action will be ignored if you use it together with block. It + can be combined with fast-redirects{check-decoded-url} to redirect + to a decoded version of a rewritten URL. -Effect: + Use this action carefully, make sure not to create redirection + loops and be aware that using your own redirects might make it + possible to fingerprint your requests. - All server headers to which this action applies are filtered on-the-fly - through the specified regular expression based substitutions. + Example usages: -Type: + # Replace example.com's style sheet with another one + { +redirect{http://localhost/css-replacements/example.com.css} } + example.com/stylesheet\.css - Parameterized. + # Create a short, easy to remember nickname for a favorite site + # (relies on the browser accept and forward invalid URLs to Privoxy) + { +redirect{http://www.privoxy.org/user-manual/actions-file.html} } + a -Parameter: + # Always use the expanded view for Undeadly.org articles + # (Note the $ at the end of the URL pattern to make sure + # the request for the rewritten URL isn't redirected as well) + {+redirect{s@$@&mode=expanded@}} + undeadly.org/cgi\?action=article&sid=\d*$ - The name of a server-header filter, as defined in one of the filter files. + -------------------------------------------------------------------------- -Notes: + 8.5.32. send-vanilla-wafer - Server-header filters are applied to each header on its own, not to all at - once. This makes it easier to diagnose problems, but on the downside you - can't write filters that only change header x if header y's value is z. You - can do that by using tags though. + Typical use: - Server-header filters are executed after the other header actions have - finished and use their output as input. + Feed log analysis scripts with useless data. - Please refer to the filter file chapter to learn which server-header - filters are available by default, and how to create your own. + Effect: -Example usage (section): + 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. - {+server-header-filter{html-to-xml}} - example.org/xml-instance-that-is-delivered-as-html + Type: - {+server-header-filter{xml-to-html}} - example.org/instance-that-is-delivered-as-xml-but-is-not + Boolean. + Parameter: + N/A -------------------------------------------------------------------------------- + Notes: -8.5.35. server-header-tagger + The vanilla wafer is a (relatively) unique header and could + conceivably be used to track you. -Typical use: + This action is rarely used and not enabled in the default + configuration. - Enable or disable filters based on the Content-Type header. + Example usage: -Effect: + +send-vanilla-wafer - Server headers to which this action applies are filtered on-the-fly through - the specified regular expression based substitutions, the result is used as - tag. + -------------------------------------------------------------------------- -Type: + 8.5.33. send-wafer - Parameterized. + Typical use: -Parameter: + Send custom cookies or feed log analysis scripts with even more + useless data. - The name of a server-header tagger, as defined in one of the filter files. + Effect: -Notes: + Sends a custom, user-defined cookie with each request. - Server-header taggers are applied to each header on its own, and as the - header isn't modified, each tagger "sees" the original. + Type: - Server-header taggers are executed before all other header actions that - modify server headers. Their tags can be used to control all of the other - server-header actions, the content filters and the crunch actions (redirect - and block). + Multi-value. - Obviously crunching based on tags created by server-header taggers doesn't - prevent the request from showing up in the server's log file. + Parameter: -Example usage (section): + A string of the form "name=value". - # Tag every request with the content type declared by the server - {+server-header-tagger{content-type}} - / + 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): -8.5.36. session-cookies-only + {+send-wafer{UsingPrivoxy=true}} + my-internal-testing-server.void -Typical use: + -------------------------------------------------------------------------- - Allow only temporary "session" cookies (for the current browser session - only). + 8.5.34. server-header-filter -Effect: + Typical use: - Deletes the "expires" field from "Set-Cookie:" server headers. Most - browsers will not store such cookies permanently and forget them in between - sessions. + Rewrite or remove single server headers. -Type: + Effect: - Boolean. + All server headers to which this action applies are filtered + on-the-fly through the specified regular expression based + substitutions. -Parameter: + Type: - N/A + Parameterized. -Notes: + Parameter: - 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. + The name of a server-header filter, as defined in one of the + filter files. - 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. + Notes: - 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. + Server-header filters are applied to each header on its own, not + to all at once. This makes it easier to diagnose problems, but on + the downside you can't write filters that only change header x if + header y's value is z. You can do that by using tags though. - 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. + Server-header filters are executed after the other header actions + have finished and use their output as input. - 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. + Please refer to the filter file chapter to learn which + server-header filters are available by default, and how to create + your own. - Privoxy also uses the content-cookies filter to block some types of - cookies. Content cookies are not effected by session-cookies-only. + Example usage (section): -Example usage: + {+server-header-filter{html-to-xml}} + example.org/xml-instance-that-is-delivered-as-html - +session-cookies-only + {+server-header-filter{xml-to-html}} + example.org/instance-that-is-delivered-as-xml-but-is-not + + + -------------------------------------------------------------------------- + + 8.5.35. server-header-tagger + + Typical use: + + Enable or disable filters based on the Content-Type header. + + Effect: + + Server headers to which this action applies are filtered + on-the-fly through the specified regular expression based + substitutions, the result is used as tag. + + Type: + + Parameterized. + + Parameter: + The name of a server-header tagger, as defined in one of the + filter files. -------------------------------------------------------------------------------- + Notes: -8.5.37. set-image-blocker + Server-header taggers are applied to each header on its own, and + as the header isn't modified, each tagger "sees" the original. -Typical use: + Server-header taggers are executed before all other header actions + that modify server headers. Their tags can be used to control all + of the other server-header actions, the content filters and the + crunch actions (redirect and block). - Choose the replacement for blocked images + Obviously crunching based on tags created by server-header taggers + doesn't prevent the request from showing up in the server's log + file. -Effect: + Example usage (section): - 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. + # Tag every request with the content type declared by the server + {+server-header-tagger{content-type}} + / -Type: - Parameterized. + -------------------------------------------------------------------------- -Parameter: + 8.5.36. session-cookies-only - + "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. + Typical use: - + "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. + Allow only temporary "session" cookies (for the current browser + session only). - + "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). + Effect: - 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. + Deletes the "expires" field from "Set-Cookie:" server headers. + Most browsers will not store such cookies permanently and forget + them in between sessions. -Notes: + Type: - The URLs for the built-in images are "http://config.privoxy.org/ - send-banner?type=type", where type is either "blank" or "pattern". + Boolean. - 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. + Parameter: -Example usage: + N/A - Built-in pattern: + Notes: - +set-image-blocker{pattern} + 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. - Redirect to the BSD daemon: + 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. - +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} + 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. - Redirect to the built-in pattern for better caching: + Privoxy also uses the content-cookies filter to block some types + of cookies. Content cookies are not effected by + session-cookies-only. - +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern} + Example usage: + +session-cookies-only -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -8.5.38. treat-forbidden-connects-like-blocks + 8.5.37. set-image-blocker -Typical use: + Typical use: - Block forbidden connects with an easy to find error message. + Choose the replacement for blocked images -Effect: + Effect: - If this action is enabled, Privoxy no longer makes a difference between - forbidden connects and ordinary blocks. + 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: + Type: - Boolean + Parameterized. -Parameter: + Parameter: - N/A + * "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. -Notes: + * "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. - 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. + * "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). - 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. + 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. - 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" wouldn't work and is therefore suppressed. + Notes: -Example usage: + The URLs for the built-in images are + "http://config.privoxy.org/send-banner?type=type", where type is + either "blank" or "pattern". - +treat-forbidden-connects-like-blocks + 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: -8.5.39. Summary + +set-image-blocker{pattern} -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. + Redirect to the BSD daemon: -------------------------------------------------------------------------------- + +set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif} -8.6. Aliases + Redirect to the built-in pattern for better caching: -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. + +set-image-blocker{http://config.privoxy.org/send-banner?type=pattern} -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. + 8.5.38. treat-forbidden-connects-like-blocks -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. + Typical use: -Now let's define some aliases... + 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" wouldn't work and is therefore + suppressed. + + Example usage: + + +treat-forbidden-connects-like-blocks + + -------------------------------------------------------------------------- + + 8.5.39. 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. + + -------------------------------------------------------------------------- + + 8.6. 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. + + Now let's define some aliases... # Useful custom aliases we can use later. # @@ -5070,70 +5256,68 @@ Now let's define some aliases... 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): -...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 - # Gmail is really mail.google.com, not gmail.com - mail.google.com - - # Shopping sites: - # Allow cookies (for setting and retrieving your customer data) - # - {shop} - .quietpc.com - .worldpay.com # for quietpc.com - mybank.example.com - - # These shops require pop-ups: - # - {-kill-popups -filter{all-popups} -filter{unsolicited-popups}} - .dabs.com - .overclockers.co.uk - - -Aliases like "shop" and "fragile" are typically used for "problem" sites that -require more than one action to be disabled in order to function properly. + # 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 + # Gmail is really mail.google.com, not gmail.com + mail.google.com + + # Shopping sites: + # Allow cookies (for setting and retrieving your customer data) + # + {shop} + .quietpc.com + .worldpay.com # for quietpc.com + mybank.example.com -------------------------------------------------------------------------------- + # These shops require pop-ups: + # + {-kill-popups -filter{all-popups} -filter{unsolicited-popups}} + .dabs.com + .overclockers.co.uk -8.7. Actions Files Tutorial + Aliases like "shop" and "fragile" are typically used for "problem" sites + that require more than one action to be disabled in order to function + properly. -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: + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 8.7. Actions Files Tutorial -8.7.1. default.action + 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: -Every config file should start with a short comment stating its purpose: + -------------------------------------------------------------------------- -# Sample default.action file <ijbswa-developers@lists.sourceforge.net> + 8.7.1. default.action + Every config file should start with a short comment stating its purpose: -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: + # Sample default.action file <ijbswa-developers@lists.sourceforge.net> -########################################################################## -# Settings -- Don't change! For internal Privoxy use ONLY. -########################################################################## + 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}} -for-privoxy-version=3.0 + ########################################################################## + # 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: + 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 @@ -5154,239 +5338,236 @@ used: 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 need -to disable any actions here. (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: -########################################################################## - { \ - +deanimate-gifs \ - +filter{html-annoyances} \ - +filter{refresh-tags} \ - +filter{webbugs} \ - +filter{ie-exploits} \ - +hide-forwarded-for-headers \ - +hide-from-header{block} \ - +hide-referrer{forge} \ - +prevent-compression \ - +session-cookies-only \ - +set-image-blocker{pattern} \ - } - / # forward slash will match *all* potential URL patterns. - - -The default behavior is now set. - -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 -mail.google.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: - -########################################################################## -# Images: -########################################################################## - -# 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)$ - - -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 -.qkimg.net - - -One of the most important jobs of Privoxy is to block banners. Many of these -can be "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 many 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: - -########################################################################## -# Block these fine banners: -########################################################################## -{ +block } - -# 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)?)/ - -# Site-specific patterns (abbreviated): -# -.hitbox.com - - -It's quite remarkable 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. - -########################################################################## -# 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) -adobe. # (has nothing to do with ads either) -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 -bugzilla. -developer. -wiki. -.sourceforge.net - - -The actual default.action is of course much more comprehensive, but we hope -this example made clear how it works. - -------------------------------------------------------------------------------- - -8.7.2. 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@example.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: + 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 + need to disable any actions here. (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: + ########################################################################## + { \ + +deanimate-gifs \ + +filter{html-annoyances} \ + +filter{refresh-tags} \ + +filter{webbugs} \ + +filter{ie-exploits} \ + +hide-forwarded-for-headers \ + +hide-from-header{block} \ + +hide-referrer{forge} \ + +prevent-compression \ + +session-cookies-only \ + +set-image-blocker{pattern} \ + } + / # forward slash will match *all* potential URL patterns. + + The default behavior is now set. + + 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 + mail.google.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: + + ########################################################################## + # Images: + ########################################################################## + + # 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)$ + + 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 + .qkimg.net + + One of the most important jobs of Privoxy is to block banners. Many of + these can be "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 many 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: + + ########################################################################## + # Block these fine banners: + ########################################################################## + { +block } + + # 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)?)/ + + # Site-specific patterns (abbreviated): + # + .hitbox.com + + It's quite remarkable 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. + + ########################################################################## + # 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) + adobe. # (has nothing to do with ads either) + 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 + bugzilla. + developer. + wiki. + .sourceforge.net + + The actual default.action is of course much more comprehensive, but we + hope this example made clear how it works. + + -------------------------------------------------------------------------- + + 8.7.2. 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@example.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: @@ -5418,222 +5599,214 @@ allow-ads = -block -filter{banners-by-size} -filter{banners-by-link} handle-as-text = -filter +-content-type-overwrite{text/plain} +-force-text-mode -hide-content-disposition - - -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. - -{ allow-all-cookies } - sourceforge.net - .yahoo.com - .msdn.microsoft.com - .redhat.com - - -Your bank is allergic to some filter, but you don't know which, so you disable -them all: - -{ -filter } - .your-home-banking-site.com - - -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.example.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. - -{ +block-as-image } - .doubleclick.net - .fastclick.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. We later find other regular sites that -misbehave, and add those to our personalized list of troublemakers: - -{ fragile } - .forbes.com - webmail.example.com - .mybank.com - - -You like the "fun" text replacements in default.filter, but it is disabled in -the distributed actions file. So you'd like to turn it on in your private, -update-safe config, once and for all: -{ +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. - -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: - -{ allow-ads } - .sourceforge.net - .slashdot.org - .osdn.net - - -Note that allow-ads has been aliased to -block, -filter{banners-by-size}, and - -filter{banners-by-link} above. - -Invoke another alias here to force an over-ride of the MIME type application/ -x-sh which typically would open a download type dialog. In my case, I want to -look at the shell script, and then I can save it should I choose to. - -{ handle-as-text } - /.*\.sh$ - - -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: - -{ +set-image-blocker{blank} } -/ # ALL sites - - -------------------------------------------------------------------------------- + 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. + + { allow-all-cookies } + sourceforge.net + .yahoo.com + .msdn.microsoft.com + .redhat.com + + Your bank is allergic to some filter, but you don't know which, so you + disable them all: + + { -filter } + .your-home-banking-site.com + + 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.example.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. + + { +block-as-image } + .doubleclick.net + .fastclick.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. We + later find other regular sites that misbehave, and add those to our + personalized list of troublemakers: + + { fragile } + .forbes.com + webmail.example.com + .mybank.com + + You like the "fun" text replacements in default.filter, but it is disabled + in the distributed actions file. So you'd like to turn it on in your + private, update-safe config, once and for all: + + { +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. + + 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: + + { allow-ads } + .sourceforge.net + .slashdot.org + .osdn.net + + Note that allow-ads has been aliased to -block, -filter{banners-by-size}, + and -filter{banners-by-link} above. + + Invoke another alias here to force an over-ride of the MIME type + application/x-sh which typically would open a download type dialog. In my + case, I want to look at the shell script, and then I can save it should I + choose to. + + { handle-as-text } + /.*\.sh$ + + 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: + + { +set-image-blocker{blank} } + / # ALL sites + + -------------------------------------------------------------------------- 9. Filter Files -On-the-fly text substitutions need to be defined in a "filter file". Once -defined, they can then be invoked as an "action". - -Privoxy supports three different filter actions: filter to rewrite the content -that is send to the client, client-header-filter to rewrite headers that are -send by the client, and server-header-filter to rewrite headers that are send -by the server. - -Privoxy also supports two tagger actions: client-header-tagger and -server-header-tagger. Taggers and filters use the same syntax in the filter -files, the difference is that taggers don't modify the text they are filtering, -but use a rewritten version of the filtered text as tag. The tags can then be -used to change the applying actions through sections with tag-patterns. + On-the-fly text substitutions need to be defined in a "filter file". Once + defined, they can then be invoked as an "action". -Multiple filter files can be defined through the filterfile config directive. -The filters as supplied by the developers are located in default.filter. It is -recommended that any locally defined or modified filters go in a separately -defined file such as user.filter. + Privoxy supports three different filter actions: filter to rewrite the + content that is send to the client, client-header-filter to rewrite + headers that are send by the client, and server-header-filter to rewrite + headers that are send by the server. -Common tasks for content filters 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. + Privoxy also supports two tagger actions: client-header-tagger and + server-header-tagger. Taggers and filters use the same syntax in the + filter files, the difference is that taggers don't modify the text they + are filtering, but use a rewritten version of the filtered text as tag. + The tags can then be used to change the applying actions through sections + with tag-patterns. -Enabled content filters are applied to any content whose "Content Type" header -is recognised as a sign of text-based content, with the exception of text/ -plain. Use the force-text-mode action to also filter other content. + Multiple filter files can be defined through the filterfile config + directive. The filters as supplied by the developers are located in + default.filter. It is recommended that any locally defined or modified + filters go in a separately defined file such as user.filter. -Substitutions are made at the source level, so if you want to "roll your own" -filters, you should first be familiar with HTML syntax, and, of course, regular -expressions. + Common tasks for content filters 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. -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 one of the keywords FILTER:, CLIENT-HEADER-FILTER: or -SERVER-HEADER-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. + Enabled content filters are applied to any content whose "Content Type" + header is recognised as a sign of text-based content, with the exception + of text/plain. Use the force-text-mode action to also filter other + content. -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. + Substitutions are made at the source level, so if you want to "roll your + own" filters, you should first be familiar with HTML syntax, and, of + course, regular expressions. -Filter definitions start with a header line that contains the filter type, the -filter name and the filter description. A content filter header line for a -filter called "foo" could look like this: + 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 one of the keywords FILTER:, CLIENT-HEADER-FILTER: or + SERVER-HEADER-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. -FILTER: foo Replace all "foo" with "bar" + 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. + Filter definitions start with a header line that contains the filter type, + the filter name and the filter description. A content filter header line + for a filter called "foo" could look like this: -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. + FILTER: foo Replace all "foo" with "bar" -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. + 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. -9.1. Filter File Tutorial + -------------------------------------------------------------------------- -Now, let's complete our "foo" content 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: + 9.1. Filter File Tutorial -s/foo/bar/ + Now, let's complete our "foo" content 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: + 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: + 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: -s/foo/bar/g + s/foo/bar/g + Our complete filter now looks like this: -Our complete filter now looks like this: + FILTER: foo Replace all "foo" with "bar" + s/foo/bar/g -FILTER: foo Replace all "foo" with "bar" -s/foo/bar/g - - -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: + 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: FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse @@ -5641,1428 +5814,1464 @@ FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse # s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg - -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 (\). - -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. - -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). - -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. - -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. - -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!". - -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. - -We'll show you two other jobs from the JavaScript taming department, but this -time only point out the constructs of special interest: - -# The status bar is for displaying link targets, not pointless blahblah -# -s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig - - -\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 -back-reference to the first parenthesis just like $1 above, with the difference -that in the pattern, a backslash indicates a back-reference, 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. + 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 + (\). + + 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. + + 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). + + 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. + + 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. + + 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!". + + 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. + + We'll show you two other jobs from the JavaScript taming department, but + this time only point out the constructs of special interest: + + # The status bar is for displaying link targets, not pointless blahblah + # + s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig + + \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 back-reference to the first parenthesis just like $1 above, with + the difference that in the pattern, a backslash indicates a + back-reference, 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. # Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html # s/(<body [^>]*)onunload(.*>)/$1never$2/iU + 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. -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 last example is from the fun department: -The last example is from the fun department: + FILTER: fun Fun text replacements -FILTER: fun Fun text replacements - -# Spice the daily news: -# -s/microsoft(?!\.com)/MicroSuck/ig + # Spice the daily news: + # + s/microsoft(?!\.com)/MicroSuck/ig + 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. -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. - -# 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 + # 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 + 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. -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. + You get the idea? -You get the idea? + -------------------------------------------------------------------------- -------------------------------------------------------------------------------- + 9.2. The Pre-defined Filters -9.2. The Pre-defined Filters + The distribution default.filter file contains a selection of pre-defined + filters for your convenience: -The distribution default.filter file contains a selection of pre-defined -filters for your convenience: + js-annoyances -js-annoyances + The purpose of this filter is to get rid of particularly annoying + JavaScript abuse. To that end, it - 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. - + 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 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-resizeable, without location, status or menu bar etc. - + removes code that causes new windows to be opened with undesired - properties, such as being full-screen, non-resizeable, without - location, status or menu bar etc. + Use with caution. This is an aggressive filter, and can break + sites that rely heavily on JavaScript. - Use with caution. This is an aggressive filter, and can break sites that - rely heavily on JavaScript. + js-events -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. Use with caution! - 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. Use with caution! + 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). - 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). + html-annoyances -html-annoyances + This filter will undo many common instances of HTML based abuse. - 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 resizeable (as of course they + should be!), and will have location, scroll and menu bars -- even + if specified otherwise. - The BLINK and MARQUEE tags are neutralized (yeah baby!), and browser - windows will be created as resizeable (as of course they should be!), and - will have location, scroll and menu bars -- even if specified otherwise. + content-cookies -content-cookies + Most cookies are set in the HTTP dialog, 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. - Most cookies are set in the HTTP dialog, 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 most HTML and JavaScript code that reads or + sets cookies. It cannot detect all clever uses of these types of + code, so it should not be relied on as an absolute fix. Use it + wherever you would also use the cookie crunch actions. - This filter disables most HTML and JavaScript code that reads or sets - cookies. It cannot detect all clever uses of these types of code, so it - should not be relied on as an absolute fix. Use it wherever you would also - use the cookie crunch actions. + refresh tags -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. - 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 -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. - 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, PrivoxyWindowOpen(), + during the loading and rendering phase of each HTML page access, + and restoring the function afterward. - Technical note: The filter works by redefining the window.open JavaScript - function to a dummy function, PrivoxyWindowOpen(), during the loading and - rendering phase of each HTML page access, and restoring the function - afterward. + This is recommended only for browsers that cannot perform this + function reliably themselves. And be aware that some sites require + such windows in order to function normally. Use with caution. - This is recommended only for browsers that cannot perform this function - reliably themselves. And be aware that some sites require such windows in - order to function normally. Use with caution. + all-popups -all-popups + Attempt to prevent all pop-up windows from opening. Note this + should be used with even more discretion than the above, since it + is more likely to break some sites that require pop-ups for normal + usage. Use with caution. - Attempt to prevent all pop-up windows from opening. Note this should be - used with even 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 -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. - 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 -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. - 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. - 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. + Recommended only for those who require extreme ad blocking. The + default block rules should catch 95+% of all ads without this + filter enabled. - Recommended only for those who require extreme ad blocking. The default - block rules should catch 95+% of all ads without this filter enabled. + banners-by-link -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. - 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 + 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 user + ever becoming aware of the interaction with the third-party site. + HTML-ized spam also uses a similar technique to verify email + addresses. - 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 user 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". - This filter removes the HTML code that loads such "webbugs". + tiny-textforms -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. - 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. - It is not recommended to use this filter as a default. + jumping-windows -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. Use with caution. - 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. Use with caution. + frameset-borders -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. - 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. - This filter removes the related HTML code. It should only be applied to - sites which need it. + demoronizer -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. - 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 weird garbage characters sometimes appear on some + pages, or user agents that don't correct for this on the fly. - 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 weird garbage characters - sometimes appear on some pages, or user agents that don't correct for this - on the fly. + shockwave-flash -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. - 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 -quicktime-kioskmode + Change HTML code that embeds Quicktime objects so that kioskmode, + which prevents saving, is disabled. - Change HTML code that embeds Quicktime objects so that kioskmode, which - prevents saving, is disabled. + fun -fun + Text replacements for subversive browsing fun. Make fun of your + favorite Monopolist or play buzzword bingo. - Text replacements for subversive browsing fun. Make fun of your favorite - Monopolist or play buzzword bingo. + crude-parental -crude-parental + A demonstration-only filter that shows how Privoxy can be used to + delete web content on a keyword basis. - A demonstration-only filter that shows how Privoxy can be used to delete - web content on a keyword basis. + ie-exploits -ie-exploits + An experimental collection of text replacements to disable + malicious HTML and JavaScript code that exploits known security + holes in Internet Explorer. - An experimental 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. - Presently, it only protects against Nimda and a cross-site scripting bug, - and would need active maintenance to provide more substantial protection. + site-specifics -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. - 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. - 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. + google -google + A CSS based block for Google text ads. Also removes a width + limitation and the toolbar advertisement. - A CSS based block for Google text ads. Also removes a width limitation and - the toolbar advertisement. + yahoo -yahoo + Another CSS based block, this time for Yahoo text ads. And removes + a width limitation as well. - Another CSS based block, this time for Yahoo text ads. And removes a width - limitation as well. + msn -msn + Another CSS based block, this time for MSN text ads. And removes + tracking URLs, as well as a width limitation. - Another CSS based block, this time for MSN text ads. And removes tracking - URLs, as well as a width limitation. + blogspot -blogspot + Cleans up some Blogspot blogs. Read the fine print before using + this one! - Cleans up some Blogspot blogs. Read the fine print before using this one! + This filter also intentionally removes some navigation stuff and + sets the page width to 100%. As a result, some rounded "corners" + would appear to early or not at all and as fixing this would + require a browser that understands background-size (CSS3), they + are removed instead. - This filter also intentionally removes some navigation stuff and sets the - page width to 100%. As a result, some rounded "corners" would appear to - early or not at all and as fixing this would require a browser that - understands background-size (CSS3), they are removed instead. + xml-to-html -xml-to-html + Server-header filter to change the Content-Type from xml to html. - Server-header filter to change the Content-Type from xml to html. + html-to-xml -html-to-xml + Server-header filter to change the Content-Type from html to xml. - Server-header filter to change the Content-Type from html to xml. + no-ping -no-ping + Removes the non-standard ping attribute from anchor and area HTML + tags. - Removes the non-standard ping attribute from anchor and area HTML tags. + hide-tor-exit-notation -hide-tor-exit-notation + Client-header filter to remove the Tor exit node notation found in + Host and Referer headers. - Client-header filter to remove the Tor exit node notation found in Host and - Referer headers. + If Privoxy and Tor are chained and Privoxy is configured to use + socks4a, one can use "http://www.example.org.foobar.exit/" to + access the host "www.example.org" through the Tor exit node + "foobar". - If Privoxy and Tor are chained and Privoxy is configured to use socks4a, - one can use "http://www.example.org.foobar.exit/" to access the host - "www.example.org" through the Tor exit node "foobar". + As the HTTP client isn't aware of this notation, it treats the + whole string "www.example.org.foobar.exit" as host and uses it for + the "Host" and "Referer" headers. From the server's point of view + the resulting headers are invalid and can cause problems. - As the HTTP client isn't aware of this notation, it treats the whole string - "www.example.org.foobar.exit" as host and uses it for the "Host" and - "Referer" headers. From the server's point of view the resulting headers - are invalid and can cause problems. + An invalid "Referer" header can trigger "hot-linking" protections, + an invalid "Host" header will make it impossible for the server to + find the right vhost (several domains hosted on the same IP + address). - An invalid "Referer" header can trigger "hot-linking" protections, an - invalid "Host" header will make it impossible for the server to find the - right vhost (several domains hosted on the same IP address). + This client-header filter removes the "foo.exit" part in those + headers to prevent the mentioned problems. Note that it only + modifies the HTTP headers, it doesn't make it impossible for the + server to detect your Tor exit node based on the IP address the + request is coming from. - This client-header filter removes the "foo.exit" part in those headers to - prevent the mentioned problems. Note that it only modifies the HTTP - headers, it doesn't make it impossible for the server to detect your Tor - exit node based on the IP address the request is coming from. - -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 10. Privoxy's Template Files -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/. - -The templates are basically normal HTML files, but with place-holders (called -symbols or exports), which Privoxy fills at run time. It is possible to edit -the templates with a normal text editor, should you want to customize them. -(Not recommended for the casual user). Should you create your own custom -templates, you should use the config setting templdir to specify an alternate -location, so your templates do not get overwritten during upgrades. + 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.) -Note that just like in configuration files, lines starting with # are ignored -when the templates are filled in. + These templates are stored in a subdirectory of the configuration + directory called templates. On Unixish platforms, this is typically + /etc/privoxy/templates/. -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. + The templates are basically normal HTML files, but with place-holders + (called symbols or exports), which Privoxy fills at run time. It is + possible to edit the templates with a normal text editor, should you want + to customize them. (Not recommended for the casual user). Should you + create your own custom templates, you should use the config setting + templdir to specify an alternate location, so your templates do not get + overwritten during upgrades. -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: + Note that just like in configuration files, lines starting with # are + ignored when the templates are filled in. -<!-- @if-unstable-start --> + 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. - ... beta warning HTML code goes here ... + 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-end@ --> + <!-- @if-unstable-start --> + ... beta warning HTML code goes here ... -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: + <!-- if-unstable-end@ --> -<!-- --> + 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: + <!-- --> -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 ;-) + 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. + 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. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 11. Contacting the Developers, Bug Reporting and Feature Requests -We value your feedback. In fact, we rely on it to improve Privoxy and its -configuration. However, please note the following hints, so we can provide you -with the best support: + We value your feedback. In fact, we rely on it to improve Privoxy and its + configuration. However, please note the following hints, so we can provide + you with the best support: -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -11.1. Get Support + 11.1. Get Support -For casual users, our support forum at SourceForge is probably best suited: -http://sourceforge.net/tracker/?group_id=11118&atid=211118 + For casual users, our support forum at SourceForge is probably best + suited: http://sourceforge.net/tracker/?group_id=11118&atid=211118 -All users are of course welcome to discuss their issues on the users mailing -list, where the developers also hang around. + All users are of course welcome to discuss their issues on the users + mailing list, where the developers also hang around. -Note that the Privoxy mailing lists are moderated. Posts from unsubscribed -addresses have to be accepted manually by a moderator. This may cause a delay -of several days and if you use a subject that doesn't clearly mention Privoxy -or one of its features, your message may be accidentally discarded as spam. + Note that the Privoxy mailing lists are moderated. Posts from unsubscribed + addresses have to be accepted manually by a moderator. This may cause a + delay of several days and if you use a subject that doesn't clearly + mention Privoxy or one of its features, your message may be accidentally + discarded as spam. -If you aren't subscribed, you should therefore spend a few seconds to come up -with a proper subject. Additionally you should make it clear that you want to -get CC'd. Otherwise some responses will be directed to the mailing list only, -and you won't see them. + If you aren't subscribed, you should therefore spend a few seconds to come + up with a proper subject. Additionally you should make it clear that you + want to get CC'd. Otherwise some responses will be directed to the mailing + list only, and you won't see them. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -11.2. Reporting Problems + 11.2. Reporting Problems -"Problems" for our purposes, come in two forms: + "Problems" for our purposes, come in two forms: - * Configuration issues, such as ads that slip through, or sites that don't - function properly due to one Privoxy "action" or another being turned "on". + * Configuration issues, such as ads that slip through, or sites that + don't function properly due to one Privoxy "action" or another being + turned "on". - * "Bugs" in the programming code that makes up Privoxy, such as that might - cause a crash. + * "Bugs" in the programming code that makes up Privoxy, such as that + might cause a crash. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -11.2.1. Reporting Ads or Other Configuration Problems + 11.2.1. Reporting Ads or Other Configuration Problems -Please send feedback on ads that slipped through, innocent images that were -blocked, sites that don't work properly, and other configuration related -problem of default.action file, to http://sourceforge.net/tracker/?group_id= -11118&atid=460288, the Actions File Tracker. + Please send feedback on ads that slipped through, innocent images that + were blocked, sites that don't work properly, and other configuration + related problem of default.action file, to + http://sourceforge.net/tracker/?group_id=11118&atid=460288, the Actions + File Tracker. -New, improved default.action files may occasionally be made available based on -your feedback. These will be announced on the ijbswa-announce list and -available from our the files section of our project page. + New, improved default.action files may occasionally be made available + based on your feedback. These will be announced on the ijbswa-announce + list and available from our the files section of our project page. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -11.2.2. Reporting Bugs + 11.2.2. Reporting Bugs -Please report all bugs through our bug tracker: http://sourceforge.net/tracker -/?group_id=11118&atid=111118. + Please report all bugs through our bug tracker: + http://sourceforge.net/tracker/?group_id=11118&atid=111118. -Before doing so, please make sure that the bug has not already been submitted -and observe the additional hints at the top of the submit form. If already -submitted, please feel free to add any info to the original report that might -help to solve the issue. + Before doing so, please make sure that the bug has not already been + submitted and observe the additional hints at the top of the submit form. + If already submitted, please feel free to add any info to the original + report that might help to solve the issue. -Please try to verify that it is a Privoxy bug, and not a browser or site bug or -documented behaviour that just happens to be different than what you expected. -If unsure, try toggling off Privoxy, and see if the problem persists. + Please try to verify that it is a Privoxy bug, and not a browser or site + bug or documented behaviour that just happens to be different than what + you expected. If unsure, try toggling off Privoxy, and see if the problem + persists. -If you are using your own custom configuration, please try the stock configs to -see if the problem is configuration related. If you're having problems with a -feature that is disabled by default, please ask around on the mailing list if -others can reproduce the problem. + If you are using your own custom configuration, please try the stock + configs to see if the problem is configuration related. If you're having + problems with a feature that is disabled by default, please ask around on + the mailing list if others can reproduce the problem. -If you aren't using the latest Privoxy version, the bug may have been found and -fixed in the meantime. We would appreciate if you could take the time to -upgrade to the latest version (or even the latest CVS snapshot) and verify that -your bug still exists. + If you aren't using the latest Privoxy version, the bug may have been + found and fixed in the meantime. We would appreciate if you could take the + time to upgrade to the latest version (or even the latest CVS snapshot) + and verify that your bug still exists. -Please be sure to provide the following information: + Please be sure to provide the following information: - * The exact Privoxy version you are using (if you got the source from CVS, - please also provide the source code revisions as shown in http:// - config.privoxy.org/show-version). + * The exact Privoxy version you are using (if you got the source from + CVS, please also provide the source code revisions as shown in + http://config.privoxy.org/show-version). - * The operating system and versions you run Privoxy on, (e.g. Windows XP - SP2), if you are using a Unix flavor, sending the output of "uname -a" - should do, in case of GNU/Linux, please also name the distribution. + * The operating system and versions you run Privoxy on, (e.g. Windows XP + SP2), if you are using a Unix flavor, sending the output of "uname -a" + should do, in case of GNU/Linux, please also name the distribution. - * The name, platform, and version of the browser you were using (e.g. - Internet Explorer v5.5 for Mac). + * The name, platform, and version of the browser you were using (e.g. + Internet Explorer v5.5 for Mac). - * The URL where the problem occurred, or some way for us to duplicate the - problem (e.g. http://somesite.example.com/?somethingelse=123). + * The URL where the problem occurred, or some way for us to duplicate + the problem (e.g. http://somesite.example.com/?somethingelse=123). - * Whether your version of Privoxy is one supplied by the Privoxy developers - via SourceForge, or if you got your copy somewhere else. + * Whether your version of Privoxy is one supplied by the Privoxy + developers via SourceForge, or if you got your copy somewhere else. - * Whether you are using Privoxy in tandem with another proxy such as Tor. If - so, please temporary disable the other proxy to see if the symptoms change. + * Whether you are using Privoxy in tandem with another proxy such as + Tor. If so, please temporary disable the other proxy to see if the + symptoms change. - * Whether you are using a personal firewall product. If so, does Privoxy work - without it? + * Whether you are using a personal firewall product. If so, does Privoxy + work without it? - * Any other pertinent information to help identify the problem such as config - or log file excerpts (yes, you should have log file entries for each action - taken). + * Any other pertinent information to help identify the problem such as + config or log file excerpts (yes, you should have log file entries for + each action taken). -You don't have to tell us your actual name when filing a problem report, but -please use a nickname so we can differentiate between your messages and the -ones entered by other "anonymous" users that may respond to your request if -they have the same problem or already found a solution. + You don't have to tell us your actual name when filing a problem report, + but please use a nickname so we can differentiate between your messages + and the ones entered by other "anonymous" users that may respond to your + request if they have the same problem or already found a solution. -Please also check the status of your request a few days after submitting it, as -we may request additional information. If you use a SF id, you should -automatically get a mail when someone responds to your request. + Please also check the status of your request a few days after submitting + it, as we may request additional information. If you use a SF id, you + should automatically get a mail when someone responds to your request. -The appendix of the Privoxy User Manual also has helpful information on -understanding actions, and action debugging. + The appendix of the Privoxy User Manual also has helpful information on + understanding actions, and action debugging. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -11.3. Request New Features + 11.3. Request New Features -You are welcome to submit ideas on new features or other proposals for -improvement through our feature request tracker at http://sourceforge.net/ -tracker/?atid=361118&group_id=11118. + You are welcome to submit ideas on new features or other proposals for + improvement through our feature request tracker at + http://sourceforge.net/tracker/?atid=361118&group_id=11118. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- -11.4. Other + 11.4. Other -For any other issues, feel free to use the mailing lists. Technically -interested users and people who wish to contribute to the project are also -welcome on the developers list! You can find an overview of all Privoxy-related -mailing lists, including list archives, at: http://sourceforge.net/mail/? -group_id=11118. + For any other issues, feel free to use the mailing lists. Technically + interested users and people who wish to contribute to the project are also + welcome on the developers list! You can find an overview of all + Privoxy-related mailing lists, including list archives, at: + http://sourceforge.net/mail/?group_id=11118. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 12. Privoxy Copyright, License and History -Copyright 2001-2008 by Privoxy Developers < -ijbswa-developers@lists.sourceforge.net> - -Some source code is based on code Copyright 1997 by Anonymous Coders and -Junkbusters, Inc. and licensed under the GNU General Public License. - -------------------------------------------------------------------------------- - -12.1. License - -Privoxy is free software; you can redistribute it and/or modify it under the -terms of the GNU General Public License, version 2, as published by the Free -Software Foundation. - -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, 51 Franklin Street, Fifth -Floor, Boston, MA 02110-1301, USA - -You should have received a copy of the GNU General Public License along with -this program; if not, write to the - - Free Software - Foundation, Inc. 51 Franklin Street, Fifth Floor - Boston, MA 02110-1301 - USA - -------------------------------------------------------------------------------- - -12.2. History - -A long time ago, there was the Internet Junkbuster, by Anonymous Coders and -Junkbusters Corporation. This saved many users a lot of pain in the early days -of web advertising and user tracking. - -But the web, its protocols and standards, and with it, the techniques for -forcing ads on users, give up autonomy over their browsing, and for tracking -them, keeps evolving. Unfortunately, the Internet Junkbuster did not. Version -2.0.2, published in 1998, was (and is) the last official release available from -Junkbusters Corporation. Fortunately, it had been released under the GNU GPL, -which allowed further development by others. - -So Stefan Waldherr started maintaining an improved version of the software, to -which eventually a number of people contributed patches. It could already -replace banners with a transparent image, and had a first version of pop-up -killing, but it was still very closely based on the original, with all its -limitations, such as the lack of HTTP/1.1 support, flexible per-site -configuration, or content modification. The last release from this effort was -version 2.0.2-10, published in 2000. - -Then, some developers picked up the thread, and started turning the software -inside out, upside down, and then reassembled it, adding many new features -along the way. - -The result of this is Privoxy, whose first stable version, 3.0, was released -August, 2002. - -------------------------------------------------------------------------------- - -12.3. Authors - -Current Privoxy Team: - - Fabian Keil, lead developer - David Schmidt, developer - - Hal Burgiss - Gerry Murphy - Roland Rosenfeld - J rg Strohmayer - -Former Privoxy Team Members: - - Johny Agotnes - Rodrigo Barbosa - Moritz Barsnick - Ian Cummings - Brian Dessent - Jon Foster - Karsten Hopp - Alexander Lazic - Daniel Leite - G bor Lipt k - Adam Lock - Guy Laroche - Mark Martinec - Justin McMurtry - Andreas Oesterhelt - Haroon Rafique - Georg Sauthoff - Thomas Steudten - Rodney Stromlund - Sviatoslav Sviridov - Sarantis Paskalis - Stefan Waldherr - -Thanks to the many people who have tested Privoxy, reported bugs, provided -patches, made suggestions or contributed in some way. These include (in -alphabetical order): - - Ken Arromdee - Devin Bayer - Gergely Bor - Reiner Buehl - Andrew J. Caines - Clifford Caoile - Fr d ric Crozat - Michael T. Davis - Mattes Dolak - Peter E. - Florian Effenberger - Markus Elfring - Dean Gaudet - Stephen Gildea - Daniel Griscom - Felix Gr bert - Aaron Hamid - Darel Henman - Magnus Holmgren - Ralf Horstmann - Stefan Huehner - Peter Hyman - Derek Jennings - Petr Kadlec - David Laight - Bert van Leeuwen - Don Libes - Paul Lieverse - Toby Lyward - Wil Mahan - Jindrich Makovicka - David Mediavilla - Raphael Moll - Amuro Namie - Adam Piggott - Dan Price - Lee R. - Roberto Ragusa - F lix Rauch - Maynard Riley - Chung-chieh Shan - Spinor S. - Bart Schelstraete - Oliver Stoeneberg - Peter Thoenen - Martin Thomas - Song Weijia - J rg Weinmann - Darren Wiebe - Bobby G. Vinyard - Anduin Withers - Oliver Yeoh - Jamie Zawinski - -Privoxy is based in part on code originally developed by Junkbusters Corp. and -Anonymous Coders. - -Privoxy heavily relies on Philip Hazel's PCRE. - -The code to filter compressed content makes use of zlib which is written by -Jean-loup Gailly and Mark Adler. - -On systems that lack snprintf(), Privoxy is using a version written by Mark -Martinec. On systems that lack strptime(), Privoxy is using the one from the -GNU C Library written by Ulrich Drepper. - -------------------------------------------------------------------------------- + Copyright © 2001-2008 by Privoxy Developers + <ijbswa-developers@lists.sourceforge.net> + + Some source code is based on code Copyright © 1997 by Anonymous Coders + and Junkbusters, Inc. and licensed under the GNU General Public License. + + -------------------------------------------------------------------------- + + 12.1. License + + Privoxy is free software; you can redistribute it and/or modify it under + the terms of the GNU General Public License, version 2, as published by + the Free Software Foundation. + + 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, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the + + Free Software + Foundation, Inc. 51 Franklin Street, Fifth Floor + Boston, MA 02110-1301 + USA + + -------------------------------------------------------------------------- + + 12.2. History + + A long time ago, there was the Internet Junkbuster, by Anonymous Coders + and Junkbusters Corporation. This saved many users a lot of pain in the + early days of web advertising and user tracking. + + But the web, its protocols and standards, and with it, the techniques for + forcing ads on users, give up autonomy over their browsing, and for + tracking them, keeps evolving. Unfortunately, the Internet Junkbuster did + not. Version 2.0.2, published in 1998, was (and is) the last official + release available from Junkbusters Corporation. Fortunately, it had been + released under the GNU GPL, which allowed further development by others. + + So Stefan Waldherr started maintaining an improved version of the + software, to which eventually a number of people contributed patches. It + could already replace banners with a transparent image, and had a first + version of pop-up killing, but it was still very closely based on the + original, with all its limitations, such as the lack of HTTP/1.1 support, + flexible per-site configuration, or content modification. The last release + from this effort was version 2.0.2-10, published in 2000. + + Then, some developers picked up the thread, and started turning the + software inside out, upside down, and then reassembled it, adding many new + features along the way. + + The result of this is Privoxy, whose first stable version, 3.0, was + released August, 2002. + + -------------------------------------------------------------------------- + + 12.3. Authors + + Current Privoxy Team: + + Fabian Keil, lead developer + David Schmidt, developer + + Hal Burgiss + Gerry Murphy + Roland Rosenfeld + Jörg Strohmayer + + Former Privoxy Team Members: + + Johny Agotnes + Rodrigo Barbosa + Moritz Barsnick + Ian Cummings + Brian Dessent + Jon Foster + Karsten Hopp + Alexander Lazic + Daniel Leite + Gábor Lipták + Adam Lock + Guy Laroche + Mark Martinec + Justin McMurtry + Andreas Oesterhelt + Haroon Rafique + Georg Sauthoff + Thomas Steudten + Rodney Stromlund + Sviatoslav Sviridov + Sarantis Paskalis + Stefan Waldherr + + Thanks to the many people who have tested Privoxy, reported bugs, provided + patches, made suggestions or contributed in some way. These include (in + alphabetical order): + + Ken Arromdee + Devin Bayer + Gergely Bor + Reiner Buehl + Andrew J. Caines + Clifford Caoile + Frédéric Crozat + Michael T. Davis + Mattes Dolak + Peter E. + Florian Effenberger + Markus Elfring + Dean Gaudet + Stephen Gildea + Daniel Griscom + Felix Gröbert + Aaron Hamid + Darel Henman + Magnus Holmgren + Ralf Horstmann + Stefan Huehner + Peter Hyman + Derek Jennings + Petr Kadlec + David Laight + Bert van Leeuwen + Don Libes + Paul Lieverse + Toby Lyward + Wil Mahan + Jindrich Makovicka + David Mediavilla + Raphael Moll + Amuro Namie + Adam Piggott + Dan Price + Lee R. + Roberto Ragusa + Félix Rauch + Maynard Riley + Chung-chieh Shan + Spinor S. + Bart Schelstraete + Oliver Stoeneberg + Peter Thoenen + Martin Thomas + Song Weijia + Jörg Weinmann + Darren Wiebe + Bobby G. Vinyard + Anduin Withers + Oliver Yeoh + Jamie Zawinski + + Privoxy is based in part on code originally developed by Junkbusters Corp. + and Anonymous Coders. + + Privoxy heavily relies on Philip Hazel's PCRE. + + The code to filter compressed content makes use of zlib which is written + by Jean-loup Gailly and Mark Adler. + + On systems that lack snprintf(), Privoxy is using a version written by + Mark Martinec. On systems that lack strptime(), Privoxy is using the one + from the GNU C Library written by Ulrich Drepper. + + -------------------------------------------------------------------------- 13. See Also -Other references and sites of interest to Privoxy users: + Other references and sites of interest to Privoxy users: -http://www.privoxy.org/, the Privoxy Home page. + http://www.privoxy.org/, the Privoxy Home page. -http://www.privoxy.org/faq/, the Privoxy FAQ. + http://www.privoxy.org/faq/, the Privoxy FAQ. -http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on -SourceForge. + http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on + SourceForge. -http://config.privoxy.org/, the web-based user interface. Privoxy must be -running for this to work. Shortcut: http://p.p/ + http://config.privoxy.org/, the web-based user interface. Privoxy must be + running for this to work. Shortcut: http://p.p/ -http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit "misses" -and other configuration related suggestions to the developers. + http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit + "misses" and other configuration related suggestions to the developers. -http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies are -used to track web users. + http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies + are used to track web users. -http://www.junkbusters.com/ijb.html, the original Internet Junkbuster. + http://www.junkbusters.com/ijb.html, the original Internet Junkbuster. -http://privacy.net/, a useful site to check what information about you is -leaked while you browse the web. + http://privacy.net/, a useful site to check what information about you is + leaked while you browse the web. -http://www.squid-cache.org/, a popular caching proxy, which is often used -together with Privoxy. + http://www.squid-cache.org/, a popular caching proxy, which is often used + together with Privoxy. -http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy with -advanced features like pipelining, multiplexing and caching of partial -instances. In many setups it can be used as Squid replacement. + http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy + with advanced features like pipelining, multiplexing and caching of + partial instances. In many setups it can be used as Squid replacement. -http://tor.eff.org/, Tor can help anonymize web browsing, web publishing, -instant messaging, IRC, SSH, and other applications. + http://tor.eff.org/, Tor can help anonymize web browsing, web publishing, + instant messaging, IRC, SSH, and other applications. -http://www.privoxy.org/developer-manual/, the Privoxy developer manual. + http://www.privoxy.org/developer-manual/, the Privoxy developer manual. -------------------------------------------------------------------------------- + -------------------------------------------------------------------------- 14. Appendix -14.1. Regular Expressions - -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 ;-) - -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. - -To make a simple analogy, we do something similar when we use wild-card -characters when listing files with the dir command in DOS. *.* matches all -filenames. The "special" character here is the asterisk which matches any and -all characters. We can be more specific and use ? to match just individual -characters. So "dir file?.text" would match "file1.txt", "file2.txt", etc. We -are pattern matching, using a similar technique to "regular expressions"! - -Regular expressions do essentially the same thing, but are much, much more -powerful. There are many more "special characters" and ways of building complex -patterns however. Let's look at a few of the common ones, and then some -examples: - -. - Matches any single character, e.g. "a", "A", "4", ":", or "@". - -? - The preceding character or expression is matched ZERO or ONE times. Either/ -or. - -+ - The preceding character or expression is matched ONE or MORE times. - -* - The preceding character or expression is matched ZERO or MORE times. - -\ - The "escape" character denotes that the following character should be taken -literally. This is used where one of the special characters (e.g. ".") needs to -be taken literally and not as a special meta-character. Example: "example -\.com", makes sure the period is recognized only as a period (and not expanded -to its meta-character meaning of any single character). - -[ ] - Characters enclosed in brackets will be matched if any of the enclosed -characters are encountered. For instance, "[0-9]" matches any numeric digit -(zero through nine). As an example, we can combine this with "+" to match any -digit one of more times: "[0-9]+". - -( ) - parentheses are used to group a sub-expression, or multiple -sub-expressions. - -| - The "bar" character works like an "or" conditional statement. A match is -successful if the sub-expression on either side of "|" matches. As an example: -"/(this|that) example/" uses grouping and the bar character and would match -either "this example" or "that example", and nothing else. - -These are just some of the ones you are likely to use when matching URLs with -Privoxy, and is a long way from a definitive list. This is enough to get us -started with a few simple examples which may be more illuminating: - -/.*/banners/.* - A simple example that uses the common combination of "." and -"*" to denote any character, zero or more times. In other words, any string at -all. So we start with a literal forward slash, then our regular expression -pattern (".*") another literal forward slash, the string "banners", another -forward slash, and lastly another ".*". We are building a directory path here. -This will match any file with the path that has a directory named "banners" in -it. The ".*" matches any characters, and this could conceivably be more forward -slashes, so it might expand into a much longer looking path. For example, this -could match: "/eye/hate/spammers/banners/annoy_me_please.gif", or just "/ -banners/annoying.html", or almost an infinite number of other possible -combinations, just so it has "banners" in the path somewhere. - -And now something a little more complex: - -/.*/adv((er)?ts?|ertis(ing|ements?))?/ - We have several literal forward -slashes again ("/"), so we are building another expression that is a file path -statement. We have another ".*", so we are matching against any conceivable -sub-path, just so it matches our expression. The only true literal that must -match our pattern is adv, together with the forward slashes. What comes after -the "adv" string is the interesting part. + 14.1. Regular Expressions + + 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 ;-) + + 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. + + To make a simple analogy, we do something similar when we use wild-card + characters when listing files with the dir command in DOS. *.* matches all + filenames. The "special" character here is the asterisk which matches any + and all characters. We can be more specific and use ? to match just + individual characters. So "dir file?.text" would match "file1.txt", + "file2.txt", etc. We are pattern matching, using a similar technique to + "regular expressions"! + + Regular expressions do essentially the same thing, but are much, much more + powerful. There are many more "special characters" and ways of building + complex patterns however. Let's look at a few of the common ones, and then + some examples: + + . - Matches any single character, e.g. "a", "A", "4", ":", or "@". + + ? - The preceding character or expression is matched ZERO or ONE times. + Either/or. + + + - The preceding character or expression is matched ONE or MORE times. + + * - The preceding character or expression is matched ZERO or MORE times. + + \ - The "escape" character denotes that the following character should be + taken literally. This is used where one of the special characters (e.g. + ".") needs to be taken literally and not as a special meta-character. + Example: "example\.com", makes sure the period is recognized only as a + period (and not expanded to its meta-character meaning of any single + character). + + [ ] - Characters enclosed in brackets will be matched if any of the + enclosed characters are encountered. For instance, "[0-9]" matches any + numeric digit (zero through nine). As an example, we can combine this with + "+" to match any digit one of more times: "[0-9]+". + + ( ) - parentheses are used to group a sub-expression, or multiple + sub-expressions. + + | - The "bar" character works like an "or" conditional statement. A match + is successful if the sub-expression on either side of "|" matches. As an + example: "/(this|that) example/" uses grouping and the bar character and + would match either "this example" or "that example", and nothing else. + + These are just some of the ones you are likely to use when matching URLs + with Privoxy, and is a long way from a definitive list. This is enough to + get us started with a few simple examples which may be more illuminating: + + /.*/banners/.* - A simple example that uses the common combination of "." + and "*" to denote any character, zero or more times. In other words, any + string at all. So we start with a literal forward slash, then our regular + expression pattern (".*") another literal forward slash, the string + "banners", another forward slash, and lastly another ".*". We are building + a directory path here. This will match any file with the path that has a + directory named "banners" in it. The ".*" matches any characters, and this + could conceivably be more forward slashes, so it might expand into a much + longer looking path. For example, this could match: + "/eye/hate/spammers/banners/annoy_me_please.gif", or just + "/banners/annoying.html", or almost an infinite number of other possible + combinations, just so it has "banners" in the path somewhere. + + And now something a little more complex: + + /.*/adv((er)?ts?|ertis(ing|ements?))?/ - We have several literal forward + slashes again ("/"), so we are building another expression that is a file + path statement. We have another ".*", so we are matching against any + conceivable sub-path, just so it matches our expression. The only true + literal that must match our pattern is adv, together with the forward + slashes. What comes after the "adv" string is the interesting part. + + Remember the "?" means the preceding expression (either a literal + character or anything grouped with "(...)" in this case) can exist or not, + since this means either zero or one match. So + "((er)?ts?|ertis(ing|ements?))" is optional, as are the individual + sub-expressions: "(er)", "(ing|ements?)", and the "s". The "|" means "or". + We have two of those. For instance, "(ing|ements?)", can expand to match + either "ing" OR "ements?". What is being done here, is an attempt at + matching as many variations of "advertisement", and similar, as possible. + So this would expand to match just "adv", or "advert", or "adverts", or + "advertising", or "advertisement", or "advertisements". You get the idea. + But it would not match "advertizements" (with a "z"). We could fix that by + changing our regular expression to: + "/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/", which would then match + either spelling. + + /.*/advert[0-9]+\.(gif|jpe?g) - Again another path statement with forward + slashes. Anything in the square brackets "[ ]" can be matched. This is + using "0-9" as a shorthand expression to mean any digit one through nine. + It is the same as saying "0123456789". So any digit matches. The "+" means + one or more of the preceding expression must be included. The preceding + expression here is what is in the square brackets -- in this case, any + digit one through nine. Then, at the end, we have a grouping: + "(gif|jpe?g)". This includes a "|", so this needs to match the expression + on either side of that bar character also. A simple "gif" on one side, and + the other side will in turn match either "jpeg" or "jpg", since the "?" + means the letter "e" is optional and can be matched once or not at all. So + we are building an expression here to match image GIF or JPEG type image + file. It must include the literal string "advert", then one or more + digits, and a "." (which is now a literal, and not a special character, + since it is escaped with "\"), and lastly either "gif", or "jpeg", or + "jpg". Some possible matches would include: "//advert1.jpg", + "/nasty/ads/advert1234.gif", "/banners/from/hell/advert99.jpg". It would + not match "advert1.gif" (no leading slash), or "/adverts232.jpg" (the + expression does not include an "s"), or "/advert1.jsp" ("jsp" is not in + the expression anywhere). -Remember the "?" means the preceding expression (either a literal character or -anything grouped with "(...)" in this case) can exist or not, since this means -either zero or one match. So "((er)?ts?|ertis(ing|ements?))" is optional, as -are the individual sub-expressions: "(er)", "(ing|ements?)", and the "s". The " -|" means "or". We have two of those. For instance, "(ing|ements?)", can expand -to match either "ing" OR "ements?". What is being done here, is an attempt at -matching as many variations of "advertisement", and similar, as possible. So -this would expand to match just "adv", or "advert", or "adverts", or -"advertising", or "advertisement", or "advertisements". You get the idea. But -it would not match "advertizements" (with a "z"). We could fix that by changing -our regular expression to: "/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/", which -would then match either spelling. + We are barely scratching the surface of regular expressions here so that + you can understand the default Privoxy configuration files, and maybe use + this knowledge to customize your own installation. There is much, much + more that can be done with regular expressions. Now that you know enough + to get started, you can learn more on your own :/ -/.*/advert[0-9]+\.(gif|jpe?g) - Again another path statement with forward -slashes. Anything in the square brackets "[ ]" can be matched. This is using -"0-9" as a shorthand expression to mean any digit one through nine. It is the -same as saying "0123456789". So any digit matches. The "+" means one or more of -the preceding expression must be included. The preceding expression here is -what is in the square brackets -- in this case, any digit one through nine. -Then, at the end, we have a grouping: "(gif|jpe?g)". This includes a "|", so -this needs to match the expression on either side of that bar character also. A -simple "gif" on one side, and the other side will in turn match either "jpeg" -or "jpg", since the "?" means the letter "e" is optional and can be matched -once or not at all. So we are building an expression here to match image GIF or -JPEG type image file. It must include the literal string "advert", then one or -more digits, and a "." (which is now a literal, and not a special character, -since it is escaped with "\"), and lastly either "gif", or "jpeg", or "jpg". -Some possible matches would include: "//advert1.jpg", "/nasty/ads/ -advert1234.gif", "/banners/from/hell/advert99.jpg". It would not match -"advert1.gif" (no leading slash), or "/adverts232.jpg" (the expression does not -include an "s"), or "/advert1.jsp" ("jsp" is not in the expression anywhere). + More reading on Perl Compatible Regular expressions: + http://perldoc.perl.org/perlre.html -We are barely scratching the surface of regular expressions here so that you -can understand the default Privoxy configuration files, and maybe use this -knowledge to customize your own installation. There is much, much more that can -be done with regular expressions. Now that you know enough to get started, you -can learn more on your own :/ + For information on regular expression based substitutions and their + applications in filters, please see the filter file tutorial in this + manual. -More reading on Perl Compatible Regular expressions: http://perldoc.perl.org/ -perlre.html + -------------------------------------------------------------------------- -For information on regular expression based substitutions and their -applications in filters, please see the filter file tutorial in this manual. + 14.2. Privoxy's Internal Pages -------------------------------------------------------------------------------- + Since Privoxy proxies each requested web page, it is easy for Privoxy to + trap certain special URLs. In this way, we can talk directly to Privoxy, + and see how it is configured, see how our rules are being applied, change + these rules and other configuration options, and even turn Privoxy's + filtering off, all with a web browser. -14.2. Privoxy's Internal Pages + The URLs listed below are the special ones that allow direct access to + Privoxy. Of course, Privoxy must be running to access these. If not, you + will get a friendly error message. Internet access is not necessary + either. -Since Privoxy proxies each requested web page, it is easy for Privoxy to trap -certain special URLs. In this way, we can talk directly to Privoxy, and see how -it is configured, see how our rules are being applied, change these rules and -other configuration options, and even turn Privoxy's filtering off, all with a -web browser. + * Privoxy main page: -The URLs listed below are the special ones that allow direct access to Privoxy. -Of course, Privoxy must be running to access these. If not, you will get a -friendly error message. Internet access is not necessary either. + http://config.privoxy.org/ - * Privoxy main page: + 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) - http://config.privoxy.org/ + * Show information about the current configuration, including viewing + and editing of actions files: - 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) + http://config.privoxy.org/show-status - * Show information about the current configuration, including viewing and - editing of actions files: + * Show the source code version numbers: - http://config.privoxy.org/show-status + http://config.privoxy.org/show-version - * Show the source code version numbers: + * Show the browser's request headers: - http://config.privoxy.org/show-version + http://config.privoxy.org/show-request - * Show the browser's request headers: + * Show which actions apply to a URL and why: - http://config.privoxy.org/show-request + http://config.privoxy.org/show-url-info - * Show which actions apply to a URL and why: + * Toggle Privoxy on or off. This feature can be turned off/on in the + main config file. When toggled "off", "Privoxy" continues to run, but + only as a pass-through proxy, with no actions taking place: - http://config.privoxy.org/show-url-info + http://config.privoxy.org/toggle - * Toggle Privoxy on or off. This feature can be turned off/on in the main - config file. When toggled "off", "Privoxy" continues to run, but only as a - pass-through proxy, with no actions taking place: + Short cuts. Turn off, then on: - http://config.privoxy.org/toggle + http://config.privoxy.org/toggle?set=disable - Short cuts. Turn off, then on: + http://config.privoxy.org/toggle?set=enable - http://config.privoxy.org/toggle?set=disable + These may be bookmarked for quick reference. See next. - http://config.privoxy.org/toggle?set=enable + -------------------------------------------------------------------------- -These may be bookmarked for quick reference. See next. + 14.2.1. 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). -14.2.1. Bookmarklets + 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. -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). + * Privoxy - Enable -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 - Disable - * Privoxy - Enable + * Privoxy - Toggle Privoxy (Toggles between enabled and disabled) - * Privoxy - Disable + * Privoxy- View Status - * Privoxy - Toggle Privoxy (Toggles between enabled and disabled) + * Privoxy - Why? - * Privoxy- View Status + Credit: The site which gave us the general idea for these bookmarklets is + www.bookmarklets.com. They have more information about bookmarklets. - * Privoxy - Why? + -------------------------------------------------------------------------- -Credit: The site which gave us the general idea for these bookmarklets is -www.bookmarklets.com. They have more information about bookmarklets. + 14.3. Chain of Events -------------------------------------------------------------------------------- + Let's take a quick look at how some of Privoxy's core features are + triggered, and the ensuing sequence of events when a web page is requested + by your browser: -14.3. Chain of Events + * 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: -Let's take a quick look at how some of Privoxy's core features are triggered, -and the ensuing sequence of events when a web page is requested by your -browser: + * Privoxy traps any request for its own internal CGI pages (e.g + http://p.p/) and sends the CGI page back to the browser. - * 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: + * 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" and "+handle-as-empty-document" are then + checked, and if there is no match, an HTML "BLOCKED" page is sent back + to the browser. Otherwise, if it does match, an image is returned for + the former, and an empty text document for the latter. The type of + image would depend on the setting of "+set-image-blocker" (blank, + checkerboard pattern, or an HTTP redirect to an image elsewhere). - * Privoxy traps any request for its own internal CGI pages (e.g http://p.p/) - and sends the CGI page back to the browser. + * Untrusted URLs are blocked. If URLs are being added to the trust file, + then that is done. - * 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" and "+handle-as-empty-document" are then - checked, and if there is no match, an HTML "BLOCKED" page is sent back to - the browser. Otherwise, if it does match, an image is returned for the - former, and an empty text document for the latter. The type of image would - depend on the setting of "+set-image-blocker" (blank, checkerboard pattern, - or an HTTP redirect to an image elsewhere). + * If the URL pattern matches the "+fast-redirects" action, it is then + processed. Unwanted parts of the requested URL are stripped. - * Untrusted URLs are blocked. If URLs are being added to the trust file, then - that is done. + * 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. - * If the URL pattern matches the "+fast-redirects" action, it is then - processed. Unwanted parts of the requested URL are stripped. + * Now the web server starts sending its response back (i.e. typically a + web page). - * 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. + * 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. - * Now the web server starts sending its response back (i.e. typically a web - page). + * 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. - * 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. - - * If the "+kill-popups" action applies, and it is an HTML or JavaScript - document, the popup-code in the response is filtered on-the-fly as it is - received. - - * If any "+filter" action 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 - and any other filter files) 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. - - If neither a "+filter" action or "+deanimate-gifs" matches, then Privoxy - passes the raw data through to the client browser as it becomes available. - - * As the browser receives the now (possibly 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 - separate request (this is easily viewable in Privoxy's logs). And each such - request is in turn processed just as above. Note that a complex web page - will have many, many such embedded URLs. If these secondary requests are to - a different server, then quite possibly a very differing set of actions is - triggered. - -NOTE: This is somewhat of a simplistic overview of what happens with each URL -request. For the sake of brevity and simplicity, we have focused on Privoxy's -core features only. - -------------------------------------------------------------------------------- - -14.4. Troubleshooting: Anatomy of an Action - -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. - -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. (Note that both the -toggle feature and logging are enabled via config file settings, and may need -to be turned "on".) - -Another easy troubleshooting step to try is if you have done any customization -of your installation, revert back to the installed defaults and see if that -helps. There are times the developers get complaints about one thing or -another, and the problem is more related to a customized configuration issue. - -Privoxy also provides the http://config.privoxy.org/show-url-info page that can -show us very specifically how actions are being applied to any given URL. This -is a big help for troubleshooting. - -First, enter one URL (or partial URL) at the prompt, and then Privoxy will tell -us how the current configuration will handle it. This will not help with -filtering effects (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. - -Let's try an example, google.com, and look at it one section at a time in a -sample configuration (your real configuration may vary): - - Matches for http://www.google.com: - - In file: default.action [ View ] [ Edit ] - - {+deanimate-gifs {last} - +fast-redirects {check-decoded-url} - +filter {refresh-tags} - +filter {img-reorder} - +filter {banners-by-size} - +filter {webbugs} - +filter {jumping-windows} - +filter {ie-exploits} - +hide-forwarded-for-headers - +hide-from-header {block} - +hide-referrer {forge} - +session-cookies-only - +set-image-blocker {pattern} -/ - - { -session-cookies-only } - .google.com - - { -fast-redirects } - .google.com - -In file: user.action [ View ] [ Edit ] -(no matches in this file) - - -This is telling us how we have defined our "actions", and which ones match for -our test case, "google.com". Displayed is all the actions that are available to -us. Remember, the + sign denotes "on". - denotes "off". So some are "on" here, -but many are "off". Each example we try may provide a slightly different end -result, depending on our configuration directives. - -The first listing is for 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 -- " / ". - -But we have defined additional actions that would be exceptions to these -general rules, and then we 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, at least that is how it is in this -example. 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" or "mail.google.com". But it would not match -"www.google.de"! So, apparently, we have these two actions defined as -exceptions to the general rules at the top 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. So there is nothing -google-specific that we might have added to our own, local configuration. If -there was, those actions would over-rule any actions from previously processed -files, such as default.action. user.action typically has the last word. This is -the best place to put hard and fast exceptions, - -And finally we pull it all together in the bottom section and summarize how -Privoxy is applying all its "actions" to "google.com": - - Final results: - - -add-header - -block - -client-header-filter{hide-tor-exit-notation} - -content-type-overwrite - -crunch-client-header - -crunch-if-none-match - -crunch-incoming-cookies - -crunch-outgoing-cookies - -crunch-server-header - +deanimate-gifs {last} - -downgrade-http-version - -fast-redirects - -filter {js-events} - -filter {content-cookies} - -filter {all-popups} - -filter {banners-by-link} - -filter {tiny-textforms} - -filter {frameset-borders} - -filter {demoronizer} - -filter {shockwave-flash} - -filter {quicktime-kioskmode} - -filter {fun} - -filter {crude-parental} - -filter {site-specifics} - -filter {js-annoyances} - -filter {html-annoyances} - +filter {refresh-tags} - -filter {unsolicited-popups} - +filter {img-reorder} - +filter {banners-by-size} - +filter {webbugs} - +filter {jumping-windows} - +filter {ie-exploits} - -filter {google} - -filter {yahoo} - -filter {msn} - -filter {blogspot} - -filter {no-ping} - -force-text-mode - -handle-as-empty-document - -handle-as-image - -hide-accept-language - -hide-content-disposition - +hide-forwarded-for-headers - +hide-from-header {block} - -hide-if-modified-since - +hide-referrer {forge} - -hide-user-agent - -inspect-jpegs - -kill-popups - -limit-connect - -overwrite-last-modified - -prevent-compression - -redirect - -send-vanilla-wafer - -send-wafer - -server-header-filter{xml-to-html} - -server-header-filter{html-to-xml} - -session-cookies-only - +set-image-blocker {pattern} - -treat-forbidden-connects-like-blocks - - -Notice the only difference here to the previous listing, is to "fast-redirects" -and "session-cookies-only", which are activated specifically for this site in -our configuration, and thus show in the "Final Results". - -Now another example, "ad.doubleclick.net": - - { +block } - ad*. - - { +block } - .ad. - - { +block +handle-as-image } - .[a-vx-z]*.doubleclick.net - - -We'll just show the interesting part here - the explicit matches. It is matched -three different times. Two "+block" sections, and a "+block +handle-as-image", -which is the expanded form of one of our aliases that had been defined as: -"+block-as-image". ("Aliases" are defined in the first section of the actions -file and typically used to combine more than one action.) - -Any one of these would have done the trick and blocked this as an unwanted -image. This is unnecessarily redundant since the last case effectively would -also cover the first. No point in taking chances with these guys though ;-) -Note that if you want an ad or obnoxious URL to be invisible, it should be -defined as "ad.doubleclick.net" is done here -- as both a "+block" and an -"+handle-as-image". The custom alias "+block-as-image" just simplifies the -process and make it more readable. - -One last example. Let's try "http://www.example.net/adsl/HOWTO/". This one is -giving us problems. We are getting a blank page. Hmmm ... - - Matches for http://www.example.net/adsl/HOWTO/: - - In file: default.action [ View ] [ Edit ] - - {-add-header - -block - -client-header-filter{hide-tor-exit-notation} - -content-type-overwrite - -crunch-client-header - -crunch-if-none-match - -crunch-incoming-cookies - -crunch-outgoing-cookies - -crunch-server-header - +deanimate-gifs - -downgrade-http-version - +fast-redirects {check-decoded-url} - -filter {js-events} - -filter {content-cookies} - -filter {all-popups} - -filter {banners-by-link} - -filter {tiny-textforms} - -filter {frameset-borders} - -filter {demoronizer} - -filter {shockwave-flash} - -filter {quicktime-kioskmode} - -filter {fun} - -filter {crude-parental} - -filter {site-specifics} - -filter {js-annoyances} - -filter {html-annoyances} - +filter {refresh-tags} - -filter {unsolicited-popups} - +filter {img-reorder} - +filter {banners-by-size} - +filter {webbugs} - +filter {jumping-windows} - +filter {ie-exploits} - -filter {google} - -filter {yahoo} - -filter {msn} - -filter {blogspot} - -filter {no-ping} - -force-text-mode - -handle-as-empty-document - -handle-as-image - -hide-accept-language - -hide-content-disposition - +hide-forwarded-for-headers - +hide-from-header{block} - +hide-referer{forge} - -hide-user-agent - -inspect-jpegs - -kill-popups - -overwrite-last-modified - +prevent-compression - -redirect - -send-vanilla-wafer - -send-wafer - -server-header-filter{xml-to-html} - -server-header-filter{html-to-xml} - +session-cookies-only - +set-image-blocker{blank} - -treat-forbidden-connects-like-blocks } + * If any "+filter" action 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 and any other filter files) 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. + + If neither a "+filter" action or "+deanimate-gifs" matches, then + Privoxy passes the raw data through to the client browser as it + becomes available. + + * As the browser receives the now (possibly 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 separate request (this is easily viewable in Privoxy's logs). + And each such request is in turn processed just as above. Note that a + complex web page will have many, many such embedded URLs. If these + secondary requests are to a different server, then quite possibly a + very differing set of actions is triggered. + + NOTE: This is somewhat of a simplistic overview of what happens with each + URL request. For the sake of brevity and simplicity, we have focused on + Privoxy's core features only. + + -------------------------------------------------------------------------- + + 14.4. Troubleshooting: Anatomy of an Action + + 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. + + 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. (Note + that both the toggle feature and logging are enabled via config file + settings, and may need to be turned "on".) + + Another easy troubleshooting step to try is if you have done any + customization of your installation, revert back to the installed defaults + and see if that helps. There are times the developers get complaints about + one thing or another, and the problem is more related to a customized + configuration issue. + + Privoxy also provides the http://config.privoxy.org/show-url-info page + that can show us very specifically how actions are being applied to any + given URL. This is a big help for troubleshooting. + + First, enter one URL (or partial URL) at the prompt, and then Privoxy will + tell us how the current configuration will handle it. This will not help + with filtering effects (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. + + Let's try an example, google.com, and look at it one section at a time in + a sample configuration (your real configuration may vary): + + Matches for http://www.google.com: + + In file: default.action [ View ] [ Edit ] + + {+deanimate-gifs {last} + +fast-redirects {check-decoded-url} + +filter {refresh-tags} + +filter {img-reorder} + +filter {banners-by-size} + +filter {webbugs} + +filter {jumping-windows} + +filter {ie-exploits} + +hide-forwarded-for-headers + +hide-from-header {block} + +hide-referrer {forge} + +session-cookies-only + +set-image-blocker {pattern} / - { +block +handle-as-image } - /ads - - -Ooops, the "/adsl/" is matching "/ads" in our configuration! But we did not -want this at all! Now we see why we get the blank page. It is actually -triggering two different actions here, and the effects are aggregated so that -the URL is blocked, and Privoxy is told to treat the block as if it were an -image. But this is, of course, all wrong. We could now add a new action below -this (or better in our own user.action file) that explicitly un blocks ( " -{-block}") paths with "adsl" in them (remember, last match in the configuration -wins). There are various ways to handle such exceptions. Example: - - { -block } - /adsl - - -Now the page displays ;-) Remember to flush your browser's caches when making -these kinds of changes to your configuration to insure that you get a freshly -delivered page! 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 helpful 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 of default.action 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 } - # Disable ALL filter actions for sites in this section - .forbes.com - developer.ibm.com - localhost - - -This would turn off all filtering for these sites. This is best put in -user.action, for local site exceptions. Note that when a simple domain pattern -is used by itself (without the subsequent path portion), all sub-pages within -that domain are included automatically in the scope of the action. - -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 that are the most likely -to cause trouble. This can be used as a last resort for problem sites. - - { fragile } - # Handle with care: easy to break - mail.google. - mybank.example.com - - -Remember to flush caches! Note that the mail.google reference lacks the TLD -portion (e.g. ".com"). This will effectively match any TLD with google in it, -such as mail.google.de., just as an example. - -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. - + { -session-cookies-only } + .google.com + + { -fast-redirects } + .google.com + + In file: user.action [ View ] [ Edit ] + (no matches in this file) + + This is telling us how we have defined our "actions", and which ones match + for our test case, "google.com". Displayed is all the actions that are + available to us. Remember, the + sign denotes "on". - denotes "off". So + some are "on" here, but many are "off". Each example we try may provide a + slightly different end result, depending on our configuration directives. + + The first listing is for 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 -- " / ". + + But we have defined additional actions that would be exceptions to these + general rules, and then we 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, at least that + is how it is in this example. 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" or + "mail.google.com". But it would not match "www.google.de"! So, apparently, + we have these two actions defined as exceptions to the general rules at + the top 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. So there is nothing + google-specific that we might have added to our own, local configuration. + If there was, those actions would over-rule any actions from previously + processed files, such as default.action. user.action typically has the + last word. This is the best place to put hard and fast exceptions, + + And finally we pull it all together in the bottom section and summarize + how Privoxy is applying all its "actions" to "google.com": + + Final results: + + -add-header + -block + -client-header-filter{hide-tor-exit-notation} + -content-type-overwrite + -crunch-client-header + -crunch-if-none-match + -crunch-incoming-cookies + -crunch-outgoing-cookies + -crunch-server-header + +deanimate-gifs {last} + -downgrade-http-version + -fast-redirects + -filter {js-events} + -filter {content-cookies} + -filter {all-popups} + -filter {banners-by-link} + -filter {tiny-textforms} + -filter {frameset-borders} + -filter {demoronizer} + -filter {shockwave-flash} + -filter {quicktime-kioskmode} + -filter {fun} + -filter {crude-parental} + -filter {site-specifics} + -filter {js-annoyances} + -filter {html-annoyances} + +filter {refresh-tags} + -filter {unsolicited-popups} + +filter {img-reorder} + +filter {banners-by-size} + +filter {webbugs} + +filter {jumping-windows} + +filter {ie-exploits} + -filter {google} + -filter {yahoo} + -filter {msn} + -filter {blogspot} + -filter {no-ping} + -force-text-mode + -handle-as-empty-document + -handle-as-image + -hide-accept-language + -hide-content-disposition + +hide-forwarded-for-headers + +hide-from-header {block} + -hide-if-modified-since + +hide-referrer {forge} + -hide-user-agent + -inspect-jpegs + -kill-popups + -limit-connect + -overwrite-last-modified + -prevent-compression + -redirect + -send-vanilla-wafer + -send-wafer + -server-header-filter{xml-to-html} + -server-header-filter{html-to-xml} + -session-cookies-only + +set-image-blocker {pattern} + -treat-forbidden-connects-like-blocks + + Notice the only difference here to the previous listing, is to + "fast-redirects" and "session-cookies-only", which are activated + specifically for this site in our configuration, and thus show in the + "Final Results". + + Now another example, "ad.doubleclick.net": + + { +block } + ad*. + + { +block } + .ad. + + { +block +handle-as-image } + .[a-vx-z]*.doubleclick.net + + We'll just show the interesting part here - the explicit matches. It is + matched three different times. Two "+block" sections, and a "+block + +handle-as-image", which is the expanded form of one of our aliases that + had been defined as: "+block-as-image". ("Aliases" are defined in the + first section of the actions file and typically used to combine more than + one action.) + + Any one of these would have done the trick and blocked this as an unwanted + image. This is unnecessarily redundant since the last case effectively + would also cover the first. No point in taking chances with these guys + though ;-) Note that if you want an ad or obnoxious URL to be invisible, + it should be defined as "ad.doubleclick.net" is done here -- as both a + "+block" and an "+handle-as-image". The custom alias "+block-as-image" + just simplifies the process and make it more readable. + + One last example. Let's try "http://www.example.net/adsl/HOWTO/". This one + is giving us problems. We are getting a blank page. Hmmm ... + + Matches for http://www.example.net/adsl/HOWTO/: + + In file: default.action [ View ] [ Edit ] + + {-add-header + -block + -client-header-filter{hide-tor-exit-notation} + -content-type-overwrite + -crunch-client-header + -crunch-if-none-match + -crunch-incoming-cookies + -crunch-outgoing-cookies + -crunch-server-header + +deanimate-gifs + -downgrade-http-version + +fast-redirects {check-decoded-url} + -filter {js-events} + -filter {content-cookies} + -filter {all-popups} + -filter {banners-by-link} + -filter {tiny-textforms} + -filter {frameset-borders} + -filter {demoronizer} + -filter {shockwave-flash} + -filter {quicktime-kioskmode} + -filter {fun} + -filter {crude-parental} + -filter {site-specifics} + -filter {js-annoyances} + -filter {html-annoyances} + +filter {refresh-tags} + -filter {unsolicited-popups} + +filter {img-reorder} + +filter {banners-by-size} + +filter {webbugs} + +filter {jumping-windows} + +filter {ie-exploits} + -filter {google} + -filter {yahoo} + -filter {msn} + -filter {blogspot} + -filter {no-ping} + -force-text-mode + -handle-as-empty-document + -handle-as-image + -hide-accept-language + -hide-content-disposition + +hide-forwarded-for-headers + +hide-from-header{block} + +hide-referer{forge} + -hide-user-agent + -inspect-jpegs + -kill-popups + -overwrite-last-modified + +prevent-compression + -redirect + -send-vanilla-wafer + -send-wafer + -server-header-filter{xml-to-html} + -server-header-filter{html-to-xml} + +session-cookies-only + +set-image-blocker{blank} + -treat-forbidden-connects-like-blocks } + / + + { +block +handle-as-image } + /ads + + Ooops, the "/adsl/" is matching "/ads" in our configuration! But we did + not want this at all! Now we see why we get the blank page. It is actually + triggering two different actions here, and the effects are aggregated so + that the URL is blocked, and Privoxy is told to treat the block as if it + were an image. But this is, of course, all wrong. We could now add a new + action below this (or better in our own user.action file) that explicitly + un blocks ( "{-block}") paths with "adsl" in them (remember, last match in + the configuration wins). There are various ways to handle such exceptions. + Example: + + { -block } + /adsl + + Now the page displays ;-) Remember to flush your browser's caches when + making these kinds of changes to your configuration to insure that you get + a freshly delivered page! 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 helpful 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 of default.action 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 } + # Disable ALL filter actions for sites in this section + .forbes.com + developer.ibm.com + localhost + + This would turn off all filtering for these sites. This is best put in + user.action, for local site exceptions. Note that when a simple domain + pattern is used by itself (without the subsequent path portion), all + sub-pages within that domain are included automatically in the scope of + the action. + + 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 that are the most + likely to cause trouble. This can be used as a last resort for problem + sites. + + { fragile } + # Handle with care: easy to break + mail.google. + mybank.example.com + + Remember to flush caches! Note that the mail.google reference lacks the + TLD portion (e.g. ".com"). This will effectively match any TLD with google + in it, such as mail.google.de., just as an example. + + 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. diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index e6c8476c..0d19acb3 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -17,7 +17,10 @@ TITLE="Testing Guidelines" HREF="testing.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" @@ -2333,7 +2336,7 @@ WIDTH="100%" ><TD ><PRE CLASS="PROGRAMLISTING" ->const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $"; +>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.16 2008/01/19 17:52:38 hal9 Exp $"; /********************************************************************* * * File : $Source$ @@ -2421,7 +2424,7 @@ WIDTH="100%" CLASS="PROGRAMLISTING" >#ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.16 2008/01/19 17:52:38 hal9 Exp $" /********************************************************************* * * File : $Source$ diff --git a/doc/webserver/developer-manual/contact.html b/doc/webserver/developer-manual/contact.html index bca0e3c2..409719b6 100644 --- a/doc/webserver/developer-manual/contact.html +++ b/doc/webserver/developer-manual/contact.html @@ -17,7 +17,10 @@ TITLE="Privoxy Copyright, License and History" HREF="copyright.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/copyright.html b/doc/webserver/developer-manual/copyright.html index e8a604be..30264dfa 100644 --- a/doc/webserver/developer-manual/copyright.html +++ b/doc/webserver/developer-manual/copyright.html @@ -17,7 +17,10 @@ TITLE="See also" HREF="seealso.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/cvs.html b/doc/webserver/developer-manual/cvs.html index 051495d3..30f3f694 100644 --- a/doc/webserver/developer-manual/cvs.html +++ b/doc/webserver/developer-manual/cvs.html @@ -17,7 +17,10 @@ TITLE="Documentation Guidelines" HREF="documentation.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/documentation.html b/doc/webserver/developer-manual/documentation.html index 944aeb35..8f31f16e 100644 --- a/doc/webserver/developer-manual/documentation.html +++ b/doc/webserver/developer-manual/documentation.html @@ -17,7 +17,10 @@ TITLE="Coding Guidelines" HREF="coding.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/index.html b/doc/webserver/developer-manual/index.html index dec4622c..cf7283ed 100644 --- a/doc/webserver/developer-manual/index.html +++ b/doc/webserver/developer-manual/index.html @@ -11,7 +11,10 @@ TITLE="Introduction" HREF="introduction.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="ARTICLE" BGCOLOR="#EEEEEE" @@ -48,7 +51,7 @@ TARGET="_top" <BR></P ><P CLASS="PUBDATE" ->$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $<BR></P +>$Id: developer-manual.sgml,v 2.16 2008/01/19 17:52:38 hal9 Exp $<BR></P ><DIV ><DIV CLASS="ABSTRACT" diff --git a/doc/webserver/developer-manual/introduction.html b/doc/webserver/developer-manual/introduction.html index 96049cd2..3a7a6952 100644 --- a/doc/webserver/developer-manual/introduction.html +++ b/doc/webserver/developer-manual/introduction.html @@ -17,7 +17,10 @@ TITLE="The CVS Repository" HREF="cvs.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/newrelease.html b/doc/webserver/developer-manual/newrelease.html index 62dd5160..5b62242d 100644 --- a/doc/webserver/developer-manual/newrelease.html +++ b/doc/webserver/developer-manual/newrelease.html @@ -17,7 +17,10 @@ TITLE="Update the Webserver" HREF="webserver-update.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/seealso.html b/doc/webserver/developer-manual/seealso.html index 58af85bf..5c85fc83 100644 --- a/doc/webserver/developer-manual/seealso.html +++ b/doc/webserver/developer-manual/seealso.html @@ -14,7 +14,10 @@ TITLE="Privoxy Copyright, License and History" HREF="copyright.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/testing.html b/doc/webserver/developer-manual/testing.html index d831f77e..cf2ba01c 100644 --- a/doc/webserver/developer-manual/testing.html +++ b/doc/webserver/developer-manual/testing.html @@ -17,7 +17,10 @@ TITLE="Releasing a New Version" HREF="newrelease.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/developer-manual/webserver-update.html b/doc/webserver/developer-manual/webserver-update.html index e435f116..b54d6462 100644 --- a/doc/webserver/developer-manual/webserver-update.html +++ b/doc/webserver/developer-manual/webserver-update.html @@ -17,7 +17,10 @@ TITLE="Contacting the developers, Bug Reporting and Feature Requests" HREF="contact.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/configuration.html b/doc/webserver/faq/configuration.html index e4d36f08..85782404 100644 --- a/doc/webserver/faq/configuration.html +++ b/doc/webserver/faq/configuration.html @@ -17,7 +17,10 @@ TITLE="Miscellaneous" HREF="misc.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/contact.html b/doc/webserver/faq/contact.html index a6aee947..48afd19c 100644 --- a/doc/webserver/faq/contact.html +++ b/doc/webserver/faq/contact.html @@ -17,7 +17,10 @@ TITLE="Privoxy Copyright, License and History" HREF="copyright.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/copyright.html b/doc/webserver/faq/copyright.html index 83dc0ad1..610fd031 100644 --- a/doc/webserver/faq/copyright.html +++ b/doc/webserver/faq/copyright.html @@ -14,7 +14,10 @@ TITLE="Contacting the developers, Bug Reporting and Feature Requests" HREF="contact.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/general.html b/doc/webserver/faq/general.html index 236ca940..fd258f5b 100644 --- a/doc/webserver/faq/general.html +++ b/doc/webserver/faq/general.html @@ -17,7 +17,10 @@ TITLE="Installation" HREF="installation.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/index.html b/doc/webserver/faq/index.html index 0df847ec..698b361b 100644 --- a/doc/webserver/faq/index.html +++ b/doc/webserver/faq/index.html @@ -11,7 +11,10 @@ TITLE="General Information" HREF="general.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="ARTICLE" BGCOLOR="#EEEEEE" @@ -45,7 +48,7 @@ TARGET="_top" ><BR></P ><P CLASS="PUBDATE" ->$Id: faq.sgml,v 2.37 2008/01/19 15:03:05 hal9 Exp $<BR></P +>$Id: faq.sgml,v 2.38 2008/01/19 17:52:39 hal9 Exp $<BR></P ><DIV ><DIV CLASS="ABSTRACT" diff --git a/doc/webserver/faq/installation.html b/doc/webserver/faq/installation.html index 5c9d32b7..8135379a 100644 --- a/doc/webserver/faq/installation.html +++ b/doc/webserver/faq/installation.html @@ -17,7 +17,10 @@ TITLE="Configuration" HREF="configuration.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/misc.html b/doc/webserver/faq/misc.html index 8c33e68b..b6496d1a 100644 --- a/doc/webserver/faq/misc.html +++ b/doc/webserver/faq/misc.html @@ -17,7 +17,10 @@ TITLE="Troubleshooting" HREF="trouble.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/faq/trouble.html b/doc/webserver/faq/trouble.html index eb611a5d..248a5901 100644 --- a/doc/webserver/faq/trouble.html +++ b/doc/webserver/faq/trouble.html @@ -17,7 +17,10 @@ TITLE="Contacting the developers, Bug Reporting and Feature Requests" HREF="contact.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"></HEAD +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#EEEEEE" diff --git a/doc/webserver/index.html b/doc/webserver/index.html index 4fed2c5d..6ae70273 100644 --- a/doc/webserver/index.html +++ b/doc/webserver/index.html @@ -54,7 +54,10 @@ NAME="KEYWORD" CONTENT="junkbuster"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="p_doc.css"> +HREF="p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <meta name="description" content="Privoxy helps consumers reduce unwanted junk email and protect their privacy from direct marketing companies."> <meta name="MSSmartTagsPreventParsing" content="TRUE"></HEAD ><BODY diff --git a/doc/webserver/privoxy-index.html b/doc/webserver/privoxy-index.html index 607d0e30..c564c7d7 100644 --- a/doc/webserver/privoxy-index.html +++ b/doc/webserver/privoxy-index.html @@ -54,7 +54,10 @@ NAME="KEYWORD" CONTENT="junkbuster"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="p_doc.css"> +HREF="p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <meta name="description" content="Privoxy helps consumers reduce unwanted junk email and protect their privacy from direct marketing companies."> <meta name="MSSmartTagsPreventParsing" content="TRUE"></HEAD ><BODY diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index da2f0797..52b7fe1e 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -17,7 +17,10 @@ TITLE="Filter Files" HREF="filter-file.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/appendix.html b/doc/webserver/user-manual/appendix.html index 8617400f..0d819ae8 100644 --- a/doc/webserver/user-manual/appendix.html +++ b/doc/webserver/user-manual/appendix.html @@ -14,7 +14,10 @@ TITLE="See Also" HREF="seealso.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/config.html b/doc/webserver/user-manual/config.html index 88e628f8..6e72817e 100644 --- a/doc/webserver/user-manual/config.html +++ b/doc/webserver/user-manual/config.html @@ -17,7 +17,10 @@ TITLE="Actions Files" HREF="actions-file.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/configuration.html b/doc/webserver/user-manual/configuration.html index 1fae582e..725fd169 100644 --- a/doc/webserver/user-manual/configuration.html +++ b/doc/webserver/user-manual/configuration.html @@ -17,7 +17,10 @@ TITLE="The Main Configuration File" HREF="config.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/contact.html b/doc/webserver/user-manual/contact.html index 72d621f3..da99a598 100644 --- a/doc/webserver/user-manual/contact.html +++ b/doc/webserver/user-manual/contact.html @@ -18,7 +18,10 @@ TITLE="Privoxy Copyright, License and History" HREF="copyright.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/copyright.html b/doc/webserver/user-manual/copyright.html index eb6ae38a..73bfcd79 100644 --- a/doc/webserver/user-manual/copyright.html +++ b/doc/webserver/user-manual/copyright.html @@ -18,7 +18,10 @@ TITLE="See Also" HREF="seealso.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/filter-file.html b/doc/webserver/user-manual/filter-file.html index 315f6a19..63a0bd2a 100644 --- a/doc/webserver/user-manual/filter-file.html +++ b/doc/webserver/user-manual/filter-file.html @@ -17,7 +17,10 @@ TITLE="Privoxy's Template Files" HREF="templates.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/index.html b/doc/webserver/user-manual/index.html index 79325812..ddd73176 100644 --- a/doc/webserver/user-manual/index.html +++ b/doc/webserver/user-manual/index.html @@ -11,7 +11,10 @@ TITLE="Introduction" HREF="introduction.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY @@ -47,7 +50,7 @@ TARGET="_top" ><BR></P ><P CLASS="PUBDATE" ->$Id: user-manual.sgml,v 2.53 2008/01/19 15:03:05 hal9 Exp $<BR></P +>$Id: user-manual.sgml,v 2.55 2008/01/19 21:26:37 hal9 Exp $<BR></P ><DIV ><DIV CLASS="ABSTRACT" diff --git a/doc/webserver/user-manual/installation.html b/doc/webserver/user-manual/installation.html index 77017cc2..f1e22972 100644 --- a/doc/webserver/user-manual/installation.html +++ b/doc/webserver/user-manual/installation.html @@ -17,7 +17,10 @@ TITLE="What's New in this Release" HREF="whatsnew.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/introduction.html b/doc/webserver/user-manual/introduction.html index 8aef2df7..fcdf7b29 100644 --- a/doc/webserver/user-manual/introduction.html +++ b/doc/webserver/user-manual/introduction.html @@ -17,7 +17,10 @@ TITLE="Installation" HREF="installation.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/quickstart.html b/doc/webserver/user-manual/quickstart.html index 75c3a338..27ff4d32 100644 --- a/doc/webserver/user-manual/quickstart.html +++ b/doc/webserver/user-manual/quickstart.html @@ -17,7 +17,10 @@ TITLE="Starting Privoxy" HREF="startup.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/seealso.html b/doc/webserver/user-manual/seealso.html index a32da106..ed2eee21 100644 --- a/doc/webserver/user-manual/seealso.html +++ b/doc/webserver/user-manual/seealso.html @@ -17,7 +17,10 @@ TITLE="Appendix" HREF="appendix.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/startup.html b/doc/webserver/user-manual/startup.html index 7e706cd7..265ffc91 100644 --- a/doc/webserver/user-manual/startup.html +++ b/doc/webserver/user-manual/startup.html @@ -17,7 +17,10 @@ TITLE="Privoxy Configuration" HREF="configuration.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY @@ -206,7 +209,7 @@ CLASS="GUIBUTTON" ><P > For <SPAN CLASS="APPLICATION" ->Internet Explorer v.5-6</SPAN +>Internet Explorer v.5-7</SPAN >: </P ><P CLASS="LITERALLAYOUT" diff --git a/doc/webserver/user-manual/templates.html b/doc/webserver/user-manual/templates.html index 5536ce07..4e960004 100644 --- a/doc/webserver/user-manual/templates.html +++ b/doc/webserver/user-manual/templates.html @@ -18,7 +18,10 @@ Requests" HREF="contact.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/doc/webserver/user-manual/whatsnew.html b/doc/webserver/user-manual/whatsnew.html index 40c64b7f..d07ea3f8 100644 --- a/doc/webserver/user-manual/whatsnew.html +++ b/doc/webserver/user-manual/whatsnew.html @@ -17,7 +17,10 @@ TITLE="Quickstart to Using Privoxy" HREF="quickstart.html"><LINK REL="STYLESHEET" TYPE="text/css" -HREF="../p_doc.css"> +HREF="../p_doc.css"><META +HTTP-EQUIV="Content-Type" +CONTENT="text/html; +charset=ISO-8859-1"> <LINK REL="STYLESHEET" TYPE="text/css" HREF="p_doc.css"> </head ><BODY diff --git a/privoxy.1 b/privoxy.1 index 6fe756af..6081581c 100644 --- a/privoxy.1 +++ b/privoxy.1 @@ -320,7 +320,7 @@ the \fBPrivoxy\fR developer manual. .SH "COPYRIGHT AND LICENSE" .SS "COPYRIGHT" .PP -Copyright (C) 2001-2007 by Privoxy Developers <ijbswa-developers@lists.sourceforge.net> +Copyright (C) 2001-2008 by Privoxy Developers <ijbswa-developers@lists.sourceforge.net> .PP Some source code is based on code Copyright (C) 1997 by Anonymous Coders and Junkbusters, Inc. and licensed under the \fIGNU General Public -- 2.39.2