Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Configure a NETCONF Proxy Telemetry Sensor in Junos

 

Using Junos telemetry streaming, you can turn any available state information into a telemetry sensor by means of the XML Proxy functionality. The NETCONF XML management protocol and Junos XML API fully document all options for every supported Junos OS operational request. After you configure XML proxy sensors, you can access data over NETCONF “get” remote procedure calls (RPCs).

This task shows you how to stream the output of a Junos OS operational mode command.

Best Practice

We recommend that you not use YANG files that map to an extensive or verbose Junos OS operational commands, such as show interfaces or show route. The use of such a file could result in very slow or no streaming of telemetry data or very high CPU usage for various processes.

This task requires the following:

  • An MX Series, vMX Series, or PTX Series router operating Junos OS Release 17.3R2 or later.

  • Installation of the required Network Agent package ( network-agent-x86–32–17.4R1.16-C1.tgz or later).

  • A telemetry data receiver, such as OpenNTI, to verify proper operation of your telemetry sensor.

In this task, you will stream the contents of the Junos OS command show system users.

show system users (vMX Series)

user@switch> show system users

In addition to the expected list of currently logged-in users, the show system users output also provides the average system load as 1, 5 and 15 minutes. You can find the load averages by using the show system users | display xml command to view the XML tagging for the output fields. See <load-average-1>, <load-average-5>, and <load-average-15> in the XML tagging output below.

user@switch> show system users | display xml
Tip

The uptime-information tag shown in the preceding output is a container that contains leafs, such as date-time, up-time, active-user-count. and load-average-1. Below is a sample YANG file for this container:

Tip

The uptime-information tag also has another container named user-table that contains a list of user entries.

Below is a sample YANG file for this container:

Create a User-Defined YANG File

The YANG file defines the Junos CLI command to be executed, the resource path the sensors are placed under, and the key value pairs taken from the matching XML tags.

Custom YANG files for Junos OS conform to the YANG language syntax defined in RFC 6020 YANG 1.0 YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF) and RFC 7950 The YANG 1.1 Data Modeling Language. Certain directives need to be present in the file that configure XML proxy.

To use the xmlproxyd (daemon) process to translate telemetry data, create a render.yang file. In this file, the dr:command-app is set to xmlproxyd.

The XML proxy YANG filename and module name must start with xmlproxyd_:

  • For the XML proxy YANG filename, add the extension .yang, for example, xmlproxyd_sysusers.yang

  • For the module name, use the filename without the extension .yang, for example, xmlproxyd_sysusers

To simplify creating a YANG file, it’s easiest to start by modifying a working example.

  1. Provide a name for the module. The module name must start with xmlproxyd_ and be the same name as the XML proxy YANG file name.

    For example, for an XML proxy YANG file called sysusers.yang, drop the .yang extension and name the module xmlproxyd_sysusers:

    module xmlproxyd_sysusers {

  2. For the Junos Telemetry Interface, include the process (daemon) name xmlproxyd:

    dr:command-app "xmlproxyd";

  3. Include the following RPC for the NETCONF get request:

    rpc juniper-netconf-get {

  4. Specify the location of the output of the RPC, where company-name is the name you give to the location:

    dr:command-top-of-output "/company-name";

  5. Include the following command to execute the RPC:

    dr:command-full-name "drend juniper-netconf-get";

  6. Specify the CLI command from which to retrieve data. The Junos OS CLI command that gets executed at the requested sample frequency is defined under dr:cli-command and executed by the xmlproxyd daemon.

    To retrieve command output for the Junos OS command show system users:

    dr:cli-command "show system users";

  7. Escalate privileges, logon as “root”, connect to the internal management socket via Telnet, and specify help for an RPC:

    dr: command-help “default <get> rpc”;

    When this is included in the YANG file, output that is helpful for debugging is displayed in the help drend output on the internal management socket:

    200-juniper-netconf-get-0 system users <get> RPC

  8. Specify the hierarchy and use the dr:source command to map to a container, a list, or a specific leaf. The absolute path under which the sensors will be reported is built from the output group junos plus system-users-information, concatenated by /’. The path /junos/system-users-information/ is the path to query for information about this custom sensor.Warning

    You should not create a custom YANG model that conflicts or overlaps with predefined native paths (Juniper defined paths) and OpenConfig paths (resources). Doing so can result in undefined behavior.

    For example, do not create a model that defines new leafs at or augments nodes for resource paths such as /junos/system/linecard/firewallor /interfaces.

    A one-to-one mapping between container, leafs and the XML tag or value from the CLI command output is defined in the grouping referenced by uses within the output container. A grouping can be referred to multiple times in different container outputs. The container system-users-information below uses the grouping system-users-information. However, it is defined without the aforementioned one-to-one mapping for every container, list and leaf to an output XML tag from the CLI command XML output.

  9. The following YANG file shows how to include these commands to enable the xmlproxyd process to retrieve the full operational state and map it to the leafs in Juniper’s own data model:

Load the Yang File in Junos

After the YANG file is complete, upload the YANG file and verify that the module is created.

  1. Upload the YANG file to the router.
  2. Register the YANG file using the request system yang add package command.
    user@switch> request system yang add package sysusers proxy-xml module xmlproxyd_sysusers.yang
    Note

    Starting in Junos OS Release 18.3R1, adding, deleting, or updating YANG packages in configuration mode with the run command is not supported.

  3. Verify that the module (sensor) is registered using the show system yang package sysusers command, where sysusers is the name of the package:
    user@switch> show system yang package sysusers
  4. Enable gRPC in the Junos OS configuration:
    user@switch> set system services extension-service request-response grpc port 32767

Collect Sensor Data

Use your favorite collector to pull the newly created telemetry sensor data from the device. .The following instructions use the collector jtimon. For information about jtimon setup, see Junos Telemetry Interface client.

  1. Create a simple configuration file, here named vmx1.json. Adjust the host IP address and the port, as needed. The path /junos/system-users-information is specified. The freq field is defined in MicroSoft, streaming a new set of key value pairs every 5 seconds. Optionally, you can add multiple paths.
  2. Launch the collector, using either your own compiled file or an automatically built image from Docker Hub.

    The sample query output below shows the sensor report by path. Every key is sent in human-readable form as an absolute path. In case of lists, the absolute path contains an index in the form of XPATH which is ideal to group values from a (time series) database, such as InfluxDB. For example, the output below shows the path /junos/system-users-information/uptime-information/user-table/user-entry[user='ab']/.

    You can terminate the stream of sensor data using Ctrl-C.

    $ docker run -tu --rm -v $(PWD):/u mw/jtimon --config vmx1.json --print

    The sample query shown below shows two sensor reports per path, then I terminated it with Ctrl-C. Every key is sent in human readable form as an absolute path and in case of lists, contains an index in form of XPATH, ideal to group values from a (time series) database like InfluxDB e.g. /junos/system-users-information/uptime-information/user-table/user-entry[user='ab']/

  3. Verify that the module (sensor) is loaded using the show system yang package sysusers command, where sysusers is the name of the package:
    user@switch> show system yang package sysusers
  4. Enable gRPC in the Junos OS configuration:
    user@switch> set system services extension-service request-response grpc port 32767

Installing a User-Defined YANG File

To add, validate, modify, or delete a user-defined YANG file for XML proxy for the Junos Telemetry Interface, use the request system yang set of commands from the operational mode:

  1. Specify the name of the XML proxy YANG file and the file path to install it. This command creates a .json file in the /opt/lib/render directory.
    Note

    This command can be performed only on the current routing engine.

    To add multiple YANG modules with the request system yang add package package-name proxy-xml module command, enclose the file-path-name in brackets: [ file-path-name 1 file-path-name 2 ]

  2. (Optional) Validate an module before adding it to the router using the request system yang validate proxy-xml module module-name command. .

    The output XML proxy YANG module validation for xmlproxyd_<module-name> : SUCCESS indicates successful module validation.

    Mismatch error sometimes occur. If the command returns the error below, you can eliminate the error by using Junos OS Release 17.3R2 or later:

  3. (Optional) Update an existing XML proxy YANG file that was previously added.
  4. Delete an existing XML proxy YANG file.
  5. Verify that the YANG file has been installed by entering the show system yang package command.

Troubleshoot Telemetry Sensors

Problem

Description: Use the following methods to troubleshoot user-define telemetry sensors:

  • Execute a tcpdump for the interface your gRPC requests came from (for this task, interface fxp0 was used).

    user@switch>monitor traffic interface fxp0 no-resolve matching "tcp port 32767"
  • Enable traceoptions using the set services analytics traceoptions flag xmlproxy command. Check the xmlproxyd log file for confirmation of whether the CLI command’s RPC was sent and if a response was received:

  1. Issue the show log xmlproxyd command to show the xmlproxyd log. The value for the field xmlproxy_execute_cli_command: indicates if the RPC was sent or not. The value for the field xmlproxy_build_context indicates the command.
user@switch>show log xmlproxyd