jmx4perl
                              ========

INTRODUCTION

 jmx4perl provides an alternate way for accessing Java JEE Server
 management interfaces which are based on JMX (Java Management
 Extensions). It is an agent based approach, where a small Java
 Webapplication deployed on the application server provides an
 HTTP/JSON based access to JMX MBeans registered within the
 application server.

 A discussion about the pros and cons of an agent based vs. a direct
 JMX remoting (which is available via JSR 160 connectors) can be
 found in the manual "JMX::Jmx4Perl::Manual" contained within this
 package. The biggest advantage for an agent based approach is that
 no local java installation is required.

 Since version 0.50 a second operational mode has been added in which
 jmx4perl acts as a JMX bridge. It accepts the usual HTTP/JSON
 requests which are forwarded to the target server via JSR-160 based
 remote communication. The advantage of this proxy mode is that no
 agent is required to be installed on the target platform.

HOW IT WORKS

 For the agent mode, you need to deploy a small (~ 100k) Java Agent
 WAR (web archive) to the Java application server to monitor. Thats
 all on the java side. There is no need to add any startup parameters
 to the application server and to open any additional ports. All
 communication takes places via HTTP where JSON objects are
 exchanged. Additionally, the agent benefits from the security
 infrastructure in place which every application server provides for
 web application.

 The proxy mode needs the j4p.war to de deployed on an arbitrary
 servlet engine, which can reach the target platform to monitor for
 the selected JSR-160 connector (e.g RMI/JRMP or RMI/IIOP). The
 target server needs to have remote JMX access enabled.

 The Perl module JMX::Jmx4Perl::Agent accesses the deployed agent
 servlet and transform the request's results from JSON into a simple
 Perl object. This distribution contains a sample Nagios check
 'check_jmx4perl' which use this result to perform various checks.
 The tool 'jmx4perl' provides an easy access to the
 agent from the command line.

INSTALLATION

 The Perl part installs as any other module via Module::Build, which
 you need to have installed. Using

 perl Build.PL
 ./Build
 ./Build test
 ./Build install

 will install the modules. If you have Java and "ant" (a Java build
 tool) installed, the Java agent will be compiled and packaged as
 well when you use 'Build dist'. However, this is not required. A
 precompiled "j4p.war" can be found in the "agent" directory.

 For the module to work, you need to deploy "j4p.war" to the JEE
 Server to monitor. The concrete steps depend on the specific
 deploying mechanism of your target server, which in most cases is a
 simple copy in to a specific directory. Please consult the
 documentation of your Java application server for the details (look
 for "deployment" and "war")

 To test it, you can use 'jmx4perl' with the URL of the deployed
 agent:

     jmx4perl http://<jeeserver>:<port>/j4p

 Consult 'man jmx4perl' for further details.

SUPPORTED APPLICATION SERVERS

 The following Java Application Servers has been confirmed to work
 with jmx4perl in agent mode deployed as war:

 * JBoss 4.2.3 GA, 5.1.0 GA & 6.0.0 M3
 * Oracle WebLogic 9.2 MP3 & 10.0.2.0
 * Jonas 4.10.7 (with Jetty 5.1.10 and Tomcat 5.5.28) and 5.1.1
 * Apache Geronimo 2.2 (Jetty 7 and Tomcat 6)
 * Glassfish 2.1.1 and v3
 * Apache Tomcat 5.5.28 & 6.0.26
 * Jetty 5.1.15 & 6.1.22 & 7.0.1 (with JMX enabled) & 8.0.0.M0
 * IBM Websphere 6.1 & 7.0
 * Resin 3.1.9
 * Spring dm Server 2.0.0.RELEASE

 The OSGi agent budle has been tested on

 * Felix 2.0.4 & 3.0.1
 * Equinox 3.5.2 & 3.6.0

 The JVM JDK 6 agent has been verified to work on

 * ActiveMQ 5.3.1
 * Terracotta 3.2.1
 * Hadoop 0.20.2

 The proxy mode has been explicitely tested for

 * JBoss 4.2.3 GA & 5.1.0 GA
 * Oracle WebLogic 9.2 MP3 & 10.0.2.0
 * Glassfish 2.1.1 and v3

 The jmx4perl OSGi Bundle has been tested with the following containers:

 * Felix ...
 * Equinox ...
 * Knopflerfish ...
 * Spring dm Server ...

 More test are scheduled, detailed setup instructions for individual
 JEE servers can be found at http://labs.consol.de/tags/jsr-160

 It is expected that every Java application server which runs with at
 least Java 1.5 and conforms to at least version 2.4 of the Servlet
 specification should work out of the box.  Please open a bug at
 http://rt.cpan.org/Public/Bug/Report.html?Queue=jmx4perl if you
 encounter any problems.

MULE AGENT SUPPORT

 This distribution contains a Mule ESB (www.mulesoft.org) agent which
 can be deployed on the Mule ESB (running in standalone
 mode). Currently, you need to build the agent from source,
 though. Maven is required for building the agen. Call 'mvn install'
 within the 'agent' directory, you find the agent then as
 'agent/modules/j4p-mule/target/j4p-mule-<version>-agent.jar'.
 Alternatively the agent jar can be downloaded from the maven
 labs.consol.de's repository at
 http://labs.consol.de/maven/repository/org/jmx4perl/j4p-mule/

 Installation instruction are included in JMX::Jmx4Perl::Manual
 The initial article related can be found at
 http://labs.consol.de/blog/jmx4perl/jmx4perl-mule-agent

OSGi AGENT SUPPORT

 An j4p OSGi bundle can be deployed on any OSGi container where a
 OSGi compliant HttpService is available. You can download the bundle
 from http://labs.consol.de/maven/repository/org/jmx4perl/j4p-osgi
 or build it from scratch with maven. The source is located in
 agent/modules/j4p-osgi

JDK6 JVM AGENT

 A native Java JVM agent is provided, too. The only dependency is on
 Sun's JDK 6, which contains a lightweight HTTP Server used for
 exporting the j4p data. You can download it from
 http://labs.consol.de/maven/repository/org/jmx4perl/j4p-jvm-jdk6
 or build it from scratch with maven out of
 agent/modules/j4p-jvm-jdk6.

 To use it simply provide the following argument to the Java
 application to monitor (any Java 6 application can be used):

 -javaagent:/path/to/j4p-jvm-jdk6-<version>-agent.jar

 By default, it will listen on port 8778, but this can be configured
 as well as other aspects like authentication:

 * Provide options on the commandline as key-value pairs:
   -javaagent:agent.jar=port=7777,host=localhost

 * Via a properties file
   -javaagent:agent.jar=config=/path/to/config.properties

 * Via packaging a j4p-agent.properties top level in the agent.jar

 Options are used in the given precedence, the former overwritting
 the later values.

RESOURCES

 * Jmx4perl's source is hosted on github.com. You can clone the
   repository with git://github.com/rhuss/jmx4perl.git as URL

 * Interesting articles around Jmx4Perl, JMX and Nagios can be found
   at http://labs.consol.de Checkout the various post categories for
   selecting a specific topic.

 * www.jmx4perl.org is the canonical entry point for jmx4perl related
   information.

LICENSE

 Copyright (C) 2009 Roland Huss ([email protected])

 Jmx4perl is free software: you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 2 of the License, or
 (at your option) any later version.

 jmx4perl is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with jmx4perl.  If not, see <http://www.gnu.org/licenses/>.

 A commercial license is available as well. You can either apply the
 GPL or obtain a commercial license for closed source
 development. Please contact [email protected] for further information.

PROFESSIONAL SERVICES

 Just in case you need professional support for this module (or
 Nagios, JMX or JEE in general), you might want to have a look at
 http://www.consol.com/nagios-monitoring . Contact
 [email protected] for further information (or use the contact
 form at http://www.consol.com/contact/ )

ACKNOWLEDGMENTS

 Many thanks go to Gerhard Lausser, who pushed me to think harder
 about a better way for monitoring JEE Servers with Nagios.

BUGS

 Please report any bugs and/or feature requests at
 http://rt.cpan.org/Public/Bug/Report.html?Queue=jmx4perl

AUTHOR

 [email protected]

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.