The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Net-MCMP-0.08
River stage one • 1 direct dependent • 1 total dependent
/ Net::MCMP

NAME

Net::MCMP - Mod Cluster Management Protocol client

SYNOPSIS


            

              
              
use Net::MCMP;
my $mcmp = Net::MCMP->new( { uri => 'http://127.0.0.1:6666' } );
$mcmp->config(
    {
        JvmRoute => 'MyJVMRoute',
        Host     => 'localhost',
        Port     => '3000',
        Type     => 'http',
        Context  => '/myContext',
        Alias    => 'Vhost',
    }
);
$mcmp->enable_app(
    {
        JvmRoute => 'MyJVMRoute',
        Alias    => 'Vhost',
        Context  => '/myContext'
    }
);
$mcmp->remove_app(
    {
        JvmRoute => 'MyJVMRoute',
        Alias    => 'SomeHost',
        Context  => '/cluster'
    }
);
$mcmp->remove_route(
    {
        JvmRoute => 'MyJVMRoute',
    }
);
$mcmp->status(
    {
        JvmRoute => 'MyJVMRoute',
        Load     => 55,
    }
);
$mcmp->disable_app(
    {
        JvmRoute => 'MyJVMRoute',
        Alias    => 'SomeHost',
        Context  => '/cluster'
    }
);
$mcmp->stop_app(
    {
        JvmRoute => 'MyJVMRoute',
        Alias    => 'SomeHost',
        Context  => '/cluster'
    }
);

DESCRIPTION

Net::MCMP is an implementation of the Mod Cluster Management Protocol (MCMP). Net::MCMP uses LWP::UserAgent and HTTP::Request for its communication with mod_cluster.

MCMP stands for Mod Cluster Management Protocol and is a method of adding proxy settings dynamically, as appose to creating static apache rules.

Official documentation of MCMP can be found here: https://community.jboss.org/wiki/Mod-ClusterManagementProtocol

USAGE

Net::MCMP->new(\%args)

Creates a new MCMP object, and returns a Net::MCMP object representing that connection.


            

              
              
my $mcmp = Net::MCMP({ uri => 'http://127.0.0.1:6666', debug => 0});

%args can contain:

  • uri (required)

    The URI of a mod_cluster handler.

  • debug (optional)

    If set to a true value, debugging messages will be printed out for every request and respons to mod_cluster.

$mcmp->config(\%conig)

Sends configuration for a node or set of nodes

If a low-level protocol error or unexpected local error occurs, we die with an error message.


            

              
              
$mcmp->config({
        JvmRoute            => "MyAppNode1",
        Balancer            => 'MyApp',
        Domain              => 'MyApp',
        StickySessionCookie => 'myapp_session',
        StickySessionPath   => 'myapp',
        Host                => '192.168.0.101',
        Port                => '3000',
        Type                => 'http',
        Context             => '/myapp',
        Alias               => "MyApp",      
});

%config can contain:

  • JvmRoute (required)

    Name of the node.

  • Alias (required)

    List the virtual hosts. ex. localhost,localhost2.

  • Host (optional)

    IP address (or hostname) where the node is going to receive requests from httpd (Defaults to localhost)

  • Port (optional)

    Port on which the node except to receive requests (Defaults to 8009)

  • Type (optional)

    http/https/ajp The protocol to use between httpd and application to process requests (Defaults to ajp)

  • Domain (optional)

    domain corresponding to the node (ie LB group), (Defaults to mycluster)

  • Balancer (optional)

    is the name of the balancer in httpd (Defaults to mycluster)

  • StickySession (optional)

    stick a request to a node "yes"/"no" (Defaults to "yes")

  • StickySessionCookie (optional)

    Name of the cookie containing the sessionid (Defaults to "JSESSIONID")

  • StickySessionPath (optional)

    Name of the parameter containing the sessionid (Defaults to "jsessionid")

  • StickySessionRemove (optional)

    remove the sessionid (cookie or parameter) when the request can't be routed to the right node "yes"/"no" (Defaults to "no")

  • StickySessionForce (optional)

    Return an error if the request can't be routed according to JVMRoute (Defaults to "yes")

  • WaitWorker (optional)

    value in seconds: time to wait for an available worker. (Defaults to 0, no wait)

  • MaxAttempts (optional)

    number of attemps to send the request to the backend server (Defaults to 1)

  • FlushPackets (optional)

    Tell how to flush the packets. On: Send immediately, Auto wait for flushwait time before sending, Off don't flush. (Defaults to "off")

  • FlushWait (optional)

    Time to wait before flushing. Value in seconds (Defaults to 10)

  • Ping (optional)

    Time to wait for a pong answer to a ping. 0 means we don't try to ping before sending. Value in secondes (Defaults to 10)

  • Smax (optional)

    soft max inactive connection over that limit after ttl are closed. Default depends on the mpm configuration

  • Ttl (optional)

    max time in seconds to life for connection above smax. (Defaults to 60)

  • Timeout (optional)

    Max time httpd will wait for the backend connection. (Defaults to 0, no timeout)

  • Context (optional)

    List of the contexts that node supports. ex. /myapp,/ourapp.

$mcmp->ping(\%ping)

Request a ping to httpd or node


            

              
              
my $ping_resp = $mcmp->ping(
        {
                JvmRoute => 'MyAppNode1',
        }
);
# SAMPLE $ping_response
#$VAR1 = {
#    'id' => '-540134453',
#    'JvmRoute' => 'MyJVMRoute',
#    'State' => 'OK',
#    'Type' => 'PING-RSP'
#};

$mcmp->enable_app(\%enable_app)

Sends request to enable newly configured Node


            

              
              
$mcmp->enable_app(
        {
                JvmRoute => 'MyAppNode1',
                Alias    => 'MyApp',
                Context  => '/myapp'
        }
);

$mcmp->status(\%status)

Sends load metrics for configured node, number from 1-100


            

              
              
my $status_response = $mcmp->status(
        {
                JvmRoute => 'MyAppNode1',
                Load    => 99,
        }
);
# SAMPLE $status_response
# $VAR1 = {
#     'State' => 'OK',
#     'JvmRoute' => 'MyJVMRoute',
#     'id' => '-297586570',
#     'Type' => 'STATUS-RSP'
# };

$mcmp->disable_app(\%disable_app)

Apache should not create new session for this webapp, but still continue serving existing session on this node


            

              
              
$mcmp->disable_app(
        {
                JvmRoute => 'MyAppNode1',
                Alias    => 'MyApp',
                Context  => '/myapp'
        }
);

$mcmp->stop_app(\%stop_app)

New requests for this webapp should not be sent to this node.


            

              
              
$mcmp->stop_app(
        {
                JvmRoute => 'MyAppNode1',
                Alias    => 'MyApp',
                Context  => '/myapp'
        }
);

$mcmp->remove_app(\%remove_app)

Remove registered context from registered node.


            

              
              
$mcmp->remove_app(
        {
                JvmRoute => 'MyAppNode1',
                Alias    => 'MyApp',
                Context  => '/myapp'
        }
);

$mcmp->enable_route(\%enable_route)

Sends request to enable all of the registered contexts in a selected node


            

              
              
$mcmp->enable_route(
        {
                JvmRoute => 'MyAppNode1',
        }
);

$mcmp->disable_route(\%disable_route)

Sends request to disable all of the registered contexts in a selected node


            

              
              
$mcmp->disable_route(
        {
                JvmRoute => 'MyAppNode1',
        }
);

$mcmp->stop_route(\%stop_route)

Sends request to stop all of the registered contexts in a selected node


            

              
              
$mcmp->stop_route(
        {
                JvmRoute => 'MyAppNode1',
        }
);

$mcmp->remove_route(\%remove_route)

Sends request to remove registered node


            

              
              
$mcmp->remove_route(
        {
                JvmRoute => 'MyAppNode1',
        }
);

$mcmp->debug()

Sends request to receive unparsed DEBUG content of mod_cluster


            

              
              
my $debug_response = $mcmp->debug();

$mcmp->info()

Sends request to receive unparsed INFO content of mod_cluster


            

              
              
my $info_response = $mcmp->info();

$mcmp->has_errors()

Checks if a remote call returned any errors


            

              
              
my $has_errors = $mcmp->has_errors();

$mcmp->error()

Error string that was returned from mod_cluster handler.


            

              
              
my $error_string = $mcmp->error();

SUPPORT

For samples/tutorials, take a look at provided tests in t/ in the distribution directory.

Please report all bugs via github at https://github.com/winfinit/Net-MCMP

AUTHOR

Roman Jurkov (winfinit) <winfinit@cpan.org>

COPYRIGHT

Copyright (c) 2014 the Net::MCMP "AUTHORS" as listed above.

LICENSE

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.