-
-
Notifications
You must be signed in to change notification settings - Fork 338
/
snmp-subdrivers.txt
295 lines (216 loc) · 10.7 KB
/
snmp-subdrivers.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
How to make a new subdriver to support another SNMP device
----------------------------------------------------------
Overall concept
~~~~~~~~~~~~~~~
The SNMP protocol allow for a common way to interact with devices over
the network.
The NUT "snmp-ups" driver is a meta-driver that handles many SNMP devices,
such as UPS and PDU. It consists of a core driver that handles most of the
work of talking to the SNMP agent, and several sub-drivers to handle
specific device manufacturers. Adding support for a new SNMP device is
easy, because it requires only the creation of a new sub-driver.
SNMP data Tree
~~~~~~~~~~~~~~
From the point of view of writing an SNMP subdriver, an SNMP device
consists of a bunch of variables, called OIDs (for Object IDentifiers).
Some OIDs (such as the current input voltage) are read-only, whereas
others (such as the beeper enabled/disabled/muted status) can be read and
written. OID are grouped together and arranged in a hierarchical tree
shape, similar to directories in a file system. OID components are
separated by ".", and can be expressed in numeric or textual form.
For example:
.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID
is equivalent to:
.1.3.6.1.2.1.1.2.0
Here is an excerpt tree, showing only two OIDs, sysDescr and sysObjectID:
.iso
.org
.dod
.internet
.mgmt
.mib-2
.system
.sysDescr.0 = STRING: Dell UPS Tower 1920W HV
.sysObjectID.0 = OID: .iso.org.dod.internet.private.enterprises.674.10902.2
(...)
.upsMIB
.upsObjects
.upsIdent
.upsIdentModel = STRING: "Dell UPS Tower 1920W HV"
(...)
.private
.enterprises
.674
.10902
.2
.100
.1.0 = STRING: "Dell UPS Tower 1920W HV"
(...)
As you can see in the above example, the device name is exposed three times,
through three different MIBs:
- Generic MIB-II (RFC 1213):
.iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0 = STRING: Dell UPS Tower 1920W HV
.1.3.6.1.2.1.1.1.0 = STRING: Dell UPS Tower 1920W HV
- UPS MIB (RFC 1628):
.iso.org.dod.internet.mgmt.mib-2.upsMIB.upsObjects.upsIdent.upsIdentModel = STRING: "Dell UPS Tower 1920W HV"
.1.3.6.1.2.1.33.1.1.2.0 = STRING: "Dell UPS Tower 1920W HV"
- DELL SNMP UPS MIB:
.iso.org.dod.internet.private.enterprises.674.10902.2.100.1.0 = STRING: "Dell UPS Tower 1920W HV"
But only the two last can serve useful data for NUT.
An highly interesting OID is *sysObjectID*: its value is an OID that refers to
the main MIB of the device. In the above example, the device points us at the
Dell UPS MIB. *sysObjectID*, also called "sysOID" is used by snmp-ups to find
the right mapping structure.
For more information on SNMP, refer to the
link:http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol[Wikipedia]
article, or browse the Internet.
To be able to convert values, NUT SNMP subdrivers need to provide:
- manufacturer-specific sysOID, to determine which lookup structure applies
to which devices,
- a mapping of SNMP variables to NUT variables,
- a mapping of SNMP values to NUT values.
Moreover, subdrivers might have to provide additional functionality,
such as custom implementations of specific instant commands (load.off,
shutdown.restart), and conversions of manufacturer specific data
formats. At the time of writing this document, snmp-ups doesn't provide
such mechanisms (only formatting ones), but it is planned in a future release.
Creating a subdriver
~~~~~~~~~~~~~~~~~~~~
In order to create a subdriver, you will need the following:
- the "MIB definition file. This file has a ".mib" extension, and is
generally available on the accompanying disc, or on the manufacturer
website. It should either be placed in a system directory
(/usr/share/mibs/ or equivalent), or pointed using *-M* option,
- a network access to the device
- OR information dumps.
You can create an initial "stub" subdriver for your device by using the helper
script *scripts/subdriver/gen-snmp-subdriver.sh*. Note that this only creates
a "stub" which MUST be customized to be useful (see CUSTOMIZATION below).
You have two options to run gen-snmp-subdriver.sh:
mode 1: get SNMP data from a real agent
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This method requires to have a network access to the device, in order to
automatically retrieve the needed information.
You have to specify the following parameters:
- *-H* host address: is the SNMP host IP address or name
- *-c* community: is the SNMP v1 community name (default: public)"
For example:
$ gen-snmp-subdriver.sh -H W.X.Y.Z -c foobar -n <MIB name>.mib
mode 2: get data from files
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This method does not require direct access to the device, at least
not for the one using gen-snmp-subdriver.sh.
The following SNMP data need to be dumped first:
- sysOID value: for example '.1.3.6.1.4.1.705.1'
- a numeric SNMP walk (OIDs in dotted numeric format) of the tree
pointed by sysOID. For example:
snmpwalk -On -c foobar W.X.Y.Z .1.3.6.1.4.1.705.1 > snmpwalk-On.log
- a textual SNMP walk (OIDs in string format) of the tree pointed by
sysOID. For example:
snmpwalk -Os -c foobar W.X.Y.Z .1.3.6.1.4.1.705.1 > snmpwalk-Os.log
NOTE: if the OID are only partially resolved (i.e, there are still parts
expressed in numeric form), then try using *-M* to point your .mib file.
Then call the script using:
$ gen-snmp-subdriver.sh -s <sysOID value> <numeric SNMP walk> <string SNMP walk>
For example:
$ gen-snmp-subdriver.sh -s .1.3.6.1.4.1.705.1 snmpwalk-On.log snmpwalk-Os.log
This script prompts you for a name for the subdriver if you don't provide it
with *-n*. Use only letters and digits, and use natural capitalization such
as "Camel" (not "camel" or "CAMEL", apart if it natural). The script may
prompt you for additional information.
Integrating the subdriver with snmp-ups
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Beside of the mandatory customization, there are a few things that you have
to do, as mentioned at the end of the script:
- edit drivers/snmp-ups.h and add #include "<HFILE>.h", where <HFILE> is the
name of the header file, with the *.h* extension,
- edit drivers/snmp-ups.c and bump DRIVER_VERSION by adding "0.01".
- also add "&<LDRIVER>" to snmp-ups.c:mib2nut[] list, where <LDRIVER> is the
lower case driver name
- add "<LDRIVER>-mib.c" to snmp_ups_SOURCES in drivers/Makefile.am
- add "<LDRIVER>-mib.h" to dist_noinst_HEADERS in drivers/Makefile.am
- copy "<LDRIVER>-mib.c" and "<LDRIVER>-mib.h" to ../drivers/
- finally call the following, from the top level directory, to test
compilation:
$ autoreconf && configure && make
You can already start experimenting with the new subdriver; but all data
will be prefixed by "unmapped.". You will now have to customize it.
CUSTOMIZATION
^^^^^^^^^^^^^
The initially generated subdriver code is only a stub (mainly a big C
structure to be precise), and will not implement any useful functionality
(in particular, it will be unable to shut down the UPS). In the beginning,
it simply attempts to monitor some UPS variables. To make this driver useful,
you must examine the NUT variables of the form "unmapped.*" in the
hid_info_t data structure, and map them to actual NUT variables and
instant commands. There are currently no step-by-step instructions for
how to do this. Please look at the files to see how the currently implemented
subdrivers are written:
- apc-mib.c/h
- baytech-mib.c/h
- bestpower-mib.c/h
- compaq-mib.c/h
- cyberpower-mib.c/h
- eaton-*-mib.c/h
- ietf-mib.c/h
- mge-mib.c/h
- netvision-mib.c/h
- powerware-mib.c/h
- raritan-pdu-mib.c
- huawei-mib.c/h
To help you, above each entry in <LDRIVER>-mib.c, there is a comment that
displays the textual OID name. For example, the following entry:
/* upsMIB.upsObjects.upsIdent.upsIdentModel = STRING: "Dell UPS Tower 1920W HV" */
{ "unmapped.upsidentmodel", ST_FLAG_STRING, SU_INFOSIZE,
".1.3.6.1.4.1.2254.2.4.1.1.0", NULL, SU_FLAG_OK, NULL },
Many times, only the first field will need to be modified, to map to an actual
NUT variable name.
Check the <<nut-names,NUT command and variable naming scheme>> section first
to find a name that matches the OID name (closest fit). If nothing matches,
contact the upsdev list, and we'll figure it out.
In the above example, the right NUT variable is obviously "device.model".
The MIB definition file (.mib) also contains some description of these OIDs,
along with the possible enumerated values.
NOTE: To test existing data points (including those not yet translated
to standard NUT mappings conforming to <<nut-names,NUT command and
variable naming scheme>>), you can use custom drivers built after you
`./configure --with-unmapped-data-points`.
Production driver builds must not include any non-standard names.
////////////////////////////////////////////////////////////////////////////////
FIXME:
Shutting down the UPS
~~~~~~~~~~~~~~~~~~~~~
It is desirable to support shutting down the UPS. Usually (for
devices that follow the HID Power Device Class specification), this
requires sending the UPS two commands. One for shutting down the UPS
(with an 'offdelay') and one for restarting it (with an 'ondelay'),
where offdelay < ondelay. The two NUT commands for which this is
relevant, are 'shutdown.return' and 'shutdown.stayoff'.
Since the one-to-one mapping above doesn't allow sending two HID
commands to the UPS in response to sending one NUT command to the
driver, this is handled by the driver. In order to make this work,
you need to define the following four NUT values:
ups.delay.start (variable, R/W)
ups.delay.shutdown (variable, R/W)
load.off.delay (command)
load.on.delay (command)
If the UPS supports it, the following variables can be used to show
the countdown to start/shutdown:
ups.timer.start (variable, R/O)
ups.timer.shutdown (variable, R/O)
The `load.on` and `load.off` commands will be defined implicitly by
the driver (using a delay value of '0'). Define these commands
yourself, if your UPS requires a different value to switch on/off
the load without delay.
Note that the driver expects the `load.off.delay` and `load.on.delay`
to follow the HID Power Device Class specification, which means that
the `load.on.delay` command should NOT switch on the load in the
absence of mains power. If your UPS switches on the load regardless of
the mains status, DO NOT define this command. You probably want to
define the `shutdown.return` and/or `shutdown.stayoff` commands in
that case. Commands defined in the subdriver will take precedence over
the ones that are composed in the driver.
When running the driver with the '-k' flag, it will first attempt to
send a `shutdown.return` command and if that fails, will fallback to
`shutdown.reboot`.
////////////////////////////////////////////////////////////////////////////////