jolokia - Utility for managing Jolokia agents used by jmx4perl
# 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
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
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
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.
For a given Jolokia agent, this manager gives you information about the version of the agent and also allows for PGP validation.
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 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
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.
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:
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
The OSGi agents can be used to access OSGi containers
For accessing a Mule ESB, this agent is the proper choice
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
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.
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
If the option <--policy> is provided, an included Jolokia policy file will be printed out (if any).
Repack an Jolokia agent in order to switch on/off certain features.
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.
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
jolokia repack --security-role JMX jolokia.war
By default, the WAR agent allows for JSR-160 proxy requests. This can be switched by repacking the agent with
jolokia repack --no-jsr160 jolokia.war
jmx4perl - CLI for accessing the agents
j4psh - readline based JMX shell with context sensitive command line completion.
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/>.