
= CLI-Based Utility
:description: Learn how to install and use the command line-based JMX Configuration Generator generator tool with {page-component-title} (Debian and RPM).

The JMX Configuration Generator command line-based (CLI) tool is not installed by default.
ifeval::["{page-component-name}" == "meridian"]
It is available as an RPM package in the official repositories.
endif::[]
ifeval::["{page-component-name}" == "horizon"]
It is available as Debian and RPM packages in the official repositories.
endif::[]

== Installation

.RHEL-based installation with Yum
[source, console]
yum install opennms-jmx-config-generator

ifndef::opennms-prime[]
.Debian-based installation with apt
[source, console]
apt-get install opennms-jmx-config-generator

endif::opennms-prime[]
=== 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:

[source, console]
----
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:

[source, console]
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:

[source, console]
----
$ cd /path/to/opennms/bin
$ ./jmx-config-generator
----

TIP: 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.

.JMX Configuration Generator subcommands
[options="autowidth"]
|===
| 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:

[options="autowidth"]
|===
| 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:

[source, console]
----
./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:

[cols="1,3,1"]
|===
| 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:

[source, console]
----
jmx-config-generator generate-conf --host myserver --username myusername --password mypassword --port 7199 "java.lang:*" --output myconfig.xml
Dictionary entries loaded: '18'
----

NOTE: 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:

[cols="1,3,1"]
|===
| 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
|===

IMPORTANT: 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`:

[source, console]
----
./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:

[cols="2,4,1"]
|===
| 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 http://velocity.apache.org[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`:

[source, console]
----
./jmx-config-generator generate-graph --input myconfig.xml --output mygraph.properties --template mytemplate.vm
----

The template file must be in the http://velocity.apache.org[Apache Velocity] format.
The following sample represents the template that is used by default:

[source, properties]
----
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`:

[options="autowidth"]
|===
| 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.
|===
