Command Line Reference
While most of zenpacklib’s functionality is as a Python module to be used as a library for helping build ZenPacks, zenpacklib also acts as a command line script to perform some useful actions.
The zenpacklib script can be run from the command line with:
zenpacklib
Running the command alone or with --help will return 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:
- -c, --create: Create a new zenpacklib-enabled ZenPack source directory.
- -l, --lint: Provides syntax and correctness on a YAML file.
- -d, --diagram: Export yUML (yuml.me) class diagram from a YAML file.
- -t, --dump-templates: Export existing monitoring templates to YAML.
- -e, --dump-event-classes: Export existing event classes and mappings to YAML.
- -r, --dump-process-classes: Export existing process classes to YAML.
- -p, --paths: Using the specified device, print a report of paths between objects.
- -o, --optimize: Optimize the layout of an existing zenpack.yaml file
- --version: Print zenpacklib version.
create
The --create switch will create a source directory for a zenpacklib-enabled ZenPack. This will include a setup.py, MANIFEST.in, the namespace and module directories, and a zenpack.yaml in the module directory. This ZenPack will be ready to be installed immediately though it will contain no functionality yet.
Example usage:
zenpacklib --create ZenPacks.example.MyNewPack
Running the above command would result in 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 will check the provided YAML file 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
lint will provide no output if the provided YAML file is found to be correct.
diagram
The --diagram switch will use Classes and Relationships in the provided YAML file to output the source for a yUML (http://yuml.me) class diagram. For ZenPacks with a non-trivial class model this can provide a useful view of the model.
Using this 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
Then running the following command.
zenpacklib --diagram zenpack.yaml
Would result in the following yUML class diagram source. You can now paste this into http://yuml.me to see what it looks like.
# 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 in the zenpack, 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 zenoss UI when a component is selected and a target class is selected from the filter dropdown.
The default behavior is to show component 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. —paths is primarily intended as 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 is designed to export monitoring templates already loaded into your Zenoss instance and associated with a ZenPack. It will export 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 is designed to export event class organizers and mappings already loaded into your Zenoss instance and associated with a ZenPack. It will export 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 will be exported. Any event classes sourced from the ZenPack’s YAML will not be exported. If the YAML for these event classes is desired, it should be copied from the ZenPack’s existing YAML.
Example usage:
zenpacklib --dump-event-classes ZenPacks.example.BetterAlreadyBeInstalled
When dumping existing event classes using the zenpacklib tool 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 of these two formats are acceptable when used in zenpack.yaml.
dump-process-classes
The --dump-process-classes switch is designed to export process class organizers and classes already loaded into your Zenoss instance and associated with a ZenPack. It will export 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 will be exported. Any process class organizers sourced from the ZenPack’s YAML will not be exported. If the YAML for these process class organizers is desired, it should be copied 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.
Example usage:
zenpacklib --optimize zenpack.yaml
version
The --version switch prints the zenpacklib version.
Example usage:
zenpacklib --version