From: Fabian Keil Date: Mon, 2 Jun 2014 06:20:51 +0000 (+0000) Subject: Add documentation for external filters X-Git-Tag: v_3_0_22~136 X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=commitdiff_plain;h=2b8bec1ba7fa010ae0aa6aadfae62261ca11dabd Add documentation for external filters --- diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml index c1ef4d7b..d8d9fb3f 100644 --- a/doc/source/p-config.sgml +++ b/doc/source/p-config.sgml @@ -3,7 +3,7 @@ Purpose : Used with other docs and files only. - $Id: p-config.sgml,v 2.103 2014/02/10 14:39:13 fabiankeil Exp $ + $Id: p-config.sgml,v 2.104 2014/05/05 09:59:30 fabiankeil Exp $ Copyright (C) 2001-2011 Privoxy Developers http://www.privoxy.org/ See LICENSE. @@ -97,7 +97,7 @@ Sample Configuration File for Privoxy &p-version; - $Id: p-config.sgml,v 2.103 2014/02/10 14:39:13 fabiankeil Exp $ + $Id: p-config.sgml,v 2.104 2014/05/05 09:59:30 fabiankeil Exp $ Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/ @@ -588,6 +588,55 @@ II. FORMAT OF THE CONFIGURATION FILE + +temporary-directory + + + + Specifies: + + A directory where Privoxy can create temporary files. + + + + Type of value: + + Path name + + + + Default value: + + unset + + + + Effect if unset: + + No temporary files are created, external filters don't work. + + + + Notes: + + + To execute external filters, + Privoxy has to create temporary files. + This directive specifies the directory the temporary files should + be written to. + + + It should be a directory only Privoxy + (and trusted users) can access. + + + + + +@@#temporary-directory .]]> + + + logdir diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 10d0add7..eb4fd30e 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -36,7 +36,7 @@ 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.183 2014/05/26 10:48:39 fabiankeil Exp $ Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/ See LICENSE. @@ -62,7 +62,7 @@ -$Id: user-manual.sgml,v 2.182 2014/05/05 10:08:43 fabiankeil Exp $ +$Id: user-manual.sgml,v 2.183 2014/05/26 10:48:39 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. + + + + 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 @@ -6453,7 +6539,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 +6559,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 + + + + + + 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. + + +