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. + + +