Configure Apache with mod_cluster load balancer on Ubuntu

[Part 1 of a 3 part series]

Apache 2.4.7 with Load Balancer on Ubuntu 14.04




This post is the first of a series on how to set up and configure a clustered environment. In this post, we’ll walk through the basic steps required to set up and configure mod_cluster load balancer with Apache 2.4.7 on Ubuntu 14.04. One of the biggest reasons we would like to setup a load balancer in a clustered environment is because the load balancer provides us with a communication channel to forward request from Apache (httpd) to one of a set of Application Server nodes; such as Wildfly.

Note: this guide is by no means the absolute way of doing what we’re setting out to accomplish.

Apache (httpd) will be run on its own dedicated host, where we will enable the mod_cluster module for load balancing. What we will end up with will look something like this:

For this guide, we are mainly concerned with the host network domain, where the host with Apache will reside.

What we need

We’ll need a machine with Ubuntu 14.04 installed. The other tools required for this guide will be covered in the next section.

Tip: although not mandatory, a static IP for this host will prevent a lot of future frustrations.

Installing Apache et al

We’ll install these tools by issuing commands to Ubuntu’s command line.

Tip: change to root user to prevent access permission issues when accessing apt-get and compiling the mod_cluster sources.

Before we start,

We want to make sure our package lists from the repositories are updated to get information on the newest versions of packages and their dependencies. To do this, just run:


apt-get update


For Apache we run the following command.


apt-get install -y apache2


Autoconf is mainly used for configuring source code and Makefiles. We’re not going to do any of this, we just need the tool for building the mod_cluster sources. For Autoconf we run the following command.


apt-get install -y autoconf


Libtool is mainly used to create portable libraries. This is required because the mod_cluster sources are built into .so (Shared Object), which in essence is a shared or dynamically linked library. For Libtool we run the following command.


apt-get install -y libtool


Git is going to be used to clone the latest mod_cluster repo. At writing it was 1.3.1 (beta). The 1.2.x sources is (from what I could gather) only compatible with Apache version 2.2.x. For Git we run the following command.


apt-get install -y git

Apache2 Dev

When compiling the mod_cluster sources, there is a dependency on axps, which is a tool for building and installing extension modules for the Apache HyperText Transfer Protocol (HTTP) server. For axps, we need to install the apache2-dev package, by:

Apache2 Dev

apt-get install -y apache2-dev

 Quickest Way

Alternatively, you can just do all of the above in one go,

Install all

apt-get install -y apache2 autoconf libtool git apache2-dev

That is all we need for now. In the next section we’ll build the mod_cluster sources.

Compiling mod_cluster sourcesapache2-dev

Checkout on Github

Most of the insight gained for this part was found from a french wiki[2]. To compile the sources, we first need to checkout the mod_cluster project on GitHub.

At a suitable location, issue the following command:

Clone mod_cluster


Next, we need to compile the four native modules that make up mod_cluster. First we compile the advertise module, copy it to Apache’s module library and add a directive to enable it in.

Compile advertise

cd native/advertise
./buildconf; ./configure –with-apxs=/usr/bin/apxs; make; cp *.so /usr/lib/apache2/modules/
echo “LoadModule advertise_module /usr/lib/apache2/modules/” >> /etc/apache2/mods-available/proxy_cluster.load

Next is the manager module.

Compile manager

cd ../mod_manager
./buildconf; ./configure –with-apxs=/usr/bin/apxs; make; cp *.so /usr/lib/apache2/modules/
echo “LoadModule manager_module /usr/lib/apache2/modules/” >> /etc/apache2/mods-available/proxy_cluster.load

Then we compile the proxy_cluster module.

Compile proxy_cluster

cd ../mod_proxy_cluster
./buildconf; ./configure –with-apxs=/usr/bin/apxs; make; cp *.so /usr/lib/apache2/modules/
echo “LoadModule proxy_cluster_module /usr/lib/apache2/modules/” >> /etc/apache2/mods-available/proxy_cluster.load

Lastly, we build the slotmem module.

Compile slotmem

cd ../mod_cluster_slotmem
./buildconf; ./configure –with-apxs=/usr/bin/apxs; make; cp *.so /usr/lib/apache2/modules/
echo “LoadModule cluster_slotmem_module /usr/lib/apache2/modules/” >> /etc/apache2/mods-available/proxy_cluster.load

Navigate to /etc/apache2/mods-available/ and see that proxy_cluster.load contains the following four lines.


LoadModule advertise_module /usr/lib/apache2/modules/
LoadModule manager_module /usr/lib/apache2/modules/
LoadModule proxy_cluster_module /usr/lib/apache2/modules/
LoadModule cluster_slotmem_module /usr/lib/apache2/modules/

That is it for compiling the modules. In the next section we will configure the mod_cluster load balancer.

Configuring mod_cluster

The proxy_cluster.load file will be responsible for loading the relevant modules.

However, we still need to add it to the mods-enabled folder in /etc/apache2/.

Symbolic link

To do this, we’re going to add a symbolic link as shown below.

Sym link proxy_cluster.load

In -s /etc/apache2/mods-available/proxy_cluster.load /etc/apache2/mods-enabled/

You can double check the mods-enabled directory to see of it contains a proxy_cluster.load file.

Enable proxy and proxy_ajp

We also need to enable two additional modules which the load balancer will need to work properly, they are proxy and proxy_ajp. We’ll use the provided a2enmod tool from Apache to enable them. See the command below. The tool automatically resolves the dependency for proxy_ajp and enables the proxy module as well.

Enable proxy and proxy_ajp

In -s /etc/apache2/mods-available/proxy_cluster.load /etc/apache2/mods-enabled/

Virtual host directive for the mod_cluster load balancer

Next, we need to configure a virtual host directive for the mod_cluster load balancer. In the mods-available directory inside /etc/apache2/ we create a file called proxy_cluster.conf. The conf file will look like this:


MemManagerFile /var/chache/mod_cluster
 <IfModule manager_module>
  Listen <host>:6666
  ManagerBalancerName mycluster
  <VirtualHost <host>:6666>
    <Location />
      Require all granted
      Allow from <host>
      #e.g.: 192.168.0.
    KeepAliveTimeout 300
    MaxKeepAliveRequests 0
    AdvertiseFrequency 5
    EnableMCPMReceive On
    <Location /mod_cluster_manager>
      SetHandler mod_cluster-manager
      Require all granted
      Allow from <host>
      #e.g.: 192.168.0.
Note: the line “MemManagerFile /var/cache/mod_cluster” is mandatory because the default location Apache will use to store configuration, generate keys for shared memory or lock files is $server_root/logs/, which does not exist.
Tip: ensure the host machine’s IP and port number you’re using for mod_cluster are acessible.


EnableMCPMReceive (Mod-Cluster Management Protocol (MCMP)) is very important, because this connection is used to transmit server-side load balance factors and lifecycle events back to Apache via a custom set of HTTP methods.

We also need to add this proxy_cluster.conf file to the mods-enabled directory. To do this we’ll ad a symbolic link as shown below.

Sym link proxy_cluster.conf

ln -s /etc/apache2/mods-available/proxy_cluster.conf /etc/apache2/mods-enabled/

Now, we need to reload the server, start/stop or restart, which ever takes your preference to ensure Apache pulls in our extensions.

Reload the Apache

/etc/init.d/apache2 reload
service apache2 reload
service apache2 restart

Is it working?

Right, now it’s time to see if our efforts were not in vain. To see if the mod_cluster is running, we have to do two backflips, while spinning a hula hoop around our waist and balancing a glass of water on our nose – at the same time!

Just kidding…

Open a browser window and navigate to <host>:6666/mod_cluster_manager.
You should see a screen similar to the following:


If you see this, congratulations!

You’re a step closer to load balance magic

Stay tuned for the next post in this series. We will be looking at setting up a Wildfly cluster, and how to register the nodes with the load balancer so we can access our application from a single address and let the load balancer balance requests to nodes in the Wildfly cluster.

Any feedback or questions are welcome.

2 comments to “Configure Apache with mod_cluster load balancer on Ubuntu”

You can leave a reply or Trackback this post.

Write a Reply or Comment

Your email address will not be published.