Author: mladen.turk(a)jboss.com Date: 2008-05-28 11:37:46 -0400 (Wed, 28 May 2008) New Revision: 1626 Added: sandbox/aloha/ sandbox/aloha/docs/ sandbox/aloha/docs/ActiveTransaction.vsd sandbox/aloha/docs/BasicDataModel.vsd sandbox/aloha/docs/CommErr.png sandbox/aloha/docs/CommErr.vsd sandbox/aloha/docs/ConfigAppDataFlow.vsd sandbox/aloha/docs/ConfigBalancerDataFlow.vsd sandbox/aloha/docs/ConfigHostDataFlow.vsd sandbox/aloha/docs/ConfigMemberDataFlow.vsd sandbox/aloha/docs/ConnErrorDataFlow.vsd sandbox/aloha/docs/ConnPoolDataFlow.vsd sandbox/aloha/docs/EmptyConfig.png sandbox/aloha/docs/EmptyConfig.vsd sandbox/aloha/docs/GeneralTopology.png sandbox/aloha/docs/GeneralTopology.vsd sandbox/aloha/docs/InitConfig.png sandbox/aloha/docs/InitConfig.vsd sandbox/aloha/docs/ManyToMany.png sandbox/aloha/docs/ManyToMany.vsd sandbox/aloha/docs/NewApplication.png sandbox/aloha/docs/NewApplication.vsd sandbox/aloha/docs/NodeDown.png sandbox/aloha/docs/NodeDown.vsd sandbox/aloha/docs/NodeNew.png sandbox/aloha/docs/NodeNew.vsd sandbox/aloha/docs/NodeRemove.png sandbox/aloha/docs/NodeRemove.vsd sandbox/aloha/docs/OneToMany.png sandbox/aloha/docs/OneToMany.vsd sandbox/aloha/docs/OneToOne.png sandbox/aloha/docs/OneToOne.vsd sandbox/aloha/docs/StartupHostDataFlow.vsd sandbox/aloha/docs/UPingErrorDataFlow.vsd sandbox/aloha/docs/UpdateConfig.png sandbox/aloha/docs/UpdateConfig.vsd sandbox/aloha/docs/globaltopo.dia sandbox/aloha/docs/globaltopo.png sandbox/aloha/docs/html/ sandbox/aloha/docs/html/images/ sandbox/aloha/docs/html/images/add.gif sandbox/aloha/docs/html/images/bdbm.png sandbox/aloha/docs/html/images/code.gif sandbox/aloha/docs/html/images/commnew.png sandbox/aloha/docs/html/images/commshutdown.png sandbox/aloha/docs/html/images/commstop.png sandbox/aloha/docs/html/images/configappdf.png sandbox/aloha/docs/html/images/configbalancerdf.png sandbox/aloha/docs/html/images/configdeploy.png sandbox/aloha/docs/html/images/confighostdf.png sandbox/aloha/docs/html/images/configinit.png sandbox/aloha/docs/html/images/configmemberdf.png sandbox/aloha/docs/html/images/configupdate.png sandbox/aloha/docs/html/images/configzero.png sandbox/aloha/docs/html/images/connconcepts.png sandbox/aloha/docs/html/images/connerr.png sandbox/aloha/docs/html/images/connerrordf.png sandbox/aloha/docs/html/images/connpooldf.png sandbox/aloha/docs/html/images/design.gif sandbox/aloha/docs/html/images/docs.gif sandbox/aloha/docs/html/images/fix.gif sandbox/aloha/docs/html/images/genarch.png sandbox/aloha/docs/html/images/jboss_logo.gif sandbox/aloha/docs/html/images/jbossweblogo.gif sandbox/aloha/docs/html/images/m2m.png sandbox/aloha/docs/html/images/mcmpclass.png sandbox/aloha/docs/html/images/mcmpclasssm.png sandbox/aloha/docs/html/images/o2m.png sandbox/aloha/docs/html/images/o2o.png sandbox/aloha/docs/html/images/starthostdf.png sandbox/aloha/docs/html/images/update.gif sandbox/aloha/docs/html/images/upingdf.png sandbox/aloha/docs/html/images/void.gif sandbox/aloha/docs/html/index.html sandbox/aloha/docs/html/modcluster.html sandbox/aloha/docs/html/style.css sandbox/aloha/docs/mcmp-class.dia sandbox/aloha/docs/mcmp-class.png sandbox/aloha/docs/rfc5501.txt Log: Add Aloha docs Added: sandbox/aloha/docs/ActiveTransaction.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ActiveTransaction.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/BasicDataModel.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/BasicDataModel.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/CommErr.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/CommErr.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/CommErr.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/CommErr.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ConfigAppDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ConfigAppDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ConfigBalancerDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ConfigBalancerDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ConfigHostDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ConfigHostDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ConfigMemberDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ConfigMemberDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ConnErrorDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ConnErrorDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ConnPoolDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ConnPoolDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/EmptyConfig.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/EmptyConfig.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/EmptyConfig.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/EmptyConfig.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/GeneralTopology.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/GeneralTopology.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/GeneralTopology.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/GeneralTopology.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/InitConfig.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/InitConfig.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/InitConfig.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/InitConfig.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/ManyToMany.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ManyToMany.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/ManyToMany.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/ManyToMany.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/NewApplication.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NewApplication.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/NewApplication.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NewApplication.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/NodeDown.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NodeDown.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/NodeDown.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NodeDown.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/NodeNew.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NodeNew.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/NodeNew.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NodeNew.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/NodeRemove.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NodeRemove.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/NodeRemove.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/NodeRemove.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/OneToMany.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/OneToMany.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/OneToMany.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/OneToMany.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/OneToOne.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/OneToOne.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/OneToOne.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/OneToOne.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/StartupHostDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/StartupHostDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/UPingErrorDataFlow.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/UPingErrorDataFlow.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/UpdateConfig.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/UpdateConfig.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/UpdateConfig.vsd =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/UpdateConfig.vsd ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/globaltopo.dia =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/globaltopo.dia ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/globaltopo.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/globaltopo.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/add.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/add.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/bdbm.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/bdbm.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/code.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/code.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/commnew.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/commnew.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/commshutdown.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/commshutdown.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/commstop.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/commstop.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configappdf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configappdf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configbalancerdf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configbalancerdf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configdeploy.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configdeploy.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/confighostdf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/confighostdf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configinit.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configinit.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configmemberdf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configmemberdf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configupdate.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configupdate.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/configzero.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/configzero.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/connconcepts.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/connconcepts.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/connerr.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/connerr.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/connerrordf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/connerrordf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/connpooldf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/connpooldf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/design.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/design.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/docs.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/docs.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/fix.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/fix.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/genarch.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/genarch.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/jboss_logo.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/jboss_logo.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/jbossweblogo.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/jbossweblogo.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/m2m.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/m2m.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/mcmpclass.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/mcmpclass.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/mcmpclasssm.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/mcmpclasssm.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/o2m.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/o2m.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/o2o.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/o2o.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/starthostdf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/starthostdf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/update.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/update.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/images/upingdf.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/upingdf.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/html/images/void.gif =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/html/images/void.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/html/index.html =================================================================== --- sandbox/aloha/docs/html/index.html (rev 0) +++ sandbox/aloha/docs/html/index.html 2008-05-28 15:37:46 UTC (rev 1626) @@ -0,0 +1,11 @@ +<html> +<head> + <title>JBoss&trade; ModCluster</title> + <link type="text/css" rel="stylesheet" href="./style.css"/> + <meta value="Mladen Turk" name="author"/> + <meta value=&quot;mturk(a)redhat.com&quot; name="email"/> +</head> +<body> + This page intentionally left blank. +</body> +</html> \ No newline at end of file Property changes on: sandbox/aloha/docs/html/index.html ___________________________________________________________________ Name: svn:eol-style + native Added: sandbox/aloha/docs/html/modcluster.html =================================================================== --- sandbox/aloha/docs/html/modcluster.html (rev 0) +++ sandbox/aloha/docs/html/modcluster.html 2008-05-28 15:37:46 UTC (rev 1626) @@ -0,0 +1,858 @@ +<html> +<head> + <title>JBoss&trade; ModCluster</title> + <link type="text/css" rel="stylesheet" href="./style.css"/> + <meta value="Mladen Turk" name="author"/> + <meta value=&quot;mturk(a)redhat.com&quot; name="email"/> +</head> +<body> + <img src="./images/jboss_logo.gif"> + <br/><br/><br/> + <h2>1. ModCluster - Technology overview</h2> + + <p>ModCluster is next generation clustering solution for connecting native + web servers and application servers. + The major advantage of ModCluster is dynamic configuration that is done + by ModClusterService and propagated to all web servers. + </p> + <p>ModClusterService is dedicated application embedded inside Application Server + or an stand-alone application. It's main duty is to configure and manage front-end + web server(s) and to track various objects in application server(s). + </p> + <img src="./images/o2m.png"> + <p class="image"><strong>Figure 1.</strong> Typical configuration with Web server in front of + multiple application servers. + </p> + <br/> + <p>ModClusterService connects to the ModCluster using HTTP or HTTPS protocol + and both configures and monitors Apache Httpd Web server. + </p> + <p>ModClusterService is capable of managing multiple Web servers in front. + Any number of web servers and be defined. Their status are checked at regular + intervals and ModClusterService can act accordingly + </p> + <img src="./images/m2m.png"> + <p class="image"><strong>Figure 2.</strong> Multiple Web servers in front of + multiple application servers. + </p> + <br/><br/> + <h2>1.2. Graceful node shutdown</h2> + <p>When an Application Server Stop event is received from one of the Nodes + that are member of the cluster, or direct command to Stop the server is + made by Administrator the ModClusterService informs all Web Servers he is + aware being operable to Stop serving new requests. + </p> + <img src="./images/commstop.png"> + <p class="image"><strong>Figure 3.</strong> Node Stop event handling. + </p> + <p>Existing requests that have session affinity information present will + still continue to be served by that particular node. This allows to + gracefully shutdown particular node for maintenance. + </p> + <br/><br/> + <h2>1.3. Node disable</h2> + <p>Unlike graceful shutdown, Disable immediately shutdowns the connections from + web servers to that particular node. + </p> + <img src="./images/commshutdown.png"> + <p class="image"><strong>Figure 4.</strong> Node Disable event handling. + </p> + <p>This operation is usually issued after graceful shutdown and after + all active sessions timed out, or it can be used as a way of putting Nodes + down in case there is session replication in place among application servers, + meaning that users will not loose their sessions. + </p> + <br/><br/> + <h2>1.4. Communication errors</h2> + <p>If there is communication error between particular web server and one of the + Application servers the ModClusterService will be informed about that on next + regular status interval query. + </p> + <img src="./images/connerr.png"> + <p class="image"><strong>Figure 5.</strong> Communication error handling. + </p> + <p>Reasons for communication errors can be caused by many reasons. + The ModCluster service will figure out the reason, and if the reason + is unrecoverable it will inform all other Web servers that one of the + nodes is down. Multiple handling scenarios can then be employed from + setting up the fail-over node, to informing the administrator via e-mail + </p> + <br/><br/> + <h2>1.5. Node discovery</h2> + <p>ModeClusterServices uses JBossClustering to discover new nodes that + have joined the cluster. In case of such event the front-end Web servers + are informed about that and node configuration is added. + </p> + <img src="./images/commnew.png"> + <p class="image"><strong>Figure 6.</strong> Node discovery handling. + </p> + <br/><br/> + <br/><br/> + <h2>2. ModCluster - Basic design</h2> + <p>ModCluster basic design is shown on the following picture + </p> + <img src="./images/genarch.png"> + <p class="image"><strong>Figure 7.</strong> Basic Architecture. + </p> + <p>Shared memory is used to dynamically configure the Apache Httpd so it can + use zero-configuration presumption of ModCluster. + The core engine for ModClusterProxy is <strong>mod_proxy</strong>, and + supported Apache Httpd versions are <strong>2.2.3</strong> and up. + </p> + <br/><br/> + <h2>2.1. Startup</h2> + <p>Upon startup ModCluster service uses configuration and connects to the + Apache Httpd Web server that has loaded ModCluster native module. + </p> + <img src="./images/configzero.png"> + <p class="image"><strong>Figure 8.</strong> ModCluster startup. + </p> + <p>Apache Httpd server on startup has empty configuration, so any + user request will produce 404 until ModClusterService configures the + ModCluster. + </p> + <br/><br/> + <h2>2.2. Initial Configuration</h2> + <p>ModClusterService discovers the members of the cluster and all + additional information like defined Hosts and deployed Applications. + </p> + <img src="./images/configinit.png"> + <p class="image"><strong>Figure 9.</strong> ModCluster initialization. + </p> + <p>ModClusterService has the full view of the cluster that + is managed, so it can decide what configuration will be send + to the Web server. It can use some sort of GUI or any other + type of configuration for that purpose. + </p> + <br/><br/> + <h2>2.3. Undeploying applications</h2> + <p>When the undeploy event is received from the particular + Node that information is send to the Web server. + </p> + <img src="./images/configupdate.png"> + <p class="image"><strong>Figure 10.</strong> Undeploy/Stop Application. + </p> + <p>ModCluster can handle undeploy events in various ways depending + on the instructions received from ModClusterService. + If the Undeploy will be followed by Deploy (Redeploy event) + it may queue the requests until the application is deployed + again. + </p> + <br/><br/> + <h2>2.4. Deploying new applications</h2> + <p>When the deploy event is received from the particular + Node that information is send to the Web server. + </p> + <img src="./images/configdeploy.png"> + <p class="image"><strong>Figure 11.</strong> Deploying New applications. + </p> + <p>When new application is deployed to the cluster that information + is send to all web servers and is ready to be used. + ModClusterManager adds that information to the shared memory, + and ModClusterProxy can use that info to route the requests + to the newly deployed application. + </p> + <br/><br/> + <br/><br/> + <h2>3. ModCluster Management Protocol -- MCMP/1.0</h2> + <p>ModCluster uses HTTP/1.1 protocol for the management of clustering + properties, creation and management of cluster nodes, application + name space manipulation, and load balancing. + Complete description of the protocol can be found in the RFC-like form + at <a href="http://jira.jboss.com/jira/secure/attachment/12319781/rfc5501.... Jira</a>. + </p> + <p>ModClusterManager parses HTTP requests at the predefined location. + By default, the listening location is <code>/modclustermanager</code>. + However the administrator can for increased security use different + naming and protect this url inside Apache Httpd <code>Location</code> directive: + </p> + <pre> + &lt;Location /manager&gt; + SetHandler ModClusterManagerHandler + Order Deny,Allow + Allow from 192.168.0 + &lt;/Location&gt; + </pre> + <p>For even more enhanced security certain operations can be limited, allowing + multiple MCMP capable clients to gather data and only certain to manage + the ModCluster. + </p> + <pre> + &lt;Location /manager/info&gt; + SetHandler ModClusterManagerHandler + Order Deny,Allow + Allow from All + &lt;/Location&gt; + </pre> + <pre> + &lt;Location /manager/config&gt; + SetHandler ModClusterManagerHandler + Order Deny,Allow + Allow from 192.168.0 + &lt;/Location&gt; + </pre> + </p> + <p>Major protocol presumption is the single header value named + <code>Server-Resource</code> that <b>must</b> be present for each + management request. + <br/> + The format of the <code>Server-Resource</code> header variable + corresponds to the HTTP State Management Mechanism <code>rfc2109</code>, + or commonly known as Cookie specification. + </p> + <p>This allows to go beyond request query size limitations and also there + is no need for additional query parameter encoding that would have to + be used for query like processing. + </p> + <p>Each management request produces reply with <code>text/plain</code> + mime type, and manager uses the body of the reply as an response + to the management request + </p> + <br/><br/> + <h2>3.1. Protocol commands</h2> + <p>Each management request must define operation or command that ModCluster must + accomplish. If the operation is successful the ModCluster responds with + <code>OK</code> and sends any additional data for that command. + </p> + <p>Commands that MCMP protocol supports are: + <ul> + <li><strong>INFO</strong> + command causes the manager to gather the information about + the specific resource on the server. + </li> + <br/> + <li><strong>ENABLE</strong> + command causes the manager to enable the specific resource + on the server. + </li> + <br/> + <li><strong>DISABLE</strong> + command causes the manager to disable the specific resource + on the server. + Depending on the resource object type the DISABLE command has different + consequences. For Node object it will disable further acceptance of + the request that does not carry the session affinity mark information, + while preserving the ones that carry + the session affinity mark. + </li> + <br/> + <li><strong>STOP</strong> + command causes the manager to stop the specific resource + on the server. + </li> + <br/> + <li><strong>DELETE</strong> + command causes the manager to completely remove the specific + resource on the server. + </li> + <li><strong>CONFIG</strong> + command causes the manager to create or update the specific + resource on the server. + </li> + </ul> + </p> + <p>Commands are case insensitive and can be send to the manager in various ways: + <ul> + <li>As query argument<br/> + <pre> + GET /modclustermanager?info HTTP/1.1 + Host: localhost + Server-Resource: Host/foo + </pre> + </li> + <li>As <code>Server-Command</code> header<br/> + <pre> + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: info + Server-Resource: Host/foo + </pre> + </li> + </ul> + </li> + <li>As <code>Command</code> section inside <code>Server-Resource</code><br/> + <pre> + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Resource: Command=info; Host/foo + </pre> + </li> + <li>As last part or Url path<br/> + <pre> + GET /modclustermanager/info HTTP/1.1 + Server-Resource: Host/foo + </pre> + </li> + </ul> + </p> + <br/><br/> + <h2>3.2. Info command</h2> + <p>Info command is used to gather the info about the web server resources. + Each resource carries his own set of attributes that are contained in + the response message one line at a time + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager?info HTTP/1.1 + Host: localhost + Server-Resource: Server + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 193 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + ServerName localhost@localdomain + ServerRoot /usr/local/http + ServerVersion Apache/2.2.8 (Unix) + ServerBuilt Jan 18 2008 00:37:19 + ServerArchitecture 32-bit + ThreadsPerChild 64 + MaxRequestsPerChild 0 + </pre> + <p>If the single resource attribute is requested then the only + the single line with attribute value is replied + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager?info HTTP/1.1 + Host: localhost + Server-Resource: Server; ThreadsPerChild + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 2 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + 64 + </pre> + <br/><br/> + <h2>3.3. Enable command</h2> + <p>Enable command is used to enable specific resource. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Enable + Server-Resource: Member/foo + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK + </pre> + <p>If the enable is attempted for non existing resource then + the error message is replied + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Enable + Server-Resource: Member/foo + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 27 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + ?Unknown-Type: Member/foo + </pre> + <br/><br/> + <h2>3.4. Disable command</h2> + <p>Disable command has the same format as Enable command. + The only difference is that disable command disables the + resource making it unavailable for any new processing. + </p> + <br/><br/> + <h2>3.5. Stop command</h2> + <p>Stop command has the same format as Enable command. + The only difference is that stop command disables the + resource for any all processing. + </p> + <p>If the Enable, Disable or Stop commands are attempted on + the resource object that doesn't support that operation + the error message is returned + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Stop + Server-Resource: Server + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 36 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + ?Error: 1; Operation not permitted + </pre> + <br/><br/> + <h2>3.6. Delete command</h2> + <p>Delete command deletes the resource from the shared memory. + However some resources can be delete only if they have been + previously stopped by Stop command. + In case the object like Application was not stopped previously + the error message is returned + </p> + <pre> + ?Error: 16; Device or resource busy + </pre> + <br/><br/> + <h2>3.6. Config command</h2> + <p>Config command updates or creates a new resource if it's not + already created. + </p> + <p>The resource is activated after the command is executed if all + needed attributes are present. + For example if Config creates a new Member it is not activated + until all the required parameters are set. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Config + Server-Resource: Member/node1 + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK|Id + </pre> + <p>If this was a new Member object added it will not be activated + until protocol and communication parameters are set. The returned + value in that case will not be <code>OK</code> but rather the + internal database record number or <code>Id</code> or the new Member. + ModClusterService can then use that Id for referencing the Member + insted using its name. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Config + Server-Resource: Member/node1; Type=ajp, Activation=A + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK + </pre> + <p>The latest directive will activate the node1 because all required + parameter are set. By default the Address parameter for Node is + <code>localhost</code> and port default to <code>8009</code> because of + ajp type. + </p> + <br/><br/> + <br/><br/> + <h2>4. Objects</h2> + <p>Diagram on the Figure 12. shows all objects that are managed + inside ModCluster + </p> + <a href="./images/mcmpclass.png"> + <img src="./images/mcmpclasssm.png" border="0" alt="Click for the full image"> + </a> + <p class="image"><strong>Figure 12.</strong> ModCluster UML diagram. + </p> + <br/><br/> + <h2>4.1. Database model</h2> + <p>Diagram on the Figure 13. shows basic database model for few core objects + </p> + <img src="./images/bdbm.png"> + <p class="image"><strong>Figure 13.</strong> Object database model. + </p> + <p>Database is stored in shared memory so that it is directly accessible by all + child processes in Web server. Each table is stored in separate shared memory + and each record is of fixed size. This makes memory usage not fully optimized, + but allows very fast record access. + </p> + <p>Each table <code>Id</code> field is not actually stored in the table, but rather + it represents the record number in the table. Referencing tables contain that + record number as foreign record key. The tables are not indexed, however some + tables are backed up by in-memory hash table for faster access. + Before each request, inside request post processing phase, ModCluster module + checks the atomic time stamps of each table, and if they do not match the + internal hash table index is recreated. This allows both optimal key based + access and does not require full blown backed database. + </p> + <p>Internal Hash tables are created on demand, and the cause for their creation is + the size of the table and length of the key value. Those options are compile time + defined, and in general the table is not indexed unless its size gets really big + (thousands of records). In most use cases those numbers won't be that large, and + simple sequential scan is used instead. + </p> + <br/><br/> + <h2>4.2. Host table initialization</h2> + <p>Diagram on the Figure 14. shows the data flow diagram of Host tables that is + executed on Web server startup. + </p> + <img src="./images/starthostdf.png"> + <p class="image"><strong>Figure 14.</strong> Web server startup. + </p> + <p>When the Web server is started or fully restarted it contains empty configuration + as shown on the Figure 9. However Host and Server tables are created on the startup + containing objects that are defined inside native Web server configuration. + </p> + <p>Host table is loaded with all virtual host definitions by default. + However the administrator of the web server can use specific directives + in case the Web server is used for large ISP providers with thousands of + Virtual Host definitions. + The only reason for using those directives is for limiting the memory + usage if there will be no need to map requests from each Virtual Host to the + Application server cluster. Two configuration directives exist for this + reason <code>ModClusterHostCopy</code> and <code>ModClusterEnable</code> + The first directive if set to <code>Off</code> will not create any Host + object except default Host, and the second if defined inside Virtual Host + and set to <code>On</code>will create Host record for that virtual host. + </p> + <br/><br/> + <h2>4.3. Host configuration</h2> + <p>Diagram on the Figure 15. shows the data flow diagram of Host tables when + the <strong>Config</strong> command is executed. + </p> + <img src="./images/confighostdf.png"> + <p class="image"><strong>Figure 15.</strong> Host object configuration. + </p> + <p>Host configuration operates on two main levels, Host itself and Alias. + Host object contains actual data and is stored directly in HostList table. + Both Host and Alias are stored in Host table, with later having table + self reference key to the Host. + This allows to have a single table for both Host and Aliases, but since + Aliases are dependent on the Host, any operation on the Host will propagate + to all its aliases. HostList table is helper table because Host and its + Aliases always point to the same data. Their only difference is in the + name, so this table is used to lower down the overall memory usage. + </p> + <p>Host Config like any other config directive can operate on wildchar + principle, meaning that it will be executed for all Host objects matching + the given expression. Expression evaluator is modified <code>fnmatch</code> + Posix function, available from the Apache APR library. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Config + Server-Resource: Host/www.*.com; KeepAlive=Off + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK + </pre> + <p>The upper example will disable <code>KeepAlive</code> in Web Server + for all virtual host requests matching <code>www.*.com</code>. The Command + will actually set the <code>KeepAlive</code> attribute to <code>Off</code> + for each Host table entry. Since the operation is performed on Host table + and KeepAlive attribute is held in HostList table this attribute will be + applied for both Host and all of his Aliases. Likewise if one of the Aliases + matches the <code>www.*.com</code> pattern it will cause the attribute change + in both parent Host and all other Aliases for that Host. + </p> + <br/><br/> + <h2>4.4. Application configuration</h2> + <p>Diagram on the Figure 16. shows the data flow diagram of Application table when + the <strong>Config</strong> command is executed. + </p> + <img src="./images/configappdf.png"> + <p class="image"><strong>Figure 16.</strong> Application object configuration. + </p> + <p>Applications are contained inside Host object and cannot live outside the + Host as stand-alone entity. If the Host was not provided with the Config + command default Host is selected. Default host <code>_default_</code> is + the Web servers default host that matches the Server object ServerName attribute. + </p> + <p>Application name uniquely identifies application within Host and it defaults + to <code>Url</code> field. However the application can be referenced by name + attribute as convenient method for accessing application object. Application + command SubType is always url unless enclosed inside underscore characters + <code>'_'</code> in which case SubType is assumed to be application name not its url. + There is no need to add the leading slash for the Application Url because it is assumed. + </p> + <p>When new Host object is created default Application with empty Url is created + for that Host as well, but it is initially disabled. This Application object + corresponds to Application server Default Context. This Application has + empty Url that corresponds to Application server Context object with + <code>path=&quot;&quot;</code>. Its name is internally set to <code>_default_</code>, + and can be later referenced as <code>Application/_default_</code>. + If later used as part of Application Config command the ModCluster will not need + to create that object again, so this is basically performance optimization. + </p> + <p>Operations on the Application object can be performed using wildchar causing + execution on all applications matching the expression. However attributes for + such operation must not be application object unique. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Config + Server-Resource: Host/www.*.com; Application/*/production; State=S + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK + </pre> + <p>The upper example set State of all Applications to <code>S (Stopped)</code> + which Url matches <code>/*/production</code> and which are contained + in Hosts which ServerName matches <code>www.*.com</code>. + </p> + <p>Returned value for newly created applications is its numeric record <code>Id</code> + and can be later used when referencing object if the SubType is enclosed + inside braces. The Id of each object within its type is guaranteed to be + unique, so this allows to have multiple objects sharing the same name + while still being uniquely identified inside ModCluster. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Config + Server-Resource: Application/(1234); State=S + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK + </pre> + <br/><br/> + <h2>4.5. Member configuration</h2> + <p>Diagram on the Figure 17. shows the data flow diagram of Member table when + the <strong>Config</strong> command is executed. + </p> + <img src="./images/configmemberdf.png"> + <p class="image"><strong>Figure 17.</strong> Member object configuration. + </p> + <p>Member object corresponds to the physical Application server instance. + Actually it corresponds to the <code>Connector</code> element in Application + Server configuration and represents the physical connection to the + Application server. The reason for such design comes from old mod_jk and + mod_proxy limitations using Ajp connections. They have tendency for high + connection count, so this enable to create fail-over to the same physical + Application Server instance but on other usually Http connector. + </p> + <p>Like on any other Resource object the operations on the Member object can + be done using wildchar causing to execute the Config on all Members matching + the given expression. Of course this is like for Application or Host object limited + only to the non unique attributes + </p> + <p>Member can be assigned to Balancer object, and if not explicitly specified + when added it will be added to the default Balancer object that is created + on startup. Member can be referenced by multiple Balancer objects allowing + different balancer algorithms on application name space basis. + </p> + <br/><br/> + <h2>4.6. Balancer configuration</h2> + <p>Diagram on the Figure 18. shows the data flow diagram of Balancer table when + the <strong>Config</strong> command is executed. + </p> + <img src="./images/configbalancerdf.png"> + </a> + <p class="image"><strong>Figure 18.</strong> Balancer object configuration. + </p> + <p>Balancer object is responsible for routing requests to one of its Member + objects. On system startup a single default Balancer object is created + and it is used for all Members unless explicitly specified during Member + configuration. Members can be referenced by multiple balancers but not + by default and some other balancers. If the member is referenced from + non default Balancer it will be removed from the default Balancer object. + </p> + <p>Balancer can contain reference to Application objects and Host objects. + Host object is special kind of relationship resulting in referencing + all Application objects contained inside Host object. This allows that + new Applications deployed inside specific Host get automatically referenced + by the specified Balancer object. + </p> + <pre> + ModClusterService -> ModClusterManager + + GET /modclustermanager HTTP/1.1 + Host: localhost + Server-Command: Config + Server-Resource: Balancer/productionCluster; Host/production.*; Member/node[1-7]; + + + ModClusterManager -> ModClusterService + + HTTP/1.1 200 OK + Server: Apache/2.2.8 (Unix) + Content-Length: 4 + Keep-Alive: timeout=5, max=100 + Connection: Keep-Alive + Content-Type: text/plain + + OK|Id + </pre> + <p>The upper example will create (if it wasn't alread, returning Id of the newly created) + Balancer object and add reference to it for all Applications that are + contained in each Host which name matches the <code>production.*</code> + expression, and add reference to Member objects which name matches + the <code>node[1-7]</code> expression. As can be seen that simple Config + command can result in large number of internal objects created and referenced. + Deploying new applications to any <code>production.*</code> Host will automatically + reference that Application to this Balancer object. + </p> + <br/><br/> + <h2>4.7. Connection Pool configuration</h2> + <p>Diagram on the Figure 19. shows the data flow diagram of Connection Pool + the <strong>Config</strong> command for Member is executed. + </p> + <img src="./images/connpooldf.png"> + <p class="image"><strong>Figure 19.</strong> Connection Pool management. + </p> + <p>For each Member if not specifically configured during + creation ModCluster creates a pool of empty connections with maximum size + equal to Web server's maximum limit. For threaded servers this value + equals to <code>MaxThreadsPerChild</code> configuration directive in Apache + Httpd. This pool is created for each child process the Web server + creates for serving requests. Updating this value and dynamically changing + it from already set or default value is done both by Configure + Member command and by maintenance thread or on first request, which ever + comes first. If the value is lower then already defined, all extra + connections that doesn't currently serve requests are closed. If then + extra connections are currently serving requests, they are closed when + those request are finished. + </p> + <br/><br/> + <br/><br/> + <h2>5. Communication Error Handling</h2> + <p>Diagram on the Figure 20. shows how ModProxy deducts connection errors. + </p> + <img src="./images/connerrordf.png"> + <p class="image"><strong>Figure 20.</strong> Connection Error algorithm. + </p> + <p>ModCluster uses <code>Ping/Pong</code> feature of the <code>Ajp</code> + protocol or modified <code>OPTIONS</code> request for <code>Http</code> + protocol to verify the physical connection state before sending actual request + to the Member itself. This allows to fail over to another cluster Member + if the member has connection errors. + However various actions can be done when such error occurs, from + simply failing over to another node, to reconnect attempts, or any + combination of them. + </p> + <p>For Http(s) protocol needs to be developed special <code>OPTIONS</code> + filter that will allow <code>HTTP/1.1 with KeepAlive</code>. + <em>Default Tomcat implementation doesn't allow KeepAlive for OPTIONS request + so this either needs to get revised or create a new Filter for + ModCluster usage</em>. + </p> + <p>ModCluster will mark the Member as in Error state only when there is no + active connections present. In other case it will cause the same + behavior as for Connection Poll busyness. The reason for such behavior is + probability that Application Server cannot accept any new connections + since there is already some number of requests currently executing. + </p> + <br/><br/> + <h2>5.1. Unattended Connection Monitoring</h2> + <p>Diagram on the Figure 21. shows how ModProxy monitors the connections + for availability. + </p> + <img src="./images/upingdf.png"> + <p class="image"><strong>Figure 21.</strong> Connection state monitoring. + </p> + <p>Maintenance thread that is created inside each Web server child process + on regular time interval checks the health of all connections in the + Connection poll. He does that only for connections that are not + active (currently serving requests) and which were inactive for a + certain amount of time. This solves two major problems found in mod_jk + and current mod_proxy. Firewall shutting down inactive connections and + burst load delays. + </p> + <p>In case the Member was in error state ModCluster will try to reconnect + to the Application server creating new connection if needed. This is + major difference compared with mod_jk and mod_proxy and is called + <b>Active Recovery</b>. + <br/> + <br/> + <img src="./images/connconcepts.png"> + <p class="image"><strong>Figure 22.</strong> Connection states. + <p>Connection between ModCluster and Application server has two major states + <code>Active Request</code> and <code>Active Transaction</code>. + During Active Request state management thread cannot access the Connection + and it is presumed as active. Active Transaction can contain multiple + Request cycles. The KeepAliveTimeout depends on two things, if not set + directly for a Connector it inherits the KeepAliveTimeout of the Web server, + corresponding to the client timeout. If set it usually corresponds to the + connectionTimeout of the Application server's Connector. ModCluster can + close the connection if there were no Active Requests inside this time + interval. There is no need to check the connections since we are sure it + was already closed by the Application server. + </p> +</body> +</html> \ No newline at end of file Property changes on: sandbox/aloha/docs/html/modcluster.html ___________________________________________________________________ Name: svn:eol-style + native Added: sandbox/aloha/docs/html/style.css =================================================================== --- sandbox/aloha/docs/html/style.css (rev 0) +++ sandbox/aloha/docs/html/style.css 2008-05-28 15:37:46 UTC (rev 1626) @@ -0,0 +1,220 @@ +html { + font-size: 11px; +} + +body { + background-color: #ffffff; + padding: 0 1em 0 0; + font-family: Helvetica, Arial, sans-serif; + font-weight: normal; +} + +h1 { + padding: 0.2em; + margin: 0; + background-color: inherit; + text-decoration: none; + font-size: 1.6em; + font-weight: bold; +} + +h2 { + padding: 0.2em 0 0.2em 0.7em; + margin: 0 ; + text-decoration: none; + font-size: 1.4em; + font-weight: bold; +} + +h2 a, +h2 a:hover, +h2 a:active { + color: inherit; + background-color: inherit; + text-decoration: none; +} + +h3 { + background-color: inherit; + text-decoration: none; + font-weight: bold; + font-size: 1.2em; + padding: 0; + margin: 0 ; +} + +h4 { + background-color: inherit; + text-decoration: none; + font-weight: bold; + font-size: 1.1em; + padding: 0; + margin: 0 ; +} + +/* margin adjustment */ +h3 + *, h4 + * { + margin-top: 0; +} + +strong { + font-weight: bold; +} + +q, em, var { + font-style: italic; +} + +p.image { + font-size: 0.8em; + font-style: italic; +} + +/* fixup IE & Opera + * otherwise they forget to inherit + * the computed font-size value + */ +table, code { + font-size: 1em; +} + +a:link, +a:visited, +a:active { + color: #0073c7; + background-color: inherit; +} + +a:link:hover, +a:visited:hover { + color: #0073c7; + background-color: inherit; +} + +div.screen { + background-color: #000000; + font-size: 1em; + color: #ffffff; + margin: 1em 2em 1em 1em; +} + +div.example { + background-color: #e5ecf3; + color: #000000; + padding: 0.5em; + margin: 1em 2em 1em 1em; +} + +div.warn { + color: #ed2e38; +} + +pre, code { + font-family: Andale Mono, Courier New, Courier, monospace; + font-weight: normal; + font-style: normal; + font-size: 1em; +} +em.screen { + font-weight: normal; + font-style: normal; + font-size: 1em; + color: #c0c0c0; +} +p.screen { + background-color: #000000; + border-style: none; + color: #c0c0c0; + margin-left: 0.5em; + margin-right: 0px; + text-align: left; + font-size: 1em; +} +b.screen { + font-weight: normal; + font-style: normal; + color: #c0c0c0; + font-size: 1em; +} + +b.note { + font-weight: normal; + font-style: italic; + color: #c0c0c0; + font-size: 1em; +} + +code.screen { + font-family: Andale Mono, Courier New, Courier, monospace; + background-color: #000000; + border-style: none; + color: #c0c0c0; + margin-left: 0.5em; + margin-right: 0px; + text-align: left; +} +b.code { + font-family: Andale Mono, Courier New, Courier, monospace; + font-weight: normal; + font-style: normal; + font-size: 1em; + color: #023264; +} +p.todo { + background-color: #ffffff; + border-style: none; + color: #ed2e38; + text-align: justify; + font-size: 1em; +} + +td.section { + background-color: #023264; + color: #ffffff; + font-weight: bold; + font-size: 1.2em; + padding-left: 0.5em; +} + +td.subsection { + background-color: #557697; + color: #ffffff; + font-weight: bold; + font-size: 1em; + padding-left: 0.5em; +} + +th.directive { + background-color: #e5ecf3; + color: #405871; + font-weight: bold; + font-size: 1em; +} + +th.attribute { + background-color: #e5ecf3; + color: #405871; + font-weight: bold; + font-size: 1em; +} + +table.screen { + background-color: #000000; + border: 1px solid; +} + +td.screen { + padding-left: 0.5em; + background-color: #000000; + text-align: left; +} + +td.figure { + background-color: #ffffff; + color: #000000; + font-family: Andale Mono, Courier New, Courier, monospace; + font-weight: normal; + font-style: italic; + font-size: 0.8em; + text-align: justify; +} Property changes on: sandbox/aloha/docs/html/style.css ___________________________________________________________________ Name: svn:eol-style + native Added: sandbox/aloha/docs/mcmp-class.dia =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/mcmp-class.dia ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: sandbox/aloha/docs/mcmp-class.png =================================================================== (Binary files differ) Property changes on: sandbox/aloha/docs/mcmp-class.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: sandbox/aloha/docs/rfc5501.txt =================================================================== --- sandbox/aloha/docs/rfc5501.txt (rev 0) +++ sandbox/aloha/docs/rfc5501.txt 2008-05-28 15:37:46 UTC (rev 1626) @@ -0,0 +1,1854 @@ + + + + + +Network Working Group M. Turk +Request for Comments: 5501 J. Clere +Category: Standards Track B. Stansberry + B. Ban + Red Hat Middleware, LLC + March 2008 + + + HTTP Extensions for Mod Cluster Management Protocol -- MCMP/1.0 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardisation state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) Red Hat Middleware, LLC. or its licensors, as applicable. + All Rights Reserved. + +Abstract + + This document specifies a set of methods, headers, and content-types + ancillary to HTTP/1.1 for the management of clustering properties, + creation and management of cluster nodes, application namespace + manipulation, and load balancing. + +Table of Contents + + 1 Introduction ............................................2 + 1.1 Purpose ..............................................2 + 1.2 Requirements .........................................2 + 1.3 Terminology ..........................................3 + 1.4 Overall Operation ....................................5 + 2 Notational Conventions and Generic Grammar ..............6 + 3 Protocol Parameters .....................................6 + 3.1 HTTP Version .........................................6 + 3.2 MCMP Version .........................................6 + 3.3 HTTP Methods .........................................6 + 3.4 MCMP URL .............................................7 + 3.5 Command ..............................................7 + 3.5.1 INFO ..............................................8 + 3.5.2 ENABLE ...........................................10 + 3.5.3 DISABLE ..........................................11 + 3.5.4 STOP .............................................12 + 3.5.5 DELETE ...........................................13 + 3.5.6 CONFIG ...........................................14 + 3.5.7 EXEC ...........................................14 + 3.5.8 RESET ...........................................14 + 4 Resource Types .........................................15 + 4.1 Server ..............................................15 + 4.1.1 General Information ..............................15 + 4.1.2 Client Connection Information ....................17 + 4.2 Host ................................................18 + 4.2.1 General Information ..............................18 + 4.2.2 Application ......................................19 + 4.3 Balancer ............................................21 + 4.3.1 StickySession ....................................21 + 4.3.2 StickySessionCookie ..............................21 + 4.3.3 StickySessionPath ................................22 + 4.3.4 StickySessionRemove ..............................23 + 4.3.5 StickySessionForce ...............................23 + 4.3.6 TimeOut ..........................................23 + 4.4 Member ..............................................24 + 4.4.1 Type .............................................24 + 4.4.2 Address ..........................................24 + 4.4.3 Port .............................................24 + 4.4.4 Route ............................................25 + 4.4.5 Domain ...........................................25 + 4.4.6 Ping .............................................25 + 4.4.7 MaxConnections ...................................26 + 4.4.8 MinConnections ...................................26 + 4.4.9 TTL ..............................................26 + 4.4.10 LF ..............................................26 + 4.4.11 Distance ........................................26 + 4.4.12 Activation ......................................27 + 4.4.13 Statistical data ................................27 + 4.4.14 ENABLE ..........................................28 + 4.4.15 DISABLE .........................................28 + 4.4.16 STOP ............................................28 + 4.4.17 INFO ............................................28 + 4.4.18 DELETE ..........................................29 + 4.5 Application .........................................29 + 4.5.1 State ............................................29 + 4.5.2 Statistical data .................................29 + 4.5.3 DELETE ...........................................30 + 4.6 ApplicationPool .....................................31 + 4.6.1 Status ...........................................31 + 4.6.2 Concurrency ......................................31 + 4.6.3 TimeOut ..........................................31 + 4.6.4 Statistical data .................................31 + 5.Manager ................................................32 + 5.1 Strict ...............................................33 + 5.2 ProtocolVersion ......................................33 + 5.3 ServerId .............................................34 + + +Turk, et. al. Standards Track [Page 1] + +RFC 5501 MCMP March 2008 + + +1 Introduction + +1.1 Purpose + + This document describes an extension to the HTTP/1.1 protocol that + allows clients to perform remote clustering management operations. + This extension provides a coherent set of methods, headers, request + entity body formats, and response entity body formats that provide + operations for: + + Members: The ability to create, remove, update and query information + about cluster members, such as their node address, session route, etc. + Also, the ability to link Applications of any media type to related + members. + + Applications: The ability to create sets of mapped Applications and to + establish relationship between applications and members. + +1.2 Requirements + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [34]. + + An implementation is not compliant if it fails to satisfy one or more + of the MUST or REQUIRED level requirements for the protocols it + implements. An implementation that satisfies all the MUST or REQUIRED + level and all the SHOULD level requirements for its protocols is said + to be "unconditionally compliant"; one that satisfies all the MUST + level requirements but not all the SHOULD level requirements for its + protocols is said to be "conditionally compliant." + + + +Turk, et. al. Standards Track [Page 2] + +RFC 5501 MCMP March 2008 + + +1.3 Terminology + + This specification uses a number of terms to refer to the roles + played by participants in, and objects of, the MCMP communication. + + connection + A transport layer virtual circuit established between two programs + for the purpose of communication. + + client + A program that establishes connections for the purpose of sending + requests. + + message + The basic unit of HTTP communication, consisting of a structured + sequence of octets matching the syntax defined in HTTP/1.1 + specification [RFC2068]. + + request + An HTTP request message, as defined in HTTP/1.1 specification + [RFC2068]. + + response + An HTTP response message, as defined in HTTP/1.1 specification + [RFC2068]. + + server + An application program that accepts connections in order to + service requests by sending back responses. Any given program may + be capable of being server; our use presumes it is Web server. + + member + A dynamic resource in the web server that connects to the + remote backend application server node and proxies the requests + back and forth. + + node + An backend application program that accepts connections in order + to service requests from member by sending back responses. + + node connection + A transport layer virtual circuit established between member + and node for the purpose of communication. + + node connection pool + A pool of connections between member and node for the purpose + of limiting and caching the node connections. + + +Turk, et. al. Standards Track [Page 3] + +RFC 5501 MCMP March 2008 + + + node protocol + The protocol used for communication between member and node. + Supported protocols are Apache Jserv Protocol (AJP) version + 1.3 as described in AJP protocol specification + [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html], + HTTP 1.1 [RFC2068] and HTTPS [RFC2818]. + + application + A network data object or service that can be identified by a URI, + as defined n HTTP/1.1 specification [RFC2068] and provided by + the node. + + cluster + A set of nodes that creates an management entity; our + use presumes they provide the same set of applications. + + cluster group + A set of nodes in the cluster that shares the session replication + between them; our use presumes they have "buddy replication" + in place. + + balancer + An static resource in the web server that consists of the list + of members. Balancer chooses the best member for servicing the + client request from the cluster or cluster group. + + manager + An static resource in the web server that receives protocol + requests and manages the resources in the web server. + + administrator + An application or applications in the cluster that communicates + with the manager using MCMP protocol. Its main usage is to + provide the manager with list of nodes, clusters, cluster groups + and applications together with the balancer information needed + for selecting the best node within the cluster for servicing the + client request. + + + +Turk, et. al. Standards Track [Page 4] + +RFC 5501 MCMP March 2008 + + +1.4 Overall Operation + + The MCMP protocol is a request/response protocol. An administrator + sends a request to the web server in the form of a HTTP request method, + URI, and protocol version, followed by a set of headers containing request + modifiers, node information, etc. The manager responds with a status line, + including the message's protocol version and a success or error code, + followed by a text/plain MIME-like message containing server information, + entity metainformation, and possible entity-body content. + + Client--->Balancer--->1*Member---->1*Node + | | | + +---------Manager<---->1*Administrator + + The figure above shows the typical relation between participants + in the system. + +Turk, et. al. Standards Track [Page 5] + +RFC 5501 MCMP March 2008 + + +2 Notational Conventions and Generic Grammar + + The Notational Conventions and Generic Grammar used is the one specified + in the HTTP 1.1 protocol specification RFC2068 [2]. + +3 Protocol Parameters + +3.1 HTTP Version + + MCMP uses HTTP 1.1 protocol version as defined in HTTP/1.1 specification + [RFC2068]. For the increased security the protocol used can be HTTP over + TLS or usually known as HTTPS [RFC2818]. + +3.2 MCMP Version + + The current MCMP version according to this rfc is "1.0". + MCMP uses a "<major>.<minor>" numbering scheme to indicate versions + of the protocol. + + The version of an MCMP message is indicated by an MCMP-Version field + in the first line of the message. + + MCMP-Version = "MCMP" "/" 1*DIGIT "." 1*DIGIT + + Note that the major and minor numbers MUST be treated as separate + integers and that each may be incremented higher than a single digit. + Thus, MCMP/2.4 is a lower version than MCMP/2.13, which in turn is + lower than MCMP/12.3. Leading zeros MUST be ignored by recipients and + MUST NOT be sent. + +3.3 HTTP Methods + + MCMP uses GET HTTP method for management and OPTIONS method for + determining the validity of the connection between member and node. + + + +Turk, et. al. Standards Track [Page 6] + +RFC 5501 MCMP March 2008 + + + +3.4 MCMP URL + + Each mcmp requests MUST be an valid http request with URI + compliant to the RFC2068 [3.2]. The query MAY be present to + specify the command. In case the query is not present then the + administrator MUST provide the Server-Command header with corresponding + command value or use the appropriate HTTP method. + This section defines the scheme-specific + syntax and semantics for mcmp URLs. + + mcmp_URL = "http:" "//" host [ ":" port ] abs_path [ cmd_path | "?" query ] + + If the port is empty or not given, port 80 is assumed. Each mcmp_URL MUST + have either cmd_path, query or Server-Command header that corresponds to the + specific command the manager will fulfil. An example mcmp URL would be: + + http://localhost:8000/manager/info + or: + http://localhost:8000/manager?info + or: + GET /manager HTTP/1.0 + Host: localhost + Server-Command: info + + The first example from above allows the web server to enforce command + based grained security as shown in the following Apache Httpd example: + + <Location /manager/info> + SetHandler cluster-manager + Order Deny,Allow + Allow from 127. + </Location> + + In case the query is not present the manager SHOULD treat the last part + of the mcmp_URL as a command in the same fashion as query. Both cmd_path + and query are case insensitive. + +3.5 Command + + The Command token indicates the command to be performed on the manager + identified by the MCMP URL. The command is case-insensitive. + + Command = "INFO" ; Section 3.5.1 + | "ENABLE" ; Section 3.5.2 + | "DISABLE" ; Section 3.5.3 + | "STOP" ; Section 3.5.4 + | "DELETE" ; Section 3.5.5 + | "CONFIG" ; Section 3.5.6 + + Each command usually carries additional command line parameters. The + command line parameters are described for each particular command. + + If the command is not recognised by the manager the manager SHOULD + respond with 200 (OK) response and the following entity-body using + text/plain MIME-type: + + "?" MCMP-Version CRLF + + Any other non 200 response is treated by the administrator as + communication problem between administrator and the manager. + + +Turk, et. al. Standards Track [Page 7] + +RFC 5501 MCMP March 2008 + + + +3.5.1 INFO + + The INFO command causes the manager to gather the information about + the specific resource on the server and present that information to + the administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + Server-Resource = "Server-Resource" ":" + #( resource-type ) + + resource-type = ( "*/*" + | ( type ) + | ( type "/" "*" ) + | ( type "/" subtype ) + ) *( ";" parameter ) + + parameter = token [ "=" ( token | quoted-string ) ] + + type = "server" + | "host" + | "balancer" + | "member" + | "application" + + The asterisk "*" character is used to group resource types, + with "*/*" indicating all resource types and "type/*" indicating all + subtypes of that type. The resource type MAY include resource type + parameters that are applicable to that type. + + The example + + Server-Resource: member/*; load-factor; busy + + will return the all members in the server with their load-factor and + busy parameter fields. If the parameters are not present then the + full information for the resource type SHOULD be returned. + The application subtype MAY contain the full application URL + in which case the leading slash MUST NOT be provided. + + Server-Resource: application/foo/bar; status; host/* + + will return the list of hosts on which the application with /foo/bar + URL is configured, and the status of the application within each host. + + +Turk, et. al. Standards Track [Page 8] + +RFC 5501 MCMP March 2008 + + + + If the manager does contain information about requested type then it + MUST respond with 200 (OK) response and the following entity-body + using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does contain information about requested subtype then it + MUST respond with 200 (OK) response and the following entity-body + using text/plain MIME-type: + + "?" "Unknown-Type" ":" type "/" subtype CRLF + + In case the manager has the requested resource type information then + those information is returned as entity-body in random order with each + line representing a single resource-type. + + Resource-Response = *( resource-type CRLF ) + + The example + + member/node1; load-factor=10; busy=100 + member/node2; load-factor=10; busy=105 + + Administrator MUST take the order of Resource-Response information + into account. If the Resource-Response contains the hierarchical + information the manager will provide the correct hierarchical order + of the resources. + + The example + + host/www.foo.org + application/foo; status=200 + application/bar; status=404 + host/www.foo.com + application/foo; status=503 + application/baz; status=200 + + The resource-type hierarchy is implied by the system and + it looks like shown: + + server ---> 1*host ----> 1*application + | ^ + | | + +--> balancer --> 1*member -+ + + The output of INFO command MUST include the resource type + name in case the command evaluation results in multiple resource types + returned. + The output of INFO command MUST include the parameter name in case + the command evaluation results in multiple parameters returned. + + +Turk, et. al. Standards Track [Page 9] + +RFC 5501 MCMP March 2008 + + + +3.5.2 ENABLE + + The ENABLE command causes the manager to enable the specific resource + on the server and presents the result of that operation to the + administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + If the manager does not contain the requested type object configured + then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does not contain the requested subtype object configured + then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type "/" subtype CRLF + + In case the manager has the requested resource type object configured + and enable succeeds then it MUST response with the following entity-body + using text/plain MIME-type: + + "OK" CRLF + + In case the enable for the specified resource type object does not + succeeds then the manager MUST response with the following entity-body + using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + The error-code is manager specified error code and error-description + is human readable description of the error code. + Error codes MAY be standard POSIX errno values with corresponding + description according to the POSIX specification. + + The example + + ?Error: 22; Invalid argument + + Where 22 corresponds to the EINVAL error code from the POSIX + specification. + For the resources objects for which the ENABLE command is invalid + manager MUST respond with: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + + In case the resource object is already enabled the manager MUST + reply with the success, and MAY skip any processing that might + be needed. + + + +Turk, et. al. Standards Track [Page 10] + +RFC 5501 MCMP March 2008 + + + +3.5.3 DISABLE + + The DISABLE command causes the manager to disable the specific resource + on the server and presents the result of that operation to the + administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + If the manager does not contain the requested type object configured + mode then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does not contain the requested subtype object configured + mode then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type "/" subtype CRLF + + In case the manager has the requested resource type object configured + and disable succeeds then it MUST response with the following entity-body + using text/plain MIME-type: + + "OK" CRLF + + In case the disable for the specified resource type object does not + succeeds then the manager MUST response with the following entity-body + using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + Depending on the resource object type the DISABLE command has different + consequences. For node object it MUST disable further acceptance of + the request that does not carry the session affinity mark information. + This will cause that those nodes MUST get excluded from the balancer + scheduler list for all new requests while preserving the ones that carry + the session affinity mark. + For the resources objects for which the DISABLE command is invalid + manager MUST respond with: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + In case the resource object is already disabled the manager MUST + reply with the success, and MAY skip any processing that might + be needed. + + + +Turk, et. al. Standards Track [Page 11] + +RFC 5501 MCMP March 2008 + + + +3.5.4 STOP + + The STOP command causes the manager to stop the specific resource + on the server and presents the result of that operation to the + administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + If the manager does not contain the requested type object configured + then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does not contain the requested subtype object configured + then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type "/" subtype CRLF + + In case the manager has the requested resource type object configured + and stop succeeds then it MUST response with the following entity-body + using text/plain MIME-type: + + "OK" CRLF + + In case the stop for the specified resource type object does not + succeeds then the manager MUST response with the following entity-body + using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + Depending on the resource object type the STOP command has different + consequences. For node object it MUST stop further acceptance of + the request after finishing the currently executing requests. + In case there is no more application left attached to this node all + the connections from the member to the node MUST be closed. + This will cause that those nodes MUST get excluded from the balancer + scheduler list for all requests until enabled again. + For the resources objects for which the STOP command is invalid + manager MUST respond with: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + In case the resource object is already stopped the manager MUST + reply with the success, and MAY skip any processing that might + be needed. + + + +Turk, et. al. Standards Track [Page 12] + +RFC 5501 MCMP March 2008 + + +3.5.5 DELETE + + The DELETE command causes the manager to remove the specific resource + on the server and presents the result of that operation to the + administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + If the manager does not contain the requested type object configured + and is in strict mode then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does not contain the requested subtype object configured + and is in strict mode then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type "/" subtype CRLF + + In case the manager has the requested resource type object configured + and delete succeeds then it MUST response with the following entity-body + using text/plain MIME-type: + + "OK" CRLF + + In case the delete for the specified resource type object does not + succeeds then the manager MUST response with the following entity-body + using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + Depending on the resource object type the DELETE command has different + consequences. In general, object resource MUST NOT be deleted in case + it is referenced by some other object resource. + Application resource object MUST NOT be deleted unless it is in the + STOP mode. Node object MUST NOT be deleted if it contains any application + that is not in the STOP mode. In both cases the manager MUST respond + with the following entity-body using text/plain MIME-type: + + ?Error: 16; Device or resource busy + + Where 16 corresponds to the EBUSY error code from the POSIX + specification. + + Deleting static objects or web server objects is not permitted and + manager MUST respond with the following entity-body using text/plain + MIME-type: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + Deleting objects from the web server does not mean the server will + reuse the memory occupied by the deleted resource, thus the deletion + must be taken with care and avoid large number of deletions. + + + +Turk, et. al. Standards Track [Page 13] + +RFC 5501 MCMP March 2008 + + + +3.5.6 CONFIG + + The CONFIG command causes the manager to create or update the specific + resource on the server and presents the result of that operation to the + administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + If the manager does not contain the requested type object configured + and is in strict mode then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does not contain the requested subtype object configured + then it MUST create the specified object. If the object creation succeeds + then it MUST response with the following entity-body using text/plain + MIME-type: + + "OK" CRLF + + In case the manager has the requested resource type object configured + then CONFIG command MUST update the resource object and MUST overwrite + provided parameters. If update of the resource object succeeds then it + MUST response with the following entity-body using text/plain MIME-type: + + "OK" CRLF + + In case CONFIG for the specified resource type object is not + permitted or the resource or resource parameter is read only, + then the manager MUST response with the following entity-body + using text/plain MIME-type: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + + + In case CONFIG for the specified resource type object does not + succeeds then the manager MUST response with the following entity-body + using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + By default, newly created objects MUST be in STOP mode. To be functional + the objects MUST be put in the desired operational mode (ENABLE or DISABLE). + Creating new objects MAY cause the additional processing on + the web server and dependency on the other objects. In case the dependency + is not satisfied the manager MUST roll back the creation of the object + and it MUST response with the following entity-body using text/plain + MIME-type: + + ?Error: 19; No such device + + Where 19 corresponds to the ENODEV error code from the POSIX + specification. + +3.5.7 EXEC + + The EXEC command is reserved for future use. + It will be used for Member to execute the ping/pong or to clear all + the active connections or to try to reconnect. + + +3.5.8 RESET + + The RESET command causes the manager to reset the specific resource + on the server and presents the result of that operation to the + administrator in a form of text/plain MIME-type reply. + The Server-Resource header field MUST be present in the request to + determine the type of server resource. + + If the manager does not contain the requested type object configured + then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type CRLF + + If the manager does not contain the requested subtype object configured + then it MUST respond with 200 (OK) response and the + following entity-body using text/plain MIME-type: + + "?" "Unknown-Type" ":" type "/" subtype CRLF + + In case the manager has the requested resource type object configured + and reset succeeds then it MUST response with the following entity-body + using text/plain MIME-type: + + "OK" CRLF + + In case the reset for the specified resource type object does not + succeeds then the manager MUST response with the following entity-body + using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + Depending on the resource object type the RESET command has different + consequences. + For the resources objects for which the RESET command is invalid + manager MUST respond with: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + In case the resource object is already stopped the manager MUST + reply with the success, and MAY skip any processing that might + be needed. + + +Turk, et. al. Standards Track [Page 14] + +RFC 5501 MCMP March 2008 + + + +4 Resource Types + + Resource types are fixed objects or object collections inside web server + accessible by manager. There are five basic resource types; server, host, + balancer, member and application (see section 3.5.1). + Each resource type MAY contain the collection of name based resources + either as resource instance or reference to the resource instance. + In case the object is a reference to the resource instance the + resource collection item MAY contain local resource parameters. The object + reference MUST inherit parameters from the object instance, but then if + the object have local parameters they MUST preserve local data integrity. + Updating instance parameters MAY propagate the values to all references + local data having the same parameter. + +4.1 Server + + Server resource type is the root object in the system and contains the + web server parameters. It MUST support the INFO command and MAY support + the CONFIG command. In case the CONFIG is not supported the manager MUST + respond with EPERM error code (see section 3.5.6). + +4.1.1 General Information + + Server MUST provide the following parameters: + + ServerName + Hostname and port that the server uses to identify itself. + + ServerRoot + Base directory for the server installation. + + ServerVersion + Version if the server. + + ServerBuilt + Date and time when the server was built. + + ServerArchitecture. + CPU architecture of the server (32 or 64 bit). + + ThreadsPerChild + Number of threads created by each child process. + If the server does not use threading model then it MUST + report this value as 1. + + MaxRequestsPerChild + Limit on the number of requests that an individual child server + will handle during its life. After MaxRequestsPerChild requests, + the child process will die. + + +Turk, et. al. Standards Track [Page 15] + +RFC 5501 MCMP March 2008 + + + + ListenBackLog + Maximum length of the queue of pending connections + + MaxClients + Limit on the number of simultaneous requests that will be served. + Any connection attempts over the MaxClients limit will normally + be queued, up to a number based on the ListenBacklog parameter. + + CurrentTime + Current time on the server. + + RestartTime + Time when the server was restarted. + + ServerUpTime + Number of seconds since server start. + + AccessCount + Number of requests since ServerUpTime. + + BytesServed + Number of bytes served since ServerUpTime. + + LimitRequestFields + Number is an integer from 0 (meaning unlimited) to 32767. + The default value is defined by the compile-time constant + DEFAULT_LIMIT_REQUEST_FIELDS (100 as distributed). + + LimitRequestFieldSize + Specifies the number of bytes that are allowed in an HTTP + request header. + + The server SHOULD provide the following parameters: + + ConfigurationFile + Name of the configuration file the server is using. + + + +Turk, et. al. Standards Track [Page 16] + +RFC 5501 MCMP March 2008 + + + + CurrentConfiguration + Dump the current server configuration using the following notation: + + current-configuration = *( "File" ":" configuration-file CRLF + *( [line-number] ":" directive CRLF ) + ) + + The CurrentConfiguration parameter MUST be the only parameter + when executing server INFO command. All other parameters MUST + be disregarded from the requested parameter list. + + The example output from the Apache Httpd server: + + File: /opt/apache/conf/httpd.conf + 99: <Directory /> + 100: Options FollowSymLinks + 101: AllowOverride None + : </Directory> + File: /opt/apache/conf/extra/httpd.info + 14: <Location /server-status> + 15: SetHandler server-status + : </Location> + File: /opt/apache/conf/httpd.conf + 5: Listen 80 + + Note that CurrentConfiguration does not represent the real + configuration file structure because it MAY remove all comments + and empty lines, neither the ordering reflects the original + ordering. + + +4.1.2 Client Connection Information + + Server SHOULD provide the connection information about each client + connection up to the MaxClients server parameter. + + Connection = "Connection" "=" #( connection-id ) + + connection-id = ( "*" | connection-id ) + + will result in response containing the connection-status for one + or single connection. + + connection-status = *( "." ; Server is dead + | "-" ; Ready + | "S" ; Starting + | "R" ; Reading + | "W" ; Writing + | "K" ; Keep-Alive + | "L" ; Writing to log + | "D" ; Resolving DNS + | "C" ; Closing + | "G" ; In graceful restart + | "I" ; Idle + + + +Turk, et. al. Standards Track [Page 17] + +RFC 5501 MCMP March 2008 + + + +4.2 Host + + + Host resource type represents the servers Host or Virtual Host. + Host MAY contain any number of application resource objects. + By default the Host object is created from server native configuration. + + The Host that was created from server native configuration + MUST not be deleted. If the manager tries to DELETE such Host + the manager must respond with the following entity-body using + text/plain MIME-type: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + + +4.2.1 General Information + + Host MUST provide the following parameters: + + ServerName + Specifies what hostname must appear in the request's Host: header + to match this virtual host. + + ServerAlias + Alternate names for a host used when matching requests + to name-virtual hosts. + [ "ServerAlias" "=" ] *( hostname SP ) + + IsVirtual + Is this a virtual host. + [ "IsVirtual" "=" ] ( "On" | "Off" ) + + DocumentRoot + Directory that forms the main document tree visible from the web. + + ServerPath + Legacy URL pathname for a name-based virtual host that is accessed + by an incompatible browser. + + KeepAlive + This server supports the persistent connections. + [ "KeepAlive" "=" ] ( "On" | "Off") + + KeepAliveTimeout + Amount of time the server will wait for subsequent requests on a + persistent connection. + + MaxKeepAliveRequests + Number of requests allowed on a persistent connection. + + TimeOut + Amount of time the server will wait for certain events before + failing a request + + +Turk, et. al. Standards Track [Page 18] + +RFC 5501 MCMP March 2008 + + + + LimitRequestBody + Specifies the number of bytes from 0 (meaning unlimited) to + 2147483647 (2GB) that are allowed in a request body. + + Address + The bound IPV4 or IPV6 address for this host. + + Port + The bound port for this host. + + The host MAY provide the following parameters: + + VirtualName + The name given in <VirtualHost > configuration. + +4.2.2 Application + + Application resource type is configurable object inside host, + and it maps the incoming URLs to global balancer object. + Host MUST support unlimited number of application resource objects + and MUST support all commands. + If the application was already configured and created inside balancer + resource object then the manager MUST create application object + instance inside host object, otherwise it MUST reference already + created application instance inside balancer object. + This allows to have multiple instances of the application that have + the same name. Likewise it allows to share the common applications + between host resource objects. + + Each application configured inside host MUST have it's own status + parameter that defines how the manager will map the application. + + application-status = "Status" "=" + ( 200 ; Application mapping allowed + | HTTP-Status ; Return HTTP-Status to the client + ) + + HTTP-Status as defined in RFC2068 [10]. + + When configuring the application object application-status MUST be + set to 200 unless explicitly specified inside CONFIG command. + On evaluation if the application is reference the manager MUST + first use the application-status from the instance of the application + object and only if the application-status is 200 the manager MAY + apply his local application-status. + + DELETE command MUST remove the application object from the host. + In case the application object was a reference then the manager MUST + preserve the original application object and delete only the local + parameter data. Deleting the application from the host is the same + + + +Turk, et. al. Standards Track [Page 19] + +RFC 5501 MCMP March 2008 + + + + as setting the application-status to 404, so the administrator + MAY use this instead object deletion. Processing application with + application-status equal to 404 MUST produce the same result as if + the application was not defined at all. + + STOP command MUST set the application-status to 404. + DISABLE command MUST set the application-status to 503. + ENABLE command MUST set the application-status to 200. + Those commands are convenience methods for using the CONFIG + command with corresponding application-status value. + + The example + + DISABLE Server-Resource: host/www.foo.org; application/* + + MUST set the application-status to 503 for all the applications + inside www.foo.org host resource object. Next client request to the + www.foo.org host MUST then always return 503 HTTP-Status message + to the client for all configured applications. + + The following example does exactly the same thing as above, but + using the CONFIG command and status parameter to set the + application-status. + + CONFIG Server-Resource: host/www.foo.org; application/*; status=503 + + + + + + +Turk, et. al. Standards Track [Page 20] + +RFC 5501 MCMP March 2008 + + + +4.3 Balancer + + Balancer resource type is static object inside server. Default + balancer object instance MUST be created at server startup and + present for the server lifetime. The name of this resource MUST + be set to "_default_", and server MUST use this balancer if the + balancer resource name or type was not provided with the command. + + Balancer object instance contains the list of member instance + objects and it MUST support all commands. + + Additional balancer object instances MAY be created inside server + and the server SHOULD NOT limit their number. However different + balancer object instances cannot share the same member object + instances and server MUST assure that two members with the same + member-host and member-port do not appear in two different balancer + instances. In case such attempt is made the manager must respond + with the following entity-body using text/plain MIME-type: + + ?Error: 18; Cross-device link + + Where 18 corresponds to the EXDEV error code from the POSIX + specification. + + +4.3.1 StickySession + + StickySession is balancer parameter with default value set to "On". + The balancer MAY extract the data from the sticky-session-cookie + or from the sticky-session-path to maintain the session affinity + for the particular member matching the session-route + (see 4.3.1 and 4.3.2). + + +4.3.2 StickySessionCookie + + StickySessionCookie is balancer parameter with default value + equal to "JSESSIONID" and is used to find the session affinity + mark that matches the member name. The member name comparison + MUST be case insensitive. However the comparison for the + StickySessionCookie MUST be case sensitive. + + If the Cookie or Cookie2 header value provided by the client have + multiple occurrences of the StickySessionCookie only the last one + MUST be used for further processing. + + sticky-session-cookie = "StickySessionCookie" "=" string + + + + +Turk, et. al. Standards Track [Page 21] + +RFC 5501 MCMP March 2008 + + + + The extracted route information from the Cookie is + + sticky-route = StickySessionCookie" "=" + #( session-route ) + + session-route = ( session-id [ "." [ token ] ] ) + + session-domain = ( session-route + | session-route [ "." token ] ] + ) + + If the session-id contains the "." character everything after + that character MUST be treated as session-route. If the session + route contains "." character everything after that character + MUST be treated as session-domain. + + +4.3.3 StickySessionPath + + StickySessionPath is balancer parameter with default value + equal to ";jsessionid" and is used to find the session affinity + mark that matches the member name. The member name comparison + MUST be case insensitive. However the comparison for the + StickySessionPath MUST be case sensitive. + + If the URL header value provided by the client have + multiple occurrences of the StickySessionPath only the last one + MUST be used for further processing. + + sticky-session-path = "StickySessionPath" "=" string + + The extracted route information from the Cookie is + + sticky-route = "StickySessionPath" "=" + #( session-route ) + + session-route = ( session-id [ "." [ token ] ] ) + + session-domain = ( session-route + | session-route [ "." token ] ] + ) + + If the session-id contains the "." character everything after + that character MUST be treated as session-route. If the session + route contains "." character everything after that character + MUST be treated as session-domain. + + + + +Turk, et. al. Standards Track [Page 22] + +RFC 5501 MCMP March 2008 + + + +4.3.4 StickySessionRemove + + StickySessionRemove is balancer parameter with default value + equal to "On" and is used to remove the sticky-session-cookie or + the sticky-session-path for failed mappings and routes. + (see section 4.3.5). + + [ "StickySessionRemove" "=" ] ( "On" | "Off" ) + + When set to "On" the server MUST remove the sticky-session-cookie + from the Cookie header or sticky-session-path from the URL. + + +4.3.5 StickySessionForce + + Specifies whether requests with session-route for members that are + in error state should be rejected. If StickySessionForce is set to + "On" and the member that matches that session-route is in error state, + client will receive 500 (Server Error). + If set to "Off" (default value) failover on another member will be + issued with possibility of loosing client session. + + [ "StickySessionForce" "=" ] ( "On" | "Off" ) + + If StickySessionRemove was set to "On" and member that matches the + session-route was in error state, the server MUST remove the + sticky-session-cookie from the Cookie header or sticky-session-path + from the URL. However this directive MUST be evaluated only if + the StickySession was set to "On" + + For domain session routes all members of the domain MUST be + in error state to evaluate this rule. + + +4.3.6 TimeOut + + Connection wait timeout in seconds. If not set the balancer will + wait until the free connection is available. This directive is + used for limiting the number of connections to the node together + with MaxConnections member parameter. + Default value is server TimeOut. + + +Turk, et. al. Standards Track [Page 23] + +RFC 5501 MCMP March 2008 + + + +4.4 Member + + Member is resource object contained inside balancer object. Member + object provides the connection capability from the server to the node + and proxies the requests from the client to the node. + + +4.4.1 Type + + Type parameter defines the protocol the member is using when + communication to the node. + + type = "Type" "=" + #( protocol-type ) + + protocol-type = "ajp" + | "http" + | "https" + + Once created the member MUST NOT change its protocol-type. Any such + attempt MUST respond with the following entity-body using + text/plain MIME-type: + + ?Error: 1; Operation not permitted + + Where 1 corresponds to the EPERM error code from the POSIX + specification. + + +4.4.2 Address + + Host name or IP address of the node to which the member connects. + The Host name can have a port number embedded separated by the + colon (":") character. Default value for the Address is "localhost" + + Once created the member MUST NOT change its address unless the + member is in the STOP mode. Any such attempt must respond with + error message (see section 4.4.1). + + +4.4.3 Port + + Port number of the node to which the member connects. + The default value depends on the protocol-type and is + + ajp = "8009" + http = "8080" + https = "8443" + + Once created the member MUST NOT change its address unless the + member is in the STOP mode. Any such attempt must respond with + error message (see section 4.4.1). + + + +Turk, et. al. Standards Track [Page 24] + +RFC 5501 MCMP March 2008 + + + +4.4.4 Route + + Route of the member is a value that SHOULD match to the session-route. + Balancer to whom the member belongs will select this member if the + session-route matches the Route. Route value MUST be case insensitive. + + The length of the Route MUST be within 0 and 63 characters. In case + the length of Route is outside the limited range the manager MUST + respond with the following entity-body using text/plain MIME-type: + + ?Error: 22; Invalid argument + + Where 22 corresponds to the EINVAL error code from the POSIX + specification. + + +4.4.5 Domain + + Domain of the member is a value that SHOULD match to the session-domain. + Balancer to whom the member belongs will select this member if the + session-domain matches the Domain. Domain value MUST be case insensitive. + Balancer MUST match the Domain only if the matched session-route member + is not inside operational state. + + The length of the Route MUST be within 0 and 63 characters. In case + the length of Domain is outside the limited range the manager MUST + respond with EINVAL error code (see section 4.4.4). + + +4.4.6 Ping + + Ping property MAY cause member to send a CPING request on ajp connection + before forwarding a request. The parameter is the delay in seconds + to wait for the CPONG reply. Currently this has an effect only if the + member Type is ajp. If the value of the property is zero (default) + then the member MUST NOT send the CPING requests. + + If the attempt is made to set the non zero value to the member which + Type is different then ajp the manager MUST respond with EINVAL + error code (see section 4.4.4). + + + +Turk, et. al. Standards Track [Page 25] + +RFC 5501 MCMP March 2008 + + + +4.4.7 MaxConnections + + Maximum number of connections that are allowed at any moment to + the node on each child process inside server. For threaded servers + this value MUST be within the range of 1 and the number of + ThreadsPerChild (see section 4.1.1). For non threaded servers this + value MUST always be one. + + In case MaxConnections is outside the limited range the manager MUST + respond with EINVAL error code (see section 4.4.4). + + +4.4.8 MinConnections + + Minimum number of connections that the member will keep opened. + This value MUST be within the range of 1 and MaxConnections. + + In case MinConnections is outside the limited range the manager MUST + respond with EINVAL error code (see section 4.4.4). + + +4.4.9 TTL + + Time To Live for the inactive connections above the MinConnections + in seconds. Apache will close all connections that has not been + used inside that time period. + + +4.4.10 LF + + Load Factor is the property of the member used by the balancer + to schedule the load. The value of LF property MUST be + within the 1 and 100 and defines the normalized weighted load + applied to the member. Default value is 1. + + +4.4.11 Distance + + An integer number to express preferences between the balanced + members of an balancer. A balancer MUST never choose some + member in case there is another usable member with lower distance. + + Only in case all members below a given distance are in error, + disabled or stopped, member of a larger distance MAY be eligible + for balancing. This property is used for creating hot standby + members. Multiple hot standby chains might be created each + having the same Distance property larger by one. + Default value for Distance property is zero. + + + +Turk, et. al. Standards Track [Page 26] + +RFC 5501 MCMP March 2008 + + + +4.4.12 Activation + + Defines the activation state of the member. + + activation = ( "D" ; Disabled + | "S" ; Stopped + | "A" ; Active + ) + + Member with activation disabled ("D") only gets requests, which belong + to sessions for that member. + Member with activation stopped ("S") does not get requests requests. + Active ("A") means that the member works normally. + + +4.4.13 Statistical data + + Member MUST provide the following parameters: + + State + Current state of the member resource object can be one + of the following values: + + member-state = ( operational-state + | activation-state + | error-state + ) + + operational-state = ( "I" ; Idle + | "A" ; Active + | "B" ; Busy + ) + + activation-state = ( "D" ; Disabled + | "S" ; Stopped + ) + + error-state = "E" ; Error + + Error + Error code and textual description of the error code + + error = error-code [ ":" error-description ] + + Busy + Number of connections that are currently servicing the + client requests. + + Connected + Number of connections that are currently opened between + member and node. + + Elected + Number of times the member was elected from the load balancer. + + StickySessions + Number of times the member was elected according to the + sticky session rule. + + ClientErrors + Number of client errors caused by communication error + between member and client. + + + +Turk, et. al. Standards Track [Page 27] + +RFC 5501 MCMP March 2008 + + + + NodeErrors + Number of errors caused by communication error between + member and node. + + Readed + Number of bytes read from node. + + Transferred + Number of bytes transferred to node. + + Trace + Number of times the member was doing health check call + to the node. + + TraceErrors + Number of times the member was doing health check call + to the node and the trace failed. + + +4.4.14 ENABLE + + ENABLE command when applied to the member if the member was in the + error-state state MUST make internal redirect that MUST result in + balancer electing this member. ENABLE MUST change the member status + only if the Trace call succeeds. In case the call does not succeeds + manager MUST NOT change the state of the member and MUST respond to + the administrator with the error-code provided by the member with the + following entity-body using text/plain MIME-type: + + "?" "Error" ":" error-code; error-description CRLF + + After successful trace the the member MUST change its state to + the one defined by activation. ENABLE command MAY have the + Activation parameter embedded in the command in which case the + member will update its activation status. + + +4.4.15 DISABLE + + DISABLE command is convenient method of setting the Activation + to "D" (see section 4.4.12). + + +4.4.16 STOP + + STOP command is convenient method of setting the Activation to + "S" (see section 4.4.12). However the manager MUST close all + connections to the node once the currently executing requests + are finished. + + +4.4.17 INFO + + If no parameters for the INFO command are present member MUST + respond as if the requested parameter was State. + + + +Turk, et. al. Standards Track [Page 28] + +RFC 5501 MCMP March 2008 + + + +4.4.18 DELETE + + DELETE command MUST be executed only on stopped members. + In case the member is not in stop mode manager MUST return + EBUSY error code (see section 3.3.5). + If some of the members connections are still servicing the + request, those connections MUST be closed. + Administrator SHOULD usually wait until all pending + client requests are done, but it MAY use this feature to + forcibly close the stalled connections + + +4.5 Application + + Application resource object is instantiated inside balancer + but it MUST have reference link inside each balancer member. + Each member MUST track the status and statistical data for + each application defined inside balancer. Aplication instance + parameters MUST have higher priority then local member application + parameters. By default adding and deleting application objects + MUST be reflected to all balancer members. + + +4.5.1 State + + Application State parameter tells the balancer the state of + the application: + + application-state = ( "D" ; Disabled + | "S" ; Stopped + | "A" ; Active + ) + + Application-state MUST have its local copy inside each balancer member. + Balancer MUST treat the final application-state as Active only + if both balancer and member application-state parameters are Active. + In any other case the balancer application-state MUST take + precedence. Disabled and Stopped state MUST be handled like + for the member itself (see section 4.4.12). + + +4.5.2 Statistical data + + For each member application MUST provide the following parameters: + + Busy + Number of connections that are currently servicing the + client requests for this application. + + Readed + Number of bytes read from node for this application + + Transferred + Number of bytes transferred to node for this application. + + + +Turk, et. al. Standards Track [Page 29] + +RFC 5501 MCMP March 2008 + + + + Transactions + Number of requests for this application. + + ClientErrors + Number of client errors caused by communication error + between member and client for this application. + + To get the total statistical data across all members for this + application administrator MAY execute the following example: + + INFO application/foo/bar + + Manager MUST calculate the total sum of all statistical data + from each members of the balancer and present them to the + administrator. The output of this operation MAY look like + shown below: + + Busy=101; Readed=230364; Transferred=271132; Transactions=50; \ + ClientErrors=1 + + +4.5.3 DELETE + + DELETE command MUST be executed only on stopped applications. + In case the application is not in stop mode manager MUST return + EBUSY error code (see section 3.3.5). + + +Turk, et. al. Standards Track [Page 30] + +RFC 5501 MCMP March 2008 + + + +4.6 ApplicationPool + + ApplicationPool resource object inside server that holds references + to the Application objects. There is always on (_default_) ApplicationPool + created in the server holding reference for all Applications that have + not ApplicationPool explicitly defined. + + +4.6.1 Status + + ApplicationPool Status parameter tells the server the state of + the application pool: + + application-pool-status = ( "D" ; Disabled + | "S" ; Stopped + | "A" ; Active + ) + + If the ApplicationPool status is Disabled all applications will + be rejected causing server to stop any url processing for the + Applications that are contained in this Application pool. + +4.6.2 Concurrency + + ApplicationPool Concurrency tells the server the maximum number of + of requests that are currently in processing. If the total number of + active connections exceddes this value new requests MUST be delayed + for the maximum of TimeOut parameter. + + +4.6.3 TimeOut + + TimeOut is maximum time the connection that was blocked by excedding + the Concurrency value be held in the internal queue. + +4.6.4 Statistical data + + For each member application MUST provide the following parameters: + + Busy + Number of connections that are currently servicing the + client requests for this application pool. + + Applications + Number of applications that are currently members of this + application pool. + + + + +Turk, et. al. Standards Track [Page 31] + +RFC 5501 MCMP March 2008 + + + + + +5. Manager + + Manager is the application inside server that manages the resource + inside web server. In case manager does not understand the + given command it MUST return the error message back to the + administrator (see section 3.5). + + If the manager does not understand any of the provided command + parameters it MUST silently disregard those parameter and use + only the one that he understand how to process. + + If the strict flag is set and manager does not understand one of + the requested parameters then it MUST respond with 200 (OK) + response and the following entity-body using text/plain MIME-type: + + "?" MCMP-Version CRLF + 1*("?" "Unknown-Parameter" ":" param CRLF) + + for each parameter that he don't understand and MUST not execute + any other action. + + + +Turk, et. al. Standards Track [Page 32] + +RFC 5501 MCMP March 2008 + + + +5.1 Strict + + Strict parameter enforces the manager to treat the object types or + parameters as errors if they are not understandable by the current + manager version. + + manager-strict = ( "On" | "Off" ) + + Default strict value is "Off" meaning that manager will disregard + all unknown parameters. + + +5.2 ProtocolVersion + + Current version of the MCMP protocol and manager + + MCMP-Version ";" manager-version + + Manager-version is read only property defined at compile time. + + +5.3 ServerId + + Unique id of the server where the Manager is running + ServerId is read only property defined at server statup. + + + +Turk, et. al. Standards Track [Page 33] + +RFC 5501 MCMP March 2008 Property changes on: sandbox/aloha/docs/rfc5501.txt ___________________________________________________________________ Name: svn:eol-style + native