<!entity license SYSTEM "license.sgml">
<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
-<!entity p-version "2.9.16">
-<!entity p-status "beta">
+<!entity p-version SYSTEM "doc_version.tmp">
+<!entity p-status SYSTEM "doc_status.tmp">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
-<!entity % p-not-stable "INCLUDE">
+<!entity % p-not-stable "IGNORE">
<!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 -->
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 1.123.2.11 2002/07/26 15:20:31 oes Exp $
+ $Id: user-manual.sgml,v 2.5 2002/10/10 03:50:38 hal9 Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 1.123.2.11 2002/07/26 15:20:31 oes Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.5 2002/10/10 03:50:38 hal9 Exp $</pubdate>
<!--
<para>
You can find the latest version of the <citetitle>User Manual</citetitle> 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
+ Please see the <link linkend="contact">Contact section</link> on how to
contact the developers.
</para>
<para>
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> ;-)]]>.
+ and is mostly complete at this point.
+ Development of version 3.2 is just beginning,
+ and will include many significant changes and enhancements over
+ earlier versions]]>.
</para>
<!-- include only in non-stable versions -->
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!
+ not many! Please find them!
</para>
]]>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-mac"><title>Mac OSX</title>
<para>
- Unzip the downloaded package (you can either double-click on the file
- in the finder, or on the desktop if you downloaded it there). The
- Privoxy.pkg package should appear after unzipping. Then,
- double-click on that Privoxy.pkg package installer icon and follow
- the installation process.
+ Unzip the downloaded file (you can either double-click on the file
+ from the finder, or from the desktop if you downloaded it there).
+ Then, double-click on the package installer icon named
+ <literal>Privoxy.pkg</literal>
+ and follow the installation process.
<application>Privoxy</application> will be installed in the folder
<literal>/Library/Privoxy</literal>.
- It will run automatically whenever you start up. To prevent it from
- running automatically, remove or rename the folder
+ It will start automatically whenever you start up. To prevent it from
+ starting automatically, remove or rename the folder
<literal>/Library/StartupItems/Privoxy</literal>.
</para>
<para>
- To run Privoxy by hand, double-click on
- <literal>RunPrivoxy.command</literal>.
- To run Privoxy from Terminal, execute
- <literal>/Library/Privoxy/RunPrivoxy.command</literal>.
+ To start Privoxy by hand, double-click on
+ <literal>StartPrivoxy.command</literal> in the
+ <literal>/Library/Privoxy</literal> folder.
+ Or, type this command in the Terminal:
+</para>
+<para>
+ <screen>
+ /Library/Privoxy/StartPrivoxy.command
+ </screen>
+</para>
+<para>
+ You will be prompted for the administrator password.
</para>
</sect3>
remove this directory.
</para>
</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="installattion-gentoo"><title>Gentoo</title>
+<para>
+ Gentoo source packages (Ebuilds) for <application>Privoxy</application> are
+ contained in the Gentoo Portage Tree (they are not on the download page,
+ but there is a Gentoo section, where you can see when a new
+ <application>Privoxy</application> Version is added to the Portage Tree).
+</para>
+<para>
+ Before installing <application>Privoxy</application> under Gentoo just do
+ first <literal>emerge rsync</literal> to get the latest changes from the
+ Portage tree. With <literal>emerge privoxy</literal> you install the latest
+ version.
+</para>
+<para>
+ Configuration files are in <filename>/etc/privoxy</filename>, the
+ documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
+ and the Log directory is in <filename>/var/log/privoxy</filename>.
+</para>
+</sect3>
+
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
<para>
As user feedback comes in and development continues, we will make updated versions
- of both the software and the main <link linkend="actions-file">actions file</link>
- (<literal>default.action</literal>) available for download.
+ of both the main <link linkend="actions-file">actions file</link> (as a <ulink
+ url="http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670">separate
+ package</ulink>) and the software itself (including the actions file) available for
+ download.
</para>
<para>
to our announce mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
</para>
-<para>
- Both can be downloaded from the <ulink
- url="http://sourceforge.net/project/showfiles.php?group_id=11118">files
- section</ulink> on <ulink url="http://sourceforge.net/">SourceForge</ulink>.
-</para>
-
<para>
In order not to loose your personal changes and adjustments when updating
to the latest <literal>default.action</literal> file we <emphasis>strongly
<listitem>
<para>
Set your browser to use <application>Privoxy</application> as HTTP and
- HTTPS proxy by setting the proxy configuration for address of
+ HTTPS (SSL) proxy by setting the proxy configuration for address of
<literal>127.0.0.1</literal> and port <literal>8118</literal>.
(<application>Junkbuster</application> and earlier versions of
<application>Privoxy</application> used port 8000.) See the section <link
<listitem>
<para>
Flush your browser's disk and memory caches, to remove any cached ad images.
+ If using <application>Privoxy</application> to manage cookies, you should
+ remove any currently stored cookies too.
</para>
</listitem>
<title>Mac OSX</title>
<para>
During installation, <application>Privoxy</application> is configured to
- start automatically when the system restarts. To run Privoxy by hand,
- double-click on the <literal>RunPrivoxy.command</literal> icon in the
+ start automatically when the system restarts. To start Privoxy by hand,
+ double-click on the <literal>StartPrivoxy.command</literal> icon in the
<literal>/Library/Privoxy</literal> folder. Or, type this command
in the Terminal:
</para>
<para>
<screen>
- /Library/Privoxy/RunPrivoxy.command
+ /Library/Privoxy/StartPrivoxy.command
</screen>
</para>
<para>
- If you are not logged in as an administrator, you will be asked for the
- administrator password when starting <application>Privoxy</application>
- by hand.
+ You will be prompted for the administrator password.
</para>
</sect2>
</para>
</sect2>
+<sect2 id="start-gentoo">
+<title>Gentoo</title>
+<para>
+ A script is again used. It will use the file <filename>/etc/privoxy/config
+ </filename> as its main configuration file.
+</para>
+<para>
+ <screen>
+ /etc/init.d/privoxy start
+ </screen>
+</para>
+<para>
+ Note that <application>Privoxy</application> is not automatically started at
+ boot time by default. You can change this with the <literal>rc-update</literal>
+ command.
+</para>
+<para>
+ <screen>
+ rc-update add privoxy default
+ </screen>
+</para>
+</sect2>
+
<!--
<para>
</para>
<para>
- If the above paragraph sounds gibberish to you, you might want to <ulink
- url="actions-file.html#ACTIONSFILE">read more about the actions concept</ulink>
- or even dive deep into the <ulink url="appendix.html#ACTIONSANAT">Appendix
- on actions</ulink>.
+ If the above paragraph sounds gibberish to you, you might want to <link
+ linkend="actions-file">read more about the actions concept</link>
+ or even dive deep into the <link linkend="actionsanat">Appendix
+ on actions</link>.
</para>
<para>
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
- section <ulink url="contact.html"><quote>Contacting the
- Developers</quote></ulink> below.
+ section <link linkend="contact"><quote>Contacting the
+ Developers</quote></link> below.
</para>
-->
<member>
▪ <ulink url="http://config.privoxy.org/toggle">Toggle Privoxy on or off</ulink>
</member>
+ <member>
+ ▪ <ulink url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
+ </member>
</simplelist>
</msgtext>
</screen>
<application>Privoxy</application> takes for which URLs, and thus determine
how ad images, cookies and various other aspects of HTTP content and
transactions are handled, and on which sites (or even parts thereof). There
- are three such files included with <application>Privoxy</application> (as of
- version 2.9.15), with differing purposes:
- </para>
+ are three such files included with <application>Privoxy</application>, with
+ differing purposes:
+</para>
<para>
<itemizedlist>
url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
The editor allows both fine-grained control over every single feature on a
per-URL basis, and easy choosing from wholesale sets of defaults like
- <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.
+ <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Radical</quote>.
+ Warning: the <quote>Radical</quote> setting is not only more aggressive,
+ but includes settings that are fun and subversive, and which some may find of
+ dubious merit!
</para>
<para>
the same URL set the same action differently, the last match wins. If not,
the effects are aggregated. E.g. a URL might match a regular section with
a heading line of <literal>{
- +<ulink url="actions-file.html#HANDLE-AS-IMAGE">handle-as-image</ulink> }</literal>,
+ +<link linkend="handle-as-image">handle-as-image</link> }</literal>,
then later another one with just <literal>{
- +<ulink url="actions-file.html#BLOCK">block</ulink> }</literal>, resulting
+ +<link linkend="block">block</link> }</literal>, resulting
in <emphasis>both</emphasis> actions to apply.
</para>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="af-patterns">
<title>Patterns</title>
+<para>
+ As mentioned, <application>Privoxy</application> uses <quote>patterns</quote>
+ to determine what actions might apply to which sites and pages your browser
+ attempts to access. These <quote>patterns</quote> use wild card type
+ <emphasis>pattern</emphasis> matching to achieve a high degree of
+ flexibility. This allows one expression to be expanded and potentially match
+ against many similar patterns.
+</para>
+
<para>
- Generally, a pattern has the form <literal><domain>/<path></literal>,
- where both the <literal><domain></literal> and <literal><path></literal>
- are optional. (This is why the pattern <literal>/</literal> matches all URLs).
+ Generally, a <application>Privoxy</application> pattern has the form
+ <literal><domain>/<path></literal>, where both the
+ <literal><domain></literal> and <literal><path></literal> are
+ optional. (This is why the special <literal>/</literal> pattern matches all
+ URLs). Note that the protocol portion of the URL pattern (e.g.
+ <literal>http://</literal>) should <emphasis>not</emphasis> be included in
+ the pattern. This is assumed already!
</para>
<variablelist>
<listitem>
<para>
matches any domain that <emphasis>ENDS</emphasis> in
- <literal>.example.com</literal>
+ <literal>.example.com</literal> (e.g. <literal>www.example.com</literal>)
</para>
</listitem>
</varlistentry>
<para>
It makes <emphasis>no sense at all</emphasis> to use this action in conjunction
with the <literal><link linkend="session-cookies-only">session-cookies-only</link></literal> action,
- since it would prevent the session cookies from being set.
+ since it would prevent the session cookies from being set. See also
+ <literal><link linkend="filter-content-cookies">filter-content-cookies</link></literal>.
</para>
</listitem>
</varlistentry>
<literal><link linkend="buffer-limit">buffer-limit</link></literal>
option in the main <link linkend="config">config file</link>. The
default is 4096 KB (4 Megs). Once this limit is exceeded, the buffered
- data, and all pending data, is passed through unfiltered. Inappropriate
- MIME types are not filtered.
+ data, and all pending data, is passed through unfiltered.
+ </para>
+ <para>
+ Inappropriate MIME types, such as zipped files, are not filtered at all.
+ Encrypted SSL data (from HTTPS servers) cannot be filtered either since
+ this would violate the integrity of the secure transaction.
</para>
<para>
At this time, <application>Privoxy</application> cannot (yet!) uncompress compressed
Note that it is up to the browser how it handles such cookies without an <quote>expires</quote>
field. If you use an exotic browser, you might want to try it out to be sure.
</para>
+ <para>
+ This setting also has no effect on cookies that may have been stored
+ previously by the browser before starting <application>Privoxy</application>.
+ These would have to be removed manually.
+ </para>
+ <para>
+ <application>Privoxy</application> also uses
+ the <link linkend="filter-content-cookies">content-cookies filter</link>
+ to block some types of cookies. Content cookies are not effected by
+ <literal>session-cookies-only</literal>.
+ </para>
</listitem>
</varlistentry>
<para>
Credit: The site which gave us the general idea for these bookmarklets is
- <ulink url="http://www.bookmarklets.com">www.bookmarklets.com</ulink>. They
+ <ulink url="http://www.bookmarklets.com/">www.bookmarklets.com</ulink>. They
have more information about bookmarklets.
</para>
<para>
First, the server headers are read and processed to determine, among other
things, the MIME type (document type) and encoding. The headers are then
- filtered as deterimined by the
+ filtered as determined by the
<link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
<link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: user-manual.sgml,v $
+ Revision 2.5 2002/10/10 03:50:38 hal9
+ Update cookie sections for pre-existing condition, and content cookies not
+ effected by session-cookies setting.
+
+ Revision 2.4 2002/09/26 05:58:07 hal9
+ Change development status from working on 3.0 to 3.2.
+
+ Revision 2.3 2002/09/26 00:12:17 hal9
+ Additional notes on Privoxy patterns, and filtering vs SSL.
+
+ Revision 2.2 2002/09/05 05:45:30 hal9
+ Syncing with 3.0. This should be it for doc sources. Not all builds tested
+ yet. No new content, just catching up.
+
+ Revision 1.123.2.18 2002/08/22 23:47:58 hal9
+ Add 'Documentation' to Privoxy Menu shot in Configuration section to match
+ CGIs.
+
+ Revision 1.123.2.17 2002/08/18 01:13:05 hal9
+ Spell checked (only one typo this time!).
+
+ Revision 1.123.2.16 2002/08/09 19:20:54 david__schmidt
+ Update to Mac OSX startup script name
+
+ Revision 1.123.2.15 2002/08/07 17:32:11 oes
+ Converted some internal links from ulink to link for PDF creation; no content changed
+
+ Revision 1.123.2.14 2002/08/06 09:16:13 oes
+ Nits re: actions file download
+
+ Revision 1.123.2.13 2002/08/02 18:23:19 g_sauthoff
+ Just 2 small corrections to the Gentoo sections
+
+ Revision 1.123.2.12 2002/08/02 18:17:21 g_sauthoff
+ Added 2 Gentoo sections
+
Revision 1.123.2.11 2002/07/26 15:20:31 oes
- Added version info to title
- Added info on new filters
projects / privoxy.git / blobdiff