Cisco Crosswork Network Controller 7.2.x Administration Guide

PDF

Cisco Crosswork Network Controller 7.2.x Administration Guide

Device package management

Updated: August 14, 2026

Want to summarize with AI?

Log in

Describes device package management in Cisco Crosswork Data Gateway, including how system and custom device packages extend data collection for Cisco and third-party devices and support tailored coverage for specific collection requirements.

A device management capability, often referred to as device package management, is a feature of Cisco Crosswork Data Gateway that

  • extends data collection capabilities to Cisco applications and third-party devices

  • supports both custom and system device packages that are pre-bundled and automatically deployed but cannot be modified, and

  • allows customization and uploading of device packages to cover third-party devices or specific data collection needs not addressed by default packages, with support available from Cisco or Cisco partners.

Types of custom packages

You can upload these types of custom packages to Cisco Crosswork:

  • CLI device package: Use CLI-based KPIs to monitor the health of third-party devices. Include all custom CLI device packages and their corresponding YANG models in the file custom-cli-device-packages.tar.xz. The system does not support multiple files. You can use the aggregate package to bundle various files for different devices in a single package.

  • Custom MIB package: Custom MIBs and device packages can be specific to third-party devices. They can also be used to filter collected data or format it differently for Cisco devices. You can edit these packages. Include all custom SNMP MIB packages, along with the necessary YANG models, in the file custom-mib-packages.tar.xz. The system does not support multiple files.

    Note

    Crosswork Data Gateway enables SNMP polling on third-party devices for standard MIBs included in the system. You only need proprietary MIBs if the collection request references specific table names or scalar names from a proprietary MIB. If the requests are OID-based, MIBs are not required.

  • SNMP device package: Extend SNMP coverage by uploading custom SNMP device packages in the .xar format.

  • Aggregate package: Include multiple supported file extensions in a single package. These files can be collector or application-specific. For example, an aggregate package can contain files for CLI and SNMP device packages.

Supported file types for custom packages

In the Crosswork UI, you can upload or download device or data collection packages that extend the Data Gateway’s coverage or functionality. Each package can include a combination of these file types, depending on whether you are installing custom device definitions, YANG models, or SNMP MIBs.

  • Collector files: YANG (.yang), MIB (.mib, .my), Definition (.def), Device Packages (.xar)

  • Application files: Device-metadata (.yaml, .yml), Zips (.zip), SDU bundle (.sdu)

Workflow for adding a custom package

Crosswork Network Controller can only load one file at a time. If you have loaded a package containing two files and need to add support for a third device type, place the new file in the common directory. Then, create a new replacement file containing all three files for upload.

Summary

Crosswork Network Controller enables device support expansion through custom package upload workflows for non-Cisco devices.

Workflow

Use this workflow to learn how to add a custom package for non-Cisco devices.

  1. Obtain the YANG model files for the devices you want to support from the vendors.
  2. Store the files in a common/ directory.
  3. Create a single custom package by tarring up the directory.
  4. Add that file to Crosswork Network Controller.

What’s next

Review the prerequisites for uploading custom device packages at Requirements to upload custom packages. Then, follow the procedure to upload the custom device packages. See Upload custom packages.

Requirements to upload custom packages

Guidelines for custom packages

You must complete these requirements when uploading custom software packages to Crosswork Network Controller:

  • Upload only one file at a time. If you need to add support for a third device type, add the file to the common directory and create a replacement file containing all required files before uploading.

  • Bundle all the new MIBs and the necessary dependencies to prevent import errors.

  • Only upload package files with supported extensions. For collector files, the supported extensions are YANG (.yang), MIB (.mib, .my), Definition (.def), and Device Packages (.xar). For application files, the supported extensions are Device metadata (.yaml, .yml), Zips (.zip), and SDU bundle (.sdu).

  • Bundle the files in the .tar.gz format before uploading.

  • Ensure the top-level directory of the package includes at least one collector type, such as SNMP, CLI, or Common.

  • Do not attempt to overwrite system MIB package files with custom MIB files; this action fails.

  • When uploading an aggregate package, place files for cli/ and snmp/ in their respective directories and files used by both in the common/ directory.

    Sample directory structure for an aggregate package:

    
├── cli
│   ├── defs
│   │   └── cli-def1.def
│   ├── device-metadata
│   │   ├── cli.yml
│   │   └── cli-device-metadata.yaml
│   ├── zips
│   │   └── cli-zip.zip
│   ├── sdus
|   │   └── cli-sdu.sdu
│   ├── xars
│   │   ├── cli-xar1.xar
│   │   └── cli-xar2.xar
│   └── yangs
│       ├── cli-yang1.yang
│       └── cli-yang2.yang
├── common
│   ├── defs
│   │   └── common-def1.def
│   ├── device-metadata
│   │   ├── common.yml
│   │   └── common-device-metadata.yaml
│   ├── zips
│   │   └── common-zip.zip
│   ├── mibs
│   │   ├── common-mib1.mib
│   │   └── common-mib2.my
│   ├── sdus
|   │   └── common-sdu.sdu
│   ├── xars
│   │   ├── common-xar1.xar
│   │   └── common-xar2.xar
│   └── yangs
│       ├── common-yang1.yang
│       └── common-yang2.yang
└── snmp
    ├── defs
    │   └── snmp-def1.def
    ├── device-metadata
    │   ├── snmp.yml
    │   └── snmp-device-metadata.yaml
    ├── mibs
    │   ├── snmp-mib1.mib
    │   └── snmp-mib2.my
    ├── sdus
    │   └── snmp-sdu.sdu
    ├── zips
    │   └── snmp-zip.zip
    ├── xars
    │   ├── snmp-xar1.xar
    │   └── snmp-xar2.xar
    └── yangs
        ├── snmp-yang1.yang
        └── snmp-yang2.yang

Upload considerations

When uploading custom software packages to Crosswork Network Controller, consider these:

  • Updating a software package replaces the existing file.

  • To upload multiple .xar files, combine them into a single .tar.gz archive before uploading.

  • Do not attempt to overwrite system MIB package files with custom MIB files; this action fails.

  • Ensure the .tar.gz archive contains only the package folders at the top level, without any parent or hierarchy folders.

  • Crosswork Network Controller validates only the file extension and does not check the internal contents of the file.

  • For validating custom MIBs and YANGs before upload, see Use Custom MIBs and Yangs on Cisco DevNet.

Performance considerations

The performance of collection jobs using custom packages depends on the optimization of those packages. Ensure that the packages are optimized for the scale of deployment before uploading them to Cisco Crosswork. For information on how to validate custom MIBs and YANGs that can be uploaded to Data Gateway, see Use Custom MIBs and Yangs on Cisco DevNet.

Third-party device considerations

When adding a custom package for third-party devices, name the sys-oids YAML file exactly as third-party-sys-oids.yaml. Use only lowercase letters for the file name and do not include any additional prefixes or suffixes. For example, do not use names like third-party-name-sys-oids.yaml. Place the third-party-sys-oids.yaml file in the common/device-metadata/ directory of your package.

If the file name or location is different, Crosswork Network Controller will not load the file. Ensure that you verify and update your package before uploading.

Upload custom packages

The process of adding custom packages involves bundling multiple files into a single tar.gz package format and then uploading it. This ensures that the packages are optimized and contain only the necessary files, such as supported file extensions and specific collector types, such as SNMP and CLI.

Before you begin

Confirm that you have met the prerequisites before uploading a custom package. See Requirements to upload custom packages.

Use these steps to upload a custom software package.

Procedure

1.

Go to Administration > Data Collectors Global Settings > Custom packages.

2.

In the Custom packages page, click the add icon.
3.

In the Add custom packages window, choose the package type to import from the Type drop-down.
4.

Click the blank field in File name to open the file browser window.

  1. Select the package you want to import.

  2. Click Open.
5.

Add a description of the package in the Notes field. We recommend including a unique description for each package to easily distinguish between them.
6.

Click Upload.

Delete a custom package

Remove custom packages that are no longer used, freeing up resources and updating collection jobs.

Deleting a custom performance package does not remove the database tables or schema that store performance data for the associated custom policy. If you add, modify, or delete any fields in the schema and upload the package again using the same schema name, Crosswork continues to use the existing schema and cannot store data for the changes. To apply the schema changes, create a new version of the custom performance package with a new schema name, and create a new custom policy that uses the updated package. Manually clear any Threshold Crossing Alarm (TCA) alarms associated with the previous custom policy, refer to Create monitoring policies section in the Cisco Crosswork Network Controller 7.2.x Device Lifecycle Management document.

Procedure

1.

Go to Administration > Data Collector(s) Global Settings> Custom packages.

2.

From the Custom packages pane, select the package you want to delete.
3.

Click the delete icon.
4.

In the Delete custom package window, click Delete to confirm.

The custom package and its YANG and XAR files are removed, and collection jobs using the package will no longer function.

System packages

A system device package is a configuration supplied via an application-specific manifest in JSON format.

  • is added or updated automatically whenever Cisco Crosswork applications are installed or updated

  • enables applications to install multiple device packages as needed, and

  • contains one or more separate installable file sets, with each file set in the package belonging to the same application.

Downloading a device package

Administrators cannot modify the system device packages. Only applications can modify these files. To modify the system device packages, contact the Cisco Customer Experience team.

  1. Locate the device package you want to download in the File name column.

  2. Click the download button next to the package name.

The device package is downloaded to your computer.

Figure 1. System device packages