Application Layer Switching Module for Apache

1. Configuration Guide
2. Apache Configuration
  2.1. Loading Required Modules
  2.2. Configuring mod_layer7
3. Control Scripts
  3.1. Example Script

Configuration Guide

Configuration for mod_layer7 module is divided to two parts:

Apache Configuration
Control Script (optional)

Apache Configuration

This section describes how to configure mod_layer7 into Apache HTTP Server. See configuration directive reference for list of supported configuration directives.

Loading Required Modules

To use mod_layer7 you need have to mod_proxy support compiled/loaded into your Apache HTTP Server.

mod_proxy (and at least one of the 'protocol module' mod_proxy_http, mod_proxy_ajp, ...)
mod_layer7

Following example shows what you should have in Apache HTTP Server httpd.conf file.

config-example-LoadModule.txt

# Load mod_proxy and some protocol modules needed for reverse-proxy operations.
#
# NOTE: change paths to match your apache installation 
#
LoadModule proxy_module          /opt/local/apache/2.2.15+dso/modules/mod_proxy.so
LoadModule proxy_http_module     /opt/local/apache/2.2.15+dso/modules/mod_proxy_http.so
LoadModule proxy_balancer_module /opt/local/apache/2.2.15+dso/modules/mod_proxy_balancer.so
LoadModule proxy_balancer_module /opt/local/apache/2.2.15+dso/modules/mod_proxy_ajp.so

# Configure mod_proxy..
#
# disable proxy requests (mod_layer7 users mod_proxy in reverse-proxy mode)
# 
ProxyRequests Off
ProxyPreserveHost On
ProxyReceiveBufferSize 4096

# Load mod_layer7 module ..
#
# NOTE: change paths to match mod_layer7 install paths.
#
LoadModule layer7_module /opt/local/mod_layer7/0.1.0/lib/libmod_layer7.so

Configuring mod_layer7

...

scripts-example1-config.txt

# load mod_proxy module(s) required for reverse proxy operations..
LoadModule proxy_module      /opt/local/apache/2.2.15+dso/modules/mod_proxy.so
LoadModule proxy_module_http /opt/local/apache/2.2.15+dso/modules/mod_proxy_http.so
LoadModule proxy_module_ajp  /opt/local/apache/2.2.15+dso/modules/mod_proxy_ajp.so

# load mod_layer7 module
LoadModule layer7_module /opt/local/mod_layer7/0.1.0/modules/libmod_layer7.so

# Pool for web-application (tomcat)
#
# NOTE: first defined pool is default pool 
#       use L7DefaultPool to override/explicitely define default pool

<L7Pool "dynamic-pool">
  L7PoolMember "ajp://10.0.0.12:5090" ratio=1.0
  L7PoolMember "ajp://10.0.0.13:5090" ratio=1.0
  L7PoolMember "ajp://10.0.0.14:5090" ratio=0.5

  L7BalancingMethod "round-robin"
  L7PersistMethod   "cookie-insert"
</L7Pool>

# pool of normal HTTP servers for static content
# (eg. images, css files, ...)

<L7Pool "static-pool">
  L7PoolMember "http://10.0.0.20" ratio=1.2
  L7PoolMember "http://10.0.0.21" ratio=1.0
</L7Pool>

# You could also use mod_proxy_balancer pools
# 
# <L7Pool "balancer-pool">
#  L7PoolMember "balancer://mycluster"
# </L7Pool>  
#
# <Proxy balancer://mycluster>
# BalancerMember http://192.168.1.50:80
# BalancerMember http://192.168.1.51:80
# </Proxy>
# 

L7DefaultPool     "dynamic-pool"
L7PerlScript      "example1.pl"

# define sub-routine names to be called on different 
# events during HTTP request processing cycle.
# 
L7EventFunction ON_REQUEST   on_request
L7EventFunction ON_RESPONSE  on_response
L7EventFunction ON_LBFAILURE on_lbfailure
# L7EventFunction ON_STARTUP   on_startup
# L7EventFunction ON_SHUTDOWN  on_shutdown

Control Scripts

Control scripts written in Perl language can be used for creating powerful traffic manipulations and content based load balancing criterias. See control scripts reference document for more information.

Example Script

scripts-example1-script.txt

# -*-perl-*- 
# 
# To use this file use configuration directive:
#  
# L7PerlScript /path/to/this/file.pl
#
# See: http://layer7.sourceforge.net/config.html for more details
#

use L7::Runtime;

# 
# L7EventFunction ON_REQUEST on_request
#

sub on_request
{
    # obtain handle to context,request and response objects..
    # my ($context, $request, $response) = L7::Runtime::ON_REQUEST(@_);
    my ($context, $request, $response) = L7::Runtime::OBJECTS(@_);
        
    my $uri = $request->get_uri();
    #
    # select 'static-pool' with criteria based on 
    # request URI..
    # 
    if (index($uri, "/static") >= 0) {
        $context->select_pool("static-pool");
    } else {
        # use default pool (== dynamic pool)
    }

    # you could do other things like...
    $request->add_header('X-Client-Address', $request->get_client_ip());
    $request->add_header('X-Client-Port',    $request->get_client_port());
    
}

#
# L7EventFunction ON_REQUEST on_response
#

sub on_response
{
    # obtain handle to context,request and response objects..
    # my ($context, $request, $response) = L7::Runtime::ON_RESPONSE(@_);
    my ($context, $request, $response) = L7::Runtime::OBJECTS(@_);

    # security by obscurity
    $response->set_header('Server', 'Acme-HTTP-Server');
    
    # ...
}

# 
# L7EventFunction ON_LBFAILURE on_failure
#

sub on_lbfailure
{
    # obtain handle to context,request and response objects..
    # my ($context, $request, $response) = L7::Runtime::ON_LBFAILURE(@_);
    my ($context, $request, $response) = L7::Runtime::OBJECTS(@_);
    my $uri     = $request->get_uri();
    my $count   = $request->get_retry_count();
    $request->set_header('X-Layer7-LBFAILURE-URI', $uri);
    # warn "$$ : PERL($0) :: on_lbfailure() retry_count: $count - URI: $uri\n";
    if ($count > 1) {
        # change pool and retry ...
        $context->select_pool("fallback-pool");
    }
    return 0;
}

Essentials

Get mod_layer7

Documentation