289 lines
10 KiB
Plaintext
289 lines
10 KiB
Plaintext
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 time, 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.
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
FIXME:
|
|
|
|
Shutting down the UPS
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
It is desireable 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`.
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|