Example workflows for creating user defined data receivers

Introduction

Example 1 - Adding sub-objects to a server device

Example 2 – Adding sub-objects with attributes to a device 

Example 3 – Adding attributes to a custom device 

Introduction

The following workflows show how to create user defined data receivers that add sub-objects and attributes to devices using streaming telemetry. Each example includes a different supported streaming telemetry method:

• DMTF's Redfish 
• Cisco Model-Driven Telemetry (MDT)
• gNMI (gRPC Network Management Interface) 

General tab

After the device and Entuity server are configured (see Device configuration), messages sent to the Entuity server are displayed on the Data Sources tab of the User Defined Data Receiver page.

1. From the Entuity Main menu, go to Administration, and click User Defined Data Receiver under Polling.
   The User Defined Data Receiver page is displayed.
2. Click the Data Sources tab at the top of the User Defined Data Receiver page.
3. From the table, select the Redfish data source for which you want to create a data receiver, and click Create Receiver at the top of the page or via the Overflow Menu.
   This takes you to the General tab. 
4. Enter the Receiver Name and Display Name for the receiver.
   In this example, the receiver name is iDRAC_PSU and the display name is iDRAC PSU. 
5. Specify the Context Type as Server Device.
   
   
    
6. Specify the Receiver Type as Sub-object Creation.
   This means the data receiver will create one or more sub-components associated with the server device each time a new message is received from the data source.
7. If the Media Type is not automatically detected as JSON, select JSON from the Media Type drop-down menu.
8. Select JSON Sanitiser Adaptor from the Data Adaptor drop-down menu to format the payload into valid JSON.
   
   
9. Click Next to go to the Steps tab.

Steps tab

Create at least one step for the new data receiver:

1. On the Steps tab of the User Defined Data receiver page, click New Object Creation Step.
2. In the Step Details column, click the toggle option on Step Execution to make it Conditional.
3. In the Step Filter field, enter ${ and select the dataSourceID option.
   This limits object creation to only the device sending this record type.
   
4. In the Component Type field, enter the Type Name and Type Display Name.
   In this example, PSU is the value for both fields.
5. Click Done and then click Next to go to the Attributes tab.

Attributes tab 

The Attributes tab for a Sub-object Creation step displays the Index and Name attributes. The Index attribute is mandatory and must always be defined to supply a unique identifier for each sub-object. The Name attribute defaults to a value based on the value of the Index attribute.

1. Select the Index attribute, and click Edit. 
   
   
    
2. Click Explore Path to choose the field within each array that will provide the most appropriate unique identifier for each sub-object. 
   In this example, the member_id field is selected.
   
   
    
3. Click Done to close the form, and then select the Name attribute, and click Edit. 
   It is not necessary to specify a value for the name, but Entuity recommends doing so for ease of use in the Entuity UI. 
4. Click Explore Path to open the Data Explorer window for this attribute, and select the field.
   In this example, name is selected.
5. Click Done.
6. Click Add to create a new attribute, and click Data Explorer.
   In this example, the power_capacity_watts field is selected on the Data Explorer window. 
   The Name and Display Name fields are automatically populated for the attribute on the Create Attribute pane. 
   You can optionally edit the display name.
7. Specify the appropriate Data Type for the attribute you are adding:
   • String – Treated as a string of text.
   • Integer32/Integer64 – Whole number integers.
   • Float32/Float64 – Values that have potential decimal places.
   • Unsigned32/Unsigned64 – Unsigned integers.
     In this example, Usigned32 is selected.
8. In Display Format, select the unit to be used for this attribute. 
   In this example, Power in watts is selected.
   
   
9. Click Done and then click Next to go to the Summary tab. 

Summary tab

1. Review the data receiver settings, and click Save.

To verify and view the sub-object created by the receiver, navigate to the Associations dashboard of the server device the receiver was configured for.
You can now see PSU as an association with the created objects along with the attributes that you created in the data receiver populated. 

 

Example 2 – Adding sub-objects with attributes to a device

This example workflow shows the process for adding a sub-object with attributes to a custom device through the Cisco Model-Driven Telemetry (MDT) plug-in.  

Device configuration 

In this example, the device being configured is a Cisco Nexus switch running IOS-XE 17.11 or later that has support for Cisco Model-Driven Telemetry with gRPC Dial-Out capabilities.

Note, for detailed information about configuring a device to stream telemetry data, refer to the OEM documentation for the device. 

1. Log into the switch as a privileged user.

2.  Enter the following commands to enable Cisco MDT.

   N9K-C9372PX# conf t 
   N9K-C9372PX(config)# feature telemetry

3. Configure the destination to which the switch can send telemetry data by substituting this example IP address with the IP address of the Entuity server.
   For example:

   telemetry
     destination-group 1
       ip address 10.0.0.0 port 57000 protocol gRPC encoding GPB

4. Define sensor groups to retrieve the data required, in either the YANG or native DME model. Note, the sensor-group number assigned may differ depending on the device configuration if other sensor-group numbers already in use.
   In this example, the DME model is used:

   sensor-group 107
     data-source DME 
     path sys/intf/phys-[eth1/2] query-condition query-target=subtree&target-subtree-class=rmonEtherStats 
   sensor-group 108
     data-source DME 
     path sys/procsys/sysmem/sysmemfree

5. Configure subscriptions to send the sensor group data to the Entuity server, and define the time intervals for sending.  
   Note, the subscription ID is recognized as the Record Type in Entuity when the ID is received by the Entuity server. 

   subscription 107
     dst-grp 1
     snsr-grp 107 sample-interval 10000
   subscription 108 
     dst-grp 1
     snsr-grp 108 sample-interval 5000

6. Configure the Telegraf integration in Entuity by configuring the Message Broker port during the Entuity configure process. Please see this article for further help and information on how to configure Entuity. 

General tab 

After the device and Entuity server are configured (see Device configuration), messages sent to the Entuity server are displayed on the Data Sources tab of the User Defined Data Receiver page.

1. From the Entuity Main menu, go to Administration, and click User Defined Data Receiver under Polling.
   The User Defined Data Receiver page is displayed.
2. Click the Data Sources tab at the top of the User Defined Data Receiver page.
3. From the table, select the Cisco MDT data source for which you want to create a receiver, and click Create Receiver at the top of the page or via the Overflow Menu.
   This takes you to the General tab, from which you can start creating a user defined data receiver. 
4. From the General tab, enter the Receiver Name and Display Name for the receiver.
   In this example, the Receiver Name is CiscoPort and the Display Name is Cisco Port.
5. Specify the Context Type as Device.
6. Specify the Receiver Type Sub-object Creation.
   This means the data receiver will create one or more sub-components associated with the device each time a new message is received from the data source. 
   
   
    
7. If the Media Type is not automatically detected as JSON, select the JSON option from the drop-down menu.
8. Select the JSON Sanitiser Adaptor option from the Data Adaptor drop-down to format the payload into valid JSON.
9. Click Next to go to the Steps tab.

Steps tab

Create at least one step for the new data receiver:

1. Click New Object Creation Step.
2. In the Step Details column, in the Component Type field, specify the Type Name and Type Display Name and then click Done. 
   In this example, the Type Name is MDTPort and the Display Name is MDT Port. 
   
   
3. Click Next to go to the Attributes tab.

Attributes tab 

The Attributes tab for a Sub-object Creation step displays the Index and Name attributes. The Index attribute is mandatory and must always be defined to supply a unique identifier for each sub-object. The Name attribute defaults to a value based on the value of the Index attribute.

1. Select the Index attribute, and click Edit.
2. Click Explore Path to choose the field within each array that will provide the most appropriate unique identifier for each sub-object. 
   In this example, ifIndex is selected. 
   
   
    
3. Click Done to close the form.
4. Select the Name attribute, and click Edit. 
   It is not necessary to specify a value for the name, but Entuity recommends doing so for ease of use in the Entuity UI.
5. Click Explore Path to open the Data Explorer for the Name attribute.
   In this example, the dn field is selected.
6. Click Done.
7. Click Add to create a new attribute, and click Data Explorer. 
   In this example, the accessVlan field is selected from the Data Explorer window. 
   The Name and Display Name fields are automatically populated in the Create Attribute pane.
   You can optionally edit the display name. 
8. Click Done and then click Next to go to the Summary tab. 

Summary tab

1. Review the newly created data receiver settings, and click Save.

To verify and view the sub-object created by the receiver, navigate to the Associations dashboard of the device the receiver was configured for.

You can now see MDT Port as an association with the created objects along with the attributes that you created in the data receiver populated. 

Example 3 – Adding attributes to a custom device

This example workflow shows the process for adding attributes to a custom device through the gNMI (gRPC Network Management Interface) plug-in.

Device configuration

In this example, the device being configured is a Cisco Nexus switch running IOS-XE 17.11 or later that has support for gRPC Dial-Out capabilities. 

Note, for detailed information about configuring a device to stream telemetry data, refer to the OEM documentation for the device.

Note, text that is italicized within the example code text boxes are user input fields and can be substituted with different values.

1. Log into the switch as a privileged user, and enable guestshell by entering the following command.

   N9K-C9372PX# guestshell enable

2. Enter the guestshell, with the following command:

   N9K-C9372PX# run guestshell sudo su 
   [root@guestshell admin]#

3. Use the openssh of the guest shell to create a keypair, and complete the input fields, as applicable to your device, for the Country Code, State/Province, Locality, Organization Name, and so on.

   [root@guestshell admin]# openssl req -x509 -newkey rsa:2048 -keyout self_sign2048.key -out self_sign2048.pem -days 365 -nodes 
   Generating a 2048 bit RSA private key 
   ...................................................+++ 
   ...+++ 
   writing new private key to 'self_sign2048.key' 
   -----

4. List the .pem and .key files, and print each file to the terminal window so that you can obtain the private key and certificate. 

   [root@guestshell admin]# ls -l 
   -rw-rw-r-- 1 root root 1704 May 20 15:18 self_sign2048.key 
   -rw-rw-r-- 1 root root 1310 May 20 15:18 self_sign2048.pem 
   
   [root@guestshell admin]# more self_sign2048.key
   -----BEGIN PRIVATE KEY----- 
   [Private_Key] 
   -----END PRIVATE KEY----- 
   
   [root@guestshell admin]# more self_sign2048.pem 
   -----BEGIN CERTIFICATE----- 
   [Certificate] 
   -----END CERTIFICATE-----

5. Create a pfx file from the key and certificate files.

   [root@guestshell admin]# openssl pkcs12 -export -out self_sign2048.pfx -inkey self_sign2048.key -in self_sign2048.pem -certfile self_sign2048.pem -password pass:abcxyz12345 
   [root@guestshell admin]# ls 
   self_sign2048.key  self_sign2048.pem  self_sign2048.pfx

6. Copy the created pfx file to the /bootflash directory so it is available to the NX-OS CLI and then exit guestshell.

   [root@guestshell admin]# cp self_sign2048.pfx /bootflash 
   [root@guestshell admin]# exit

7. Import the pfx file that you created into the CA store on the switch, and apply the certificate to be used with gRPC.

   N9K-C9372PX# conf t 
   N9K-C9372PX(config)# 
   N9K-C9372PX(config)# crypto ca import gnmicert pkcs12 bootflash:self_sign2048.pfx abcxyz12345 
   N9K-C9372PX(config)# grpc certificate gnmicert 
   Applying grpc certificate gnmicert 
   N9K-C9372PX(config)#

8. Verify the certificate by running the show crypto ca certificates command, and confirming the new certificate is present with the Trustpoint value set to gnmicert.

   N9K-C9372PX# show crypto ca certificates 
   Trustpoint: gnmicert 
   certificate: 
   …

9. Configure the Telegraf integration in Entuity by configuring the Message Broker port during the Entuity configure process. Please see this article for further help and information on how to configure Entuity.
10. Navigate to the entuity_home/lib/telegraf/conf directory on the Entuity server, and open the telegraf-entuity-gnmi-grpc.conf file.

11. In the [[inputs.gnmi]] section of the telegraf-entuity-gnmi-grpc.conf file, remove the comment hashtag # before each line, and fill out the IP address (with the appended port of 50051), username, and password fields with the information of the configured device. Then enter the name of the newly created .pem file in the tls_ca line. 

    # gNMI telemetry input plugin 
    [[inputs.gnmi]] 
    
    addresses = ["10.0.0.0:50051"] 
    username = "username" 
    password = "password1" 
    
    tags = { inputSource="gnmi" } 
    encoding = "proto" 
    tls_enable = true 
    
    tls_ca = "./self_sign2048.pem" 
    
    insecure_skip_verify = true

12. Remove the comment hashtag # before the gNMI subscription inputs that you want to send to the Entuity server, and ensure the path matches the paths on your target device. 

    [[inputs.gnmi.subscription]] 
    origin = "device" 
    path = "/System/procsys-items/syscpusummary-items/syscpuhistory-items/SysCpuHistory-list/usageAvg" 
    name = "native_cpu_load" 
    subscription_mode = "sample" 
    sample_interval = "10s"

13. Save the telegraf-entuity-gnmi-grpc.conf file and restart Entuity. 

General tab 

After the device and Entuity server are configured (see Device configuration), messages sent to the Entuity server are displayed on the Data Sources tab of the User Defined Data Receiver page.

1. From the Entuity Main menu, go to Administration, and click User Defined Data Receiver under Polling.
   The User Defined Data Receiver page is displayed.
2. Click the Data Sources tab at the top of the User Defined Data Receiver page.
3. From the table, select the gNMI/gRPC data source for which you want to create a receiver, and click Create Receiver at the top of the page or via the Overflow Menu.
   This takes you to the General tab, from which you can start creating a user defined data receiver. 
4. From the General tab, enter the Receiver Name and Display Name for the receiver.
   In this example, the Receiver Name is HardwareModel and the Display Name is Hardware Model.
5. Specify the Context Type as the matching Custom Device.
   
   
    
6. Specify the Receiver Type as Attributes Only.
7. If the Media Type is not automatically detected as JSON, select JSON from the drop-down menu.
8. Select the JSON Sanitiser Adaptor option from the Data Adaptor drop-down to format the payload into valid JSON.
9. Click Next to go to the Steps tab.

Steps tab 

Create at least one step for the new data receiver:

1. Click New Attribute Population Step. 
2. Click Next to go to the Attributes tab.
   
   

Attributes tab 

The Attributes tab for an Attribute Population step lets you define how attributes are populated by the data receiver:

1. Click Add to create a new attribute, and click Data Explorer.
   In this example, the model field is selected from the UDReceiver_TelemetryPayload section of the Data Explorer window. 
   The Name and Display Name fields are automatically populated for the attribute on the Create Attribute pane. 
   You can optionally edit the display name.
2. Specify the appropriate Data Type for the attribute you are adding:
   • String – Treated as a string of text.
   • Integer32/Integer64 – Whole number integers.
   • Float32/Float64 – Values that have potential decimal places.
   • Unsigned32/Unsigned64 – Unsigned integers.
     In this example, String is selected.
     
     
      
3. Click Done, and then click Next to go to the Summary tab. 

Summary Tab 

1. Review the newly created data receiver settings, and click Save.

To verify and view the attribute populated by the receiver, navigate to the Associations dashboard of the device the receiver was configured for.

You can now see Hardware Model as an association with the populated Model attribute that you created in the data receiver.