DragonFly On-Line Manual Pages
JOLOKIA(1) User Contributed Perl Documentation JOLOKIA(1)
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:
o 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
o osgi, osgi-bundle
The OSGi agents can be used to access OSGi containers
o mule
For accessing a Mule ESB, this agent is the proper choice
o 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
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
perl v5.20.2 2015-09-16 JOLOKIA(1)