<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
<!entity p-version "3.0.9">
-<!entity p-status "UNRELEASED">
+<!entity p-status "beta">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.69 2008/03/29 12:14:25 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.75 2008/06/13 16:06:48 fabiankeil Exp $
Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.69 2008/03/29 12:14:25 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.75 2008/06/13 16:06:48 fabiankeil Exp $</pubdate>
<!--
<sect1 id="whatsnew">
<title>What's New in this Release</title>
<para>
- There are many improvements and new features since <application>Privoxy 3.0.6</application>, the last stable release:
+ There are many improvements and new features since <application>Privoxy 3.0.8</application>, the last stable release:
</para>
<para>
<itemizedlist>
<listitem>
<para>
- Two new actions <link
- linkend="server-header-tagger">server-header-tagger</link>
- and <link
- linkend="client-header-tagger">client-header-tagger</link>
- that can be used to create arbitrary <quote>tags</quote>
- based on client and server headers.
- These <quote>tags</quote> can then subsequently be used
- to control the other actions used for the current request,
- greatly increasing &my-app;'s flexibility and selectivity. See <link
- linkend="tag-pattern">tag patterns</link> for more information on tags.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Header filtering is done with dedicated header filters now. As a result
- the actions <quote>filter-client-headers</quote> and <quote>filter-server-headers</quote>
- that were introduced with <application>Privoxy 3.0.5</application> to apply
- content filters to the headers have been removed.
- See the new actions <link
- linkend="server-header-filter">server-header-filter</link>
- and <link
- linkend="client-header-filter">client-header-filter</link> for details.
- </para>
- </listitem>
- <listitem>
- <para>
- There are four new options for the main <filename>config</filename> file:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <link
- linkend="allow-cgi-request-crunching">allow-cgi-request-crunching</link>
- which allows requests for Privoxy's internal CGI pages to be
- blocked, redirected or (un)trusted like ordinary requests.
- </para>
- </listitem>
- <listitem>
- <para>
- <link
- linkend="split-large-forms">split-large-forms</link>
- that will work around a browser bug that caused IE6 and IE7 to
- ignore the Submit button on the Privoxy's edit-actions-for-url CGI
- page.
- </para>
- </listitem>
- <listitem>
- <para>
- <link
- linkend="accept-intercepted-requests">accept-intercepted-requests</link>
- which allows to combine Privoxy with any packet filter to create an
- intercepting proxy for HTTP/1.1 requests (and for HTTP/1.0 requests
- with Host header set). This means clients can be forced to use
- &my-app; even if their proxy settings are configured differently.
- </para>
- </listitem>
- <listitem>
- <para>
- <link
- linkend="templdir">templdir</link>
- to designate an alternate location for &my-app;'s
- locally customized CGI templates so that
- these are not overwritten during upgrades.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
-
+ Added SOCKS5 support (with address resolution done by
+ the SOCKS5 server). Patch provided by Eric M. Hopper.
+ </para>
+ </listitem>
<listitem>
<para>
- A new command line option <literal>--pre-chroot-nslookup hostname</literal> to
- initialize the resolver library before chroot'ing. On some systems this
- reduces the number of files that must be copied into the chroot tree.
- (Patch provided by Stephen Gildea)
+ The "blocked" CGI pages include a block reason that was
+ provided as argument to the last-applying block action.
</para>
</listitem>
-
<listitem>
<para>
- The <link
- linkend="forward-override">forward-override</link> action
- allows changing of the forwarding settings through the actions files.
- Combined with tags, this allows to choose the forwarder based on
- client headers like the <literal>User-Agent</literal>, or the request origin.
- </para>
+ If enable-edit-actions is disabled (the default since 3.0.7 beta)
+ the show-status page hides the edit buttons and explains why.
+ Previously the user would get the "this feature has been disabled"
+ message after using the edit button.
+ </para>
</listitem>
-
<listitem>
<para>
- The <link
- linkend="redirect">redirect</link> action can now use regular
- expression substitutions against the original URL.
+ Forbidden CONNECT requests are treated like blocks by default.
+ The now-pointless treat-forbidden-connects-like-blocks action
+ has been removed.
</para>
</listitem>
-
<listitem>
<para>
- <application>zlib</application> support is now available as a compile
- time option to filter compressed content. Patch provided by Wil Mahan.
+ Not enabling limit-connect now allows CONNECT requests to all ports.
+ In previous versions it would only allow CONNECT requests to port 443.
+ Use +limit-connect{443} if you think you need the old default behaviour.
</para>
</listitem>
- <listitem>
- <para>
- Improve various filters, and add new ones.
+ <listitem>
+ <para>
+ The CGI editor gets turned off after three edit requests with invalid
+ file modification timestamps. This makes life harder for attackers
+ who can leverage browser bugs to send fake Referers and intend to
+ brute-force edit URLs.
</para>
</listitem>
-
-
<listitem>
<para>
- Include support for RFC 3253 so that <filename>Subversion</filename> works
- with &my-app;. Patch provided by Petr Kadlec.
+ Action settings for multiple patterns in the same section are
+ shared in memory. As a result these sections take up less space
+ (and are loaded slightly faster). Problem reported by Franz Schwartau.
</para>
</listitem>
-
<listitem>
<para>
- Logging can be completely turned off by not specifying a logfile directive.
+ Linear white space in HTTP headers will be normalized to single
+ spaces before parsing the header's content, headers split across
+ multiple lines get merged first.
</para>
</listitem>
-
-
<listitem>
<para>
- A number of improvements to Privoxy's internal CGI pages, including the
- use of favicons for error and control pages.
+ Host information is gathered outside the main thread so it's less
+ likely to delay other incoming connections if the host is misconfigured.
</para>
</listitem>
-
<listitem>
<para>
- Many bugfixes, memory leaks addressed, code improvements, and logging
- improvements.
+ New config option "hostname" to use a hostname other than
+ the one returned by the operating system. Useful to speed-up responses
+ for CGI requests on misconfigured systems. Requested by Max Khon.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The CGI editor supports the "disable all filters of this type"
+ directives "-client-header-filter", "-server-header-filter",
+ "-client-header-tagger" and "-server-header-tagger".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fixed false-positives with the link-by-url filter and URLs that
+ contain the pattern "/jump/".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The less-download-windows filter no longer messes
+ "Content-Type: application/x-shockwave-flash" headers up.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the show-url-info page's "Final results" section active and
+ inactive actions are listed separately. Patch provided by Lee.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The GNUmakefile supports the DESTDIR variable. Patch for
+ the install target submitted by Radoslaw Zielinski.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Embedding the content of configuration files in the show-status
+ page is significantly faster now. For a largish action file (1 MB)
+ a speedup of about 2450 times has been measured. This is mostly
+ interesting if you are using large action files or regularly use
+ Privoxy-Regression-Test while running Privoxy through Valgrind,
+ for stock configuration files it doesn't really matter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If zlib support is unavailable and there are content
+ filters active but the prevent-compression action is disabled,
+ the show-url-info page includes a warning that compression
+ might prevent filtering.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The show-url-info page provides an OpenSearch Description that
+ allows to access the page through browser search plugins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The obsolete kill-popups action has been removed as the
+ PCRS-based popup filters can do the same and are slightly
+ less unreliable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The inspect-jpegs action has been removed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The send-wafer and send-vanilla-wafer actions have been removed.
+ They weren't particular useful and their behaviour could be emulated
+ with add-header anyway.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Privoxy-Regression-Test has been significantly improved.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Most sections in the default.action file contain tests for
+ Privoxy-Regression-Test to verify that they are working as intended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Parts of Privoxy have been refactored to increase maintainability.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Building with zlib (if available) is done by default.
</para>
</listitem>
-
</itemizedlist>
</para>
+
<para>
For a more detailed list of changes please have a look at the ChangeLog.
</para>
</para>
<para>
The default profiles, and their associated actions, as pre-defined in
- <filename>standard.action</filename> are<!-- different than this table which is out of date -->:
+ <filename>standard.action</filename> are
</para>
<para>
<table frame=all><title>Default Configurations</title>
<row>
<entry>Image tag reordering</entry>
<entry>no</entry>
- <entry>no</entry>
+ <entry>yes</entry>
<entry>yes</entry>
</row>
<para>
The pattern matching syntax is different for the domain and path parts of
the URL. The domain part uses a simple globbing type matching technique,
- while the path part uses a more flexible
+ while the path part uses more flexible
<ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expressions (PCRE)</quote></ulink> based syntax.
+ Expressions</quote></ulink> (POSIX 1003.2).
</para>
<variablelist>
<sect3><title>The Path Pattern</title>
<para>
- <application>Privoxy</application> uses Perl compatible (PCRE)
+ <application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
<ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
- Expression</quote></ulink> based syntax
- (through the <ulink url="http://www.pcre.org/">PCRE</ulink> library) for
- matching the path portion (after the slash), and is thus more flexible.
+ Expressions</quote></ulink> for matching the path portion (after the slash),
+ and is thus more flexible.
</para>
<para>
There is an <link linkend="regex">Appendix</link> with a brief quick-start into regular
- expressions, and full (very technical) documentation on PCRE regex syntax is available on-line
- at <ulink url="http://www.pcre.org/man.txt">http://www.pcre.org/man.txt</ulink>.
- You might also find the Perl man page on regular expressions (<literal>man perlre</literal>)
- useful, which is available on-line at <ulink
- url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>.
+ expressions, you also might want to have a look at your operating system's documentation
+ on regular expressions (try <literal>man re_format</literal>).
</para>
<para>
to the blocked content (the latter only if the force feature is available and
enabled).
</para>
-<!--
-This doesn't actually work in all browser configuration and the user probably doesn't care anyway.
- <para>
- The <quote>BLOCKED</quote> page adapts to the available
- screen space -- it displays full-blown if space allows, or miniaturized and text-only
- if loaded into a small frame or window. If you are using <application>Privoxy</application>
- right now, you can take a look at the
- <ulink url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
- page</ulink>.
- </para>
--->
<para>
A very important exception occurs if <emphasis>both</emphasis>
<literal>block</literal> and <literal><link linkend="handle-as-image">handle-as-image</link></literal>,
<listitem>
<para>
<anchor id="filter-js-annoyances">
- <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse</screen>
+ <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.</screen>
</para>
<para>
<anchor id="filter-js-events">
- <screen>+filter{js-events} # Kill all JS event bindings (Radically destructive! Only for extra nasty sites)</screen>
+ <screen>+filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
</para>
<para>
<anchor id="filter-html-annoyances">
- <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse</screen>
+ <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
</para>
<para>
<anchor id="filter-content-cookies">
- <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content</screen>
+ <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content.</screen>
</para>
<para>
<anchor id="filter-refresh-tags">
- <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups)</screen>
+ <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).</screen>
</para>
<para>
<anchor id="filter-unsolicited-popups">
</para>
<para>
<anchor id="filter-img-reorder">
- <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective</screen>
+ <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.</screen>
</para>
<para>
<anchor id="filter-banners-by-size">
- <screen>+filter{banners-by-size} # Kill banners by size</screen>
+ <screen>+filter{banners-by-size} # Kill banners by size.</screen>
</para>
<para>
<anchor id="filter-banners-by-link">
- <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers</screen>
+ <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers.</screen>
</para>
<para>
<anchor id="filter-webbugs">
- <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking)</screen>
+ <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
</para>
<para>
<anchor id="filter-tiny-textforms">
- <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap</screen>
+ <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
</para>
<para>
<anchor id="filter-jumping-windows">
- <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves</screen>
+ <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves.</screen>
</para>
<para>
<anchor id="filter-frameset-borders">
- <screen>+filter{frameset-borders} # Give frames a border and make them resizeable</screen>
+ <screen>+filter{frameset-borders} # Give frames a border and make them resizable.</screen>
</para>
<para>
<anchor id="filter-demoronizer">
- <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets</screen>
+ <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</screen>
</para>
<para>
<anchor id="filter-shockwave-flash">
- <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects</screen>
+ <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects.</screen>
</para>
<para>
<anchor id="filter-quicktime-kioskmode">
- <screen>+filter{quicktime-kioskmode} # Make Quicktime movies savable</screen>
+ <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
</para>
<para>
<anchor id="filter-fun">
</para>
<para>
<anchor id="filter-crude-parental">
- <screen>+filter{crude-parental} # Crude parental filtering (demo only)</screen>
+ <screen>+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliable.</screen>
</para>
<para>
<anchor id="filter-ie-exploits">
- <screen>+filter{ie-exploits} # Disable a known Internet Explorer bug exploits</screen>
+ <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits.</screen>
</para>
<para>
<anchor id="filter-site-specifics">
- <screen>+filter{site-specifics} # Custom filters for specific site related problems</screen>
+ <screen>+filter{site-specifics} # Cure for site-specific problems. Don't apply generally!</screen>
+ </para>
+ <para>
+ <anchor id="filter-no-ping">
+ <screen>+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.</screen>
</para>
<para>
<anchor id="filter-google">
- <screen>+filter{google} # Removes text ads and other Google specific improvements</screen>
+ <screen>+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
</para>
<para>
<anchor id="filter-yahoo">
- <screen>+filter{yahoo} # Removes text ads and other Yahoo specific improvements</screen>
+ <screen>+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
</para>
<para>
<anchor id="filter-msn">
- <screen>+filter{msn} # Removes text ads and other MSN specific improvements</screen>
+ <screen>+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
</para>
<para>
<anchor id="filter-blogspot">
- <screen>+filter{blogspot} # Cleans up Blogspot blogs</screen>
- </para>
- <para>
- <anchor id="filter-no-ping">
- <screen>+filter{no-ping} # Removes non-standard ping attributes from anchor and area tags</screen>
+ <screen>+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
</para>
</listitem>
</varlistentry>
and be aware that using your own redirects might make it
possible to fingerprint your requests.
</para>
+ <para>
+ In case of problems with your redirects, or simply to watch
+ them working, enable <link linkend="DEBUG">debug 128</link>.
+ </para>
</listitem>
</varlistentry>
# (Note the $ at the end of the URL pattern to make sure
# the request for the rewritten URL isn't redirected as well)
{+redirect{s@$@&mode=expanded@}}
-undeadly.org/cgi\?action=article&sid=\d*$</screen>
+undeadly.org/cgi\?action=article&sid=\d*$
+
+# Redirect Google search requests to MSN
+{+redirect{s@^http://[^/]*/search\?q=([^&]*).*@http://search.msn.com/results.aspx?q=$1@}}
+.google.com/search
+
+# Redirect MSN search requests to Yahoo
+{+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}}
+search.msn.com//results\.aspx\?q=
+
+# Redirect remote requests for this manual
+# to the local version delivered by Privoxy
+{+redirect{s@^http://www@http://config@}}
+www.privoxy.org/user-manual/</screen>
</para>
</listitem>
</varlistentry>
USA
$Log: user-manual.sgml,v $
+ Revision 2.75 2008/06/13 16:06:48 fabiankeil
+ Update the "What's New in this Release" section with
+ the ChangeLog entries changelog2doc.pl could handle.
+
+ Revision 2.74 2008/05/26 15:55:46 fabiankeil
+ - Update "default profiles" table.
+ - Add some more pcrs redirect examples and note that
+ enabling debug 128 helps to get redirects working.
+
+ Revision 2.73 2008/05/23 14:43:18 fabiankeil
+ Remove previously out-commented block that caused syntax problems.
+
+ Revision 2.72 2008/05/12 10:26:14 fabiankeil
+ Synchronize content filter descriptions with the ones in default.filter.
+
+ Revision 2.71 2008/04/10 17:37:16 fabiankeil
+ Actually we use "modern" POSIX 1003.2 regular
+ expressions in path patterns, not PCRE.
+
+ Revision 2.70 2008/04/10 15:59:12 fabiankeil
+ Add another section to the client-header-tagger example that shows
+ how to actually change the action settings once the tag is created.
+
Revision 2.69 2008/03/29 12:14:25 fabiankeil
Remove send-wafer and send-vanilla-wafer actions.
projects / privoxy.git / blobdiff