Privoxy Developer Manual
-
By: Privoxy Developers
-$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $
-
+$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $
The developer manual gives the users information on how to help the developer
team. It provides guidance on coding, testing, documentation and other issues.
networks.
Privoxy is based on the code of the Internet Junkbuster (tm). Junkbuster was
-originally written by JunkBusters Corporation, and was released as free
+originally written by Junkbusters Corporation, and was released as free
open-source software under the GNU GPL. Stefan Waldherr made many improvements,
and started the SourceForge project to continue development.
developers.
-------------------------------------------------------------------------------
+
Table of Contents
-
+
1. Introduction
3. Quickstart to Privoxy Development
4. Documentation Guidelines
+
4.1. Quickstart to Docbook and SGML
- 1
-
-
4.2. Privoxy Documentation Style
4.3. Privoxy Custom Entities
-
5. Coding Guidelines
+
5.1. Introduction
5.2. Using Comments
+
5.2.1. Comment, Comment, Comment
5.2.2. Use blocks for comments
5.2.3. Keep Comments on their own line
5.2.6. Comment at the end of braces if the content is more than one
screen length
-
5.3. Naming Conventions
+
5.3.1. Variable Names
5.3.2. Function Names
5.3.3. Header file prototypes
5.3.4. Enumerations, and #defines
5.3.5. Constants
-
5.4. Using Space
+
5.4.1. Put braces on a line by themselves.
5.4.2. ALL control statements should have a block
5.4.3. Do not belabor/blow-up boolean expressions
5.4.6. Make the last brace of a function stand out
5.4.7. Use 3 character indentions
-
5.5. Initializing
- 5.5.1. Initialize all variables
+ 5.5.1. Initialize all variables
5.6. Functions
+
5.6.1. Name functions that return a boolean as a question.
5.6.2. Always specify a return type for a function.
5.6.3. Minimize function calls when iterating by using variables
5.6.9. Where Possible, Use Forward Struct Declaration Instead of
Includes
-
5.7. General Coding Practices
+
5.7.1. Turn on warnings
5.7.2. Provide a default case for all switch statements
5.7.3. Try to avoid falling through cases in a switch statement.
5.7.9. Add loaders to the `file_list' structure and in order
5.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME
-
5.8. Addendum: Template for files and function comment blocks:
-
6. Version Control Guidelines
7. Testing Guidelines
+
7.1. Testplan for releases
7.2. Test reports
-
8. Releasing a new version
+
8.1. Before the Release
8.2. Update the webserver
8.3. SuSE or Red Hat
8.12. Amiga OS
8.13. AIX
-
9. Contacting the developers, Bug Reporting and Feature Requests
10. Copyright and History
+
10.1. Copyright
10.2. History
-
11. See also
-
-------------------------------------------------------------------------------
+
1. Introduction
Privoxy, as an heir to Junkbuster, is an Open Source project and licensed under
One does not have to be a programmer to contribute. Packaging, testing, and
porting, are all important jobs as well.
+
-------------------------------------------------------------------------------
3. Quickstart to Privoxy Development
5. A major redesign of some part of the code: ask the list
-
-------------------------------------------------------------------------------
+
4. Documentation Guidelines
All formal documents are maintained in docbook SGML and located in the doc/
-source directory. You will need docbook and the docbook 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, is also now
-maintained as SGML. The README in the top-level source directory is a generated
-file. DO NOT edit this directly. Edit the SGML source!
-
-Other, less formal documents (e.g. AUTHORS, LICENSE) are maintained as plain
+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 privoxy.1 (man page) files are also now maintained as Docbook
+SGML. The finished files are all in the top-level source directory are
+generated files! Also, index.html, the Privoxy home page, is maintained as
+SGML. DO NOT edit these directly. Edit the SGML source, or contact someone
+involved in the documentation (at present Stefan and Hal).
+
+Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as plain
text files in the toplevel source directory. At least for the time being.
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. Or
-HTML versions can be downloaded from the www.privoxy.org website, which should
-be fairly current. (This is only a temporary solution.)
+ability to build the docs locally, text versions of each are kept in CVS. HTML
+versions are also now being kept in CVS under doc/webserver/*.
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.
+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.
2. Run make webserver which copies all files from doc/webserver to the
sourceforge webserver via scp.
-
-------------------------------------------------------------------------------
-4.1. Quickstart to Docbook and SGML
-If you are not familiar with SGML, it is a markup language similar to HTML. In
-fact, HTML is an SGML application. Both use "tags" to format text and other
-content. SGML tags are 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.
+4.1. Quickstart to Docbook and SGML
-Tags in SGML need to be always "closed". If not, you will likely generate
-errors. Example: <title>My Title</title>. They are also case-insensitive, but
-we strongly suggest using all lower case. This keeps compatibility with
-[Docbook] XML.
+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</title>. They are also
+case-insensitive, but we strongly suggest using all lower case. This keeps
+compatibility with [Docbook] XML.
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
Some common elements that you likely will use:
<para></para>, paragraph delimiter. Most text needs to be within paragraph
-elements.
-<emphasis></emphasis>, stylesheets make this italics.
+elements (there are some exceptions).
+<emphasis></emphasis>, the stylesheets make this italics.
<filename></filename>, files and directories.
<command></command>, command examples.
<literallayout></literllayout>, like <pre>, more or less.
<quote></quote>, for, doh, quoting text.
Look at any of the existing docs for examples of all these and more.
+
-------------------------------------------------------------------------------
4.2. Privoxy Documentation Style
Here it is:
- * All tags should be lower case.
+ * All tags should be lower case.
+
+ * Tags delimiting a block of text (even small blocks) should be on their own
+ line. Like:
- * Tags delimiting a block of text should be on their own line. Like:
+ <para>
+ Some text goes here.
+ </para>
+
- <para>
- Some text goes here.
- </para>
-
Tags marking individual words, or few words, should be in-line:
- Just to <emphasis>emphasize</emphasis>, some text goes here.
-
+ Just to <emphasis>emphasize</emphasis>, some text goes here.
+
+
+ * Tags should be nested and step indented for block text like: (except
+ in-line tags)
- * Tags should be nested and step indented like:
+ <para>
+ <itemizedlist>
+ <para>
+ <listitem>
+ Some text goes here in our list example.
+ </listitem>
+ </para>
+ </itemizedlist>
+ </para>
+
- <para>
- <itemizedlist>
- <para>
- <listitem>
- Some text goes here in our list example.
- </listitem>
- </para>
- </itemizedlist>
- </para>
-
This makes it easier to find the text amongst the tags ;-)
- * Use white space to separate logical divisions within a document, like
+
+ * 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.
- * Do not hesitate to make comments. Comments can either use the <comment>
- element, or the <!-- --> style comment familiar from HTML.
+ * 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>.)
- * We have an international audience. Refrain from slang, or English
+ * We have an international audience. Refrain from slang, or English
idiosyncrasies (too many to list :).
- * Try to keep overall line lengths in source files to 80 characters or less
+ * Try to keep overall line lengths in source files to 80 characters or less
for obvious reasons. This is not always possible, with lenghty URLs for
instance.
- * Our documents are available in differing formats. Right now, they are just
+ * Our documents are available in differing formats. Right now, they are just
plain text, and HTML, but PDF, and others is always a future possibility.
Be careful with URLs (<ulink>), and avoid this mistake:
My favorite site is <ulink url="http://example.com">example.com</ulink>.
- * All documents should be spell checked occasionally. aspell can check SGML
+ * All documents should be spell checked occasionally. aspell can check SGML
with the -H option. (ispell I think too.)
-
-------------------------------------------------------------------------------
+
4.3. Privoxy Custom Entities
Privoxy documentation is using a number of customized "entities" to facilitate
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. A sampling of custom entities are listed below.
-See any of the main docs for examples.
+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.
- * Re-cyclable "boilerplate" text entities are defined like:
+ * Re-cyclable "boilerplate" text entities are defined like:
<!entity supported SYSTEM "supported.sgml">
semi-colon), and the contents will be dumped into the finished doc at that
point.
- * Commonly used "internal entities":
+ * Commonly used "internal entities":
p-version: the Privoxy version string, e.g. "2.9.13".
p-status: the project status, either "ALPHA", "BETA", or "STABLE".
p-stable: just the opposite.
p-text: this doc is only generated as text.
-
-
There are others in various places that are defined for a specific purpose.
Read the source!
+
-------------------------------------------------------------------------------
5. Coding Guidelines
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. ;->
+
-------------------------------------------------------------------------------
5.2. Using Comments
programming error is occurring.
Example:
+
/* if page size greater than 1k ... */
if ( PageLength() > 1024 )
{
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.
+
-------------------------------------------------------------------------------
5.2.2. Use blocks for comments
surrounding the code with a clear, definable pattern.
Example:
+
/*********************************************************************
* This will stand out clearly in your code!
*********************************************************************/
If you are trying to add a small logic comment and do not wish to "disrubt" the
flow of the code, feel free to use a 1 line comment which is NOT on the same
line as the code.
+
-------------------------------------------------------------------------------
5.2.3. Keep Comments on their own line
used to comment parameters.
Example:
+
/*********************************************************************
* This will stand out clearly in your code,
* But the second example won't.
...code here...
} /* -END- DoSomethingVeryImportant */
+
-------------------------------------------------------------------------------
5.2.4. Comment each logical step
Most "for", "while", "do", etc... loops _probably_ need a comment. After all,
these are usually major logic containers.
+
-------------------------------------------------------------------------------
5.2.5. Comment All Functions Thoroughly
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.
+
-------------------------------------------------------------------------------
5.2.6. Comment at the end of braces if the content is more than one screen
use following a closing brace: } /* -END- if() or while () or etc... */
Example:
+
if ( 1 == X )
{
DoSomethingVeryImportant();
DoSomethingVeryImportant();
...some long list of commands...
} /* -END- if ( 1 == X ) */
+
-------------------------------------------------------------------------------
5.3. Naming Conventions
port Privoxy to C++.
Example:
+
int ms_iis5_hack = 0;
Instead of:
int msiis5hack = 0; int msIis5Hack = 0;
+
-------------------------------------------------------------------------------
5.3.2. Function Names
port Privoxy to C++.
Example:
+
int load_some_file( struct client_state *csp )
Instead of:
int loadsomefile( struct client_state *csp )
int loadSomeFile( struct client_state *csp )
+
-------------------------------------------------------------------------------
5.3.3. Header file prototypes
the same parameter name in the header file that you use in the c file.
Example:
+
(.h) extern int load_aclfile( struct client_state *csp );
(.c) int load_aclfile( struct client_state *csp )
Instead of:
+
(.h) extern int load_aclfile( struct client_state * ); or
(.h) extern int load_aclfile();
(.c) int load_aclfile( struct client_state *csp )
+
-------------------------------------------------------------------------------
5.3.4. Enumerations, and #defines
and system headers.)
Example:
+
(enumeration) : enum Boolean { FALSE, TRUE };
(#define) : #define DEFAULT_SIZE 100;
description.
Example:
+
#define FEATURE_FORCE 1
#ifdef FEATURE_FORCE
#define FORCE_PREFIX blah
#endif /* def FEATURE_FORCE */
+
-------------------------------------------------------------------------------
5.3.5. Constants
terminate a name with an underscore.
Example:
+
#define USE_IMAGE_LIST 1
Instead of:
#define USE_IMAGE_LIST_ 1 or
#define use_image_list 1 or
#define UseImageList 1
+
-------------------------------------------------------------------------------
5.4. Using Space
block.
Example:
+
if ( this == that )
{
...
Status: developer-discrection.
Example exception:
+
while ( more lines are read )
{
/* Please document what is/is not a comment line here */
do_something( line );
}
+
-------------------------------------------------------------------------------
5.4.2. ALL control statements should have a block
to error. All control statements should have a block defined.
Example:
+
if ( this == that )
{
DoSomething();
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.
+
-------------------------------------------------------------------------------
5.4.3. Do not belabor/blow-up boolean expressions
Example:
+
structure->flag = ( condition );
Instead of:
Note: The former is readable and consice. 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-)
+
-------------------------------------------------------------------------------
5.4.4. Use white space freely because it is free
in the next guideline.
Example:
+
int firstValue = 0;
int someValue = 0;
int anotherValue = 0;
if ( thisVariable == thatVariable )
firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
+
-------------------------------------------------------------------------------
5.4.5. Don't use white space around structure operators
variable/function name is not as clear.
Example:
+
aStruct->aMember;
aStruct.aMember;
FunctionName();
Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
+
-------------------------------------------------------------------------------
5.4.6. Make the last brace of a function stand out
Example:
+
int function1( ... )
{
...code...
Status: developer-discrection on the number of blank lines. Enforced is the end
of function comments.
+
-------------------------------------------------------------------------------
5.4.7. Use 3 character indentions
your code through a filter such as "expand -t3" before checking in your code.
Example:
+
static const char * const url_code_map[256] =
{
NULL, ...
return( NEVER_GETS_HERE );
}
+
-------------------------------------------------------------------------------
5.5. Initializing
accidentally using an unassigned variable.
Example:
+
short anShort = 0;
float aFloat = 0;
struct *ptr = NULL;
Status: developer-discrection if and only if the variable is assigned a value
"shortly after" declaration.
+
-------------------------------------------------------------------------------
5.6. Functions
true or false statement
Example:
+
ShouldWeBlockThis();
ContainsAnImage();
IsWebPageBlank();
+
-------------------------------------------------------------------------------
5.6.2. Always specify a return type for a function.
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.
+
-------------------------------------------------------------------------------
5.6.3. Minimize function calls when iterating by using variables
the code is easy to understand:
Example:
+
for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
{
....
variable, and evaluate using the variable.
Example:
+
size_t len = blockListLength();
for ( size_t cnt = 0; cnt < len; cnt ++ )
Exceptions: if the value of blockListLength() *may* change or could *
potentially* change, then you must code the function call in the for/while
loop.
+
-------------------------------------------------------------------------------
5.6.4. Pass and Return by Const Reference
Both these pointers are *const*! If the c runtime library maintainers do it, we
should too.
+
-------------------------------------------------------------------------------
5.6.5. Pass and Return by Value
would not work. So, to be consistent, we should declare all prototypes with
"pass by value": int load_aclfile( struct client_state *csp )
+
-------------------------------------------------------------------------------
5.6.6. Names of include files
other header files.
Example:
+
#include <iostream.h> /* This is not a local include */
#include "config.h" /* This IS a local include */
Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
This duplicates the #include "file.h" behaviour.
+
-------------------------------------------------------------------------------
5.6.7. Provide multiple inclusion protection
to "_", and make it uppercase.
Example:
+
#ifndef PROJECT_H_INCLUDED
#define PROJECT_H_INCLUDED
...
#endif /* ndef PROJECT_H_INCLUDED */
+
-------------------------------------------------------------------------------
5.6.8. Use `extern "C"` when appropriate
of our code.
Example:
+
#ifdef __cplusplus
extern "C"
{
#ifdef __cplusplus
}
#endif /* def __cplusplus */
+
-------------------------------------------------------------------------------
5.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
excess header files may cause needless compiles.
Example:
+
/*********************************************************************
* We're avoiding an include statement here!
*********************************************************************/
however, the header file is unneccessary.
Status: Use with discrection.
+
-------------------------------------------------------------------------------
5.7. General Coding Practices
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.
+
-------------------------------------------------------------------------------
5.7.2. Provide a default case for all switch statements
statement.
Example:
+
switch( hash_string( cmd ) )
{
case hash_actions_file :
stream (as in load_config). Or it may really be an ABEND condition.
Status: Programmer discretion is advised.
+
-------------------------------------------------------------------------------
5.7.3. Try to avoid falling through cases 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.
+
-------------------------------------------------------------------------------
5.7.4. Use 'long' or 'short' Instead of 'int'
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?
+
-------------------------------------------------------------------------------
5.7.5. Don't mix size_t and other types
size_t against another variable of a different type (or even against a
constant) without casting one of the values. Try to avoid using size_t if you
can.
+
-------------------------------------------------------------------------------
5.7.6. Declare each variable and struct on its own line.
It can be tempting to declare a series of variables all on one line. Don't.
Example:
+
long a = 0;
long b = 0;
long c = 0;
good comment on their functions.
Status: developer-discrection.
+
-------------------------------------------------------------------------------
5.7.7. Use malloc/zalloc sparingly
the context of one function call.
Example:
+
If a function creates a struct and stores a pointer to it in a
list, then it should definately be allocated via `malloc'.
+
-------------------------------------------------------------------------------
5.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
function to accomodate this.
Example:
+
int load_re_filterfile( struct client_state *csp ) { ... }
static void unload_re_filterfile( void *f ) { ... }
Status: developer-discrection. The "main" use of this standard is for
allocating and freeing data structures (complex or nested).
+
-------------------------------------------------------------------------------
5.7.9. Add loaders to the `file_list' structure and in 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.
+
-------------------------------------------------------------------------------
5.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME
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 conversly exclude
from the project).
+
-------------------------------------------------------------------------------
5.8. Addendum: Template for files and function comment blocks:
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $";
+
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
code (via `forward-page' and `backward-page'). Please include it if you can.
Example for file header comments:
+
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
*/
Example for function comments:
+
/*********************************************************************
*
* Function : FUNCTION_NAME
Note: If we all follow this practice, we should be able to parse our code to
create a "self-documenting" web page.
+
-------------------------------------------------------------------------------
6. Version Control Guidelines
To be filled. note on cvs comments. Don't only comment what you did, but also
why you did it!
+
-------------------------------------------------------------------------------
7. Testing Guidelines
To be filled.
+
-------------------------------------------------------------------------------
7.1. Testplan for releases
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?
4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/
6. Remove the rpm. Any error messages? All files removed?
-
-------------------------------------------------------------------------------
+
7.2. Test reports
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
+ * Fill the Summary and Detailed Description with something intelligent (keep
it short and precise).
-
Do not mail to the mailinglist (we cannot keep track on issues there).
+
-------------------------------------------------------------------------------
8. Releasing a new version
The following programs are required to follow this process: ncftpput (ncftp),
scp (ssh), gmake (GNU's version of make), autoconf, cvs, ???.
+
-------------------------------------------------------------------------------
8.1. Before the Release
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
+ * 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.
- * Increment the version number in configure.in in CVS. Also, the RPM release
+ * Increment the version number in configure.in in CVS. Also, the RPM release
number in configure.in. Do NOT touch version information after export from
CVS. All packages will use the version and release data from configure.in.
Local files should not be changed, except prior to a CVS commit!!! This way
we are all on the same page!
- * If the default actionsfile has changed since last release, bump up its
+ * If the default actionsfile has changed since last release, bump up its
version info 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";'
- * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z" (where
+ * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z" (where
X = major, Y = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z
(won't work) etc.
- * The first package uploaded should be the official "tarball" release. This
+ * The first package uploaded should be the official "tarball" release. This
is built with the "make tarball-dist" Makefile target, and then can be
uploaded with "make tarball-upload" (see below).
-
-------------------------------------------------------------------------------
+
8.2. Update the webserver
All files must be group-readable and group-writable (or no one else will be
Please do NOT use any other means of transferring files to the webserver. "make
webserver" not only uploads, but will make sure that the appropriate
permissions are preserved for shared group access.
+
-------------------------------------------------------------------------------
8.3. SuSE or Red Hat
Go to the displayed URL and release the file publicly on Sourceforge.
+
-------------------------------------------------------------------------------
8.4. OS/2
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:
+
os2build
+
And in the ./files directory you will have the WarpIN-installable executable.
Upload this anonymously to uploads.sourceforge.net/incoming, create a release
for it, and you're done.
+
-------------------------------------------------------------------------------
8.5. Solaris
ssh cf.sourceforge.net
-Choose the right operating system (not the Debian one). If you have downloaded
+Choose the right operating system (not the Debian one). If you have downloaded
Privoxy before,
cd current
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.
+
-------------------------------------------------------------------------------
8.6. Windows
Then do FIXME.
+
-------------------------------------------------------------------------------
8.7. Debian
Then do FIXME.
+
-------------------------------------------------------------------------------
8.8. Mac OSX
From the osxsetup directory, run:
+
build
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
+
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.
+
-------------------------------------------------------------------------------
8.9. FreeBSD
Change the version number of Privoxy in the configure.in file. Run:
+
autoheader && autoconf && ./configure
+
Then ...
Login to Sourceforge's compilefarm via ssh:
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.
+
-------------------------------------------------------------------------------
8.10. Tarball
Goto the displayed URL and release the file publicly on Sourceforge.
+
-------------------------------------------------------------------------------
8.11. HP-UX 11
Then do FIXME.
+
-------------------------------------------------------------------------------
8.12. Amiga OS
Then do FIXME.
+
-------------------------------------------------------------------------------
8.13. AIX
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.
+
-------------------------------------------------------------------------------
9. Contacting the developers, Bug Reporting and Feature Requests
We value your feedback. However, to provide you with the best support, please
note:
- * Use the Sourceforge Support Forum to get help:
-
- http://sourceforge.net/tracker/?group_id=11118&atid=211118
-
+ * Use the Sourceforge Support Forum to get help:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=211118
+
- * Submit bugs only through our Sourceforge Bug Forum:
-
- http://sourceforge.net/tracker/?group_id=11118&atid=111118.
-
+ * Submit bugs only through our Sourceforge Bug Forum:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=111118.
+
Make sure that the bug has not already been submitted. Please try to verify
that it is a Privoxy bug, and not a browser or site bug first. If you are
platform, browser, any pertinent log data, any other relevant details
(please be specific) and, if possible, some way to reproduce the bug.
- * Submit feature requests only through our Sourceforge feature request
- forum:
-
- http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
-
+ * Submit feature requests only through our Sourceforge feature request
+ forum:
+
+ http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
+
- * We will soon have an automated way to submit advertisements, incorrectly
- blocked images, popups and the like. Check back.
-
+ * We will soon have an automated way to submit advertisements, incorrectly
+ blocked images, popups and the like. Check back.
+
- * For any other issues, feel free to use the mailing lists:
-
- http://sourceforge.net/mail/?group_id=11118.
-
+ * For any other issues, feel free to use the mailing lists:
+
+ http://sourceforge.net/mail/?group_id=11118.
+
Anyone interested in actively participating in development and related
discussions can also join the appropriate mailing list. Archives are
available too.
-
-------------------------------------------------------------------------------
+
10. Copyright and History
10.1. Copyright
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., 59 Temple
Place, Suite 330, Boston, MA 02111-1307 USA.
+
-------------------------------------------------------------------------------
10.2. History
Privoxy to rekindle development. There are now several active developers
contributing. The last stable release of Junkbuster was v2.0.2, which has now
grown whiskers ;-).
+
-------------------------------------------------------------------------------
11. See also
http://www.squid-cache.org/
+
Privoxy User Manual
-
By: Privoxy Developers
-$Id: user-manual.sgml,v 1.69 2002/04/06 05:07:29 hal9 Exp $
-
+$Id: user-manual.sgml,v 1.70 2002/04/08 20:53:56 swa Exp $
-The user manual gives users information on how to install, configure and use
+The user manual gives users information on how to install, configure and use
Privoxy.
Privoxy is a web proxy with advanced filtering capabilities for protecting
networks.
Privoxy is based on the code of the Internet Junkbuster (tm). Junkbuster was
-originally written by JunkBusters Corporation, and was released as free
+originally written by Junkbusters Corporation, and was released as free
open-source software under the GNU GPL. Stefan Waldherr made many improvements,
and started the SourceForge project to continue development.
user-manual/. Please see the Contact section on how to contact the developers.
-------------------------------------------------------------------------------
+
Table of Contents
-
+
1. Introduction
- 1.1. New Features
+ 1.1. New Features
3. Installation
+
3.1. Source
+
3.1.1. Red Hat
3.1.2. SuSE
3.1.3. OS/2
3.1.4. Windows
3.1.5. Other
-
-
-
4. Quickstart to Using Privoxy
- 4.1. Command Line Options
+ 4.1. Command Line Options
5. Privoxy Configuration
+
5.1. Controlling Privoxy with Your Web Browser
5.2. Configuration Files Overview
5.3. The Main Configuration File
+
5.3.1. Defining Other Configuration Files
5.3.2. Other Configuration Options
5.3.3. Access Control List (ACL)
5.3.4. Forwarding
5.3.5. Windows GUI Options
-
5.4. The Actions File
+
5.4.1. URL Domain and Path Syntax
5.4.2. Actions
5.4.3. Aliases
-
5.5. The Filter File
5.6. Templates
-
6. Contacting the Developers, Bug Reporting and Feature Requests
7. Copyright and History
+
7.1. Copyright
7.2. History
-
8. See Also
9. Appendix
+
9.1. Regular Expressions
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
-
-
9.2. Privoxy's Internal Pages
- 9.2.1. Bookmarklets
+ 9.2.1. Bookmarklets
9.3. Anatomy of an Action
-
-
-
-------------------------------------------------------------------------------
+
1. Introduction
-This documentation is included with the current BETA version of Privoxy,
-v.2.9.13, and is mostly complete at this point. The most up to date reference
+This documentation is included with the current beta version of Privoxy,
+v.2.9.14, and is mostly complete at this point. The most up to date reference
for the time being is still the comments in the source files and in the
individual configuration files. Development of version 3.0 is currently nearing
completion, and includes many significant changes and enhancements over earlier
versions. The target release date for stable v3.0 is "soon" ;-).
-Since this is a BETA version, not all new features are well tested. This
+Since this is a beta version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with CVS
sources). And there may be bugs, though hopefully not many!
+
-------------------------------------------------------------------------------
1.1. New Features
blocking and cookie management, Privoxy provides new features, some of them
currently under development:
- * Integrated browser based configuration and control utility (http://p.p).
+ * Integrated browser based configuration and control utility (http://p.p).
Browser-based tracing of rule and filter effects.
- * Blocking of annoying pop-up browser windows.
+ * Blocking of annoying pop-up browser windows.
- * HTTP/1.1 compliant (most, but not all 1.1 features are supported).
+ * HTTP/1.1 compliant (most, but not all 1.1 features are supported).
- * Support for Perl Compatible Regular Expressions in the configuration files,
+ * Support for Perl Compatible Regular Expressions in the configuration files,
and generally a more sophisticated and flexible configuration syntax over
previous versions.
- * GIF de-animation.
+ * GIF de-animation.
- * Web page content filtering (removes banners based on size, invisible
+ * Web page content filtering (removes banners based on size, invisible
"web-bugs", JavaScript, pop-ups, status bar abuse, etc.)
- * Bypass many click-tracking scripts (avoids script redirection).
+ * Bypass many click-tracking scripts (avoids script redirection).
- * Multi-threaded (POSIX and native threads).
+ * Multi-threaded (POSIX and native threads).
- * Auto-detection and re-reading of config file changes.
+ * Auto-detection and re-reading of config file changes.
- * User-customizable HTML templates (e.g. 404 error page).
+ * User-customizable HTML templates (e.g. 404 error page).
- * Improved cookie management features (e.g. session based cookies).
+ * Improved cookie management features (e.g. session based cookies).
- * Improved signal handling, and a true daemon mode (Unix).
+ * Improved signal handling, and a true daemon mode (Unix).
- * Builds from source on most UNIX-like systems. Packages available for: Linux
+ * Builds from source on most UNIX-like systems. Packages available for: Linux
(RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11
and AmigaOS.
- * In addition, the configuration is much more powerful and versatile
+ * In addition, the configuration is much more powerful and versatile
over-all.
-
-------------------------------------------------------------------------------
+
3. Installation
Privoxy is available as raw source code (tarball or via CVS), or pre-compiled
(RedHat, Suse, Debian), FreeBSD, and many flavors of Unix. There are source and
binary releases for these available for download at http://sourceforge.net/
project/showfiles.php?group_id=11118.
+
-------------------------------------------------------------------------------
3.1. Source
To build Privoxy from source, autoconf and GNU make (gmake) are required.
Source is available as gzipped tar archives. For this, first unpack the source:
- tar xzvf privoxy-2.9.13-beta-src* [.tgz or .tar.gz]
- cd privoxy-2.9.13-beta
+ tar xzvf privoxy-2.9.14-beta-src* [.tgz or .tar.gz]
+ cd privoxy-2.9.14-beta
For retrieving the current CVS sources, you'll need the CVS package installed
www.gnu.org).
For Redhat and SuSE Linux RPM packages, see below.
+
-------------------------------------------------------------------------------
3.1.1. Red Hat
This will create both binary and src RPMs in the usual places. Example:
- /usr/src/redhat/RPMS/i686/privoxy-2.9.13-1.i686.rpm
+ /usr/src/redhat/RPMS/i686/privoxy-2.9.14-1.i686.rpm
- /usr/src/redhat/SRPMS/privoxy-2.9.13-1.src.rpm
+ /usr/src/redhat/SRPMS/privoxy-2.9.14-1.src.rpm
To install, of course:
- rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.13-1.i686.rpm
+ rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.14-1.i686.rpm
This will place the Privoxy configuration files in /etc/privoxy/, and log files
in /var/log/privoxy/. Run ckconfig privoxy on to have Privoxy start
automatically during init.
+
-------------------------------------------------------------------------------
3.1.2. SuSE
This will create both binary and src RPMs in the usual places. Example:
- /usr/src/packages/RPMS/i686/privoxy-2.9.13-1.i686.rpm
+ /usr/src/packages/RPMS/i686/privoxy-2.9.14-1.i686.rpm
- /usr/src/packages/SRPMS/privoxy-2.9.13-1.src.rpm
+ /usr/src/packages/SRPMS/privoxy-2.9.14-1.src.rpm
To install, of course:
- rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.13-1.i686.rpm
+ rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.14-1.i686.rpm
This will place the Privoxy configuration files in /etc/privoxy/, and log files
in /var/log/privoxy/.
+
-------------------------------------------------------------------------------
3.1.3. OS/2
Privoxy is packaged in a WarpIN self- installing archive. The self-installing
program will be named depending on the release version, something like:
-privoxyos2_setup_2.9.13.exe. In order to install it, simply run this executable
+privoxyos2_setup_2.9.14.exe. In order to install it, simply run this executable
or double-click on its icon and follow the WarpIN installation panels. A shadow
of the Privoxy executable will be placed in your startup folder so it will
start automatically whenever OS/2 starts.
In addition to needing the source code distribution as outlined earlier, you
will want to extract the os2seutp directory from CVS:
+
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+
This will create a directory named os2setup/, which will contain the
Makefile.vac makefile and os2build.cmd which is used to completely create the
binary distribution. The sequence of events for building the executable for
yourself goes something like this:
+
cd current
autoheader
autoconf
cd ..\os2setup
nmake -f Makefile.vac
+
You will see this sequence laid out in os2build.cmd.
+
-------------------------------------------------------------------------------
3.1.4. Windows
Click-click. (I need help on this. Not a clue here. Also for configuration
section below. HB.)
+
-------------------------------------------------------------------------------
3.1.5. Other
For FreeBSD (and other *BSDs?), the build will require gmake instead of the
included make. gmake is available from http://www.gnu.org. The rest should be
the same as above for Linux/Unix.
+
-------------------------------------------------------------------------------
4. Quickstart to Using Privoxy
Privoxy is HTTP/1.1 compliant, but not all 1.1 features are as yet implemented.
If browsers that support HTTP/1.1 (like Mozilla or recent versions of I.E.)
experience problems, you might try to force HTTP/1.0 compatibility. For
-Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the
+Mozilla, look under Edit -> Preferences -> Debug -> Networking. Or set the
"+downgrade" config option in default.action.
After running Privoxy for a while, you can start to fine tune the configuration
In fact, various aspects of Privoxy configuration can be viewed from this page,
including current configuration parameters, source code version numbers, the
browser's request headers, and "actions" that apply to a given URL. In addition
-to the default.action file editor mentioned above, Privoxy can also be turned
+to the default.action file editor mentioned above, Privoxy can also be turned
"on" and "off" from this page.
-If you encounter problems, please verify it is a Privoxy bug, by disabling
+If you encounter problems, please verify it is a Privoxy bug, by disabling
Privoxy, and then trying the same page. Also, try another browser if possible
to eliminate browser or site problems. Before reporting it as a bug, see if
there is not a configuration option that is enabled that is causing the page
try adding it to the {fragile} section of default.action. This will turn off
most actions for this site. For more on troubleshooting problem sites, see the
Appendix. If a bug, please report it to the developers (see below).
+
-------------------------------------------------------------------------------
4.1. Command Line Options
Privoxy may be invoked with the following command-line options:
- * --version
+ * --version
Print version info and exit, Unix only.
- * --help
+ * --help
Print a short usage info and exit, Unix only.
- * --no-daemon
+ * --no-daemon
Don't become a daemon, i.e. don't fork and become process group leader,
don't detach from controlling tty. Unix only.
- * --pidfile FILE
+ * --pidfile FILE
On startup, write the process ID to FILE. Delete the FILE on exit. Failiure
to create or delete the FILE is non-fatal. If no FILE option is given, no
PID file will be used. Unix only.
- * --user USER[.GROUP]
+ * --user USER[.GROUP]
After (optionally) writing the PID file, assume the user ID of USER, and if
included the GID of GROUP. Exit if the privileges are not sufficient to do
so. Unix only.
- * configfile
+ * configfile
If no configfile is included on the command line, Privoxy will look for a
file named "config" in the current directory (except on Win32 where it will
look for "config.txt" instead). Specify full path to avoid confusion.
-
-------------------------------------------------------------------------------
+
5. Privoxy Configuration
All Privoxy configuration is stored in text files. These files can be edited
with a text editor. Many important aspects of Privoxy can also be controlled
easily with a web browser.
+
-------------------------------------------------------------------------------
5.1. Controlling Privoxy with Your Web Browser
-This should be self-explanatory. Note the last item is an editor for the
+This should be self-explanatory. Note the last item is an editor for the
"actions list", which is where much of the ad, banner, cookie, and URL blocking
magic is configured as well as other advanced features of Privoxy. This is an
easy way to adjust various aspects of Privoxy configuration. The actions file,
your current actions and filters, or just to test if a site misbehaves, whether
it is Privoxy causing the problem or not. Privoxy continues to run as a proxy
in this case, but all filtering is disabled.
+
-------------------------------------------------------------------------------
5.2. Configuration Files Overview
aggressive by some standards. For the time being, there are only three default
configuration files (this may change in time):
- * The main configuration file is named config on Linux, Unix, BSD, OS/2, and
+ * The main configuration file is named config on Linux, Unix, BSD, OS/2, and
AmigaOS and config.txt on Windows.
- * The default.action file is used to define various "actions" relating to
+ * The default.action file is used to define various "actions" relating to
images, banners, pop-ups, access restrictions, banners and cookies. There
is a CGI based editor for this file that can be accessed via http://p.p.
(Other actions files are included as well with differing levels of
filtering and blocking, e.g. basic.action.)
- * The default.filter file can be used to re-write the raw page content,
+ * The default.filter file can be used to re-write the raw page content,
including viewable text as well as embedded HTML and JavaScript, and
whatever else lurks on any given web page.
-
default.action and default.filter can use Perl style regular expressions for
maximum flexibility. All files use the "#" character to denote a comment. Such
lines are not processed by Privoxy. After making any changes, there is no need
below documentation may not be accurate by the time you read this. Also, what
constitutes a "default" setting, may change, so please check all your
configuration files on important issues.
+
-------------------------------------------------------------------------------
5.3. The Main Configuration File
followed by a list of values, all separated by whitespace (any number of spaces
or tabs). For example:
- blockfile blocklist.ini
-
+ blockfile blocklist.ini
+
Indicates that the blockfile is named "blocklist.ini". (A default installation
does not use this.)
character.
There are various aspects of Privoxy behavior that can be tuned.
+
-------------------------------------------------------------------------------
5.3.1. Defining Other Configuration Files
The location of the configuration files:
- confdir /etc/privoxy # No trailing /, please.
-
+ confdir /etc/privoxy # No trailing /, please.
+
The directory where all logging (i.e. logfile and jarfile) takes place. No
trailing "/", please:
- logdir /var/log/privoxy
-
+ logdir /var/log/privoxy
+
Note that all file specifications below are relative to the above two
directories!
file is explained in detail below. Other "actions" files are included, and you
are free to use any of them. They have varying degrees of aggressiveness.
- actionsfile default.action
-
+ actionsfile default.action
+
The "default.filter" file contains content modification rules that use "regular
expressions". These rules permit powerful changes on the content of Web pages,
e.g., you could disable your favorite JavaScript annoyances, re-write the
-actual displayed text, or just have some fun replacing "Microsoft" with
+actual displayed text, or just have some fun replacing "Microsoft" with
"MicroSuck" wherever it appears on a Web page. Default: whatever the developers
are playing with :-/
not incrementally displayed.) This effect will be more noticeable on slower
connections.
- filterfile default.filter
-
+ filterfile default.filter
+
The logfile is where all logging and error messages are written. The logfile
can be useful for tracking down a problem with Privoxy (e.g., it's not blocking
Default: Log to the a file named logfile. Comment out to disable logging.
- logfile logfile
-
+ logfile logfile
+
The "jarfile" defines where Privoxy stores the cookies it intercepts. Note that
if you use a "jarfile", it may grow quite large. Default: Don't store
intercepted cookies.
- #jarfile jarfile
-
+ #jarfile jarfile
+
If you specify a "trustfile", Privoxy will only allow access to sites that are
named in the trustfile. You can also mark sites as trusted referrers, with the
is a very restrictive feature that typical users most probably want to leave
disabled. Default: Disabled, don't use the trust mechanism.
- #trustfile trust
-
+ #trustfile trust
+
If you use the trust mechanism, it is a good idea to write up some on-line
documentation about your blocking policy and to specify the URL(s) here. They
untrusted content. Use multiple times for multiple URLs. Default: Don't display
links on the "untrusted" info page.
- trust-info-url http://www.example.com/why_we_block.html
- trust-info-url http://www.example.com/what_we_allow.html
-
+ trust-info-url http://www.example.com/why_we_block.html
+ trust-info-url http://www.example.com/what_we_allow.html
+
+
-------------------------------------------------------------------------------
5.3.2. Other Configuration Options
"Admin-address" should be set to the email address of the proxy administrator.
It is used in many of the proxy-generated pages. Default: fill@me.in.please.
- #admin-address fill@me.in.please
-
+ #admin-address fill@me.in.please
+
"Proxy-info-url" can be set to a URL that contains more info about this Privoxy
installation, it's configuration and policies. It is used in many of the
installations, since your users will want to know why certain content is
blocked or modified. Default: Don't show a link to on-line documentation.
- proxy-info-url http://www.example.com/proxy.html
-
+ proxy-info-url http://www.example.com/proxy.html
+
"Listen-address" specifies the address and port where Privoxy will listen for
connections from your Web browser. The default is to listen on the localhost
port 8118, and this is suitable for most users. (In your web browser, under
-proxy configuration, list the proxy server as "localhost" and the port as
+proxy configuration, list the proxy server as "localhost" and the port as
"8118").
If you already have another service running on port 8118, or if you want to
serve requests from other machines (e.g. on your local network) as well, you
-will need to override the default. The syntax is "listen-address [<ip-address
->]:<port>". If you leave out the IP address, Privoxy will bind to all
-interfaces (addresses) on your machine and may become reachable from the
-Internet. In that case, consider using access control lists (acl's) (see
+will need to override the default. The syntax is "listen-address
+[<ip-address>]:<port>". If you leave out the IP address, Privoxy will bind to
+all interfaces (addresses) on your machine and may become reachable from the
+Internet. In that case, consider using access control lists (acl's) (see
"aclfile" above), or a firewall.
For example, suppose you are running Privoxy on a machine which has the address
connection with a different address. You want it to serve requests from inside
only:
- listen-address 192.168.0.1:8118
-
+ listen-address 192.168.0.1:8118
+
If you want it to listen on all addresses (including the outside connection):
- listen-address :8118
-
+ listen-address :8118
+
If you do this, consider using ACLs (see "aclfile" above). Note: you will need
to point your browser(s) to the address and port that you have configured here.
because it will show you each request as it happens. Higher levels of debug are
probably only of interest to developers.
- debug 1 # GPC = show each GET/POST/CONNECT request
- debug 2 # CONN = show each connection status
- debug 4 # IO = show I/O status
- debug 8 # HDR = show header parsing
- debug 16 # LOG = log all data into the logfile
- debug 32 # FRC = debug force feature
- debug 64 # REF = debug regular expression filter
- debug 128 # = debug fast redirects
- debug 256 # = debug GIF de-animation
- debug 512 # CLF = Common Log Format
- debug 1024 # = debug kill pop-ups
- debug 4096 # INFO = Startup banner and warnings.
- debug 8192 # ERROR = Non-fatal errors
-
+ debug 1 # GPC = show each GET/POST/CONNECT request
+ debug 2 # CONN = show each connection status
+ debug 4 # IO = show I/O status
+ debug 8 # HDR = show header parsing
+ debug 16 # LOG = log all data into the logfile
+ debug 32 # FRC = debug force feature
+ debug 64 # REF = debug regular expression filter
+ debug 128 # = debug fast redirects
+ debug 256 # = debug GIF de-animation
+ debug 512 # CLF = Common Log Format
+ debug 1024 # = debug kill pop-ups
+ debug 4096 # INFO = Startup banner and warnings.
+ debug 8192 # ERROR = Non-fatal errors
+
It is highly recommended that you enable ERROR reporting (debug 8192), at least
until v3.0 is released.
Multiple "debug" directives, are OK - they're logical-OR'd together.
- debug 15 # same as setting the first 4 listed above
-
+ debug 15 # same as setting the first 4 listed above
+
Default:
- debug 1 # URLs
- debug 4096 # Info
- debug 8192 # Errors - *we highly recommended enabling this*
-
+ debug 1 # URLs
+ debug 4096 # Info
+ debug 8192 # Errors - *we highly recommended enabling this*
+
Privoxy normally uses "multi-threading", a software technique that permits it
to handle many different requests simultaneously. In some cases you may wish to
-disable this -- particularly if you're trying to debug a problem. The
+disable this -- particularly if you're trying to debug a problem. The
"single-threaded" option forces Privoxy to handle requests sequentially.
Default: Multi-threaded mode.
- #single-threaded
-
+ #single-threaded
+
-"toggle" allows you to temporarily disable all Privoxy's filtering. Just set
+"toggle" allows you to temporarily disable all Privoxy's filtering. Just set
"toggle 0".
The Windows version of Privoxy puts an icon in the system tray, which also
"toggle 1" means Privoxy runs normally, "toggle 0" means that Privoxy becomes a
non-anonymizing non-blocking proxy. Default: 1 (on).
- toggle 1
-
+ toggle 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
buffer may use. When the documents buffer exceeds this size, it is flushed to
the client unfiltered and no further attempt to filter the rest of it is made.
Remember that there may multiple threads running, which might require
-increasing the "buffer-limit" Kbytes each, unless you have enabled
+increasing the "buffer-limit" Kbytes each, unless you have enabled
"single-threaded" above.
- buffer-limit 4069
-
+ buffer-limit 4069
+
To enable the web-based default.action file editor set enable-edit-actions to
1, or 0 to disable. Note that you must have compiled Privoxy with support for
actions file, and their changes will affect all users. For shared proxies, you
probably want to disable this. Default: enabled.
- enable-edit-actions 1
-
+ enable-edit-actions 1
+
-Allow Privoxy to be toggled on and off remotely, using your web browser. Set
+Allow Privoxy to be toggled on and off remotely, using your web browser. Set
"enable-remote-toggle"to 1 to enable, and 0 to disable. Note that you must have
compiled Privoxy with support for this feature, otherwise this option has no
effect.
on or off (see http://p.p), and their changes will affect all users. For shared
proxies, you probably want to disable this. Default: enabled.
- enable-remote-toggle 1
-
+ enable-remote-toggle 1
+
+
-------------------------------------------------------------------------------
5.3.3. Access Control List (ACL)
The syntax for an entry in the Access Control List is:
- ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
-
+ ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
+
Where the individual fields are:
- ACTION = "permit-access" or "deny-access"
+ ACTION = "permit-access" or "deny-access"
- SRC_ADDR = client hostname or dotted IP address
- SRC_MASKLEN = number of bits in the subnet mask for the source
+ SRC_ADDR = client hostname or dotted IP address
+ SRC_MASKLEN = number of bits in the subnet mask for the source
- DST_ADDR = server or forwarder hostname or dotted IP address
- DST_MASKLEN = number of bits in the subnet mask for the target
-
+ DST_ADDR = server or forwarder hostname or dotted IP address
+ DST_MASKLEN = number of bits in the subnet mask for the target
+
The field separator (FS) is whitespace (space or tab).
"localhost" is OK -- no DST_ADDR implies that ALL destination addresses are OK:
- permit-access localhost
-
+ permit-access localhost
+
-A silly example to illustrate permitting any host on the class-C subnet with
+A silly example to illustrate permitting any host on the class-C subnet with
Privoxy to go anywhere:
- permit-access www.privoxy.com/24
-
+ permit-access www.privoxy.com/24
+
Except deny one particular IP address from using it at all:
- deny-access ident.privoxy.com
-
+ deny-access ident.privoxy.com
+
You can also specify an explicit network address and subnet mask. Explicit
addresses do not have to be resolved to be used.
- permit-access 207.153.200.0/24
-
+ permit-access 207.153.200.0/24
+
A subnet mask of 0 matches anything, so the next line permits everyone.
- permit-access 0.0.0.0/0
-
+ permit-access 0.0.0.0/0
+
Note, you cannot say:
- permit-access .org
-
+ permit-access .org
+
to allow all *.org domains. Every IP address listed must resolve fully.
(i.e. its own subscribers). Say, for instance the ISP owns the Class-B IP
address block 123.124.0.0 (a 16 bit netmask). This is how they could do it:
- permit-access 0.0.0.0/0 0.0.0.0/0 # other clients can go anywhere
- # with the following exceptions:
-
- deny-access 0.0.0.0/0 123.124.0.0/16 # block all external requests for
- # sites on the ISP's network
+ permit-access 0.0.0.0/0 0.0.0.0/0 # other clients can go anywhere
+ # with the following exceptions:
+
+ deny-access 0.0.0.0/0 123.124.0.0/16 # block all external requests for
+ # sites on the ISP's network
- permit 0.0.0.0/0 www.my_isp.com # except for the ISP's main
- # web site
+ permit 0.0.0.0/0 www.my_isp.com # except for the ISP's main
+ # web site
- permit 123.124.0.0/16 0.0.0.0/0 # the ISP's clients can go
- # anywhere
-
+ permit 123.124.0.0/16 0.0.0.0/0 # the ISP's clients can go
+ # anywhere
+
Note that if some hostnames are listed with multiple IP addresses, the primary
value returned by DNS (via gethostbyname()) is used. Default: Anyone can access
the proxy.
+
-------------------------------------------------------------------------------
5.3.4. Forwarding
The syntax of each line is:
- forward target_domain[:port] http_proxy_host[:port]
- forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:
+ forward target_domain[:port] http_proxy_host[:port]
+ forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:
port]
- forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:
+ forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:
port]
-
+
If http_proxy_host is ".", then requests are not forwarded to a HTTP proxy but
are made directly to the web servers.
anything not finding a match on the list is to go out without forwarding or
gateway protocol, like so:
- forward .* . # implicit
-
+ forward .* . # implicit
+
In the following common configuration, everything goes to Lucent's LPWA, except
SSL on port 443 (which it doesn't handle):
- forward .* lpwa.com:8000
- forward :443 .
-
+ forward .* lpwa.com:8000
+ forward :443 .
+
Some users have reported difficulties related to LPWA's use of "." as the last
element of the domain, and have said that this can be fixed with this:
- forward lpwa. lpwa.com:8000
-
+ forward lpwa. lpwa.com:8000
+
(NOTE: the syntax for specifying target_domain has changed since the previous
paragraph was written -- it will not work now. More information is welcome.)
In this fictitious example, everything goes via an ISP's caching proxy, except
requests to that ISP:
- forward .* caching.myisp.net:8000
- forward myisp.net .
-
+ forward .* caching.myisp.net:8000
+ forward myisp.net .
+
For the @home network, we're told the forwarding configuration is this:
- forward .* proxy:8080
-
+ forward .* proxy:8080
+
Also, we're told they insist on getting cookies and JavaScript, so you should
allow cookies from home.com. We consider JavaScript a potential security risk.
everything else goes through Lucent's LPWA by way of the company's SOCKS
gateway to the Internet.
- forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080
- forward my_company.com .
-
+ forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080
+ forward my_company.com .
+
This is how you could set up a site that always uses SOCKS but no forwarders:
- forward-socks4a .* . firewall.my_company.com:1080
-
+ forward-socks4a .* . firewall.my_company.com:1080
+
An advanced example for network administrators:
host-a has a PPP connection to isp-a.com. And host-b has a PPP connection to
isp-b.com. host-a can run a Privoxy proxy with forwarding like this:
- forward .* .
- forward isp-b.com host-b:8118
-
+ forward .* .
+ forward isp-b.com host-b:8118
+
host-b can run a Privoxy proxy with forwarding like this:
- forward .* .
- forward isp-a.com host-a:8118
-
+ forward .* .
+ forward isp-a.com host-a:8118
+
Now, anyone on the Internet (including users on host-a and host-b) can set
their browser's proxy to either host-a or host-b and be able to browse the
with a network connection in their room, who need to use the University's Squid
web cache.
- forward *. ssbcache.ukc.ac.uk:3128 # Use the proxy, except for:
- forward .ukc.ac.uk . # Anything on the same domain as us
- forward * . # Host with no domain specified
- forward 129.12.*.* . # A dotted IP on our /16 network.
- forward 127.*.*.* . # Loopback address
- forward localhost.localdomain . # Loopback address
- forward www.ukc.mirror.ac.uk . # Specific host
-
+ forward *. ssbcache.ukc.ac.uk:3128 # Use the proxy, except for:
+ forward .ukc.ac.uk . # Anything on the same domain as us
+ forward * . # Host with no domain specified
+ forward 129.12.*.* . # A dotted IP on our /16 network.
+ forward 127.*.*.* . # Loopback address
+ forward localhost.localdomain . # Loopback address
+ forward www.ukc.mirror.ac.uk . # Specific host
+
If you intend to chain Privoxy and squid locally, then chain as browser ->
squid -> privoxy is the recommended way.
Your squid configuration could then look like this (assuming that the IP
address of the box is 192.168.0.1 ):
- # Define Privoxy as parent cache
-
- cache_peer 192.168.0.1 parent 8118 0 no-query
+ # Define Privoxy as parent cache
+
+ cache_peer 192.168.0.1 parent 8118 0 no-query
+
+ # don't listen to the whole world
+ http_port 192.168.0.1:3128
- # don't listen to the whole world
- http_port 192.168.0.1:3128
+ # define the local lan
+ acl mylocallan src 192.168.0.1-192.168.0.5/255.255.255.255
- # define the local lan
- acl mylocallan src 192.168.0.1-192.168.0.5/255.255.255.255
+ # grant access for http to local lan
+ http_access allow mylocallan
+
+ # Define ACL for protocol FTP
+ acl FTP proto FTP
- # grant access for http to local lan
- http_access allow mylocallan
-
- # Define ACL for protocol FTP
- acl FTP proto FTP
+ # Do not forward ACL FTP to privoxy
+ always_direct allow FTP
- # Do not forward ACL FTP to privoxy
- always_direct allow FTP
+ # Do not forward ACL CONNECT (https) to privoxy
+ always_direct allow CONNECT
- # Do not forward ACL CONNECT (https) to privoxy
- always_direct allow CONNECT
+ # Forward the rest to privoxy
+ never_direct allow all
+
- # Forward the rest to privoxy
- never_direct allow all
-
-------------------------------------------------------------------------------
5.3.5. Windows GUI Options
Privoxy has a number of options specific to the Windows GUI interface:
-If "activity-animation" is set to 1, the Privoxy icon will animate when
+If "activity-animation" is set to 1, the Privoxy icon will animate when
"Privoxy" is active. To turn off, set to 0.
- activity-animation 1
-
+ activity-animation 1
+
If "log-messages" is set to 1, Privoxy will log messages to the console window:
- log-messages 1
-
+ log-messages 1
+
If "log-buffer-size" is set to 1, the size of the log buffer, i.e. the amount
of memory used for the log messages displayed in the console window, will be
Warning: Setting this to 0 will result in the buffer to grow infinitely and eat
up all your memory!
- log-buffer-size 1
-
+ log-buffer-size 1
+
log-max-lines is the maximum number of lines held in the log buffer. See above.
- log-max-lines 200
-
+ log-max-lines 200
+
If "log-highlight-messages" is set to 1, Privoxy will highlight portions of the
log messages with a bold-faced font:
- log-highlight-messages 1
-
+ log-highlight-messages 1
+
The font used in the console window:
- log-font-name Comic Sans MS
-
+ log-font-name Comic Sans MS
+
Font size used in the console window:
- log-font-size 8
-
+ log-font-size 8
+
"show-on-task-bar" controls whether or not Privoxy will appear as a button on
the Task bar when minimized:
- show-on-task-bar 0
-
+ show-on-task-bar 0
+
If "close-button-minimizes" is set to 1, the Windows close button will minimize
Privoxy instead of closing the program (close with the exit option on the File
menu).
- close-button-minimizes 1
-
+ close-button-minimizes 1
+
The "hide-console" option is specific to the MS-Win console version of Privoxy.
If this option is used, Privoxy will disconnect from and hide the command
console.
- #hide-console
-
+ #hide-console
+
+
-------------------------------------------------------------------------------
5.4. The Actions File
There are four types of lines in this file: comments (begin with a "#"
character), actions, aliases and patterns, all of which are explained below, as
well as the configuration file syntax that Privoxy understands.
+
-------------------------------------------------------------------------------
5.4.1. URL Domain and Path Syntax
<path> part are optional. If you only specify a domain part, the "/" can be
left out:
-www.example.com - is a domain only pattern and will match any request to
+www.example.com - is a domain only pattern and will match any request to
"www.example.com".
www.example.com/ - means exactly the same.
-www.example.com/index.html - matches only the single document "/index.html" on
+www.example.com/index.html - matches only the single document "/index.html" on
"www.example.com".
/index.html - matches the document "/index.html", regardless of the domain. So
.?pix.com - matches "www.ipix.com", "pictures.epix.com", "a.b.c.d.e.upix.com",
etc.
-www[1-9a-ez].example.com - matches "www1.example.com", "www4.example.com",
+www[1-9a-ez].example.com - matches "www1.example.com", "www4.example.com",
"wwwd.example.com", "wwwz.example.com", etc., but not "wwww.example.com".
If Privoxy was compiled with "pcre" support (the default), Perl compatible
www.example.com/(?-i)PaTtErN.* - will match only documents whose path starts
with "PaTtErN" in exactly this capitalization.
+
-------------------------------------------------------------------------------
5.4.2. Actions
-Actions are enabled if preceded with a "+", and disabled if preceded with a "-"
-. Actions are invoked by enclosing the action name in curly braces (e.g.
+Actions are enabled if preceded with a "+", and disabled if preceded with a
+"-". Actions are invoked by enclosing the action name in curly braces (e.g.
{+some_action}), followed by a list of URLs to which the action applies. There
are three classes of actions:
- * Boolean (e.g. "+/-block"):
+ * Boolean (e.g. "+/-block"):
- {+name} # enable this action
- {-name} # disable this action
-
+ {+name} # enable this action
+ {-name} # disable this action
+
- * parameterized (e.g. "+/-hide-user-agent"):
+ * parameterized (e.g. "+/-hide-user-agent"):
- {+name{param}} # enable action and set parameter to "param"
- {-name} # disable action
-
+ {+name{param}} # enable action and set parameter to "param"
+ {-name} # disable action
+
- * Multi-value (e.g. "{+/-add-header{Name: value}}", "{+/-wafer{name=value}}"
- ):
+ * Multi-value (e.g. "{+/-add-header{Name: value}}", "{+/-wafer{name=value}}
+ "):
- {+name{param}} # enable action and add parameter "param"
- {-name{param}} # remove the parameter "param"
- {-name} # disable this action totally
-
+ {+name{param}} # enable action and add parameter "param"
+ {-name{param}} # remove the parameter "param"
+ {-name} # disable this action totally
+
-
-If nothing is specified in this file, no "actions" are taken. So in this case
+If nothing is specified in this file, no "actions" are taken. So in this case
Privoxy would just be a normal, non-blocking, non-anonymizing proxy. You must
specifically enable the privacy and blocking features you need (although the
provided default default.action file will give a good starting point).
The list of valid Privoxy "actions" are:
- * Add the specified HTTP header, which is not checked for validity. You may
+ * Add the specified HTTP header, which is not checked for validity. You may
specify this many times to specify many different headers:
- +add-header{Name: value}
-
+ +add-header{Name: value}
+
- * Block this URL totally. In a default installation, a "blocked" URL will
+ * Block this URL totally. In a default installation, a "blocked" URL will
result in bright red banner that says "BLOCKED", with a reason why it is
being blocked, and an option to see it anyway. The page displayed for this
is the "blocked" template file.
- +block
-
+ +block
+
- * De-animate all animated GIF images, i.e. reduce them to their last frame.
+ * De-animate all animated GIF images, i.e. reduce them to their last frame.
This will also shrink the images considerably (in bytes, not pixels!). If
the option "first" is given, the first frame of the animation is used as
the replacement. If "last" is given, the last frame of the animation is
but also has the risk of not showing the entire last frame (if it is only a
delta to an earlier frame).
- +deanimate-gifs{last}
- +deanimate-gifs{first}
-
+ +deanimate-gifs{last}
+ +deanimate-gifs{first}
+
- * "+downgrade" will downgrade HTTP/1.1 client requests to HTTP/1.0 and
+ * "+downgrade" will downgrade HTTP/1.1 client requests to HTTP/1.0 and
downgrade the responses as well. Use this action for servers that use HTTP/
1.1 protocol features that Privoxy doesn't handle well yet. HTTP/1.1 is
only partially implemented. Default is not to downgrade requests.
- +downgrade
-
+ +downgrade
+
- * Many sites, like yahoo.com, don't just link to other sites. Instead, they
+ * Many sites, like yahoo.com, don't just link to other sites. Instead, they
will link to some script on their own server, giving the destination as a
parameter, which will then redirect you to the final target. URLs resulting
from this scheme typically look like: http://some.place/some_script?http://
request and send a local redirect back to your browser without contacting
the intermediate site(s).
- +fast-redirects
-
+ +fast-redirects
+
- * Apply the filters in the section_header section of the default.filter file
+ * Apply the filters in the section_header section of the default.filter file
to the site(s). default.filter sections are grouped according to like
functionality. Filters can be used to re-write any of the raw page content.
This is a potentially a very powerful feature!
- +filter{section_header}
-
+ +filter{section_header}
+
Filter sections that are pre-defined in the supplied default.filter
include:
-
html-annoyances: Get rid of particularly annoying HTML abuse.
js-annoyances: Get rid of particularly annoying JavaScript abuse
crude-parental: Kill all web pages that contain the words "sex" or
"warez"
-
+ * Block any existing X-Forwarded-for header, and do not add a new one:
- * Block any existing X-Forwarded-for header, and do not add a new one:
+ +hide-forwarded
+
- +hide-forwarded
-
-
- * If the browser sends a "From:" header containing your e-mail address, this
+ * If the browser sends a "From:" header containing your e-mail address, this
either completely removes the header ("block"), or changes it to the
specified e-mail address.
- +hide-from{block}
- +hide-from{spam@sittingduck.xqq}
-
+ +hide-from{block}
+ +hide-from{spam@sittingduck.xqq}
+
- * Don't send the "Referer:" (sic) header to the web site. You can block it,
+ * Don't send the "Referer:" (sic) header to the web site. You can block it,
forge a URL to the same server as the request (which is preferred because
some sites will not send images otherwise) or set it to a constant, user
defined string of your choice.
- +hide-referer{block}
- +hide-referer{forge}
- +hide-referer{http://nowhere.com}
-
+ +hide-referer{block}
+ +hide-referer{forge}
+ +hide-referer{http://nowhere.com}
+
- * Alternative spelling of "+hide-referer". It has the same parameters, and
+ * Alternative spelling of "+hide-referer". It has the same parameters, and
can be freely mixed with, "+hide-referer". ("referrer" is the correct
English spelling, however the HTTP specification has a bug - it requires it
to be spelled "referer".)
- +hide-referrer{...}
-
+ +hide-referrer{...}
+
- * Change the "User-Agent:" header so web servers can't tell your browser
+ * Change the "User-Agent:" header so web servers can't tell your browser
type. Warning! This breaks many web sites. Specify the user-agent value you
want. Example, pretend to be using Netscape on Linux:
- +hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}
-
+ +hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}
+
- * Treat this URL as an image. This only matters if it's also "+block"ed, in
- which case a "blocked" image can be sent rather than a HTML page. See
+ * Treat this URL as an image. This only matters if it's also "+block"ed, in
+ which case a "blocked" image can be sent rather than a HTML page. See
"+image-blocker{}" below for the control over what is actually sent. If you
want invisible ads, they should be defined as images and blocked. And also,
"image-blocker" should be set to "blank". Note you cannot treat HTML pages
display. So a frame that is an ad, cannot be treated as an image. Forcing
an "image" in this situation just will not work.
- +image
-
+ +image
+
- * Decides what to do with URLs that end up tagged with "{+block +image}", e.g
+ * Decides what to do with URLs that end up tagged with "{+block +image}", e.g
an advertizement. There are five options. "-image-blocker" will send a HTML
"blocked" page, usually resulting in a "broken image" icon. "+image-blocker
- {blank}" will send a 1x1 transparent GIF image. And finally,
+ {blank}" will send a 1x1 transparent GIF image. And finally,
"+image-blocker{http://xyz.com}" will send a HTTP temporary redirect to the
specified image. This has the advantage of the icon being being cached by
the browser, which will speed up the display. "+image-blocker{pattern}"
will send a checkboard type pattern
- +image-blocker{blank}
- +image-blocker{pattern}
- +image-blocker{http://p.p/send-banner}
-
+ +image-blocker{blank}
+ +image-blocker{pattern}
+ +image-blocker{http://p.p/send-banner}
+
- * By default (i.e. in the absence of a "+limit-connect" action), Privoxy will
+ * By default (i.e. in the absence of a "+limit-connect" action), Privoxy will
only allow CONNECT requests to port 443, which is the standard port for
https as a precaution.
port ranges (the latter using dashes, with the minimum defaulting to 0 and
max to 65K):
- +limit-connect{443} # This is the default and need no be specified.
- +limit-connect{80,443} # Ports 80 and 443 are OK.
- +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100
- #and above 500 are OK.
-
+ +limit-connect{443} # This is the default and need no be specified.
+ +limit-connect{80,443} # Ports 80 and 443 are OK.
+ +limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100
+ #and above 500 are OK.
+
- * "+no-compression" prevents the website from compressing the data. Some
- websites do this, which can be a problem for Privoxy, since "+filter",
+ * "+no-compression" prevents the website from compressing the data. Some
+ websites do this, which can be a problem for Privoxy, since "+filter",
"+no-popup" and "+gif-deanimate" will not work on compressed data. This
- will slow down connections to those websites, though. Default is
+ will slow down connections to those websites, though. Default is
"no-compression" is turned on.
- +nocompression
-
+ +nocompression
+
- * If the website sets cookies, "no-cookies-keep" will make sure they are
+ * If the website sets cookies, "no-cookies-keep" will make sure they are
erased when you exit and restart your web browser. This makes profiling
cookies useless, but won't break sites which require cookies so that you
can log in for transactions. Default: on.
- +no-cookies-keep
-
+ +no-cookies-keep
+
- * Prevent the website from reading cookies:
+ * Prevent the website from reading cookies:
- +no-cookies-read
-
+ +no-cookies-read
+
- * Prevent the website from setting cookies:
+ * Prevent the website from setting cookies:
- +no-cookies-set
-
+ +no-cookies-set
+
- * Filter the website through a built-in filter to disable those obnoxious
+ * Filter the website through a built-in filter to disable those obnoxious
JavaScript pop-up windows via window.open(), etc. The two alternative
spellings are equivalent.
- +no-popup
- +no-popups
-
+ +no-popup
+ +no-popups
+
- * This action only applies if you are using a jarfile for saving cookies. It
+ * This action only applies if you are using a jarfile for saving cookies. It
sends a cookie to every site stating that you do not accept any copyright
on cookies sent to you, and asking them not to track you. Of course, this
is a (relatively) unique header they could use to track you.
- +vanilla-wafer
-
+ +vanilla-wafer
+
- * This allows you to add an arbitrary cookie. It can be specified multiple
+ * This allows you to add an arbitrary cookie. It can be specified multiple
times in order to add as many cookies as you like.
- +wafer{name=value}
-
+ +wafer{name=value}
+
-
The meaning of any of the above is reversed by preceding the action with a "-",
in place of the "+".
Turn off cookies by default, then allow a few through for specified sites:
- # Turn off all persistent cookies
- { +no-cookies-read }
- { +no-cookies-set }
- # Allow cookies for this browser session ONLY
- { +no-cookies-keep }
-
- # Exceptions to the above, sites that benefit from persistent cookies
- { -no-cookies-read }
- { -no-cookies-set }
- { -no-cookies-keep }
- .javasoft.com
- .sun.com
- .yahoo.com
- .msdn.microsoft.com
- .redhat.com
-
- # Alternative way of saying the same thing
- {-no-cookies-set -no-cookies-read -no-cookies-keep}
- .sourceforge.net
- .sf.net
-
+ # Turn off all persistent cookies
+ { +no-cookies-read }
+ { +no-cookies-set }
+ # Allow cookies for this browser session ONLY
+ { +no-cookies-keep }
+
+ # Exceptions to the above, sites that benefit from persistent cookies
+ { -no-cookies-read }
+ { -no-cookies-set }
+ { -no-cookies-keep }
+ .javasoft.com
+ .sun.com
+ .yahoo.com
+ .msdn.microsoft.com
+ .redhat.com
+
+ # Alternative way of saying the same thing
+ {-no-cookies-set -no-cookies-read -no-cookies-keep}
+ .sourceforge.net
+ .sf.net
+
Now turn off "fast redirects", and then we allow two exceptions:
- # Turn them off!
- {+fast-redirects}
-
- # Reverse it for these two sites, which don't work right without it.
- {-fast-redirects}
- www.ukc.ac.uk/cgi-bin/wac\.cgi\?
- login.yahoo.com
-
+ # Turn them off!
+ {+fast-redirects}
+
+ # Reverse it for these two sites, which don't work right without it.
+ {-fast-redirects}
+ www.ukc.ac.uk/cgi-bin/wac\.cgi\?
+ login.yahoo.com
+
Turn on page filtering according to rules in the defined sections of
refilterfile, and make one exception for sourceforge:
- # Run everything through the filter file, using only the
- # specified sections:
- +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
- +filter{webbugs} +filter{nimda} +filter{banners-by-size}
-
- # Then disable filtering of code from sourceforge!
- {-filter}
- .cvs.sourceforge.net
-
+ # Run everything through the filter file, using only the
+ # specified sections:
+ +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}\
+ +filter{webbugs} +filter{nimda} +filter{banners-by-size}
+
+ # Then disable filtering of code from sourceforge!
+ {-filter}
+ .cvs.sourceforge.net
+
Now some URLs that we want "blocked" (normally generates the "blocked" banner).
Many of these use regular expressions that will expand to match multiple URLs:
- # Blocklist:
- {+block}
- /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
- /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
- /.*/(ng)?adclient\.cgi
- /.*/(plain|live|rotate)[-_.]?ads?/
- /.*/(sponsor)s?[0-9]?/
- /.*/_?(plain|live)?ads?(-banners)?/
- /.*/abanners/
- /.*/ad(sdna_image|gifs?)/
- /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
- /.*/adbanners/
- /.*/adserver
- /.*/adstream\.cgi
- /.*/adv((er)?ts?|ertis(ing|ements?))?/
- /.*/banner_?ads/
- /.*/banners?/
- /.*/banners?\.cgi/
- /.*/cgi-bin/centralad/getimage
- /.*/images/addver\.gif
- /.*/images/marketing/.*\.(gif|jpe?g)
- /.*/popupads/
- /.*/siteads/
- /.*/sponsor.*\.gif
- /.*/sponsors?[0-9]?/
- /.*/advert[0-9]+\.jpg
- /Media/Images/Adds/
- /ad_images/
- /adimages/
- /.*/ads/
- /bannerfarm/
- /grafikk/annonse/
- /graphics/defaultAd/
- /image\.ng/AdType
- /image\.ng/transactionID
- /images/.*/.*_anim\.gif # alvin brattli
- /ip_img/.*\.(gif|jpe?g)
- /rotateads/
- /rotations/
- /worldnet/ad\.cgi
- /cgi-bin/nph-adclick.exe/
- /.*/Image/BannerAdvertising/
- /.*/ad-bin/
- /.*/adlib/server\.cgi
- /autoads/
-
+ # Blocklist:
+ {+block}
+ /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
+ /.*/(.*[-_.])?count(er)?(\.cgi|\.dll|\.exe|[?/])
+ /.*/(ng)?adclient\.cgi
+ /.*/(plain|live|rotate)[-_.]?ads?/
+ /.*/(sponsor)s?[0-9]?/
+ /.*/_?(plain|live)?ads?(-banners)?/
+ /.*/abanners/
+ /.*/ad(sdna_image|gifs?)/
+ /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
+ /.*/adbanners/
+ /.*/adserver
+ /.*/adstream\.cgi
+ /.*/adv((er)?ts?|ertis(ing|ements?))?/
+ /.*/banner_?ads/
+ /.*/banners?/
+ /.*/banners?\.cgi/
+ /.*/cgi-bin/centralad/getimage
+ /.*/images/addver\.gif
+ /.*/images/marketing/.*\.(gif|jpe?g)
+ /.*/popupads/
+ /.*/siteads/
+ /.*/sponsor.*\.gif
+ /.*/sponsors?[0-9]?/
+ /.*/advert[0-9]+\.jpg
+ /Media/Images/Adds/
+ /ad_images/
+ /adimages/
+ /.*/ads/
+ /bannerfarm/
+ /grafikk/annonse/
+ /graphics/defaultAd/
+ /image\.ng/AdType
+ /image\.ng/transactionID
+ /images/.*/.*_anim\.gif # alvin brattli
+ /ip_img/.*\.(gif|jpe?g)
+ /rotateads/
+ /rotations/
+ /worldnet/ad\.cgi
+ /cgi-bin/nph-adclick.exe/
+ /.*/Image/BannerAdvertising/
+ /.*/ad-bin/
+ /.*/adlib/server\.cgi
+ /autoads/
+
Note that many of these actions have the potential to cause a page to
misbehave, possibly even not to display at all. There are many ways a site
designer may choose to design his site, and what HTTP header content he may
depend on. There is no way to have hard and fast rules for all sites. See the
Appendix for a brief example on troubleshooting actions.
+
-------------------------------------------------------------------------------
5.4.3. Aliases
Now let's define a few aliases:
- # Useful custom aliases we can use later. These must come first!
- {{alias}}
- +no-cookies = +no-cookies-set +no-cookies-read
- -no-cookies = -no-cookies-set -no-cookies-read
- fragile =
- -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
- shop = -no-cookies -filter -fast-redirects
- +imageblock = +block +image
-
- #For people who don't like to type too much: ;-)
- c0 = +no-cookies
- c1 = -no-cookies
- c2 = -no-cookies-set +no-cookies-read
- c3 = +no-cookies-set -no-cookies-read
- #... etc. Customize to your heart's content.
-
+ # Useful custom aliases we can use later. These must come first!
+ {{alias}}
+ +no-cookies = +no-cookies-set +no-cookies-read
+ -no-cookies = -no-cookies-set -no-cookies-read
+ fragile =
+ -block -no-cookies -filter -fast-redirects -hide-referer -no-popups
+ shop = -no-cookies -filter -fast-redirects
+ +imageblock = +block +image
+
+ #For people who don't like to type too much: ;-)
+ c0 = +no-cookies
+ c1 = -no-cookies
+ c2 = -no-cookies-set +no-cookies-read
+ c3 = +no-cookies-set -no-cookies-read
+ #... etc. Customize to your heart's content.
+
Some examples using our "shop" and "fragile" aliases from above:
- # These sites are very complex and require
- # minimal interference.
- {fragile}
- .office.microsoft.com
- .windowsupdate.microsoft.com
- .nytimes.com
-
- # Shopping sites - still want to block ads.
- {shop}
- .quietpc.com
- .worldpay.com # for quietpc.com
- .jungle.com
- .scan.co.uk
-
- # These shops require pop-ups
- {shop -no-popups}
- .dabs.com
- .overclockers.co.uk
-
+ # These sites are very complex and require
+ # minimal interference.
+ {fragile}
+ .office.microsoft.com
+ .windowsupdate.microsoft.com
+ .nytimes.com
+
+ # Shopping sites - still want to block ads.
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+
+ # These shops require pop-ups
+ {shop -no-popups}
+ .dabs.com
+ .overclockers.co.uk
+
The "shop" and "fragile" aliases are often used for "problem" sites that
require most actions to be disabled in order to function properly.
+
-------------------------------------------------------------------------------
5.5. The Filter File
tags and non-visible content. The default filter file is default.filter,
located in the config directory.
-This is potentially a very powerful feature, and requires knowledge of both
+This is potentially a very powerful feature, and requires knowledge of both
"regular expression" and HTML in order create custom filters. But, there are a
number of useful filters included with Privoxy for many common situations.
The included example file is divided into sections. Each section begins with
the FILTER keyword, followed by the identifier for that section, e.g. "FILTER:
-webbugs". Each section performs a similar type of filtering, such as
+webbugs". Each section performs a similar type of filtering, such as
"html-annoyances".
This file uses regular expressions to alter or remove any string in the target
Stop web pages from displaying annoying messages in the status bar by deleting
such references:
- FILTER: html-annoyances
+ FILTER: html-annoyances
- # New browser windows should be resizeable and have a location and status
- # bar. Make it so.
- #
- s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
- s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
- s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
- s/menubar="?(no|0)"?/menubar=1/ig
+ # New browser windows should be resizeable and have a location and status
+ # bar. Make it so.
+ #
+ s/resizable="?(no|0)"?/resizable=1/ig s/noresize/yesresize/ig
+ s/location="?(no|0)"?/location=1/ig s/status="?(no|0)"?/status=1/ig
+ s/scrolling="?(no|0|Auto)"?/scrolling=1/ig
+ s/menubar="?(no|0)"?/menubar=1/ig
- # The <BLINK> tag was a crime!
- #
- s*<blink>|</blink>**ig
+ # The <BLINK> tag was a crime!
+ #
+ s*<blink>|</blink>**ig
- # Is this evil?
- #
- #s/framespacing="?(no|0)"?//ig
- #s/margin(height|width)=[0-9]*//gi
-
+ # Is this evil?
+ #
+ #s/framespacing="?(no|0)"?//ig
+ #s/margin(height|width)=[0-9]*//gi
+
Just for kicks, replace any occurrence of "Microsoft" with "MicroSuck", and
have a little fun with topical buzzwords:
- FILTER: fun
+ FILTER: fun
- s/microsoft(?!.com)/MicroSuck/ig
+ s/microsoft(?!.com)/MicroSuck/ig
- # Buzzword Bingo:
- #
- s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></
+ # Buzzword Bingo:
+ #
+ s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></
font>/ig
-
+
Kill those pesky little web-bugs:
- # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
- FILTER: webbugs
+ # webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking)
+ FILTER: webbugs
+
+ s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1
+(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
+
- s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1
-(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
-
-------------------------------------------------------------------------------
5.6. Templates
The default "Blocked" banner page with the bright red top banner, is called
just "blocked". This may be customized or replaced with something else if
desired.
+
-------------------------------------------------------------------------------
6. Contacting the Developers, Bug Reporting and Feature Requests
We value your feedback. However, to provide you with the best support, please
note:
- * Use the Sourceforge Support Forum to get help:
-
- http://sourceforge.net/tracker/?group_id=11118&atid=211118
-
+ * Use the Sourceforge Support Forum to get help:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=211118
+
- * Submit bugs only through our Sourceforge Bug Forum:
-
- http://sourceforge.net/tracker/?group_id=11118&atid=111118.
-
+ * Submit bugs only through our Sourceforge Bug Forum:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=111118.
+
Make sure that the bug has not already been submitted. Please try to verify
that it is a Privoxy bug, and not a browser or site bug first. If you are
platform, browser, any pertinent log data, any other relevant details
(please be specific) and, if possible, some way to reproduce the bug.
- * Submit feature requests only through our Sourceforge feature request
- forum:
-
- http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
-
+ * Submit feature requests only through our Sourceforge feature request
+ forum:
+
+ http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
+
- * We will soon have an automated way to submit advertisements, incorrectly
- blocked images, popups and the like. Check back.
-
+ * We will soon have an automated way to submit advertisements, incorrectly
+ blocked images, popups and the like. Check back.
+
- * For any other issues, feel free to use the mailing lists:
-
- http://sourceforge.net/mail/?group_id=11118.
-
+ * For any other issues, feel free to use the mailing lists:
+
+ http://sourceforge.net/mail/?group_id=11118.
+
Anyone interested in actively participating in development and related
discussions can also join the appropriate mailing list. Archives are
available too.
-
-------------------------------------------------------------------------------
+
7. Copyright and History
7.1. Copyright
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., 59 Temple
Place, Suite 330, Boston, MA 02111-1307 USA.
+
-------------------------------------------------------------------------------
7.2. History
Privoxy to rekindle development. There are now several active developers
contributing. The last stable release of Junkbuster was v2.0.2, which has now
grown whiskers ;-).
+
-------------------------------------------------------------------------------
8. See Also
http://www.squid-cache.org/
+
-------------------------------------------------------------------------------
9. Appendix
s/string1/string2/g - This is used to rewrite strings of text. "string1" is
replaced by "string2" in this example.
-These are just some of the ones you are likely to use when matching URLs with
+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:
|" 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
+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
+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
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
+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://www.perldoc.com/
perl5.6/pod/perlre.html
+
-------------------------------------------------------------------------------
9.2. Privoxy's Internal Pages
Of course, Privoxy must be running to access these. If not, you will get a
friendly error message. Internet access is not necessary either.
- * Privoxy main page:
+ * Privoxy main page:
-
http://config.privoxy.org/
-
Alternately, this may be reached at http://p.p/, but this variation may not
work as reliably as the above in some configurations.
- * Show information about the current configuration:
+ * Show information about the current configuration:
-
http://config.privoxy.org/show-status
+ * Show the source code version numbers:
- * Show the source code version numbers:
-
-
http://config.privoxy.org/show-version
+ * Show the client's request headers:
- * Show the client's request headers:
-
-
http://config.privoxy.org/show-request
+ * Show which actions apply to a URL and why:
- * Show which actions apply to a URL and why:
-
-
http://config.privoxy.org/show-url-info
-
- * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but
+ * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but
only as a pass-through proxy, with no actions taking place:
-
http://config.privoxy.org/toggle
-
Short cuts. Turn off, then on:
-
http://config.privoxy.org/toggle?set=disable
-
-
http://config.privoxy.org/toggle?set=enable
+ * Edit the actions list file:
- * Edit the actions list file:
-
-
http://config.privoxy.org/edit-actions
-
-
These may be bookmarked for quick reference.
+
-------------------------------------------------------------------------------
9.2.1. Bookmarklets
bar (IE) or the "Personal Toolbar" (Netscape), and run them with a single
click.
- * Enable Privoxy
+ * Enable Privoxy
- * Disable Privoxy
+ * Disable Privoxy
- * Toggle Privoxy (Toggles between enabled and disabled)
+ * Toggle Privoxy (Toggles between enabled and disabled)
- * View Privoxy Status
+ * View Privoxy Status
-
Credit: The site which gave me the general idea for these bookmarklets is
www.bookmarklets.com. They have more information about bookmarklets.
+
-------------------------------------------------------------------------------
9.3. 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
+we need to be able to see just what Privoxy is doing. Especially, if something
Privoxy is doing is causing us a problem inadvertantly. It can be a little
daunting to look at the actions and filters files themselves, since they tend
to be filled with "regular expressions" whose consequences are not always so
This is much more informative, and tells us how we have defined our "actions",
and which ones match for our example, "google.com". The first grouping shows
-our default settings, which would apply to all URLs. If you look at your
+our default settings, which would apply to all URLs. If you look at your
"actions" file, this would be the section just below the "aliases" section near
the top. This applies to all URLs as signified by the single forward slash -- "
/".
URLs that these exceptions would apply to. Last match wins. Just below this
then are two explict matches for ".google.com". The first is negating our
various cookie blocking actions (i.e. we will allow cookies here). The second
-is allowing "fast-redirects". Note that there is a leading dot here --
+is allowing "fast-redirects". Note that there is a leading dot here --
".google.com". This will match any hosts and sub-domains, in the google.com
domain also, such as "www.google.com". So, apparently, we have these actions
defined somewhere in the lower part of our actions file, and "google.com" is
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
+defined as "ad.doubleclick.net" is done here -- as both a "+block" and an
"+image". The custom alias "+imageblock" does this for us.
One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". This one is
resort for problem sites. Remember to flush caches! If this still does not
work, you will have to go through the remaining actions one by one to find
which one(s) is causing the problem.
+
projects / privoxy.git / commitdiff