| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache module mod_ext_filter</TITLE> |
| </HEAD> |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Module mod_ext_filter</H1> |
| |
| <P> |
| This module is contained in the <CODE>mod_ext_filter.c</CODE> file, with |
| Apache 2.0 and later. It provides the ability to pass the response body |
| through an external program before delivering to the client. |
| <CODE>mod_ext_filter</CODE> is not compiled into the server by default. |
| </P> |
| |
| <H2>Summary</H2> |
| <P> |
| This is an <STRONG>experimental</STRONG> module and should be used with |
| care. Test your <CODE>mod_ext_filter</CODE> configuration carefully to |
| ensure that it performs the desired function. You may wish to review |
| XXX for background on the Apache filtering model. |
| </P> |
| |
| <P> |
| <CODE>mod_ext_filter</CODE> presents a simple and familiar programming |
| model for filters. With this module, a program which reads from stdin and |
| writes to stdout (i.e., a Unix-style filter command) can be a filter for |
| Apache. This filtering mechanism is much slower than using a filter which |
| is specially written for the Apache API and runs inside of the Apache |
| server process, but it does have the following benefits: |
| </P> |
| |
| <UL> |
| <LI>the programming model is much simpler |
| <LI>any programming/scripting language can be used, provided that |
| it allows the program to read from standard input and write to standard |
| output |
| <LI>existing programs can be used unmodified as Apache filters |
| </UL> |
| |
| <P> |
| Even when the performance characteristics are not suitable for production |
| use, <CODE>mod_ext_filter</CODE> can be used as a prototype environment |
| for filters. |
| </P> |
| |
| <H2>Directives</H2> |
| <UL> |
| <LI><A HREF="#extfilterdefine">ExtFilterDefine</A> |
| <LI><A HREF="#extfilteroptions">ExtFilterOptions</A> |
| </LI> |
| </UL> |
| |
| <HR> |
| |
| <H2><A NAME="extfilterdefine">ExtFilterDefine</A></H2> |
| <P> |
| <A |
| HREF="directive-dict.html#Syntax" |
| REL="Help" |
| ><STRONG>Syntax:</STRONG></A> ExtFilterDefine <EM>filtername</EM> <EM>parameters</EM> |
| <BR> |
| <A |
| HREF="directive-dict.html#Default" |
| REL="Help" |
| ><STRONG>Default:</STRONG></A> <EM>None</EM> |
| <BR> |
| <A |
| HREF="directive-dict.html#Context" |
| REL="Help" |
| ><STRONG>Context:</STRONG></A> server |
| <BR> |
| <A |
| HREF="directive-dict.html#Override" |
| REL="Help" |
| ><STRONG>Override:</STRONG></A> none |
| <BR> |
| <A |
| HREF="directive-dict.html#Status" |
| REL="Help" |
| ><STRONG>Status:</STRONG></A> Experimental |
| <BR> |
| <A |
| HREF="directive-dict.html#Module" |
| REL="Help" |
| ><STRONG>Module:</STRONG></A> mod_ext_filter |
| <BR> |
| <A |
| HREF="directive-dict.html#Compatibility" |
| REL="Help" |
| ><STRONG>Compatibility:</STRONG></A> Only available in Apache 2.0 or later |
| |
| <P> |
| The <CODE>ExtFilterDefine</CODE> directive defines the characteristics of |
| an external filter, including the program to run and its arguments. |
| </P> |
| |
| <P> |
| <EM>filtername</EM> specifies the name of the filter being defined. This name |
| can then be used in AddOutputFilter directives. It must be unique among all |
| registered filters. <EM>At the present time, no error is reported by the |
| register-filter API, so a problem with duplicate names isn't reported to the |
| user.</EM> |
| </P> |
| |
| <P> |
| Subsequent parameters can appear in any order and define the external command |
| to run and certain other characteristics. The only required parameter is |
| <EM>cmd=</EM>. These parameters are: |
| </P> |
| |
| <DL> |
| <DT>cmd=<EM>cmdline</EM> |
| <DD> |
| The <SAMP>cmd=</SAMP> keyword allows you to specify the external command |
| to run. If there are arguments after the program name, the command line |
| should be surrounded in quotation marks. |
| <DT>mode=<EM>mode</EM> |
| <DD> |
| <EM>mode</EM> should be <EM>output</EM> for now (the default). In the |
| future, <EM>mode=input</EM> will be used to specify a filter for request |
| bodies. |
| <DT>intype=<EM>imt</EM> |
| <DD> |
| This parameter specifies the internet media |
| type (i.e., MIME type) of documents which should be filtered. By default, |
| all documents are filtered. If <CODE>intype=</CODE> is specified, |
| the filter will be disabled for documents of other types. |
| <DT>outtype=<EM>imt</EM> |
| <DD> |
| This parameter specifies the internet media |
| type (i.e., MIME type) of filtered documents. It is useful when the filter |
| changes the internet media type as part of the filtering operation. By |
| default, the internet media type is unchanged. |
| <DT>PreservesContentLength |
| <DD> |
| The <SAMP>PreservesContentLength</SAMP> keyword specifies that the filter |
| preserves the content length. This is not the default, as most filters |
| change the content length. In the event that the filter doesn't modify the |
| length, this keyword should be specified. |
| </DL> |
| |
| <H2><A NAME="extfilteroptions">ExtFilterOptions</A></H2> |
| <P> |
| <A |
| HREF="directive-dict.html#Syntax" |
| REL="Help" |
| ><STRONG>Syntax:</STRONG></A> ExtFilterOptions <EM>option option ...</EM> |
| <BR> |
| <A |
| HREF="directive-dict.html#Default" |
| REL="Help" |
| ><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoLogStderr</EM> |
| <BR> |
| <A |
| HREF="directive-dict.html#Context" |
| REL="Help" |
| ><STRONG>Context:</STRONG></A> directory |
| <BR> |
| <A |
| HREF="directive-dict.html#Override" |
| REL="Help" |
| ><STRONG>Override:</STRONG></A> none |
| <BR> |
| <A |
| HREF="directive-dict.html#Status" |
| REL="Help" |
| ><STRONG>Status:</STRONG></A> Experimental |
| <BR> |
| <A |
| HREF="directive-dict.html#Module" |
| REL="Help" |
| ><STRONG>Module:</STRONG></A> mod_ext_filter |
| <BR> |
| <A |
| HREF="directive-dict.html#Compatibility" |
| REL="Help" |
| ><STRONG>Compatibility:</STRONG></A> Only available in Apache 2.0 or later |
| |
| <P> |
| The <CODE>ExtFilterOptions</CODE> directive specifies special processing |
| options for <CODE>mod_ext_filter</CODE>. <EM>Option</EM> can be one of |
| <DL> |
| <DT>DebugLevel=<EM>n</EM> |
| <DD> |
| The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of |
| debug messages generated by <CODE>mod_ext_filter</CODE>. By default, no |
| debug messages are generated. This is equivalent to |
| <SAMP>DebugLevel=0</SAMP>. With higher numbers, more debug messages are |
| generated, and server performance will be degraded. The actual meanings |
| of the numeric values are described with the definitions of the DBGLVL_ |
| constants near the beginning of <CODE>mod_ext_filter.c</CODE>. |
| <P> |
| Note: The core directive LogLevel should be used to cause debug messages |
| to be stored in the Apache error log. |
| <DT>LogStderr | NoLogStderr |
| <DD> |
| The <SAMP>LogStderr</SAMP> keyword specifies that messages written to |
| standard error by the external filter program will be saved in the Apache |
| error log. <SAMP>NoLogStderr</SAMP> disables this feature. |
| </DL> |
| </P> |
| |
| Example: |
| |
| <PRE> |
| ExtFilterOptions LogStderr DebugLevel=0 |
| </PRE> |
| |
| Messages written to the filter's standard error will be stored in the Apache |
| error log. No debug messages will be generated by |
| <CODE>mod_ext_filter</CODE>. |
| |
| <P> |
| |
| <H2>Examples</H2> |
| |
| <H3>Generating HTML from some other type of response</H3> |
| |
| <PRE> |
| # mod_ext_filter directive to define a filter to HTML-ize text/c files |
| # using the external program /usr/bin/enscript, with the type of the |
| # result set to text/html |
| ExtFilterDefine c-to-html mode=output intype=text/c outtype=text/html \ |
| cmd="/usr/bin/enscript --color -W html -Ec -o - -" |
| |
| <Directory "/export/home/trawick/apacheinst/htdocs/c"> |
| |
| # core directive to cause the new filter to be run on output |
| AddOutputFilter c-to-heml |
| |
| # mod_mime directive to set the type of .c files to text/c |
| AddType text/c .c |
| |
| # mod_ext_filter directive to set the debug level just high |
| # enough to see a log message per request showing the configuration |
| # in force |
| ExtFilterOptions DebugLevel=1 |
| |
| </Directory> |
| </PRE> |
| |
| <H3>Implementing a content encoding filter</H3> |
| |
| <PRE> |
| # mod_ext_filter directive to define the external filter |
| ExtFilterDefine gzip mode=output cmd=/bin/gzip |
| |
| <Location /gzipped> |
| |
| # core directive to cause the gzip filter to be run on output |
| AddOutputFilter gzip |
| |
| # mod_header directive to add "Content-Encoding: gzip" header field |
| Header set Content-Encoding gzip |
| |
| </Location> |
| </PRE> |
| |
| <H3>Slowing down the server</H3> |
| <PRE> |
| # mod_ext_filter directive to define a filter which runs everything |
| # through cat; cat doesn't modify anything; it just introduces extra |
| # pathlength and consumes more resources |
| ExtFilterDefine slowdown mode=output cmd=/bin/cat preservescontentlength |
| |
| <Location /> |
| |
| # core directive to cause the slowdown filter to be run several times on |
| # output |
| AddOutputFilter slowdown slowdown slowdown |
| |
| </Location> |
| </PRE> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
