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

  # 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 "jvm". 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 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
jvm
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 "jvm" 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

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