
= Cisco NX-OS Telemetry
:description: Learn how to enable support for Cisco NX-OS telemetry to push operational statistic asynchronously in OpenNMS {page-component-title}.

The Cisco NX-OS Telemetry lets you push operational statistics asynchronously to {page-component-title}.
{page-component-title} sends a request to stream periodic updates once to the device.
Data is generated as Google protocol buffers (GPB) structured messages over UDP.
Detailed information about NX-OS can be found in link:https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus9000/sw/7-x/programmability/guide/b_Cisco_Nexus_9000_Series_NX-OS_Programmability_Guide_7x/b_Cisco_Nexus_9000_Series_NX-OS_Programmability_Guide_7x_chapter_011000.html[NXOS documentation].

To enable support for NX-OS Telemetry, edit `$OPENNMS_HOME/etc/telemetryd-configuration.xml` and set `enabled=true` for the NXOS protocol.

.Enable NX-OS protocol in telemetryd-configuration.xml
[source, xml]
----
<listener name="NXOS-UDP-50001" class-name="org.opennms.netmgt.telemetry.listeners.simple.Udp" enabled="false">
    <parameter key="port" value="50001"/>

    <parser name="NXOS-GPB" class-name="org.opennms.netmgt.telemetry.protocols.common.parser.ForwardParser" queue="NXOS" />
</listener>

<queue name="NXOS">
    <adapter name="NXOS-GPB" class-name="org.opennms.netmgt.telemetry.protocols.nxos.adapter.NxosGpbAdapter" enabled="false">
        <parameter key="script" value="$OPENNMS_HOME/etc/telemetryd-adapters/cisco-nxos-telemetry-interface.groovy"/>

        <package name="NXOS-Default">
            <rrd step="300">
                <rra>RRA:AVERAGE:0.5:1:2016</rra>
                <rra>RRA:AVERAGE:0.5:12:1488</rra>
                <rra>RRA:AVERAGE:0.5:288:366</rra>
                <rra>RRA:MAX:0.5:288:366</rra>
                <rra>RRA:MIN:0.5:288:366</rra>
            </rrd>
        </package>
    </adapter>
</queue>
----

Apply the changes without restarting by sending a `reloadDaemonConfig` event in the CLI or the Web UI:

.Send a reloadDaemonConfig event through CLI
[source, console]
----
$OPENNMS_HOME/bin/send-event.pl -p 'daemonName Telemetryd' uei.opennms.org/internal/reloadDaemonConfig
----

By default, this will open a UDP socket bound to `0.0.0.0:50001` to which NXOS messages can be forwarded.

== Configure NX-OS listener on a Minion

To enable and configure a UDP listener for NX-OS on Minion, connect to the Karaf Console and set the following properties:

[source, console]
----
$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit --alias udp-50001-nxos --factory org.opennms.features.telemetry.listeners
admin@minion()> config:property-set name NXOS
admin@minion()> config:property-set class-name org.opennms.netmgt.telemetry.listeners.UdpListener
admin@minion()> config:property-set parameters.port 50001
admin@minion()> config:property-set parsers.0.name NXOS
admin@minion()> config:property-set parsers.0.class-name org.opennms.netmgt.telemetry.protocols.common.parser.ForwardParser
admin@minion()> config:update
----

NOTE: The protocol must also be enabled on {page-component-title} to process the messages.

== Cisco NX-OS adapter

The NX-OS adapter handles Cisco NX-OS telemetry payloads.
Messages are decoded using the published protobuf (proto3) specifications and forwarded to a JSR-223 compatible script (for example, Beanshell or Groovy) for further processing.
Using the script extension you can extract the desired metrics from the NX-OS messages and persist the results as time series data.

=== Facts

[options="autowidth"]
|===
| Class Name          | `org.opennms.netmgt.telemetry.protocols.nxos.adapter.NxosGpbAdapter`
|===

=== Configuration and use

.Required adapter-specific parameters for the NxosGpbAdapter
[options="header", cols="1,3,1"]
|===
| Parameter
| Description
| Default

| script
| Full path to the script used to handle the NXOS messages.
| none
|===

=== Scripting

The script will be invoked for every NX-OS message that is received and successfully decoded.

The following globals will be passed to the script:

.Globals passed to the script
[options="header", cols="1,3,3"]
|===
| Parameter
| Description
| Type

| agent
| The agent (node) against which the metrics will be associated.
| org.opennms.netmgt.collection.api.CollectionAgent

| builder
| Builder in which the resources and metrics should be added.
| org.opennms.netmgt.collection.support.builder.CollectionSetBuilder

| msg
| Decoded NX-OS message from which the metrics should be extracted.
| org.opennms.netmgt.telemetry.adapters.nxos.proto.TelemetryBis
|===
