<!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml -->
<!entity my-copy "©"> <!-- kludge for docbook2man -->
<!entity % draft "IGNORE"> <!-- WIP stuff -->
+<!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml -->
<!entity my-app "<application>Privoxy</application>">
]>
<!--
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.93 2009/02/14 10:14:42 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.102 2009/03/15 19:31:36 fabiankeil Exp $
Copyright (C) 2001-2009 Privoxy Developers http://www.privoxy.org/
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.93 2009/02/14 10:14:42 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.102 2009/03/15 19:31:36 fabiankeil Exp $</pubdate>
<!--
<sect1 id="whatsnew">
<title>What's New in this Release</title>
<para>
- There are only a few improvements and new features since
- <application>Privoxy 3.0.10</application>, the last stable release:
+ <application>Privoxy 3.0.12</application> is mainly a bugfix release:
</para>
<para>
<itemizedlist>
<listitem>
<para>
- The mingw32 version uses mutex locks now which prevents
- log message corruption under load. As a side effect,
- the "no thread-safe PRNG" warning could be removed as well.
+ The socket-timeout option now also works on platforms whose
+ select() implementation modifies the timeout structure.
+ Previously the timeout was triggered even if the connection
+ didn't stall. Reported by cyberpatrol.
</para>
</listitem>
<listitem>
<para>
- Support for remote toggling is controlled by the configure
- option --disable-toggle only. In previous versions it also
- depended on the action editor and thus configuring with the
- --disable-editor option would disable remote toggling support
- as well.
+ The Connection: keep-alive code properly deals with files
+ larger than 2GB. Previously the connection was closed too
+ early.
</para>
</listitem>
<listitem>
<para>
- The hide-forwarded-for-headers action has been replaced with
- the change-x-forwarded-for{} action which can also be used to
- add X-Forwarded-For headers. The latter functionality already
- existed in Privoxy versions prior to 3.0.7 but has been removed
- as it was often used unintentionally (by not using the
- hide-forwarded-for-headers action).
+ The content length for files above 2GB is logged correctly.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The user-manual directive on the show-status page links to
+ the documentation location specified with the directive,
+ not to the Privoxy website.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When running in daemon mode, Privoxy doesn't log anything
+ to the console unless there are errors before the logfile
+ has been opened.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The show-status page prints warnings about invalid directives
+ on the same line as the directives themselves.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fixed several justified (but harmless) compiler warnings,
+ mostly on 64 bit platforms.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The mingw32 version explicitly requests the default charset
+ to prevent display problems with some fonts available on more
+ recent Windows versions. Patch by Burberry.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The mingw32 version uses the Privoxy icon in the alt-tab
+ windows. Patch by Burberry.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The timestamp and the thread id is omitted in the "Fatal error"
+ message box on mingw32.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fixed two related mingw32-only buffer overflows. Triggering
+ them required control over the configuration file, therefore
+ this isn't seen as a security issue.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In verbose mode, or if the new option --show-skipped-tests
+ is used, Privoxy-Regression-Test logs skipped tests and the
+ skip reason.
</para>
</listitem>
</itemizedlist>
</para>
-<para>
- For a more detailed list of changes please have a look at the ChangeLog.
-</para>
<!-- ~~~~~ New section ~~~~~ -->
</para>
</listitem>
- <listitem>
- <para>
- The <quote>filter-client-headers</quote> and
- <quote>filter-server-headers</quote> actions that were introduced with
- <application>Privoxy 3.0.5</application> to apply content filters to
- the headers have been removed and replaced with new actions.
- See the <link
- linkend="whatsnew">What's New section</link> above.
- </para>
- </listitem>
-
-
<!--
<listitem>
<para>
<quote>reset-to-request-time</quote> overwrites the value of the
<quote>Last-Modified:</quote> header with the current time. You could use
this option together with
- <literal><link linkend="hide-if-modified-since">hided-if-modified-since</link></literal>
+ <literal><link linkend="hide-if-modified-since">hide-if-modified-since</link></literal>
to further customize your random range.
</para>
<para>
linkend="actions">specified</link> and <link linkend="actions-apply">applied
to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
define and use <link linkend="aliases">aliases</link>. Now, let's look at an
- example <filename>default.action</filename> and <filename>user.action</filename>
- file and see how all these pieces come together:
+ example <filename>match-all.action</filename>, <filename>default.action</filename>
+ and <filename>user.action</filename> file and see how all these pieces come together:
</para>
-<sect3><title>default.action</title>
+<sect3>
+<title>match-all.action</title>
+<para>
+ Remember <emphasis>all actions are disabled when matching starts</emphasis>,
+ so we have to explicitly enable the ones we want.
+</para>
<para>
-Every config file should start with a short comment stating its purpose:
+ While the <filename>match-all.action</filename> file only contains a
+ single section, it is probably the most important one. It has only one
+ pattern, <quote><literal>/</literal></quote>, but this pattern
+ <link linkend="af-patterns">matches all URLs</link>. Therefore, the set of
+ actions used in this <quote>default</quote> section <emphasis>will
+ be applied to all requests as a start</emphasis>. It can be partly or
+ wholly overridden by other actions files like <filename>default.action</filename>
+ and <filename>user.action</filename>, but it will still be largely responsible
+ for your overall browsing experience.
</para>
<para>
- <screen># Sample default.action file <ijbswa-developers@lists.sourceforge.net></screen>
+ Again, at the start of matching, all actions are disabled, so there is
+ no need to disable any actions here. (Remember: a <quote>+</quote>
+ preceding the action name enables the action, a <quote>-</quote> disables!).
+ Also note how this long line has been made more readable by splitting it into
+ multiple lines with line continuation.
+</para>
+
+<para>
+ <screen>
+{ \
+ +<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
+ +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
+ +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
+}
+/ # Match all URLs
+ </screen>
</para>
<para>
-Then, since this is the <filename>default.action</filename> file, the
-first section is a special section for internal use that you needn't
-change or worry about:
+ The default behavior is now set.
+</para>
+</sect3>
+
+<sect3>
+<title>default.action</title>
+
+<para>
+ If you aren't a developer, there's no need for you to edit the
+ <filename>default.action</filename> file. It is maintained by
+ the &my-app; developers and if you disagree with some of the
+ sections, you should overrule them in your <filename>user.action</filename>.
+</para>
+
+<para>
+ Understanding the <filename>default.action</filename> file can
+ help you with your <filename>user.action</filename>, though.
+</para>
+
+<para>
+ The first section in this file is a special section for internal use
+ that prevents older &my-app; versions from reading the file:
</para>
<para>
##########################################################################
# Settings -- Don't change! For internal Privoxy use ONLY.
##########################################################################
-
{{settings}}
-for-privoxy-version=3.0</screen>
+for-privoxy-version=3.0.11</screen>
</para>
<para>
-After that comes the (optional) alias section. We'll use the example
-section from the above <link linkend="aliases">chapter on aliases</link>,
-that also explains why and how aliases are used:
+ After that comes the (optional) alias section. We'll use the example
+ section from the above <link linkend="aliases">chapter on aliases</link>,
+ that also explains why and how aliases are used:
</para>
<para>
shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
</para>
-<para>
- Now come the regular sections, i.e. sets of actions, accompanied
- by URL patterns to which they apply. Remember <emphasis>all actions
- are disabled when matching starts</emphasis>, so we have to explicitly
- enable the ones we want.
-</para>
-
-<para>
- The first regular section is probably the most important. It has only
- one pattern, <quote><literal>/</literal></quote>, but this pattern
- <link linkend="af-patterns">matches all URLs</link>. Therefore, the
- set of actions used in this <quote>default</quote> section <emphasis>will
- be applied to all requests as a start</emphasis>. It can be partly or
- wholly overridden by later matches further down this file, or in user.action,
- but it will still be largely responsible for your overall browsing
- experience.
-</para>
-
-<para>
- Again, at the start of matching, all actions are disabled, so there is
- no need to disable any actions here. (Remember: a <quote>+</quote>
- preceding the action name enables the action, a <quote>-</quote> disables!).
- Also note how this long line has been made more readable by splitting it into
- multiple lines with line continuation.
-</para>
-
-<para>
- <screen>
-##########################################################################
-# "Defaults" section:
-##########################################################################
- { \
- +<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
- +<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
- +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
- +<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
- +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
- +<link linkend="FILTER-IE-EXPLOITS">filter{ie-exploits}</link> \
- +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
- +<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
- +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
- +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
- +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
- }
- / # forward slash will match *all* potential URL patterns.</screen>
-</para>
-
-<para>
- The default behavior is now set.
- <!--
- This needs rewording, but it can wait for now.
- fk 2007-11-17
-
- Note that some actions, like not hiding
- the user agent, are part of a <quote>general policy</quote> that applies
- universally and won't get any exceptions defined later. Other choices,
- like not blocking (which is <emphasis>understandably</emphasis> the
- default!) need exceptions, i.e. we need to specify explicitly what we
- want to block in later sections.
- -->
-</para>
-
<para>
The first of our specialized sections is concerned with <quote>fragile</quote>
sites, i.e. sites that require minimum interference, because they are either
.scan.co.uk</screen>
</para>
-<!-- No longer needed BEGIN OF COMMENTED OUT BLOCK
-
-<para>
- Then, there are sites which rely on pop-up windows (yuck!) to work.
- Since we made pop-up-killing our default above, we need to make exceptions
- now. <ulink url="http://www.mozilla.org/">Mozilla</ulink> users, who
- can turn on smart handling of unwanted pop-ups in their browsers, can
- safely choose
- -<literal><link linkend="FILTER-ALL-POPUPS">filter{popups}</link></literal> above
- and hence don't need this section. Anyway, disabling an already disabled
- action doesn't hurt, so we'll define our exceptions regardless of what was
- chosen in the defaults section:
-</para>
-
-<para>
- <screen>
-# These sites require pop-ups too :(
-#
-{ -<link linkend="FILTER-ALL-POPUPS">filter{popups}</link> }
-.dabs.com
-.overclockers.co.uk
-.deutsche-bank-24.de</screen>
-</para>
-
- END OF COMMENTED OUT BLOCK -->
-
<para>
The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
- action, which we enabled per default above, breaks some sites. So disable
- it for popular sites where we know it misbehaves:
+ action, which may have been enabled in <filename>match-all.action</filename>,
+ breaks some sites. So disable it for popular sites where we know it misbehaves:
</para>
<para>
be blocked, a substitute image can be sent, rather than an HTML page.
Contacting the remote site to find out is not an option, since it
would destroy the loading time advantage of banner blocking, and it
- would feed the advertisers (in terms of money <emphasis>and</emphasis>
- information). We can mark any URL as an image with the <literal><link
+ would feed the advertisers information about you. We can mark any
+ URL as an image with the <literal><link
linkend="handle-as-image">handle-as-image</link></literal> action,
and marking all URLs that end in a known image file extension is a
good start:
USA
$Log: user-manual.sgml,v $
+ Revision 2.102 2009/03/15 19:31:36 fabiankeil
+ Update "What's New in this Release" section.
+
+ Revision 2.101 2009/02/25 19:01:56 fabiankeil
+ Fix typo.
+
+ Revision 2.100 2009/02/19 17:14:11 fabiankeil
+ - Copy the release cycle description from announce.txt into
+ the "What's New" section.
+ - Stop referring to the ChangeLog for a "complete list of changes".
+ The "What's New" section already contains the complete list.
+
+ Revision 2.99 2009/02/19 02:20:22 hal9
+ Make some links in seealso conditional. Man page is now privoxy only links.
+
+ Revision 2.98 2009/02/16 17:10:33 fabiankeil
+ Fix entry about shortened log messages. Noticed by Lee.
+
+ Revision 2.97 2009/02/14 18:01:00 fabiankeil
+ Import ChangeLog.
+
+ Revision 2.96 2009/02/14 13:14:03 fabiankeil
+ Unbreak syntax.
+
+ Revision 2.95 2009/02/14 12:51:26 fabiankeil
+ Mention match-all.action in the "Actions Files Tutorial" section.
+
+ Revision 2.94 2009/02/14 11:50:31 fabiankeil
+ Some indentation fixes.
+
Revision 2.93 2009/02/14 10:14:42 fabiankeil
Mention match-all.action in the action file descriptions.
projects / privoxy.git / blobdiff