X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=b073142698c104cff7b600209e24bc07f5f49b9a;hb=8d8434eb9aa05b011f9613f88c34d0d7baa704d7;hp=10d0add7aae6befe79c9d53a3a27f1ca0e631395;hpb=9e8218ff00c020b0d3216744fb3f26242326ada5;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 10d0add7..b0731426 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -36,9 +36,9 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.182 2014/05/05 10:08:43 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.190 2014/07/14 13:37:08 fabiankeil Exp $
- Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
@@ -57,12 +57,12 @@
- Copyright &my-copy; 2001-2013 by
+ Copyright &my-copy; 2001-2014 by
Privoxy Developers
-$Id: user-manual.sgml,v 2.182 2014/05/05 10:08:43 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.190 2014/07/14 13:37:08 fabiankeil Exp $
+
+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
@@ -5280,9 +5368,15 @@ new action
filter file section.
- This action will be ignored if you use it together with
- block.
- It can be combined with
+ Requests can't be blocked and redirected at the same time,
+ applying this action together with
+ block
+ 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.
+
+
+ This action can be combined with
fast-redirects{check-decoded-url}
to redirect to a decoded version of a rewritten URL.
@@ -5325,6 +5419,19 @@ 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)
+
+# 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@}}
@@ -5493,6 +5600,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/
@@ -6453,7 +6568,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
@@ -6473,6 +6588,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
+
+
+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 -
+
+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]" -
+
+
+
+
+
+ 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.
+
+
+