-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<!entity % dummy "INCLUDE">
+<!entity supported SYSTEM "supported.sgml">
+<!entity newfeatures SYSTEM "newfeatures.sgml">
+<!entity p-intro SYSTEM "privoxy.sgml">
+<!entity seealso SYSTEM "seealso.sgml">
+<!entity buildsource SYSTEM "buildsource.sgml">
+<!entity contacting SYSTEM "contacting.sgml">
+<!entity history SYSTEM "history.sgml">
+<!entity copyright SYSTEM "copyright.sgml">
+<!entity p-version "2.9.14">
+<!entity p-status "beta">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
+<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
+<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
+<!entity % p-readme "IGNORE">
+<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
+]>
<!--
File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.58 2002/03/26 22:29:55 swa Exp $
+ $Id: user-manual.sgml,v 1.76 2002/04/16 04:25:51 hal9 Exp $
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
--->
-<!--
-Sat 03/02/02 04:53:47 PM
-This should be ready for BETA release.
+ ========================================================================
+ NOTE: Please read developer-manual/documentation.html before touching
+ anything in this, or other Privoxy documentation.
+ ========================================================================
-Hal Burgiss <hal@foobox.net>
-->
<article id="index">
<artheader>
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.58 2002/03/26 22:29:55 swa Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.76 2002/04/16 04:25:51 hal9 Exp $</pubdate>
<authorgroup>
<author>
</authorgroup>
<abstract>
+<![%dummy;[
<para>
- The user manual gives users information on how to install, configure and use
- <application>Privoxy</application>. <application>Privoxy</application> 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. <application>Privoxy</application> has a very flexible configuration
- and can be customized to suit individual needs and
- tastes. <application>Privoxy</application> has application for both
- stand-alone systems and multi-user networks.
+ <comment>
+ This is here to keep vim syntax file from breaking :/
+ If I knew enough to fix it, I would.
+ PLEASE DO NOT REMOVE! HB: hal@foobox.net
+ </comment>
</para>
+]]>
+
<para>
-You can find the latest version of the user manual at <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
- </para>
+ The user manual gives users information on how to install, configure and use
+ <ulink
+ url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
+ </para>
+
+<!-- Include privoxy.sgml boilerplate: -->
+ &p-intro;
+<!-- end privoxy.sgml -->
+
+ <para>
+ You can find the latest version of the user manual at <ulink
+ url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
+ Please see the <ulink url="contact.html">Contact section</ulink> on how to
+ contact the developers.
+ </para>
<!-- <para> -->
<!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
</artheader>
-
<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="intro" label=""><title></title>
+<!-- dummy section to force TOC on page by itself -->
+<!-- DO NOT REMOVE! please ;) -->
+<para> </para>
+</sect1>
-<sect1 id="introduction"><title>Introduction</title>
-<para>
- <application>Privoxy</application> 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. <application>Privoxy</application> has a very
- flexible configuration and can be customized to suit individual needs and
- tastes. <application>Privoxy</application> has application for both
- stand-alone systems and multi-user networks.
-</para>
-
-<para>
- <application>Privoxy</application> is based on the code of the
- <application>Internet Junkbuster</application>.
- <application>Junkbuster</application> 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.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
-<para>
- <application>Privoxy</application> continues the
- <application>Junkbuster</application> tradition, but adds many
- refinements and enhancements.
-</para>
+<sect1 label="1" id="introduction"><title>Introduction</title>
<para>
- This documentation is included with the current BETA version of
- <application>Privoxy</application> 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 <quote>soon</quote> ;-)
+ This documentation is included with the current &p-status; version of
+ <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
+ 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 <quote>soon</quote> ;-)]]>.
</para>
+<![%p-not-stable;[
+<!-- include only in non-stable versions -->
<para>
- Since this is a BETA version, not all new features are well tested. This
+ Since this is a &p-status; version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with
CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
not many!
</para>
-
+]]>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="newfeatures">
<title>New Features</title>
<para>
In addition to <application>Internet Junkbuster's</application> traditional
feature of ad and banner blocking and cookie management,
- <application>Privoxy</application> provides new features, some of them
- currently under development:
-</para>
-
-<!--
- The section is in both user-manual and faq. Please keep in sync.
--->
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Integrated browser based configuration and control utility (<ulink
- url="http://p.p">http://p.p</ulink>). Browser-based tracing of rule
- and filter effects.
- </para>
- </listitem>
-<!--
- <listitem>
- <para>
- Modularized configuration that will allow for system wide settings, and
- individual user settings. (not implemented yet, probably a 3.1 feature)
- </para>
- </listitem>
--->
- <listitem>
- <para>
- Blocking of annoying pop-up browser windows.
- </para>
- </listitem>
-
- <listitem>
- <para>
- HTTP/1.1 compliant (most, but not all 1.1 features are supported).
- </para>
- </listitem>
-
- <listitem>
- <para>
- Support for Perl Compatible Regular Expressions in the configuration files, and
- generally a more sophisticated and flexible configuration syntax over
- previous versions.
- </para>
- </listitem>
-
- <listitem>
- <para>
- GIF de-animation.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Web page content filtering (removes banners based on size,
- invisible <quote>web-bugs</quote>, JavaScript, pop-ups, status bar abuse,
- etc.)
- </para>
- </listitem>
-
- <listitem>
- <para>
- Bypass many click-tracking scripts (avoids script redirection).
-
- </para>
- </listitem>
-
- <listitem>
- <para>
- Multi-threaded (POSIX and native threads).
- </para>
- </listitem>
-
- <listitem>
- <para>
- Auto-detection and re-reading of config file changes.
- </para>
- </listitem>
-
- <listitem>
- <para>
- User-customizable HTML templates (e.g. 404 error page).
- </para>
- </listitem>
-
- <listitem>
- <para>
- Improved cookie management features (e.g. session based cookies).
- </para>
-</listitem>
-
- <listitem>
- <para>
- 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.
-
- </para>
- </listitem>
-
- <listitem>
- <para>
- In addition, the configuration is much more powerful and versatile over-all.
- </para>
-</listitem>
-
- </itemizedlist>
+ <application>Privoxy</application> provides new features<![%p-not-stable;[,
+ some of them currently under development]]>:
+<anchor id="testing"/>
</para>
+<!-- Include newfeatures.sgml boilerplate here: -->
+ &newfeatures;
+<!-- end boilerplate -->
</sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="installation"><title>Installation</title>
<para>
- <application>Privoxy</application> is available as raw source code, or
- pre-compiled binaries. See the <ulink
- url="http://sourceforge.net/projects/ijbswa/">Privoxy Home Page</ulink>
- for binaries and current release info. <application>Privoxy</application>
- is also available via <ulink
- url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/current/">CVS</ulink>.
- This is the recommended approach at this time. But please be aware that CVS
- is constantly changing, and it may break in mysterious ways.
+ <application>Privoxy</application> is available both in convenient pre-compiled
+ packages for a wide range of operating systems, and as raw source code.
+ For most users, we recommend using the packages, which can be downloaded from our
+ <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
+</para>
+<para>
+ If you like to live on the bleeding edge and are not afraid of using
+ possibly unstable development versions, you can check out the up-to-the-minute
+ version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
+ CVS repository</ulink> or simply download <ulink
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
+ tarball.</ulink>
</para>
+<!-- Include supported.sgml boilerplate -->
+&supported;
+<!-- end boilerplate -->
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-source"><title>Source</title>
+<sect2 id="installation-packages"><title>Binary Packages</title>
<para>
- For gzipped tar archives, unpack the source:
+ The packages can be downloaded from our <ulink
+ url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
</para>
<para>
- <screen>
- tar xzvf privoxy-2.9.13-beta-src* [.tgz or .tar.gz]
- cd privoxy-2.9.13-beta
- </screen>
+ How to install them depends on your operating system:
</para>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-rpm"><title>Redhat and SuSE RPMs</title>
+
<para>
- For retrieving the current CVS sources, you'll need the CVS
- package installed first. To download CVS source:
+ RPMs can be installed with <literal>rpm -i <name-of-rpm.rpm></literal>,
+ and will use <filename>/etc/privoxy</filename> for configuration files.
</para>
<para>
- <screen>
- 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
- </screen>
+ Note that if you have a Junkbuster RPM installed on your system, you
+ need to remove it first, because the packages conflict.
</para>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
<para>
- This will create a directory named <filename>current/</filename>, which will
- contain the source tree.
+ Create a new directory, <literal>cd</literal> to it, then unzip and
+ untar the archive. For the most part, you'll have to figure out where
+ things go. FIXME.
</para>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-pack-win"><title>Windows</title>
<para>
- Then, in either case, to build from tarball/CVS source:
+ Just double-click the installer, which will guide you through
+ the installation process.
</para>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-os2"><title>OS/2</title>
<para>
- <screen>
- ./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)
- </screen>
+ Just double-click the WarpIN self-installing archive, which will guide
+ you through the installation process. A shadow of the
+ <application>Privoxy</application> executable will be placed in your
+ startup folder so it will start automatically whenever OS/2 starts.
</para>
<para>
- For Redhat and SuSE Linux RPM packages, see below.
+ The directory you choose to install <application>Privoxy</application>
+ into will contain all of the configuration files.
</para>
-
-</sect2>
-
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-rh"><title>Red Hat</title>
+<sect3 id="installation-deb"><title>Debian</title>
<para>
- To build Redhat RPM packages, install source as above. Then:
+ FIXME.
</para>
+</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installation-amiga"><title>AmigaOS</title>
<para>
- <screen>
- autoheader
- autoconf
- ./configure
- make redhat-dist
- </screen>
+ Unpack the <literal>.lha</literal> archive, then FIXME.
</para>
+</sect3>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-source"><title>Building from Source</title>
+
+<!-- include buildsource.sgml boilerplate: -->
+&buildsource;
+<!-- end boilerplate -->
<para>
- This will create both binary and src RPMs in the usual places. Example:
+ For more detailed instructions, on how to build Redhat and SuSE RPMs,
+ Windows self-extracting installers etc, please consult the <ulink
+ url="../developer-manual/newrelease.html">developer manual</ulink>.
</para>
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="upgradersnote">
+<title>Note to Upgraders</title>
<para>
- /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ There are very significant changes from older versions of
+ <application>Junkbuster</application> to the current
+ <application>Privoxy</application>. Configuration is substantially
+ changed. <application>Junkbuster 2.0.x</application> and earlier
+ configuration files will not migrate. The functionality of the old
+ <filename>blockfile</filename>, <filename>cookiefile</filename> and
+ <filename>imagelist</filename>, are now combined into the
+ <quote>actions file</quote> (<filename>default.action</filename>
+ for most installations).
</para>
<para>
- /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.rpm
+ A <quote>filter file</quote> (typically <filename>default.filter</filename>)
+ is new with <application>Privoxy 2.9.x</application>, and provides some
+ of the new sophisticaton (explained below). <filename>config</filename> is
+ much the same as before.
</para>
-
<para>
- To install, of course:
+ If upgrading from a 2.0.x version, you will have to use the new config
+ files, and possibly adapt any personal rules from your older files.
+ When porting personal rules over from the old <filename>blockfile</filename>
+ to the new actions file, please note that even the pattern syntax has
+ changed.
+ If upgrading from 2.9.x development versions, it is still recommended
+ to use the new configuration files.
</para>
-
<para>
- <screen>
- rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
- </screen>
+ A quick list of things to be aware of before upgrading:
</para>
<para>
- This will place the <application>Privoxy</application> configuration
- files in <filename>/etc/privoxy/</filename>, and log files in
- <filename>/var/log/privoxy/</filename>.
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The default listening port is now 8118 due to a conflict with another
+ service (NAS).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Some installers may remove earlier versions completely. Save any
+ important configuration files!
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Privoxy</application> is controllable with a web browser
+ at the special URL: <ulink
+ url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (Shortcut: <ulink url="http://p.p/">http://p.p/</ulink>). Many
+ aspects of configuration can be done here, including temporarily disabling
+ <application>Privoxy</application>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The primary configuration file for cookie management, ad and banner
+ blocking, and many other aspects of <application>Privoxy</application>
+ configuration is <filename>default.action</filename>. It is strongly
+ recommended to make oneself familiar with the new actions concept below
+ before modifying that file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- I think it is best to keep this somewhat vague, in case -->
+<!-- the situation changes under our feet. -->
+ Some installers may not automatically start
+ <application>Privoxy</application> after installation.
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-suse"><title>SuSE</title>
+<sect2 id="startup">
+<title>Starting <application>Privoxy</application></title>
<para>
- To build SuSE RPM packages, install source as above. Then:
+ Before launching <application>Privoxy</application> for the first time, you
+ will want to configure your browser(s) to use <application>Privoxy</application>
+ as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
+ and port 8118 (earlier versions used port 8000). This is the one required
+ configuration that must be done!
</para>
-
-<para>
- <screen>
- autoheader
- autoconf
- ./configure
- make suse-dist
- </screen>
+
+<para>
+ With <application>Netscape</application> (and
+ <application>Mozilla</application>), this can be set under <literal>Edit
+ -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
+ For <application>Internet Explorer</application>: <literal>Tools ->
+ Internet Properties -> Connections -> LAN Setting</literal>. Then,
+ check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
+ localhost, Port: 8118). Include if HTTPS proxy support too.
</para>
<para>
- This will create both binary and src RPMs in the usual places. Example:
+ 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
+ <application>Privoxy</application>.
</para>
+
<para>
- /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ <application>Privoxy</application> is typically started by specifying the
+ main configuration file to be used on the command line. Example Unix startup
+ command:
</para>
+
<para>
- /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.rpm
+ <screen>
+
+ # /usr/sbin/privoxy /etc/privoxy/config
+
+ </screen>
</para>
<para>
- To install, of course:
+ An init script is provided for SuSE and Redhat.
</para>
<para>
- <screen>
- rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
- </screen>
+ For for SuSE: <command>rcprivoxy start</command>
</para>
<para>
- This will place the <application>Privoxy</application> configuration
- files in <filename>/etc/privoxy/</filename>, and log files in
- <filename>/var/log/privoxy/</filename>.
+ For RedHat: <command>/etc/rc.d/init.d/privoxy start</command>
</para>
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-os2"><title>OS/2</title>
+<para>
+ If no configuration file is specified on the command line,
+ <application>Privoxy</application> will look for a file named
+ <filename>config</filename> in the current directory. Except on Win32 where
+ it will try <filename>config.txt</filename>. If no file is specified on the
+ command line and no default configuration file can be found,
+ <application>Privoxy</application> will fail to start.
+</para>
-<!--
-Thanx David Schmidt!
--->
<para>
- <application>Privoxy</application> is packaged in a WarpIN self-
- installing archive. The self-installing program will be named depending
- on the release version, something like:
- <filename>ijbos2_setup_1.2.3.exe</filename>. 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 <application>Privoxy</application>
- executable will be placed in your startup folder so it will start
- automatically whenever OS/2 starts.
+ The included default configuration files should give a reasonable starting
+ point. Most of the per site configuration is done in the
+ <quote>actions</quote> files. These are where various cookie actions are
+ defined, ad and banner blocking, and other aspects of
+ <application>Privoxy</application> configuration. There are several such
+ files included, with varying levels of aggressiveness.
</para>
<para>
- The directory you choose to install <application>Privoxy</application>
- into will contain all of the configuration files.
+ You will probably want to keep an eye out for sites that require persistent
+ cookies, and add these to <filename>default.action</filename> as needed. By
+ default, most of these will be accepted only during the current browser
+ session (aka <quote>session cookies</quote>), until you add them to the
+ configuration. If you want the browser to handle this instead, you will need
+ to edit <filename>default.action</filename> and disable this feature. If you
+ use more than one browser, it would make more sense to let
+ <application>Privoxy</application> handle this. In which case, the
+ browser(s) should be set to accept all cookies.
</para>
<para>
- 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.
+ Another feature where you will propably want to define exceptions for trusted
+ sites is the popup-killing (through the <literal>+popup</literal> and
+ <literal>+filter{popups}</literal> actions), because your favourite shopping,
+ banking, or leisure site may need popups.
</para>
<para>
- In addition to needing the source code distribution as outlined earlier,
- you will want to extract the <filename>os2seutp</filename> directory from CVS:
- <screen>
- cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
- </screen>
- This will create a directory named os2setup/, which will contain the
- <filename>Makefile.vac</filename> makefile and <filename>os2build.cmd</filename>
- which is used to completely create the binary distribution. The sequence
- of events for building the executable for yourself goes something like this:
- <screen>
- cd current
- autoheader
- autoconf
- sh configure
- cd ..\os2setup
- nmake -f Makefile.vac
- </screen>
- You will see this sequence laid out in <filename>os2build.cmd</filename>.
+ <application>Privoxy</application> is HTTP/1.1 compliant, but not all of
+ the optional 1.1 features are as yet supported. In the unlikely event that
+ you experience inexplicable problems with browsers that use HTTP/1.1 per default
+ (like <application>Mozilla</application> or recent versions of I.E.), you might
+ try to force HTTP/1.0 compatibility. For Mozilla, look under <literal>Edit ->
+ Preferences -> Debug -> Networking</literal>.
+ Alternatively, set the <quote>+downgrade</quote> config option in
+ <filename>default.action</filename> which will downgrade you brower's HTTP
+ requests from HTTP/1.1 to HTTP/1.0 before processing them.
</para>
-</sect2>
+<para>
+ After running <application>Privoxy</application> 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. <quote>Actions</quote> (as specified in <filename>default.action</filename>)
+ can be adjusted by pointing your browser to
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
+ and then follow the link to <quote>edit the actions list</quote>.
+ (This is an internal page and does not require Internet access.)
+</para>
+<para>
+ In fact, various aspects of <application>Privoxy</application>
+ configuration can be viewed from this page, including
+ current configuration parameters, source code version numbers,
+ the browser's request headers, and <quote>actions</quote> that apply
+ to a given URL. In addition to the <filename>default.action</filename> file
+ editor mentioned above, <application>Privoxy</application> can also
+ be turned <quote>on</quote> and <quote>off</quote> (toggled) from this page.
+</para>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-win"><title>Windows</title>
-<para>Click-click. (I need help on this. Not a clue here. Also for
-configuration section below. HB.)
+<para>
+ If you encounter problems, try loading the page without
+ <application>Privoxy</application>. If that helps, enter the URL where
+ you have the problems into <ulink url="http://p.p/show-url-info">the browser
+ based rule tracing utility</ulink>. Watch out which rules apply and why, and
+ then try turning them off for that site one after the other, until the problem
+ is gone. When you have found the culprit, you might want to turn the rest on
+ again.
</para>
-</sect2>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-other"><title>Other</title>
<para>
- Some quick notes on other Operating Systems.
+ If the above paragraph sounds gibberish to you, you might want to <ulink
+ url="configuration.html#ACTIONSFILE">read more about the actions concept</ulink>
+ or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
+ on actions</ulink>.
</para>
<para>
- For FreeBSD (and other *BSDs?), the build will require <command>gmake</command>
- instead of the included <command>make</command>. <command>gmake</command> is
- available from <ulink url="http://www.gnu.org">http://www.gnu.org</ulink>.
- The rest should be the same as above for Linux/Unix.
+ If you can't get rid of the problem at all, think you've found a bug in
+ Privoxy, want to propose a new feature or smarter rules, please see the
+ chapter "Contacting the Developers, .." below.
</para>
</sect2>
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
- <para>
- All <application>Privoxy</application> configuration is kept
- in text files. These files can be edited with a text editor.
- Many important aspects of <application>Privoxy</application> can
- also be controlled easily with a web browser.
-
- </para>
-
<!-- ~~~~~ New section ~~~~~ -->
-
+<sect2>
+<title>Command Line Options</title>
+<para>
+ <application>Privoxy</application> may be invoked with the following
+ command-line options:
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>--version</emphasis>
+ </para>
+ <para>
+ Print version info and exit, Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--help</emphasis>
+ </para>
+ <para>
+ Print a short usage info and exit, Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--no-daemon</emphasis>
+ </para>
+ <para>
+ Don't become a daemon, i.e. don't fork and become process group
+ leader, don't detach from controlling tty. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--pidfile FILE</emphasis>
+
+ </para>
+ <para>
+ On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
+ <emphasis>FILE</emphasis> on exit. Failiure to create or delete the
+ <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
+ option is given, no PID file will be used. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>--user USER[.GROUP]</emphasis>
+
+ </para>
+ <para>
+ After (optionally) writing the PID file, assume the user ID of
+ <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
+ privileges are not sufficient to do so. Unix only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>configfile</emphasis>
+ </para>
+ <para>
+ If no <emphasis>configfile</emphasis> is included on the command line,
+ <application>Privoxy</application> will look for a file named
+ <quote>config</quote> in the current directory (except on Win32
+ where it will look for <quote>config.txt</quote> instead). Specify
+ full path to avoid confusion.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="configuration"><title><application>Privoxy</application> Configuration</title>
+ <para>
+ All <application>Privoxy</application> configuration is stored
+ in text files. These files can be edited with a text editor.
+ Many important aspects of <application>Privoxy</application> can
+ also be controlled easily with a web browser.
+
+ </para>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
<sect2>
<title>Controlling <application>Privoxy</application> with Your Web Browser</title>
<para>
- <application>Privoxy</application> can be reached by the special
- URL <ulink url="http://p.p/">http://p.p/</ulink> (or alternately
- <ulink url="http://www.privoxy.org/config/">http://www.privoxy.org/config/</ulink>),
- which is an internal page. You will see the following section:
+ <application>Privoxy</application>'s user interface can be reached through the special
+ URL <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
+ which is a built-in page and works without internet access.
+ You will see the following section:
</para>
Please choose from the following options:
+ * Privoxy main page
* Show information about the current configuration
* Show the source code version numbers
- * Show the client's request headers.
+ * Show the request headers.
* Show which actions apply to a URL and why
* Toggle Privoxy on or off
* Edit the actions list
<application>Privoxy</application>. This is an easy way to adjust various
aspects of <application>Privoxy</application> configuration. The actions
file, and other configuration files, are explained in detail below.
- <application>Privoxy</application> will automatically detect any changes
- to these files.
</para>
<para>
<quote>Toggle Privoxy On or Off</quote> 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 <application>Privoxy</application>
+ have problems with your current actions and filters. You can in fact use
+
it as a test to see whether it is <application>Privoxy</application>
causing the problem or not. <application>Privoxy</application> continues
- to run as a proxy in this case, but all filtering is disabled.
+ to run as a proxy in this case, but all filtering is disabled. There
+ is even a toggle Bookmarklet offered, so that you can toggle
+ <application>Privoxy</application> with one click from your browser.
</para>
For Unix, *BSD and Linux, all configuration files are located in
<filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
AmigaOS these are all in the same directory as the
- <application>Privoxy</application> executable. The name and number of
- configuration files has changed from previous versions, and is subject to
- change as development progresses.
+ <application>Privoxy</application> executable. <![%p-not-stable;[ The name
+ and number of configuration files has changed from previous versions, and is
+ subject to change as development progresses.]]>
</para>
<para>
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):
+ default configuration files (this may change in time):
</para>
<para>
<listitem>
<para>
- The <filename>default.action</filename> file is used to define various
- <quote>actions</quote> 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 <ulink
- url="http://p.p">http://p.p</ulink>. (Other actions
- files are included as well with differing levels of filtering
- and blocking, e.g. <filename>ijb-basic.action</filename>.)
+ <filename>default.action</filename> (the actions file) is used to define
+ which of a set of various <quote>actions</quote> relating to images, banners,
+ pop-ups, access restrictions, banners and cookies are to be applied where.
+ There is a web based editor for this file that can be accessed at <ulink
+ url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
+ (Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).
+ (Other actions files are included as well with differing levels of filtering
+ and blocking, e.g. <filename>basic.action</filename>.)
</para>
</listitem>
<listitem>
<para>
- The <filename>default.filter</filename> file can be used to re-write the raw
+ <filename>default.filter</filename> (the filter file) can be used to re-write the raw
page content, including viewable text as well as embedded HTML and JavaScript,
- and whatever else lurks on any given web page.
+ and whatever else lurks on any given web page. The filtering jobs are only
+ pre-defined here; whether to apply them or not is up to the actions file.
</para>
</listitem>
</itemizedlist>
</para>
+<para>
+ All files use the <quote><literal>#</literal></quote> character to denote a
+ comment (the rest of the line will be ignored) and understand line continuation
+ through placing a backslash ("<literal>\</literal>") as the very last character
+ in a line. If the <literal>#</literal> is preceded by a backslash, it looses
+ its special function. Placing a <literal>#</literal> in front of an otherwise
+ valid configuration line to prevent it from being interpreted is called "commenting
+ out" that line.
+</para>
+
<para>
<filename>default.action</filename> and <filename>default.filter</filename>
- can use Perl style regular expressions for maximum flexibility. All files use
- the <quote><literal>#</literal></quote> character to denote a comment. Such
- lines are not processed by <application>Privoxy</application>. After
- making any changes, there is no need to restart
+ can use Perl style regular expressions for maximum flexibility.
+</para>
+
+<para>
+ After making any changes, there is no need to restart
<application>Privoxy</application> in order for the changes to take
- effect. <application>Privoxy</application> should detect such changes
- automatically.
+ effect. <application>Privoxy</application> detects such changes
+ automatically. Note, however, that it may take one or two additional
+ requests for the change to take effect. When changing the listening address
+ of <application>Privoxy</application>, these <quote>wake up</quote> requests
+ must obviously be sent to the <emphasis>old</emphasis> listening address.
</para>
+<![%p-not-stable;[
<para>
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 <quote>default</quote> setting, may change, so
please check all your configuration files on important issues.
</para>
+]]>
</sect2>
<literal>
<msgtext>
<literallayout>
- <emphasis>blockfile blocklist.ini</emphasis>
+ <emphasis>confdir /etc/privoxy</emphasis>
</literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- Indicates that the blockfile is named <quote>blocklist.ini</quote>. (A
- default installation does not use this.)
-</para>
-
-<para>
- A <quote><literal>#</literal></quote> indicates a comment. Any part of a
- line following a <quote><literal>#</literal></quote> is ignored, except if
- the <quote><literal>#</literal></quote> is preceded by a
- <quote><literal>\</literal></quote>.
+ </msgtext>
+ </literal>
</para>
<para>
- Thus, by placing a <quote><literal>#</literal></quote> 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 <quote>commenting out</quote> an
- option and can be useful to turn off features: If you comment out the
- <quote>logfile</quote> line, <application>Privoxy</application> will not
- log to a file at all. Watch for the <quote>default:</quote> section in each
- explanation to see what happens if the option is left unset (or commented
- out).
+ Assigns the value <literal>/etc/privoxy</literal> to the option
+ <literal>confdir</literal> and thus indicates that the configuration
+ directory is named <quote>/etc/privoxy/</quote>.
</para>
<para>
- Long lines can be continued on the next line by using a
- <quote><literal>\</literal></quote> as the very last character.
+ All options in the config file except for <literal>confdir</literal> and
+ <literal>logdir</literal> are optional. Watch out in the below description
+ for what happens if you leave them unset.
</para>
<para>
- There are various aspects of <application>Privoxy</application> behavior
- that can be tuned.
+ The main config file controls all aspects of <application>Privoxy</application>'s
+ operation that are not location dependent (i.e. that apply invariantly no matter
+ where in the web you are surfing).
</para>
<!-- ~~~~~ New section ~~~~~ -->
<sect3>
-<title>Defining Other Configuration Files</title>
-
-<para>
- <application>Privoxy</application> 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 <application>Privoxy</application> where to find
- all those other files.
-</para>
-
-<para>
- On <application>Windows</application> and <application>AmigaOS</application>,
- <application>Privoxy</application> looks for these files in the same
- directory as the executable. On Unix and OS/2,
- <application>Privoxy</application> looks for these files in the current
- working directory. In either case, an absolute path name can be used to
- avoid problems.
-</para>
+<title>Configuration and Log File Locations</title>
<para>
- When development goes modular and multi-user, the blocker, filter, and
- per-user config will be stored in subdirectories of <quote>confdir</quote>.
- For now, only <filename>confdir/templates</filename> is used for storing HTML
- templates for CGI results.
+ <application>Privoxy</application> can (and normally does) use a number of
+ other files for addidtional configuration and logging.
+ This section of the configuration file tells <application>Privoxy</application>
+ where to find those other files.
</para>
-<para>
- The location of the configuration files:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>confdir /etc/privoxy</emphasis> # No trailing /, please.
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<sect4><title>confdir</title>
-<para>
- The directory where all logging (i.e. <filename>logfile</filename> and
- <filename>jarfile</filename>) takes place. No trailing
- <quote><literal>/</literal></quote>, please:
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>The directory where the other configuration files are located</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Path name</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>/etc/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para><emphasis>Mandatory</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ No trailing <quote><literal>/</literal></quote>, please
+ </para>
+ <para>
+ When development goes modular and multi-user, the blocker, filter, and
+ per-user config will be stored in subdirectories of <quote>confdir</quote>.
+ For now, the configuration dir structure is flat, except for
+ <filename>confdir/templates</filename>, where the HTML templates for CGI
+ output reside.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>logdir /var/log/privoxy</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-<para>
- Note that all file specifications below are relative to
- the above two directories!
-</para>
+<sect4><title>logdir</title>
-<para>
- The <quote>default.action</quote> 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 <quote>default.filter</quote>. No sites
- are blocked. <application>Privoxy</application> displays a checkboard type
- pattern for filtered ads and other images. The syntax of this file is
- explained in detail <link linkend="actionsfile">below</link>. Other
- <quote>actions</quote> files are included, and you are free to use any of
- them. They have varying degrees of aggressiveness.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The directory where all logging takes place (i.e. where <filename>logfile</filename> and
+ <filename>jarfile</filename> are located)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Path name</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>/var/log/privoxy (Unix) <emphasis>or</emphasis> <application>Privoxy</application> installation dir (Windows) </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para><emphasis>Mandatory</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ No trailing <quote><literal>/</literal></quote>, please
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>actionsfile default.action</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<sect4><title>actionsfile</title>
-<para>
- The <quote>default.filter</quote> file contains content modification rules
- that use <quote>regular expressions</quote>. 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 <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
- it appears on a Web page. Default: whatever the developers are playing with
- :-/
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The actions file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>default.action (Unix) <emphasis>or</emphasis> default.action.txt (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No action is taken at all. Simple neutral proxying.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ There is no point in using <application>Privoxy</application> without
+ an actions file.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- 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.
+<sect4><title>actionsfile</title>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The actions file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>default.action (Unix) <emphasis>or</emphasis> default.action.txt (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No action is taken at all. Simple neutral proxying.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ There is no point in using <application>Privoxy</application> without
+ an actions file. There are three diffrent actions files included in the
+ distribution, with varying degrees of aggressiveness:
+ <filename>default.action</filename>, <filename>intermediate.action</filename> and
+ <filename>advanced.action</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>filterfile default.filter</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<sect4><title>filterfile</title>
-<para>
- The logfile is where all logging and error messages are written. The logfile
- can be useful for tracking down a problem with
- <application>Privoxy</application> (e.g., it's not blocking an ad you
- think it should block) but in most cases you probably will never look at it.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The filter file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>default.filter (Unix) <emphasis>or</emphasis> default.filter.txt (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No textual content filtering takes place, i.e. all
+ <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
+ actions in the actions file are turned off
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The <quote>default.filter</quote> file contains content modification rules
+ that use <quote>regular expressions</quote>. 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 <quote>Microsoft</quote> with <quote>MicroSuck</quote> wherever
+ it appears on a Web page.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- 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 <quote>man cron</quote>). For Redhat, a <command>logrotate</command>
- script has been included.
-</para>
+<sect4><title>logfile</title>
-<para>
- On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
- +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
- the effect that cron.daily will automatically archive, gzip, and empty the
- log, when it exceeds 1M size.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The log file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>logdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>logfile (Unix) <emphasis>or</emphasis> privoxy.log (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No log file is used, all log messages go to the console (<literal>stderr</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The windows version will additionally log to the console
+ </para>
+ <para>
+ The logfile is where all logging and error messages are written. The level
+ of detail and number of messages are set with the <literal>debug</literal>
+ option (see below). The logfile can be useful for tracking down a problem with
+ <application>Privoxy</application> (e.g., it's not blocking an ad you
+ think it should block) but in most cases you probably will never look at it.
+ </para>
+ <para>
+ 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 <quote>man cron</quote>). For Redhat, a <command>logrotate</command>
+ script has been included.
+ </para>
+ <para>
+ On SuSE Linux systems, you can place a line like <quote>/var/log/privoxy.*
+ +1024k 644 nobody.nogroup</quote> in <filename>/etc/logfiles</filename>, with
+ the effect that cron.daily will automatically archive, gzip, and empty the
+ log, when it exceeds 1M size.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- Default: Log to the a file named <filename>logfile</filename>.
- Comment out to disable logging.
-</para>
+<sect4><title>jarfile</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>logfile logfile</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The file to store intercepted cookies in
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>logdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>jarfile (Unix) <emphasis>or</emphasis> privoxy.jar (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Intercepted cookies are not stored at all.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The jarfile may grow to ridiculous sizes over time.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- The <quote>jarfile</quote> defines where
- <application>Privoxy</application> stores the cookies it intercepts. Note
- that if you use a <quote>jarfile</quote>, it may grow quite large. Default:
- Don't store intercepted cookies.
-</para>
+<sect4><title>trustfile</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#jarfile jarfile</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- If you specify a <quote>trustfile</quote>,
- <application>Privoxy</application> 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
- <quote>trustfile</quote>. This is a very restrictive feature that typical
- users most probably want to leave disabled. Default: Disabled, don't use the
- trust mechanism.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#trustfile trust</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- 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 <quote>untrusted</quote> info page.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>trust-info-url http://www.your-site.com/why_we_block.html</emphasis>
- <emphasis>trust-info-url http://www.your-site.com/what_we_allow.html</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The trust file to use
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>File name, relative to <literal>confdir</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset (commented out)</emphasis>. When activated: trust (Unix) <emphasis>or</emphasis> trust.txt (Windows)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The whole trust mechansim is turned off.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The trust mechansim is an experimental feature for building whitelists and should
+ be used with care. It is <emphasis>NOT</emphasis> recommended for the casual user.
+ </para>
+ <para>
+ If you specify a trust file, <application>Privoxy</application> will only allow
+ access to sites that are named in the trustfile.
+ You can also mark sites as trusted referrers (with <literal>+</literal>), 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 <quote>trustfile</quote>.
+ Possible applications include limiting internet access for children.
+ </para>
+ <para>
+ If you use <literal>+</literal> operator in the trust file, it may grow considerably over time.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<sect3>
-<title>Other Configuration Options</title>
-
-<para>
- This part of the configuration file contains options that control how
- <application>Privoxy</application> operates.
-</para>
+<title>Local Setup Documentation</title>
-<para>
- <quote>Admin-address</quote> 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.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#admin-address fill@me.in.please</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <para>
+ If you intend to operate <application>Privoxy</application> for more users
+ that just yourself, it might be a good idea to let them know how to reach
+ you, what you block and why you do that, your policies etc.
+ </para>
-<para>
- <quote>Proxy-info-url</quote> can be set to a URL that contains more info
- about this <application>Privoxy</application> 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.
-</para>
+<sect4><title>trust-info-url</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>proxy-info-url http://www.your-site.com/proxy.html</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A URL to be displayed in the error page that users will see if access to an untrusted page is denied.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>Two example URL are provided</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No links are displayed on the "untrusted" error page.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The value of this option only matters if the experimental trust mechanism has been
+ activated. (See <literal>trustfile</literal> above.)
+ </para>
+ <para>
+ If you use the trust mechanism, it is a good idea to write up some online
+ documentation about your trust policy and to specify the URL(s) here.
+ Use multiple times for multiple URLs.
+ </para>
+ <para>
+ The URL(s) should be added to the trustfile as well, so users don't end up
+ locked out from the information on why they were locked out in the first place!
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <quote>Listen-address</quote> specifies the address and port where
- <application>Privoxy</application> 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 <quote>localhost</quote> and the
- port as <quote>8118</quote>).
-</para>
+<sect4><title>admin-address</title>
-<para>
- 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
- <quote>listen-address [<ip-address>]:<port></quote>. If you leave
- out the IP address, <application>Privoxy</application> 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
- <quote>aclfile</quote> above), or a firewall.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ An email address to reach the proxy administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Email address</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No email address is displayed on error pages and the CGI user interface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
+ are unset, the whole "Local Privoxy Support" box on all generated pages will
+ not be shown.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
+
+<sect4><title>proxy-info-url</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A URL to documentation about the local <application>Privoxy</application> setup,
+ configuration or policies.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No link to local documentation is displayed on error pages and the CGI user interface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If both <literal>admin-address</literal> and <literal>proxy-info-url</literal>
+ are unset, the whole "Local Privoxy Support" box on all generated pages will
+ not be shown.
+ </para>
+ <para>
+ This URL shouldn't be blocked ;-)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- For example, suppose you are running <application>Privoxy</application> 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:
-</para>
+</sect3>
+<!-- ~ End section ~ -->
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>listen-address 192.168.0.1:8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
-<para>
- If you want it to listen on all addresses (including the outside
- connection):
-</para>
+<sect3>
+<title>Debugging</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>listen-address :8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <para>
+ These options are mainly useful when tracing a problem.
+ Note that you might also want to invoke
+ <application>Privoxy</application> with the <literal>--no-daemon</literal>
+ command line option when debugging.
+ </para>
-<para>
- If you do this, consider using ACLs (see <quote>aclfile</quote> 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).
-</para>
+<sect4><title>debug</title>
-<para>
- 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.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Keys that determine what information gets logged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Integer values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>12289 (i.e.: URLs plus informational and warning messages)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Nothing gets logged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ The available debug levels are:
+ </para>
+ <para>
+ <programlisting>
+ debug 1 # show each GET/POST/CONNECT request
+ debug 2 # show each connection status
+ debug 4 # show I/O status
+ debug 8 # show header parsing
+ debug 16 # log all data into the logfile
+ debug 32 # debug force feature
+ debug 64 # debug regular expression filter
+ debug 128 # debug fast redirects
+ debug 256 # debug GIF de-animation
+ debug 512 # Common Log Format
+ debug 1024 # debug kill pop-ups
+ debug 4096 # Startup banner and warnings.
+ debug 8192 # Non-fatal errors
+ </programlisting>
+ </para>
+ <para>
+ To select multiple debug levels, you can either add them or use
+ multiple <literal>debug</literal> lines.
+ </para>
+ <para>
+ A debug level of 1 is informative because it will show you each request
+ as it happens. <emphasis>1, 4096 and 8192 are highly recommended</emphasis>
+ so that you will notice when things go wrong. The other levels are probably
+ only of interest if you are hunting down a specific problem. They can produce
+ a hell of output (especially 16).
+ </para>
+ <para>
+ The reporting of <emphasis>fatal</emphasis> errors (i.e. ones which crash
+ <application>Privoxy</application>) is always on and cannot be disabled.
+ </para>
+ <para>
+ If you want to use CLF (Common Log Format), you should set <quote>debug
+ 512</quote> <emphasis>ONLY</emphasis> and not enable anything else.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- 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
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<sect4><title>single-threaded</title>
-<para>
- It is <emphasis>highly recommended</emphasis> that you enable ERROR
- reporting (debug 8192), at least until v3.0 is released.
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether to run only one server thread
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para><emphasis>None</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Multi-threaded (or, where unavailable: forked) operation, i.e. the ability to
+ serve multiple requests simultaneously.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This option is only there for debug purposes and you should never
+ need to use it. <emphasis>It will drastically reduce performance.</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- The reporting of FATAL errors (i.e. ones which crash
- <application>Privoxy</application>) is always on and cannot be disabled.
-</para>
+</sect3>
-<para>
- If you want to use CLF (Common Log Format), you should set <quote>debug
- 512</quote> ONLY, do not enable anything else.
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
-<para>
- Multiple <quote>debug</quote> directives, are OK - they're logical-OR'd
- together.
-</para>
+<sect3>
+<title>Access Control and Security</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>debug 15 # same as setting the first 4 listed above</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+ <para>
+ This section of the config file controls the security-relevant aspects
+ of <application>Privoxy</application>'s configuration.
+ </para>
-<para>
- Default:
-</para>
+<sect4><title>listen-address</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>debug 1 # URLs</emphasis>
- <emphasis>debug 4096 # Info</emphasis>
- <emphasis>debug 8192 # Errors - *we highly recommended enabling this*</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The IP address and TCP port on which <application>Privoxy</application> will
+ listen for client requests.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>[<replaceable class="parameter">IP-Adddress</replaceable>]:<replaceable class="parameter">Port</replaceable></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>localhost:8118</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Bind to localhost (127.0.0.1), port 8118. This is suitable and recommended for
+ home users who run <application>Privoxy</application> on the same machine as
+ their browser.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ You will need to configure your browser(s) to this proxy address and port.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ If you leave out the IP address, <application>Privoxy</application> 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 <quote>Acls</quote> below), or a firewall.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Example:</term>
+ <listitem>
+ <para>
+ Suppose you are running <application>Privoxy</application> 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:
+ </para>
+ <para>
+ <programlisting>
+ listen-address 192.168.0.1:8118
+ </programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <application>Privoxy</application> normally uses
- <quote>multi-threading</quote>, 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
- <quote>single-threaded</quote> option forces
- <application>Privoxy</application> to handle requests sequentially.
- Default: Multi-threaded mode.
-</para>
+<sect4><title>toggle</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>#single-threaded</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Initial state of "toggle" status
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>1 or 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Act as if toggled on
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If set to 0, <application>Privoxy</application> will start in
+ <quote>toggled off</quote> mode, i.e. behave like a normal, content-neutral
+ proxy. See <literal>enable-remote-toggle</literal>
+ below. This is not really useful anymore, since toggling is much easier
+ via <ulink url="http://config.privoxy.org/toggle">the web
+ interface</ulink> then via editing the <filename>conf</filename> file.
+ </para>
+ <para>
+ The windows version will only display the toggle icon in the system tray
+ if this option is present.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- <quote>toggle</quote> allows you to temporarily disable all
- <application>Privoxy's</application> filtering. Just set <quote>toggle
- 0</quote>.
-</para>
-<para>
- The Windows version of <application>Privoxy</application> 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 <quote>Options</quote> menu), one
- choice is <quote>Enable</quote>. Clicking on enable toggles
- <application>Privoxy</application> on and off. This is useful if you want
- to temporarily disable <application>Privoxy</application>, 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 <application>Privoxy</application>
- internal address of <ulink url="http://p.p">http://p.p</ulink> on
- any platform.
-</para>
-
-<para>
- <quote>toggle 1</quote> means <application>Privoxy</application> runs
- normally, <quote>toggle 0</quote> means that
- <application>Privoxy</application> becomes a non-anonymizing non-blocking
- proxy. Default: 1 (on).
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>toggle 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- For content filtering, i.e. the <quote>+filter</quote> and
- <quote>+deanimate-gif</quote> actions, it is necessary that
- <application>Privoxy</application> 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.
-</para>
-
-<para>
- The <application>buffer-limit</application> 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 <quote>buffer-limit</quote>
- Kbytes <emphasis>each</emphasis>, unless you have enabled
- <quote>single-threaded</quote> above.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>buffer-limit 4069</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- To enable the web-based <filename>default.action</filename> file editor set
- <application>enable-edit-actions</application> to 1, or 0 to disable. Note
- that you must have compiled <application>Privoxy</application> with
- support for this feature, otherwise this option has no effect. This
- internal page can be reached at <ulink
- url="http://p.p">http://p.p</ulink>.
- </para>
-
-<para>
- 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.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>enable-edit-actions 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- Allow <application>Privoxy</application> to be toggled on and off
- remotely, using your web browser. Set <quote>enable-remote-toggle</quote>to
- 1 to enable, and 0 to disable. Note that you must have compiled
- <application>Privoxy</application> with support for this feature,
- otherwise this option has no effect.
-</para>
-
-<para>
- Security note: If this is enabled, anyone who can use the proxy can toggle
- it on or off (see <ulink url="http://p.p">http://p.p</ulink>), and
- their changes will affect all users. For shared proxies, you probably want to
- disable this. Default: enabled.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>enable-remote-toggle 1</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3>
-<title>Access Control List (ACL)</title>
-<para>
- 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.
-</para>
-
-<para>
- 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.
-</para>
-
-<para>
- Summary -- if using an ACL:
-</para>
-
- <simplelist>
- <member>
- Client must have permission to receive service.
- </member>
- </simplelist>
- <simplelist>
- <member>
- LAST match in ACL wins.
- </member>
- </simplelist>
- <simplelist>
- <member>
- Default behavior is to deny service.
- </member>
- </simplelist>
-
-<para>
- The syntax for an entry in the Access Control List is:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- ACTION SRC_ADDR[/SRC_MASKLEN] [ DST_ADDR[/DST_MASKLEN] ]
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- Where the individual fields are:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>ACTION</emphasis> = <quote>permit-access</quote> or <quote>deny-access</quote>
-
- <emphasis>SRC_ADDR</emphasis> = client hostname or dotted IP address
- <emphasis>SRC_MASKLEN</emphasis> = number of bits in the subnet mask for the source
-
- <emphasis>DST_ADDR</emphasis> = server or forwarder hostname or dotted IP address
- <emphasis>DST_MASKLEN</emphasis> = number of bits in the subnet mask for the target
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-
-<para>
- The field separator (FS) is whitespace (space or tab).
-</para>
-
-<para>
- IMPORTANT NOTE: If <application>Privoxy</application> is using a
- forwarder (see below) or a gateway for a particular destination URL, the
- <literal>DST_ADDR</literal> that is examined is the address of the forwarder
- or the gateway and <emphasis>NOT</emphasis> the address of the ultimate
- target. This is necessary because it may be impossible for the local
- <application>Privoxy</application> to determine the address of the
- ultimate target (that's often what gateways are used for).
-</para>
-
-<para>
- Here are a few examples to show how the ACL features work:
-</para>
-
-<para>
- <quote>localhost</quote> is OK -- no DST_ADDR implies that
- <emphasis>ALL</emphasis> destination addresses are OK:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access localhost</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- A silly example to illustrate permitting any host on the class-C subnet with
- <application>Privoxy</application> to go anywhere:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access www.privoxy.com/24</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- Except deny one particular IP address from using it at all:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>deny-access ident.privoxy.com</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- You can also specify an explicit network address and subnet mask.
- Explicit addresses do not have to be resolved to be used.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access 207.153.200.0/24</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- A subnet mask of 0 matches anything, so the next line permits everyone.
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access 0.0.0.0/0</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- Note, you <emphasis>cannot</emphasis> say:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access .org</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- to allow all *.org domains. Every IP address listed must resolve fully.
-</para>
-
-<para>
- An ISP may want to provide a <application>Privoxy</application> that is
- accessible by <quote>the world</quote> 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:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>permit-access 0.0.0.0/0 0.0.0.0/0</emphasis> # other clients can go anywhere
- # with the following exceptions:
-
- <emphasis>deny-access</emphasis> 0.0.0.0/0 123.124.0.0/16 # block all external requests for
- # sites on the ISP's network
-
- <emphasis>permit 0.0.0.0/0 www.my_isp.com</emphasis> # except for the ISP's main
- # web site
-
- <emphasis>permit 123.124.0.0/16 0.0.0.0/0</emphasis> # the ISP's clients can go
- # anywhere
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- 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.
-</para>
-
-</sect3>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect3 id="forwarding">
-<title>Forwarding</title>
-
-<para>
- 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.
-</para>
-
-<para>
- 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.
-</para>
-
-<para>
- Also specified here are SOCKS proxies. <application>Privoxy</application>
- 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.
-</para>
-
-<para>
- The syntax of each line is:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward target_domain[:port] http_proxy_host[:port]</emphasis>
- <emphasis>forward-socks4 target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
- <emphasis>forward-socks4a target_domain[:port] socks_proxy_host[:port] http_proxy_host[:port]</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- If http_proxy_host is <quote>.</quote>, then requests are not forwarded to a
- HTTP proxy but are made directly to the web servers.
-</para>
-
-<para>
- Lines are checked in sequence, and the last match wins.
-</para>
-
-<para>
- 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:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* . </emphasis># implicit
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- In the following common configuration, everything goes to Lucent's LPWA,
- except SSL on port 443 (which it doesn't handle):
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* lpwa.com:8000</emphasis>
- <emphasis>forward :443 .</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
-<!--
- See the FAQ for instructions on how to automate the login procedure for LPWA.
--->
- Some users have reported difficulties related to LPWA's use of
- <quote>.</quote> as the last element of the domain, and have said that this
- can be fixed with this:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward lpwa. lpwa.com:8000</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- (NOTE: the syntax for specifying target_domain has changed since the
- previous paragraph was written -- it will not work now. More information
- is welcome.)
-</para>
+<sect4><title>enable-remote-toggle</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not the <ulink url="http://config.privoxy.org/toggle">web-based toggle
+ feature</ulink> may be used
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>0 or 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The web-based toggle feature is disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ When toggled off, <application>Privoxy</application> acts like a normal,
+ content-neutral proxy, i.e. it acts as if none of the actions applied to
+ any URL.
+ </para>
+ <para>
+ For the time being, access to the toggle feature can <emphasis>not</emphasis> be
+ controlled separately by <quote>Acls</quote> or HTTP authentication,
+ so that everybody who can access <application>Privoxy</application> (see
+ <quote>Acls</quote> and <literal>listen-address</literal> above) can
+ toggle it for all users. So this option is <emphasis>not recommended</emphasis>
+ for multi-user environments with untrusted users.
+ </para>
+ <para>
+ Note that you must have compiled <application>Privoxy</application> with
+ support for this feature, otherwise this option has no effect.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- In this fictitious example, everything goes via an ISP's caching proxy,
- except requests to that ISP:
-</para>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* caching.myisp.net:8000</emphasis>
- <emphasis>forward myisp.net .</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- For the @home network, we're told the forwarding configuration is this:
-</para>
+<sect4><title>enable-edit-actions</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Whether or not the <ulink url="http://config.privoxy.org/edit-actions">web-based actions
+ file editor</ulink> may be used
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>0 or 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ The web-based actions file editor is disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ For the time being, access to the editor can <emphasis>not</emphasis> be
+ controlled separately by <quote>Acls</quote> or HTTP authentication,
+ so that everybody who can access <application>Privoxy</application> (see
+ <quote>Acls</quote> and <literal>listen-address</literal> above) can
+ modify its configuration for all users. So this option is <emphasis>not
+ recommended</emphasis> for multi-user environments with untrusted users.
+ </para>
+ <para>
+ Note that you must have compiled <application>Privoxy</application> with
+ support for this feature, otherwise this option has no effect.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
+
+<sect4><title>Acls: permit-access and deny-access</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Who can access what.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">src_addr</replaceable>[/<replaceable class="parameter">src_masklen</replaceable>]
+ [<replaceable class="parameter">dst_addr</replaceable>[/<replaceable class="parameter">dst_masklen</replaceable>]]
+ </para>
+ <para>
+ Where <replaceable class="parameter">src_addr</replaceable> and
+ <replaceable class="parameter">dst_addr</replaceable> are IP addresses in dotted decimal notation or valid
+ DNS names, and <replaceable class="parameter">src_masklen</replaceable> and
+ <replaceable class="parameter">dst_masklen</replaceable> are subnet masks in CIDR notation, i.e. integer
+ values from 2 to 30 representing the length (in bits) of the network address. The masks and the whole
+ destination part are optional.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Don't restrict access further than implied by <literal>listen-address</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Access controls are included at the request of ISPs and systems
+ administrators, and <emphasis>are not usually needed by individual users</emphasis>.
+ For a typical home user, it will normally suffice to ensure that
+ <application>Privoxy</application> only listens on the localhost or internal (home)
+ network address by means of the <literal>listen-address</literal> option.
+ </para>
+ <para>
+ Please see 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.
+ </para>
+ <para>
+ Multiple acl lines are OK.
+ If any acls are specified, then the <application>Privoxy</application>
+ talks only to IP addresses that match at least one <literal>permit-access</literal> line
+ and don't match any subsequent <literal>deny-access</literal> line. In other words, the
+ last match wins, with the default being <literal>deny-access</literal>.
+ </para>
+ <para>
+ If <application>Privoxy</application> is using a forwarder (see <literal>forward</literal> below)
+ for a particular destination URL, the <replaceable class="parameter">dst_addr</replaceable>
+ that is examined is the address of the forwarder and <emphasis>NOT</emphasis> the address
+ of the ultimate target. This is necessary because it may be impossible for the local
+ <application>Privoxy</application> to determine the IP address of the
+ ultimate target (that's often what gateways are used for).
+ </para>
+ <para>
+ You should prefer using IP addresses over DNS names, because the address lookups take
+ time. All DNS names must resolve! You can <emphasis>not</emphasis> use domain patterns
+ like <quote>*.org</quote> or partial domain names. If a DNS name resolves to multiple
+ IP addresses, only the first one is used.
+ </para>
+ <para>
+ Denying access to particular sites by acl may have undesired side effects
+ if the site in question is hosted on a machine which also hosts other sites.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ Explicitly define the defauklt behaviour if no acl and
+ <literal>listen-address</literal> are set: <quote>localhost</quote>
+ is OK. The absence of a <replaceable class="parameter">dst_addr</replaceable> implies that
+ <emphasis>all</emphasis> destination addresses are OK:
+ </para>
+ <para>
+ <screen>
+ permit-access localhost
+ </screen>
+ </para>
+ <para>
+ Allow any host on the same class C subnet as www.privoxy.org access to
+ nothing but www.example.com:
+ </para>
+ <para>
+ <screen>
+ permit-access www.privoxy.org/24 www.example.com/32
+ </screen>
+ </para>
+ <para>
+ Allow access from any host on the 26-bit subnet 192.168.45.64 to anywhere,
+ with the exception that 192.168.45.73 may not access www.dirty-stuff.example.com:
+ </para>
+ <para>
+ <screen>
+ permit-access 192.168.45.64/26
+ deny-access 192.168.45.73 www.dirty-stuff.example.com
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
+<sect4><title>buffer-limit</title>
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* proxy:8080</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Maximum size of the buffer for content filtering.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>Size in Kbytes</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>4096</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Use a 4MB (4096 KB) limit.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ For content filtering, i.e. the <literal>+filter</literal> and
+ <literal>+deanimate-gif</literal> actions, it is necessary that
+ <application>Privoxy</application> buffers the entire document body.
+ This can be potentially dangerous, since a server could just keep sending
+ data indefinitely and wait for your RAM to exhaust -- with nasty consequences.
+ Hence this option.
+ </para>
+ <para>
+ When a document buffer size reaches the <literal>buffer-limit</literal>, it is
+ flushed to the client unfiltered and no further attempt to
+ filter the rest of the document is made. Remember that there may be multiple threads
+ running, which might require up to <literal>buffer-limit</literal> Kbytes
+ <emphasis>each</emphasis>, unless you have enabled <quote>single-threaded</quote>
+ above.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
-<para>
- 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.
-</para>
+</sect3>
-<para>
- In this example direct connections are made to all <quote>internal</quote>
- domains, but everything else goes through Lucent's LPWA by way of the
- company's SOCKS gateway to the Internet.
-</para>
+<!-- ~ End section ~ -->
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward-socks4 .* lpwa.com:8000 firewall.my_company.com:1080</emphasis>
- <emphasis>forward my_company.com .</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
-<para>
- This is how you could set up a site that always uses SOCKS but no forwarders:
-</para>
+<!-- ~~~~~ New section ~~~~~ -->
-<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward-socks4a .* . firewall.my_company.com:1080</emphasis>
- </literallayout>
- </msgtext>
- </literal>
-</para>
+<sect3 id="forwarding">
+<title>Forwarding</title>
<para>
- An advanced example for network administrators:
+ This feature allows routing of HTTP requests through a chain of
+ multiple proxies.
+ It can be used to better protect privacy and confidentiality when
+ accessing specific domains by routing requests to those domains
+ through an anonymous public proxy (see e.g. <ulink
+ url="http://www.multiproxy.org/anon_list.htm">http://www.multiproxy.org/anon_list.htm</ulink>)
+ Or to use a caching proxy to speed up browsing. Or chaining to a parent
+ proxy may be necessary because the mackine that <application>Privoxy</application>
+ runs on has no direct internet access.
</para>
<para>
- 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.
+ Also specified here are SOCKS proxies. <application>Privoxy</application>
+ supports the SOCKS 4 and SOCKS 4A protocols.
</para>
-<para>
- This is a bit tricky, but here's an example:
-</para>
+<sect4><title>forward</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ To which parent HTTP proxy specific requests should be routed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ </para>
+ <para>
+ Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
+ chapter on domain matching in the actions file),
+ <replaceable class="parameter">http_parent</replaceable> is the address of the parent HTTP proxy
+ as an IP addresses in dotted decimal notation or as a valid DNS name (or <quote>.</quote> to denote
+ <quote>no forwarding</quote>, and the optional
+ <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer
+ values from 1 to 64535
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Don't use parent HTTP proxies.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
+ forwarded to another HTTP proxy but are made directly to the web servers.
+ </para>
+ <para>
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ Everything goes to an example anonymizing proxy, except SSL on port 443 (which it doesn't handle):
+ </para>
+ <para>
+ <screen>
+ forward .* anon-proxy.example.org:8080
+ forward :443 .
+ </screen>
+ </para>
+ <para>
+ Everything goes to our example ISP's caching proxy, except for requests
+ to that ISP's sites:
+ </para>
+ <para>
+ <screen>
+ forward .*. caching-proxy.example-isp.net:8000
+ forward .example-isp.net .
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
+
+<sect4><title>forward-socks4 and forward-socks4a</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Through which SOCKS proxy (and to which parent HTTP proxy) specific requests should be routed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ <replaceable class="parameter">target_domain</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">socks_proxy</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ <replaceable class="parameter">http_parent</replaceable>[/<replaceable class="parameter">port</replaceable>]
+ </para>
+ <para>
+ Where <replaceable class="parameter">target_domain</replaceable> is a domain name pattern (see the
+ chapter on domain matching in the actions file),
+ <replaceable class="parameter">http_parent</replaceable> and <replaceable class="parameter">socks_proxy</replaceable>
+ are IP addresses in dotted decimal notation or valid DNS names (<replaceable class="parameter">http_parent</replaceable>
+ may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
+ <replaceable class="parameter">port</replaceable> parameters are TCP ports, i.e. integer values from 1 to 64535
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Unset</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Don't use SOCKS proxies.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Multiple lines are OK, they are checked in sequence, and the last match wins.
+ </para>
+ <para>
+ The difference between <literal>forward-socks4</literal> and <literal>forward-socks4a</literal>
+ is that in the SOCKS 4A protocol, the DNS resolution of the target hostname happens on the SOCKS
+ server, while in SOCKS 4 it happens locally.
+ </para>
+ <para>
+ If <replaceable class="parameter">http_parent</replaceable> is <quote>.</quote>, then requests are not
+ forwarded to another HTTP proxy but are made (HTTP-wise) directly to the web servers, albeit through
+ a SOCKS proxy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ From the company example.com, direct connections are made to all <quote>internal</quote>
+ domains, but everything outbound goes through their ISP's proxy by way example.com's
+ corporate SOCKS 4A gateway to the Internet.
+ </para>
+ <para>
+ <screen>
+ forward-socks4a .*. socks-gw.example.com:1080 www-cache.example-isp.net:8080
+ forward .example.com .
+ </screen>
+ </para>
+ <para>
+ A rule that uses a SOCKS 4 gateway for all destinations but no HTTP parent looks like this:
+ </para>
+ <para>
+ <screen>
+ forward-socks4 .*. socks-gw.example.com:1080 .
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>
+<sect4><title>Advanced Forwarding Examples</title>
<para>
- 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 <application>Privoxy</application> proxy with
- forwarding like this:
+ If you have links to multiple ISPs that provide various special content
+ only to their subscribers, you can configure multiple <application>Privoxies</application>
+ which have connections to the respective ISPs to act as forwarders to each other, so that
+ <emphasis>your</emphasis> users can see the internal content of all ISPs.
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* .</emphasis>
- <emphasis>forward isp-b.com host-b:8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ Assume that host-a has a PPP connection to isp-a.net. And host-b has a PPP connection to
+ isp-b.net. Both run <application>Privoxy</application>. Their forwarding
+ configuration can look like this:
</para>
<para>
- host-b can run a <application>Privoxy</application> proxy with forwarding
- like this:
+ host-a:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward .* .</emphasis>
- <emphasis>forward isp-a.com host-a:8118</emphasis>
- </literallayout>
- </msgtext>
- </literal>
+ <screen>
+ forward .*. .
+ forward .isp-b.net host-b:8118
+ </screen>
</para>
<para>
- Now, <emphasis>anyone</emphasis> on the Internet (including users on host-a
- and host-b) can set their browser's proxy to <emphasis>either</emphasis>
- host-a or host-b and be able to browse the content on isp-a or isp-b.
+ host-b:
</para>
<para>
- 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.
+ <screen>
+ forward .*. .
+ forward .isp-a.net host-a:8118
+ </screen>
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- <emphasis>forward *. ssbcache.ukc.ac.uk:3128</emphasis> # Use the proxy, except for:
- <emphasis>forward .ukc.ac.uk . </emphasis> # Anything on the same domain as us
- <emphasis>forward * . </emphasis> # Host with no domain specified
- <emphasis>forward 129.12.*.* . </emphasis> # A dotted IP on our /16 network.
- <emphasis>forward 127.*.*.* . </emphasis> # Loopback address
- <emphasis>forward localhost.localdomain . </emphasis> # Loopback address
- <emphasis>forward www.ukc.mirror.ac.uk . </emphasis> # Specific host
- </literallayout>
- </msgtext>
- </literal>
+ Now, you users can set their browser's proxy to use either
+ host-a or host-b and be able to browse the internal content
+ on both isp-a or isp-b.
</para>
<para>
</para>
<para>
- Your squid configuration could then look like this:
+ Assuming that <application>Privoxy</application> and <application>squid</application>
+ run on the same box, your squid configuration could then look like this:
</para>
<para>
- <literal>
- <msgtext>
- <literallayout>
- # Define Privoxy as parent cache
- <!-- per feedback from user...
- cache_peer 127.0.0.1 8118 parent 0 no-query
- -->
- cache_peer 127.0.0.1 parent 8118 0 no-query
-
- # Define ACL for protocol FTP
- acl FTP proto FTP
+ <screen>
+ # Define Privoxy as parent proxy (without ICP)
+ cache_peer 127.0.0.1 parent 8118 7 no-query
- # Do not forward ACL FTP to privoxy
- always_direct allow FTP
+ # Define ACL for protocol FTP
+ acl ftp proto FTP
- # Do not forward ACL CONNECT (https) to privoxy
- always_direct allow CONNECT
+ # Do not forward FTP requests to Privoxy
+ always_direct allow ftp
- # Forward the rest to privoxy
+ # Forward all the rest to Privoxy
never_direct allow all
- </literallayout>
- </msgtext>
- </literal>
+ </screen>
+</para>
+
+<para>
+ You would then need to change your browser's proxy settings to <application>squid</application>'s address and port.
+ Squid normally uses port 3128. If unsure consult <literal>http_port</literal> in <filename>squid.conf</filename>.
</para>
+</sect4>
+
</sect3>
<!-- ~ End section ~ -->
<para>
The <quote>default.action</quote> file (formerly
- <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used to define what actions
- <application>Privoxy</application> 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 <filename>default.action</filename> should
- be immediately visible to <application>Privoxy</application> without
- the need to restart.
+ <filename>actionsfile</filename> or <filename>ijb.action</filename>) is used
+ to define what actions <application>Privoxy</application> 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.
+</para>
+<para>
+ 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 <filename>default.action</filename> should be immediately visible
+ to <application>Privoxy</application> without the need to restart.
</para>
<para>
- The easiest way to edit <quote>actions</quote> file is with a browser by
- loading <ulink url="http://p.p/">http://p.p/</ulink>, and then select
+ 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 <application>Privoxy's</application> 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.
+
+</para>
+
+<para>
+ The easiest way to edit the <quote>actions</quote> file is with a browser by
+ loading <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
<quote>Edit Actions List</quote>. A text editor can also be used.
</para>
</para>
<para>
- <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>, regardless of
- the domain.
+ <emphasis>/index.html</emphasis> - matches the document <quote>/index.html</quote>,
+ regardless of the domain. So would match any page named <quote>index.html</quote>
+ on any site.
</para>
<para>
</para>
<para>
- <emphasis>.example.com</emphasis> - matches any domain that <emphasis>ENDS</emphasis> in
- <quote>.example.com</quote>.
+ <emphasis>.example.com</emphasis> - matches any domain or sub-domain that
+ <emphasis>ENDS</emphasis> in <quote>.example.com</quote>.
</para>
<para>
<para>
If <application>Privoxy</application> was compiled with
- <quote>pcre</quote> support (default), Perl compatible regular expressions
- can be used. See the <filename>pcre/docs/</filename> directory or <quote>man
+ <quote>pcre</quote> support (the default), Perl compatible regular expressions
+ can be used. These are more flexible and powerful than other types
+ of <quote>regular expressions</quote>. See the <filename>pcre/docs/</filename> directory or <quote>man
perlre</quote> (also available on <ulink
url="http://www.perldoc.com/perl5.6/pod/perlre.html">http://www.perldoc.com/perl5.6/pod/perlre.html</ulink>)
for details. A brief discussion of regular expressions is in the
</para>
<para>
- Later defined actions always over-ride earlier ones. For multi-valued
- actions, the actions are applied in the order they are specified.
+ 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.
</para>
<para>
<para>
Block this URL totally. In a default installation, a <quote>blocked</quote>
URL will result in bright red banner that says <quote>BLOCKED</quote>,
- with a reason why it is being blocked.
+ with a reason why it is being blocked, and an option to see it anyway.
+ The page displayed for this is the <quote>blocked</quote> template
+ file.
</para>
<para>
<literal>
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.
+ <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
</para>
<para>
Sometimes, there are even multiple consecutive redirects encoded in the
</para>
<para>
The <quote>+fast-redirects</quote> option enables interception of these
- requests by <application>Privoxy</application>, 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.
+ types of requests by <application>Privoxy</application>, 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).
</para>
<para>
<literal>
Apply the filters in the <literal>section_header</literal>
section of the <filename>default.filter</filename> file to the site(s).
<filename>default.filter</filename> sections are grouped according to like
- functionality.
+ functionality. <application>Filters</application> can be used to
+ re-write any of the raw page content. This is a potentially a
+ very powerful feature!
</para>
<para>
</simplelist>
</blockquote>
+ <para>
+ Note: 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.
+</para>
+
</listitem>
<listitem>
Don't send the <quote>Referer:</quote> (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.
+ constant, user defined string of your choice.
</para>
<para>
<literal>
See <quote>+image-blocker{}</quote> below for the control over what is actually sent.
If you want <emphasis>invisible</emphasis> ads, they should be defined as
<emphasis>images</emphasis> and <emphasis>blocked</emphasis>. And also,
- <quote>image-blocker</quote> should be set to <quote>blank</quote>.
+ <quote>image-blocker</quote> should be set to <quote>blank</quote>. 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 <quote>image</quote> in this
+ situation just will not work.
</para>
<para>
<literal>
<application>Privoxy</application>, since <quote>+filter</quote>,
<quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work on
compressed data. This will slow down connections to those websites,
- though. Default is <quote>nocompression</quote> is turned on.
+ though. Default is <quote>no-compression</quote> is turned on.
</para>
<para>
</para>
<para>
- Now some URLs that we want <quote>blocked</quote>, 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 <quote>blocked</quote> (normally generates
+ the <quote>blocked</quote> banner). Many of these use regular expressions
+ that will expand to match multiple URLs:
</para>
<para>
content he may depend on. There is no way to have hard and fast rules
for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
for a brief example on troubleshooting actions.
-
</para>
</sect3>
<quote>z</quote>, <quote>0</quote>-<quote>9</quote>, <quote>+</quote>, and
<quote>-</quote>. Alias names are not case sensitive, and
<emphasis>must be defined before anything</emphasis> else in the
- <filename>default.action</filename>file ! And there can only be one set of
+ <filename>default.action</filename>file! And there can only be one set of
<quote>aliases</quote> defined.
</para>
<literal>
<msgtext>
<literallayout>
- # 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
</literal>
</para>
+<para>
+ The <quote>shop</quote> and <quote>fragile</quote> aliases are often used for
+ <quote>problem</quote> sites that require most actions to be disabled
+ in order to function properly.
+
+</para>
+
</sect3>
</sect2>
<filename>default.filter</filename>, located in the config directory.
</para>
+<para>
+ This is potentially a very powerful feature, and requires knowledge of both
+ <quote>regular expression</quote> and HTML in order create custom
+ filters. But, there are a number of useful filters included with
+ <application>Privoxy</application> for many common situations.
+</para>
+
<para>
The included example file is divided into sections. Each section begins
with the <literal>FILTER</literal> keyword, followed by the identifier
for that section, e.g. <quote>FILTER: webbugs</quote>. Each section performs
a similar type of filtering, such as <quote>html-annoyances</quote>.
-
</para>
<para>
</para>
<para>
- Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
- <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- FILTER: fun
-
- s/microsoft(?!.com)/MicroSuck/ig
-
- # Buzzword Bingo:
- #
- s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-<para>
- Kill those pesky little web-bugs:
-</para>
-
-<para>
- <literal>
- <msgtext>
- <literallayout>
- # 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
- </literallayout>
- </msgtext>
- </literal>
-</para>
-
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2>
-<title>Templates</title>
-<para>
- When <application>Privoxy</application> 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
- <filename>/etc/privoxy/templates</filename> by default. These may be
- customized, if desired.
-
-</para>
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
-<para>
- Install package, then run and enjoy! <application>Privoxy</application>
- is typically started by specifying the main configuration file to be
- used on the command line. Example Unix startup command:
-</para>
-
-<para>
- <screen>
-
- # /usr/sbin/privoxy /etc/privoxy/config
-
- </screen>
-</para>
-
-<para>
- An init script is provided for SuSE and Redhat.
-</para>
-
-<para>
-For for SuSE: /etc/rc.d/privoxy start
-</para>
-
-<para>
-For RedHat: /etc/rc.d/init.d/privoxy start
-</para>
-
-
-<para>
- If no configuration file is specified on the command line,
- <application>Privoxy</application> will look for a file named
- <filename>config</filename> in the current directory. Except on Win32 where
- it will try <filename>config.txt</filename>. If no file is specified on the
- command line and no default configuration file can be found,
- <application>Privoxy</application> will fail to start.
-</para>
-
-<para>
- Be sure your browser is set to use the proxy which is by default at
- localhost, port 8118. With <application>Netscape</application> (and
- <application>Mozilla</application>), this can be set under <literal>Edit
- -> Preferences -> Advanced -> Proxies -> HTTP Proxy</literal>.
- For <application>Internet Explorer</application>: <literal>Tools >
- Internet Properties -> Connections -> LAN Setting</literal>. Then,
- check <quote>Use Proxy</quote> and fill in the appropriate info (Address:
- localhost, Port: 8118). Include if HTTPS proxy support too.
-</para>
-
-<para>
- 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
- <filename>default.action</filename> 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 <filename>default.action</filename> and disable this feature. If you
- use more than one browser, it would make more sense to let
- <application>Privoxy</application> handle this. In which case, the
- browser(s) should be set to accept all cookies.
+ Just for kicks, replace any occurrence of <quote>Microsoft</quote> with
+ <quote>MicroSuck</quote>, and have a little fun with topical buzzwords:
</para>
<para>
- If a particular site shows problems loading properly, try adding it
- to the <literal>{fragile}</literal> section of
- <filename>default.action</filename>. This will turn off most actions for
- this site.
-</para>
+ <literal>
+ <msgtext>
+ <literallayout>
+ FILTER: fun
-<para>
- <application>Privoxy</application> is HTTP/1.1 compliant, but not all 1.1
- features are as yet implemented. If browsers that support HTTP/1.1 (like
- <application>Mozilla</application> or recent versions of I.E.) experience
- problems, you might try to force HTTP/1.0 compatibility. For Mozilla, look
- under <literal>Edit -> Preferences -> Debug -> Networking</literal>.
- Or set the <quote>+downgrade</quote> config option in
- <filename>default.action</filename>.
-</para>
+ s/microsoft(?!.com)/MicroSuck/ig
-<para>
- After running <application>Privoxy</application> 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. <quote>Actions</quote> (as specified in <filename>default.action</filename>)
- can be adjusted by pointing your browser to
- <ulink url="http://p.p/">http://p.p/</ulink>,
- and then follow the link to <quote>edit the actions list</quote>.
- (This is an internal page and does not require Internet access.)
+ # Buzzword Bingo:
+ #
+ s/industry-leading|cutting-edge|award-winning/<font color=red><b>BINGO!</b></font>/ig
+ </literallayout>
+ </msgtext>
+ </literal>
</para>
<para>
- In fact, various aspects of <application>Privoxy</application>
- configuration can be viewed from this page, including
- current configuration parameters, source code version numbers,
- the browser's request headers, and <quote>actions</quote> that apply
- to a given URL. In addition to the <filename>default.action</filename> file
- editor mentioned above, <application>Privoxy</application> can also
- be turned <quote>on</quote> and <quote>off</quote> from this page.
+ Kill those pesky little web-bugs:
</para>
<para>
- If you encounter problems, please verify it is a
- <application>Privoxy</application> bug, by disabling
- <application>Privoxy</application>, 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).
+ <literal>
+ <msgtext>
+ <literallayout>
+ # 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
+ </literallayout>
+ </msgtext>
+ </literal>
</para>
+</sect2>
+
+<!-- ~ End section ~ -->
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2>
-<title>Command Line Options</title>
+<title>Templates</title>
<para>
- <application>Privoxy</application> may be invoked with the following
- command-line options:
+ When <application>Privoxy</application> 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
+ <filename>/etc/privoxy/templates</filename> by default. These may be
+ customized, if desired. <filename>cgi-style.css</filename> is
+ used to control the HTML attributes (fonts, etc).
</para>
-
<para>
- <itemizedlist>
-
- <listitem>
- <para>
- <emphasis>--version</emphasis>
- </para>
- <para>
- Print version info and exit, Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--help</emphasis>
- </para>
- <para>
- Print a short usage info and exit, Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--no-daemon</emphasis>
- </para>
- <para>
- Don't become a daemon, i.e. don't fork and become process group
- leader, don't detach from controlling tty. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--pidfile FILE</emphasis>
-
- </para>
- <para>
- On startup, write the process ID to <emphasis>FILE</emphasis>. Delete the
- <emphasis>FILE</emphasis> on exit. Failiure to create or delete the
- <emphasis>FILE</emphasis> is non-fatal. If no <emphasis>FILE</emphasis>
- option is given, no PID file will be used. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>--user USER[.GROUP]</emphasis>
-
- </para>
- <para>
- After (optionally) writing the PID file, assume the user ID of
- <emphasis>USER</emphasis>, and if included the GID of GROUP. Exit if the
- privileges are not sufficient to do so. Unix only.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>configfile</emphasis>
- </para>
- <para>
- If no <emphasis>configfile</emphasis> is included on the command line,
- <application>Privoxy</application> will look for a file named
- <quote>config</quote> in the current directory (except on Win32
- where it will look for <quote>config.txt</quote> instead). Specify
- full path to avoid confusion.
- </para>
- </listitem>
+ The default <quote>Blocked</quote> banner page with the bright red top
+ banner, is called just <quote><filename>blocked</filename></quote>. This
+ may be customized or replaced with something else if desired.
- </itemizedlist>
</para>
-
</sect2>
</sect1>
<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
Requests</title>
-<para>
-We value your feedback. However, to provide you with the best support,
-please note:
-
- <itemizedlist>
-
- <listitem><para>Use the <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=211118">Sourceforge support forum</ulink> to get
- help.</para></listitem>
-
- <listitem><para>Submit bugs only thru our <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=111118">Sourceforge bug
- forum</ulink>.
-Make sure that the bug has not already been submitted. Please try to
-verify that it is a <application>Privoxy</application> 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.</para>
-</listitem>
-
-
- <listitem><para>Submit feature requests only thru our <ulink
- url="http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse">Sourceforge feature request forum</ulink>.</para></listitem>
+<!-- Include contacting.sgml boilerplate: -->
+ &contacting;
+<!-- end boilerplate -->
- </itemizedlist>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="submitactions">
+<title>Submitting Ads and <quote>Action</quote> Problems</title>
+<para>
+ Ads and banners that are not stopped by <application>Privoxy</application>
+ can be submitted to the developers by accessing a special page and filling
+ out the brief, required form. Conversely, you can also report pages, images,
+ etc. that <application>Privoxy</application> is blocking, but should not.
+ The form itself does require Internet access.
</para>
-
<para>
-For any other issues, feel free to use the <ulink url="http://sourceforge.net/mail/?group_id=11118">mailing lists</ulink>.
+ To do this, point your browser to <application>Privoxy</application>
+ at <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ (shortcut: <ulink url="http://p.p/">http://p.p/</ulink>), and then select
+ <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>,
+ near the bottom of the page. Paste in the URL that is the cause of the
+ unwanted behavior, and follow the prompts. The developers will
+ try to incorporate a fix for the problem you reported into future versions.
</para>
<para>
- Anyone interested in actively participating in development and related
- discussions can join the appropriate mailing list
- <ulink url="http://sourceforge.net/mail/?group_id=11118">here</ulink>.
- Archives are available here too.
+ New <filename>default.actions</filename> files will occasionally be made
+ available based on your feedback. These
+ will be announced on the
+ <ulink
+ url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink>
+ list.
</para>
+</sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="copyright"><title>Copyright and History</title>
-<sect2>
-<title>License</title>
-<para>
- <application>Privoxy</application> 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.
-</para>
-
-<para>
- 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 <ulink
- url="http://www.gnu.org/copyleft/gpl.html">the Free Software Foundation,
- Inc</ulink>, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-</para>
-
+<sect2><title>Copyright</title>
+<!-- Include copyright.sgml: -->
+ ©right;
+<!-- end copyright -->
</sect2>
<!-- ~ End section ~ -->
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>History</title>
-<para>
- <application>Privoxy</application> is derived from
- <application>the Internet Junkbuster</application>, with many
- improvments and enhancements over the original.
-</para>
-
-<para>
- <application>Junkbuster</application> was originally written by Anonymous
- Coders and <ulink
- url="http://www.junkbusters.com">Junkbuster's
- Corporation</ulink>, and was released as free open-source software under the
- GNU GPL. <ulink url="http://www.waldherr.org/junkbuster/">Stefan
- Waldherr</ulink> made many improvements, and started the <ulink
- url="http://sourceforge.net/projects/ijbswa/">SourceForge project
- Privoxy</ulink> to rekindle development. There are now several active
- developers contributing. The last stable release of
- <application>Junkbuster</application> was v2.0.2, which has now
- grown whiskers ;-).
-</para>
-
+<sect2 id="history"><title>History</title>
+<!-- Include history.sgml: -->
+ &history;
+<!-- end history -->
</sect2>
-
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="seealso"><title>See also</title>
-<para>
-
- <simplelist>
- <member>
- <ulink url="http://sourceforge.net/projects/ijbswa">http://sourceforge.net/projects/ijbswa</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.privoxy.org/">http://www.privoxy.org/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://p.p/">http://p.p/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.junkbusters.com/ht/en/cookies.html">http://www.junkbusters.com/ht/en/cookies.html</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.waldherr.org/junkbuster/">http://www.waldherr.org/junkbuster/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://privacy.net/analyze/">http://privacy.net/analyze/</ulink>
- </member>
- </simplelist>
- <simplelist>
- <member>
- <ulink url="http://www.squid-cache.org/">http://www.squid-cache.org/</ulink>
- </member>
- </simplelist>
-
-</para>
+<sect1 id="seealso"><title>See Also</title>
+<!-- Include seealso.sgml: -->
+ &seealso;
+<!-- end seealso -->
</sect1>
and then some examples:
</para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
<quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
times. Either/or.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
times.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
times.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
the following character should be taken literally. This is used where one of the
special characters (e.g. <quote>.</quote>) needs to be taken literally and
not as a special meta-character.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
any of the enclosed characters are encountered.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>()</emphasis> - parentheses are used to group a sub-expression,
or multiple sub-expressions.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>|</emphasis> - The <quote>bar</quote> character works like an
<quote>or</quote> conditional statement. A match is successful if the
sub-expression on either side of <quote>|</quote> matches.
</member>
-</simplelist>
+</simplelist></para>
-<simplelist>
+<para><simplelist>
<member>
<emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text.
<quote>string1</quote> is replaced by <quote>string2</quote> in this
example.
</member>
-</simplelist>
+</simplelist></para>
<para>
These are just some of the ones you are likely to use when matching URLs with
<para>
Since <application>Privoxy</application> proxies each requested
web page, it is easy for <application>Privoxy</application> to
- trap certain URLs. In this way, we can talk directly to
+ trap certain special URLs. In this way, we can talk directly to
<application>Privoxy</application>, and see how it is
configured, see how our rules are being applied, change these
rules and other configuration options, and even turn
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/">http://www.privoxy.org/config/</ulink>
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
</para>
</blockquote>
<para>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-status">http://www.privoxy.org/config/show-status</ulink>
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-version">http://www.privoxy.org/config/show-version</ulink>
+ <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-request">http://www.privoxy.org/config/show-request</ulink>
+ <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/show-url-info">http://www.privoxy.org/config/show-url-info</ulink>
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
</para>
</blockquote>
</listitem>
<listitem>
<para>
- Toggle Privoxy on or off:
+ Toggle Privoxy on or off. In this case, <quote>Privoxy</quote> continues
+ to run, but only as a pass-through proxy, with no actions taking place:
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/toggle">http://www.privoxy.org/config/toggle</ulink>
+ <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
</para>
</blockquote>
<para>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/toggle?set=disable">http://www.privoxy.org/config/toggle?set=disable</ulink>
+ <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
</para>
</blockquote>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/toggle?set=enable">http://www.privoxy.org/config/toggle?set=enable</ulink>
+ <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
</para>
</blockquote>
</listitem>
</para>
<blockquote>
<para>
- <ulink url="http://www.privoxy.org/config/edit-actions">http://www.privoxy.org/config/edit-actions</ulink>
+ <ulink url="http://config.privoxy.org/edit-actions">http://config.privoxy.org/edit-actions</ulink>
</para>
</blockquote>
</listitem>
</para>
+<sect3 id="bookmarklets">
+<title>Bookmarklets</title>
+<para>
+ Below are some <quote>bookmarklets</quote> to allow you to easily access a
+ <quote>mini</quote> version of some of <application>Privoxy's</application>
+ 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).
+</para>
+<para>
+ To save them, right-click the link and choose <quote>Add to Favorites</quote>
+ (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
+ the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
+ Bookmarklet directly from your favourites/bookmarks. For even faster access,
+ you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
+ Toolbar</quote> (Netscape), and run them with a single click.
+</para>
+
+<para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Enable Privoxy</ulink>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Disable Privoxy</ulink>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Toggle Privoxy</ulink> (Toggles between enabled and disabled)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">View Privoxy Status</ulink>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Actions file feedback system</ulink>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+</para>
+
+
+
+<para>
+ Credit: The site which gave me the general idea for these bookmarklets is
+ <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
+ have more information about bookmarklets.
+</para>
+
+
+</sect3>
+
</sect2>
<para>
The way <application>Privoxy</application> applies <quote>actions</quote>
- 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 <emphasis>see</emphasis>
- just what <application>Privoxy</application> is doing. Especially,
- if something <application>Privoxy</application> 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
+ and <quote>filters</quote> 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
+ <emphasis>see</emphasis> just what <application>Privoxy</application> is
+ doing. Especially, if something <application>Privoxy</application> 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
<quote>regular expressions</quote> whose consequences are not always
so obvious. <application>Privoxy</application> provides the
- <ulink url="http://www.privoxy.org/config/show-url-info">http://www.privoxy.org/config/show-url-info</ulink>
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
page that can show us very specifically how <application>actions</application>
are being applied to any given URL. This is a big help for troubleshooting.
</para>
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 <quote>View Page Source</quote> option
- for this.
+ for this. Or right click on the ad, and grab the URL.
</para>
<para>
</para>
<para>
- Now the page displays ;-)
+ Now the page displays ;-) Be sure to flush your browser's caches when
+ making such changes. Or, try using <literal>Shift+Reload</literal>.
+</para>
+
+<para>
+ But now what about a situation where we get no explicit matches like
+ we did with:
+</para>
+
+<para>
+ <screen>
+
+ { -block }
+ /adsl
+
+ </screen>
+</para>
+
+<para>
+ 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 <quote>{+filter}</quote> actions. Try
+ adding the URL for the site to one of aliases that turn off <quote>+filter</quote>:
+</para>
+
+<para>
+ <screen>
+
+ {shop}
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+
+ </screen>
+</para>
+
+<para>
+ <quote>{shop}</quote> is an <quote>alias</quote> that expands to
+ <quote>{ -filter -no-cookies -no-cookies-keep }</quote>. Or you could do
+ your own exception to negate filtering:
+
+</para>
+
+<para>
+ <screen>
+ {-filter}
+ .forbes.com
+
+ </screen>
+</para>
+
+<para>
+ <quote>{fragile}</quote> 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.
</para>
</sect2>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 1.76 2002/04/16 04:25:51 hal9
+ -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
+ -Note about proxy may need requests to re-read config files.
+
+ Revision 1.75 2002/04/12 02:08:48 david__schmidt
+ Remove OS/2 building info... it is already in the developer-manual
+
+ Revision 1.74 2002/04/11 00:54:38 hal9
+ Add small section on submitting actions.
+
+ Revision 1.73 2002/04/10 18:45:15 swa
+ generated
+
+ Revision 1.72 2002/04/10 04:06:19 hal9
+ Added actions feedback to Bookmarklets section
+
+ Revision 1.71 2002/04/08 22:59:26 hal9
+ Version update. Spell chkconfig correctly :)
+
+ Revision 1.70 2002/04/08 20:53:56 swa
+ ?
+
+ Revision 1.69 2002/04/06 05:07:29 hal9
+ -Add privoxy-man-page.sgml, for man page.
+ -Add authors.sgml for AUTHORS (and p-authors.sgml)
+ -Reworked various aspects of various docs.
+ -Added additional comments to sub-docs.
+
+ Revision 1.68 2002/04/04 18:46:47 swa
+ consistent look. reuse of copyright, history et. al.
+
+ Revision 1.67 2002/04/04 17:27:57 swa
+ more single file to be included at multiple points. make maintaining easier
+
+ Revision 1.66 2002/04/04 06:48:37 hal9
+ Structural changes to allow for conditional inclusion/exclusion of content
+ based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
+ definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
+ eventually be set by Makefile.
+ More boilerplate text for use across multiple docs.
+
+ Revision 1.65 2002/04/03 19:52:07 swa
+ enhance squid section due to user suggestion
+
+ Revision 1.64 2002/04/03 03:53:43 hal9
+ A few minor bug fixes, and touch ups. Ready for review.
+
+ Revision 1.63 2002/04/01 16:24:49 hal9
+ Define entities to include boilerplate text. See doc/source/*.
+
+ Revision 1.62 2002/03/30 04:15:53 hal9
+ - Fix privoxy.org/config links.
+ - Paste in Bookmarklets from Toggle page.
+ - Move Quickstart nearer top, and minor rework.
+
+ Revision 1.61 2002/03/29 01:31:08 hal9
+ Minor update.
+
+ Revision 1.60 2002/03/27 01:57:34 hal9
+ Added more to Anatomy section.
+
+ Revision 1.59 2002/03/27 00:54:33 hal9
+ Touch up intro for new name.
+
Revision 1.58 2002/03/26 22:29:55 swa
we have a new homepage!
projects / privoxy.git / blobdiff