Chapter 1. Overview

This section contains the following topics:

- Audience

- Overview of Cisco Crosswork Change Automation and Health Insights

- API Documentation

- Licensing

- Log In and Log Out

- Use the Main Window Controls

- Set, Sort and Filter Table Data

Audience

This guide is for experienced network administrators who want to use Cisco Crosswork Change Automation and Health Insights in their network. This guide assumes that you are familiar with the following topics:

- Networking technologies and protocols (IS-IS, BGP, and so on)

- Network monitoring and troubleshooting

- Familiarity with the different operating systems used on devices that form your network, such as Cisco IOS-XR, ISO-XE, and NX-OS.

Overview of Cisco Crosswork Change Automation and Health Insights

Cisco Crosswork Network Automation is a microservices-based platform that brings together streaming telemetry, big data and application programming interfaces (APIs) to redefine service provider network operations.

Cisco Crosswork Network Automation enables multiple use cases, including those targeted by Cisco Crosswork Change Automation and Health Insights:

- Continuous real-time monitoring of key performance indicators (KPIs)

- Routinizing scheduled network maintenance and network reconfiguration tasks

- Linking optimization and remediation playbooks to KPIs in order to streamline response to network events

Begining with release 3.1 the data collection functionality has been separated out into its own VM and software package called Cisco Crosswork Data Gateway. Cisco Crosswork Data Gateway gathers all the information from the monitored devices and forwards it to Cisco Crosswork Change Automation and Health Insights for analysis and processing. Cisco Crosswork Change Automation and Health Insights can then be used by the operator to manage the network or respond to changes in the network. Apart from Cisco Crosswork Change Automation and Health Insights, Cisco Crosswork Data Gateway can also be used for external data collection integration. Cisco Crosswork Change Automation and Health Insights uses Cisco Network Services Orchestrator (Cisco NSO) as the default provider to manage the devices according to their expected functions, including configuring any required model-driven telemetry (MDT) sensor paths for data collection. Cisco NSO is vital in supplying device management and configuration-maintenance services

This guide explains how to use both Cisco Crosswork Change Automation and Health Insights and Cisco Crosswork Data Gateway.

For more information about the Cisco Crosswork Network Automation platform and Cisco Crosswork Change Automation and Health Insights, see the Cisco Crosswork Network Automation Product page on Cisco.com.

API Documentation

Advanced users can extend Cisco Crosswork Change Automation and Health Insights functions by using the product APIs.

For more about the product APIs, see the Cisco Crosswork Network Automation API Documentation on Cisco DevNet.

Licensing

Licenses determine the applications you can use and the numbers of devices that Cisco Crosswork Change Automation and Health Insights can manage.

Change Automation and Health Insights are separately licensed applications.

Cisco Crosswork Data Gateway license is included in Cisco Crosswork Change Automation and Health Insights license apart from Cisco Crosswork Data Gateway API access for external data collection integration which is separately licensed.

To purchase a Cisco Crosswork Change Automation and Health Insights license, contact your Cisco account representative. Do not make copies of licenses.

For more about licensing, see the Cisco Crosswork Network Automation Product Data Sheet on Cisco.com.

Note

For demonstrations and field trials, Cisco Crosswork Change Automation and Health Insights can be used without a license for up to 90 days.

Log In and Log Out

The Cisco Crosswork Change Automation and Health Insights user interface is browser based. It supports the following browsers:

- Google Chrome, version 70 or later

- Mozilla Firefox, version 60 or later

Procedure

Step 1

Open a web browser and enter:

https://<CrossworkVMManagementIPAddress>:30603/

Step 2

The Cisco Crosswork Change Automation and Health Insights browser-based user interface displays the login window. Enter your username and password.

Note

The default Cisco Crosswork Change Automation and Health Insights administrator user name and password is admin. This account is created automatically at installation (see Administrative Users Created During Installation). The initial password for this account must be changed during installation verification, as explained in the Cisco Crosswork Change Automation and Health Insights Installation Guide. Cisco strongly recommends that you keep the default administrator credential secure, and never use it for routine logins. Instead, create new user accounts with appropriate privileges and their own credentials (as explained in Add Users) and use only those accounts for all subsequent user logins.

Step 3

Click Log In.

When you access Cisco Crosswork Change Automation and Health Insights from your browser for the first time, some browsers display a warning that the site is untrusted. When this happens, follow the prompts to add a security exception and download the self-signed certificate from the server. After you do this, the browser accepts the Cisco Crosswork Change Automation and Health Insights server as a trusted site in all subsequent logins.

Note:

- You might need to log in again when you cross-launch from one application to another.

- A cross-launched application might remain open even after you log out of Cisco Crosswork Change Automation and Health Insights.

- If this is your first time logging in using your own user account, you will be prompted to create a new password for your account.

Step 4

To log out, click in the top right of the Cisco Crosswork Change Automation and Health Insights main window and choose Log out.

Use the Main Window Controls

The Cisco Crosswork Change Automation and Health Insights main window (also known as the dashboard) provides the controls and dashboard displays described below.

Main Window

Main Window Controls

Item

Description

1

More: Toggles the main menu between compact mode, which requires you to click on each menu icon before you can select the options under it, and expanded mode, which displays the entire menu and lets you pick options directly.

2

Network Visualization Tile: Summarizes overall device and link health across the network, showing the current number of high-use, degraded, or down links. Click on the Show Topology Map link at the bottom of the tile to open the Network Visualization application and get more details.

3

Health Insights Tile: Summarizes the number of devices and KPIs reporting problems. Click on the View Health Insights Dashboard link at the bottom of the tile to open the Health Insights application and get more details.

4

Change Automation Tile: The ring chart summarizes the state of Playbook execution, showing how many of your playbooks are running, scheduled to run, succeeded, and failed. Click on the View Change Automation Dashboard link at the bottom of the tile to the Change Automation application and get more details.

5

The icon lets you access the list of current notifications, alerts and messages.

The About icon displays the current version of Cisco Crosswork Change Automation and Health Insights.

The User Account icon lets you view the currently logged in user's name, change your password, and log out.

6

Home: Returns you to the Dashboard from any other window. The dashboard tiles on this window provide at-a-glance views of the most important data in your network.

7

Change Automation Menu: Lets you select from the options available in the Change Automation application, which automates the process of deploying changes to the network. Click the blue View Change Automation Dashboard link at the bottom of the Change Automation tile to bypass the menu and open the Change Automation application directly.

8

Inventory Management Menu: Lets you select from the options available in the Inventory Management application, which lets you add, organize, update and view information about the devices in your network; manage the providers, tags, and credential profiles you use; and view Job History for all device-related tasks.

9

Health Insights Menu: Lets you select from the options available in the Health Insights application, which allows you to view the Alert Dashboard, Manage KPIs and KPI Profiles, enable or disable KPI Profiles on selected devices, and see the KPI Profile Job History. Click the blue Show Health Insights Dashboard link at the bottom of the Health Insights tile to bypass the menu and open the Health Insights application directly.

10

Network Visualization Menu: Lets you select from the options available in the Network Visualization application, which presents both a geographical and a logical map view of the devices in your network, their topology and the links between them, the general condition of those devices and links, and other information. Click the blue Show Topology Map link at the bottom of the Network Visualization tile to bypass the menu and open the Network Visualization application directly.

11

Admin Menu: Lets you access the Administrative section of the user interface, where you can:

- Collect Cisco show-tech and logs

- Monitor system activity and restart services

- Manage users, roles, AAA TACACS+, and AAA LDAP servers

- Change Network Visualization topology map settings

- Manage certificates

- Manage Cisco Crosswork Data Gateway and collection jobs

- Register with Cisco Smart Licensing

Set, Sort and Filter Table Data

Many Cisco Crosswork Change Automation and Health Insights windows show database records in tables. For example: You will see tables in the Devices and Credentials windows accessed directly from Inventory Management, and also in the Links window accessed via the topological map in Network Visualization.

Any window with a table will also provide column selection, sorting, and filter functions that let you control the database records shown in the tables and help you locate particular records quickly.

Click to display a list of all the fields in the database for the kind of data record displayed in the table. You can choose which fields you want to display as table columns by checking or unchecking the box next to any field in the list. Your choices are enabled immediately and are permanent.

For example: In the Devices window shown below, we have unchecked the UUID field which is normally shown as part of the default Devices table, but now removed. We have also checked the Node IP field, adding it to the table.

You can also sort all the records displayed in the table according to the data in any one column by clicking that column's title:

- To sort the records in ascending order, click the column title once.

- To sort the records in descending order, click the column title again.

Sorting takes place immediately. You can only have one active sort at a time. The example Links window, below, shows an active sort on the Link Type field.

You can also filter the table to show only the records you want, using a quick filter or an advanced filter. Many tables have all these features enabled by default. If you cannot see the quick and advanced filter features displayed on a window with a table, click .

The quick filter displays only the records that match the value you enter above the column in the quick filter field (see item 2, below). Filtering takes place immediately, as you type.

The advanced filter narrows the content in the table by applying a filter that includes both a value and a logical operator, such as Equals, Starts with, Contains, and so on. Click in the column header to access the advanced filter (see items 4 and 5, below).

In addition to these quick and advanced filters, you can also use tags to filter the devices shown in the Devices window and on the Network Topology map (see Filter Devices by Tags).

Links Window With Active Sort and Filters

Item

Description

1

Sort active icon: This arrow icon indicates that the user has sorted the links by clicking on the column header. The arrow's direction shows that the table is sorted by Link Type, in ascending order.

2

Quick filter field: Type a text or numeric value in this field to show only the links that match the value you enter. The field shows the values you entered for both quick and advanced filters.

3

Filter active icon: This icon shows that a quick or advanced filter is currently applied to the data in this column.

4

Advanced filter icon: Click , shown in each column header, to specify an advanced filter on that column, using logical operators as well as alphanumerical values.

5

Filter criteria fields: These fields appear in a popup next to the column after you click the icon. Set the filter criteria by selecting the logical operator from the drop down list in the first field, and then entering the filter value in the second field. Your criteria will be applied immediately. You will then be prompted to enter more operators and values, and to decide if you want to concatenate them using logical AND or OR. The quick filter field shows the values you entered (but not the operators). Logical operators include Equals, Not equal, Starts with, Ends with, Contains, and Not contains.

Chapter 2. Get Started

This section contains the following topics:

- Basic Concepts

- Before You Begin

- High-Level Workflow

- Workflow 1: Setup

- Workflow 2: Monitor Performance Indicators

- Workflow 3: Respond to KPI Data

- Workflow 4: Schedule Playbooks

- Workflow 5: Develop Custom KPIs

- Workflow 6: Develop Custom Playbooks

- Workflow 7: Set Up Data Collection for External Data Destinations

- Workflow 8: Add Additional Device Collection Support

Basic Concepts

Cisco Crosswork Change Automation and Health Insights makes extensive use of three basic concepts. It is helpful to be familiar with them before you get started.

- Tags: Tags will be familiar from other Web applications. They are simple text strings you can attach to objects to help group them. Cisco Crosswork Change Automation and Health Insights comes with a short list of ready-made tags used to group network devices. You can create your own tags and use them to identify, find, and group devices for a variety of purposes. For example, in addition to type and geolocation, which are already stored when you on-board devices, you may want to identify and group them by their location in your network topology (Spine vs. Leaf), or the function they serve on your network (Provider vs. ProviderEdge). Tags are especially useful when setting up KPI monitoring, as you can apply a KPI to every member of a tagged group. You will want to develop your own tags for your purposes, and rework them as needed to meet changing needs.

- Providers: Cisco Crosswork Change Automation and Health Insights does not perform network discovery, inventory collection, monitoring, or configuration changes directly. Instead, it relies on providers, such as Cisco Network Services Orchestrator, to deliver these special services. The provider family determines the type of service that provider supplies to Cisco Crosswork Change Automation and Health Insights, and the parameters unique to that service, which must be configured. Because these providers are separate applications, you will be asked to register them and provide values for their unique parameters when you set up Cisco Crosswork Change Automation and Health Insights. This architecture permits Cisco Crosswork Change Automation and Health Insights to devote all of its resources to processing and interpreting network events and rolling out changes in response to these events.

- Credential Profiles: For Cisco Crosswork Change Automation and Health Insights to be able to access a device or to interact with a provider, it must be able to present credentials. Rather than entering credentials each time they are needed, you can instead create credential profiles to securely store this information. The platform supports unique credentials for each type of access protocol, and allows you to bundle multiple protocols and their corresponding credentials in a single profile. Devices that use the same credentials can share a credential profile. For example, if all of your routers in a particular building share a single SSH user ID and password, you can create a single credential profile to allow Cisco Crosswork Change Automation and Health Insights to access and manage them.

Before You Begin

Before you begin using Cisco Crosswork Change Automation and Health Insights, Cisco recommends that you complete the following planning and information-gathering steps, in any order you wish:

- User Accounts : Cisco recommends as a best practice that you create separate accounts for all of your users, so that there is an audit record of user activity on the system. Prepare a list of the people who will use Cisco Crosswork Change Automation and Health Insights. Decide on their user names and preliminary passwords, and create user profiles for them (see Manage Users).

- User Roles: Cisco recommends that you use role-based access control to confine users to just the software functions needed to perform their job duties. By default, every new user you create has full administrative privileges. Unless you want to extend the same privileges to every user, you will need to plan a system of user roles, create them, and assign them to the user profiles you create (see Create User Roles).

- Credentials: Gather the access credentials for your providers and for each supported protocol that you will use to monitor and manage your devices. For providers, this always includes user IDs, passwords, and connection protocols. For devices, it includes user IDs, passwords, and additional data such as the SNMP v2 read and write community strings, and SNMPv3 auth and privilege types. You will use these to create credential profiles (see Basic Concepts and Manage Credential Profiles).

- Tags: Plan a preliminary list of custom tags to create when setting up the system, so that you can use them to group your devices when you first onboard them. As explained in Basic Concepts, you will want to consider grouping devices by functionality, so that you can apply KPI monitoring to tagged groups easily. You need not have a complete list of tags at first, as you can always add more later, but please note that all the tags you do plan to use must be in place before you need them; you cannot create them "on the fly" (see Manage Tags and Create Tags).

- Providers: As explained in Basic Concepts, providers do the basic work of direct interaction with network devices, so that Cisco Crosswork Change Automation and Health Insights can automate monitoring and responses to network events. Cisco Network Services Orchestrator (Cisco NSO) is the default provider used in nearly every Cisco Crosswork Change Automation and Health Insights installation, so you will need to gather the Cisco NSO IP address or host name, port and protocol, and the credentials to be used to communicate with it (which you will need to add as a credential profile). You will need to do the same for any other providers you may plan to use, such as Cisco Software Manager or Cisco WAN Automation Engine (see Manage Providers and Add Cisco NSO Providers). This includes system service providers, such as an FTP server to store syslogs, or Cisco Crosswork Situation Manager for processing alerts.

- Devices: Decide how you are going to onboard your devices: manually, via the user interface, or automatically via synchronization or CSV import. This determines the amount of additional information you will need to onboard your devices, which is covered in About Adding Devices to Inventory.

- External Data Destination(s): Decide which external data destination (Kafka or gRPC) you are going to use and ensure it is set up to receive input from Cisco Crosswork Data Gateway.

- KPI Profile(s): KPIs (Key Performance Indicators) are used to monitor the health of the network. You can establish unique performance criteria based on the way a device or devices are used in the network. KPIs can be grouped to form a KPI Profile. It is helpful if you to have a good idea of the data you plan to monitor and the performance targets that you want to establish as you setup Health Insights.

Note that you can capture the devices, credential profiles, tags, and providers lists in spreadsheet form, convert the spreadsheet to CSV format, and then upload them in bulk to Cisco Crosswork Change Automation and Health Insights. You do this using the Import feature (accessed using the Import icon, ).

You can access CSV templates for each of these lists by clicking the Import icon in the corresponding places in the user interface. Select the Download template link when prompted to choose an export destination path and file name.

High-Level Workflow

The following workflow describes the main steps to getting started with Cisco Crosswork Change Automation and Health Insights.

Step

For details, see...

1. Populate the Cisco Crosswork Change Automation and Health Insights environment and set up Cisco Crosswork Data Gateway.

Workflow 1: Setup

2. Create KPI Profiles to monitor device Key Performance Indicators (KPIs) for issues and anomalies.

Workflow 2: Monitor Performance Indicators

3. Link KPIs to playbooks.

Workflow 3: Respond to KPI Data

4. Schedule Playbooks to perform routine maintenance.

Workflow 4: Schedule Playbooks

5. Expand telemetry insight with custom KPIs.

Workflow 5: Develop Custom KPIs

6. Remediate common scenarios and automate routine tasks with custom playbooks.

Workflow 6: Develop Custom Playbooks

7. Create collection jobs for external data destinations.

Note

This is applicable only if the add on entitlement license for Cisco Crosswork Data Gateway API access has been purchased.

Workflow 7: Set Up Data Collection for External Data Destinations

8. Adding additional device collection support

Workflow 8: Add Additional Device Collection Support

Workflow 1: Setup

The first step in getting started with Cisco Crosswork Change Automation and Health Insights is to prepare the system for use. The table below provides topics to refer to for help when executing each of the following tasks:

1. Create a credential profile for at least one provider

2. Gather the setup for the provider using that credential profile

3. Create credential profiles for the devices from that provider

4. Get the devices from that provider

5. Create tags.

6. Create any additional credential profiles for other providers you need, the setup for those providers, and credential profiles for the devices from those providers

7. Add devices to Cisco Crosswork Data Gateway.

Note

This workflow assumes that you have already installed and enrolled Cisco Crosswork Data Gateway as explained in Cisco Crosswork Change Automation and Health Insights 3.1 Installation Guide.

If you were able to complete the recommended planning steps explained in Before You Begin, you should have all the information you need to finish each step in this workflow.

Step

Action

1. Ensure that your devices are themselves configured properly for communication and telemetry.

Refer to the guidelines and sample configurations in:

Prerequisites for Onboarding Devices

Sample Configuration for Devices in Cisco NSO

Prerequisites for Device Model Driven Telemetry

2. Create credential profiles for your device provider and for your devices.

Follow the steps in Create Credential Profiles

3. Add the device provider (Cisco NSO).

Follow the steps in About Adding Providers

4. Validate communications with the device provider.

Check on the provider's reachability using the steps in Get Provider Details

5. Import or create tags.

To import them: Import Tags

To create them: Create Tags

6. Onboard devices using the method you prefer.

See About Adding Devices to Inventory

7. Attach devices to Cisco Crosswork Data Gateway.

Review the Data Gateways pane (see Manage Cisco Crosswork Data Gateway Instances). The operational state of the Cisco Crosswork Data Gateway instance to which you want to attach devices must be Up.

Follow the steps in Attach a Device to a Cisco Crosswork Data Gateway Instance

8. Validate Cisco Crosswork Change Automation and Health Insights communications with imported devices.

Review the Devices window (see Manage Devices). All the devices you have onboarded should be reachable.

Click to investigate any device whose Reachability State is marked as (unreachable), (degraded), or (unknown).

9. (Optional) Create additional user accounts.

Follow the steps in Add Users

10. (Optional) Import or create additional credential profiles and providers.

To import providers: Import Providers

To create providers: Add Providers Through the UI

Workflow 2: Monitor Performance Indicators

Once you have completed initial setup, use Cisco Crosswork Change Automation and Health Insights to begin device performance monitoring using KPI Profiles.

Step

Action

1. (Optional) Tag all of the devices whose KPIs you plan to monitor with a tag indicating the function they perform, per your plan.

Follow the tasks in the Manage Tags section. You can add them in the UI, or import them via CSV, and then apply them to the devices you want to monitor.

2. Plan which Cisco-supplied KPIs you want to begin using, based on each device's function and the device performance characteristics you want to monitor.

Review the Cisco-supplied KPIs documented in List of Health Insights KPIs.

3. Group the relevant KPIs to form KPI Profiles.

Follow the instructions in Create a New KPI Profile.

4. Enable the appropriate KPI Profiles on the devices you want to monitor.

Review and follow the instructions in Monitor Network Health and KPIs

Workflow 3: Respond to KPI Data

The following workflow describes the steps to follow when using Cisco Crosswork Change Automation and Health Insights Playbook to reconfigure the network in response to changes in performance detected by your selected KPIs.

Step

Action

1. Research the KPIs that are triggering alerts, and determine the best corrective action to take for the situation your network has experienced.

Follow the instructions in Monitor Network Health and KPIs, using the Alerts Dashboard to research the alerts and their possible causes.

2. Review the Cisco-supplied Playbooks and determine which ones will allow you to address the situation.

Review the list of Plays, Playbooks, and generic parameters in the "Playbooks" and "Verbs" references in the Change Automation Developer Guide on Cisco Devnet.

3. Try out the selected Playbooks and see if they are applicable to your purposes. As you experiment, adjust the Playbook parameters as needed.

See:

Perform a Dry Run of a Playbook

Run Playbooks In Single Stepping Mode

Run Playbooks In Continuous Mode

4. If the Playbooks are appropriate for your purposes, and the situation occurs often, link the selected Playbooks and KPIs, so alerts triggered by a KPI will always display the linked Playbook for selection by operators.

Once the KPI and Playbook are linked, operators can click on the Remediation icon, modify the Playbook parameters as needed, and execute the selected Playbook.

Follow the steps in Link KPIs to Playbooks. Use the Remediation icon shown in View Alerts for Network Devices to trigger a run of a linked Playbook from a device or KPI alert.

Workflow 4: Schedule Playbooks

The workflow below describes the steps to follow when using Cisco Crosswork Change Automation and Health Insights to automate routine network upkeep, and to verify that each routine change completed correctly.

Step

Action

1. Identify routine maintenance tasks (such as throughput checks, software upgrades, SMU installs, and so on) that you perform on a regular schedule and that may be suitable for automation using one or more Cisco Crosswork Change Automation and Health Insights Playbooks.

See About Running Playbooks and View the Playbook List

2. Configure Playbooks to perform these tasks at the desired time.

See About Running Playbooks and Schedule Playbook Runs

3. Review the Change Automation Job History to review the current status of the Playbook and confirm that it ran successfully.

See Use the Change Automation Dashboard and View or Abort Playbook Jobs

4. Use the APIs to perform routine maintenance tasks from your own scripts and applications.

See the Cisco Crosswork Network Automation API Documentation on Cisco DevNet.

Workflow 5: Develop Custom KPIs

The following workflow describes the steps to follow when considering whether or not to develop Cisco Crosswork Change Automation and Health Insights custom KPIs for your special needs, and how to proceed if you decide you do.

Step

Action

1. Review the existing KPIs to make sure the telemetry you want to monitor is not already available.

Follow the instructions in Monitor Network Health and KPIs, using the Alerts Dashboard to research the alerts and their possible causes.

2. Review the data available from the devices you want to monitor to see if they can supply the needed information:

- If they can, proceed with building a custom KPI.

- If they cannot: Contact Cisco to see if we can include the required data in a future version of the device code.

The latest information on the data your devices can provide is always available at the Cisco Telemetry Data Mapper (https://tdm.cisco.com).

Review the KPIs in List of Health Insights KPIs.

3. Build the custom KPI and add it to a KPI Profile.

See Create a New KPI and Create a New KPI Profile

4. Enable the new KPI Profile on a test device and confirm that the data reported matches your expectations. Be aware that KPIs that depend on data over time to establish baseline performance will need some time to "calibrate" before they provide meaningful data.

See Enable KPI Profile on Devices and View Alerts for Network Devices

5. If the KPI Profile is meeting expectations, enable it on all devices where you consider it applicable.

Follow the steps in Enable KPI Profile on Devices.

6. Review the Health Insights Job History to make sure the KPI Profile was deployed to all targeted devices

See Verify the Deployment Status of Enabled KPIs

Workflow 6: Develop Custom Playbooks

The following workflow describes the steps to follow when deciding to develop a Cisco Crosswork Change Automation and Health Insights custom Playbook.

Step

Action

1. Review the existing Playbook to see if any of them meet your needs fully or partially.

Review the Plays, Playbooks, and parameters in the "Playbooks" and "Verbs" references in the Change Automation Developer Guide on Cisco Devnet.

2. Find the Playbook that most closely matches your requirements and export that Playbook. Once you get good at modifying Playbook, you may choose to build them from scratch and skip this step.

See Export Playbooks

3. Modify the exported Playbook or create a new Playbook as necessary to meet your requirements.

Review the "Custom Playbooks" tutorial in the Change Automation Developer Guide on Cisco DevNet.

4. Import the new Playbook and then perform a dry run, or run it in single-stepping or continuous mode against a test device or devices, to confirm that it performs as expected.

First, follow the instructions in Import Playbooks. Then:

Perform a Dry Run of a Playbook

Run Playbooks In Single Stepping Mode

Run Playbooks In Continuous Mode

5. For a Playbook you have developed that meets your needs:

- In response to KPI alerts: If the Playbook is meeting expectations, link it to the KPI that indicates the need for the Playbook to be run, so that it is easy for operators to trigger the Playbook in response.

- For planned maintenance or configuration changes: Schedule the Playbook to run, or run it, at the planned time.

See:

Link KPIs to Playbooks

Schedule Playbook Runs

Workflow 7: Set Up Data Collection for External Data Destinations

Crosswork allows you to add two types of external data destinations:

- Kafka Server

- gRPC Server

The following workflow describes the steps to follow to add external destinations to Crosswork and create collection jobs to feed these external data destinations.

Step

Action

1. Ensure that you have set up the external data destination servers that you want to use.

Also, if you are using an external Kafka server, ensure that you have created Kafka topics prior to Crosswork using them.

The target destination installation and administration are left to the user and outside the scope of this document. Please refer your Kafka/gRPC administration and configuration guide.

Refer to the guidelines and sample configurations in:

Prerequisites for Onboarding Devices

Sample Configuration for Devices in Cisco NSO

Prerequisites for Device Model Driven Telemetry

2. Add a data destination to Crosswork.

Review the Data Destinations pane (see Manage Data Destinations).

Follow the steps in Add a Data Destination.

3. Ensure that prerequisites for device telemtery are met.

Refer to the guidelines and sample configurations in:

Prerequisites for Device Model Driven Telemetry

4. Create collection jobs

Refer to the following topics (in order of their listing) for guidelines and sample configurations:

1. About Collection Jobs

2. Collection Job Payload Model

3. Collection Jobs

4. Best Practices and Limitations for Creating Collection Jobs

Then, follow the steps in Create Collection Jobs.

5. Monitor collection jobs for status updates, issues, and alerts.

See Monitoring Collection Jobs.

Workflow 8: Add Additional Device Collection Support

Cisco Crosswork Data Gateway allows you to register and deploy three types of custom software packages to expand device coverage for external data collection:

1. CLI Device Package

2. Custom MIB Packages

3. SNMP Device Packages

The following workflow describes the steps to follow to add a custom package.

Step

Action

1. If you want to use a CLI Device Package, Custom MIB Package, or an SNMP Device Package, add them to Cisco Crosswork Data Gateway prior to creating collection jobs.

Review the Custom Software pane (see Manage Custom Software Packages).

Follow the steps in Add a Custom Software Package

Chapter 3. Automate Network Changes

This section contains the following topics:

- Change Automation Overview

- About Running Playbooks

- About Customizing Playbooks

- Troubleshoot Change Automation

Change Automation Overview

The Change Automation application automates the process of deploying changes to the network. You define intended network states in Change Automation using Playbooks. Playbooks are based on the Ansible specification, but with enhanced modules called Cisco verbs. You can then push configuration changes to Cisco Network Service Orchestrator (NSO), which deploys these changes to the network devices.

The difference between Change Automation and other existing scripted automation frameworks is that Change Automation is a closed-loop framework. Changes are deployed to the router or other device using programmable APIs, and the intent of the change is verified using telemetry that comes back from the router. Change Automation relies on telemetry to verify the intent of the change, avoiding the need to frequently poll the device for updates.

Traditional Ansible implementations in open source use CLI towards network devices without a configuration store, which leads to out-of-sync states. Driving network configuration change with a store provides transactional rollback and locking abilities and enables a single source of truth for device configuration.

The following is a high-level Change Automation workflow:

1. Define your desired network changes in an Ansible Playbook.

2. Push configuration changes to the network device indirectly, using a configuration services provider (such as Cisco Network Services Orchestrator).

3. Receive real-time feedback via telemetry from the devices, telling you that the network changes were made and the impact of the changes. You can also use post-change KPIs to determine if a particular change should be undone and the devices returned to their previous configuration.

Change Automation comes with a robust library of Playbooks, each with its own collection of atomic configuration and check plays. (A Playbook consists of multiple plays.)

You can configure what each Playbook does by specifying the values of runtime parameters to create a Playbook Job. With the correct programming skills, you can download, modify and then upload and run your own versions of the Cisco-supplied Playbooks, or create your own custom Playbooks. For more information, see About Customizing Playbooks

- Use the Change Automation Dashboard

- View the Playbook List

Use the Change Automation Dashboard

The Change Automation application's Dashboard window (shown in the following figure) lets you view all Playbook-related activity and initiate Playbook runs. It displays an alphabetical list of Playbooks, the most recently run Playbook jobs, and the same network topology map you see when you select Network Visualization > View Topology. For help using the topology map, see Network Visualization Overview.

To view the Change Automation Dashboard window, select Change Automation > Dashboard.

The View All Playbooks and View All Jobs links on the Dashboard window give you direct access to the Change Automation Run Playbook and Job History windows, respectively. For help using these two windows, see the topics in the section About Running Playbooks.

Change Automation Dashboard Window

View the Playbook List

The Change Automation application's Playbook List window (in the following figure) gives you a consolidated list of all the Playbooks in the system. To view the Playbook List window, select Change Automation > Playbook List.

Item

Description

1

Click to delete the currently selected custom Playbook. See Delete Custom Playbooks.

Click to import Playbooks from a gzipped TAR archive file. See Import Playbooks.

Click to export the currently selected Playbook(s) as a gzipped TAR archive file. See Export Playbooks.

2

Click to see a popup Playbook Details window showing the Playbook's description, hardware and software compatibility, version number, and its plays. When you are finished viewing these details, click to close the popup window.

3

Click on the Name, Description, Version, Software Platform, and Last Modified column headings in the table to sort the table by that column's data. You can also choose which columns are shown, and set quick or advanced filters on any column. See Set, Sort and Filter Table Data.

4

Click to refresh the Playbooks list.

5

Click to set filter criteria on one or more columns in the table.

Click the Clear Filter link to clear any filter criteria you may have set.

About Running Playbooks

Running any Playbook consists of five steps:

1. Select the Playbook you want to run (see View the Playbook List).

2. Select the device or devices you want to run it on.

3. Enter the appropriate runtime parameters you want the Playbook to apply.

4. Select the execution mode you want to use:

1. Perform a Dry Run of a Playbook, where you can see what the Playbook will do before you commit to making changes to the network.

2. Run Playbooks In Single Stepping Mode, so you have a chance to pause after each Playbook check or action, and roll back changes you did not intend.

3. Run Playbooks In Continuous Mode and apply the changes immediately.

While selecting the execution mode, you can also choose to:

- Schedule Playbook Runs for another calendar date or time.

- Collect syslogs during and after the run. Syslog collection is available only when running the Playbook in single-stepping or continuous execution mode, and only if you have already configured a syslog storage provider (see Add Syslog Storage Providers).

- Specify a Failure Policy, where you decide what the system should do in case a failure occurs at any time during the Playbook run.

5. Confirm your settings and run the Playbook in the execution mode you selected.

Depending on their complexity and on network factors, some Playbooks may take a lot of time to run. At any time during and after completion of a run, you can view the run details and status. If the Playbook is still running, you can also choose to abort it. For details, see View or Abort Playbook Jobs.

- Playbook Execution Order

- Perform a Dry Run of a Playbook

- Run Playbooks In Single Stepping Mode

- Run Playbooks In Continuous Mode

- Schedule Playbook Runs

- View or Abort Playbook Jobs

Playbook Execution Order

When it is running, every Playbook conducts checks and configuration changes in four phases, which correspond to sections of the Playbook code (identified using the tags discussed in Playbook Components and Files):

1. Pre-Maintenance—This phase of the Playbook includes non-disruptive checks and any other operations on the device that prepare it for potentially traffic-impacting changes. For example:

- Take snapshots of various routing protocol states.

- Take snapshots of memory, CPU, and system health parameters.

- Validate the capacity (storage, memory) on active and standby routers for the new software patch upgrade.

2. Maintenance—This phase of the Playbook includes any task that may disrupt traffic flowing through the router or impact neighboring routers. For example:

- Cost out the router and wait until traffic drains out completely.

- Verify that the redundant router is healthy and carrying traffic.

- Perform the upgrade procedure on the device.

- Reconfigure the device(s) to support a new configuration or feature.

3. Post-Maintenance—This phase of the Playbook includes verification tasks to perform on the router after any disruptive operation. For example:

- Verify that the current state matches the desired state.

- Cost in the router and wait for traffic to return to normal levels.

4. Continuous—In addition to the three serial phases already described, Change Automation also runs check tasks that span the entire duration of Playbook execution. These tasks check the state of the router while the Playbook is being deployed, and cancel the Playbook execution if any catastrophic or undesirable state change occurs. The checks in the Playbook may also monitor a neighboring router to guarantee that there are no second-order failures in the network while the changes are being deployed.

Perform a Dry Run of a Playbook

A dry run lets you view configuration changes that the Playbook will send to the device, without performing the actual commit of the changes, as you would with a run in the single-stepping or continuous execution modes.

It is a best practice to perform a dry run and verify the configuration changes before you deploy those changes to the router. If the dry run fails, you may want to debug its parameter values using another dry run. You can also debug by performing a single-stepping run, which will allow you to abort and rollback changes after one or more of the plays, instead of only at the end, as part of a continuous run's Failure Policy.

Note that dry run mode is intended for use only with Playbooks that perform actual device configuration changes via Cisco NSO. See the "Playbooks" and "Verbs" references in the Change Automation Developer Guide on Cisco Devnet for details on Playbooks that do not support dry run mode. These will include, for example, Node state snapshot, Install optional package or SMU, and Uninstall optional package or SMU.

Procedure

Step 1

From the main menu, choose Change Automation > Run Playbook.

Step 2

In the Select Playbook list on the left, click on the Playbook you want to dry run. On the right, the window displays the Playbook name, hardware and software compatibility information, and descriptions for all the plays in the selected Playbook.

Step 3

Click Next. The Select Devices window appears. Using this window:

- You can toggle between the table view and topology map view by clicking and selecting the relevant option on the drop-down button on the upper left corner of the window. Choose Select Devices From List or Select Devices From Map to select the table view or topology map view respectively. By default, the table view is displayed.

- With the topology map view displayed, you can toggle between the map's geographical and logical views by clicking on the or the . You can also zoom, display bandwidth utilization, and change logical view layouts as you do with the topology map you see when you select Network Visualization > View Topology (see Network Visualization Overview).

- You can select the devices using Static or Dynamic using Tags device selection options. Static selection allows you to select devices from the list using quick and advanced filters and filter by tags on the left. Dynamic using Tags selection targets you to select the relevant tag intead of devices from the table on the left side, and all devices associated with the relevant tag are selected. Hover the mouse pointer over the icon next to the options for more information. You can also view the selection criteria such as number of devices required for the selected playbook.

- In Static selection mode, you can check the Allow Bulk Jobs check box to select multple devices and run the selected playbook on them at the simultaneously. Based on your selection, the system creates a static group of multiple jobs. Hover the mouse pointer over the icon next to the check box for more information. There is no limitation on the number of devices you can select for a bulk job.

Step 4

The Select Devices window will prompt you to select one or more of the devices shown (depending on the Playbook). Click on the devices you want to select, then click Next. The Parameters window appears.

Step 5

In the fields provided in the Parameters window, enter the Playbook parameter values to use for this dry run.

With the Parameters window displayed, you can also:

- Click JSON to enter the parameter values in JSON format. A popup text window displays the full list of JSON parameters, with empty values in quotes. Edit the values and, when you are finished, click Save.

- Click to upload a JSON file with the parameter values you want. You will be prompted to navigate to the JSON parameters file you have previously prepared (or downloaded from a previous Playbook run) and then upload it as appropriate for your browser and operating system.

- Click + Add to add additional instances of a particular parameter, if required for the Playbook you are running. Click X Remove to delete instances added in this way.

- Click to clear all the parameter values entered so far.

Step 6

With the parameter values set, click Next. The Execution Policy window appears.

Step 7

Choose Dry Run and click Next. The Review your Job window appears, displaying a summary of all of your choices: playbook, devices, parameters, and execution policy. In this window:

- You must provide a relevant Name for the job.

- You can assign tags to your job. Click New Job Tag, provide a name and color and save your settings to create your own tag. You can also select from the list of existing job tags by clicking the corresponding checkboxes. Click Manage Job Tags to create, edit or delete job tags.

- You can click on any of the Change links in the Review your Job window summary to modify your choices.

Step 8

When you are ready to continue, click Run Playbook.

Step 9

At the confirmation prompt, click Confirm. The Execution Mode window is displayed.

Step 10

After the dry run is complete:

- Click the Dry Run tab and verify the configuration changes that would be pushed to the device had this not been a dry run. This tab will display a no config change message if no changes would have been made. Please note that this tab shows only cumulative configuration changes, not each individual change made. For example, if a Playbook configures set-overload-bit in one step and then unconfigures it using no set-overload-bit in a later step, the tab will show no config change.

- Click the Events tab to see success and failure messages for each step of the Playbook. This can help you diagnose and correct problems with individual plays and the run as a whole.

- Click the Console tab to see messages that Ansible generated during the run.

As syslog collection is disabled for drying runs, the Syslog tab will contain only a message stating that.

Step 11

(Optional) If you want to perform a single-step debugging run, or are ready to commit the changes to the device, click Execute Now. The Execution Policy window will display, with all of your parameter values from the dry run pre-filled.

Run Playbooks In Single Stepping Mode

Single-stepping execution mode is a handy way to test a custom or modified Playbook, or diagnose problems with a pre-packaged Playbook that is not giving you the results you want. Unlike a dry run, a single-stepping execution commits configuration changes to the device as the Playbook runs. However, you can set breakpoints on or pauses after any Maintenance or Post-Maintenance action in the Playbook. Please note that, while you can set breakpoints on Pre-Maintenance actions, doing so will have no effect, and these actions will not pause.

Whenever the Playbook hits a breakpoint, it will stop, and will not continue until you issue the command to proceed. At each pause, you can also choose to abort the entire run and roll back all changes made, or rollback to any previous play.

Procedure

Step 1

From the main menu, choose Change Automation > Run Playbook.

Step 2

In the Select Playbook list on the left, click on the Playbook you want to run. On the right, the window displays the Playbook name, hardware and software compatibility information, and descriptions for all the plays in the selected Playbook.

Step 3

Click Next. The Select Devices window appears. Using this window:

- You can toggle between the table view and topology map view by clicking and selecting the relevant option on the drop-down button on the upper left corner of the window. Choose Select Devices From List or Select Devices From Map to select the table view or topology map view respectively. By default, the table view is displayed.

- With the topology map view displayed, you can toggle between the map's geographical and logical views by clicking on the or the . You can also zoom, display bandwidth utilization, and change logical view layouts as you do with the topology map you see when you select Network Visualization > View Topology (see Network Visualization Overview).

- You can select the devices using Static or Dynamic using Tags device selection options. Static selection allows you to select devices from the list using quick and advanced filters and filter by tags on the left. Dynamic using Tags selection allows you to select the relevant tag from the table on the left side, and all devices associated with the relevant tag are selected. Hover the mouse pointer over the icon next to the options for more information. You can also view the selection criteria such as number of devices required for the selected playbook.

- In Static selection mode, you can check the Allow Bulk Jobs check box to select multple devices and run the selected playbook on them at the simultaneously. Based on your selection, the system creates a static group of multiple jobs. Hover the mouse pointer over the icon next to the check box for more information. There is no limitation on the number of devices you can select for a bulk job.

Step 4

The Select Devices window will prompt you to select one or more of the devices shown (depending on the Playbook). Click on the devices you want. Click Next.

Step 5

Click Next. The Parameters window appears.

Step 6

In the fields provided in the Parameters window, enter the Playbook parameter values to use for this run.

With the Parameters window displayed, you can also:

- Click JSON to enter the parameter values in JSON format. A popup text window displays the full list of JSON parameters, with empty values in quotes. Edit the values and, when you are finished, click Save.

- Click to upload a JSON file with the parameter values you want. You will be prompted to navigate to the JSON parameters file you have previously prepared (or downloaded from a previous Playbook run) and then upload it as appropriate for your browser and operating system.

- Click + Add to add additional instances of a particular parameter, if required for the Playbook you are running. Click X Remove to delete instances added in this way.

- Click to clear all the parameter values entered so far.

Step 7

With the parameter values set, click Next. The Execution Policy window appears.

Step 8

Choose Single Stepping. The Execution Policy window displays additional features to customize the job:

- Under Collect Syslogs, click Yes if you want syslogs to be collected during and immediately after the run, No if you do not. Yes is the default selection only if you have a syslog provider configured (see Add Syslog Storage Providers).

- From the Failure Policy dropdown, select:

- Abort to abort the entire run, without rolling back any changes, if a failure occurs at any point. This is the default. Any configuration changes made up to the point of failure will not be rolled back.

- Pause to pause the run and allow you to decide how to handle the failure. This pause will be in addition to any breakpoints you set using the Single stepping breakpoints dropdown.

- Complete Roll Back to abort the entire run and roll back all configuration changes made.

- In the Schedule area, uncheck the default Run Now selection to schedule the job for a later time. See Schedule Playbook Runs for help on using the Schedule area features

Step 9

From the Single stepping breakpoints dropdown, select either

- Every step to pause automatically after every step in the Playbook.

- Customize to select the steps where you want the Playbook to pause.

If you select Customize, the Customize Breakpoints popup displays a list of all the plays in the Playbook, with a at the step between each play. Click the at each step where you want to set a breakpoint. When you are finished, click Done.

Step 10

Click Next. The Review your Job window appears, displaying a summary of all of your choices: playbook, devices, parameters, and execution policy. In this window:

- You must provide a relevant Name for the job.

- You can assign tags to your job. Click New Job Tag, provide a name and color and save your settings to create your own tag. You can also select from the list of existing job tags by clicking the corresponding checkboxes. Click Manage Job Tags to create, edit or delete job tags.

- You can click on any of the Change links in the Review your Job window summary to modify your choices.

Step 11

When you are ready to continue, click Run Playbook.

Step 12

At the confirmation prompt, click Confirm. The Job History window is displayed, with the details of the current job displayed on the right side. The job details include information such as job status, job set tags, title of selected playbook, execution parameters and policy, last updated date and update comments (if any). Click the icon next to the detail to view more information.

Step 13

While the run is executing, the blue Running tile at the top of the window will change to Paused for each step at which you have set a breakpoint. Your choices at each pause will be displayed as buttons below the blue tiles:

- Click Resume to resume running from this point, with no changes. The Resume request includes the runtime parameters from the previous step; you can edit these, as needed, later.

- Click Roll Back to roll back any changes made so far. You can choose how far to rollback:

- Click Complete Roll Back to roll back all changes to the start of the Playbook run. Once you have rolled back to the start, you can choose to Resume from that point, Abort the run entirely, or Edit runtime parameters of the run.

- Click Select Roll Back Point to roll back changes to the step you select. All the previous steps will then have a roll back point icon displayed next to them: . Click the for the step to which you want to roll back. Once you have selected the step, you can choose to Resume from that step, Roll Back further, Abort the run entirely, or Edit runtime parameters.

- Click Abort to abort the run entirely. No changes made will be rolled back.

- Click Edit runtime parameters to edit the parameters the run is using. You edit using a popup version of the Parameters window, just as you did in step 6. The parameters exposed for editing when resuming are specific to the task being resumed, which means that they are not the same global parameters you defined in step 6. Most of the time, they are a subset of the global parameters. When you are finished, click Apply. You can then choose to Resume execution with the changed parameters.

Step 14

While the run is executing, you can also use the following features of the progress window:

- View the execution status of each play in the Playbook in the Maintenance play list at the left side of the window. Plays that fail are indicated with a red icon; plays that succeed are indicated with a green icon.

- See reminders of your choices in the blue Playbook and Devices tiles at the top of the window.

- See the current status of the run in the blue Running tile at the top of the window.

- Click View in the Parameters tile to view the run's parameters. While viewing the parameters, you can click Download Parameters to save them in a JSON file. You will be prompted to name and save the file as appropriate for your browser and operating system.

- Use the network topology in the map at the right side of the window to view the device and its connections to the rest of your network.

Step 15

After the run is complete:

- Click the Events tab to see success and failure messages for each step of the Playbook. This can help you diagnose and correct problems with individual plays and the run as a whole.

- Click the Syslogs tab to access syslog messages collected during and immediately after the run. If syslog collection is enabled, the tab will provide a pointer to the path on the syslog storage provider where collected syslogs are stored. If you chose not to collect syslogs, or no syslog storage provider has been configured, this tab will display a message indicating that syslog collection is disabled.

- Click the Console tab to see relevant commands and responses from the device consoles that took place during the run. These messages can also help with diagnostics.

Run Playbooks In Continuous Mode

Continuous execution mode is the standard way to run Playbooks. Configuration changes are committed to the device during the run, with no checks or delays except those programmed into it for system resets or other purposes. The run continues until it succeeds or fails. If it fails, you can use the run's Failure Policy to abort, rollback all changes made to the device, or pause execution at the failure point.

It is always good practice to perform a dry run and verify the configuration changes before committing to a continuous run (see Perform a Dry Run of a Playbook). You can also run the Playbook in single-stepping mode, which will allow you to pause execution after any play you select, abort and rollback changes as needed, and even change runtime parameters in the middle of the run (see Run Playbooks In Single Stepping Mode).

Procedure

Step 1

From the main menu, choose Change Automation > Run Playbook.

Step 2

In the Select Playbook list on the left, click on the Playbook you want to run. On the right, the window displays the Playbook name, hardware and software compatibility information, and descriptions for all the plays in the selected Playbook.

Step 3

Click Next. The Select Devices window appears. Using this window:

- You can toggle between the table view and topology map view by clicking and selecting the relevant option on the drop-down button on the upper left corner of the window. Choose Select Devices From List or Select Devices From Map to select the table view or topology map view respectively. By default, the table view is displayed.

- With the topology map view displayed, you can toggle between the map's geographical and logical views by clicking on the or the . You can also zoom, display bandwidth utilization, and change logical view layouts as you do with the topology map you see when you select Network Visualization > View Topology (see Network Visualization Overview).

- You can select the devices using Static or Dynamic using Tags device selection options. Static selection allows you to select devices from the list using quick and advanced filters and filter by tags on the left. Dynamic using Tags selection allows you to select the relevant tag from the table on the left side, and all devices associated with the relevant tag are selected. Hover the mouse pointer over the icon next to the options for more information. You can also view the selection criteria such as number of devices required for the selected playbook.

- In Static selection mode, you can check the Allow Bulk Jobs check box to select multple devices and run the selected playbook on them at the simultaneously. Based on your selection, the system creates a static group of multiple jobs. Hover the mouse pointer over the icon next to the check box for more information. There is no limitation on the number of devices you can select for a bulk job.

Step 4

The Select Devices window will prompt you to select one or more of the devices shown (depending on the Playbook). Click on the devices you want to select them, then click Next. The Parameters window appears.

Step 5

In the fields provided in the Parameters window, enter the Playbook parameter values to use for this dry run.

With the Parameters window displayed, you can also:

- Click JSON to enter the parameter values in JSON format. A popup text window displays the full list of JSON parameters, with empty values in quotes. Edit the values and, when you are finished, click Save.

- Click to upload a JSON file with the parameter values you want. You will be prompted to navigate to the JSON parameters file you have previously prepared (or downloaded from a previous Playbook run) and then upload it as appropriate for your browser and operating system.

- Click + Add to add additional instances of a particular parameter, if required for the Playbook you are running. Click X Remove to delete instances added in this way.

- Click to clear all the parameter values entered so far.

Step 6

With the parameter values set, click Next. The Execution Policy window appears.

Step 7

Choose Continuous. The Execution Policy window displays additional features to customize the job:

- Under Collect Syslogs, click Yes if you want syslogs to be collected during and immediately after the run, No if you do not. Yes is the default selection only if you have a syslog provider configured (see Add Syslog Storage Providers).

- From the Failure Policy dropdown, select:

- Abort to abort the entire run, without rolling back any changes, if a failure occurs at any point. This is the default. Any configuration changes made up to the point of failure will not be rolled back.

- Pause to pause the run and allow you to decide how to handle the failure.

- Complete Roll Back to abort the entire run and roll back all configuration changes made.

- In the Schedule area, uncheck the default Run Now selection to schedule the job for a later time. See Schedule Playbook Runs for help on using the Schedule features.

Step 8

Click Next. The Review your Job window appears, displaying a summary of all of your choices: playbook, devices, parameters, and execution policy. In this window:

- You must provide a relevant Name for the job.

- You can assign tags to your job. Click New Job Tag, provide a name and color and save your settings to create your own tag. You can also select from the list of existing job tags by clicking the corresponding checkboxes. Click Manage Job Tags to create, edit or delete job tags.

- You can click on any of the Change links in the Review your Job window summary to modify your choices.

Step 9

When you are ready to continue, click Run Playbook.

Step 10

At the confirmation prompt, click Confirm. The Job History window is displayed, with the details of the current job displayed on the right side. The job details include information such as job status, job set tags, title of selected playbook, execution parameters and policy, last updated date and update comments (if any). Click the icon next to the detail to view more information.

Step 11

While the run is executing, the blue Running tile at the top of the window will change to Paused if you chose a Failure Policy of Pause. Your choices will be displayed as buttons below the blue tiles:

- Click Resume to resume running from this point, with no changes.

- Click Roll Back to roll back any changes made so far.

- Click Abort to abort the run entirely. No changes made will be rolled back.

Step 12

While the run is executing, you can also use the following features of the progress window:

- View the execution status of each play in the Playbook in the Maintenance play list at the left side of the window. Plays that fail are indicated with a red icon; plays that succeed are indicated with a green icon.

- See reminders of your choices in the blue Playbook and Devices tiles at the top of the window.

- See the current status of the run in the blue Running tile at the top of the window.

- Click View in the Parameters tile to view the run's parameters. While viewing the parameters, you can click Download Parameters to save them in a JSON file. You will be prompted to name and save the file as appropriate for your browser and operating system.

- Use the network topology in the map at the right side of the window to view the device and its connections to the rest of your network.

Step 13

After the run is complete:

- Click the Events tab to see success and failure messages for each step of the Playbook. This can help you diagnose and correct problems with individual plays and the run as a whole.

- Click the Syslogs tab to access syslog messages collected during and immediately after the run. If syslog collection is enabled, the tab will provide a pointer to the path on the syslog storage provider where collected syslogs are stored. If you chose not to collect syslogs, or no syslog storage provider has been configured, this tab will display a message indicating that syslog collection is disabled.

- Click the Console tab to see relevant commands and responses from the device consoles that took place during the run. These messages can also help with diagnostics.

Schedule Playbook Runs

The Change Automation application's Execution Mode window allows you to schedule future Playbook runs as jobs, and view all the jobs that have been scheduled. Use the Schedule area on the left to schedule a job. Use the All Scheduled Jobs area on the right to view scheduled jobs on the calendar.

The Execution Mode window's scheduling features are only displayed when you have chosen to run a Playbook in continuous or single-stepping mode. You cannot schedule a dry run of a Playbook.

Execution Mode Scheduling Features

Item

Description

1

Run Now: Running Playbooks immediately is the default for continuous and single-stepping execution modes. To schedule a run for a future time and date, you must uncheck this box.

2

Schedule Selectors: Use these fields to select the future time and date when the Playbook runs. Although it is the default for the Pre-Maintenance and Maintenance phases of a scheduled Playbook to start at the same time, you can use the upper Schedule Pre-check and lower Schedule Perform fields to schedule the start of Pre-Maintenance and the start of Maintenance independently. Note that the Schedule Perform time must always be greater than or equal to the Schedule Pre-check time.

3

Previous/Today/Next Selectors: Use these three selectors with the Month/Week/Day selectors to focus the calendar's display of scheduled jobs on the time range in which you are interested. For example: To show only those jobs scheduled for next week, click Next and Week.

4

Job Icons: Red, numbered icons in the squares representing each calendar date show how many jobs are scheduled for that date. Yellow circle icons represent each scheduled job.

5

Job Details Popup: Hover your mouse cursor over a yellow circle icon to see the details for the scheduled job represented by that icon. The popup shows the execution ID of the job and the name of the Playbook to be run.

6

Show jobs for selected devices only: Check this box to restrict the calendar display to only those jobs scheduled to run on the devices you have already selected. This is a handy way to see if the schedule you plan for your Playbook run will conflict with other scheduled jobs on the same devices.

7

Month/Week/Day Selectors: Use these three selectors with the Previous/Today/Nextselectors to focus the calendar's display of scheduled jobs on the time range in which you are interested. For example: To show only those jobs scheduled for last month, click Last and Month.

Note

Change Automation Playbooks have a mop_timeout parameter, which is a user specified input needed to schedule any Playbook. If your are scheduling a Playbook with Failure Policy set to Complete Roll Back, you must double the value of the mop_timeout parameter as it can possibly take as much time to roll back the Playbook as it takes to run it until the last step. For example, if Playbook timeout is typically set to 1 hour, set it to 2 hours instead when enabling complete rollback on failure policy. Without sufficient mop_timeout, the Playbook can end up in a bad state if the timeout gets triggered while roll back is in progress.

View or Abort Playbook Jobs

There are two ways to view Playbook jobs:

1. The Change Automation Dashboard window's Jobs panel, which shows general information about the Playbook jobs that have been run most recently, including whether these jobs succeeded or failed.

2. The Change Automation Job History window lists all Playbookjobs, with much more detail.

Both methods let you click on any individual job in the list to see that job's detailed execution progress panel, which displays the name of the Playbook, its plays, the devices it ran on, the parameters used, and all event, syslog, console and other messages. These details are useful when diagnosing failures.

The Job History window also allows you to abort running jobs.

Procedure

Step 1

From the main menu, select Change Automation > Dashboard. The Jobs panel at the upper right displays summary information for jobs that are running or have been recently run.

Step 2

To view information about a specific Playbook job in the Jobs panel, click the blue job title link in the Job column. The job's execution progress panel displays.

Step 3

To view information about all jobs:

- Click the View All Jobs link at the bottom of the Jobs panel.

- From the main menu, choose Change Automation > Job History

The Job History window opens with a table of detailed job information. The table data is sorted by the Last Update Time, with running or most recently executed jobs at the top. You can apply quick or advanced filters to the Playbook Title and Devices columns as you would with columns in other table windows (see Set, Sort and Filter Table Data).

Step 4

To view information about a specific Playbook job in the Job History window, click the relevant job ID checkbox on the left. in the Execution ID column. The job's status and execution details are displayed on the right side.

Step 5

With the Job History window displayed, you can abort running, paused or scheduled jobs, as follows:

- To abort a specific job, click the check box next to it and then click Abort Selected.

- To abort all jobs immediately, click Abort All.

When prompted, click Confirm. Jobs that are currently paused or scheduled will abort once the current task has run to completion.

About Customizing Playbooks

Users can download and customize Cisco-supplied Playbooks, or create their own based on Cisco models or from scratch.

Creating and modifying Playbooks are engineering tasks that take place outside of the user interface for Cisco Crosswork Change Automation and Health Insights. As such, they are outside the scope of this User Guide.

Cisco supplies developer-level documentation for Cisco-supplied Playbooks, Cisco verbs used in these Playbooks, and tutorials on how to create custom plays and Playbooks. For help, see the:

- "Playbooks" and "Verbs" references in the Change Automation Developer Guide on Cisco Devnet

- "Custom Playbooks" tutorial in the Change Automation Developer Guide on Cisco DevNet

- Playbook Components and Files

- Export Playbooks

- Import Playbooks

- Delete Custom Playbooks

Playbook Components and Files

Change Automation Playbooks contain a variety of components, referred to using specialized names. The components are implemented in the Playbook as files. Some of these components' names are borrowed from the Ansible specification, but all have their own definitions, and not all of the corresponding files can be customized by users. Some components are Cisco-proprietary intellectual property; while you can use them in custom Plays and Playbooks, you cannot customize them directly. The following table explains the function of each of these components, explains how they are implemented, and shows which of them you can customize.

Playbook Components and Files

Component

Description

File/Format

Customizable?

Play

A play is a single task to be executed. A task is a list of actions to be performed in service of that play. A play is typically a script that uses one or more verbs.

YAML/YML in the Playbook file

Yes

Playbook

A Playbook is an aggregation of one or more plays, and is structured by the plays it contains. There can be many plays inside a Playbook. The function of a Playbook is to map a set of actions onto the features of a particular host. For example: A query and configuration change script with abstract variables that can be mapped to a particular instance of a device. For more details, see the "Playbooks" and "Verbs" references in the Change Automation Developer Guide on Cisco Devnet.

YAML/YML file

Yes

Verb

A verb is a Cisco-supplied module that extends the Ansible module library. Like Ansible modules, each Cisco verb is a modularized unit of activity. These are Cisco intellectual property, supplied as object code, used under license and not modifiable by users. For more on Cisco verbs and how to use them, see the "Custom Playbooks" tutorial in the Change Automation Developer Guide on Cisco DevNet.

Binary executable file

No

Params

Params are simply variables, used in Playbooks just as variables are used in any programming language. A Params file in a Playbook is an optional file that collects all the user-defined input variables in one place. It is optional because all these variables are also in the plays.

JSON file

Yes

Specs

Short for "specifications", specs are Cisco verb-specific object files, written in JSON schema format. They define all the Playbook input parameters and their constraints.

JSON Schema file

Yes

Tags

Tags are predefined phases of execution for plays within a Playbook, and define the order of execution of all plays:

- Continuous

- Pre-Maintenance

- Maintenance

- Post-Maintenance

Any play tagged as Continuous or Pre-Maintenance runs in parallel with other plays with the same tags. All plays tagged as Maintenance or Post-Maintenance run serially. These tags are Cisco intellectual property, used under license and not modifiable by users.

Binary Executable files

No, but you select from the predefined tag set.

Role

A role is a built-in Ansible wrapper for Cisco’s verbs. These files are Cisco intellectual property, used under license and not modifiable by users.

YAML/YML file

No

Export Playbooks

You can export any Playbook as a gzipped tar archive. This includes any Cisco-supplied Playbook, as well as custom Playbooks that you or another party have authored and have imported into Cisco Crosswork Change Automation and Health Insights.

The exported archive will contain only the user-customizable files listed in Playbook Components and Files. Once you extract them from the archive, you can identify the Playbook components by their file names and filename extensions. The filename will include the Playbook's unique ID (for example: router_config_bgp_rd.yaml for the Playbook YAML code). If files share the same filename extension, the filename will also include an indicator of the type of Playbook component it is (for example: router_config_bgp_rd_specs.json and router_config_bgp_rd_params.json for the Specs and Params files, respectively). For details on each Cisco-supplied Playbook and its components, see the "Playbooks" and "Verbs" references in the Change Automation Developer Guide on Cisco Devnet.

You can edit the exported files as needed, following the guidelines in the "Custom Playbooks" tutorial in the Change Automation Developer Guide on Cisco DevNet. You can then import them as explained in Import Playbooks.

You cannot re-import an exported Cisco-supplied Playbook with the same name as the original.

Your user ID must have Change Automation read permission to export Playbooks.

Procedure

Step 1

From the main menu, choose Change Automation > Playbook List.

Step 2

(Optional) In the Playbook List window, filter the table as needed (see ).

Step 3

Check the check boxes for the Playbooks you want to export. Check the check box at the top of the column to select all of the Playbooks for export.

Step 4

Click . Your browser will prompt you to select a path and the file name to use when saving the gzipped tar archive. Follow the prompts to save the file.

Import Playbooks

You can import any custom Playbook, provided it meets the following requirements:

- The Playbook files must be packaged as a gzipped tar archive.

- The archive must contain a Playbook YAML file and a Specs JSON file, at minimum.

- The archive file must have a unique name.

Cisco recommends that your imported archive also contain:

- An ASCII TXT file documenting the Playbook, its plays, and their input parameters.

- A Params JSON file.

The individual files included in the archive must meet the additional validation requirements described in the "Custom Playbooks" tutorial in the Change Automation Developer Guide on Cisco DevNet.

Note that you cannot overwrite a Cisco-provided Playbook. You can overwrite a custom Playbook. The system will warn you when you are about to overwrite a custom Playbook, but will not prevent you from doing so. Take precautions to ensure that you do not overwrite your custom Playbooks accidentally.

Your user ID must have Change Automation write permissions to import Playbooks.

Procedure

Step 1

From the main menu, choose Change Automation > Playbook List.

Step 2

Click . Your browser will prompt you to browse to and select the gzipped archive file containing the Playbooks you want to import.

Make sure there is no existing Playbook with the same name as the Playbook you intent to import, unless it is your intent to overwrite the existing Playbook.

Step 3

Follow the prompts to import the archive file.

Delete Custom Playbooks

You can delete user-defined Playbooks only. You cannot delete a Cisco-supplied Playbook.

Your user ID must have Change Automation delete permission to delete Playbooks.

Procedure

Step 1

From the main menu, choose Change Automation > Playbooks List.

Step 2

In the Playbooks List window, select the custom Playbook that you want to delete

Step 3

Click Delete.

Step 4

Click Delete again to confirm.

Troubleshoot Change Automation

The following table describes issues you may encounter when using the Change Automation application, and their solutions or workarounds.

Change Automation Troubleshooting

Issue

Solution

Playbook run fails with messages indicating that Cisco Network Services Orchestrator (Cisco NSO) and the target device are out of sync or otherwise out of communication. Message text will vary, but may include "device out of sync", "NC client timeout", and other text indicating that there are connectivity or sync issues between Cisco NSO and the device.

Run the Playbook again. Under normal circumstances, doing so will initiate a sync operation between the device and NSO.

"Failed to end NSO transaction, 500:fatal:YClientError: Failed to send RPC:" error is displayed while running the playbook.

Include the below settings in the Cisco NSO configuration file (ncs.conf):

<ssh>
<client-alive-interval>infinity</client-alive-interval>
<client-alive-count-max>5</client-alive-count-max>
</ssh>

Playbook aborted due to failure in locking the device nodes.

In the Devices window, select the relevant devices and clear the lock by moving the device to DOWN and then UP. Go to Admin > Crosswork Manager, and restart the robot-nca process. Once the protocols are reachable, you can schedule to run a new playbook.

Chapter 4. Manage Inventory

This section contains the following topics:

- Inventory Management Overview

- Reachability and Operational State

- Manage Credential Profiles

- Manage Providers

- Manage Devices

- Manage Tags

Inventory Management Overview

The Inventory Management application lets you create, edit, and delete:

- The credential profiles that control Cisco Crosswork Change Automation and Health Insights's access to devices and providers. See Manage Credential Profiles.

- The providers who supply special services, such as device configuration, data storage, or alert processing, to Cisco Crosswork Change Automation and Health Insights. See Manage Providers.

- The devices you manage using Cisco Crosswork Change Automation and Health Insights. See Manage Devices.

- The tags you use to sort and group devices. See Manage Tags.

You can also use Inventory Management to review the jobs executed on your devices. See View Device Job History.

Reachability and Operational State

Cisco Crosswork Change Automation and Health Insights computes the Reachability State of the providers it uses and devices it manages, as well as the Operational State of reachable managed devices. It indicates these states using the icons in the following table.

Reachability and Operational State Icons

This Icon...

Indicates...

Reachability State icons show whether a device or a provider is reachable or not

Reachable: The device or provider can be reached by all configured protocols configured for it.

Reachability Degraded: The device or provider can be reached by at least one protocol, but is not reachable by one or more of the other protocols configured for it.

Unreachable: The device or provider cannot be reached by reachable by any protocol configured for it.

Reachability Unknown: Cisco Crosswork Change Automation and Health Insights cannot determine if the device is reachable, degraded, or unreachable . This state can also occur if the device is not connected to Cisco Crosswork Data Gateway.

Operational State icons show whether a device is operational or not.

The device is operational and under management, and all individual protocols are "OK" ( also known as "up").

The device is not operational ("down"). The same icon is used when the device has been set "administratively down" by an operator.

The device's operational or configuration state is unknown.

The device's operational or configuration state is degraded.

The device's operational or configuration state is in an error condition. It is either not up, or unreachable, or both, due to errors encountered while attempting to reach it and compute its operational state. The number in the circle shown next to the icon indicates the number of recent errors. Click on the number to see a list of these errors. (Note that the icon badging for errors is not available in the Network Visualization application.)

The device's operational state is currently being checked

The device is being deleted.

The device is unmanaged.

The Reachability State of a device is computed as follows:

1. Reachability is always computed for each device as long as the device's configured state (as configured by users) is UP. It is not computed if the device is administratively DOWN or UNMANAGED.

2. Reachability state is always either REACHABLE, UNREACHABLE, or UNKNOWN.

- The Reachability state is REACHABLE if there is at least one route to the device via at least one protocol AND the device is discoverable.

- The Reachability state is UNREACHABLE if there are no routes to the device via one protocol OR the device does not respond.

- The Reachability state is UNKNOWN if the device is UNMANAGED.

The Operational State of a device is computed as follows:

1. Operational state is always computed for each device as long as the device's configured state (as configured by users) is UP. It is not computed if the device is administratively DOWN or UNMANAGED.

2. Operational state is always OK or ERROR.

3. For a device to be Operational=OK, the device must be REACHABLE and discoverable. Any other Reachability state is ERROR.

4. For XR or XE devices only, Operational=OK also requires that Clock Drift difference between the Crosswork host and device clocks is <=the default Drift Value, currently 2 minutes.

Note

Confirm that devices have Telnet/SSH enabled. If it is not enabled, the Clock Drift throws an error and the operational state will always show a clock synchronization error.

Manage Credential Profiles

Credential profiles are collections of credentials for SNMP, Telnet/SSH, HTTP, and other network protocols. You can have multiple protocols and credentials in a single credential profile.

Using credential profiles lets you automate device configuration changes and monitoring, and communicate with providers. When you add or import devices, or create providers, you specify the credential profile(s) those devices and providers use.

Note

Credentials just validates authentication since the corresponding protocol configured on the devices does the work. Devices should be present in the Devices window and be reachable.

From the Credential Profiles window, you can create a new credential profile, update the settings configured for an existing profile, or delete a profile. To open this window, choose Inventory Management > Credential Profiles from the main menu.

Credentials Profile window

Item

Description

1

Click to add a credential profile. See Create Credential Profiles.

Click to edit the settings for the selected credential profile. See Edit Credential Profiles.

Click to delete the selected credential profile. See Delete Credential Profiles.

Click to import new credential profiles from a CSV file. You can also download a CSV file template by clicking this icon. The template includes sample data that you can use as a guide for building your own CSV file. See Import Credential Profiles.

Click to export credential profiles to a CSV file. See Export Credential Profiles.

2

Click to refresh the Credential Profiles window.

Click to choose the columns to make visible in the Credential Profiles window (see Set, Sort and Filter Table Data).

3

Click to set filter criteria on one or more columns in the Credential Profiles window.

Click the Clear Filter link to clear any filter criteria you may have set.

- Create Credential Profiles

- Import Credential Profiles

- Edit Credential Profiles

- Delete Credential Profiles

- Export Credential Profiles

- Change a Device's Credential Profile

- Change the Credential Profile for Multiple Devices

Create Credential Profiles

Follow the steps below to create a new credential profile. You can then use the profile to apply credentials consistently when you add new devices or providers. You can add as many protocols and corresponding credentials to the profile as you want.

If you have many credential profiles to add, you may find it more efficient to put the information in a CSV file and import the file. See Import Credential Profiles.

When creating device credential profiles that contain SNMP credentials, Cisco recommends that the profile contain credentials for the version of SNMP actually enabled on the device, and that version only. For example: If SNMPv3 is not enabled in the device configuration, do not include SNMPv3 credentials in the device credential profile.

If you plan to use the import and export features and CSV files to create credential profiles in bulk, please note that:

- All the characters in each password or community string entry in every credential profile exported to a CSV file are replaced with asterisks (Export Credential Profiles).

- You cannot import credential profiles if the passwords and community strings in the CSV file are blank (see Import Credential Profiles).

To maintain network security, Cisco recommends that you use asterisks in place of real passwords and community strings in any CSV file you plan to import. After the import, follow the steps in Edit Credential Profiles to replace the asterisks with actual passwords and community strings.

Procedure

Step 1

From the main menu, choose Inventory Management > Credential Profiles.

Step 2

Click .

Step 3

In the Profile Name field, enter a descriptive profile name. The name can contain a maximum of 128 alphanumeric characters, plus underscores ("_") or hyphens ("-"). No other special characters are allowed.

If you will have many credential profiles, make the name as informative as possible because that information will be displayed on the Credential Profiles panel.

Step 4

Select a protocol from the Connectivity Type dropdown.

Step 5

Complete the credentials fields described in the following table. The required and optional fields displayed will vary with the connectivity type you chose. The values you enter must match the values configured on the device.

Connectivity Type

Fields

SSH

Enter the required User Name, Password, and Confirm Password. The Enable Password is optional.

SNMPv2

Enter the required SNMPv2 Read Community string. The Write Community string is optional.

NETCONF

Enter the required User Name, Password, and Confirm Password.

TELNET

Enter the required User Name, Password, and Confirm Password. The Enable Password is optional.

HTTP

Enter the required User Name, Password, and Confirm Password.

HTTPS

Enter the required User Name, Password, and Confirm Password.

GRPC

Enter the required User Name, Password, and Confirm Password.

SNMPv3

Choose the required Security Level and enter the User Name.

If you chose the NO_AUTH_NO_PRIV Security Level of AUTH_NO_PRIV or AUTH_PRIV, the remaining fields are optional.

If you chose the AUTH_NO_PRIV Security Level, you must choose an Auth Type and enter an Auth Password.

If you chose the AUTH_PRIV Security Level, you must choose an Auth Type and Priv Type, and enter an Auth Password and Priv Password.

Only the following SNMPv3 Privacy Types are supported

- CFB_AES_128

- CBC_DES_56

The following Privacy Types are not supported:

- AES192

- AES256

- 3DES

Step 6

(Optional) Click + Add Another and repeat the above steps, as needed, for all other protocols and corresponding credentials you want to add to this credential profile.

Step 7

Click Save.

Import Credential Profiles

Complete the steps below to create a CSV file that specifies multiple credential profiles and then import it into Cisco Crosswork Change Automation and Health Insights.

Importing credential profiles from a CSV file adds any profiles not already in the database. You cannot import a credential profile that already exists.

If you are re-importing a credential profile CSV file that you previously exported and modified, remember that all the passwords and community strings in the exported credential profile CSV file are replaced with asterisks. You cannot re-import an exported credential profile CSV file with blank passwords. To maintain security, Cisco recommends that you use asterisks in place of real passwords and community strings in the CSV file. After the import, follow the steps in Edit Credential Profiles to replace the asterisks with actual passwords and community strings.

Procedure

Step 1

From the main menu, choose Inventory Management > Credential Profiles.

Step 2

Click to open the Import CSV File dialog box.

Step 3

If you have not already created a credential profile CSV file to import:

1. Click the Download sample 'Credential template (*.csv)' file link and save the CSV file template to your local disk.

2. Open the template using your preferred tool. Begin adding rows to the file, one row for each credential profile.

Use a semicolon to separate multiple entries in the same field. Use two semicolons with no space between them to indicate that you are leaving the field blank. When you separate multiple entries with semicolons, remember that the order in which you enter values in each field is important. For example, if you enter SSH;NETCONF;TELNET in the Connectivity Type field and you enter UserTom;UserDick;UserHarry; in the User Name field, the order of entry determines the mapping between the two fields:

- SSH: UserTom

- NETCONF: UserDick

- TELNET: UserHarry

Also note:

- Be sure to enter SNMP community string information exactly as currently entered on your devices. Failure to do so may result in loss of device connectivity, and inability to collect certain KPI data or execute configured Playbooks on devices associated with the credential profile.

- Password and community string information associated with a user ID are stored in plain text in the CSV file you prepare. Be aware of the security implications of this, and apply appropriate safeguards.

Field

Entries

Required or Optional

Credential Profile

The name of the credential profile. For example: nso.

Required

Connectivity Type

Valid values are: SSH, SNMPv2, NETCONF, TELNET, HTTP, HTTPS, GRPC or SNMPv3

Required

User Name

For example: NSOUser

Required if Connectivity Type is SSH, NETCONF, TELNET, HTTP, HTTPS, SNMPv3 or GRPC.

Password

The password for the preceding User Name.

Required if Connectivity Type is SSH, NETCONF, TELNET, HTTP, HTTPS or GRPC

Enable Password

Use an Enable password. Valid values are: ENABLE, DISABLE

Required if Connectivity Type is SSH or TELNET. Otherwise leave blank.

Enable Password Value

Specify the Enable password to use.

Required if Connectivity Type is SSH or TELNET and Enable Password is set to ENABLE. Otherwise leave blank.

SnmpV2 Read Community

For example: readprivate

Required if Connectivity Type is SNMPv2

SnmpV2 Write Community

For example: writeprivate

Required if Connectivity Type is SNMPv2

SnmpV3 User Name

For example: DemoUser

Required if Connectivity Type is SNMPv3

SnmpV3 Security Level

Valid values are noAuthNoPriv, AuthNoPriv or AuthPriv

Required if Connectivity Type is SNMPv3

SnmpV3 Auth Type

Valid values are HMAC_MD5 or HMAC_SHA

Required if Connectivity Type is SNMPv3 and SnmpV3 Security Level is AuthNoPriv or AuthPriv

SnmpV3 Auth Password

The password for this authorization type.

Required if Connectivity Type is SNMPv3 and SnmpV3 Security Level is AuthNoPriv or AuthPriv

SnmpV3 Priv Type

Valid values are CFB_AES_128 or CBC_DES_56

The following SNMPv3 privacy types are not supported: AES192, AES256, 3DES

Required if Connectivity Type is SNMPv3 and SnmpV3 Security Level is AuthPriv

SnmpV3 Priv Password

The password for this privilege type.

Required if Connectivity Type is SNMPv3 and SnmpV3 Security Level is AuthPriv

Be sure to delete the sample data rows before saving the file or they will be imported along with the data you want. The column header row can stay, as it is ignored during import.

3. When you are finished, save the new CSV file.

Step 4

Click Browse to navigate to the CSV file you just created and then click Open to select it.

Step 5

With the CSV file selected, click Import.

The credential profiles you imported should now be displayed in the Devices window.

Edit Credential Profiles

A credential profile can be shared by multiple devices, even hundreds of devices in a large network. Complete the following procedure to edit credential profile settings.

Warning

Changing the settings in a credential profile without first changing the settings on the device associated with the profile may result in a loss of connectivity, inability to collect certain KPI data, or an inability to execute configured playbooks on devices associated with the modified profile. For example: If the SNMP community string on the device no longer matches what is in the credential profile, SNMP-based KPIs will not function.

Before editing any credential profile, it is always good practice to export a CSV backup of the profiles you want to change (see Export Credential Profiles).

Procedure

Step 1

From the main menu, choose Inventory Management > Credential Profiles.

Step 2

From the left-hand side of the Credential Profiles window, select the profile you want to update, and click .

The Edit Profile window of the selected credential is displayed.

Step 3

Make the necessary changes and then click Save.

Delete Credential Profiles

Follow the steps below to delete a credential profile.

Note

You cannot delete a credential profile that is associated with one or more devices or providers.

Procedure

Step 1

Export a backup CSV file containing the credential profile you plan to delete (see Export Credential Profiles).

Step 2

Check whether any devices or providers are using the credential profile you plan to delete. You can do this by filtering on the Credential Profile column, which is available on both the Devices window (choose Inventory Management > Credential Profiles) and the Providers window (choose Inventory Management > Providers).

Step 3

Reassign the devices or providers to a different credential profile (for help with this task, see Change a Device's Credential Profile or Change the Credential Profile for Multiple Devices, and Edit Providers).

Step 4

After all devices and providers have had their credential profiles reassigned: From the main menu, choose Inventory Management > Credential Profiles.

Step 5

In the Credential Profiles window, choose the profile that you want to delete and then click .

Export Credential Profiles

Exporting credential profiles stores all the profiles you selected in a CSV file. This is a quick way to make backup copies of your credential profiles. You can also edit the CSV file as needed, and re-import it to add new credential profile data. You cannot overwrite existing credential profiles by importing a CSV file.

The exported credential profiles CSV file does not contain real passwords or community strings. All the characters in the passwords and community strings entries in the credential profiles are replaced with asterisks in the exported CSV file. If you plan on modifying your exported CSV file and then re-importing it, Cisco recommends that you use asterisks in place of real passwords and community strings. After the import, follow the steps in Edit Credential Profiles to replace the asterisks with actual passwords and community strings.

Procedure

Step 1

From the main menu, choose Inventory Management > Credential Profiles.

Step 2

(Optional) In the Credential Profiles window, filter the credential profile list as needed.

Step 3

Check the check boxes for the profiles you want to export. Check the check box at the top of the column to select all the profiles for export.

Step 4

Click . Depending on your browser, you will be prompted to select a path and file name to use when saving the CSV file, or to open it immediately

Change a Device's Credential Profile

You can edit device information, including changing the credential profile in the device record. This operation changes an existing association between a device and a credential profile.

Before you begin

You need a credential profile to complete this task. To create a credential profile, see Create Credential Profiles.

Note

Make sure the profile’s credential settings are correct before following this procedure.

Procedure

Step 1

From the main menu, choose Inventory Management > Devices.

Step 2

(Optional) In the Devices window, filter the device list by entering text in the Search field or filtering specific columns.

Step 3

Check the check box of the device you want to change, and click .

Step 4

Choose a different credential profile from the Credential Profile drop-down list.

Step 5

Click Save.

After the device record is updated, the system attempts to communicate with the device using the new profile. Confirm that the device is reachable without any errors.

Change the Credential Profile for Multiple Devices

If you want to change the credential profile for a large number of devices, you may find it more efficient to make the change by editing a devices CSV file. The basic method is:

1. Export a CSV file containing the devices whose credential profiles you want to change (see Export Devices).

2. Edit the CSV file, changing the credential profile for each device (this credential profile must already exist). Save the edited file.

3. Import the edited devices CSV file using the Update Existing option. You will overwrite the credential profile data for each device (see Import Devices).

You will need to make sure that the credential profile to which you are changing already exists. If you have not yet created that credential profile, the CSV import will fail. The credential profile you associate with these devices must also have the authorization credentials for every protocol that was configured for these devices during onboarding. If any credential for a specific protocol configured on the devices is missing from or incorrect in the credential profile, then the CSV import will succeed, but reachability checks will fail for these devices.

Procedure

Step 1

From the main menu, choose Inventory Management > Devices.

Step 2

In the Devices window, choose the devices whose credential profiles you want to change. Your options are:

- Click to include all devices.

- Filter the device list by entering text in the Search field or by filtering specific columns. Then click to include only the filtered list of devices.

- Check the boxes next to the device records you want to change. Then click to include only the devices that have been checked.

Step 3

Edit and save the new CSV file using the tool of your choice. Be sure to enter the correct credential profile name in the Credential Profile field for each device.

Step 4

In the Devices window, click .

Step 5

In the Import dialog box, click Browse, choose the new CSV file, and click Import.

Manage Providers

Cisco Crosswork Change Automation and Health Insights communicates with external providers. You decide which providers you will use and then configure them. Cisco Crosswork Change Automation and Health Insights stores the provider connectivity details and makes that information available to applications.

From the Providers window, you can add a new provider, update the settings configured for an existing provider, and delete a particular provider. To open this window, choose Inventory Management > Providers.

Providers window

Item

Description

1

The icon shown next to the provider in this column indicates the provider's Reachability. For more on the icons and how reachability is determined, see Reachability and Operational State.

2

Click to add a provider. See About Adding Providers.

Click to edit the settings for the selected provider. See Edit Providers.

Click to delete the selected provider. See Delete Providers.

Click to import new providers or update existing providers from a CSV file. You can also download a CSV file template by clicking this icon. The template includes sample data that you can use as a guide for building your own CSV file. See Import Providers.

Click to export a provider to a CSV file. See Export Providers.

3

Click next to the provider in the Provider Name column to open the Properties for pop-up window, showing the details of any startup session key/value pairs for the provider.

4

Click next to the provider in the Connectivity Type column to open the Connectivity Details pop-up window, showing the protocol, IP and other connection information for the provider.

5

Click to refresh the Providers window.

Click to choose the columns to make visible in the Providers window (see Set, Sort and Filter Table Data).

6

Click to set filter criteria on one or more columns in the Providers window.

Click the Clear Filter link to clear any filter criteria you may have set.

7

Click next to the provider in the Model Prefix column to open the Supported Models pop-up window, showing a list of the model prefix names and versions in use (for Cisco NSO providers only).

- About Provider Families

- About Adding Providers

- Get Provider Details

- Edit Providers

- Delete Providers

- Export Providers

About Provider Families

Cisco Crosswork Change Automation and Health Insights supports different types, or families, of providers. Each provider family supplies its own mix of special services to Cisco Crosswork Change Automation and Health Insights, and each comes with unique requirements and options.

The currently supported provider families are shown in the following table.

Supported Provider Families

Provider Family

Description

NSO

Instances of Cisco Network Services Orchestrator (Cisco NSO), used to configure network devices. See Add Cisco NSO Providers.

WAE

Instances of Cisco WAN Automation Engine (Cisco WAE) provide "what if" analysis used to evaluate network changes as part of Cisco Crosswork Change Automation and Health Insights Playbooks. See Add Cisco WAE Providers.

SR-PCE

Instances of Cisco Segment Routing Path Computation Elements (Cisco SR-PCE) containing the configuration information needed to allow Cisco Crosswork Change Automation and Health Insights to communicate with and retrieve segment routing information for the network. See Add Cisco SR-PCE Providers.

Syslog Storage

Instances of storage servers (remote or on the Cisco Crosswork Change Automation and Health Insights VM itself) where you want store syslogs and other data retrieved from devices by KPIs and Playbooks. See Add Syslog Storage Providers.

Alert

Instances of providers (such as Cisco Crosswork Situation Manager) to which alerts collected during KPI monitoring are to be forwarded. See Add an Alert Provider

About Adding Providers

Cisco Crosswork Change Automation and Health Insights depends on a variety of providers to perform various functions. For example, Cisco Network Services Orchestrator provides device and routing information. Features that depend on new providers may be added in the future, and you may need to communicate with more than one instance of a single provider. Also, not every Cisco Crosswork Change Automation and Health Insights deployment will use the same mix of providers. In any case, to access each provider's services, the provider must be added to the Cisco Crosswork Change Automation and Health Insights system configuration.

There are two ways to add providers:

1. Adding providers via the UI: This method is explained in Add Providers Through the UI. Although this method is the most time-consuming, it is more often used because most deployments will not need a lot of separate providers or provider instances.

2. Importing providers from a providers CSV file: This method is explained in Import Providers. Importing a CSV file is useful when you have a lot of separate providers or provider instances to add or update at one time.

Note that both methods require that you:

- Create a corresponding credential profile, beforehand, so that Cisco Crosswork Change Automation and Health Insights can access the provider. For help, see Create Credential Profiles.

- Know the protocol, IP address, port number, and other information needed to connect with the provider.

- Know any special properties the provider may require during the session startup.

For help on adding the most common providers using the UI, see the following topics.

- Add Providers Through the UI

- Import Providers

- Add Cisco NSO Providers

- Add Cisco SR-PCE Providers

- Add Cisco WAE Providers

- Add Syslog Storage Providers

- Add an Alert Provider

Add Providers Through the UI

Use this procedure to add a new external provider. You can then map the provider to devices.

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click .

Step 3

Enter values for the provider as listed in the following table.

Step 4

When you have complete entries in all of the required fields, click Save to add the new provider.

Step 5

(Optional) Repeat to add more providers.

Add Provider Fields (*=required)

Field

Description

* Provider Name

The name for the provider that will be used to refer to it in Cisco Crosswork Change Automation and Health Insights. For example: MyWAE. The name can contain a maximum of 128 alphanumeric characters, plus underscores ("_") or hyphens ("-"). No other special characters are allowed.

* Credential Profile

Select the name of the credential profile that Cisco Crosswork Change Automation and Health Insights will use to connect to the provider.

* Family

Select the provider family. Choices are: NSO, WAE, SR-PCE, ALERT and SYSLOG_STORAGE.

* Device Key

Select the method that the Cisco NSO provider uses to identify devices uniquely. This will serve as the way Cisco Crosswork Change Automation and Health Insights maps the device in its own inventory to the device as it is stored in the Cisco NSO provider. Choices are:

- NODE_IP—Use this value if the device identifier Cisco NSO uses is the IP address.

- INVENTORY_ID—Use this value if the device identifier Cisco NSO uses is the inventory ID.

- HOST_NAME—If Cisco NSO uses the device hostname as the device identifier, this value must match the hostname that is specified for the device in the inventory.

Note that the Device Key is only required for the Cisco NSO provider. It is not needed for other providers.

Connection Type(s)

* Protocol

Select the principal protocol that Cisco Crosswork Change Automation and Health Insights will use to connect to the provider. Options include: HTTP, HTTPS, SSH, SNMP, NETCONF, TELNET, and more.

To add more connectivity protocols for this provider, click at the end of the first row. To delete a protocol you have entered, click shown next to that row.

You can enter as many sets of connectivity details as you want, including multiple sets for the same protocol.

* IP Address/ Subnet Mask

Enter the IP address (IPv4 or IPv6) and subnet mask of the provider's server.

* Port

Enter the port number to use to connect to the provider's server. This is the port corresponding to the protocol being configured. For example, if the protocol used to communicate with the provider server is SSH, the port number is usually 22.

Timeout

Enter the amount of time (in seconds) to wait before the connection times out. The default is 30 seconds.

Model Prefix Info

* Model

Required only if you are adding a Cisco NSO provider: Select the model prefix that matches the NED CLI used by Cisco NSO. Valid values are:

Cisco-IOS-XR

Cisco-NX-OS

Cisco-IOS-XE

For telemetry, only Cisco-IOS-XR is supported.

To add more model prefix information for this Cisco NSO provider, click the at the end of any row in the Model Prefix Info section. To delete a model prefix you have entered, click the shown next to that row.

* Version

Required only if you are adding a Cisco NSO provider: Enter the Cisco NSO NED driver version used on the NSO server.

Provider Properties

Property Key

Enter the name of the key for the special provider property you want to configure.

Provider properties control how Cisco Crosswork Change Automation and Health Insights interacts with the provider. Not all providers need them, and the number and type of properties vary with the provider family. These properties are documented in topics about adding specific providers elsewhere in this Guide. Please note, however, that Cisco Crosswork Change Automation and Health Insights does not validate provider properties. Make sure the properties you enter are valid for the provider.

Property Value

Enter the value to assign to the property key.

To add more special properties for this provider, click at the end of any key/value pair in the Provider Properties section. To delete a key/value pair you have entered, click shown next to that pair.

Import Providers

Complete the steps below to create a CSV file that specifies providers and then import it into Cisco Crosswork Change Automation and Health Insights.

Importing providers from a CSV file adds any providers not already in the database, and updates any providers with the same name as an imported provider. For this reason, it is a good idea to export a backup copy of all your current providers before an import (see Export Providers).

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click to open the Import CSV File dialog box.

Step 3

If you have not already created a provider CSV file to import:

1. Click the Download sample 'Provider template (*.csv)' file link and save the CSV file template to a local storage resource.

2. Open the template using your preferred tool. Begin adding rows to the file, one row for each provider.

Use a semicolon to separate multiple entries in the same field. Use two semicolons with no space between them to indicate that you are leaving the field blank. When you separate entries with semicolons, the order in which you enter values is important. For example, if you enter SSH;SNMP;NETCONF;TELNET in the connectivity_type field and you enter 22;161;830;23 in the connectivity_port field, the order of entry determines the mapping between the two fields:

- SSH: port 22

- SNMP: port 161

- NETCONF: port 830

- Telnet: port 23

Field

Description

Required or Optional

Provider Name

Enter the name for the provider that will be used in Cisco Crosswork Change Automation and Health Insights. For example: MyWAE.

Required

Connectivity Type

Enter the name of the protocol that Cisco Crosswork Change Automation and Health Insights will use to connect to the provider. Valid values are: ROBOT_MSVC_TRANS_TCP, ROBOT_MSVC_TRANS_UDP, ROBOT_MSVC_TRANS_HTTP, ROBOT_MSVC_TRANS_HTTPS, ROBOT_MSVC_TRANS_GRPC, ROBOT_MSVC_TRANS_SSH, ROBOT_MSVC_TRANS_NETCONF, ROBOT_MSVC_TRANS_TELNET, ROBOT_MSVC_TRANS_SNMP, ROBOT_MSVC_TRANS_TL1, ROBOT_MSVC_TRANS_TL1_SECURE, ROBOT_MSVC_TRANS_ICMP, ROBOT_MSVC_TRANS_KAFKA, ROBOT_MSVC_TRANS_NATS.

Required

Connectivity IP

Enter the IP address (IPv4 or IPv6) of the provider.

Required

Connectivity Port

Enter the port number to use to connect to the provider's server.

Required

Connectivity Timeout

Enter the amount of time (in seconds) to wait before the connection to the provider times out. The default is 30 seconds.

Required

Credential Profile

Enter the name of the credential profile that Cisco Crosswork Change Automation and Health Insights will use to connect to the provider. This profile must already exist in the system.

Required

Provider Device Key

Enter the enum value corresponding to the key that the Cisco NSO provider uses to identify devices uniquely. This will serve as the way Cisco Crosswork Change Automation and Health Insights maps the device to the Cisco NSO provider. Valid values are:

- ROBOT_PROVDEVKEY_HOST_NAME—If you are using the device hostname as the device ID within NSO, this value must match the hostname that is specified for the device in the inventory.

- ROBOT_PROVDEVKEY_NODE_IP—Use this enum value if the NSO device identifier is the IP address for the Node IP value in the CSV file.

- ROBOT_PROVDEVKEY_INVENTORY_ID—Use this enum value if the inventory ID is the device identifier for NSO.

This entry is only required if you are creating or updating a Cisco NSO provider.

Required

Family

Enter the provider family. Valid entries are: WAE, SYSLOG_STORAGE, ALERT, SR_PCE, and NSO.

Required

Model Prefix

If you are adding a Cisco NSO provider: Select the model prefix that matches the NED CLI used by the NSO server. Valid entries are: Cisco-IOS-XR, Cisco-NX-OS, Cisco-IOS-XE.

For telemetry, only Cisco-IOS-XR is supported.

Required for Cisco NSO providers only

Model Version

If you adding a Cisco NSO provider: Enter the Cisco NSO NED driver version used on the

Required for Cisco NSO only

server (should be 6.0.4).

Required for Cisco NSO providers only

Properties

Enter the name of the key for the special provider property you want to configure.

See the documentation on adding individual providers for property key/value requirements. Cisco Crosswork Change Automation and Health Insights does not validate provider property key names or values. Make sure the properties you enter are valid for the provider.

Required for some providers, otherwise optional

Be sure to delete the sample data rows before saving the file, or they will be imported along with the data you want. The column header row can stay, as it is ignored during import.

3. When you are finished, save the new CSV file.

Step 4

Click Browse to navigate to the CSV file you just created and then click Open to select it.

Step 5

With the CSV file selected, click Import.

The provider information you imported should now be displayed in the Providers window.

Step 6

Resolve any errors reported during the import and check provider details to confirm connection.

Add Cisco NSO Providers

Cisco Network Services Orchestrator (Cisco NSO) providers supply device management and configuration maintenance services to Cisco Crosswork Change Automation and Health Insights.

Follow the steps below to add (through the UI) one or more instances of Cisco NSO as providers for Cisco Crosswork Change Automation and Health Insights. You can also add providers using CSV files (see Import Providers).

Before you begin

You will need to:

- Create a credential profile for the Cisco NSO provider (see Create Credential Profiles).

Know the name you want to assign to the Cisco NSO provider.

- Know the Cisco NSO NED device models and driver versions used in your topology.

- Know the Cisco NSO server IP address and hostname.

- Confirm Cisco NSO device configurations (see Sample Configuration for Devices in Cisco NSO).

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click .

Step 3

Enter the following values for the Cisco NSO provider fields:

1. Required fields:

- Provider Name: Enter a name for the provider that will be used in Cisco Crosswork Change Automation and Health Insights.

- Credential Profile: Select the previously created Cisco NSO credential profile.

- Family: Select NSO only.

- Protocol: Select NETCONF only.

- Device Key: Select the method that Cisco NSO uses to identify devices uniquely. This will serve as the way Cisco Crosswork Change Automation and Health Insights maps the device to Cisco NSO. Choices are: NONE, NODE_IP, INVENTORY_ID, or HOST_NAME.

- IP Address/Subnet Mask: Enter the IP address (IPv4 or IPv6) and subnet mask of the Cisco NSO server.

- Port: Enter the port to use to connect to the Cisco NSO server. The default is 2022.

- Model: Select the model (Cisco-IOS-XR, Cisco-NX-OS, or Cisco-IOS-XE) from the drop-down list and enter its associated NED driver version. Add a model for each type of device that will be used in the topology. If you have more than one, select to add another supported model.

- Version: Enter the Cisco NSO NED driver version used on the NSO server.

For more information on fields, see Import Providers.

2. Optional values:

- Timeout: The amount of time (in seconds) to wait before timing out the connection to the Cisco NSO server. The default is 30 seconds.

Step 4

When you have completed entries in all of the required fields, click Save to add Cisco NSO as a provider.

Add Cisco SR-PCE Providers

Cisco Segment Routing Path Computation Elements (Cisco SR-PCE) providers supply device discovery, management, configuration-maintenance and route-calculation services to Cisco Crosswork Change Automation and Health Insights. At least one SR-PCE provider is required in order to learn and discover SR policies, Layer 3 links, and devices that are part of the topology using XR Topology Controller (XTC).

Follow the steps below to add (through the UI) one or more instances of Cisco SR-PCE as providers for Cisco Crosswork Change Automation and Health Insights.

Before you begin

You will need to:

- Create a credential profile for the Cisco SR-PCE provider (see Create Credential Profiles). This should be a basic HTTP text-authentication credential (currently, MD5 authentication is not supported). If the Cisco SR-PCE server you are adding does not require authentication, you must still supply a credential profile for the provider, but it can be any profile that does not use the HTTP protocol.

- Know the name you want to assign to the Cisco SR-PCE provider. This is usually the DNS hostname of the Cisco SR-PCE server.

- Know the Cisco SR-PCE server IP address.

- Determine whether you want to auto-onboard the devices that Cisco SR-PCE discovers and, if so, whether you want the new devices to have their management status set to managed or unmanaged when added. Your options, set using the Provider Properties fields, are as follows:

- auto-onboard is off: If you set these Provider Properties values, you will add or import devices manually. When Cisco SR-PCE discovers devices, the device data is recorded in the Cisco SR-PCE database, but is not registered in the Cisco Crosswork Change Automation and Health Insights Inventory Management database.

- auto-onboard is unmanaged: If you set these Provider Properties values, all devices that Cisco SR-PCE discovers will be registered in the Cisco Crosswork Change Automation and Health Insights Inventory Management database, with their configured state set to unmanaged. SNMP polling will be disabled for these devices, and no management IP information will be included. To get these devices into the managed state later, you will need to download them as a CSV file (see Export Devices), and modify the CSV file to add the SNMP and management IP address information. You can then update the auto-onboarded devices with this information by importing the modified CSV file (see Import Devices). You can also assign credential profiles by adding them to the device CSV file before import (the credential profiles must already exist).

- auto-onboard is managed: If you set these Provider Properties values, all devices that Cisco SR-PCE discovers will be registered in the Cisco Crosswork Change Automation and Health Insights Inventory Management database, with their configured state set to managed. Their connectivity IP addresses will be set to their router IDs, and SNMP polling will be enabled. For successful SNMP polling, you will have to correct the connectivity IP address. You can do this by editing the device, or use the device CSV import feature to correct it. You will also need to add a second Provider Properties key/value pair, with the key device-profile and the value being the name of an SNMP credential profile for the new devices.

- outgoing-interface: Cisco SR-PCE reachability can be established over management network by providing outgoing-interface and eth1 as the property key/value pair. If this property is set, a static route is installed on the Cisco Crosswork Change Automation and Health Insights pointing to the eth1 interface gateway. You can do this by editing the device or using the device CSV import feature to correct it.

- If you plan to auto-onboard devices that the Cisco SR-PCE provider discovers, and set them to a managed state when they are added to the database:

- Assign an existing credential profile for communication with the new managed devices.

- The credential profile must be configured with an SNMP protocol.

- For high availability, ensure that you set up two separate Cisco SR-PCE providers with unique names and IP addresses, but with matching configurations .

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click .

Step 3

Enter the following values for the Cisco SR-PCE provider fields:

1. Required fields:

- Provider Name: Name of the SR-PCE provider that will be used in Cisco Crosswork Change Automation and Health Insights.

- Credential Profile: Select the previously created Cisco SR-PCE credential profile.

- Family: Select SR_PCE. All other options should be ignored.

- Protocol: Select HTTP. All other options should be ignored.

- IP Address/ Subnet Mask: Enter the IP address (IPv4 or IPv6) and subnet mask of the server.

- Provider Properties: Enter one of the following key/value pairs in the first set of fields:

Property Key

Value

auto-onboard

off

auto-onboard

unmanaged

auto-onboard

managed

If you enter the auto-onboard/managed pair:

1. Click the next to the first set of fields to add a new set.

2. In the new Property Key field, enter device-profile.

3. In the new Property Value field, enter the name of a credential profile that contains SNMP credentials for all the new devices.

2. Optional value:

- Timeout: The amount of time (in seconds) to wait before timing out the connection to the SR-PCE server. The default is 30 seconds.

Step 4

When you have completed entries in all of the required fields, click Save to add the SR-PCE provider.

Step 5

Confirm that the SR-PCE provider shows a green Reachability status without any errors. You can also view the Events window to see if the provider has been configured correctly.

Note

It is not recommended to modify auto-onboard options (managed/unmanaged/off) once set. If you need to modify them, do the following:

1. Delete the provider and wait until deletion confirmation is displayed in the Events page.

2. Re-add the provider with the updated auto-onboard option.

3. Confirm the provider has been added with the correct auto-onboard option in the Events page.

Add Cisco WAE Providers

Cisco WAN Automation Engine (Cisco WAE) providers supply traffic and topology analysis to Cisco Crosswork Change Automation and Health Insights. The foundation software is Cisco WAE Planning, which provides a cross-sectional view of traffic, topology, and equipment state. It takes advantage of a predictive model that performs "what if" analysis of failure impacts.

Follow the steps below to use the UI to add one or more instances of Cisco WAE as providers. You can also add providers using CSV files (see About Adding Providers).

Before you begin

You will need to:

- Create a credential profile for the Cisco WAE provider (see Create Credential Profiles). This should be a basic HTTP/HTTPS text-authentication credential (currently, MD5 authentication is not supported). If the Cisco WAE server you are adding does not require authentication, you must still supply a credential profile for the provider, but it can be any profile that does not use the HTTP/HTTPS protocol.

- Know the name you want to assign to the provider. This is usually the DNS hostname of the Cisco WAE server.

- Know the Cisco WAE server IP address and port. The connection protocol will be HTTP or HTTPS.

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click .

Step 3

Enter the following values for the provider fields:

1. Required fields:

- Provider Name: Name of the Cisco WAE provider that will be used in Cisco Crosswork Change Automation and Health Insights.

- Credential Profile: Select the previously created credential profile.

- Family: Select WAE.

- Protocol: Select HTTP or HTTPS respectively as per the credential profile you are using.

- IP Address/ Subnet Mask: Enter the IP address (IPv4 or IPv6) and subnet mask of the server.

- Port: Enter the port number (usually, 8080 for HTTP, and 8083 for HTTPS).

2. Optional values:

- Timeout: The amount of time (in seconds) to wait before timing out the connection to the server. The default is 30 seconds.

Step 4

When you have completed entries in all of the required fields, click Save to add the provider.

Add Syslog Storage Providers

Storage providers supply storage for data collected during KPI monitoring, Playbook execution, and other operations (such as syslog storage).

Follow the steps below to use the UI to add one or more storage providers for Cisco Crosswork Change Automation and Health Insights. You can also add providers using CSV files (see About Adding Providers).

Before you begin

You will need to:

- Create a credential profile for the storage provider (see Create Credential Profiles). This should be an SSH or HTTPS credential, depending on the protocol you plan to use (SSH is recommended).

- Know the name you want to assign to the storage provider. This is usually the DNS hostname of the server.

- Know the storage provider's server IPv4 address and port. The connection protocol will be SSH or HTTPS.

- Know the destination directory on the storage provider's server. You will need to specify this using the Provider Properties fields.

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click .

Step 3

Enter the following values for the provider fields:

1. Required fields:

- Provider Name: Name of the storage provider that will be used in Cisco Crosswork Change Automation and Health Insights.

- Credential Profile: Select the previously created storage credential profile.

- Family: Select SYSLOG_STORAGE.

- Protocol: Select SSH or HTTPS.

- IP Address/ Subnet Mask: Enter the IP address (IPv4 or IPv6) and subnet mask of the server.

- Port: Enter the port number (usually, 22 for SSH or 443 for HTTPS).

- Provider Properties: Enter the following key/value pair in these fields:

Property Key

Property Value

DestinationDirectory

The absolute path where the collected data will be stored on the server. For example: /root/cw-syslogs

2. Optional values:

- Timeout: The amount of time (in seconds) to wait before timing out the connection to the storage server.

Step 4

When you have completed entries in all of the required fields, click Save to add the syslog storage provider.

Add an Alert Provider

An Alert provider is a destination to which you want to forward alerts collected during KPI monitoring (such as Cisco Crosswork Situation Manager). An alert provider must be capable of receiving and processing incoming alert packages.

Follow the steps below to use the UI to add an alert provider for Cisco Crosswork Change Automation and Health Insights. You can also add the alert provider by importing a CSV file (see About Adding Providers).

Currently, only one alert provider is supported.

Before you begin

You will need to:

- Create a credential profile for the alert provider (see Create Credential Profiles). This should be a basic HTTP text-authentication credential (currently, MD5 authentication is not supported). If the provider does not require authentication, you must still supply a credential profile for the provider, but it can be any profile that does not use the HTTP protocol.

- Know the name you want to assign to the alert provider. This is usually the DNS hostname of the server.

- Know the alert server IPv4 address and port. The connection protocol will be HTTP.

- Know the URL of the alert server endpoint. You will need to specify this using the Property Value field.

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

Click .

Step 3

Enter the following values for the provider fields:

1. Required fields:

- Provider Name: Name of the provider that will be used in Cisco Crosswork Change Automation and Health Insights.

- Credential Profile: Select the previously created alert provider credential profile.

- Family: Select ALERT.

- Protocol: HTTP is pre-selected.

- IP Address/ Subnet Mask: Enter the IP Address (IPv4 or IPv6) and subnet mask of the alert server.

- Port: Enter the port number (usually, 80 for HTTP).

- Provider Properties: The alertEndpointUrl property key name is pre-entered. In the Property Value field, enter the alert server endpoint only. For example, if the complete path to the endpoint is http://aws.amazon.com:80/myendpoint/bar1/, you would enter /myendpoint/bar1/ only.

2. Optional values:

- Timeout: The amount of time (in seconds) to wait before timing out the connection to the alert server.

Step 4

When you have completed entries in all of the required fields, click Save to add the alert provider.

Get Provider Details

Use the Providers window to get details about your providers and to check on their reachability.

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

For each provider configured in Cisco Crosswork Change Automation and Health Insights, the Providers window lists information such as the provider's name, universally unique identifier (UUID), associated credential profile, device key, and more, as shown in the figure below.

Providers Window

Step 2

The icons in the Reachability column indicate whether a provider is reachable via the listed connectivity protocols. For a description of each icon and its meaning, see Reachability and Operational State.

Cisco Crosswork Change Automation and Health Insights checks provider reachability immediately after a provider is added or modified. Other than these events, Cisco Crosswork Change Automation and Health Insights checks reachability every 5 minutes.

Step 3

Get additional details for any provider, as follows:

1. In the Provider Name column, click the to view provider-specific key/value properties.

2. In the Connectivity Type column, click the to view detailed connectivity information for the provider, such as provider-specific protocol, IP format, IP address, port, and timeout information.

3. In the Model Prefix column, click the to view the supported NED version(s) for a Cisco Network Services Orchestrator (Cisco NSO) provider's configured NED model prefix(es).

4. When you are finished, click to close the details window.

If you are running into provider reachability problems, you can troubleshoot as follows:

1. Ping the provider host.

2. Attempt a connection using the protocols specified in the connectivity settings for the provider. For an SR-PCE provider, it is typically HTTP and port 8080.

The following CLI command can be used to perform this check:

curl -v -H "X-Subscribe: stream" "http://<ip-address>:8080/
bwod/subscribe/json?keepalive-30&priority=5"

3. Check your firewall setting and network configuration.

4. Check the provider host or intervening devices for Access Control List settings that might limit who can connect.

Edit Providers

When editing provider settings, be aware that a provider can be mapped to many devices, even thousands of devices in a large network.

Note

- Before making any changes to a provider configuration you should be certain that you understand the full impact of the change. If you are unsure about the potential risk of making a change, contact Cisco services for guidance.

- See Add Cisco SR-PCE Providers before modifying an SR-PCE provider. There are additional steps that must be done when editing an SR-PCE provider.

.

Before editing any provider, it is always good practice to export a CSV backup of the providers you want to change (see Export Providers).

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

In the Providers window, choose the provider you want to update and click .

Step 3

Make the necessary changes and then click Save.

Step 4

Resolve any errors and confirm provider reachability.

Delete Providers

Follow the steps below to delete a provider.

Note

If an SR-PCE provider's auto-onboard managed or unmanaged options are set, you must do one of the following:.

- Reconfigure and remove the devices from the network before deleting the device from Cisco Crosswork Change Automation and Health Insights. This avoids Cisco Crosswork Change Automation and Health Insights from rediscovering and adding the device back.

- Set auto-onboard to off, and then delete the device from Cisco Crosswork Change Automation and Health Insights. However, doing so will not allow Cisco Crosswork Change Automation and Health Insights to detect or auto-onboard any new devices in the network.

You are alerted when you try to delete a provider that is associated with one or more devices or credential profiles.

Procedure

Step 1

Export a backup CSV file containing the provider you plan to delete (see Export Providers).

Step 2

(Optional) Check whether any devices are mapped to the provider and change the provider before deletion.

1. From the main menu, choose Inventory Management > Devices.

2. In the Devices window, enter the obsolete provider name in the Search field.

3. Check the check box for the device that is mapped to the obsolete provider, and click .

4. Choose a different provider from the Provider drop-down list.

5. Click Save.

Step 3

Delete the provider as follows:

1. From the main menu, choose Inventory Management > Providers.

2. In the Providers window, choose the provider(s) that you want to delete and click .

3. In the confirmation dialog box, click Delete.

Export Providers

You can quickly export provider data to a CSV file. This is a handy way to keep backup copies of your provider information.

Note

You cannot edit a CSV file and then re-import it to update existing providers.

Procedure

Step 1

From the main menu, choose Inventory Management > Providers.

Step 2

(Optional) In the Providers window, filter the provider list as needed.

Step 3

Check the check boxes for the providers you want to export. Check the check box at the top of the column to select all the providers for export.

Step 4

Click . Depending on your browser, you will be prompted to select a path and file name to use when saving the CSV file, or to open it immediately.

Manage Devices

The Inventory Management application's Devices window (shown below) gives you a consolidated list of all your devices and their status. To view the Devices window, select Inventory Management > Devices.

Devices Window

Item

Description

1

Icons in the Reachability State column show whether a device is reachable or not. See Reachability and Operational State.

2

The Filter by tags field lets you filter the devices by the tags applied to them. Type the name of the tag that has been applied to the device that you are trying to find. See Filter Devices by Tags.

3

Click to add a new device to the device inventory. See About Adding Devices to Inventory.

Click to edit the information for the currently selected devices. See Edit Devices.

Click to delete the currently selected devices. See Delete Devices.

Click to import new devices and update existing devices, using a CSV file. You can also download a CSV file template by clicking this icon. The template includes sample data that you can use as a guide for building your own CSV file. See Import Devices.

Click to export information for selected devices to a CSV file. See Export Devices.

Click to modify tags applied to the selected devices. See Apply or Remove Device Tags.

4

Click to open the Device Details pop-up window, where you can view important information for the selected device. See Get Device Details.

5

Click to see all the tags that have been applied to the device. See Manage Tags.

6

Icons in the Operational State column show whether a device is operational or not. See Reachability and Operational State

7

Click to refresh the Devices list.

8

Click to select which columns to display in the Devices list (see Set, Sort and Filter Table Data).

9

Click to set filter criteria on one or more columns in the Devices list.

Click the Clear Filter link to clear any filter criteria you may have set.

- About Adding Devices to Inventory

- Get Device Details

- Filter Devices by Tags

- Edit Devices

- Delete Devices

- Export Devices

- View Device Job History

About Adding Devices to Inventory

There are four ways to add devices to Cisco Crosswork Change Automation and Health Insights. Each has its own set of prerequisites, which you must fulfill if the device addition is to succeed.

In order of preference for most users, the methods and their prerequisites are:

1. Importing devices using the Cisco Crosswork Change Automation and Health Insights APIs: : This is the fastest and most efficient of the three methods, but requires programming skills and API knowledge. For more, see the inventory management APIs on Cisco Devnet.

2. Importing devices from a Devices CSV file: This method is explained in Import Devices. This method is time-consuming and error-prone, as you must create and format all of the data yourself beforehand (including not only devices, but also the providers, credential profiles and tags), and then ensure all of these items are properly associated with the devices after the CSV import. To succeed with this method, you must first:

- Create the provider(s) that will be associated with the devices (see Manage Providers)

- Create corresponding credential profiles for all of the devices and providers listed in the CSV file (see Create Credential Profiles)

- Create tags for use in grouping the new devices (see Manage Tags)

- Download the CSV template file from Cisco Crosswork Change Automation and Health Insights and populate it with all the devices you will need.

3. Adding them via the UI: This method is explained in Add Devices Through the UI. It is the least error-prone of the three methods, as all data is validated during entry, but also the most time-consuming, being suitable only for adding a few devices at a time. Note that the providers, credential profiles and tags you want to apply to them must exist beforehand.

4. Auto-onboarding from a Cisco SR-PCE provider: This method is explained in Add Cisco SR-PCE Providers. Note that the device and provider credential profiles and tags you want to apply to these devices must exist beforehand. After onboarding devices from this source, you will need to edit each device to add device information that is not automatically discovered.

5. Onboard the devices on Cisco Crosswork Data Gateway: This method is explained in Attach a Device to a Cisco Crosswork Data Gateway Instance.

- Prerequisites for Onboarding Devices

- Sample Configuration for Devices in Cisco NSO

- Import Devices

- Add Devices Through the UI

Prerequisites for Onboarding Devices

Before adding devices, you must ensure that the devices themselves are configured to collect and transmit telemetry data properly and communicate successfully with Cisco Crosswork Change Automation and Health Insights. The following sections provide sample configurations for a variety of communications options. Use them as a guide to configuring the devices you plan to manage using Cisco Crosswork Change Automation and Health Insights.

Pre-Onboarding SNMP v2 Device Configuration

Note

Only users configured with privilege level 15 can use the NETCONF APIs. Privilege level 15 can be used to configure the "enable" password option in XE devices. In such cases, NETCONF should not be included as one of the protocols to verify reachability and operational state for the onboarded devices.

Note

Only SNMPv2 and SNMPv3 (NoAuth/NoPriv) traps are supported.

The following commands provide a sample pre-onboarding device configuration that sets the correct SNMPv2 and NETCONF configuration, and SSH and Telnet rate limits. The NETCONF setting is only needed if the device is MDT-capable (XR 612 or higher).

logging console debugging
logging monitor debugging
telnet vrf default ipv4 server max-servers 100
telnet vrf default ipv6 server max-servers 100
crypto key generate rsa
line default
exec-timeout 0 0
width 107
length 37
absolute-timeout 0
!
snmp-server community public RO
snmp-server community robot-demo2 RO
snmp-server ifindex persist
ntp
server <NTPServerIPAddress>
!
service cli history size 5000
service cli interactive disable
ssh server v2
ssh server vrf default
ssh server netconf vrf default
ssh server logging
ssh server rate-limit 100
ssh server session-limit 100
grpc
port 57400
!
netconf agent tty
!
netconf-yang agent
ssh
!

Pre-Onboarding SNMPv3 Device Configuration

If you want to enable SNMPv3 data collection, repeat the SNMPv2 configuration commands in the previous section, and add the following commands:

snmp-server group grpauthpriv v3 priv notify v1default
snmp-server user <user-ID> grpauthpriv v3 auth md5 <password> priv aes 128 <password>

Pre-Onboarding SNMPv2 and SNMPv3 Trap Configuration

If you want the device to send SNMP traps to Cisco Crosswork Change Automation and Health Insights, use the following commands to perform a pre-onboarding device configuration and test for the trap version you want.

For SNMP v2 traps:

snmp-server trap link ietf

snmp-server host <CrossworkVMDataPortIPAddress> traps version 2c cisco123 udp-port 30162

snmp-server community cisco123

snmp-server traps snmp linkup

snmp-server traps snmp linkdown

For SNMP v3 traps:

snmp-server trap link ietf

snmp-server host <CrossworkVMDataPortIPAddress> traps version 3 cisco123 udp-port 30162

snmp-server community cisco123

snmp-server traps snmp linkup

snmp-server traps snmp linkdown

Please note that, for traps to be received, the node_ip field for the device as listed in the Cisco Crosswork Change Automation and Health Insights inventory must match the IP address of the device interface from which the traps are sent. If they do not, Cisco Crosswork Change Automation and Health Insights will reject the traps. Also, the device needs to be in ADMIN_UP state for traps to be received.

Sample Configuration for Devices in Cisco NSO

If you plan to use Cisco NSO as a provider to configure devices managed by Cisco Crosswork Change Automation and Health Insights, be sure that the Cisco NSO device configurations observe the following guidelines.

The following example shows a Cisco NSO setup that uses the hostname as the device ID. If you are using a CSV file to import devices, use ROBOT_PROVDEVKEY_HOST_NAME as the enum value for the provider_node_key field. The example hostname RouterFremont used here must match the hostname for the device in the CSV file.

configure
set devices device RouterFremont address 198.18.1.11 port 22
set devices device RouterSFO address 198.18.1.12 port 22

The authgroup username and password in the CSV file must match the username and password in the credential profile associated with the Cisco NSO provider. For example:

set devices authgroups group cisco default-map remote-name cisco remote-password cisco
set devices device Router* device-type cli ned-id cisco-ios-xr
set devices device Router* authgroup cisco

The device itself must be synchronized with Cisco NSO before you import that device. For example:

set devices device Router* state admin-state unlocked
request devices device Router* ssh fetch-host-keys
request devices device Router* sync-from
commit

Import Devices

Complete the steps below to create a CSV file that specifies multiple devices and then import it into Cisco Crosswork Change Automation and Health Insights.

Note

If you plan on using a CSV file to import devices managed by Cisco Network Services Orchestrator (Cisco NSO), you must prepare the CSV following the guidelines given in Sample Configuration for Devices in Cisco NSO.

Procedure

Step 1

From the main menu, choose Inventory Management > Devices.

Step 2

Click to open the Import CSV File dialog box.

Step 3

If you have not already created a device CSV file to import:

1. Click the Download sample 'Device Management template (*.csv)' file link and save the CSV file template to a local storage resource.

2. Open the template using your preferred tool. Begin adding rows to the file, one row for each device.

Use a semicolon to separate multiple entries in the same field. Use two semicolons with no space between them to indicate that you are leaving the field blank. When you separate multiple entries with semicolons, remember that the order in which you enter values in each field is important. For example, if you enter SSH;SNMP;NETCONF;TELNET in the Connectivity Type field and you enter 22;161;830;23 in the Connectivity Port field, the order of entry determines the mapping between the two fields:

- SSH: port 22

- SNMP: port 161

- NETCONF: port 830

- Telnet: port 23

For a list of the fields and the mandatory values you must enter, see the "Add New Device" field table in Add Devices Through the UI.

Be sure to delete the sample data rows before saving the file, or they will be imported along with the data you want. The column header row can stay, as it is ignored during import.

3. When you are finished, save the new CSV file.

Step 4

Click Browse to navigate to the CSV file you just created and then click Open to select it.

Step 5

With the CSV file selected, click Import.

Step 6

Resolve any errors and confirm device reachability.

The device information you imported should be displayed in the Devices window within a few minutes (see Manage Devices).

It is normal for devices to show as unreachable or not operational when they are first imported. However, if after 30 minutes they are still displayed as unreachable or not operational, there is an issue that needs to be investigated. To investigate, select Inventory Management > Job History and click on any you see in the Status column. Common issues include failure to ensure the associated credential profile contains the correct credentials. You can test this by opening a terminal window on the Cisco Crosswork Change Automation and Health Insights server and then trying to access the device using the protocol and credentials specified in the associated credential profile.

Add Devices Through the UI

Follow the steps below to add devices one by one, using the UI. Under normal circumstances, you will want to use this method when adding one or a few devices only. For the bulk of your devices, add them either by synchronization with a provider (see Add Cisco SR-PCE Providers), or by importation from a CSV file (see Import Devices).

Before you begin

Be sure you have completed the planning steps and setup requirements discussed in Get Started, and that the devices themselves have been pre-configured as explained in Prerequisites for Onboarding Devices.

Procedure

Step 1

From the main menu, choose Inventory Management > Devices. The Devices window opens.

Step 2

Click .

Step 3

Enter values for the new device, as listed in the table below.

Step 4

Click Save. (The Save button is disabled until all mandatory fields are complete.)

Step 5

(Optional) Repeat to add more devices.

Add New Device Window (*=Required)

Field

Description

* Configured State

The management state of the device. Options are

- UNMANAGED—Cisco Crosswork Change Automation and Health Insights is not monitoring the device.

- DOWN—The device is being managed and is down.

- UP—The device is being managed and is up.

* Reachability Check

Determines whether Cisco Crosswork Change Automation and Health Insights performs reachability checks on the device. Options are:

- ENABLE (In CSV: REACH_CHECK_ENABLE)—Checks for reachability and then updates the Reachability State in the UI automatically.

- DISABLE (In CSV: REACH_CHECK_DISABLE)—The device reachability check is disabled.

Cisco recommends that you always set this to ENABLE. This field is optional if Configured State is marked as UNMANAGED.

* Credential Profile

The name of the credential profile to be used to access the device for data collection and configuration changes. For example: nso23 or srpce123.

This field is optional if Configured State is marked as UNMANAGED.

Host Name

The hostname of the device. Cisco Crosswork Change Automation and Health Insights discovers it and updates it.

Inventory ID

Inventory ID value for the device.

UUID

Universally unique identifier (UUID) for the device.

Serial Number

Serial number for the device.

Node IP

IP address of the device.

MAC Address

MAC address of the device.

* Capability

The capabilities that allow collection of device data and that are configured on the device. You must select at least SNMP as this is a required capability. The device will not be onboarded if SNMP is not configured. Other options are YANG_MDT, TL1, YANG_CLI, and YANG-EPNM. The capabilities you select will depend on the device software type and version.

Tags

The available tags to assign to the device for identification and grouping purposes.

Use device tags to group devices for monitoring, and to provide additional information that might be of interest to other users, such as the device’s physical location or its administrator’s email ID. For more information, see Manage Device Tags.

Connectivity Details

Protocol

The connectivity protocols used by the device. Choices are: SSH, SNMPv2, NETCONF, TELNET, HTTP, HTTPS, GRPC, and SNMPv3.

To add more connectivity protocols for this device, click at the end of the first row in the Connectivity Details panel. To delete a protocol you have entered, click shown next to that row in the panel.

You can enter as many sets of connectivity details as you want, including multiple sets for the same protocol. You must enter details for at least SSH and SNMP. If you do not configure SNMP, the device will not be added. If you want to manage the device (or you are managing XR devices), you must enter details for NETCONF. TELNET connectivity is optional.

* IP Address / Subnet Mask

Enter the device's IP address (IPv4 or IPv6) and subnet mask.

* Port

The port used for this connectivity protocol. Each protocol is mapped to a port, so be sure to enter the port number that corresponds to the Protocol you chose. The standard port assignments for each protocol are:

- SSH: 22

- SNMP: 161

- NETCONF: 830

- TELNET: 23

- HTTP: 80

- HTTPS: 443

Timeout

The elapsed time (in seconds) before communication attempts using this protocol will time out. The default value is 30 seconds. For XE devices using NETCONF, the recommended minimum timeout value is 90 seconds. For all other devices and protocols, the recommended minimum timeout value is 60 seconds.

Routing Info

ISIS System ID

The device's IS-IS system ID. This ID identifies the router in an IS-IS topology, and is required for SR-PCE integration.

OSPF Router ID

The device's OSPF router ID. This ID identifies the router in an OSPF topology, and is required for SR-PCE integration.

Streaming Telemetry Config

Telemetry Interface Source VRF

Name of the VRF within which Model Driven Telemetry (MDT) traffic is routed.

Location

All location fields are optional, with the exception of Longitude and Latitude, which are required for the geographical view of your network topology.

Longitude, Latitude

Longitude and latitude values are required so that the geographical map can present the correct geographical location of the device and its links to other devices. Enter the longitude and latitude in Decimal Degrees (DD) format.

Altitude

The altitude, in feet or meters, at which the device is located. For example, 123.

Providers and Access

Local Config: Device Key and Provider

Provider type used to configure devices. Choose a provider from the list.

If a Cisco NSO provider is chosen, the Device Key will automatically populate and the Credential Profile appears.

For CSV entry, use ROBOT_PROVIDER_LOCAL_CONFIG and enter the Provider name.

Compute Config: Provider

Provider type used for topology computation. Choose a provider from the list.

For CSV entry, use ROBOT_PROVIDER_COMPUTE and enter the Provider name.

Example

Add New Device Window

Get Device Details

Whenever you select Inventory Management > Devices and display the list of devices, you can click next to any listed device to get more information about that device. Clicking this icon opens the Details for DeviceName pop-up window, as shown in the following example:

Details for DeviceName Window

Expand the Connectivity Details area at the top of the pop-up window (if it is not already expanded). This area shows the reachability status for all transport types (for help with the icons shown in this area, see Device and Link Icons).

Expand and collapse the other areas of the pop-up window, as needed. Click to close the window.

Filter Devices by Tags

By creating a tag and assigning it to a particular device, you can easily provide additional information that might be of interest to other users, such as the device’s physical location and its administrator’s email ID. You can also use tags to find and group devices with the same or similar tags in any window that lists devices.

For help with tagging your devices, see Apply or Remove Device Tags. For help with creating and deleting tags, see Manage Tags.

To filter devices by tags:

Procedure

Step 1

Display the Devices window or the Network Topology map:

1. Display the Devices window by choosing Inventory Management > Devices.

2. Display the topology map by choosing Network Visualization > View Topology.

Step 2

In the Type to filter by tags bar at the top of the user interface, type all or part of the name of a tag.

The Type to filter by Tags bar has a type-ahead feature: As you start typing, the field shows a drop-down list of tags that match all the characters you have typed so far. To force the drop-down list to display all available tags, type *.

Step 3

Choose the name of the tag you want to add to the filter. The filter appears in the Type to filter by tags filter bar. The table or map shows only the devices with that tag.

Step 4

If you want to filter on more than one tag:

1. Repeat Steps 2 and 3 for each additional tag you want to set as part of the filter.

2. When you have selected all the tags you want, click Apply Filters. The table or map shows only the devices with tags that match all the tags in your filter.

Step 5

To clear all tag filters, click the Clear Filters link. To remove a tag from a filter containing multiple tags, click the X icon next to that tag's name in the filter.

Edit Devices

Complete the following procedure to update a device's information.

Before editing any device, it is always good practice to export a CSV backup of the devices you want to change (see Export Devices).

Procedure

Step 1

From the main menu, choose Inventory Management > Devices.

Step 2

(Optional) In the Devices window, filter the list of devices by filtering specific columns.

Step 3

Check the check box of the device you want to change, then click .

Step 4

Edit the values configured for the device, as needed. For a description of the fields you can update, see Add Devices Through the UI.

Note

In addition to the exising fields, you can also view the Data Gateway configured for the selected device. This field is read-only.

Step 5

Click Save. (The Save button remains dimmed until all required fields are filled in.)

Step 6

Resolve any errors and confirm device reachability.

Delete Devices

Complete the following procedure to delete devices.

Procedure

Step 1

Export a backup CSV file containing the devices you plan to delete (see Export Devices).

Step 2

From the main menu, choose Inventory Management > Devices.

Step 3

(Optional) In the Devices window, filter the list of devices by entering text in the Search field or filtering specific columns.

Step 4

Check the check boxes for the devices you want to delete.

Step 5

Click to edit the devices, as follows:

1. Change each device's state to DOWN or UNMANAGED.

If you want to delete devices in bulk, Cisco recommends that you change the device state in this manner in batches of 50 devices, then complete deletion of these devices before deleting another batch.

2. Delete any KPIs currently running on the devices.

3. Abort any Playbooks running on or scheduled to run on the devices.

Step 6

Click .

Step 7

In the confirmation dialog box, click Delete.

Step 8

After deleting a device from the user interface, delete any telemetry configuration objects on the router that match the regex pattern .*CW_*.*. For example: You would find and delete router config objects like the three shown below:

!
destination-group CW_df5068767b68f9f0d9649cb32aca0cde917e5694
address-family ipv4 172.16.2.31 port 31500
encoding self-describing-gpb
protocol tcp
!
!
sensor-group CW_df5068767b68f9f0d9649cb32aca0cde917e5694
sensor-path Cisco-IOS-XR-nto-misc-oper:memory-summary/nodes/node/summary
!
subscription CW_df5068767b68f9f0d9649cb32aca0cde917e5694
sensor-group-id CW_df5068767b68f9f0d9649cb32aca0cde917e5694 sample-interval 120000
destination-id CW_df5068767b68f9f0d9649cb32aca0cde917e5694
!
!

Export Devices

When you export the device list, all device information is exported to a CSV file. Exporting the device list is a handy way to keep a record of all devices in the system at one time. You can also edit the CSV file as needed, and re-import it to overwrite existing device data.

Note

The exported device CSV file will contain only the name of the credential profile for each device, not the credentials themselves.

Procedure

Step 1

From the main menu, choose Inventory Management > Devices.

Step 2

(Optional) In the Devices window, filter the device list as needed.

Step 3

Check the check boxes for the devices you want to export. Check the check box at the top of the column to select all the devices for export.

Step 4

Click . Your browser will prompt you to select a path and the file name to use when saving the CSV file, or to open it immediately

View Device Job History

Inventory Management collects and stores information about device-related jobs. Follow the steps below to track all create, update and delete activities.

Procedure

Step 1

From the main menu, choose Inventory Management > Job History. The Job History window displays a log of all device-related jobs, like the one shown below.

Job History Window With Error Details Popup

The jobs display in descending order of creation time. The most recent job is shown first. To sort the data in the table, click a column heading. You can toggle between ascending and descending sort order (for more help, see Set, Sort and Filter Table Data).

Step 2

The Status column shows three types of states: completed, failed, and partial. For any failed or partial job, click shown next to the error for information.

Error information may include clean-up failure events as audit messages. These messages indicate that Cisco Crosswork Network Automation configuration objects on the device could not be removed, and will explain why they could not be removed. Users will need to take manual action to remove them. This typically involves deleting any XR telemetry configuration objects with names starting with CW_.

Manage Tags

Use the Tag Management window to manage the tags available for assignment to the devices in your network. Tags can provide information such as the device’s physical location and its administrator’s email ID, and are used to group devices.

To open this window, choose Inventory Management > Tags from the Cisco Crosswork Change Automation and Health Insights main window.

Note

Cisco Crosswork Change Automation and Health Insights automatically creates a default set of tags and assigns them to every device it manages:

- cli

- mdt

- reach-check

- snmp

- clock-drift-check

You cannot select, edit, delete, or manually associate these default tags with any device.

Item

Description

1

Click to create new device tags. See Create Device Tags.

2

Click to delete currently selected device tags. See Delete Device Tags.

3

Click to import the device tags defined in a CSV file into Cisco Crosswork Change Automation and Health Insights. See Import Tags. You can also download a CSV file template by clicking this icon. The template includes sample data that you can use as a guide for building your own CSV file.

4

Click to export a CSV file that lists the tags that are currently configured and their attributes. You can update this file and import it back into Cisco Crosswork Change Automation and Health Insights to quickly add or edit multiple tags. See Export Tags.

5

Displays the tags currently available in Cisco Crosswork Change Automation and Health Insights and their attributes.

6

Indicates the number of tags that are currently selected in the table.

7

Click to refresh the Tag Management window.

8

Click to choose the columns to make visible in the Tag Management window (see Set, Sort and Filter Table Data).

Click to set filter criteria on one or more columns in the Tag Management window.

Click the Clear Filter link to clear any filter criteria you may have set.

- Create Tags

- Import Tags

- Apply or Remove Device Tags

- Delete Tags

- Export Tags

Create Tags

You can create as many tags and tag categories as you want. If you will have many tags, it might be quicker to list them in a CSV file and import the file, instead of creating each tag individually. See Import Tags.

Note

Tag and tag category names are case-insensitive and can contain up to 128 alphanumeric characters, and can use full stops ("."), underscores ("_"), and hyphens ("-"). They cannot contain other special characters, symbols, or spaces.

Procedure

Step 1

From the main menu, choose Inventory Management > Tags. The Tag Management window opens.

Step 2

Click . The Create New Tags pane opens.

Step 3

In the Category area:

- To associate your new tags with an existing category: Choose the category from the drop-down list.

- To associate your new tags with a new category: Click the New Category link, enter the new category's name in the text field, and click Save.

All the new tags you create after this step will be assigned to the category you selected or created.

Step 4

In the Tags area: Start entering the names of the new tags that you want to create. Press Return after you type each tag.

To keep from entering duplicate tags, click the Show Tags link. The Create New Tags window will list only the tags that already exist in your currently selected category.

Step 5

When you are finished entering new tags, click Save.

What to do next

Add tags to devices. See Apply or Remove Device Tags.

Import Tags

Complete the steps below to create a CSV file that lists the tags you want to apply to your devices, and then import it into Cisco Crosswork Change Automation and Health Insights. This is the easiest way to create a lot of new tags and tag categories quickly.

When you import the CSV file, any tags not already in the database will be added. Tags with the same name as an imported tag will be overwritten. For this reason, it is a good idea to export a backup copy of all your current tags before import (see Export Tags).

Procedure

Step 1

From the main menu, choose Inventory Management > Tags.

Step 2

Click to open the Import CSV File dialog box.

Step 3

If you have not already created a CSV file to import:

1. Click the Download sample 'Tags template (*.csv)' file link and save the CSV file template to a local storage resource.

2. Open the template using your preferred tool. Begin adding rows to the file, one row for each tag. Use a comma to delimit each field within a row. Use a semicolon to separate multiple entries in the same field.

Field

Description

Required or Optional

Tag Name

Enter the name of the tag. For example: SanFrancisco or Spine/Leaf.

Required

Tag Category

Enter the tag category. For example: City or Network Role.

Required

Be sure to delete the sample data rows before saving the file, or they will be imported along with the data you want. The column header row can stay, as it is ignored during import.

3. When you are finished, save the new CSV file.

Step 4

Click Browse to navigate to the CSV file you just created and then click Open to select it.

Step 5

With the CSV file selected, click Import.

The tags and tag categories that you imported should now be displayed in the Tag Management window.

What to do next

Add tags to devices. See Apply or Remove Device Tags.

Apply or Remove Device Tags

Tags and their categories are your main tool for grouping devices. Once you have tagged a set of devices with the same tag, they are considered part of a group, and you can manage them more easily.

In order to apply a tag to a device or group of devices, the tag must already exist (see Create Tags).

For efficiency, Cisco Crosswork Change Automation and Health Insights automatically updates inventory data, including topology, for all the devices in a tagged group, as a single set of inventory collection jobs. But please note that tag-group membership is static for other functions. For example, if you add or remove a device from a tagged group after applying a KPI, the KPI will monitor only the original group members. If you change group membership and want the KPI to monitor all the members of the group, re-apply the KPI to the changed group.

You can apply a maximum of 15 tags to any one device.

To apply tags to a device or set of devices, do the following:

Procedure

Step 1

From the main menu, choose Inventory Management > Devices. The Devices window opens, showing the list of devices.

Step 2

(Optional) If the list is long, click to set one or more filters and narrow the list to only those devices you want to tag.

Step 3

Check the check box next to the device(s) you want to tag. If you select multiple devices, any changes you make will be applied to all the devices you selected.

Step 4

From the toolbar, click . The Modify Tags window opens, showing the tags currently applied to the device(s) you selected.

Step 5

Click in the Type to autocomplete item field to display the list of existing tags, or begin typing the name of the tag you want.

Step 6

Click on individual tags in the list to add them to the list of tags applied to the device(s). To delete an applied tag, click the X icon shown next to that tag.

Delete Tags

Use caution when deleting existing tags. They are used to group devices and deleting them can affect which KPIs are being monitored and the Playbooks run on them.

To delete device tags, do the following:

Note

If the tag is mapped to any devices, then the tag cannot be deleted.

Procedure

Step 1

Export a backup CSV file containing the tags you plan to delete (see Export Tags).

Step 2

From the main menu, choose Inventory Management > Tag Management.

Step 3

Check the check box next to the tags you want to delete.

Step 4

From the toolbar, click .

Step 5

The confirmation dialog box will list the number of devices currently using the tag(s) you are about to delete. Click Delete to confirm deletion.

Export Tags

You can quickly export tags and tag categories to a CSV file. This will allow you to keep backup copies of your tags. You can also edit the CSV file as needed, and re-import it to overwrite existing tags. Note that you will need to re-associate devices and tags in some cases.

Procedure

Step 1

From the main menu, choose Inventory Management > Tags.

Step 2

(Optional) In the Tag Management window, filter the tag list as needed.

Step 3

Check the check boxes for the tags you want to export. Check the check box at the top of the column to select all the tags for export.

Step 4

Click . Depending on your browser, you will be prompted to select a path and file name to use when saving the CSV file, or to open it immediately.

Chapter 5. Monitor Network Health and KPIs

This section contains the following topics:

- Health Insights Overview

- Health Insights Alert Dashboard

- Create a New KPI Profile

- Enable KPI Profile on Devices

- View Alerts for Network Devices

- Manage KPI Profiles

- Manage KPIs

- Create a New KPI

- Link KPIs to Playbooks

- Verify the Deployment Status of Enabled KPIs

- Disable KPI Profile on Devices or Device Groups

- List of Health Insights KPIs

- Troubleshoot Health Insights

Health Insights Overview

Health Insights is a network health application that performs real-time key performance indicator (KPI) monitoring, alerting, and troubleshooting. The Health Insights application enables programmable monitoring and analytics. With Health Insights, network operators can create a platform to dynamically address changes to the network infrastructure. Health Insights builds dynamic detection and analytics modules that allow operators to monitor and alert network events with user-defined logic. Health Insights uses the Device Management component to bring devices on board. For more information, see Inventory.

Health Insights provides prebuilt KPIs that are based on model-driven and SNMP-based telemetry. The Health Insights Recommendation Engine uses data mining to analyze your network and then recommends which telemetry paths you should enable and monitor.

Note

For the recommendation engine to work in Health Insights, the reachability should be established between Cisco Crosswork Change Automation and Health Insights and the device. When a device is onboarded, Cisco Crosswork Change Automation and Health Insights installs an explicit static route pointing to the data network gateway on the device subnet. You need to ensure that direct connectivity is established between Cisco Crosswork Change Automation and Health Insights and the device.

Health Insights helps predict KPI deviations and creates a probability distribution of problems in the network.

The following high-level example shows how Health Insights interacts with the other Cisco Crosswork Network Automation components:

1. Health Insights detects an anomaly: The optical bit error rate that you are monitoring on each of the links in your network suddenly increases.

2. Change Automation Playbooks automate remediation: Switch to the backup link immediately. Restore service. Open an RMA ticket. Alert the network engineer.

Any network remediation can be orchestrated via Change Automation Playbooks, which closes the loop on problem detection and resolution.

Health Insights Alert Dashboard

The Health Insights alert dashboard provides device health summary information that is based on real-time network state events. The dashboard displays a network view of KPI sensors that are paired to specific device groups. Health Insights raises customizable events and alerts that are based on user-defined logic.

Note

Alert dashboard displays individual KPI alerts, even though the mechanism of enabling KPI on a device is done through a KPI profile.

To display the Health Insights dashboard, choose Health Insights > Alert Dashboard from the main menu.

Item

Description

1

Device/KPI Alert Selector: Click here to toggle between device alert and KPI alert information.

2

Alerts History: This dashlet shows the total number of device alerts or KPI alerts that have been raised during the chosen time period, with detailed time lines showing both individual sets of alerts and the overall alert trend.

3

Alerts Trend Line: This line shows the overall trend in alerts for the chosen time period. You can use the Alerts Trend Line to select and zoom in on a specific time period within the Alerts History Line, as follows:

1. Click the time-period starting point in the Alerts Trend Line and hold down the mouse.

2. Drag the cursor to the endpoint and then release the mouse.

The time range you selected is indicated by light gray shading on the Alerts Trend Line, with + and - zoom icons shown above the Alerts History Line. Click the + icon to zoom in on the time range you selected. Click the - to zoom out. To restore the full view of the Alerts History Line, click on any point outside of the light gray shading on the Alerts Trend Line.

4

Top 20 Impacted Devices/ Top 20 Impacted KPIs: When selected, this dashlet displays a map of tiles, each tile representing one of the 20 devices or KPIs with the most alerts during the selected time period. The amount of space that each tile occupies in the map corresponds to the number of alerts raised: the more alerts, the bigger the tile. To view more detailed information for a particular device or KPI, click the device or KPI name link in the center of the tile.

5

Filter By Tags: This field lets you filter the alert dashboard information by associated tag names. To select a tag, do one of the following:

- If you know the tag that you want to use, enter it in the Type to filter by Tags field and then check its check box. Repeat this step to select more tags.

- If you want to select a tag from the tags that are currently available:

1. In the Type to filter by Tags field, type any character to open the results list.

2. Click the View All Tags link at the bottom of the list.

3. Check the check box for each tag you want to use and then click Apply Filters.

4. Delete the character that you typed in Step 1 to clear the results list.

Tag filters you create are not saved. If you open another window and then return to the alert dashboard, you will need to re-create tag filters.

6

All Impacted Devices/All Impacted KPIs: When selected, this dashlet provides a complete list of all devices or KPIs affected by alerts. The information for each affected device or KPI includes:

- Device Name or KPI Name

- Device or KPI Type

- IP address: The IP address of the impacted device. This column is only displayed for devices.

- Alert count: The total number of alerts for that device or KPI during the selected period.

- Impact score—This value is determined using the following formula: (4 x number of critical alerts) + (3 x number of major alerts) + (2 x number of minor alerts) + number of warning alerts. When monitoring the health of your network, focus on devices or KPIs with a higher impact score.

- Severity distribution—Provides a visual breakdown of the severity that is associated with a device or KPI's alerts. To view a tooltip that indicates the number of raised alarms (by severity and in total), place your cursor over the appropriate bar segment.

7

Alerts History: The Alerts History line shows alerts as discrete bar indicators whose height represents the total number of alerts gathered at each point in time. To see the total for each type of alert, hover your mouse cursor over the bar indicator. You can also use the Alerts Trend line to zoom in on particular portions of the alert history.

8

Time Period: Specifies the time period for which the dashboard provides alert information: The past one hour, past day, past week, and so on. Please note that the dashboard provides alert information only, not telemetry information.

9

Severity Legend: Maps the bar indicator colors that are used in the Alert History dashlet to the corresponding alert severity. To display or hide the alerts for a particular severity, click the circle representing that severity. A filled circle indicates that alerts of that severity have been raised and are being displayed. An empty circle indicates that alerts of that severity are either not being displayed or have not been raised during the displayed time period.

10

Auto Refresh: Specifies how often the dashboard is automatically refreshed.

11

Refresh Icon: Refreshes the dashboard.

Note

Alert group logic does not show the alerts impacted on dashboard, only API shows the impacted results.

Note

Composite Alerting is not displayed in the Alert dashboard.

Create a New KPI Profile

A KPI Profile is a collection of KPIs and their corresponding parameters such as alert frequency, alert type, cadence, and more. You can group relevant KPIs into a KPI Profile, give it meaningful name based on the purpose (for example, environmental or health check), and configure parameters that are relevant to monitoring a specific type of devices (for example, edge routers). Once the KPI profiles are created and validated by the system, they are ready to be used. You can select the device(s) in Health Insights, select appropriate KPI Profiles and enable them. This action enables all the KPIs in the selected KPI Profile. Similarly, you can select the device(s) and choose to disable the KPI Profiles. This removes all KPIs enabled as part of the selected KPI profile(s).

You can create a KPI Profile and enable it on the desired devices. The workflow is as follows:

1. Supply basic information, such as the Profile name and a description.

2. Add KPI(s) and save the profile.

3. Edit KPI parameters and create alert groups.

4. Enable the KPI Profile on the devices.

The following steps explain how to perform all of these tasks.

Procedure

Step 1

From the main menu, choose Health Insights > Manage KPI Profiles. The Manage KPI Profiles window opens.

Step 2

Click the . The Create New Profile window opens.

Step 3

In the text fields provided, enter a unique Profile Name, a short Description. The Profile Name can contain a maximum of 32 alphanumeric characters, plus underscores ("_"). No other special characters are allowed.

Step 4

Add KPI to the profile, using the following filter options:

1. All KPIs: By default, this option is selected and the list of all KPIs are displayed in the list. You can select the required KPI by checking the relevant checkbox.

2. Recommended KPIs: You may also select KPIs based on the KPI recommendation for a specific device. Click Recommended KPIs and the device list is displayed. You may filter the device list by entering relevant values in the Name and State fields, or filter by tags. using tags. Select a device from the list and the recommended KPI list is displayed on the right side. Select the required KPI by checking the relevant checkbox.

Note

Selecting KPIs from the recommended KPI list of a selected device does not automatically enable the KPI Profile in the selected device. The KPI Profile can be enabled after it is created. For more information, see Enable KPI Profile on Devices

Step 5

Click Save save the new KPI Profile and display the Manage KPI Profiles window.

Step 6

In the KPI Profiles area on the left side, choose the KPI Profile that you created, and the individual KPI details are displayed on the right side.

Step 7

You can leave the KPI parameters at the default or choose a different value. To edit the KPI parameters, click Edit Details, and the KPI Details window is displayed. Edit the parameter values as appropriate for the purpose of your KPI. The common parameters are:

- Alert: This is an on/off toggle switch for alerting. Based on the Alert parameter value, the corresponding alerting logic is deployed. Alerting can be enabled even after the KPI Profile has been applied to the devices.

Note

Any KPI using the composite alerting logic need to have the alerting flag set to ON.

- Cadence (sec): Set the frequency of sensor data. Set the frequency (in seconds) in which the KPI will gather sensor data from the devices on which the KPI Profile is enabled.

- Alerting Down Sample Rate: Alert frequency rate. It determines how often KPI data will be evaluated for any alert conditions, and is relative to the Cadence. For example, if Cadence is 60 seconds and you want to do an alerting evaluation every 300 sec, then specify Alerting Down Sample Rate as "5".

Step 8

You can also edit the alert logic parameters of the selected KPI. To learn more about a parameter, hover your mouse cursor over the shown next to the parameter name.

Note

When different thresholds are desired for different types of devices in the network, it is advisable to create multiple profiles and split the KPIs across them to meet the needs of different device types.

Step 9

When you are finished making changes, click Save to save the new KPI Profile. Health Insights validates your input parameters and displays the Manage KPI Profiles window.

Note

You can create up to 50 KPI profiles, and an individual KPI Profile can consist up to 50 KPIs. KPI profile creation can fail if the total number is exceeded, or if Health Insights could not create the required tags in Inventory manager. This status is reflected in the profile state. Once profile is ready, it can be applied on devices.

With the Manage KPI Profiles window displayed, you can enable the new KPI Profiles on one or more devices immediately, following the steps given in Enable KPI Profile on Devices.

See Disable KPI Profile on Devices or Device Groups for instructions to disable KPI Profiles.

Step 10

(Optional) You can also create alert groups for a KPI Profile. Alert groups use boolean logic (cascaded OR and AND) to combine alert outputs from primary KPIs in your KPI profile and create a composite logic query. To create an alert group, click + Alert Group. The Create Alert Group window is displayed.

Note

Configuring an alert provider enables composite alert forwarding. For information on adding alert providers, see Add an Alert Provider

Step 11

Provide a relevant entry in the Name field. Summary and Details are optional fields.

Step 12

The Alert Group Conditions area on the right side lets you select a logic gate (AND/OR) and add a KPI on which the logic is applied. Your alert group can be based on the alert criteria of a single KPI, or it can be a combination of mutliple KPI outputs. Click the desired logic (AND gate is selected by default), and click the + ADD dropdown list to add an Item or a Group.

Item allows you to add individual KPI items and set the corresponding alert level, and Group allows you to add a nested alert group.

Step 13

Choose the desired KPI from the Select KPI dropdown, and select the desired level(s) for which the alerts need to be set for the chosen KPI. The alert levels are CRITICAL, MAJOR, MINOR, WARNING and INFO. Based on the logic gate and alert criteria you select, the output of the KPIs are evaluated and the alert is generated.

In the example shown above, the alert is set based on the output of two logic gates. The first logic gate is the output of an OR operation between the Memory Utilization and Interface Bandwidth monitor KPIs. If the set alert levels are met for either of the KPIs, the output of the first logic gate is set as true. This output is considered as the input for the second logic gate, which is an AND operation with the CPU Utilization KPI. If the alert levels of both the KPIs are met, the output of the second logic gate is set as true.

Step 14

Click Save to save the new alert group and display the Manage KPI Profiles window. Click Edit Details or to edit or delete an existing alert group respectively.

Enable KPI Profile on Devices

With Health Insights, you can enable and monitor the KPI Profiles in which you are interested. Instead of sifting through all the data that a given device can supply, you choose to monitor only the information relevant to the role the device plays in your network. Your equipment and management infrastructure operates as efficiently as possible, without requiring the collection and storage of data that is unrelated to device roles. This operational efficiency reduces the amount of time required to set up specific monitoring, leading to faster problem identification and resolution.

Note that some KPIs trigger alerts based on deviation from an established level of performance. For these types of KPIs, it is necessary to allow the system some annealing time in order to establish normal performance levels.

Important

You can only enable KPI Profiles with MDT-based KPIs on a device that has been mapped to a Cisco Network Services Orchestrator (Cisco NSO) provider. See the following topics for more information:

- Add Providers Through the UI

- Upload New Providers

- Sample Configuration for Devices in Cisco NSO

- Prerequisites for Onboarding Devices

To enable KPI Profile on devices:

Procedure

Step 1

From the main menu, choose Health Insights > Enable-Disable KPI Profiles. The Enable-Disable KPI Profiles window is displayed.

Step 2

Select the devices for which you want to enable KPI Profiles. You can click the Devices or Device Tags buttons above the table on the left to toggle between selecting the devices by name or by tagged device group membership. Depending on your selection, the device list or the device tag list is displayed on the left.

If you choose to select by Devices:

- Click in the table on the right. Type a Name or Device Type in the filter fields. As you type, the table displays only the devices whose name or type match the text you typed.

- Click the check box next to the device(s) you want. You can select multiple devices at the same time.

If you choose to select by Device Tags:

- Type a tag name in the Name field to find a Device Group in the table. As you type, the table displays only the tag names that match the text you typed.

- Click the check box next to the group you want. The names of all the devices in that group appear in the devices table on the right.

Step 3

Click Enable KPI Profiles to continue. Health Insights detects the selected devices, their types and models, and retrieves and analyzes their running configurations. The KPI Profiles window presents the KPI Profiles available for your selected devices.

Step 4

Choose the KPI Profiles you want to enable by clicking the check box next to the KPI Profile name. :

Step 5

When you are finished, click Next. The Verify Details window appears, listing all the KPI Profiles you have chosen to be enabled on the selected devices, as shown in the following figure.

Step 6

(Optional) To get information about the KPIs included in the KPI Profile. Click the KPI Profile in the Selected Profile(s) table, and the content of the selected KPI Profile is displayed on the right side. Click View More Details to view the parameters of a specific KPI. A popup window provides the details of the KPI. Click the to close the popup window.

Step 7

To enable the selected KPI Profiles on the selected devices, click Enable. Health Insights schedules the KPI Profile(s) as a series of job sets.

Step 8

From the main menu, choose Health Insights > Job History to watch the progress of each job set, as shown below. You should see job sets completing with a status of "Success". If job sets complete with a "Partial" or "Failed" status, be sure to read the job completion messages, and check that the selected devices are still reachable.

When the job sets complete successfully, the KPIs are now associated to the devices and the platform begins the process of enabling the relevant collection procedures for those network elements. In making these changes, you are automating the configuration of both the platform and the devices themselves to collect only the information required.

Step 9

From the main menu, choose Health Insights > Alert Dashboard. The dashboard shows the alert status for the devices on which you have enabled KPI monitoring.

Note

- SNMP/MDT jobs may take more time than expected to reach the completed state when there is an increase in the number of devices, interfaces and KPIs.

- Enabling KPI profile per device takes around 3 to 5 seconds. If the device is not reachable, it will keep trying until it is timed out. This may result in the job taking more time to reach the completed state.

View Alerts for Network Devices

After enabling KPIs on a device, you can view alerts for that device and get data for each performance indicator being monitored.

Note

The KPIs shown in the following steps are examples. There are many more KPIs available in Health Insights. For the complete list, see List of Health Insights KPIs.

Procedure

Step 1

From the main menu, choose Health Insights > Alert Dashboard. The Health Insights dashboard opens.

Step 2

Make sure that the Device Alerts view is displayed (select the Device Alerts toggle, if needed). Then scroll down below the Total Alerts panel and click on the All Impacted Devices tab. The dashboard displays a list of devices with alerts.

Step 3

Click on the Device Name for the device whose details you want to see. Health Insights displays the device's basicOverview information, Total Alerts, a Topology map, and the list of the device's currently Enabled KPIs.

The Topology map is a version of the map you see when you select Network Visualization > View Topology. For help using it, see Network Visualization Overview.

Step 4

To see detailed KPI data, scroll down to the Enabled KPIs panel at the bottom of the window and click on one of the enabled KPIs in the list at left. A graphical representation of that KPIs data, along with a list of alert messages and other information, is displayed on the right.

In the example shown below, the Interface rate counters KPI was selected, so the accompanying information includes a list of the interfaces at the right of the graphic time-series data.

Item

Description

1

Click on the KPI name in the list to display its data on the right.

2

Graphical time-series data for the selected KPI appears here. In the example shown, the KPI graphic shows real-time data that has been collected on the interfaces and the points at which the sensor detected an alert event.

To have the graphic display data for a single interface instead of all interfaces, click on the interface name in the list at right.

To zoom in on a period within the time series graph, click and drag within the graph.

3

Hover the mouse cursor over any data point in the KPI graphic to see additional popup information for that data point.

A red line or tag represents a point at which the KPI was triggered. This can occur on any subscribed statistic the KPI is monitoring. Health Insights collects and identifies the time points and frequency, which help determine when these events become an operational concern.

4

Below the KPI timeline, the alerts panel shows each KPI alert that was generated on the device. It also shows which link or interface was affected and when the alert occurred. The blue color indicates that the alert has cleared and is informational only. Red signifies a critical alert.

Search for alert messages in the list below by severity, any part of the message text, the alert ID, or by time and date.

5

View additional information by clicking the Summary and Raw graph pages in the View widget.

6

Click the empty square icon to use the whole page to display the Enabled KPIs panel only.

If you choose to enlarge the Enabled KPIs panel, a blue < icon appears next to the list of KPIs. Click the icon to hide the list.

Click the inverted versions of these icons to restore the KPI list and return the Enabled KPIs panel to its normal size.

Manage KPI Profiles

The Health Insights Manage KPI Profiles window allows you to create, edit, and delete KPI Profiles.

To display the Health Insights Manage KPI Profiles window, choose Health Insights > Manage KPI Profiles from the main menu.

Item

Description

1

Filter KPI Profile: To find a KPI category, enter all or part of the KPI Profile name in this field, and the list is automatically filtered based on your input. Click to clear any filters you have set.

2

Create KPI Profile: Click to create a new, user-created KPI Profile. For help with this task, see Create a New KPI Profile.

3

Edit KPI Profile: Select a user-created KPI Profile in the list and then click to edit it. For help with this task, see Create a New KPI Profile.

4

Delete KPI Profile: Select a user-created KPI Profile in the list and then click to delete it. You cannot delete a KPI Profile that has been enabled on any device(s).

5

KPI On Profile: The KPI(s) added on the selected KPI Profile and the associated parameters are displayed here. You can edit the KPI parameters, or remove a KPI from the selected KPI Profile using the appropriate options here. For more information, see Create a New KPI Profile.

6

#KPIs on Profile: This is the number of KPIs added on the selected KPI Profile.

7

Enabled Devices: This is the number of devices on which the selected KPI Profile is enabled.

8

+Alert Group: Click this option to create Alert Group for the selected KPI Profile. For help with this task, see Create a New KPI Profile

Manage KPIs

The Health Insights Manage KPIs window gives you complete access to Cisco-supplied and user-created KPIs. You can add, edit, delete, import, and export your KPIs. You can also link your KPIs to the Change Automation application's Playbooks, which enable scripted responses to KPI changes.

To display the Health Insights Manage KPIs window, choose Health Insights > Manage KPIs from the main menu.

Item

Description

1

Add KPIs: Click to add a new, user-created KPI. For help with this task, see Create a New KPI.

2

Delete KPIs: Select one or more existing user-created KPIs in the list and then click . You will be prompted to confirm that you want to delete the KPIs. Click Delete to confirm.

Note that you can delete user-created KPIs only. You cannot delete Cisco-supplied KPIs.

3

Import KPIs: Click to import new user-written or Cisco-supplied KPIs.

You will be prompted to browse to the gzipped tar archive containing the KPIs to be imported. When you have selected the archive, click OK to begin importing it. Once imported, the new KPIs will appear immediately in the list of KPIs, with each KPI name and category assigned based on the definition in the KPI itself.

In order for Cisco Crosswork Change Automation and Health Insights to import them, KPI files must:

- Be packaged as a gzip tar archive. You can include more than one KPI in a single archive; each will be imported as a separate KPI.

- Have unique names and descriptions. These must not match the name or description of any Cisco-supplied KPI. If the name or description of the KPI matches an existing user-created KPI, the import will overwrite the existing KPI.

- Meet other minimum requirements for Health Insights KPIs, as explained in the Cisco Crosswork Network Automation Custom KPI Tutorial Documentation on Cisco DevNet.

4

Export KPIs: Select one or more existing KPIs in the list and then click to export them. Health Insights will package the exported KPIs as a single TGZ archive with a unique name. Your browser will then prompt you to save the archive to a name and location in your local file system that you select.

5

Link Playbooks: Select a KPI and then click to link it to a Playbook. That Playbook will execute whenever the KPI raises an alert thereafter. You can specify the values the Playbook will use when operators trigger it in response to the KPI alert. For help with this task, see Link KPIs to Playbooks.

6

Unlink Playbooks: Select a KPI with a linked Playbook and then click to unlink the Playbook. You will be prompted to confirm that you want to unlink the Playbook. Click Unlink to confirm.

7

Clear Filters: Click Clear All Filters to clear any filters you have set.

8

Filter KPI Categories: To find a KPI category, enter all or part of the KPI Category name in this field. Then click to filter the list below.

9

Filter KPIs: To find a KPI, enter all or part of the KPI Name, Category, Description, or Linked Playbook in the fields provided. The list below is automatically filtered to match your typed entry.

Create a New KPI

You can create a custom KPI and enable it on the desired devices. The workflow is as follows:

1. Supply basic information, such as the KPI name and a summary description.

2. Set the KPI cadence.

3. Select a YANG module and choose sensor paths

4. Select an alert template and set its parameters

5. Enable the KPI on the devices.

The following steps explain how to perform all of these tasks.

Procedure

Step 1

From the main menu, choose Health Insights > Manage KPIs. The Manage KPIs window opens.

Step 2

Click the . The Create KPI window opens.

Step 3

In the text fields provided, enter a unique KPI Name, a short KPI Summary description, and KPI details. The KPI Group is preset to User Created.

Step 4

The Cadence field sets the number of times per minute the KPI will gather sensor data from the devices on which the KPI is enabled. Leave it at the default or use the numerical selector to choose a different value.

Step 5

In the Select YANG Paths area, choose one module and one or more sensor leaf paths from which to stream data:

1. Use Filter Modules to filter and choose the desired Cisco IOS XR YANG module.

2. Use Filter Paths to filter and choose the desired sensor path. When you choose a path, the leaf node gets resolved to the base encoding path. If the YANG module is hierarchical, the field names are concatenated down from the base path. Note that only one gather path is supported for user-created KPIs.

3. Click Next to display the Select Alert Templates window.

Step 6

Choose the alert template you want to use with your new KPI: No Alert, Standard Deviation, Two-Level Threshold or Rate Change. Then click Next to display the Alert Parameters window appropriate for the type of alert template you chose.

Step 7

Edit the alert template parameter values as appropriate for the template and the purpose of your KPI, as follows:

- Use the Basic and Advanced Parameters dropdowns to view and edit the parameter sets you need.

- Change alert parameter numerical values using the selectors or by editing the field contents

- Change alert parameters with discrete choices using parameter field dropdowns and select each choice as needed.

- Learn more about an alert parameter: Hover your mouse cursor over the shown next to the parameter name.

- Click the View Tick Script link to view the tick script code you are generating with your changes. The tick script code updates as you make your edits. At any time, click the Hide Tick Script to close the tick script code window.

Step 8

When you are finished making changes, click Finish to save the new KPI and display the Manage KPIs window.

Link KPIs to Playbooks

You can link any Health Insights KPI to one Change Automation Playbook of your choice. A user can run the linked Playbook whenever the linked KPI raises an alert in response to the event associated with the performance indicator the KPI is monitoring. The KPI alert can be raised in response to a threshold crossing, topology changes, flapping conditions, and other parameters. These parameters will vary, as appropriate, for each KPI.

You can specify the Source of the parameter values the linked Playbook will use when you run it. You can select these sources:

- Playbook: Use default values coded into the Playbook itself

- KPI Alert: Use values taken from the alert raised by the linked KPI.

- Runtime Input: Use values you enter only at the moment you run the Playbook.

The ability to set the source of these Playbook parameter values gives you flexibility in how you use the linked Playbook. For example: Link the KPI Interface flap detection, which detects interface flapping, to the Playbook Interface state change, which can be used to set the interface up or down. Depending on circumstances, you might want to set the Playbook parameters as follows:

- Playbook: You want to run the Playbook as it normally does, so you would set the Source as Playbook for the provider, collection_type and mop_timeout parameters. In the case of the collection_type, you can still choose between telemetry and snmp, depending on whether you want to use MDT or SNMP to gather device data.

- KPI Alert: You want the Playbook to run only on the host device and interface affected by the flapping, which are identified in the flap-detection Alert. So set the Source of the Playbook's hosts and if_names parameters to KPI Alert. You can then use the alert's data about the Producer device and the interface_name of the flapping interface on that device.

- Runtime Input: You want the freedom to decide at runtime whether to bring the flapping interface up or down. So set the Source of the Playbook parameter admin_state to Runtime Input. The Playbook will prompt you for an up or down choice when you initiate the run.

The following figure shows what this set of choices will look like:

Example: Specifying Parameter Value Sources for a Linked Playbook

Procedure

Step 1

From the main menu, choose Health Insights > Manage KPIs. The Manage KPIs window opens, displaying lists of the KPI categories and the KPIs available in each category.

Step 2

Select the KPI you want to link to a Playbook. You can use filters to find the KPI you want, as explained in Manage KPIs.

Step 3

Click . The Link KPI to Playbook window opens.

Step 4

The left side of the window lists the name of the selected KPI and the Playbooks appropriate for linking to it. Scroll through the list, or use the Playbook Name field and the to restrict the list to just the Playbooks you want.

Step 5

When you have found the Playbook you want to link, click on its name. The right side of the window will then list the Playbook Details for the selected Playbook, including:

- The hardware and software platforms with which it is compatible.

- The minimum software version requirement

- The Source and default values that will be used when the Playbook runs. In many cases, you can select from a range of default values, or enter your own.

Step 6

Verify or modify the Source and parameter values as needed.

During the maintenance cycle, the Playbook will perform a variety of actions. To see a list of these actions, click the View Maintenance link. A popup Maintenance panel opens, listing them. Click if you want to continue to refer to this action list while you adjust the Playbook runtime parameter sources and values. Click at any time to close the Maintenance panel.

Step 7

When you are finished making changes, click Link to KPI. Change Automation displays the Manage KPIs window again, this time with the linked Playbook shown next to name of the KPI in the Key Performance Indicators (KPIs) list.

Step 8

To change the Playbook linked to a given KPI, repeat steps 3 through 7 for that KPI, this time choosing the Playbook you want. To unlink a Playbook entirely, select the KPI and click .

Verify the Deployment Status of Enabled KPIs

After you enable KPIs, you can verify their deployment status.

Procedure

Step 1

From the main menu, choose Health Insights > Job History The Job History window lists the jobs that have been run most recently, indicating whether they succeeded or failed, when they ran, and on what devices.

Step 2

Click the transaction ID in the job listing to view detailed KPI job information, including the device on which the KPI was enabled and the KPI ID.

Disable KPI Profile on Devices or Device Groups

You can use the Enable-Disable KPI Profiles window to disable all of the KPI Profiles running on device(s).

Procedure

Step 1

From the main menu, choose Health Insights > Enable-Disable KPI Profiles. The Enable-Disable KPI Profiles window opens.

Step 2

To disable all KPI Profiles enabled on all the devices within a device group:

1. Click the Device Tags button above the table on the left. The table displays the list of device tags.

2. Click the checkbox next to the device tag(s) on which you want to disable KPI Profiles.

When you select a device tag, the Devices table on the right shows all the devices that are associated with that tag. All of the devices are preselected.

3. Click Disable KPI Profiles. You will be prompted to confirm that you want to disable all the KPIs running on all the devices in the group. Click Disable to confirm.

Step 3

To disable KPIs enabled on one or more devices:

1. Click the Devices button above the table on the left. The Devices table on the right shows all the devices, with the total number of KPIs enabled on each device.

2. Click the checkbox next to the devices on which you want to disable KPIs.

If you select one device, you can disable all KPI Profiles for the device or just some of the KPI Profiles. If you select more than one device, you can only disable all KPIs for them.

3. Click Disable KPI Profiles. You will be prompted to confirm that you want to disable the KPIs running on all the selected devices. If you selected only one device, click the checkboxes next to the KPI Profiles you want to disable on that device, or click the checkbox at the top of the column to disable all the KPI Profiles running on that device. Click Disable to confirm.

List of Health Insights KPIs

The table below lists the prebuilt Health Insights KPIs supplied with Cisco Crosswork Change Automation and Health Insights.

Alerting types in the table that you can select when you create a new KPI (see Create a New KPI are:

- No Alert: The KPI gathers, tracks and reports performance data without triggering alerts.

- Standard Deviation: The KPI detects spikes or drops in measured values and alerts when these values deviate some number of standard deviations away from their normal values.

- Two-Level Threshold: The KPI detects abnormal measured values using two custom thresholds and the ability to provide dampening intervals on the thresholds.

- Rate Change: The KPI detects abnormal rates of change in measured values to detect rising or falling values.

Additional alerting types that you can use when you export and use a prebuilt KPIs to create KPIs with custom parameters are:

- Standard Deviation of Rate Change: The KPI alerts on standard deviations of the rate of change.

- Low Single Threshold: The KPI alerts on a single threshold when the value falls below that threshold.

- Direct Alarm Forwarding: The KPI uses the alarm from the device directly, as a Health Insights KPI alert.

- Major/Minor/Low/High Thresholds: The KPI alerts on Major high, Minor high, Minor low, and Major low values.

- Line State Changes: The KPI alerts on shutdowns and flapping in line states.

For more on creating KPIs with custom parameters from exported KPIs, see the Cisco Crosswork Network Automation Custom KPI Tutorial Documentation on Cisco DevNet.

Health Insights KPIs

Category

KPI Name

Description

Alerting

MDT or SNMP

Dataplane-Counters

CEF drops

Monitors CEF drop counters and baseline. Generates an alert for an unusual number of drops.

Rate Change

MDT

CPU

CPU threshold

Monitors CPU usage across route policies and line cards on routers. Generates an alert when CPU utilization exceeds the configured threshold

Two-Level Threshold

MDT

CPU

CPU utilization

Monitors CPU usage across route policies and line cards on routers. Generates an alert when CPU utilization is unusual.

Standard Deviation

MDT

Basics

Device uptime

Monitors device uptime.

Low Single Threshold

MDT

Layer 1-Traffic

Ethernet port error counters

Monitors port transmit and receive error counters.

Rate Change

MDT

Layer 1-Traffic

Ethernet port packet size distribution

Monitors port transmit and receive packet size distributions.

No Alert

MDT

Layer 1-Traffic

Ethernet port packet statistics

Monitors port transmit and receive packet statistics.

Standard Deviation of Rate Change

MDT

Layer 2-Traffic

Interface bandwidth monitor

Monitors bandwidth utilization across all interfaces on a router. Generates an alert when bandwidth exceeds the configured threshold.

Two-Level Threshold

MDT

Layer 3-Traffic

Interface counters by protocol

Monitors interface statistics (such as incoming and outgoing packets or byte counters) organized by protocol.

Standard Deviation

MDT

Layer2-Interface

Interface flap detection

Monitors interface flaps and alerts when flap count reaches set threshold.

Two-Level Threshold

MDT

Layer 2-Traffic

Interface packet counters

Monitors interface transmit and receive counters. Generates an alert when unusual traffic rates occur.

No Alert

MDT

Layer 2-Traffic

Interface packet error counters

Monitors interface transmit and receive error counters. Generates an alert when unusual error rates occur.

Rate Change

MDT

QOS

Interface QoS (egress)

Monitors interface QoS on the egress direction for queue statistics, queue depth, and so on.

No Alert

MDT

QOS

Interface QoS (ingress)

Monitors interface QoS on the ingress direction for queue statistics, queue depth, and so on.

No Alert

MDT

Layer 2-Traffic

Interface rate counters

Monitors interface statistics as rate counters. Generates an alert when unusual traffic rates occur.

Standard Deviation

MDT

IPSLA

IP SLA UDP echo RTT

Monitors IP SLA UDP echo RTT. Generates an alert when unusual RTT values occur.

Standard Deviation

MDT

IPSLA

IP SLA UDP jitter monitoring

Monitors IP SLA UDP jitter. Generates an alert when an abnormal UDP jitter occurs.

Standard Deviation

MDT

Layer 3-Routing

IPv6 RIB BGP route count

Monitors IPv6 RIB for route count and memory used by BGP. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIB IS-IS route count

Monitors RIB for route count and memory used by IS-IS. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

IPv6 RIB IS-IS route count

Monitors IPv6 RIB for route count and memory used by IS-IS. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

IPv6 RIB OSPF route count

Monitors IPv6 RIB for route count and memory used by OSPF. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Protocol-ISIS

ISIS neighbor summary

Monitors ISIS neighbor summaries for changes in neighbor status. Generates an alert when an anomaly is detected (such as neighbors down or flapping).

Standard Deviation

MDT

Layer 1-Optics

Layer 1 optical alarms

Monitors per-port optical alarms (current and past).

Direct Alarm Forwarding

MDT

Layer 1-Optics

Layer 1 optical errors

Monitors per-port Layer 1 errors. Generates an alert when error rates exceed the configured threshold.

Rate Change

MDT

Layer 1-Optics

Layer 1 optical FEC errors

Monitors per-port optical FEC errors. Generates an alert when FEC errors exceed the configured threshold.

Rate Change

MDT

Layer 1-Optics

Layer 1 optical power

Monitors per-port optical power. Generates an alert when power levels exceed the configured threshold.

Major/Minor/Low/High Thresholds

MDT

Layer 1-Optics

Layer 1 optical temperature

Monitors per-port optical temperature. Generates an alert when temperature exceeds the configured threshold.

Major/Minor/Low/High Thresholds

MDT

Layer 1-Optics

Layer 1 optical voltage

Monitors per-port optical voltage. Generates an alert when voltages exceed the configured threshold.

Major/Minor/Low/High Thresholds

MDT

Layer 2-Interface

Line state

Monitors interface line states. Generates an alert when link states change.

Line State Changes

MDT

LLDP

LLDP neighbors

Monitors LLDP neighbors. Generates an alert when any sudden changes are detected.

Standard Deviation

MDT

Memory

Memory utilization

Monitors memory usage across route processor and line cards on routers. Generates an alert when memory utilization is unusual.

Standard Deviation

MDT

Memory

Memory utilization (cXR)

Monitors memory usage across route processor and line cards on classic XR devices. Generates an alert when memory utilization is unusual.

Standard Deviation

MDT

Layer 3-Routing

RIB BGP route count

Monitors RIB for route count and memory used by BGP. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIB connected route count

Monitors RIB for route count and memory used by connected. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIB IS-IS route count

Monitors RIB for route count and memory used by IS-IS. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts)

Standard Deviation

MDT

Layer 3-Routing

RIB local route count

Monitors RIB for route count and memory used by local. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIB OSPF route count

Monitors RIB for route count and memory used by OSPF. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIB static route count

Monitors RIB for route count and memory used by static. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIBv6 connected route count

Monitors RIBv6 for route count and memory used by connected. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIBv6 local route count

Monitors RIBv6 for route count and memory used by local. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIBv6 static route count

Monitors RIBv6 for route count and memory used by static. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 3-Routing

RIBv6 subscriber route count

Monitors RIBv6 for route count and memory used by subscriber. Generates an alert when an anomaly is detected (such as significant increase or decrease in route counts).

Standard Deviation

MDT

Layer 2-Traffic

SNMP interface packet error counters

Monitors interface transmit and receive error counters. Generates an alert when unusual error rates occur.

No Alert

SNMP

Layer 2-Traffic

SNMP interface packet counters

Monitors interface transmit and receive counters. Generates an alert when unusual traffic rates occur.

Rate Change

SNMP

Layer 2-Traffic

SNMP interface rate counters

Monitors interface statistics as rate counters. Generates an alert when unusual traffic rates occur.

Standard Deviation Rate of Change

SNMP

Layer 2-Traffic

SNMP traffic black hole

Monitors input and output data rates for black hole behavior.

Checks the ratio of output data rate to input data rate and verifies that the ratio is within acceptable ranges, otherwise a black hole is occurring.

Two-Level Threshold

SNMP

Layer 2-Traffic

Traffic black hole

Monitors input and output data rates for black hole behavior.

Checks the ratio of output data rate to input data rate and verifies that the ratio is within acceptable ranges, otherwise black hole.

Two-Level Threshold

MDT

Troubleshoot Health Insights

The following table describes issues you may encounter when using the Health Insights application, and their solutions or workarounds.

Health Insights Troubleshooting

Issue

Solution

Apply a KPI to a device fails with messages indicating that Cisco Network Services Orchestrator (Cisco NSO) and the target device are out of sync or otherwise out of communication. Message text will vary, but may include "device out of sync", "NC client timeout", and other text indicating that there are connectivity or sync issues between NSO and the device.

Apply the KPI again. Under normal circumstances, doing so will initiate a sync operation between the device and NSO.

Health Insights not receiving data.

Check the following and ensure they are responsive:

- Crosswork Data Gateway health: View Cisco Crosswork Data Gateway Instance Health

- Collection/distribution status: Monitoring Collection Jobs

- Operational status of the devices: Reachability and Operational State

Chapter 6. Visualize the Network

This section contains the following topics:

- Network Visualization Overview

- Identify the Members of a Cluster

- Device and Link Icons

- Get More Information About Devices on the Map

- Access the Device Console

- Get More Information About Links

- Network Link Discovery

- Show Bandwidth Utilization for Links on the Map

- Define Color Thresholds for Link Bandwidth Utilization

- Configure Geographical Map Settings

- Change the Layout of a Logical Map

- Create Custom Map Views

- Manage Custom Map Views

Network Visualization Overview

Cisco Crosswork Change Automation and Health Insights provides a graphical, topological map view of devices and the links between them so that you can visualize your network. The network topology can be displayed on a logical map or a geographical map, where the devices and links are shown in their geographic context. From the map, you can drill down to get detailed information about devices and links in order to troubleshoot problems. You can also filter the devices shown on the map using tags (see Filter Devices by Tags), and you can customize the map to show just the information you want, and save these custom maps for later recall.

To open the topology map view, choose Network Visualization > View Topology from the left navigation bar in the Cisco Crosswork Change Automation and Health Insights main window.

Note

If you encounter topology issues, such as topology components not rendering as expected or component data not displaying on the map, Cisco recommends the following:

- If you cannot see geographical map tiles: Make sure your browser has Internet connectivity to your selected geographical map services vendor. The map services vendor and the vendor’s URL are set by the system administrator, as explained in Configure Geographical Map Settings.

- If your devices are missing from the geographical map: Ensure that geographic location data was included when onboarding your devices, or entered later. Cisco Crosswork Change Automation and Health Insights cannot position devices properly on the geographical map without location information.

- If you are having intermittent problems displaying the map or your devices: Clear your browser cache and try again.

Also, please note that disjoint network discovery and display are not supported.

Network Visualization: Geographical Map

Item

Description

1

Filter by Tags: If tags have been assigned to devices, you can filter the map to show only devices with specific tags. For help with this task, see Filter Devices by Tags

2

Device Cluster: If devices are in close physical proximity, the geographical map shows them as a cluster, represented by a solid blue circle with a number in the center, indicating the number of devices in the cluster. Displaying devices in this manner helps prevent overlap and clutter on the map. In this example, there are two devices in the cluster. To see the individual devices in the cluster, zoom in on the cluster or click on the cluster icon. If all the devices in the cluster are in the same location or extremely close to one another, you will be prompted to show the cluster devices in the logical map. See Identify the Members of a Cluster.

Links: A solid line indicates a single link between two devices. If there is more than one link between two devices, or between a device and a cluster of devices, the line is shown dashed instead. A dashed line indicates an aggregated link that represents more than one link.

3

Single Device: The device icon represents the type of device (router, switch, and so on). A blue icon means the device is reachable; a gray icon means the device is not reachable.

Hover the mouse cursor over the device icon to see device details.

4

Geographical Map: Click this icon to toggle from the logical map to the geographical map.

The geographical map shows single devices, device clusters, and the links between them, superimposed on a map of the world. The location of a device on the map reflects the device's GPS coordinates (longitude and latitude) as defined in the Device ManagementInventory Management application.

5

Logical Map: Click this icon to toggle from the geographical map to the logical map. The logical map shows devices and their links, positioned according to an automatic layout algorithm, ignoring their geographical location. You can change the layout algorithm; see Change the Layout of a Logical Map.

The logical map displays up to 1000 devices and never displays devices in clusters.

6

Display Preferences: Lets you view display settings for devices and link color. For example, you can toggle link color based on state or bandwidth utilization for the mapped links. For more information, see Show Bandwidth Utilization for Links on the Map.

7

Custom Views: Lets you create a named custom view using the settings and layout for your current map, or display a custom view you have created previously. See Create Custom Map Views.

8

Zoom In: Click the + icon to zoom in on a specific area.

9

Zoom Out: Click the - icon to zoom out.

10

Zoom Fit: Lets you automatically scale the map to fit your zoom area.

Identify the Members of a Cluster

When there are multiple devices that are too close to be shown individually at the current Zoom level, they are combined together and shown as a single cluster. The cluster is represented on the geographical map by a circle with a number in its center, indicating the number of devices in the cluster.

Zoom in on a cluster to see the individual devices in the cluster displayed on the map.

If cluster members are very close to each other or in the same location, zooming in will not show the individual devices. In this case, follow these steps to see the individual members of the cluster:

Procedure

Step 1

In the geographical map, click . The map zooms in on the cluster area.

Step 2

Click again. If you are at the maximum zoom level, the geographical map toggles to the logical map and displays the individual devices in the cluster. When you close the view, you will be switched back to the geographical map.

Device and Link Icons

The following tables describe the icons used to represent device states, link states, and device types in the Cisco Crosswork Change Automation and Health Insights user interface.

Device State Icons

Icon

Description

The device is reachable.

The device is unreachable.

The device has an unknown reachability state (its reachability cannot be determined).

The device is operational.

The device is not operational. It is either not up, or unreachable, or both.

In some Cisco Crosswork Change Automation and Health Insights applications (not Network Visualization), a number in a circle is shown next to this icon. The number indicates the number of recent errors and can be clicked on to display error details.

Some connections to the device are down.

Link State Icons

Icon

Description

Link is down.

Link is up and traffic is passing through it.

Link is degraded.

If some (but not all links) in an aggregated link are down, the aggregated link shows a degraded icon. The link will also show as degraded if only one direction of an L2 or L3 link was discovered instead of both directions. Click the degraded icon to see exactly which link or interface is down.

If all links in an aggregated link are down, the connectivity link shows a link down icon.

Device Icons

Icon

Description

Switch

Switch (unreachable)

Router

Router (unreachable)

Amplifier

Amplifier (unreachable)

Converged Broadband Router (cBR)

cBR (unreachable)

Reconfigurable optical add/drop multiplexer (ROADM)

ROADM (unreachable)

Device is reachable, but is undefined or of an unknown type

Unreachable device

Get More Information About Devices on the Map

In the topology map, hover over a device icon to open a popup window with the most important device details: hostname, reachability state, IP address, and type. Click on the device icon to open the Device Details pop-up window, where you can view more detailed information about the device and its associated links. See the following examples.

Device Details

In the Device Details window, click on the Links tab to see a list of all of the device's links to other devices, as in the following example (see Get More Information About Links):

Links Tab of Device Details Window

Access the Device Console

After drilling down to a device's details from the topology map, you can access the device's CLI command console from the Device Details window (see Get More Information About Devices on the Map).

Before you begin

- Depending on your environment, your local machine may not have direct access to your network devices (for example: you cannot ping the device's management address directly from the command line on your local machine). If this is the case, you may need to configure a tunnel. Contact Cisco Services for assistance with this more advanced configuration.

- Be sure you have installed on your client an application that can connect to devices via Secure Shell (SSH) or Telnet.

Procedure

Step 1

From the main menu, choose Network Visualization > View Topology.

Step 2

In the topology map, click on the icon representing the device to which you want to connect. The Device Details window displays its Details tab, with the device hostname, reachability state, IP address, and other details.

Step 3

In the Connect to Device field, click the relevant link to connect to the device console via Telnet , or via SSH .

If you have already defined a default connectivity application that you want to launch, Cisco Crosswork Change Automation and Health Insights launches your selected application and attempts to connect to the device. Log into the device and enter the commands you want.

If you have not defined a default application to launch, your browser will prompt you to select one. Your choices and how they are presented will be appropriate for your client operating system, the applications you have installed, and the connectivity protocol you choose. Select the application you want and, for convenience, make sure that you select the check box indicating that this is your default choice before continuing.

Get More Information About Links

You can drill down in the topology map to view detailed information about links, using either of these methods:

- Click on an aggregated link (symbolized by a dashed line) to show the individual links in the side panel.

- Click on a single link (solid line) to show the Link Details page.

The Links page provides information about the configuration and status of all of a device's links, including each link's type, interfaces, and utilization (you can get the same information from the Links tab on the Device Details window; see Get More Information About Devices on the Map). The Links window lists all the underlying links in the aggregation, as in the following example:

Links Window

Use the expand and collapse icons (< and >) to the left of the Links title to expand the window to the entire screen, or collapse the window back to its normal size.

Click to choose the columns to make visible in the Links window's table:

- State—Displays each link's state: up, down, degraded, and so on (see Device and Link Icons).

- Link Type—Displays the type of link. Click on the link type to open the Link Details window for the specific link.

- A Side Device—Displays the originating device for the link.

- Z Side Device—Displays the destination device for the link.

- A Side Interface—Displays the originating interface for the link.

- Z Side Interface—Displays the destination interface for the link.

- A Side Utilization—Displays the percentage of bandwidth consumption on the originating side of the link.

- Z Side Utilization—Displays the percentage of bandwidth consumption on the destination side of the link.

You can also use sorts and filters in the Links window to focus the table on only the links in which you are interested (see Set, Sort and Filter Table Data).

The Link Details window provides information about the configuration and status of a single link, including link type, the link's interfaces, associated adjacent segment IDs, and so on.

Network Link Discovery

Layer 2 links are discovered by enabling SNMP on the inventory. Devices must be onboarded in order to be visible on the topology. SNMP data is required as CDP MIB and/or LLDP MIB are needed to discover the Layer 2 links. For more information on onboarding prerequisites, see Prerequisites for Onboarding Devices

Layer 3 links are discovered from adding the Cisco Segment Routing Path Computation Elements (SR-PCE) providers. At least one SR-PCE provider is required in order to discover the Layer 3 links. Devices must be onboarded (at least in unmanaged state) so that the Layer 3 links and nodes are properly displayed. For more information, see Add Cisco SR-PCE Providers

Note

The SR-PCE provider must be reachable from Cisco Crosswork Change Automation and Health Insights and must have a topology detected before the links can be displayed.

Show Bandwidth Utilization for Links on the Map

In the geographical map and in the logical map, you can enable visualization of the bandwidth utilization for links over which circuits are provisioned. When bandwidth utilization visualization is enabled, links in the map are colored based on the percentage of total bandwidth currently utilized on the link. The utilization value is a percentage calculated by dividing link traffic by link capacity.

In this way, you can easily identify when a link is over-utilized or approaching over-utilization. Bandwidth visualization is enabled by default. The color of the link indicates the percentage of total bandwidth being used by provisioned circuits on the link:

- Green—0–25% usage

- Yellow—25–50% usage

- Orange—50–75% usage

- Red—75–100% usage

You can adjust the thresholds for each color as needed (see Define Color Thresholds for Link Bandwidth Utilization). When visualization is disabled, the links are shown only in blue.

Please note that link bandwidth utilization data can be collected and displayed only if the linked devices are added to and managed in the device inventory.

To enable or disable visualization of bandwidth utilization:

Procedure

Step 1

From the main menu, choose Network Visualization > View Topology..

Step 2

In the top-right corner of the map, click , to open display preferences which can be used to toggle the display of bandwidth utilization. When usage visualization is enabled, the links can be shown in green, yellow, orange, or red, depending on their utilization. If you see only blue links, usage visualization is disabled.

Define Color Thresholds for Link Bandwidth Utilization

Cisco Crosswork Change Automation and Health Insights comes with a default set of bandwidth utilization thresholds (percentage ranges) and corresponding color indicators. You can customize these to meet your needs, taking into account the following notes and limitations:

- You can enter values in the "To" ranges. Each row begins automatically from the end of the previous row's range.

- The thresholds must be sequential, meaning that each row's range must follow on from the previous row's range. For example, if the range in the first row is 0-25%, the second row's range must end with a value greater than 25.

- You cannot use the same color for multiple thresholds. For example, you cannot choose Green for both the first and second rows.

Administrator privileges are required to change these settings.

Procedure

Step 1

From the main menu, choose Admin > Visualization Settings.

Step 2

Click the Bandwidth Utilization tab.

Step 3

In the Polling Interval field, enter a whole number from 5 to 60 (minutes) to specify how often links will be polled for bandwidth utilization. By default, link bandwidth is polled every 5 minutes.

Step 4

In the Link Coloring Thresholds area, define the criteria for coloring the links. Each row defines a color and the bandwidth percentage range that the color will represent. The default thresholds are:

- Green—0–25% usage

- Yellow—25–50% usage

- Orange—50–75% usage

- Red—75–100% usage

Step 5

Click Save.

Configure Geographical Map Settings

The geographical map lets you position your network devices on a world map and monitor them within their geographical context. The displayed world map is imported by accessing the map vendor's site over the Internet (online mode). The look of the map will vary depending on the map vendor you choose.

By default, the client machine from where you access Optimization Engine UI is setup to get map tiles from a specific Mapbox URL over internet connection. If required, you can use a different map vendor (such as Google Maps or OpenStreetMap) by providing the appropriate URL. Both of these options require an Internet connection from your client machine.

Cisco Crosswork Change Automation and Health Insights administrator privileges are required to change these settings.

Procedure

Step 1

From the main menu, choose Admin > Visualization Settings.

Step 2

Click the Map tab.

Step 3

From the Map Provider drop-down list, choose one of the following:

- Mapbox—Specifies that you want to display the geographical map using the default map provider.

- Custom—Identifies the map tiles source (using an Internet connection). To use a map provider other than Mapbox, you must provide the URL for map tiles access. Be sure to request the exact format of this URL from the map tiles provider.

Step 4

If you are using a custom map provider, in the Map Source URL field, enter the URL for map access.

Step 5

Click Save.

Step 6

Navigate to Optimization Engine > Traffic Engineering and confirm that the map is displayed correctly.

Change the Layout of a Logical Map

When you open the logical map, it is displayed according to the default standard layout. You can change the layout, but any changes you make will not persist if you close the map. To save your layout changes, create a custom view (see Create Custom Map Views).

Procedure

Step 1

From the main menu, choose Network Visualization > View Topology.

Step 2

In the top-right corner of the map, toggle from the geographical map view to the logical map view.

Step 3

In the logical map, click the System Layouts icon in the toolbar to access the layout options.

System Layouts

Step 4

Choose one of the predefined options to rearrange the devices and links in the map according to your preference:

- Standard (default)—Maintains consistent link length and distributes devices evenly. This ensures that adjacent devices are closer to each other and prevents overlap.

- Lens—Positions highly connected devices in the center, and moves less-connected devices out to the edges. This layout is especially useful in large networks.

- Radial—Arranges the devices in a circular style around the original subject. Each generation of devices becomes a new concentric ring that orbits the original parent. This layout is useful in networks where each parent has many child devices.

- Hierarchy—Displays devices in a family tree, where child devices are shown in horizontal layers underneath their parents.

- Structural—Groups devices with similar attributes together in a fan shape. This layout gives you an overview of the clusters in the network.

- Tweak—Adjusts the layout as the network evolves. As devices and links are added and removed, the layout adapts itself, allowing you to visualize network changes.

Create Custom Map Views

When you rearrange the devices and links on a map, your changes are not normally saved. When you open the map later, your map settings are lost.

To easily recreate a useful map layout, you can save it as a named custom view and quickly retrieve it, without having to rearrange the map each time. This is especially useful when managing large networks with many devices.

When you save a custom view, the following settings will be saved:

- Whether it is a geographical or logical map.

- Device positions in the logical map layout.

- Whether bandwidth utilization visualization is enabled or disabled.

- Tag filters that have been applied to the map.

The map zoom level will not be saved.

Your custom map views are not user-specific. Any Cisco Crosswork Change Automation and Health Insights user who is logged into the same host as you can see and further customize the map views you create.

To create custom views:

Procedure

Step 1

Choose Network Visualization > View Topology from the left navigation bar.

Step 2

Customize the current map view until it contains only the information you want and until the layout meets your needs.

Step 3

When you have the view the way you want it, click .

Step 4

Click Save View and the Save View popup displays a new, blank input field under the Name field.

Step 5

Enter a unique name for the new custom view and click Save.

What to do next

Retrieve, update and delete your custom views as explained in Manage Custom Map Views.

Manage Custom Map Views

You can display, update or delete any of the custom views created using the instructions in Create Custom Map Views. This includes custom views created by other users.

To manage custom views:

Procedure

Step 1

Open the topology map by choosing Network Visualization > View Topology from the left navigation bar.

Step 2

Click and the following options are displayed:

- View Saved Views—Displays all saved custom views. You can choose to see only custom views saved with your user ID (My Views tab) or all custom views that have been saved on the server (All Views tab).

- Save View—Allows you to save the current view.

- Save View As—Click this option if you are currently modifying a custom view and want to save changes as a new custom view with a new name.

- Rename View—Click this option if you are currently modifying a custom view and want to rename it.

Step 3

To delete a custom view:

1. Click the View Saved Views to display the list of custom views.

2. Find the view you want to delete and click from the custom view.

Chapter 7. Perform Administrative Tasks

This section contains the following topics:

- Manage Cisco Crosswork Network Automation

- Manage Backup and Restore

- Manage Users

- Manage TACACS+ Servers

- Manage LDAP Servers

- Define Network Visualization Display Settings

- Manage Certificates

- Smart Licensing Registration

- Security Hardening Overview

Manage Cisco Crosswork Network Automation

The Crosswork Manager window gives you consolidated information about the current status of each installed Cisco Crosswork Change Automation and Health Insights application and its supporting services. It also supplies tools and information that, with support and guidance from your Cisco Customer Experience account team, you can use to identify, diagnose and fix issues with Cisco Crosswork Change Automation and Health Insights.

Select Admin > Crosswork Manager to display a Crosswork Manager window, with information like the window shown in the following example.

The Crosswork Manager window has two main views. The Crosswork Applications Summary view, at the top of the window, is a dashboard giving you a quick look at the overall health of the system. It displays the total number of Cisco Crosswork Change Automation and Health Insights applications currently installed in the system, and how many of that total are Running, Down, or Degraded.

The Applications Detail view, below the Crosswork Applications Summary view, allows you to:

- View the name and current runtime status of each installed application and its supporting services.

- Get advice about what to do when an application or one of its services has issues.

- Collect logs and metrics on any application or service, or for the system as a whole.

- Stop, start, or restart any application or service.

The Applications Detail view, shown in the following figure, is the best way to investigate any system health issues indicated in the Crosswork Applications Summary.

Applications Detail View

Item

Description

1

Click the Show/Hide Service Detail link in each application tile to view the detailed status of the underlying services for that application.

2

An application tile like this shows the current status of the named application and a summary of the status of that application's services. This includes the total number of services, and how many of those services are Running, Down, or Degraded.

3

Both the application tile and its Service Detail table provide the name, status, description and recommendation for the respective application or service. The Service Detail table also provides service uptime, and you can click on the link in the Name column to see more details about the service, such as its process ID and pod identifier.

4

To control an application or service, click on any of the links in this section of the application tile or Service Detail table. You can click:

- Restart to restart the application or service.

- Stop to stop the application or service.

- Start to start the application or service.

See Control Cisco Crosswork Network Automation Applications and Services.

5

To gather logs and metrics for the entire system, or for any application or service, click on any of the "collect" links at the system (in the dropdown menu), application, or service level. You can choose:

- Collect All to collect both logs and metrics.

- Collect Logs to collect only logs.

- Collect Metrics to collect only metrics.

See Collect and Share Cisco Crosswork Network Automation Logs and Metrics.

6

Click the Monitor link to monitor individual Cisco Crosswork Change Automation and Health Insights functions and features, using analytical dashboards and data gathered over the last 24 hours of run time.

See Monitor Cisco Crosswork Network Automation Functions in Real Time.

7

Choosing any of the control or collect actions at the system, application or service level will initiate a job. You can view each job's progress by clicking the Show Jobs Listlink at the top right corner of the window. You can also use the Show Jobs Listto publish collected logs and metrics files, and check on the status of publish jobs you initiate.

- Monitor Cisco Crosswork Network Automation Functions in Real Time

- Collect and Share Cisco Crosswork Network Automation Logs and Metrics

- Control Cisco Crosswork Network Automation Applications and Services

Monitor Cisco Crosswork Network Automation Functions in Real Time

You can monitor the health of Cisco Crosswork Change Automation and Health Insights and any of its functions in real time, using a set of monitoring dashboards you can access from the Crosswork Manager window.

Cisco Crosswork Change Automation and Health Insights uses Grafana to create these dashboards. They give you a graphical view of the product's infrastructure, using metrics collected in its database. You can use these dashboards to diagnose problems you may encounter with individual Cisco Crosswork Change Automation and Health Insights applications or their underlying services.

There are multiple monitor dashboards, categorized by the type of functionality they monitor and the metrics they provide, as shown in the following table.

Monitoring Dashboard Categories

This dashboard category...

Monitors...

Change Automation

Playbook functions. Metrics include the number of MOP jobs executed, response latency, API calls, database activity, and so on.

Collection - Manager

Device-data collection functions. Metrics include telemetry collection latencies, total collection operations, memory and database activity related to telemetry, delayed collections, and so on.

Health Insights

Key Performance Indicator functions. Metrics include the number of KPI alerts, API calls, and so on.

Infra

System infrastructure messaging and database activity.

Inventory

Inventory manager functions. These metrics include total numbers of inventory change activities.

Platform

System hardware and communications usage and performance. Metrics include disk and CPU usage, database size, network and disk operations, and client/server communications.

To conserve disk space, Cisco Crosswork Change Automation and Health Insights maintains a maximum of 24 hours of collected metric data.

Grafana is an open-source visualization tool. The following provides general information about how to use the Cisco Crosswork Change Automation and Health Insights implementation of Grafana. For more information about Grafana itself, see https://grafana.com and http://docs.grafana.org

Procedure

Step 1

From the main menu, choose Admin > Crosswork Manager.

Step 2

At the right, just below the Crosswork Applications Summary view, click the Monitor link, highlighted below.

The Grafana user interface appears within the Crosswork Manager window, replacing the Applications Detail view.

Step 3

In the Grafana user interface, click Home. Grafana displays the list of monitoring dashboards and their categories, as shown in the following example.

Step 4

Click the icon next to the dashboard you want to view. For example: Clicking on the Platform - Summary dashboard displays a view like the one shown in the following figure. For more information on how to use Grafana go to htttps://grafana.com.

Step 5

Scroll the dashboard as needed to display all of the metrics it provides, or select any of the functions described in the following table.

Item

Description

1

Dashboard Icon: Click the icon to re-display the dashboard list and select a different dashboard.

2

Time Series Graph Zoom: You can zoom in on a specific time period within the graph of any time series data, as follows:

1. Click a time-period starting point in the graph line and hold down the mouse.

2. Drag the cursor to the endpoint. Light gray shading will appear in the block you are selecting. When you reach the endpoint, release the mouse.

To reset a zoomed time series graph to the default, click the Zoom Out icon.

3

Share Dashboard icon: Click the icon to make the dashboard you are viewing shareable with other users. Clicking this icon displays a popup window with tabs and options to share the dashboard in your choice of these forms:

- URL Link: Click the Link tab and then click Copy to copy the dashboard's URL to your clipboard. You can also choose whether to retain the current time and template settings with the URL.

- Local Snapshot File: Click the Snapshot tab and then click Local Snapshot. Grafana creates a local snapshot of the dashboard on the server. When the snapshot is ready, click Copy Link to copy the URL of the snapshot to your clipboard.

- Export to JSON File: Click the Export tab and then click Save to file. You will be prompted to save or open the exported JSON file. You can also choose to turn data source names in the file into templates by selecting the Export for sharing externally checkbox before clicking Save to file.

- View JSON File and Copy to Clipboard: Click the Export tab and then click View JSON (you can choose to templatize data source names by selecting the Export for sharing externally checkbox before clicking View JSON). Grafana displays the exported JSON code in a popup window. Click Copy to Clipboard to copy the file to your clipboard.

4

Cycle View Mode icon: Click this icon to toggle between the default Grafana TV view mode and the Kiosk mode. The Kiosk view hides most of the Grafana menu. Press Esc to exit the Kiosk view.

5

Time/Refresh Selector: Indicates the time period for the metrics displayed in the dashboard and how often the metrics are refreshed. Click the selector to choose a different time range and refresh rate.

You can specify a custom pair of time-range start and end points, or choose from one of several predefined ranges, such as Today so far or Last three hours.

You can choose predefined refresh rates from Off to 2 Days.

When you have finished making changes, click Apply.

When making selections, remember that Cisco Crosswork Change Automation and Health Insights keeps only 24 hours of data. If you select time ranges or refresh rates beyond that limit, the dashboard may be blank.

6

Show Application Details: Click this link to re-display the Crosswork Manager window's Applications Detail view.

7

Zoom Out icon: Click this icon to reset a zoomed time series graph back to the unzoomed state.

8

Refresh icon: Immediately refresh the data shown.

Collect and Share Cisco Crosswork Network Automation Logs and Metrics

You can collect logs and metrics on multiple levels of Cisco Crosswork Change Automation and Health Insights. You can collect logs and metrics for the entire system, for any of its installed application, or for any service supporting an application. You can also choose to collect only logs, only the additional metrics, or both.

Collected logs and metrics are stored in gzipped tar archive files. You can publish these archives to an HTTP or HTTPS server of your choice.

Procedure

Step 1

From the main menu, choose Admin > Crosswork Manager. The Crosswork Manager window displays, with the Application Detail section listing all the applications.

Step 2

Click the option for the collection level and target information you want, as follows:

- To collect for the entire system: From the Action drop down on the right, opposite the Applications Detail section title, choose Collect All, Collect Logs, or Collect Metrics. See item 1 in the following figure.

- To collect for an application: Scroll to the Application Detail tile for the application you want. Then click the Collect All, Collect Logs, or Collect Metrics link on the right, opposite the application's name. See item 2 in the following figure.

- To collect for a service: Scroll to the Application Detail tile for the application whose service you want to collect. Click the Show Service Detail link for that application. Then click the Collect All, Collect Logs, or Collect Metrics link on the right, opposite the service's name. See item 3 in the following figure.

Step 3

When you click on the collection option you want, the Crosswork Manager window displays a popup message indicating that a job was successfully created and giving the job ID. Click on the Show Jobs List link at the right to view the job's progress in the Crosswork Managerwindow's Jobs List view, which replaces the Applications Detail view.

Step 4

Wait for the job to complete. When the Jobs List view's Status column for your job has changed to JobCompleted, the Action column for the job will show an enabled Publish link for the completed job, and the Description column will show the file name of the gzipped tar archive file containing the collected information.

Step 5

(Optional) Click on the Publish link to publish the collected information to an HTTP or HTTPS server, as follows:

1. A popup window will prompt you for the destination server host name, the storage path on the server, the port number, and the login user name and password for the server (if required). Enter the server information and click Publish.

2. The Job List view's Publish Status column for the job shows an enabled Details link. Click the Details link to view a popup window showing the status of the publish job.

Step 6

When you are finished, click the Show Application Details link to re-display the Applications Detail view.

Control Cisco Crosswork Network Automation Applications and Services

Users with administrator privileges can control the runtime status of any Cisco Crosswork Change Automation and Health Insights application or service. This can include:

- Stopping a running application or service

- Starting a stopped application or service

- Restarting a running or stopped application or service

Please note that stopping, starting and restarting Cisco Crosswork Change Automation and Health Insights applications and services can result in anomalous system behavior and possible data loss. Use these functions only with the supervision of Cisco TAC staff.

Procedure

Step 1

From the main menu, choose Admin > Crosswork Manager. The Crosswork Manager window displays, with the Application Detail view listing all the applications.

Step 2

Display the application or service whose runtime status you want to control:

- To control an application: Scroll to the Application Detail tile for the application you want.

- To control a service: Scroll to the Application Detail tile for the application whose service you want to control, then click the Show Service Detail link for that application to show its services.

Step 3

Click on the Start, Stop, or Restart link shown next to the service (item 1 in the following figure) or the application whose runtime status you want to control.

Step 4

Click the Show Jobs List link at upper right to view the runtime control job's progress in the Crosswork Managerwindow's Jobs List view.

Step 5

When you are finished, click the Show Application Details link to re-display the Applications Detail view.

Manage Backup and Restore

The Backup Restore functionality is critical to prevent data loss in your Cisco Crosswork Change Automation and Health Insights VM.

Follow the steps below to create a backup for the Cisco Crosswork Change Automation and Health Insights VM and to restore a backup.

Important

- Cisco recommends that you perform the backup or restore operation only during a scheduled maintenance window when admin users should not access the UI. Both operations are time-consuming and stops all other applications running in the system.

- The same Cisco Crosswork Change Automation and Health Insights software image that was used to backup must also be used when doing a restore operation.

- Stay on the Backup Restore window until the backup/restore process completes. Otherwise, you may see incorrect content or UI errors since various services are rebooting frequently.

- Only one backup or restore operation can be running at any given time.

Before you begin, ensure that:

- You have the Host Name, Port number, and Remote path to a Secure FTP server to use as the destination for backup files.

- You have the user credentials to an account with write permissions to create files and directories in the destination server remote path.

Procedure

Step 1

From the main menu, choose Admin > Backup Restore. The Backup Restore window is displayed.

Step 2

During your first login, you should configure a destination server to store the backup file. This is a one-time activity and has to be completed before taking the backup. Click Destination to display the Edit Destination dialog box. Make relevant entries in the fields provided.

Click Save to confirm the server details.

Step 3

To create a backup:

1. Click Backup. The Backup dialog box is displayed with destination server details pre-filled.

2. Provide a relevant name in the Job Name field.

3. (Optional) Click Verify Backup to check if Cisco Crosswork Change Automation and Health Insights has enough resources to complete the operation. If the check is successful, a warning message is displayed about the time-consuming nature of the operation. Click OK.

4. Click Start Backup to start the backup operation. The corresponding backup job set is created and added to the job list. See Step 5 to view Backup progress.

Step 4

To restore a backup file:

1. Select the required backup file from the Backup Restore Job Sets table, and the job details are displayed on the right side.

2. Click the Restore button to display the Restore dialog box with destination server details pre-filled.

3. Provide a relevant name in the Job Name field.

4. (Optional) Click Verify Restore to check if Cisco Crosswork Change Automation and Health Insights has enough resources to complete the operation. If the check is successful, a warning message is displayed about the time-consuming nature of the operation. Click OK.

5. Click Start Restore to start the restore operation. The corresponding restore job set is created and added to the job list.

Step 5

To view the progress of a backup or restore job:

1. Enter the job details (such as Status, Job Name, or Job Type) in the search fields in Backup Restore Job Sets table on the left side. Click to select which columns to display in the Job set list. The list is automatically filtered based on your search string. Click the required job set from the search results.

2. Alternately, you can manually scroll the list and click the required job set.

3. The Job Details table on the right side displays information about the selected job set such as Status, Job Type and Start time. In case of a failed job, hover the mouse pointer over the icon near Status to view the error details.

- Disaster Restore

Disaster Restore

Disaster Restore is a restore operation, appropriately named to be used in case of a disaster, such as VM crash. The Disaster Restore option is displayed if no backup jobs have been initiated in the system. After the completion of the first backup job, this button is disabled.

Note

While using disaster recovery operation, please note the following:

- The new VM that you use needs to have the same IP address as the one where backup was performed. This is important as internal certificates are tied to the IP address.

- The same software image that was used to backup must also be used when doing a restore operation.

- The VM which is brought up should have same services running when the backup was performed. If the previous VM was patched/upgraded then the new VM also needs to be patched/upgraded before disaster restore is performed.

- The disaster restore operation trusts the backup file which is provided. Caution is advised while selecting the appropriate backup file.

To perform a disaster restore:

Procedure

Step 1

From the main menu, choose Admin > Backup Restore. The Backup Restore window is displayed.

Step 2

Click Destination to display the Edit Destination dialog box. Enter the details of the remote destination server where the backup file is uploaded.

Step 3

Click Disaster Restore to display the Disaster Restore dialog box with destination server detailed pre-filled.

Step 4

Make relevant entry in the Backup File Name field.

Step 5

Click Start Restore to start the disaster restore operation.

Note

If disaster restore operation fails, you are recommended to bring up a new VM to retry the disaster restore operation.

Manage Users

From the main menu, select Admin > Users to display the Users window. Using this window, you can add a new user, edit the settings for an existing user, delete a user from the network, and create user roles.

Note

Before you can create a new user that does not have admin-level access to Cisco Crosswork Change Automation and Health Insights functionality, you must first create a new role that limits the features they can access. See Define Role Settings for more information.

Only a local admin user can add, update, and delete other local user accounts. A TACACS+ user, regardless of role assigned, will not be able to manage local users.

- Administrative Users Created During Installation

- Add Users

- Edit Users

- Delete Users

- User Roles, Functional Categories and Permissions

- Create User Roles

- Edit User Roles

- Clone User Roles

- Delete User Roles

Administrative Users Created During Installation

During installation, Cisco Crosswork Change Automation and Health Insights creates two special administrative IDs:

1. The virtual machine administrator, with the username cw-admin, and the default password admin. Data center administrators use this ID to log in to and troubleshoot the VM hosting the Cisco Crosswork Change Automation and Health Insights server.

2. The Crosswork administrator, with the username admin and the default password admin. Product administrators use this ID to log in to and configure the Cisco Crosswork Change Automation and Health Insights user interface, and to perform special operations, such as creating new user IDs.

The default password for both administrative user IDs must be changed the first time they are used. You can also change the Crosswork administrator password using the following methods:

- Log in as the admin user and edit the admin user password, as explained in Edit Users.

- Enter the following command: admin(config)# username admin <password>

Add Users

Follow the steps below to create a new user ID.

The user ID's user name must be unique. You cannot create a new user ID with the same user name as an existing user ID.

The special administrative user names admin (for administering Cisco Crosswork Change Automation and Health Insights) and cw-admin (for administering the virtual machine hosting the product) are created during installation and are reserved for those purposes (see Administrative Users Created During Installation).

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Users tab.

Step 2

Click to open the Add New User dialog box.

Step 3

Enter the following information for the user you are adding:

- User Name: Enter a unique name for the user ID. User names cannot contain spaces or special characters.

- First Name and Last Name: Enter the first and last name of the person assigned to this user ID.

- From the Role drop-down at the bottom of the dialog box, choose the role that you want to assign to the user. See Define Role Settings for more information.

- Password and Confirm Password: Enter the default password for this user ID. The user will be required to change the default password the first time they attempt to log on using it.

Note

The user password must be string of minimum 8 characters without spaces and should include letters, numbers, upper-case and lower-case characters, and one of the allowed special characters ("@!$%*?&").

Step 4

Click Save.

Edit Users

Users with administrator privileges can edit any user ID's User Name, First Name, Last Name, and Role.

Administrators cannot change a user's password by editing the user ID. Users can change their passwords by logging in, clicking , and selecting Change Password.

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Users tab.

Step 2

Click on the check box of the user whose settings you want to update, then click to open the Edit User dialog box.

Step 3

Make the necessary updates to the user ID.

Note

First Name, Last Name and Role can be edited for user accounts with administrative privileges.

Step 4

Click Update to save your changes.

Delete Users

Follow the steps below to delete an existing user ID.

The administrative user IDs admin and cw-admin created during installation cannot be deleted (see Administrative Users Created During Installation).

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Users tab.

Step 2

Click on the check box of the user you want to delete, then click . TheDelete Username User dialog displays.

Step 3

Click Delete to confirm deletion.

User Roles, Functional Categories and Permissions

The Roles window lets users with the appropriate privileges define custom user roles. As with the default admin role, a custom user role consists of:

- A unique name, such as “Operator” or “admin”.

- One or more selected, named functional categories, which control whether or not a user with that role has access to the APIs needed to perform specific Crosswork functions controlled by that API. For example: The “Health Insights” category provides access to all of the “Health Insights API” functions, such as selecting and running KPI Profiles, importing custom user-defined KPIs, deleting custom KPIs, and so on.

- One or more selected permissions, which control the scope of what a user with that role can do in the functional category.

For a user role to have access to a functional category, that category and its underlying API must show as selected on the Roles page for that role. If the user role shows a functional category as unselected, then users with this role assigned will have no access to that functional area at all.

Some functional categories group multiple APIs under one category name. For example: The “AAA” category controls access to the Password Change, Remote Authentication Servers Integration, and Users and Role Management APIs. With this type of category, you can deny access to some of the APIs by leaving them unselected, while providing access to other APIs under the category by selecting them . For example: If you want to create an “Operator” role who is able to change his own password, but not see or change the settings for your installation’s integration with remote AAA servers, or create new users and roles, you would select the “AAA” category name, but uncheck the “Remote Authentication Server Integration API” and “Users and Role Management API” checkboxes.

For each role with a selected category, the Roles page also lets you define permissions to each underlying functional API:

- Read permission lets the user see and interact with the objects controlled by that API, but not change or delete them.

- Write permission lets the user see and change the objects controlled by that API, but not delete them.

- Delete permission gives the user role delete privileges over the objects controlled by that API. It is useful to remember that delete permission does not override basic limitations set by the Crosswork platform and it applications.

Although you can mix permissions as you wish:

- If you select an API for user access, you must provide at least “Read” permission to that API.

- When you select an API for user access, Cisco Crosswork Change Automation and Health Insights will assume that you want the user to have all permissions on that API, and will select all three permissions for you, automatically.

- If you uncheck all of the permissions, including “Read”, Cisco Crosswork Change Automation and Health Insights will assume that you want to deny access to the API, and unselect it for you.

Best Practices:

Cisco recommends that you follow these best practices when creating custom user roles:

- Restrict Delete permissions in roles for admin users with explicit administrative responsibility for maintenance and management of the Crosswork deployment as a whole.

- Roles for developers working with all the Crosswork APIs will need the same permissions as admin users.

- Apply at least Read and Write permissions in roles for users who are actively engaged in managing the network using Cisco Crosswork Change Automation and Health Insights.

- Give read-only access to roles for users who only need to see Cisco Crosswork Change Automation and Health Insights data to help their work as system architects or planners.

The following table describes some sample custom user roles you should consider creating:

Sample custom user roles

Role

Description

Categories/API

Privileges

Operator

Active network manager, triggers Playbooks in response to KPI alerts

All

Read, Write

Monitor

Monitors alerts only

Health Insights, Inventory, Topology

Read only

KPI Developer

Develops custom KPIs for others to use

Core Infra, Health Insights, Inventory/All

All

API Integrator

All

All

All

Note

Admin role needs to include permissions for Read, Write, and Delete, while read-write roles need to include both Read and Write permissions.

Create User Roles

Local users with administrator privileges can create new users as needed (see Add Users).

Users created in this way can perform only the functions or tasks that are associated with the user role they are assigned.

The local admin role enables access to all functionality. It is created during installation and cannot be changed or deleted. However, its privileges can be assigned to new local users. Only local users can create or update user roles; TACACS users cannot.

Follow the steps below to create a new user role.

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Roles tab. The Roles window has a Roles table on the left side and a corresponding admin table on the right side which shows the grouping of user permissions for the selected role.

Step 2

On the Roles table, click to display a new role entry in the table.

Step 3

Enter a unique name for the new role.

Step 4

Define the user role's privilege settings:

1. Check the check box for every API that users with this role can access. The APIs are grouped logically based their corresponding application.

2. For each API, define whether the user role has Read, Write, and Delete permission by checking the appropriate check box. You can also select an entire API group (such as AAA), and all the APIs under the group will be selected with Read,Write and Delete permissions pre-selected.

Step 5

Click Save to create the new role.

To assign the new user role to one or more user IDs, edit the Role setting for the user IDs (see Edit Users).

Edit User Roles

Users with administrator privileges can quickly change the privileges of any user role other than the default admin role.

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Roles tab.

Step 2

In the Roles table, click on an existing role to select it. The Admin table on the right side displays the permission settings for the selected role.

Step 3

Define the role's settings:

1. Check the check box for every API that the role can access.

2. For each API, define whether the role has Read, Write, and Delete permission by checking the appropriate check box. You can also select an entire API group (such as AAA), and all the APIs under the group will be selected with Read,Write and Delete permissions pre-selected.

Step 4

When you are finished, click Save to save your changes.

Clone User Roles

Cloning an existing user role is the same as creating a new user role (see Create User Roles), except that you need not set privileges for it. If you like, you can let the cloned user role inherit all the privileges of the original user role.

Cloning user roles is a handy way to create and assign many new user roles quickly. Following the steps below, you can clone an existing role multiple times. Defining the cloned user role's privileges is an optional step; you are only required to give the cloned role a new name. If you like, you can assign it a name that indicates the role you want a group of users to perform. You can then edit the user IDs of that group of users to assign them their new role (see Edit Users). Later, you can edit the roles themselves to give users the privileges you want (see edit user roles).

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Roles tab.

Step 2

Click on an existing role to select it.

Step 3

Click to create a new duplicate entry in the Roles table with all the permissions of the original role.

Step 4

Enter a unique name for the cloned role.

Step 5

(Optional) Define the role's settings:

1. Check the check box for every API that the cloned role can access.

2. For each API, define whether the clone role has Read, Write, and Delete permission by checking the appropriate check box. You can also select an entire API group (such as AAA), and all the APIs under the group will be selected with Read,Write and Delete permissions pre-selected.

Step 6

Click Save to create the newly cloned role.

Delete User Roles

Users with administrator privileges can delete any user role that is not the default admin user role or that is not currently assigned to a user ID. If you want to delete a role that is currently assigned to one or more user IDs, you must first edit those user IDs to assign them to a different user role.

Procedure

Step 1

From the main menu, choose Admin > Users.

The Users window opens.

If it is not already displayed, click the Roles tab.

Step 2

Click on the role you want to delete, to select it.

Step 3

Click to display the Delete Role dialog box.

Step 4

Click Delete to confirm that you want to delete the user role.

Manage TACACS+ Servers

In addition to local database authentication, Cisco Crosswork Change Automation and Health Insights can use TACACS+ servers to authenticate users. TACACS+ is a security protocol that provides centralized validation of users attempting to access your network. It allows for a single access control server (the TACACS+ daemon) to provide authentication, authorization, and accounting (AAA) services independently of one another.

Local database authorization takes precedence over authorization by TACACS+ server. When adding the TACACS+ server, you can specify the priority value for each instance.

Note

Please note that any operation you do following the instructions in this section will affect all new logins to the Cisco Crosswork Change Automation and Health Insights user interface. To minimize session interruption, Cisco recommends that you perform all your TACACS+ changes and submit them in a single session.

- Add a TACACS+ Server

- Edit a TACACS+ Server

- Delete a TACACS+ Server

Add a TACACS+ Server

Before adding a TACACS+ server, you will need to know the server's IP address, port number, shared secret, and service name.

Procedure

Step 1

From the main menu, choose Admin > AAA.

The AAA window opens. If it is not already displayed, click the TACACS+ Servers tab.

Step 2

Click to open the Add Server dialog box.

Step 3

Enter the TACACS+ server's settings, then click Add.

Note

Only the server's IP address, port number, shared secret, and service name are required. You can leave the other values blank, as needed.

Step 4

Click Save Server Changes to submit the changes. You will be prompted with a warning message about restarting the server to update the changes. Click Save Changes to confirm.

Edit a TACACS+ Server

Procedure

Step 1

From the main menu, choose Admin > AAA.

The AAA window opens. If it is not already displayed, click the TACACS+ Servers tab.

Step 2

Click the check box next to the TACACS+ server whose settings you want to update, then click .

The Edit Server dialog box opens.

Step 3

Make the necessary changes, then click Update.

Note

You cannot change the value for the Shared Secret parameter.

Step 4

Click Save Server Changes to submit the changes. You will be prompted with a warning message about restarting the server to update the changes. Click Save Changes to confirm.

Delete a TACACS+ Server

Procedure

Step 1

From the main menu, choose Admin > AAA.

The AAA window opens. If it is not already displayed, click the TACACS+ Servers tab.

Step 2

Click the check box next to the TACACS+ server you want to delete.

Note

You can delete only one TACACS+ server at a time.

Step 3

Click . The Delete server-IP-address dialog box opens.

Step 4

Click Delete to confirm.

Manage LDAP Servers

Cisco Crosswork Change Automation and Health Insights supports the use of LDAP servers to authenticate users. Lightweight Directory Access Protocol (LDAP) is a server protocol used to access and manage directory information. It manages directories over IP networks and runs directly over TCP/IP using simple string formats for data transfer.

Like TACACS+ server, you can specify the priority value to assign precedence in the authentication request.

Note

Please note that any operation you do following the instructions in this section will affect all new logins to the Cisco Crosswork Change Automation and Health Insights user interface. To minimize session interruption, Cisco recommends that you perform all your LDAP changes and submit them in a single session.

- Add a LDAP Server

- Edit a LDAP Server

- Delete a LDAP Server

Add a LDAP Server

Before adding a LDAP server, you will need to know the Server name and URL, Bind DN and credential, Base DN, user filter, DN format, Principal Attribute ID, Policy ID, and connection timeout value.

Procedure

Step 1

From the main menu, choose Admin > AAA.

The AAA window opens. Click on the LDAP Servers tab.

Step 2

Click to open the Add Server dialog box.

Step 3

Enter the LDAP server settings, then click Add.

Note

Priority field value is unique across TACACS+ and LDAP servers. Providing a duplicate value will result in an error.

Step 4

Click Save Server Changes to submit the changes. You will be prompted with a warning message about restarting the server to update the changes. Click Save Changes to confirm.

Edit a LDAP Server

Procedure

Step 1

From the main menu, choose Admin > AAA.

The AAA window opens. Click on the LDAP Servers tab.

Step 2

Click the check box next to the LDAP server whose settings you want to update, then click .

The Edit Server dialog box opens.

Step 3

Make the necessary changes, then click Update.

Step 4

Click Save Server Changes to submit the changes. You will be prompted with a warning message about restarting the server to update the changes. Click Save Changes to confirm.

Delete a LDAP Server

Procedure

Step 1

From the main menu, choose Admin > AAA.

The AAA window opens. Click on the LDAP Servers tab.

Step 2

Click the check box next to the LDAP server you want to delete.

Note

You can delete only one LDAP server at a time.

Step 3

Click . The Delete server-IP-address dialog box opens.

Step 4

Click Delete to confirm.

Define Network Visualization Display Settings

Cisco Crosswork Change Automation and Health Insights administrator privileges are required to configure the display settings that are used by the Network Visualization application.

For a description of how to configure these settings, see the following topics:

- Define Color Thresholds for Link Bandwidth Utilization

- Configure Geographical Map Settings

Manage Certificates

The Cisco Crosswork Change Automation and Health Insights VM-hosted server and its browser-based user interface communicate with each other using SSL certificates exchanged over HTTPS. For details about these protocols, see SSL Certificates and HTTPS

When installed, Cisco Crosswork Change Automation and Health Insights secures these interactions using a self-signed TLS certificate. This certificate has a two-year lifespan, after which it expires. If you want to continue using the expired self-signed certificate to secure server/client communications, you will need to regenerate it by following the steps in Extend Self-Signed Certificate Expiration

If you prefer to secure these communications with a user-provided certificate, either purchased from a Certificate Authority (CA) or self-signed by your organization, you can validate and upload it by following the steps in Substitute a User-Provided Certificate.

The user-provided certificate must meet the following requirements:

- Cisco Crosswork Change Automation and Health Insights supports IP Subject Alternative Name (SAN) server certificates only. The IP address is the primary means to reach the user interface.

- The server will present your user-provided certificates to the browser, so the certificates you supply must be valid both for Cisco and for Cisco Crosswork Change Automation and Health Insights.

- It must also include the required fields and field values shown in the following table.

Required User-Provided Certificate Fields and Values

Field

Description

Value

<NUMBER OF DAYS>

Number of days the certificate will be valid.

Must be greater than 30 days and less than 730 days (or two years)

<COUNTRY>

Country (C=)

US

<STATE>

State (ST=)

CALIFORNIA

<LOCATION>

Location (L=)

SAN JOSE

<ORGANIZATION>

Organization (O=)

CISCO SYSTEMS INC

<ORGANIZATIONAL UNIT NAME>

Organizational Unit (OU=)

CROSSWORK

<COMMON NAME>

Common Name (CN=)

The IP address of the Cisco Crosswork Change Automation and Health Insights server VM.

- The certificate must also have the SAN extension set, with both DNS and IP address keys. The following provides an example of how to generate a self-signed certificate using OpenSSL:

/usr/bin/openssl req \
-x509 \
-nodes \
-days 730 \
-newkey rsa:4096 \
-keyout "filename.key" \
-out "filename.crt" \
-subj "/C=US/ST=CALIFORNIA/L=SAN JOSE/O=CISCO SYSTEMS INC/OU=CROSSWORK/CN=1.1.1.1" \
-extensions SAN \
-config <(cat /etc/ssl/openssl.cnf \
<(printf "\n[SAN]\nsubjectAltName=DNS:0.0.0.0,IP:1.1.1.1"))

- Extend Self-Signed Certificate Expiration

- Substitute a User-Provided Certificate

Extend Self-Signed Certificate Expiration

Follow these steps to regenerate the self-signed certificate and extend its lifetime by two years.

Procedure

Step 1

From the main menu, select Admin > Certificate Management. The Certificate Management window appears.

Step 2

Select the Regenerate Crosswork Certificate radio button.

Step 3

When you are ready, click Regenerate Certificate.

When Cisco Crosswork Change Automation and Health Insights has finished regenerating the certificate, it displays an alert message indicating that the regeneration operation is successful and you will be logged out. You must log in again to continue using Cisco Crosswork Change Automation and Health Insights.

Substitute a User-Provided Certificate

Follow the steps below to validate and upload a user-provided certificate. The certificate must meet the requirements explained in Manage Certificates.

Before you begin

You must know the names of the user-provided certificate and key files and their locations in your local storage.

Procedure

Step 1

From the main menu, select Admin > Certificate Management. The Certificate Management window appears.

Step 2

Select the Validate/Update radio button.

Step 3

Use the Browse button next to each field to browse to and select the key and certificate files you want to validate and use.

Step 4

Click Validate to validate the certificate and key files.

Step 5

Click Update to replace the existing certificate with the user-provided certificate you have validated.

Smart Licensing Registration

This section provides an overview of the Cisco Smart Licensing feature integrated with the Cisco Crosswork Change Automation and Health Insights and describes the instructions to complete the product registration.

- Overview

- Configure Transport Settings

- Register Cisco Crosswork Change Automation and Health Insights

- Manual Actions

- License Authorization Statuses

Overview

Smart Licensing is a software based end-to-end license platform that comprises several tools and processes that authorizes customers to use Cisco products. Smart Licensing provides a software inventory management system that provides Customers, Cisco, and selected Partners with information about Software Ownership and Software Utilization.

A Cisco Smart Account provides the repository for Smart enabled products and enables you to activate Cisco licenses, monitor license usage and track Cisco purchases. The Cisco Smart Software Manager (CSSM) enables you to manage all your Cisco Smart software licenses from one centralized website. With Cisco Smart Software Manager, you may create and manage multiple virtual accounts within your Smart Account to manage licenses. For more information, see https://www.cisco.com/c/en/us/buy/smart-accounts/software-manager.html

From the main menu, select Admin > Smart Licensing Registration to display the Smart Software Licensing window. Using this window, you can register your Cisco Crosswork Change Automation and Health Insights application, edit the transport settings, renew the license, and de-register your application.

Prerequisites for Smart Licensing Registration

You should have:

- A Cisco Smart Account.

- Purchased licenses for the Cisco Crosswork Change Automation and Health Insights application.

Configure Transport Settings

You can configure the transport settings to decide how Cisco Crosswork Change Automation and Health Insights communicates with the Cisco servers.

- Direct: The application directly connects with Cisco Smart Software Manager (CSSM).

- Transport Gateway: The application communicates via a Transport Gateway or CSSM on-prem, which replicates the cloud-based user experience but keeps all communication on premises.

Note

For more information on the CSSM on-prem option, see the Smart Software Manager guide.

- HTTP/HTTPS Gateway: The application connects via an intermediate proxy server. This is applicable only for Direct mode.

Note

Transport Settings cannot be changed while the Cisco Crosswork Change Automation and Health Insights is in Registered mode. You have to de-register to change them.

Procedure

Step 1

In the Smart Software Licensing window, the Transport Settings display the current transport mode selected. To modify, click View/Edit.

The Transport Settings dialog box is displayed.

Step 2

Select the relevant transport mode and make relevant entries in the fields provided.

Step 3

Click Save.

Register Cisco Crosswork Change Automation and Health Insights

To enable licensed features, Cisco Crosswork Change Automation and Health Insights must be registered to CSSM using a registration ID token. Once registered, an Identity Certificate is saved securely in the Smart Account and used for all ongoing communications. The certificate is valid for one year and will be renewed automatically after six months to ensure continuous operation.

Note

For information on generating the registration token, please refer to the support resources provided in the Smart Software Manager webpage.

Procedure

Step 1

From the main menu, select Admin > Smart Licensing Registration to display the Smart Software Licensing window. The registration status

The registration status and license authorization status will be Unregistered and Evaluation mode respectively.

Smart Software Licensing Unregistered

Step 2

In the Smart Software Licensing window, click Register.

The Smart Software Licensing Product Registration dialog box is displayed.

Step 3

In the Product Instance Registration Token field, enter the registration token generated from your Smart Account. Make sure the token ID is accurate and within validity period. For more information, see https://www.cisco.com/c/en_in/products/software/smart-accounts/software-licensing.html.

Step 4

(Optional) If you are re-registering the application, check the Re-register this product registration if it is already registered checkbox.

Step 5

Click Register. It may take a few minutes to process the registration. If successful, the 'Product Registration completed successfully' message is displayed.

The registration status and license authorization status will be updated as Registered and Authorized respectively.

Note

If you encounter a communication timeout error during registration, click OK in the error dialog box and the application will reattempt the registration.

Manual Actions

The renewal of registration and authorization are automatically enabled for Cisco Crosswork Change Automation and Health Insights, by default. However, in the event of a communication failure between the application and the Cisco server, these actions can be manually initiated. You can use the Actions drop-down button to manually renew, re-register and de-register the application.

Procedure

Step 1

In the Smart Software Licensing window, click Actions drop-down button and select the relevant option for the following quick actions.

1. Actions > Renew Authorization: To renew the authorization manually if the automatic renewal service fails at the end of 30 days.

2. Actions > Renew Registration: To renew the registration manually if the automatic renewal service fails at the end of 6 months.

3. Actions > Re-register: Re-register the application, for example, on account of the expiry of registration tokens.

4. Actions > De-register: De-register the application, for example, when the transport settings need to be changed.

Note

Once de-registered, the Cisco Crosswork Change Automation and Health Insights application will be moved to Evaluation mode (if evaluation period is available), or Evaluation Expired mode. For more information, see License Authorization Statuses

Step 2

The selected action is executed successfully.

License Authorization Statuses

Based on the registration status of your Cisco Crosswork Change Automation and Health Insights application, you can see the following License Authorization Statuses.

License Authorization Statuses

Registration Status

License Authorization Status

Description

Unregistered

Evaluation mode

A 90-day evaluation period during which the licensed features of the application can be freely used. This state is initiated when you use the application for the first time.

Evaluation Expired

The application has not been successfully registered at the end of the evaluation period. During this state, the application features are disabled, and you must register to continue using the application.

Registered Expired

The application is unable to contact the CSSM before the expiration of Identity Certificates and has returned to the unregistered state. The application resumes the remaining evaluation period, if available. At this stage, new registration ID token is required to reregister the application.

Registered

Authorized (In Compliance)

The application has been fully authorized to use the reserved licensed features. The authorization is automatically renewed every 30 days.

Out of Compliance

The associated Virtual Account does not have enough licenses to reserve for the application’s current feature use. You must renew the entitlement/usage limit registered with the token to continue using the application.

Authorization Expired

The application is unable to communicate with the CSSM for 90 days or more, and the authorization has expired.

Security Hardening Overview

Security hardening entails making adjustments to ensure that the following components optimize their security mechanisms:

- Cisco Crosswork Change Automation and Health Insights infrastructure

- Cisco Crosswork Change Automation and Health Insights storage system (local or external)

Hardening Cisco Crosswork Change Automation and Health Insights security requires completion of the following tasks:

- Shutting down insecure and unused ports

- Configuring network firewalls

- Hardening the Cisco Crosswork Change Automation and Health Insights infrastructure, as needed

Although your primary source of information is your Cisco representative, who can provide server hardening guidance specific to your deployment, you can also follow the steps in this section to secure Cisco Crosswork Change Automation and Health Insights.

- Authentication Throttling

- Core Security Concepts

- Disable Insecure Ports and Services

- Harden Your Storage

Authentication Throttling

Cisco Crosswork Change Automation and Health Insights throttles the login attempts after a failed login attempt to avoid password guessing and other related abuse scenarios. After a failed login attempt for a username, all authentication attempts for that username would be blocked for 3 seconds. The throttling is applicable to all supported authentication schemes such as TACACS, LDAP and the default local authentication.

Core Security Concepts

If you are an administrator and are looking to optimize the security of your Cisco Crosswork Change Automation and Health Insights product, you should have a good understanding of the following security concepts.

- HTTPS

- SSL Certificates

- 1-Way SSL Authentication

HTTPS

Hypertext Transfer Protocol Secure (HTTPS) uses Secure Sockets Layer (SSL) or its subsequent standardization, Transport Layer Security (TLS), to encrypt the data transmitted over a channel. Several vulnerabilities have been found in SSL, so Cisco Crosswork Change Automation and Health Insights now supports TLS only.

Note

TLS is loosely referred to as SSL often, so we will also follow this convention.

SSL employs a mix of privacy, authentication, and data integrity to secure the transmission of data between a client and a server. To enable these security mechanisms, SSL relies upon certificates, private-public key exchange pairs, and Diffie-Hellman key agreement parameters.

SSL Certificates

SSL certificates and private-public key pairs are a form of digital identification for user authentication and the verification of a communication partner’s identity. Certificate Authorities (CAs), such as VeriSign and Thawte, issue certificates to identify an entity (either a server or a client). A client or server certificate includes the name of the issuing authority and digital signature, the serial number, the name of the client or server that the certificate was issued for, the public key, and the certificate's expiration date. A CA uses one or more signing certificates to create SSL certificates. Each signing certificate has a matching private key that is used to create the CA signature. The CA makes signed certificates (with the public key embedded) readily available, enabling anyone to use them to verify that an SSL certificate was actually signed by a specific CA.

In general, setting up certificates in both High Availability (HA) and non-HA environments involves the following steps:

1. Generating an identity certificate for a server.

2. Installing the identity certificate on the server.

3. Installing the corresponding root certificate on your client or browser.

The specific tasks you need to complete will vary depending on your environment.

Note the following:

- The start-stop sequencing of servers needs to be done carefully in HA environments.

- Non-HA environments, where a virtual IP address is configured, require the completion of a more complicated certificate request process.

1-Way SSL Authentication

This authentication method is used when a client needs assurance that it is connecting to the right server (and not an intermediary server), making it suitable for public resources like online banking websites. Authentication begins when a client requests access to a resource on a server. The server on which the resource resides then sends its server certificate (also known as an SSL certificate) to the client in order to verify its identity. The client then verifies the server certificate against another trusted object: a server root certificate, which must be installed on the client or browser. After the server has been verified, an encrypted (and therefore secure) communication channel is established. At this point, the Cisco Crosswork Change Automation and Health Insights server prompts for the entry of a valid username and password in an HTML form. Entering user credentials after an SSL connection is established protects them from being intercepted by an unauthorized party. Finally, after the username and password have been accepted, access is granted to the resource residing on the server.

Note

A client might need to store multiple server certificates to enable interaction with multiple servers.

To determine whether you need to install a root certificate on your client, look for a lock icon in your browser’s URL field. If you see this icon, this generally indicates that the necessary root certificate has already been installed. This is usually the case for server certificates signed by one of the bigger Certifying Authorities (CAs), because root certificates from these CAs are included with popular browsers.

If your client does not recognize the CA that signed a server certificate, it will indicate that the connection is not secure. This is not necessarily a bad thing. It just indicates that the identity of the server you want to connect has not been verified. At this point, you can do one of two things: First, you can install the necessary root certificate on your client or browser. A lock icon in your browser’s URL field will indicate the certificate was installed successfully. And second, you can install a self-signed certificate on your client. Unlike a root certificate, which is signed by a trusted CA, a self-signed certificate is signed by the person or entity that created it. While you can use a self-signed certificate to create an encrypted channel, understand that it carries an inherent amount of risk because the identity of the server you are connected with has not been verified.

Disable Insecure Ports and Services

As a general policy, any ports that are not needed should be disabled. You need to first know which ports are enabled, and then decide which of these ports can be safely disabled without disrupting the normal functioning of Cisco Crosswork Change Automation and Health Insights. You can do this by listing the ports that are open and comparing it with a list of ports needed for Cisco Crosswork Change Automation and Health Insights.

To view a list of all open listening ports:

Procedure

Step 1

Log in as a Linux CLI admin user and enter the netstat -aln command.

The netstat -aln command displays the server's currently open (enabled) TCP/UDP ports, the status of other services the system is using, and other security-related configuration information. The command returns output similar to the following:

[root@vm ~]# netstat -aln
Active Internet connections (servers and established)
Proto  Recv-Q   Send-Q   Local Address            Foreign Address         State
tcp    0        0        0.0.0.0:111              0.0.0.0:*               LISTEN
tcp    0        0        127.0.0.1:8080           0.0.0.0:*               LISTEN
tcp    0        0        0.0.0.0:22               0.0.0.0:*               LISTEN
tcp    0        0        127.0.0.1:25             0.0.0.0:*               LISTEN
tcp    0        0        127.0.0.1:10248          0.0.0.0:*               LISTEN
tcp    0        0        127.0.0.1:10249          0.0.0.0:*               LISTEN
tcp    0        0        192.168.125.114:40764    192.168.125.114:2379    ESTABLISHED
tcp    0        0        192.168.125.114:48714    192.168.125.114:10250   CLOSE_WAIT
tcp    0        0        192.168.125.114:40798    192.168.125.114:2379    ESTABLISHED
tcp    0        0        127.0.0.1:33392          127.0.0.1:8080          TIME_WAIT
tcp    0        0        192.168.125.114:40814    192.168.125.114:2379    ESTABLISHED
tcp    0        0        192.168.125.114:40780    192.168.125.114:2379    ESTABLISHED
tcp    0        0        127.0.0.1:8080           127.0.0.1:44276         ESTABLISHED
tcp    0        0        192.168.125.114:40836    192.168.125.114:2379    ESTABLISHED
tcp    0        0        192.168.125.114:40768    192.168.125.114:2379    ESTABLISHED
tcp    0        0        127.0.0.1:59434          127.0.0.1:8080          ESTABLISHED
tcp    0        0        192.168.125.114:40818    192.168.125.114:2379    ESTABLISHED
tcp    0        0        192.168.125.114:22       192.168.125.1:45837     ESTABLISHED
tcp    0        0        127.0.0.1:8080           127.0.0.1:48174         ESTABLISHED
tcp    0        0        127.0.0.1:49150          127.0.0.1:8080          ESTABLISHED
tcp    0        0        192.168.125.114:40816    192.168.125.114:2379    ESTABLISHED
tcp    0        0        192.168.125.114:55444    192.168.125.114:2379    ESTABLISHED

Step 2

Check the Cisco Crosswork Change Automation and Health Insights Installation Guide for the table of ports used by Cisco Crosswork Change Automation and Health Insights, and see if your ports are listed in that table. That table will help you understand which services are using the ports, and which services you do not need—and thus can be safely disabled. In this case, safe means you can safely disable the port without any adverse effects to the product.

Note

If you are not sure whether you should disable a port or service, contact your Cisco representative.

Step 3

If you have firewalls in your network, configure the firewalls to only allow traffic that is needed for Cisco Crosswork Change Automation and Health Insights to operate.

Harden Your Storage

We recommend that you secure all storage elements that will participate in your Cisco Crosswork Change Automation and Health Insights installation, such as the database, backup servers, and so on.

- If you are using external storage, contact your storage vendor and your Cisco representative.

- If you are using internal storage, contact your Cisco representative.

- If you ever uninstall or remove Cisco Crosswork Change Automation and Health Insights, make sure that all VM-related files that might contain sensitive data are digitally shredded (as opposed to simply deleted). Contact your Cisco representative for more information.

Chapter 8. Manage Cisco Crosswork Data Gateway

Networks maintain a large amount of data that spans thousands of devices. Cisco Crosswork Change Automation and Health Insights Collection Service collects and manages this data through its integral component - Cisco Crosswork Data Gateway.

This section contains the following topics:

- Overview of Cisco Crosswork Data Gateway

- Manage Cisco Crosswork Data Gateway Instances

- Configure Cisco Crosswork Data Gateway Settings

Overview of Cisco Crosswork Data Gateway

When Cisco Crosswork Change Automation and Health Insights and Cisco Crosswork Change Automation and Health Insights are deployed together, Cisco Crosswork Change Automation and Health Insights acts as the controller application for the Cisco Crosswork Data Gateway instance. You can use the UI to add and manage additional instances of Cisco Crosswork Data Gateway no matter if they are forwarding data to Cisco Crosswork Change Automation and Health Insights or other compatible data consumers. The number of Cisco Crosswork Data Gateway you need depends on the number of devices being supported, the amount of data being processed and your network architecture.

Cisco Crosswork Data Gateway can also be deployed with other Crosswork products and in that case, will have a different controller application.

Note

This chapter explains only the Cisco Crosswork Data Gateway features that can be accessed via Cisco Crosswork Change Automation and Health Insights UI.

For more information about Cisco Crosswork Data Gateway VM and how to manage it, see Appendix B: Configure Cisco Crosswork Data Gateway Base VM.

We also recommended that you read about components of Cisco Crosswork Data Gateway at Cisco Crosswork Data Gateway Components before moving further.

Manage Cisco Crosswork Data Gateway Instances

Cisco Crosswork Data Gateway is initially deployed with just a basic VM called the Base VM (containing only enough software to register itself with its controller).

It follows the instructions from Crosswork - collects data as requested and sends it to the defined output destination.

Depending on your private network's size and configuration, you may require one or more Cisco Crosswork Data Gateway instances for collection. It may be necessary to deploy multiple Cisco Crosswork Data Gateway instances to address the requirements for:

1. Geo-separated regions

2. Massive scale

Cisco recommends the simplest approach of a fixed configuration of devices to a particular instance (such as x to y for CDG1 and (y+1) to z for CDG2).

Note

More complicated approaches for resource optimization and dynamic assignment of tasks are possible and if desired, we recommend working with Cisco Customer Experience team to design the behavior.

Cisco Crosswork Data Gateway features can be accessed via Crosswork Network Automation UI.

To open Cisco Crosswork Data Gateway management view, choose Admin > Data Gateway Management from the left navigation bar in the Crosswork Network Automation UI.

Data Gateway Management View

Item

Description

Data Gateway Metrics Summary Pane

Summarizes the overall metrics of all Cisco Crosswork Data Gateway instances currently enrolled with Crosswork:

- Administration State Tile: shows the number of Cisco Crosswork Data Gateway instances in each adminstration state i.e., Up and Maintenance.

- Operational State Tile: shows the number of Cisco Crosswork Data Gateway instances in each operational state i.e., Up, Error, Degraded, and Unknown.

- Detached Devices Tile: Shows the number of devices that are currently not attached to any Cisco Crosswork Data Gateway instance.

Data Gateways Pane

Provides options to add, edit, and delete Cisco Crosswork Data Gateway VMs, attach/detach devices, change administration state, and filter options.

It also displays the following details for the individual Cisco Crosswork Data Gateway instances:

- Name: Name of the Cisco Crosswork Data Gateway VM.

- Administration State: Adminstration state of the Cisco Crosswork Data Gateway VM. A Cisco Crosswork Data Gateway VM has either of the two states at a time:

- Up: The VM is currently active.

- Maintenance: The VM is not operational ("down") and has been set to "Maintenance" mode by the user. No new jobs are submitted to Cisco Crosswork Data Gateway while it is in this mode.

- Operational State: Operational state of the Cisco Crosswork Data Gateway VM. A Crosswork Data Gateway VM has either of the four states at a time:

- Up: The VM is operational and all individual components are "OK".

- Error:

The VM's operational state is in an error condition. It is either not reachable or all the critical components on the VM are "not OK".

- Degraded:

The VM's operational state is degraded as one or more critical components on the VM are "not OK".

- Unknown:

The VM's operational state is unknown as it has enrolled itself with Crosswork, but hasn't established a session yet.

From the Data Gateways pane, you can add a new Cisco Crosswork Data Gateway instance, update the settings configured for an existing instance, de-enroll an instance, attach devices to an instance, detach devices from a instance, or change adminstration state of an instance.

Data Gateways Pane

Item

Description

1

Click to add a Cisco Crosswork Data Gateway VM. See Add a Cisco Crosswork Data Gateway Instance.

Click to edit the settings for the selected Cisco Crosswork Data Gateway VM. See Update Cisco Crosswork Data Gateway Instance Enrollment Settings.

Click to de-enroll the selected Cisco Crosswork Data Gateway VM. See De-enroll a Cisco Crosswork Data Gateway Instance.

2

Click Attach Devices to attach devices to the selected Cisco Crosswork Data Gateway VM. See Attach a Device to a Cisco Crosswork Data Gateway Instance.

3

Click Detach Devices to detach devices from the selected Cisco Crosswork Data Gateway VM. See Detach a Device From a Cisco Crosswork Data Gateway Instance.

4

Click Adminstration State to switch administration state of the selected Data Gateway VM. See Change the Administration State of a Cisco Crosswork Data Gateway Instance.

5

Click to refresh the Data Gateways window.

Click to choose the columns to make visible in the Data Gateways window (see Set, Sort and Filter Table Data).

6

Click to set filter criteria on one or more columns in the Data Gateways window.

Click the Clear All Filters link to clear any filter criteria you may have set.

The Data Gateways pane displays the following details of the enrolled Cisco Crosswork Data Gateway instances:

Field

Description

Name

Name of the Cisco Crosswork Data Gateway.

Administration State

Adminstration state of the Cisco Crosswork Data Gateway instance.

Operational State

Operational state of the Cisco Crosswork Data Gateway instance.

Attached Device Count

Number of devices attached to the Cisco Crosswork Data Gateway instance.

Unique Identifier

Unique identifier of the Cisco Crosswork Data Gateway instance.

- Add a Cisco Crosswork Data Gateway Instance

- Update Cisco Crosswork Data Gateway Instance Enrollment Settings

- View Enrollment Details

- Change the Administration State of a Cisco Crosswork Data Gateway Instance

- De-enroll a Cisco Crosswork Data Gateway Instance

- Attach a Device to a Cisco Crosswork Data Gateway Instance

- Detach a Device From a Cisco Crosswork Data Gateway Instance

- View Cisco Crosswork Data Gateway Instance Health

Add a Cisco Crosswork Data Gateway Instance

After installing Cisco Crosswork Data Gateway, you must enroll it with Cisco Crosswork Change Automation and Health Insights.

After enrolling, you must verify that the operational state of the Cisco Crosswork Data Gateway instance is Up before beginning to use it.

Note

Watch out for "alerts" at the top of the Data Gateway page while the Cisco Crosswork Data Gateway is not operationally up.

Procedure to enroll a Cisco Crosswork Data Gateway instance is described in Cisco Crosswork Change Automation and Health Insights 3.1 Installation Guide in Section: Enroll Cisco Crosswork Data Gateway With Cisco Crosswork Change Automation and Health InsightsCisco Crosswork Optimization Engine

Update Cisco Crosswork Data Gateway Instance Enrollment Settings

If there's an update for the Cisco Crosswork Data Gateway VM, you can regenerate a new enrollment package and upload it to Crosswork by following these steps:

Before you begin

Ensure that you have manually copied the new enrollment package to your local PC as per the procedure described in the Cisco Crosswork Change Automation and Health Insights 3.1 Installation Guide in Section: Export Enrollment Package.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Management. The Data Gateway Management view opens.

Step 2

From the Data Gateways window, select the Cisco Crosswork Data Gateway instance you want to update.

Step 3

Click to edit the settings for the selected Cisco Crosswork Data Gateway instance.

Step 4

In the Update Data Gateway pop up, click Browse to select the new enrollment package.

Select the admin state in which you want to bring up the Cisco Crosswork Data Gateway instance.

Step 5

Click Enroll.

View Enrollment Details

To view enrollment details of a Cisco Crosswork Data Gateway instance, in the Data Gateways pane, click icon next to the Cisco Crosswork Data Gateway name as shown in the following figure.

Note

Some of these details are the OVF parameters that were configured in the OVA Template while installing Cisco Crosswork Data Gateway. For description of these parameters, see Section: Install Crosswork Data Gateway in Cisco Crosswork Change Automation and Health Insights 3.1 Installation Guide.

Following enrollment details are displayed:

Field

Description

Summary

name

Name of the Cisco Crosswork Data Gateway instance.

description

User-friendly description to be displayed in the controller i.e., Crosswork.

Additional Details

duuid

Unique identifier for the Cisco Crosswork Data Gateway instance.

version

Currently installed version of Cisco Crosswork Data Gateway.

role

Is the Cisco Crosswork Data Gateway instance active or in maintenance mode.

cpu

Number of vCPUs.

memory

Amount of total memory.

nics

Number of NICs being used by Cisco Crosswork Data Gateway. This is 3 in case of on-premise installation i.e., for Cisco Crosswork Change Automation and Health Insights.

interfacename

Name of the interface.

interfacemac

MAC address of the interface

interfaceIPv4address/interfaceIPv6address

IPv4/IPv6 address of the interface.

cert_chain

Certificate used for handshake between Cisco Crosswork Data Gateway instance and Cisco Crosswork Change Automation and Health Insights.

Change the Administration State of a Cisco Crosswork Data Gateway Instance

You can change the adminstration state of a Cisco Crosswork Data Gateway instance via Crosswork UI.

Note

If the maintenance activities are affecting the communication between Crosswork and Cisco Crosswork Data Gateway, the collection is interrupted and resumes when the communication is restored.

While an instance is in in Maintenance mode, no new jobs are submitted to it. During downtime, admin can do modifications to Cisco Crosswork Data Gateway, such as updating the certificates, changing management address, etc.

Once changes are done, Admin can change the administration state to Up. Once the Cisco Crosswork Data Gateway is up, Crosswork resumes sending jobs to it.

Follow the steps below to change the administration state of a Cisco Crosswork Data Gateway instance.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Management. The Data Gateway Management view opens.

Step 2

From the Data Gateways window, select the Cisco Crosswork Data Gateway instance whose administration state you want to change.

Step 3

From the Administration State dropdown, select the state to which you want to switch to.

De-enroll a Cisco Crosswork Data Gateway Instance

Follow the steps below to de-enroll a Cisco Crosswork Data Gateway instance.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Management. The Data Gateway Management view opens.

Step 2

From the Data Gateways window, select the Cisco Crosswork Data Gateway instance you want to delete.

Step 3

Click .

Step 4

A Cisco Crosswork Data Gateway instance must be in maintenance mode to be deleted. Click Switch & Continue when prompted to switch to Maintenance mode.

The selected Cisco Crosswork Data Gateway instance is deleted.

Attach a Device to a Cisco Crosswork Data Gateway Instance

Note

A device can only be attached to one Cisco Crosswork Data Gateway instance.

Follow the steps below to attach a device to a Cisco Crosswork Data Gateway instance.

Before you begin

1. For optimal performance, it is recommended that device attaching to Cisco Crosswork Data Gateway instance should be done in batches of no more than 300 devices.

You can add more than 300 devices. However, doing so may cause a performance impact.

2. Ensure that both the adminstration state and operational state of the Cisco Crosswork Data Gateway instance to which you want to attach devices is "Up". Only then proceed with attaching devices.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Management. The Data Gateway Management view opens.

Step 2

From the Data Gateways window, select the Cisco Crosswork Data Gateway instance which you want to attach devices to.

Step 3

Click Attach Devices. The Attach Devices window opens. It lists all the devices available for attaching.

Step 4

To attach all the devices click Attach All Devices. Otherwise, select the devices you want to attach and click Attach Selected Devices.

What to do next

To verify if the devices were attached to the VM, check the Attached Device Count under Data Gateways pane. The count would have increased.

Click on icon next to the attached device count to see the list of all devices attached to the selected instance as shown in the following figure.

Detach a Device From a Cisco Crosswork Data Gateway Instance

Follow the steps below to detach a device from a Cisco Crosswork Data Gateway instance.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Management. The Data Gateway Management view opens.

Step 2

From the Data Gateways window, select the Cisco Crosswork Data Gateway instance from which you want to detach devices.

Step 3

Click Detach Devices. The Detach Devices window opens. It lists all the devices attached to the selected Cisco Crosswork Data Gateway instance.

Step 4

To detach all the devices click Detach All Devices. Otherwise, select the devices you want to detach and click Detach Selected Devices.

What to do next

To verify if the devices were detached from the VM, check the Attached Device Count under Data Gateways window. The count would have decreased.

View Cisco Crosswork Data Gateway Instance Health

Cisco Crosswork Data Gateway comprises of various containerized services running on an Ubuntu VM. Its overall health depends on health of each containerized service.

Cisco Crosswork Data Gateway collects host and container metrics and writes them to a container mounted path in vitals.json file and sends it to the Crosswork.

Vitals also contains the health information of individual container services running on the Cisco Crosswork Data Gateway instance and their resource consumption.

To view health of a Cisco Crosswork Data Gateway instance, in the Data Gateways window, click the name of the Cisco Crosswork Data Gateway instance whose health you want to view as shown in the following figure.

The Health pop up displays the following details:

Field

Description

Host VM

Last Refresh

Date and time of the last refresh.

Click to refresh the Data Gateway Health pop up.

Disk Space Used

Percentage of the disk space used for partitions:

/

/opt/dg/log

/var/lib/docker

Disk In/Out

Number of read/write or input/output operations involving a disk for the partitions:

/

/opt/dg/log

/var/lib/docker

Note

This is a cumulative counter, not a delta time series.

CPU Utilization

Amount of actively used CPU and total number of vCPUs.

Load

Load average – is the average system load over a given period of time of 1, 5, and 15 minutes.

Memory

Amount of memory used and available memory.

Network In/Out

The amount of data sent/received in MB for NIC interfaces:

eth0

eth1

eth2

Note

This is a cumulative counter, not a delta time series.

Service Status

Service

Name of the Cisco Crosswork Data Gateway service.

Status

Status of the service:

- Running

- Degraded

- Error

CPU Utilization

Percentage of actively utilized CPU by the service.

Version

Version of the service deployed.

Memory Used (MB)

Amount of memory being used by the service.

Network In/Out

The amount of data sent/received in MB by the service over its interface.

Note

This is a cumulative counter, not a delta time series.

Disk In/Out

Number of read/write or input/output operations that the service has done involving a disk.

Note

This is a cumulative counter, not a delta time series.

Configure Cisco Crosswork Data Gateway Settings

This section describes how to configure global settings for Cisco Crosswork Data Gateway i.e., managing data destinations and custom software packages.

To open Cisco Crosswork Data Gateway global settings view, choose Admin > Data Gateway Global Settings from the left navigation bar in the Cisco Crosswork Change Automation and Health Insights window.

Data Gateway Global Settings View

Item

Description

Data Destinations Pane

Shows approved external data destinations that can be used by collection jobs to deposit their data and provides options to add, edit, and delete data destinations.

Custom Software Pane

Provides options to:

- add and delete custom MIBs and device packages

- download custom MIBs, system MIBs, and device packages

- Manage Data Destinations

- Manage Custom Software Packages

Manage Data Destinations

From the Data Destinations pane, you can add a new data destination, update the settings configured for an existing data destination, and delete a data destination.

Note

The Crosswork_Kafka data destination in the below figure is Cisco Crosswork Change Automation and Health Insights's internal data destination and hence, it cannot be updated or deleted.

Data Destinations Pane

Item

Description

1

Click to add a data destination. See Add a Data Destination.

Click to edit the settings for the selected data destination. See Update a Data Destination.

Click to delete the selected data destination. See Delete a Data Destination.

2

Click to refresh the Data Destinations window.

Click to choose the columns to make visible in the Data Destinations window (see Set, Sort and Filter Table Data).

3

Click to set filter criteria on one or more columns in the Data Destinations window.

Click the Clear All Filters link to clear any filter criteria you may have set.

Data Destination pane displays the following details of the data destinations:

Field

Description

Destination Name

Name of the data destination

Server Type

Server type of the data destination i.e., external Kafka or gRPC server.

Compression Type

Compression type being used for the data destination. Crosswork

Encoding

Encoding type being used for the data destination.

UUID

Unique identifier for the data destination. This ID is automatically generated by Crosswork when an external data destination is created and is a required parameter for collection job creation.

- Add a Data Destination

- Update a Data Destination

- View Data Destination Details

- Delete a Data Destination

Add a Data Destination

Note

If you reinstall an already existing external Kafka data destination with the same IP address, then the collectors need to be restarted for changes to take place .

Follow the steps below to add a new data destination. You can then use this data destination for data collection. You can add multiple data destinations.

Before you begin

If you are using an external Kafka server for data collection, ensure the following:

- You have configure the following properties on the external Kafka server:

Note

Refer your Kafka documentation for description and usage of these properties as this explanation is out of scope of this document.

- num.io.threads = 8

- num.network.threads = 3

- message.max.bytes= 30000000

- Create Kafka topics that you want to be used for data collection.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Global Settings.

Step 2

From Data Destinations pane, choose .

Step 3

In the Add Destination pop-up, enter the values for the following fields as per the table below:

Field

Value

Destination Name

Enter a descriptive data destination name. The name can contain a maximum of 128 alphanumeric characters, plus underscores ("_") or hyphens ("-"). No other special characters are allowed.

If you will have many data destinations, make the name as informative as possible to be able to distinguish later.

Server Type

From the drop down, select the server type of your data destination (Kafka/gRPC).

Encoding

From the drop down, select the encoding (json/gpbkv).

Compression Type

From the drop down, select the compression type:

Compression types supported for Kafka are snappy, gzip, lz4, zstd, and none)

Note

zstd compression type is supported only for Kafka 2.0 or higher.

Compression types supported for gRPC are snappy, gzip, and deflate.

Maximum Message Size (bytes) (Kafka-only)

Enter the maximum message size in bytes.

- Default Value: 30000000 bytes/ 30 MB

- Min: 1000000 bytes/1 MB

- Max: 30000000 bytes/ 30 MB

For Maximum Message Size property, you can input a value lesser than the default, but not more.

Batch Size (bytes) (Kafka-only)

Enter the required batch size in bytes.

- Default Value: 6400000 bytes/6.4 MB

- Min: 16384 bytes/ 16.38 KB

- Max: 6400000 bytes/6.4 MB

Note

For Batch Size property, you can input a value lesser than the default, but not more.

Linger (milliseconds) (Kafka-only)

Enter the required linger time in milliseconds.

- Default Value: 5000 ms

- Min: 0 ms

- Max: 5000 ms

Step 4

Select a protocol from the Connection Details options. Cisco Crosswork Data Gateway supports both IPv4 and IPv6.

Step 5

Complete the Connection Details fields as described in the following table. The fields displayed will vary with the connectivity type you chose. The values you enter must match the values configured on the device.

Connectivity Type

Fields

IPv4

Enter the required IPv4 Address/ Subnet Mask, and Port. You can add multiple IPv4 addresses by clicking + Add Another

IPv6

Enter the required IPv6 Address/ Subnet Mask, and Port. You can add multiple IPv6 addresses by clicking + Add Another.

Step 6

Click Save.

What to do next

Create the Kafka topics prior to submitting the job to Crosswork. Depending on external Kafka and how topics are managed in that external Kafka, Cisco Crosswork Data Gateway logs may show the exception listed when and if the topic does not exist at the time of dispatching the collected data to that specific external Kafka / topic. This could be either due to the topic is not yet created or topic got deleted prior to the completion of the requested collection job and dispatching the collected data.

destinationContext: topicmdt4
org.apache.kafka.common.errors.UnknownTopicOrPartitionException: This server does not host this topic-partition.

Update a Data Destination

Note

Updating a data destination causes the Cisco Crosswork Data Gateway instance using it to re-establish a session with that data destination. Thus, the data collection is paused and resumes once the session is re-established.

Follow the steps below to update a data destination.

Procedure

Step 1

From Data Destinations window, select the destination you want to update.

Step 2

Click .

Step 3

In the Edit Destination pop up, make the required changes.

Note

In Edit mode, you cannot update Destination Name and Server Type.

Step 4

Click Save.

View Data Destination Details

To view details of a data destination, in the Data Destinations pane, click icon next to the data destination name whose details you want to see. Cisco Crosswork Data Gateway displays the details as shown in the following figure.

Delete a Data Destination

Follow the steps below to delete a data destination.

Before you begin

A data destination can only be deleted if it is not associated with any collection job. We recommend to check in the Collection Jobs view to see if any collection jobs are using the data destination. See Monitoring Collection Jobs.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Global Settings.

Step 2

From the Data Destinations pane, select the Data destination(s) you want to delete.

Step 3

Click .

Step 4

In Delete Data Destination(s) pop up, click Delete to confirm.

Manage Custom Software Packages

To support third party device CLI and SNMP MIBs, Cisco Crosswork Data Gateway allows you to import the device packages and MIBs to the collectors. Device packages can be imported to allow Cisco Crosswork Data Gateway to retrieve CLI and SNMP data and convert it into xml for third party devices. You can extend the SNMP coverage of Cisco Crosswork Change Automation and Health Insights by uploading Custom MIB Packages with any additional MIB and YANG descriptions you require. If you only wish raw SNMP data, no additional files are needed, the system will fold the entire data package into the the Cisco Crosswork Data Gateway data payload.

Note

MIBs are required only if the collection request references MIB TABLE names or SCALAR names. However, if the requests are OID-based, then MIBs are not required.

Cisco Crosswork Data Gateway allows you to register and deploy three types of custom software packages:

1. CLI Device Package: provides instructions for how to speak to a device using CLI and parse the results into the desired xml.

2. Custom MIB Packages:

3. SNMP Device Package: provides instructions for how to speak to a device using SNMP and parse the results into the desired xml.

Custom MIBs and device packages can be specific to third party devices or be used to filter the collected data or format it differently for Cisco devices. These are editable by the user.

Cisco Crosswork Data Gateway also allows you to download Custom MIB package, System MIB package, and System Device package.

System Device and MIB Packages are bundled in the Crosswork software and are automatically downloaded to the Cisco Crosswork Data Gateway instances. These are NOT modifiable by the user. Custom Device Packages can be downloaded when required for interfacing with third-party devices.

From the Custom Software pane, you can add a new custom package, delete a custom package, and download custom packages.

Item

Description

1

Click to add a new custom package. See Add a Custom Software Package.

Click to delete a custom package. See Delete a Custom Software Package.

2

Click Download Custom MIB Package to download custom MIB packages. See Download Custom or System MIBs and Packages.

3

Click Download System MIB Package to download system MIB packages. See Download Custom or System MIBs and Packages.

4

Click Download System Device Package to download system device packages. See Download Custom or System MIBs and Packages.

5

Click to refresh the Custom Software window.

Click to choose the columns to make visible in the Custom Software window (see Set, Sort and Filter Table Data).

6

Click to set filter criteria on one or more columns in the Custom Software window.

Click the Clear All Filters link to clear any filter criteria you may have set.

Custom Software pane displays the following details for the available custom software packages:

Field

Description

File Name

Name of the custom software package.

Upload Time

Time of the file upload.

Type

Type of the custom software package.

Notes

Notes related to the custom software package entered by the user while importing the package.

- Add a Custom Software Package

- Delete a Custom Software Package

- Download Custom or System MIBs and Packages

Add a Custom Software Package

Crosswork allows you to upload Custom Device Packages in case you want to filter/format the collected raw data differently.

There are two types of upload:

1. Custom MIB Package upload (a single file custom-mib-packages.tar.xz): which is archive of all custom MIBs/YANGs file

2. Individual Device Package Upload

When uploading new MIBs as a part of Custom MIB Package, it’s required that those new MIBs files are loadable within collectors along with existing System MIB files i.e., all dependencies in the files get resolved properly. An offline tool steps are provided for you to ensure that their new MIBs gets parsed and uploaded properly. Accordingly, you can prepare the Custom MIB Package and upload.

For information on how to validate custom MIBs and Yangs i.e., to check if they can be uploaded to Crosswork, see Use Custom MIBs and Yangs on Cisco DevNet.

Note

Crosswork doesn't allow Custom MIB package files to overwrite the System MIB Package files. It results in a failed upload attempt.

Using UI, Admin can upload CLI device packages, custom MIB packages, and SNMP device packages. This gets downloaded on the Cisco Crosswork Data Gateway instance to mounted path of respective collectors.

Follow these steps to import a custom software package into Cisco Crosswork Data Gateway:

Note

- Ensure that the custom software package TAR file has just the device package folders and none of the parent folder or hierarchy of folders as part of the TAR file. If not imported properly, Cisco Crosswork Data Gateway throws exceptions when executing the job with custom device package.

- Crosswork does not implement any control on the files being uploaded other than checking the file extension.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Global Settings.

Step 2

From Custom Software window, choose .

Step 3

From the Add Custom Software pop up, select the type of custom software package you want to import from the Type dropdown.

Step 4

Click in the blank field of Software Location to open the file browser window and select the custom software package to import and click Import File.

Step 5

Add a description of the custom software package in the Notes field. This is recommended if you have many packages, to be able to distinguish among them.

Step 6

Click Upload.

Delete a Custom Software Package

Follow the steps below to delete a custom software package.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Global Settings.

Step 2

From the Custom Software pane, select the custom package you want to delete.

Step 3

Click .

Step 4

In the Delete Custom Software pop up, click Delete to confirm.

Download Custom or System MIBs and Packages

Cisco Crosswork Data Gateway has some pre-loaded MIBs and device packages. You can download them to obtain a tarball of the custom MIBs and device packages from the Crosswork UI, add more custom MIBs and device packages and re-upload them to the Crosswork. See List of Pre-loaded Traps and MIBs for SNMP Collection.

System MIB Packages and System Device Packages are downloadable only. This is only if you want to know the abilities that already exists in the system. These cannot be modified.

If you have a new version, you can delete the existing one and upload the new one.

Follow the below steps to download custom software packages from Crosswork UI.

Procedure

Step 1

From the main menu, choose Admin > Data Gateway Global Settings.

Step 2

From Custom Software pane, choose based on the following table:

If you want to download

Click...

Custom MIB Package

Download Custom MIB Package

System MIB Package

Download System MIB Package

System Device Package

Download System Device Package

Step 3

In the download window, navigate to the location where you want to download the file and click Save.

What to do next

To add new MIBs/Yangs, follow the steps:

1. Extract the package and add new files.

2. Run the package through the offline tool as explained at Use Custom MIBs and Yangs on Cisco DevNet to ensure that it can be uploaded to Crosswork.

3. Tar it back as custom-mib-packages.tar

4. Run XZ utility to compress it to custom-mib-packages.tar.xz

5. Upload the package back into Crosswork by following the steps described at Add a Custom Software Package.

Chapter 9. Configure Collection

This section contains the following topics:

- Collection Service Overview

- Prerequisites for Device Model Driven Telemetry

- About Collection Jobs

- Collection Job Payload Model

- Create Collection Jobs

- Best Practices and Limitations for Creating Collection Jobs

- Collection Jobs

- Monitoring Collection Jobs

- List of Pre-loaded Traps and MIBs for SNMP Collection

- List of Pre-loaded YANG Modules for MDT Collection

Collection Service Overview

Networks maintain a large amount of data that spans thousands of devices. The Cisco Crosswork Change Automation and Health Insights collects and manages that flow of data via Cisco Crosswork Data Gateway in a multi-vendor environment to provide a real-time publish/subscribe model infrastructure to Cisco Crosswork Network Automation applications. The Collection Service is highly scalable in order to meet the performance demands of the Cisco Crosswork Change Automation and Health Insights applications.

Multiple applications requesting same data overload network devices causing outages. Cisco Crosswork Data Gateway's Collection Optimization feature tackles this problem by optimizing collection requests. Thereby, reducing redundant data collections.

Users with administrative privileges can monitor Collection Service status and performance, and start/stop/restart it or its underlying services, using the Cisco Crosswork Change Automation and Health Insights user interface. You can also collect logs and performance metrics for this service. For help with these tasks, see Manage Cisco Crosswork Network Automation.

Prerequisites for Device Model Driven Telemetry

The Cisco Crosswork Change Automation and Health Insights Collection Service configures telemetry as needed on the devices enrolled within the service.

Note

If an operator configures telemetry directly on the same devices either manually or through some mechanism outside of the Collection Service, the commands must not contain the keyword CW. The keyword CW is reserved for use by the Collection Service. In particular, the following commands must not contain the keyword CW when configured outside of the Collection Service:

destination-group
sensor-group
subscription
sensor-group-id
destination-id

For example (invalid telemetry configuration):

telemetry model-driven
destination-group CW_1b4ac245d863cf3e787d42bae97f1d18dd300d5e

For more information, see the telemetry configuration documentation for your particular device (for example: Telemetry Configuration Guide for Cisco ASR 9000)

For collection to work, the maximum number of interfaces on a single device must be less than 8,000. The cumulative count of interfaces across all devices must be less than 30,000.

Invalid Telemetry Configuration

The following sample output shows an invalid telemetry configuration on a device when configured outside of the Collection Service.

telemetry model-driven
destination-group CW_1b4ac245d863cf3e787d42bae97f1d18dd300d5e
address-family ipv4 172.16.2.31 port 31500
encoding self-describing-gpb
protocol tcp
!
!
destination-group CW_6da4e808ed4724911f2288dbaeee605bb62f9617
address-family ipv4 <IP_address> port 31500
encoding self-describing-gpb
protocol tcp
!
!
destination-group CW_7ee5d52d7e513640f71417d4fcdb584c6a883f7c
address-family ipv4 <IP_address> port 31500
encoding self-describing-gpb
protocol tcp
!
!
destination-group CW_bbd6f2991d04e920fbda0f2a5ceb63d1c9f62cdf
address-family ipv4 <IP_address> port 31500
encoding self-describing-gpb
protocol tcp
!

Valid Telemetry Configuration

The following sample output shows a valid telemetry configuration on a device when configured outside of the Collection Service. Note that the <IP_address> referred to in this sample should not be the IP address of the Cisco Crosswork Change Automation and Health Insights server. It should be the IP address of the other data consumer.

telemetry model-driven
destination-group CUSTOM_X_1171424d5b08d674367318299db2f8a0d7d489e9
address family ipv4 <IP_address> port 6700
encoding gpb
protocol grpc no-tls
!
!
sensor-group CUSTOM_X_1171424d5b08d674367318299db2f8a0d7d489e9
sensor-path Cisco-IOS-XR-spirit-install-instmgr-oper:software-install/active
!
subscription CUSTOM_X_1171424d5b08d674367318299db2f8a0d7d489e9
sensor-group-id CUSTOM_X_1171424d5b08d674367318299db2f8a0d7d489e9 sample-interval 70000
destination-id CUSTOM_X_1171424d5b08d674367318299db2f8a0d7d489e9
!

Note

The sample-interval can be changed depending on the size of your network. It is defined in milliseconds and determines how fast you want the data to be pushed out.

Confirm that all PCCs or provider edge routers have telemetry configured and report data to . For example, routers should report prefix and tunnel counters:

RP/0/RP0/CPU0:PE1#show traffic-collector ipv4 counters prefix
Thu Jul 11 08:32:32.993 UTC
Prefix Label Base rate TM rate State
(Bytes/sec) (Bytes/sec)
------------------------------ -------- ------------ ------------ ----------
192.168.0.1/32 16001 1 0 Active
192.168.0.2/32 16002 1 0 Active
192.168.0.3/32 16003 1 0 Active
192.168.0.4/32 16004 2 0 Active
192.168.0.6/32 16006 501023 501021 Active
192.168.0.7/32 16007 17320774 17320772 Active
192.168.0.8/32 16008 3737825 3737823 Active
192.168.0.9/32 16097 3 0 Active
192.168.0.10/32 16096 2 0 Active

RP/0/RP0/CPU0:PE1#show traffic-collector ipv4 counters tunnel
Thu Jul 11 08:32:20.746 UTC
Interface Base rate Base rate State
(Packet/sec) (Bytes/sec)
------------------------------ ------------ ------------ ----------
srte_c_102_ep_192.168.0.7 0 0 Active

Cisco IOS XR devices that are onboarded through telemetry must have the following configuration settings on the device to ensure that NETCONF and SSH work correctly:

ssh server v2
ssh server vrf default
ssh server netconf vrf default
ssh server rate-limit 600
ssh server session-limit 1024
netconf-yang agent ssh

Cisco IOS XR devices that are onboarded through SNMP must have SNMP enabled on the device. The following is an example of an SNMP configuration on a Cisco IOS XR device:

snmp-server community public RO

Please note that, currently, Cisco Crosswork Change Automation and Health Insights does not itself support execution of EXEC privilege commands, such as enable, on devices. These types of commands must be executed using the device console or other means.

About Collection Jobs

As mentioned earlier, Crosswork Data Gateway pulls functional images from the Crosswork. Each functional image represents a collection type. You can create multiple jobs for a given collection type. A collection job describes what task a Crosswork Data Gateway is expected to perform. Crosswork receives the data collection requests via these collection jobs and assigns to a Crosswork Data Gateway instance to serve the request.

You can collect more than one type of data at a time by using separate collection jobs.

For each collection job you create, Crosswork Data Gateway executes the collection request and deposits the collected data in the preferred data destination(s).

Crosswork Data Gateway lets you create three types of collection jobs:

CLI Collection Job

Enables CLI-based data collection (such as device configuration) from the network devices. The CLI collector uses XDE/PAL to collect device data for a given CLI. Only show commands are supported for this type of collection job.

SNMP Collection Job

Enables SNMP-based data collection based on the OIDs supported on the devices.

Supported SNMP versions include SNMPv1, SNMPv2c, and SNMPv3 for data polling and traps.

MDT Collection Job

Collects model driven telemetry data streamed from the device to the Crosswork Data Gateway.

Note

1. Crosswork Data Gateway drops incoming southbound traffic if there is no corresponding (listening) collection job request for the same. It also drops data/SNMP traps received from an unsolicitied device (i.e., not attached to Crosswork Data Gateway). Crosswork Data Gateway records this in log and notifies Crosswork.

2. Polled data cannot be requested from the device until Crosswork Data Gateway is ready to process and transmit the data. If it cannot keep up with the amount of data, it sends an error to northbound interface indicating when the throttling began and condition cleared.

Collection Job Payload Model

A collection job describes the following:

- Data to be collected.

- Devices from which collection is desired and credentials to authenticate.

- Collection intervals (a periodic interval no less than 60 seconds or greater than 32 days or immediately on demand.)

- Data Destinations where the collected data is to be deposited.

A single collection job can contain either CLI commands, SNMP MIB requests, or MDT subscriptions. Crosswork Data Gateway routes the request to the appropriate collector to fetch the requested data.

A collection job has three main parts:

//          Device Groups(s) -- identifies the different device groups from which data is
//                              to be collected and their authentication credentials.
//          Data Destinations(s) -- identifies the different output destination the final data
//                               is sent to
//

Note

Without clustered setup of external Kafka, if two destination nodes are specified, one is discarded.

Shown below is a sample collection job payload:

{
"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": "tel:60000"
}
],
"sensor_output_configs": [
{
"sensor_data": {
"cli_sensor": {
"command": "show platform"
}
},
"destination": {
"destination_id": "1e71f2fb-ea65-4242-8efa-e33cec71b369",
"context_id": "topic1"
}
}
]
}
}

The following table explains the fields of the above payload:

Field

Type

(M)andatory or (O)ptional

Description

collection_job

json object

M

Describes collection job with application context as key.

application_context

json object

M

Unique handle to identify your application's subscription.

Note

Combination of application ID and Context ID must be globally unique.

application_id

String

M

Unique identifier for the application.

Note

The prefix "cw" is reserved for Crosswork collection jobs and must not be used for jobs of other applications.

context_id

String

M

Unique identifier for the application subscription across all the collection jobs.

collection_mode

json object

M

A json object that holds lifetime type and collector type attributes of the collection job.

lifetime_type

string

O

Type of lifetime of job:

- UNKNOWN_TEMPORAL_TYPE (default)

- APPLICATION_MANAGED

- CALENDAR_MANAGED

- AUTO_DELETE_AFTER_ N_SAMPLES

collector_type

string

M

Type of the collector:

- UNKNOWN_COLLECTOR (default)

- CLI_COLLECTOR

- SNMP_COLLECTOR

- TRAP_COLLECTOR

- MDT_COLLECTOR

n_collections

int

M

Number of collections to run before auto-deletion. Used only when lifetime_type is AUTO_DELETE_ AFTER_N_SAMPLES.

job_device_set

json object

M

A json object containing device sets information.

device_set

json object

M

Device Grouping Object. For a given request, set one of either one device grouping i.e., list of devices or a device group, but not both.

device_ids

json array

M

Array of device IDs. Corresponds to UUID of the devices in the Crosswork inventory.

sensor_input_configs

json object

M

A group of sensors and their cadences.

sensor_data

json object

M

Type of sensor data:

- snmp_sensor

- snmp_yang_sensor

- cli_yang_sensor

- cli_sensor

- mdt_sensor

- trap_sensor

- trap_yang_sensor

Note

YANG sensors are used for Crosswork initiated collection jobs, whereas Non-YANG sensors are used for API-initiated collection jobs.

cadence_in_millisec

int

O

Optional cadence value of this sensor config in seconds. If not passed the sensor config collection is done once.

sensor_output_configs

json array

M

A group of sensors and their cadences. Sensor Output represents output of sensor to a destination for given sensor which is a topic on Kafka or gRPC server.

sensor_data

json object

M

Every sensor path on the input side needs to have one mapping on the output side:

- snmp_sensor

- snmp_yang_sensor

- cli_yang_sensor

- cli_sensor

- mdt_sensor

- trap_sensor

- trap_yang_sensor

Note

YANG sensors are used for Crosswork initiated collection jobs, whereas Non-YANG sensors are used for API-initiated collection jobs.

destination

json object

M

A JSON object that holds the final data destination information. It can hold one or more type of target information. Currently supported data destinations are kafka and gRPC.

destination > context_id

string

M

Destination context identifier. It could be Kafka topic name if destination is external Kafka server. The combination of destination_id and context_id needs to be unique for destination.

What context id means depends on the destination type of destination provider. If gRPC is destination type, context_id is not used and will be ignored.

destination_id

string

M

Unique identifier for the data destination in inventory.

Create Collection Jobs

Note

Cisco Crosswork Data Gateway API access for external data collection integration is separately licensed.

You can create and delete collection jobs using the Crosswork REST APIs. To access API documentation, see API Documentation.

For reference of collection job payloads, see Collection Jobs. Once the collection job is created, Crosswork adds it to the respective collector of the Crosswork Data Gateway.

The collection job is then picked up by the Crosswork Data Gateway for execution when the Image Manager syncs with Crosswork and retrieves the latest boot-config and docker-compose.

Upon successful creation of collection job, if the data destination is up, running, and accessible, Crosswork Data Gateway starts sending data to it. In this scenario, status for per device per sensor config is shown as ACTIVE in the Crosswork UI in Collection Jobs view. See Monitoring Collection Jobs

Note

Sensor output and input configs can be changed post creation by using a PUT collection job API. Other collection job parameters are immutable.

However, if output server is inaccessible, Crosswork Data Gateway fails to send data to it.

If you want to delete a collection job created by a Cisco Crosswork Change Automation and Health Insights application, it must be deleted via the corresponding application only.

Upon job deletion, the collector sends an alert to the Crosswork for that job once all the devices per sensor path execution has stopped that can be viewed in the Crosswork UI at Admin > Collection Jobs.

Best Practices and Limitations for Creating Collection Jobs

Cisco recommends that following best practices be followed while creating collection job payloads:

Limitation

Best Practices

Scale

Maximum size of sensor path collected data is 10 MB.

Crosswork Data Gateway collector data at the same time from N devices cannot exceed 6 GB.

1. Any collected sensor path's data size should not be > 10 MB when data destination is Kafka, otherwise you will get the following error message in collector.log file (to access log files, see Run show-tech.):

RecordTooLargeException: The message is xxxxxxxx bytes when serialized which is larger than the maximum request size you have configured with the max.request.size configuration.

2. Crosswork Data Gateway collector data at the same time from N devices with M sensor path per device and with P average size of collected data per sensor path cannot exceed 6 GB i.e.,

(N = # of devices) x (M = # of sensor path) x (P= Average Message size per sensor path) < 6GB

Log Purge Policy

When total log file size for a collector reaches 2 GB, Crosswork Data Gateway starts cleaning up by removing the old log files.

If you would like to save the old log files, save it to any other remote server before the total log file size reaches 2 GB per collector. This can be done by running show-tech from Crosswork Data Gateway Main Menu > Troubleshooting.

Collection Jobs

This section contains sample collection job payloads for the following collection profiles:

- CLI Collection Job

- SNMP Collection Jobs

- MDT Collection Job

- CLI Collection Job

- SNMP Collection Jobs

- MDT Collection Job

CLI Collection Job

Crosswork Data Gateway supports CLI-based data collection from the network devices. It uses XDE/PAL to collect device data for a given CLI. Only show commands are supported for this type of collection job.

Note

- While creating a CLI collection job, you must validate it for any errors. Crosswork Data Gateway does not validate collection jobs. Hence, even though a collection job is invalid, its staus is still shown as Active on Collection Jobs page in the Crosswork UI.

- Device should not have any banner configuration for CLI collection to work properly. Please refer to device documentation on how to turn this off.

- The value of Cadence is in seconds. It should be set either to 0 to indicate the sensor configured to be collected only once.

OR

It should be >= 60 (i.e. at least 1 minute) up to 2764800 seconds ( i.e. at most 32 days) max, indicating how frequently configured sensor data should be collected.

Following is a CLI collection job sample:

{
"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": "tel: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

Crosswork Data Gateway supports SNMP-based data collection based on the OIDs supported on the devices.

The SNMP collector makes a poll request to Crosswork to get its configuration profile (a list of MIB objects to collect and a list of devices to fetch from). It determines the corresponding OIDs by looking up the pre-packaged list of MIB modules or the custom list of MIB modules.

Note

MIBs are required only if the collection request references MIB TABLE names or SCALAR names. However, if the requests are OID-based, then MIBs are not required.

Once the OIDs are resolved, they are provided as input to the SNMP collectors.

The device packages can be imported into the Crosswork Data Gateway VM as described in Section Add a Custom Software Package.

The following SNMP versions are supported:

- SNMPv1

- SNMPv2c

- SNMPv3

The table below lists supported privacy protocols and the value that needs to be given in the collection payload for SNMP and SNMP Trap collection jobs:

Protocol

SNMP Collection Payload

SNMP Trap Collection Payload

aes

AES

N/A

des56

DES

DES

3des

3DES

3DES

aes 128

AES128

AES128

aes 192

AES192 or CiscoAES192(Cisco specific)

AES192 or CiscoAES192(Cisco specific)

aes 256

AES256 or CiscoAES256(Cisco specific)

AES256 or CiscoAES256(Cisco specific)

Note

- While creating an SNMP collection job, you must validate it for any errors. Crosswork Data Gateway does not validate collection jobs. Hence, even though a collection job is invalid, its status is still shown as Active.

- The value of Cadence is in seconds. It should be set either to 0 to indicate the sensor configured to be collected only once.

OR

It should be >= 60 (i.e. at least 1 minute) up to 2764800 seconds ( i.e. at most 32 days) max, indicating how frequently configured sensor data should be collected.

- When collection from a device is skipped due to previous execution still in progress, Crosswork Data Gateway raises a warning log. No alert is generated for this scenario.

- For SNMP v1/v2c, if the device details (such as host or community string) are incorrect in the payload, Crosswork Data Gateway ignores the traps received from the device and logs the a WARN message.

In case of SNMP v3, if the device details (such as auth, priv, and security name details) are incorrect in the payload, Crosswork Data Gateway filters it out and hence, does not receive the trap. Thus, no WARN message is logged.

Sample Configurations on Device:

Version

Configuration

V1

snmp-server group group1 v1

snmp-server user user1 group1 v1

snmp-server host <host_ip> traps <community_string> udp-port 1062

For example,

snmp-server host 172.29.194.78 traps test udp-port 1062

Note

Version 1 is the default version used by the device.

V2c

snmp-server group group1 v2c

snmp-server user user1 group1 v2c

snmp-server host 172.29.194.142 traps version 2c v2test udp-port 1062

V3

snmp-server group group1 v3 auth notify user1 read user1 write user1

snmp-server view user1 1.3 included

snmp-server user user1 group1 v3 auth md5 <password> priv aes 128 <password>

snmp-server host 172.23.92.193 traps version 3 priv user1 udp-port 1062

The SNMP Collector supports the following operations:

- SCALAR

- MIB_WALK

- TRAP

- DEVICE_PACKAGE

These operations are defined in the sensor config (see payload sample below).

Note

There is an optional deviceParams attribute snmpRequestTimeoutMillis (not shown in the sample payloads) that should be used if the device response time is very high. It’s not recommended to use snmpRequestTimeoutMillis unless you are absolutely certain that your device response time is very high.

The value for snmpRequestTimeoutMillis should be specified in milliseconds:

Default value is 1500 milliseconds

Minimum value is 1500 milliseconds

However, there is no limitation on the maximum value of this attribute.

Following is an SNMP collection job sample:

{
"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 traps are handled in a similar manner. Trap listeners listen on a port and then dispatch data to recipients (based on their topic of interest).

Note

- Device should have been pre-configured by the traps.

- Crosswork Data Gateway listens on UDP port 1062 for Traps.

- Collection jobn gets stuck in Accepted state when wrong authentication credentials are passed for SNMP Traps.

- For list of supported Traps and MIBs, see List of Pre-loaded Traps and MIBs for SNMP Collection.

On receiving a trap, Crosswork Data Gateway does the following validations:

1. Check if any collection job is created for the device.

2. Checks the trap version and community string.

3. For SNMP v3, validates for user auth and priv protocol and credentials.

Following is an SNMP-Trap collection job sample:

{
"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"
}
}
]
}
}

MDT Collection Job

Crosswork Data Gateway supports data collection from network devices using Model-driven Telemetry (MDT) to consume telemetry streams directly from devices.

Note

- MDT collector retains the collection ID that comes as part of the telemetry proto for the device. This behavior is different from CLI and SNMP collectors which compute the collection ID based on the sequence number of the collection.

- MDT collection jobs require some configuration to be done on the device. This configuration is automatically taken care of by NSO.

- If there is some change (delete/update) in existing MDT jobs between backup and restore operations, Crosswork does not replay the jobs for config update on the devices as it involves Provider(NSO). You have to restore configs on provider/devices. Crosswork will just restore the jobs in database.

- Before using any YANG modules, check if they are supported. See Section: List of Pre-loaded YANG Modules for MDT Collection.

It supports data collection for the following transport mode:

- MDT TCP Dial-out Mode

Following is a sample of MDT collection payload:

{
"collection_job": {
"job_device_set": {
"device_set": {
"device_group": "mdt"
}
},
"sensor_output_configs": [{
"sensor_data": {
"mdt_sensor": {
"path": "Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/latest/generic-counters"
}
},
"destination": {
"context_id": "cw.mdt_sensor.cisco-ios-xr-infra-statsd-oper.gpb",
"destination_id": "c2a8fba8-8363-3d22-b0c2-a9e449693fae"
}
},
{
"sensor_data": {
"mdt_sensor": {
"path": "Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/data-rate"
}
},
"destination": {
"context_id": "cw.mdt_sensor.cisco-ios-xr-infra-statsd-oper.gpb",
"destination_id": "c2a8fba8-8363-3d22-b0c2-a9e449693fae"
}
}
],
"sensor_input_configs": [{
"sensor_data": {
"mdt_sensor": {
"path": "Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/data-rate"
}
},
"cadence_in_millisec": "70000"
}, {
"sensor_data": {
"mdt_sensor": {
"path": "Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/latest/generic-counters"
}
},
"cadence_in_millisec": "70000"
}
],
"application_context": {
"context_id": "c4",
"application_id": "a4-mdt"
},
"collection_mode": {
"lifetime_type": "APPLICATION_MANAGED",
"collector_type": "MDT_COLLECTOR"
}
}
}

Monitoring Collection Jobs

From the Collection Jobs view, you can monitor the status of the collection jobs currently active on all the Cisco Crosswork Data Gateway instances enrolled with Cisco Crosswork Change Automation and Health Insights, such as system jobs and API-defined collection jobs.

From the navigation bar, choose Admin > Collection Jobs.

Item

Description

Data Gateway Jobs Pane

Shows the list of all active collection jobs along with their status and application ID.

Job Details Pane

Shows the details of a particular job selected in the Data Gateway Jobs pane.

To view details of a collection job, select the collection job from the Data Gateway Jobs pane. The details of the selected job are displayed in the Job Details pane right next to the Data Gateway Jobs pane.

Item

Description

1

Click to refresh the Data Gateway Jobs window.

Click to choose the columns to make visible in the Data Gateway Jobs window (see Set, Sort and Filter Table Data).

2

Click to set filter criteria on one or more columns in the Data Destinations window.

Click the Clear All Filters link to clear any filter criteria you may have set.

Data Gateway Jobs pane displays only the status and application ID.

Note

- Create Failed error means out of N devices , some devices detup failed. However, the collection would happen on the other devices. You can identify the device(s) causing this error by using Control Status API.

- If job creation failed on a particular device because of NSO errors, after fixing NSO errors , you have to manually change the administration state of the device first to "Down" and then "Up". However, doing so resets the collection on the device.

Note

Create/Delete failed errors are shown in a different screen pop up. Click next to the job status to see details of the error.

- You may also try recreating the job using PUT collection job API with the same payload.

However, when you select a job, more details are displayed in the Job Details pane:

Item

Description

1

Application name and context associated with the collection job.

2

Lifecycle status of the collection job.

3

Job payload of the collection job that you pass in the REST API request. Click icon next to Config Details to view the job configuration. Crosswork Data Gateway lets you view configuration in two modes:

- View Mode

- Text Mode

4

Collection Type

5

Time and date of last modification of the collection job.

6

Collections (x): x refers to requested input collections that span device by sensor paths. The corresponding (y) Issues is the count of input collections that are in UNKNOWN or FAILED state.

7

Distributions (x): x refers to requested output collections that span device by sensor paths. The corresponding (y) Issues is the count of output collections that are in UNKNOWN or FAILED state.

8

Click to refresh the Job Details window.

Click to choose the columns to make visible in the Job Details window (see Set, Sort and Filter Table Data).

9

Click to set filter criteria on one or more columns in the Job Details window.

Click the Clear All Filters link to clear any filter criteria you may have set.

Job Details pane displays the following details about a collection job:

Field

Description

Collection/Distribution Status

Status of the collection/distribution. It is reported on a on change basis from Cisco Crosswork Data Gateway. Click next to the collection/distribution status for details.

Hostname

Application with which the collection job is associated.

Device Id

Unique identifier of the device from which data is being collected.

Sensor Data

Sensor path

Click to see collection/distribution summary. From the sensor data summary pop up you can copy the sensor data by clicking Copy to Clipboard.

and

Click to see collection/distribution metrics summary. The metrics are reported on cadence-basis i.e., once every 10 minutes by default. It shows the following metrics for a collection:

- last_collection_time_msec

- total_collection_message_count

- last_device_latency_msec

- last_collection_cadence_msec

It shows the following metrics for a collection:

- total_output_message_count

- last_destination_latency_msec

- last_output_cadence_msec

- last_output_time_msec

- total_output_bytes_count

Destination

Data destination for the job.

Last Status Change Reported Time

Time and date on which last status change was reported for that device sensor pair from Cisco Crosswork Data Gateway.

List of Pre-loaded Traps and MIBs for SNMP Collection

This section lists the Traps and MIBs that the Collection Service supports for SNMP collection.

Note

This list is applicable only when Crosswork is the target application and is not limited when the target is an external application.

Note the following constraints:

- The system cannot extract index values from OIDs of conceptual tables. If any of the columns that define indices in the conceptual table are not populated, the index value is replaced on the data plane with the instance identifier (oid suffix) of the row.

- The system cannot extract index values from conceptual tables that include the AUGMENT keyword or refer to indices of other tables.

- Named-number enumerations (using the integer syntax) are sent on the wire using their numeric value.

Supported Yangified Traps

Trap

OID

linkDown

1.3.6.1.6.3.1.1.5.3

linkUp

1.3.6.1.6.3.1.1.5.4

coldStart

1.3.6.1.6.3.1.1.5.1

isisAdjacencyChange

1.3.6.1.2.1.138.0.17

ADSL-LINE-MIB.mib

CISCO-UBE-MIB.mib

JUNIPER-ANALYZER-MIB.mib

ADSL-TC-MIB.mib

CISCO-UNIFIED-COMPUTING -ADAPTOR-MIB.mib

JUNIPER-ATM-COS-MIB.mib

AGENTX-MIB.mib

CISCO-UNIFIED-COMPUTING -COMPUTE-MIB.mib

JUNIPER-ATM-MIB.mib

AIRESPACE-REF -MIB.mib

CISCO-UNIFIED-COMPUTING -ETHER-MIB.mib

JUNIPER-BFD-MIB.mib

AIRESPACE-SWITCHING -MIB.mib

CISCO-UNIFIED-COMPUTING -FC-MIB.mib

JUNIPER-CFGMGMT -MIB.mib

AIRESPACE-WIRELESS -MIB.mib

CISCO-UNIFIED-COMPUTING -MEMORY-MIB.mib

JUNIPER-CHASSIS-DEFINES -MIB.mib

ALARM-MIB.mib

CISCO-UNIFIED-COMPUTING -MIB.mib

JUNIPER-CHASSIS-FWDD -MIB.mib

ALCATEL-IEEE8021 -PAE-MIB.mib

CISCO-UNIFIED-COMPUTING -NETWORK-MIB.mib

JUNIPER-COLLECTOR-MIB.mib

APS-MIB.mib

CISCO-UNIFIED-COMPUTING -PROCESSOR-MIB.mib

JUNIPER-COS-MIB.mib

ARUBA-TC.mib

CISCO-UNIFIED-COMPUTING -TC-MIB.mib

JUNIPER-DCU-MIB.mib

ATM-FORUM-MIB.mib

CISCO-VLAN-IFTABLE -RELATIONSHIP-MIB.mib

JUNIPER-DFC-MIB.mib

ATM-FORUM-TC-MIB.mib

CISCO-VLAN-MEMBERSHIP -MIB.mib

JUNIPER-DOM-MIB.mib

ATM-MIB.mib

CISCO-VOICE-COMMON- DIAL-CONTROL-MIB.mib

JUNIPER-EVENT-MIB.mib

ATM-TC-MIB.mib

CISCO-VOICE-DIAL- CONTROL-MIB.mib

JUNIPER-EX-MAC- NOTIFICATION-MIB.mib

ATM2-MIB.mib

CISCO-VOICE-DNIS-MIB.mib

JUNIPER-EX-SMI.mib

BFD-STD-MIB.mib

CISCO-VPDN-MGMT- MIB.mib

JUNIPER-EXPERIMENT- MIB.mib

BGP4-MIB.mib

CISCO-VTP-MIB.mib

JUNIPER-FIREWALL- MIB.mib

BGP4-V2-MIB-JUNIPER.mib

CISCO-WIRELESS-NOTIFICATION -MIB.mib

JUNIPER-HOSTRESOURCES -MIB.mib

BRIDGE-MIB.mib

CISCOSB-DEVICEPARAMS -MIB.mib

JUNIPER-IF-MIB.mib

CISCO-AAA-SERVER -MIB.mib

CISCOSB-HWENVIROMENT.mib

JUNIPER-IPFORWARD -MIB.mib

CISCO-AAA-SESSION -MIB.mib

CISCOSB-MIB.mib

JUNIPER-IPSEC-FLOW -MON-MIB.mib

CISCO-AAL5-MIB.mib

CISCOSB-Physicaldescription -MIB.mib

JUNIPER-IPv4-MIB.mib

CISCO-ACCESS-ENVMON -MIB.mib

COGNIO-SMI.mib

JUNIPER-IPv6-MIB.mib

CISCO-ATM-EXT-MIB.mib

COGNIO-TRAPS-MIB.mib

JUNIPER-JDHCP-MIB.mib

CISCO-ATM-PVCTRAP -EXTN-MIB.mib

DIAL-CONTROL-MIB.mib

JUNIPER-JDHCPV6-MIB.mib

CISCO-ATM-QOS-MIB.mib

DIFFSERV-DSCP-TC.mib

JUNIPER-JS-AUTH-MIB.mib

CISCO-AUTH-FRAMEWORK -MIB.mib

DIFFSERV-MIB.mib

JUNIPER-JS-CERT-MIB.mib

CISCO-BGP-POLICY- ACCOUNTING-MIB.mib

DISMAN-EVENT-MIB.mib

JUNIPER-JS-DNS-MIB.mib

CISCO-BGP4-MIB.mib

DISMAN-EXPRESSION-MIB.mib

JUNIPER-JS-IDP-MIB.mib

CISCO-BULK-FILE-MIB.mib

DISMAN-NSLOOKUP-MIB.mib

JUNIPER-JS-IF-EXT-MIB.mib

CISCO-CBP-TARGET-MIB.mib

DISMAN-PING-MIB.mib

JUNIPER-JS-IPSEC-VPN -MIB.mib

CISCO-CBP-TARGET -TC-MIB.mib

DISMAN-SCHEDULE-MIB.mib

JUNIPER-JS-NAT-MIB.mib

CISCO-CBP-TC-MIB.mib

DISMAN-SCRIPT-MIB.mib

JUNIPER-JS-POLICY-MIB.mib

CISCO-CCME-MIB.mib

DISMAN-TRACEROUTE-MIB.mib

JUNIPER-JS-SCREENING-MIB.mib

CISCO-CDP-MIB.mib

DOT3-OAM-MIB.mib

JUNIPER-JS-SMI.mib

CISCO-CEF-MIB.mib

DRAFT-MSDP-MIB.mib

JUNIPER-L2ALD-MIB.mib

CISCO-CEF-TC.mib

DS0-MIB.mib

JUNIPER-L2CP-FEATURES -MIB.mib

CISCO-CLASS-BASED -QOS-MIB.mib

DS1-MIB.mib

JUNIPER-LDP-MIB.mib

CISCO-CONFIG-COPY -MIB.mib

DS3-MIB.mib

JUNIPER-MAC-MIB.mib

CISCO-CONFIG-MAN -MIB.mib

ENTITY-MIB.mib

JUNIPER-MAG-MIB.mib

CISCO-CONTENT-ENGINE -MIB.mib

ENTITY-SENSOR-MIB.mib

JUNIPER-MIB.mib

CISCO-CONTEXT-MAPPING -MIB.mib

ENTITY-STATE-MIB.mib

JUNIPER-MIMSTP-MIB.mib

CISCO-DATA-COLLECTION -MIB.mib

ENTITY-STATE-TC-MIB.mib

JUNIPER-MPLS-LDP-MIB.mib

CISCO-DEVICE-EXCEPTION -REPORTING-MIB.mib

ESO-CONSORTIUM-MIB.mib

JUNIPER-OTN-MIB.mib

CISCO-DIAL-CONTROL -MIB.mib

ETHER-WIS.mib

JUNIPER-PAE-EXTENSION -MIB.mib

CISCO-DOT11-ASSOCIATION -MIB.mib

EXPRESSION-MIB.mib

JUNIPER-PFE-MIB.mib

CISCO-DOT11-HT-PHY -MIB.mib

EtherLike-MIB.mib

JUNIPER-PING-MIB.mib

CISCO-DOT11-IF-MIB.mib

FDDI-SMT73-MIB.mib

JUNIPER-PMon-MIB.mib

CISCO-DOT11-SSID- SECURITY-MIB.mib

FR-MFR-MIB.mib

JUNIPER-POWER-SUPPLY- UNIT-MIB.mib

CISCO-DOT3-OAM-MIB.mib

FRAME-RELAY-DTE-MIB.mib

JUNIPER-PW-ATM-MIB.mib

CISCO-DS3-MIB.mib

FRNETSERV-MIB.mib

JUNIPER-PW-TDM-MIB.mib

CISCO-DYNAMIC-TEMPLATE -MIB.mib

GMPLS-LSR-STD-MIB.mib

JUNIPER-RMON-MIB.mib

CISCO-DYNAMIC-TEMPLATE -TC-MIB.mib

GMPLS-TC-STD-MIB.mib

JUNIPER-RPF-MIB.mib

CISCO-EIGRP-MIB.mib

GMPLS-TE-STD-MIB.mib

JUNIPER-RPM-MIB.mib

CISCO-EMBEDDED-EVENT -MGR-MIB.mib

HC-PerfHist-TC-MIB.mib

JUNIPER-RPS-MIB.mib

CISCO-ENHANCED-IMAGE-MIB.mib

HC-RMON-MIB.mib

JUNIPER-RSVP-MIB.mib

CISCO-ENHANCED-MEMPOOL-MIB.mib

HCNUM-TC.mib

JUNIPER-SCU-MIB.mib

CISCO-ENTITY-ASSET-MIB.mib

HOST-RESOURCES-MIB.mib

JUNIPER-SECURE-ACCESS-PORT-MIB.mib

CISCO-ENTITY-EXT-MIB.mib

HOST-RESOURCES-TYPES.mib

JUNIPER-SMI.mib

CISCO-ENTITY-FRU-CONTROL-MIB.mib

HUAWEI-ALARM-RELIABILITY-MIB.mib

JUNIPER-SONET-MIB.mib

CISCO-ENTITY-QFP-MIB.mib

HUAWEI-BASE-TRAP-MIB.mib

JUNIPER-SP-MIB.mib

CISCO-ENTITY-REDUNDANCY-MIB.mib

HUAWEI-BFD-MIB.mib

JUNIPER-SRX5000-SPU-MONITORING-MIB.mib

CISCO-ENTITY-REDUNDANCY-TC-MIB.mib

HUAWEI-BGP-ACCOUNTING-MIB.mib

JUNIPER-SYSLOG-MIB.mib

CISCO-ENTITY-SENSOR-MIB.mib

HUAWEI-BGP-GR-MIB.mib

JUNIPER-TRACEROUTE-MIB.mib

CISCO-ENTITY-VENDORTYPE-OID-MIB.mib

HUAWEI-BGP-VPN-MIB.mib

JUNIPER-USER-AAA-MIB.mib

CISCO-ENVMON-MIB.mib

HUAWEI-BRAS-L2TP-MIB.mib

JUNIPER-UTIL-MIB.mib

CISCO-EPM-NOTIFICATION-MIB.mib

HUAWEI-BRAS-MULTICAST-MIB.mib

JUNIPER-VIRTUALCHASSIS-MIB.mib

CISCO-ETHER-CFM-MIB.mib

HUAWEI-BRAS-PPPoX-MIB.mib

JUNIPER-VLAN-MIB.mib

CISCO-ETHERLIKE-EXT-MIB.mib

HUAWEI-BRAS-SRVCFG-STATICUSER-MIB.mib

JUNIPER-VPN-MIB.mib

CISCO-FABRIC-C12K-MIB.mib

HUAWEI-BRAS-USERVLAN-MIB.mib

L2TP-MIB.mib

CISCO-FIREWALL-TC.mib

HUAWEI-BULKSTAT-MIB.mib

LANGTAG-TC-MIB.mib

CISCO-FLASH-MIB.mib

HUAWEI-CCC-MIB.mib

LLDP-EXT-DOT1-MIB.mib

CISCO-FRAME-RELAY-MIB.mib

HUAWEI-CE-PING-MIB.mib

LLDP-EXT-DOT3-MIB.mib

CISCO-FTP-CLIENT-MIB.mib

HUAWEI-CLOCK-MIB.mib

LLDP-MIB.mib

CISCO-HSRP-EXT-MIB.mib

HUAWEI-CONFIG-MAN-MIB.mib

MAU-MIB.mib

CISCO-HSRP-MIB.mib

HUAWEI-CPU-MIB.mib

MGMD-STD-MIB.mib

CISCO-IETF-ATM2-PVCTRAP-MIB.mib

HUAWEI-DATASYNC-MIB.mib

MPLS-FTN-STD-MIB.mib

CISCO-IETF-BFD-MIB.mib

HUAWEI-DC-TRAP-MIB.mib

MPLS-L3VPN-STD-MIB.mib

CISCO-IETF-FRR-MIB.mib

HUAWEI-DEVICE-EXT-MIB.mib

MPLS-LDP-ATM-STD-MIB.mib

CISCO-IETF-IPMROUTE-MIB.mib

HUAWEI-DEVICE-MIB.mib

MPLS-LDP-FRAME-RELAY-STD-MIB.mib

CISCO-IETF-ISIS-MIB.mib

HUAWEI-DHCPR-MIB.mib

MPLS-LDP-GENERIC-STD-MIB.mib

CISCO-IETF-MPLS-ID-STD-03-MIB.mib

HUAWEI-DIALER-MIB.mib

MPLS-LDP-MIB.mib

CISCO-IETF-MPLS-TE-EXT-STD-03-MIB.mib

HUAWEI-DLDP-MIB.mib

MPLS-LDP-STD-MIB.mib

CISCO-IETF-MPLS-TE-P2MP-STD-MIB.mib

HUAWEI-E-TRUNK-MIB.mib

MPLS-LSR-MIB.mib

CISCO-IETF-MSDP-MIB.mib

HUAWEI-ENTITY-TRAP-MIB.mib

MPLS-LSR-STD-MIB.mib

CISCO-IETF-PIM-EXT-MIB.mib

HUAWEI-EPON-MIB.mib

MPLS-MIB.mib

CISCO-IETF-PIM-MIB.mib

HUAWEI-FIREWALL-MIB.mib

MPLS-TC-MIB.mib

CISCO-IETF-PW-ATM-MIB.mib

HUAWEI-FR-QOS-MIB.mib

MPLS-TC-STD-MIB.mib

CISCO-IETF-PW-ENET-MIB.mib

HUAWEI-FTP-MIB.mib

MPLS-TE-MIB.mib

CISCO-IETF-PW-MIB.mib

HUAWEI-GTL-MIB.mib

MPLS-TE-STD-MIB.mib

CISCO-IETF-PW-MPLS-MIB.mib

HUAWEI-GTSM-MIB.mib

MPLS-VPN-MIB.mib

CISCO-IETF-PW-TC-MIB.mib

HUAWEI-HGMP-MIB.mib

MSDP-MIB.mib

CISCO-IETF-PW-TDM-MIB.mib

HUAWEI-HTTP-MIB.mib

NET-SNMP-AGENT-MIB.mib

CISCO-IETF-VPLS-BGP-EXT -MIB.mib

HUAWEI-HWTACACS-MIB.mib

NET-SNMP-EXAMPLES -MIB.mib

CISCO-IETF-VPLS-GENERIC -MIB.mib

HUAWEI-IF-QOS-MIB.mib

NET-SNMP-MIB.mib

CISCO-IETF-VPLS-LDP-MIB.mib

HUAWEI-IMA-MIB.mib

NET-SNMP-TC.mib

CISCO-IF-EXTENSION-MIB.mib

HUAWEI-IPV6-MIB.mib

NHRP-MIB.mib

CISCO-IGMP-FILTER-MIB.mib

HUAWEI-KOMPELLA-MIB.mib

NOTIFICATION-LOG-MIB.mib

CISCO-IMAGE-LICENSE-MGMT -MIB.mib

HUAWEI-L2IF-MIB.mib

OLD-CISCO-CHASSIS-MIB.mib

CISCO-IMAGE-MIB.mib

HUAWEI-L2MULTICAST-MIB.mib

OLD-CISCO-INTERFACES- MIB.mib

CISCO-IMAGE-TC.mib

HUAWEI-L2TP-EXT-MIB.mib

OLD-CISCO-SYS-MIB.mib

CISCO-IP-LOCAL-POOL -MIB.mib

HUAWEI-L2VPN-MIB.mib

OLD-CISCO-SYSTEM-MIB.mib

CISCO-IP-TAP-MIB.mib

HUAWEI-L3VLAN-MIB.mib

OPT-IF-MIB.mib

CISCO-IP-URPF-MIB.mib

HUAWEI-LDT-MIB.mib

ORiNOCO-MIB.mib

CISCO-IPMROUTE-MIB.mib

HUAWEI-LINE-MIB.mib

OSPF-MIB.mib

CISCO-IPSEC-FLOW-MONITOR -MIB.mib

HUAWEI-LLDP-MIB.mib

OSPF-TRAP-MIB.mib

CISCO-IPSEC-MIB.mib

HUAWEI-LOOPDETECT -MIB.mib

OSPFV3-MIB-JUNIPER.mib

CISCO-IPSEC-POLICY-MAP -MIB.mib

HUAWEI-MEMORY-MIB.mib

OSPFV3-MIB.mib

CISCO-IPSLA-AUTOMEASURE -MIB.mib

HUAWEI-MFLP-MIB.mib

P-BRIDGE-MIB.mib

CISCO-IPSLA-ECHO-MIB.mib

HUAWEI-MIB.mib

PIM-MIB.mib

CISCO-IPSLA-JITTER-MIB.mib

HUAWEI-MINM-MIB.mib

PIM-STD-MIB.mib

CISCO-IPSLA-TC-MIB.mib

HUAWEI-MIRROR-MIB.mib

POWER-ETHERNET-MIB.mib

CISCO-ISDN-MIB.mib

HUAWEI-MPLSLSR-EXT-MIB.mib

PPP-IP-NCP-MIB.mib

CISCO-LICENSE-MGMT -MIB.mib

HUAWEI-MPLSOAM-MIB.mib

PPP-LCP-MIB.mib

CISCO-LOCAL-AUTH-USER -MIB.mib

HUAWEI-MPLSOAM-PS -MIB.mib

PPVPN-TC-MIB.mib

CISCO-LWAPP-AAA-MIB.mib

HUAWEI-MSTP-MIB.mib

PTOPO-MIB.mib

CISCO-LWAPP-AP-MIB.mib

HUAWEI-NAT-EXT-MIB.mib

PerfHist-TC-MIB.mib

CISCO-LWAPP-CCX-RM- MIB.mib

HUAWEI-OSPFV2-MIB.mib

Q-BRIDGE-MIB.mib

CISCO-LWAPP-CDP-MIB.mib

HUAWEI-OSPFV3-MIB.mib

RADIUS-ACC-CLIENT-MIB.mib

CISCO-LWAPP-CLIENT- ROAMING-CAPABILITY.mib

HUAWEI-PERFORMANCE-MIB.mib

RADIUS-AUTH-CLIENT-MIB.mib

CISCO-LWAPP-CLIENT- ROAMING-MIB.mib

HUAWEI-PIM-BSR-MIB.mib

RFC-1212.mib

CISCO-LWAPP-DHCP-MIB.mib

HUAWEI-PIM-STD-MIB.mib

RFC-1215.mib

CISCO-LWAPP-DOT11 -CLIENT-CALIB-MIB.mib

HUAWEI-PORTAL-MIB.mib

RFC1155-SMI.mib

CISCO-LWAPP-DOT11 -CLIENT-CCX-TC-MIB.mib

HUAWEI-PORTBLOCK-MIB.mib

RFC1213-MIB.mib

CISCO-LWAPP-DOT11 -LDAP-MIB.mib

HUAWEI-PPP-MIB.mib

RFC1315-MIB.mib

CISCO-LWAPP-DOT11 -MIB.mib

HUAWEI-RANAPS-MIB.mib

RFC1398-MIB.mib

CISCO-LWAPP-DOWNLOAD -MIB.mib

HUAWEI-RIPV2-EXT-MIB.mib

RIPv2-MIB.mib

CISCO-LWAPP-IDS-MIB.mib

HUAWEI-RM-EXT-MIB.mib

RMON-MIB.mib

CISCO-LWAPP-INTERFACE -MIB.mib

HUAWEI-RRPP-MIB.mib

RMON2-MIB.mib

CISCO-LWAPP-IPS-MIB.mib

HUAWEI-SECURITY-MIB.mib

RSTP-MIB.mib

CISCO-LWAPP-LINKTEST-MIB.mib

HUAWEI-SLB-MIB.mib

RSVP-MIB.mib

CISCO-LWAPP-LOCAL -AUTH-MIB.mib

HUAWEI-SNMP-EXT-MIB.mib

SMON-MIB.mib

CISCO-LWAPP-MDNS-MIB.mib

HUAWEI-SSH-MIB.mib

SNA-SDLC-MIB.mib

CISCO-LWAPP-MESH-BATTERY -MIB.mib

HUAWEI-STACK-MIB.mib

SNMP-COMMUNITY-MIB.mib

CISCO-LWAPP-MESH-LINKTEST -MIB.mib

HUAWEI-SYS-MAN-MIB.mib

SNMP-FRAMEWORK-MIB.mib

CISCO-LWAPP-MOBILITY -EXT-MIB.mib

HUAWEI-TAD-MIB.mib

SNMP-MPD-MIB.mib

CISCO-LWAPP-MOBILITY -MIB.mib

HUAWEI-TASK-MIB.mib

SNMP-NOTIFICATION-MIB.mib

CISCO-LWAPP-NETFLOW -MIB.mib

HUAWEI-TC-MIB.mib

SNMP-PROXY-MIB.mib

CISCO-LWAPP-REAP-MIB.mib

HUAWEI-TCP-MIB.mib

SNMP-REPEATER-MIB.mib

CISCO-LWAPP-RF-MIB.mib

HUAWEI-TRANSPARENTBRIDGE -MIB.mib

SNMP-TARGET-MIB.mib

CISCO-LWAPP-SI-MIB.mib

HUAWEI-TRNG-MIB.mib

SNMP-USER-BASED-SM-MIB.mib

CISCO-LWAPP-TC-MIB.mib

HUAWEI-TUNNEL-MIB.mib

SNMP-USM-AES-MIB.mib

CISCO-LWAPP-TRUSTSEC -MIB.mib

HUAWEI-USERLOG-MIB.mib

SNMP-USM-DH-OBJECTS -MIB.mib

CISCO-LWAPP-TSM-MIB.mib

HUAWEI-VE-MIB.mib

SNMP-VIEW-BASED-ACM -MIB.mib

CISCO-LWAPP-WLAN-MIB.mib

HUAWEI-VGMP-MIB.mib

SNMPv2-CONF.mib

CISCO-LWAPP-WLAN-SECURITY -MIB.mib

HUAWEI-VLL-STATISTIC-MIB.mib

SNMPv2-MIB.mib

CISCO-MEDIA-GATEWAY-MIB.mib

HUAWEI-VPLS-EXT-MIB.mib

SNMPv2-SMI.mib

CISCO-MOTION-MIB.mib

HUAWEI-VPLS-TNL-MIB.mib

SNMPv2-TC-v1.mib

CISCO-MPLS-LSR-EXT-STD -MIB.mib

HUAWEI-WAN-MIB.mib

SNMPv2-TC.mib

CISCO-MPLS-TC-EXT-STD -MIB.mib

HUAWEI-WLAN-DEVICE-MIB.mib

SNMPv2-TM.mib

CISCO-MPLS-TE-STD-EXT -MIB.mib

HUAWEI-WLAN-MIB.mib

SONET-MIB.mib

CISCO-NAC-TC-MIB.mib

HUAWEI-WLAN-QOS-MIB.mib

SYSAPPL-MIB.mib

CISCO-NBAR-PROTOCOL- DISCOVERY-MIB.mib

HUAWEI-WLAN-RADIO-MIB.mib

TCP-MIB.mib

CISCO-NETSYNC-MIB.mib

HUAWEI-WLAN-SERVICE-MIB.mib

TIMETRA-ALARM-MIB.mib

CISCO-NTP-MIB.mib

HUAWEI-WLAN-SYS-MIB.mib

TIMETRA-APS-MIB.mib

CISCO-OSPF-MIB.mib

HUAWEI-WLAN-UPDATE-MIB.mib

TIMETRA-ATM-MIB.mib

CISCO-OSPF-TRAP-MIB.mib

IANA-ADDRESS-FAMILY -NUMBERS-MIB.mib

TIMETRA-BGP-MIB.mib

CISCO-OTN-IF-MIB.mib

IANA-GMPLS-TC-MIB.mib

TIMETRA-CFLOWD-MIB.mib

CISCO-PAE-MIB.mib

IANA-ITU-ALARM-TC-MIB.mib

TIMETRA-CHASSIS-MIB.mib

CISCO-PAGP-MIB.mib

IANA-LANGUAGE-MIB.mib

TIMETRA-CLEAR-MIB.mib

CISCO-PIM-MIB.mib

IANA-RTPROTO-MIB.mib

TIMETRA-CONN-PROF-MIB.mib

CISCO-PING-MIB.mib

IANAifType-MIB.mib

TIMETRA-DIAMETER-MIB.mib

CISCO-POLICY-GROUP-MIB.mib

IEEE8021-CFM-MIB.mib

TIMETRA-DOT3-OAM-MIB.mib

CISCO-POWER-ETHERNET -EXT-MIB.mib

IEEE8021-PAE-MIB.mib

TIMETRA-FILTER-MIB.mib

CISCO-PRIVATE-VLAN-MIB.mib

IEEE8021-TC-MIB.mib

TIMETRA-GLOBAL-MIB.mib

CISCO-PROCESS-MIB.mib

IEEE802171-CFM-MIB.mib

TIMETRA-IPSEC-STATIC -SA-MIB.mib

CISCO-PRODUCTS-MIB.mib

IEEE8023-LAG-MIB.mib

TIMETRA-LLDP-MIB.mib

CISCO-PTP-MIB.mib

IEEE802dot11-MIB.mib

TIMETRA-LOG-MIB.mib

CISCO-RADIUS-EXT-MIB.mib

IF-INVERTED-STACK-MIB.mib

TIMETRA-MSDP-MIB.mib

CISCO-RF-MIB.mib

IF-MIB.mib

TIMETRA-OTU-MIB.mib

CISCO-RF-SUPPLEMENTAL -MIB.mib

IGMP-STD-MIB.mib

TIMETRA-ROUTE-POLICY -MIB.mib

CISCO-RTTMON-TC-MIB.mib

INET-ADDRESS-MIB.mib

TIMETRA-SYSTEM-MIB.mib

CISCO-SELECTIVE-VRF- DOWNLOAD-MIB.mib

INT-SERV-MIB.mib

TIMETRA-TC-MIB.mib

CISCO-SESS-BORDER-CTRLR -CALL-STATS-MIB.mib

INTEGRATED-SERVICES-MIB.mib

TIMETRA-TWAMP-MIB.mib

CISCO-SESS-BORDER-CTRLR -EVENT-MIB.mib

IP-FORWARD-MIB.mib

TIMETRA-VRRP-V3-MIB.mib

CISCO-SESS-BORDER-CTRLR -STATS-MIB.mib

IP-MIB.mib

TOKEN-RING-RMON-MIB.mib

CISCO-SMI.mib

IPMCAST-MIB.mib

TOKENRING-MIB.mib

CISCO-SONET-MIB.mib

IPMROUTE-MIB.mib

TRANSPORT-ADDRESS -MIB.mib

CISCO-ST-TC.mib

IPMROUTE-STD-MIB.mib

TUNNEL-MIB.mib

CISCO-STACKWISE-MIB.mib

IPV6-FLOW-LABEL-MIB.mib

UCD-DEMO-MIB.mib

CISCO-STP-EXTENSIONS -MIB.mib

IPV6-ICMP-MIB.mib

UCD-DISKIO-MIB.mib

CISCO-SUBSCRIBER-IDENTITY -TC-MIB.mib

IPV6-MIB.mib

UCD-DLMOD-MIB.mib

CISCO-SUBSCRIBER-SESSION -MIB.mib

IPV6-MLD-MIB.mib

UCD-IPFWACC-MIB.mib

CISCO-SUBSCRIBER-SESSION -TC-MIB.mib

IPV6-TC.mib

UCD-SNMP-MIB.mib

CISCO-SYSLOG-MIB.mib

IPV6-TCP-MIB.mib

UDP-MIB.mib

CISCO-SYSTEM-EXT-MIB.mib

IPV6-UDP-MIB.mib

VPLS-BGP-DRAFT-01 -MIB.mib

CISCO-SYSTEM-MIB.mib

ISDN-MIB.mib

VPLS-GENERIC-DRAFT -01-MIB.mib

CISCO-TAP2-MIB.mib

ISIS-MIB.mib

VPLS-LDP-DRAFT-01 -MIB.mib

CISCO-TC.mib

ITU-ALARM-MIB.mib

VPN-TC-STD-MIB.mib

CISCO-TCP-MIB.mib

ITU-ALARM-TC-MIB.mib

VRRP-MIB.mib

CISCO-TEMP-LWAPP- DHCP-MIB.mib

JNX-IPSEC-MONITOR-MIB.mib

ietf-inet-types.mib

CISCO-TRUSTSEC-SXP -MIB.mib

JNX-L2TP-MIB.mib

ietf-yang-smiv2.mib

CISCO-TRUSTSEC-TC -MIB.mib

JUNIPER-ALARM-MIB.mib

ietf-yang-types.mib

List of Pre-loaded YANG Modules for MDT Collection

This section lists the YANG modules that the Collection Service supports for MDT collection on Cisco IOS XR devices.

Supported YANG Modules

Cisco-IOS-XR-Subscriber-infra-subdb-oper

Cisco-IOS-XR-aaa-locald-oper

Cisco-IOS-XR-aaa-nacm-oper

Cisco-IOS-XR-aaa-protocol-radius-oper

Cisco-IOS-XR-alarmgr-server-oper

Cisco-IOS-XR-ascii-ltrace-oper

Cisco-IOS-XR-asic-errors-ope

Cisco-IOS-XR-atm-vcm-oper

Cisco-IOS-XR-bundlemgr-oper

Cisco-IOS-XR-cdp-oper

Cisco-IOS-XR-clns-isis-oper

Cisco-IOS-XR-cmproxy-oper

Cisco-IOS-XR-cofo-infra-oper

Cisco-IOS-XR-config-cfgmgr-exec-oper

Cisco-IOS-XR-config-cfgmgr-oper

Cisco-IOS-XR-controller-optics-oper

Cisco-IOS-XR-controller-otu-oper

Cisco-IOS-XR-crypto-macsec-mka-oper

Cisco-IOS-XR-crypto-macsec-secy-oper

Cisco-IOS-XR-crypto-sam-oper

Cisco-IOS-XR-crypto-ssh-oper

Cisco-IOS-XR-dot1x-oper

Cisco-IOS-XR-drivers-media-eth-oper

Cisco-IOS-XR-dwdm-ui-oper

Cisco-IOS-XR-es-acl-oper

Cisco-IOS-XR-ethernet-lldp-oper

Cisco-IOS-XR-evpn-oper

Cisco-IOS-XR-fib-common-oper

Cisco-IOS-XR-flowspec-oper

Cisco-IOS-XR-freqsync-oper

Cisco-IOS-XR-ha-eem-policy-oper

Cisco-IOS-XR-icpe-infra-oper

Cisco-IOS-XR-iedge4710-oper

Cisco-IOS-XR-ifmgr-oper

Cisco-IOS-XR-infra-alarm-logger-oper

Cisco-IOS-XR-infra-correlator-oper

Cisco-IOS-XR-infra-objmgr-oper

Cisco-IOS-XR-infra-policymgr-oper

Cisco-IOS-XR-infra-rcmd-oper

Cisco-IOS-XR-infra-rmf-oper

Cisco-IOS-XR-infra-rsi-oper

Cisco-IOS-XR-infra-serg-oper

Cisco-IOS-XR-infra-statsd-oper

Cisco-IOS-XR-infra-syslog-oper

Cisco-IOS-XR-infra-tc-oper

Cisco-IOS-XR-infra-xtc-agent-oper

Cisco-IOS-XR-infra-xtc-oper

Cisco-IOS-XR-invmgr-oper

Cisco-IOS-XR-ip-bfd-oper

Cisco-IOS-XR-ip-daps-oper

Cisco-IOS-XR-ip-domain-oper

Cisco-IOS-XR-ip-iarm-v4-oper

Cisco-IOS-XR-ip-iarm-v6-oper

Cisco-IOS-XR-ip-iep-oper

Cisco-IOS-XR-ip-mobileip-oper

Cisco-IOS-XR-ip-ntp-admin-oper

Cisco-IOS-XR-ip-ntp-oper

Cisco-IOS-XR-ip-pfilter-oper

Cisco-IOS-XR-ip-rib-ipv4-oper

Cisco-IOS-XR-ip-rib-ipv6-oper

Cisco-IOS-XR-ip-rip-oper

Cisco-IOS-XR-ip-rsvp-oper

Cisco-IOS-XR-ip-sbfd-oper

Cisco-IOS-XR-ip-tcp-oper

Cisco-IOS-XR-ip-udp-oper

Cisco-IOS-XR-ipv4-acl-oper

Cisco-IOS-XR-ipv4-arp-oper

Cisco-IOS-XR-ipv4-autorp-oper

Cisco-IOS-XR-ipv4-bgp-oc-oper

Cisco-IOS-XR-ipv4-bgp-oper

Cisco-IOS-XR-ipv4-dhcpd-oper

Cisco-IOS-XR-ipv4-hsrp-oper

Cisco-IOS-XR-ipv4-igmp-oper

Cisco-IOS-XR-ipv4-io-oper

Cisco-IOS-XR-ipv4-ospf-oper

Cisco-IOS-XR-ipv4-pim-oper

Cisco-IOS-XR-ipv4-vrrp-oper

Cisco-IOS-XR-ipv6-acl-oper

Cisco-IOS-XR-ipv6-io-oper

Cisco-IOS-XR-ipv6-ma-oper

Cisco-IOS-XR-ipv6-nd-oper

Cisco-IOS-XR-ipv6-new-dhcpv6d-oper

Cisco-IOS-XR-ipv6-ospfv3-oper

Cisco-IOS-XR-l2-eth-infra-oper

Cisco-IOS-XR-l2rib-oper

Cisco-IOS-XR-l2vpn-oper

Cisco-IOS-XR-lib-keychain-oper

Cisco-IOS-XR-lib-mpp-oper

Cisco-IOS-XR-linux-os-reboot-history-oper

Cisco-IOS-XR-lmp-oper

Cisco-IOS-XR-lpts-ifib-oper

Cisco-IOS-XR-lpts-pa-oper

Cisco-IOS-XR-lpts-pre-ifib-oper

Cisco-IOS-XR-macsec-ctrlr-oper

Cisco-IOS-XR-man-ems-oper

Cisco-IOS-XR-man-ipsla-oper

Cisco-IOS-XR-man-xml-ttyagent-oper

Cisco-IOS-XR-manageability-object-tracking-oper

Cisco-IOS-XR-manageability-perfmgmt-oper

Cisco-IOS-XR-mediasvr-linux-oper

Cisco-IOS-XR-mpls-io-oper

Cisco-IOS-XR-mpls-ldp-oper

Cisco-IOS-XR-mpls-lsd-oper

Cisco-IOS-XR-mpls-oam-oper

Cisco-IOS-XR-mpls-static-oper

Cisco-IOS-XR-mpls-te-oper

Cisco-IOS-XR-mpls-vpn-oper

Cisco-IOS-XR-ncs6k-acl-oper

Cisco-IOS-XR-nto-misc-oper

Cisco-IOS-XR-nto-misc-shmem-oper

Cisco-IOS-XR-nto-misc-shprocmem-oper

Cisco-IOS-XR-ocni-intfbase-oper

Cisco-IOS-XR-ocni-local-routing-oper

Cisco-IOS-XR-ocni-oper

Cisco-IOS-XR-pbr-oper

Cisco-IOS-XR-pbr-vservice-ea-oper

Cisco-IOS-XR-pbr-vservice-mgr-oper

Cisco-IOS-XR-perf-meas-oper

Cisco-IOS-XR-pfi-im-cmd-ctrlr-oper

Cisco-IOS-XR-pfi-im-cmd-oper

Cisco-IOS-XR-plat-chas-invmgr-ng-oper

Cisco-IOS-XR-plat-chas-invmgr-oper

Cisco-IOS-XR-pmengine-oper

Cisco-IOS-XR-policy-repository-oper

Cisco-IOS-XR-ppp-ea-oper

Cisco-IOS-XR-ppp-ma-oper

Cisco-IOS-XR-pppoe-ea-oper

Cisco-IOS-XR-procmem-oper

Cisco-IOS-XR-ptp-oper

Cisco-IOS-XR-qos-ma-oper

Cisco-IOS-XR-rgmgr-oper

Cisco-IOS-XR-sdr-invmgr-diag-oper

Cisco-IOS-XR-segment-routing-ms-oper

Cisco-IOS-XR-shellutil-filesystem-oper

Cisco-IOS-XR-shellutil-oper

Cisco-IOS-XR-show-fpd-loc-ng-oper

Cisco-IOS-XR-snmp-agent-oper

Cisco-IOS-XR-spirit-install-instmgr-oper

Cisco-IOS-XR-sse-span-oper

Cisco-IOS-XR-subscriber-accounting-oper

Cisco-IOS-XR-subscriber-ipsub-oper

Cisco-IOS-XR-subscriber-pppoe-ma-oper

Cisco-IOS-XR-subscriber-session-mon-oper

Cisco-IOS-XR-subscriber-srg-oper

Cisco-IOS-XR-syncc-oper

Cisco-IOS-XR-telemetry-model-driven-oper

Cisco-IOS-XR-tty-management-cmd-oper

Cisco-IOS-XR-tty-server-oper

Cisco-IOS-XR-tunnel-l2tun-oper

Cisco-IOS-XR-tunnel-nve-oper

Cisco-IOS-XR-tunnel-vpdn-oper

Cisco-IOS-XR-upgrade-fpd-oper

Cisco-IOS-XR-wanphy-ui-oper

Cisco-IOS-XR-wd-oper

Cisco-IOS-XR-wdsysmon-fd-oper

cisco-xr-ietf-netconf-acm-deviations

cisco-xr-ietf-netconf-monitoring-deviations

cisco-xr-openconfig-acl-deviations

cisco-xr-openconfig-bgp-policy-deviations

cisco-xr-openconfig-if-ethernet-deviations

cisco-xr-openconfig-if-ip-deviations

cisco-xr-openconfig-interfaces-deviations

cisco-xr-openconfig-lacp-deviations

cisco-xr-openconfig-lldp-deviations

cisco-xr-openconfig-local-routing-deviations

cisco-xr-openconfig-network-instance-deviations

cisco-xr-openconfig-optical-amplifier-deviations

cisco-xr-openconfig-platform-deviations

cisco-xr-openconfig-platform-transceiver-deviations

cisco-xr-openconfig-rib-bgp-deviations

cisco-xr-openconfig-routing-policy-deviations

cisco-xr-openconfig-rsvp-sr-ext-deviations

cisco-xr-openconfig-telemetry-deviations

cisco-xr-openconfig-terminal-device-deviations

cisco-xr-openconfig-transport-line-protection-deviations

cisco-xr-openconfig-vlan-deviations

ietf-netconf

ietf-netconf-acm

ietf-netconf-monitoring

openconfig-acl

openconfig-aft

openconfig-aft-common

openconfig-aft-ethernet

openconfig-aft-ipv4

openconfig-aft-ipv6

openconfig-aft-mpls

openconfig-aft-network-instance

openconfig-aft-pf

openconfig-bgp

openconfig-bgp-common

openconfig-bgp-common-multiprotocol

openconfig-bgp-common-structure

openconfig-bgp-global

openconfig-bgp-neighbor

openconfig-bgp-peer-group

openconfig-bgp-policy

openconfig-channel-monitor

openconfig-extensions

openconfig-if-aggregate

openconfig-if-ethernet

openconfig-if-ip

openconfig-interfaces

openconfig-isis

openconfig-isis-lsp

openconfig-isis-policy

openconfig-isis-routing

openconfig-lacp

openconfig-lldp

openconfig-local-routing

openconfig-mpls

openconfig-mpls-igp

openconfig-mpls-ldp

openconfig-mpls-rsvp

openconfig-mpls-sr

openconfig-mpls-static

openconfig-mpls-te

openconfig-network-instance

openconfig-network-instance-l2

openconfig-network-instance-l3

openconfig-optical-amplifier

openconfig-packet-match

openconfig-platform

openconfig-platform-transceiver

openconfig-rib-bgp

openconfig-routing-policy

openconfig-rsvp-sr-ext

openconfig-segment-routing

openconfig-telemetry

openconfig-terminal-device

openconfig-transport-line-common

openconfig-transport-line-protection

openconfig-vlan

Device and Credentials Sync With Cisco NSO

This section contains the following topics:

- Add Devices and Credential Profiles By Synchronizing With Cisco NSO

Add Devices and Credential Profiles By Synchronizing With Cisco NSO

If you are currently using Cisco Network Services Orchestrator (Cisco NSO) to manage your network devices, you may be able to perform a bulk upload of your Cisco NSO devices to Cisco Crosswork Change Automation and Health Insights by synchronizing the two systems. Cisco strongly recommends that you undertake this synchronization only once, and only with the direct assistance of your Cisco CX account team.

Note

If you encounter NSO read timeout error while pushing configuration, increase the NSO timeout from 20 to 120 seconds by editing the ncs.conf file with set devices global-settings read-timeout 120.

Before you begin

To perform this task, you will need:

- A Cisco NSO server that is fully populated with the devices you want to add.

- The protocol, IP address, port, administrative user name and password needed to connect to the Cisco NSO server.

- Access to a text editor that you can use to edit the Cisco NSO server ncs.conf file.

- The parameters required to add Cisco NSO as a Cisco Crosswork Change Automation and Health Insights provider.

- The SNMP community strings and other credentials that Cisco NSO uses to access the devices you want to add to Cisco Crosswork Change Automation and Health Insights.

You will also need to ensure that you have pre-configured your devices to work with Cisco Crosswork Change Automation and Health Insights, as explained in Prerequisites for Onboarding Devices, Sample Configuration for Devices in Cisco NSO and Prerequisites for Device Model Driven Telemetry.

Procedure

Step 1

On the Cisco NSO server: Access and edit the ncs.conf file to enable port 8080 and then restart the server with a package reload:

1. Access the Cisco NSO command line interface (CLI) via SSH. For example: myname@host$:ssh NSOadmin@NSOServerIPAddress. Supply the Cisco NSO administrator password when prompted.

2. Navigate to the ncs.conf file, which is usually located under /./home/nso/.

3. Make a backup copy of the current ncs.conf. Use the date in the file name to identify it as a backup. For example: cp ncs.conf ncs.conf-1-1-2019.

4. Edit the ncs.conf file's <webui> parameters to include the following (the critical enabling command is highlighted):

<webui>
<enabled>true</enabled>
<transport>
<tcp>
<enabled>true</enabled>
<ip>0.0.0.0</ip>
<port>8080</port>
</tcp>

5. Restart the server and its packages by running the following commands in this order:

[root@localhost ncs-run]# source /home/nso/nso-5.2/ncsrc

To start NSO:

[root@localhost ncs-run]# ncs

To stop NSO:

[nso@localhost ncs-run]$ ncs --stop

Step 2

Log into Cisco Crosswork Change Automation and Health Insights and set up Cisco NSO as a provider, with the credentials needed to connect to Cisco NSO and to the imported devices:

1. Create a credential profile for the Cisco NSO devices, as explained in Create Credential Profiles. Be sure to include in the credential profile at least the SNMP credentials that Cisco NSO uses to manage these devices; you can create multiple sets of SNMP credentials in the profile, as well as credentials for other protocols.

2. Create an HTTP credential profile for the Cisco NSO server.

3. Add Cisco NSO as a provider, as explained in Add Providers Through the UI. Be sure to assign to the Cisco NSO provider the HTTP credential profile you just created.

4. Before logging out of the Cisco Crosswork Change Automation and Health Insights user interface, take note of the names you assigned to the Cisco NSO provider. You will need them to finish the next step.

Step 3

Synchronize Cisco Crosswork Change Automation and Health Insights's Inventory Management application with Cisco NSO's inventory services, as follows:

1. Access the Cisco Crosswork Change Automation and Health Insights CLI using SSH and the administrator ID. For example: myname@host$:ssh cw-admin@CrossworkServerIPAddress.

myname@host$:ssh cw-admin@CrossworkServerIPAddress

When prompted, enter the administrator password.

2. Switch to superuser status:

myname@host$:sudo su

When prompted, enter the administrator password.

3. Enter the following command to find the component ID for the Inventory Management Kubernetes pod container:

kubectl get pods | grep dlmi

The response will contain the component ID as a hash appended to the pod name: robot-dlminvmgr-componentID

4. Enter the following command to access the Inventory Management Kubernetes container:

kubectl exec -it robot-dlminvmgr-componentID bash

Where componentID is the ID you retrieved in the previous step.

5. Synchronize Cisco NSO inventory services with Inventory Management using the following command:

bash# syncsvc --cwhost CrossworkServerIPAddress --cwuser CrossworkAdminUser --cwpass 'CrossworkAdminPassword' --provpass NSOAdminPassword --provider ProviderName --oper get

Where:

- CrossworkServerIPAddress is the IP address of the Cisco Crosswork Change Automation and Health Insights server.

- CrossworkAdminUser is the user name of the Cisco Crosswork Change Automation and Health Insights administrator (cw-admin).

- CrossworkAdminPassword is the password for the Cisco Crosswork Change Automation and Health Insights cw-admin user.

- NSOAdminPassword is the password for the Cisco NSO admin user.

- ProviderName is the name of the Cisco NSO provider you created.

Synchronization will begin as soon as connection is established. When device processing is finished, verify that the sync added all the Cisco NSO devices to Cisco Crosswork Change Automation and Health Insights successfully.

Configure Cisco Crosswork Data Gateway Base VM

This appendix describes how to configure a Cisco Crosswork Data Gateway Base VM.

This section contains the following topics:

- About Cisco Crosswork Data Gateway Base VM

- Basic Concepts

- Manage Users

- View Current System Settings

- Change Current System Settings

- Monitor Cisco Crosswork Data Gateway Health

- Troubleshooting

About Cisco Crosswork Data Gateway Base VM

A Cisco Crosswork Data Gateway instance is created as a standalone VM and can be geographically separate from the controller application (the controller application could be Crosswork Cloud or a Crosswork On-Prem application, such as Cisco Crosswork Change Automation and Health Insights). This Base VM is capable of connecting to the controller application and enable data collection from the network.

Crosswork orchestrates the collection from the distributed Cisco Crosswork Data Gateway VM instances.

The Cisco Crosswork Data Gateway VM is delivered as an OVA file and the additional functional images are delivered as Docker images.

- Base VM Contents

- Log In and Log Out

- Use the Interactive Console

Base VM Contents

The Base VM (OVA) is pre-packaged with basic functionality required to reach the controller application.

The Cisco Crosswork Data Gateway VM (OVA) contains the following pre-packaged contents:

- Cisco hardened Ubuntu distribution of Linux

- Cisco Crosswork Data Gateway services:

- Vitals Monitor - Monitors resource usage on the VM.

- Controller Gateway – Coordinates between the Cisco Crosswork Data Gateway and the controller application to download functional images and configuration files.

- Image Manager – Establishes trusted connection with the controller application via the Controller Gateway and downloads functional images and configuration files.

- Route Manager – Directs traffic to devices on different south-bound destinations and also connects to the controller application and data devices via the north-bound interface.

- Docker IPv6nat - Programs IPv6 routes for docker containers.

Note

Functional images (CLI, SNMP, and MDT collectors) are not included in the Base VM. They are downloaded by Cisco Crosswork Data Gateway from the controller application after successful authentication and bootstrap.

Log In and Log Out

You can use either of the following two ways to access Cisco Crosswork Data Gateway:

- Access Cisco Crosswork Data Gateway Through vCenter

- Access Cisco Crosswork Data Gateway Via SSH

- Access Cisco Crosswork Data Gateway Through vCenter

- Access Cisco Crosswork Data Gateway Via SSH

Access Cisco Crosswork Data Gateway Through vCenter

Follow these steps to log in via vCenter:

Procedure

Step 1

Locate the VM in vCenter and then right click and select Open Console.

The Cisco Crosswork Data Gateway flash screen comes up.

Step 2

Enter username (dg-admin or dg-oper as per the role assigned to you) and the corresponding password (the one that you created during installation process) and press Enter.

Access Cisco Crosswork Data Gateway Via SSH

Follow these steps to login via SSH.

Procedure

Step 1

Run the following command:

ssh <username>@<ManagementNetworkIP>

where ManagementNetworkIP is the management network IP address.

For example,

To login as adminstrator user: ssh dg-admin@<ManagementNetworkIP>

To login as operator user: ssh dg-oper@<ManagementNetworkIP>

The following Cisco Crosswork Data Gateway flash screen opens prompting for password:

Step 2

Input the corresponding password (the one that you created during installation process) and press Enter.) and press Enter.

Use the Interactive Console

Cisco Crosswork Data Gateway launches an interactive console upon successful login. The interactive console displays the Main Menu as shown in the following figure:

Note

The Main Menu shown here corresponds to dg-admin user. It is different for dg-oper user as the operator does not have same privileges as the adminstrator. See Supported User Roles.

The Main Menu presents the following options:

1. Export Enrollment Package

2. Show System Settings

3. Change Current System Settings

4. Vitals

5. Troubleshooting

p. Change Passphrase

l. Logout

Basic Concepts

Cisco Crosswork Data Gateway makes extensive use of certain concepts. It is helpful to be familiar with them before you get started.

- Cisco Crosswork Data Gateway Components

Cisco Crosswork Data Gateway Components

Cisco Crosswork Data Gateway has the following five main components or services:

- Controller Gateway

- Image Manager

- Vitals Monitor

- Route Manager

- Docker IPv6nat

- Controller Gateway

- Image Manager

- Vitals Monitor

- Route Manager

- Docker IPv6nat

Controller Gateway

Controller Gateway is the component responsible for all the interaction between a Cisco Crosswork Data Gateway instance and its controller application. It manages the session creation with the controller application and makes sure all the payloads and responses are signed and verified for integrity. Components such as Image Manager, Vitals Monitor, and Route manager interact via Controller Gateway with the controller application to exchange the details those components need.

Note

When the Controller Gateway stops, any alerts are not updated in cdg-alerts.log. However, when it starts, it sends an alert that it has started. This is because all the alerts go through the Controller Gateway and if it is down, the controller application won't receive the alerts. To access log files, see Run show-tech.

Image Manager

The Image Manager comes into play upon Cisco Crosswork Data Gateway VM boot up. It downloads the functional images from the repository as instructed by the controller application and brings up the services.

It has the following responsibilities:

- Periodically pull boot-config file from the controller application via Controller Gateway.

- Based on the boot-config and local images metadata cache, determine if the functional images and docker-compose file need to be downloaded.

- Send appropriate alerts to the controller application, if there are issues while processing the boot-config.

- Stop and remove any services that are no longer called for in the latest boot-config.

- Cleanup the local images metadata cache to keep it synchronized with the latest boot-config received from the controller application.

- Downloads collectors environment and other files that facilitate establishment of connection between collectors and Crosswork.

- Downloads system device packages and MIB packages required by the collectors from Crosswork.

- Downloads custom software to the collectors when uploaded via Crosswork UI.

Note

Functional images are downloaded only when there is a change in boot-config response.

Vitals Monitor

The Vitals Monitor monitors the health and vitals of the Cisco Crosswork Data Gateway VM. It collects the CPU, memory, disk usage, docker containers metrics, etc. and aggregates this information in a file on the host filesystem.

For more information, see Monitor Cisco Crosswork Data Gateway Health.

Route Manager

Route Manager manages south-bound routes to devices and north-bound routes to data destinations based on add/delete requests from collector upon the updates of inventory and collection jobs.

Route manager adds/deletes the static routes by comparing the existing routes configured on the VM with the routes configuration. This configuration is pushed to the Route Manager by the controller application in case of Crosswork On-Premise deployment.

Appropriate alerts are sent to the controller application if there is any failure in processing route request.

Docker IPv6nat

docker-ipv6nat is a special process that programs ipv6 routes for docker containers.

Manage Users

This section contains the following topics:

- Supported User Roles

- Change Password

- Supported User Roles

- Change Password

Supported User Roles

Cisco Crosswork Data Gateway supports only two users with the following user roles:

- Administrator: One default user with administrator role is created when Cisco Crosswork Data Gateway is brought up for the first time. This user cannot be deleted and has both read and write privileges such as start/shut down Cisco Crosswork Data Gateway, register an application, apply authentication certificates, configure server settings, and perform kernel upgrade.

- Operator: This user is also created by default during the initial VM bring up. Operator can review the state/health of theCisco Crosswork Data Gateway, retrieve health/error logs, receive error notifications and run connectivity tests between Cisco Crosswork Data Gateway instance and the output destination.

Note

- Both users' credentials are configured during Cisco Crosswork Data Gateway installation.

- Users are locally authenticated.

The following table shows the permissions available to each role:

Permissions Per Role

Permissions

Administrator

Operator

Export enrollment package

✓

✓

Show system settings

- Management and South/North-bound Data Addresses

- NTP

- DNS

- Proxy

- UUID

- Syslog

- Certificates

✓

✓

Change Current System Settings

- Configure NTP

- Configure DNS

- Configure Control Proxy

- Configure Static Routes

- Configure Syslog

- Create new SSH keys

- Import Certificate

✓

╳

Vitals

- Docker Containers

- Docker Images

- Controller Reachability

- NTP Reachability

- Route Table

- ARP Table

- Network Connections

- Disk Space Usage

✓

✓

Troubleshooting

Ping a Host

✓

✓

Traceroute to a Host

✓

✓

NTP Status

✓

✓

System Uptime

✓

✓

Run show-tech

✓

✓

Remove All Collectors and Reboot VM

✓

╳

Reboot VM

✓

╳

Change Passphrase

✓

✓

Change Password

Both Adminstrator and Operator users can change their own passphrases but not each others'.

Follow these steps to change your passphrase:

Procedure

Step 1

From the Main Menu, select p Change Passphrase and click OK.

Step 2

Input your current password and press Enter.

Step 3

Enter new password and press Enter. Re-type the new password and press Enter.

View Current System Settings

Cisco Crosswork Data Gateway allows you to view the following settings:

- Management and South/North-bound Data Addresses

- NTP

- DNS

- Proxy

- UUID

- Syslog

- Certificates

Follow these steps to view the current system settings:

Procedure

Step 1

From the Main Menu, select 2 Show System Settings, as shown in the following figure:

Step 2

Click OK. The Show Current System Settings menu opens.

Step 3

Select the setting you want to view.

Setting Option

Description

1 Management and South/North-bound Data Addresses

Displays the addresses of the management, northbound, and southbound interfaces.

2 NTP

Displays NTP settings.

It is important that NTP time be synchronized with the controller application and its Cisco Crosswork Data Gateway instances.

If not, then session handshake doesn’t happen and functional images are not downloaded. In such cases, error message clock time not matched and sync failed is logged in controller-gateway.log and same is sent to the data destination. To access log files, see Run show-tech.

You can use Controller Reachability and NTP Reachability options from Main Menu > Vitals to check NTP reachability for the controller application as well as the Cisco Crosswork Data Gateway instance. See View Cisco Crosswork Data Gateway Vitals. If NTP has been set incorrectly,you will see error Session not established.

To configure NTP settings, see Configure NTP.

3 DNS

Displays addresses of the DNS servers.

4 Proxy

Displays proxy server settings if there's any.

5 UUID

Displays the unique identifier of the Cisco Crosswork Data Gateway VM.

6 Syslog

Displays syslog settings.

The Controller Gateway doesn't send a start event to the Syslog server. Also, SNMP, MDT, and CLI events are not updated in the local syslog file, but are sent to the external syslog server. To configure syslog settings, see Configure Syslog.

7 Certificates

Provides the following options to view certificate files:

- Collector certificate file

- Controller signing certificate file

- Controller SSL/TLS certificate file

- Syslog certificate file

Step 4

Click OK. Cisco Crosswork Data Gateway displays the selected setting.

After you are done viewing the settings, press any key to return to the Show Current System Settings menu.

To return to the Main Menu, select x Exit Menu and click OK.

Change Current System Settings

Note

- Cisco Crosswork Data Gateway System settings can only be configured by the Administrator.

- In settings options where you require to use SCP, if you are not using the default SCP port 22, you can specify the port as a part of the SCP command. For example,

-P55 user@host:path/to/file

where 55 is a custom port.

Cisco Crosswork Data Gateway allows you to change the following settings:

- NTP

- DNS

- Control Proxy

- Static routes

- Syslog

- SSH keys

- Certificate

Follow these steps to change the current system settings:

Procedure

Step 1

From the Main Menu, select 3 Change Current System Settings, as shown in the following figure.

Step 2

Click OK. The Change System Settings menu opens.

Step 3

Select the setting you want to change.

Step 4

Click OK. Cisco Crosswork Data Gateway prompts you to input new value for the selected setting.

Step 5

After you have entered the new settings, click OK to save the settings and return to the Change System System Settings menu.

To return to the Main Menu, select x Exit Menu and click OK.

- Configure NTP

- Configure DNS

- Configure Control Proxy

- Configure Static Routes

- Configure Syslog

- Create New SSH Keys

- Import Certificate

Configure NTP

Procedure

Step 1

From the Change Current System Settings Menu, select 1 Configure NTP and click OK.

Step 2

Enter the new NTP server.

Step 3

Click OK to save the settings.

Configure DNS

Procedure

Step 1

From the Change Current System Settings menu, select 2 Configure DNS and click OK.

Step 2

Enter the new DNS domain and server address.

Step 3

Click OK to save the settings.

Configure Control Proxy

Procedure

Step 1

From the Change Current System Settings menu, select 3 Configure Control Proxy and click OK.

Step 2

Enter the new Proxy server URL and the exception list.

Step 3

Click OK to save the settings.

Configure Static Routes

In Cisco Crosswork Data Gateway, the static routes are configured when the Route Manager receives add/delete requests from the collectors. The Configure Static Routes option from the main menu can be used for troubleshooting purpose.

Note

Static routes configured using this option are lost when the Cisco Crosswork Data Gateway reboots.

- Add Static Routes

- Delete Static Routes

Add Static Routes

Procedure

Step 1

From the Change Current System Settings menu, select 4 Configure Static Routes and click OK.

Step 2

To add a static route, select a Add and click OK.

Step 3

Select the interface for which you want to add a static route and click OK.

Step 4

Select the IP address version for which you want to add a route and click OK.

Step 5

Enter IPv4/IPv6 subnet in CIDR format when prompted.

Step 6

Click OK to save the settings.

Delete Static Routes

Procedure

Step 1

From the Change Current System Settings Menu, select 4 Configure Static Routes and click OK.

Step 2

To delete a static route, select d Delete and click OK.

Step 3

Select the interface for which you want to delete a static route and click OK.

Step 4

Select the IP address version for which you want to delete a route and click OK.

Step 5

Enter IPv4/IPv6 subnet in CIDR format.

Step 6

Click OK to save the settings.

Configure Syslog

Note

For any Syslog server configuration with IPv4/IPv6 support for different linux distributions, please refer your system administrator and configuration guides.

Procedure

Step 1

From the Change Current System Settings Menu, select 5 Configure Syslog and click OK.

Step 2

Enter the new values for the following syslog attributes:.

- Server address: IPv4 or IPv6 address of a syslog server accessible from the management interface. If you are using an IPv6 addres, it must be surrounded by square brackets ([1::1]).

- Port: Port number of the syslog server

- Protocol: Use UDP, TCP, or RELP when sending syslog.

- Use Syslog over TLS?: Use TLS to encrypt syslog traffic.

- TLS Peer Name: Syslog server's hostname exactly as entered in the server certificate SubjectAltName or subject common name.

- Syslog Root Certificate File URI: PEM formatted root cert of syslog server retrieved using SCP.

- Syslog Certificate File Passphrase: Password of SCP user to retrieve Syslog certificate chain.

Step 3

Click OK to save the settings.

Create New SSH Keys

Procedure

Step 1

From the Change Current System Settings Menu, select 6 Create new SSH keys.

Step 2

Click OK. Crosswork Data Gateway launches an auto-configuration process that generates new SSH keys.

Import Certificate

Updating any certificate other than Controller Signing Certificate causes a collector restart.

Procedure

Step 1

From the Change Current System Settings Menu, select 7 Import Certificate and click OK.

Step 2

Select the certificate you want to import and click OK.

Step 3

Enter SCP URI for the selected certificate file and click OK.

Step 4

Enter passphrase for the SCP URI and click OK.

Monitor Cisco Crosswork Data Gateway Health

This section contains the following topics:

- Vitals Monitor

- View Cisco Crosswork Data Gateway Vitals

- Vitals Service

- Vitals Monitor

- View Cisco Crosswork Data Gateway Vitals

- Vitals Service

Vitals Monitor

The Vitals Monitor component of Cisco Crosswork Data Gateway enables you to view vitals for the following:

1. Docker containers

2. Docker images

3. Controller reachability

4. NTP reachability

5. Route table

6. ARP table

7. Network connections

8. Disk space usage

View Cisco Crosswork Data Gateway Vitals

Follow these steps to view Cisco Crosswork Data Gateway vitals:

Procedure

Step 1

From the Main Menu, select 4 Vitals and click OK.

The Show VM Vitals menu opens.

Step 2

Select the vital you want to view and click OK.

Vital

Description

Docker Containers

Displays the following vitals for the docker containers:

• Container ID

• Image

• Name

• Command

• Created Time

• Status

• Port

Docker Images

Displays the following vitals for the docker images:

• Repository

• Image ID

• Created Time

• Size

• Tag

Controller Reachability

Displays the following vitals for controller reachability:

• Default gateway status

• Reachability test details (number of packets transmitted and received, packet loss percentage, and time)

• DNS server

• DNS server status

• Reachability test details (number of packets transmitted and received, packet loss percentage, and time)

• Controller session status

NTP Reachability

Displays the following vitals for NTP reachability:

• NTP server

• Resolved IP Address

• Status

• Reachability test details (number of packets transmitted and received, packet loss percentage, and time)

• Chrony status

• Reference ID

• System time

Route Table

Displays IPv4 and IPv6 route tables.

ARP Table

Displays ARP tables.

Network Connections

Displays the following vitals for network connections:

• Netid

• State

• Recv-Q

• Send-Q

• Local Address and Port

• Peer Address and Port

Disk Space Usage

Displays the following vitals for disk space usage:

• Filesystem

• Size

• Used space

• Available space

• Use percentage

• Mounted on volume

Cisco Crosswork Data Gateway displays the vitals for the selected item.

After you are done viewing the vitals, press any key to return to the ShowVM Vitals menu.

To return to the Main Menu, select x Exit Menu and click OK.

Vitals Service

Vitals service monitors the running status of all container services on Cisco Crosswork Data Gateway. It sends container services start and stop alert events to the controller.

When either of the following components listed below are not responsive, Cisco Crosswork Data Gateway vital service alert functionality is impacted:

- Docker Engine

- Vitals Monitor

- Controller Gateway

Troubleshooting

You can troubleshoot a Cisco Crosswork Data Gateway instance directly from the VM. Cisco Crosswork Data Gateway provides logs of errors, requests to the server, and changes made to the VM and reports any process failures/outages.

To access Troubleshooting menu, select 5 Troubleshooting from the Main Menu and click OK, as shown in the following figure:

Cisco Crosswork Data Gateway opens the Troubleshooting menu that provides you the following options to troubleshoot your Cisco Crosswork Data Gateway instance:

Note

The following figure shows the Troubleshooting Menu corresponding to dg-admin user. Few of these options are not available to dg-oper user. See Table Table 1.

This section contains the following topics:

- Ping a Host

- Traceroute to a Host

- Check NTP Status

- Check System Uptime

- Run show-tech

- Reboot Crosswork Data Gateway VM

- Ping a Host

- Traceroute to a Host

- Check NTP Status

- Check System Uptime

- Run show-tech

- Reboot Crosswork Data Gateway VM

Ping a Host

To aid troubleshooting, Cisco Crosswork Data Gateway provides you Ping utility that can be used to check reachability to any IP address.

Procedure

Step 1

From Troubleshooting menu, select 1 Ping a Host and click OK.

Step 2

Enter the ping destination.

Step 3

Click OK.

Cisco Crosswork Data Gateway displays the result of the ping operation.

Traceroute to a Host

Cisco Crosswork Data Gateway provides Traceroute to a Host option to help troubleshoot latency issues. Using this option provides you a rough time estimate for the Cisco Crosswork Data Gateway to reach the controller application.

Procedure

Step 1

From Troubleshooting menu, select 2 Traceroute to a Host and click OK.

Step 2

Enter the traceroute destination.

Step 3

Click OK.

Check NTP Status

Use this option to check the status of the NTP server.

Procedure

Step 1

From Troubleshooting menu, select 3 NTP Status.

Step 2

Click OK. The Cisco Crosswork Data Gateway displays the NTP server status.

Check System Uptime

Use this option to check system uptime.

Procedure

Step 1

From Troubleshooting menu, select 4 System Uptime.

Step 2

Click OK. The Crosswork Data Gateway displays the system uptime.

Run show-tech

Cisco Crosswork Data Gateway provides the option show_tech to export its log files to a user-defined SCP destination.

The collected data includes the following:

- Logs of all the Data Gateway components running on docker containers

- VM Vitals

It creates a tarball in the directory where it is executed. The output is a tarball named CDG-<CDG-version>-year-month-day--hour-minute-second-*.tar.bz2

The execution of this command may take several minutes depending on the state of Crosswork Data Gateway.

Procedure

Step 1

From Troubleshooting menu, select 5 Show-tech and click OK.

Step 2

Enter the destination to save the tarball containing logs and vitals.

Step 3

Enter your SCP passphrase and click OK.

Reboot Crosswork Data Gateway VM

Note

This task can only be performed by dg-admin user.

Crosswork Data Gateway gives you two options to reboot the VM:

- Remove All Collectors and Reboot VM: Select this option from the Troubleshooting menu if you want to remove all the collectors (functional images) and reboot VM.

- Reboot VM: Select this option from the Troubleshooting menu for a normal reboot.