<!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.13">
+<!entity p-status "BETA">
+<!entity % p-not-stable "INCLUDE"> <!-- set to IGNORE for stable release -->
+<!entity % p-stable "IGNORE"> <!-- set INCLUDE for stable release -->
+<!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.63 2002/04/01 16:24:49 hal9 Exp $
+ $Id: user-manual.sgml,v 1.68 2002/04/04 18:46:47 swa 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. You have been warned!
+ Failure to abide by this rule will result in the revocation of your license
+ to live a peaceful existence!
+ ========================================================================
-Hal Burgiss <hal@foobox.net>
-->
<article id="index">
<artheader>
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.63 2002/04/01 16:24:49 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.68 2002/04/04 18:46:47 swa Exp $</pubdate>
<authorgroup>
<author>
<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.
- </para>
+ <application>Privoxy</application>.
+ </para>
+
+<!--
+ Include privoxy.sgml boilerplate:
+-->
+ &p-intro;
+
<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>
+ 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 Contact section 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>
<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="introduction"><title>Introduction</title>
-<!--
- Include privoxy.sgml boilerplate:
--->
-&p-intro;
+<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>
<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:
+ <application>Privoxy</application> provides new features<![%p-not-stable;[,
+ some of them currently under development]]>:
</para>
-<!--
- Include newfeatures.sgml here:
--->
-
-&newfeatures;
+<!-- Include newfeatures.sgml boilerplate here: -->
+ &newfeatures;
+<!-- end boilerplate -->
</sect2>
<!-- ~~~~~ 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
+ <application>Privoxy</application> is available as raw source code (tarball
+
or via CVS), or pre-compiled binaries for various platforms. See the <ulink
+ url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink> for
+ the most up to date release information.
+
<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.
+ <![%p-not-stable;[This is the recommended approach at this time.]]> But
+ please be aware that CVS is constantly changing, and it may break in
+ mysterious ways.
</para>
+<!-- Include supported.sgml boilerplate -->
+ &supported;
+<!-- end boilerplate -->
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-source"><title>Source</title>
-<para>
- For gzipped tar archives, unpack the source:
-</para>
-<para>
- <screen>
- tar xzvf privoxy-2.9.13-beta-src* [.tgz or .tar.gz]
- cd privoxy-2.9.13-beta
- </screen>
-</para>
-<para>
- For retrieving the current CVS sources, you'll need the CVS
- package installed first. To download CVS source:
-</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>
-</para>
-
-<para>
- This will create a directory named <filename>current/</filename>, which will
- contain the source tree.
-</para>
-
-<para>
- Then, in either case, to build from tarball/CVS source:
-</para>
-
-<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>
-</para>
+<!-- include buildsource.sgml boilerplate: -->
+ &buildsource;
+<!-- end boilerplate -->
<para>
For Redhat and SuSE Linux RPM packages, see below.
</para>
-</sect2>
-
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-rh"><title>Red Hat</title>
+<sect3 id="installation-rh"><title>Red Hat</title>
<para>
- To build Redhat RPM packages, install source as above. Then:
+ To build Redhat RPM packages from source, install source as above. Then:
</para>
<para>
</para>
<para>
- /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ /usr/src/redhat/RPMS/i686/privoxy-&p-version;-1.i686.rpm
</para>
<para>
- /usr/src/redhat/SRPMS/privoxy-2.9.11-1.src.rpm
+ /usr/src/redhat/SRPMS/privoxy-&p-version;-1.src.rpm
</para>
<para>
<para>
<screen>
- rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ rpm -Uvv /usr/src/redhat/RPMS/i686/privoxy-&p-version;-1.i686.rpm
</screen>
</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>.
+ <filename>/var/log/privoxy/</filename>. Run
+ <command>ckconfig privoxy on</command> to have
+ <application>Privoxy</application> start automatically during init.
+
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-suse"><title>SuSE</title>
+<sect3 id="installation-suse"><title>SuSE</title>
<para>
To build SuSE RPM packages, install source as above. Then:
</para>
</para>
<para>
- /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ /usr/src/packages/RPMS/i686/privoxy-&p-version;-1.i686.rpm
</para>
<para>
- /usr/src/packages/SRPMS/privoxy-2.9.11-1.src.rpm
+ /usr/src/packages/SRPMS/privoxy-&p-version;-1.src.rpm
</para>
<para>
<para>
<screen>
- rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-2.9.11-1.i686.rpm
+ rpm -Uvv /usr/src/packages/RPMS/i686/privoxy-&p-version;-1.i686.rpm
</screen>
</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>.
+ <filename>/var/log/privoxy/</filename>.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-os2"><title>OS/2</title>
+<sect3 id="installation-os2"><title>OS/2</title>
<!--
Thanx David Schmidt!
<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>privoxyos2_setup_1.2.3.exe</filename>. In order to install it, simply
+ <filename>privoxyos2_setup_&p-version;.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
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
+ 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.
+ <function>select()</function> socket call.
</para>
<para>
You will see this sequence laid out in <filename>os2build.cmd</filename>.
</para>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-win"><title>Windows</title>
+<sect3 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>
-</sect2>
+</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-other"><title>Other</title>
+<sect3 id="installation-other"><title>Other</title>
<para>
Some quick notes on other Operating Systems.
</para>
The rest should be the same as above for Linux/Unix.
</para>
+</sect3>
</sect2>
</sect1>
</para>
<para>
-For for SuSE: /etc/rc.d/privoxy start
+ For for SuSE: <command>/etc/rc.d/privoxy start</command>
</para>
<para>
-For RedHat: /etc/rc.d/init.d/privoxy start
+ For RedHat: <command>/etc/rc.d/init.d/privoxy start</command>
</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>
automatically.
</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>
</para>
+<![%p-not-stable;[
<para>
It is <emphasis>highly recommended</emphasis> that you enable ERROR
reporting (debug 8192), at least until v3.0 is released.
</para>
+]]>
<para>
The reporting of FATAL errors (i.e. ones which crash
</para>
<para>
- Your squid configuration could then look like this:
+Your squid configuration could then look like this (assuming that the IP
+address of the box is <literal>192.168.0.1</literal> ):
</para>
<para>
<!-- 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
+ cache_peer 192.168.0.1 parent 8118 0 no-query
+
+ # don't listen to the whole world
+ http_port 192.168.0.1:3128
+
+ # define the local lan
+ acl mylocallan src 192.168.0.1-192.168.0.5/255.255.255.255
+
+ # grant access for http to local lan
+ http_access allow mylocallan
# Define ACL for protocol FTP
acl FTP proto FTP
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
<emphasis>images</emphasis> and <emphasis>blocked</emphasis>. And also,
<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. Forcing an <quote>image</quote> in this
+ 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>
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>
<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
<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>.
- </para>
- <para>
- 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. Please be sure to include the
- <application>Privoxy</application>/<application>Junkbuster</application>
- version, platform, browser, any pertinent log data, any other relevant
- details (please be specific) and, if possible, some way to reproduce the
- bug.
- </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>
-
-
- </itemizedlist>
-</para>
+<!-- Include contacting.sgml boilerplate: -->
-<para>
-For any other issues, feel free to use the <ulink url="http://sourceforge.net/mail/?group_id=11118">mailing lists</ulink>.
-</para>
+ &contacting;
-<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.
-</para>
+<!-- end boilerplate -->
</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
-<!--
- <informalfigure float="0">
- <mediaobject>
- <imageobject>
- <imagedata fileref="gnu.jpg" format="jpg">
- </imageobject>
- <textobject>
- <phrase>GNU's Pet GNU</phrase>
- </textobject>
- </mediaobject>
- </informalfigure>
--->
- 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 the Free Software Foundation,
- Inc, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-</para>
-
-<para>
- You should have received a copy of the <ulink
- url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</ulink>
- along with this program; if not, write to the Free Software Foundation, Inc.,
- 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 id="history">
-<title>History</title>
-<para>
- <application>Privoxy</application> is evolved, and 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>
-<!--
- Include seealso.sgml:
--->
-&seealso;
-
+<!-- Include seealso.sgml: -->
+ &seealso;
+<!-- end seealso -->
</sect1>
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>
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>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ 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/*.
projects / privoxy.git / blobdiff