<!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-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">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.67 2002/04/04 17:27:57 swa Exp $
+ $Id: user-manual.sgml,v 1.75 2002/04/12 02:08:48 david__schmidt Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
by and Copyright (C) 1997 Anonymous Coders and
Junkbusters Corporation. http://www.junkbusters.com
+
+ ========================================================================
+ NOTE: Please read developer-manual/documentation.html before touching
+ anything in this, or other Privoxy documentation.
+ ========================================================================
+
-->
<article id="index">
<artheader>
<title>Privoxy User Manual</title>
-<pubdate>$Id: user-manual.sgml,v 1.67 2002/04/04 17:27:57 swa Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.75 2002/04/12 02:08:48 david__schmidt Exp $</pubdate>
<authorgroup>
<author>
<para>
The user manual gives users information on how to install, configure and use
- <application>Privoxy</application>.
+ <ulink
+ url="http://www.privoxy.org/"><application>Privoxy</application></ulink>.
</para>
-<!--
- Include privoxy.sgml boilerplate:
--->
+<!-- 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 Contact section on how to contact the developers.
+ 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> -->
<para>
This documentation is included with the current &p-status; 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> ;-)
+ <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;[
]]>
<!-- ~~~~~ 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<![%p-not-stable;[,
some of them currently under development]]>:
+<anchor id="testing"/>
</para>
<!-- Include newfeatures.sgml boilerplate here: -->
&newfeatures;
<!-- end boilerplate -->
-
</sect2>
</sect1>
This will place the <application>Privoxy</application> configuration
files in <filename>/etc/privoxy/</filename>, and log files in
<filename>/var/log/privoxy/</filename>. Run
- <command>ckconfig privoxy on</command> to have
+ <quote><command>chkconfig privoxy on</command></quote> to have
<application>Privoxy</application> start automatically during init.
</para>
into will contain all of the configuration files.
</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.
-</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>.
-</para>
-
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="quickstart"><title>Quickstart to Using <application>Privoxy</application></title>
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="upgradersnote">
+<title>Note to Upgraders</title>
+<para>
+ 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><filename>actions file</filename></quote>
+ (<filename>default.action</filename> for most installations).
+</para>
+<para>
+ A <quote><filename>filterfile</filename></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.
+</para>
+<para>
+ 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.
+ If upgrading from 2.9.x development versions, it is still recommended
+ to use the new configuration files.
+</para>
+<para>
+ A quick list of things to be aware of before upgrading:
+</para>
+
+<para>
+ <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 reachable with a web browser
+ at the special URL: <ulink url="http://p.p/">http://p.p/</ulink>. Many
+ aspects of configuration can be done here, including temporarily disabling
+ <application>Privoxy</application>. Alternately,
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org</ulink>
+ may work in some rare cases where the former does not.
+ </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>.
+ </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="startup">
+<title>Starting <application>Privoxy</application></title>
<para>
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 800). This is the one required
+ and port 8118 (earlier versions used port 8000). This is the one required
configuration that must be done!
</para>
</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>
<para>
The included default configuration files should give a reasonable starting
- point, though may be somewhat aggressive in blocking junk. Most of the
- per site configuration is done in the <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.
+ 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>
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.
+ 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>
to the developers (see below).
</para>
+</sect2>
-<!-- ~~~~~ New section ~~~~~ -->
+<!-- ~~~~~ New section ~~~~~ -->
<sect2>
<title>Command Line Options</title>
<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
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.
+ to these files. Note: one or two requests to the proxy might required to
+ <quote>wake up</quote> <application>Privoxy</application>,
+ and force a re-reading of the configuration. It is not necessarily
+ instantaneous.
</para>
<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
<literal>
<msgtext>
<literallayout>
- <emphasis>buffer-limit 4069</emphasis>
+ <emphasis>buffer-limit 4096</emphasis>
</literallayout>
</msgtext>
</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
<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
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.
+ customized, if desired. <filename>cgi-style.css</filename> is
+ used to control the HTML attributes (fonts, etc).
</para>
<para>
The default <quote>Blocked</quote> banner page with the bright red top
Requests</title>
<!-- Include contacting.sgml boilerplate: -->
-
&contacting;
-
<!-- end boilerplate -->
+
+<!-- ~~~~~ 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>
+ To do this, point your browser to <application>Privoxy</application>
+ at <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 your submission into future versions.
+</para>
+
+<para>
+ 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>
<sect3 id="bookmarklets">
<title>Bookmarklets</title>
<para>
- Here are some bookmarklets to allow you to easily access a
- <quote>mini</quote> version of this page. They are designed for MS Internet
- Explorer, but should work equally well in Netscape, Mozilla, and other
- browsers which support JavaScript. They are designed to run directly from
- your bookmarks - not by clicking the links below (although that will work for
- testing).
+ 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>
</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
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.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
projects / privoxy.git / blobdiff