NAME
mod_sar - apache2 module which works as output filter and it's
          purpose is to Search And Replace strings found in web
          content before it's sending to the client.


COMPILE
mod_sar can be compiled with apxs(8) or manually by hand.

1. Using apxs for compilation:
apxs -c mod_sar.c

If everything goes fine, you will find mod_sar.so under .libs in your
current directory.

2. Compiling mod_sar manually:
gcc -pthread -I/usr/include/httpd -c mod_sar.c
gcc -shared mod_sar.o -Wl,-soname -Wl,mod_sar.so -o mod_sar.so

If needed, modify path to your httpd include directory and if everything
goes fine, you will find mod_sar.so in your current directory.


INSTALL
mod_sar can be installed with apxs(8) or manually by hand.

1. Using apxs for instalation:
This command will compile and install your mod_sar module.
apxs -i -a -c mod_sar.c

Restart apache by first stopping it and then starting it:
apachectl stop
apachectl start

2. Installing mod_sar manually:
cp mod_sar.so /usr/lib/httpd/modules
chown root: /usr/lib/httpd/modules/mod_sar.so
chmod 755 /usr/lib/httpd/modules/mod_sar.so

If needed, modify path to your httpd modules directory.
Now, you have to modify your httpd.conf file. Find the bunch of
LoadModule directives and append your own line under them:
LoadModule sar_module modules/mod_sar.so

Restart apache by first stopping it and then starting it:
apachectl stop
apachectl start


DESCRIPTION
mod_sar ("sar" stands for Search And Replace) is apache2 module which
works as output filter. It's purpose is to search and replace strings
found in web content before it's sending to the client.
Search performed can be case sensitive or case insensitive, depending
on configuration.
Perfect example of common usage of this module is reverse proxy.

Reverse proxy is proxy in front of the local server, which can be
accessed from Internet only trough that proxy. In some cases such
configuration can be used effectively to prevent worms and other
unwanted guests but most commonly it just present a false layer of
security for those who do not understand server - client communication.

Whatever reason you have, for usable reverse proxy you will have to
solve two problems: modification of headers and modification of
content before it's sending to client.

1. Header modification
Header modification is not problem at all. It can be achieved two
ways.
You can use mod_proxy_http:
    <IfModule mod_proxy.c>
        <Proxy *>
            Order deny,allow
            Allow from all
        </Proxy>
        ProxyRequests On
        ProxyPass / http://some-domain.local/
        ProxyPassReverse / http://some-domain.local/
        ProxyErrorOverride On
    </IfModule>
Or, you can use mod_rewrite:
    <IfModule mod_rewrite.c>
        RewriteEngine on
        RewriteRule ^/(.*) http://some-domain.local/$1 [P]
        RewriteOptions inherit
    </IfModule>

2. Content modification
Header modification will make all relative links look like they are
coming from external domain some-domain.com instead of real, local
domain some-domain.local. But if server behind reverse proxy the
serves pages with absolute links, we will have to modify content of
that pages on the fly, using apache2 output filter mechanism.

There are three choices: mod_proxy_html, mod_ext_filter and mod_sar.
The first uses a libxml2 and because of that, it is not good for
purpose such as reverse proxy. For example, libxml2 will seriously
corrupt HTML code in case of a minor errors in HTML such as missing
quote. mod_proxy_html inherits that nasty habit from libxml2 but
if you want to try it your own, you can find that module at
http://apache.webthing.com/mod_proxy_html/
The second one is not a third party module, it comes with apache2
and it can suite needs for reverse proxy but it is not good for heavy
loaded sites because external command is executed for every request.
Here is example of mod_ext_filter usage:
    <IfModule mod_ext_filter.c>
        ExtFilterDefine fixtext mode=output intype=text/html \
            cmd="/bin/sed s/some-domain\.local/some-domain\.com/g"
        <Location />
            SetOutputFilter fixtext
        </Location>
    </IfModule>
And the third one is the one you are just looking at: mod_sar.
See the DIRECTIVES and EXAMPLES sections for usage information.
mod_sar will do one simple thing. It will replace one string
with another, depending on configuration. It can perform case
insensitive search if needed. It has been tested under heavy load
without performance impact.


DIRECTIVES
SarStrings <search_string> <replace_string>
       This directive requires two parameters, search string and
       replace string enclosed with double quotes.
       It can be used in server config and virtual host context.

SarCaseInsensitive <On|Off>
       If set to On, case insensitive search will be performed instead
       of exact string match.
       Default is Off.
       It can be used in server config and virtual host context.

SarVerbose <On|Off>
       If set to On, every time mod_sar is used as filter, message is
       printed into apache error logs.
       Default is Off.
       It can be used in server config and virtual host context.


EXAMPLES
       <IfModule mod_sar.c>
           AddOutputFilterByType sar_filter text/html
           SarStrings "http://some-domain.local" "http//some-domain.com"
           SarCaseInsensitive Off
           SarVerbose Off
       </IfModule>


REQUIREMENTS
Apache-2.0.


COMPATIBILITY
It has been tested on Linux but there is no obvious reason why it
would'n work on other unix platforms supported by apache2.
             OS:  Linux
       compiler:  gcc-2.9x, gcc-3.x
         apache:  apache-2.0.x


BUGS
Current version of mod_sar does not contain known bugs.


SEE ALSO
apxs(8), http://www.apache.org/


AUTHOR
Josip Deanovic <djosip@linuxpages.org>
