Home | History | Annotate | Download | only in mod_sed
      1 Table of contents :
      2 1. Introduction
      3 2. Compilation
      4    2.1 Compilation on Unix platforms
      5    2.2 Compiling on Windows
      6 3. Installation
      7 4. Configuration
      8    4.1 Loading sed module.
      9    4.2 Configuring filter for a directory/location
     10    4.3 Configuring sed scripts
     11 5. Examples
     12    5.1 Adding a output (response) filter
     13    5.2 Adding a input (request) filter
     14       5.2.1 Converting "<" and ">" characters in input data in an HTML form.
     15    5.3 Removing a filter
     16 6. Sed differences.
     17    6.1 a\ and c\ commands
     18 7. About License
     19 
     20 
     21 1. Introduction
     22 ---------------
     23    Apache sed filter can be used to filter the input (typically POST data) and
     24    output filter (generated data) using sed commands. Sed code is taken from
     25    Opensolaris sed command (/usr/ucb/sed). Man page for sed is located at
     26    http://docs.sun.com/app/docs/doc/816-5165/sed-1b?a=view
     27 
     28    Functional specification documentation is available at mod_sed_filter.html
     29 
     30 2. Compilation
     31 --------------
     32 
     33 2.1 Compilation on Unix platforms
     34 ---------------------------------
     35     To compile the mod_sed, use the apxs tool provided by apache :
     36     $ apxs -c mod_sed.c regexp.c sed0.c sed1.c
     37          apxs will typically generate the mod_sed.so in .libs directory.
     38 
     39 2.2 Compiling on Windows
     40 ------------------------
     41     Windows apache don't have apxs tool so to compile mod_sed, we need
     42     apache sources (built).
     43     C:> mkdir sed
     44     C:> cd sed
     45     C:> rem Copy sources to sed directory
     46        Now build the sources using mod_sed.mak makefile. Set the APACHE_DIR
     47        to your Apache installation directory in mod_sed.mak file and then 
     48        build.
     49        Make sure you have VC 6 installed and you have sourced vcvars32.bat.
     50     C:> nmake /f mod_sed.mak APACHE_DIR=<path to apache>
     51         If successful then compiled library is located in Release\mod_sed.so 
     52 
     53 
     54 3. Installation
     55 ---------------
     56    Copy mod_sed.so in <apache_inst_dir>/modules directory. 
     57 
     58 4. Configuration
     59 ----------------
     60 
     61 4.1 Loading sed module.
     62 ---------------------------
     63     Load the sed module using LoadModule apache directive in httpd.conf e.g
     64 LoadModule sed_module modules/mod_sed.so
     65 
     66 4.2 Configuring filter for a directory/location
     67 ------------------------------------------------
     68     Filter can be added using AddOutputFilter apache directive in 
     69     httpd.conf e.g 
     70 
     71        AddOutputFilter Sed html
     72 
     73 4.3 Configuring sed scripts
     74 ---------------------------
     75     Sed script/command for output filter is provided by OutputSed and for input
     76     filter, it is provided by InputSed e.g
     77 
     78        OutputSed "s/california/CA/g"
     79 
     80     Multiple sed scripts are provided by multiple OutputSed/InputSed
     81     directives.
     82 
     83 5. Examples
     84 -----------
     85 
     86 5.1 Adding a output (response) filter
     87 --------------------------
     88 <Directory "/opt/sun/apache2/htdocs/testsed">
     89     AddOutputFilter Sed html
     90     OutputSed "s/california/CA/g"
     91     OutputSed "s/washington/WA/g"
     92 </Directory>
     93 
     94    The above example will replace the string "california" to "CA" and
     95    "washington" to "WA" in all html docs in testsed directory before sending
     96    to client.
     97 
     98 5.2 Adding a input (request) filter
     99 -----------------------------------
    100     Following example adds a input filter to php cgi scripts.  Sed scripts
    101     will be executed for any POST data to php files.
    102 <Directory "/opt/sun/apache2/cgi-bin">
    103     AddInputFilter Sed php
    104     InputSed "s/california/CA/g"
    105 </Directory>
    106     In the above example, if POST (or even GET in HTTP/1.1) data (not the
    107     headers) contains the string "california" then it is replaced with string
    108     "CA" before the post data is made available to php script.
    109 
    110 5.2.1 Converting "<" and ">" characters in input data in an HTML form.
    111 ----------------------------------------------------------------------
    112 <Directory "/opt/sun/apache2/cgi-bin">
    113     AddInputFilter Sed php
    114     InputSed "s/</&lt;/g"
    115     InputSed "s/%3c/&lt;/g"
    116     InputSed "s/%3C/&lt;/g"
    117     InputSed "s/>/&gt;/g"
    118     InputSed "s/%3e/&gt;/g"
    119     InputSed "s/%3E/&gt;/g"
    120 </Directory>
    121 
    122 5.3 Removing a filter
    123 ---------------------
    124     Once a filter is added to a directory, it works for any subdirectory
    125     underneath. To remove a filter for a particular subdirectory
    126     RemoveOutputFilter/RemoveInputFilter apache directives are used. Following
    127     removes the output filter from subdir1.
    128 <Directory "/opt/sun/apache2/htdocs/testsed/subdir1">
    129     RemoveOutputFilter Sed html
    130 </Directory>
    131 
    132 
    133 
    134 6. Sed differences.
    135 ------------------
    136 
    137 6.1 a\ and c\ commands
    138 ----------------------
    139     sed allows commands to continue by adding "\" at the e.g.
    140 a\
    141 ok
    142 q
    143 
    144 If we specify the equivalent in httpd.conf e.g
    145 OutputSed "a\"
    146 OutputSed "ok"
    147 OutputSed "q"
    148 
    149 Since "a\" command expect new line to be followed, httpd.conf provides no
    150 means to insert new line (AFAIK) so it doesn't seem possible to use "a\"
    151 and "c\" commands.
    152 
    153 7. About License
    154 ----------------
    155     The code is available under Apache 2.0 license. While the original sed code
    156 from OpenSolaris.org was licensed under CDDL, Sun is dontating this code
    157 under Apache license to the benefit of Apache Community.  The code has been
    158 derived from 4 files which are published under CDDL license in the ON
    159 consolidation. These files are :
    160 http://src.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/ucbcmd/sed/sed.h
    161 http://src.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/ucbcmd/sed/sed0.c
    162 http://src.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/ucbcmd/sed/sed1.c
    163 http://src.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/ucbhead/regexp.h
    164 
    165