NAME

jolokia - Utility for managing Jolokia agents used by jmx4perl

SYNOPSIS

# Execute command 'command' with options and additional, command specific 
# arguments
jolokia [options] <command> <arg1> <arg2> ...

# Download the latest Jolokia WAR agent compatible with this jmx4perl release
# into the local directory as 'jolokia.war'
jolokia download

# Print information about a downloaded agent (i.e. its version)
jolokia info jolokia.war

# Repackage the agent to include a security policy
jolokia repack --policy jolokia.war

# Current Jmx4Perl version
jolokia --version

# Online help
jolokia --help

Options:

Command 'download':
   --agent <type>[:<version>]    Agent to download. <type> must be one of "war", "osgi", 
                                 "osgi-bundle", "mule" or "jdk6". An optional Jolokia version 
                                 can be added after a colon.
   --outdir <dir>                Output directory for the agent downloaded (default: ".")
   --repository <repo-url>       Repository URL from where to fetch the Jolokia agent. 
                                 (default is taken from meta data)
   --template <name>[:<version>] Download a template with given name and optional version. E.g.
                                 "jolokia-access.xml:0.83". If used with --agent, the same version
                                 as for the agent is used by default
   --policy                      Same as --template jolokia-access.xml

Command 'info':
   --verify                      Check signature of given file
   --policy                      Print out an embedded jolokia-access.xml

Command 'repack':
   --policy                      Adds a jolokia-access.xml policy file, which is in the current 
                                 directory. --no-policy removes the policy file.
   --policy-file <policy file>   Alternate policy file to use (implies --policy)
   --security                    Add security to the web.xml with role 'jolokia' by default. 
                                 Use no-security in order to remove security section completely
   --security-role <role>        Select a different role for WEB security. Implies --security
   --no-jsr160-proxy             Remove the JSR-160 proxy declaration from web.xml. Re-add with 
                                 --jsr160-proxy

General:
   --quiet            No output on the standard out
   --verbose          Print verbose
   --no-color         Don't use colors
   --no-cache         Fetch meta information afresh from www.jolokia.org
   --proxy            Proxy-URL for HTTP(S) requests
   --proxy-user       Proxy user for proxy authentication
   --proxy-password   Proxy password for proxy authentication
   --help             Print online help (and exit)
   --version          Current Jmx4Perl version

DESCRIPTION

jolokia is a command line utility for managing the Jolokia agent, which is used by jmx4perl for accessing remote JMX information. Several commands are available

download

This mode allows for downloading the latest Jolokia agent version compatible with this Jmx4Perl installation or any other agent version. PGP is used optionally for verifying the integrity of the downloaded artifacts.

info

For a given Jolokia agent, this manager gives you information about the version of the agent and also allows for PGP validation.

repack

A Jolokia agent can be repacked in order to add a policy file or to manipulate the internal web.xml with this mode.

download ist the default mode when no non-opt argument is given, if a single argument is given and this single argument is not one of the modes above, info is used as the default command and the single argument is the file to examine.

META-DATA

Meta-data about the available Jolokia agents and their compatibility to given Jmx4Perl versions is obtained from http://www.jolokia.org/jolokia.meta. This meta data is cached locally in ~/.jolokia_meta and only fetched once a day. The meta download can be forced by using the option --no-cache.

VALIDATION

jolokia uses PGP for validating all files downloaded. For this to work, either the CPAN module Crypt::OpenPGP or GnuPG (http://www.gnupg.org/) must be installed. If it is not available, validation falls back to simple checksum validation with a SHA1 alogrithm, or, if this is not possible to an MD5 check. Since the checksums are also downloaded over an insecure channel, using PGP is highly recommended. The public key used for the signature check is contained locally in the modules so there is no need to add the key manually or to download it from an PGP key server. I.e. if GnuPG is used, the key will be added to the local keystore for the first validation.

COMMANDS

download

This commands allows for downloading a certain Jolokia agent from Jolokia's Maven repository. The repository URL is taken from the meta descriptor, but can be overridden with the --repository option. Agents come in several flavors:

• war

  The WAR agent is the most popular one and is used for instrumenting an JEE application server. It is a simple web application which needs to deployed on the target server

• osgi, osgi-bundle

  The OSGi agents can be used to access OSGi containers

• mule

  For accessing a Mule ESB, this agent is the proper choice

• jdk6

  For all other Java server, which don't contain a servlet container, this agent can be used. The only prerequisite is, that the application must run with an Oracle Java 6 virtual machine

Much more information about those agents can be found at http://www.jolokia.org/agent.html.

By default, the war agent is downloaded. The agent type ("war", "osgi", "osgi-bundle", "mule" or "jdk6" can be specified with the --agent option.

Also by default, the latest agent version compatible with the installed Jmx4Perl release is downloaded. A specific version can be given on the command line also with the --agent option, added after the agent type with a ':'. E.g. --agent osgi:0.82 will download the OSGi agent with version 0.82.

The output directory for the agent can be specified with the --outdir option. By default, the agent is stored in the current working directory.

A template can be downloaded with --template. This option uses the same syntax as --agent, i.e. a version number can be optionally defined. If no version number is provided, either the default template is downloaded, or, if used together with --agent, the template matching the agent's version is used.

info

In order to determine the version number of an already downloaded agent, the info command can be used. It takes as single argument the path to the agent, e.g.

jolokia info ./jolokia.war

The output contains information about the agent's type and version, whether a security policy file is installed, if authentication is switched on and if the JSR160 proxy is active.

With the option --verify an additional signature check can be performed, where the signature is fetched from the Jolokia repository.

info is the default command if a single file argument is given (i.e. the example above could be abreviated to jolokia ./jolokia.war).

If the option <--policy> is provided, an included Jolokia policy file will be printed out (if any).

repack

Repack an Jolokia agent in order to switch on/off certain features.

--policy / --no-policy

Adds a Jolokia policy file to the agent given as argument. By default a policy file jolokia-access.xml from the current directory is used, but this file can be directly specified with the --policy-file option. For example,

jolokia repack --policy jolokia.war

add the local policy file jolokia-access.xml to the WAR agent specified as argument. A sample jolokia-access.xml can be downloaded with jolokia --policy which will then be saved locally. The policy contained in agent can be viewed with jolokia --policy jolokia.war. "ACCESS POLICY" in JMX::Jmx4Perl::Manual contains more information about Jolokia policy files.

--security / --no-security

For WAR agents, the included web.xml descriptor can contain authentication configuration. This configuration (which is absent by default), associates an URL pattern with a role. With jolokia repack --security jolokia.war the authenticatin mechanism is switched on with an associated role "Jolokia". You need to configure your servlet container accordingly to connect a user to this role. The role can be specified with --security-role (which implies --security):

jolokia repack --security-role JMX jolokia.war

--jsr160-proxy / --no-jsr160-proxy

By default, the WAR agent allows for JSR-160 proxy requests. This can be switched by repacking the agent with --no-jsr160-proxy:

jolokia repack --no-jsr160 jolokia.war

SEE ALSO

check_jmx4perl - a production ready Nagios check using JMX::Jmx4Perl

jmx4perl - CLI for accessing the agents

j4psh - readline based JMX shell with context sensitive command line completion.

LICENSE

This file is part of jmx4perl.

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

AUTHOR

roland@cpan.org

cpanm JMX::Jmx4Perl

perl -MCPAN -e shell
install JMX::Jmx4Perl