CINXE.COM

<!doctype html>     <html class="no-js" lang="en"> <head>   <meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src 'self' https://asciinema.org https://www.google-analytics.com; script-src 'self' 'sha256-h3L/NhdJgGKWmnGRsTCb/wrduwiZ8dYXtCD6USjbTZk=' https://www.googletagmanager.com https://www.google-analytics.com; style-src 'self' 'sha256-CwE3Bg0VYQOIdNAkbB/Btdkhul49qZuwgNCMPgNY5zw=' 'sha256-anQSeQoEnQnBulZOQkDOFf+e6xBIGmqh7M8YFT992co=' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; form-action 'none'; base-uri 'none'; frame-ancestors 'none';">   <meta http-equiv="X-XSS-Protection" content="1; mode=block"> <meta charset="utf-8"> <title>Project mod_cluster – mod_cluster</title> <meta name="keywords" content="about, mod_cluster, mod_proxy_cluster, load, balancer">  <meta name="twitter:title" content="Project mod_cluster"> <meta name="twitter:card" content="summary_large_image"> <meta name="twitter:image" content="https://www.modcluster.io/images/header_1900x100.jpg">  <meta property="og:locale" content="en_US"> <meta property="og:type" content="article"> <meta property="og:title" content="Project mod_cluster"> <meta property="og:url" content="https://www.modcluster.io/"> <meta property="og:site_name" content="mod_cluster"> <meta property="og:image" content="https://www.modcluster.io/images/header_1900x100.jpg">  <link rel="canonical" href="https://www.modcluster.io/"> <link href="https://www.modcluster.io/feed.xml" type="application/atom+xml" rel="alternate" title="mod_cluster Feed">  <meta name="HandheldFriendly" content="True"> <meta name="MobileOptimized" content="320"> <meta name="viewport" content="width=device-width, initial-scale=1.0">  <link rel="stylesheet" href="https://www.modcluster.io/assets/css/main.css"> <meta http-equiv="cleartype" content="on">    <script src="https://www.modcluster.io/assets/js/vendor/modernizr-2.7.1.custom.min.js"></script> <link href='https://fonts.googleapis.com/css?family=PT+Sans+Narrow:400,700%7CPT+Serif:400,700,400italic' rel='stylesheet' type='text/css'>  <link rel="shortcut icon" href="/images/favicon.ico" type="image/x-icon"/> <link rel="apple-touch-icon" href="/images/apple-touch-icon/apple-touch-icon.png"/> <link rel="apple-touch-icon" sizes="57x57" href="/images/apple-touch-icon/apple-touch-icon-57x57.png"/> <link rel="apple-touch-icon" sizes="72x72" href="/images/apple-touch-icon/apple-touch-icon-72x72.png"/> <link rel="apple-touch-icon" sizes="76x76" href="/images/apple-touch-icon/apple-touch-icon-76x76.png"/> <link rel="apple-touch-icon" sizes="114x114" href="/images/apple-touch-icon/apple-touch-icon-114x114.png"/> <link rel="apple-touch-icon" sizes="120x120" href="/images/apple-touch-icon/apple-touch-icon-120x120.png"/> <link rel="apple-touch-icon" sizes="144x144" href="/images/apple-touch-icon/apple-touch-icon-144x144.png"/> <link rel="apple-touch-icon" sizes="152x152" href="/images/apple-touch-icon/apple-touch-icon-152x152.png"/> <link rel="apple-touch-icon" sizes="180x180" href="/images/apple-touch-icon/apple-touch-icon-180x180.png"/> <meta name="apple-mobile-web-app-title" content="mod_cluster"> </head> <body class="page">  <div class="navigation-wrapper"> <div class="site-name"> <a href="https://www.modcluster.io/">mod_cluster</a> </div> <div class="top-navigation"> <nav role="navigation" id="site-nav" class="nav"> <ul> <li><a href="https://www.modcluster.io/" >Introduction</a></li> <li><a href="https://www.modcluster.io/getting-started/" >Getting Started</a></li> <li><a href="https://www.modcluster.io/examples/" >Examples</a></li> <li><a href="https://www.modcluster.io/downloads/" >Downloads</a></li> <li><a href="https://www.modcluster.io/source-code/" >Source Code</a></li> <li><a href="https://docs.modcluster.io" target="_blank">Documentation</a></li> </ul> </nav> </div> </div> <div class="image-wrap"> <img src= "https://www.modcluster.io/images/header_1900x100.jpg" alt="Project mod_cluster feature image"> </div> <div id="main" role="main"> <div class="article-author-side"> <div itemscope itemtype="http://schema.org/Person"> <img src="https://www.modcluster.io/images/mod_cluster-200x200.png" class="bio-photo" alt="mod_cluster bio photo"> <h3 itemprop="name">mod_cluster</h3> <p>mod_cluster is an intelligent native Apache httpd-based and pure-Java Undertow-based load-balancer</p> <a href="https://github.com/modcluster" class="author-social" target="_blank"><i class="fa fa-fw fa-github"></i> GitHub</a> <a href="https://github.com/modcluster/mod_cluster/releases" class="author-social" target="_blank"><i class="fa fa-fw fa-arrow-circle-down"></i> Download releases</a> <a href="https://issues.redhat.com/projects/MODCLUSTER" class="author-social" target="_blank"><i class="fa fa-fw fa-bug"></i> Issue Tracking</a> <a href="https://docs.modcluster.io" class="author-social" target="_blank"><i class="fa fa-fw fa-book"></i> Documentation</a> <a href="https://github.com/modcluster/mod_cluster/discussions" class="author-social" target="_blank"><i class="fa fa-fw fa-commenting"></i> Discussions</a> <a href="https://lists.jboss.org/mailman/listinfo/mod_cluster-dev" class="author-social" target="_blank"><i class="fa fa-fw fa-send-o"></i> JBoss mailing list</a> <a href="mailto:mod_cluster-dev@lists.jboss.org" class="author-social" target="_blank"><i class="fa fa-fw fa-envelope-o"></i> Drop us a line</a> </div> </div> <article class="page"> <h1>Project mod_cluster</h1> <div class="article-wrap"> <section id="table-of-contents" class="toc"> <header> <h3><i class="fa fa-book"></i> Index</h3> </header> <div id="drawer"> <ul id="markdown-toc"> <li><a href="#introduction" id="markdown-toc-introduction">Introduction</a></li> <li><a href="#advantages" id="markdown-toc-advantages">Advantages</a></li> <li><a href="#getting-started" id="markdown-toc-getting-started">Getting started</a></li> </ul> </div> </section>  <h2 id="introduction">Introduction</h2> <p>Project mod_cluster/mod_proxy_cluster is an intelligent load balancer.</p> <p>Like mod_jk and mod_proxy, mod_cluster uses a communication channel to forward requests from the load balancer to one of a set of application server nodes. Unlike mod_jk and mod_proxy, mod_cluster leverages an additional connection between the application server nodes and the load balancer.</p> <p>The application server nodes use this connection to transmit server-side load balance factors and lifecycle events back to load balancer via a custom set of HTTP methods, affectionately called the Mod-Cluster Management Protocol (MCMP). This additional feedback channel allows mod_cluster to offer a level of intelligence and granularity not found in other load balancing solutions.</p> <p>Within Apache httpd, mod_proxy_cluster is implemented as a set of modules for httpd with enabled mod_proxy. Much of the logic comes from mod_proxy, e.g. mod_proxy_ajp provides all the AJP logic needed by mod_proxy_cluster.</p> <h3 id="implementation-and-naming">Implementation and naming</h3> <p>Project mod_cluster consists of two implementations: one in Java and one (native) in C.</p> <p>Both formerly shared the same code repository under the name of mod_cluster. However, the different lifecycles and an effort for a simpler development resulted in their separation. Currently, under mod_cluster is only the Java implementation, whereas the C implementation is now in a separate repository as mod_proxy_cluster.</p> <p>A pure-Java load balancer implementation is available as part of <a href="https://undertow.io/">Undertow</a>. Container integration modules are available for <a href="https://wildfly.org">WildFly</a> (formerly known as JBoss AS), JBoss EAP and Apache <a href="https://tomcat.apache.org">Tomcat</a>.</p> <h2 id="advantages">Advantages</h2> <p>mod_cluster boasts the following advantages over other load balancers:</p> <h3 id="dynamic-configuration-of-httpd-workers">Dynamic configuration of httpd workers</h3> <p>Traditional httpd-based load balancers require explicit configuration of the workers available to a proxy. In mod_cluster, the bulk of the proxy鈥檚 configuration resides on the application servers.</p> <p>The set of proxies to which an application server will communicate is determined either by a static list or using dynamic discovery via the advertising mechanism. The application server relays lifecycle events (e.g. server startup/shutdown) to the proxies allowing them to effectively auto-configure themselves. Notably, the graceful shutdown of a server will not result in a fail-over response by a proxy, as is the case with traditional httpd-based load balancers.</p> <h3 id="server-side-load-balance-factor-calculation">Server-side load balance factor calculation</h3> <p>In contrast with traditional load balancers, mod_cluster uses load balance factors calculated and provided by the application servers rather than computing these in the proxy. Consequently, mod_cluster offers a more robust and accurate set of load metrics than is available from the proxy.</p> <h3 id="fine-grained-web-app-lifecycle-control">Fine grained web-app lifecycle control</h3> <p>Traditional load balancers do not handle web application undeployments particularly well. From the proxy鈥檚 perspective, requests to an undeployed web application are indistinguishable from a request for a non-existent resource and will result in 404 errors. In mod_cluster, each server forwards any web application context lifecycle events (e.g. web-app deploy/undeploy) to the proxy, informing it to start/stop routing requests for a given context to that server.</p> <h3 id="ajp-is-optional">AJP is optional</h3> <p>Unlike mod_jk, mod_cluster does not require AJP. Connections to application server nodes can use HTTP, HTTPS, or AJP.</p> <h2 id="getting-started">Getting started</h2> <p>Ready? Continue to <a href="/getting-started">Getting started</a> page.</p> <hr /> <div class="social-share"> <h4>Share on</h4> <ul> <li> <a href="https://twitter.com/intent/tweet?text=https://www.modcluster.io/" class="twitter" title="Share on Twitter"><i class="fa fa-twitter"></i><span> Twitter</span></a> </li> <li> <a href="https://www.facebook.com/sharer/sharer.php?u=https://www.modcluster.io/" class="facebook" title="Share on Facebook"><i class="fa fa-facebook"></i><span> Facebook</span></a> </li> </ul> </div> </div> </article> </div> <div class="footer-wrap"> <footer> <span><a href="https://www.gnu.org/licenses/lgpl-3.0.en.html">LGPL 3.0</a> — mod_cluster contributors 2025 — Powered by <a href="https://jekyllrb.com" rel="nofollow">Jekyll</a> using the <a href="https://mademistakes.com/minimal-mistakes/" rel="nofollow">Minimal Mistakes</a> theme.</span> </footer> </div>  <script async src="https://www.googletagmanager.com/gtag/js?id=UA-71749425-1" integrity="EBKQYLbbmZRAlEqep3F4fdIsBgoPGWr92mYpPbXfDmyK3FIHy9L9PiXh02C5rfUh" crossorigin="anonymous"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-71749425-1'); </script>   <script src="https://www.modcluster.io/assets/js/vendor/jquery-1.9.1.min.js"></script> <script src="https://www.modcluster.io/assets/js/scripts.min.js"></script> </body> </html>