Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Start cleaning up MCMP documentation. #207

Merged
merged 2 commits into from
Sep 10, 2024
Merged

Start cleaning up MCMP documentation. #207

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fef34ee
Start cleaning up MCMP documentation.
rhusar Sep 10, 2024
a623dac
Drop obsolete document.
rhusar Sep 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/developer/design.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ See also the following wiki pages:

Implementation details:

* xref:management_protocol.adoc[ModCluster_Management_Protocol]
* xref:management_protocol.adoc[ModCluster Management Protocol (MCMP)]

* xref:internals.adoc[ModCluster_Internals]

Expand Down
21 changes: 6 additions & 15 deletions docs/src/main/asciidoc/developer/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,25 +28,16 @@ ifdef::basebackend-html[toc::[]]

= Developer Resources

WARNING: These resources were converted from retired
https://developer.jboss.org/docs/DOC-11431[developer.jboss.org] and are likely to be
out-of-date on various topics. We're working on making them up-to-date.
WARNING: These resources were converted from retired https://developer.jboss.org/docs/DOC-11431[developer.jboss.org]
and are out-of-date on various topics.
We're working on making them up to date.

include::design.adoc[]


= Miscellaneous

* xref:choosing_doc_platform.adoc[Choosing Documentation Platform for
mod_cluster]

* xref:choosing_doc_platform.adoc[Choosing Documentation Platform for mod_cluster]
* xref:q_a_webinar.adoc[Questions and Answers on mod_cluster webinar]

* xref:version_1.3.1.adoc[mod_cluster version 1.3.1.Final released!]

* xref:hw_load_balancer.adoc[Using a hardware load balancer in combination with
mod_cluster server-side load metrics]

* xref:fedora24_25_update_testing.adoc[mod_cluster 1.2.6.Final -> 1.3.3.Final
in Fedora 24 and Fedora 25 updates-testing]

* xref:hw_load_balancer.adoc[Using a hardware load balancer in combination with mod_cluster server-side load metrics]
* xref:fedora24_25_update_testing.adoc[mod_cluster 1.2.6.Final -> 1.3.3.Final in Fedora 24 and Fedora 25 updates-testing]
88 changes: 52 additions & 36 deletions docs/src/main/asciidoc/developer/management_protocol.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
= ModCluster Management Protocol
= ModCluster Management Protocol (MCMP)

The document describes the protocol elements of the
xref:design.adoc[mod_cluster] protocol between a container (AS) and a load
balancer (Apache httpd).
The document describes the protocol elements of the xref:design.adoc[mod_cluster] protocol between a container (AS) and a load balancer (Apache httpd / Undertow).

== Messages

|===
| Message type | Description

| CONFIG | Send configuration information for a node or set of nodes.
| ENABLE-APP | Send requests and assign new sessions to the specified app. Use of to identify the app means enable all apps on the given node.
| DISABLE-APP | apache should not create new session for this webapp, but still continue serving existing session on this node. Use of to identify the app means disable all apps on the given node.
Expand All @@ -24,17 +23,17 @@ balancer (Apache httpd).
| PING-RSP | Response to PING
|===

=== Message payload:
=== Message payload

The information is in ASCII and URL encoded if needed.

All numbers are integer and a string representation is used.

The command is string it is the first part of a message it is followed by
a / HTTP/1.0<CR><LF>
The command is string it is the first part of a message it is followed by a / HTTP/1.0<CR><LF>

Example:

[source]
----
DISABLE-APP / HTTP/1.0<CR><LF>
----
Expand All @@ -52,6 +51,7 @@ their pairs is <&>

Example:

[source]
----
DISABLE / HTTP/1.0<CR><LF>

Expand All @@ -62,13 +62,13 @@ Content-length: 44<CR><LF>
Jvmroute=node1&Context=myapp&Context=ourapp<CR><LF>
----

To make the document more readable the " / HTTP/1.0" is not added a the end of
the commands.
To make the document more readable the " / HTTP/1.0" is not added a the end of the commands.

== CONFIG

|===
| Key | Description | Default | Max size

| Alias | List of virtual hosts like host1,host2 (See http://tomcat.apache.org/tomcat-6.0-doc/config/host.html#Host%20Name%20Aliases[Alias]) | |
| Balancer | is the name of the balancer in httpd (for example mycluster in ProxyPass /myapp balancer://mycluster/) | mycluster | 40
| Context | List the context the virtual host list supports like (Ex. "/myapp,/ourapp") | |
Expand All @@ -77,37 +77,56 @@ the commands.
| JvmRoute | Is what is after the . in the JSESSIONID cookie or the parameter jsessionid | | 80
| Port | is the port on which the node except to receive requests | 8009 | 7
| Type | http/https/ajp The protocol to use between httpd and AS to process requests | ajp | 6

// The following is a dump of parameters sent by the current implementation, which were missing from the protocol definition
// TODO: these need to properly described
// https://github.com/modcluster/mod_cluster/blob/main/core/src/main/java/org/jboss/modcluster/mcmp/impl/DefaultMCMPRequestFactory.java#L39

| Reversed | TODO | TODO | TODO
| flushpackets | TODO | TODO | TODO
| flushwait | TODO | TODO | TODO
| ping | TODO | TODO | TODO
| smax | TODO | TODO | TODO
| ttl | TODO | TODO | TODO
| Timeout | TODO | TODO | TODO
| StickySession | TODO | TODO | TODO
| StickySessionCookie | TODO | TODO | TODO
| StickySessionPath | TODO | TODO | TODO
| StickySessionRemove | TODO | TODO | TODO
| StickySessionForce | TODO | TODO | TODO
| WaitWorker | TODO | TODO | TODO
| Maxattempts | TODO | TODO | TODO

|===

For node and balancer configuration keys refer to
xref:node_balancers.adoc[ModCluster Node and Balancer].
For node and balancer configuration keys refer to xref:node_balancers.adoc[ModCluster Node and Balancer].

== ENABLE-APP

|===
| Key | Description

| JvmRoute | See CONFIG
| Alias | See CONFIG
| Context | That is the context of the application
|===

== DISABLE-APP

Like ENABLE-APP.
Same as ENABLE-APP.


== STOP-APP

Like ENABLE-APP.
Same as ENABLE-APP.

== REMOVE-APP

Like ENABLE-APP.
Same as ENABLE-APP.

== STOP-APP-RSP

That is a response to STOP-APP, like a http response it starts with
HTTP/1.1 200 OK<CR><LF> and it has the format:
That is a response to STOP-APP, like a http response it starts with HTTP/1.1 200 OK<CR><LF> and it has the format:

|===
| Key | Description
Expand All @@ -124,6 +143,7 @@ Note that a Wildcard STOP-APP won't cause a STOP-APP-RSP but just a 200 or 500.

|===
| Key | Description | Default | Max size

| JvmRoute | See CONFIG | |
| Load | number between 1 and 100 and defines the normalized weighted load applied to the worker. Only possible values are real load factor."0": node is on standby. +
"-1": node is broken (The cluster can't connect to it). +
Expand All @@ -137,6 +157,7 @@ and it has the format:

|===
| Key | Description

| Type | STATUS-RSP
| JvmRoute | See CONFIG
| State | That is the state httpd see for the node at the time of the processing (value from shared memory).
Expand All @@ -149,31 +170,31 @@ Empty request.

== INFO-RSP

"readable" description of the mod_cluster configuration corresponding to the
messages the cluster has sent to mod_cluster.
A "readable" description of the mod_cluster configuration corresponding to the messages the cluster has sent to mod_cluster.

== DUMP

Empty request.

== DUMP-RSP

"readable" description of the mod_cluster configuration corresponding to the
messages the cluster has sent to mod_cluster.
A "readable" description of the mod_cluster configuration corresponding to the messages the cluster has sent to mod_cluster.

== PING

There are 3 different pings: (for version 0.1.0 on).
There are three different pings: (for version 0.1.0 on).

|===
| Combination | Description

| Empty=? | check that the proxy is alive.
| JvmRoute=? | check if a node is alive.
| Type=?&Host=?&Port=? | check that httpd can connect to a possible node defined by Type://Host:Port/
|===

|===
| Key | Description

| JvmRoute | See CONFIG
| Type | See CONFIG
| Host | See CONFIG
Expand All @@ -184,6 +205,7 @@ There are 3 different pings: (for version 0.1.0 on).

|===
| Key | Description

| Type | PING-RSP
| State | See STATUS_RSP
| id | See STATUS_RSP
Expand All @@ -196,6 +218,7 @@ mod_cluster only the JVMRoute is going to be relevant in the payload message.

For example:

[source]
----
DISABLE HTTP/1.0

Expand All @@ -210,6 +233,7 @@ Jvmroute=node1&Context=myapp&Context=ourapp<CR><LF>

will be handled like:

[source]
----
DISABLE HTTP/1.0<CR><LF>

Expand All @@ -225,11 +249,8 @@ Other values between the command and HTTP/1.0 (or 1.1) are ignored in the actual
A shutdown of a node will cause the following events:

* DISABLE-APP / for each application.

* STOP-APP / for each application.

* DISABLE-APP

* STOP-APP

(xref:design.adoc[ModCluster Design] suggests that
Expand Down Expand Up @@ -257,6 +278,7 @@ error.

The error response status line will be something like:

[source]
----
HTTP/1.1 500 ERROR

Expand Down Expand Up @@ -292,6 +314,7 @@ to mod_cluster.

Example:

[source]
----
HTTP/1.1 500 ERROR
Date: Fri, 16 May 2008 09:55:21 GMT
Expand All @@ -312,28 +335,21 @@ The mod_cluster-manager handler allows to do operation like
ENABLE_APP/DISABLE_APP through a web interface. The format of the request
string is the following:

[source]
----
Nonce:<nonce>&Cmd:<cmd>&Range:<range>&<MCMP String>
----

where:

* <nonce> Is a string like e17066b4-0cb1-4e58-93e3-cdc9efb6be9 corresponding to
a unique id of httpd.

* <nonce> Is a string like e17066b4-0cb1-4e58-93e3-cdc9efb6be9 corresponding to a unique id of httpd.
* <cmd> Is the command: one of ENABLE_APP, DISABLE_APP etc.

* <range> Is a "NODE" or "CONTEXT". "NODE" means that the _APP command is a
wildcard command.

* <range> Is a "NODE" or "CONTEXT". "NODE" means that the _APP command is a wildcard command.
* <MCMP String> is a string containing a command described above.

Example
Example:

[source]
----
http://localhost:8000/mod_cluster-manager?nonce=e17066b4-0cb1-4e58-93e3-cdc9efb6be9c&Cmd=DISABLE-APP&Range=CONTEXT&JVMRoute=jvm1&Alias=
----




Loading