<!entity history SYSTEM "history.sgml">
<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
+<!entity GPLv2 SYSTEM "../../LICENSE">
<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
-<!entity p-version "3.0.20">
+<!entity changelog SYSTEM "changelog.sgml">
+<!entity p-version "3.0.25">
<!entity p-status "beta">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "INCLUDE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.161 2013/01/12 12:21:38 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.212 2016/05/25 10:50:55 fabiankeil Exp $
- Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
<subscript>
<!-- Completely the wrong markup, but very little is allowed -->
<!-- in this part of an article. FIXME -->
- <link linkend="copyright">Copyright</link> &my-copy; 2001-2013 by
- <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2016 by
+ <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.161 2013/01/12 12:21:38 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.212 2016/05/25 10:50:55 fabiankeil Exp $</pubdate>
<!--
<para>
The <citetitle>Privoxy User Manual</citetitle> gives users information on how to
install, configure and use <ulink
- url="http://www.privoxy.org/">Privoxy</ulink>.
+ url="https://www.privoxy.org/">Privoxy</ulink>.
</para>
<!-- Include privoxy.sgml boilerplate: -->
<para>
You can find the latest version of the <citetitle>Privoxy User Manual</citetitle> at <ulink
- url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink>.
+ url="https://www.privoxy.org/user-manual/">https://www.privoxy.org/user-manual/</ulink>.
Please see the <link linkend="contact">Contact section</link> 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>. -->
-<!-- </para> -->
</abstract>
</artheader>
<sect1 label="1" id="introduction"><title>Introduction</title>
<para>
This documentation is included with the current &p-status; version of
- <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[,
+ <application>Privoxy</application>, &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 a new version is currently nearing
<application>Privoxy</application> is available both in convenient pre-compiled
packages for a wide range of operating systems, and as raw source code.
For most users, we recommend using the packages, which can be downloaded from our
- <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project
+ <ulink url="https://sourceforge.net/projects/ijbswa/">Privoxy Project
Page</ulink>.
</para>
</sect3>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-tbz"><title>FreeBSD</title>
+<sect3 id="installation-freebsd"><title>FreeBSD</title>
<para>
Privoxy is part of FreeBSD's Ports Collection, you can build and install
it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
</para>
-<para>
- If you don't use the ports, you can fetch and install
- the package with <literal>pkg_add -r privoxy</literal>.
-</para>
-<para>
- The port skeleton and the package can also be downloaded from the
- <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">File Release
- Page</ulink>, but there's no reason to use them unless you're interested in the
- beta releases which are only available there.
-</para>
-</sect3>
-
-</sect2>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-source"><title>Building from Source</title>
-
-<para>
- The most convenient way to obtain the <application>Privoxy</application> sources
- is to download the source tarball from our
- <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118&package_id=10571">project download
- page</ulink>.
-</para>
-
-<para>
- If you like to live on the bleeding edge and are not afraid of using
- possibly unstable development versions, you can check out the up-to-the-minute
- version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
- CVS repository</ulink>.
-<!--
- deprecated...out of business.
- or simply download <ulink
- url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
- tarball.</ulink>
--->
-</para>
-
-<!-- include buildsource.sgml boilerplate: -->
-&buildsource;
-<!-- end boilerplate -->
-
-</sect2>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
-
-<para>
- If you wish to receive an email notification whenever we release updates of
- <application>Privoxy</application> or the actions file, <ulink
- url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce/">subscribe
- to our announce mailing list</ulink>, ijbswa-announce@lists.sourceforge.net.
-</para>
-
-<para>
- In order not to lose your personal changes and adjustments when updating
- to the latest <literal>default.action</literal> file we <emphasis>strongly
- recommend</emphasis> that you use <literal>user.action</literal> and
- <literal>user.filter</literal> for your local
- customizations of <application>Privoxy</application>. See the <link
- linkend="actions-file">Chapter on actions files</link> for details.
-</para>
-
-</sect2>
-
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="whatsnew">
-<title>What's New in this Release</title>
-<para>
- <application>Privoxy 3.0.20</application> is a beta release.
- The changes since 3.0.19 stable are:
-</para>
-
-<para>
- <itemizedlist>
- <listitem>
- <para>
- Bug fixes:
- <itemizedlist>
- <listitem>
- <para>
- Client sockets are now properly shutdown and drained before being
- closed. This fixes page truncation issues with clients that aggressively
- pipeline data on platforms that otherwise discard already written data.
- The issue mainly affected Opera users and was initially reported
- by Kevin in #3464439, szotsaki provided additional information to track
- down the cause.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix latency calculation for shared connections (disabled by default).
- It was broken since their introduction in 2009. The calculated latency
- for most connections would be 0 in which case the timeout detection
- failed to account for the real latency.
- </para>
- </listitem>
- <listitem>
- <para>
- Reject URLs with invalid port. Previously they were parsed incorrectly and
- characters between the port number and the first slash were silently
- dropped as shown by curl test 187.
- </para>
- </listitem>
- <listitem>
- <para>
- The default-server-timeout and socket-timeout directives accept 0 as
- valid value.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix a race condition on Windows that could cause Privoxy to become
- unresponsive after toggling it on or off through the taskbar icon.
- Reported by Tim H. in #3525694.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix the compilation on Windows when configured without IPv6 support.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix an assertion that could cause debug builds to abort() in case of
- socks5 connection failures with "debug 2" enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix an assertion that could cause debug builds to abort() if a filter
- contained nul bytes in the replacement text.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- General improvements:
- <itemizedlist>
- <listitem>
- <para>
- Significantly improved keep-alive support for both client and server
- connections.
- </para>
- </listitem>
- <listitem>
- <para>
- New debug log level 65536 which logs all actions that were applied to
- the request.
- </para>
- </listitem>
- <listitem>
- <para>
- New directive client-header-order to forward client headers in a
- different order than the one in which they arrived.
- </para>
- </listitem>
- <listitem>
- <para>
- New directive tolerate-pipelining to allow client-side pipelining.
- If enabled (3.0.20 beta enables it by default), Privoxy will keep
- pipelined client requests around to deal with them once the current
- request has been served.
- </para>
- </listitem>
- <listitem>
- <para>
- New --config-test option to let Privoxy exit after checking whether or not
- the configuration seems valid. The limitations noted in TODO #22 and #23
- still apply. Based on a patch by Ramkumar Chinchani.
- </para>
- </listitem>
- <listitem>
- <para>
- New limit-cookie-lifetime{} action to let cookies expire before the end
- of the session. Suggested by Rick Sykes in #1049575.
- </para>
- </listitem>
- <listitem>
- <para>
- Increase the hard-coded maximum number of actions and filter files from
- 10 to 30 (each). It doesn't significantly affect Privoxy's memory usage
- and recompiling wasn't an option for all Privoxy users that reached the
- limit.
- </para>
- </listitem>
- <listitem>
- <para>
- Add support for chunk-encoded client request bodies. Previously
- chunk-encoded request bodies weren't guaranteed to be forwarded correctly,
- so this can also be considered a bug fix although chunk-encoded request
- bodies aren't commonly used in the real world.
- </para>
- </listitem>
- <listitem>
- <para>
- Add support for Tor's optimistic-data SOCKS extension, which can reduce the
- latency for requests on newly created connections. Currently only the
- headers are sent optimistically and only if the client request has already
- been read completely which rules out requests with large bodies.
- </para>
- </listitem>
- <listitem>
- <para>
- After preventing the client from pipelining, don't signal keep-alive
- intentions. When looking at the response headers alone, it previously
- wasn't obvious from the client's perspective that no additional responses
- should be expected.
- </para>
- </listitem>
- <listitem>
- <para>
- Stop considering client sockets tainted after receving a request with body.
- It hasn't been necessary for a while now and unnecessarily causes test
- failures when using curl's test suite.
- </para>
- </listitem>
- <listitem>
- <para>
- Allow HTTP/1.0 clients to signal interest in keep-alive through the
- Proxy-Connection header. While such client are rare in the real world, it
- doesn't hurt and couple of curl tests rely on it.
- </para>
- </listitem>
- <listitem>
- <para>
- Only remove duplicated Content-Type headers when filters are enabled.
- If they are not it doesn't cause ill effects and the user might not want it.
- Downgrade the removal message to LOG_LEVEL_HEADER to clarify that it's not
- an error in Privoxy and is unlikely to cause any problems in general.
- Anonymously reported in #3599335.
- </para>
- </listitem>
- <listitem>
- <para>
- Set the socket option SO_LINGER for the client socket.
- </para>
- </listitem>
- <listitem>
- <para>
- Move several variable declarations to the beginning of their code block.
- It's required when compiling with gcc 2.95 which is still used on some
- platforms. Initial patch submitted by Simon South in #3564815.
- </para>
- </listitem>
- <listitem>
- <para>
- Optionally try to sanity-check strptime() results before trusting them.
- Broken strptime() implementations have caused problems in the past and
- the most recent offender seems to be FreeBSD's libc (standards/173421).
- </para>
- </listitem>
- <listitem>
- <para>
- When filtering is enabled, let Range headers pass if the range starts at
- the beginning. This should work around (or at least reduce ) the video
- playback issues with various Apple clients as reported by Duc in #3426305.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not confuse a client hanging up with a connection time out. If a client
- closes its side of the connection without sending a request line, do not
- send the CLIENT_CONNECTION_TIMEOUT_RESPONSE, but report the condition
- properly.
- </para>
- </listitem>
- <listitem>
- <para>
- Allow closing curly braces as part of action values as long as they are
- escaped.
- </para>
- </listitem>
- <listitem>
- <para>
- On Windows, the logfile is now written before showing the GUI error
- message which blocks until the user acknowledges it.
- Reported by Adriaan in #3593603.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove an unreasonable parameter limit in the CGI interface. The new
- parameter limit depends on the memory available and is currently unlikely
- to be reachable, due to other limits in both Privoxy and common clients.
- Reported by Andrew on ijbswa-users@.
- </para>
- </listitem>
- <listitem>
- <para>
- Decrease the chances of parse failures after requests with unsupported
- methods were sent to the CGI interface.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Action file improvements:
- <itemizedlist>
- <listitem>
- <para>
- Remove the comment that indicated that updated default.action versions
- are released on their own.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'optimize.indieclick.com/' and 'optimized-by.rubiconproject.com/'
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock 'adjamblog.wordpress.com/' and 'adjamblog.files.wordpress.com/'.
- Reported by Ryan Farmer in #3496116.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock '/.*Bugtracker'. Reported by pwhk in #3522341.
- </para>
- </listitem>
- <listitem>
- <para>
- Add test URLs for '.freebsd.org' and '.watson.org'.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock '.urbandictionary.com/popular'.
- </para>
- </listitem>
- <listitem>
- <para>
- Block '.adnxs.com/'.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'farm.plista.com/widgetdata.php'.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'rotation.linuxnewmedia.com/'.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'reklamy.sfd.pl/'. Reported by kacperdominik in #3399948.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'g.adspeed.net/'.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock 'websupport.wdc.com/'. Reported by Adam Piggot in #3577851.
- </para>
- </listitem>
- <listitem>
- <para>
- Block '/openx/www/delivery/'.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable fast-redirects for '.googleapis.com/'.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'imp.double.net/'. Reported by David Bo in #3070411.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'gm-link.com/' whis is used for email tracking.
- Reported by David Bo in #1812733.
- </para>
- </listitem>
- <listitem>
- <para>
- Verify that requests to "bwp." are blocked. URL taken from #1736879
- submitted by Francois Marier.
- </para>
- </listitem>
- <listitem>
- <para>
- Block '/.*bannerid='. Reported by Adam Piggott in #2975779.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'cltomedia.info/delivery/' and '.adexprt.com/'.
- Anonymously reported in #2965254.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'de17a.com/'. Reported by David Bo in #3061472.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'oskar.tradera.com/'. Reported by David Bo in #3060596.
- </para>
- </listitem>
- <listitem>
- <para>
- Block '/scripts/webtrends\.js'. Reported by johnd16 in #3002729.
- </para>
- </listitem>
- <listitem>
- <para>
- Block requests for 'pool.*.adhese.com/'. Reported by johnd16 in #3002716.
- </para>
- </listitem>
- <listitem>
- <para>
- Update path pattern for Coremetrics and add tests.
- Pattern and URLs submitted by Adam Piggott #3168443.
- </para>
- </listitem>
- <listitem>
- <para>
- Enable +fast-redirects{check-decoded-url} for 'tr.anp.se/'.
- Reported by David Bo in #3268832.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock '.conrad.se/newsletter/banners/'. Reported by David Bo in #3413824.
- </para>
- </listitem>
- <listitem>
- <para>
- Block '.tynt.com/'. Reported by Dan Stahlke in #3421767.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock '.bbci.co.uk/radio/'. Reported by Adam Piggott in #3569603.
- </para>
- </listitem>
- <listitem>
- <para>
- Block requests to 'service.maxymiser.net/'.
- Reported by johnd16 in #3118401 (with a previous URL).
- </para>
- </listitem>
- <listitem>
- <para>
- Disable fast-redirects for Google's "let's pretend your computer is
- infected" page.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock '/.*download' to resolve actionsfile feedback #3498129.
- Submitted by Steven Kolins (soundcloud.com not working).
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock '.wlxrs.com/' which is required by hotmail.com.
- Fixes #3413827 submitted by David Bo.
- </para>
- </listitem>
- <listitem>
- <para>
- Add two unblock patterns for popup radio and TV players.
- Submitted by Adam Piggott in #3596089.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Filter file improvements & bug fixes:
- <itemizedlist>
- <listitem>
- <para>
- Add a referer tagger.
- </para>
- </listitem>
- <listitem>
- <para>
- Reduce the likelihood that the google filter messes up HTML-generating
- JavaScript. Reported by Zeno Kugy in #3520260.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Documentation improvements:
- <itemizedlist>
- <listitem>
- <para>
- Revised all OS X sections due to new packaging module (OSXPackageBuilder).
- </para>
- </listitem>
- <listitem>
- <para>
- Update the list of supported operating systems to clarify that all Windows
- versions after 95 are expected to work and note that the platform-specific
- code for AmigaOS and QNX currently isn't maintained.
- </para>
- </listitem>
- <listitem>
- <para>
- Update 'Signals' section, the only explicitly handled signals are SIGINT,
- SIGTERM and SIGHUP.
- </para>
- </listitem>
- <listitem>
- <para>
- Add Haiku to the list of operating systems on which Privoxy is known to
- run.
- </para>
- </listitem>
- <listitem>
- <para>
- Add DragonFly to the list of BSDs on which Privoxy is known to run.
- </para>
- </listitem>
- <listitem>
- <para>
- Removed references to redhat-specific documentation set since it no longer
- exists.
- </para>
- </listitem>
- <listitem>
- <para>
- Removed references to building PDFs since we no longer do so.
- </para>
- </listitem>
- <listitem>
- <para>
- Multiple listen-address directives are supported since 3.0.18, correct the
- documentation to say so.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove bogus section about long and short being preferable to int.
- </para>
- </listitem>
- <listitem>
- <para>
- Corrected some Internet JunkBuster references to Privoxy.
- </para>
- </listitem>
- <listitem>
- <para>
- Removed references to www.junkbusters.com since it is no longer
- maintained. Reported by Angelina Matson.
- </para>
- </listitem>
- <listitem>
- <para>
- Various grammar and spelling corrections
- </para>
- </listitem>
- <listitem>
- <para>
- Add a client-header-tagger{} example for disabling filtering for range
- requests.
- </para>
- </listitem>
- <listitem>
- <para>
- Correct a URL in the "Privoxy with Tor" FAQ.
- </para>
- </listitem>
- <listitem>
- <para>
- Spell 'refresh-tags' correctly. Reported by Don in #3571927.
- </para>
- </listitem>
- <listitem>
- <para>
- Sort manpage options alphabetically.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove an incorrect sentence in the toggle section. The toggle state
- doesn't affect whether or not the Windows version uses the tray icon.
- Reported by Zeno Kugy in #3596395.
- </para>
- </listitem>
- <listitem>
- <para>
- Add new contributors since 3.0.19.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Log message improvements:
- <itemizedlist>
- <listitem>
- <para>
- When stopping to watch a client socket due to pipelining, additionally log
- the socket number.
- </para>
- </listitem>
- <listitem>
- <para>
- Log the client socket and its condition before closing it. This makes it
- more obvious that the socket actually gets closed and should help when
- diagnosing problems like #3464439.
- </para>
- </listitem>
- <listitem>
- <para>
- In case of SOCKS5 failures, do not explicitly log the server's response.
- It hasn't helped so far and the response can already be logged by enabling
- "debug 32768" anyway. This reverts v1.81 and the follow-up bug fix v1.84.
- </para>
- </listitem>
- <listitem>
- <para>
- Relocate the connection-accepted message from listen_loop() to serve().
- This way it's printed by the thread that is actually serving the
- connection which is nice when grepping for thread ids in log files.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Code cleanups:
- <itemizedlist>
- <listitem>
- <para>
- Remove compatibility layer for versions prior to 3.0 since it has been
- obsolete for more than 10 years now.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove the ijb_isupper() and ijb_tolower() macros from parsers.c since
- they aren't used in this file.
- </para>
- </listitem>
- <listitem>
- <para>
- Removed the 'Functions declared include:' comment sections since they tend
- to be incomplete, incorrect and out of date and the benefit seems
- questionable.
- </para>
- </listitem>
- <listitem>
- <para>
- Various comment grammar and comprehensibility improvements.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a pointless fflush() call in chat(). Flushing all streams pretty
- much all the time for no obvious reason is ridiculous.
- </para>
- </listitem>
- <listitem>
- <para>
- Relocate ijb_isupper()'s definition to project.h and get the ijb_tolower()
- definition from there, too.
- </para>
- </listitem>
- <listitem>
- <para>
- Relocate ijb_isdigit()'s definition to project.h.
- </para>
- </listitem>
- <listitem>
- <para>
- Rename ijb_foo macros to privoxy_foo.
- </para>
- </listitem>
- <listitem>
- <para>
- Add malloc_or_die() which will allow to simplify code paths where malloc()
- failures don't need to be handled gracefully.
- </para>
- </listitem>
- <listitem>
- <para>
- Add strdup_or_die() which will allow to simplify code paths where strdup()
- failures don't need to be handled gracefully.
- </para>
- </listitem>
- <listitem>
- <para>
- Replace strdup() calls with strdup_or_die() calls where it's safe and
- simplifies the code.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix white-space around parentheses.
- </para>
- </listitem>
- <listitem>
- <para>
- Add missing white-space behind if's and the following parentheses.
- </para>
- </listitem>
- <listitem>
- <para>
- Unwrap a memcpy() call in resolve_hostname_to_ip().
- </para>
- </listitem>
- <listitem>
- <para>
- Declare pcrs_get_delimiter()'s delimiters[] static const.
- </para>
- </listitem>
- <listitem>
- <para>
- Various optimisations to remove dead code and merge inefficient code
- structures for improved clarity, performance or code compactness.
- </para>
- </listitem>
- <listitem>
- <para>
- Various data type corrections.
- </para>
- </listitem>
- <listitem>
- <para>
- Change visibility of several code segments when compiling without
- FEATURE_CONNECTION_KEEP_ALIVE enabled for clarity.
- </para>
- </listitem>
- <listitem>
- <para>
- In pcrs_get_delimiter(), do not use delimiters ouside the ASCII range.
- Fixes a clang complaint.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix an error message in get_last_url() nobody is supposed to see.
- Reported by Matthew Fischer in #3507301.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix a typo in the no-zlib-support complaint. Patch submitted by Matthew
- Fischer in #3507304.
- </para>
- </listitem>
- <listitem>
- <para>
- Shorten ssplit()'s prototype by removing the last two arguments. We always
- want to skip empty fields and ignore leading delimiters, so having
- parameters for this only complicates the API.
- </para>
- </listitem>
- <listitem>
- <para>
- Use an enum for the type of the action value.
- </para>
- </listitem>
- <listitem>
- <para>
- Rename action_name's member takes_value to value_type as it isn't used as
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- Turn family mismatches in match_sockaddr() into fatal errors.
- </para>
- </listitem>
- <listitem>
- <para>
- Let enlist_unique_header() verify that the caller didn't pass a header
- containing either \r or \n.
- </para>
- </listitem>
- <listitem>
- <para>
- Change the hashes used in load_config() to unsigned int. That's what
- hash_string() actually returns and using a potentiallly larger type
- is at best useless.
- </para>
- </listitem>
- <listitem>
- <para>
- Use privoxy_tolower() instead of vanilla tolower() with manual casting of
- the argument.
- </para>
- </listitem>
- <listitem>
- <para>
- Catch ssplit() failures in parse_cgi_parameters().
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Regression-Test:
- <itemizedlist>
- <listitem>
- <para>
- Add an 'Overwrite condition' directive to skip any matching tests before
- it. As it has a global scope, using it is more convenient than clowning
- around with the Ignore directive.
- </para>
- </listitem>
- <listitem>
- <para>
- Log to STDOUT instead of STDERR.
- </para>
- </listitem>
- <listitem>
- <para>
- Include the Privoxy version in the output.
- </para>
- </listitem>
- <listitem>
- <para>
- Various grammar and spelling corrections in documentation and code.
- </para>
- </listitem>
- <listitem>
- <para>
- Additional tests for range requests with filtering enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- Tests with mostly invalid range request.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a couple of hide-if-modified-since{} tests with different date formats.
- </para>
- </listitem>
- <listitem>
- <para>
- Cleaned up the format of the regression-tests.action file to match the
- format of default.action.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove the "Copyright" line from print_version(). When using --help, every
- line of screen space matters and thus shouldn't be wasted on things the
- user doesn't care about.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Log-Parser:
- <itemizedlist>
- <listitem>
- <para>
- Improve the --statistics performance by skipping sanity checks for input
- that shouldn't affect the results anyway. Add a --strict-checks option
- that enables some of the checks again, just in case anybody cares.
- </para>
- </listitem>
- <listitem>
- <para>
- The distribution of client requests per connection is included in
- the --statistic output.
- </para>
- </listitem>
- <listitem>
- <para>
- The --accept-unknown-messages option has been removed and the behavior
- is now the default.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and (mostly) highlight new log messages introduced with
- Privoxy 3.0.20.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- uagen:
- <itemizedlist>
- <listitem>
- <para>
- Bump generated Firefox version to 17.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- GNUmakefile improvements:
- <itemizedlist>
- <listitem>
- <para>
- The dok-tidy target no longer taints documents with a tidy-mark
- </para>
- </listitem>
- <listitem>
- <para>
- Change RA_MODE from 0664 to 0644. Suggested by Markus Dittrich in
- #3505445.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove tidy's clean flag as it changes the scope of attributes.
- Link-specific colors end up being applied to all text. Reported by Adam
- Piggott in #3569551.
- </para>
- </listitem>
- <listitem>
- <para>
- Leave it up to the user whether or not smart tags are inserted.
- </para>
- </listitem>
- <listitem>
- <para>
- Let w3m itself do the line wrapping for the config file. It works better
- than fmt as it can honour pre tags causing less unintentional line breaks.
- </para>
- </listitem>
- <listitem>
- <para>
- Ditch a pointless '-r' passed to rm to delete files.
- </para>
- </listitem>
- <listitem>
- <para>
- The config-file target now requires less manual intervention and updates
- the original config.
- </para>
- </listitem>
- <listitem>
- <para>
- Change WDUMP to generate ASCII. Add WDUMP_UTF8 to allow UTF-8 in the
- AUTHORS file so the names are right.
- </para>
- </listitem>
- <listitem>
- <para>
- Stop pretending that lynx and links are supported for the documentation.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- configure improvements:
- <itemizedlist>
- <listitem>
- <para>
- On Haiku, do not pass -lpthread to the compiler. Haiku's pthreads
- implementation is contained in its system library, libroot, so no
- additional library needs to be searched.
- Patch submitted by Simon South in #3564815.
- </para>
- </listitem>
- <listitem>
- <para>
- Additional Haiku-specific improvements. Disable checks intended for
- multi-user systems as Haiku is presently single-user. Group Haiku-specific
- settings in their own section, following the pattern for Solaris, OS/2 and
- AmigaOS. Add additional library-related settings to remove the need for
- providing configure with custom LDFLAGS.
- Submitted by Simon South in #3574538.
- *** Version 3.0.19 Stable ***
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Bug fixes:
- <itemizedlist>
- <listitem>
- <para>
- Prevent a segmentation fault when de-chunking buffered content.
- It could be triggered by malicious web servers if Privoxy was
- configured to filter the content and running on a platform
- where SIZE_T_MAX isn't larger than UINT_MAX, which probably
- includes most 32-bit systems. On those platforms, all Privoxy
- versions before 3.0.19 appear to be affected.
- To be on the safe side, this bug should be presumed to allow
- code execution as proving that it doesn't seems unrealistic.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not expect a response from the SOCKS4/4A server until it
- got something to respond to. This regression was introduced
- in 3.0.18 and prevented the SOCKS4/4A negotiation from working.
- Reported by qqqqqw in #3459781.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- General improvements:
- <itemizedlist>
- <listitem>
- <para>
- Fix an off-by-one in an error message about connect failures.
- </para>
- </listitem>
- <listitem>
- <para>
- Use a GNUMakefile variable for the webserver root directory and
- update the path. Sourceforge changed it which broke various
- web-related targets.
- </para>
- </listitem>
- <listitem>
- <para>
- Update the CODE_STATUS description.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
+</sect3>
+
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-source"><title>Building from Source</title>
+
+<para>
+ The most convenient way to obtain the <application>Privoxy</application> sources
+ is to download the source tarball from our
+ <ulink url="https://sourceforge.net/projects/ijbswa/files/Sources/">project download
+ page</ulink>.
+</para>
+
+<para>
+ If you like to live on the bleeding edge and are not afraid of using
+ possibly unstable development versions, you can check out the up-to-the-minute
+ version directly from <ulink url="https://sourceforge.net/p/ijbswa/code/?source=navbar">the
+ CVS repository</ulink>.
+<!--
+ deprecated...out of business.
+ or simply download <ulink
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">the nightly CVS
+ tarball.</ulink>
+-->
+</para>
+
+<!-- include buildsource.sgml boilerplate: -->
+&buildsource;
+<!-- end boilerplate -->
+
+</sect2>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-keepupdated"><title>Keeping your Installation Up-to-Date</title>
+
+<para>
+ If you wish to receive an email notification whenever we release updates of
+ <application>Privoxy</application> or the actions file, <ulink
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-announce">subscribe
+ to our announce mailing list</ulink>, privoxy-announce@lists.privoxy.org.
+</para>
+
+<para>
+ In order not to lose your personal changes and adjustments when updating
+ to the latest <literal>default.action</literal> file we <emphasis>strongly
+ recommend</emphasis> that you use <literal>user.action</literal> and
+ <literal>user.filter</literal> for your local
+ customizations of <application>Privoxy</application>. See the <link
+ linkend="actions-file">Chapter on actions files</link> for details.
</para>
+</sect2>
+
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="whatsnew">
+<title>What's New in this Release</title>
+
+&changelog;
<!-- ~~~~~ New section ~~~~~ -->
files, thinking you will want to do that yourself.
</para>
</listitem>
- <listitem>
- <para>
- <filename>standard.action</filename> has been merged into
- the <filename>default.action</filename> file.
- </para>
- </listitem>
<listitem>
<para>
In the default configuration only fatal errors are logged now.
</para>
</listitem>
-<!--
- Did anyone test these lately?
- fk 2007-11-10
- <listitem>
- <para>
- For easy access to &my-app;'s most important controls, drag the provided
- <link linkend="bookmarklets">Bookmarklets</link> into your browser's
- personal toolbar.
- </para>
- </listitem>
--->
-
<listitem>
<para>
Please see the section <link linkend="contact">Contacting the
directory. Except on Win32 where it will try <filename>config.txt</filename>.
</para>
-<sect2 id="start-redhat">
-<title>Red Hat and Fedora</title>
+<sect2 id="start-debian">
+<title>Debian</title>
<para>
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file <filename>/etc/privoxy/config</filename> as its main configuration
+ We use a script. Note that Debian typically starts &my-app; upon booting per
+ default. It will use the file
+ <filename>/etc/privoxy/config</filename> as its main configuration
file.
</para>
<para>
<screen>
- # /etc/rc.d/init.d/privoxy start
+ # /etc/init.d/privoxy start
</screen>
</para>
+</sect2>
+
+<sect2 id="start-freebsd">
+<title>FreeBSD and ElectroBSD</title>
<para>
- Or ...
+ To start <application>Privoxy</application> upon booting, add
+ "privoxy_enable='YES'" to <filename>/etc/rc.conf</filename>.
+ <application>Privoxy</application> will use
+ <filename>/usr/local/etc/privoxy/config</filename> as its main
+ configuration file.
</para>
<para>
- <screen>
- # service privoxy start
-</screen>
+ If you installed <application>Privoxy</application> into a jail, the
+ paths above are relative to the jail root.
</para>
-</sect2>
-
-<sect2 id="start-debian">
-<title>Debian</title>
<para>
- We use a script. Note that Debian typically starts &my-app; upon booting per
- default. It will use the file
- <filename>/etc/privoxy/config</filename> as its main configuration
- file.
+ To start <application>Privoxy</application> manually, run:
</para>
<para>
<screen>
- # /etc/init.d/privoxy start
+ # service privoxy onestart
</screen>
</para>
</sect2>
</sect2>
<sect2 id="start-unices">
-<title>Solaris, NetBSD, FreeBSD, HP-UX and others</title>
+<title>Generic instructions for Unix derivates (Solaris, NetBSD, HP-UX etc.)</title>
<para>
Example Unix startup command:
</para>
<para>
<screen>
- # /usr/sbin/privoxy /etc/privoxy/config
+ # /usr/sbin/privoxy --user privoxy /etc/privoxy/config
</screen>
</para>
+<para>
+ Note that if you installed <application>Privoxy</application> through
+ a package manager, the package will probably contain a platform-specific
+ script or configuration file to start <application>Privoxy</application>
+ upon boot.
+</para>
</sect2>
<sect2 id="start-os2">
<sect2 id="start-macosx">
<title>Mac OS X</title>
<para>
- After downloading the privoxy software, unzip the downloaded file by
- double-clicking on the zip file icon. Then, double-click on the
- installer package icon and follow the installation process.
-</para>
-<para>
- The privoxy service will automatically start after a successful
- installation. In addition, the privoxy service will automatically
- start every time your computer starts up.
-</para>
-<para>
- To prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- /Library/StartupItems/Privoxy.
-</para>
-<para>
- A simple application named Privoxy Utility has been created which
- enables administrators to easily start and stop the privoxy service.
-</para>
-<para>
- In addition, the Privoxy Utility presents a simple way for
- administrators to edit the various privoxy config files. A method
- to uninstall the software is also available.
-</para>
-<para>
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
-</para>
-</sect2>
-
-
-<sect2 id="start-amigaos">
-<title>AmigaOS</title>
-<para>
- Start <application>Privoxy</application> (with RUN <>NIL:) in your
- <filename>startnet</filename> script (AmiTCP), in
- <filename>s:user-startup</filename> (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- <application>Privoxy</application> will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- <application>Privoxy</application> is still running).
-</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>
+ The privoxy service will automatically start after a successful installation
+ (and thereafter every time your computer starts up) however you will need to
+ configure your web browser(s) to use it. To do so, configure them to use a
+ proxy for HTTP and HTTPS at the address 127.0.0.1:8118.
</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.
+ To prevent the privoxy service from automatically starting when your computer
+ starts up, remove or rename the file <literal>/Library/LaunchDaemons/org.ijbswa.privoxy.plist</literal>
+ (on OS X 10.5 and higher) or the folder named
+ <literal>/Library/StartupItems/Privoxy</literal> (on OS X 10.4 'Tiger').
</para>
<para>
- <screen>
- rc-update add privoxy default
- </screen>
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
</para>
</sect2>
+
<!--
<para>
<emphasis>--pre-chroot-nslookup hostname</emphasis>
</para>
<para>
- Specifies a hostname to look up before doing a chroot. On some systems, initializing the
- resolver library involves reading config files from /etc and/or loading additional shared
- libraries from /lib. On these systems, doing a hostname lookup before the chroot reduces
+ Specifies a hostname (for example www.privoxy.org) to look up before doing a chroot.
+ On some systems, initializing the resolver library involves reading config files from
+ /etc and/or loading additional shared libraries from /lib.
+ On these systems, doing a hostname lookup before the chroot reduces
the number of files that must be copied into the chroot tree.
</para>
<para>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="control-with-webbrowser">
<title>Controlling Privoxy with Your Web Browser</title>
<para>
<application>Privoxy</application>'s user interface can be reached through the special
</member>
<member>
▪ <ulink
- url="http://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
+ url="https://www.privoxy.org/&p-version;/user-manual/">Documentation</ulink>
</member>
</simplelist>
</msgtext>
it as a test to see whether it is <application>Privoxy</application>
causing the problem or not. <application>Privoxy</application> continues
to run as a proxy in this case, but all manipulation is disabled, i.e.
- <application>Privoxy</application> acts like a normal forwarding proxy. There
- is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
- that you can toggle <application>Privoxy</application> with one click from
- your browser.
+ <application>Privoxy</application> acts like a normal forwarding proxy.
</para>
<para>
</para>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="right-mix">
<title>Finding the Right Mix</title>
<para>
Note that some <link linkend="actions">actions</link>, like cookie suppression
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="how-to-edit">
<title>How to Edit</title>
<para>
The easiest way to edit the actions files is with a browser by
<para>
Generally, an URL pattern has the form
- <literal><domain><port>/<path></literal>, where the
- <literal><domain></literal>, the <literal><port></literal>
+ <literal><host><port>/<path></literal>, where the
+ <literal><host></literal>, the <literal><port></literal>
and the <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>
<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,
+ The pattern matching syntax is different for the host and path parts of
+ the URL. The host part uses a simple globbing type matching technique,
while the path part uses more flexible
<ulink url="http://en.wikipedia.org/wiki/Regular_expressions"><quote>Regular
Expressions</quote></ulink> (POSIX 1003.2).
</para>
<para>
The port part of a pattern is a decimal port number preceded by a colon
- (<literal>:</literal>). If the domain part contains a numerical IPv6 address,
+ (<literal>:</literal>). If the host part contains a numerical IPv6 address,
it has to be put into angle brackets
(<literal><</literal>, <literal>></literal>).
</para>
<term><literal>www.example.com/</literal></term>
<listitem>
<para>
- is a domain-only pattern and will match any request to <literal>www.example.com</literal>,
+ is a host-only pattern and will match any request to <literal>www.example.com</literal>,
regardless of which document on that server is requested. So ALL pages in
this domain would be covered by the scope of this action. Note that a
simple <literal>example.com</literal> is different and would NOT match.
<term><literal>www.example.com</literal></term>
<listitem>
<para>
- means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+ means exactly the same. For host-only patterns, the trailing <literal>/</literal> may
be omitted.
</para>
</listitem>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>10.0.0.1/</literal></term>
+ <listitem>
+ <para>
+ Matches any URL with the host address <literal>10.0.0.1</literal>.
+ (Note that the real URL uses plain brackets, not angle brackets.)
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><literal><2001:db8::1>/</literal></term>
<listitem>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3><title>The Domain Pattern</title>
+<sect3 id="host-pattern"><title>The Host Pattern</title>
<para>
- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
+ The matching of the host part offers some flexible options: if the
+ host pattern starts or ends with a dot, it becomes unanchored at that end.
+ The host pattern is often referred to as domain pattern as it is usually
+ used to match domain names and not IP addresses.
For example:
</para>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3><title>The Path Pattern</title>
+<sect3 id="path-pattern"><title>The Path Pattern</title>
<para>
<application>Privoxy</application> uses <quote>modern</quote> POSIX 1003.2
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="tag-pattern"><title>The Tag Pattern</title>
+<sect3 id="tag-pattern"><title>The Request Tag Pattern</title>
<para>
- Tag patterns are used to change the applying actions based on the
- request's tags. Tags can be created with either the
- <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
+ Request tag patterns are used to change the applying actions based on the
+ request's tags. Tags can be created based on HTTP headers with either
+ the <link linkend="CLIENT-HEADER-TAGGER">client-header-tagger</link>
or the <link linkend="SERVER-HEADER-TAGGER">server-header-tagger</link> action.
</para>
<para>
- Tag patterns have to start with <quote>TAG:</quote>, so &my-app;
- can tell them apart from URL patterns. Everything after the colon
+ Request tag patterns have to start with <quote>TAG:</quote>, so &my-app;
+ can tell them apart from other patterns. Everything after the colon
including white space, is interpreted as a regular expression with
path pattern syntax, except that tag patterns aren't left-anchored
automatically (&my-app; doesn't silently add a <quote>^</quote>,
</para>
<para>
- Sections can contain URL and tag patterns at the same time,
- but tag patterns are checked after the URL patterns and thus
+ Sections can contain URL and request tag patterns at the same time,
+ but request tag patterns are checked after the URL patterns and thus
always overrule them, even if they are located before the URL patterns.
</para>
<para>
- Once a new tag is added, Privoxy checks right away if it's matched by one
- of the tag patterns and updates the action settings accordingly. As a result
- tags can be used to activate other tagger actions, as long as these other
+ Once a new request tag is added, Privoxy checks right away if it's matched by one
+ of the request tag patterns and updates the action settings accordingly. As a result
+ request tags can be used to activate other tagger actions, as long as these other
taggers look for headers that haven't already be parsed.
</para>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="negative-tag-patterns"><title>The Negative Request Tag Patterns</title>
+
+<para>
+ To match requests that do not have a certain request tag, specify a negative tag pattern
+ by prefixing the tag pattern line with either <quote>NO-REQUEST-TAG:</quote>
+ or <quote>NO-RESPONSE-TAG:</quote> instead of <quote>TAG:</quote>.
+</para>
+
+<para>
+ Negative request tag patterns created with <quote>NO-REQUEST-TAG:</quote> are checked
+ after all client headers are scanned, the ones created with <quote>NO-RESPONSE-TAG:</quote>
+ are checked after all server headers are scanned. In both cases all the created
+ tags are considered.
+</para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="client-tag-pattern"><title>The Client Tag Pattern</title>
+
+<!-- XXX: This section contains duplicates content from the
+ client-specific-tag documentation. -->
+
+<warning>
+<para>
+ This is an experimental feature. The syntax is likely to change in future versions.
+</para>
+</warning>
+
+<para>
+ Client tag patterns are not set based on HTTP headers but based on
+ the client's IP address. Users can enable them themselves, but the
+ Privoxy admin controls which tags are available and what their effect
+ is.
+</para>
+
+<para>
+ After a client-specific tag has been defined with the
+ <link linkend="client-specific-tag">client-specific-tag</link>,
+ directive, action sections can be activated based on the tag by using a
+ CLIENT-TAG pattern. The CLIENT-TAG pattern is evaluated at the same priority
+ as URL patterns, as a result the last matching pattern wins. Tags that
+ are created based on client or server headers are evaluated later on
+ and can overrule CLIENT-TAG and URL patterns!
+</para>
+<para>
+ The tag is set for all requests that come from clients that requested
+ it to be set. Note that "clients" are differentiated by IP address,
+ if the IP address changes the tag has to be requested again.
+</para>
+<para>
+ Clients can request tags to be set by using the CGI interface <ulink
+ url="http://config.privoxy.org/client-tags">http://config.privoxy.org/client-tags</ulink>.
+</para>
+
+<para>
+ Example:
+</para>
+
+<para>
+ <screen>
+# If the admin defined the client-specific-tag circumvent-blocks,
+# and the request comes from a client that previously requested
+# the tag to be set, overrule all previous +block actions that
+# are enabled based on URL to CLIENT-TAG patterns.
+{-block}
+CLIENT-TAG:^circumvent-blocks$
+
+# This section is not overruled because it's located after
+# the previous one.
+{+block{Nobody is supposed to request this.}}
+example.org/blocked-example-page</screen>
+</para>
+
</sect2>
<!-- ~ End section ~ -->
<term>Example usage:</term>
<listitem>
<para>
- <screen>+add-header{X-User-Tracking: sucks}</screen>
+ <screen># Add a DNT ("Do not track") header to all requests,
+# event to those that already have one.
+#
+# This is just an example, not a recommendation.
+#
+# There is no reason to believe that user-tracking websites care
+# about the DNT header and depending on the User-Agent, adding the
+# header may make user-tracking easier.
+{+add-header{DNT: 1}}
+/</screen>
</para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="external-filter">
+<title>external-filter</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Modify content using a programming language of your choice.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ All instances of text-based type, most notably HTML and JavaScript, to which
+ this action applies, can be filtered on-the-fly through the specified external
+ filter.
+ By default plain text documents are exempted from filtering, because web
+ servers often use the <literal>text/plain</literal> MIME type for all files
+ whose type they don't know.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Multi-value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of an external content filter, as defined in the
+ <link linkend="filter-file">filter file</link>.
+ External filters can be defined in one or more files as defined by the
+ <literal><link linkend="filterfile">filterfile</link></literal>
+ option in the <link linkend="config">config file</link>.
+ </para>
+ <para>
+ When used in its negative form,
+ and without parameters, <emphasis>all</emphasis> filtering with external
+ filters is completely disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ External filters are scripts or programs that can modify the content in
+ case common <literal><link linkend="filter">filters</link></literal>
+ aren't powerful enough. With the exception that this action doesn't
+ use pcrs-based filters, the notes in the
+ <literal><link linkend="filter">filter</link></literal> section apply.
+ </para>
+ <warning>
+ <para>
+ Currently external filters are executed with &my-app;'s privileges.
+ Only use external filters you understand and trust.
+ </para>
+ </warning>
+ <para>
+ This feature is experimental, the <literal><link
+ linkend="external-filter-syntax">syntax</link></literal>
+ may change in the future.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+external-filter{fancy-filter}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="fast-redirects">
<title>fast-redirects</title>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
</para>
<para>
<anchor id="filter-js-events">
- <screen>+filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
+ <screen>+filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
</para>
<para>
<anchor id="filter-html-annoyances">
</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 if refresh time is larger than 9 seconds.</screen>
</para>
<para>
<anchor id="filter-unsolicited-popups">
- <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</screen>
+ <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows.</screen>
</para>
<para>
<anchor id="filter-all-popups">
- <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</screen>
+ <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML.</screen>
</para>
<para>
<anchor id="filter-img-reorder">
<anchor id="filter-frameset-borders">
<screen>+filter{frameset-borders} # Give frames a border and make them resizable.</screen>
</para>
+ <para>
+ <anchor id="filter-iframes">
+ <screen>+filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites.</screen>
+ </para>
<para>
<anchor id="filter-demoronizer">
<screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</screen>
<term>Type:</term>
<!-- Boolean, Parameterized, Multi-value -->
<listitem>
- <para>Multi-value.</para>
+ <para>Parameterized.</para>
</listitem>
</varlistentry>
for socks5 connections (with remote DNS resolution).
</para>
</listitem>
+ <listitem>
+ <para>
+ <quote>forward-webserver 127.0.0.1:80</quote> to use the HTTP
+ server listening at 127.0.0.1 port 80 without adjusting the
+ request headers.
+ </para>
+ <para>
+ This makes it more convenient to use Privoxy to make
+ existing websites available as onion services as well.
+ </para>
+ <para>
+ Many websites serve content with hardcoded URLs and
+ can't be easily adjusted to change the domain based
+ on the one used by the client.
+ </para>
+ <para>
+ Putting Privoxy between Tor and the webserver (or an stunnel
+ that forwards to the webserver) allows to rewrite headers and
+ content to make client and server happy at the same time.
+ </para>
+ <para>
+ Using Privoxy for webservers that are only reachable through
+ onion addresses and whose location is supposed to be secret
+ is not recommended and should not be necessary anyway.
+ </para>
+ </listitem>
</itemizedlist>
</listitem>
</varlistentry>
<para>
If the ports are missing or invalid, default values will be used. This might change
in the future and you shouldn't rely on it. Otherwise incorrect syntax causes Privoxy
- to exit.
+ to exit. Due to design limitations, invalid parameter syntax isn't detected until the
+ action is used the first time.
</para>
<para>
Use the <ulink url="http://config.privoxy.org/show-url-info">show-url-info CGI page</ulink>
<listitem>
<para>
<screen>
-# Always use direct connections for requests previously tagged as
+# Use an ssh tunnel for requests previously tagged as
# <quote>User-Agent: fetch libfetch/2.0</quote> and make sure
# resuming downloads continues to work.
+#
# This way you can continue to use Tor for your normal browsing,
# without overloading the Tor network with your FreeBSD ports updates
# or downloads of bigger files like ISOs.
+#
# Note that HTTP headers are easy to fake and therefore their
# values are as (un)trustworthy as your clients and users.
-{+forward-override{forward .} \
+{+forward-override{forward-socks5 10.0.0.2:2222 .} \
-hide-if-modified-since \
-overwrite-last-modified \
}
<link linkend="filter-file">filter file</link> section.
</para>
<para>
- This action will be ignored if you use it together with
- <literal><link linkend="block">block</link></literal>.
- It can be combined with
+ Requests can't be blocked and redirected at the same time,
+ applying this action together with
+ <literal><link linkend="block">block</link></literal>
+ is a configuration error. Currently the request is blocked
+ and an error message logged, the behavior may change in the
+ future and result in Privoxy rejecting the action file.
+ </para>
+ <para>
+ This action can be combined with
<literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
to redirect to a decoded version of a rewritten URL.
</para>
example.com/stylesheet\.css
# Create a short, easy to remember nickname for a favorite site
-# (relies on the browser accept and forward invalid URLs to &my-app;)
-{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
+# (relies on the browser to accept and forward invalid URLs to &my-app;)
+{ +redirect{https://www.privoxy.org/user-manual/actions-file.html} }
a
# Always use the expanded view for Undeadly.org articles
{+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}}
search.msn.com//results\.aspx\?q=
+# Redirect http://example.com/&bla=fasel&toChange=foo (and any other value but "bar")
+# to http://example.com/&bla=fasel&toChange=bar
+#
+# The URL pattern makes sure that the following request isn't redirected again.
+{+redirect{s@toChange=[^&]+@toChange=bar@}}
+example.com/.*toChange=(?!bar)
+
+# Add a shortcut to look up illumos bugs
+{+redirect{s@^http://i([0-9]+)/.*@https://www.illumos.org/issues/$1@}}
+# Redirected URL = http://i4974/
+# Redirect Destination = https://www.illumos.org/issues/4974
+i[0-9][0-9][0-9][0-9]*/
+
# Redirect remote requests for this manual
# to the local version delivered by Privoxy
{+redirect{s@^http://www@http://config@}}
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
# Tag every request with the content type declared by the server
{+server-header-tagger{content-type}}
/
+
+# If the response has a tag starting with 'image/' enable an external
+# filter that only applies to images.
+#
+# Note that the filter is not available by default, it's just a
+# <literal><link linkend="external-filter-syntax">silly example</link></literal>.
+{+external-filter{rotate-image} +force-text-mode}
+TAG:^image/
</screen>
</para>
</listitem>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
+<sect3 id="summary">
<title>Summary</title>
<para>
Note that many of these actions have the potential to cause a page to
and <filename>user.action</filename> file and see how all these pieces come together:
</para>
-<sect3>
+<sect3 id="match-all">
<title>match-all.action</title>
<para>
Remember <emphasis>all actions are disabled when matching starts</emphasis>,
</para>
</sect3>
-<sect3>
+<sect3 id="default-action">
<title>default.action</title>
<para>
</sect3>
-<sect3><title>user.action</title>
+<sect3 id="user-action"><title>user.action</title>
<para>
So far we are painting with a broad brush by setting general policies,
</para>
<para>
- &my-app; supports three different filter actions:
+ &my-app; supports three different pcrs-based filter actions:
<literal><link linkend="filter">filter</link></literal> to
rewrite the content that is send to the client,
<literal><link linkend="client-header-filter">client-header-filter</link></literal>
applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
</para>
+<para>
+ Finally &my-app; supports the
+ <literal><link linkend="external-filter">external-filter</link></literal> action
+ to enable <literal><link linkend="external-filter-syntax">external filters</link></literal>
+ written in proper programming languages.
+</para>
+
<para>
Multiple filter files can be defined through the <literal> <link
in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
<literal>s///</literal> operator. If you are familiar with Perl, you
will find this to be quite intuitive, and may want to look at the
- PCRS documentation for the subtle differences to Perl behaviour. Most
- notably, the non-standard option letter <literal>U</literal> is supported,
- which turns the default to ungreedy matching.
+ PCRS documentation for the subtle differences to Perl behaviour.
+</para>
+
+<para>
+ Most notably, the non-standard option letter <literal>U</literal> is supported,
+ which turns the default to ungreedy matching (add <literal>?</literal> to
+ quantifiers to turn them greedy again).
+</para>
+
+<para>
+ The non-standard option letter <literal>D</literal> (dynamic) allows
+ to use the variables $host, $origin (the IP address the request came from),
+ $path, $url and $listen-address (the address on which Privoxy accepted the
+ client request. Example: 127.0.0.1:8118).
+ They will be replaced with the value they refer to before the filter
+ is executed.
+</para>
+
+<para>
+ Note that '$' is a bad choice for a delimiter in a dynamic filter as you
+ might end up with unintended variables if you use a variable name
+ directly after the delimiter. Variables will be resolved without
+ escaping anything, therefore you also have to be careful not to chose
+ delimiters that appear in the replacement text. For example '<' should
+ be save, while '?' will sooner or later cause conflicts with $url.
+</para>
+
+<para>
+ The non-standard option letter <literal>T</literal> (trivial) prevents
+ parsing for backreferences in the substitute. Use it if you want to include
+ text like '$&' in your substitute without quoting.
</para>
<para>
<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
-<sect2><title>Filter File Tutorial</title>
+<sect2 id="filter-file-tut"><title>Filter File Tutorial</title>
<para>
Now, let's complete our <quote>foo</quote> content filter. We have already defined
the heading, but the jobs are still missing. Since all it does is to replace
</variablelist>
</sect2>
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+<sect2 id="external-filter-syntax"><title>External filter syntax</title>
+<para>
+ External filters are scripts or programs that can modify the content in
+ case common <literal><link linkend="filter">filters</link></literal>
+ aren't powerful enough.
+</para>
+<para>
+ External filters can be written in any language the platform &my-app; runs
+ on supports.
+</para>
+<para>
+ They are controlled with the
+ <literal><link linkend="external-filter">external-filter</link></literal> action
+ and have to be defined in the <literal><link linkend="filterfile">filterfile</link></literal>
+ first.
+</para>
+<para>
+ The header looks like any other filter, but instead of pcrs jobs, external
+ filters contain a single job which can be a program or a shell script (which
+ may call other scripts or programs).
+</para>
+<para>
+ External filters read the content from STDIN and write the rewritten
+ content to STDOUT.
+ The environment variables PRIVOXY_URL, PRIVOXY_PATH, PRIVOXY_HOST,
+ PRIVOXY_ORIGIN, PRIVOXY_LISTEN_ADDRESS can be used to get some details
+ about the client request.
+</para>
+<para>
+ &my-app; will temporary store the content to filter in the
+ <literal><link linkend="temporary-directory">temporary-directory</link></literal>.
+</para>
+<para>
+ <screen>
+EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
+/bin/cat
+
+# Incorrect reimplementation of the filter above in POSIX shell.
+#
+# Note that it's a single job that spans multiple lines, the line
+# breaks are not passed to the shell, thus the semicolons are required.
+#
+# If the script isn't trivial, it is recommended to put it into an external file.
+#
+# In general, writing external filters entirely in POSIX shell is not
+# considered a good idea.
+EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
+while read line; \
+do \
+ echo "$line"; \
+done
+
+EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value.
+/usr/local/bin/convert - -rotate 180 -
+
+EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment.
+/usr/local/bin/convert - -pointsize 16 -fill white -annotate +17+418 "[citation needed]" -
+</screen>
+</para>
+
+<warning>
+ <para>
+ Currently external filters are executed with &my-app;'s privileges!
+ Only use external filters you understand and trust.
+ </para>
+</warning>
+<para>
+ External filters are experimental and the syntax may change in the future.
+</para>
+</sect2>
+
</sect1>
<!-- ~ End section ~ -->
©right;
<!-- end copyright -->
+<para>
+ <application>Privoxy</application> is free software; you can
+ redistribute it and/or modify it under the terms of the
+ <citetitle>GNU General Public License</citetitle>, version 2,
+ as published by the Free Software Foundation and included in
+ the next section.
+</para>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect2><title>License</title>
-<!-- Include copyright.sgml: -->
- &license;
-<!-- end copyright -->
+<sect2 id="license"><title>License</title>
+<para>
+ <screen><![ RCDATA [ &GPLv2; ]]></screen>
+</para>
+
</sect2>
<!-- ~ End section ~ -->
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="internal-pages">
<title>Privoxy's Internal Pages</title>
<para>
</itemizedlist>
</para>
-<para>
- These may be bookmarked for quick reference. See next.
-
-</para>
-
-<sect3 id="bookmarklets">
-<title>Bookmarklets</title>
-<para>
- 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>
- (IE) or <quote>Add Bookmark</quote> (Netscape). You will get a warning that
- the bookmark <quote>may not be safe</quote> - just click OK. Then you can run the
- Bookmarklet directly from your favorites/bookmarks. For even faster access,
- you can put them on the <quote>Links</quote> bar (IE) or the <quote>Personal
- Toolbar</quote> (Netscape), and run them with a single click.
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- <ulink
- url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=enabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Enable</ulink>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <ulink
- url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=disabled','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Disable</ulink>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <ulink
- url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y&set=toggle','ijbstatus','width=250,height=100,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Toggle Privoxy</ulink> (Toggles between enabled and disabled)
- </para>
- </listitem>
-
- <listitem>
- <para>
- <ulink
- url="javascript:void(window.open('http://config.privoxy.org/toggle?mini=y','ijbstatus','width=250,height=2,resizable=yes,scrollbars=no,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy- View Status</ulink>
- </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/index.php?url='+escape(location.href),'Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">Privoxy - Submit Actions File Feedback</ulink>
- </para>
- </listitem>
- -->
- <listitem>
- <para>
- <ulink url="javascript:void(window.open('http://config.privoxy.org/show-url-info?url='+escape(location.href),'Why').focus());">Privoxy - Why?</ulink>
- </para>
- </listitem>
- </itemizedlist>
-</para>
-
-<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
- have more information about bookmarklets.
-</para>
-
-
-</sect3>
-
</sect2>
<para>
One quick test to see if <application>Privoxy</application> is causing a problem
or not, is to disable it temporarily. This should be the first troubleshooting
- step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick
- and easy way to do this (be sure to flush caches afterward!). Looking at the
+ step (be sure to flush caches afterward!). Looking at the
logs is a good idea too. (Note that both the toggle feature and logging are
enabled via <filename>config</filename> file settings, and may need to be
turned <quote>on</quote>.)
projects / privoxy.git / blobdiff