                               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 both in agent mode :

  * JBoss 4.2.3 GA & 5.1.0 GA
  * Oracle WebLogic 9.2 MP3 & 10.0.2.0
  * Jonas 4.10.3 (with Jetty 5.1.10 and Tomcat 5.5.26) and 5.1.0
  * Apache Geronimo 2.1.4 (Jetty 6 and Tomcat 6)
  * Glassfish 2.1.1 and v3
  * Apache Tomcat 5.5.28 & 6.0.20
  * Jetty 5.1.15 & 6.1.21 & 7.0.0 (with JMX enabled)
  * IBM Websphere 6.1 & 7.0

  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

  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.conso.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

LEGACY JDK 1.4 SUPPORT

  For legacy application servers like Weblogic 8.1 a JDK 1.4 backport
  for the agent is provided. However, you need to build the agent on
  your own by using 'ant jdk14' within the "agent" directory which
  builds a j4p14.war. A maven build is provided as well within
  agent/modules/jdk14. Please note the this support is experimentally
  and the version is freezed to 0.36. j4p14.war has been successfully
  tested with Weblogic 8.1. This JDK 1.4 support will be removed in
  the next version (you can always download 0.50 if you need the JDK
  1.4 support)

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 (roland@cpan.org)

  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 roland@cpan.org 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
  roland.huss@consol.de 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. Good
  luck, Gerhard, with your new Nagios book, available since October
  2010

BUGS 

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

AUTHOR

  roland@cpan.org
