<!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.18">
+<!entity changelog SYSTEM "changelog.sgml">
+<!entity p-version "3.0.22">
<!entity p-status "UNRELEASED">
<!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc -->
<!entity % p-not-stable "INCLUDE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.135 2011/09/04 11:10:12 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.190 2014/07/14 13:37:08 fabiankeil Exp $
- Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://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-2011 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2014 by
<ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-<pubdate>$Id: user-manual.sgml,v 2.135 2011/09/04 11:10:12 fabiankeil Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 2.190 2014/07/14 13:37:08 fabiankeil Exp $</pubdate>
<!--
<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
<!-- XXX: The installation sections should be sorted -->
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-rpm"><title>Red Hat and Fedora RPMs</title>
-
-<para>
- RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
- and will use <filename>/etc/privoxy</filename> for the location
- of configuration files.
-</para>
-
-<para>
- Note that on Red Hat, <application>Privoxy</application> will
- <emphasis>not</emphasis> be automatically started on system boot. You will
- need to enable that using <command>chkconfig</command>,
- <command>ntsysv</command>, or similar methods.
-</para>
-
-<para>
- If you have problems with failed dependencies, try rebuilding the SRC RPM:
- <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm</literal>. This
- will use your locally installed libraries and RPM version.
-</para>
-
-<para>
- Also note that if you have a <application>Junkbuster</application> RPM installed
- on your system, you need to remove it first, because the packages conflict.
- Otherwise, RPM will try to remove <application>Junkbuster</application>
- automatically if found, before installing <application>Privoxy</application>.
-</para>
-</sect3>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-deb"><title>Debian and Ubuntu</title>
<para>
</sect3>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-pack-bintgz"><title>Solaris <!--, NetBSD, HP-UX--></title>
-
-<para>
- Create a new directory, <literal>cd</literal> to it, then unzip and
- untar the archive. For the most part, you'll have to figure out where
- things go. <!-- FIXME, more info needed? -->
-</para>
-</sect3>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-os2"><title>OS/2</title>
<!-- ~~~~~ New section ~~~~~ -->
<sect3 id="installation-mac"><title>Mac OS X</title>
<para>
- Unzip the downloaded file (you can either double-click on the zip file
- icon from the Finder, or from the desktop if you downloaded it there).
- Then, double-click on the package installer icon and follow the
- installation process.
+ Installation instructions for the OS X platform depend upon whether
+ you downloaded a ready-built installation package (.pkg or .mpkg) or have
+ downloaded the source code.
</para>
+</sect3>
+<sect3 renderas="sect4" id="OS-X-install-from-package">
+<title>Installation from ready-built package</title>
<para>
- The privoxy service will automatically start after a successful
- installation (in addition to every time your computer starts up). To
- prevent the privoxy service from automatically starting when your
- computer starts up, remove or rename the folder named
- <literal>/Library/StartupItems/Privoxy</literal>.
+ The downloaded file will either be a .pkg (for OS X 10.5 upwards) or a bzipped
+ .mpkg file (for OS X 10.4). The former can be double-clicked as is and the
+ installation will start; double-clicking the latter will unzip the .mpkg file
+ which can then be double-clicked to commence the installation.
</para>
<para>
- To manually start or stop the privoxy service, use the Privoxy Utility
- for Mac OS X. This application controls the privoxy service (e.g.
- starting and stopping the service as well as uninstalling the software).
+ 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>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-amiga"><title>AmigaOS</title>
<para>
- Copy and then unpack the <filename>lha</filename> archive to a suitable location.
- All necessary files will be installed into <application>Privoxy</application>
- directory, including all configuration and log files. To uninstall, just
- remove this directory.
+ To manually start or stop the privoxy service, use the scripts startPrivoxy.sh
+ and stopPrivoxy.sh supplied in /Applications/Privoxy. They must be run from an
+ administrator account, using sudo.
+</para>
+<para>
+ To uninstall, run /Applications/Privoxy/uninstall.command as sudo from an
+ administrator account.
</para>
</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installation-tbz"><title>FreeBSD</title>
-
+<sect3 renderas="sect4" id="OS-X-install-from-source">
+<title>Installation from source</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>.
+ 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>
- If you don't use the ports, you can fetch and install
- the package with <literal>pkg_add -r privoxy</literal>.
+ 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>
- 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.
+ 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>
-</sect3>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect3 id="installattion-gentoo"><title>Gentoo</title>
<para>
- Gentoo source packages (Ebuilds) for <application>Privoxy</application> are
- contained in the Gentoo Portage Tree (they are not on the download page,
- but there is a Gentoo section, where you can see when a new
- <application>Privoxy</application> Version is added to the Portage Tree).
+ 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>
- Before installing <application>Privoxy</application> under Gentoo just do
- first <literal>emerge --sync</literal> to get the latest changes from the
- Portage tree. With <literal>emerge privoxy</literal> you install the latest
- version.
+ 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>
- Configuration files are in <filename>/etc/privoxy</filename>, the
- documentation is in <filename>/usr/share/doc/privoxy-&p-version;</filename>
- and the Log directory is in <filename>/var/log/privoxy</filename>.
+ 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-keepupdated"><title>Keeping your Installation Up-to-Date</title>
-<para>
- As user feedback comes in and development continues, we will make updated versions
- of both the main <link linkend="actions-file">actions file</link> (as a <ulink
- url="http://sourceforge.net/project/showfiles.php?group_id=11118&release_id=103670">separate
- package</ulink>) and the software itself (including the actions file) available for
- download.
-</para>
<para>
If you wish to receive an email notification whenever we release updates of
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="whatsnew">
<title>What's New in this Release</title>
+
+&changelog;
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect2 id="upgradersnote">
+<title>Note to Upgraders</title>
+
<para>
- <application>Privoxy 3.0.17</application> is a stable release.
- The changes since 3.0.16 stable are:
+ A quick list of things to be aware of before upgrading from earlier
+ versions of <application>Privoxy</application>:
</para>
<para>
<itemizedlist>
- <listitem>
- <para>
- Fixed last-chunk-detection for responses where the content was small
- enough to be read with the body, causing Privoxy to wait for the
- end of the content until the server closed the connection or the
- request timed out. Reported by "Karsten" in #3028326.
- </para>
- </listitem>
- <listitem>
- <para>
- Responses with status code 204 weren't properly detected as body-less
- like RFC2616 mandates. Like the previous bug, this caused Privoxy to
- wait for the end of the content until the server closed the connection
- or the request timed out. Fixes #3022042 and #3025553, reported by a
- user with no visible name. Most likely also fixes a bunch of other
- AJAX-related problem reports that got closed in the past due to
- insufficient information and lack of feedback.
- </para>
- </listitem>
- <listitem>
- <para>
- Fixed an ACL bug that made it impossible to build a blacklist.
- Usually the ACL directives are used in a whitelist, which worked
- as expected, but blacklisting is still useful for public proxies
- where one only needs to deny known abusers access.
- </para>
- </listitem>
- <listitem>
- <para>
- Added LOG_LEVEL_RECEIVED to log the not-yet-parsed data read from the
- network. This should make debugging various parsing issues a lot easier.
- </para>
- </listitem>
- <listitem>
- <para>
- The IPv6 code is enabled by default on Windows versions that support it.
- Patch submitted by oCameLo in #2942729.
- </para>
- </listitem>
- <listitem>
- <para>
- In mingw32 versions, the user.filter file is reachable through the
- GUI, just like default.filter is. Feature request 3040263.
- </para>
+
+ <listitem>
+ <para>
+ The recommended way to upgrade &my-app; is to backup your old
+ configuration files, install the new ones, verify that &my-app;
+ is working correctly and finally merge back your changes using
+ <application>diff</application> and maybe <application>patch</application>.
+ </para>
+ <para>
+ There are a number of new features in each &my-app; release and
+ most of them have to be explicitly enabled in the configuration
+ files. Old configuration files obviously don't do that and due
+ to syntax changes using old configuration files with a new
+ &my-app; isn't always possible anyway.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Note that some installers remove earlier versions completely,
+ including configuration files, therefore you should really save
+ any important configuration files!
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On the other hand, other installers don't overwrite existing configuration
+ files, thinking you will want to do that yourself.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the default configuration only fatal errors are logged now.
+ You can change that in the <link linkend="DEBUG">debug section</link>
+ of the configuration file. You may also want to enable more verbose
+ logging until you verified that the new &my-app; version is working
+ as expected.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Three other config file settings are now off by default:
+ <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
+ <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
+ and <link linkend="enable-edit-actions">enable-edit-actions</link>.
+ If you use or want these, you will need to explicitly enable them, and
+ be aware of the security issues involved.
+ </para>
</listitem>
+
+<!--
+ <listitem>
+ <para>
+ What constitutes a <quote>default</quote> configuration has changed,
+ and you may want to review which actions are <quote>on</quote> by
+ default. This is primarily a matter of emphasis, but some features
+ you may have been used to, may now be <quote>off</quote> by default.
+ There are also a number of new actions and filters you may want to
+ consider, most of which are not fully incorporated into the default
+ settings as yet (see above).
+ </para>
+ </listitem>
+-->
+<!--
<listitem>
<para>
- Added the configure option --enable-large-file-support to set a few
- defines that are required by platforms like GNU/Linux to support files
- larger then 2GB. Mainly interesting for users without proper logfile
- management.
+ The default actions setting is now <literal>Cautious</literal>. Previous
+ releases had a default setting of <literal>Medium</literal>. Experienced
+ users may want to adjust this, as it is fairly conservative by &my-app;
+ standards and past practices. See <ulink
+ url="http://config.privoxy.org/edit-actions-list?f=default">
+ http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
+ should try the default settings for a while before turning up the volume.
</para>
</listitem>
+
<listitem>
<para>
- Logging with "debug 16" no longer stops at the first nul byte which is
- pretty useless. Non-printable characters are replaced with their hex value
- so the result can't span multiple lines making parsing them harder then
- necessary.
+ The default setting has filtering turned <emphasis>off</emphasis>, which
+ subsequently means that compression is <emphasis>on</emphasis>. Remember
+ 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>
- </listitem>
- <listitem>
<para>
- Privoxy logs when reading an action, filter or trust file.
+ <screen>
+ { +<link linkend="filter">filter</link>{google} +<link linkend="prevent-compression">prevent-compression</link> }
+ .google.</screen>
</para>
- </listitem>
- <listitem>
<para>
- Fixed incorrect regression test markup which caused a test in
- 3.0.16 to fail while Privoxy itself was working correctly.
- While Privoxy accepts hide-referer, too, the action name is actually
- hide-referrer which is also the name used one the final results page,
- where the test expected the alias.
+ Or if you use a number of filters, or filter many sites, you may just want
+ to turn off compression for all sites in
+ <filename>default.action</filename> (or
+ <filename>user.action</filename>).
</para>
+
</listitem>
+
<listitem>
- <para>
- CGI interface improvements:
- <itemizedlist>
- <listitem>
- <para>
- In finish_http_response(), continue to add the 'Connection: close'
- header if the client connection will not be kept alive.
- Anonymously pointed out in #2987454.
- </para>
- </listitem>
- <listitem>
- <para>
- Apostrophes in block messages no longer cause parse errors
- when the blocked page is viewed with JavaScript enabled.
- Reported by dg1727 in #3062296.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix a bunch of anchors that used underscores instead of dashes.
- </para>
- </listitem>
- <listitem>
- <para>
- Allow to keep the client connection alive after crunching the previous request.
- Already opened server connections can be kept alive, too.
- </para>
- </listitem>
- <listitem>
- <para>
- In cgi_show_url_info(), don't forget to prefix URLs that only contain
- http:// or https:// in the path. Fixes #2975765 reported by Adam Piggott.
- </para>
- </listitem>
- <listitem>
- <para>
- Show the 404 CGI page if cgi_send_user_manual() is called while
- local user manual delivery is disabled.
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ <para>
+ Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is
+ off by default now. If you've liked this feature in the past, you may want
+ to turn it back on in <filename>user.action</filename> now.
+ </para>
</listitem>
+
+
<listitem>
- <para>
- Action file improvements:
- <itemizedlist>
- <listitem>
- <para>
- Enable user.filter by default. Suggested by David White in #3001830.
- </para>
- </listitem>
- <listitem>
- <para>
- Block .sitestat.com/. Reported by johnd16 in #3002725.
- </para>
- </listitem>
- <listitem>
- <para>
- Block .atemda.com/. Reported by johnd16 in #3002723.
- </para>
- </listitem>
- <listitem>
- <para>
- Block js.adlink.net/. Reported by johnd16 in #3002720.
- </para>
- </listitem>
- <listitem>
- <para>
- Block .analytics.yahoo.com/. Reported by johnd16 in #3002713.
- </para>
- </listitem>
- <listitem>
- <para>
- Block sb.scorecardresearch.com, too. Reported by dg1727 in #2992652.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix problems noticed on Yahoo mail and news pages.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove the too broad yahoo section, only keeping the
- fast-redirects exception as discussed on ijbswa-devel@.
- </para>
- </listitem>
- <listitem>
- <para>
- Don't block adesklets.sourceforge.net. Reported in #2974204.
- </para>
- </listitem>
- <listitem>
- <para>
- Block chartbeat ping tracking. Reported in #2975895.
- </para>
- </listitem>
- <listitem>
- <para>
- Tag CSS and image requests with cautious and medium settings, too.
- </para>
- </listitem>
- <listitem>
- <para>
- Don't handle view.atdmt.com as image. It's used for click-throughs
- so users should be able to "go there anyway".
- Reported by Adam Piggott in #2975927.
- </para>
- </listitem>
- <listitem>
- <para>
- Also let the refresh-tags filter remove invalid refresh tags where
- the 'url=' part is missing. Anonymously reported in #2986382.
- While at it, update the description to mention the fact that only
- refresh tags with refresh times above 9 seconds are covered.
- </para>
- </listitem>
- <listitem>
- <para>
- javascript needs to be blocked with +handle-as-empty-document to
- work around Firefox bug 492459. So move .js blockers from
- +block{Might be a web-bug.} -handle-as-empty-document to
- +block{Might be a web-bug.} +handle-as-empty-document.
- </para>
- </listitem>
- <listitem>
- <para>
- ijbswa-Feature Requests-3006719 - Block 160x578 Banners.
- </para>
- </listitem>
- <listitem>
- <para>
- Block another omniture tracking domain.
- </para>
- </listitem>
- <listitem>
- <para>
- Added a range-requests tagger.
- </para>
- </listitem>
- <listitem>
- <para>
- Added two sections to get Flickr's Ajax interface working with
- default pre-settings. If you change the configuration to block
- cookies by default, you'll need additional exceptions.
- Reported by Mathias Homann in #3101419 and by Patrick on ijbswa-users@.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Documentation improvements:
- <itemizedlist>
- <listitem>
- <para>
- Explicitly mention how to match all URLs.
- </para>
- </listitem>
- <listitem>
- <para>
- Consistently recommend socks5 in the Tor FAQ entry and mention
- its advantage compared to socks4a. Reported by David in #2960129.
- </para>
- </listitem>
- <listitem>
- <para>
- Slightly improve the explanation of why filtering may appear
- slower than it is.
- </para>
- </listitem>
- <listitem>
- <para>
- Grammar fixes for the ACL section.
- </para>
- </listitem>
- <listitem>
- <para>
- Fixed a link to the 'intercepting' entry and add another one.
- </para>
- </listitem>
- <listitem>
- <para>
- Rename the 'Other' section to 'Mailing Lists' and reword it
- to make it clear that nobody is forced to use the trackers
- </para>
- </listitem>
- <listitem>
- <para>
- Note that 'anonymously' posting on the trackers may not always
- be possible.
- </para>
- </listitem>
- <listitem>
- <para>
- Suggest to enable debug 32768 when suspecting parsing problems.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Privoxy-Log-Parser improvements:
- <itemizedlist>
- <listitem>
- <para>
- Gather statistics for ressources, methods, and HTTP versions
- used by the client.
- </para>
- </listitem>
- <listitem>
- <para>
- Also gather statistics for blocked and redirected requests.
- </para>
- </listitem>
- <listitem>
- <para>
- Provide the percentage of keep-alive offers the client accepted.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a --url-statistics-threshold option.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a --host-statistics-threshold option to also gather
- statistics about how many request where made per host.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix a bug in handle_loglevel_header() where a 'scan: ' got lost.
- </para>
- </listitem>
- <listitem>
- <para>
- Add a --shorten-thread-ids option to replace the thread id with
- a decimal number.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and ignore: Looks like we got the last chunk together
- with the server headers. We better stop reading.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and ignore: Continue hack in da house.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and higlight: Rejecting connection from 10.0.0.2.
- Maximum number of connections reached.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Loading actions file: /usr/local/etc/privoxy/default.action
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Loading filter file: /usr/local/etc/privoxy/default.filter
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Killed all-caps Host header line: HOST: bestproxydb.com
- </para>
- </listitem>
- <listitem>
- <para>
- Accept and highlight: Reducing expected bytes to 0. Marking
- the server socket tainted after throwing 4 bytes away.
- </para>
- </listitem>
- <listitem>
- <para>
- Accept: Merged multiple header lines to: 'X-FORWARDED-PROTO: http X-HOST: 127.0.0.1'
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Code cleanups:
- <itemizedlist>
- <listitem>
- <para>
- Remove the next member from the client_state struct. Only the main
- thread needs access to all client states so give it its own struct.
- </para>
- </listitem>
- <listitem>
- <para>
- Garbage-collect request_contains_null_bytes().
- </para>
- </listitem>
- <listitem>
- <para>
- Ditch redundant code in unload_configfile().
- </para>
- </listitem>
- <listitem>
- <para>
- Ditch LogGetURLUnderCursor() which doesn't seem to be used anywhere.
- </para>
- </listitem>
- <listitem>
- <para>
- In write_socket(), remove the write-only variable write_len in
- an ifdef __OS2__ block. Spotted by cppcheck.
- </para>
- </listitem>
- <listitem>
- <para>
- In connect_to(), don't declare the variable 'flags' on OS/2 where
- it isn't used. Spotted by cppcheck.
- </para>
- </listitem>
- <listitem>
- <para>
- Limit the scope of various variables. Spotted by cppcheck.
- </para>
- </listitem>
- <listitem>
- <para>
- In add_to_iob(), turn an interestingly looking for loop into a
- boring while loop.
- </para>
- </listitem>
- <listitem>
- <para>
- Code cleanup in preparation for external filters.
- </para>
- </listitem>
- <listitem>
- <para>
- In listen_loop(), mention the socket on which we accepted the
- connection, not just the source IP address.
- </para>
- </listitem>
- <listitem>
- <para>
- In write_socket(), also log the socket we're writing to.
- </para>
- </listitem>
- <listitem>
- <para>
- In log_error(), assert that escaped characters get logged
- completely or not at all.
- </para>
- </listitem>
- <listitem>
- <para>
- In log_error(), assert that ival and sval have reasonable values.
- There's no reason not to abort() if they don't.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove an incorrect cgi_error_unknown() call in a
- cannot-happen-situation in send_crunch_response().
- </para>
- </listitem>
- <listitem>
- <para>
- Clean up white-space in http_response definition and
- move the crunch_reason to the beginning.
- </para>
- </listitem>
- <listitem>
- <para>
- Turn http_response.reason into an enum and rename it
- to http_response.crunch_reason.
- </para>
- </listitem>
- <listitem>
- <para>
- Silence a 'gcc (Debian 4.3.2-1.1) 4.3.2' warning on i686 GNU/Linux.
- </para>
- </listitem>
- <listitem>
- <para>
- Fix white-space in a log message in remove_chunked_transfer_coding().
- While at it, add a note that the message doesn't seem to
- be entirely correct and should be improved later on.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- GNUmakefile improvements:
- <itemizedlist>
- <listitem>
- <para>
- Use $(SSH) instead of ssh, so one only needs to specify a username once.
- </para>
- </listitem>
- <listitem>
- <para>
- Removed references to the action feedback thingy that hasn't been
- working for years.
- </para>
- </listitem>
- <listitem>
- <para>
- Consistently use shell.sourceforge.net instead of shell.sf.net so
- one doesn't need to check server fingerprints twice.
- </para>
- </listitem>
- <listitem>
- <para>
- Removed GNUisms in the webserver and webactions targets so they
- work with standard tar.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
+ <para>
+ Some installers may not automatically start
+ <application>Privoxy</application> after installation.
+ </para>
+ </listitem>
+-->
+
</itemizedlist>
</para>
+</sect2>
+</sect1>
<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="upgradersnote">
-<title>Note to Upgraders</title>
-
-<para>
- A quick list of things to be aware of before upgrading from earlier
- versions of <application>Privoxy</application>:
-</para>
-
+<sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
<para>
<itemizedlist>
<listitem>
<para>
- The recommended way to upgrade &my-app; is to backup your old
- configuration files, install the new ones, verify that &my-app;
- is working correctly and finally merge back your changes using
- <application>diff</application> and maybe <application>patch</application>.
- </para>
- <para>
- There are a number of new features in each &my-app; release and
- most of them have to be explicitly enabled in the configuration
- files. Old configuration files obviously don't do that and due
- to syntax changes using old configuration files with a new
- &my-app; isn't always possible anyway.
- </para>
+ Install <application>Privoxy</application>. See the <link
+ linkend="installation">Installation Section</link> below for platform specific
+ information.
+ </para>
</listitem>
- <listitem>
- <para>
- Note that some installers remove earlier versions completely,
- including configuration files, therefore you should really save
- any important configuration files!
- </para>
- </listitem>
- <listitem>
- <para>
- On the other hand, other installers don't overwrite existing configuration
- 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.
- You can change that in the <link linkend="DEBUG">debug section</link>
- of the configuration file. You may also want to enable more verbose
- logging until you verified that the new &my-app; version is working
- as expected.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Three other config file settings are now off by default:
- <link linkend="enable-remote-toggle">enable-remote-toggle</link>,
- <link linkend="enable-remote-http-toggle">enable-remote-http-toggle</link>,
- and <link linkend="enable-edit-actions">enable-edit-actions</link>.
- If you use or want these, you will need to explicitly enable them, and
- be aware of the security issues involved.
- </para>
- </listitem>
-
-<!--
- <listitem>
- <para>
- What constitutes a <quote>default</quote> configuration has changed,
- and you may want to review which actions are <quote>on</quote> by
- default. This is primarily a matter of emphasis, but some features
- you may have been used to, may now be <quote>off</quote> by default.
- There are also a number of new actions and filters you may want to
- consider, most of which are not fully incorporated into the default
- settings as yet (see above).
- </para>
- </listitem>
--->
-<!--
- <listitem>
- <para>
- The default actions setting is now <literal>Cautious</literal>. Previous
- releases had a default setting of <literal>Medium</literal>. Experienced
- users may want to adjust this, as it is fairly conservative by &my-app;
- standards and past practices. See <ulink
- url="http://config.privoxy.org/edit-actions-list?f=default">
- http://config.privoxy.org/edit-actions-list?f=default</ulink>. New users
- should try the default settings for a while before turning up the volume.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The default setting has filtering turned <emphasis>off</emphasis>, which
- subsequently means that compression is <emphasis>on</emphasis>. Remember
- 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
- <filename>default.action</filename> (or
- <filename>user.action</filename>).
- </para>
-
- </listitem>
-
- <listitem>
- <para>
- Also, <link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> is
- off by default now. If you've liked this feature in the past, you may want
- to turn it back on in <filename>user.action</filename> now.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Some installers may not automatically start
- <application>Privoxy</application> after installation.
- </para>
- </listitem>
--->
-
- </itemizedlist>
-</para>
-
-</sect2>
-</sect1>
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="quickstart"><title>Quickstart to Using Privoxy</title>
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Install <application>Privoxy</application>. See the <link
- linkend="installation">Installation Section</link> below for platform specific
- information.
- </para>
- </listitem>
-
+
<listitem>
<para>
Advanced users and those who want to offer <application>Privoxy</application>
directory. Except on Win32 where it will try <filename>config.txt</filename>.
</para>
-<sect2 id="start-redhat">
-<title>Red Hat and Fedora</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
- file.
-</para>
-<para>
- <screen>
- # /etc/rc.d/init.d/privoxy start
-</screen>
-</para>
-<para>
- Or ...
-</para>
-<para>
- <screen>
- # service privoxy start
-</screen>
-</para>
-</sect2>
-
<sect2 id="start-debian">
<title>Debian</title>
<para>
</sect2>
-<sect2 id="start-amigaos">
-<title>AmigaOS</title>
-<para>
- Start <application>Privoxy</application> (with RUN <>NIL:) in your
- <filename>startnet</filename> script (AmiTCP), in
- <filename>s:user-startup</filename> (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- <application>Privoxy</application> will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- <application>Privoxy</application> is still running).
-</para>
-</sect2>
-
-<sect2 id="start-gentoo">
-<title>Gentoo</title>
-<para>
- A script is again used. It will use the file <filename>/etc/privoxy/config
- </filename> as its main configuration file.
-</para>
-<para>
- <screen>
- /etc/init.d/privoxy start
- </screen>
-</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>
-
<!--
<para>
<para>
<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>--config-test</emphasis>
+ </para>
+ <para>
+ Exit after loading the configuration files before binding to
+ the listen address. The exit code signals whether or not the
+ configuration files have been successfully loaded.
+ </para>
+ <para>
+ If the exit code is 1, at least one of the configuration files
+ is invalid, if it is 0, all the configuration files have been
+ successfully loaded (but may still contain errors that can
+ currently only be detected at run time).
+ </para>
+ <para>
+ This option doesn't affect the log setting, combination with
+ <emphasis>--no-daemon</emphasis> is recommended if a configured
+ log file shouldn't be used.
+ </para>
+ </listitem>
<listitem>
<para>
<emphasis>--version</emphasis>
<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>
<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>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 id="negative-tag-patterns"><title>The Negative Tag Patterns</title>
+
+<para>
+ To match requests that do not have a certain 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 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>
+
+
</sect2>
<!-- ~ End section ~ -->
and use their output as input.
</para>
<para>
- If the request URL gets changed, &my-app; will detect that and use the new
+ If the request URI gets changed, &my-app; will detect that and use the new
one. This can be used to rewrite the request destination behind the client's
back, for example to specify a Tor exit relay for certain requests.
</para>
{+client-header-filter{hide-tor-exit-notation}}
/
</screen>
- </para>
+ </para>
</listitem>
</varlistentry>
TAG:^User-Agent: Ubuntu APT-HTTP/
TAG:^User-Agent: MPlayer/
</screen>
+ </para>
+ <para>
+ <screen>
+# Tag all requests with the Range header set
+{+client-header-tagger{range-requests}}
+/
+
+# Disable filtering for the tagged requests.
+#
+# With filtering enabled Privoxy would remove the Range headers
+# to be able to filter the whole response. The downside is that
+# it prevents clients from resuming downloads or skipping over
+# parts of multimedia files.
+{-filter -deanimate-gifs}
+TAG:^RANGE-REQUEST$
+ </screen>
</para>
</listitem>
</varlistentry>
<para>
This is a left-over from the time when <application>Privoxy</application>
didn't support important HTTP/1.1 features well. It is left here for the
- unlikely case that you experience HTTP/1.1 related problems with some server
- out there. Not all HTTP/1.1 features and requirements are supported yet,
- so there is a chance you might need this action.
+ unlikely case that you experience HTTP/1.1-related problems with some server
+ out there.
+ </para>
+ <para>
+ Note that enabling this action is only a workaround. It should not
+ be enabled for sites that work without it. While it shouldn't break
+ any pages, it has an (usually negative) performance impact.
+ </para>
+ <para>
+ If you come across a site where enabling this action helps, please report it,
+ so the cause of the problem can be analyzed. If the problem turns out to be
+ caused by a bug in <application>Privoxy</application> it should be
+ fixed so the following release works without the work around.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="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>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The name of an external content filter, as defined in the
+ <link linkend="filter-file">filter file</link>.
+ External filters can be defined in one or more files as defined by the
+ <literal><link linkend="filterfile">filterfile</link></literal>
+ option in the <link linkend="config">config file</link>.
+ </para>
+ <para>
+ When used in its negative form,
+ and without parameters, <emphasis>all</emphasis> filtering with external
+ filters is completely disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ External filters are scripts or programs that can modify the content in
+ case common <literal><link linkend="filter">filters</link></literal>
+ aren't powerful enough. With the exception that this action doesn't
+ use pcrs-based filters, the notes in the
+ <literal><link linkend="filter">filter</link></literal> section apply.
+ </para>
+ <warning>
+ <para>
+ Currently external filters are executed with &my-app;'s privileges.
+ Only use external filters you understand and trust.
+ </para>
+ </warning>
+ <para>
+ This feature is experimental, the <literal><link
+ linkend="external-filter-syntax">syntax</link></literal>
+ may change in the future.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usage:</term>
+ <listitem>
+ <para>
+ <screen>+external-filter{fancy-filter}</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect3 renderas="sect4" id="fast-redirects">
<title>fast-redirects</title>
</para>
<para>
<anchor id="filter-js-events">
- <screen>+filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
+ <screen>+filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).</screen>
</para>
<para>
<anchor id="filter-html-annoyances">
</para>
<para>
<anchor id="filter-refresh-tags">
- <screen>+filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).</screen>
+ <screen>+filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds.</screen>
</para>
<para>
<anchor id="filter-unsolicited-popups">
- <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.</screen>
+ <screen>+filter{unsolicited-popups} # Disable only unsolicited pop-up windows.</screen>
</para>
<para>
<anchor id="filter-all-popups">
- <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.</screen>
+ <screen>+filter{all-popups} # Kill all popups in JavaScript and HTML.</screen>
</para>
<para>
<anchor id="filter-img-reorder">
<anchor id="filter-frameset-borders">
<screen>+filter{frameset-borders} # Give frames a border and make them resizable.</screen>
</para>
+ <para>
+ <anchor id="filter-iframes">
+ <screen>+filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites.</screen>
+ </para>
<para>
<anchor id="filter-demoronizer">
<screen>+filter{demoronizer} # Fix MS's non-standard use of standard charsets.</screen>
</variablelist>
</sect3>
+
<!-- ~~~~~ New section ~~~~~ -->
-<sect3 renderas="sect4" id="prevent-compression">
+<sect3 renderas="sect4" id="limit-cookie-lifetime">
+<title>limit-cookie-lifetime</title>
+
+<variablelist>
+ <varlistentry>
+ <term>Typical use:</term>
+ <listitem>
+ <para>Limit the lifetime of HTTP cookies to a couple of minutes or hours.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Effect:</term>
+ <listitem>
+ <para>
+ Overwrites the expires field in Set-Cookie server headers if it's above the specified limit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Type:</term>
+ <!-- Boolean, Parameterized, Multi-value -->
+ <listitem>
+ <para>Parameterized.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Parameter:</term>
+ <listitem>
+ <para>
+ The lifetime limit in minutes, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This action reduces the lifetime of HTTP cookies coming from the
+ server to the specified number of minutes, starting from the time
+ the cookie passes Privoxy.
+ </para>
+ <para>
+ Cookies with a lifetime below the limit are not modified.
+ The lifetime of session cookies is set to the specified limit.
+ </para>
+ <para>
+ The effect of this action depends on the server.
+ </para>
+ <para>
+ In case of servers which refresh their cookies with each response
+ (or at least frequently), the lifetime limit set by this action
+ is updated as well.
+ Thus, a session associated with the cookie continues to work with
+ this action enabled, as long as a new request is made before the
+ last limit set is reached.
+ </para>
+ <para>
+ However, some servers send their cookies once, with a lifetime of several
+ years (the year 2037 is a popular choice), and do not refresh them
+ until a certain event in the future, for example the user logging out.
+ In this case this action may limit the absolute lifetime of the session,
+ even if requests are made frequently.
+ </para>
+ <para>
+ If the parameter is <quote>0</quote>, this action behaves like
+ <literal><link linkend="session-cookies-only">session-cookies-only</link></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Example usages:</term>
+ <listitem>
+ <para>
+ <screen>+limit-cookie-lifetime{60}
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="prevent-compression">
<title>prevent-compression</title>
<variablelist>
single pcrs command to the original URL.
</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
+ The syntax for pcrs commands is documented in the
+ <link linkend="filter-file">filter file</link> section.
+ </para>
+ <para>
+ Requests can't be blocked and redirected at the same time,
+ applying this action together with
+ <literal><link linkend="block">block</link></literal>
+ is a configuration error. Currently the request is blocked
+ and an error message logged, the behavior may change in the
+ future and result in Privoxy rejecting the action file.
+ </para>
+ <para>
+ This action can be combined with
<literal><link linkend="fast-redirects">fast-redirects{check-decoded-url}</link></literal>
to redirect to a decoded version of a rewritten URL.
</para>
example.com/stylesheet\.css
# Create a short, easy to remember nickname for a favorite site
-# (relies on the browser accept and forward invalid URLs to &my-app;)
+# (relies on the browser to accept and forward invalid URLs to &my-app;)
{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
a
{+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@}}
# Tag every request with the content type declared by the server
{+server-header-tagger{content-type}}
/
+
+# If the response has a tag starting with 'image/' enable an external
+# filter that only applies to images.
+#
+# Note that the filter is not available by default, it's just a
+# <literal><link linkend="external-filter-syntax">silly example</link></literal>.
+{+external-filter{rotate-image} +force-text-mode}
+TAG:^image/
</screen>
</para>
</listitem>
</para>
<para>
- &my-app; supports three different filter actions:
+ &my-app; supports three different pcrs-based filter actions:
<literal><link linkend="filter">filter</link></literal> to
rewrite the content that is send to the client,
<literal><link linkend="client-header-filter">client-header-filter</link></literal>
applying actions through sections with <link linkend="tag-pattern">tag-patterns</link>.
</para>
+<para>
+ Finally &my-app; supports the
+ <literal><link linkend="external-filter">external-filter</link></literal> action
+ to enable <literal><link linkend="external-filter-syntax">external filters</link></literal>
+ written in proper programming languages.
+</para>
+
<para>
Multiple filter files can be defined through the <literal> <link
in a syntax that imitates <ulink url="http://www.perl.org/">Perl</ulink>'s
<literal>s///</literal> operator. If you are familiar with Perl, you
will find this to be quite intuitive, and may want to look at the
- PCRS documentation for the subtle differences to Perl behaviour. Most
- notably, the non-standard option letter <literal>U</literal> is supported,
- which turns the default to ungreedy matching.
+ PCRS documentation for the subtle differences to Perl behaviour.
+</para>
+
+<para>
+ Most notably, the non-standard option letter <literal>U</literal> is supported,
+ which turns the default to ungreedy matching (add <literal>?</literal> to
+ quantifiers to turn them greedy again).
+</para>
+
+<para>
+ The non-standard option letter <literal>D</literal> (dynamic) allows
+ to use the variables $host, $origin (the IP address the request came from),
+ $path and $url. 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>
</varlistentry>
<varlistentry>
- <term><emphasis>refresh tags</emphasis></term>
+ <term><emphasis>refresh-tags</emphasis></term>
<listitem>
<para>
Disable any refresh tags if the interval is greater than nine seconds (so
</listitem>
</varlistentry>
-->
-</variablelist>
-
-</sect2>
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect1 id="templates">
-<title>Privoxy's Template Files</title>
-<para>
- All <application>Privoxy</application> built-in pages, i.e. error pages such as the
- <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
- error page</ulink>, the <ulink
- url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
- page</ulink>
- and all pages of its <ulink url="http://config.privoxy.org/">web-based
- user interface</ulink>, are generated from <emphasis>templates</emphasis>.
- (<application>Privoxy</application> must be running for the above links to work as
- intended.)
-</para>
-
-<para>
- These templates are stored in a subdirectory of the <link linkend="confdir">configuration
- directory</link> called <filename>templates</filename>. On Unixish platforms,
- this is typically
- <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
-</para>
-
-<para>
- The templates are basically normal HTML files, but with place-holders (called symbols
- or exports), which <application>Privoxy</application> fills at run time. It
- is possible to edit the templates with a normal text editor, should you want
- to customize them. (<emphasis>Not recommended for the casual
- user</emphasis>). Should you create your own custom templates, you should use
- the <filename>config</filename> setting <link linkend="templdir">templdir</link>
- to specify an alternate location, so your templates do not get overwritten
- during upgrades.
- </para>
- <para>
- Note that just like in configuration files, lines starting
- with <literal>#</literal> are ignored when the templates are filled in.
-</para>
-
-<para>
- The place-holders are of the form <literal>@name@</literal>, and you will
- find a list of available symbols, which vary from template to template,
- in the comments at the start of each file. Note that these comments are not
- always accurate, and that it's probably best to look at the existing HTML
- code to find out which symbols are supported and what they are filled in with.
-</para>
-
-<para>
- A special application of this substitution mechanism is to make whole
- blocks of HTML code disappear when a specific symbol is set. We use this
- for many purposes, one of them being to include the beta warning in all
- our user interface (CGI) pages when <application>Privoxy</application>
- 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
- <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
- 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>
- mechanism, but you'll sure find out if you are inclined to edit the
- templates ;-)
-</para>
-
-<para>
- All templates refer to a style located at
- <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
- This is, of course, locally served by <application>Privoxy</application>
- and the source for it can be found and edited in the
- <filename>cgi-style.css</filename> template.
-</para>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
-Requests</title>
-
-<!-- Include contacting.sgml boilerplate: -->
- &contacting;
-<!-- end boilerplate -->
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
-
-<!-- Include copyright.sgml: -->
- ©right;
-<!-- end copyright -->
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2><title>License</title>
-<!-- Include copyright.sgml: -->
- &license;
-<!-- end copyright -->
-</sect2>
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-
-<sect2 id="history"><title>History</title>
-<!-- Include history.sgml: -->
- &history;
-<!-- end history -->
-</sect2>
-
-<sect2 id="authors"><title>Authors</title>
-<!-- Include p-authors.sgml: -->
- &p-authors;
-<!-- end authors -->
-</sect2>
-
-</sect1>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="seealso"><title>See Also</title>
-<!-- Include seealso.sgml: -->
- &seealso;
-<!-- end seealso -->
-</sect1>
-
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="appendix"><title>Appendix</title>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="regex">
-<title>Regular Expressions</title>
-<para>
- <application>Privoxy</application> uses Perl-style <quote>regular
- expressions</quote> in its <link linkend="actions-file">actions
- files</link> and <link linkend="filter-file">filter file</link>,
- through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
-<!--
- dead 08/27/06
- <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
--->
- <application>PCRS</application> libraries.
-</para>
-
-<para>
- If you are reading this, you probably don't understand what <quote>regular
- expressions</quote> are, or what they can do. So this will be a very brief
- introduction only. A full explanation would require a <ulink
- url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
-</para>
-
-<para>
- Regular expressions provide a language to describe patterns that can be
- run against strings of characters (letter, numbers, etc), to see if they
- match the string or not. The patterns are themselves (sometimes complex)
- strings of literal characters, combined with wild-cards, and other special
- characters, called meta-characters. The <quote>meta-characters</quote> have
- special meanings and are used to build complex patterns to be matched against.
- Perl Compatible Regular Expressions are an especially convenient
- <quote>dialect</quote> of the regular expression language.
-</para>
-
-<para>
- To make a simple analogy, we do something similar when we use wild-card
- characters when listing files with the <command>dir</command> command in DOS.
- <literal>*.*</literal> matches all filenames. The <quote>special</quote>
- character here is the asterisk which matches any and all characters. We can be
- more specific and use <literal>?</literal> to match just individual
- characters. So <quote>dir file?.text</quote> would match
- <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
- matching, using a similar technique to <quote>regular expressions</quote>!
-</para>
-
-<para>
- Regular expressions do essentially the same thing, but are much, much more
- powerful. There are many more <quote>special characters</quote> and ways of
- building complex patterns however. Let's look at a few of the common ones,
- and then some examples:
-</para>
-
-<para><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>
-
-<para><simplelist>
- <member>
- <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
- times. Either/or.
- </member>
-</simplelist></para>
-
-<para><simplelist>
- <member>
- <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
- times.
- </member>
-</simplelist></para>
-
-<para><simplelist>
- <member>
- <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
- times.
- </member>
-</simplelist></para>
-
-<para><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
- special characters (e.g. <quote>.</quote>) needs to be taken literally and
- not as a special meta-character. Example: <quote>example\.com</quote>, makes
- sure the period is recognized only as a period (and not expanded to its
- meta-character meaning of any single character).
- </member>
-</simplelist></para>
-
-<para><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>
-
-<para><simplelist>
- <member>
- <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
- or multiple sub-expressions.
- </member>
-</simplelist></para>
-
-<para><simplelist>
- <member>
- <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
- <quote>or</quote> conditional statement. A match is successful if the
- sub-expression on either side of <quote>|</quote> matches. As an example:
- <quote>/(this|that) example/</quote> uses grouping and the bar character
- and would match either <quote>this example</quote> or <quote>that
- example</quote>, and nothing else.
- </member>
-</simplelist></para>
-
-<para>
- These are just some of the ones you are likely to use when matching URLs with
- <application>Privoxy</application>, and is a long way from a definitive
- list. This is enough to get us started with a few simple examples which may
- be more illuminating:
-</para>
-
-<para>
- <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
- that uses the common combination of <quote>.</quote> and <quote>*</quote> to
- denote any character, zero or more times. In other words, any string at all.
- So we start with a literal forward slash, then our regular expression pattern
- (<quote>.*</quote>) another literal forward slash, the string
- <quote>banners</quote>, another forward slash, and lastly another
- <quote>.*</quote>. We are building
- a directory path here. This will match any file with the path that has a
- directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
- any characters, and this could conceivably be more forward slashes, so it
- might expand into a much longer looking path. For example, this could match:
- <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
- <quote>/banners/annoying.html</quote>, or almost an infinite number of other
- possible combinations, just so it has <quote>banners</quote> in the path
- somewhere.
-</para>
-
-<para>
- And now something a little more complex:
-</para>
-
-<para>
- <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
- We have several literal forward slashes again (<quote>/</quote>), so we are
- building another expression that is a file path statement. We have another
- <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
- it matches our expression. The only true literal that <emphasis>must
- match</emphasis> our pattern is <application>adv</application>, together with
- the forward slashes. What comes after the <quote>adv</quote> string is the
- interesting part.
-</para>
-
-<para>
- Remember the <quote>?</quote> means the preceding expression (either a
- literal character or anything grouped with <quote>(...)</quote> in this case)
- can exist or not, since this means either zero or one match. So
- <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
- individual sub-expressions: <quote>(er)</quote>,
- <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
- means <quote>or</quote>. We have two of those. For instance,
- <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
- <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
- attempt at matching as many variations of <quote>advertisement</quote>, and
- similar, as possible. So this would expand to match just <quote>adv</quote>,
- or <quote>advert</quote>, or <quote>adverts</quote>, or
- <quote>advertising</quote>, or <quote>advertisement</quote>, or
- <quote>advertisements</quote>. You get the idea. But it would not match
- <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
- changing our regular expression to:
- <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
- either spelling.
-</para>
-
-<para>
- <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
- another path statement with forward slashes. Anything in the square brackets
- <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
- shorthand expression to mean any digit one through nine. It is the same as
- saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
- means one or more of the preceding expression must be included. The preceding
- expression here is what is in the square brackets -- in this case, any digit
- one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
- This includes a <quote>|</quote>, so this needs to match the expression on
- either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
- side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
- since the <quote>?</quote> means the letter <quote>e</quote> is optional and
- can be matched once or not at all. So we are building an expression here to
- match image GIF or JPEG type image file. It must include the literal
- string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
- (which is now a literal, and not a special character, since it is escaped
- with <quote>\</quote>), and lastly either <quote>gif</quote>, or
- <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
- include: <quote>//advert1.jpg</quote>,
- <quote>/nasty/ads/advert1234.gif</quote>,
- <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
- <quote>advert1.gif</quote> (no leading slash), or
- <quote>/adverts232.jpg</quote> (the expression does not include an
- <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
- in the expression anywhere).
-</para>
-
-<para>
- We are barely scratching the surface of regular expressions here so that you
- can understand the default <application>Privoxy</application>
- configuration files, and maybe use this knowledge to customize your own
- installation. There is much, much more that can be done with regular
- expressions. Now that you know enough to get started, you can learn more on
- your own :/
-</para>
-
-<para>
- More reading on Perl Compatible Regular expressions:
- <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
-</para>
-
-<para>
- For information on regular expression based substitutions and their applications
- in filters, please see the <link linkend="filter-file">filter file tutorial</link>
- in this manual.
-</para>
-</sect2>
-
-<!-- ~ End section ~ -->
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2>
-<title>Privoxy's Internal Pages</title>
-
-<para>
- Since <application>Privoxy</application> proxies each requested
- web page, it is easy for <application>Privoxy</application> to
- trap certain special URLs. In this way, we can talk directly to
- <application>Privoxy</application>, and see how it is
- configured, see how our rules are being applied, change these
- rules and other configuration options, and even turn
- <application>Privoxy's</application> filtering off, all with
- a web browser.
-
-</para>
-
-<para>
- The URLs listed below are the special ones that allow direct access
- to <application>Privoxy</application>. Of course,
- <application>Privoxy</application> must be running to access these. If
- not, you will get a friendly error message. Internet access is not
- necessary either.
-</para>
-
-<para>
- <itemizedlist>
-
- <listitem>
- <para>
- Privoxy main page:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
- </para>
- </blockquote>
- <para>
- There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
- doesn't provide a fall-back to a real page, in case the request is not
- sent through <application>Privoxy</application>)
- </para>
- </listitem>
-
- <listitem>
- <para>
- Show information about the current configuration, including viewing and
- editing of actions files:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
- </para>
- </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:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
- </para>
- </blockquote>
- </listitem>
-
- <listitem>
- <para>
- Show which actions apply to a URL and why:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
- </para>
- </blockquote>
- </listitem>
-
- <listitem>
- <para>
- Toggle Privoxy on or off. This feature can be turned off/on in the main
- <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
- continues to run, but only as a pass-through proxy, with no actions taking
- place:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
- </para>
- </blockquote>
- <para>
- Short cuts. Turn off, then on:
- </para>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
- </para>
- </blockquote>
- <blockquote>
- <para>
- <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
- </para>
- </blockquote>
- </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>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="chain">
-<title>Chain of Events</title>
-<para>
- Let's take a quick look at how some of <application>Privoxy's</application>
- core features are triggered, and the ensuing sequence of events when a web
- page is requested by your browser:
-</para>
-
-<para>
- <itemizedlist>
- <listitem>
- <para>
- First, your web browser requests a web page. The browser knows to send
- the request to <application>Privoxy</application>, which will in turn,
- relay the request to the remote web server after passing the following
- tests:
- </para>
- </listitem>
- <listitem>
- <para>
- <application>Privoxy</application> traps any request for its own internal CGI
- pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
- </para>
- </listitem>
- <listitem>
- <para>
- Next, <application>Privoxy</application> checks to see if the URL
- matches any <link
- linkend="BLOCK"><quote>+block</quote></link> patterns. If
- so, the URL is then blocked, and the remote web server will not be contacted.
- <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
- and
- <link linkend="HANDLE-AS-EMPTY-DOCUMENT"><quote>+handle-as-empty-document</quote></link>
- are then checked, and if there is no match, an
- HTML <quote>BLOCKED</quote> page is sent back to the browser. Otherwise, if
- it does match, an image is returned for the former, and an empty text
- document for the latter. The type of image would depend on the setting of
- <link linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
- (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
- </para>
- </listitem>
- <listitem>
- <para>
- Untrusted URLs are blocked. If URLs are being added to the
- <filename>trust</filename> file, then that is done.
- </para>
- </listitem>
- <listitem>
- <para>
- If the URL pattern matches the <link
- linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
- it is then processed. Unwanted parts of the requested URL are stripped.
- </para>
- </listitem>
- <listitem>
- <para>
- Now the rest of the client browser's request headers are processed. If any
- of these match any of the relevant actions (e.g. <link
- linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
- etc.), headers are suppressed or forged as determined by these actions and
- their parameters.
- </para>
- </listitem>
- <listitem>
- <para>
- Now the web server starts sending its response back (i.e. typically a web
- page).
- </para>
- </listitem>
- <listitem>
- <para>
- First, the server headers are read and processed to determine, among other
- things, the MIME type (document type) and encoding. The headers are then
- filtered as determined by the
- <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
- <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
- and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
- actions.
- </para>
- </listitem>
- <listitem>
- <para>
- If any <link linkend="FILTER"><quote>+filter</quote></link> action
- or <link
- linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
- action applies (and the document type fits the action), the rest of the page is
- read into memory (up to a configurable limit). Then the filter rules (from
- <filename>default.filter</filename> and any other filter files) are
- processed against the buffered content. Filters are applied in the order
- they are specified in one of the filter files. Animated GIFs, if present,
- are reduced to either the first or last frame, depending on the action
- setting.The entire page, which is now filtered, is then sent by
- <application>Privoxy</application> back to your browser.
- </para>
- <para>
- If neither a <link linkend="FILTER"><quote>+filter</quote></link> action
- or <link
- linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
- matches, then <application>Privoxy</application> passes the raw data through
- to the client browser as it becomes available.
- </para>
- </listitem>
- <listitem>
- <para>
- As the browser receives the now (possibly filtered) page content, it
- reads and then requests any URLs that may be embedded within the page
- source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
- frames), sounds, etc. For each of these objects, the browser issues a
- separate request (this is easily viewable in <application>Privoxy's</application>
- logs). And each such request is in turn processed just as above. Note that a
- complex web page will have many, many such embedded URLs. If these
- secondary requests are to a different server, then quite possibly a very
- differing set of actions is triggered.
- </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
- <application>Privoxy's</application> core features only.
-</para>
-
-</sect2>
-
-
-<!-- ~~~~~ New section ~~~~~ -->
-<sect2 id="actionsanat">
-<title>Troubleshooting: Anatomy of an Action</title>
-
-<para>
- The way <application>Privoxy</application> applies
- <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
- to any given URL can be complex, and not always so
- easy to understand what is happening. And sometimes we need to be able to
- <emphasis>see</emphasis> just what <application>Privoxy</application> is
- doing. Especially, if something <application>Privoxy</application> is doing
- is causing us a problem inadvertently. It can be a little daunting to look at
- the actions and filters files themselves, since they tend to be filled with
- <link linkend="regex">regular expressions</link> whose consequences are not
- always so obvious.
-</para>
-
-<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
- 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>.)
-</para>
-<para>
- Another easy troubleshooting step to try is if you have done any
- customization of your installation, revert back to the installed
- defaults and see if that helps. There are times the developers get complaints
- about one thing or another, and the problem is more related to a customized
- configuration issue.
-</para>
-
-<para>
- <application>Privoxy</application> also provides the
- <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
- page that can show us very specifically how <application>actions</application>
- are being applied to any given URL. This is a big help for troubleshooting.
-</para>
-
-<para>
- First, enter one URL (or partial URL) at the prompt, and then
- <application>Privoxy</application> will tell us
- how the current configuration will handle it. This will not
- help with filtering effects (i.e. the <link
- linkend="FILTER"><quote>+filter</quote></link> action) from
- one of the filter files since this is handled very
- differently and not so easy to trap! It also will not tell you about any other
- URLs that may be embedded within the URL you are testing. For instance, images
- such as ads are expressed as URLs within the raw page source of HTML pages. So
- you will only get info for the actual URL that is pasted into the prompt area
- -- not any sub-URLs. If you want to know about embedded URLs like ads, you
- will have to dig those out of the HTML source. Use your browser's <quote>View
- Page Source</quote> option for this. Or right click on the ad, and grab the
- URL.
-</para>
-
-<para>
- Let's try an example, <ulink url="http://google.com">google.com</ulink>,
- and look at it one section at a time in a sample configuration (your real
- configuration may vary):
-</para>
-
-<para>
- <screen>
- Matches for http://www.google.com:
-
- In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
-
- {+change-x-forwarded-for{block}
- +deanimate-gifs {last}
- +fast-redirects {check-decoded-url}
- +filter {refresh-tags}
- +filter {img-reorder}
- +filter {banners-by-size}
- +filter {webbugs}
- +filter {jumping-windows}
- +filter {ie-exploits}
- +hide-from-header {block}
- +hide-referrer {forge}
- +session-cookies-only
- +set-image-blocker {pattern}
-/
-
- { -session-cookies-only }
- .google.com
-
- { -fast-redirects }
- .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
- <link linkend="ACTIONS"><quote>actions</quote></link>, and
- which ones match for our test case, <quote>google.com</quote>.
- Displayed is all the actions that are available to us. Remember,
- the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
- denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
- are <quote>off</quote>. Each example we try may provide a slightly different
- end result, depending on our configuration directives.
-</para>
-<para>
- The first listing
- is for our <filename>default.action</filename> file. The large, multi-line
- listing, is how the actions are set to match for all URLs, i.e. our default
- settings. If you look at your <quote>actions</quote> file, this would be the
- section just below the <quote>aliases</quote> section near the top. This
- will apply to all URLs as signified by the single forward slash at the end
- of the listing -- <quote> / </quote>.
-</para>
-
-<para>
- But we have defined additional actions that would be exceptions to these general
- rules, and then we list specific URLs (or patterns) that these exceptions
- would apply to. Last match wins. Just below this then are two explicit
- matches for <quote>.google.com</quote>. The first is negating our previous
- cookie setting, which was for <link
- linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
- (i.e. not persistent). So we will allow persistent cookies for google, at
- least that is how it is in this example. The second turns
- <emphasis>off</emphasis> any <link
- linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
- action, allowing this to take place unmolested. Note that there is a leading
- dot here -- <quote>.google.com</quote>. This will match any hosts and
- sub-domains, in the google.com domain also, such as
- <quote>www.google.com</quote> or <quote>mail.google.com</quote>. But it would not
- match <quote>www.google.de</quote>! So, apparently, we have these two actions
- defined as exceptions to the general rules at the top somewhere in the lower
- part of our <filename>default.action</filename> file, and
- <quote>google.com</quote> is referenced somewhere in these latter sections.
-</para>
-
-<para>
- Then, for our <filename>user.action</filename> file, we again have no hits.
- So there is nothing google-specific that we might have added to our own, local
- configuration. If there was, those actions would over-rule any actions from
- previously processed files, such as <filename>default.action</filename>.
- <filename>user.action</filename> typically has the last word. This is the
- best place to put hard and fast exceptions,
-</para>
-
-<para>
- 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
- -block
- +change-x-forwarded-for{block}
- -client-header-filter{hide-tor-exit-notation}
- -content-type-overwrite
- -crunch-client-header
- -crunch-if-none-match
- -crunch-incoming-cookies
- -crunch-outgoing-cookies
- -crunch-server-header
- +deanimate-gifs {last}
- -downgrade-http-version
- -fast-redirects
- -filter {js-events}
- -filter {content-cookies}
- -filter {all-popups}
- -filter {banners-by-link}
- -filter {tiny-textforms}
- -filter {frameset-borders}
- -filter {demoronizer}
- -filter {shockwave-flash}
- -filter {quicktime-kioskmode}
- -filter {fun}
- -filter {crude-parental}
- -filter {site-specifics}
- -filter {js-annoyances}
- -filter {html-annoyances}
- +filter {refresh-tags}
- -filter {unsolicited-popups}
- +filter {img-reorder}
- +filter {banners-by-size}
- +filter {webbugs}
- +filter {jumping-windows}
- +filter {ie-exploits}
- -filter {google}
- -filter {yahoo}
- -filter {msn}
- -filter {blogspot}
- -filter {no-ping}
- -force-text-mode
- -handle-as-empty-document
- -handle-as-image
- -hide-accept-language
- -hide-content-disposition
- +hide-from-header {block}
- -hide-if-modified-since
- +hide-referrer {forge}
- -hide-user-agent
- -limit-connect
- -overwrite-last-modified
- -prevent-compression
- -redirect
- -server-header-filter{xml-to-html}
- -server-header-filter{html-to-xml}
- -session-cookies-only
- +set-image-blocker {pattern} </screen>
-</para>
-
-<para>
- Notice the only difference here to the previous listing, is to
- <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
- which are activated specifically for this site in our configuration,
- and thus show in the <quote>Final Results</quote>.
-</para>
-
-<para>
- Now another example, <quote>ad.doubleclick.net</quote>:
-</para>
-
-<para>
- <screen>
-
- { +block{Domains starts with "ad"} }
- ad*.
-
- { +block{Domain contains "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
- matched three different times. Two <quote>+block{}</quote> sections,
- and a <quote>+block{} +handle-as-image</quote>,
- which is the expanded form of one of our aliases that had been defined as:
- <quote>+block-as-image</quote>. (<link
- linkend="ALIASES"><quote>Aliases</quote></link> are defined in
- the first section of the actions file and typically used to combine more
- than one action.)
-</para>
-
-<para>
- Any one of these would have done the trick and blocked this as an unwanted
- image. This is unnecessarily redundant since the last case effectively
- would also cover the first. No point in taking chances with these guys
- though ;-) Note that if you want an ad or obnoxious
- URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
- is done here -- as both a <link
- linkend="BLOCK"><quote>+block{}</quote></link>
- <emphasis>and</emphasis> an
- <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
- The custom alias <quote><literal>+block-as-image</literal></quote> just
- simplifies the process and make it more readable.
-</para>
-
-<para>
- One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
- 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>
-
- {-add-header
- -block
- +change-x-forwarded-for{block}
- -client-header-filter{hide-tor-exit-notation}
- -content-type-overwrite
- -crunch-client-header
- -crunch-if-none-match
- -crunch-incoming-cookies
- -crunch-outgoing-cookies
- -crunch-server-header
- +deanimate-gifs
- -downgrade-http-version
- +fast-redirects {check-decoded-url}
- -filter {js-events}
- -filter {content-cookies}
- -filter {all-popups}
- -filter {banners-by-link}
- -filter {tiny-textforms}
- -filter {frameset-borders}
- -filter {demoronizer}
- -filter {shockwave-flash}
- -filter {quicktime-kioskmode}
- -filter {fun}
- -filter {crude-parental}
- -filter {site-specifics}
- -filter {js-annoyances}
- -filter {html-annoyances}
- +filter {refresh-tags}
- -filter {unsolicited-popups}
- +filter {img-reorder}
- +filter {banners-by-size}
- +filter {webbugs}
- +filter {jumping-windows}
- +filter {ie-exploits}
- -filter {google}
- -filter {yahoo}
- -filter {msn}
- -filter {blogspot}
- -filter {no-ping}
- -force-text-mode
- -handle-as-empty-document
- -handle-as-image
- -hide-accept-language
- -hide-content-disposition
- +hide-from-header{block}
- +hide-referer{forge}
- -hide-user-agent
- -overwrite-last-modified
- +prevent-compression
- -redirect
- -server-header-filter{xml-to-html}
- -server-header-filter{html-to-xml}
- +session-cookies-only
- +set-image-blocker{blank} }
- /
-
- { +block{Path contains "ads".} +handle-as-image }
- /ads
-</screen>
-</para>
-
-<para>
- Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
- configuration! But we did not want this at all! Now we see why we get the
- blank page. It is actually triggering two different actions here, and
- the effects are aggregated so that the URL is blocked, and &my-app; is told
- to treat the block as if it were an image. But this is, of course, all wrong.
- We could now add a new action below this (or better in our own
- <filename>user.action</filename> file) that explicitly
- <emphasis>un</emphasis> blocks (
- <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
- <quote>adsl</quote> in them (remember, last match in the configuration
- wins). There are various ways to handle such exceptions. Example:
-</para>
-
-<para>
- <screen>
-
- { -block }
- /adsl
-</screen>
-</para>
-
-<para>
- Now the page displays ;-)
- Remember to flush your browser's caches when making these kinds of changes to
- your configuration to insure that you get a freshly delivered page! Or, try
- using <literal>Shift+Reload</literal>.
-</para>
-
-<para>
- But now what about a situation where we get no explicit matches like
- we did with:
-</para>
-
-<para>
- <screen>
-
- { +block{Path starts with "ads".} +handle-as-image }
- /ads
-</screen>
-</para>
+</variablelist>
-<para>
- That actually was very helpful and pointed us quickly to where the problem
- was. If you don't get this kind of match, then it means one of the default
- rules in the first section of <filename>default.action</filename> is causing
- the problem. This would require some guesswork, and maybe a little trial and
- error to isolate the offending rule. One likely cause would be one of the
- <link linkend="FILTER"><quote>+filter</quote></link> actions.
- These tend to be harder to troubleshoot.
- Try adding the URL for the site to one of aliases that turn off
- <link linkend="FILTER"><quote>+filter</quote></link>:
-</para>
+</sect2>
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+<sect2 id="external-filter-syntax"><title>External filter syntax</title>
<para>
- <screen>
-
- { shop }
- .quietpc.com
- .worldpay.com # for quietpc.com
- .jungle.com
- .scan.co.uk
- .forbes.com
-</screen>
+ 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>
- <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:
-
+ External filters can be written in any language the platform &my-app; runs
+ on supports.
</para>
-
<para>
- <screen>
-
- { -filter }
- # Disable ALL filter actions for sites in this section
- .forbes.com
- developer.ibm.com
- localhost
-</screen>
+ 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>
- This would turn off all filtering for these sites. This is best
- put in <filename>user.action</filename>, for local site
- exceptions. Note that when a simple domain pattern is used by itself (without
- the subsequent path portion), all sub-pages within that domain are included
- automatically in the scope of the action.
+ 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>
- Images that are inexplicably being blocked, may well be hitting the
-<link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
- rule, which assumes
- that images of certain sizes are ad banners (works well
- <emphasis>most of the time</emphasis> since these tend to be standardized).
+ 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 can be used to get some details about the
+ client request.
</para>
-
<para>
- <quote><literal>{ fragile }</literal></quote> is an alias that disables most
- actions that are the most likely to cause trouble. This can be used as a
- last resort for problem sites.
+ &my-app; will temporary store the content to filter in the
+ <literal><link linkend="temporary-directory">temporary-directory</link></literal>.
</para>
<para>
<screen>
+EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
+/bin/cat
- { fragile }
- # Handle with care: easy to break
- mail.google.
- mybank.example.com</screen>
+# Incorrect reimplementation of the filter above in POSIX shell.
+#
+# Note that it's a single job that spans multiple lines, the line
+# breaks are not passed to the shell, thus the semicolons are required.
+#
+# If the script isn't trivial, it is recommended to put it into an external file.
+#
+# In general, writing external filters entirely in POSIX shell is not
+# considered a good idea.
+EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
+while read line; \
+do \
+ echo "$line"; \
+done
+
+EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value.
+/usr/local/bin/convert - -rotate 180 -
+
+EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The coordinates may need adjustment.
+/usr/local/bin/convert - -pointsize 16 -fill white -annotate +17+418 "[citation needed]" -
+</screen>
</para>
-
-<para>
- <emphasis>Remember to flush caches!</emphasis> Note that the
- <literal>mail.google</literal> reference lacks the TLD portion (e.g.
- <quote>.com</quote>). This will effectively match any TLD with
- <literal>google</literal> in it, such as <literal>mail.google.de.</literal>,
- just as an example.
-</para>
+<warning>
+ <para>
+ Currently external filters are executed with &my-app;'s privileges!
+ Only use external filters you understand and trust.
+ </para>
+</warning>
<para>
- If this still does not work, you will have to go through the remaining
- actions one by one to find which one(s) is causing the problem.
+ External filters are experimental and the syntax may change in the future.
</para>
-
</sect2>
</sect1>
- <!--
-
- This program is free software; you can redistribute it
- and/or modify it under the terms of the GNU General
- Public License as published by the Free Software
- Foundation; either version 2 of the License, or (at
- your option) any later version.
-
- This program is distributed in the hope that it will
- be useful, but WITHOUT ANY WARRANTY; without even the
- implied warranty of MERCHANTABILITY or FITNESS FOR A
- PARTICULAR PURPOSE. See the GNU General Public
- License for more details.
-
- The GNU General Public License should be included with
- this file. If not, you can view it at
- http://www.gnu.org/copyleft/gpl.html
- or write to the Free Software Foundation, Inc.,
- 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
- USA
-
- $Log: user-manual.sgml,v $
- Revision 2.135 2011/09/04 11:10:12 fabiankeil
- Ditch trailing whitespace
-
- Revision 2.134 2011/08/18 11:45:02 fabiankeil
- Don't use unspecified MSN sites as examples for User-Agent-based descrimination
-
- Without knowing the URLs, nobody can easily verify it and it could
- be mistaken as FUD. I also assume that it's no longer an issue anyway.
-
- Revision 2.133 2011/08/18 11:42:50 fabiankeil
- Bump some more documentation copyright ranges.
-
- Revision 2.132 2011/08/17 10:40:07 fabiankeil
- Update the entities.
-
- This commit is chronological out of order.
-
- Revision 2.131 2011/04/19 13:14:10 fabiankeil
- Fix spelling errors in the documentation. Found with codespell.
-
- Revision 2.130 2010/12/01 19:28:28 fabiankeil
- Hopefully unbreak the dok target when using some kind of jade.
-
- Reported by Lee.
-
- Revision 2.129 2010/11/13 20:17:11 fabiankeil
- Merge ChangeLog updates
-
- Revision 2.128 2010/11/10 22:00:13 fabiankeil
- Update the first paragraph of the 'What's New' section.
-
- Revision 2.127 2010/11/10 21:48:54 fabiankeil
- Update the "What's New" section.
-
- Revision 2.126 2010/11/06 12:55:48 fabiankeil
- Set p-version to 3.0.17
-
- Revision 2.125 2010/09/03 17:39:37 fabiankeil
- Slightly improve the explanation of why filtering may appear slower than it is.
-
- Revision 2.124 2010/05/01 18:21:30 fabiankeil
- Explicitly mention how to match any URL.
-
- Revision 2.123 2010/02/19 16:00:38 fabiankeil
- Even more fixes.
-
- Revision 2.122 2010/02/19 15:22:47 fabiankeil
- Add missing word.
-
- Revision 2.121 2010/02/15 15:30:13 fabiankeil
- Mention the use of the no-such-domain template for DNS problems with FEATURE_IPV6_SUPPORT enabled.
-
- Revision 2.120 2010/02/13 17:38:39 fabiankeil
- Update entities for 3.0.16 stable.
-
- Revision 2.119 2010/02/13 16:37:37 fabiankeil
- Update 'What's new?' section.
-
- Revision 2.118 2010/02/11 13:59:48 fabiankeil
- Mention that the headers added by the add-header action aren't modified by other actions.
-
- Revision 2.117 2010/01/11 12:56:04 fabiankeil
- Bump copyright range as p-config.sgml's copyright line is only used in the config file.
-
- Revision 2.116 2009/11/15 14:24:12 fabiankeil
- Prepare to generate docs for 3.0.16 UNRELEASED.
-
- Revision 2.115 2009/10/10 06:19:34 fabiankeil
- Ditch a duplicated 'since'.
-
- Revision 2.114 2009/10/10 05:51:48 fabiankeil
- Update "What's new" section.
-
- Revision 2.113 2009/10/10 05:48:55 fabiankeil
- Prepare for 3.0.15 beta.
-
- Revision 2.112 2009/07/24 12:20:30 fabiankeil
- Remove duplicated period.
-
- Revision 2.111 2009/07/18 18:11:11 fabiankeil
- Don't claim that NTLM should work when there are multiple reports that it doesn't.
-
- Revision 2.110 2009/07/18 16:25:17 fabiankeil
- Fix trailing whitespace.
-
- Revision 2.109 2009/07/18 16:24:39 fabiankeil
- Bump entities for 3.0.14 beta.
-
- Revision 2.108 2009/07/18 15:49:23 fabiankeil
- Add most of the changes in 3.0.14 to the "What's New" section.
-
- Revision 2.107 2009/06/12 14:30:58 fabiankeil
- Update entities for 3.0.13 beta.
-
- Revision 2.106 2009/06/12 11:04:13 fabiankeil
- Import ChangeLog for 3.0.13 beta.
-
- Revision 2.105 2009/04/17 11:32:57 fabiankeil
- Grammar and spelling fixes.
-
- Revision 2.104 2009/04/17 11:27:49 fabiankeil
- Petr Pisar's privoxy-3.0.12-ipv6-3.diff.
-
- Revision 2.103 2009/03/21 10:49:05 fabiankeil
- Merge updated ChangeLog.
-
- Revision 2.102 2009/03/15 19:31:36 fabiankeil
- Update "What's New in this Release" section.
-
- Revision 2.101 2009/02/25 19:01:56 fabiankeil
- Fix typo.
-
- Revision 2.100 2009/02/19 17:14:11 fabiankeil
- - Copy the release cycle description from announce.txt into
- the "What's New" section.
- - Stop referring to the ChangeLog for a "complete list of changes".
- The "What's New" section already contains the complete list.
-
- Revision 2.99 2009/02/19 02:20:22 hal9
- Make some links in seealso conditional. Man page is now privoxy only links.
-
- Revision 2.98 2009/02/16 17:10:33 fabiankeil
- Fix entry about shortened log messages. Noticed by Lee.
-
- Revision 2.97 2009/02/14 18:01:00 fabiankeil
- Import ChangeLog.
-
- Revision 2.96 2009/02/14 13:14:03 fabiankeil
- Unbreak syntax.
-
- Revision 2.95 2009/02/14 12:51:26 fabiankeil
- Mention match-all.action in the "Actions Files Tutorial" section.
-
- Revision 2.94 2009/02/14 11:50:31 fabiankeil
- Some indentation fixes.
-
- Revision 2.93 2009/02/14 10:14:42 fabiankeil
- Mention match-all.action in the action file descriptions.
-
- Revision 2.92 2009/02/12 16:08:26 fabiankeil
- Declare the code stable.
-
- Revision 2.91 2009/01/13 16:50:35 fabiankeil
- The standard.action file is gone.
-
- Revision 2.90 2008/09/26 16:53:09 fabiankeil
- Update "What's new" section.
-
- Revision 2.89 2008/09/21 15:38:56 fabiankeil
- Fix Portage tree sync instructions in Gentoo section.
- Anonymously reported at ijbswa-developers@.
-
- Revision 2.88 2008/09/21 14:42:52 fabiankeil
- Add documentation for change-x-forwarded-for{},
- remove documentation for hide-forwarded-for-headers.
-
- Revision 2.87 2008/08/30 15:37:35 fabiankeil
- Update entities.
-
- Revision 2.86 2008/08/16 10:12:23 fabiankeil
- Merge two sentences and move the URL to the end of the item.
-
- Revision 2.85 2008/08/16 10:04:59 fabiankeil
- Some more syntax fixes. This version actually builds.
-
- Revision 2.84 2008/08/16 09:42:45 fabiankeil
- Turns out building docs works better if the syntax is valid.
-
- Revision 2.83 2008/08/16 09:32:02 fabiankeil
- Mention changes since 3.0.9 beta.
-
- Revision 2.82 2008/08/16 09:00:52 fabiankeil
- Fix example URL pattern (once more with feeling).
-
- Revision 2.81 2008/08/16 08:51:28 fabiankeil
- Update version-related entities.
-
- Revision 2.80 2008/07/18 16:54:30 fabiankeil
- Remove erroneous whitespace in documentation link.
- Reported by John Chronister in #2021611.
-
- Revision 2.79 2008/06/27 18:00:53 markm68k
- remove outdated startup information for mac os x
-
- Revision 2.78 2008/06/21 17:03:03 fabiankeil
- Fix typo.
-
- Revision 2.77 2008/06/14 13:45:22 fabiankeil
- Re-add a colon I unintentionally removed a few revisions ago.
-
- Revision 2.76 2008/06/14 13:21:28 fabiankeil
- Prepare for the upcoming 3.0.9 beta release.
-
- Revision 2.75 2008/06/13 16:06:48 fabiankeil
- Update the "What's New in this Release" section with
- the ChangeLog entries changelog2doc.pl could handle.
-
- Revision 2.74 2008/05/26 15:55:46 fabiankeil
- - Update "default profiles" table.
- - Add some more pcrs redirect examples and note that
- enabling debug 128 helps to get redirects working.
-
- Revision 2.73 2008/05/23 14:43:18 fabiankeil
- Remove previously out-commented block that caused syntax problems.
-
- Revision 2.72 2008/05/12 10:26:14 fabiankeil
- Synchronize content filter descriptions with the ones in default.filter.
-
- Revision 2.71 2008/04/10 17:37:16 fabiankeil
- Actually we use "modern" POSIX 1003.2 regular
- expressions in path patterns, not PCRE.
-
- Revision 2.70 2008/04/10 15:59:12 fabiankeil
- Add another section to the client-header-tagger example that shows
- how to actually change the action settings once the tag is created.
-
- Revision 2.69 2008/03/29 12:14:25 fabiankeil
- Remove send-wafer and send-vanilla-wafer actions.
-
- Revision 2.68 2008/03/28 15:13:43 fabiankeil
- Remove inspect-jpegs action.
-
- Revision 2.67 2008/03/27 18:31:21 fabiankeil
- Remove kill-popups action.
-
- Revision 2.66 2008/03/06 16:33:47 fabiankeil
- If limit-connect isn't used, don't limit CONNECT requests to port 443.
-
- Revision 2.65 2008/03/04 18:30:40 fabiankeil
- Remove the treat-forbidden-connects-like-blocks action. We now
- use the "blocked" page for forbidden CONNECT requests by default.
-
- Revision 2.64 2008/03/01 14:10:28 fabiankeil
- Use new block syntax. Still needs some polishing.
-
- Revision 2.63 2008/02/22 05:50:37 markm68k
- fix merge problem
-
- Revision 2.62 2008/02/11 11:52:23 hal9
- Fix entity ... s/&/&
-
- Revision 2.61 2008/02/11 03:41:47 markm68k
- more updates for mac os x
-
- Revision 2.60 2008/02/11 03:40:25 markm68k
- more updates for mac os x
-
- Revision 2.59 2008/02/11 00:52:34 markm68k
- reflect new changes for mac os x
-
- Revision 2.58 2008/02/03 21:37:40 hal9
- Apply patch from Mark: s/OSX/OS X/
-
- Revision 2.57 2008/02/03 19:10:14 fabiankeil
- Mention forward-socks5.
-
- Revision 2.56 2008/01/31 19:11:35 fabiankeil
- Let the +client-header-filter{hide-tor-exit-notation} example apply
- to all requests as "tainted" Referers aren't limited to exit TLDs.
-
- Revision 2.55 2008/01/19 21:26:37 hal9
- Add IE7 to configuration section per Gerry.
-
- Revision 2.54 2008/01/19 17:52:39 hal9
- Re-commit to fix various minor issues for new release.
-
- Revision 2.53 2008/01/19 15:03:05 hal9
- Doc sources tagged for 3.0.8 release.
-
- Revision 2.52 2008/01/17 01:49:51 hal9
- Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon
- enough.
-
- Revision 2.51 2007/12/23 16:48:24 fabiankeil
- Use more precise example descriptions for the mysterious domain patterns.
-
- Revision 2.50 2007/12/08 12:44:36 fabiankeil
- - Remove already commented out pre-3.0.7 changes.
- - Update the "new log defaults" paragraph.
-
- Revision 2.49 2007/12/06 18:21:55 fabiankeil
- Update hide-forwarded-for-headers description.
-
- Revision 2.48 2007/11/24 19:07:17 fabiankeil
- - Mention request rewriting.
- - Enable the conditional-forge paragraph.
- - Minor rewordings.
-
- Revision 2.47 2007/11/18 14:59:47 fabiankeil
- A few "Note to Upgraders" updates.
-
- Revision 2.46 2007/11/17 17:24:44 fabiankeil
- - Use new action defaults.
- - Minor fixes and rewordings.
-
- Revision 2.45 2007/11/16 11:48:46 hal9
- Fix one typo, and add a couple of small refinements.
-
- Revision 2.44 2007/11/15 03:30:20 hal9
- Results of spell check.
-
- Revision 2.43 2007/11/14 18:45:39 fabiankeil
- - Mention some more contributors in the "New in this Release" list.
- - Minor rewordings.
-
- Revision 2.42 2007/11/12 03:32:40 hal9
- Updates for "What's New" and "Notes to Upgraders". Various other changes in
- preparation for new release. User Manual is almost ready.
-
- Revision 2.41 2007/11/11 16:32:11 hal9
- This is primarily syncing What's New and Note to Upgraders sections with the many
- new features and changes (gleaned from memory but mostly from ChangeLog).
-
- Revision 2.40 2007/11/10 17:10:59 fabiankeil
- In the first third of the file, mention several times that
- the action editor is disabled by default in 3.0.7 beta and later.
-
- Revision 2.39 2007/11/05 02:34:49 hal9
- Various changes in preparation for the upcoming release. Much yet to be done.
-
- Revision 2.38 2007/09/22 16:01:42 fabiankeil
- Update embedded show-url-info output.
-
- Revision 2.37 2007/08/27 16:09:55 fabiankeil
- Fix pre-chroot-nslookup description which I failed to
- copy and paste properly. Reported by Stephen Gildea.
-
- Revision 2.36 2007/08/26 16:47:14 fabiankeil
- Add Stephen Gildea's pre-chroot-nslookup patch [#1276666],
- extensive comments moved to user manual.
-
- Revision 2.35 2007/08/26 14:59:49 fabiankeil
- Minor rewordings and fixes.
-
- Revision 2.34 2007/08/05 15:19:50 fabiankeil
- - Don't claim HTTP/1.1 compliance.
- - Use $ in some of the path pattern examples.
- - Use a hide-user-agent example argument without
- leading and trailing space.
- - Make it clear that the cookie actions work with
- HTTP cookies only.
- - Rephrase the inspect-jpegs text to underline
- that it's only meant to protect against a single
- exploit.
-
- Revision 2.33 2007/07/27 10:57:35 hal9
- Add references for user-agent strings for hide-user-agenet
-
- Revision 2.32 2007/06/07 12:36:22 fabiankeil
- Apply Roland's 29_usermanual.dpatch to fix a bunch
- of syntax errors I collected over the last months.
-
- Revision 2.31 2007/06/02 14:01:37 fabiankeil
- Start to document forward-override{}.
-
- Revision 2.30 2007/04/25 15:10:36 fabiankeil
- - Describe installation for FreeBSD.
- - Start to document taggers and tag patterns.
- - Don't confuse devils and daemons.
-
- Revision 2.29 2007/04/05 11:47:51 fabiankeil
- Some updates regarding header filtering,
- handling of compressed content and redirect's
- support for pcrs commands.
-
- Revision 2.28 2006/12/10 23:42:48 hal9
- Fix various typos reported by Adam P. Thanks.
-
- Revision 2.27 2006/11/14 01:57:47 hal9
- Dump all docs prior to 3.0.6 release. Various minor changes to faq and user
- manual.
-
- Revision 2.26 2006/10/24 11:16:44 hal9
- Add new filters.
-
- Revision 2.25 2006/10/18 10:50:33 hal9
- Add note that since filters are off in Cautious, compression is ON. Turn off
- compression to make filters work on all sites.
-
- Revision 2.24 2006/10/03 11:13:54 hal9
- More references to the new filters. Include html this time around.
-
- Revision 2.23 2006/10/02 22:43:53 hal9
- Contains new filter definitions from Fabian, and few other miscellaneous
- touch-ups.
-
- Revision 2.22 2006/09/22 01:27:55 hal9
- Final commit of probably various minor changes here and there. Unless
- something changes this should be ready for pending release.
-
- Revision 2.21 2006/09/20 03:21:36 david__schmidt
- Just the tiniest tweak. Wafer thin!
-
- Revision 2.20 2006/09/10 14:53:54 hal9
- Results of spell check. User manual has some updates to standard.actions file
- info.
-
- Revision 2.19 2006/09/08 12:19:02 fabiankeil
- Adjust hide-if-modified-since example values
- to reflect the recent changes.
-
- Revision 2.18 2006/09/08 02:38:57 hal9
- Various changes:
- -Fix a number of broken links.
- -Migrate the new Windows service command line options, and reference as
- needed.
- -Rebuild so that can be used with the new "user-manual" config capabilities.
- -Etc.
-
- Revision 2.17 2006/09/05 13:25:12 david__schmidt
- Add Windows service invocation stuff (duplicated) in FAQ and in user manual under Windows startup. One probably ought to reference the other.
-
- Revision 2.16 2006/09/02 12:49:37 hal9
- Various small updates for new actions, filterfiles, etc.
-
- Revision 2.15 2006/08/30 11:15:22 hal9
- More work on the new actions, especially filter-*-headers, and What's New
- section. User Manual is close to final form for 3.0.4 release. Some tinkering
- and proof reading left to do.
-
- Revision 2.14 2006/08/29 10:59:36 hal9
- Add a "Whats New in this release" Section. Further work on multiple filter
- files, and assorted other minor changes.
-
- Revision 2.13 2006/08/22 11:04:59 hal9
- Silence warnings and errors. This should build now. New filters were only
- stubbed in. More to be done.
-
- Revision 2.12 2006/08/14 08:40:39 fabiankeil
- Documented new actions that were part of
- the "minor Privoxy improvements".
-
- Revision 2.11 2006/07/18 14:48:51 david__schmidt
- Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch)
- with what was really the latest development (the v_3_0_branch branch)
-
- Revision 1.123.2.43 2005/05/23 09:59:10 hal9
- Fix typo 'loose'
-
- Revision 1.123.2.42 2004/12/04 14:39:57 hal9
- Fix two minor typos per bug SF report.
-
- Revision 1.123.2.41 2004/03/23 12:58:42 oes
- Fixed an inaccuracy
-
- Revision 1.123.2.40 2004/02/27 12:48:49 hal9
- Add comment re: redirecting to local file system for set-image-blocker may
- is dependent on browser.
-
- Revision 1.123.2.39 2004/01/30 22:31:40 oes
- Added a hint re bookmarklets to Quickstart section
-
- Revision 1.123.2.38 2004/01/30 16:47:51 oes
- Some minor clarifications
+<!-- ~ End section ~ -->
- Revision 1.123.2.37 2004/01/29 22:36:11 hal9
- Updates for no longer filtering text/plain, and demoronizer default settings,
- and copyright notice dates.
- Revision 1.123.2.36 2003/12/10 02:26:26 hal9
- Changed the demoronizer filter description.
- Revision 1.123.2.35 2003/11/06 13:36:37 oes
- Updated link to nightly CVS tarball
+<!-- ~~~~~ New section ~~~~~ -->
- Revision 1.123.2.34 2003/06/26 23:50:16 hal9
- Add a small bit on filtering and problems re: source code being corrupted.
+<sect1 id="templates">
+<title>Privoxy's Template Files</title>
+<para>
+ All <application>Privoxy</application> built-in pages, i.e. error pages such as the
+ <ulink url="http://show-the-404-error.page"><quote>404 - No Such Domain</quote>
+ error page</ulink>, the <ulink
+ url="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"><quote>BLOCKED</quote>
+ page</ulink>
+ and all pages of its <ulink url="http://config.privoxy.org/">web-based
+ user interface</ulink>, are generated from <emphasis>templates</emphasis>.
+ (<application>Privoxy</application> must be running for the above links to work as
+ intended.)
+</para>
- Revision 1.123.2.33 2003/05/08 18:17:33 roro
- Use apt-get instead of dpkg to install Debian package, which is more
- solid, uses the correct and most recent Debian version automatically.
+<para>
+ These templates are stored in a subdirectory of the <link linkend="confdir">configuration
+ directory</link> called <filename>templates</filename>. On Unixish platforms,
+ this is typically
+ <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
+</para>
- Revision 1.123.2.32 2003/04/11 03:13:57 hal9
- Add small note about only one filterfile (as opposed to multiple actions
- files).
+<para>
+ The templates are basically normal HTML files, but with place-holders (called symbols
+ or exports), which <application>Privoxy</application> fills at run time. It
+ is possible to edit the templates with a normal text editor, should you want
+ to customize them. (<emphasis>Not recommended for the casual
+ user</emphasis>). Should you create your own custom templates, you should use
+ the <filename>config</filename> setting <link linkend="templdir">templdir</link>
+ to specify an alternate location, so your templates do not get overwritten
+ during upgrades.
+ </para>
+ <para>
+ Note that just like in configuration files, lines starting
+ with <literal>#</literal> are ignored when the templates are filled in.
+</para>
- Revision 1.123.2.31 2003/03/26 02:03:43 oes
- Updated hard-coded copyright dates
+<para>
+ The place-holders are of the form <literal>@name@</literal>, and you will
+ find a list of available symbols, which vary from template to template,
+ in the comments at the start of each file. Note that these comments are not
+ always accurate, and that it's probably best to look at the existing HTML
+ code to find out which symbols are supported and what they are filled in with.
+</para>
- Revision 1.123.2.30 2003/03/24 12:58:56 hal9
- Add new section on Predefined Filters.
+<para>
+ A special application of this substitution mechanism is to make whole
+ blocks of HTML code disappear when a specific symbol is set. We use this
+ for many purposes, one of them being to include the beta warning in all
+ our user interface (CGI) pages when <application>Privoxy</application>
+ is in an alpha or beta development stage:
+</para>
- Revision 1.123.2.29 2003/03/20 02:45:29 hal9
- More problems with \-\-chroot causing markup problems :(
+<para>
+ <screen>
+<!-- @if-unstable-start -->
- Revision 1.123.2.28 2003/03/19 00:35:24 hal9
- Manual edit of revision log because 'chroot' (even inside a comment) was
- causing Docbook to hang here (due to double hyphen and the processor thinking
- it was a comment).
+ ... beta warning HTML code goes here ...
- Revision 1.123.2.27 2003/03/18 19:37:14 oes
- s/Advanced|Radical/Adventuresome/g to avoid complaints re fun filter
+<!-- if-unstable-end@ --></screen>
+</para>
- Revision 1.123.2.26 2003/03/17 16:50:53 oes
- Added documentation for new chroot option
+<para>
+ If the "unstable" symbol is set, everything in between and including
+ <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
+ will disappear, leaving nothing but an empty comment:
+</para>
- Revision 1.123.2.25 2003/03/15 18:36:55 oes
- Adapted to the new filters
+<para>
+ <screen><!-- --></screen>
+</para>
- Revision 1.123.2.24 2002/11/17 06:41:06 hal9
- Move default profiles table from FAQ to U-M, and other minor related changes.
- Add faq on cookies.
+<para>
+ There's also an if-then-else construct and an <literal>#include</literal>
+ mechanism, but you'll sure find out if you are inclined to edit the
+ templates ;-)
+</para>
- Revision 1.123.2.23 2002/10/21 02:32:01 hal9
- Updates to the user.action examples section. A few new ones.
+<para>
+ All templates refer to a style located at
+ <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
+ This is, of course, locally served by <application>Privoxy</application>
+ and the source for it can be found and edited in the
+ <filename>cgi-style.css</filename> template.
+</para>
- Revision 1.123.2.22 2002/10/12 00:51:53 hal9
- Add demoronizer to filter section.
+</sect1>
- Revision 1.123.2.21 2002/10/10 04:09:35 hal9
- s/Advanced/Radical/ and added very brief note.
+<!-- ~ End section ~ -->
- Revision 1.123.2.20 2002/10/10 03:49:21 hal9
- Add notes to session-cookies-only and Quickstart about pre-existing
- cookies. Also, note content-cookies work differently.
- Revision 1.123.2.19 2002/09/26 01:25:36 hal9
- More explanation on Privoxy patterns, more on content-cookies and SSL.
- Revision 1.123.2.18 2002/08/22 23:47:58 hal9
- Add 'Documentation' to Privoxy Menu shot in Configuration section to match
- CGIs.
+<!-- ~~~~~ New section ~~~~~ -->
- Revision 1.123.2.17 2002/08/18 01:13:05 hal9
- Spell checked (only one typo this time!).
+<sect1 id="contact"><title>Contacting the Developers, Bug Reporting and Feature
+Requests</title>
- Revision 1.123.2.16 2002/08/09 19:20:54 david__schmidt
- Update to Mac OS X startup script name
+<!-- Include contacting.sgml boilerplate: -->
+ &contacting;
+<!-- end boilerplate -->
- Revision 1.123.2.15 2002/08/07 17:32:11 oes
- Converted some internal links from ulink to link for PDF creation; no content changed
+</sect1>
- Revision 1.123.2.14 2002/08/06 09:16:13 oes
- Nits re: actions file download
+<!-- ~ End section ~ -->
- Revision 1.123.2.13 2002/08/02 18:23:19 g_sauthoff
- Just 2 small corrections to the Gentoo sections
- Revision 1.123.2.12 2002/08/02 18:17:21 g_sauthoff
- Added 2 Gentoo sections
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="copyright"><title>Privoxy Copyright, License and History</title>
- Revision 1.123.2.11 2002/07/26 15:20:31 oes
- - Added version info to title
- - Added info on new filters
- - Revised parts of the filter file tutorial
- - Added info on where to get updated actions files
+<!-- Include copyright.sgml: -->
+ ©right;
+<!-- end copyright -->
- Revision 1.123.2.10 2002/07/25 21:42:29 hal9
- Add brief notes on not proxying non-HTTP protocols.
+<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>
- Revision 1.123.2.9 2002/07/11 03:40:28 david__schmidt
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="license"><title>License</title>
+<para>
+ <screen><![ RCDATA [ &GPLv2; ]]></screen>
+</para>
- Updated Mac OS X sections due to installation location change
+</sect2>
+<!-- ~ End section ~ -->
- Revision 1.123.2.8 2002/06/09 16:36:32 hal9
- Clarifications on filtering and MIME. Hardcode 'latest release' in index.html.
- Revision 1.123.2.7 2002/06/09 00:29:34 hal9
- Touch ups on filtering, in actions section and Anatomy.
+<!-- ~~~~~ New section ~~~~~ -->
- Revision 1.123.2.6 2002/06/06 23:11:03 hal9
- Fix broken link. Linkchecked all docs.
+<sect2 id="history"><title>History</title>
+<!-- Include history.sgml: -->
+ &history;
+<!-- end history -->
+</sect2>
- Revision 1.123.2.5 2002/05/29 02:01:02 hal9
- This is break out of the entire config section from u-m, so it can
- eventually be used to generate the comments, etc in the main config file
- so that these are in sync with each other.
+<sect2 id="authors"><title>Authors</title>
+<!-- Include p-authors.sgml: -->
+ &p-authors;
+<!-- end authors -->
+</sect2>
- Revision 1.123.2.4 2002/05/27 03:28:45 hal9
- Ooops missed something from David.
+</sect1>
- Revision 1.123.2.3 2002/05/27 03:23:17 hal9
- Fix FIXMEs for OS2 and Mac OS X startup. Fix Redhat typos (should be Red Hat).
- That's a wrap, I think.
+<!-- ~ End section ~ -->
- Revision 1.123.2.2 2002/05/26 19:02:09 hal9
- Move Amiga stuff around to take of FIXME in start up section.
- Revision 1.123.2.1 2002/05/26 17:04:25 hal9
- -Spellcheck, very minor edits, and sync across branches
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="seealso"><title>See Also</title>
+<!-- Include seealso.sgml: -->
+ &seealso;
+<!-- end seealso -->
+</sect1>
- Revision 1.123 2002/05/24 23:19:23 hal9
- Include new image (Proxy setup). More fun with guibutton.
- Minor corrections/clarifications here and there.
- Revision 1.122 2002/05/24 13:24:08 oes
- Added Bookmarklet for one-click pre-filled access to show-url-info
- Revision 1.121 2002/05/23 23:20:17 oes
- - Changed more (all?) references to actions to the
- <literal><link> style.
- - Small fixes in the actions chapter
- - Small clarifications in the quickstart to ad blocking
- - Removed <emphasis> from <title>s since the new doc CSS
- renders them red (bad in TOC).
+<!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="appendix"><title>Appendix</title>
- Revision 1.120 2002/05/23 19:16:43 roro
- Correct Debian specials (installation and startup).
- Revision 1.119 2002/05/22 17:17:05 oes
- Added Security hint
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="regex">
+<title>Regular Expressions</title>
+<para>
+ <application>Privoxy</application> uses Perl-style <quote>regular
+ expressions</quote> in its <link linkend="actions-file">actions
+ files</link> and <link linkend="filter-file">filter file</link>,
+ through the <ulink url="http://www.pcre.org/">PCRE</ulink> and
+<!--
+ dead 08/27/06
+ <ulink url="http://www.oesterhelt.org/pcrs/">PCRS</ulink> libraries.
+-->
+ <application>PCRS</application> libraries.
+</para>
- Revision 1.118 2002/05/21 04:54:55 hal9
- -New Section: Quickstart to Ad Blocking
- -Reformat Actions Anatomy to match new CGI layout
+<para>
+ If you are reading this, you probably don't understand what <quote>regular
+ expressions</quote> are, or what they can do. So this will be a very brief
+ introduction only. A full explanation would require a <ulink
+ url="http://www.oreilly.com/catalog/regex/">book</ulink> ;-)
+</para>
- Revision 1.117 2002/05/17 13:56:16 oes
- - Reworked & extended Templates chapter
- - Small changes to Regex appendix
- - #included authors.sgml into (C) and hist chapter
+<para>
+ Regular expressions provide a language to describe patterns that can be
+ run against strings of characters (letter, numbers, etc), to see if they
+ match the string or not. The patterns are themselves (sometimes complex)
+ strings of literal characters, combined with wild-cards, and other special
+ characters, called meta-characters. The <quote>meta-characters</quote> have
+ special meanings and are used to build complex patterns to be matched against.
+ Perl Compatible Regular Expressions are an especially convenient
+ <quote>dialect</quote> of the regular expression language.
+</para>
- Revision 1.116 2002/05/17 03:23:46 hal9
- Fixing merge conflict in Quickstart section.
+<para>
+ To make a simple analogy, we do something similar when we use wild-card
+ characters when listing files with the <command>dir</command> command in DOS.
+ <literal>*.*</literal> matches all filenames. The <quote>special</quote>
+ character here is the asterisk which matches any and all characters. We can be
+ more specific and use <literal>?</literal> to match just individual
+ characters. So <quote>dir file?.text</quote> would match
+ <quote>file1.txt</quote>, <quote>file2.txt</quote>, etc. We are pattern
+ matching, using a similar technique to <quote>regular expressions</quote>!
+</para>
- Revision 1.115 2002/05/16 16:25:00 oes
- Extended the Filter File chapter & minor fixes
+<para>
+ Regular expressions do essentially the same thing, but are much, much more
+ powerful. There are many more <quote>special characters</quote> and ways of
+ building complex patterns however. Let's look at a few of the common ones,
+ and then some examples:
+</para>
- Revision 1.114 2002/05/16 09:42:50 oes
- More ulink->link, added some hints to Quickstart section
+<para><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>
- Revision 1.113 2002/05/15 21:07:25 oes
- Extended and further commented the example actions files
+<para><simplelist>
+ <member>
+ <emphasis>?</emphasis> - The preceding character or expression is matched ZERO or ONE
+ times. Either/or.
+ </member>
+</simplelist></para>
- Revision 1.112 2002/05/15 03:57:14 hal9
- Spell check. A few minor edits here and there for better syntax and
- clarification.
+<para><simplelist>
+ <member>
+ <emphasis>+</emphasis> - The preceding character or expression is matched ONE or MORE
+ times.
+ </member>
+</simplelist></para>
- Revision 1.111 2002/05/14 23:01:36 oes
- Fixing the fixes
+<para><simplelist>
+ <member>
+ <emphasis>*</emphasis> - The preceding character or expression is matched ZERO or MORE
+ times.
+ </member>
+</simplelist></para>
- Revision 1.110 2002/05/14 19:10:45 oes
- Restored alphabetical order of actions
+<para><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
+ special characters (e.g. <quote>.</quote>) needs to be taken literally and
+ not as a special meta-character. Example: <quote>example\.com</quote>, makes
+ sure the period is recognized only as a period (and not expanded to its
+ meta-character meaning of any single character).
+ </member>
+</simplelist></para>
- Revision 1.109 2002/05/14 17:23:11 oes
- Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs
+<para><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>
- Revision 1.108 2002/05/14 15:29:12 oes
- Completed proofreading the actions chapter
+<para><simplelist>
+ <member>
+ <emphasis>( )</emphasis> - parentheses are used to group a sub-expression,
+ or multiple sub-expressions.
+ </member>
+</simplelist></para>
- Revision 1.107 2002/05/12 03:20:41 hal9
- Small clarifications for 127.0.0.1 vs localhost for listen-address since this
- apparently an important distinction for some OS's.
+<para><simplelist>
+ <member>
+ <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
+ <quote>or</quote> conditional statement. A match is successful if the
+ sub-expression on either side of <quote>|</quote> matches. As an example:
+ <quote>/(this|that) example/</quote> uses grouping and the bar character
+ and would match either <quote>this example</quote> or <quote>that
+ example</quote>, and nothing else.
+ </member>
+</simplelist></para>
- Revision 1.106 2002/05/10 01:48:20 hal9
- This is mostly proposed copyright/licensing additions and changes. Docs
- are still GPL, but licensing and copyright are more visible. Also, copyright
- changed in doc header comments (eliminate references to JB except FAQ).
+<para>
+ These are just some of the ones you are likely to use when matching URLs with
+ <application>Privoxy</application>, and is a long way from a definitive
+ list. This is enough to get us started with a few simple examples which may
+ be more illuminating:
+</para>
- Revision 1.105 2002/05/05 20:26:02 hal9
- Sorting out license vs copyright in these docs.
+<para>
+ <emphasis><literal>/.*/banners/.*</literal></emphasis> - A simple example
+ that uses the common combination of <quote>.</quote> and <quote>*</quote> to
+ denote any character, zero or more times. In other words, any string at all.
+ So we start with a literal forward slash, then our regular expression pattern
+ (<quote>.*</quote>) another literal forward slash, the string
+ <quote>banners</quote>, another forward slash, and lastly another
+ <quote>.*</quote>. We are building
+ a directory path here. This will match any file with the path that has a
+ directory named <quote>banners</quote> in it. The <quote>.*</quote> matches
+ any characters, and this could conceivably be more forward slashes, so it
+ might expand into a much longer looking path. For example, this could match:
+ <quote>/eye/hate/spammers/banners/annoy_me_please.gif</quote>, or just
+ <quote>/banners/annoying.html</quote>, or almost an infinite number of other
+ possible combinations, just so it has <quote>banners</quote> in the path
+ somewhere.
+</para>
- Revision 1.104 2002/05/04 08:44:45 swa
- bumped version
+<para>
+ And now something a little more complex:
+</para>
- Revision 1.103 2002/05/04 00:40:53 hal9
- -Remove the TOC first page kludge. It's fixed proper now in ldp.dsl.in.
- -Some minor additions to Quickstart.
+<para>
+ <emphasis><literal>/.*/adv((er)?ts?|ertis(ing|ements?))?/</literal></emphasis> -
+ We have several literal forward slashes again (<quote>/</quote>), so we are
+ building another expression that is a file path statement. We have another
+ <quote>.*</quote>, so we are matching against any conceivable sub-path, just so
+ it matches our expression. The only true literal that <emphasis>must
+ match</emphasis> our pattern is <application>adv</application>, together with
+ the forward slashes. What comes after the <quote>adv</quote> string is the
+ interesting part.
+</para>
- Revision 1.102 2002/05/03 17:46:00 oes
- Further proofread & reactivated short build instructions
+<para>
+ Remember the <quote>?</quote> means the preceding expression (either a
+ literal character or anything grouped with <quote>(...)</quote> in this case)
+ can exist or not, since this means either zero or one match. So
+ <quote>((er)?ts?|ertis(ing|ements?))</quote> is optional, as are the
+ individual sub-expressions: <quote>(er)</quote>,
+ <quote>(ing|ements?)</quote>, and the <quote>s</quote>. The <quote>|</quote>
+ means <quote>or</quote>. We have two of those. For instance,
+ <quote>(ing|ements?)</quote>, can expand to match either <quote>ing</quote>
+ <emphasis>OR</emphasis> <quote>ements?</quote>. What is being done here, is an
+ attempt at matching as many variations of <quote>advertisement</quote>, and
+ similar, as possible. So this would expand to match just <quote>adv</quote>,
+ or <quote>advert</quote>, or <quote>adverts</quote>, or
+ <quote>advertising</quote>, or <quote>advertisement</quote>, or
+ <quote>advertisements</quote>. You get the idea. But it would not match
+ <quote>advertizements</quote> (with a <quote>z</quote>). We could fix that by
+ changing our regular expression to:
+ <quote>/.*/adv((er)?ts?|erti(s|z)(ing|ements?))?/</quote>, which would then match
+ either spelling.
+</para>
- Revision 1.101 2002/05/03 03:58:30 hal9
- Move the user-manual config directive to top of section. Add note about
- Privoxy needing read permissions for configs, and write for logs.
+<para>
+ <emphasis><literal>/.*/advert[0-9]+\.(gif|jpe?g)</literal></emphasis> - Again
+ another path statement with forward slashes. Anything in the square brackets
+ <quote>[ ]</quote> can be matched. This is using <quote>0-9</quote> as a
+ shorthand expression to mean any digit one through nine. It is the same as
+ saying <quote>0123456789</quote>. So any digit matches. The <quote>+</quote>
+ means one or more of the preceding expression must be included. The preceding
+ expression here is what is in the square brackets -- in this case, any digit
+ one through nine. Then, at the end, we have a grouping: <quote>(gif|jpe?g)</quote>.
+ This includes a <quote>|</quote>, so this needs to match the expression on
+ either side of that bar character also. A simple <quote>gif</quote> on one side, and the other
+ side will in turn match either <quote>jpeg</quote> or <quote>jpg</quote>,
+ since the <quote>?</quote> means the letter <quote>e</quote> is optional and
+ can be matched once or not at all. So we are building an expression here to
+ match image GIF or JPEG type image file. It must include the literal
+ string <quote>advert</quote>, then one or more digits, and a <quote>.</quote>
+ (which is now a literal, and not a special character, since it is escaped
+ with <quote>\</quote>), and lastly either <quote>gif</quote>, or
+ <quote>jpeg</quote>, or <quote>jpg</quote>. Some possible matches would
+ include: <quote>//advert1.jpg</quote>,
+ <quote>/nasty/ads/advert1234.gif</quote>,
+ <quote>/banners/from/hell/advert99.jpg</quote>. It would not match
+ <quote>advert1.gif</quote> (no leading slash), or
+ <quote>/adverts232.jpg</quote> (the expression does not include an
+ <quote>s</quote>), or <quote>/advert1.jsp</quote> (<quote>jsp</quote> is not
+ in the expression anywhere).
+</para>
- Revision 1.100 2002/04/29 03:05:55 hal9
- Add clarification on differences of new actions files.
+<para>
+ We are barely scratching the surface of regular expressions here so that you
+ can understand the default <application>Privoxy</application>
+ configuration files, and maybe use this knowledge to customize your own
+ installation. There is much, much more that can be done with regular
+ expressions. Now that you know enough to get started, you can learn more on
+ your own :/
+</para>
- Revision 1.99 2002/04/28 16:59:05 swa
- more structure in starting section
+<para>
+ More reading on Perl Compatible Regular expressions:
+ <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
+</para>
- Revision 1.98 2002/04/28 05:43:59 hal9
- This is the break up of configuration.html into multiple files. This
- will probably break links elsewhere :(
+<para>
+ For information on regular expression based substitutions and their applications
+ in filters, please see the <link linkend="filter-file">filter file tutorial</link>
+ in this manual.
+</para>
+</sect2>
- Revision 1.97 2002/04/27 21:04:42 hal9
- -Rewrite of Actions File example.
- -Add section for user-manual directive in config.
+<!-- ~ End section ~ -->
- Revision 1.96 2002/04/27 05:32:00 hal9
- -Add short section to Filter Files to tie in with +filter action.
- -Start rewrite of examples in Actions Examples (not finished).
- Revision 1.95 2002/04/26 17:23:29 swa
- bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2>
+<title>Privoxy's Internal Pages</title>
- Revision 1.94 2002/04/26 05:24:36 hal9
- -Add most of Andreas suggestions to Chain of Events section.
- -A few other minor corrections and touch up.
+<para>
+ Since <application>Privoxy</application> proxies each requested
+ web page, it is easy for <application>Privoxy</application> to
+ trap certain special URLs. In this way, we can talk directly to
+ <application>Privoxy</application>, and see how it is
+ configured, see how our rules are being applied, change these
+ rules and other configuration options, and even turn
+ <application>Privoxy's</application> filtering off, all with
+ a web browser.
- Revision 1.92 2002/04/25 18:55:13 hal9
- More catchups on new actions files, and new actions names.
- Other assorted cleanups, and minor modifications.
+</para>
- Revision 1.91 2002/04/24 02:39:31 hal9
- Add 'Chain of Events' section.
+<para>
+ The URLs listed below are the special ones that allow direct access
+ to <application>Privoxy</application>. Of course,
+ <application>Privoxy</application> must be running to access these. If
+ not, you will get a friendly error message. Internet access is not
+ necessary either.
+</para>
- Revision 1.90 2002/04/23 21:41:25 hal9
- Linuxconf is deprecated on RH, substitute chkconfig.
+<para>
+ <itemizedlist>
- Revision 1.89 2002/04/23 21:05:28 oes
- Added hint for startup on Red Hat
+ <listitem>
+ <para>
+ Privoxy main page:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/">http://config.privoxy.org/</ulink>
+ </para>
+ </blockquote>
+ <para>
+ There is a shortcut: <ulink url="http://p.p/">http://p.p/</ulink> (But it
+ doesn't provide a fall-back to a real page, in case the request is not
+ sent through <application>Privoxy</application>)
+ </para>
+ </listitem>
- Revision 1.88 2002/04/23 05:37:54 hal9
- Add AmigaOS install stuff.
+ <listitem>
+ <para>
+ Show information about the current configuration, including viewing and
+ editing of actions files:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ </para>
+ </blockquote>
+ </listitem>
- Revision 1.87 2002/04/23 02:53:15 david__schmidt
- Updated Mac OS X installation section
- Added a few English tweaks here an there
+ <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>
- Revision 1.86 2002/04/21 01:46:32 hal9
- Re-write actions section.
+ <listitem>
+ <para>
+ Show the browser's request headers:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-request">http://config.privoxy.org/show-request</ulink>
+ </para>
+ </blockquote>
+ </listitem>
- Revision 1.85 2002/04/18 21:23:23 hal9
- Fix ugly typo (mine).
+ <listitem>
+ <para>
+ Show which actions apply to a URL and why:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
+ </para>
+ </blockquote>
+ </listitem>
- Revision 1.84 2002/04/18 21:17:13 hal9
- Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
+ <listitem>
+ <para>
+ Toggle Privoxy on or off. This feature can be turned off/on in the main
+ <filename>config</filename> file. When toggled <quote>off</quote>, <quote>Privoxy</quote>
+ continues to run, but only as a pass-through proxy, with no actions taking
+ place:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/toggle">http://config.privoxy.org/toggle</ulink>
+ </para>
+ </blockquote>
+ <para>
+ Short cuts. Turn off, then on:
+ </para>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/toggle?set=disable">http://config.privoxy.org/toggle?set=disable</ulink>
+ </para>
+ </blockquote>
+ <blockquote>
+ <para>
+ <ulink url="http://config.privoxy.org/toggle?set=enable">http://config.privoxy.org/toggle?set=enable</ulink>
+ </para>
+ </blockquote>
+ </listitem>
- Revision 1.83 2002/04/18 18:21:12 oes
- Added RPM install detail
+ </itemizedlist>
+</para>
- Revision 1.82 2002/04/18 12:04:50 oes
- Cosmetics
+<para>
+ These may be bookmarked for quick reference. See next.
- Revision 1.81 2002/04/18 11:50:24 oes
- Extended Install section - needs fixing by packagers
+</para>
- Revision 1.80 2002/04/18 10:45:19 oes
- Moved text to buildsource.sgml, renamed some filters, details
+<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>
- Revision 1.79 2002/04/18 03:18:06 hal9
- Spellcheck, and minor touchups.
+<para>
+ <itemizedlist>
- Revision 1.78 2002/04/17 18:04:16 oes
- Proofreading part 2
+ <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>
- Revision 1.77 2002/04/17 13:51:23 oes
- Proofreading, part one
+ <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>
- Revision 1.76 2002/04/16 04:25:51 hal9
- -Added 'Note to Upgraders' and re-ordered the 'Quickstart' section.
- -Note about proxy may need requests to re-read config files.
+ <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>
- Revision 1.75 2002/04/12 02:08:48 david__schmidt
- Remove OS/2 building info... it is already in the developer-manual
+ <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>
- Revision 1.74 2002/04/11 00:54:38 hal9
- Add small section on submitting actions.
+<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>
- Revision 1.73 2002/04/10 18:45:15 swa
- generated
- Revision 1.72 2002/04/10 04:06:19 hal9
- Added actions feedback to Bookmarklets section
+</sect3>
- Revision 1.71 2002/04/08 22:59:26 hal9
- Version update. Spell chkconfig correctly :)
+</sect2>
- Revision 1.70 2002/04/08 20:53:56 swa
- ?
- Revision 1.69 2002/04/06 05:07:29 hal9
- -Add privoxy-man-page.sgml, for man page.
- -Add authors.sgml for AUTHORS (and p-authors.sgml)
- -Reworked various aspects of various docs.
- -Added additional comments to sub-docs.
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="chain">
+<title>Chain of Events</title>
+<para>
+ Let's take a quick look at how some of <application>Privoxy's</application>
+ core features are triggered, and the ensuing sequence of events when a web
+ page is requested by your browser:
+</para>
- Revision 1.68 2002/04/04 18:46:47 swa
- consistent look. reuse of copyright, history et. al.
+<para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ First, your web browser requests a web page. The browser knows to send
+ the request to <application>Privoxy</application>, which will in turn,
+ relay the request to the remote web server after passing the following
+ tests:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Privoxy</application> traps any request for its own internal CGI
+ pages (e.g <ulink url="http://p.p/">http://p.p/</ulink>) and sends the CGI page back to the browser.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Next, <application>Privoxy</application> checks to see if the URL
+ matches any <link
+ linkend="BLOCK"><quote>+block</quote></link> patterns. If
+ so, the URL is then blocked, and the remote web server will not be contacted.
+ <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>
+ and
+ <link linkend="HANDLE-AS-EMPTY-DOCUMENT"><quote>+handle-as-empty-document</quote></link>
+ are then checked, and if there is no match, an
+ HTML <quote>BLOCKED</quote> page is sent back to the browser. Otherwise, if
+ it does match, an image is returned for the former, and an empty text
+ document for the latter. The type of image would depend on the setting of
+ <link linkend="SET-IMAGE-BLOCKER"><quote>+set-image-blocker</quote></link>
+ (blank, checkerboard pattern, or an HTTP redirect to an image elsewhere).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Untrusted URLs are blocked. If URLs are being added to the
+ <filename>trust</filename> file, then that is done.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the URL pattern matches the <link
+ linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link> action,
+ it is then processed. Unwanted parts of the requested URL are stripped.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now the rest of the client browser's request headers are processed. If any
+ of these match any of the relevant actions (e.g. <link
+ linkend="HIDE-USER-AGENT"><quote>+hide-user-agent</quote></link>,
+ etc.), headers are suppressed or forged as determined by these actions and
+ their parameters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Now the web server starts sending its response back (i.e. typically a web
+ page).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ First, the server headers are read and processed to determine, among other
+ things, the MIME type (document type) and encoding. The headers are then
+ filtered as determined by the
+ <link linkend="CRUNCH-INCOMING-COOKIES"><quote>+crunch-incoming-cookies</quote></link>,
+ <link linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>,
+ and <link linkend="DOWNGRADE-HTTP-VERSION"><quote>+downgrade-http-version</quote></link>
+ actions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If any <link linkend="FILTER"><quote>+filter</quote></link> action
+ or <link
+ linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
+ action applies (and the document type fits the action), the rest of the page is
+ read into memory (up to a configurable limit). Then the filter rules (from
+ <filename>default.filter</filename> and any other filter files) are
+ processed against the buffered content. Filters are applied in the order
+ they are specified in one of the filter files. Animated GIFs, if present,
+ are reduced to either the first or last frame, depending on the action
+ setting.The entire page, which is now filtered, is then sent by
+ <application>Privoxy</application> back to your browser.
+ </para>
+ <para>
+ If neither a <link linkend="FILTER"><quote>+filter</quote></link> action
+ or <link
+ linkend="DEANIMATE-GIFS"><quote>+deanimate-gifs</quote></link>
+ matches, then <application>Privoxy</application> passes the raw data through
+ to the client browser as it becomes available.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ As the browser receives the now (possibly filtered) page content, it
+ reads and then requests any URLs that may be embedded within the page
+ source, e.g. ad images, stylesheets, JavaScript, other HTML documents (e.g.
+ frames), sounds, etc. For each of these objects, the browser issues a
+ separate request (this is easily viewable in <application>Privoxy's</application>
+ logs). And each such request is in turn processed just as above. Note that a
+ complex web page will have many, many such embedded URLs. If these
+ secondary requests are to a different server, then quite possibly a very
+ differing set of actions is triggered.
+ </para>
+ </listitem>
- Revision 1.67 2002/04/04 17:27:57 swa
- more single file to be included at multiple points. make maintaining easier
+ </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
+ <application>Privoxy's</application> core features only.
+</para>
- Revision 1.66 2002/04/04 06:48:37 hal9
- Structural changes to allow for conditional inclusion/exclusion of content
- based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
- definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
- eventually be set by Makefile.
- More boilerplate text for use across multiple docs.
+</sect2>
- Revision 1.65 2002/04/03 19:52:07 swa
- enhance squid section due to user suggestion
- Revision 1.64 2002/04/03 03:53:43 hal9
- A few minor bug fixes, and touch ups. Ready for review.
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="actionsanat">
+<title>Troubleshooting: Anatomy of an Action</title>
- Revision 1.63 2002/04/01 16:24:49 hal9
- Define entities to include boilerplate text. See doc/source/*.
+<para>
+ The way <application>Privoxy</application> applies
+ <link linkend="ACTIONS">actions</link> and <link linkend="FILTER">filters</link>
+ to any given URL can be complex, and not always so
+ easy to understand what is happening. And sometimes we need to be able to
+ <emphasis>see</emphasis> just what <application>Privoxy</application> is
+ doing. Especially, if something <application>Privoxy</application> is doing
+ is causing us a problem inadvertently. It can be a little daunting to look at
+ the actions and filters files themselves, since they tend to be filled with
+ <link linkend="regex">regular expressions</link> whose consequences are not
+ always so obvious.
+</para>
- Revision 1.62 2002/03/30 04:15:53 hal9
- - Fix privoxy.org/config links.
- - Paste in Bookmarklets from Toggle page.
- - Move Quickstart nearer top, and minor rework.
+<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
+ 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>.)
+</para>
+<para>
+ Another easy troubleshooting step to try is if you have done any
+ customization of your installation, revert back to the installed
+ defaults and see if that helps. There are times the developers get complaints
+ about one thing or another, and the problem is more related to a customized
+ configuration issue.
+</para>
- Revision 1.61 2002/03/29 01:31:08 hal9
- Minor update.
+<para>
+ <application>Privoxy</application> also provides the
+ <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
+ page that can show us very specifically how <application>actions</application>
+ are being applied to any given URL. This is a big help for troubleshooting.
+</para>
- Revision 1.60 2002/03/27 01:57:34 hal9
- Added more to Anatomy section.
+<para>
+ First, enter one URL (or partial URL) at the prompt, and then
+ <application>Privoxy</application> will tell us
+ how the current configuration will handle it. This will not
+ help with filtering effects (i.e. the <link
+ linkend="FILTER"><quote>+filter</quote></link> action) from
+ one of the filter files since this is handled very
+ differently and not so easy to trap! It also will not tell you about any other
+ URLs that may be embedded within the URL you are testing. For instance, images
+ such as ads are expressed as URLs within the raw page source of HTML pages. So
+ you will only get info for the actual URL that is pasted into the prompt area
+ -- not any sub-URLs. If you want to know about embedded URLs like ads, you
+ will have to dig those out of the HTML source. Use your browser's <quote>View
+ Page Source</quote> option for this. Or right click on the ad, and grab the
+ URL.
+</para>
- Revision 1.59 2002/03/27 00:54:33 hal9
- Touch up intro for new name.
+<para>
+ Let's try an example, <ulink url="http://google.com">google.com</ulink>,
+ and look at it one section at a time in a sample configuration (your real
+ configuration may vary):
+</para>
- Revision 1.58 2002/03/26 22:29:55 swa
- we have a new homepage!
+<para>
+ <screen>
+ Matches for http://www.google.com:
- Revision 1.57 2002/03/24 20:33:30 hal9
- A few minor catch ups with name change.
+ In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
- Revision 1.56 2002/03/24 16:17:06 swa
- configure needs to be generated.
+ {+change-x-forwarded-for{block}
+ +deanimate-gifs {last}
+ +fast-redirects {check-decoded-url}
+ +filter {refresh-tags}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ +hide-from-header {block}
+ +hide-referrer {forge}
+ +session-cookies-only
+ +set-image-blocker {pattern}
+/
- Revision 1.55 2002/03/24 16:08:08 swa
- we are too lazy to make a block-built
- privoxy logo. hence removed the option.
+ { -session-cookies-only }
+ .google.com
- Revision 1.54 2002/03/24 15:46:20 swa
- name change related issue.
+ { -fast-redirects }
+ .google.com
- Revision 1.53 2002/03/24 11:51:00 swa
- name change. changed filenames.
+In file: user.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
+(no matches in this file)
+</screen>
+</para>
- Revision 1.52 2002/03/24 11:01:06 swa
- name change
+<para>
+ This is telling us how we have defined our
+ <link linkend="ACTIONS"><quote>actions</quote></link>, and
+ which ones match for our test case, <quote>google.com</quote>.
+ Displayed is all the actions that are available to us. Remember,
+ the <literal>+</literal> sign denotes <quote>on</quote>. <literal>-</literal>
+ denotes <quote>off</quote>. So some are <quote>on</quote> here, but many
+ are <quote>off</quote>. Each example we try may provide a slightly different
+ end result, depending on our configuration directives.
+</para>
+<para>
+ The first listing
+ is for our <filename>default.action</filename> file. The large, multi-line
+ listing, is how the actions are set to match for all URLs, i.e. our default
+ settings. If you look at your <quote>actions</quote> file, this would be the
+ section just below the <quote>aliases</quote> section near the top. This
+ will apply to all URLs as signified by the single forward slash at the end
+ of the listing -- <quote> / </quote>.
+</para>
- Revision 1.51 2002/03/23 15:13:11 swa
- renamed every reference to the old name with foobar.
- fixed "application foobar application" tag, fixed
- "the foobar" with "foobar". left junkbustser in cvs
- comments and remarks to history untouched.
+<para>
+ But we have defined additional actions that would be exceptions to these general
+ rules, and then we list specific URLs (or patterns) that these exceptions
+ would apply to. Last match wins. Just below this then are two explicit
+ matches for <quote>.google.com</quote>. The first is negating our previous
+ cookie setting, which was for <link
+ linkend="SESSION-COOKIES-ONLY"><quote>+session-cookies-only</quote></link>
+ (i.e. not persistent). So we will allow persistent cookies for google, at
+ least that is how it is in this example. The second turns
+ <emphasis>off</emphasis> any <link
+ linkend="FAST-REDIRECTS"><quote>+fast-redirects</quote></link>
+ action, allowing this to take place unmolested. Note that there is a leading
+ dot here -- <quote>.google.com</quote>. This will match any hosts and
+ sub-domains, in the google.com domain also, such as
+ <quote>www.google.com</quote> or <quote>mail.google.com</quote>. But it would not
+ match <quote>www.google.de</quote>! So, apparently, we have these two actions
+ defined as exceptions to the general rules at the top somewhere in the lower
+ part of our <filename>default.action</filename> file, and
+ <quote>google.com</quote> is referenced somewhere in these latter sections.
+</para>
- Revision 1.50 2002/03/23 05:06:21 hal9
- Touch up.
+<para>
+ Then, for our <filename>user.action</filename> file, we again have no hits.
+ So there is nothing google-specific that we might have added to our own, local
+ configuration. If there was, those actions would over-rule any actions from
+ previously processed files, such as <filename>default.action</filename>.
+ <filename>user.action</filename> typically has the last word. This is the
+ best place to put hard and fast exceptions,
+</para>
- Revision 1.49 2002/03/21 17:01:05 hal9
- New section in Appendix.
+<para>
+ 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>:
- Revision 1.48 2002/03/12 06:33:01 hal9
- Catching up to Andreas and re_filterfile changes.
+</para>
- Revision 1.47 2002/03/11 13:13:27 swa
- correct feedback channels
+<para>
+ <screen>
- Revision 1.46 2002/03/10 00:51:08 hal9
- Added section on JB internal pages in Appendix.
+ Final results:
- Revision 1.45 2002/03/09 17:43:53 swa
- more distros
+ -add-header
+ -block
+ +change-x-forwarded-for{block}
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs {last}
+ -downgrade-http-version
+ -fast-redirects
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-from-header {block}
+ -hide-if-modified-since
+ +hide-referrer {forge}
+ -hide-user-agent
+ -limit-connect
+ -overwrite-last-modified
+ -prevent-compression
+ -redirect
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ -session-cookies-only
+ +set-image-blocker {pattern} </screen>
+</para>
- Revision 1.44 2002/03/09 17:08:48 hal9
- New section on Jon's actions file editor, and move some stuff around.
+<para>
+ Notice the only difference here to the previous listing, is to
+ <quote>fast-redirects</quote> and <quote>session-cookies-only</quote>,
+ which are activated specifically for this site in our configuration,
+ and thus show in the <quote>Final Results</quote>.
+</para>
- Revision 1.43 2002/03/08 00:47:32 hal9
- Added imageblock{pattern}.
+<para>
+ Now another example, <quote>ad.doubleclick.net</quote>:
+</para>
- Revision 1.42 2002/03/07 18:16:55 swa
- looks better
+<para>
+ <screen>
- Revision 1.41 2002/03/07 16:46:43 hal9
- Fix a few markup problems for jade.
+ { +block{Domains starts with "ad"} }
+ ad*.
- Revision 1.40 2002/03/07 16:28:39 swa
- provide correct feedback channels
+ { +block{Domain contains "ad"} }
+ .ad.
- Revision 1.39 2002/03/06 16:19:28 hal9
- Note on perceived filtering slowdown per FR.
+ { +block{Doubleclick banner server} +handle-as-image }
+ .[a-vx-z]*.doubleclick.net
+</screen>
+</para>
- Revision 1.38 2002/03/05 23:55:14 hal9
- Stupid I did it again. Double hyphen in comment breaks jade.
+<para>
+ We'll just show the interesting part here - the explicit matches. It is
+ matched three different times. Two <quote>+block{}</quote> sections,
+ and a <quote>+block{} +handle-as-image</quote>,
+ which is the expanded form of one of our aliases that had been defined as:
+ <quote>+block-as-image</quote>. (<link
+ linkend="ALIASES"><quote>Aliases</quote></link> are defined in
+ the first section of the actions file and typically used to combine more
+ than one action.)
+</para>
- Revision 1.37 2002/03/05 23:53:49 hal9
- jade barfs on '- -' embedded in comments. - -user option broke it.
+<para>
+ Any one of these would have done the trick and blocked this as an unwanted
+ image. This is unnecessarily redundant since the last case effectively
+ would also cover the first. No point in taking chances with these guys
+ though ;-) Note that if you want an ad or obnoxious
+ URL to be invisible, it should be defined as <quote>ad.doubleclick.net</quote>
+ is done here -- as both a <link
+ linkend="BLOCK"><quote>+block{}</quote></link>
+ <emphasis>and</emphasis> an
+ <link linkend="HANDLE-AS-IMAGE"><quote>+handle-as-image</quote></link>.
+ The custom alias <quote><literal>+block-as-image</literal></quote> just
+ simplifies the process and make it more readable.
+</para>
- Revision 1.36 2002/03/05 22:53:28 hal9
- Add new - - user option.
+<para>
+ One last example. Let's try <quote>http://www.example.net/adsl/HOWTO/</quote>.
+ This one is giving us problems. We are getting a blank page. Hmmm ...
+</para>
- Revision 1.35 2002/03/05 00:17:27 hal9
- Added section on command line options.
+<para>
+ <screen>
- Revision 1.34 2002/03/04 19:32:07 oes
- Changed default port to 8118
+ Matches for http://www.example.net/adsl/HOWTO/:
- Revision 1.33 2002/03/03 19:46:13 hal9
- Emphasis on where/how to report bugs, etc
+ In file: default.action <guibutton>[ View ]</guibutton> <guibutton>[ Edit ]</guibutton>
- Revision 1.32 2002/03/03 09:26:06 joergs
- AmigaOS changes, config is now loaded from PROGDIR: instead of
- AmiTCP:db/junkbuster/ if no configuration file is specified on the
- command line.
+ {-add-header
+ -block
+ +change-x-forwarded-for{block}
+ -client-header-filter{hide-tor-exit-notation}
+ -content-type-overwrite
+ -crunch-client-header
+ -crunch-if-none-match
+ -crunch-incoming-cookies
+ -crunch-outgoing-cookies
+ -crunch-server-header
+ +deanimate-gifs
+ -downgrade-http-version
+ +fast-redirects {check-decoded-url}
+ -filter {js-events}
+ -filter {content-cookies}
+ -filter {all-popups}
+ -filter {banners-by-link}
+ -filter {tiny-textforms}
+ -filter {frameset-borders}
+ -filter {demoronizer}
+ -filter {shockwave-flash}
+ -filter {quicktime-kioskmode}
+ -filter {fun}
+ -filter {crude-parental}
+ -filter {site-specifics}
+ -filter {js-annoyances}
+ -filter {html-annoyances}
+ +filter {refresh-tags}
+ -filter {unsolicited-popups}
+ +filter {img-reorder}
+ +filter {banners-by-size}
+ +filter {webbugs}
+ +filter {jumping-windows}
+ +filter {ie-exploits}
+ -filter {google}
+ -filter {yahoo}
+ -filter {msn}
+ -filter {blogspot}
+ -filter {no-ping}
+ -force-text-mode
+ -handle-as-empty-document
+ -handle-as-image
+ -hide-accept-language
+ -hide-content-disposition
+ +hide-from-header{block}
+ +hide-referer{forge}
+ -hide-user-agent
+ -overwrite-last-modified
+ +prevent-compression
+ -redirect
+ -server-header-filter{xml-to-html}
+ -server-header-filter{html-to-xml}
+ +session-cookies-only
+ +set-image-blocker{blank} }
+ /
- Revision 1.31 2002/03/02 22:45:52 david__schmidt
- Just tweaking
+ { +block{Path contains "ads".} +handle-as-image }
+ /ads
+</screen>
+</para>
- Revision 1.30 2002/03/02 22:00:14 hal9
- Updated 'New Features' list. Ran through spell-checker.
+<para>
+ Ooops, the <quote>/adsl/</quote> is matching <quote>/ads</quote> in our
+ configuration! But we did not want this at all! Now we see why we get the
+ blank page. It is actually triggering two different actions here, and
+ the effects are aggregated so that the URL is blocked, and &my-app; is told
+ to treat the block as if it were an image. But this is, of course, all wrong.
+ We could now add a new action below this (or better in our own
+ <filename>user.action</filename> file) that explicitly
+ <emphasis>un</emphasis> blocks (
+ <link linkend="BLOCK"><quote>{-block}</quote></link>) paths with
+ <quote>adsl</quote> in them (remember, last match in the configuration
+ wins). There are various ways to handle such exceptions. Example:
+</para>
- Revision 1.29 2002/03/02 20:34:07 david__schmidt
- Update OS/2 build section
+<para>
+ <screen>
- Revision 1.28 2002/02/24 14:34:24 jongfoster
- Formatting changes. Now changing the doctype to DocBook XML 4.1
- will work - no other changes are needed.
+ { -block }
+ /adsl
+</screen>
+</para>
- Revision 1.27 2002/01/11 14:14:32 hal9
- Added a very short section on Templates
+<para>
+ Now the page displays ;-)
+ Remember to flush your browser's caches when making these kinds of changes to
+ your configuration to insure that you get a freshly delivered page! Or, try
+ using <literal>Shift+Reload</literal>.
+</para>
- Revision 1.26 2002/01/09 20:02:50 hal9
- Fix bug re: auto-detect config file changes.
+<para>
+ But now what about a situation where we get no explicit matches like
+ we did with:
+</para>
- Revision 1.25 2002/01/09 18:20:30 hal9
- Touch ups for *.action files.
+<para>
+ <screen>
- Revision 1.24 2001/12/02 01:13:42 hal9
- Fix typo.
+ { +block{Path starts with "ads".} +handle-as-image }
+ /ads
+</screen>
+</para>
- Revision 1.23 2001/12/02 00:20:41 hal9
- Updates for recent changes.
+<para>
+ That actually was very helpful and pointed us quickly to where the problem
+ was. If you don't get this kind of match, then it means one of the default
+ rules in the first section of <filename>default.action</filename> is causing
+ the problem. This would require some guesswork, and maybe a little trial and
+ error to isolate the offending rule. One likely cause would be one of the
+ <link linkend="FILTER"><quote>+filter</quote></link> actions.
+ These tend to be harder to troubleshoot.
+ Try adding the URL for the site to one of aliases that turn off
+ <link linkend="FILTER"><quote>+filter</quote></link>:
+</para>
- Revision 1.22 2001/11/05 23:57:51 hal9
- Minor update for startup now daemon mode.
+<para>
+ <screen>
- Revision 1.21 2001/10/31 21:11:03 hal9
- Correct 2 minor errors
+ { shop }
+ .quietpc.com
+ .worldpay.com # for quietpc.com
+ .jungle.com
+ .scan.co.uk
+ .forbes.com
+</screen>
+</para>
- Revision 1.18 2001/10/24 18:45:26 hal9
- *** empty log message ***
+<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:
- Revision 1.17 2001/10/24 17:10:55 hal9
- Catching up with Jon's recent work, and a few other things.
+</para>
- Revision 1.16 2001/10/21 17:19:21 swa
- wrong url in documentation
+<para>
+ <screen>
- Revision 1.15 2001/10/14 23:46:24 hal9
- Various minor changes. Fleshed out SEE ALSO section.
+ { -filter }
+ # Disable ALL filter actions for sites in this section
+ .forbes.com
+ developer.ibm.com
+ localhost
+</screen>
+</para>
- Revision 1.13 2001/10/10 17:28:33 hal9
- Very minor changes.
+<para>
+ This would turn off all filtering for these sites. This is best
+ put in <filename>user.action</filename>, for local site
+ exceptions. Note that when a simple domain pattern is used by itself (without
+ the subsequent path portion), all sub-pages within that domain are included
+ automatically in the scope of the action.
+</para>
- Revision 1.12 2001/09/28 02:57:04 hal9
- Ditto :/
+<para>
+ Images that are inexplicably being blocked, may well be hitting the
+<link linkend="FILTER-BANNERS-BY-SIZE"><quote>+filter{banners-by-size}</quote></link>
+ rule, which assumes
+ that images of certain sizes are ad banners (works well
+ <emphasis>most of the time</emphasis> since these tend to be standardized).
+</para>
- Revision 1.11 2001/09/28 02:25:20 hal9
- Ditto.
+<para>
+ <quote><literal>{ fragile }</literal></quote> is an alias that disables most
+ actions that are the most likely to cause trouble. This can be used as a
+ last resort for problem sites.
+</para>
+<para>
+ <screen>
- Revision 1.9 2001/09/27 23:50:29 hal9
- A few changes. A short section on regular expression in appendix.
+ { fragile }
+ # Handle with care: easy to break
+ mail.google.
+ mybank.example.com</screen>
+</para>
- Revision 1.8 2001/09/25 00:34:59 hal9
- Some additions, and re-arranging.
- Revision 1.7 2001/09/24 14:31:36 hal9
- Diddling.
+<para>
+ <emphasis>Remember to flush caches!</emphasis> Note that the
+ <literal>mail.google</literal> reference lacks the TLD portion (e.g.
+ <quote>.com</quote>). This will effectively match any TLD with
+ <literal>google</literal> in it, such as <literal>mail.google.de.</literal>,
+ just as an example.
+</para>
+<para>
+ If this still does not work, you will have to go through the remaining
+ actions one by one to find which one(s) is causing the problem.
+</para>
- Revision 1.6 2001/09/24 14:10:32 hal9
- Including David's OS/2 installation instructions.
+</sect2>
- Revision 1.2 2001/09/13 15:27:40 swa
- cosmetics
+</sect1>
- Revision 1.1 2001/09/12 15:36:41 swa
- source files for junkbuster documentation
+ <!--
- Revision 1.3 2001/09/10 17:43:59 swa
- first proposal of a structure.
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General
+ Public License as published by the Free Software
+ Foundation; either version 2 of the License, or (at
+ your option) any later version.
- Revision 1.2 2001/06/13 14:28:31 swa
- docs should have an author.
+ This program is distributed in the hope that it will
+ be useful, but WITHOUT ANY WARRANTY; without even the
+ implied warranty of MERCHANTABILITY or FITNESS FOR A
+ PARTICULAR PURPOSE. See the GNU General Public
+ License for more details.
- Revision 1.1 2001/06/13 14:20:37 swa
- first import of project's documentation for the webserver.
+ The GNU General Public License should be included with
+ this file. If not, you can view it at
+ http://www.gnu.org/copyleft/gpl.html
+ or write to the Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA
-->
projects / privoxy.git / blobdiff