Skip to content

CLI reference

While most of benefit of the ZDK is the zenpacklib library to help you build ZenPacks, there is also a zenpacklib command line script that performs some useful actions.

Running the script alone or with --help returns the following usage instructions:

Usage: zenpacklib [options] [FILENAME|ZENPACK|DEVICE]

ZenPack Conversion:
 -t, --dump-templates
                     export existing monitoring templates to YAML
 -e, --dump-event-classes
                     export existing event classes to YAML
 -r, --dump-process-classes
                     export existing process classes to YAML

ZenPack Development:
 -c, --create        Create a new ZenPack source directory
 -l, --lint          check zenpack.yaml syntax for errors
 -o, --optimize      optimize zenpack.yaml format and DEFAULTS
 -d, --diagram       print YUML (http://yuml.me/) class diagram source
                     based on zenpack.yaml
 -p, --paths         print possible facet paths for a given device and
                     whether currently filtered.

The following commands are supported:

create

The --create switch creates a source directory for a ZDK-enabled ZenPack. This will include a setup.py, MANIFEST.in, the namespace and module directories, and a zenpack.yaml in the module directory. The ZenPack is ready to install immediately even though it contains no functionality.

Example usage:

zenpacklib --create ZenPacks.example.MyNewPack

The preceding command yields the following output:

Creating source directory for ZenPacks.test.ZPLTest2:
  - making directory: ZenPacks.test.ZPLTest2/ZenPacks/test/ZPLTest2
  - creating file: ZenPacks.test.ZPLTest2/setup.py
  - creating file: ZenPacks.test.ZPLTest2/MAINFEST.in
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/__init__.py
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/test/__init__.py
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/test/ZPLTest2/__init__.py
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/test/ZPLTest2/zenpack.yaml

lint

The --lint switch checks YAML files for correctness. It checks that the provided file is syntactically-valid YAML, and it will also perform many others checks that validate that the contained entries, fields and their values are valid.

The following example shows an example of using an unrecognized parameter in a monitoring template.

$ zenpacklib --lint zenpack.yaml
zenpack.yaml:47:9: Unrecognized parameter 'targetPythnoClass' found while processing RRDTemplateSpec

The --lint switch returns no result when a YAML file is valid.

diagram

The --diagram switch uses the classes and relationships in a YAML file to generate the source for a yUML class diagram. For ZenPacks with a non-trivial class model this can provide a useful view of the model.

Example:

zenpack.yaml
name: ZenPacks.example.NetBotz

classes:
  NetBotzDevice:
    base: [zenpacklib.Device]

  NetBotzEnclosure:
    base: [zenpacklib.Component]

  NetBotzSensor:
    base: [zenpacklib.Component]

class_relationships:
  - NetBotzDevice 1:MC NetBotzEnclosure
  - NetBotzDevice 1:MC NetBotzSensor
  - NetBotzEnclosure 1:M NetBotzSensor

Running the zenpacklib script with the --diagram switch yields the following yUML class diagram source, which you can paste this into the sample window at https://yuml.me/diagram/scruffy/class/draw to see a diagram.

## Classes
[NetBotzDevice]
[NetBotzEnclosure]
[NetBotzSensor]

## Inheritence
[Device]^-[NetBotzDevice]
[Component]^-[NetBotzEnclosure]
[Component]^-[NetBotzSensor]

## Containing Relationships
[NetBotzDevice]++netBotzEnclosures-netBotzDevice[NetBotzEnclosure]
[NetBotzDevice]++netBotzSensors-netBotzDevice[NetBotzSensor]

## Non-Containing Relationships
[NetBotzEnclosure]netBotzSensors-.-netBotzEnclosure++[NetBotzSensor]

paths

The --paths switch shows the paths between defined component classes using the device name you have specified as a sample. To obtain useful results, ensure that the device has at least one component of each type you are interested in.

The paths shown are those used to control which devices will show up in the bottom grid of the Collection Zone or Resource Manager browser interface when both a component and a target class are selected from the filter dropdown.

The default behavior is to show components of that type that are directly related to the selected component through 1:M or 1:MC relationships, but additional objects that are indirectly related can be added through the use of the ‘extra_paths’ configuration directive. The —-paths switch is primarily a debugging tool during the development of extra_paths patterns to verify that they are having the intended effect.

Example usage:

zenpacklib --paths mydevice

dump-templates

The --dump-templates switch exports monitoring templates already loaded into your Zenoss instance and associated with a ZenPack. It exports them to the YAML format required for zenpack.yaml. It is up to you to merge that YAML with your existing zenpack.yaml file.

Example usage:

zenpacklib --dump-templates ZenPacks.example.BetterAlreadyBeInstalled

dump-event-classes

The --dump-event-classes switch exports event class organizers and mappings already loaded into your Zenoss instance and associated with a ZenPack. It exports them to the YAML format required for zenpack.yaml. It is up to you to merge that YAML with your existing zenpack.yaml file.

Only event classes sourced from the ZenPack’s XML are exported; event classes sourced from the ZenPack’s YAML are not exported. If you want the YAML for these event classes, copy it from the ZenPack’s existing YAML.

Example usage:

zenpacklib --dump-event-classes ZenPacks.example.BetterAlreadyBeInstalled

When dumping existing event classes using the zenpacklib script with the --dump-event-classes option, some transforms and/or explanations may show as either unformatted text within double quotes or as formatted text within single quotes. This is due to how the Python yaml package handles strings. Either format is acceptable in zenpack.yaml.

dump-process-classes

The --dump-process-classes switch exports process class organizers and classes already loaded into your Zenoss instance and associated with a ZenPack. It exports them to the YAML format required for zenpack.yaml. It is up to you to merge that YAML with your existing zenpack.yaml file.

Only process class organizers sourced from the ZenPack’s XML are exported; process class organizers sourced from the ZenPack’s YAML are not exported. If you want the YAML for these process class organizers, copy it from the ZenPack’s existing YAML.

Example usage:

zenpacklib --dump-process-classes ZenPacks.example.BetterAlreadyBeInstalled

optimize

The --optimize switch (experimental) is designed to examine your zenpack.yaml file and rearrange it for brevity and use of DEFAULTS where detected. Once optimized, the command compares the original YAML file to the optimized version to ensure that the same objects are created. The change detection, however, is still being improved and may output false warnings. It is recommended to double-check the optimized YAML output by hand.

Example usage:

zenpacklib --optimize zenpack.yaml