<!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 p-status "beta">
+<!entity changelog SYSTEM "changelog.sgml">
+<!entity p-version "3.0.28">
+<!entity p-status "stable">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
-<!entity % p-not-stable "INCLUDE">
-<!entity % p-stable "IGNORE">
+<!entity % p-not-stable "IGNORE">
+<!entity % p-stable "INCLUDE">
<!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">
<!entity my-app "<application>Privoxy</application>">
]>
<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/user-manual.sgml,v $
+ File : doc/source/user-manual.sgml
Purpose : user manual
- This file belongs into
- ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.160 2013/01/12 12:20:29 fabiankeil Exp $
-
- Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2018 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-2018 by
+ <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.160 2013/01/12 12:20:29 fabiankeil Exp $</pubdate>
-
<!--
Note: the following should generate a separate page, and a live link to it,
<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
<para>
Since this is a &p-status; version, not all new features are well tested. This
documentation may be slightly out of sync as a result (especially with
- CVS sources). And there <emphasis>may be</emphasis> bugs, though hopefully
+ <ulink url="https://www.privoxy.org/gitweb/?p=privoxy.git;a=summary">git sources</ulink>).
+ And there <emphasis>may be</emphasis> bugs, though hopefully
not many!
</para>
]]>
<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>
system. Check that no <application>Junkbuster</application>
or <application>Privoxy</application> objects are in
your startup folder.
-
</para>
<para>
</para>
<para>
To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
- administrator account.
-</para>
-</sect3>
-<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 (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>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-tbz"><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.19</application> is a stable release.
- The changes since 3.0.18 stable are:
-</para>
-
-<para>
- <itemizedlist>
- <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>
-</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 logic bug that could cause Privoxy to reuse a server
- socket after it got tainted by a server-header-tagger-induced
- block that was triggered before the whole server response had
- been read. If keep-alive was enabled and the request following
- the blocked one was to the same host and using the same forwarding
- settings, Privoxy would send it on the tainted server socket.
- While the server would simply treat it as a pipelined request,
- Privoxy would later on fail to properly parse the server's
- response as it would try to parse the unread data from the
- first response as server headers for the second one.
- Regression introduced in 3.0.17.
- </para>
- </listitem>
- <listitem>
- <para>
- When implying keep-alive in client_connection(), remember that
- the client didn't. Fixes a regression introduced in 3.0.13 that
- would cause Privoxy to wait for additional client requests after
- receiving a HTTP/1.1 request with "Connection: close" set
- and connection sharing enabled.
- With clients which terminates the client connection after detecting
- that the whole body has been received it doesn't really matter,
- but with clients that don't the connection would be kept open until
- it timed out.
- </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
- 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.
- So far this has only been reproduced while stress testing in
- valgrind while touching action files in a loop. It's unlikely
- to have caused any actual problems in the real world.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable filters if SDCH compression is used unless filtering is forced.
- If SDCH was combined with a supported compression algorithm, Privoxy
- previously could try to decompress it and ditch the Content-Encoding
- header even though the SDCH compression wasn't dealt with.
- Reported by zebul666 in #3225863.
- </para>
- </listitem>
- <listitem>
- <para>
- Make a copy of the --user value and only mess with that when splitting
- user and group. On some operating systems modifying the value directly
- is reflected in the output of ps and friends and can be misleading.
- Reported by zepard in #3292710.
- </para>
- </listitem>
- <listitem>
- <para>
- If forwarded-connect-retries is set, only retry if Privoxy is actually
- forwarding the request. Previously direct connections would be retried
- as well.
- </para>
- </listitem>
- <listitem>
- <para>
- Fixed a small memory leak when retrying connections with IPv6
- support enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove an incorrect assertion in compile_dynamic_pcrs_job_list()
- It could be triggered by a pcrs job with an invalid pcre
- pattern (for example one that contains a lone quantifier).
- </para>
- </listitem>
- <listitem>
- <para>
- If the --user argument user[.group] contains a dot, always bail out
- if no group has been specified. Previously the intended, but undocumented
- (and apparently untested), behaviour was to try interpreting the whole
- argument as user name, but the detection was flawed and checked for '0'
- instead of '\0', thus merely preventing group names beginning with a zero.
- </para>
- </listitem>
- <listitem>
- <para>
- In html_code_map[], use a numeric character reference instead of '
- which wasn't standardized before XHTML 1.0.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix an invalid free when compiled with FEATURE_GRACEFUL_TERMINATION
- and shut down through http://config.privoxy.org/die
- </para>
- </listitem>
- <listitem>
- <para>
- In get_actions(), fix the "temporary" backwards compatibility hack
- to accept block actions without reason.
- It also covered other actions that should be rejected as invalid.
- Reported by Billy Crook.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- General improvements:
- <itemizedlist>
- <listitem>
- <para>
- Privoxy can (re)compress buffered content before delivering
- it to the client. Disabled by default as most users wouldn't
- benefit from it.
- </para>
- </listitem>
- <listitem>
- <para>
- The +fast-redirects{check-decoded-url} action checks URL
- segments separately. If there are other parameters behind
- the redirect URL, this makes it unnecessary to cut them off
- by additionally using a +redirect{} pcrs command.
- Initial patch submitted by Jamie Zawinski in #3429848.
- </para>
- </listitem>
- <listitem>
- <para>
- When loading action sections, verify that the referenced filters
- exist. Currently missing filters only result in an error message,
- but eventually the severity will be upgraded to fatal.
- </para>
- </listitem>
- <listitem>
- <para>
- Allow to bind to multiple separate addresses.
- Patch set submitted by Petr Pisar in #3354485.
- </para>
- </listitem>
- <listitem>
- <para>
- 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>
- Adjust url_code_map[] so spaces are replaced with %20 instead of '+'
- While '+' can be used by client's submitting form data, this is not
- actually what Privoxy is using the lookups for. This is more of a
- cosmetic issue and doesn't fix any known problems.
- </para>
- </listitem>
- <listitem>
- <para>
- When compiled without FEATURE_FAST_REDIRECTS, do not silently
- ignore +fast-redirect{} directives
- </para>
- </listitem>
- <listitem>
- <para>
- Added a workaround for GNU libc's strptime() reporting negative
- year values when the parsed year is only specified with two digits.
- On affected systems cookies with such a date would not be turned
- into session cookies by the +session-cookies-only action.
- Reported by Vaeinoe in #3403560
- </para>
- </listitem>
- <listitem>
- <para>
- Fixed bind failures with certain GNU libc versions if no non-loopback
- IP address has been configured on the system. This is mainly an issue
- if the system is using DHCP and Privoxy is started before the network
- is completely configured.
- Reported by Raphael Marichez in #3349356.
- Additional insight from Petr Pisar.
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy log messages now use the ISO 8601 date format %Y-%m-%d.
- It's only slightly longer than the old format, but contains
- the full date including the year and allows sorting by date
- (when grepping in multiple log files) without hassle.
- </para>
- </listitem>
- <listitem>
- <para>
- In get_last_url(), do not bother trying to decode URLs that do
- not contain at least one '%' sign. It reduces the log noise and
- a number of unnecessary memory allocations.
- </para>
- </listitem>
- <listitem>
- <para>
- In case of SOCKS5 failures, dump the socks response in the log message.
- </para>
- </listitem>
- <listitem>
- <para>
- Simplify the signal setup in main().
- </para>
- </listitem>
- <listitem>
- <para>
- Streamline socks5_connect() slightly.
- </para>
- </listitem>
- <listitem>
- <para>
- 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
- more than a whole socks response.
- </para>
- </listitem>
- <listitem>
- <para>
- In chat(), do not bother to generate a client request in case of
- direct CONNECT requests. It will not be used anyway.
- </para>
- </listitem>
- <listitem>
- <para>
- Reduce server_last_modified()'s stack size.
- </para>
- </listitem>
- <listitem>
- <para>
- Shorten get_http_time() by using strftime().
- </para>
- </listitem>
- <listitem>
- <para>
- Constify the known_http_methods pointers in unknown_method().
- </para>
- </listitem>
- <listitem>
- <para>
- Constify the time_formats pointers in parse_header_time().
- </para>
- </listitem>
- <listitem>
- <para>
- Constify the formerly_valid_actions pointers in action_used_to_be_valid().
- </para>
- </listitem>
- <listitem>
- <para>
- Introduce a GNUMakefile MAN_PAGE variable that defaults to privoxy.1.
- The Debian package uses section 8 for the man page and this
- should simplify the patch.
- </para>
- </listitem>
- <listitem>
- <para>
- Deduplicate the INADDR_NONE definition for Solaris by moving it to jbsockets.h
- </para>
- </listitem>
- <listitem>
- <para>
- In block_url(), ditch the obsolete workaround for ancient Netscape versions
- that supposedly couldn't properly deal with status code 403.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a useless NULL pointer check in load_trustfile().
- </para>
- </listitem>
- <listitem>
- <para>
- Remove two useless NULL pointer checks in load_one_re_filterfile().
- </para>
- </listitem>
- <listitem>
- <para>
- Change url_code_map[] from an array of pointers to an array of arrays
- It removes an unnecessary layer of indirection and on 64bit system reduces
- the size of the binary a bit.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix various typos. Fixes taken from Debian's 29_typos.dpatch by Roland Rosenfeld.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a dok-tidy GNUMakefile target to clean up the messy HTML
- generated by the other dok targets.
- </para>
- </listitem>
- <listitem>
- <para>
- GNUisms in the GNUMakefile have been removed.
- </para>
- </listitem>
- <listitem>
- <para>
- Change the HTTP version in static responses to 1.1
- </para>
- </listitem>
- <listitem>
- <para>
- Synced config.sub and config.guess with upstream
- 2011-11-11/386c7218162c145f5f9e1ff7f558a3fbb66c37c5.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a dedicated function to parse the values of toggles. Reduces duplicated
- code in load_config() and provides better error handling. Invalid or missing
- toggle values are now a fatal error instead of being silently ignored.
- </para>
- </listitem>
- <listitem>
- <para>
- Terminate HTML lines in static error messages with \n instead of \r\n.
- </para>
- </listitem>
- <listitem>
- <para>
- Simplify cgi_error_unknown() a bit.
- </para>
- </listitem>
- <listitem>
- <para>
- In LogPutString(), don't bother looking at pszText when not
- actually logging anything.
- </para>
- </listitem>
- <listitem>
- <para>
- Change ssplit()'s fourth parameter from int to size_t.
- Fixes a clang complaint.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a warning that the statistics currently can't be trusted.
- Mention Privoxy-Log-Parser's --statistics option as
- an alternative for the time being.
- </para>
- </listitem>
- <listitem>
- <para>
- In rfc2553_connect_to(), start setting cgi->error_message on error.
- </para>
- </listitem>
- <listitem>
- <para>
- Change the expected status code returned for http://p.p/die depending
- on whether or not FEATURE_GRACEFUL_TERMINATION is available.
- </para>
- </listitem>
- <listitem>
- <para>
- In cgi_die(), mark the client connection for closing.
- If the client will fetch the style sheet through another connection
- it gets the main thread out of the accept() state and should thus
- trigger the actual shutdown.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a proper CGI message for cgi_die().
- </para>
- </listitem>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- <listitem>
- <para>
- 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().
- </para>
- </listitem>
- <listitem>
- <para>
- In block_url(), consistently use the block reason "Request blocked by Privoxy"
- In two places the reason was "Request for blocked URL" which hides the
- fact that the request got blocked by Privoxy and isn't necessarily
- correct as the block may be due to tags.
- </para>
- </listitem>
- <listitem>
- <para>
- In listen_loop(), reload the configuration files after accepting
- a new connection instead of before.
- Previously the first connection that arrived after a configuration
- change would still be handled with the old configuration.
- </para>
- </listitem>
- <listitem>
- <para>
- In chat()'s receive-data loop, skip a client socket check if
- the socket will be written to right away anyway. This can
- increase the transfer speed for unfiltered content on fast
- network connections.
- </para>
- </listitem>
- <listitem>
- <para>
- The socket timeout is used for SOCKS negotiations as well which
- previously couldn't timeout.
- </para>
- </listitem>
- <listitem>
- <para>
- Don't keep the client connection alive if any configuration file
- changed since the time the connection came in. This is closer to
- Privoxy's behaviour before keep-alive support for client connection
- has been added and also less confusing in general.
- </para>
- </listitem>
- <listitem>
- <para>
- Treat all Content-Type header values containing the pattern
- 'script' as a sign of text. Reported by pribog in #3134970.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Action file improvements:
- <itemizedlist>
- <listitem>
- <para>
- Moved the site-specific block pattern section below the one for the
- generic patterns so for requests that are matched in both, the block
- reason for the domain is shown which is usually more useful than showing
- the one for the generic pattern.
- </para>
- </listitem>
- <listitem>
- <para>
- 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.
- 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.
- Reported by Dan Stahlke in #3421755.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock linuxcounter.net/.
- Reported by Dan Stahlke in #3422612.
- </para>
- </listitem>
- <listitem>
- <para>
- Block 'www91.intel.com/' which is used by Omniture.
- Reported by Adam Piggott in #3167370.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable the handle-as-empty-doc-returns-ok option and mark it as deprecated.
- Reminded by tceverling in #2790091.
- </para>
- </listitem>
- <listitem>
- <para>
- Add ".ivwbox.de/" to the "Cross-site user tracking" section.
- Reported by Nettozahler in #3172525.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock and fast-redirect ".awin1.com/.*=http://".
- Reported by Adam Piggott in #3170921.
- </para>
- </listitem>
- <listitem>
- <para>
- Block "b.collective-media.net/".
- </para>
- </listitem>
- <listitem>
- <para>
- Widen the Debian popcon exception to "qa.debian.org/popcon".
- Seen in Debian's 05_default_action.dpatch by Roland Rosenfeld.
- </para>
- </listitem>
- <listitem>
- <para>
- Block ".gemius.pl/" which only seems to be used for user tracking.
- Reported by johnd16 in #3002731. Additional input from Lee and movax.
- </para>
- </listitem>
- <listitem>
- <para>
- 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/'.
- Reported by kacperdominik in #3372959.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock adainitiative.org/.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a fast-redirects exception for '.googleusercontent.com/.*=cache'.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a fast-redirects exception for webcache.googleusercontent.com/.
- </para>
- </listitem>
- <listitem>
- <para>
- Unblock http://adassier.wordpress.com/ and http://adassier.files.wordpress.com/.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Filter file improvements:
- <itemizedlist>
- <listitem>
- <para>
- Let the yahoo filter hide '.ads'.
- </para>
- </listitem>
- <listitem>
- <para>
- Let the msn filter hide overlay ads for Facebook 'likes' in search
- results and elements with the id 's_notf_div'. They only seem to be
- used to advertise site 'enhancements'.
- </para>
- </listitem>
- <listitem>
- <para>
- Let the js-events filter additionally disarm setInterval().
- Suggested by dg1727 in #3423775.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Documentation improvements:
- <itemizedlist>
- <listitem>
- <para>
- Clarify the effect of compiling Privoxy with zlib support.
- Suggested by dg1727 in #3423782.
- </para>
- </listitem>
- <listitem>
- <para>
- Point out that the SourceForge messaging system works like a black
- hole and should thus not be used to contact individual developers.
- </para>
- </listitem>
- <listitem>
- <para>
- Mention some of the problems one can experience when not explicitly
- configuring an IP addresses as listen address.
- </para>
- </listitem>
- <listitem>
- <para>
- Explicitly mention that hostnames can be used instead of IP addresses
- for the listen-address, that only the first address returned will be
- used and what happens if the address is invalid.
- Requested by Calestyo in #3302213.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Log message improvements:
- <itemizedlist>
- <listitem>
- <para>
- If only the server connection is kept alive, do not pretend to
- wait for a new client request.
- </para>
- </listitem>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- <listitem>
- <para>
- Let load_one_actions_file() properly complain about a missing
- '{' at the beginning of the file.
- Simply stating that a line is invalid isn't particularly helpful.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not claim to listen on a socket until Privoxy actually does.
- Patch submitted by Petr Pisar #3354485
- </para>
- </listitem>
- <listitem>
- <para>
- Prevent a duplicated LOG_LEVEL_CLF message when sending out
- the "no-server-data" response.
- </para>
- </listitem>
- <listitem>
- <para>
- Also log the client socket when dropping a connection.
- </para>
- </listitem>
- <listitem>
- <para>
- Include the destination host in the 'Request ... marked for
- blocking. limit-connect{...} doesn't allow CONNECT ...' message
- Patch submitted by Saperski in #3296250.
- </para>
- </listitem>
- <listitem>
- <para>
- Prevent a duplicated log message if none of the resolved IP
- addresses were reachable.
- </para>
- </listitem>
- <listitem>
- <para>
- In connect_to(), do not pretend to retry if forwarded-connect-retries
- is zero or unset.
- </para>
- </listitem>
- <listitem>
- <para>
- When a specified user or group can't be found, put the name in
- single-quotes when logging it.
- </para>
- </listitem>
- <listitem>
- <para>
- In rfc2553_connect_to(), explain getnameinfo() errors better.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a useless log message in chat().
- </para>
- </listitem>
- <listitem>
- <para>
- When retrying to connect, also log the maximum number of connection
- attempts.
- </para>
- </listitem>
- <listitem>
- <para>
- Rephrase a log message in compile_dynamic_pcrs_job_list().
- Divide the error code and its meaning with a colon. Call the pcrs
- job dynamic and not the filter. Filters may contain dynamic and
- non-dynamic pcrs jobs at the same time. Only mention the name of
- the filter or tagger, but don't claim it's a filter when it could
- be a tagger.
- </para>
- </listitem>
- <listitem>
- <para>
- In a fatal error message in load_one_actions_file(), cover both
- URL and TAG patterns.
- </para>
- </listitem>
- <listitem>
- <para>
- In pcrs_strerror(), properly report unknown positive error code
- values as such. Previously they were handled like 0 (no error).
- </para>
- </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.
- </para>
- </listitem>
- <listitem>
- <para>
- Don't bother trying to continue chatting if the client didn't ask for it.
- Reduces log noise a bit.
- </para>
- </listitem>
- <listitem>
- <para>
- 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 '..'.
- </para>
- </listitem>
- <listitem>
- <para>
- In load_file(), log a message if opening a file failed.
- The CGI error message alone isn't too helpful.
- </para>
- </listitem>
- <listitem>
- <para>
- In connection_destination_matches(), improve two log messages
- to help understand why the destinations don't match.
- </para>
- </listitem>
- <listitem>
- <para>
- Rephrase a log message in serve(). Client request arrival
- should be differentiated from closed client connections now.
- </para>
- </listitem>
- <listitem>
- <para>
- In serve(), log if a client connection isn't reused due to a
- configuration file change.
- </para>
- </listitem>
- <listitem>
- <para>
- Let mark_server_socket_tainted() always mark the server socket tainted,
- just don't talk about it in cases where it has no effect. It doesn't change
- Privoxy's behaviour, but makes understanding the log file easier.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- configure:
- <itemizedlist>
- <listitem>
- <para>
- Added a --disable-ipv6-support switch for platforms where support
- is detected but doesn't actually work.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not check for the existence of strerror() and memmove() twice
- </para>
- </listitem>
- <listitem>
- <para>
- Remove a useless test for setpgrp(2). Privoxy doesn't need it and
- it can cause problems when cross-compiling.
- </para>
- </listitem>
- <listitem>
- <para>
- Rename the --disable-acl-files switch to --disable-acl-support.
- Since about 2001, ACL directives are specified in the standard
- config file.
- </para>
- </listitem>
- <listitem>
- <para>
- Update the URL of the 'Removing outdated PCRE version after the
- next stable release' posting. The old URL stopped working after
- one of SF's recent site "optimizations". Reported by Han Liu.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Regression-Test:
- <itemizedlist>
- <listitem>
- <para>
- Added --shuffle-tests option to increase the chances of detection race conditions.
- </para>
- </listitem>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- <listitem>
- <para>
- The --privoxy-address option now works with IPv6 addresses containing brackets, too.
- </para>
- </listitem>
- <listitem>
- <para>
- Perform limited sanity checks for parameters that are supposed to have numerical values.
- </para>
- </listitem>
- <listitem>
- <para>
- Added a --sleep-time option to specify a number of seconds to
- sleep between tests, defaults to 0.
- </para>
- </listitem>
- <listitem>
- <para>
- Disable the range-requests tagger for tests that break if it's enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- Log messages use the ISO 8601 date format %Y-%m-%d.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix spelling in two error messages.
- </para>
- </listitem>
- <listitem>
- <para>
- In the --help output, include a list of supported tests and their default levels.
- </para>
- </listitem>
- <listitem>
- <para>
- Adjust the tests to properly deal with FEATURE_TOGGLE being disabled.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Log-Parser:
- <itemizedlist>
- <listitem>
- <para>
- Perform limited sanity checks for command line parameters that
- are supposed to have numerical values.
- </para>
- </listitem>
- <listitem>
- <para>
- Implement a --unbreak-lines-only option to try to revert MUA breakage.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Added header: Content-Encoding: deflate
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Compressed content from 29258 to 8630 bytes.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Client request arrived in time on socket 21.
- </para>
- </listitem>
- <listitem>
- <para>
- Highlight: Didn't receive data in time: a.fsdn.com:443
- </para>
- </listitem>
- <listitem>
- <para>
- Accept log messages with ISO 8601 time stamps, too.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- uagen:
- <itemizedlist>
- <listitem>
- <para>
- Bump generated Firefox version to 8.0.
- </para>
- </listitem>
- <listitem>
- <para>
- Only randomize the release date if the new --randomize-release-date
- option is enabled. Firefox versions after 4 use a fixed date string
- without meaning.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
+ administrator account.
+</para>
+</sect3>
+<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 (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>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<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>
+</sect3>
+
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="installation-source"><title>Building from Source</title>
+
+<para>
+ The most convenient way to obtain the <application>Privoxy</application> source
+ code is to download the source tarball from our
+ <ulink url="https://sourceforge.net/projects/ijbswa/files/Sources/">
+ project download page</ulink>,
+ or you can get the up-to-the-minute, possibly unstable, development version from
+ <ulink url="https://www.privoxy.org/">https://www.privoxy.org/</ulink>.
+</para>
+
+<!-- include buildsource.sgml boilerplate: -->
+&buildsource;
+<!-- end boilerplate -->
+
+
+ <sect3 id="WINBUILD-CYGWIN"><title>Windows</title>
+
+ <sect4 id="WINBUILD-SETUP"><title>Setup</title>
+ <para>
+ Install the Cygwin utilities needed to build <application>Privoxy</application>.
+ If you have a 64 bit CPU (which most people do by now), get the
+ Cygwin setup-x86_64.exe program <ulink url="https://cygwin.com/setup-x86_64.exe">here</ulink>
+ (the .sig file is <ulink url="https://cygwin.com/setup-x86_64.exe.sig">here</ulink>).
+ </para>
+ <para>
+ Run the setup program and from View / Category select:
+ </para>
+ <screen>
+ Devel
+ autoconf 2.5
+ automake 1.15
+ binutils
+ cmake
+ gcc-core
+ gcc-g++
+ git
+ make
+ mingw64-i686-gcc-core
+ mingw64-i686-zlib
+ Editors
+ vim
+ Libs
+ libxslt: GNOME XSLT library (runtime)
+ Net
+ curl
+ openssh
+ Text
+ docbook-dssl
+ docbook-sgml31
+ docbook-utils
+ openjade
+ Utils
+ gnupg
+ Web
+ w3m
+</screen>
+
+ <para>
+ If you haven't already downloaded the Privoxy source code, get it now:
+ </para>
+ <screen>
+ mkdir <root-dir>
+ cd <root-dir>
+ git clone https://www.privoxy.org/git/privoxy.git
+</screen>
+
+ <para>
+ Get the source code (.zip or .tar.gz) for tidy from
+ <ulink url="https://github.com/htacg/tidy-html5/releases">
+ https://github.com/htacg/tidy-html5/releases</ulink>,
+ unzip into <root-dir> and build the software:
+ </para>
+ <screen>
+ cd <root-dir>
+ cd tidy-html5-x.y.z/build/cmake
+ cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIB:BOOL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local
+ make && make install
+</screen>
+
+ <para>
+ If you want to be able to make a Windows release package, get the NSIS .zip file from
+ <!-- FIXME: which version(s) are known to work? -->
+ <ulink url="https://sourceforge.net/projects/nsis/files/NSIS%203/">
+ https://sourceforge.net/projects/nsis/files/NSIS%203/</ulink>
+ and extract the NSIS directory to <literal>privoxy/windows</literal>.
+ Then edit the windows/GNUmakefile to set the location of the NSIS executable - eg:
+ </para>
+ <screen>
+# Path to NSIS
+MAKENSIS = ./nsis/makensis.exe
+</screen>
+
+ </sect4>
+
+ <sect4 id="WINBUILD-BUILD"><title>Build</title>
+
+ <para>
+ To build just the Privoxy executable and not the whole installation package, do:
+ </para>
+ <programlisting>
+ cd <root-dir>/privoxy
+ ./windows/MYconfigure && make
+</programlisting>
+
+ <para>
+ Privoxy uses the <ulink url="https://en.wikipedia.org/wiki/GNU_build_system">GNU Autotools</ulink>
+ for building software, so the process is:
+ </para>
+ <programlisting>
+ $ autoheader # creates config.h.in
+ $ autoconf # uses config.h.in to create the configure shell script
+ $ ./configure [options] # creates GNUmakefile
+ $ make [options] # builds the program
+</programlisting>
+
+ <para>
+ The usual <literal>configure</literal> options for building a native Windows application under cygwin are
+ </para>
+
+ <literallayout class="Monospaced">
+ --host=i686-w64-mingw32
+ --enable-mingw32
+ --enable-zlib
+ --enable-static-linking
+ --disable-pthread
+ --disable-dynamic-pcre
+</literallayout>
+
+ <para>
+ You can set the <literal>CFLAGS</literal> and <literal>LDFLAGS</literal> envars before
+ running <literal>configure</literal> to set compiler and linker flags. For example:
+ </para>
+
+ <programlisting>
+ $ export CFLAGS="-O2" # set gcc optimization level
+ $ export LDFLAGS="-Wl,--nxcompat" # Enable DEP
+ $ ./configure --host=i686-w64-mingw32 --enable-mingw32 --enable-zlib \
+ > --enable-static-linking --disable-pthread --disable-dynamic-pcre
+ $ make # build Privoxy
+</programlisting>
+
+ <para>
+ See the <ulink url="../developer-manual/newrelease.html#NEWRELEASE-WINDOWS">Developer's Manual</ulink>
+ for building a Windows release package.
+ </para>
+
+ </sect4>
+ </sect3>
+</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 ~~~~~ -->
versions of <application>Privoxy</application>:
</para>
-<para>
<itemizedlist>
<listitem>
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.
that filtering does not work on compressed pages, so if you use, or want to
use, filtering, you will need to force compression off. Example:
</para>
- <para>
<screen>
{ +<link linkend="filter">filter</link>{google} +<link linkend="prevent-compression">prevent-compression</link> }
.google.</screen>
- </para>
<para>
Or if you use a number of filters, or filter many sites, you may just want
to turn off compression for all sites in
-->
</itemizedlist>
-</para>
</sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
-<para>
+
<itemizedlist>
<listitem>
</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
</listitem>
</itemizedlist>
-</para>
<!-- ~~~~~ New section ~~~~~ -->
<literal><link linkend="set-image-blocker">set-image-blocker</link></literal>:
</para>
-<para>
<itemizedlist>
<listitem>
</listitem>
</itemizedlist>
-</para>
<para>
Advanced users will eventually want to explore &my-app;
A quick and simple step by step example:
</para>
-<para>
<itemizedlist>
<listitem>
</para>
<!-- image of editor and actions files selections -->
- <para>
<figure pgwide="0" float="0"><title>Actions Files in Use</title>
<mediaobject>
<imageobject>
</textobject>
</mediaobject>
</figure>
- </para>
</listitem>
<listitem>
</listitem>
</itemizedlist>
-</para>
<para>
This is a very crude and simple example. There might be good reasons to use a
</para>
<!-- image of Mozilla Proxy configuration -->
- <para>
<figure pgwide="0" float="0"><title>Proxy Configuration Showing
Mozilla/Netscape HTTP and HTTPS (SSL) Settings</title>
<mediaobject>
</textobject>
</mediaobject>
</figure>
- </para>
<para>
<literallayout>
<guibutton>Tools</guibutton> -> <guibutton>Options</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Network</guibutton> -><guibutton>Connection</guibutton> -> <guibutton>Settings</guibutton>
-
</literallayout>
<para>
<literallayout>
<guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>General</guibutton> -> <guibutton>Connection Settings</guibutton> -> <guibutton>Manual Proxy Configuration</guibutton>
-
</literallayout>
<!-- Mix ascii and gui art, something for everybody -->
<!-- spacing on this is tricky -->
<guibutton>Edit</guibutton> -> <guibutton>Preferences</guibutton> -> <guibutton>Advanced</guibutton> -> <guibutton>Proxies</guibutton> -> <guibutton>HTTP Proxy</guibutton>
-
</literallayout>
<para>
</para>
<!-- image of IE Proxy configuration -->
- <para>
<figure pgwide="0" float="0"><title>Proxy Configuration Showing
Internet Explorer HTTP and HTTPS (Secure) Settings</title>
<mediaobject>
</textobject>
</mediaobject>
</figure>
- </para>
<para>
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 id="start-windows">
</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>
+ 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-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.
+ 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>
- An administrator username and password must be supplied in order for
- the Privoxy Utility to perform any of the tasks.
+ 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>
-</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).
+ 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>
-<sect2 id="start-gentoo">
-<title>Gentoo</title>
-<para>
- A script is again used. It will use the file <filename>/etc/privoxy/config
- </filename> as its main configuration file.
-</para>
-<para>
- <screen>
- /etc/init.d/privoxy start
- </screen>
-</para>
-<para>
- Note that <application>Privoxy</application> is not automatically started at
- boot time by default. You can change this with the <literal>rc-update</literal>
- command.
-</para>
-<para>
- <screen>
- rc-update add privoxy default
- </screen>
-</para>
-</sect2>
<!--
command-line options:
</para>
-<para>
<itemizedlist>
<listitem>
<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>
</listitem>
</itemizedlist>
-</para>
<para>
On <application>MS Windows</application> only there are two additional
<!-- ~~~~~ 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
(shortcut: <ulink url="http://p.p/">http://p.p/</ulink>),
which is a built-in page and works without Internet access.
You will see the following section:
-
</para>
<!-- Needs to be put in a table and colorized -->
-<screen>
+<screen><!-- want the background color that goes with screen -->
<msgtext>
<bridgehead renderas="sect2"> Privoxy Menu</bridgehead>
-
<simplelist>
<member>
▪ <ulink url="http://config.privoxy.org/show-status">View & change the current configuration</ulink>
</member>
- <member>
- ▪ <ulink url="http://config.privoxy.org/show-version">View the source code version numbers</ulink>
- </member>
<member>
▪ <ulink url="http://config.privoxy.org/show-request">View the request headers.</ulink>
</member>
</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>
<sect2 id="confoverview">
<title>Configuration Files Overview</title>
<para>
- For Unix, *BSD and Linux, all configuration files are located in
- <filename>/etc/privoxy/</filename> by default. For MS Windows, OS/2, and
- AmigaOS these are all in the same directory as the
+ For Unix, *BSD and GNU/Linux, all configuration files are located in
+ <filename>/etc/privoxy/</filename> by default. For MS Windows and OS/2
+ these are all in the same directory as the
<application>Privoxy</application> executable. <![%p-not-stable;[ The name
and number of configuration files has changed from previous versions, and is
subject to change as development progresses.]]>
principle configuration files are:
</para>
-<para>
<itemizedlist>
<listitem>
<para>
The <link linkend="config">main configuration file</link> is named <filename>config</filename>
- on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
+ on GNU/Linux, Unix, BSD, and OS/2, and <filename>config.txt</filename>
on Windows. This is a required file.
</para>
</listitem>
</listitem>
</itemizedlist>
-</para>
<para>
The syntax of the configuration and filter files may change between different
are three action files included with <application>Privoxy</application> with
differing purposes:
</para>
-<para>
<itemizedlist>
<listitem>
<para>
The default profiles, and their associated actions, as pre-defined in
<filename>default.action</filename> are:
</para>
- <para>
<table frame=all><title>Default Configurations</title>
<tgroup cols=4 align=left colsep=1 rowsep=1>
<colspec colname=c1>
</tbody>
</tgroup>
</table>
- </para>
</listitem>
</itemizedlist>
-</para>
<para>
The list of actions files to be used are defined in the main configuration
</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
might look like:
</para>
- <para>
<screen>
{ +<literal>handle-as-image</literal> +<literal>block{Banner ads.}</literal> }
# Block these as if they were images. Send no block page.
banners.example.com
media.example.com/.*banners
.example.com/images/ads/</screen>
- </para>
<para>
You can trace this process for URL patterns and any given URL by visiting <ulink
<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
This regular expression is conditional so it will match any page
named <quote>index.html</quote> regardless of path which in this case can
have one or more <quote>/'s</quote>. And this one must contain exactly
- <quote>.html</quote> (but does not have to end with that!).
+ <quote>.html</quote> (and end with that!).
</para>
</listitem>
</varlistentry>
that contains any of the words <quote>ads</quote>, <quote>banner</quote>,
<quote>banners</quote> (because of the <quote>?</quote>) or <quote>junk</quote>.
The path does not have to end in these words, just contain them.
+ The path has to contain at least two slashes (including the one at the beginning).
</para>
</listitem>
</varlistentry>
<!-- ~~~~~ 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>
+</sect3>
+
+<!-- ~~~~~ 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>
+
+ <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>
+
+</sect3>
+
</sect2>
<!-- ~ End section ~ -->
following patterns</quote>, and <literal>-block</literal> means <quote>don't
block URLs that match the following patterns, even if <literal>+block</literal>
previously applied.</quote>
-
</para>
<para>
Actions fall into three categories:
</para>
-<para>
<itemizedlist>
<listitem>
<para>
Boolean, i.e the action can only be <quote>enabled</quote> or
<quote>disabled</quote>. Syntax:
</para>
- <para>
<screen>
+<replaceable class="function">name</replaceable> # enable action <replaceable class="parameter">name</replaceable>
-<replaceable class="function">name</replaceable> # disable action <replaceable class="parameter">name</replaceable></screen>
- </para>
<para>
Example: <literal>+handle-as-image</literal>
</para>
Parameterized, where some value is required in order to enable this type of action.
Syntax:
</para>
- <para>
<screen>
+<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
# overwriting parameter from previous match if necessary
-<replaceable class="function">name</replaceable> # disable action. The parameter can be omitted</screen>
- </para>
<para>
Note that if the URL matches multiple positive forms of a parameterized action,
the last match wins, i.e. the params from earlier matches are simply ignored.
that can be executed for the same request repeatedly, like adding multiple
headers, or filtering through multiple filters. Syntax:
</para>
- <para>
<screen>
+<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
-<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>} # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
# If it was the last one left, disable the action.
<replaceable class="parameter">-name</replaceable> # disable this action completely and remove all parameters from the list</screen>
- </para>
<para>
Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
<literal>+filter{html-annoyances}</literal>
</listitem>
</itemizedlist>
-</para>
<para>
If nothing is specified in any actions file, no <quote>actions</quote> are
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
- <screen>+add-header{X-User-Tracking: sucks}</screen>
- </para>
+ <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>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen>{+block{No nasty stuff for you.}}
# Block and replace with "blocked" page
.nasty-stuff.example.com
{+block{Layered ads.} +handle-as-empty-document}
# Block and then ignore
adserver.example.net/.*\.js$</screen>
- </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>+change-x-forwarded-for{block}</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen>
# Hide Tor exit notation in Host and Referer Headers
{+client-header-filter{hide-tor-exit-notation}}
/
- </screen>
- </para>
+</screen>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen>
# Tag every request with the User-Agent header
{+client-header-tagger{user-agent}}
TAG:^User-Agent: fetch libfetch/
TAG:^User-Agent: Ubuntu APT-HTTP/
TAG:^User-Agent: MPlayer/
- </screen>
- </para>
- <para>
+</screen>
+
<screen>
# Tag all requests with the Range header set
{+client-header-tagger{range-requests}}
# parts of multimedia files.
{-filter -deanimate-gifs}
TAG:^RANGE-REQUEST$
- </screen>
- </para>
+</screen>
+
+ <screen>
+# Tag all requests with the client IP address
+#
+# (Technically the client IP address isn't included in the
+# client headers but client-header taggers can set it anyway.
+# For details see the tagger in default.filter)
+{+client-header-tagger{client-ip-address}}
+/
+
+# Change forwarding settings for requests coming from address 10.0.0.1
+{+forward-override{forward-socks5 127.0.1.2:2222 .}}
+TAG:^IP-ADDRESS: 10\.0\.0\.1$
+</screen>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage (sections):</term>
<listitem>
- <para>
<screen># Check if www.example.net/ really uses valid XHTML
{ +content-type-overwrite{application/xml} }
www.example.net/
www.example.net/.*\.css$
www.example.net/.*style
</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen># Block the non-existent "Privacy-Violation:" client header
{ +crunch-client-header{Privacy-Violation:} }
/
- </screen>
- </para>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen># Let the browser revalidate cached documents but don't
# allow the server to use the revalidation headers for user tracking.
{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
-/ </screen>
- </para>
+/
+</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>+crunch-incoming-cookies</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen># Crunch server headers that try to prevent caching
{ +crunch-server-header{no-cache} }
-/ </screen>
- </para>
+/
+</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>+crunch-outgoing-cookies</screen>
- </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>+deanimate-gifs{last}</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="delay-response">
+<title>delay-response</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Delay responses to the client to reduce the load</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Delays responses to the client by sending the response in ca. 10 byte chunks.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- boolean, parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ <quote>Number of milliseconds</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Sometimes when JavaScript code is used to fetch advertisements
+ it doesn't respect Privoxy's blocks and retries to fetch the
+ same resource again causing unnecessary load on the client.
+ </para>
+ <para>
+ This action delays responses to the client and can be combined
+ with <literal><link linkend="block">blocks</link></literal>
+ to slow down the JavaScript code, thus reducing
+ the load on the client.
+ </para>
+ <para>
+ When used without <literal><link linkend="block">blocks</link></literal>
+ the action can also be used to simulate a slow internet connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <screen>+delay-response{100}</screen>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="downgrade-http-version">
<title>downgrade-http-version</title>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen>{+downgrade-http-version}
problem-host.example.com</screen>
+ </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>
+ <screen>+external-filter{fancy-filter}</screen>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect3>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>
{ +fast-redirects{simple-check} }
one.example.com
{ +fast-redirects{check-decoded-url} }
another.example.com/testing</screen>
- </para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<listitem>
<para>
<anchor id="filter-js-annoyances">
- <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.</screen>
</para>
+ <screen>+filter{js-annoyances} # Get rid of particularly annoying JavaScript abuse.</screen>
<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>
</para>
+ <screen>+filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
<para>
<anchor id="filter-html-annoyances">
- <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
</para>
+ <screen>+filter{html-annoyances} # Get rid of particularly annoying HTML abuse.</screen>
<para>
<anchor id="filter-content-cookies">
- <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content.</screen>
</para>
+ <screen>+filter{content-cookies} # Kill cookies that come in the HTML or JS content.</screen>
<para>
<anchor id="filter-refresh-tags">
- <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).</screen>
</para>
+ <screen>+filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds.</screen>
<para>
<anchor id="filter-unsolicited-popups">
- <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</screen>
</para>
+ <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows.</screen>
<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>
</para>
+ <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML.</screen>
<para>
<anchor id="filter-img-reorder">
- <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.</screen>
</para>
+ <screen>+filter{img-reorder} # Reorder attributes in <img> tags to make the banners-by-* filters more effective.</screen>
<para>
<anchor id="filter-banners-by-size">
- <screen>+filter{banners-by-size} # Kill banners by size.</screen>
</para>
+ <screen>+filter{banners-by-size} # Kill banners by size.</screen>
<para>
<anchor id="filter-banners-by-link">
- <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers.</screen>
</para>
+ <screen>+filter{banners-by-link} # Kill banners by their links to known clicktrackers.</screen>
<para>
<anchor id="filter-webbugs">
- <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
</para>
+ <screen>+filter{webbugs} # Squish WebBugs (1x1 invisible GIFs used for user tracking).</screen>
<para>
<anchor id="filter-tiny-textforms">
- <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
</para>
+ <screen>+filter{tiny-textforms} # Extend those tiny textareas up to 40x80 and kill the hard wrap.</screen>
<para>
<anchor id="filter-jumping-windows">
- <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves.</screen>
</para>
+ <screen>+filter{jumping-windows} # Prevent windows from resizing and moving themselves.</screen>
<para>
<anchor id="filter-frameset-borders">
+ </para>
<screen>+filter{frameset-borders} # Give frames a border and make them resizable.</screen>
+ <para>
+ <anchor id="filter-iframes">
</para>
+ <screen>+filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites.</screen>
<para>
<anchor id="filter-demoronizer">
- <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</screen>
</para>
+ <screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</screen>
<para>
<anchor id="filter-shockwave-flash">
- <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects.</screen>
</para>
+ <screen>+filter{shockwave-flash} # Kill embedded Shockwave Flash objects.</screen>
<para>
<anchor id="filter-quicktime-kioskmode">
- <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
</para>
+ <screen>+filter{quicktime-kioskmode} # Make Quicktime movies saveable.</screen>
<para>
<anchor id="filter-fun">
- <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
</para>
+ <screen>+filter{fun} # Text replacements for subversive browsing fun!</screen>
<para>
<anchor id="filter-crude-parental">
- <screen>+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably.</screen>
</para>
+ <screen>+filter{crude-parental} # Crude parental filtering. Note that this filter doesn't work reliably.</screen>
<para>
<anchor id="filter-ie-exploits">
- <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits.</screen>
</para>
+ <screen>+filter{ie-exploits} # Disable some known Internet Explorer bug exploits.</screen>
<para>
<anchor id="filter-site-specifics">
- <screen>+filter{site-specifics} # Cure for site-specific problems. Don't apply generally!</screen>
</para>
+ <screen>+filter{site-specifics} # Cure for site-specific problems. Don't apply generally!</screen>
<para>
<anchor id="filter-no-ping">
- <screen>+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.</screen>
</para>
+ <screen>+filter{no-ping} # Removes non-standard ping attributes in <a> and <area> tags.</screen>
<para>
<anchor id="filter-google">
- <screen>+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
</para>
+ <screen>+filter{google} # CSS-based block for Google text ads. Also removes a width limitation and the toolbar advertisement.</screen>
<para>
<anchor id="filter-yahoo">
- <screen>+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
</para>
+ <screen>+filter{yahoo} # CSS-based block for Yahoo text ads. Also removes a width limitation.</screen>
<para>
<anchor id="filter-msn">
- <screen>+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
</para>
+ <screen>+filter{msn} # CSS-based block for MSN text ads. Also removes tracking URLs and a width limitation.</screen>
<para>
<anchor id="filter-blogspot">
- <screen>+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
</para>
+ <screen>+filter{blogspot} # Cleans up some Blogspot blogs. Read the fine print before using this.</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>
+force-text-mode
- </screen>
- </para>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<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>
<varlistentry>
<term>Example usage:</term>
<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 \
}
TAG:^User-Agent: fetch libfetch/2\.0$
- </screen>
- </para>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen># Block all documents on example.org that end with ".js",
# but send an empty document instead of the usual HTML message.
{+block{Blocked JavaScript} +handle-as-empty-document}
example.org/.*\.js$
- </screen>
- </para>
+</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (sections):</term>
<listitem>
- <para>
<screen># Generic image extensions:
#
{+handle-as-image}
{+block{Nasty banners.} +handle-as-image}
nasty-banner-server.example.com/junk.cgi\?output=trash
</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen># Pretend to use Canadian language settings.
{+hide-accept-language{en-ca} \
+hide-user-agent{Mozilla/5.0 (X11; U; OpenBSD i386; en-CA; rv:1.8.0.4) Gecko/20060628 Firefox/1.5.0.4} \
}
-/ </screen>
- </para>
+/
+</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen># Disarm the download link in Sourceforge's patch tracker
{ -filter \
+content-type-overwrite{text/plain}\
+hide-content-disposition{block} }
.sourceforge.net/tracker/download\.php</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen># Let the browser revalidate but make tracking based on the time less likely.
{+hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
- <screen>+hide-from-header{block}</screen> or
+ <screen>+hide-from-header{block}</screen>
+ <para>or</para>
<screen>+hide-from-header{spam-me-senseless@sittingduck.example.com}</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
- <screen>+hide-referrer{forge}</screen> or
+ <screen>+hide-referrer{forge}</screen>
+ <para>or</para>
<screen>+hide-referrer{http://www.yahoo.com/}</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<!-- I had trouble getting the spacing to look right in my browser -->
<!-- I probably have the wrong font setup, bollocks. -->
<!-- Apparently the emphasis tag uses a proportional font no matter what -->
- <para>
<screen>+limit-connect{443} # Port 443 is OK.
+limit-connect{80,443} # Ports 80 and 443 are OK.
+limit-connect{-3, 7, 20-100, 500-} # Ports less than 3, 7, 20 to 100 and above 500 are OK.
+limit-connect{-} # All ports are OK
+limit-connect{,} # No HTTPS/SSL traffic is allowed</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usages:</term>
<listitem>
- <para>
- <screen>+limit-cookie-lifetime{60}
- </screen>
- </para>
+ <screen>+limit-cookie-lifetime{60}</screen>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Example usage (sections):</term>
<listitem>
- <para>
<screen>
# Selectively turn off compression, and enable a filter
#
#
{ -prevent-compression }
.compusa.com/</screen>
- </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen># Let the browser revalidate without being tracked across sessions
{ +hide-if-modified-since{-60} \
+overwrite-last-modified{randomize} \
+crunch-if-none-match}
/</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<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>
<varlistentry>
<term>Example usages:</term>
<listitem>
- <para>
<screen># Replace example.com's style sheet with another one
{ +redirect{http://localhost/css-replacements/example.com.css} }
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@}}
www.privoxy.org/user-manual/</screen>
- </para>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen>
{+server-header-filter{html-to-xml}}
example.org/xml-instance-that-is-delivered-as-html
{+server-header-filter{xml-to-html}}
example.org/instance-that-is-delivered-as-xml-but-is-not
- </screen>
- </para>
+</screen>
</listitem>
</varlistentry>
<term>Type:</term>
<!-- boolean, parameterized, Multi-value -->
<listitem>
- <para>Parameterized.</para>
+ <para>Multi-value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage (section):</term>
<listitem>
- <para>
<screen>
# Tag every request with the content type declared by the server
{+server-header-tagger{content-type}}
/
- </screen>
- </para>
+
+# 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>
</listitem>
</varlistentry>
<varlistentry>
<term>Example usage:</term>
<listitem>
- <para>
<screen>+session-cookies-only</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<para>
Built-in pattern:
</para>
- <para>
<screen>+set-image-blocker{pattern}</screen>
- </para>
<para>
Redirect to the BSD daemon:
</para>
- <para>
<screen>+set-image-blocker{http://www.freebsd.org/gifs/dae_up3.gif}</screen>
- </para>
<para>
Redirect to the built-in pattern for better caching:
</para>
- <para>
<screen>+set-image-blocker{http://config.privoxy.org/send-banner?type=pattern}</screen>
- </para>
</listitem>
</varlistentry>
</variablelist>
<!-- ~~~~~ New section ~~~~~ -->
-<sect3>
+<sect3 id="summary">
<title>Summary</title>
<para>
Note that many of these actions have the potential to cause a page to
Now let's define some aliases...
</para>
-<para>
<screen>
# Useful custom aliases we can use later.
#
#
c0 = +crunch-all-cookies
c1 = -crunch-all-cookies</screen>
-</para>
<para>
...and put them to use. These sections would appear in the lower part of an
up for the <quote>/</quote> pattern):
</para>
-<para>
<screen>
# These sites are either very complex or very keen on
# user data and require minimal interference to work:
{-filter{all-popups} -filter{unsolicited-popups}}
.dabs.com
.overclockers.co.uk</screen>
-</para>
<para>
Aliases like <quote>shop</quote> and <quote>fragile</quote> are typically used for
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>,
multiple lines with line continuation.
</para>
-<para>
<screen>
{ \
+<link linkend="CHANGE-X-FORWARDED-FOR">change-x-forwarded-for{block}</link> \
+<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
}
/ # Match all URLs
- </screen>
-</para>
+</screen>
<para>
The default behavior is now set.
</para>
</sect3>
-<sect3>
+<sect3 id="default-action">
<title>default.action</title>
<para>
that prevents older &my-app; versions from reading the file:
</para>
-<para>
<screen>
##########################################################################
# Settings -- Don't change! For internal Privoxy use ONLY.
##########################################################################
{{settings}}
for-privoxy-version=3.0.11</screen>
-</para>
<para>
After that comes the (optional) alias section. We'll use the example
that also explains why and how aliases are used:
</para>
-<para>
<screen>
##########################################################################
# Aliases
#
fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link>
shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link></screen>
-</para>
<para>
The first of our specialized sections is concerned with <quote>fragile</quote>
sites, i.e. sites that require minimum interference, because they are either
very complex or very keen on tracking you (and have mechanisms in place that
- make them unusable for people who avoid being tracked). We will simply use
+ make them unusable for people who avoid being tracked). We will use
our pre-defined <literal>fragile</literal> alias instead of stating the list
of actions explicitly:
</para>
-<para>
<screen>
##########################################################################
# Exceptions for sites that'll break under the default action set:
.office.microsoft.com # surprise, surprise!
.windowsupdate.microsoft.com
mail.google.com</screen>
-</para>
<para>
Shopping sites are not as fragile, but they typically
carts or item details. Again, we'll use a pre-defined alias:
</para>
-<para>
<screen>
# Shopping sites:
#
.worldpay.com # for quietpc.com
.jungle.com
.scan.co.uk</screen>
-</para>
<para>
The <literal><link linkend="FAST-REDIRECTS">fast-redirects</link></literal>
breaks some sites. So disable it for popular sites where we know it misbehaves:
</para>
-<para>
<screen>
{ -<link linkend="FAST-REDIRECTS">fast-redirects</link> }
login.yahoo.com
.altavista.com/.*(like|url|link):http
.altavista.com/trans.*urltext=http
.nytimes.com</screen>
-</para>
<para>
It is important that <application>Privoxy</application> knows which
good start:
</para>
-<para>
<screen>
##########################################################################
# Images:
#
{ +<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> }
/.*\.(gif|jpe?g|png|bmp|ico)$</screen>
-</para>
<para>
And then there are known banner sources. They often use scripts to
action before, it still applies and needn't be repeated:
</para>
-<para>
<screen>
# Known ad generators:
#
.a[0-9].yimg.com/(?:(?!/i/).)*$
bs*.gsanet.com
.qkimg.net</screen>
-</para>
<para>
One of the most important jobs of <application>Privoxy</application>
to keep the example short:
</para>
-<para>
<screen>
##########################################################################
# Block these fine banners:
# Site-specific patterns (abbreviated):
#
.hitbox.com</screen>
-</para>
<para>
It's quite remarkable how many advertisers actually call their banner
servers ads.<replaceable>company</replaceable>.com, or call the directory
- in which the banners are stored simply <quote>banners</quote>. So the above
+ in which the banners are stored literally <quote>banners</quote>. So the above
generic patterns are surprisingly effective.
</para>
<para>
with no <literal><link linkend="BLOCK">block</link></literal> action applying.
</para>
-<para>
<screen>
##########################################################################
# Save some innocent victims of the above generic block patterns:
#
www.globalintersec.com/adv # (adv = advanced)
www.ugu.com/sui/ugu/adv</screen>
-</para>
<para>
Filtering source code can have nasty side effects,
disables <emphasis>all</emphasis> filters in one fell swoop!
</para>
-<para>
<screen>
# Don't filter code!
#
developer.
wiki.
.sourceforge.net</screen>
-</para>
<para>
The actual <filename>default.action</filename> is of course much more
</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,
<!-- brief sample user.action here -->
-<para>
<screen>
# My user.action file. <fred@example.com></screen>
-</para>
<para>
As <link linkend="aliases">aliases</link> are local to the actions
<filename>default.action</filename>, unless you repeat them here:
</para>
-<para>
<screen>
# Aliases are local to the file they are defined in.
# (Re-)define aliases for this file:
# MIME types. We want the browser to force these to be text documents.
handle-as-text = -<link linkend="FILTER">filter</link> +-<link linkend="content-type-overwrite">content-type-overwrite{text/plain}</link> +-<link linkend="FORCE-TEXT-MODE">force-text-mode</link> -<link linkend="HIDE-CONTENT-DISPOSITION">hide-content-disposition</link></screen>
-</para>
-
<para>
Say you have accounts on some sites that you visit regularly, and
you don't want to have to log in manually each time. So you'd like
processing of cookies to make them only temporary.
</para>
-<para>
<screen>
{ allow-all-cookies }
sourceforge.net
.yahoo.com
.msdn.microsoft.com
.redhat.com</screen>
-</para>
<para>
Your bank is allergic to some filter, but you don't know which, so you disable them all:
</para>
-<para>
<screen>
{ -<link linkend="FILTER">filter</link> }
.your-home-banking-site.com</screen>
-</para>
<para>
Some file types you may not want to filter for various reasons:
</para>
-<para>
<screen>
# Technical documentation is likely to contain strings that might
# erroneously get altered by the JavaScript-oriented filters:
# so that Privoxy thinks it is getting HTML and starts filtering:
#
stupid-server.example.com/</screen>
-</para>
<para>
Example of a simple <link linkend="BLOCK">block</link> action. Say you've
in default.action anyway:
</para>
-<para>
<screen>
{ +<link linkend="BLOCK">block</link>{Nasty ads.} }
www.example.com/nasty-ads/sponsor\.gif
another.example.net/more/junk/here/</screen>
-</para>
<para>
The URLs of dynamically generated banners, especially from large banner
browser. Use cautiously.
</para>
-<para>
<screen>
{ +block-as-image }
.doubleclick.net
.fastclick.net
/Realmedia/ads/
ar.atwola.com/</screen>
-</para>
<para>
Now you noticed that the default configuration breaks Forbes Magazine,
that misbehave, and add those to our personalized list of troublemakers:
</para>
-<para>
<screen>
{ fragile }
.forbes.com
webmail.example.com
.mybank.com</screen>
-</para>
<para>
You like the <quote>fun</quote> text replacements in <filename>default.filter</filename>,
update-safe config, once and for all:
</para>
-<para>
<screen>
{ +<link linkend="filter-fun">filter{fun}</link> }
/ # For ALL sites!</screen>
-</para>
<para>
Note that the above is not really a good idea: There are exceptions
sites that you feel provide value to you:
</para>
-<para>
<screen>
{ allow-ads }
.sourceforge.net
.slashdot.org
.osdn.net</screen>
-</para>
<para>
Note that <literal>allow-ads</literal> has been aliased to
it should I choose to.
</para>
-<para>
<screen>
{ handle-as-text }
/.*\.sh$</screen>
-</para>
<para>
<filename>user.action</filename> is generally the best place to define
paths and patterns:
</para>
-<para>
<screen>
{ +<link linkend="set-image-blocker">set-image-blocker{blank}</link> }
/ # ALL sites</screen>
-</para>
</sect3>
</sect2>
</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
like this:
</para>
-<para>
<screen>FILTER: foo Replace all "foo" with "bar"</screen>
-</para>
<para>
Below that line, and up to the next header line, come the jobs that
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
needed:
</para>
-<para>
<screen>s/foo/bar/</screen>
-</para>
<para>
But wait! Didn't the comment say that <emphasis>all</emphasis> occurrences
we'll need to add the <literal>g</literal> option:
</para>
-<para>
<screen>s/foo/bar/g</screen>
-</para>
<para>
Our complete filter now looks like this:
</para>
-<para>
+
<screen>FILTER: foo Replace all "foo" with "bar"
s/foo/bar/g</screen>
-</para>
<para>
Let's look at some real filters for more interesting examples. Here you see
</para>
-<para>
<screen>
FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
# Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
#
s|(<script.*)document\.referrer(.*</script>)|$1"Not Your Business!"$2|Usg</screen>
-</para>
<para>
Following the header line and a comment, you see the job. Note that it uses
this time only point out the constructs of special interest:
</para>
-<para>
<screen>
# The status bar is for displaying link targets, not pointless blahblah
#
s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</screen>
-</para>
<para>
<literal>\s</literal> stands for whitespace characters (space, tab, newline,
you move your mouse over links.
</para>
-<para>
<screen>
# Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
#
s/(<body [^>]*)onunload(.*>)/$1never$2/iU</screen>
-</para>
<para>
Including the
The last example is from the fun department:
</para>
-<para>
<screen>
FILTER: fun Fun text replacements
# Spice the daily news:
#
s/microsoft(?!\.com)/MicroSuck/ig</screen>
-</para>
<para>
Note the <literal>(?!\.com)</literal> part (a so-called negative lookahead)
still replacing the word everywhere else.
</para>
-<para>
<screen>
# Buzzword Bingo (example for extended regex syntax)
#
| unrivalled \
*<font color="red"><b>BINGO!</b></font> \
*igx</screen>
-</para>
<para>
The <literal>x</literal> option in this job turns on extended syntax, and allows for
<para>
The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
To that end, it
+ </para>
<itemizedlist>
<listitem>
<para>
</para>
</listitem>
</itemizedlist>
- </para>
<para>
Use with caution. This is an aggressive filter, and can break sites that
rely heavily on JavaScript.
</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>
+
+ <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>
+
+<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 ~ -->
is in an alpha or beta development stage:
</para>
-<para>
<screen>
<!-- @if-unstable-start -->
... beta warning HTML code goes here ...
<!-- if-unstable-end@ --></screen>
-</para>
<para>
If the "unstable" symbol is set, everything in between and including
will disappear, leaving nothing but an empty comment:
</para>
-<para>
<screen><!-- --></screen>
-</para>
<para>
There's also an if-then-else construct and an <literal>#include</literal>
©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>
+
+ <screen><![ RCDATA [ &GPLv2; ]]></screen>
+
</sect2>
<!-- ~ End section ~ -->
and then some examples:
</para>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>.</emphasis> - Matches any single character, e.g. <quote>a</quote>,
<quote>A</quote>, <quote>4</quote>, <quote>:</quote>, or <quote>@</quote>.
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
times. Either/or.
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
times.
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
times.
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
the following character should be taken literally. This is used where one of the
sure the period is recognized only as a period (and not expanded to its
meta-character meaning of any single character).
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>[ ]</emphasis> - Characters enclosed in brackets will be matched if
any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
matches any numeric digit (zero through nine). As an example, we can combine
this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
or multiple sub-expressions.
</member>
-</simplelist></para>
+</simplelist>
-<para><simplelist>
+<simplelist>
<member>
<emphasis>|</emphasis> - The <quote>bar</quote> character works like an
<quote>or</quote> conditional statement. A match is successful if the
and would match either <quote>this example</quote> or <quote>that
example</quote>, and nothing else.
</member>
-</simplelist></para>
+</simplelist>
<para>
These are just some of the ones you are likely to use when matching URLs with
<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
+<sect2 id="internal-pages">
<title>Privoxy's Internal Pages</title>
<para>
rules and other configuration options, and even turn
<application>Privoxy's</application> filtering off, all with
a web browser.
-
</para>
<para>
necessary either.
</para>
-<para>
<itemizedlist>
<listitem>
</blockquote>
</listitem>
- <listitem>
- <para>
- Show the source code version numbers:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/show-version">http://config.privoxy.org/show-version</ulink>
- </para>
- </blockquote>
- </listitem>
-
<listitem>
<para>
Show the browser's request headers:
</listitem>
</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>
page is requested by your browser:
</para>
-<para>
<itemizedlist>
<listitem>
<para>
</listitem>
</itemizedlist>
-</para>
+
<para>
NOTE: This is somewhat of a simplistic overview of what happens with each URL
request. For the sake of brevity and simplicity, we have focused on
<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>.)
configuration may vary):
</para>
-<para>
<screen>
Matches for http://www.google.com:
In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
(no matches in this file)
</screen>
-</para>
<para>
This is telling us how we have defined our
And finally we pull it all together in the bottom section and summarize how
<application>Privoxy</application> is applying all its <quote>actions</quote>
to <quote>google.com</quote>:
-
</para>
-<para>
<screen>
-
Final results:
-add-header
-server-header-filter{xml-to-html}
-server-header-filter{html-to-xml}
-session-cookies-only
- +set-image-blocker {pattern} </screen>
-</para>
+ +set-image-blocker {pattern}
+</screen>
<para>
Notice the only difference here to the previous listing, is to
Now another example, <quote>ad.doubleclick.net</quote>:
</para>
-<para>
<screen>
-
{ +block{Domains starts with "ad"} }
ad*.
{ +block{Doubleclick banner server} +handle-as-image }
.[a-vx-z]*.doubleclick.net
</screen>
-</para>
<para>
We'll just show the interesting part here - the explicit matches. It is
This one is giving us problems. We are getting a blank page. Hmmm ...
</para>
-<para>
<screen>
-
Matches for http://www.example.net/adsl/HOWTO/:
In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
{ +block{Path contains "ads".} +handle-as-image }
/ads
</screen>
-</para>
<para>
Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
wins). There are various ways to handle such exceptions. Example:
</para>
-<para>
<screen>
-
{ -block }
/adsl
</screen>
-</para>
<para>
Now the page displays ;-)
we did with:
</para>
-<para>
<screen>
-
{ +block{Path starts with "ads".} +handle-as-image }
/ads
</screen>
-</para>
<para>
That actually was very helpful and pointed us quickly to where the problem
<link linkend="FILTER"><quote>+filter</quote></link>:
</para>
-<para>
<screen>
-
{ shop }
.quietpc.com
.worldpay.com # for quietpc.com
.scan.co.uk
.forbes.com
</screen>
-</para>
<para>
<quote><literal>{ shop }</literal></quote> is an <quote>alias</quote> that expands to
<quote><literal>{ -filter -session-cookies-only }</literal></quote>.
Or you could do your own exception to negate filtering:
-
</para>
-<para>
<screen>
-
{ -filter }
# Disable ALL filter actions for sites in this section
.forbes.com
developer.ibm.com
localhost
</screen>
-</para>
<para>
This would turn off all filtering for these sites. This is best
actions that are the most likely to cause trouble. This can be used as a
last resort for problem sites.
</para>
-<para>
- <screen>
+ <screen>
{ fragile }
# Handle with care: easy to break
mail.google.
mybank.example.com</screen>
-</para>
<para>
projects / privoxy.git / blobdiff