Collection jobs and supported protocols | Embedded Collectors in Single VM Deployments | Cisco Crosswork Network Controller 7.2.x Administration Guide

Introduces collection jobs and supported protocols in Crosswork Network Controller, including how Embedded Collectors handle internal and external data requests, execute CLI-, SNMP-, syslog-, and gNMI-based jobs, and forward collected data to Cisco Crosswork and external destinations.

A data collection process is a mechanism that

enables applications to request network data through collection jobs
allows the Crosswork Network Controller to assign these jobs to an appropriate collector, and
ensures that the collector initiates and performs data collection based on the type of data requested.

The Embedded Collector collects data using supported protocols such as CLI, SNMP, gNMI (dial-in), and syslog. It can collect any type of data if it is able to forward it through one of these supported protocols. Embedded Collectors offer flexibility in data collection by supporting multiple protocols. This capability ensures compatibility with diverse data types and network devices.

Types of collection jobs

There are two types of data collection requests in Crosswork Network Controller:

A data collection request forwards data for internal processes within Cisco Crosswork. Cisco Crosswork creates system jobs for this purpose. If you want the Embedded Collectors to collect specific information from non-Cisco devices, you must use custom device packages. For more information about custom device packages, see Custom packages.

To learn how to build a model that enables Crosswork to communicate with non-Crosswork devices, see Cisco Devnet.
Data collection request to forward data to an external data destination. For more information about configuring the external data destinations (Kafka or gRPC), see Data destinations in Embedded Collectors.

Supported types of collection jobs

CLI-based collection
SNMP-based collection
Syslog-based collection
gNMI-based collection

For each collection job you create, Embedded Collectors execute the collection request and forward the data to both internal and external destinations. A single collection request allows you to send the collected data to the Crosswork Network Controller and to an external data destination.

You can create collection jobs from the Cisco Crosswork Network Controller UI. You can also use APIs to create jobs, see Cisco DevNet. For example, you may create an SNMP-based collection job to regularly retrieve interface statistics from a device and deliver data to both the controller and an external monitoring server.

How collection job state transitions work

Collection jobs progress through distinct status stages, beginning with creation and ending with execution in the Crosswork system.

Summary

Collection jobs transition through distinct status stages as they move from creation to execution within the Crosswork system.

The key components involved in the process are:

Collection job: the request that is created to collect data.
Embedded Collector: the collector that validates and executes jobs.
Crosswork Network Controller UI: the management interface where users monitor job status.

Workflow

The process involves these stages:

Initially, every collection job appears in the UI with the status Unknown.
The Embedded Collector receives the collection job and performs basic validation checks.
If the job passes validation, its status changes to Successful.
If the job fails validation, its status changes to Failed.

Result

Users can track and manage the lifecycle of collection jobs. They can quickly see whether their jobs have succeeded, failed, or are waiting to be processed.

Status changes in event-based collection jobs

These scenarios illustrate how status changes appear in event-based collection jobs.

When data collection is successful, the status of the collection job changes from Unknown to Success in the Collection Jobs pane.
When a device is detached from Embedded Collectors, all corresponding collection jobs are deleted, and the job status is displayed as Success in the Collection Jobs pane. No devices or collection tasks are displayed in the Job Details pane.
When a device is attached to an Embedded Collector, Crosswork receives a new collection job with the status set to Unknown, which changes to Success after events are received from the device.
If the device configuration is updated incorrectly on an already attached device (and Embedded Collectors has received the job and events), there is no change in the status of the collection task in the Jobs Details pane.
If device inventory is updated with an incorrect device IP, the collection task status in the Jobs Details pane remains Unknown.

CLI collection jobs

A CLI collection job in the Embedded Collectors is a data collection method that

uses command-line interface (CLI) commands to retrieve operational or configuration data from network devices,
enables collection of real-time information when devices do not support other protocols such as SNMP or gNMI, and
supports troubleshooting and monitoring by ensuring critical data is available.

Best practice for devices with banner configurations

If a banner configuration is currently enabled on your device, refer to the device's official documentation for instructions on how to disable it.

How CLI jobs collect data

Summary

CLI collection jobs automate data collection from devices. They reference designated destinations and device identifiers using the CLI protocol.

Workflow

The key steps for configuring a CLI collection job are:

Configure a data destination: To create a custom CLI collection job, configure a data destination. Each destination receives a unique UUID, which is required as destination_id in API payloads. You can create a destination using Data Collectors > Data Destinations.
Identify the device. The device uses a UUID instead of an IP address for identification.
For jobs built using the UI, Crosswork Network Controller automatically retrieves required UUIDs. For custom jobs, retrieve UUIDs manually.

Result

Setting up a CLI collection job with correctly referenced destinations and devices enables streamlined and accurate CLI-based data collection in the network management system.

Cadence for data collection

Cadence is a configuration parameter that

determines how frequently the Embedded Collectors collect data from each device
accepts a range between 10 and 604,800,000 milliseconds, and
allows the user to tailor the data collection rate to operational needs.

For example, a cadence value of 60,000 milliseconds (1 minute) means data will be retrieved every minute. The minimum recommended cadence is 60 milliseconds. Select an appropriate cadence to balance data granularity with system and network performance.

Best practice for setting data collection cadence

Set a minimum cadence of 60 milliseconds for most data collection jobs.
Use a higher cadence (slower rate) for collecting consistent data, such as memory consumption or CPU utilization.
Use a shorter cadence (faster rate) to collect data points that are more dynamic and fast-changing.
High-frequency collection can increase the load on both devices and the Crosswork Network Controller. Consider this impact when choosing a cadence.
Experiment with different cadence values to find the optimal balance between actionable insight and system performance.

Considerations for skipped collection attempts

When a collection attempt is skipped because a previous execution is still in progress, Embedded Collectors issue a warning log. However, the system does not generate an alert for this scenario. This behavior prevents overlapping data collection processes and helps maintain operational efficiency.

Sample payload of CLI collection job

A sample payload is a structured example that demonstrates how device data can be sent to an external system using a defined schema. It clarifies the usage of system-assigned identifiers such as UUIDs and provides a template for integrating Crosswork jobs with external Kafka destinations.

The sample payload includes the structure and values used when Crosswork sends device data to an external Kafka destination. It uses the UUID assigned by the Device Lifecycle Manager..

For detailed information about the API payload fields and usage examples, see the API documentation on Cisco Devnet.

{
  "collection_job": {
    "application_context": {
      "context_id": "collection-job1",
      "application_id": "APP1"
    },
    "collection_mode": {
      "lifetime_type": "APPLICATION_MANAGED",
      "collector_type": "CLI_COLLECTOR"
    },
    "job_device_set": {
      "device_set": {
        "devices": {
          "device_ids": [
            "658adb03-cc61-448d-972f-4fcec32cbfe8"
          ]
        }
      }
    },
    "sensor_input_configs": [
      {
        "sensor_data": {
          "cli_sensor": {
            "command": "show platform"
          }
        },
        "cadence_in_millisec": "60000"
      }
    ],
    "sensor_output_configs": [
     {
        "sensor_data": {
          "cli_sensor": {
            "command": "show platform"
          }
        },
        "destination": {
          "destination_id": "1e71f2fb-ea65-4242-8efa-e33cec71b369",
          "context_id": "topic1"
        }
      }
    ]
  }
}

SNMP collection jobs

An SNMP-based data collection job is a process that collects device data using SNMP through Embedded Collectors configured via the UI or API. It retrieves data based on the device’s Management Information Base (MIB) and associated Object Identifiers (OIDs). This collection can be configured in two ways:

MIB-based polling, which gathers data according to the device’s supported MIB and OID definitions, and
Trap-based listening, which collects SNMP traps by configuring the collector to listen for incoming trap messages.

Standard MIBs included with Crosswork enable collection of common device attributes. Custom or vendor-specific MIB packages can be uploaded for specialized devices.

Supported SNMP versions for polling and traps include SNMP v2 and SNMP v3. These versions offer various authentication protocols (such as HMAC_MD5 and HMAC_SHA variants) and privacy protocols (such as AES, DES, 3-DES, and Cisco-specific AES). This approach enables a flexible and secure collection of network device data for monitoring and management.

Supported SNMP versions and operations

Supported SNMP versions for data polling and traps are

Polling data

SNMP V2
SNMP V3 (no auth nopriv, auth no priv, authpriv)
Supported auth protocols: HMAC_MD5, HMAC_SHA, HMAC_SHA2-512, HMAC_SHA2_384, HMAC_SHA2_256, and HMAC_SHA2_224
Supported priv protocols: AES-128, AES-192, AES-256, CiscoAES192, CiscoAES256, DES, and 3-DES

Traps

SNMP V2
SNMP V3 (no auth nopriv, auth no priv, authpriv)

Sample SNMP device configuration commands

This table lists sample SNMP configuration commands for enabling polling and traps on V2 and V3 devices, including IP address, port notes, and authentication or naming requirements.

Table 1. Sample configuration to enable SNMP on device
Version	Command	Purpose
V2c	`snmp-server group <group_name> v2c` `snmp-server user <user_name> <group_name> v2c`	Defines the SNMP version, user or user group details.
	`snmp-server host <host_ip> traps SNMP version <community_string> udp-port 31062` `snmp-server host a.b.c.d traps version 2c v2test udp-port 31062`	Defines the destination to which trap data must be forwarded. Note The IP address must be the Data VIP address of the Embedded Collectors.
	`snmp-server traps snmp linkup` `snmp-server traps snmp linkdown`	Enables traps that notify about link status.
V3 Note Password for a SNMPv3 user must be at least 8 bytes.	`snmp-server host <host_IP> traps version 3 priv <user_name> udp-port 31062`	Defines the destination to which trap data must be forwarded. Note The IP address must be the Data VIP address of the Embedded Collectors.
	`snmp-server user <user_name> <group_name> v3 auth md5 <password> priv aes 128 <password>`	Configures the SNMP server group and enables authentication for specified members in a named access list.
	`snmp-server view <user_name> < MIB > included`	Specifies the information that must be reported.
	`snmp-server group <group_name> v3 auth notify <user_name> read <user_name> write <user_name>`	Defines the SNMP version, user, or user group details.
	`snmp-server enable traps snmp [authentication ] [linkup ] [linkdown ] [warmstart ] [coldstart ]`	When you use this command without any optional keywords, it enables authenticationFailure, linkUp, linkDown, warmStart, and coldStart traps. When you include keywords with this command, it enables only the specified trap types. For instance, to enable only linkUp and linkDown SNMP traps for all interfaces, use the snmp-server enable traps snmp linkup linkdown command.

SNMP collector supported operations

SCALAR
TABLE
WALK
COLUMN

Notes for supported operations

If a single collection requests for multiple scalar OIDs, you can pack multiple SNMP GET requests in a single getbulkrequestquery to the device.
For TABLE operations, you can provide either a Table OID or a Column OID.
There is an optional deviceParams attribute snmpRequestTimeoutMillis (not shown in the sample payloads) that should be used if the device response time is more than 1500 milliseconds.
- Use snmpRequestTimeoutMillis unless you are certain that your device response time is high.
- The value for snmpRequestTimeoutMillis should be specified in milliseconds:
- The default and minimum value is 1500 milliseconds. There is no maximum value for this attribute.

SNMP collection job example

{
  "collection_job": {
    "application_context": {
      "context_id": "collection-job1",
      "application_id": "APP1"
    },
    "collection_mode": {
      "lifetime_type": "APPLICATION_MANAGED",
      "collector_type": "SNMP_COLLECTOR"
    },
    "job_device_set": {
      "device_set": {
        "devices": {
          "device_ids": [
            "c70fc034-0cbd-443f-ad3d-a30d4319f937",
            "8627c130-9127-4ed7-ace5-93d3b4321d5e",
            "c0067069-c8f6-4183-9e67-1f2e9bf56f58"
          ]
        }
      }
    },
    "sensor_input_configs": [
      {
        "sensor_data": {
          "snmp_sensor": {
            "snmp_mib": {
              "oid": "1.3.6.1.2.1.1.3.0",
              "snmp_operation": "SCALAR"
            }
          }
        },
        "cadence_in_millisec": "60000"
      },
      {
        "sensor_data": {
          "snmp_sensor": {
            "snmp_mib": {
              "oid": "1.3.6.1.2.1.31.1.1",
              "snmp_operation": "TABLE"
            }
          }
        },
        "cadence_in_millisec": "60000"
      }
    ],
    "sensor_output_configs": [
      {
        "sensor_data": {
          "snmp_sensor": {
            "snmp_mib": {
              "oid": "1.3.6.1.2.1.1.3.0",
              "snmp_operation": "SCALAR"
            }
          }
        },
        "destination": {
          "destination_id": "4c2ab662-2670-4b3c-b7d3-b94acba98c56",
          "context_id": "topic1_461cb8aa-a16a-44b8-b79f-c3daf3ea925f"
        }
      },
      {
        "sensor_data": {
          "snmp_sensor": {
            "snmp_mib": {
              "oid": "1.3.6.1.2.1.31.1.1",
              "snmp_operation": "TABLE"
            }
          }
        },
        "destination": {
          "destination_id": "4c2ab662-2670-4b3c-b7d3-b94acba98c56",
          "context_id": "topic2_e7ed6300-fc8c-47ee-8445-70e543057f8a"
        }
      }
    ]
  }
}

SNMP traps collection job

SNMP trap collection jobs are created only through the API. Trap listeners monitor specific ports and dispatch data to recipients according to their topics of interest.

How SNMP trap collection jobs work

When the Embedded Collector receives an SNMP trap, it performs these actions:

Checks if any collection job is created for the device.
Checks the trap version and community string.

Note

To prevent Embedded Collectors from checking the community string for SNMP traps, select the SNMP Disable Trap Check check box when adding a device through the Crosswork Network Controller UI. For more information about this option, see Add devices individually through the UI in Cisco Crosswork Network Controller 7.2.x Device Lifecycle Management .
For SNMP v3, the system also validates the user authentication protocol, privacy protocol, and credentials.

Note
SNMPv3 authentication and privacy traps depend on the engineId of the device or router to maintain the local USM user tables. If the engineId changes, trap collection is interrupted. To restore trap reception, detach the respective device and then reattach it.

Best practice for enabling SNMP traps

Before starting the SNMP trap collection, install the Common EMS Services application and configure the host information for SNMP.
Embedded Collectors listen on UDP port 31062 for traps.
Before submitting SNMP trap collection jobs, ensure that SNMP traps are properly configured on the device and directed to the Data VIP address of the Embedded Collector.

Types of SNMP trap filters

Embedded Collectors filter traps using the trap OID specified in the sensor path and send only the requested traps. The job can remain in the Unknown state in these scenarios:

If the collection job is invalid, the status of the job remains "Unknown."
If configuration is missing on the device, the status of the job remains "Unknown."
If no trap is received, the status of the job remains "Unknown."

For a list of supported traps and MIBs, refer to List of Pre-loaded YANG Modules for MDT Collection

Table 2. List of Supported Non-Yang/OID based Traps
Sensor path	Purpose
*	To get all the traps pushed from the device without any filter.
MIB level traps	OID of one MIB notification (Ex: 1.3.6.1.2.1.138.0 to get all the isis-mib level traps)
Specific trap	OID of the specific trap (Ex: 1.3.6.1.6.3.1.1.5.4 to get the linkUp trap)

Sample payload of SNMP collection job

In this example, Crosswork sends an SNMP trap collection job to receive SNMP traps from network devices.

For detailed information about the API payload fields and usage examples, see the API documentation on Cisco Devnet.

{
  "collection_job": {
    "application_context": {
      "context_id": "collection-job1",
      "application_id": "APP1"
    },
    "collection_mode": {
      "lifetime_type": "APPLICATION_MANAGED",
      "collector_type": "TRAP_COLLECTOR"
    },
    "job_device_set": {
      "device_set": {
        "devices": {
          "device_ids": [
            "a9b8f43d-130b-4866-a26a-4d0f9e07562a",
            "8c4431a0-f21d-452d-95a8-84323a19e0d6",
            "eaab2647-2351-40ae-bf94-6e4a3d79af3a"
          ]
        }
      }
    },
    "sensor_input_configs": [
      {
        "sensor_data": {
          "trap_sensor": {
            "path": "1.3.6.1.6.3.1.1.4"
          }
        },
        "cadence_in_millisec": "60000"
      }
    ],
    "sensor_output_configs": [
      {
        "sensor_data": {
          "trap_sensor": {
            "path": "1.3.6.1.6.3.1.1.4"
          }
        },
        "destination": {
          "destination_id": "4c2ab662-2670-4b3c-b7d3-b94acba98c56",
          "context_id": "topic1_696600ae-80ee-4a02-96cb-3a01a2415324"
        }
      }
    ]
  }
}

Enabling trap forwarding with OID identification

To identify the type of trap from the data received at the destination, look for the oid (OBJECT_IDENTIFIER, for example, 1.3.6.1.6.3.1.1.4.1.0 ) and strValue associated to the oid in the OidRecords (application can match the OID of interest to determine the kind of trap).

These are the sample values used in the payload to forward traps to external applications:

Link up

1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.6.3.1.1.5.4
Link down

1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.6.3.1.1.5.3
Syslog

1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.4.1.9.9.41.2.0.1
Cold start

1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.6.3.1.1.5.1

Sample payload to forward traps to external applications

{
  "nodeIdStr": "BF5-XRV9K1.tr3.es",
  "nodeIdUuid": "C9tZ5lJoSJKf5OZ67+U5JQ==",
  "collectionId": "133",
  "collectionStartTime": "1580931985267",
  "msgTimestamp": "1580931985267",
  "dataGpbkv": [
    {
      "timestamp": "1580931985267",
      "name": "trapsensor.path",
      "snmpTrap": {
        "version": "V2c",
        "pduType": "TRAP",
        "v2v3Data": {
          "agentAddress": "172.70.39.227",
          "oidRecords": [
            {
              "oid": "1.3.6.1.2.1.1.3.0",
              "strValue": "7 days, 2:15:17.02"
            },
            {
              "oid": "1.3.6.1.6.3.1.1.4.1.0",  // This oid is the Object Identifier.
              "strValue": "1.3.6.1.6.3.1.1.5.3" // This is the value that determines the kind of trap.
            },
            {
              "oid": "1.3.6.1.2.1.2.2.1.1.8",
              "strValue": "8"
            },
            {
              "oid": "1.3.6.1.2.1.2.2.1.2.8",
              "strValue": "GigabitEthernet0/0/0/2"
            },
            {
              "oid": "1.3.6.1.2.1.2.2.1.3.8",
              "strValue": "6"
            },
            {
              "oid": "1.3.6.1.4.1.9.9.276.1.1.2.1.3.8",
              "strValue": "down"
            }
          ]
        }
      }
    }
  ],
  "collectionEndTime": "1580931985267",
  "collectorUuid": "YmNjZjEzMTktZjFlOS00NTE5LWI4OTgtY2Y1ZmQxZDFjNWExOlRSQVBfQ09MTEVDVE9S",
  "status": {
    "status": "SUCCESS"
  },
  "modelData": {},
  "sensorData": {
    "trapSensor": {
      "path": "1.3.6.1.6.3.1.1.5.4"
    }
  },
  "applicationContexts": [
    {
      "applicationId": "APP1",
      "contextId": "collection-job-snmp-traps"
    }
  ]
}

Syslog collection jobs

A Syslog collection job is a data collection process that

uses Embedded Collectors to gather Syslog-based events from network devices in RFC 5424 and RFC 3164 formats
employs SyslogSensors to filter events based on severity, facility, and regular expressions, and
applies logical operators to customize filtering, reducing noise and optimizing the volume of collected Syslog data.

Supported Syslog formats

Embedded Collectors support the collection of Syslog-based events from network devices. The collectors support these Syslog message formats:

RFC 5424
RFC 3164

The supported Syslog formats are:

RFC5424 Syslog format
RFC3164 Syslog format

Filtering the Syslog events

A Syslog event filter is a configuration mechanism that:

manages and controls the volume of Syslog data collected from devices through SyslogSensors
supports PRI-based and filter-based rules that help capture relevant Syslog events for network monitoring and analysis, and
applies filters based on severity, facility, or regular expressions to forward only required events, thereby reducing noise, optimizing storage, and streamlining downstream processing.

Syslog filters allow the use of logical operators such as AND and OR to define up to three filter combinations. This approach provides flexibility in how filters are evaluated.

Configure syslog data collection for Embedded Collectors

Enable syslog data collection from network devices using Embedded Collectors.

Use this procedure to configure the Embedded Collectors to receive syslog event data and forward it for monitoring and analysis with Crosswork.

Before you begin

Confirm the devices to be monitored are reachable and support the necessary capabilities.

Use these steps to configure syslog data collection.

Procedure

	1.	Install the Element Management Functions application and configure the host information for syslog. For additional details, refer to the Cisco Crosswork Network Controller 7.2.x Installation Guide.
	2.	Add the device and select the `YANG_CLI` capability.
	3.	Configure the required parameters to enable syslog data collection from Embedded Collectors. Note The order of the steps does not affect the outcome. However, steps 2 and 3 are required; skipping either will prevent syslog data collection. Additional information: For example configurations, refer to Sample syslog configuration for single VM deployment Sample device configuration for single VM deployment Review your platform-specific documentation to obtain configuration guidance.

Syslog data from selected devices is collected and made available in Crosswork via the Embedded Collectors.

Sample syslog collection payload

In this example, Crosswork sends a syslog-trap collection job to receive syslog messages sent from network devices. For detailed information about the API payload fields and usage examples, see the API documentation on Cisco Devnet.

{
  "collection_job": {
      "job_device_set": {
      "device_set": {
        "devices": {
          "device_ids": [
            "c6f25a33-92e6-468a-ba0d-15490f1ce787"
          ]
        }
      }
    },
    "sensor_output_configs": [
      {
        "sensor_data": {
          "syslog_sensor": {
            "pris": {
                "facilities": [0, 1, 3, 23,4],
                "severities": [0, 4, 5, 6, 7]
            }
        }
        },
        "destination": {
          "context_id": "syslogtopic",
          "destination_id": "c2a8fba8-8363-3d22-b0c2-a9e449693fae"
        }
      }
    ],
    "sensor_input_configs": [
      {
        "sensor_data": {
          "syslog_sensor": {
            "pris": {
                "facilities": [0,1, 3, 23,4],
                "severities": [0,4, 5, 6, 7]
            }
        }
        },
        "cadence_in_millisec": "60000"
      }
    ],
    "application_context": {
      "context_id": "demomilesstone2syslog",
      "application_id": "SyslogDemo2"
    },
    "collection_mode": {
      "lifetime_type": "APPLICATION_MANAGED",
      "collector_type": "SYSLOG_COLLECTOR"
    }
  }
}

Syslog collection job outputs

A Syslog collection job output is a record generated by the Syslog collector that:

reflects the format configuration for the onboarded device
contains Syslog events received from the device in the specified format, and
is used to monitor and audit Syslog messages in Crosswork Network Controller.

When onboarding a network device, you must select the appropriate Syslog Format. The chosen format determines whether Syslog events are parsed and displayed as UNKNOWN, RFC5424, or RFC3164.

Syslog collection job output formats (Reference)

UNKNOWN: Syslog Collection Job output contains Syslog events as received from device.

Note

If the device is configured to generate Syslog events in RFC5424/RFC3164 format but no format is specified in the Syslog Format field, this is considered as UNKNOWN by default.

Sample output:

node_id_str: "xrv9k-VM8"
node_id_uuid: ":i\300\216>\366BM\262\270@\337\225\2723&"
collection_id: 1056
collection_start_time: 1616711596200
msg_timestamp: 1616711596201
data_gpbkv {
  timestamp: 1616711596201
  name: "syslogsensor.path"
  fields {
    name: "RAW"
    string_value: "<6>1 Mar 25 15:34:41.321 PDT - SSHD_ 69570 - - 98949: RP/0/RP0/CPU0:SSHD_[69570]: %SECURITY-SSHD-6-INFO_SUCCESS : Successfully authenticated user \'admin\' from \'40.40.40.116\' on \'vty0\'(cipher \'aes128-ctr\', mac \'hmac-sha1\') \n"
  }
  fields {
    name: "DEVICE_IP"
    string_value: "40.40.40.30"
  }
}
collection_end_time: 1616711596200
collector_uuid: "17328736-b726-4fe3-b922-231a4a30a54f:SYSLOG_COLLECTOR"
status {
  status: SUCCESS
}
model_data {
}
sensor_data {
  syslog_sensor {
    pris {
      facilities: 0
      facilities: 3
      facilities: 4
      facilities: 23
      severities: 0
      severities: 5
      severities: 6
      severities: 7
    }
  }
}
application_contexts {
  application_id: "SyslogApp-xr-8-job1"
  context_id: "xr-8-job1"
}
version: "1"

RFC5424: If the device is configured to generate Syslog events in RFC5424 format and the RFC5424 format is selected in the Syslog Format field, the Syslog Job Collection output contains Syslog events as received from device (RAW) and the RFC5424 best-effort parsed Syslog events from the device.

Note

The Syslog collector will parse the Syslog event on best efforts as per the following Java RegEx pattern:

Sample output:

....
....
 
 
collection_start_time: 1596307542398
msg_timestamp: 1596307542405
data_gpbkv {
  timestamp: 1596307542405
  name: "syslogsensor.path"
  fields {
    name: "RAW"
    string_value: "<13>1 2020 Aug  1 12:03:32.461 UTC:  iosxr254node config 65910 - - 2782: RP/0/RSP0/CPU0:2020 Aug  1 12:03:32.461 UTC: config[65910]: %MGBL-SYS-5-CONFIG_I : Configured from console by admin on vty0 (10.24.88.215) \n"
  }
  fields {
    name: "RFC5424"
    string_value: "pri=13,  severity=5,  facility=1,  version=1,  date=2020-08-01T12:03:32.461,  remoteAddress=/172.28.122.254,  host=\'iosxr254node\',  message=\'2782: RP/0/RSP0/CPU0:2020 Aug  1 12:03:32.461 UTC: config[65910]: %MGBL-SYS-5-CONFIG_I : Configured from console by admin on vty0 (10.24.88.215) \', messageId=null, processName=config, structuredDataList=null"
  }
  fields {
    name: "DEVICE_IP"
    string_value: "172.28.122.254"
  }
}
collection_end_time: 1596307542404
collector_uuid: "ac961b09-8f67-4c93-a99a-31eef50f7fa9:SYSLOG_COLLECTOR"
status {
  status: SUCCESS
}
...
...

RFC3164: If the device is configured to generate Syslog events in RFC3164 format and the RFC3164 format is selected in Syslog Format field, the Syslog Job Collection output contains both RAW (as received from device) Syslog events and the RFC3164 best-effort parsed Syslog events from the device.

Note

The Syslog collector will parse the Syslog event on best efforts as per the following Java RegEx pattern:

Sample output:

....
.....
collection_id: 20
collection_start_time: 1596306752737
msg_timestamp: 1596306752743
data_gpbkv {
  timestamp: 1596306752743
  name: "syslogsensor.path"
  fields {
    name: "RAW"
    string_value: "<14>2020 Aug  1 11:50:22.799 UTC:  iosxr254node 2756: RP/0/RSP0/CPU0:2020 Aug  1 11:50:22.799 UTC: config[65910]: %MGBL-CONFIG-6-DB_COMMIT : Configuration committed by user \'admin\'. Use \'show configuration commit changes 1000000580\' to view the changes. \n"
  }
  fields {
    name: "RFC3164"
    string_value: "pri=14,  severity=6,  facility=1,  version=null,  date=2020-08-01T11:50:22.799,  remoteAddress=/172.28.122.254,  host=\'iosxr254node\',  message=\'RP/0/RSP0/CPU0:2020 Aug  1 11:50:22.799 UTC: config[65910]: %MGBL-CONFIG-6-DB_COMMIT : Configuration committed by user \'admin\'. Use \'show configuration commit changes 1000000580\' to view the changes. \', tag=2756"
  }
  fields {
    name: "DEVICE_IP"
    string_value: "172.28.122.254"
  }
}
collection_end_time: 1596306752742
collector_uuid: "ac961b09-8f67-4c93-a99a-31eef50f7fa9:SYSLOG_COLLECTOR"
status {
  status: SUCCESS
}
....
....

Warning

If the Syslog collector is unable to parse the Syslog events according to the format specified in the Syslog Format field, then the Syslog Collection Job output contains Syslog events as received from device (RAW).

Device configuration for non-secure Syslog

This section presents configurations for non-secure Syslog operation in Cisco IOS XR and IOS XE platforms, supporting both RFC3164 and RFC5424 message formats. Use the configurations below to achieve correct syslog parsing and message delivery.

Configure RFC3164 syslog format

For IOS XR:

logging <Data IP> port 30514 OR logging <Data IP> vrf <vrfname> port 30514 
logging trap [severity]
logging facility [facility value]
logging suppress duplicates
service timestamps log datetime msec show-timezone year
logging hostnameprefix <some host related prefix e.g.iosxrhost2>

Note

Ensure “service timestamps log…” and “logging hostnameprefix…” are present.

For IOS XE:

no logging message-counter syslog 
logging trap <severity>
logging facility <facility>
logging host <Data IP> transport tcp port 309898 session-id string <sessionidstring> --> To use TCP channel
OR
logging host <Data IP> transport udp port 30514 session-id string <sessionidstring> ---> To use UDP channel
OR
logging host <Data IP> vrf Mgmt-intf transport udp port 30514 session-id string <sessionidstring> --> To use UDP via vrf 
service timestamps log datetime msec year show-timezone

Note

TCP transports require explicit configuration as shown.

Configure RFC5424 syslog format

For IOS XR:

logging <Data IP> port 30514 OR logging <server 1> vrf <vrfname> port 30514 
logging trap [severity]
logging facility [facility value]
logging suppress duplicates
service timestamps log datetime msec show-timezone year
logging hostnameprefix <some host related prefix e.g.iosxrhost2>
logging format rfc5424

Note

Ensure “service timestamps log…” and “logging hostnameprefix…” are present.

For IOS XE:

no logging message-counter syslog
logging trap <severity>
logging facility <facility>
logging host <Data IP> transport tcp port 309898 session-id string <sessionidstring> --> To use TCP channel
OR
logging host <Data IP> transport udp port 30514 session-id string <sessionidstring> ---> To use UDP channel
OR
logging host <Data IP> vrf Mgmt-intf transport udp port 30514 session-id string <sessionidstring> --> To use UDP via vrf 
service timestamps log datetime msec year show-timezone
logging trap syslog-format 5424 --> if applicable

Note

TCP transports require explicit configuration as shown.

Device configuration for secure Syslog

This section presents configurations for secure Syslog operation in Cisco IOS XR and IOS XE platforms, supporting both RFC3164 and RFC5424 message formats. Use the configurations below to achieve correct syslog parsing and message delivery.

Use the steps to establish a secured syslog communication with the device.

Download the Cisco Crosswork trust chain from the Certificate Management UI page in Cisco Crosswork. See Download syslog certificates.
Configure the device with the Cisco Crosswork trustchain. See Configure a Crosswork trustpoint on a device.

Download syslog certificates

Provide users with the ability to download syslog certificates from the Crosswork Network Controller UI.

This task helps administrators securely export device syslog certificates for system integration, troubleshooting, or compliance requirements.

Procedure

	1.	In the Crosswork Network Controller UI, go to Administration > Certificate Management.
	2.	Click the icon in the Crosswork-Device-Syslog row.
	3.	Click Export All to download the certificates. The intermediate.crt and ca.crt are downloaded to your system. Figure 1. Certificate files that are downloaded

The files are downloaded to your system.

Configure a Crosswork trustpoint on a device

This procedure enables secure, trusted communication (TLS/PKI) between a Cisco device (IOS XR or IOS XE) and Crosswork applications using trustpoints.

When integrating network devices with Cisco Crosswork monitoring for authenticated, encrypted syslog export.

Procedure

Enable TLS by configuring the IOS XR or XE device (refer to these samples):

For IOS XR:

RP/0/RSP0/CPU0:ASR9k(config)#crypto ca trustpoint syslog-root
RP/0/RSP0/CPU0:ASR9k(config-trustp)#enrollment terminal
RP/0/RSP0/CPU0:ASR9k(config-trustp)#crl optional
RP/0/RSP0/CPU0:ASR9k(config-trustp)#commit
RP/0/RSP0/CPU0:ASR9k(config-trustp)#end
RP/0/RSP0/CPU0:ASR9k#
RP/0/RSP0/CPU0:ASR9k#crypto ca authenticate syslog-root
Fri Jan 22 11:07:41.880 GMT
  
  
Enter the base 64 encoded certificate.
End with a blank line or the word "quit" on a line by itself
  
-----BEGIN CERTIFICATE-----
MIIGKzCCBBOgAwIBAgIRAKfyU89yjmrXVDRKBWuSGPgwDQYJKoZIhvcNAQELBQAw
bDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMREwDwYDVQQHEwhTYW4gSm9zZTEa
................................................................
................................................................
jPQ/UrO8N3sC1gGJX7CIIh5cE+KIJ51ep8i1eKSJ5wHWRTmv342MnG2StgOTtaFF
vrkWHD02o6jRuYXDWEUptDOg8oEritZb+SNPXWUc/2mbYog6ks6EeMC69VjkZPo=
-----END CERTIFICATE-----
  
Read 1583 bytes as CA certificate
  Serial Number  : A7:F2:53:CF:72:8E:6A:D7:54:34:4A:05:6B:92:18:F8
  Subject:
                CN=Crosswork Device Root CA,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Issued By      :
                CN=Crosswork Device Root CA,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Validity Start : 02:37:09 UTC Sat Jan 16 2021
  Validity End   : 02:37:09 UTC Thu Jan 15 2026
  SHA1 Fingerprint:
                209B3815271C22ADF78CB906F6A32DD9D97BBDBA
  
Fingerprint: 2FF85849EBAAB9B059ACB9F5363D5C9CDo you accept this certificate? [yes/no]: yes
RP/0/RSP0/CPU0:ASR9k#config
RP/0/RSP0/CPU0:ASR9k(config)#crypto ca trustpoint syslog-inter
RP/0/RSP0/CPU0:ASR9k(config-trustp)#enrollment terminal
RP/0/RSP0/CPU0:ASR9k(config-trustp)#crl optional
RP/0/RSP0/CPU0:ASR9k(config-trustp)#commit
RP/0/RSP0/CPU0:ASR9k#crypto ca authenticate syslog-inter
Fri Jan 22 11:10:30.090 GMT
  
  
Enter the base 64 encoded certificate.
End with a blank line or the word "quit" on a line by itself
  
-----BEGIN CERTIFICATE-----
MIIGFDCCA/ygAwIBAgIRAkhqHQXcJzQzeQK6U2wn8PIwDQYJKoZIhvcNAQELBQAw
bDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMREwDwYDVQQHEwhTYW4gSm9zZTEa
................................................................
................................................................
5lBk617z6cxFER5c+/PmJFhcreisTxXg1aJbFdnB5C8f+0uUIdLghykQ/zaZGuBn
AAB70c9r9OeKGJWzvv1e2U8HH1pdQ/nd
-----END CERTIFICATE-----
  
Read 1560 bytes as CA certificate
  Serial Number  : 02:48:6A:1D:05:DC:27:34:33:79:02:BA:53:6C:27:F0:F2
  Subject:
                CN=device-syslog,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Issued By      :
                CN=Crosswork Device Root CA,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Validity Start : 02:37:11 UTC Sat Jan 16 2021
  Validity End   : 02:37:11 UTC Mon Jan 16 2023
  SHA1 Fingerprint:
                B06F2BFDE95413A8D08A01EE3511BC3D42F01E59
  
CA Certificate validated using issuer certificate.
RP/0/RSP0/CPU0:ASR9k#show crypto ca certificates
Fri Jan 22 15:45:17.196 GMT
 
 
Trustpoint       : syslog-root
==================================================
CA certificate
  Serial Number  : A7:F2:53:CF:72:8E:6A:D7:54:34:4A:05:6B:92:18:F8
  Subject:
        CN=Crosswork Device Root CA,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Issued By      :
        CN=Crosswork Device Root CA,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Validity Start : 02:37:09 UTC Sat Jan 16 2021
  Validity End   : 02:37:09 UTC Thu Jan 15 2026
  SHA1 Fingerprint:
         209B3815271C22ADF78CB906F6A32DD9D97BBDBA
 
 
Trustpoint       : syslog-inter
==================================================
CA certificate
  Serial Number  : 02:48:6A:1D:05:DC:27:34:33:79:02:BA:53:6C:27:F0:F2
  Subject:
        CN=device-syslog,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Issued By      :
        CN=Crosswork Device Root CA,O=CISCO SYSTEMS INC,L=San Jose,ST=CA,C=US
  Validity Start : 02:37:11 UTC Sat Jan 16 2021
  Validity End   : 02:37:11 UTC Mon Jan 16 2023
  SHA1 Fingerprint:
         B06F2BFDE95413A8D08A01EE3511BC3D42F01E59
RP/0/RSP0/CPU0:ASR9k(config)#logging tls-server syslog-tb131
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#tls-hostname <Device Southbound IP>
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#trustpoint syslog-inter
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#severity debugging
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#vrf default
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#commit
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#exit
RP/0/RSP0/CPU0:ASR9k(config)#exit
RP/0/RSP0/CPU0:ASR9k#exit
RP/0/RSP0/CPU0:ASR9k#show running-config logging
Fri Jan 22 11:17:19.385 GMT
logging tls-server syslog-tb131
vrf default
severity debugging
trustpoint syslog-inter
tls-hostname <Device Southbound IP>
!
logging trap debugging
logging format rfc5424
logging facility user
logging hostnameprefix ASR9k
logging suppress duplicates
  
RP/0/RSP0/CPU0:ASR9k#

For IOS XE:

csr8kv(config)#crypto pki trustpoint syslog-root
csr8kv(ca-trustpoint)#enrollment terminal
csr8kv(ca-trustpoint)#revocation-check none
csr8kv(ca-trustpoint)#chain-validation stop
csr8kv(ca-trustpoint)#end
csr8kv(config)#crypto pki authenticate syslog-root
 
Enter the base 64 encoded CA certificate.
End with a blank line or the word "quit" on a line by itself
 
-----BEGIN CERTIFICATE-----
MIIFPjCCAyYCCQCO6pK5AOGYdjANBgkqhkiG9w0BAQsFADBhMQswCQYDVQQGEwJV
UzELMAkGA1UECAwCQ0ExETAPBgNVBAcMCE1pbHBpdGFzMQ4wDAYDVQQKDAVDaXNj
................................................................
................................................................
JbimOpXAncoBLo14DXOJLvMVRjn1EULE9AXXCNfnrnBx7jL4CV+qHgEtF6oqclFW
JEA=
-----END CERTIFICATE-----
 
Certificate has the following attributes:
       Fingerprint MD5: D88D6D8F E53750D4 B36EB498 0A435DA1
      Fingerprint SHA1: 649DE822 1C222C1F 5101BEB8 B29CDF12 5CEE463B
 
% Do you accept this certificate? [yes/no]: yes
Trustpoint CA certificate accepted.
% Certificate successfully imported
 
 
csr8kv(config)#crypto pki trustpoint syslog-intermediate
csr8kv(ca-trustpoint)#enrollment terminal
csr8kv(ca-trustpoint)#revocation-check none
csr8kv(ca-trustpoint)#chain-validation continue syslog-root
csr8kv(ca-trustpoint)#end
csr8kv(config)#crypto pki authenticate syslog-intermediate
 
Enter the base 64 encoded CA certificate.
End with a blank line or the word "quit" on a line by itself
 
-----BEGIN CERTIFICATE-----
MIIFfTCCA2WgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwXDELMAkGA1UEBhMCVVMx
EzARBgNVBAgMCkNhbGlmb3JuaWExDjAMBgNVBAoMBUNpc2NvMQ4wDAYDVQQLDAVT
................................................................
................................................................
Nmz6NQynD7bxdQa9Xq9kyPuY3ZVKXkf312IRH0MEy2yFX/tAen9JqOeZ1g8canmw
TxsWA5TLzy1RmxqQh88f0CM=
-----END CERTIFICATE-----
Trustpoint 'syslog-intermediate' is a subordinate CA.
but certificate is not a CA certificate.
Manual verification required
Certificate has the following attributes:
       Fingerprint MD5: FE27BDBE 9265208A 681670AC F59A2BF1
      Fingerprint SHA1: 03F513BD 4BEB689F A4F4E001 57EC210E 88C7BD19
 
csr8kv(config)#logging host <Device Southbound IP> transport tls port 30614
csr8kv(config)#logging trap informational syslog-format rfc5424
csr8kv(config)#logging facility user
csr8kv(config)#service timestamps log datetime msec year show-timezone

csr8kv(config)#logging tls-profile tlsv12

If configuring for FQDN, perform these additional steps:

Configure the domain name and DNS IP on the device:

For IOS XR:

RP/0/RSP0/CPU0:ASR9k#config
RP/0/RSP0/CPU0:ASR9k(config)#domain name <DNS domain name>
RP/0/RSP0/CPU0:ASR9k(config)#domain name-server <DNS server IP>

For IOS XE:

Device(config)# ip name-server <IP of DNS>
Device(config)# ip domain name <domain name>

Configure Embedded Collectors VIP FQDN for tls-hostname:

For IOS XR:

RP/0/RSP0/CPU0:ASR9k(config)#logging tls-server syslog-tb131
RP/0/RSP0/CPU0:ASR9k(config-logging-tls-peer)#tls-hostname <Device VIP FQDN>

For IOS XE:

Device(config)# logging host fqdn ipv4 <hostname> transport tls port 30614

The device is now securely configured with a Crosswork trustpoint, enabling authenticated and encrypted log exports using TLS.

gNMI collection jobs

A gNMI telemetry collection is a data collection mechanism that:

uses the gRPC Network Management Interface (gNMI) protocol via Embedded Collectors to gather telemetry data from devices
supports only the gNMI Dial-In (gRPC Dial-In) streaming telemetry model based on subscriptions, relays subscription responses (notifications) to designated destinations, and
relies on model compatibility with the target device platform. Devices require gNMI configuration before collection jobs can be initiated.

In the gNMI operation, Crosswork Network Controller can use both secure and insecure connection modes, with preference dictated by inventory settings. If a device reloads, the gNMI collector automatically resubscribes to maintain ongoing data collection. The gNMI specification does not define message termination, so some cadence controls are unsupported for gNMI collectors.

The gNMI specification does not define a message termination mechanism; therefore, Destination and Dispatch cadence settings are unsupported for gNMI collectors. The cadence parameter that controls polling frequency for Embedded Collectors is not applicable in gNMI-based collection.

Note

When secure mode is enabled, gNMI uses server authentication only. The Embedded Collectors validates the device's certificate to establish a trusted connection, but does not present a client certificate for device validation. Mutual TLS authentication, where both parties authenticate each other, is not supported for gNMI device configuration.

Additional reference information

Supported gNMI subscribtion options

Embedded Collectors support multiple subscription paths per device, allowing combinations of ON_CHANGE and ONCE collection jobs:

ON_CHANGE: Collects and delivers data only when specified elements change.
ONCE: Collects and sends a one-time snapshot of the current data for the specified path.
SAMPLE (under STREAM): Collects data at specified intervals if the device supports cadence-based collection.
TARGET_DEFINED: The device determines the mode for each path (SAMPLE or ON_CHANGE) according to its capabilities.

Table 3. gNMI subscription options
Type	Subtype	Description
Once	None	Collects and sends the current snapshot of the system configuration only once for all specified paths.
Stream	SAMPLE	Cadence-based collection.
	ON_CHANGE	Sends initial state, then updates when the subscribed data changes.
	TARGET_DEFINED	Router or device selects mode (SAMPLE or ON_CHANGE) per path according to device configuration. Router/Device chooses the mode of subscription on a per-leaf basis based on the subscribed path (i.e. one of SAMPLE or ON_CHANGE)

Note
Embedded Collectors depend on the device to declare supported subscription modes.
gNMI sensor paths with default values do not appear in the payload due to Protocol Buffers conventions (e.g., default bool is false).

For boolean the default value is false. For enum, it is gnmi.proto specified.

Example:
message GNMIDeviceSetting {
bool suppress_redundant = 1;
bool allow_aggregation = 4;
bool updates_only = 6;
}
Example:
enum SubscriptionMode {
TARGET_DEFINED = 0; //default value will not be printed
ON_CHANGE = 1;
SAMPLE = 2;
}

Sample gNMI collection payload

In this sample you see two collections for the device group "milpitas". The first job collects interface statistics, every 60 seconds using the "mode" = "SAMPLE". The second job captures any changes to the interface state (up/down). If this is detected, it is simply sent "mode" = "STREAM" to the collector.

{
    "collection_job": {
        "job_device_set": {
            "device_set": {
                "device_group": "milpitas"
            }
        },
        "sensor_output_configs": [{
            "sensor_data": {
                "gnmi_standard_sensor": {
                    "Subscribe_request": {
                        "subscribe": {
                            "subscription": [{
                                "path": {
                                    "origin": "openconfig-interfaces",
                                    "elem": [{
                                        "name": "interfaces/interface/state/ifindex"
                                    }]
                                },
                                "mode": "SAMPLE",
                                "sample_interval": 10000000000
                            }, {
                                "path": {
                                    "origin": "openconfig-interfaces",
                                    "elem": [{
                                        "name": "interfaces/interfaces/state/counters/out-octets"
                                    }]
                                },
                                "mode": "ON_CHANGE",
                                "sample_interval": 10000000000
                            }],
                            "mode": "STREAM",
                            "encoding": "JSON"
                        }
                    }
                }
            },
            "destination": {
                "context_id": "hukarz",
                "destination_id": "c2a8fba8-8363-3d22-b0c2-a9e449693fae"
            }
        }],
        "sensor_input_configs": [{
            "sensor_data": {
                "gnmi_standard_sensor": {
                    "Subscribe_request": {
                        "subscribe": {
                            "subscription": [{
                                "path": {
                                    "origin": "openconfig-interfaces",
                                    "elem": [{
                                        "name": "interfaces/interface/state/ifindex"
                                    }]
                                },
                                "mode": "SAMPLE",
                                "sample_interval": 10000000000
                            }, {
                                "path": {
                                    "origin": "openconfig-interfaces",
                                    "elem": [{
                                        "name": "interfaces/interfaces/state/counters/out-octets"
                                    }]
                                },
                                "mode": "ON_CHANGE",
                                "sample_interval": 10000000000
                            }],
                            "mode": "STREAM",
                            "encoding": "JSON"
                        }
                    }
                }
            },
            "cadence_in_millisec": "60000"
        }],
        "application_context": {
            "context_id": "testing.group.gnmi.subscription.onchange",
            "application_id": "testing.postman.gnmi.standard.persistent"
        },
        "collection_mode": {
            "lifetime_type": "APPLICATION_MANAGED",
            "collector_type": "GNMI_COLLECTOR"
        }
    }
}

Enable secure gNMI communication between a device and Crosswork

Enable secure gNMI data exchanges between a device and Cisco Crosswork using certificate-based authentication.

Cisco Crosswork accepts a single rootCA for signing device certificates. All device certificates must be signed by the same CA, ensuring trusted and secure communication.

Before you begin

Ensure you have required certificate files (root CA, device certificates, device key).

Use these steps to enable secure gNMI between Cisco Crosswork and the devices.

Procedure

	1.	Generate certificates for the device, signed by the rootCA trusted by Crosswork. See Generate the device certificates.
	2.	Upload the certificates to the Crosswork Certificate Management UI. See Configure the gNMI certificate.
	3.	Update device configuration with secure gNMI port details provided by Crosswork. See Update protocol on device from Crosswork.
	4.	Enable gNMI on the device. See Configure devices for gNMI-based telemetry. Note Embedded Collectors supports server authentication only for gNMI device configuration. The device validates the Embedded Collectors's certificate, but the Embedded Collectors do not require a client certificate from the device. Mutual TLS authentication is not supported for gNMI collectors.
	5.	Enable gNMI bundling on the device. See Configure gNMI bundling for IOS XR.
	6.	Configure the certificates and device key on the device. See Certificate management for IOS XR and XE devices.

The device and Cisco Crosswork establish a secure, certificate-authenticated gNMI connection.

Generate the device certificates

Generate device certificates using OpenSSL for secure communication between devices and certificate authorities.

The certificate generation procedure has been validated using both OpenSSL and Microsoft tools. Contact Cisco Support if using a different tool.

Note
To generate device certificates using a different utility, contact the Cisco Support team.

Before you begin

Install OpenSSL on your system.
Ensure you have access permissions for certificate storage.

Procedure

Create the rootCA certificate.

Set the desired validity duration of the certificates using the “days” parameter (recommended: 365 or more).

# openssl genrsa -out rootCA.key
# openssl req -subj /C=/ST=/L=/O=/CN=CrossworkCA -x509 -new -nodes -key rootCA.key -sha256 -out rootCA.pem -days 1024

Create device key and certificate.


# openssl genrsa -out device.key
# openssl req -subj /C=/ST=/L=/O=/CN=Crosswork -new -key device.key -out device.csr
# openssl x509 -req -extfile <(printf "subjectAltName=IP.0: 10.58.56.18") -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -sha256 -out device.crt -days 1024

For multiple devices, specify multiple IP addresses in the subjectAltName, separated by commas in subjectAltName.

# openssl x509 -req -extfile <(printf "subjectAltName=IP.0: 10.58.56.18, IP.1: 10.58.56.19, IP.2: 10.58.56.20 ..... ") -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -sha256 -out device.crt -days 1024

Verify the certificate contains the expected Subject Alternative Name (SAN) details.

# openssl x509 -in device.crt -text -noout

The system generates a device certificate with the designated subject alternative names, enabling secure communication.

Sample output:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            66:38:0c:59:36:59:da:8c:5f:82:3b:b8:a7:47:8f:b6:17:1f:6a:0f
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = rootCA
        Validity
            Not Before: Oct 28 17:44:28 2021 GMT
            Not After : Aug 17 17:44:28 2024 GMT
        Subject: CN = Crosswork
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus:
                    00:c6:25:8a:e8:37:7f:8d:1a:7f:fa:e2:d6:10:0d:
                    b8:e6:2b:b0:b0:7e:ab:c9:f9:14:a3:4f:2e:e6:30:
                    97:f4:cd:d6:11:7d:c0:a6:9b:43:83:3e:26:0f:73:
                    42:89:3c:d7:62:7b:04:af:0b:16:67:4c:8e:60:05:
                    cc:dd:99:37:3f:a4:17:ed:ff:28:21:20:50:6f:d9:
                    be:23:78:07:dc:1e:31:5e:5f:ca:54:27:e0:64:80:
                    03:33:f1:cd:09:52:07:6f:13:81:1b:e1:77:e2:08:
                    9f:b4:c5:97:a3:71:e8:c4:c8:60:18:fc:f3:be:5f:
                    d5:37:c6:05:6e:9e:1f:65:5b:67:46:a6:d3:94:1f:
                    38:36:54:be:23:28:cc:7b:a1:86:ae:bd:0d:19:1e:
                    77:b7:bd:db:5a:43:1f:8b:06:4e:cd:89:88:e6:45:
                    0e:e3:17:b3:0d:ba:c8:25:9f:fc:40:08:87:32:26:
                    69:62:c9:57:72:8a:c2:a1:37:3f:9d:37:e9:69:33:
                    a5:68:0f:8f:f4:31:a8:bc:34:93:a3:81:b9:38:87:
                    2a:87:a3:4c:e0:d6:aa:ad:a7:5c:fb:98:a2:71:15:
                    68:e7:8d:0f:71:9a:a1:ca:10:81:f8:f6:85:86:c1:
                    06:cc:a2:47:16:89:ee:d1:90:c9:51:e1:0d:a3:2f:
                    9f:0b
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                IP Address:10.58.56.18
    Signature Algorithm: sha256WithRSAEncryption
         01:41:2c:91:0b:a1:10:8a:11:1a:95:36:99:2c:27:31:d3:7d:
         e9:4b:29:56:c3:b7:00:8c:f4:39:d2:8c:50:a4:da:d4:96:93:
         eb:bb:71:e3:70:d3:fe:1f:97:b2:bc:5c:f8:f4:65:ed:83:f7:
         67:56:db:0f:67:c2:3d:0c:e7:f8:37:65:1d:11:09:9a:e3:42:
         bc:c6:a0:31:7c:1f:d7:5e:c6:86:72:43:a8:c1:0c:70:33:60:
         dc:14:5b:9d:f3:ab:3d:d5:d2:94:90:1c:ba:fd:80:4d:22:e3:
         31:93:c7:16:5f:85:20:38:ad:36:b9:1a:e0:89:8e:06:8c:f8:
         cd:55:cc:a1:89:d3:91:7f:66:61:a3:40:71:c2:1e:ee:3b:80:
         37:af:73:5e:8e:0d:db:4b:49:da:a6:bd:7d:0a:aa:9e:9a:9e:
         fa:ed:05:25:08:f2:4d:cd:2f:63:55:cf:be:b1:5d:03:c2:b3:
         32:bf:f4:7b:1a:10:b9:5e:69:ac:77:5e:4a:4f:85:e3:7f:fe:
         04:df:ce:3e:bb:28:8f:e3:bf:1a:f9:0f:94:18:08:86:7d:59:
         57:71:0a:97:0d:86:9c:63:e7:0e:48:7d:f0:0e:1d:67:ff:9b:
         1d:1b:05:25:c8:c3:1f:f4:52:0f:e1:bf:86:d7:ec:47:10:bd:
         94:cf:ca:e2

Configure the gNMI certificate

Upload and configure a gNMI certificate in Cisco Crosswork to enable secure device communication via gNMI.

gNMI collectors operate as clients and access devices (gNMI servers). They require a valid certificate for trust validation. The certificate establishes a trusted chain for device authentication.

Before you begin

Ensure you have the root CA (.pem) or relevant trust chain file available.
Gather the necessary certificate details (such as name and role).
Verify that the trust chain in your .pem file includes all devices participating in gNMI communication.
Be aware that you can upload only one gNMI certificate to Crosswork.

Procedure

	1.	In the Cisco Crosswork UI, go to Administration > Certificate Management.
	2.	Click the + icon to add the certificate.
	3.	In the Add Certificate window, provide these details: Device Certificate Name: Enter a name for the certificate. Certificate Role: Select "Device gNMI/gRPC communication". Device Trust Chain: Upload the Root CA file or trust chain (.pem file). If you have multiple trust chains, add all of them (across vendors) to a single .pem file and upload that.
	4.	Click Save.

The newly added gNMI certificate appears in the configured certificates list.

Configure devices for gNMI-based telemetry

This section provides instruction on how to enable both platforms to collect and export telemetry data using gNMI.

Enable gNMI-based telemetry data collection on IOS XR and IOS XE devices.

On Cisco IOS XR devices, enable the gNMI service and specify telemetry parameters. See Configure IOS XR device for gNMI.
On Cisco IOS XE devices, enable gNMI and configure required access credentials. See Configure IOS XE device for gNMI.

Configure IOS XR device for gNMI

Configure IOS XR devices to enable gNMI-based telemetry data collection.

Use these instructions to enable gNMI on IOS XR devices so telemetry collectors can stream data via gRPC over HTTP/2.

Before you begin

Confirm the network environment supports gRPC over HTTP/2.
Obtain any necessary port numbers and security certificates.

Procedure

Enable gRPC on an HTTP/2 connection.

Enter configuration mode and activate gRPC with a specified port:

Example:

Router#configure
Router(config)#grpc
Router(config-grpc)#port <port-number>

Specify a port number within the range 57344 to 57999. If the port number is unavailable, an error will appear.

Configure session parameters.

where:

Use this command structure:

Example:

Router(config)#grpc{ address-family | dscp | max-request-per-user | max-request-total | max-streams | 
max-streams-per-user | no-tls | service-layer | tls-cipher | tls-trustpoint | vrf }

Parameter options:

Table 4. Parameters and descriptions
Parameters	Descriptions
`address-family`	Set the address-family identifier type.
`dscp`	Set the DSCP QoS marking on transmitted gRPC traffic.
`max-request-per-user`	Set the maximum concurrent requests per user.
`max-request-per-user`	Set the maximum concurrent requests per user.
`max-request-total`	Set the maximum concurrent requests in total.
`max-streams`	Set the maximum number of concurrent gRPC requests. The maximum subscription limit is 128 requests. The default is 32 requests.
`max-streams-per-user`	Set the maximum concurrent gRPC requests for each user. The maximum subscription limit is 128 requests. The default is 32 requests.
`no-tls`	Disable transport layer security (TLS). TLS is enabled by default.
`service-layer`	Enable gRPC service layer configuration.
`tls-cipher`	Enable gRPC TLS cipher suites.
`tls-trustpoint`	Configure trustpoint.
`server-vrf`	Enable server VRF.

Enable Traffic Protection for Third-Party Applications (TPA) on the device.

Configure these settings:

Example:

tpa
vrf default
  address-family ipv4
   default-route mgmt
   update-source dataports MgmtEth0/RP0/CPU0/0

The IOS XR device is configured to support secure, scalable, gNMI-based telemetry streaming as required for modern network data collection.

Configure IOS XE device for gNMI

Configure IOS XE devices to enable gNMI-based telemetry data collection.

Use these instructions to enable gNMI on IOS XE devices so telemetry collectors can stream data via gRPC over HTTP/2.

Before you begin

Confirm that your network environment supports gRPC over HTTP/2.
Obtain required port numbers for gNMI telemetry.
Acquire security certificates if you are enabling secure gNMI.

Procedure

Access device CLI in global configuration mode.

Enable the gNMI server in the insecure mode.

Example:

Device# configure terminal
Device(config)# gnmi-yang
Device(config)# gnmi-yang server
Device(config)# gnmi-yang port 50000 <The default port is 50052.>
Device(config)# end
Device

Enable the gNMI server in the secure mode.

Example:

Device# configure terminal
Device(config)# gnmi-yang server
Device(config)# gnmi-yang secure-server
Device(config)# gnmi-yang secure-trustpoint trustpoint1
Device(config)# gnmi-yang secure-client-auth
Device(config)# gnmi-yang secure-port 50001 <The default port is 50051.>
Device(config)# end
Device

The IOS XE device is now configured to stream telemetry data using gNMI over gRPC/HTTP2. Telemetry collectors can connect using the configured insecure or secure port.

What to do next

Validate the gNMI connection from your telemetry collector.

Configure gNMI bundling for IOS XR

Enable and configure gNMI bundling capability to optimize telemetry updates on IOS XR devices.

gNMI bundling allows IOS XR to combine multiple update messages into a single Notification message within a SubscribeResponse. This improves efficiency by reducing the number of notifications sent. You must enable bundling and specify the message size on the IOS XR device.

Before you begin

The gNMI bundling capability can only be configured from the device. It is not available in the Crosswork Interface. Details on how the bundling feature works are available in the Programmability Configuration Guide for Cisco 8000 Series Routers, IOS XR Release 7.8.x.
Embedded Collectors support server-side authentication for gNMI device configuration. The mutual TLS authentication is not supported for gNMI collectors.

Procedure

	1.	Enable gNMI bundling: `telemetry model-driven gnmi bundling` Note The gNMI bundling capability is disabled by default.
	2.	Set the bundling size, as needed: `telemetry model-driven gnmi bundling size <1024-65536>` The default bundling size is 32768 bytes. Note After processing the (N - 1)th instance, if the message size is less than the configured bundling size, one more instance may be included. This may result in the bundling size being exceeded.

The IOS XR device transmits bundled Update messages according to the specified message size, optimizing telemetry update delivery.

What to do next

To verify bundling is enabled and configured, use:

RP/0/RP0/CPU0:R0(config)#telemetry model-driven
RP/0/RP0/CPU0:R0(config-model-driven)#gnmi ?
  bundling   gNMI bundling of telemetry updates
  heartbeat  gNMI heartbeat
  <cr>
RP/0/RP0/CPU0:R0(config-model-driven)#gnmi bundling ?
  size  gNMI bundling size (default: 32768)
  <cr>
RP/0/RP0/CPU0:R0(config-model-driven)#gnmi bundling
RP/0/RP0/CPU0:R0(config-gnmi-bdl)#size ?
  <1024-65536>  gNMI bundling size (bytes)

Certificate management for IOS XR and XE devices

This section describes how to import and install certificates on the IOS XR and XE devices. Certificates and trustpoint are only required for secure gNMI servers.

Certificate management encompasses the procedures and requirements for securing communications between Cisco IOS XR and IOS XE devices:

Cisco IOS XR: Requires certificate and trustpoint configuration for enabling secure gNMI. See Install certificates on a Cisco IOS XR device.
Cisco IOS XE: Similarly requires certificate and trustpoint setup for secure gNMI operations. See Install certificates on a Cisco IOS XE device.

Install certificates on a Cisco IOS XR device

Import and install device certificates to enable secure gNMI server operation on Cisco IOS XR.

Certificates and a trustpoint are required only when configuring secure gNMI servers. This procedure guides you through all necessary installation steps.

Before you begin

Ensure you have the following files ready: rootCA.pem, device.key, and device.crt.
Ensure access to the IOS XR device filesystem.

Use these steps to install certificates on a Cisco IOS XR device.

Procedure

	1.	Copy the rootCA.pem, device.key, and device.crt to the device under the /tmp folder.
	2.	Log in to the IOS XR device.
	3.	Enter the VM shell mode. Example: `RP/0/RP0/CPU0:xrvr-7.2.1#run`
	4.	Navigate to the `/grpc` directory. Example: `cd /misc/config/grpc`
	5.	Create or replace the contents of these files in `/misc/config/grpc`. Note If TLS was previously enabled on your device, these files will already be present in which case replace the content of these files as explained below. If this is the first time, you are enabling TLS on the device, copy the files from the /tmp folder to this folder. If enabling TLS for the first time, copy the following from `/tmp`: ems.pem with device.crt ems.key with device.key ca.cert with rootCA.pem If TLS was previously enabled, overwrite these files with the new content.
	6.	Restart TLS on the device to activate changes: Disable TLS with the `no-tls` command. Re-enable TLS with the `no no-tls` configuration command.

Device certificates are installed, and TLS is restarted. The IOS XR device is ready for secure gNMI operations.

Install certificates on a Cisco IOS XE device

Enable secure gNMI server operation on a Cisco IOS XE device by installing the required certificates and configuring a trustpoint.

Certificates and a trustpoint are required only when configuring secure gNMI servers. This procedure guides you through all necessary installation steps.

Before you begin

Plan and note the trustpoint name and password you will use.

Obtain these files:
- The root CA certificate (e.g., rootCA.pem)
- The device’s encrypted private key (e.g., device.des3.key)
- The device certificate (e.g., device.crt)

Procedure

	1.	Enter global configuration mode.
	2.	Import the root CA certificate using the `crypto pki import [trustpoint] pem terminal password [password]` command. When prompted, paste the contents of your rootCA.pem file, followed by "quit" on a new line.
	3.	When prompted, import the device's encrypted private key. Paste contents, a by "quit", as instructed.
	4.	When prompted, import the device certificate. Paste contents, followed by "quit," as instructed.
	5.	Configure trustpoint parameters as needed (such as revocation checks). Example: # Send: Device# configure terminal Device(config)# crypto pki import trustpoint1 pem terminal password password1 # Receive: % Enter PEM-formatted CA certificate. % End with a blank line or "quit" on a line by itself. # Send: # Contents of rootCA.pem, followed by newline + 'quit' + newline: -----BEGIN CERTIFICATE----- <snip> -----END CERTIFICATE----- quit # Receive: % Enter PEM-formatted encrypted private General Purpose key. % End with "quit" on a line by itself. # Send: # Contents of device.des3.key, followed by newline + 'quit' + newline: -----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,D954FF9E43F1BA20 <snip> -----END RSA PRIVATE KEY----- quit # Receive: % Enter PEM-formatted General Purpose certificate. % End with a blank line or "quit" on a line by itself. # Send: # Contents of device.crt, followed by newline + 'quit' + newline: -----BEGIN CERTIFICATE----- <snip> -----END CERTIFICATE----- quit # Receive: % PEM files import succeeded. Device(config)# # Send: Device(config)# crypto pki trustpoint trustpoint1 Device(ca-trustpoint)# revocation-check none Device(ca-trustpoint)# end Device#

The certificates and key are installed, enabling secure gNMI server operation on Cisco IOS XE.