Home
Projects
Downloads
About me
Lang
HR EN

mod_sar

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. Good 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 the reverse proxy 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.

DOWNLOAD
mod_sar download

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/

AUTHORS
Josip Deanovic djosip@linuxpages.org