Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 172 lines (136 sloc) 7.983 kb
7e4f6649 » Nick Yeates
2011-11-08 Initial commit by nyeates publishing script; Code was supplied only f…
1 # !! UPDATE THIS DOC !!
2 This file should contain documentation that is specific to what your ZenPack does.
3 It should give example screenshots, explain how to install it, amongst other topics.
4 Please see http://community.zenoss.org/docs/DOC-8495#README for details.
5
6 This file was automatically pulled from https://raw.github.com/zenoss/ZenPackTemplate/master/README.markdown
7 It contains general comments, not specific to this ZenPack
8
9 # ZenPack Template
10 This README describes the structure of the ZenPack template that gets
11 automatically created by Zenoss when you add a ZenPack through the web
12 interface.
13
14 ## Files
15 At the top-level a ZenPack must have a setup.py. Almost always a MANIFEST.in
16 file should exist, and in cases where external dependencies must be built for
17 inclusion in the ZenPack, a GNUmakefile. Examples of these files with inline
18 comments are included in this template.
19
20 Also included in the ZenPackTemplate is a configure.zcml. As more of Zenoss'
21 extensibility moves to using ZCA (Zope Component Architecture) this file
22 becomes crucial to hooking into various aspects of Zenoss.
23
24 ## Files and Subdirectories
25 The following sections describe the purpose and use for each of the default
26 subdirectories. Note that if the described functionality is not of use in your
27 ZenPack it is safe to remove any of the default directories.
28
29 ### src/
30 The src/ top-level directory in ZenPacks is the conventional place to add
31 third-party dependencies to your ZenPack. It should only be used as a staging
32 area to do any build work necessary for the dependency.
33
34 See GNUmakefile (or GNUmakefile.example) for examples of how to have
35 your third-party dependencies automatically compiled and installed at the right
36 time and into the right location.
37
38 ### ZenPacks/NAMESPACE/PACKNAME/
39 The following sections describe the directories contained within the
40 namespaced ZenPacks/NAMESPACE/PACKNAME/ subdirectories.
41
42 #### bin/
43 Any general tools delivered by your ZenPack that would be used by the Zenoss
44 administrator at the command line should go into this directory by convention.
45 When the ZenPack is installed all files in this directory will be made
46 executable.
47
48 #### browser/
49 The browser subdirectory should contain all code and configuration that's
50 specific to the Zenoss web interface. The provided configure.zcml will
51 automatically load the example browser/configure.zcml and register the
52 browser/resources/ subdirectory to serve static web content.
53
54 #### daemons/
55 All files in the daemons/ subdirectory get special handling. Upon installing
56 the ZenPack, the following actions will occur.
57
58 1. The file will be made executable (chmod 0755)
59 2. A symlink to the file will be created in $ZENHOME/bin/
60 3. An configuration file will be generated at $ZENHOME/etc/DAEMON_NAME.conf
61
62 Assuming that you don't have a $ZENHOME/etc/DAEMONS_TXT_ONLY file this daemon
63 will also become part of the normal zenoss start and stop processes.
64
65 You can find an example daemon control script in daemons/zenexample. For most
66 purposes this file can be renamed to the name of the daemon you want to create
67 and modified to change the DAEMON_NAME. No other modifications are typically
68 needed. Note that this example control script does expect to launch the real
69 daemon code which should be located at ../DAEMON_NAME.py.
70
71 #### datasources/
72 Any new datasource types you want to add must be added as classes into the
73 datasources/ subdirectory. When Zenoss is building the list of available
74 datasources it will scan the datasources/ subdirectory for all installed
75 ZenPacks.
76
77 An example datasource at datasources/ExampleDataSource.py.example.
78
79 #### lib/
80 The lib/ directory should be the installation target for any third-party
81 libraries that are built by the GNUmakefile. It can also be used as the
82 conventional location to drop Python-only libraries that don't require
83 any compilation or special installation.
84
85 #### libexec/
86 Any scripts executed by COMMAND datasources in your ZenPack go in this
87 directory by convention. When the ZenPack is installed all files in this
88 directory will be made executable.
89
90 #### migrate/
91 ZenPacks can include migrate scripts that allow you to run custom code to
92 handle any tasks that are needed to upgrade your ZenPack from one version to
93 another. All .py files in this migrate/ subdirectory will be evaluated when the
94 ZenPack is installed.
95
96 You can find an example migrate script at migrate/ExampleMigration.py.
97
98 #### modeler/
99 Any modeler plugins distributed with your ZenPack must be located under the
100 plugins/ subdirectory. The directory structure and filenames under plugins/
101 map directly to the plugins' name in the user interface. For example, if you
102 wanted to create a modeler plugin called "community.snmp.ExampleMap" you would
103 create the following directory structure.
104
105 It is recommended that the first portion of the namespace be a short lowercase
106 form of your name, or organization's name. Alternatively you can choose to use
107 "community" if you plan to publish the ZenPack and are open to outside
108 contributions. Zenoss, Inc. will always use "zenoss." The second portion of the
109 namespace can be the protocol that is used to collect the data. If you are not
110 using a common protocol it is acceptable to skip the second portion of the
111 namespace and have something like "community.MongoDB" instead.
112
113 plugins/
114 __init__.py
115 community/
116 __init__.py
117 snmp/
118 __init__.py
119 ExampleMap.py
120
121 Note that the ```__init__.py``` files must exist and should be empty files. Otherwise
122 your modeler plugins won't be imported and usable within Zenoss.
123
124 #### objects/
125 All .xml files in this objects/ directory will be loaded into the object
126 database when the ZenPack installs. All of the objects defined in the XML files
127 will be automatically associated with the ZenPack.
128
129 When you export the ZenPack from the user interface all objects associated with
130 the ZenPack will be exported into a file called "objects.xml" specifically. For
131 this reason it is recommended to let Zenoss manage the objects.xml file and to
132 never manually create or modify any .xml files in this directory unless you
133 know what you're doing.
134
135 When a ZenPack is removed, any objects associated with the ZenPack will be
136 recursively removed from Zenoss. For example, if you associated the /Server
137 device class with your ZenPack and removed the ZenPack, the /Server device
138 class, and all devices within it would also be deleted.
139
140 When a ZenPack is upgraded, or re-installed on top of itself, all objects in
141 the XML files are overlaid on the existing object database. This results in a
142 merge of the existing objects and what are defined in the XML files with the
143 XML file properties and relationships winning any conflicts.
144
145 #### reports/
146 Custom reports will be loaded from this directory when the ZenPack is
147 installed. Subdirectories (with the exception of plugins/) will be mapped
148 directly to the report folders in the web interface. So if you add a .rpt file
149 into a subdirectory named "Performance Reports" you will find your report in
150 the Performance Reports folder in the web interface after installing the
151 ZenPack.
152
153 The plugins/ subdirectory should include any Python plugins your custom reports
154 call. So if your .rpt file contains a line such as the following..
155
156 objects python:here.ReportServer.plugin('myplugin', tableState);
157
158 There should be a corresponding myplugin.py file in the plugins/ subdirectory.
159
160 You can find an example report at Example Reports/Example Report.rpt.example
161 that uses a plugin which can be found at plugins/example_plugin.py.
162
163 #### services/
164 ZenHub services will be loaded from the services/ directory. These services
165 run inside the zenhub daemon and are responsible from all interaction with
166 collector daemons.
167
168 You can find an example service at services/ExampleConfigService.py.
169
170 #### tests/
171 All unit tests for your ZenPack should live in this directory. You can find an
172 example test suite at tests/testExample.py.
Something went wrong with that request. Please try again.