X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fuser-manual%2Ffilter-file.html;h=2fe7948aee33a85f255df59e0dfb16ba31562438;hp=e28533b78ab26a90de54c612e1c6c75c726db9cf;hb=afdf7f7b2cbdff9a333ac73e0bdb74474015705d;hpb=12b554fe26edd92957aaaec82f7505cb3d4bb985 diff --git a/doc/webserver/user-manual/filter-file.html b/doc/webserver/user-manual/filter-file.html index e28533b7..2fe7948a 100644 --- a/doc/webserver/user-manual/filter-file.html +++ b/doc/webserver/user-manual/filter-file.html @@ -6,7 +6,7 @@ Filter Files - + @@ -20,7 +20,7 @@ - + @@ -45,7 +45,7 @@ an "action".

Privoxy supports three different - filter actions: filter to rewrite the content that is send to the client, client-header-filter to @@ -65,6 +65,13 @@ used to change the applying actions through sections with tag-patterns.

+

Finally Privoxy supports the + external-filter action to + enable external filters + written in proper programming languages.

+

Multiple filter files can be defined through the filterfile config directive. The filters as supplied by the developers are located in @@ -134,9 +141,28 @@ FILTER: foo Replace all "foo" with "bar" "_top">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 + +

Most notably, the non-standard option letter U is supported, which turns the default to ungreedy - matching.

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

If you are new to

-

9.1. Filter File +

9.1. Filter File Tutorial

Now, let's complete our "foo" content @@ -825,6 +851,87 @@ s* industry[ -]leading \

+ +
+

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

+ +

Privoxy will temporary store the + content to filter in the temporary-directory.

+ +
Privoxy 3.0.20 User ManualPrivoxy 3.0.24 User Manual
+ + + +
+ 
+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]" -
+
+
+ +
+ + + + + + + + +
Warning
+

Currently external filters are executed with Privoxy's privileges! Only use external + filters you understand and trust.

+
+
+ +

External filters are experimental and the syntax may change in the + future.

+