From 16e9ef297b4cf15a61876abcc794e5a058500e4b Mon Sep 17 00:00:00 2001 From: swa Date: Sun, 7 Apr 2002 08:39:11 +0000 Subject: [PATCH] generated files. do NOT edit. --- doc/webserver/.gitignore | 4 - doc/webserver/developer-manual/coding.html | 2265 ++++++++++ doc/webserver/developer-manual/contact.html | 223 + doc/webserver/developer-manual/copyright.html | 211 + doc/webserver/developer-manual/cvs.html | 135 + .../developer-manual/documentation.html | 779 ++++ doc/webserver/developer-manual/index.html | 654 +++ .../developer-manual/introduction.html | 157 + .../developer-manual/newrelease.html | 1299 ++++++ .../developer-manual/quickstart.html | 174 + doc/webserver/developer-manual/seealso.html | 286 ++ doc/webserver/developer-manual/testing.html | 248 ++ doc/webserver/faq/configuration.html | 1111 +++++ doc/webserver/faq/contact.html | 223 + doc/webserver/faq/copyright.html | 202 + doc/webserver/faq/general.html | 658 +++ doc/webserver/faq/index.html | 688 +++ doc/webserver/faq/installation.html | 379 ++ doc/webserver/faq/misc.html | 803 ++++ doc/webserver/faq/trouble.html | 329 ++ doc/webserver/man-page/privoxy-man-page.html | 343 ++ doc/webserver/user-manual/appendix.html | 1549 +++++++ doc/webserver/user-manual/configuration.html | 3964 +++++++++++++++++ doc/webserver/user-manual/contact.html | 228 + doc/webserver/user-manual/copyright.html | 213 + doc/webserver/user-manual/index.html | 483 ++ doc/webserver/user-manual/installation.html | 567 +++ doc/webserver/user-manual/introduction.html | 266 ++ doc/webserver/user-manual/quickstart.html | 500 +++ doc/webserver/user-manual/seealso.html | 295 ++ 30 files changed, 19232 insertions(+), 4 deletions(-) create mode 100644 doc/webserver/developer-manual/coding.html create mode 100644 doc/webserver/developer-manual/contact.html create mode 100644 doc/webserver/developer-manual/copyright.html create mode 100644 doc/webserver/developer-manual/cvs.html create mode 100644 doc/webserver/developer-manual/documentation.html create mode 100644 doc/webserver/developer-manual/index.html create mode 100644 doc/webserver/developer-manual/introduction.html create mode 100644 doc/webserver/developer-manual/newrelease.html create mode 100644 doc/webserver/developer-manual/quickstart.html create mode 100644 doc/webserver/developer-manual/seealso.html create mode 100644 doc/webserver/developer-manual/testing.html create mode 100644 doc/webserver/faq/configuration.html create mode 100644 doc/webserver/faq/contact.html create mode 100644 doc/webserver/faq/copyright.html create mode 100644 doc/webserver/faq/general.html create mode 100644 doc/webserver/faq/index.html create mode 100644 doc/webserver/faq/installation.html create mode 100644 doc/webserver/faq/misc.html create mode 100644 doc/webserver/faq/trouble.html create mode 100644 doc/webserver/man-page/privoxy-man-page.html create mode 100644 doc/webserver/user-manual/appendix.html create mode 100644 doc/webserver/user-manual/configuration.html create mode 100644 doc/webserver/user-manual/contact.html create mode 100644 doc/webserver/user-manual/copyright.html create mode 100644 doc/webserver/user-manual/index.html create mode 100644 doc/webserver/user-manual/installation.html create mode 100644 doc/webserver/user-manual/introduction.html create mode 100644 doc/webserver/user-manual/quickstart.html create mode 100644 doc/webserver/user-manual/seealso.html diff --git a/doc/webserver/.gitignore b/doc/webserver/.gitignore index 7184d633..e69de29b 100644 --- a/doc/webserver/.gitignore +++ b/doc/webserver/.gitignore @@ -1,4 +0,0 @@ -developer-manual -faq -user-manual -man-page \ No newline at end of file diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html new file mode 100644 index 00000000..5b3c4883 --- /dev/null +++ b/doc/webserver/developer-manual/coding.html @@ -0,0 +1,2265 @@ +Coding Guidelines
Privoxy Developer Manual
PrevNext

5. Coding Guidelines

5.1. Introduction

This set of standards is designed to make our lives easier. It is + developed with the simple goal of helping us keep the "new and improved + Privoxy" consistent and reliable. Thus making + maintenance easier and increasing chances of success of the + project.

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

5.2.1. Comment, Comment, Comment

Explanation:

Comment as much as possible without commenting the obvious. + For example do not comment "aVariable is equal to bVariable". + Instead explain why aVariable should be equal to the bVariable. + Just because a person can read code does not mean they will + understand why or what is being done. A reader may spend a lot + more time figuring out what is going on when a simple comment + or explanation would have prevented the extra research. Please + help your brother IJB'ers out!

The comments will also help justify the intent of the code. + If the comment describes something different than what the code + is doing then maybe a programming error is occurring.

Example:

/* if page size greater than 1k ... */
+if ( PageLength() > 1024 )
+{
+    ... "block" the page up ...
+}
+
+/* if page size is small, send it in blocks */
+if ( PageLength() > 1024 )
+{
+    ... "block" the page up ...
+}
+
+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

Explanation:

Comments can help or they can clutter. They help when they + are differentiated from the code they describe. One line + comments do not offer effective separation between the comment + and the code. Block identifiers do, by surrounding the code + with a clear, definable pattern.

Example:

/*********************************************************************
+ * This will stand out clearly in your code!
+ *********************************************************************/
+if ( thisVariable == thatVariable )
+{
+   DoSomethingVeryImportant();
+}
+
+
+/* unfortunately, this may not */
+if ( thisVariable == thatVariable )
+{
+   DoSomethingVeryImportant();
+}
+
+
+if ( thisVariable == thatVariable ) /* this may not either */
+{
+   DoSomethingVeryImportant();
+}

Exception:

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

Explanation:

It goes back to the question of readability. If the comment + is on the same line as the code it will be harder to read than + the comment that is on its own line.

There are three exceptions to this rule, which should be + violated freely and often: during the definition of variables, + at the end of closing braces, when used to comment + parameters.

Example:

/*********************************************************************
+ * This will stand out clearly in your code,
+ * But the second example won't.
+ *********************************************************************/
+if ( thisVariable == thatVariable )
+{
+   DoSomethingVeryImportant();
+}
+
+if ( thisVariable == thatVariable ) /*can you see me?*/
+{
+   DoSomethingVeryImportant(); /*not easily*/
+}
+
+
+/*********************************************************************
+ * But, the encouraged exceptions:
+ *********************************************************************/
+int urls_read     = 0;     /* # of urls read + rejected */
+int urls_rejected = 0;     /* # of urls rejected */
+
+if ( 1 == X )
+{
+   DoSomethingVeryImportant();
+}
+
+
+short DoSomethingVeryImportant(
+   short firstparam,   /* represents something */
+   short nextparam     /* represents something else */ )
+{
+   ...code here...
+
+}   /* -END- DoSomethingVeryImportant */

5.2.4. Comment each logical step

Explanation:

Logical steps should be commented to help others follow the + intent of the written code and comments will make the code more + readable.

If you have 25 lines of code without a comment, you should + probably go back into it to see where you forgot to put + one.

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

Explanation:

A reader of the code should be able to look at the comments + just prior to the beginning of a function and discern the + reason for its existence and the consequences of using it. The + reader should not have to read through the code to determine if + a given function is safe for a desired use. The proper + information thoroughly presented at the introduction of a + function not only saves time for subsequent maintenance or + debugging, it more importantly aids in code reuse by allowing a + user to determine the safety and applicability of any function + for the problem at hand. As a result of such benefits, all + functions should contain the information presented in the + addendum section of this document.

5.2.6. Comment at the end of braces if the + content is more than one screen length

Explanation:

Each closing brace should be followed on the same line by a + comment that describes the origination of the brace if the + original brace is off of the screen, or otherwise far away from + the closing brace. This will simplify the debugging, + maintenance, and readability of the code.

As a suggestion , use the following flags to make the + comment and its brace more readable:

use following a closing brace: } /* -END- if() or while () + or etc... */

Example:

if ( 1 == X )
+{
+   DoSomethingVeryImportant();
+   ...some long list of commands...
+} /* -END- if x is 1 */
+
+or:
+
+if ( 1 == X )
+{
+   DoSomethingVeryImportant();
+   ...some long list of commands...
+} /* -END- if ( 1 == X ) */

5.3. Naming Conventions

5.3.1. Variable Names

Explanation:

Use all lowercase, and seperate words via an underscore + ('_'). Do not start an identifier with an underscore. (ANSI C + reserves these for use by the compiler and system headers.) Do + not use identifiers which are reserved in ANSI C++. (E.g. + template, class, true, false, ...). This is in case we ever + decide to port Privoxy to C++.

Example:

int ms_iis5_hack = 0;

Instead of:

int msiis5hack = 0; int msIis5Hack = 0;

5.3.2. Function Names

Explanation:

Use all lowercase, and seperate words via an underscore + ('_'). Do not start an identifier with an underscore. (ANSI C + reserves these for use by the compiler and system headers.) Do + not use identifiers which are reserved in ANSI C++. (E.g. + template, class, true, false, ...). This is in case we ever + decide to port Privoxy to C++.

Example:

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

Explanation:

Use a descriptive parameter name in the function prototype + in header files. Use the same parameter name in the header file + that you use in the c file.

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

Explanation:

Use all capital letters, with underscores between words. Do + not start an identifier with an underscore. (ANSI C reserves + these for use by the compiler and system headers.)

Example:

(enumeration) : enum Boolean { FALSE, TRUE };
+(#define) : #define DEFAULT_SIZE 100;

Note: We have a standard naming scheme for #defines + that toggle a feature in the preprocessor: FEATURE_>, where + > is a short (preferably 1 or 2 word) description.

Example:

#define FEATURE_FORCE 1
+
+#ifdef FEATURE_FORCE
+#define FORCE_PREFIX blah
+#endif /* def FEATURE_FORCE */

5.3.5. Constants

Explanation:

Spell common words out entirely (do not remove vowels).

Use only widely-known domain acronyms and abbreviations. + Capitalize all letters of an acronym.

Use underscore (_) to separate adjacent acronyms and + abbreviations. Never terminate a name with an underscore.

Example:

#define USE_IMAGE_LIST 1

Instead of:

#define USE_IMG_LST 1 or 
+#define _USE_IMAGE_LIST 1 or
+#define USE_IMAGE_LIST_ 1 or 
+#define use_image_list 1 or
+#define UseImageList 1

5.4. Using Space

5.4.1. Put braces on a line by themselves.

Explanation:

The brace needs to be on a line all by itself, not at the + end of the statement. Curly braces should line up with the + construct that they're associated with. This practice makes it + easier to identify the opening and closing braces for a + block.

Example:

if ( this == that )
+{
+   ...
+}

Instead of:

if ( this == that ) { ... }

or

if ( this == that ) { ... }

Note: In the special case that the if-statement is + inside a loop, and it is trivial, i.e. it tests for a + condidtion that is obvious from the purpose of the block, + one-liners as above may optically preserve the loop structure + and make it easier to read.

Status: developer-discrection.

Example exception:

while ( more lines are read )
+{
+   /* Please document what is/is not a comment line here */
+   if ( it's a comment ) continue;
+
+   do_something( line );
+}

5.4.2. ALL control statements should have a + block

Explanation:

Using braces to make a block will make your code more + readable and less prone to error. All control statements should + have a block defined.

Example:

if ( this == that )
+{
+   DoSomething();
+   DoSomethingElse();
+}

Instead of:

if ( this == that ) DoSomething(); DoSomethingElse();

or

if ( this == that ) DoSomething();

Note: The first example in "Instead of" will execute + in a manner other than that which the developer desired (per + indentation). Using code braces would have prevented this + "feature". The "explanation" and "exception" from the point + above also applies.

5.4.3. Do not belabor/blow-up boolean + expressions

Example:

structure->flag = ( condition );

Instead of:

if ( condition ) { structure->flag = 1; } else { + structure->flag = 0; }

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

Explanation:

Make it readable. The notable exception to using white space + freely is listed in the next guideline.

Example:

int firstValue   = 0;
+int someValue    = 0;
+int anotherValue = 0;
+int thisVariable = 0;
+
+if ( thisVariable == thatVariable )
+
+firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )

5.4.5. Don't use white space around structure + operators

Explanation:

- structure pointer operator ( "->" ) - member operator ( + "." ) - functions and parentheses

It is a general coding practice to put pointers, references, + and function parentheses next to names. With spaces, the + connection between the object and variable/function name is not + as clear.

Example:

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...
+   return( retCode );
+
+}   /* -END- function1 */
+
+
+int function2( ... )
+{
+}   /* -END- function2 */

Instead of:

int function1( ... ) { ...code... return( retCode ); } int + function2( ... ) { }

Note: Use 1 blank line before the closing brace and 2 + lines afterwards. This makes the end of function standout to + the most casual viewer. Although function comments help + seperate functions, this is still a good coding practice. In + fact, I follow these rules when using blocks in "for", "while", + "do" loops, and long if {} statements too. After all whitespace + is free!

Status: developer-discrection on the number of blank + lines. Enforced is the end of function comments.

5.4.7. Use 3 character indentions

Explanation:

If some use 8 character TABs and some use 3 character TABs, + the code can look *very* ragged. So use 3 character indentions + only. If you like to use TABs, pass your code through a filter + such as "expand -t3" before checking in your code.

Example:

static const char * const url_code_map[256] =
+{
+   NULL, ...
+};
+
+
+int function1( ... )
+{
+   if ( 1 )
+   {
+      return( ALWAYS_TRUE );
+   }
+   else
+   {
+      return( HOW_DID_YOU_GET_HERE );
+   }
+
+   return( NEVER_GETS_HERE );
+
+}

5.5. Initializing

5.5.1. Initialize all variables

Explanation:

Do not assume that the variables declared will not be used + until after they have been assigned a value somewhere else in + the code. Remove the chance of accidentally using an unassigned + variable.

Example:

short anShort = 0;
+float aFloat  = 0;
+struct *ptr = NULL;

Note: It is much easier to debug a SIGSEGV if the + message says you are trying to access memory address 00000000 + and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. + arrayPtr[0].

Status: developer-discrection if and only if the + variable is assigned a value "shortly after" declaration.

5.6. Functions

5.6.1. Name functions that return a boolean as a + question.

Explanation:

Value should be phrased as a question that would logically + be answered as a true or false statement

Example:

ShouldWeBlockThis();
+ContainsAnImage();
+IsWebPageBlank();

5.6.2. Always specify a return type for a + function.

Explanation:

The default return for a function is an int. To avoid + ambiguity, create a return for a function when the return has a + purpose, and create a void return type if the function does not + need to return anything.

5.6.3. Minimize function calls when iterating by + using variables

Explanation:

It is easy to write the following code, and a clear argument + can be made that the code is easy to understand:

Example:

for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+{
+   ....
+}

Note: Unfortunately, this makes a function call for + each and every iteration. This increases the overhead in the + program, because the compiler has to look up the function each + time, call it, and return a value. Depending on what occurs in + the blockListLength() call, it might even be creating and + destroying structures with each iteration, even though in each + case it is comparing "cnt" to the same value, over and over. + Remember too - even a call to blockListLength() is a function + call, with the same overhead.

Instead of using a function call during the iterations, + assign the value to a 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

Explanation:

This allows a developer to define a const pointer and call + your function. If your function does not have the const + keyword, we may not be able to use your function. Consider + strcmp, if it were defined as: extern int strcmp( char *s1, + char *s2 );

I could then not use it to compare argv's in main: int main( + int argc, const char *argv[] ) { strcmp( argv[0], "privoxy" + ); }

Both these pointers are *const*! If the c runtime library + maintainers do it, we should too.

5.6.5. Pass and Return by Value

Explanation:

Most structures cannot fit onto a normal stack entry (i.e. + they are not 4 bytes or less). Aka, a function declaration + like: int load_aclfile( struct client_state csp )

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

Explanation:

Your include statements should contain the file name without + a path. The path should be listed in the Makefile, using -I as + processor directive to search the indicated paths. An exception + to this would be for some proprietary software that utilizes a + partial path to distinguish their header files from system or + other header files.

Example:

#include <iostream.h>     /* This is not a local include */
+#include "config.h"       /* This IS a local include */

Exception:

/* This is not a local include, but requires a path element. */ 
+#include <sys/fileName.h>

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

Explanation:

Prevents compiler and linker errors resulting from + redefinition of items.

Wrap each header file with the following syntax to prevent + multiple inclusions of the file. Of course, replace PROJECT_H + with your file name, with "." Changed to "_", and make it + uppercase.

Example:

#ifndef PROJECT_H_INCLUDED
+#define PROJECT_H_INCLUDED
+ ...
+#endif /* ndef PROJECT_H_INCLUDED */

5.6.8. Use `extern "C"` when appropriate

Explanation:

If our headers are included from C++, they must declare our + functions as `extern "C"`. This has no cost in C, but increases + the potential re-usability of our code.

Example:

#ifdef __cplusplus
+extern "C"
+{
+#endif /* def __cplusplus */
+
+... function definitions here ...
+
+#ifdef __cplusplus
+}
+#endif /* def __cplusplus */

5.6.9. Where Possible, Use Forward Struct + Declaration Instead of Includes

Explanation:

Useful in headers that include pointers to other struct's. + Modifications to excess header files may cause needless + compiles.

Example:

/*********************************************************************
+ * We're avoiding an include statement here!
+ *********************************************************************/
+struct file_list;
+extern file_list *xyz;

Note: If you declare "file_list xyz;" (without the + pointer), then including the proper header file is necessary. + If you only want to prototype a pointer, however, the header + file is unneccessary.

Status: Use with discrection.

5.7. General Coding Practices

5.7.1. Turn on warnings

Explanation

Compiler warnings are meant to help you find bugs. You + should turn on as many as possible. With GCC, the switch is + "-Wall". Try and fix as many warnings as possible.

5.7.2. Provide a default case for all switch + statements

Explanation:

What you think is guaranteed is never really guaranteed. The + value that you don't think you need to check is the one that + someday will be passed. So, to protect yourself from the + unknown, always have a default step in a switch statement.

Example:

switch( hash_string( cmd ) )
+{
+   case hash_actions_file :
+      ... code ...
+      break;
+
+   case hash_confdir :
+      ... code ...
+      break;
+
+   default :
+      log_error( ... );
+      ... anomly code goes here ...
+      continue; / break; / exit( 1 ); / etc ...
+
+} /* end switch( hash_string( cmd ) ) */

Note: If you already have a default condition, you + are obviously exempt from this point. Of note, most of the + WIN32 code calls `DefWindowProc' after the switch statement. + This API call *should* be included in a default statement.

Another Note: This is not so much a readability issue + as a robust programming issue. The "anomly code goes here" may + be no more than a print to the STDERR 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.

Explanation:

In general, you will want to have a 'break' statement within + each 'case' of a switch statement. This allows for the code to + be more readable and understandable, and furthermore can + prevent unwanted surprises if someone else later gets creative + and moves the code around.

The language allows you to plan the fall through from one + case statement to another simply by omitting the break + statement within the case statement. This feature does have + benefits, but should only be used in rare cases. In general, + use a break statement for each case statement.

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'

Explanation:

On 32-bit platforms, int usually has the range of long. On + 16-bit platforms, int has the range of short.

Status: open-to-debate. In the case of most FSF + projects (including X/GNU-Emacs), there are typedefs to int4, + int8, int16, (or equivalence ... I forget the exact typedefs + now). Should we add these to IJB now that we have a "configure" + script?

5.7.5. Don't mix size_t and other types

Explanation:

The type of size_t varies across platforms. Do not make + assumptions about whether it is signed or unsigned, or about + how long it is. Do not compare a size_t against another + variable of a different type (or even against a constant) + without casting one of the values. Try to avoid using size_t if + you can.

5.7.6. Declare each variable and struct on its + own line.

Explanation:

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;

Instead of:

long a, b, c;

Explanation: - there is more room for comments on the + individual variables - easier to add new variables without + messing up the original ones - when searching on a variable to + find its type, there is less clutter to "visually" + eliminate

Exceptions: when you want to declare a bunch of loop + variables or other trivial variables; feel free to declare them + on 1 line. You should, although, provide a good comment on + their functions.

Status: developer-discrection.

5.7.7. Use malloc/zalloc sparingly

Explanation:

Create a local stuct (on the stack) if the variable will + live and die within the context of one function call.

Only "malloc" a struct (on the heap) if the variable's life + will extend beyond the context of one function call.

Example:

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'

Explanation:

If you have to "malloc" an instance, you are responsible for + insuring that the instance is `free'd, even if the deallocation + event falls within some other programmer's code. You are also + responsible for ensuring that deletion is timely (i.e. not too + soon, not too late). This is known as "low-coupling" and is a + "good thing (tm)". You may need to offer a + free/unload/destuctor type function to accomodate this.

Example:

int load_re_filterfile( struct client_state *csp ) { ... }
+static void unload_re_filterfile( void *f ) { ... }

Exceptions:

The developer cannot be expected to provide `free'ing + functions for C run-time library functions ... such as + `strdup'.

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

Explanation:

I have ordered all of the "blocker" file code to be in alpha + order. It is easier to add/read new blockers when you expect a + certain order.

Note: It may appear that the alpha order is broken in + places by POPUP tests coming before PCRS tests. But since + POPUPs can also be referred to as KILLPOPUPs, it is clear that + it should come first.

5.7.10. "Uncertain" new code and/or changes to + exitinst code, use FIXME

Explanation:

If you have enough confidence in new code or confidence in + your changes, but are not *quite* sure of the reprocussions, + add this:

/* FIXME: this code has a logic error on platform XYZ, * + attempthing to fix */ #ifdef PLATFORM ...changed code here... + #endif

or:

/* FIXME: I think the original author really meant this... + */ ...changed code here...

or:

/* FIXME: new code that *may* break something else... */ + ...new code here...

Note: If you make it clear that this may or may not + be a "good thing (tm)", it will be easier to identify and + include in the project (or 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 $";
+/*********************************************************************
+ *
+ * File        :  $Source$
+ *
+ * Purpose     :  (Fill me in with a good description!)
+ *
+ * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
+ *                Privoxy team. http://www.privoxy.org/
+ *
+ *                Based on the Internet Junkbuster originally written
+ *                by and Copyright (C) 1997 Anonymous Coders and
+ *                Junkbusters Corporation.  http://www.junkbusters.com
+ *
+ *                This program is free software; you can redistribute it
+ *                and/or modify it under the terms of the GNU General
+ *                Public License as published by the Free Software
+ *                Foundation; either version 2 of the License, or (at
+ *                your option) any later version.
+ *
+ *                This program is distributed in the hope that it will
+ *                be useful, but WITHOUT ANY WARRANTY; without even the
+ *                implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *                PARTICULAR PURPOSE.  See the GNU General Public
+ *                License for more details.
+ *
+ *                The GNU General Public License should be included with
+ *                this file.  If not, you can view it at
+ *                http://www.gnu.org/copyleft/gpl.html
+ *                or write to the Free Software Foundation, Inc., 59
+ *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+ *
+ * Revisions   :
+ *    $Log$
+ *
+ *********************************************************************/
+
+
+#include "config.h"
+
+   ...necessary include files for us to do our work...
+
+const char FILENAME_h_rcs[] = FILENAME_H_VERSION;

Note: This declares the rcs variables that should be + added to the "show-proxy-args" page. If this is a brand new + creation by you, you are free to change the "Copyright" section + to represent the rights you wish to maintain.

Note: The formfeed character that is present right + after the comment flower box is handy for (X|GNU)Emacs users to + skip the verbige and get to the heart of the code (via + `forward-page' and `backward-page'). Please include it if you + can.

Example for file header comments:

#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 $"
+/*********************************************************************
+ *
+ * File        :  $Source$
+ *
+ * Purpose     :  (Fill me in with a good description!)
+ *
+ * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
+ *                Privoxy team. http://www.privoxy.org/
+ *
+ *                Based on the Internet Junkbuster originally written
+ *                by and Copyright (C) 1997 Anonymous Coders and
+ *                Junkbusters Corporation.  http://www.junkbusters.com
+ *
+ *                This program is free software; you can redistribute it
+ *                and/or modify it under the terms of the GNU General
+ *                Public License as published by the Free Software
+ *                Foundation; either version 2 of the License, or (at
+ *                your option) any later version.
+ *
+ *                This program is distributed in the hope that it will
+ *                be useful, but WITHOUT ANY WARRANTY; without even the
+ *                implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *                PARTICULAR PURPOSE.  See the GNU General Public
+ *                License for more details.
+ *
+ *                The GNU General Public License should be included with
+ *                this file.  If not, you can view it at
+ *                http://www.gnu.org/copyleft/gpl.html
+ *                or write to the Free Software Foundation, Inc., 59
+ *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+ *
+ * Revisions   :
+ *    $Log$
+ *
+ *********************************************************************/
+
+
+#include "project.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+   ... function headers here ...
+
+
+/* Revision control strings from this header and associated .c file */
+extern const char FILENAME_rcs[];
+extern const char FILENAME_h_rcs[];
+
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* ndef _FILENAME_H */
+
+/*
+  Local Variables:
+  tab-width: 3
+  end:
+*/

Example for function comments:

/*********************************************************************
+ *
+ * Function    :  FUNCTION_NAME
+ *
+ * Description :  (Fill me in with a good description!)
+ *
+ * parameters  :
+ *          1  :  param1 = pointer to an important thing
+ *          2  :  x      = pointer to something else
+ *
+ * Returns     :  0 => Ok, everything else is an error.
+ *
+ *********************************************************************/
+int FUNCTION_NAME( void *param1, const char *x )
+{
+   ...
+   return( 0 );
+
+}

Note: If we all follow this practice, we should be + able to parse our code to create a "self-documenting" web + page.

PrevHomeNext
Documentation Guidelines Version Control Guidelines
\ No newline at end of file diff --git a/doc/webserver/developer-manual/contact.html b/doc/webserver/developer-manual/contact.html new file mode 100644 index 00000000..2e312f5e --- /dev/null +++ b/doc/webserver/developer-manual/contact.html @@ -0,0 +1,223 @@ +Contacting the developers, Bug Reporting and Feature Requests
Privoxy Developer Manual
PrevNext

9. Contacting the developers, Bug Reporting and Feature Requests

We value your feedback. However, to provide you with the best support, please + note: + +

PrevHomeNext
Releasing a new version Copyright and History
\ No newline at end of file diff --git a/doc/webserver/developer-manual/copyright.html b/doc/webserver/developer-manual/copyright.html new file mode 100644 index 00000000..58f57325 --- /dev/null +++ b/doc/webserver/developer-manual/copyright.html @@ -0,0 +1,211 @@ +Copyright and History
Privoxy Developer Manual
PrevNext

10. Copyright and History

10.1. Copyright

Privoxy is free software; you can + redistribute it and/or modify it under the terms of the GNU General Public + + License as published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details, which is available from the Free Software Foundation, Inc, 59 + Temple Place - Suite 330, Boston, MA 02111-1307, USA.

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 is evolved, and derived from, + the Internet Junkbuster, with many + improvments and enhancements over the original.

Junkbuster was originally written by Anonymous + Coders and Junkbuster's + Corporation, and was released as free open-source software under the + GNU GPL. Stefan + Waldherr made many improvements, and started the SourceForge project + Privoxy to rekindle development. There are now several active + developers contributing. The last stable release of + Junkbuster was v2.0.2, which has now + grown whiskers ;-).

PrevHomeNext
Contacting the developers, Bug Reporting and Feature Requests See also
\ No newline at end of file diff --git a/doc/webserver/developer-manual/cvs.html b/doc/webserver/developer-manual/cvs.html new file mode 100644 index 00000000..7b41c56e --- /dev/null +++ b/doc/webserver/developer-manual/cvs.html @@ -0,0 +1,135 @@ +Version Control Guidelines
Privoxy Developer Manual
PrevNext

6. Version Control Guidelines

To be filled. note on cvs comments. Don't only comment what you did, + but also why you did it!

PrevHomeNext
Coding Guidelines Testing Guidelines
\ No newline at end of file diff --git a/doc/webserver/developer-manual/documentation.html b/doc/webserver/developer-manual/documentation.html new file mode 100644 index 00000000..0ab7ad12 --- /dev/null +++ b/doc/webserver/developer-manual/documentation.html @@ -0,0 +1,779 @@ +Documentation Guidelines
Privoxy Developer Manual
PrevNext

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 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.) +

Formal documents are built with the Makefile targets of + make dok, or alternately + make redhat-dok. If you have problems, + try both. The build process uses the document SGML sources in + doc/source to update all text files in + doc/text and to update all HTML + documents in doc/webserver. +

Documentation writers should please make sure documents build + successfully before committing to CVS. +

How do you update the webserver (i.e. the pages on privoxy.org)? + +

  1. First, build the docs by running make + dok (or alternately make + redhat-dok). +

  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.

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.

Our documents use "sections" for the most part. Sections + will be processed into HTML headers (e.g. h1 for + sect1). The Docbook stylesheets + will use these to also generate the Table of Contents for each doc. Our + TOC's are set to a depth of three. Meaning sect1, + sect2, and sect3 will have TOC + entries, but sect4 will not. Each section requires + a <title> element, and at least one + <para>. There is a limit of five section + levels in Docbook, but generally three should be sufficient for our + purposes.

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. +
<filename></filename>, files and directories. +
<command></command>, command examples. +
<literallayout></literllayout>, like + <pre>, more or less. +
<itemizedlist></itemizdelist>, list with bullets. +
<listitem></listitem>, member of the above. +
<screen></screen>, screen output, implies + <literallayout>. +
<ulink url="example.com"></ulink>, like + HTML <a> tag. +
<quote></quote>, for, doh, quoting text. +

Look at any of the existing docs for examples of all these and more.

4.2. Privoxy Documentation Style

It will be easier if everyone follows a similar writing style. This + just makes it easier to read what someone else has written if it + is all done in a similar fashion. +

Here it is: +

  • All tags should be lower case. +

  • Tags delimiting a block of text should be on their own line. + Like: +

     <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.
    +       

    +

  • Tags should be nested and step indented like: +

     <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 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. +

  • 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 + 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 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">here</ulink>. +

    This will render as "My favorite site is here", which is + not real helpful in a text doc. Better like this: +

    My favorite site is <ulink url="http://example.com">example.com</ulink>. +

  • 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 + documentation maintenance. +

We are using a set of "boilerplate" files with generic text, + that is used by multiple docs. This way we can write something once, and use + it repeatedly without having to re-write the same content over and over again. + If editing such a file, keep in mind that it should be + generic. That is the purpose; so it can be used in varying + contexts without additional modifications. +

We are also using what Docbook calls + "internal entities". These are like variables in + programming. Well, sort of. For instance, we have the + p-version entity that contains the current + Privoxy version string. You are strongly + encouraged to use these where possible. Some of these obviously + require re-setting with each release. A sampling of custom entities are + listed below. See any of the main docs for examples. +

  • Re-cyclable "boilerplate" text entities are defined like: +

    <!entity supported SYSTEM "supported.sgml"> +

    In this example, the contents of the file, + supported.sgml is available for inclusion anywhere + in the doc. To make this happen, just reference the now defined + entity: &supported; (starts with an ampersand + and ends with a semi-colon), and the contents will be dumped into + the finished doc at that point. +

  • Commonly used "internal entities": +

    p-version: the Privoxy + version string, e.g. "2.9.13". +
    p-status: the project status, either + "ALPHA", "BETA", or "STABLE". +
    p-not-stable: use to conditionally include + text in "not stable" releases (e.g. "BETA"). +
    p-stable: just the opposite. +
    p-text: this doc is only generated as text. +

+

There are others in various places that are defined for a specific + purpose. Read the source! +

PrevHomeNext
Quickstart to Privoxy Development Coding Guidelines
\ No newline at end of file diff --git a/doc/webserver/developer-manual/index.html b/doc/webserver/developer-manual/index.html new file mode 100644 index 00000000..b7f88427 --- /dev/null +++ b/doc/webserver/developer-manual/index.html @@ -0,0 +1,654 @@ +Privoxy Developer Manual

Privoxy Developer Manual

By: Privoxy Developers

$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 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. +

Privoxy is a web proxy with advanced filtering + capabilities for protecting privacy, filtering web page content, managing + cookies, controlling access, and removing ads, banners, pop-ups and other + obnoxious Internet junk. Privoxy has a very + flexible configuration and can be customized to suit individual needs and + tastes. Privoxy has application for both + stand-alone systems and multi-user networks.

Privoxy is based on the code of the + Internet Junkbuster (tm). + Junkbuster was originally written by JunkBusters + Corporation, and was released as free open-source software under the GNU GPL. + Stefan Waldherr made many improvements, and started the SourceForge project + to continue development.

Privoxy continues the + Junkbuster tradition, but adds many + refinements, enhancements and new features.

You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/. + Please see the Contact section on how to contact the developers.

Table of Contents
1. Introduction
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.4. Comment each logical step
5.2.5. Comment All Functions Thoroughly
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.4. Use white space freely because it is + free
5.4.5. Don't use white space around structure + operators
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.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.4. Pass and Return by Const Reference
5.6.5. Pass and Return by Value
5.6.6. Names of include files
5.6.7. Provide multiple inclusion + protection
5.6.8. Use `extern "C"` when appropriate
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.4. Use 'long' or 'short' Instead of + 'int'
5.7.5. Don't mix size_t and other types
5.7.6. Declare each variable and struct on its + own line.
5.7.7. Use malloc/zalloc sparingly
5.7.8. The Programmer Who Uses 'malloc' is + Responsible for Ensuring 'free'
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.4. OS/2
8.5. Solaris
8.6. Windows
8.7. Debian
8.8. Mac OSX
8.9. FreeBSD
8.10. Tarball
8.11. HP-UX 11
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

  Next
  Introduction
\ No newline at end of file diff --git a/doc/webserver/developer-manual/introduction.html b/doc/webserver/developer-manual/introduction.html new file mode 100644 index 00000000..be712acb --- /dev/null +++ b/doc/webserver/developer-manual/introduction.html @@ -0,0 +1,157 @@ +Introduction
Privoxy Developer Manual
PrevNext

1. Introduction

Privoxy, as an heir to + Junkbuster, is an Open Source project + and licensed under the GPL. As such, Privoxy + development is potentially open to anyone who has the time, knowledge, + and desire to contribute in any capacity. Our goals are simply to + continue the mission, to improve Privoxy, and + to make it available to as wide an audience as possible. +

One does not have to be a programmer to contribute. Packaging, testing, + and porting, are all important jobs as well. +

PrevHomeNext
Privoxy Developer Manual Quickstart to Privoxy Development
\ No newline at end of file diff --git a/doc/webserver/developer-manual/newrelease.html b/doc/webserver/developer-manual/newrelease.html new file mode 100644 index 00000000..48813636 --- /dev/null +++ b/doc/webserver/developer-manual/newrelease.html @@ -0,0 +1,1299 @@ +Releasing a new version
Privoxy Developer Manual
PrevNext

8. Releasing a new version

To minimize trouble with distribution contents, webpage + errors and the like, we strongly encourage you + to follow this section if you prepare a new release of + code or new pages on the webserver. +

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 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 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 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 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 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 able to change them). To update the webserver, create any + pages locally in the doc/webserver directory (or + create new directories under doc/webserver), then do + 

  make webserver
+
+

Note that "make dok" + (or "make redhat-dok") creates + doc/webserver/user-manual, + doc/webserver/developer-manual, + doc/webserver/faq and + doc/webserver/man-page automatically. +

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

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

first. + 

  autoheader && autoconf && ./configure
+
+

Then do + 

  make suse-dist or make redhat-dist
+
+

To upload the package to Sourceforge, simply issue + 

  make suse-upload or make redhat-upload
+
+

Go to the displayed URL and release the file publicly on Sourceforge. +

8.4. OS/2

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+  cd ..
+  cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+
+

You will need a mix of development tools. + The main compilation takes place with IBM Visual Age C++. + Some ancillary work takes place with GNU tools, available from + various sources like hobbes.nmsu.edu. + Specificially, you will need autoheader, + autoconf and sh tools. + The packaging takes place with WarpIN, available from various sources, including + its home page: xworkplace. +

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

Login to Sourceforge's compilefarm via ssh + 

  ssh cf.sourceforge.net
+
+

Choose the right operating system (not the Debian one). If you have + downloaded Privoxy before, + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

If not, please checkout + Privoxy via CVS first. Run: + 

  autoheader && autoconf && ./configure
+
+

Then run + 

  gmake solaris-dist
+
+

which creates a gzip'ed tar archive. Sadly, you cannot use make + solaris-upload on the Sourceforge machine (no ncftpput). You now have + to manually upload the archive to Sourceforge's ftp server and release + the file publicly. +

8.6. Windows

Ensure that you have the latest code version. Hence run + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

Run: + 

  autoheader && autoconf && ./configure
+
+

Then do FIXME. +

8.7. Debian

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

first. Run: + 

  autoheader && autoconf && ./configure
+
+

Then do FIXME. +

8.8. Mac OSX

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+  cd ..
+  cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
+
+

From the osxsetup directory, run: + 
  build
+
+

This will run autoheader, autoconf and + configure as well as make. + Finally, it will copy over the necessary files to the ./osxsetup/files directory + for further processing by PackageMaker. +

Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package + name to match the release, and hit the "Create package" button. + If you specify ./Privoxy.pkg as the output package name, you can then create + the distributable zip file with the command: + 
zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
+
+ 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: + 

  ssh cf.sourceforge.net
+
+

Choose the right operating system. If you have downloaded Privoxy + before, + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

If not, please checkout + Privoxy via CVS first. Run: + 

  autoheader && autoconf && ./configure
+
+

Then run: + 

  gmake freebsd-dist
+
+

which creates a gzip'ed tar archive. Sadly, you cannot use make + freebsd-upload on the Sourceforge machine (no ncftpput). You now have + to manually upload the archive to Sourceforge's ftp server and release + the file publicly. +

8.10. Tarball

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

first. Run: + 

  make clobber
+  autoheader && autoconf && ./configure
+
+

Then do: + 

  make tarball-dist
+
+

To upload the package to Sourceforge, simply issue + 

  make tarball-upload
+
+

Goto the displayed URL and release the file publicly on Sourceforge. +

8.11. HP-UX 11

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

first. Run: + 

  autoheader && autoconf && ./configure
+
+

Then do FIXME. +

8.12. Amiga OS

Ensure that you have the latest code version. Hence run: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

first. Run: + 

  autoheader && autoconf && ./configure
+
+

Then do FIXME. +

8.13. AIX

Login to Sourceforge's compilefarm via ssh: + 

  ssh cf.sourceforge.net
+
+

Choose the right operating system. If you have downloaded Privoxy + before: + 

  cd current
+  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
+
+

If not, please checkout + Privoxy via CVS first. Run: + 

  autoheader && autoconf && ./configure
+
+

Then run: + 

  make aix-dist
+
+

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. +

PrevHomeNext
Testing Guidelines Contacting the developers, Bug Reporting and Feature Requests
\ No newline at end of file diff --git a/doc/webserver/developer-manual/quickstart.html b/doc/webserver/developer-manual/quickstart.html new file mode 100644 index 00000000..f2b39a2b --- /dev/null +++ b/doc/webserver/developer-manual/quickstart.html @@ -0,0 +1,174 @@ +Quickstart to Privoxy Development
Privoxy Developer Manual
PrevNext

3. Quickstart to Privoxy Development

You'll need an account on Sourceforge to support our development. +Mail your ID to the list and wait until a project manager has added you.

For the time being (read, this section is under construction), please note the +following guidelines for changing stuff in the code. If it is +

  1. A bugfix / clean-up / cosmetic thing: shoot +

  2. A new feature that can be turned off: shoot +

  3. A clear improvement w/o side effects on other parts of the code: shoot +

  4. A matter of taste: ask the list +

  5. A major redesign of some part of the code: ask the list +

+

PrevHomeNext
Introduction Documentation Guidelines
\ No newline at end of file diff --git a/doc/webserver/developer-manual/seealso.html b/doc/webserver/developer-manual/seealso.html new file mode 100644 index 00000000..9f313449 --- /dev/null +++ b/doc/webserver/developer-manual/seealso.html @@ -0,0 +1,286 @@ +See also
Privoxy Developer Manual
Prev 

11. See also

Other references and sites of interest to Privoxy + users:

http://www.privoxy.org/, + The Privoxy Home page. +

+

http://sourceforge.net/projects/ijbswa, + the Project Page for Privoxy on + Sourceforge. +

+

http://p.p/, access + Privoxy from your browser. Alternately, + http://config.privoxy.org + may work in some situations where the first does not. +

+

http://www.junkbusters.com/ht/en/cookies.html +

+

http://www.waldherr.org/junkbuster/ +

+

http://privacy.net/analyze/ +

+

http://www.squid-cache.org/ +

PrevHome 
Copyright and History  
\ No newline at end of file diff --git a/doc/webserver/developer-manual/testing.html b/doc/webserver/developer-manual/testing.html new file mode 100644 index 00000000..d219407d --- /dev/null +++ b/doc/webserver/developer-manual/testing.html @@ -0,0 +1,248 @@ +Testing Guidelines
Privoxy Developer Manual
PrevNext

7. Testing Guidelines

To be filled.

7.1. Testplan for releases

Explain release numbers. major, minor. developer releases. etc. + +

  1. Remove any existing rpm with rpm -e

  2. Remove any file that was left over. This includes (but is not limited to) +

    • /var/log/privoxy

    • /etc/privoxy

    • /usr/sbin/privoxy

    • /etc/init.d/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/privoxy stop). Reboot your machine. Does + autostart work?

  5. Start browsing. Does Privoxy work? Logfile written?

  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 group: the version of Privoxy that we are about to release.

  • Fill the Summary and Detailed Description with something + intelligent (keep it short and precise).

+ Do not mail to the mailinglist (we cannot keep track on issues there). +

PrevHomeNext
Version Control Guidelines Releasing a new version
\ No newline at end of file diff --git a/doc/webserver/faq/configuration.html b/doc/webserver/faq/configuration.html new file mode 100644 index 00000000..339b7629 --- /dev/null +++ b/doc/webserver/faq/configuration.html @@ -0,0 +1,1111 @@ +Configuration
Privoxy Frequently Asked Questions
PrevNext

3. Configuration

3.1. Can I use my old config files?

There are major changes to Junkbuster/ + Privoxy configuration from version 2.0.x to + 2.9.x and later. Most of the older files will not work at all. This is + especially true of blocklist. If this is the case, you + will need to re-enter your old data into the new configuration structure. + This is probably also a good recommendation even if upgrading from 2.9.x to + 3.x since there were many minor changes along the way. +

3.2. What is an "actions" file?

"actions" files are where various actions that + Privoxy might take, are configured. + Typically, you would define a set of default actions that apply + to all URLs, then add exceptions to these defaults.

Actions can be defined on a per site basis, or for groups of sites. Actions + can also be grouped together and then applied to one or more sites. There + are many possible actions that might apply to any given site. As an example, + if we are blocking cookies as one of our default + actions, but need to accept cookies from a given + site, we would define this in our "actions" file.

Privoxy comes with several default + actions files, with varying degrees + of filtering and blocking, as starting points for your own + configuration (see below).

3.3. The "actions" concept confuses me. Please list +some of these "actions".

These are all explained in the + user-manual. + Please refer to that.

3.4. How are actions files configured? What is the easiest +way to do this?

The easiest way to do this, is to access Privoxy + with your web browser at http://p.p/, + and then select + "Edit the actions list" + from the selection list. You can also do this by editing the appropriate + file with a text editor.

Please see the + user-manual for a + detailed explanation of these and other configuration files, and their + various options and syntax.

3.5. What are the differences between +intermediate.action, basic.action, etc.?

Configuring Privoxy is not easy. To help you get +started, we provide you with three different default configurations. The +following table shows you, which features are enabled in each configuration. +

Table 1. Default Configurations

Featuredefault.actionbasic.actionintermediate.actionadvanced.action
ad-filtering?xxx
blank image?xxx
de-animate GIFs?xxx
referer forging?xxx
jon's +no-cookies-keep (i.e. session cookies only)?xxx
no-popup windows? xx
fast redirects? xx
hide-referrer? xx
hide-useragent? xx
content-modification?  x
feature-x?   
feature-y?   
feature-z?   

3.6. Why can I change the configuration with a +browser? Does that not raise security issues?

What I don't understand, is how I can browser edit the config file as a +regular user, while the whole /etc/privoxy hierarchy +belongs to the user "privoxy", with only 644 permissions. +

When you use the browser-based editor, Privoxy +itself is writing to the config files. Because +Privoxy is running as the user "privoxy", it can +update the config files. +

If you don't like this, setting "enable-edit-actions 0" in the +config file will disable the browser-based editor. If you're that paranoid, +you should also consider setting "enable-remote-toggle 0" to prevent +browser-based enabling/disabling of Privoxy. +

Note that normally only local users can connect to +Privoxy, so this is not (normally) a security +problem. +

3.7. What is "default.filter"?

The "default.filter" file is used to "filter" any + web page content. By "filtering" we mean it can modify, remove, + or change anything on the page, including HTML tags, and + JavaScript. Regular expressions are used to accomplish this, and operate + on a line by line basis. This is potentially a very powerful feature, but + requires some expertise.

If you are familiar with regular expressions, and HTML, you can look at + the provided default.filter with a text editor and see + some of things it can be used for.

Presently, there is no GUI editor option for this part of the configuration, + but you can disable/enable various sections of the included default + file with the "Actions List Editor" from your browser.

3.8. How can I set up Privoxy to act as a proxy for my + LAN?

By default, Privoxy only responds to requests + from localhost. To have it act as a server for a network, this needs to be + changed in the main config file where the Privoxy + configuration is located. In that file is a "listen-address" + option. It may be commented out with a "#" symbol. Make sure + it is uncommented, and assign it the address of the LAN gateway interface, + and port number to use:

  listen-address  192.168.1.1:8118
+

Save the file, and restart Privoxy. Configure + all browsers on the network then to use this address and port number.

3.9. Instead of ads, now I get a checkerboard pattern. I don't want to see anything.

This is a configuration option for images that + Privoxy is stopping. You have the choice of a checkerboard + pattern, a transparent 1x1 GIF image (aka "blank"), or a custom + URL of your choice. Note that to fit this category, the URL must match both + the "+image" and "+block" actions.

If you want to see nothing, then change the "+image-blocker" + action to "+image-blocker{blank}". This can be done from the + "Edit Actions List" selection at http://p.p/. Or by hand editing the appropriate + actions file. This will only effect what is defined as "images" + though. Also, some URLs that generate the bright red "Blocked" + banner, can be moved to the "+image-blocker" section for the + same reason, but there are some limits and risks to this (see below).

3.10. Why would anybody want to see a checkerboard pattern?

This can be helpful for troubleshooting problems. It might also be good + for anyone new to Privoxy so that they can + see if their favorite pages are displaying correctly, and + Privoxy is not inadvertently removing something + important.

3.11. I see large red banners on some pages that say +"Blocked". Why and how do I get rid of this?

These are URLs that match something in one of + Privoxy's block actions (+block). It is meant + to be a warning so that you know something has been blocked and an easy way + for you to see why. These are handled differently than what has been defined + explicitly as "images" (e.g. ad banners). Depending on the + URL itself, it is sometimes hard for Privoxy to + really know whether there is indeed an ad image there or not. And there are + limitations as to what Privoxy can do to + "fool" the browser.

For instance, if the ad is in a frame, then it is embedded in the separate + HTML page used for the frame. In this case, you cannot just substitute an + aribitray image (like we would for a "blank" image), for an HTML + page. The browser is expecting an HTML page, and that is what it must have + for frames. So this situation can be a little trickier to deal with, and + Privoxy will use the "Blocked" page.

If you want these to be treated as if they were images, so that they can be + made invisible, you can try moving the offending URL from the + "+block" section to the "+imageblock" section of + your actions file. Just be forewarned, if any URL is made + "invisible", you may not have any inkling that something has + been removed from that page, or why. If this approach does not work, then you are + probably dealing with a frame (or "ilayer"), and the only thing + that can go there is an HTML page of some sort.

To deal with this situation, you could modify the + "block" HTML template that is used by + Privoxy to display this, and make it something + more to your liking. Currently, there is no configuration option for this. + You will have to modify, or create your own page, and use this to replace + templates/blocked, which is what + Privoxy uses to display the "Blocked" + page.

Another way to deal with this is find why and where + Privoxy is blocking the frame, and + diable this. Then let the "+image-blocker" action + handle the ad that is embedded in the frame's HTML page.

3.12. I cannot see all of the "Blocked" page banner. All I +see is a bright red square.

There is not enough space to fit the entire page. Try right clicking on the + visible, red portion, and select "Show Frame", or equivalent. + This will usually allow you to see the entire Privoxy "Blocked" + page, and from there you can see just what is being blocked, and why.

3.13. Can Privoxy run as a service +on Win2K/NT?

Yes, it can run as a system service using srvany.exe. + The only catch is that this will effectively disable the + Privoxy icon in the taskbar. You can have + one or the other, but not both at this time :(

There is a pending feature request for this functionality. See + thread: http://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118, + for details, and a sample configuration.

3.14. How can I make Privoxy work with other +proxies like Squid?

This can be done. See the user manual, + which describes how to do this.

PrevHomeNext
Installation Miscellaneous
\ No newline at end of file diff --git a/doc/webserver/faq/contact.html b/doc/webserver/faq/contact.html new file mode 100644 index 00000000..869d46c0 --- /dev/null +++ b/doc/webserver/faq/contact.html @@ -0,0 +1,223 @@ +Contacting the developers, Bug Reporting and Feature Requests
Privoxy Frequently Asked Questions
PrevNext

7. Contacting the developers, Bug Reporting and Feature Requests

We value your feedback. However, to provide you with the best support, please + note: + +

PrevHomeNext
Troubleshooting Copyright and History
\ No newline at end of file diff --git a/doc/webserver/faq/copyright.html b/doc/webserver/faq/copyright.html new file mode 100644 index 00000000..e1cce0f0 --- /dev/null +++ b/doc/webserver/faq/copyright.html @@ -0,0 +1,202 @@ +Copyright and History
Privoxy Frequently Asked Questions
Prev 

8. Copyright and History

8.1. Copyright

Privoxy is free software; you can + redistribute it and/or modify it under the terms of the GNU General Public + + License as published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details, which is available from the Free Software Foundation, Inc, 59 + Temple Place - Suite 330, Boston, MA 02111-1307, USA.

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.

8.2. History

Privoxy is evolved, and derived from, + the Internet Junkbuster, with many + improvments and enhancements over the original.

Junkbuster was originally written by Anonymous + Coders and Junkbuster's + Corporation, and was released as free open-source software under the + GNU GPL. Stefan + Waldherr made many improvements, and started the SourceForge project + Privoxy to rekindle development. There are now several active + developers contributing. The last stable release of + Junkbuster was v2.0.2, which has now + grown whiskers ;-).

PrevHome 
Contacting the developers, Bug Reporting and Feature Requests  
\ No newline at end of file diff --git a/doc/webserver/faq/general.html b/doc/webserver/faq/general.html new file mode 100644 index 00000000..de198e61 --- /dev/null +++ b/doc/webserver/faq/general.html @@ -0,0 +1,658 @@ +General Information
Privoxy Frequently Asked Questions
PrevNext

1. General Information

1.1. What is this new version of Privoxy?

The original Internet + Junkbuster™ (tm) is a copyrighted product of Junkbusters Corporation. + Development of this effort stopped some time ago as of version 2.0.2. Stefan + Waldherr started the ijbswa project on Sourceforge to + rekindle development. Other developers subsequently joined with Stefan, and + have since added many new features, refinements and enhancements. The result + of this effort is Privoxy. +

Privoxy has evolved from the + Junkbuster 2.0.2 code base, and has advanced + significantly at this point. +

+ Please see the History section for more + information on the history of Junkbuster and + Privoxy. +

1.2. Why "Privoxy"? Why a name change at all?

Privoxy is the + "Privacy Enhancing Proxy".

There are potential legal complications from the continued use of the + Junkbuster name, which is a trademark of + Junkbusters Corporation. + (There are, however, no objections from Junkbusters Corporation to the + Privoxy project itself, and they, in fact, still + share our ideals and goals.)

The developers also believed that there are so many changes from the original + code, that it was time to make a clean break from the past and make + a name in their own right, especially now with the pending + release of version 3.0.

1.3. How does Privoxy differ +from the old Junkbuster?

Privoxy picks up where + Junkbuster left off. All the old features remain. + The new Privoxy still blocks ads and banners, + still manages cookies, and still helps protect your privacy. But, these are + all enhanced, and many new features have been added, all in the same vein. +

The configuration has changed significantly as well. This is something that + users will notice right off the bat if you are upgrading from + Junkbuster 2.0.x. The "blocklist" + file does not exist any more. This is replaced by "actions" + files, such as default.actions. This is where most of + the per site configuration is now. +

1.4. What are some of the new features?

  • Integrated browser based configuration and control utility (http://p.p). Browser-based tracing of rule + and filter effects. +

  • Blocking of annoying pop-up browser windows. +

  • HTTP/1.1 compliant (most, but not all 1.1 features are supported). +

  • Support for Perl Compatible Regular Expressions in the configuration files, and + generally a more sophisticated and flexible configuration syntax over + previous versions. +

  • GIF de-animation. +

  • Web page content filtering (removes banners based on size, + invisible "web-bugs", JavaScript, pop-ups, status bar abuse, + etc.) +

  • Bypass many click-tracking scripts (avoids script redirection). + +

  • Multi-threaded (POSIX and native threads). +

  • Auto-detection and re-reading of config file changes. +

  • User-customizable HTML templates (e.g. 404 error page). +

  • Improved cookie management features (e.g. session based cookies). +

  • Improved signal handling, and a true daemon mode (Unix). +

  • Builds from source on most UNIX-like systems. Packages available for: Linux + (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11 and AmigaOS. + +

  • In addition, the configuration is much more powerful and versatile over-all. +

1.5. What is a "proxy"? How does +Privoxy work?

When you connect to a web site with Privoxy, + you are really connecting to your locally running version of + Privoxy. Privoxy + intercepts your requests for the web page, and relays that to the + "real" web site. The web site sends the HTTP data stream + back to Privoxy, where + Privoxy can work its magic before it + relays this data back to your web browser. +

Since Privoxy sits between you and the + WWW, it is in a position to intercept and completely manage all web traffic and + HTTP content before it gets to your browser. + Privoxy uses various programming methods to do + this, all of which is under your control via the various configuration + files and options. +

There are many kinds of proxies. Privoxy best + fits the "filtering proxy" category. +

1.6. How does Privoxy know what is +an ad, and what is not?

Privoxy processes all the raw content of every + web page. So it reads everything on each page. It then compares this to the + rules as set up in the configuration files, and looks for any matches to + these rules. Privoxy makes heavy use of + "regular expressions". (If you are not familiar with regular + expressions, it is explained briefly in the user manual.) Regular + expressions facilitate matching of one text string against another, using + wildcards to build complex patterns. So Privoxy + will typically look for URLs and other content that match certain key words + and expressions as defined in the configuration files. For instance a URL + that contains "/banners", has a high probability of containing + ad banners, and thus would be a prime candidate to have a matching rule.

So Privoxy will look for these kinds of obvious + looking culprits. And also, will use lists of known organizations that + specialize in ads. Again, using complex patterns to match as many potential + combinations as possible since there tend to be many, many variations used by + advertisers, and new ones are being introduced all the time.

1.7. Can Privoxy make mistakes? +This does not sound very scientific.

Actually, it's a black art ;-) And yes, it is always possible to have a broad rule + accidentally block something by mistake. There is a good chance you may run + into such a situation at some point. It is tricky writing rules to cover + every conceivable possibility, and not occasionally get false positives.

But this should not be a big concern since the + Privoxy configuration is very flexible, and + includes tools to help identify these types of situations so they can be + addressed as needed, allowing you to customize your installation. + (See the Troubleshooting section below.)

1.8. My browser does the same things as +Privoxy. Why should I use +Privoxy at all?

Modern browsers do indeed have some of the same + functionality as Privoxy. Maybe this is + adequate for you. But Privoxy is much more + versatile and powerful, and can do a number of things that browsers just can't. +

In addition, a proxy is good choice if you use multiple browsers, or + have a LAN with multiple computers. This way all the configuration + is in one place, and you don't have to maintain a similar configuration + for possibly many browsers. + +

1.9. Is there is a license or fee? What about a +warranty? Registration?

Privoxy is licensed under the GNU General Public + License (GPL). It is free to use, copy, modify or distribute as you wish + under the terms of this license. Please see the Copyright section for more + information on the license and copyright. + +

There is no warranty of any kind, expressed, implied or otherwise. That is + something that would cost real money ;-) There is no registration either. + Privoxy really is free + in every respect! + +

1.10. I would like to help you, what do I do?

1.10.1. Money Money Money

We, of course, welcome donations and use the money for domain registering, + regular world-wide get-togethers (hahaha). Anyway, we'll soon describe the + process how to donate money to the team.

1.10.2. You want to work with us?

Well, helping the team is always a good idea. We welcome new developers, + RPM gurus or documentation makers. Simply get an account on sourceforge.net + and mail your id to the developer mailing list. Then read the + section Quickstart in the Developer's Manual.

Once we have added you to the team, you'll have write access to the CVS + repository, and together we'll find a suitable task for you.

PrevHomeNext
Privoxy Frequently Asked Questions Installation
\ No newline at end of file diff --git a/doc/webserver/faq/index.html b/doc/webserver/faq/index.html new file mode 100644 index 00000000..2f327d62 --- /dev/null +++ b/doc/webserver/faq/index.html @@ -0,0 +1,688 @@ +Privoxy Frequently Asked Questions

Privoxy Frequently Asked Questions

By: Privoxy Developers

$Id: faq.sgml,v 1.43 2002/04/04 21:59:53 hal9 Exp $

This FAQ gives users and developers alike answers to frequently asked + questions about Privoxy + . +

Privoxy is a web proxy with advanced filtering + capabilities for protecting privacy, filtering web page content, managing + cookies, controlling access, and removing ads, banners, pop-ups and other + obnoxious Internet junk. Privoxy has a very + flexible configuration and can be customized to suit individual needs and + tastes. Privoxy has application for both + stand-alone systems and multi-user networks.

Privoxy is based on the code of the + Internet Junkbuster (tm). + Junkbuster was originally written by JunkBusters + Corporation, and was released as free open-source software under the GNU GPL. + Stefan Waldherr made many improvements, and started the SourceForge project + to continue development.

Privoxy continues the + Junkbuster tradition, but adds many + refinements, enhancements and new features.

You can find the latest version of the document at http://www.privoxy.org/faq/. + Please see the Contact section if you want to contact the developers. +

Table of Contents
1. General Information
1.1. What is this new version of Privoxy?
1.2. Why "Privoxy"? Why a name change at all?
1.3. How does Privoxy differ +from the old Junkbuster?
1.4. What are some of the new features?
1.5. What is a "proxy"? How does +Privoxy work?
1.6. How does Privoxy know what is +an ad, and what is not?
1.7. Can Privoxy make mistakes? +This does not sound very scientific.
1.8. My browser does the same things as +Privoxy. Why should I use +Privoxy at all?
1.9. Is there is a license or fee? What about a +warranty? Registration?
1.10. I would like to help you, what do I do?
1.10.1. Money Money Money
1.10.2. You want to work with us?
2. Installation
2.1. Which browsers are supported by Privoxy?
2.2. Which operating systems are supported?
2.3. Can I install + Privoxy over Junkbuster?
2.4. I just installed Privoxy. Is there anything +special I have to do now?
2.5. What is the proxy address of Privoxy?
2.6. I just installed Privoxy, and nothing is happening. +All the ads are there. What's wrong?
3. Configuration
3.1. Can I use my old config files?
3.2. What is an "actions" file?
3.3. The "actions" concept confuses me. Please list +some of these "actions".
3.4. How are actions files configured? What is the easiest +way to do this?
3.5. What are the differences between +intermediate.action, basic.action, etc.?
3.6. Why can I change the configuration with a +browser? Does that not raise security issues?
3.7. What is "default.filter"?
3.8. How can I set up Privoxy to act as a proxy for my + LAN?
3.9. Instead of ads, now I get a checkerboard pattern. I don't want to see anything.
3.10. Why would anybody want to see a checkerboard pattern?
3.11. I see large red banners on some pages that say +"Blocked". Why and how do I get rid of this?
3.12. I cannot see all of the "Blocked" page banner. All I +see is a bright red square.
3.13. Can Privoxy run as a service +on Win2K/NT?
3.14. How can I make Privoxy work with other +proxies like Squid?
4. Miscellaneous
4.1. How much does Privoxy slow my browsing down? This +has to add extra time to browsing.
4.2. I noticed considerable +delays in page requests compared to the old Junkbuster. What's wrong?
4.3. What is the "http://p.p/"?
4.4. Do you still maintain the blocklists?
4.5. How can I submit new ads?
4.6. How can I hide my IP address?
4.7. Can Privoxy guarantee I am anonymous?
4.8. Might some things break because header information is +being altered?
4.9. Can Privoxy act as a "caching" proxy to +speed up web browsing?
4.10. What about as a firewall? Can Privoxy protect me?
4.11. The Privoxy logo that replaces ads is very blocky +and ugly looking. Can't a better font be used?
4.12. I have large empty spaces now where ads used to be. +Why?
4.13. How can Privoxy filter Secure (HTTPS) URLs?
4.14. Privoxy runs as a "server". How +secure is it? Do I need to take any special precautions?
4.15. How can I temporarily disable Privoxy?
4.16. Where can I find more information about Privoxy +and related issues?
5. Troubleshooting
5.1. I just upgraded and am getting "connection refused" +with every web page?
5.2. I just added a new rule, but the steenkin ad is +still getting through. How?
5.3. One of my favorite sites does not work with Privoxy. +What can I do?
5.4. Where can I get help? Report bugs? Feature Requests? Etc?
5.5. What time is it?
7. Contacting the developers, Bug Reporting and Feature Requests
8. Copyright and History
8.1. Copyright
8.2. History

  Next
  General Information
\ No newline at end of file diff --git a/doc/webserver/faq/installation.html b/doc/webserver/faq/installation.html new file mode 100644 index 00000000..8b946711 --- /dev/null +++ b/doc/webserver/faq/installation.html @@ -0,0 +1,379 @@ +Installation
Privoxy Frequently Asked Questions
PrevNext

2. Installation

2.1. Which browsers are supported by Privoxy?

Any browser that can be configured to use a "proxy", which + should be virtually all browsers. Direct browser support is not necessary + since Privoxy runs as a separate application and + just exchanges standard HTML data with your browser, just like a web server + does.

2.2. Which operating systems are supported?

At present, Privoxy is known to run on Win32, Mac + OSX, OS/2, AmigaOS, Linux (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.

But any operating system that runs TCP/IP, can conceivably take advantage of + Privoxy in a networked situation where + Privoxy would run as a server on a LAN gateway. + Then only the "gateway" needs to be running one of the above + operating systems.

Source code is freely available, so porting to other operating systems, + is always a possibility.

2.3. Can I install + Privoxy over Junkbuster?

We recommend you uninstall Junkbuster + first to minimize conflicts and confusion. You may want to + save your old configuration files for future reference. The configuration + is substantially changed. +

See the user-manual for + platform specific installation instructions. +

Note: Some installers may automatically uninstall + Junkbuster, if present! +

2.4. I just installed Privoxy. Is there anything +special I have to do now?

All browsers must be told to use Privoxy + as a proxy by specifying the correct proxy address and port number + in the appropriate configuration area for the browser. See below. + Also, you should flush your browser's memory and disk cache to get rid of any + cached items.

2.5. What is the proxy address of Privoxy?

If you set up the Privoxy to run on + the computer you browse from (rather than your ISP's server or some + networked computer on a LAN), the proxy will be on "localhost" + (which is the special name used by every computer on the Internet to refer + to itself) and the port will be 8118 (unless you have Privoxy to run on a different port with the + listen-address config option). +

When configuring your browser's proxy settings you typically enter + the word "localhost" in the boxes next to "HTTP" + and "Secure" (HTTPS) and then the number "8118" + for "port". This tells your browser to send all web + requests to Privoxy instead of directly to the + Internet. +

Privoxy can also be used to proxy for + a Local Area Network. In this case, your would enter either the IP + address of the LAN host where Privoxy + is running, or the equivalent hostname. Port assignment would be + same as above. +

Privoxy does not currently handle + protocols such as FTP, SMTP, IM, IRC, ICQ, or other Internet + protocols. +

2.6. I just installed Privoxy, and nothing is happening. +All the ads are there. What's wrong?

Did you configure your browser to use Privoxy + as a proxy? It does not sound like it. See above. You might also try flushing + the browser's caches to force a full re-reading of pages. You can verify + that Privoxy is running, and your browser + is correctly configured by entering the special URL: + http://p.p/. This should give you + a banner that says "This is Privoxy" and + access to Privoxy's internal configuration. + If you see this, then you are good to go. If not, the browser or + Privoxy are not set up correctly.

PrevHomeNext
General Information Configuration
\ No newline at end of file diff --git a/doc/webserver/faq/misc.html b/doc/webserver/faq/misc.html new file mode 100644 index 00000000..9bed737b --- /dev/null +++ b/doc/webserver/faq/misc.html @@ -0,0 +1,803 @@ +Miscellaneous
Privoxy Frequently Asked Questions
PrevNext

4. Miscellaneous

4.1. How much does Privoxy slow my browsing down? This +has to add extra time to browsing.

It should not slow you down any in real terms, and may actually help + speed things up since ads, banners and other junk are not being displayed. + The actual processing time required by Privoxy + itself for each page, is relatively small in the overall scheme of things, + and happens very quickly. This is typically more than offset by time saved + not downloading and rendering ad images.

"Filtering" via the filterfile + mechanism may cause a perceived slowdown, since the entire page is buffered + before displaying. See below.

4.2. I noticed considerable +delays in page requests compared to the old Junkbuster. What's wrong?

Using the default filtering configuration, I noticed considerable delays in +page requests compared to the old Junkbuster. Loading pages with large contents +seemed to take forever, then suddenly delivering all the content at once. +

The whole content must be loaded in order to filter, and nothing is is +sent to the browser during this time. The loading time does not really +change in real numbers, but the feeling is different, because most +browsers are able to start rendering incomplete content, giving the +user a feeling of "it works". +

To modify the content of a page (i.e. make frames resizeable again, etc.) and +not just replace ads, Privoxy needs to download the +entire page first, do its content magic and then send the page to the browser.

4.3. What is the "http://p.p/"?

Since Privoxy sits between your web browser and the Internet, it can be +programmed to handle certain pages specially.

With recent versions of Privoxy (version 2.9.x), you can get some +information about Privoxy and change some settings by going to +http://p.p/ or, equivalently, http://config.privoxy.org/ +(Note that p.p is far easier to type but may not work in some +configurations. With the name change to Privoxy, +this is changed from the previous http://i.j.b/ or earlier 2.9.x versions).

These pages are not forwarded to a server on the Internet +- instead they are handled by a special web server which is built in to +Privoxy.

If you are not running Privoxy, then http://p.p/ will fail, and http://config.privoxy.org/ will +return a web page telling you you're not running +Privoxy.

If you have version 2.0.2, then the equivalent is +http://example.com/show-proxy-args (but you get far less information, and you +should really consider upgrading to 2.9.13).

4.4. Do you still maintain the blocklists?

No. The format of the blocklists has changed significantly in versions + 2.9.x and later. Once we have released the new stable + version, v3.0, there will again be blocklists that you can update + automatically.

4.5. How can I submit new ads?

As of now, please discontinue to submit new ad blocking infos. Once we + have released the new version, there will again be a form on the website, + which you can use to contribute new ads.

4.6. How can I hide my IP address?

You cannot hide your IP address with Privoxy or any other software, since +the server needs to know your IP address to send the answer to you.

Fortunately there are many publicly usable anonymous proxies out there, which +solve the problem by providing a further level of indirection between you and +the web server, shared by many people and thus letting your requests "drown" +in white noise of unrelated requests as far as user tracking is concerned.

Most of them will, however, log your IP address and make it available to the +authorities in case you abuse that anonymity for criminal purposes. In fact +you can't even rule out that some of them only exist to *collect* information +on (those suspicious) people with a more than average preference for privacy.

You can find a list of anonymous public proxies at multiproxy.org and many +more through Google.

4.7. Can Privoxy guarantee I am anonymous?

No. Your chances of remaining anonymous are greatly improved, but unless you + are an expert on Internet security it would be safest to assume that + everything you do on the Web can be traced back to you.

Privoxy can remove various information about you, + and allows you more freedom to decide which sites + you can trust, and what details you want to reveal. But it's still possible + that web sites can find out who you are. Here's one way this can happen.

A few browsers disclose the user's email address in certain situations, such + as when transferring a file by FTP. Privoxy + does not filter FTP. If you need this feature, or are concerned about the + mail handler of your browser disclosing your email address, you might + consider products such as NSClean.

Browsers available only as binaries could use non-standard headers to give + out any information they can have access to: see the manufacturer's license + agreement. It's impossible to anticipate and prevent every breach of privacy + that might occur. The professionally paranoid prefer browsers available as + source code, because anticipating their behavior is easier. Trust the source, + Luke!

4.8. Might some things break because header information is +being altered?

Definitely. More and more sites use HTTP header content to decide what to + display and how to display it. There is many ways that this can be handled, + so having hard and fast rules, is tricky.

"USER AGENT" in particular is often used in this way to identify + the browser, and adjust content accordingly. Changing this now is not + recommended, since so many sites do look for this. You may get undesirable + results by changing this.

For instance, different browsers use different encodings of Russian and Czech + characters, certain web servers convert pages on-the-fly according to the + User Agent header. Giving a "User Agent" with the wrong + operating system or browser manufacturer causes some sites in these languages + to be garbled; Surfers to Eastern European sites should change it to + something closer. And then some page access counters work by looking at the + "REFERER" header; they may fail or break if unavailable. The + weather maps of Intellicast have been blocked by their server when no + "REFERER" or cookie is provided, is another example. There are + many, many other ways things can go wrong when trying to fool a web server.

If you have problems with a site, you will have to adjust your configuration + accordingly. Cookies are probably the most likely adjustment that may + be required, but by no means the only one.

4.9. Can Privoxy act as a "caching" proxy to +speed up web browsing?

No, it does not have this ability at all. You want something like + Squid for this. And, yes, + before you ask, Privoxy can co-exist + with other kinds of proxies like Squid.

4.10. What about as a firewall? Can Privoxy protect me?

Not in the way you mean, or in the way a true firewall can, or a proxy that + has this specific capability. Privoxy can help + protect your privacy, but not really protect you from intrusion attempts.

4.11. The Privoxy logo that replaces ads is very blocky +and ugly looking. Can't a better font be used?

This is not a font problem. The logo is an image that is created by + Privoxy on the fly. So as to not waste + memory, the image is rather small. The blockiness comes when the + image is scaled to fill a largish area. There is not much to be done + about this, other than to use one of the other + "imageblock" directives: pattern, + blank, or a URL of your choosing.

Given the above problem, we have decided to remove the logo option entirely +[as of v2.9.13].

4.12. I have large empty spaces now where ads used to be. +Why?

It would be easy enough to just eliminate this space altogether, rather than + fill it with blank space. But, this would create problems with many pages + that use the overall size of the ad to help organize the page layout and + position the various components of the page where they were intended to be. + It is best left this way.

4.13. How can Privoxy filter Secure (HTTPS) URLs?

This is a limitation since HTTPS transactions are encrypted SSL sessions + between your browser and the secure site, and are meant to be reliably + secure and private. This means that all cookies and HTTP + header information are also encrypted from the time they leave your browser, + to the site, and vice versa. Privoxy does not + try to unencrypt this information, so it just passes through as is. + Privoxy can still catch images and ads that + are embedded in the SSL stream though.

4.14. Privoxy runs as a "server". How +secure is it? Do I need to take any special precautions?

There are no known exploits that might effect + Privoxy. On Unix-like systems, + Privoxy can run as a non-privileged + user, which is how we recommend it be run. Also, by default + Privoxy only listens to requests + from "localhost". The server aspect of + Privoxy is not itself directly exposed to the + Internet in this configuration. If you want to have + Privoxy serve as a LAN proxy, this will have to + be opened up to allow for LAN requests. In this case, we'd recommend + you specify only the LAN gateway address, e.g. 192.168.1.1, in the main + Privoxy config file. All LAN hosts can then use + this as their proxy address in the browser proxy configuration. In this way, + Privoxy will not listen on any external ports. + Of course, a firewall is always good too. Better safe than sorry.

4.15. How can I temporarily disable Privoxy?

The easiest way is to access Privoxy with your + browser by using the special URL: http://p.p/ + and select "Toggle Privoxy on or off" from that page.

4.16. Where can I find more information about Privoxy +and related issues?

Other references and sites of interest to Privoxy + users:

http://www.privoxy.org/, + The Privoxy Home page. +

+

http://sourceforge.net/projects/ijbswa, + the Project Page for Privoxy on + Sourceforge. +

+

http://p.p/, access + Privoxy from your browser. Alternately, + http://config.privoxy.org + may work in some situations where the first does not. +

+

http://www.junkbusters.com/ht/en/cookies.html +

+

http://www.waldherr.org/junkbuster/ +

+

http://privacy.net/analyze/ +

+

http://www.squid-cache.org/ +

PrevHomeNext
Configuration Troubleshooting
\ No newline at end of file diff --git a/doc/webserver/faq/trouble.html b/doc/webserver/faq/trouble.html new file mode 100644 index 00000000..732b1b7d --- /dev/null +++ b/doc/webserver/faq/trouble.html @@ -0,0 +1,329 @@ +Troubleshooting
Privoxy Frequently Asked Questions
PrevNext

5. Troubleshooting

5.1. I just upgraded and am getting "connection refused" +with every web page?

Either Privoxy is not running, or your + browser is configured for a different port than what + Privoxy is using.

The old Privoxy (and also + Junkbuster) used port 8000 by + default. This has been changed to port 8118 now, due to a conflict + with NAS (Network Audio Service), which uses port 8000. If you haven't, + you need to change your browser to the new port number, or alternately + change Privoxy's "listen-address" + setting in the config file used to start + Privoxy.

5.2. I just added a new rule, but the steenkin ad is +still getting through. How?

If the ad had been displayed before you added its URL, it will probably be + held in the browser's cache for some time, so it will be displayed without + the need for any request to the server, and Privoxy + will not be in the picture. The best thing to do is try flushing the browser's + caches. And then try again.

If this doesn't help, you probably have an error in the rule you + applied. Try pasting the full URL of the offending ad into http://config.privoxy.org/show-url-info + and see if any actions match your new rule.

5.3. One of my favorite sites does not work with Privoxy. +What can I do?

First verify that it is indeed a Privoxy problem, + by disabling Privoxy filtering and blocking. + Go to http://p.p/ and click on + "Toggle Privoxy On or Off", then disable it. Now try that + page again. It's probably a good idea to flush the browser cache as well.

If still a problem, go to "Show which actions apply to a URL and + why" from http://p.p/ and paste + the full URL of the page in question into the prompt. See which actions are + being applied to the URL. Now, armed with this information, go to "Edit + the actions list". Here you should see various sections that have + various Privoxy features disabled for specific + sites. Most disabled "actions" will have a "-" (minus + sign) in front of them. Some aliases are used just to disable other actions, + e.g. "shop" and "fragile", and won't necessarily + use a "+" or "-" sign. Add your problem page + URL to one of these sections that looks like it is disabling the feature that + is causing the problem. Rember to flush your browser's caches when making + such changes! As a last resort, try "fragile" which + disables most actions. Now re-try the page. There might be some trial and + error involved. This is discussed in a little more detail in the user-manual appendix.

Alternately, if you are comfortable with a text editor, you can accomplish + the same thing by editing the appropriate "actions" file.

5.4. Where can I get help? Report bugs? Feature Requests? Etc?

Feedback is encouraged, whether good, bad or ugly. Please see the contact + page in the user-manual for + details.

5.5. What time is it?

Time for you to go!

PrevHomeNext
Miscellaneous Contacting the developers, Bug Reporting and Feature Requests
\ No newline at end of file diff --git a/doc/webserver/man-page/privoxy-man-page.html b/doc/webserver/man-page/privoxy-man-page.html new file mode 100644 index 00000000..167822ee --- /dev/null +++ b/doc/webserver/man-page/privoxy-man-page.html @@ -0,0 +1,343 @@ +Privoxy Man page

NAME

+
+
+       privoxy - Privacy enhancing Proxy
+
+
+
+

SYNOPSIS

+       privoxy [--help] [--version] [--no-daemon] [--pidfile pid­
+       file] [--user user[.group]] [configfile] (Unix)
+
+       privoxy.exe [configfile] (Windows)
+
+
+
+
+

OPTIONS

+       Privoxy may be invoked  with  the  following  command-line
+       options:
+
+       --version (unix only)
+              Print version info and exit.
+
+       --help (unix only)
+              Print a short usage info and exit.
+
+       --no-daemon (unix only)
+              Don't  become  a daemon, i.e. don't fork and become
+              process group leader, don't detach from controlling
+              tty, and do all logging there.
+
+        --pidfile pidfile (unix only)
+              On startup, write the process ID to pidfile. Delete
+              the pidfile on exit. Failiure to create  or  delete
+              the pidfile is non-fatal. If no --pidfile option is
+              given, no PID file will be used.
+
+        --user user[.group] (unix only)
+              After (optionally) writing the PID file, assume the
+              user  ID  of  user and the GID of group, or, if the
+              optional group was not given, the default group  of
+              user.  Exit if the privileges are not sufficient to
+              do so.
+
+
+       If the configfile is not specified on  the  command  line,
+       Privoxy  will  look for a file named config in the current
+       directory (except on Win32 where it will try  config.txt).
+
+
+
+
+
+

DESCRIPTION

+       Privoxy  is  a web proxy with advanced filtering capabili­
+       ties for protecting privacy, filtering web  page  content,
+       managing  cookies,  controlling  access, and removing ads,
+       banners,  pop-ups  and  other  obnoxious  Internet   junk.
+       Privoxy  has a very flexible configuration and can be cus­
+       tomized to suit individual needs and tastes.  Privoxy  has
+       application  for  both  stand-alone systems and multi-user
+       Junkbuster  was originally written by JunkBusters Corpora­
+       tion, 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.
+
+
+
+
+

INSTALLATION AND USE

+       Browsers must be individually configured to use Privoxy as
+       a  HTTP  proxy.   The default setting is for localhost, on
+       port 8118 (configurable in the main config file).  To  set
+       the  HTTP proxy in Netscape and Mozilla, go through: Edit;
+       Preferences; Advanced; Proxies;  Manual  Proxy  Configura­
+       tion; View.
+
+       For Internet Explorer, go through: Tools; Internet Proper­
+       ties; Connections; LAN Settings.
+
+       The Secure (SSL) Proxy should also be set to the same val­
+       ues, otherwise https: URLs will not be proxied.
+
+       For other browsers, check the documentation.
+
+
+
+
+

CONFIGURATION

+       Privoxy  can  be configured with the various configuration
+       files.  The  default  configuration  files  are:   config,
+       default.action,  and  default.filter.  These are well com­
+       mented.  On Unix and Unix-like systems, these are  located
+       in /etc/privoxy/ by default. On Windows, OS/2 and AmigaOS,
+       these files are in the same directory as the Privoxy  exe­
+       cutable.
+
+       The  name  and  number  of configuration files has changed
+       from previous versions, and is subject to change as devel­
+       opment  progresses.  In  fact, the configuration itself is
+       changed and much more sophisticated. See  the  user-manual
+       for a brief explanation of all configuration options.
+
+       The  actions  list (ad blocks, etc) can also be configured
+       with your web  browser  at  http://www.privoxy.org/config.
+       Privoxy's  configuration  parameters can also be viewed at
+       the same page. In addition, Privoxy can be toggled on/off.
+       This is an internal page.
+
+
+
+
+

SAMPLE CONFIGURATION

+       A  brief  example  of  what a default.action configuration
+       might look like:
+
+
+       # Define a few useful custom aliases for later use
+       {{alias}}
+       +no-cookies = +no-cookies-set +no-cookies-read
+
+       # Do accept cookies
+       -no-cookies = -no-cookies-set -no-cookies-read
+
+       # Treat these blocked URLs as images.
+       +imageblock = +block +image
+
+       # Define page filters we want to use.
+       myfilters = +filter{html-annoyances} +filter{js-annoyances}\
+                   +filter{no-popups} +filter{webbugs}
+
+       ## Default Policies (actions) ############################
+       { \
+        -block \
+        -downgrade \
+        +fast-redirects \
+        myfilters \
+        +no-compression \
+        +hide-forwarded \
+        +hide-from{block} \
+        +hide-referer{forge} \
+        -hide-user-agent \
+        -image \
+        +image-blocker{blank} \
+        +no-cookies-keep \
+        -no-cookies-read \
+        -no-cookies-set \
+        +no-popups \
+        -vanilla-wafer \
+        -wafer \
+       }
+       /
+
+       # Now set exceptions to the above defined policies #######
+
+       # Sites where we want persistant cookies
+       {-no-cookies -no-cookies-keep}
+        .redhat.com
+        .sun.com
+        .yahoo.com
+        .msdn.microsoft.com
+
+       # This site requires cookies AND 'fast-redirects' on
+       {-no-cookies -no-cookies-keep -fast-redirects}
+        .nytimes.com
+
+       # Add custom headers, and turn off filtering of page source
+       {+add-header{X-Privacy: Yes please} #-add-header{*} \
+        +add-header{X-User-Tracking: No thanks!} -filter}
+        privacy.net
+
+        .adforce.imgis.com
+        .ad.preferences.com/image.*
+        .ads.web.aol.com
+        .ad-adex3.flycast.com
+        .ad.doubleclick.net
+        .ln.doubleclick.net
+        .ad.de.doubleclick.net
+        /.*/count\.cgi\?.*df=
+        194.221.183.22[1-7]
+        a196.g.akamai.net/7/196/2670/000[12]/images.gmx.net/i4/images/.*/
+
+       # Block any URLs that match these patterns
+       {+block}
+        /.*/(.*[-_.])?ads?[0-9]?(/|[-_.].*|\.(gif|jpe?g))
+        /.*/(plain|live|rotate)[-_.]?ads?/
+        /.*/(sponsor)s?[0-9]?/
+        /.*/ad(server|stream|juggler)\.(cgi|pl|dll|exe)
+        /.*/adbanners/
+        /.*/adv((er)?ts?|ertis(ing|ements?))?/
+        /.*/banners?/
+        /.*/popupads/
+        /.*/advert[0-9]+\.jpg
+        /ad_images/
+        /.*/ads/
+        /images/.*/.*_anim\.gif
+        /rotations/
+        /.*(ms)?backoff(ice)?.*\.(gif|jpe?g)
+        195.63.104.*/(inbox|log|meld|folderlu|folderru|log(in|out)[lmr]u|)
+        .images.nytimes.com
+        .images.yahoo.com/adv/
+        /.*cnnstore\.gif
+
+
+
+       See the comments in the configuration files themselves, or
+       the  user-manual for explanations of the above syntax, and
+       other Privoxy configuration options.
+
+
+
+
+

FILES

+       /usr/sbin/privoxy
+       /etc/privoxy/config
+       /etc/privoxy/default.action
+       /etc/privoxy/advanced.action
+       /etc/privoxy/basic.action
+       /etc/privoxy/intermediate.action
+       /etc/privoxy/default.filter
+       /etc/privoxy/trust
+       /etc/privoxy/templates/*
+       /var/log/privoxy/logfile
+
+
+       mentation should be included in  the  local  documentation
+       directory, though is not complete at this time.
+
+
+
+
+

SIGNALS

+       Privoxy terminates on the SIGINT, SIGTERM and SIGABRT sig­
+       nals. Log rotation scripts may cause a re-opening  of  the
+       logfile  by  sending a SIGHUP to Privoxy. Note that unlike
+       other daemons, Privoxy does not need to be made  aware  of
+       config file changes by SIGHUP -- it will detect them auto­
+       matically.
+
+
+
+
+

NOTES

+       This is a BETA version of Privoxy. Not  all  features  are
+       well tested.
+
+       Please see the user-maual on how to contact the developers
+       for feature requests, reporting problems, and other  ques­
+       tions.
+
+
+
+
+

BUGS

+       Probably.  Please see the user-manual for how and where to
+       report bugs.
+
+
+
+
+

SEE ALSO

+       http://www.privoxy.org/
+       http://config.privoxy.org/
+       http://www.privoxy.org/faq/
+       http://www.privoxy.org/user-manual/
+       http://www.privoxy.org/developer-manual/
+       http://sourceforge.net/projects/ijbswa  (Privoxy   Project
+       Page)
+       http://www.waldherr.org/junkbuster/
+       http://www.junkbusters.com/ht/en/cookies.html
+       http://privacy.net/analyze/
+       http://www.squid-cache.org/
+       http://linuxalpha.ch/steudten/software/
+
+
+
+
+

DEVELOPMENT TEAM

+        Stefan Waldherr
+        Andreas Oesterhelt
+        Jon Foster
+        Markus Breitenbach
+        Thomas Steudten
+        David Schmidt
+        Haroon Rafique
+        Joerg Strohmayer
+        Shamim Mohamed
+        John Venvertloh
+        Hal Burgiss
+        Rodrigo Barbosa
+        Gábor Lipták
+
+
+
+
+

COPYRIGHT AND LICENSE

+       This  program  is  free  software; you can redistribute it
+       and/or modify it under the terms of the GNU General Public
+       License  as  published  by  the  Free Software Foundation;
+       either version 2 of the License, or (at your  option)  any
+       later version.
+
+       This  program  is  distributed in the hope that it will be
+       useful, but WITHOUT ANY WARRANTY; without even the implied
+       warranty  of  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
+       PURPOSE.  See the GNU  General  Public  License  for  more
+       details.
+
+       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
+
+       Internet Junkbuster Proxy is a  trademark  of  Junkbusters
+       Corporation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ diff --git a/doc/webserver/user-manual/appendix.html b/doc/webserver/user-manual/appendix.html new file mode 100644 index 00000000..0546aff1 --- /dev/null +++ b/doc/webserver/user-manual/appendix.html @@ -0,0 +1,1549 @@ +Appendix
Privoxy User Manual
Prev 

9. Appendix

9.1. Regular Expressions

Privoxy can use "regular expressions" + in various config files. Assuming support for "pcre" (Perl + Compatible Regular Expressions) is compiled in, which is the default. Such + configuration directives do not require regular expressions, but they can be + used to increase flexibility by matching a pattern with wild-cards against + URLs.

If you are reading this, you probably don't understand what "regular + expressions" are, or what they can do. So this will be a very brief + introduction only. A full explanation would require a book ;-)

"Regular expressions" is a way of matching one character + expression against another to see if it matches or not. One of the + "expressions" is a literal string of readable characters + (letter, numbers, etc), and the other is a complex string of literal + characters combined with wild-cards, and other special characters, called + meta-characters. The "meta-characters" have special meanings and + are used to build the complex pattern to be matched against. Perl Compatible + Regular Expressions is an enhanced form of the regular expression language + with backward compatibility.

To make a simple analogy, we do something similar when we use wild-card + characters when listing files with the dir command in DOS. + *.* matches all filenames. The "special" + character here is the asterisk which matches any and all characters. We can be + more specific and use ? to match just individual + characters. So "dir file?.text" would match + "file1.txt", "file2.txt", etc. We are pattern + matching, using a similar technique to "regular expressions"!

Regular expressions do essentially the same thing, but are much, much more + powerful. There are many more "special characters" and ways of + building complex patterns however. Let's look at a few of the common ones, + and then some examples:

. - Matches any single character, e.g. "a", + "A", "4", ":", or "@". +

? - The preceding character or expression is matched ZERO or ONE + times. Either/or. +

+ - The preceding character or expression is matched ONE or MORE + times. +

* - The preceding character or expression is matched ZERO or MORE + times. +

\ - The "escape" character denotes that + the following character should be taken literally. This is used where one of the + special characters (e.g. ".") needs to be taken literally and + not as a special meta-character. +

[] - Characters enclosed in brackets will be matched if + any of the enclosed characters are encountered. +

() - parentheses are used to group a sub-expression, + or multiple sub-expressions. +

| - The "bar" character works like an + "or" conditional statement. A match is successful if the + sub-expression on either side of "|" matches. +

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 + Privoxy, and is a long way from a definitive + list. This is enough to get us started with a few simple examples which may + be more illuminating:

/.*/banners/.* - A simple example + that uses the common combination of "." and "*" to + denote any character, zero or more times. In other words, any string at all. + So we start with a literal forward slash, then our regular expression pattern + (".*") another literal forward slash, the string + "banners", another forward slash, and lastly another + ".*". We are building + a directory path here. This will match any file with the path that has a + directory named "banners" in it. The ".*" matches + any characters, and this could conceivably be more forward slashes, so it + might expand into a much longer looking path. For example, this could match: + "/eye/hate/spammers/banners/annoy_me_please.gif", or just + "/banners/annoying.html", or almost an infinite number of other + possible combinations, just so it has "banners" in the path + somewhere.

A now something a little more complex:

/.*/adv((er)?ts?|ertis(ing|ements?))?/ - + We have several literal forward slashes again ("/"), so we are + building another expression that is a file path statement. We have another + ".*", so we are matching against any conceivable sub-path, just so + it matches our expression. The only true literal that must + match our pattern is adv, together with + the forward slashes. What comes after the "adv" string is the + interesting part.

Remember the "?" means the preceding expression (either a + literal character or anything grouped with "(...)" in this case) + can exist or not, since this means either zero or one match. So + "((er)?ts?|ertis(ing|ements?))" is optional, as are the + individual sub-expressions: "(er)", + "(ing|ements?)", and the "s". The "|" + means "or". We have two of those. For instance, + "(ing|ements?)", can expand to match either "ing" + OR "ements?". What is being done here, is an + attempt at matching as many variations of "advertisement", and + similar, as possible. So this would expand to match just "adv", + or "advert", or "adverts", or + "advertising", or "advertisement", or + "advertisements". You get the idea. But it would not match + "advertizements" (with a "z"). We could fix that by + changing our regular expression to: + "/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/", which would then match + either spelling.

/.*/advert[0-9]+\.(gif|jpe?g) - Again + another path statement with forward slashes. Anything in the square brackets + "[]" can be matched. This is using "0-9" as a + shorthand expression to mean any digit one through nine. It is the same as + saying "0123456789". So any digit matches. The "+" + means one or more of the preceding expression must be included. The preceding + expression here is what is in the square brackets -- in this case, any digit + one through nine. Then, at the end, we have a grouping: "(gif|jpe?g)". + This includes a "|", so this needs to match the expression on + either side of that bar character also. A simple "gif" on one side, and the other + side will in turn match either "jpeg" or "jpg", + since the "?" means the letter "e" is optional and + can be matched once or not at all. So we are building an expression here to + match image GIF or JPEG type image file. It must include the literal + string "advert", then one or more digits, and a "." + (which is now a literal, and not a special character, since it is escaped + with "\"), and lastly either "gif", or + "jpeg", or "jpg". Some possible matches would + include: "//advert1.jpg", + "/nasty/ads/advert1234.gif", + "/banners/from/hell/advert99.jpg". It would not match + "advert1.gif" (no leading slash), or + "/adverts232.jpg" (the expression does not include an + "s"), or "/advert1.jsp" ("jsp" is not + in the expression anywhere).

s/microsoft(?!.com)/MicroSuck/i - This is + a substitution. "MicroSuck" will replace any occurrence of + "microsoft". The "i" at the end of the expression + means ignore case. The "(?!.com)" means + the match should fail if "microsoft" is followed by + ".com". In other words, this acts like a "NOT" + modifier. In case this is a hyperlink, we don't want to break it ;-).

We are barely scratching the surface of regular expressions here so that you + can understand the default Privoxy + configuration files, and maybe use this knowledge to customize your own + installation. There is much, much more that can be done with regular + expressions. Now that you know enough to get started, you can learn more on + your own :/

More reading on Perl Compatible Regular expressions: + http://www.perldoc.com/perl5.6/pod/perlre.html

9.2. Privoxy's Internal Pages

Since Privoxy proxies each requested + web page, it is easy for Privoxy to + trap certain special URLs. In this way, we can talk directly to + Privoxy, and see how it is + configured, see how our rules are being applied, change these + rules and other configuration options, and even turn + Privoxy's filtering off, all with + a web browser.

The URLs listed below are the special ones that allow direct access + to Privoxy. Of course, + Privoxy must be running to access these. If + not, you will get a friendly error message. Internet access is not + necessary either.

These may be bookmarked for quick reference.

9.2.1. Bookmarklets

Here are some bookmarklets to allow you to easily access a + "mini" version of this page. They are designed for MS Internet + Explorer, but should work equally well in Netscape, Mozilla, and other + browsers which support JavaScript. They are designed to run directly from + your bookmarks - not by clicking the links below (although that will work for + testing).

To save them, right-click the link and choose "Add to Favorites" + (IE) or "Add Bookmark" (Netscape). You will get a warning that + the bookmark "may not be safe" - just click OK. Then you can run the + Bookmarklet directly from your favourites/bookmarks. For even faster access, + you can put them on the "Links" bar (IE) or the "Personal + Toolbar" (Netscape), and run them with a single click.

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 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 obvious. Privoxy provides the + http://config.privoxy.org/show-url-info + page that can show us very specifically how actions + are being applied to any given URL. This is a big help for troubleshooting. +

First, enter one URL (or partial URL) at the prompt, and then + Privoxy will tell us + how the current configuration will handle it. This will not + help with filtering effects from the default.filter file! It + also will not tell you about any other URLs that may be embedded within the + URL you are testing. For instance, images such as ads are expressed as URLs + within the raw page source of HTML pages. So you will only get info for the + actual URL that is pasted into the prompt area -- not any sub-URLs. If you + want to know about embedded URLs like ads, you will have to dig those out of + the HTML source. Use your browser's "View Page Source" option + for this. Or right click on the ad, and grab the URL.

Let's look at an example, google.com, + one section at a time:

 System default actions:
+
+ { -add-header -block -deanimate-gifs -downgrade -fast-redirects -filter 
+   -hide-forwarded -hide-from -hide-referer -hide-user-agent -image 
+   -image-blocker -limit-connect -no-compression -no-cookies-keep 
+   -no-cookies-read -no-cookies-set -no-popups -vanilla-wafer -wafer }
+ 
+

This is the top section, and only tells us of the compiled in defaults. This + is basically what Privoxy would do if there + were not any "actions" defined, i.e. it does nothing. Every action + is disabled. This is not particularly informative for our purposes here. OK, + next section:


 Matches for http://google.com:
+
+ { -add-header -block +deanimate-gifs -downgrade +fast-redirects 
+   +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} 
+   +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} 
+   +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} 
+   -hide-user-agent -image +image-blocker{blank} +no-compression 
+   +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups 
+   -vanilla-wafer -wafer }
+   /
+
+ { -no-cookies-keep -no-cookies-read -no-cookies-set }
+  .google.com
+
+ { -fast-redirects }
+  .google.com
+
+

This is much more informative, and tells us how we have defined our + "actions", and which ones match for our example, + "google.com". The first grouping shows our default + settings, which would apply to all URLs. If you look at your "actions" + file, this would be the section just below the "aliases" section + near the top. This applies to all URLs as signified by the single forward + slash -- "/". +

These are the default actions we have enabled. But we can define additional + actions that would be exceptions to these general rules, and then list + specific URLs that these exceptions would apply to. Last match wins. + Just below this then are two explict matches for ".google.com". + The first is negating our various cookie blocking actions (i.e. we will allow + cookies here). The second is allowing "fast-redirects". Note + that there is a leading dot here -- ".google.com". This will + match any hosts and sub-domains, in the google.com domain also, such as + "www.google.com". So, apparently, we have these actions defined + somewhere in the lower part of our actions file, and + "google.com" is referenced in these sections.

And now we pull it altogether in the bottom section and summarize how + Privoxy is appying all its "actions" + to "google.com": 


 Final results:
+
+ -add-header -block -deanimate-gifs -downgrade -fast-redirects 
+ +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} 
+ +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} 
+ +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} 
+ -hide-user-agent -image +image-blocker{blank} -limit-connect +no-compression 
+ -no-cookies-keep -no-cookies-read -no-cookies-set +no-popups -vanilla-wafer 
+ -wafer
+
+

Now another example, "ad.doubleclick.net":


 { +block +image }
+  .ad.doubleclick.net
+
+ { +block +image }
+  ad*.
+
+ { +block +image }
+  .doubleclick.net
+
+

We'll just show the interesting part here, the explicit matches. It is + matched three different times. Each as an "+block +image", + which is the expanded form of one of our aliases that had been defined as: + "+imageblock". ("Aliases" are defined in the + first section of the actions file and typically used to combine more + than one action.)

Any one of these would have done the trick and blocked this as an unwanted + image. This is unnecessarily redundant since the last case effectively + would also cover the first. No point in taking chances with these guys + though ;-) Note that if you want an ad or obnoxious + URL to be invisible, it should be defined as "ad.doubleclick.net" + is done here -- as both a "+block" and an + "+image". The custom alias "+imageblock" does this + for us.

One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". + This one is giving us problems. We are getting a blank page. Hmmm...


 Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
+
+ { -add-header -block +deanimate-gifs -downgrade +fast-redirects 
+   +filter{html-annoyances} +filter{js-annoyances} +filter{no-popups} 
+   +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} 
+   +filter{fun} +hide-forwarded +hide-from{block} +hide-referer{forge} 
+   -hide-user-agent -image +image-blocker{blank} +no-compression 
+   +no-cookies-keep -no-cookies-read -no-cookies-set +no-popups 
+   -vanilla-wafer -wafer }
+   /
+
+ { +block +image }
+  /ads
+
+

Ooops, the "/adsl/" is matching "/ads"! But + we did not want this at all! Now we see why we get the blank page. We could + now add a new action below this that explictly does not + block (-block) pages with "adsl". There are various ways to + handle such exceptions. Example:


 { -block }
+  /adsl
+ 
+

Now the page displays ;-) Be sure to flush your browser's caches when + making such changes. Or, try using Shift+Reload.

But now what about a situation where we get no explicit matches like + we did with:


 { -block }
+  /adsl
+ 
+

That actually was very telling and pointed us quickly to where the problem + was. If you don't get this kind of match, then it means one of the default + rules in the first section is causing the problem. This would require some + guesswork, and maybe a little trial and error to isolate the offending rule. + One likely cause would be one of the "{+filter}" actions. Try + adding the URL for the site to one of aliases that turn off "+filter":


 {shop}
+ .quietpc.com
+ .worldpay.com   # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+ 
+

"{shop}" is an "alias" that expands to + "{ -filter -no-cookies -no-cookies-keep }". Or you could do + your own exception to negate filtering: 


 {-filter}
+ .forbes.com
+ 
+

"{fragile}" is an alias that disables most actions. This can be + used as a last resort for problem sites. Remember to flush caches! If this + still does not work, you will have to go through the remaining actions one by + one to find which one(s) is causing the problem.

PrevHome 
See Also  
\ No newline at end of file diff --git a/doc/webserver/user-manual/configuration.html b/doc/webserver/user-manual/configuration.html new file mode 100644 index 00000000..f2d4c3bc --- /dev/null +++ b/doc/webserver/user-manual/configuration.html @@ -0,0 +1,3964 @@ +Privoxy Configuration
Privoxy User Manual
PrevNext

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

Privoxy can be reached by the special + URL http://p.p/ (or alternately + http://config.privoxy.org/), + which is an internal page. You will see the following section: 


Please choose from the following options:
+
+    * Show information about the current configuration
+    * Show the source code version numbers
+    * Show the client's request headers.
+    * Show which actions apply to a URL and why
+    * Toggle Privoxy on or off
+    * Edit the actions list
+
+

This should be self-explanatory. Note the last item is an editor for the + "actions list", which is where much of the ad, banner, cookie, + and URL blocking magic is configured as well as other advanced features of + Privoxy. This is an easy way to adjust various + aspects of Privoxy configuration. The actions + file, and other configuration files, are explained in detail below. + Privoxy will automatically detect any changes + to these files.

"Toggle Privoxy On or Off" is handy for sites that might + have problems with your current actions and filters, or just to test if + a site misbehaves, whether it is Privoxy + causing the problem or not. Privoxy continues + to run as a proxy in this case, but all filtering is disabled.

5.2. Configuration Files Overview

For Unix, *BSD and Linux, all configuration files are located in + /etc/privoxy/ by default. For MS Windows, OS/2, and + AmigaOS these are all in the same directory as the + Privoxy executable. The name + and number of configuration files has changed from previous versions, and is + subject to change as development progresses.

The installed defaults provide a reasonable starting point, though possibly + aggressive by some standards. For the time being, there are only three + default configuration files (this may change in time):

  • 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 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, 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 to restart + Privoxy in order for the changes to take + effect. Privoxy should detect such changes + automatically.

While under development, the configuration content is subject to change. + The below documentation may not be accurate by the time you read this. + Also, what constitutes a "default" setting, may change, so + please check all your configuration files on important issues.

5.3. The Main Configuration File

Again, the main configuration file is named config on + Linux/Unix/BSD and OS/2, and config.txt on Windows. + Configuration lines consist of an initial keyword followed by a list of + values, all separated by whitespace (any number of spaces or tabs). For + example:

  blockfile blocklist.ini
+   

+

Indicates that the blockfile is named "blocklist.ini". (A + default installation does not use this.)

A "#" indicates a comment. Any part of a + line following a "#" is ignored, except if + the "#" is preceded by a + "\".

Thus, by placing a "#" at the start of an + existing configuration line, you can make it a comment and it will be treated + as if it weren't there. This is called "commenting out" an + option and can be useful to turn off features: If you comment out the + "logfile" line, Privoxy will not + log to a file at all. Watch for the "default:" section in each + explanation to see what happens if the option is left unset (or commented + out).

Long lines can be continued on the next line by using a + "\" as the very last character.

There are various aspects of Privoxy behavior + that can be tuned.

5.3.1. Defining Other Configuration Files

Privoxy can use a number of other files to tell it + what ads to block, what cookies to accept, and perform other functions. This + section of the configuration file tells Privoxy + where to find all those other files.

On Windows and AmigaOS, + Privoxy looks for these files in the same + directory as the executable. On Unix and OS/2, + Privoxy looks for these files in the current + working directory. In either case, an absolute path name can be used to + avoid problems.

When development goes modular and multi-user, the blocker, filter, and + per-user config will be stored in subdirectories of "confdir". + For now, only confdir/templates is used for storing HTML + templates for CGI results.

The location of the configuration files:

  confdir /etc/privoxy       # No trailing /, please.
+   

+

The directory where all logging (i.e. logfile and + jarfile) takes place. No trailing + "/", please:

  logdir /var/log/privoxy
+   

+

Note that all file specifications below are relative to + the above two directories!

The "default.action" file contains patterns to specify the + actions to apply to requests for each site. Default: Cookies to and from all + destinations are kept only during the current browser session (i.e. they are + not saved to disk). Pop-ups are disabled for all sites. All sites are + filtered through selected sections of "default.filter". No sites + are blocked. Privoxy displays a checkboard type + pattern for filtered ads and other images. The syntax of this file is + explained in detail below. Other + "actions" files are included, and you are free to use any of + them. They have varying degrees of aggressiveness.

  actionsfile default.action
+   

+

The "default.filter" file contains content modification rules + that use "regular expressions". These rules permit powerful + changes on the content of Web pages, e.g., you could disable your favorite + JavaScript annoyances, re-write the actual displayed text, or just have some + fun replacing "Microsoft" with "MicroSuck" wherever + it appears on a Web page. Default: whatever the developers are playing with + :-/

Filtering requires buffering the page content, which may appear to slow down + page rendering since nothing is displayed until all content has passed + the filters. (It does not really take longer, but seems that way since + the page is not incrementally displayed.) This effect will be more noticeable + on slower connections.

  filterfile default.filter
+   

+

The logfile is where all logging and error messages are written. The logfile + can be useful for tracking down a problem with + Privoxy (e.g., it's not blocking an ad you + think it should block) but in most cases you probably will never look at it.

Your logfile will grow indefinitely, and you will probably want to + periodically remove it. On Unix systems, you can do this with a cron job + (see "man cron"). For Redhat, a logrotate + script has been included.

On SuSE Linux systems, you can place a line like "/var/log/privoxy.* + +1024k 644 nobody.nogroup" in /etc/logfiles, with + the effect that cron.daily will automatically archive, gzip, and empty the + log, when it exceeds 1M size.

Default: Log to the a file named logfile. + Comment out to disable logging.

  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
+   

+

If you specify a "trustfile", + Privoxy will only allow access to sites that + are named in the trustfile. You can also mark sites as trusted referrers, + with the effect that access to untrusted sites will be granted, if a link + from a trusted referrer was used. The link target will then be added to the + "trustfile". This is a very restrictive feature that typical + users most probably want to leave disabled. Default: Disabled, don't use the + trust mechanism.

  #trustfile trust
+   

+

If you use the trust mechanism, it is a good idea to write up some on-line + documentation about your blocking policy and to specify the URL(s) here. They + will appear on the page that your users receive when they try to access + untrusted content. Use multiple times for multiple URLs. Default: Don't + display links on the "untrusted" info page.

  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

This part of the configuration file contains options that control how + Privoxy operates.

"Admin-address" should be set to the email address of the proxy + administrator. It is used in many of the proxy-generated pages. Default: + fill@me.in.please.

  #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 proxy-generated pages + and its use is highly recommended in multi-user installations, since your + users will want to know why certain content is blocked or modified. Default: + Don't show a link to on-line documentation.

  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 "8118").

If you already have another service running on port 8118, or if you want to + serve requests from other machines (e.g. on your local network) as well, you + will need to override the default. The syntax is + "listen-address [<ip-address>]:<port>". If you leave + out the IP address, Privoxy will bind to all + interfaces (addresses) on your machine and may become reachable from the + Internet. In that case, consider using access control lists (acl's) (see + "aclfile" above), or a firewall.

For example, suppose you are running Privoxy on + a machine which has the address 192.168.0.1 on your local private network + (192.168.0.0) and has another outside connection with a different address. + You want it to serve requests from inside only:

  listen-address 192.168.0.1:8118
+   

+

If you want it to listen on all addresses (including the outside + connection):

  listen-address :8118
+   

+

If you do this, consider using ACLs (see "aclfile" above). Note: + you will need to point your browser(s) to the address and port that you have + configured here. Default: localhost:8118 (127.0.0.1:8118).

The debug option sets the level of debugging information to log in the + logfile (and to the console in the Windows version). A debug level of 1 is + informative because it will show you each request as it happens. Higher + levels of debug are probably only of interest to developers.

  debug         1 # GPC   = show each GET/POST/CONNECT request
+  debug         2 # CONN  = show each connection status
+  debug         4 # IO    = show I/O status
+  debug         8 # HDR   = show header parsing
+  debug        16 # LOG   = log all data into the logfile
+  debug        32 # FRC   = debug force feature
+  debug        64 # REF   = debug regular expression filter 
+  debug       128 #       = debug fast redirects
+  debug       256 #       = debug GIF de-animation
+  debug       512 # CLF   = Common Log Format
+  debug      1024 #       = debug kill pop-ups
+  debug      4096 # INFO  = Startup banner and warnings.
+  debug      8192 # ERROR = Non-fatal errors
+    

+

It is highly recommended that you enable ERROR + reporting (debug 8192), at least until v3.0 is released.

The reporting of FATAL errors (i.e. ones which crash + Privoxy) is always on and cannot be disabled.

If you want to use CLF (Common Log Format), you should set "debug + 512" ONLY, do not enable anything else.

Multiple "debug" directives, are OK - they're logical-OR'd + together.

  debug 15 # same as setting the first 4 listed above
+   

+

Default:

  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 + "single-threaded" option forces + Privoxy to handle requests sequentially. + Default: Multi-threaded mode.

  #single-threaded
+   

+

"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 allows you to change this option. If you + right-click on that icon (or select the "Options" menu), one + choice is "Enable". Clicking on enable toggles + Privoxy on and off. This is useful if you want + to temporarily disable Privoxy, e.g., to access + a site that requires cookies which you would otherwise have blocked. This can also + be toggled via a web browser at the Privoxy + internal address of http://p.p on + any platform.

"toggle 1" means Privoxy runs + normally, "toggle 0" means that + Privoxy becomes a non-anonymizing non-blocking + proxy. Default: 1 (on).

  toggle 1
+   

+

For content filtering, i.e. the "+filter" and + "+deanimate-gif" actions, it is necessary that + Privoxy buffers the entire document body. + This can be potentially dangerous, since a server could just keep sending + data indefinitely and wait for your RAM to exhaust. With nasty consequences.

The buffer-limit option lets you set the maximum + size in Kbytes that each buffer may use. When the documents buffer exceeds + this size, it is flushed to the client unfiltered and no further attempt to + filter the rest of it is made. Remember that there may multiple threads + running, which might require increasing the "buffer-limit" + Kbytes each, unless you have enabled + "single-threaded" above.

  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 this feature, otherwise this option has no effect. This + internal page can be reached at http://p.p. +

Security note: If this is enabled, anyone who can use the proxy + can edit the actions file, and their changes will affect all users. + For shared proxies, you probably want to disable this. Default: enabled.

  enable-edit-actions 1
+   

+

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.

Security note: If this is enabled, anyone who can use the proxy can toggle + it on or off (see http://p.p), and + their changes will affect all users. For shared proxies, you probably want to + disable this. Default: enabled.

  enable-remote-toggle 1
+   

+

5.3.3. Access Control List (ACL)

Access controls are included at the request of some ISPs and systems + administrators, and are not usually needed by individual users. Please note + the warnings in the FAQ that this proxy is not intended to be a substitute + for a firewall or to encourage anyone to defer addressing basic security + weaknesses.

If no access settings are specified, the proxy talks to anyone that + connects. If any access settings file are specified, then the proxy + talks only to IP addresses permitted somewhere in this file and not + denied later in this file.

Summary -- if using an ACL:

Client must have permission to receive service. +

LAST match in ACL wins. +

Default behavior is to deny service. +

The syntax for an entry in the Access Control List is:

  ACTION    SRC_ADDR[/SRC_MASKLEN]    [ DST_ADDR[/DST_MASKLEN] ]
+   

+

Where the individual fields are:

 ACTION      = "permit-access" or "deny-access"
+
+ SRC_ADDR    = client hostname or dotted IP address
+ SRC_MASKLEN = number of bits in the subnet mask for the source
+
+ DST_ADDR    = server or forwarder hostname or dotted IP address
+ DST_MASKLEN = number of bits in the subnet mask for the target
+   

+

+ The field separator (FS) is whitespace (space or tab).

IMPORTANT NOTE: If Privoxy is using a + forwarder (see below) or a gateway for a particular destination URL, the + DST_ADDR that is examined is the address of the forwarder + or the gateway and NOT the address of the ultimate + target. This is necessary because it may be impossible for the local + Privoxy to determine the address of the + ultimate target (that's often what gateways are used for).

Here are a few examples to show how the ACL features work:

"localhost" is OK -- no DST_ADDR implies that + ALL destination addresses are OK:

  permit-access localhost
+   

+

A silly example to illustrate permitting any host on the class-C subnet with + Privoxy to go anywhere:

  permit-access www.privoxy.com/24
+   

+

Except deny one particular IP address from using it at all:

  deny-access ident.privoxy.com
+   

+

You can also specify an explicit network address and subnet mask. + Explicit addresses do not have to be resolved to be used.

  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
+   

+

Note, you cannot say:

  permit-access .org
+   

+

to allow all *.org domains. Every IP address listed must resolve fully.

An ISP may want to provide a Privoxy that is + accessible by "the world" and yet restrict use of some of their + private content to hosts on its internal network (i.e. its own subscribers). + Say, for instance the ISP owns the Class-B IP address block 123.124.0.0 (a 16 + bit netmask). This is how they could do it:

 permit-access 0.0.0.0/0 0.0.0.0/0   # other clients can go anywhere 
+                                       # with the following exceptions:
+ 
+ deny-access   0.0.0.0/0   123.124.0.0/16 # block all external requests for
+                                          # sites on the ISP's network
+
+ permit 0.0.0.0/0 www.my_isp.com        # except for the ISP's main 
+                                          # web site
+
+ permit 123.124.0.0/16 0.0.0.0/0          # the ISP's clients can go 
+                                          # anywhere
+   

+

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

This feature allows chaining of HTTP requests via multiple proxies. + It can be used to better protect privacy and confidentiality when + accessing specific domains by routing requests to those domains + to a special purpose filtering proxy such as lpwa.com. Or to use + a caching proxy to speed up browsing.

It can also be used in an environment with multiple networks to route + requests via multiple gateways allowing transparent access to multiple + networks without having to modify browser configurations.

Also specified here are SOCKS proxies. Privoxy + SOCKS 4 and SOCKS 4A. The difference is that SOCKS 4A will resolve the target + hostname using DNS on the SOCKS server, not our local DNS client.

The syntax of each line is:

 forward target_domain[:port] http_proxy_host[:port]
+ forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]
+ forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]
+   

+

If http_proxy_host is ".", then requests are not forwarded to a + HTTP proxy but are made directly to the web servers.

Lines are checked in sequence, and the last match wins.

There is an implicit line equivalent to the following, which specifies that + anything not finding a match on the list is to go out without forwarding + or gateway protocol, like so:

  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 .
+   

+

+ Some users have reported difficulties related to LPWA's use of + "." as the last element of the domain, and have said that this + can be fixed with this:

  forward lpwa. lpwa.com:8000
+   

+

(NOTE: the syntax for specifying target_domain has changed since the + previous paragraph was written -- it will not work now. More information + is welcome.)

In this fictitious example, everything goes via an ISP's caching proxy, + except requests to that ISP:

 forward .* caching.myisp.net:8000
+ forward myisp.net .
+   

+

For the @home network, we're told the forwarding configuration is this:

  forward .* proxy:8080
+   

+

Also, we're told they insist on getting cookies and JavaScript, so you should + allow cookies from home.com. We consider JavaScript a potential security risk. + Java need not be enabled.

In this example direct connections are made to all "internal" + domains, but everything else goes through Lucent's LPWA by way of the + company's SOCKS gateway to the Internet.

 forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080
+ forward my_company.com .
+   

+

This is how you could set up a site that always uses SOCKS but no forwarders:

  forward-socks4a .* . firewall.my_company.com:1080
+   

+

An advanced example for network administrators:

If you have links to multiple ISPs that provide various special content to + their subscribers, you can configure forwarding to pass requests to the + specific host that's connected to that ISP so that everybody can see all + of the content on all of the ISPs.

This is a bit tricky, but here's an example:

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
+   

+

host-b can run a Privoxy proxy with forwarding + like this:

 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 content on isp-a or isp-b.

Here's another practical example, for University of Kent at + Canterbury students with a network connection in their room, who + need to use the University's Squid web cache.

 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
+
+  # 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
+
+  # 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 CONNECT (https) to privoxy
+  always_direct allow CONNECT 
+
+  # 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 + "Privoxy" is active. To turn off, set to 0.

  activity-animation 1
+   

+

If "log-messages" is set to 1, + Privoxy will log messages to the console + window:

  log-messages 1
+   

+

+ If "log-buffer-size" is set to 1, the size of the log buffer, + i.e. the amount of memory used for the log messages displayed in the + console window, will be limited to "log-max-lines" (see below).

Warning: Setting this to 0 will result in the buffer to grow infinitely and + eat up all your memory!

  log-buffer-size 1
+   

+

log-max-lines is the maximum number of lines held + in the log buffer. See above.

  log-max-lines 200
+   

+

If "log-highlight-messages" is set to 1, + Privoxy will highlight portions of the log + messages with a bold-faced font:

  log-highlight-messages 1
+   

+

The font used in the console window:

  log-font-name Comic Sans MS
+   

+

Font size used in the console window:

  log-font-size 8
+   

+

+ "show-on-task-bar" controls whether or not + Privoxy will appear as a button on the Task bar + when minimized:

  show-on-task-bar 0
+   

+

If "close-button-minimizes" is set to 1, the Windows close + button will minimize Privoxy instead of closing + the program (close with the exit option on the File menu).

  close-button-minimizes 1
+   

+

The "hide-console" option is specific to the MS-Win console + version of Privoxy. If this option is used, + Privoxy will disconnect from and hide the + command console.

  #hide-console
+   

+

5.4. The Actions File

The "default.action" file (formerly + actionsfile or ijb.action) is used + to define what actions Privoxy takes, and thus + determines how ad images, cookies and various other aspects of HTTP content + and transactions are handled. These can be accepted or rejected for all + sites, or just those sites you choose. See below for a complete list of + actions.

+ Anything you want can blocked, including ads, banners, or just some obnoxious + URL that you would rather not see. Cookies can be accepted or rejected, or + accepted only during the current browser session (i.e. not written to disk). + Changes to default.action should be immediately visible + to Privoxy without the need to restart.

Note that some sites may misbehave, or possibly not work at all with some + actions. This may require some tinkering with the rules to get the most + mileage of Privoxy's features, and still be + able to see and enjoy just what you want to. There is no general rule of + thumb on these things. There just are too many variables, and sites are + always changing.

The easiest way to edit the "actions" file is with a browser by + loading http://p.p/, and then select + "Edit Actions List". A text editor can also be used.

To determine which actions apply to a request, the URL of the request is + compared to all patterns in this file. Every time it matches, the list of + applicable actions for the URL is incrementally updated. You can trace + this process by visiting http://p.p/show-url-info.

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

Generally, a pattern has the form <domain>/<path>, where both the + <domain> and <path> part are optional. If you only specify a + domain part, the "/" can be left out:

www.example.com - is a domain only pattern and will match any request to + "www.example.com".

www.example.com/ - means exactly the same.

www.example.com/index.html - matches only the single + document "/index.html" on "www.example.com".

/index.html - matches the document "/index.html", + regardless of the domain. So would match any page named "index.html" + on any site.

index.html - matches nothing, since it would be + interpreted as a domain name and there is no top-level domain called + ".html".

The matching of the domain part offers some flexible options: if the + domain starts or ends with a dot, it becomes unanchored at that end. + For example:

.example.com - matches any domain or sub-domain that + ENDS in ".example.com".

www. - matches any domain that STARTS with + "www".

Additionally, there are wild-cards that you can use in the domain names + themselves. They work pretty similar to shell wild-cards: "*" + stands for zero or more arbitrary characters, "?" stands for + any single character. And you can define character classes in square + brackets and they can be freely mixed:

ad*.example.com - matches "adserver.example.com", + "ads.example.com", etc but not "sfads.example.com".

*ad*.example.com - matches all of the above, and then some.

.?pix.com - matches "www.ipix.com", + "pictures.epix.com", "a.b.c.d.e.upix.com", etc.

www[1-9a-ez].example.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 regular expressions + can be used. These are more flexible and powerful than other types + of "regular expressions". See the pcre/docs/ directory or "man + perlre" (also available on http://www.perldoc.com/perl5.6/pod/perlre.html) + for details. A brief discussion of regular expressions is in the + Appendix. For instance:

/.*/advert[0-9]+\.jpe?g - would match a URL from any + domain, with any path that includes "advert" followed + immediately by one or more digits, then a "." and ending in + either "jpeg" or "jpg". So we match + "example.com/ads/advert2.jpg", and + "www.example.com/ads/banners/advert39.jpeg", but not + "www.example.com/ads/banners/advert39.gif" (no gifs in the + example pattern).

Please note that matching in the path is case + INSENSITIVE by default, but you can switch to case + sensitive at any point in the pattern by using the + "(?-i)" switch:

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. {+some_action}), followed by a list of + URLs to which the action applies. There are three classes of actions:

  • + Boolean (e.g. "+/-block"): +

      {+name}        # enable this action
    +  {-name}        # disable this action
    +     

    + +

  • + parameterized (e.g. "+/-hide-user-agent"): +

      {+name{param}}  # enable action and set parameter to "param"
    +  {-name}         # disable action
    +     

    + +

  • + Multi-value (e.g. "{+/-add-header{Name: value}}", "{+/-wafer{name=value}}"): +

      {+name{param}}   # enable action and add parameter "param"
    +  {-name{param}}   # remove the parameter "param"
    +  {-name}          # disable this action totally
    +     

    + +

If nothing is specified in this file, no "actions" are taken. + So in this case Privoxy would just be a + normal, non-blocking, non-anonymizing proxy. You must specifically + enable the privacy and blocking features you need (although the + provided default default.action file will + give a good starting point).

Later defined actions always over-ride earlier ones. So exceptions + to any rules you make, should come in the latter part of the file. For + multi-valued actions, the actions are applied in the order they are + specified.

The list of valid Privoxy "actions" are:

  • + Add the specified HTTP header, which is not checked for validity. + You may specify this many times to specify many different headers: +

      +add-header{Name: value}
    +     

    + +

  • + Block this URL totally. In a default installation, a "blocked" + URL will result in bright red banner that says "BLOCKED", + with a reason why it is being blocked, and an option to see it anyway. + The page displayed for this is the "blocked" template + file. +

      +block
    +     

    + +

  • + De-animate all animated GIF images, i.e. reduce them to their last frame. + This will also shrink the images considerably (in bytes, not pixels!). If + the option "first" is given, the first frame of the animation + is used as the replacement. If "last" is given, the last frame + of the animation is used instead, which probably makes more sense for most + banner animations, but also has the risk of not showing the entire last + frame (if it is only a delta to an earlier frame). +

      +deanimate-gifs{last}
    +  +deanimate-gifs{first}
    +     

    + +

  • "+downgrade" will downgrade HTTP/1.1 client requests to + HTTP/1.0 and downgrade the responses as well. Use this action for servers + that use HTTP/1.1 protocol features that + Privoxy doesn't handle well yet. HTTP/1.1 + is only partially implemented. Default is not to downgrade requests. +

      +downgrade
    +     

    + +

  • + Many sites, like yahoo.com, don't just link to other sites. Instead, they + will link to some script on their own server, giving the destination as a + parameter, which will then redirect you to the final target. URLs resulting + from this scheme typically look like: + http://some.place/some_script?http://some.where-else. +

    Sometimes, there are even multiple consecutive redirects encoded in the + URL. These redirections via scripts make your web browsing more traceable, + since the server from which you follow such a link can see where you go to. + Apart from that, valuable bandwidth and time is wasted, while your browser + ask the server for one redirect after the other. Plus, it feeds the + advertisers. +

    The "+fast-redirects" option enables interception of these + types of requests by Privoxy, who will cut off + all but the last valid URL in the request and send a local redirect back to + your browser without contacting the intermediate site(s). +

      +fast-redirects
    +     

    + +

  • + Apply the filters in the section_header + section of the default.filter file to the site(s). + default.filter sections are grouped according to like + functionality. 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 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 +

    no-poups: Kill all popups in JS and HTML +

    frameset-borders: Give frames a border +

    webbugs: Squish WebBugs (1x1 invisible GIFs used for user tracking) +

    no-refresh: Automatic refresh sucks on auto-dialup lines +

    fun: Text replacements for subversive browsing fun! +

    nimda: Remove (virus) Nimda code. +

    banners-by-size: Kill banners by size +

    crude-parental: Kill all web pages that contain the words "sex" or "warez" +

  • + Block any existing X-Forwarded-for header, and do not add a new one: +

      +hide-forwarded
    +     

    + +

  • + If the browser sends a "From:" header containing your e-mail + address, this either completely removes the header ("block"), or + changes it to the specified e-mail address. +

      +hide-from{block}
    +  +hide-from{spam@sittingduck.xqq}
    +     

    + +

  • + 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}
    +     

    + +

  • + 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{...}
    +     

    + +

  • + 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)}
    +     

    + +

  • + 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 as images in most cases. For instance, frames + require an HTML page to 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
    +     

    + +

  • Decides what to do with URLs that end up tagged with "{+block + +image}", e.g an advertizement. There are five options. + "-image-blocker" will send a HTML "blocked" page, + usually resulting in a "broken image" icon. +"+image-blocker{blank}" will send a 1x1 transparent GIF +image. And finally, "+image-blocker{http://xyz.com}" will send a +HTTP temporary redirect to the specified image. This has the advantage of the +icon being being cached by the browser, which will speed up the display. +"+image-blocker{pattern}" will send a checkboard type pattern +

      +image-blocker{blank}
    +  +image-blocker{pattern}
    +  +image-blocker{http://p.p/send-banner}
    +     

    + +

  • + By default (i.e. in the absence of a "+limit-connect" + action), Privoxy will only allow CONNECT + requests to port 443, which is the standard port for https as a + precaution. +

    The CONNECT methods exists in HTTP to allow access to secure websites + (https:// URLs) through proxies. It works very simply: the proxy + connects to the server on the specified port, and then short-circuits + its connections to the client and to the remote proxy. + This can be a big security hole, since CONNECT-enabled proxies can + be abused as TCP relays very easily. +

    + If you want to allow CONNECT for more ports than this, or want to forbid + CONNECT altogether, you can specify a comma separated list of ports and + port ranges (the latter using dashes, with the minimum defaulting to 0 and + max to 65K): +

      +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-popup" and "+gif-deanimate" will not work on + compressed data. This will slow down connections to those websites, + though. Default is "no-compression" is turned on. +

      +nocompression
    +     

    + +

  • + If the website sets cookies, "no-cookies-keep" will make sure + they are erased when you exit and restart your web browser. This makes + profiling cookies useless, but won't break sites which require cookies so + that you can log in for transactions. Default: on. +

      +no-cookies-keep
    +     

    + +

  • + Prevent the website from reading cookies: +

      +no-cookies-read
    +     

    + +

  • + Prevent the website from setting cookies: +

      +no-cookies-set
    +     

    + +

  • + Filter the website through a built-in filter to disable those obnoxious + JavaScript pop-up windows via window.open(), etc. The two alternative + spellings are equivalent. +

      +no-popup
    +  +no-popups
    +     

    + +

  • + This action only applies if you are using a jarfile + for saving cookies. It sends a cookie to every site stating that you do not + accept any copyright on cookies sent to you, and asking them not to track + you. Of course, this is a (relatively) unique header they could use to + track you. +

      +vanilla-wafer
    +     

    + +

  • + This allows you to add an arbitrary cookie. It can be specified multiple + times in order to add as many cookies as you like. +

      +wafer{name=value}
    +     

    + +

The meaning of any of the above is reversed by preceding the action with a + "-", in place of the "+".

Some examples:

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
+   

+

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 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
+   

+

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/
+   

+

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

Custom "actions", known to Privoxy + as "aliases", can be defined by combining other "actions". + These can in turn be invoked just like the built-in "actions". + Currently, an alias can contain any character except space, tab, "=", + "{" or "}". But please use only "a"- + "z", "0"-"9", "+", and + "-". Alias names are not case sensitive, and + must be defined before anything else in the + default.actionfile! And there can only be one set of + "aliases" defined.

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.
+   

+

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
+   

+

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

Any web page can be dynamically modified with the filter file. This + modification can be removal, or re-writing, of any web page content, + including tags and non-visible content. The default filter file is + default.filter, located in the config directory.

This is potentially a very powerful feature, and requires knowledge of both + "regular expression" and HTML in order create custom + filters. But, there are a number of useful filters included with + Privoxy for many common situations.

The included example file is divided into sections. Each section begins + with the FILTER keyword, followed by the identifier + for that section, e.g. "FILTER: webbugs". Each section performs + a similar type of filtering, such as "html-annoyances".

This file uses regular expressions to alter or remove any string in the + target page. The expressions can only operate on one line at a time. Some + examples from the included default default.filter:

Stop web pages from displaying annoying messages in the status bar by + deleting such references:

 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 
+
+ # 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
+   

+

Just for kicks, replace any occurrence of "Microsoft" with + "MicroSuck", and have a little fun with topical buzzwords:

 FILTER: fun
+
+ s/microsoft(?!.com)/MicroSuck/ig
+
+ # 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
+
+ s/<img\s+[^>]*?(width|height)\s*=\s*['"]?1\D[^>]*?(width|height)\s*=\s*['"]?1(\D[^>]*?)?>/<!-- Squished WebBug -->/sig
+   

+

5.6. Templates

When Privoxy displays one of its internal + pages, such as a 404 Not Found error page, it uses the appropriate template. + On Linux, BSD, and Unix, these are located in + /etc/privoxy/templates by default. These may be + customized, if desired.

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.

PrevHomeNext
Quickstart to Using Privoxy Contacting the Developers, Bug Reporting and Feature +Requests
\ No newline at end of file diff --git a/doc/webserver/user-manual/contact.html b/doc/webserver/user-manual/contact.html new file mode 100644 index 00000000..655340fb --- /dev/null +++ b/doc/webserver/user-manual/contact.html @@ -0,0 +1,228 @@ +Contacting the Developers, Bug Reporting and Feature +Requests
Privoxy User Manual
PrevNext

6. Contacting the Developers, Bug Reporting and Feature +Requests

We value your feedback. However, to provide you with the best support, please + note: + +

PrevHomeNext
Privoxy Configuration Copyright and History
\ No newline at end of file diff --git a/doc/webserver/user-manual/copyright.html b/doc/webserver/user-manual/copyright.html new file mode 100644 index 00000000..9aea5adb --- /dev/null +++ b/doc/webserver/user-manual/copyright.html @@ -0,0 +1,213 @@ +Copyright and History
Privoxy User Manual
PrevNext

7. Copyright and History

7.1. Copyright

Privoxy is free software; you can + redistribute it and/or modify it under the terms of the GNU General Public + + License as published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details, which is available from the Free Software Foundation, Inc, 59 + Temple Place - Suite 330, Boston, MA 02111-1307, USA.

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 is evolved, and derived from, + the Internet Junkbuster, with many + improvments and enhancements over the original.

Junkbuster was originally written by Anonymous + Coders and Junkbuster's + Corporation, and was released as free open-source software under the + GNU GPL. Stefan + Waldherr made many improvements, and started the SourceForge project + Privoxy to rekindle development. There are now several active + developers contributing. The last stable release of + Junkbuster was v2.0.2, which has now + grown whiskers ;-).

PrevHomeNext
Contacting the Developers, Bug Reporting and Feature +Requests See Also
\ No newline at end of file diff --git a/doc/webserver/user-manual/index.html b/doc/webserver/user-manual/index.html new file mode 100644 index 00000000..8b87588c --- /dev/null +++ b/doc/webserver/user-manual/index.html @@ -0,0 +1,483 @@ +Privoxy User Manual

Privoxy User Manual

By: Privoxy Developers

$Id: user-manual.sgml,v 1.69 2002/04/06 05:07:29 hal9 Exp $

+

The user manual gives users information on how to install, configure and use + Privoxy. +

Privoxy is a web proxy with advanced filtering + capabilities for protecting privacy, filtering web page content, managing + cookies, controlling access, and removing ads, banners, pop-ups and other + obnoxious Internet junk. Privoxy has a very + flexible configuration and can be customized to suit individual needs and + tastes. Privoxy has application for both + stand-alone systems and multi-user networks.

Privoxy is based on the code of the + Internet Junkbuster (tm). + Junkbuster was originally written by JunkBusters + Corporation, and was released as free open-source software under the GNU GPL. + Stefan Waldherr made many improvements, and started the SourceForge project + to continue development.

Privoxy continues the + Junkbuster tradition, but adds many + refinements, enhancements and new features.

You can find the latest version of the user manual at http://www.privoxy.org/user-manual/. Please see the Contact section on how to contact the developers. +

Table of Contents
1. Introduction
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
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.3. Anatomy of an Action

  Next
  Introduction
\ No newline at end of file diff --git a/doc/webserver/user-manual/installation.html b/doc/webserver/user-manual/installation.html new file mode 100644 index 00000000..56700d0f --- /dev/null +++ b/doc/webserver/user-manual/installation.html @@ -0,0 +1,567 @@ +Installation
Privoxy User Manual
PrevNext

3. Installation

Privoxy is available as raw source code (tarball + or via CVS), or pre-compiled binaries for various platforms. See the Privoxy Project Page for + the most up to date release information. + Privoxy is also available via CVS. + This is the recommended approach at this time. But + please be aware that CVS is constantly changing, and it may break in + mysterious ways.

At present, Privoxy is known to run on Win32, Mac + OSX, OS/2, AmigaOS, Linux (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

There are several ways to install Privoxy.

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
+

For retrieving the current CVS sources, you'll need the CVS + package installed first. Note CVS source is development quality, + and may not be stable, or well tested. To download CVS source:

  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+  cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
+  cd current
+

This will create a directory named current/, which will + contain the source tree.

Then, in either case, to build from unpacked tarball or CVS source:

 autoheader
+ autoconf
+ ./configure      (--help to see options)
+ make             (the make from gnu, gmake for *BSD) 
+ su 
+ make -n install  (to see where all the files will go)
+ make install     (to really install)
+

Redhat and SuSE src and binary RPMs can be built with + "make redhat-dist" or + "make suse-dist" from unpacked sources. You + will need to run "autoconf; autoheader; + ./configure" beforehand. *BSD will require gmake (from + http://www.gnu.org). +

For Redhat and SuSE Linux RPM packages, see below.

3.1.1. Red Hat

To build Redhat RPM packages from source, install source as above. Then:

 autoheader
+ autoconf
+ ./configure
+ make redhat-dist
+

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/SRPMS/privoxy-2.9.13-1.src.rpm

To install, of course:

 rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.13-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

To build SuSE RPM packages, install source as above. Then:

 autoheader
+ autoconf
+ ./configure
+ make suse-dist
+

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/SRPMS/privoxy-2.9.13-1.src.rpm

To install, of course:

 rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.13-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 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.

The directory you choose to install Privoxy + into will contain all of the configuration files.

If you would like to build binary images on OS/2 yourself, you will need + a few Unix-like tools: autoconf, autoheader and sh. These tools will be + used to create the required config.h file, which is not part of the + source distribution because it differs based on platform. You will also + need a compiler. + The distribution has been created using IBM VisualAge compilers, but you + can use any compiler you like. GCC/EMX has the disadvantage of needing + to be single-threaded due to a limitation of EMX's implementation of the + select() socket call.

In addition to needing the source code distribution as outlined earlier, + you will want to extract the os2seutp directory from CVS: + 
 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login          
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+
+ This will create a directory named os2setup/, which will contain the + Makefile.vac makefile and os2build.cmd + which is used to completely create the binary distribution. The sequence + of events for building the executable for yourself goes something like this: + 
 cd current
+ autoheader
+ autoconf
+ sh configure
+ cd ..\os2setup
+ nmake -f Makefile.vac
+
+ You will see this sequence laid out in os2build.cmd.

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

Some quick notes on other Operating Systems.

For FreeBSD (and other *BSDs?), the build will require gmake + instead of the included make. gmake is + available from http://www.gnu.org. + The rest should be the same as above for Linux/Unix.

PrevHomeNext
Introduction Quickstart to Using Privoxy
\ No newline at end of file diff --git a/doc/webserver/user-manual/introduction.html b/doc/webserver/user-manual/introduction.html new file mode 100644 index 00000000..ed132b97 --- /dev/null +++ b/doc/webserver/user-manual/introduction.html @@ -0,0 +1,266 @@ +Introduction
Privoxy User Manual
PrevNext

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 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 + 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

In addition to Internet Junkbuster's traditional + feature of ad and banner blocking and cookie management, + Privoxy provides new features, + some of them currently under development:

  • Integrated browser based configuration and control utility (http://p.p). Browser-based tracing of rule + and filter effects. +

  • Blocking of annoying pop-up browser windows. +

  • HTTP/1.1 compliant (most, but not all 1.1 features are supported). +

  • Support for Perl Compatible Regular Expressions in the configuration files, and + generally a more sophisticated and flexible configuration syntax over + previous versions. +

  • GIF de-animation. +

  • Web page content filtering (removes banners based on size, + invisible "web-bugs", JavaScript, pop-ups, status bar abuse, + etc.) +

  • Bypass many click-tracking scripts (avoids script redirection). + +

  • Multi-threaded (POSIX and native threads). +

  • Auto-detection and re-reading of config file changes. +

  • User-customizable HTML templates (e.g. 404 error page). +

  • Improved cookie management features (e.g. session based cookies). +

  • Improved signal handling, and a true daemon mode (Unix). +

  • Builds from source on most UNIX-like systems. Packages available for: Linux + (RedHat, SuSE, or Debian), Windows, Sun Solaris, Mac OSX, OS/2, HP-UX 11 and AmigaOS. + +

  • In addition, the configuration is much more powerful and versatile over-all. +

PrevHomeNext
Privoxy User Manual Installation
\ No newline at end of file diff --git a/doc/webserver/user-manual/quickstart.html b/doc/webserver/user-manual/quickstart.html new file mode 100644 index 00000000..956525f2 --- /dev/null +++ b/doc/webserver/user-manual/quickstart.html @@ -0,0 +1,500 @@ +Quickstart to Using Privoxy
Privoxy User Manual
PrevNext

4. Quickstart to Using Privoxy

Before launching Privoxy for the first time, you + will want to configure your browser(s) to use Privoxy + as a HTTP and HTTPS proxy. The default is localhost for the proxy address, + and port 8118 (earlier versions used port 800). This is the one required + configuration that must be done!

+ With Netscape (and + Mozilla), this can be set under Edit + -> Preferences -> Advanced -> Proxies -> HTTP Proxy. + For Internet Explorer: Tools -> + Internet Properties -> Connections -> LAN Setting. Then, + check "Use Proxy" and fill in the appropriate info (Address: + localhost, Port: 8118). Include if HTTPS proxy support too.

After doing this, flush your browser's disk and memory caches to force a + re-reading of all pages and get rid of any ads that may be cached. You + are now ready to start enjoying the benefits of using + Privoxy.

Privoxy is typically started by specifying the + main configuration file to be used on the command line. Example Unix startup + command:

 
+ # /usr/sbin/privoxy /etc/privoxy/config
+ 
+

An init script is provided for SuSE and Redhat.

For for SuSE: /etc/rc.d/privoxy start

For RedHat: /etc/rc.d/init.d/privoxy start

If no configuration file is specified on the command line, + Privoxy will look for a file named + config in the current directory. Except on Win32 where + it will try config.txt. If no file is specified on the + command line and no default configuration file can be found, + Privoxy will fail to start.

The included default configuration files should give a reasonable starting + point, though may be somewhat aggressive in blocking junk. Most of the + per site configuration is done in the "actions" files. These + are where various cookie actions are defined, ad and banner blocking, + and other aspects of Privoxy configuration. There + are several such files included, with varying levels of aggressiveness.

You will probably want to keep an eye out for sites that require persistent + cookies, and add these to default.action as needed. By + default, most of these will be accepted only during the current browser + session, until you add them to the configuration. If you want the browser to + handle this instead, you will need to edit + default.action and disable this feature. If you use more + than one browser, it would make more sense to let + Privoxy handle this. In which case, the browser(s) + should be set to accept all cookies.

Privoxy is HTTP/1.1 compliant, but not all 1.1 + features are as yet implemented. If browsers that support HTTP/1.1 (like + Mozilla or recent versions of I.E.) experience + problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look + under Edit -> Preferences -> Debug -> Networking. + Or set the "+downgrade" config option in + default.action.

After running Privoxy for a while, you can + start to fine tune the configuration to suit your personal, or site, + preferences and requirements. There are many, many aspects that can + be customized. "Actions" (as specified in default.action) + can be adjusted by pointing your browser to + http://p.p/, + and then follow the link to "edit the actions list". + (This is an internal page and does not require Internet access.)

In fact, various aspects of Privoxy + configuration can be viewed from this page, including + current configuration parameters, source code version numbers, + the browser's request headers, and "actions" that apply + to a given URL. In addition to the default.action file + editor mentioned above, Privoxy can also + be turned "on" and "off" from this page.

If you encounter problems, please verify it is a + Privoxy bug, by disabling + Privoxy, and then trying the same page. + Also, try another browser if possible to eliminate browser or site + problems. Before reporting it as a bug, see if there is not a configuration + option that is enabled that is causing the page not to load. You can then add + an exception for that page or site. For instance, try adding it to the + {fragile} section of default.action. + This will turn off most actions for this site. For more on troubleshooting + problem sites, see the Appendix. If a bug, please report it + to the developers (see below).

4.1. Command Line Options

Privoxy may be invoked with the following + command-line options:

  • --version +

    Print version info and exit, Unix only. +

  • --help +

    Print a short usage info and exit, Unix only. +

  • --no-daemon +

    Don't become a daemon, i.e. don't fork and become process group + leader, don't detach from controlling tty. Unix only. +

  • --pidfile FILE + +

    On startup, write the process ID to FILE. Delete the + FILE on exit. Failiure to create or delete the + FILE is non-fatal. If no FILE + option is given, no PID file will be used. Unix only. +

  • --user USER[.GROUP] + +

    After (optionally) writing the PID file, assume the user ID of + USER, and if included the GID of GROUP. Exit if the + privileges are not sufficient to do so. Unix only. +

  • configfile +

    If no configfile is included on the command line, + Privoxy will look for a file named + "config" in the current directory (except on Win32 + where it will look for "config.txt" instead). Specify + full path to avoid confusion. +

PrevHomeNext
Installation Privoxy Configuration
\ No newline at end of file diff --git a/doc/webserver/user-manual/seealso.html b/doc/webserver/user-manual/seealso.html new file mode 100644 index 00000000..68b11dfb --- /dev/null +++ b/doc/webserver/user-manual/seealso.html @@ -0,0 +1,295 @@ +See Also
Privoxy User Manual
PrevNext

8. See Also

Other references and sites of interest to Privoxy + users:

http://www.privoxy.org/, + The Privoxy Home page. +

+

http://sourceforge.net/projects/ijbswa, + the Project Page for Privoxy on + Sourceforge. +

+

http://p.p/, access + Privoxy from your browser. Alternately, + http://config.privoxy.org + may work in some situations where the first does not. +

+

http://www.junkbusters.com/ht/en/cookies.html +

+

http://www.waldherr.org/junkbuster/ +

+

http://privacy.net/analyze/ +

+

http://www.squid-cache.org/ +

PrevHomeNext
Copyright and History Appendix
\ No newline at end of file -- 2.39.2