jmx4perl ======== INTRODUCTION jmx4perl provides a new 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 a an HTTP/JSON based access to the 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 for using it. HOW IT WORKS 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 Perl module JMX::Jmx4Perl::Agent accesses this web application and transform the request's results from JSON into a simple pure Perl object. This distribution contains a sample Nagios check 'check_jmx4perl' which use this result to perform various checks. The command line tool 'jmx4perl' provides an easy access to the agent, too. 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 For now, the following Java Application Servers has been tested on the following servers: * 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) * Apache Geronimo 2.1.4 (Jetty 6 and Tomcat 6) * Glassfish 2.1 * Apache Tomcat 4.1.39, 5.5.27 & 6.0.18 * Jetty 5.1.15 & 6.1.18 (with JMX enabled) * IBM Websphere 6.1 & 7.0 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. 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 it is very likely, that no new features will be added to the backported j4p14.war in the future. j4p14.war has been successfully tested with Weblogic 8.1. SOURCE REPOSITORY Jmx4perl's source is hosted on github.com. You can clone the repository with git://github.com/rhuss/jmx4perl.git as URL 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 . 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 or JMX in general), you might want have a look at http://www.consol.com/opensource/nagios/. 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 forthcoming 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