<!entity license SYSTEM "license.sgml">
<!entity p-authors SYSTEM "p-authors.sgml">
<!entity config SYSTEM "p-config.sgml">
-<!entity p-version "3.0.18">
-<!entity p-status "stable">
+<!entity p-version "3.0.20">
+<!entity p-status "UNRELEASED">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
-<!entity % p-not-stable "IGNORE">
-<!entity % p-stable "INCLUDE">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
<!entity % p-readme "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.141 2011/11/20 12:41:22 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.153 2012/11/09 10:49:59 fabiankeil Exp $
Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
See LICENSE.
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.141 2011/11/20 12:41:22 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.153 2012/11/09 10:49:59 fabiankeil Exp $</pubdate>
<!--
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-mac"><title>Mac OS X</title>
<para>
- Unzip the downloaded file (you can either double-click on the zip file
- icon from the Finder, or from the desktop if you downloaded it there).
- Then, double-click on the package installer icon and follow the
- installation process.
+ Installation instructions for the OS X platform depend upon whether
+ you downloaded a ready-built installation package (.pkg or .mpkg) or have
+ downloaded the source code.
</para>
+<sect3 renderas="sect4" id="OS-X-install-from-package">
+<title>Installation from ready-built package</title>
<para>
- The privoxy service will automatically start after a successful
- installation (in addition to every time your computer starts up). To
- prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- <literal>/Library/StartupItems/Privoxy</literal>.
+ The downloaded file will either be a .pkg (for OS X 10.5 upwards) or a bzipped
+ .mpkg file (for OS X 10.4). The former can be double-clicked as is and the
+ installation will start; double-clicking the latter will unzip the .mpkg file
+ which can then be double-clicked to commence the installation.
+</para>
+<para>
+ 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>
+ 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>
+ 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>
+<para>
+ To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
+ administrator account.
+</para>
+<sect3 renderas="sect4" id="OS-X-install-from-source">
+<title>Installation from source</title>
+<para>
+ To build and install the Privoxy source code on OS X you will need to obtain
+ the macsetup module from the Privoxy Sourceforge CVS repository (refer to
+ Sourceforge help for details of how to set up a CVS client to have read-only
+ access to the repository). This module contains scripts that leverage the usual
+ open-source tools (available as part of Apple's free of charge Xcode
+ distribution or via the usual open-source software package managers for OS X
+ (MacPorts, Homebrew, Fink etc.) to build and then install the privoxy binary
+ and associated files. The macsetup module's README file contains complete
+ instructions for its use.
+</para>
+<para>
+ 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>
+ 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>
To manually start or stop the privoxy service, use the Privoxy Utility
- for Mac OS X. This application controls the privoxy service (e.g.
- starting and stopping the service as well as uninstalling the software).
+ for Mac OS X (also part of the macsetup module). This application can start
+ and stop the privoxy service and display its log and configuration files.
+</para>
+<para>
+ To uninstall, run the macsetup module's uninstall.sh as sudo from an
+ administrator account.
</para>
</sect3>
<sect1 id="whatsnew">
<title>What's New in this Release</title>
<para>
- <application>Privoxy 3.0.18</application> is a stable release.
- The changes since 3.0.17 stable are:
+ <application>Privoxy 3.0.19</application> is a stable release.
+ The changes since 3.0.18 stable are:
</para>
<para>
<itemizedlist>
<listitem>
<para>
- If the redirect URL contains characters RFC 3986 doesn't permit,
- they are (re)encoded. Not doing this makes Privoxy versions from
- 3.0.5 to 3.0.17 susceptible to HTTP response splitting (CWE-113)
+ 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>
+</para>
+
+<para>
+ The following changes were made between 3.0.17 and 3.0.18:
+</para>
+
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Bug fixes:
+ <itemizedlist>
+ <listitem>
+ <para>
+ If a generated redirect URL contains characters RFC 3986 doesn't
+ permit, they are (re)encoded. Not doing this makes Privoxy versions
+ from 3.0.5 to 3.0.17 susceptible to HTTP response splitting (CWE-113)
attacks if the +fast-redirects{check-decoded-url} action is used.
</para>
</listitem>
<listitem>
<para>
Fix a subtle race condition between prepare_csp_for_next_request()
- and sweep() A thread preparing itself for the next client request
+ and sweep(). A thread preparing itself for the next client request
could briefly appear to be inactive.
If all other threads were already using more recent files,
the thread could get its files swept away under its feet.
</listitem>
<listitem>
<para>
- Fixed a small memory leak when retrying connections with IPv6 support
- enabled.
+ Fixed a small memory leak when retrying connections with IPv6
+ support enabled.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Set socket_error to errno if connecting fails in rfc2553_connect_to()
+ Set socket_error to errno if connecting fails in rfc2553_connect_to().
Previously rejected direct connections could be incorrectly reported
as DNS issues if Privoxy was compiled with IPv6 support.
</para>
</listitem>
<listitem>
<para>
- Simplify the signal setup in main()
+ Simplify the signal setup in main().
</para>
</listitem>
<listitem>
<para>
- Streamline socks5_connect() slightly
+ Streamline socks5_connect() slightly.
</para>
</listitem>
<listitem>
<para>
- In socks5_connect(), require a complete socks response from the server
+ In socks5_connect(), require a complete socks response from the server.
Previously Privoxy didn't care how much data the server response
contained as long as the first two bytes contained the expected
values. While at it, shrink the buffer size so Privoxy can't read
</listitem>
<listitem>
<para>
- In rfc2553_connect_to(), start setting cgi->error_message on error
+ In rfc2553_connect_to(), start setting cgi->error_message on error.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Don't enforce a logical line length limit in read_config_line()
+ Don't enforce a logical line length limit in read_config_line().
</para>
</listitem>
<listitem>
<para>
- Slightly refactor server_last_modified() to remove useless gmtime*() calls
+ Slightly refactor server_last_modified() to remove useless gmtime*() calls.
</para>
</listitem>
<listitem>
<para>
- In get_content_type(), also recognize '.jpeg' as JPEG extension
+ In get_content_type(), also recognize '.jpeg' as JPEG extension.
</para>
</listitem>
<listitem>
<para>
- Add '.png' to the list of recognized file extensions in get_content_type()
+ Add '.png' to the list of recognized file extensions in get_content_type().
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Remove -prevent-compression from the fragile alias It's no longer
+ Remove -prevent-compression from the fragile alias. It's no longer
used anywhere by default and isn't known to break stuff anyway.
</para>
</listitem>
<listitem>
<para>
- Add a (disabled) section to block various Facebook tracking URLs
+ Add a (disabled) section to block various Facebook tracking URLs.
Reported by Dan Stahlke in #3421764.
</para>
</listitem>
<listitem>
<para>
Add a (disabled) section to rewrite and redirect click-tracking
- URLs used on news.google.com
+ URLs used on news.google.com.
Reported by Dan Stahlke in #3421755.
</para>
</listitem>
<listitem>
<para>
- Unblock linuxcounter.net/
+ Unblock linuxcounter.net/.
Reported by Dan Stahlke in #3422612.
</para>
</listitem>
</listitem>
<listitem>
<para>
- Unblock and fast-redirect ".awin1.com/.*=http://"
+ Unblock and fast-redirect ".awin1.com/.*=http://".
Reported by Adam Piggott in #3170921.
</para>
</listitem>
</listitem>
<listitem>
<para>
- Disable banners-by-size filters for '.thinkgeek.com/'
+ Disable banners-by-size filters for '.thinkgeek.com/'.
The filter only seems to catch pictures of the inventory.
</para>
</listitem>
<listitem>
<para>
- Block requests for 'go.idmnet.bbelements.com/please/showit/'
+ Block requests for 'go.idmnet.bbelements.com/please/showit/'.
Reported by kacperdominik in #3372959.
</para>
</listitem>
<listitem>
<para>
- Unblock adainitiative.org/
+ Unblock adainitiative.org/.
</para>
</listitem>
<listitem>
<para>
- Add a fast-redirects exception for '.googleusercontent.com/.*=cache'
+ Add a fast-redirects exception for '.googleusercontent.com/.*=cache'.
</para>
</listitem>
<listitem>
<para>
- Add a fast-redirects exception for webcache.googleusercontent.com/
+ Add a fast-redirects exception for webcache.googleusercontent.com/.
</para>
</listitem>
<listitem>
<para>
- Unblock http://adassier.wordpress.com/ and http://adassier.files.wordpress.com/
+ Unblock http://adassier.wordpress.com/ and http://adassier.files.wordpress.com/.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
- Let the yahoo filter hide '.ads'
+ Let the yahoo filter hide '.ads'.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Let the js-events filter additionally disarm setInterval()
+ Let the js-events filter additionally disarm setInterval().
Suggested by dg1727 in #3423775.
</para>
</listitem>
<itemizedlist>
<listitem>
<para>
- Clarify the effect of compiling Privoxy with zlib support
+ Clarify the effect of compiling Privoxy with zlib support.
Suggested by dg1727 in #3423782.
</para>
</listitem>
</listitem>
<listitem>
<para>
- Remove a superfluous log message in forget_connection()
+ Remove a superfluous log message in forget_connection().
</para>
</listitem>
<listitem>
<para>
In chat(), properly report missing server responses as such
- instead of calling them empty
+ instead of calling them empty.
</para>
</listitem>
<listitem>
<para>
- In forwarded_connect(), fix a log message nobody should ever see
+ In forwarded_connect(), fix a log message nobody should ever see.
</para>
</listitem>
<listitem>
<para>
Fix a log message in socks5_connect(), a failed write operation
- was logged as failed read operation
+ was logged as failed read operation.
</para>
</listitem>
<listitem>
<para>
Let load_one_actions_file() properly complain about a missing
- '{' at the beginning of the file
+ '{' at the beginning of the file.
Simply stating that a line is invalid isn't particularly helpful.
</para>
</listitem>
<listitem>
<para>
Prevent a duplicated LOG_LEVEL_CLF message when sending out
- the "no-server-data" response
+ the "no-server-data" response.
</para>
</listitem>
<listitem>
<listitem>
<para>
Prevent a duplicated log message if none of the resolved IP
- addresses were reachable
+ addresses were reachable.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Remove a useless log message in chat()
+ Remove a useless log message in chat().
</para>
</listitem>
<listitem>
<para>
When retrying to connect, also log the maximum number of connection
- attempts
+ attempts.
</para>
</listitem>
<listitem>
<listitem>
<para>
In compile_dynamic_pcrs_job_list(), also log the actual error code as
- pcrs_strerror() doesn't handle all errors reported by pcre
+ pcrs_strerror() doesn't handle all errors reported by pcre.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Make two fatal error message in load_one_actions_file() more descriptive
+ Make two fatal error message in load_one_actions_file() more descriptive.
</para>
</listitem>
<listitem>
<para>
- In cgi_send_user_manual(), log when rejecting a file name due to '/' or '..'
+ In cgi_send_user_manual(), log when rejecting a file name due to '/' or '..'.
</para>
</listitem>
<listitem>
<para>
- In load_file(), log a message if opening a file failed
+ In load_file(), log a message if opening a file failed.
The CGI error message alone isn't too helpful.
</para>
</listitem>
</listitem>
<listitem>
<para>
- Added a --local-test-file option that allows to use Privoxy-Regression-Test without Privoxy
+ Added a --local-test-file option that allows to use Privoxy-Regression-Test without Privoxy.
</para>
</listitem>
<listitem>
<para>
- Added tests for missing socks4 and socks4a forwarders
+ Added tests for missing socks4 and socks4a forwarders.
</para>
</listitem>
<listitem>
<para>
- The --privoxy-address option now works with IPv6 addresses containing brackets, too
+ The --privoxy-address option now works with IPv6 addresses containing brackets, too.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Disable the range-requests tagger for tests that break if it's enabled
+ Disable the range-requests tagger for tests that break if it's enabled.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- Accept log messages with ISO 8601 time stamps, too
+ Accept log messages with ISO 8601 time stamps, too.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
- Bump generated Firefox version to 8.0
+ Bump generated Firefox version to 8.0.
</para>
</listitem>
<listitem>
<para>
<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>--config-test</emphasis>
+ </para>
+ <para>
+ Exit after loading the configuration files before binding to
+ the listen address. The exit code signals whether or not the
+ configuration files have been successfully loaded.
+ </para>
+ <para>
+ If the exit code is 1, at least one of the configuration files
+ is invalid, if it is 0, all the configuration files have been
+ successfully loaded (but may still contain errors that can
+ currently only be detected at run time).
+ </para>
+ <para>
+ This option doesn't affect the log setting, combination with
+ <emphasis>--no-daemon</emphasis> is recommended if a configured
+ log file shouldn't be used.
+ </para>
+ </listitem>
<listitem>
<para>
<emphasis>--version</emphasis>
and use their output as input.
</para>
<para>
- If the request URL gets changed, &my-app; will detect that and use the new
+ If the request URI gets changed, &my-app; will detect that and use the new
one. This can be used to rewrite the request destination behind the client's
back, for example to specify a Tor exit relay for certain requests.
</para>
{+client-header-filter{hide-tor-exit-notation}}
/
</screen>
- </para>
+ </para>
</listitem>
</varlistentry>
TAG:^User-Agent: Ubuntu APT-HTTP/
TAG:^User-Agent: MPlayer/
</screen>
+ </para>
+ <para>
+ <screen>
+# Tag all requests with the Range header set
+{+client-header-tagger{range-requests}}
+/
+
+# Disable filtering for the tagged requests.
+#
+# With filtering enabled Privoxy would remove the Range headers
+# to be able to filter the whole response. The downside is that
+# it prevents clients from resuming downloads or skipping over
+# parts of multimedia files.
+{-filter -deanimate-gifs}
+TAG:^RANGE-REQUEST$
+ </screen>
</para>
</listitem>
</varlistentry>
<para>
This is a left-over from the time when <application>Privoxy</application>
didn't support important HTTP/1.1 features well. It is left here for the
- unlikely case that you experience HTTP/1.1 related problems with some server
- out there. Not all HTTP/1.1 features and requirements are supported yet,
- so there is a chance you might need this action.
+ unlikely case that you experience HTTP/1.1-related problems with some server
+ out there.
+ </para>
+ <para>
+ Note that enabling this action is only a workaround. It should not
+ be enabled for sites that work without it. While it shouldn't break
+ any pages, it has an (usually negative) performance impact.
+ </para>
+ <para>
+ If you come across a site where enabling this action helps, please report it,
+ so the cause of the problem can be analyzed. If the problem turns out to be
+ caused by a bug in <application>Privoxy</application> it should be
+ fixed so the following release works without the work around.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="limit-cookie-lifetime">
+<title>limit-cookie-lifetime</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Limit the lifetime of HTTP cookies to a couple of minutes or hours.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Overwrites the expires field in Set-Cookie server headers if it's above the specified limit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The lifetime limit in minutes, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action reduces the lifetime of HTTP cookies coming from the
+ server to the specified number of minutes, starting from the time
+ the cookie passes Privoxy.
+ </para>
+ <para>
+ Cookies with a lifetime below the limit are not modified.
+ The lifetime of session cookies is set to the specified limit.
+ </para>
+ <para>
+ The effect of this action depends on the server.
+ </para>
+ <para>
+ In case of servers which refresh their cookies with each response
+ (or at least frequently), the lifetime limit set by this action
+ is updated as well.
+ Thus, a session associated with the cookie continues to work with
+ this action enabled, as long as a new request is made before the
+ last limit set is reached.
+ </para>
+ <para>
+ However, some servers send their cookies once, with a lifetime of several
+ years (the year 2037 is a popular choice), and do not refresh them
+ until a certain event in the future, for example the user logging out.
+ In this case this action may limit the absolute lifetime of the session,
+ even if requests are made frequently.
+ </para>
+ <para>
+ If the parameter is <quote>0</quote>, this action behaves like
+ <literal><link linkend="session-cookies-only">session-cookies-only</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usages:</term>
+ <listitem>
+ <para>
+ <screen>+limit-cookie-lifetime{60}
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="prevent-compression">
<title>prevent-compression</title>
either provided as parameter, or derived by applying a
single pcrs command to the original URL.
</para>
+ <para>
+ The syntax for pcrs commands is documented in the
+ <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>.
</varlistentry>
<varlistentry>
- <term><emphasis>refresh tags</emphasis></term>
+ <term><emphasis>refresh-tags</emphasis></term>
<listitem>
<para>
Disable any refresh tags if the interval is greater than nine seconds (so
USA
$Log: user-manual.sgml,v $
+ Revision 2.153 2012/11/09 10:49:59 fabiankeil
+ Document --config-test option
+
+ Revision 2.152 2012/10/29 12:02:55 fabiankeil
+ Clarify that the destination-change detection works for intercepted requests as well
+
+ For some values of "clarify".
+
+ Revision 2.151 2012/10/21 12:31:59 fabiankeil
+ In the redirect{} section, refer pcrs newbies to the 'filter file' section
+
+ Revision 2.150 2012/09/26 15:20:54 fabiankeil
+ Spell 'refresh-tags' correctly
+
+ Reported by Don in #3571927.
+
+ Revision 2.149 2012/04/22 12:15:53 fabiankeil
+ Use another client-header-tagger{} example: disable filtering for range requests
+
+ Revision 2.148 2012/03/18 15:41:49 fabiankeil
+ Bump entities to 3.0.20 UNRELEASED
+
+ Revision 2.147 2012/03/11 19:03:42 diem
+ Updated user manual to refer to both packaged and source install options for OS X
+
+ Revision 2.146 2011/12/26 17:05:40 fabiankeil
+ Bump entities for 3.0.19
+
+ Revision 2.145 2011/12/26 17:04:19 fabiankeil
+ Import ChangeLog entries for 3.0.19, keeping the ones for 3.0.18 for now
+
+ Revision 2.144 2011/12/26 17:01:29 fabiankeil
+ Try to be less misleading in the downgrade-http-version description
+
+ Revision 2.143 2011/11/20 17:16:36 fabiankeil
+ Last minute ChangeLog changes that didn't make it into the tarball
+
+ Revision 2.142 2011/11/20 12:43:38 fabiankeil
+ Update ChangeLog. Once more, with feeling.
+
Revision 2.141 2011/11/20 12:41:22 fabiankeil
Document the +fast-redirects{} HTTP response splitting fix
projects / privoxy.git / blobdiff