Cisco Crosswork Network Controller 7.2.x Administration Guide

Device packages

Updated: August 14, 2026

Want to summarize with AI?

Device packages allow Embedded Collectors to communicate with network devices and enable support for multiple vendors. There are two main types of device packages: system packages, which are preinstalled and managed by Cisco, and custom packages, which users can upload and manage to extend device support.

A device package is a data collection framework that

defines communication protocols including commands, telemetry models, and SNMP objects required to retrieve device data from network devices
translates device data into a standardized format for downstream processing within Embedded Collectors, and
enables multi-vendor support allowing Embedded Collectors to communicate with multiple device types and vendors without requiring additional code changes.

Types of device packages

Embedded Collectors use device packages to define communication and data collection from network devices. These are categorized as system packages and custom device packages.

System packages are preinstalled packages that ship with Crosswork. They include built-in definitions for Cisco and commonly supported third-party devices. These packages contain the standard CLI, SNMP, and telemetry collection models required for those devices.

System device packages have these characteristics.
- Installed automatically with Embedded Collectors.
- Maintained and updated by Cisco.
- 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.
- Updated as part of Embedded Collectors or device package version upgrades.
System packages ensure that Embedded Collectors can immediately begin collecting data from supported devices without requiring manual configuration.
Custom device packages are provided by administrators. They extend the data collection capabilities of Embedded Collectors beyond the coverage of system packages. Typically, administrators use these to onboard unsupported devices, add vendor-specific MIBs, or introduce additional metrics.

Custom device packages have these characteristics.
- Created, imported, or obtained separately (for example, from Cisco or third-party vendors).
- Uploaded manually through Administration > Data Gateway > Device Packages.
- Can be edited, replaced, or deleted by administrators as needed.
- Useful for integrating proprietary, non-Cisco, or newer device types.
Note

Custom packages co-exist with system packages and take precedence when both define the same device type or data model.

Download system packages

Download system packages that are relevant for an application using the system’s administration interface.

System packages are provided through an application-specific manifest in JSON format. They are centrally managed and updated whenever applications are installed or upgraded.

Before you begin

Identify the system package you need to download.

Procedure

	1.	From the main menu, choose Administration > Data Collector(s) Global Settings > System Packages. You will see the System Packages window. Figure 1. System Packages window
	2.	Click located next to the package name in the File Name column.

The selected system package is downloaded and available for use.

What to do next

Confirm the file has downloaded successfully.

Custom packages

A custom package is a bundle that

enables user-supplied extensions for device communication and data collection
allows integration of third-party device models and data formats, and
supports enhanced monitoring and management within Crosswork Network Controller.

Types of custom packages

You can upload these types of custom packages to Crosswork Network Controller:

CLI Device Package: Monitors device health for third-party devices using KPIs based on the CLI. All packages and their corresponding YANG models must be included in the custom-cli-device-packages.tar.xz file.
Custom MIB Packages: Contains custom MIBs and device packages designed for third-party devices, and filter or format collected data for Cisco devices. You can edit these packages, which must be included in the custom-mib-packages.tar.xz file. The system supports only one custom MIB package.
SNMP Device Package: Extends SNMP coverage via custom SNMP device packages in .xar format, using Embedded Collectors.
Aggregate Package: Enables you to include multiple supported file extensions in one package. You can upload and download aggregate packages using the Crosswork UI.

Supported file extensions for aggregate packages

Aggregate packages may contain these file types:

Collector file
- YANG (.yang)
- MIB (.mib, .my)
- Definition (.def)
- Device packages (.xar)
Application files
- Device-metadata (.yaml, .yml)
- Zips (.zip)
- SDU bundle (.sdu)

Requirements for proprietary MIBs

Proprietary MIBs are only needed when collection requests reference MIB TABLE names or SCALAR names from a proprietary MIB. If requests use OIDs, proprietary MIBs are not required. Standard MIBs are already included in the system for SNMP polling on third-party devices.

Upload the custom package

Add a new custom package to the system by uploading a prepared tar.gz bundle.

Custom packages allow administrators to introduce new capabilities or configurations by uploading bundled resources in a standard archive format. Supported package types include those for SNMP and CLI collectors.

Before you begin

Review the requirements and ensure that you meet the requirements.

Procedure

	1.	From the main menu, go to Administration > Data Collector(s) Global Settings > Custom packages.
	2.	On the Custom packages page, click .
	3.	In the Add custom packages window, select the appropriate package type from the Type dropdown.
	4.	In the File name field, click to open the file browser, select your tar.gz custom package, and 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.

The system processes your upload and adds the custom package to the selected collector or gateway. Confirmation is shown upon completion.

Requirements to upload custom packages

Ensure that all prerequisites are met and review the applicable upload restrictions before uploading custom packages. Observe these requirements:.

MIB package dependencies: Ensure that the new MIBs include all necessary dependencies in the bundle to prevent import errors.
Supported file extensions: The package must include only supported file types. For the complete list of supported extensions, see the referenced documentation.

Supported file extensions: The package must include only supported file types. For the full list of supported extensions, refer to the relevant documentation. For a full list of supported extensions, see Custom packages.
Package format: Bundle all the package contents into a .tar.gz archive before uploading.
Collector types: The archive must include at least one of the top-level directories:
- cli/
- snmp/
- common/
See Sample package directory structure for the recommended directory structure.
To update a CLI package, click the Upload icon next to the filename on the Custom Packages page. This action replaces the existing file.
When uploading multiple files, combine multiple .xar files into a single .tar.gz archive before uploading.

Performance considerations for uploading custom packages

Before uploading custom MIBs and YANGs to the Crosswork Network Controller, ensure that your packages are thoroughly performance-tested and optimized for your deployment scale.

Optimize custom package efficiency to improve collection job performance.
Test package performance prior to uploading to ensure compatibility and scalability for your environment.

For detailed validation instructions on custom MIBs and YANGs, refer to Cisco DevNet documentation.

Restrictions and validations for custom package uploads

Observe these restrictions and validations when uploading custom packages:

Do not attempt to overwrite system MIBs with custom MIBs; this action is not supported and will result in a failed upload.
Package archive requirements:
- Include only the directories cli/, snmp/, and common/ at the root level of the .tar.gz archive.
- Avoid including parent folders or extra hierarchy levels to prevent exceptions during job execution.
Crosswork validates only file extensions at upload time; file contents are not validated.

Sample package directory structure

This example shows a 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

Delete the custom package

Remove a custom package from Cisco Crosswork and delete associated files.

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.

For information about creating and managing performance policies, refer to the Cisco Crosswork Network Controller 8.0 Device Lifecycle Management document.

Note

Deleting a custom package automatically removes all YANG and XAR files associated with it and affects any collection tasks that rely on it.

Procedure

	1.	From the main menu, choose Administration > Data Collector(s) Global Settings > Custom Packages.
	2.	In the Custom Packages pane, select the package you want to delete.
	3.	Click .
	4.	In the Delete Custom Package window that appears, click Delete to confirm.

Need help?

Open a support case

(Requires a Cisco Service Contract)

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.