X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=969cea2d56a1d22f8ad6c9fa990e67d420f239f5;hb=d8f504084688130e8898969c8ceedd2fe6573afe;hp=36ea41883fd0dc9df27e08a393ec24e64f7769b3;hpb=8c88ba9bbf93cdd0c5ba5b3074b74deabd7e46c8;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 36ea4188..969cea2d 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -9,10 +9,12 @@
+
-
-
+
+
+
@@ -34,9 +36,9 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.161 2013/01/12 12:21:38 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.187 2014/06/03 10:33:59 fabiankeil Exp $
- Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
@@ -55,12 +57,12 @@
- Copyright &my-copy; 2001-2013 by
+ Copyright &my-copy; 2001-2014 by
Privoxy Developers
-$Id: user-manual.sgml,v 2.161 2013/01/12 12:21:38 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.187 2014/06/03 10:33:59 fabiankeil Exp $
-FreeBSD
+FreeBSD
Privoxy is part of FreeBSD's Ports Collection, you can build and install
it with cd /usr/ports/www/privoxy; make install clean.
-
- If you don't use the ports, you can fetch and install
- the package with pkg_add -r privoxy.
-
-
- The port skeleton and the package can also be downloaded from the
- File Release
- Page, but there's no reason to use them unless you're interested in the
- beta releases which are only available there.
-
-
-
-
-
-
-Building from Source
-
-
- The most convenient way to obtain the Privoxy sources
- is to download the source tarball from our
- project download
- page.
-
-
-
- If you like to live on the bleeding edge and are not afraid of using
- possibly unstable development versions, you can check out the up-to-the-minute
- version directly from the
- CVS repository.
-
-
-
-
-&buildsource;
-
-
-
-
-Keeping your Installation Up-to-Date
-
-
- If you wish to receive an email notification whenever we release updates of
- Privoxy or the actions file, subscribe
- to our announce mailing list, ijbswa-announce@lists.sourceforge.net.
-
-
-
- In order not to lose your personal changes and adjustments when updating
- to the latest default.action file we strongly
- recommend that you use user.action and
- user.filter for your local
- customizations of Privoxy. See the Chapter on actions files for details.
-
-
-
-
-
-
-
-
-
-
-
-What's New in this Release
-
- Privoxy 3.0.20 is a beta release.
- The changes since 3.0.19 stable are:
-
-
-
-
-
-
- Bug fixes:
-
-
-
- Client sockets are now properly shutdown and drained before being
- closed. This fixes page truncation issues with clients that aggressively
- pipeline data on platforms that otherwise discard already written data.
- The issue mainly affected Opera users and was initially reported
- by Kevin in #3464439, szotsaki provided additional information to track
- down the cause.
-
-
-
-
- Fix latency calculation for shared connections (disabled by default).
- It was broken since their introduction in 2009. The calculated latency
- for most connections would be 0 in which case the timeout detection
- failed to account for the real latency.
-
-
-
-
- Reject URLs with invalid port. Previously they were parsed incorrectly and
- characters between the port number and the first slash were silently
- dropped as shown by curl test 187.
-
-
-
-
- The default-server-timeout and socket-timeout directives accept 0 as
- valid value.
-
-
-
-
- Fix a race condition on Windows that could cause Privoxy to become
- unresponsive after toggling it on or off through the taskbar icon.
- Reported by Tim H. in #3525694.
-
-
-
-
- Fix the compilation on Windows when configured without IPv6 support.
-
-
-
-
- Fix an assertion that could cause debug builds to abort() in case of
- socks5 connection failures with "debug 2" enabled.
-
-
-
-
- Fix an assertion that could cause debug builds to abort() if a filter
- contained nul bytes in the replacement text.
-
-
-
-
-
-
-
- General improvements:
-
-
-
- Significantly improved keep-alive support for both client and server
- connections.
-
-
-
-
- New debug log level 65536 which logs all actions that were applied to
- the request.
-
-
-
-
- New directive client-header-order to forward client headers in a
- different order than the one in which they arrived.
-
-
-
-
- New directive tolerate-pipelining to allow client-side pipelining.
- If enabled (3.0.20 beta enables it by default), Privoxy will keep
- pipelined client requests around to deal with them once the current
- request has been served.
-
-
-
-
- New --config-test option to let Privoxy exit after checking whether or not
- the configuration seems valid. The limitations noted in TODO #22 and #23
- still apply. Based on a patch by Ramkumar Chinchani.
-
-
-
-
- New limit-cookie-lifetime{} action to let cookies expire before the end
- of the session. Suggested by Rick Sykes in #1049575.
-
-
-
-
- Increase the hard-coded maximum number of actions and filter files from
- 10 to 30 (each). It doesn't significantly affect Privoxy's memory usage
- and recompiling wasn't an option for all Privoxy users that reached the
- limit.
-
-
-
-
- Add support for chunk-encoded client request bodies. Previously
- chunk-encoded request bodies weren't guaranteed to be forwarded correctly,
- so this can also be considered a bug fix although chunk-encoded request
- bodies aren't commonly used in the real world.
-
-
-
-
- Add support for Tor's optimistic-data SOCKS extension, which can reduce the
- latency for requests on newly created connections. Currently only the
- headers are sent optimistically and only if the client request has already
- been read completely which rules out requests with large bodies.
-
-
-
-
- After preventing the client from pipelining, don't signal keep-alive
- intentions. When looking at the response headers alone, it previously
- wasn't obvious from the client's perspective that no additional responses
- should be expected.
-
-
-
-
- Stop considering client sockets tainted after receving a request with body.
- It hasn't been necessary for a while now and unnecessarily causes test
- failures when using curl's test suite.
-
-
-
-
- Allow HTTP/1.0 clients to signal interest in keep-alive through the
- Proxy-Connection header. While such client are rare in the real world, it
- doesn't hurt and couple of curl tests rely on it.
-
-
-
-
- Only remove duplicated Content-Type headers when filters are enabled.
- If they are not it doesn't cause ill effects and the user might not want it.
- Downgrade the removal message to LOG_LEVEL_HEADER to clarify that it's not
- an error in Privoxy and is unlikely to cause any problems in general.
- Anonymously reported in #3599335.
-
-
-
-
- Set the socket option SO_LINGER for the client socket.
-
-
-
-
- Move several variable declarations to the beginning of their code block.
- It's required when compiling with gcc 2.95 which is still used on some
- platforms. Initial patch submitted by Simon South in #3564815.
-
-
-
-
- Optionally try to sanity-check strptime() results before trusting them.
- Broken strptime() implementations have caused problems in the past and
- the most recent offender seems to be FreeBSD's libc (standards/173421).
-
-
-
-
- When filtering is enabled, let Range headers pass if the range starts at
- the beginning. This should work around (or at least reduce ) the video
- playback issues with various Apple clients as reported by Duc in #3426305.
-
-
-
-
- Do not confuse a client hanging up with a connection time out. If a client
- closes its side of the connection without sending a request line, do not
- send the CLIENT_CONNECTION_TIMEOUT_RESPONSE, but report the condition
- properly.
-
-
-
-
- Allow closing curly braces as part of action values as long as they are
- escaped.
-
-
-
-
- On Windows, the logfile is now written before showing the GUI error
- message which blocks until the user acknowledges it.
- Reported by Adriaan in #3593603.
-
-
-
-
- Remove an unreasonable parameter limit in the CGI interface. The new
- parameter limit depends on the memory available and is currently unlikely
- to be reachable, due to other limits in both Privoxy and common clients.
- Reported by Andrew on ijbswa-users@.
-
-
-
-
- Decrease the chances of parse failures after requests with unsupported
- methods were sent to the CGI interface.
-
-
-
-
-
-
-
- Action file improvements:
-
-
-
- Remove the comment that indicated that updated default.action versions
- are released on their own.
-
-
-
-
- Block 'optimize.indieclick.com/' and 'optimized-by.rubiconproject.com/'
-
-
-
-
- Unblock 'adjamblog.wordpress.com/' and 'adjamblog.files.wordpress.com/'.
- Reported by Ryan Farmer in #3496116.
-
-
-
-
- Unblock '/.*Bugtracker'. Reported by pwhk in #3522341.
-
-
-
-
- Add test URLs for '.freebsd.org' and '.watson.org'.
-
-
-
-
- Unblock '.urbandictionary.com/popular'.
-
-
-
-
- Block '.adnxs.com/'.
-
-
-
-
- Block 'farm.plista.com/widgetdata.php'.
-
-
-
-
- Block 'rotation.linuxnewmedia.com/'.
-
-
-
-
- Block 'reklamy.sfd.pl/'. Reported by kacperdominik in #3399948.
-
-
-
-
- Block 'g.adspeed.net/'.
-
-
-
-
- Unblock 'websupport.wdc.com/'. Reported by Adam Piggot in #3577851.
-
-
-
-
- Block '/openx/www/delivery/'.
-
-
-
-
- Disable fast-redirects for '.googleapis.com/'.
-
-
-
-
- Block 'imp.double.net/'. Reported by David Bo in #3070411.
-
-
-
-
- Block 'gm-link.com/' whis is used for email tracking.
- Reported by David Bo in #1812733.
-
-
-
-
- Verify that requests to "bwp." are blocked. URL taken from #1736879
- submitted by Francois Marier.
-
-
-
-
- Block '/.*bannerid='. Reported by Adam Piggott in #2975779.
-
-
-
-
- Block 'cltomedia.info/delivery/' and '.adexprt.com/'.
- Anonymously reported in #2965254.
-
-
-
-
- Block 'de17a.com/'. Reported by David Bo in #3061472.
-
-
-
-
- Block 'oskar.tradera.com/'. Reported by David Bo in #3060596.
-
-
-
-
- Block '/scripts/webtrends\.js'. Reported by johnd16 in #3002729.
-
-
-
-
- Block requests for 'pool.*.adhese.com/'. Reported by johnd16 in #3002716.
-
-
-
-
- Update path pattern for Coremetrics and add tests.
- Pattern and URLs submitted by Adam Piggott #3168443.
-
-
-
-
- Enable +fast-redirects{check-decoded-url} for 'tr.anp.se/'.
- Reported by David Bo in #3268832.
-
-
-
-
- Unblock '.conrad.se/newsletter/banners/'. Reported by David Bo in #3413824.
-
-
-
-
- Block '.tynt.com/'. Reported by Dan Stahlke in #3421767.
-
-
-
-
- Unblock '.bbci.co.uk/radio/'. Reported by Adam Piggott in #3569603.
-
-
-
-
- Block requests to 'service.maxymiser.net/'.
- Reported by johnd16 in #3118401 (with a previous URL).
-
-
-
-
- Disable fast-redirects for Google's "let's pretend your computer is
- infected" page.
-
-
-
-
- Unblock '/.*download' to resolve actionsfile feedback #3498129.
- Submitted by Steven Kolins (soundcloud.com not working).
-
-
-
-
- Unblock '.wlxrs.com/' which is required by hotmail.com.
- Fixes #3413827 submitted by David Bo.
-
-
-
-
- Add two unblock patterns for popup radio and TV players.
- Submitted by Adam Piggott in #3596089.
-
-
-
-
-
-
-
- Filter file improvements & bug fixes:
-
-
-
- Add a referer tagger.
-
-
-
-
- Reduce the likelihood that the google filter messes up HTML-generating
- JavaScript. Reported by Zeno Kugy in #3520260.
-
-
-
-
-
-
-
- Documentation improvements:
-
-
-
- Revised all OS X sections due to new packaging module (OSXPackageBuilder).
-
-
-
-
- Update the list of supported operating systems to clarify that all Windows
- versions after 95 are expected to work and note that the platform-specific
- code for AmigaOS and QNX currently isn't maintained.
-
-
-
-
- Update 'Signals' section, the only explicitly handled signals are SIGINT,
- SIGTERM and SIGHUP.
-
-
-
-
- Add Haiku to the list of operating systems on which Privoxy is known to
- run.
-
-
-
-
- Add DragonFly to the list of BSDs on which Privoxy is known to run.
-
-
-
-
- Removed references to redhat-specific documentation set since it no longer
- exists.
-
-
-
-
- Removed references to building PDFs since we no longer do so.
-
-
-
-
- Multiple listen-address directives are supported since 3.0.18, correct the
- documentation to say so.
-
-
-
-
- Remove bogus section about long and short being preferable to int.
-
-
-
-
- Corrected some Internet JunkBuster references to Privoxy.
-
-
-
-
- Removed references to www.junkbusters.com since it is no longer
- maintained. Reported by Angelina Matson.
-
-
-
-
- Various grammar and spelling corrections
-
-
-
-
- Add a client-header-tagger{} example for disabling filtering for range
- requests.
-
-
-
-
- Correct a URL in the "Privoxy with Tor" FAQ.
-
-
-
-
- Spell 'refresh-tags' correctly. Reported by Don in #3571927.
-
-
-
-
- Sort manpage options alphabetically.
-
-
-
-
- Remove an incorrect sentence in the toggle section. The toggle state
- doesn't affect whether or not the Windows version uses the tray icon.
- Reported by Zeno Kugy in #3596395.
-
-
-
-
- Add new contributors since 3.0.19.
-
-
-
-
-
-
-
- Log message improvements:
-
-
-
- When stopping to watch a client socket due to pipelining, additionally log
- the socket number.
-
-
-
-
- Log the client socket and its condition before closing it. This makes it
- more obvious that the socket actually gets closed and should help when
- diagnosing problems like #3464439.
-
-
-
-
- In case of SOCKS5 failures, do not explicitly log the server's response.
- It hasn't helped so far and the response can already be logged by enabling
- "debug 32768" anyway. This reverts v1.81 and the follow-up bug fix v1.84.
-
-
-
-
- Relocate the connection-accepted message from listen_loop() to serve().
- This way it's printed by the thread that is actually serving the
- connection which is nice when grepping for thread ids in log files.
-
-
-
-
-
-
-
- Code cleanups:
-
-
-
- Remove compatibility layer for versions prior to 3.0 since it has been
- obsolete for more than 10 years now.
-
-
-
-
- Remove the ijb_isupper() and ijb_tolower() macros from parsers.c since
- they aren't used in this file.
-
-
-
-
- Removed the 'Functions declared include:' comment sections since they tend
- to be incomplete, incorrect and out of date and the benefit seems
- questionable.
-
-
-
-
- Various comment grammar and comprehensibility improvements.
-
-
-
-
- Remove a pointless fflush() call in chat(). Flushing all streams pretty
- much all the time for no obvious reason is ridiculous.
-
-
-
-
- Relocate ijb_isupper()'s definition to project.h and get the ijb_tolower()
- definition from there, too.
-
-
-
-
- Relocate ijb_isdigit()'s definition to project.h.
-
-
-
-
- Rename ijb_foo macros to privoxy_foo.
-
-
-
-
- Add malloc_or_die() which will allow to simplify code paths where malloc()
- failures don't need to be handled gracefully.
-
-
-
-
- Add strdup_or_die() which will allow to simplify code paths where strdup()
- failures don't need to be handled gracefully.
-
-
-
-
- Replace strdup() calls with strdup_or_die() calls where it's safe and
- simplifies the code.
-
-
-
-
- Fix white-space around parentheses.
-
-
-
-
- Add missing white-space behind if's and the following parentheses.
-
-
-
-
- Unwrap a memcpy() call in resolve_hostname_to_ip().
-
-
-
-
- Declare pcrs_get_delimiter()'s delimiters[] static const.
-
-
-
-
- Various optimisations to remove dead code and merge inefficient code
- structures for improved clarity, performance or code compactness.
-
-
-
-
- Various data type corrections.
-
-
-
-
- Change visibility of several code segments when compiling without
- FEATURE_CONNECTION_KEEP_ALIVE enabled for clarity.
-
-
-
-
- In pcrs_get_delimiter(), do not use delimiters ouside the ASCII range.
- Fixes a clang complaint.
-
-
-
-
- Fix an error message in get_last_url() nobody is supposed to see.
- Reported by Matthew Fischer in #3507301.
-
-
-
-
- Fix a typo in the no-zlib-support complaint. Patch submitted by Matthew
- Fischer in #3507304.
-
-
-
-
- Shorten ssplit()'s prototype by removing the last two arguments. We always
- want to skip empty fields and ignore leading delimiters, so having
- parameters for this only complicates the API.
-
-
-
-
- Use an enum for the type of the action value.
-
-
-
-
- Rename action_name's member takes_value to value_type as it isn't used as
- boolean.
-
-
-
-
- Turn family mismatches in match_sockaddr() into fatal errors.
-
-
-
-
- Let enlist_unique_header() verify that the caller didn't pass a header
- containing either \r or \n.
-
-
-
-
- Change the hashes used in load_config() to unsigned int. That's what
- hash_string() actually returns and using a potentiallly larger type
- is at best useless.
-
-
-
-
- Use privoxy_tolower() instead of vanilla tolower() with manual casting of
- the argument.
-
-
-
-
- Catch ssplit() failures in parse_cgi_parameters().
-
-
-
-
-
-
-
- Privoxy-Regression-Test:
-
-
-
- Add an 'Overwrite condition' directive to skip any matching tests before
- it. As it has a global scope, using it is more convenient than clowning
- around with the Ignore directive.
-
-
-
-
- Log to STDOUT instead of STDERR.
-
-
-
-
- Include the Privoxy version in the output.
-
-
-
-
- Various grammar and spelling corrections in documentation and code.
-
-
-
-
- Additional tests for range requests with filtering enabled.
-
-
-
-
- Tests with mostly invalid range request.
-
-
-
-
- Add a couple of hide-if-modified-since{} tests with different date formats.
-
-
-
-
- Cleaned up the format of the regression-tests.action file to match the
- format of default.action.
-
-
-
-
- Remove the "Copyright" line from print_version(). When using --help, every
- line of screen space matters and thus shouldn't be wasted on things the
- user doesn't care about.
-
-
-
-
-
-
-
- Privoxy-Log-Parser:
-
-
-
- Improve the --statistics performance by skipping sanity checks for input
- that shouldn't affect the results anyway. Add a --strict-checks option
- that enables some of the checks again, just in case anybody cares.
-
-
-
-
- The distribution of client requests per connection is included in
- the --statistic output.
-
-
-
-
- The --accept-unknown-messages option has been removed and the behavior
- is now the default.
-
-
-
-
- Accept and (mostly) highlight new log messages introduced with
- Privoxy 3.0.20.
-
-
-
-
-
-
-
- uagen:
-
-
-
- Bump generated Firefox version to 17.
-
-
-
-
-
-
-
- GNUmakefile improvements:
-
-
-
- The dok-tidy target no longer taints documents with a tidy-mark
-
-
-
-
- Change RA_MODE from 0664 to 0644. Suggested by Markus Dittrich in
- #3505445.
-
-
-
-
- Remove tidy's clean flag as it changes the scope of attributes.
- Link-specific colors end up being applied to all text. Reported by Adam
- Piggott in #3569551.
-
-
-
-
- Leave it up to the user whether or not smart tags are inserted.
-
-
-
-
- Let w3m itself do the line wrapping for the config file. It works better
- than fmt as it can honour pre tags causing less unintentional line breaks.
-
-
-
-
- Ditch a pointless '-r' passed to rm to delete files.
-
-
-
-
- The config-file target now requires less manual intervention and updates
- the original config.
-
-
-
-
- Change WDUMP to generate ASCII. Add WDUMP_UTF8 to allow UTF-8 in the
- AUTHORS file so the names are right.
-
-
-
-
- Stop pretending that lynx and links are supported for the documentation.
-
-
-
-
-
-
-
- configure improvements:
-
-
-
- On Haiku, do not pass -lpthread to the compiler. Haiku's pthreads
- implementation is contained in its system library, libroot, so no
- additional library needs to be searched.
- Patch submitted by Simon South in #3564815.
-
-
-
-
- Additional Haiku-specific improvements. Disable checks intended for
- multi-user systems as Haiku is presently single-user. Group Haiku-specific
- settings in their own section, following the pattern for Solaris, OS/2 and
- AmigaOS. Add additional library-related settings to remove the need for
- providing configure with custom LDFLAGS.
- Submitted by Simon South in #3574538.
- *** Version 3.0.19 Stable ***
-
-
-
-
-
-
+
+
+
+
+
+Building from Source
+
+
+ The most convenient way to obtain the Privoxy sources
+ is to download the source tarball from our
+ project download
+ page.
+
+
+
+ If you like to live on the bleeding edge and are not afraid of using
+ possibly unstable development versions, you can check out the up-to-the-minute
+ version directly from the
+ CVS repository.
+
+
+
+
+&buildsource;
+
+
+
+
+Keeping your Installation Up-to-Date
+
+
+ If you wish to receive an email notification whenever we release updates of
+ Privoxy or the actions file, subscribe
+ to our announce mailing list, ijbswa-announce@lists.sourceforge.net.
+
+
+
+ In order not to lose your personal changes and adjustments when updating
+ to the latest default.action file we strongly
+ recommend that you use user.action and
+ user.filter for your local
+ customizations of Privoxy. See the Chapter on actions files for details.
+
+
+
+
+
+
+
+
+
+What's New in this Release
+
+&changelog;
@@ -1387,12 +446,6 @@ How to install the binary packages depends on your operating system:
files, thinking you will want to do that yourself.
-
-
- standard.action has been merged into
- the default.action file.
-
-
In the default configuration only fatal errors are logged now.
@@ -2010,28 +1063,6 @@ How to install the binary packages depends on your operating system:
directory. Except on Win32 where it will try config.txt.
-
-Red Hat and Fedora
-
- A default Red Hat installation may not start &my-app; upon boot. It will use
- the file /etc/privoxy/config as its main configuration
- file.
-
-
-
- # /etc/rc.d/init.d/privoxy start
-
-
-
- Or ...
-
-
-
- # service privoxy start
-
-
-
-
Debian
@@ -2120,42 +1151,6 @@ Example Unix startup command:
-
-AmigaOS
-
- Start Privoxy (with RUN <>NIL:) in your
- startnet script (AmiTCP), in
- s:user-startup (RoadShow), as startup program in your
- startup script (Genesis), or as startup action (Miami and MiamiDx).
- Privoxy will automatically quit when you quit your
- TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
- Privoxy is still running).
-
-
-
-
-Gentoo
-
- A script is again used. It will use the file /etc/privoxy/config
- as its main configuration file.
-
-
-
- /etc/init.d/privoxy start
-
-
-
- Note that Privoxy is not automatically started at
- boot time by default. You can change this with the rc-update
- command.
-
-
-
- rc-update add privoxy default
-
-
-
-
-The Domain Pattern
+The Host Pattern
- 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:
@@ -3368,6 +2375,23 @@ for details.
+
+The Negative Tag Patterns
+
+
+ To match requests that do not have a certain tag, specify a negative tag pattern
+ by prefixing the tag pattern line with either NO-REQUEST-TAG:
+ or NO-RESPONSE-TAG:
instead of TAG:
.
+
+
+
+ Negative tag patterns created with NO-REQUEST-TAG:
are checked
+ after all client headers are scanned, the ones created with NO-RESPONSE-TAG:
+ are checked after all server headers are scanned. In both cases all the created
+ tags are considered.
+
+
+
@@ -4577,6 +3601,94 @@ problem-host.example.com
+
+
+external-filter
+
+
+
+ Typical use:
+
+ Modify content using a programming language of your choice.
+
+
+
+
+ Effect:
+
+
+ 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 text/plain MIME type for all files
+ whose type they don't know.)
+
+
+
+
+
+ Type:
+
+
+ Parameterized.
+
+
+
+
+ Parameter:
+
+
+ The name of an external content filter, as defined in the
+ filter file.
+ External filters can be defined in one or more files as defined by the
+ filterfile
+ option in the config file.
+
+
+ When used in its negative form,
+ and without parameters, all filtering with external
+ filters is completely disabled.
+
+
+
+
+
+ Notes:
+
+
+ External filters are scripts or programs that can modify the content in
+ case common filters
+ aren't powerful enough. With the exception that this action doesn't
+ use pcrs-based filters, the notes in the
+ filter section apply.
+
+
+
+ Currently external filters are executed with &my-app;'s privileges.
+ Only use external filters you understand and trust.
+
+
+
+ This feature is experimental, the syntax
+ may change in the future.
+
+
+
+
+
+
+ Example usage:
+
+
+ +external-filter{fancy-filter}
+
+
+
+
+
+
fast-redirects
@@ -4839,7 +3951,7 @@ problem-host.example.com
- +filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
+ +filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).
@@ -4851,15 +3963,15 @@ problem-host.example.com
- +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).
+ +filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds.
@@ -4889,6 +4001,10 @@ problem-host.example.com
+filter{frameset-borders} # Give frames a border and make them resizable.
+
+
+ +filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites.
+
+filter{demoronizer} # Fix MS's non-standard use of standard charsets.
@@ -6279,7 +5395,7 @@ new action
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
@@ -6297,6 +5413,13 @@ undeadly.org/cgi\?action=article&sid=\d*$
{+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)
+
# Redirect remote requests for this manual
# to the local version delivered by Privoxy
{+redirect{s@^http://www@http://config@}}
@@ -6465,6 +5588,14 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
# 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
+# silly example.
+{+external-filter{rotate-image} +force-text-mode}
+TAG:^image/
@@ -7425,7 +6556,7 @@ stupid-server.example.com/
- &my-app; supports three different filter actions:
+ &my-app; supports three different pcrs-based filter actions:
filter to
rewrite the content that is send to the client,
client-header-filter
@@ -7445,6 +6576,13 @@ stupid-server.example.com/
applying actions through sections with tag-patterns.
+
+ Finally &my-app; supports the
+ external-filter action
+ to enable external filters
+ written in proper programming languages.
+
+
Multiple filter files can be defined through the
in a syntax that imitates Perl's
s/// 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 U is supported,
- which turns the default to ungreedy matching.
+ PCRS documentation for the subtle differences to Perl behaviour.
+
+
+
+ Most notably, the non-standard option letter U is supported,
+ which turns the default to ungreedy matching (add ? to
+ quantifiers to turn them greedy again).
+
+
+
+ The non-standard option letter D (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.
+
+
+
+ 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.
+
+
+
+ The non-standard option letter T (trivial) prevents
+ parsing for backreferences in the substitute. Use it if you want to include
+ text like '$&' in your substitute without quoting.
@@ -8236,6 +7400,76 @@ pre-defined filters for your convenience:
+
+
+External filter syntax
+
+ External filters are scripts or programs that can modify the content in
+ case common filters
+ aren't powerful enough.
+
+
+ External filters can be written in any language the platform &my-app; runs
+ on supports.
+
+
+ They are controlled with the
+ external-filter action
+ and have to be defined in the filterfile
+ first.
+
+
+ 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).
+
+
+ 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.
+
+
+ &my-app; will temporary store the content to filter in the
+ temporary-directory.
+
+
+
+EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
+/bin/cat
+
+# Incorrect reimplementation of the filter above in POSIX shell.
+#
+# Note that it's a single job that spans multiple lines, the line
+# breaks are not passed to the shell, thus the semicolons are required.
+#
+# If the script isn't trivial, it is recommended to put it into an external file.
+#
+# In general, writing external filters entirely in POSIX shell is not
+# considered a good idea.
+EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
+while read line; \
+do \
+ echo "$line"; \
+done
+
+EXTERNAL-FILTER: rotate-image Rotate an image by 180 degree. Test filter with limited value.
+/usr/local/bin/convert - -rotate 180 -
+
+
+
+
+
+
+ Currently external filters are executed with &my-app;'s privileges!
+ Only use external filters you understand and trust.
+
+
+
+ External filters are experimental and the syntax may change in the future.
+
+
+
@@ -8356,11 +7590,20 @@ Requests
©right;
+
+ Privoxy is free software; you can
+ redistribute it and/or modify it under the terms of the
+ GNU General Public License, version 2,
+ as published by the Free Software Foundation and included in
+ the next section.
+
+
-License
-
- &license;
-
+License
+
+
+
+