By: Privoxy Developers
-$Id: user-manual.sgml,v 1.57 2002/03/24 20:33:30 hal9 Exp $
+$Id: user-manual.sgml,v 1.72 2002/04/10 04:06:19 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.
-You can find the latest version of the user manual at http://
-ijbswa.sourceforge.net/user-manual/.
+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
-2. Installation
+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
- 2.1. Source
- 2.2. Red Hat
- 2.3. SuSE
- 2.4. OS/2
- 2.5. Windows
- 2.6. Other
+ 4.1. Command Line Options
-3. Privoxy Configuration
+5. Privoxy Configuration
- 3.1. Controlling Privoxy with Your Web Browser
- 3.2. Configuration Files Overview
- 3.3. The Main Configuration File
+ 5.1. Controlling Privoxy with Your Web Browser
+ 5.2. Configuration Files Overview
+ 5.3. The Main Configuration File
- 3.3.1. Defining Other Configuration Files
- 3.3.2. Other Configuration Options
- 3.3.3. Access Control List (ACL)
- 3.3.4. Forwarding
- 3.3.5. Windows GUI Options
+ 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
- 3.4. The Actions File
+ 5.4. The Actions File
- 3.4.1. URL Domain and Path Syntax
- 3.4.2. Actions
- 3.4.3. Aliases
+ 5.4.1. URL Domain and Path Syntax
+ 5.4.2. Actions
+ 5.4.3. Aliases
- 3.5. The Filter File
- 3.6. Templates
-
-4. Quickstart to Using Privoxy
+ 5.5. The Filter File
+ 5.6. Templates
- 4.1. Command Line Options
-
-5. Contacting the Developers, Bug Reporting and Feature Requests
-6. Copyright and History
+6. Contacting the Developers, Bug Reporting and Feature Requests
+7. Copyright and History
- 6.1. License
- 6.2. History
+ 7.1. Copyright
+ 7.2. History
-7. See also
-8. Appendix
+8. See Also
+9. Appendix
- 8.1. Regular Expressions
- 8.2. Privoxy's Internal Pages
- 8.3. Anatomy of an Action
+ 9.1. Regular Expressions
+ 9.2. Privoxy's Internal Pages
+
+ 9.2.1. Bookmarklets
+
+ 9.3. Anatomy of an Action
+-------------------------------------------------------------------------------
+
1. Introduction
-Privoxy is a web proxy with advanced filtering capabilities for protecting
-privacy, filtering and modifying web page content, managing cookies,
-controlling access, and removing ads, banners, pop-ups and other obnoxious
-Internet Junk. Privoxy has a very flexible configuration and can be customized
-to suit individual needs and tastes. Privoxy has application for both
-stand-alone systems and multi-user networks.
-
-Privoxy is derived from Internet Junkbuster by Junkbusters Corporation, which
-is no longer under development. Many enhancements and new features have been
-added.
-
-This documentation is included with the current BETA version of Privoxy and is
-mostly complete at this point. The most up to date reference for the time being
-is still the comments in the source files and in the individual configuration
-files. Development of version 3.0 is currently nearing completion, and includes
-many significant changes and enhancements over earlier versions. The target
-release date for stable v3.0 is "soon" ;-)
-
-Since this is a BETA version, not all new features are well tested. This
+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!
* 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.
-------------------------------------------------------------------------------
-2. Installation
+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.
-Privoxy is available as raw source code, or pre-compiled binaries. See the
-Privoxy Home Page for binaries and current release info. Privoxy is also
-available via CVS. This is the recommended approach at this time. But please be
-aware that CVS is constantly changing, and it may break in mysterious ways.
+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.
-------------------------------------------------------------------------------
-2.1. Source
+3.1. Source
-For gzipped tar archives, unpack the 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. To download CVS source:
+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
This will create a directory named current/, which will contain the source
tree.
-Then, in either case, to build from tarball/CVS source:
+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 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.
-------------------------------------------------------------------------------
-2.2. Red Hat
+3.1.1. Red Hat
-To build Redhat RPM packages, install source as above. Then:
+To build Redhat RPM packages from source, install source as above. Then:
autoheader
autoconf
This will create both binary and src RPMs in the usual places. Example:
- /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ /usr/src/redhat/RPMS/i686/privoxy-2.9.13-1.i686.rpm
- /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.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.11-1.i686.rpm
+ 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/.
+in /var/log/privoxy/. Run "chkconfig privoxy on" to have Privoxy start
+automatically during init.
-------------------------------------------------------------------------------
-2.3. SuSE
+3.1.2. SuSE
To build SuSE RPM packages, install source as above. Then:
This will create both binary and src RPMs in the usual places. Example:
- /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ /usr/src/packages/RPMS/i686/privoxy-2.9.13-1.i686.rpm
- /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.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.11-1.i686.rpm
+ 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
-------------------------------------------------------------------------------
-2.4. OS/2
+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:
-ijbos2_setup_1.2.3.exe. In order to install it, simply run this executable or
-double-click on its icon and follow the WarpIN installation panels. A shadow of
-the Privoxy executable will be placed in your startup folder so it will start
-automatically whenever OS/2 starts.
+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.
-------------------------------------------------------------------------------
-2.5. Windows
+3.1.4. Windows
Click-click. (I need help on this. Not a clue here. Also for configuration
section below. HB.)
-------------------------------------------------------------------------------
-2.6. Other
+3.1.5. Other
Some quick notes on other Operating Systems.
-------------------------------------------------------------------------------
-3. Privoxy Configuration
+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
-All Privoxy configuration is kept in text files. These files can be edited with
-a text editor. Many important aspects of Privoxy can also be controlled easily
-with a web browser.
+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.
+
+-------------------------------------------------------------------------------
+
+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.
-------------------------------------------------------------------------------
-3.1. Controlling Privoxy with Your Web Browser
+5.1. Controlling Privoxy with Your Web Browser
Privoxy can be reached by the special URL http://p.p/ (or alternately http://
-ijbswa.sourceforge.net/config/), which is an internal page. You will see the
-following section:
+config.privoxy.org/), which is an internal page. You will see the following
+section:
-Please choose from the following options:
+ Please choose from the following options:
* Show information about the current configuration
* Show the source code version numbers
-------------------------------------------------------------------------------
-3.2. Configuration Files Overview
+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
The installed defaults provide a reasonable starting point, though possibly
aggressive by some standards. For the time being, there are only three default
-configuration files (this will change in time):
+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.
images, banners, pop-ups, access restrictions, banners and cookies. There
is a CGI based editor for this file that can be accessed via http://p.p.
(Other actions files are included as well with differing levels of
- filtering and blocking, e.g. ijb-basic.action.)
+ 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
-------------------------------------------------------------------------------
-3.3. The Main Configuration File
+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
-------------------------------------------------------------------------------
-3.3.1. Defining Other Configuration Files
+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, etc. This section of the configuration file tells Privoxy
-where to find all those other files.
+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
untrusted content. Use multiple times for multiple URLs. Default: Don't display
links on the "untrusted" info page.
- trust-info-url http://www.your-site.com/why_we_block.html
- trust-info-url http://www.your-site.com/what_we_allow.html
+ trust-info-url http://www.example.com/why_we_block.html
+ trust-info-url http://www.example.com/what_we_allow.html
-------------------------------------------------------------------------------
-3.3.2. Other Configuration Options
+5.3.2. Other Configuration Options
This part of the configuration file contains options that control how Privoxy
operates.
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.your-site.com/proxy.html
+ proxy-info-url http://www.example.com/proxy.html
"Listen-address" specifies the address and port where Privoxy will listen for
-------------------------------------------------------------------------------
-3.3.3. Access Control List (ACL)
+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
-------------------------------------------------------------------------------
-3.3.4. Forwarding
+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
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:
+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 127.0.0.1 parent 8118 0 no-query
+ 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
-------------------------------------------------------------------------------
-3.3.5. Windows GUI Options
+5.3.5. Windows GUI Options
Privoxy has a number of options specific to the Windows GUI interface:
-------------------------------------------------------------------------------
-3.4. The Actions File
+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 images, cookies and
-various other aspects of HTTP content and transactions are handled. Images can
-be anything you want, including ads, banners, or just some obnoxious URL that
-you would rather not see. Cookies can be accepted or rejected, or accepted only
-during the current browser session (i.e. not written to disk). Changes to
-default.action should be immediately visible to Privoxy without the need to
-restart.
-
-The easiest way to edit "actions" file is with a browser by loading http://p.p/
-, and then select "Edit Actions List". A text editor can also be used.
+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
-------------------------------------------------------------------------------
-3.4.1. URL Domain and Path Syntax
+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
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.
+/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 that ENDS in ".example.com".
+.example.com - matches any domain or sub-domain that ENDS in ".example.com".
www. - matches any domain that STARTS with "www".
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 (default), Perl compatible regular
-expressions can be used. See the pcre/docs/ directory or "man perlre" (also
-available on http://www.perldoc.com/perl5.6/pod/perlre.html) for details. A
-brief discussion of regular expressions is in the Appendix. For instance:
+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
-------------------------------------------------------------------------------
-3.4.2. Actions
+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.
specifically enable the privacy and blocking features you need (although the
provided default default.action file will give a good starting point).
-Later defined actions always over-ride earlier ones. For multi-valued actions,
+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:
* 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.
+ being blocked, and an option to see it anyway. The page displayed for this
+ is the "blocked" template file.
+block
ask the server for one redirect after the other. Plus, it feeds the
advertisers.
- The "+fast-redirects" option enables interception of these requests by
- Privoxy, who will cut off all but the last valid URL in the request and
- send a local redirect back to your browser without contacting the remote
- site.
+ 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.
+ 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}
* Don't send the "Referer:" (sic) header to the web site. You can block it,
forge a URL to the same server as the request (which is preferred because
- some sites will not send images otherwise) or set it to a constant string
- of your choice.
+ 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}
which case a "blocked" image can be sent rather than a HTML page. See
"+image-blocker{}" below for the control over what is actually sent. If you
want invisible ads, they should be defined as images and blocked. And also,
- "image-blocker" should be set to "blank".
+ "image-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
websites do this, which can be a problem for Privoxy, since "+filter",
"+no-popup" and "+gif-deanimate" will not work on compressed data. This
will slow down connections to those websites, though. Default is
- "nocompression" is turned on.
+ "no-compression" is turned on.
+nocompression
.cvs.sourceforge.net
-Now some URLs that we want "blocked", ie we won't see them. Many of these use
-regular expressions that will expand to match multiple URLs:
+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}
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.
+Appendix for a brief example on troubleshooting actions.
-------------------------------------------------------------------------------
-3.4.3. Aliases
+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.
+default.actionfile! And there can only be one set of "aliases" defined.
Now let's define a few aliases:
- # Useful customer aliases we can use later. These must come first!
+ # Useful custom aliases we can use later. These must come first!
{{alias}}
+no-cookies = +no-cookies-set +no-cookies-read
-no-cookies = -no-cookies-set -no-cookies-read
.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.
+
-------------------------------------------------------------------------------
-3.5. The Filter File
+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".
+"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
-------------------------------------------------------------------------------
-3.6. Templates
+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.
+desired. cgi-style.css is used to control the HTML attributes (fonts, etc).
--------------------------------------------------------------------------------
-
-4. Quickstart to Using Privoxy
-
-Install package, then run and enjoy! Privoxy is typically started by specifying
-the main configuration file to be used on the command line. Example Unix
-startup command:
-
-
- # /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.
-
-Be sure your browser is set to use the proxy which is by default at localhost,
-port 8118. With Netscape (and Mozilla), this can be set under Edit ->
-Preferences -> Advanced -> Proxies -> HTTP Proxy. For Internet Explorer: Tools
-> Internet Properties -> Connections -> LAN Setting. Then, check "Use Proxy"
-and fill in the appropriate info (Address: localhost, Port: 8118). Include if
-HTTPS proxy support too.
-
-The included default configuration files should give a reasonable starting
-point, though may be somewhat aggressive in blocking junk. You will probably
-want to keep an eye out for sites that require persistent cookies, and add
-these to default.action as needed. By default, most of these will be accepted
-only during the current browser session, until you add them to the
-configuration. If you want the browser to handle this instead, you will need to
-edit default.action and disable this feature. If you use more than one browser,
-it would make more sense to let Privoxy handle this. In which case, the browser
-(s) should be set to accept all cookies.
-
-If a particular site shows problems loading properly, try adding it to the
-{fragile} section of default.action. This will turn off most actions for this
-site.
-
-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. If a bug,
-please report it to the developers (see below).
+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.
-------------------------------------------------------------------------------
-4.1. Command Line Options
+6. Contacting the Developers, Bug Reporting and Feature Requests
-Privoxy may be invoked with the following command-line options:
+We value your feedback. However, to provide you with the best support, please
+note:
- * --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.
+ * Use the Sourceforge Support Forum to get help:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=211118
+
- * configfile
+ * Submit bugs only through our Sourceforge Bug Forum:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=111118.
+
+
+ Make sure that the bug has not already been submitted. Please try to verify
+ that it is a Privoxy bug, and not a browser or site bug first. If you are
+ using your own custom configuration, please try the stock configs to see if
+ the problem is a configuration related bug. And if not using the latest
+ development snapshot, please try the latest one. Or even better, CVS
+ sources. Please be sure to include the Privoxy/Junkbuster version,
+ platform, browser, any pertinent log data, any other relevant details
+ (please be specific) and, if possible, some way to reproduce the bug.
+
+ * Submit feature requests only through our Sourceforge feature request forum:
+
+ http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
+
- 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.
+ * Submit missed ads and banners, and incorrectly blocked images, popups, etc:
+
+ http://p.p/, and select "actions file feedback system"
+
--------------------------------------------------------------------------------
-
-5. Contacting the Developers, Bug Reporting and Feature Requests
-
-We value your feedback. However, to provide you with the best support, please
-note:
-
- * Use the Sourceforge support forum to get help.
+ This page can also be reached from many of the internal CGI pages.
- * Submit bugs only thru our Sourceforge bug forum. Make sure that the bug has
- not already been submitted. Please try to verify that it is a Privoxy bug,
- and not a browser or site bug first. If you are using your own custom
- configuration, please try the stock configs to see if the problem is a
- configuration related bug. And if not using the latest development
- snapshot, please try the latest one. Or even better, CVS sources.
+ * For any other issues, feel free to use the mailing lists:
+
+ http://sourceforge.net/mail/?group_id=11118.
+
- * Submit feature requests only thru our Sourceforge feature request forum.
+ Anyone interested in actively participating in development and related
+ discussions can also join the appropriate mailing list. Archives are
+ available too.
-
-
-For any other issues, feel free to use the mailing lists.
-
-Anyone interested in actively participating in development and related
-discussions can join the appropriate mailing list here. Archives are available
-here too.
-
-------------------------------------------------------------------------------
-6. Copyright and History
+7. Copyright and History
-6.1. License
+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
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.
+
-------------------------------------------------------------------------------
-6.2. History
+7.2. History
-Privoxy is derived from the Internet Junkbuster, with many improvments and
-enhancements over the original.
+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
+Junkbuster was originally written by Anonymous Coders and Junkbusters
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
-------------------------------------------------------------------------------
-7. See also
+8. See Also
+
+Other references and sites of interest to Privoxy users:
- http://sourceforge.net/projects/ijbswa
+http://www.privoxy.org/, The Privoxy Home page.
- http://ijbswa.sourceforge.net/
+http://sourceforge.net/projects/ijbswa, the Project Page for Privoxy on
+Sourceforge.
- http://p.p/
+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://p.p/, and select "actions file feedback system" to submit "misses" to
+the developers.
- http://www.waldherr.org/junkbuster/
+http://www.junkbusters.com/ht/en/cookies.html
- http://privacy.net/analyze/
+http://www.waldherr.org/junkbuster/
- http://www.squid-cache.org/
+http://privacy.net/analyze/
+
+http://www.squid-cache.org/
-------------------------------------------------------------------------------
-8. Appendix
+9. Appendix
-8.1. Regular Expressions
+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
-------------------------------------------------------------------------------
-8.2. Privoxy's Internal Pages
+9.2. Privoxy's Internal Pages
Since Privoxy proxies each requested web page, it is easy for Privoxy to trap
-certain 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.
+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
* Privoxy main page:
- http://ijbswa.sourceforge.net/config/
+ http://config.privoxy.org/
Alternately, this may be reached at http://p.p/, but this variation may not
work as reliably as the above in some configurations.
* Show information about the current configuration:
- http://ijbswa.sourceforge.net/config/show-status
+ http://config.privoxy.org/show-status
* Show the source code version numbers:
- http://ijbswa.sourceforge.net/config/show-version
+ http://config.privoxy.org/show-version
* Show the client's request headers:
- http://ijbswa.sourceforge.net/config/show-request
+ http://config.privoxy.org/show-request
* Show which actions apply to a URL and why:
- http://ijbswa.sourceforge.net/config/show-url-info
+ http://config.privoxy.org/show-url-info
- * Toggle Privoxy on or off:
+ * Toggle Privoxy on or off. In this case, "Privoxy" continues to run, but
+ only as a pass-through proxy, with no actions taking place:
- http://ijbswa.sourceforge.net/config/toggle
+ http://config.privoxy.org/toggle
Short cuts. Turn off, then on:
- http://ijbswa.sourceforge.net/config/toggle?set=disable
+ http://config.privoxy.org/toggle?set=disable
- http://ijbswa.sourceforge.net/config/toggle?set=enable
+ http://config.privoxy.org/toggle?set=enable
* Edit the actions list file:
- http://ijbswa.sourceforge.net/config/edit-actions
+ http://config.privoxy.org/edit-actions
These may be bookmarked for quick reference.
-------------------------------------------------------------------------------
-8.3. Anatomy of an Action
+9.2.1. Bookmarklets
+
+Below are some "bookmarklets" to allow you to easily access a "mini" version of
+some of Privoxy's special pages. They are designed for MS Internet Explorer,
+but should work equally well in Netscape, Mozilla, and other browsers which
+support JavaScript. They are designed to run directly from your bookmarks - not
+by clicking the links below (although that should work for testing).
+
+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.
+
+ * Enable Privoxy
+
+ * Disable Privoxy
+
+ * Toggle Privoxy (Toggles between enabled and disabled)
+
+ * View Privoxy Status
+
+ * Actions file feedback system
+
+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" to any given URL can be complex, and not
-always so easy to understand what is happening. And sometimes we need to be
-able to see just what Privoxy is doing. Especially, if something Privoxy is
-doing is causing us a problem inadvertantly. It can be a little daunting to
-look at the actions files themselves, since they tend to be filled with
-"regular expressions" whose consequences are not always so obvious. Privoxy
-provides the http://ijbswa.sourceforge.net/config/show-url-info page that can
-show us very specifically how actions are being applied to any given URL. This
-is a big help for troubleshooting.
+The way Privoxy applies "actions" and "filters" to any given URL can be
+complex, and not always so easy to understand what is happening. And sometimes
+we need to be able to see just what Privoxy is doing. Especially, if something
+Privoxy is doing is causing us a problem 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
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.
+"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:
it does nothing. Every action is disabled. This is not particularly informative
for our purposes here. OK, next section:
- Matches for http://google.com:
+ Matches for http://google.com:
{ -add-header -block +deanimate-gifs -downgrade +fast-redirects
+filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
And now we pull it altogether in the bottom section and summarize how Privoxy
is appying all its "actions" to "google.com":
- Final results:
+ Final results:
-add-header -block -deanimate-gifs -downgrade -fast-redirects
+filter{html-annoyances} +filter{js-annoyances} +filter{no-popups}
Now another example, "ad.doubleclick.net":
- { +block +image }
+ { +block +image }
.ad.doubleclick.net
{ +block +image }
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/:
+ 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}
explictly does not block (-block) pages with "adsl". There are various ways to
handle such exceptions. Example:
- { -block }
+ { -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
-Now the page displays ;-)
+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.
projects / privoxy.git / blobdiff