CLI-Based Utility

The JMX Configuration Generator command line-based (CLI) tool is not installed by default. It is available as an RPM package in the official repositories.

Installation

RHEL-based installation with Yum
yum install opennms-jmx-config-generator
Debian-based installation with apt
apt-get install opennms-jmx-config-generator

Install from source

Before installing the CLI-based utility from the source, you must have the Java 8 Development Kit with Apache Maven installed. The mvn binary must be in the path environment.

After cloning the repository, you must enter the source folder and compile an executable .jar file:

cd opennms/features/jmx-config-generator
mvn package

A file named jmxconfiggenerator-<VERSION>-onejar.jar is created in the new target folder. Use the following command to invoke the file:

java -jar target/jmxconfiggenerator-{full-display-version}-onejar.jar

How to use

After you install the JMC Config Generator, its wrapper script is available in ${OPENNMS_HOME}/bin. Navigate to the directory and invoke the script:

$ cd /path/to/opennms/bin
$ ./jmx-config-generator
When invoked without parameters, the tool’s usage and help information is displayed.

The JMX Configuration Generator uses subcommands for different configuration generation tasks. Each of these subcommands provides different options and parameters.

Table 1. JMX Configuration Generator subcommands
Subcommand Description

query

Queries an MBean Server for certain MBeans and attributes.

generate-conf

Generates a valid jmx-datacollection-config.xml file.

generate-graph

Generates an RRD graph definition file with matching graph definitions for a given jmx-datacollection-config.xml.

The following global options are available in each of the tool’s subcommands:

Option Description Default Value

-h, --help

Show help and usage information.

false

-v, --verbose

Enable verbose mode for debugging purposes.

false

query

The query subcommand is used to query an MBean server for its available MBean objects. The following example queries myserver with the credentials myusername/mypassword on port 7199. It searches for MBean objects in the java.lang domain:

./jmx-config-generator query --host myserver --username myusername --password mypassword --port 7199 "java.lang:*"
java.lang:type=ClassLoading
	description: Information on the management interface of the MBean
	class name: sun.management.ClassLoadingImpl
	attributes: (5/5)
		TotalLoadedClassCount
			id: java.lang:type=ClassLoading:TotalLoadedClassCount
			description: TotalLoadedClassCount
			type: long
			isReadable: true
			isWritable: false
			isIs: false
		LoadedClassCount
			id: java.lang:type=ClassLoading:LoadedClassCount
			description: LoadedClassCount
			type: int
			isReadable: true
			isWritable: false
			isIs: false

<output omitted>

The following command line options are available for the query subcommand:

Option Description Default Value

<filter criteria>

A filter criteria to query the MBean server for. Its format is <objectname>[:attribute name].
The <objectname> accepts the default JMX object name pattern, and identifies the MBeans objects to retrieve. If set to null, all domains are shown. If no key properties are specified, the domain’s MBeans are retrieved.
To run the command for certain attributes, you must add :<attribute name>. The <attribute name> accepts regular expressions.
Where multiple <filter criteria> are provided, they are OR concatenated.

Empty

--host <host>

Hostname or IP address of the remote JMX host.

Empty

--ids-only

Only show the IDs of the attributes.

false

--ignore <filter criteria>

Set <filter criteria> to ignore while running.

Empty

--include-values

Include attribute values.

false

--jmxmp

If true, use the JMX Messaging Protocol instead of JMX over RMI.

false

--password <password>

Password for JMX authentication.

Empty

--port <port>

JMX service’s port.

Empty

--show-domains

List only available domains.

true

--show-empty

Includes MBeans, even if they do not have attributes, either due to the <filter criteria> or while there are none.

false

--url <url>

Custom connection URL
<hostname>:<port>
service:jmx:<protocol>:<sap>
service:jmx:remoting-jmx://<hostname>:<port>

Empty

--username <username>

Username for JMX authentication.

Empty

-h, --help

Show help and usage information.

false

-v, --verbose

Enables verbose mode for debugging purposes.

false

generate-conf

You can use the generate-conf subcommand to generate a valid jmx-datacollection-config.xml file for a given set of MBean objects queried from an MBean server. The following example generates a myconfig.xml file for MBean objects in the java.lang domain of myserver, on port 7199. It uses the myusername/mypassword credentials for access:

jmx-config-generator generate-conf --host myserver --username myusername --password mypassword --port 7199 "java.lang:*" --output myconfig.xml
Dictionary entries loaded: '18'
You must define either a URL or a hostname and port to connect to a JMX server.

The following command line options are available for the generate-conf subcommand:

Option Description Default Value

<attribute id>

A list of attribute IDs to include in the new configuration file.

Empty

--dictionary <file>

Path to a dictionary file containing replacements for attribute names and parts of MBean attributes. Each line in the file must include a replacement definition (for example, Auxillary:Auxil).

Empty

--host <host>

Hostname or IP address of the JMX host.

Empty

--jmxmp

If true, use the JMX Messaging Protocol instead of JMX over RMI.

false

--output <file>

Output file name to write the generated configuration file to.

Empty

--password <password>

Password for JMX authentication.

Empty

--port <port>

JMX service’s port.

Empty

--print-dictionary

Prints the used dictionary to STDOUT. May be used with --dictionary.

false

--service <value>

The service name used as a JMX data collection name.

anyservice

--skipDefaultVM

Skip default JavaVM Beans. If true, the command ignores standard MBeans provided by the JVM and creates configurations only for those provided by the Java application. This is particularly useful if an optimized configuration for the JVM already exists.
If not set, the generated configuration file will include the MBeans provided by the JVM and the Java application.

false

--skipNonNumber

Skip attributes with non-number values.

false

--url <url>

Custom connection URL
<hostname>:<port>
service:jmx:<protocol>:<sap>
service:jmx:remoting-jmx://<hostname>:<port>

Empty

--username <username>

Username for JMX authentication.

Empty

-h, --help

Show help and usage information.

false

-v, --verbose

Enables verbose mode for debugging purposes.

false
Check the file and see if there are alias names with more than 19 characters. These errors are marked with NAME_CRASH_AS_19_CHAR_VALUE.

generate-graph

The generate-graph subcommand generates an RRD graph definition file for a defined configuration file. The following example generates the mygraph.properties graph definition using the configuration settings in myconfig.xml:

./jmx-config-generator generate-graph --input myconfig.xml --output mygraph.properties
reports=java.lang.ClassLoading.MBeanReport, \
java.lang.ClassLoading.0TotalLoadeClassCnt.AttributeReport, \
java.lang.ClassLoading.0LoadedClassCnt.AttributeReport, \
java.lang.ClassLoading.0UnloadedClassCnt.AttributeReport, \
java.lang.Compilation.MBeanReport, \
<output omitted>

The following command line options are available for the generate-graph subcommand:

Option Description Default Value

--input <jmx-datacollection.xml>

Configuration file to use as the input when generating the graph properties file.

Empty

--output <file>

Output file name for the generated graph properties file.

Empty

--print-template

Prints the default template.

false

--template <file>

Name of the template file to use to generate the graph properties. The file must use the Apache Velocity template engine.

Empty

-h, --help

Show help and usage information.

false

-v, --verbose

Enables verbose mode for debugging purposes.

false

Graph templates

The JMX Configuration Generator uses a template file to generate graphs. As such, you can set it to use a custom template. The --template option, followed by a file name, lets the JMX Configuration Generator use an external template file as the base for graph generation.

The following example shows how the custom mytemplate.vm file is used to generate the mygraph.properties graph definition file, using the configuration settings defined in myconfig.xml:

./jmx-config-generator generate-graph --input myconfig.xml --output mygraph.properties --template mytemplate.vm

The template file must be in the Apache Velocity format. The following sample represents the template that is used by default:

reports=#foreach( $report in $reportsList )
${report.id}#if( $foreach.hasNext ), \
#end
#end

#foreach( $report in $reportsBody )

#[[###########################################]]#
#[[##]]# $report.id
#[[###########################################]]#
report.${report.id}.name=${report.name}
report.${report.id}.columns=${report.graphResources}
report.${report.id}.type=interfaceSnmp
report.${report.id}.command=--title="${report.title}" \
 --vertical-label="${report.verticalLabel}" \
#foreach($graph in $report.graphs )
 DEF:${graph.id}={rrd${foreach.count}}:${graph.resourceName}:AVERAGE \
 AREA:${graph.id}#${graph.coloreB} \
 LINE2:${graph.id}#${graph.coloreA}:"${graph.description}" \
 GPRINT:${graph.id}:AVERAGE:" Avg \\: %8.2lf %s" \
 GPRINT:${graph.id}:MIN:" Min \\: %8.2lf %s" \
 GPRINT:${graph.id}:MAX:" Max \\: %8.2lf %s\\n" \
#end

#end

The JMX Configuration Generator generates different types of graphs from jmx-datacollection-config.xml:

Graph Type Description

AttributeReport

A graph is generated for each attribute of any MBean. Composite attributes are ignored.

MbeanReport

A combined graph of all attributes is generated for each MBean. Composite attributes are ignored.

CompositeReport

A graph is generated for each composite attribute of any MBean.

CompositeAttributeReport

A combined graph of all composite attributes is generated for each MBean.