Transcription
SNMP MIB User GuideRevision: 1.0Raritan Inc.March 31, 2016
SNMP MIB User GuideCONTENTSContentsContentsii1 Quick Start1.1 Determine the status of an outlet . . . . . . . . . . . . . . .1.2 Power cycle an outlet . . . . . . . . . . . . . . . . . . . . . .1.3 Get the voltage reading of an inlet . . . . . . . . . . . . . .1.4 Get the number of decimal digits of an inlet voltage reading1.5 Receive a trap message on an external sensor alarm assertion1.6 Get an asset management tag ID . . . . . . . . . . . . . . .1.7 Set the name of a rack unit in asset management . . . . . .112234552 About this document2.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.2 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66663 Capabilities74 Access4.1 SNMP Interface Configuration4.2 Protocol Versions . . . . . . .4.3 MIB Version . . . . . . . . . .4.4 Authentication . . . . . . . .888895 Object Indexing5.1 Scalar Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.2 Columnar Objects – Single Index . . . . . . . . . . . . . . . . . . . . . .5.3 Columnar Objects – Multiple Indexes . . . . . . . . . . . . . . . . . . . .101011126 MIB tree15.Page ii
SNMP MIB User Guide11QUICK STARTQuick StartThis section contains some brief examples of tasks that can be performed on a PDU’sSNMP interface. All of them assume the following preconditions: SNMP was set up as shown in figure 1 and 2 in section 4.1 the Net-SNMP tools are installed (see www.net-snmp.org) the MIB files (see section 4.3 how to get them) are located in the MIB search path,which can be adjusted by adding -M path to the snmp command argumentsEach example will present the MIB object identifier to deal with and an SNMP commandline with related execution output. The object identifier includes the applicable variables,e. g. “ outlet number ” which are replaced with actual values in the command andoutput example.1.1Determine the status of an outletComplete Object tletSwitchingState. pdu id . outlet number Command:snmpget -v2c -c public -m PDU2-MIB pdu IP address \PDU2-MIB::outletSwitchingState.1.4snmpget -v2c -c public pdu IP address ::outletSwitchingState.1.4 INTEGER: off(8)Page 1
SNMP MIB User Guide1.21QUICK STARTPower cycle an outletComplete Object itchingOperation. pdu id . outlet number Command:snmpset -v2c -c private -m PDU2-MIB pdu IP address \PDU2-MIB::switchingOperation.1.4 cyclesnmpset -v2c -c private pdu IP address \.1.3.6.1.4.1.13742.6.4.1.2.1.2.1.4 i 2Output:PDU2-MIB::switchingOperation.1.4 INTEGER: cycle(2)1.3Get the voltage reading of an inletComplete Object asurementsEntry.measurementsInletSensorValue. pdu id . inlet number . sensor type Command:snmpget -v2c -c public -m PDU2-MIB pdu IP address tagesnmpget -v2c -c public pdu IP address IB::measurementsInletSensorValue.1.1.rmsVoltage Gauge32: 397Page 2
SNMP MIB User Guide1.41QUICK STARTGet the number of decimal digits of an inlet voltage readingComplete Object nEntry.inletSensorDecimalDigits. pdu id . inlet number . sensor type Command:snmpget -v2c -c public -m PDU2-MIB pdu IP address snmpget -v2c -c public pdu IP address IB::inletSensorDecimalDigits.1.1.rmsVoltage Gauge32: 0Page 3
SNMP MIB User Guide1.51QUICK STARTReceive a trap message on an external sensor alarm assertionComplete Object eChangesnmptrapd Configuration File:The host that should receive the SNMP notification messages needs to run snmptrapd. Its configuration file is usually located at /etc/snmp/snmptrapd.confand specifies at least the community string and the object identifiers that shouldbe handled. A minimalistic configuration for logging external sensor state changeswill just contain two lines:authCommunity log publictraphandle PDU2-MIB::externalSensorStateChangeNote that the string “public” must be specified in the SNMP notification settingsof the PDU, see section 4.1.Command:snmptrapd -m PDU2-MIBOutput:On reception of an SNMP trap the daemon will print the trap contents to its console.The output will be printed without line breaks, the example has them to tance Timeticks: (36334) 0:06:03.34SNMPv2-MIB::snmpTrapOID.0 OID: me STRING: my PXPDU2-MIB::pduNumber INTEGER: 0PDU2-MIB::pxInetAddressType INTEGER: ipv4(1)PDU2-MIB::pxInetIPAddress Hex-STRING: C0 A8 02 93PDU2-MIB::agentInetPortNumber Gauge32: 161PDU2-MIB::externalSensorNumber INTEGER: 25PDU2-MIB::typeOfSensor INTEGER: meStamp Gauge32: e INTEGER: 42PDU2-MIB::measurementsExternalSensorState INTEGER: belowLowerWarning(3)PDU2-MIB::oldSensorState INTEGER: normal(4)PDU2-MIB::externalSensorSerialNumber STRING: AAR3Sh0005PDU2-MIB::externalOnOffSensorSubtype INTEGER: none(31)PDU2-MIB::externalSensorChannelNumber INTEGER: -1SNMPv2-MIB::sysContact STRING: n/aSNMPv2-MIB::sysName STRING: n/aSNMPv2-MIB::sysLocation STRING: n/aPage 4
SNMP MIB User Guide1.61QUICK STARTGet an asset management tag IDComplete Object tManagementEntry.tagID. asset strip number . rack unit index Command:snmpget -v2c -c public -m ASSETMANAGEMENT-MIB pdu IP address \ASSETMANAGEMENT-MIB::tagID.1.5snmpget -v2c -c public pdu IP address AGEMENT-MIB::tagID.1.5 STRING: B1A0C499D35F1.7Set the name of a rack unit in asset managementComplete Object tManagementEntry.rackUnitName. asset strip number . rack unit index Command:snmpset -v2c -c private -m ASSETMANAGEMENT-MIB pdu IP address \ASSETMANAGEMENT-MIB::rackUnitName.1.5 MyNamesnmpset -v2c -c private pdu IP address \.1.3.6.1.4.1.13742.7.1.7.1.1.12.1.5 s MyNameOutput:ASSETMANAGEMENT-MIB::rackUnitName.1.5 STRING: MyNamePage 5
SNMP MIB User Guide22ABOUT THIS DOCUMENTAbout this document2.1ScopeThe Raritan PDU SNMP MIB User Guide provides information about the following: configuration, access and capabilities of the SNMP interface usage of tables structure of the PDU’s Management Information BaseThis document applies to the following Raritan PDU devices: PX2 / PX3 / PX3TS EMX BCM2 / PMC BCM PXEThe very basics of the SNMP protocol and the SMI concepts are not covered. Toolslike MIB browsers or snmp utilities are not explained as well. This documents describeshow the SNMP interface of a Raritan PDU can be utilized by the SNMP protocol by forexample using such tools.2.2AudienceThis document should primarily guideData Center Operators who want to configure PDUs, request values or control statessporadically,DCIM software developers who want to integrate PDUs into higher level management frameworks andScript Developers who want to write code that uses the PDU’s SNMP interface.2.3PrerequisitesThis document presumes understanding of Structured Management Information (SMI), the Simple Network Management Protocol (SNMP) and Management Information Base (MIB) documents.Page 6
SNMP MIB User Guide33CAPABILITIESCapabilitiesThe SNMP interface has almost the same capabilities as the web interface and the serialcommand line interface. It can be used to: retrieve logged and current sensor measurements get notifications on events control actuators configure names, thresholds etc.The following features are not accessable via SNMP: User Management Network Configuration Services Configuration Event Rule ConfigurationPage 7
SNMP MIB User Guide44ACCESSAccess4.1SNMP Interface ConfigurationThe unit’s SNMP interface can be enabled and set up in the web frontend or commandline interface. The settings dialog can be found in the menu under Network / Services.Figure 1: SNMP settings dialog of web user interface4.2Protocol VersionsBoth SNMP v1/v2c and v3 versions are supported. They can be enabled or disabledindependently.4.3MIB VersionWhile changes of the MIB may happen between different PDU firmware versions, allchanges are done in a downward compatible way. The used MIB should be newer thanor as current as the firmware of the PDU. A PDU’s MIB can be downloaded from theweb user interface of the unit – see the “Download” button in the left bottom corner ofthe SNMP settings dialog (figure 1). There are three different MIB files: PDU2-MIB ASSETMANAGEMENT-MIB LHX-MIBPage 8
SNMP MIB User Guide4ACCESSFigure 2: SNMP notification settings dialog of the web user interface4.4AuthenticationIn SNMP v1/v2c authentication is accomplished with community strings. The read aswell as the write community string can be configured in the SNMP settings (see figure 1).SNMP v3 authentication is set up on a per user basis. The settings are accessiblein user settings (see figure 3).An example command that uses SNMP v3 access to display the whole object treebelow the PDU2-MIB::pdu2 object is:snmpwalk -v3 -l authPriv -u username \-a SHA -A authentication passphrase \-x DES -X privacy passphrase \ pdu IP address PDU2-MIB::pdu2Arguments:-l security level – “noAuthNoPriv”, “authNoPriv”, “authPriv”-a authentication protocol – “MD5”, “SHA”-x privacy protocol – “DES”, “AES”Page 9
SNMP MIB User Guide5OBJECT INDEXINGFigure 3: SNMP v3 user setup dialog of web user interface5Object Indexing5.1Scalar ObjectsInformation unique to an SNMP agent is represented by “scalar” objects. An example ispduCount which is located atPDU2-MIB::pdu2.configuration.pduCountScalar objects are marked out as such by appending a zero to their object identifier.PDU2-MIB::pdu2.configuration.pduCount.0 INTEGER: 1In numerical representation:.1.3.6.1.4.1.13742.6.3.1.0 INTEGER: 1Since one SNMP agent running on a PDU is not limited to represent only a single PDUinstance, most information entities are indexed by the PDU identifier – pduId – whichis fixed to 1 for PX products but may vary on BCM2 products.pduId OBJECT-TYPESYNTAX Integer32(0.256)DESCRIPTION"A unique value for each PDU/Power meter.PX2/3 and transfer switch: pduId 1BCM2:main controller: pduId 0power meter: pduId rotary switch settingfor the power meterIt is the same as the MeterID in the GUIExample:a power meter, rotary switch setting 5,pduId 5a panel (power meter branch metering),rotary switch setting 23, pduId 23"This “indexed” information is structured in tables as described in the next section.Page 10
SNMP MIB User Guide5.25OBJECT INDEXINGColumnar Objects – Single IndexThis section explains the use of SNMP tables in the PDU2-MIB that are indexed by asingle value. Consider the following example:nameplateTable OBJECT-TYPESYNTAXSEQUENCE OF NameplateEntryStruct.DESCRIPTION"A list of PDU nameplate entries. The number ofentries is given by the value of pduCount.":: { unit 1 }nameplateEntry An entry providing PDU nameplate information."INDEX{ pduId }:: { nameplateTable 1 }NameplateEntryStruct :: SEQUENCE ing,pduRatedFrequency layString}This part of the MIB defines a one-dimensional table of entries that hold nameplateinformation. It is one-dimensional because the INDEX clause contains a single identifier.nameplateEntry OBJECT-TYPE.INDEX { pduId }.One entry in the table corresponds to one PDU and a pduId value is sufficient tospecify an entry in the table. See table 1 and 2 as examples. An SNMP agent runningon a PX has a single PDU identifier with the value 1 for that PX per definition, as in thefirst example. The second example shows the nameplate table of a BCM2 device thatmay have multiple PDU ialNumber.1.Table 1: Nameplate table of a PDUThe table structure is built as follows. Each cell of the table header corresponds toone member of the NameplateEntryStruct sequence. The cells of the tables body arethe objects. Their object identifiers are noted below.Page 11
SNMP MIB User Guide5OBJECT .11pduSerialNumber.11.Table 2: Nameplate table of a PMC with three PMMsAs a detailed example, the full SNMP object identifier of the PDU model string intable 1 “PX3-5526X2-M5” is broken down in table ntry.pduModel. pdu id Notetable objectdefines columns and indexselected columnindex / selected rowTable 3: Object identifier of PDU model string in the unit’s nameplate tableTo address objects in the table, the shortened symbolic object identifier consists ofthe column name and the index. For example the pduModel string (from NameplateEntryStruct) of PDU 1 is:PDU2-MIB::pduModel.1Note: Most object identifiers that are used as indexes or parts of indexes like “outletId”,“inletPoleIndex” or “circuitId” are 1-based integer values.5.3Columnar Objects – Multiple IndexesIn cases where a single value is not sufficient as an index to a table of objects, the indexmay consist of multiple instances of identifiers. Consider the table that holds outlet sensormeasurement variables outletSensorMeasurementsTable.Page 12
SNMP MIB User Guide5OBJECT INDEXINGoutletSensorMeasurementsTable OBJECT-TYPESYNTAXSEQUENCE OF OutletSensorMeasurementsEntryStruct.DESCRIPTION"A list of outlet sensor entries. The number ofentries is given by the value of outletCount for the PDU.":: { measurementsOutlet 3 }outletSensorMeasurementsEntry ct.DESCRIPTION"An entry containing measurement objects for an outlet sensor."INDEX{ pduId, outletId, sensorType }:: { outletSensorMeasurementsTable 1 }OutletSensorMeasurementsEntryStruct :: SEQUENCE {measurementsOutletSensorIsAvailable surementsOutletSensorSignedValue Integer32}The structure is the same as in section 5.2 – table object, entry object and the tablecolumns. The difference here is the INDEX clause.outletSensorMeasurementsEntry OBJECT-TYPE.INDEX{ pduId, outletId, sensorType }.The definition states that the index consists of three parts. Each outlet sensor withinone SNMP agent is identified by its PDU’s identifier, its outlet number and the type ofthe sensor. The index that is appended to the object identifier of outletSensorMeasurementsEntry is formed by these three parts. For example, an object identifier tothe measurementsOutletSensorValue of the active power of the fifth outlet is formedas shown in table y.measurementsOutletSensorValue. pdu id . outlet number . sensor type Notetable objectdefines columns and indexselected column)indexes / selected rowTable 4: Object identifier of active power sensor value of the fifth outletPage 13
SNMP MIB User Guide5OBJECT INDEXINGThe symbolic object identifier can be shortened ivePowerAs another example, table 5 shows a part of the whole outlet sensor measurementstable. The first column contains the index of the entries starting with the rmsCurrentsensor of the fourth easurementsOutletSensorIsAvailable SensorState normal500truenormal0truenormal0.trueoff0.Table 5: Parts of the outlet sensor measurements table that show sensors of outletsnumber 4 and 5To inspect SNMP tables the snmptable command might be useful, for examplesnmptable -m PDU2-MIB -v2c -cpublic -Cilb pdu IP address \PDU2-MIB::inletSensorConfigurationTable cut -c1-57prints a nicely readable left hand part of the inlet sensor configuration s30000201303000020130Page 14
SNMP MIB User Guide66MIB TREEMIB treeThis section describes the basic structure of the PDU2-MIB tree. The following clip ofthe PDU2-MIB file shows the various subtrees that reside below the PDU2-MIB::pdu2object:raritan MODULE-IDENTITY.:: { enterprises 13742 }pdu2 OBJECT IDENTIFIER :: { raritan 6 IFIERIDENTIFIERIDENTIFIER:: :: :: :: :: :: :: :: :: {{{{{{{{{pdu2pdu2pdu2pdu2pdu2pdu2pdu2pdu2pdu20 }1 }2 }3 }4 }5 }6 }9 }10 }The subtree configuration contains most of the information that is writable / configurable. The measurements and log subtrees contain sensor values and state information. The control subtree allows manipulation of the PDU such as switching outletsor resetting energy counters.Table 6 shows the most commenly used tables of the PDU2-MIB. Each cell represents a name that is built by its column name and its row name appended. An “x”mark states that a table with this name can actually be found in the MIB. For example:unitConfigurationTable does exist while unitPoleConfigurationTable does xxxxxxxxxPrefixesoverCurrent- powerProtector ble 6: Table names present in the MIBThe particular contents of these tables are quite common:-ConfigurationTableContains metadata, capabilities, configuration and state information of the PDU’sparts; for example the current rating of an outlet or the unit’s IP address.1The actual name is “transferSwitchControlTable” rather than transferSwitchSwitchControlTable.Page 15
SNMP MIB User Guide6MIB TREE-SensorConfigurationTableContains sensor metadata such as accuracy or tolerance and the sensors’ thresholds.-SwitchControlTableContains objects that allow switching of outlets or between inlets of a transferswitch.-SensorControlTableContains objects that allow resetting of cumulating sensor values such as energycounters.-SensorMeasurementsTableContains sensor readings and state information.-SensorLogTableContains objects to access logged measurements data such as minimum, maximumand average values.To inspect parts of the tree, the tool snmptranslate can be used. Using the commandline option -Tp the whole subtree below the object identifier submitted to the commandwill be displayed in human readable format. For example:snmptranslate -m PDU2-MIB -Tp PDU2-MIB::pdu2. --transferSwitchPoleConfigurationTable(5) --transferSwitchPoleConfigurationEntry(1) Index: pduId, transferSwitchId, transferSwitchPoleIndex -- ---- Integer32 transferSwitchPoleIndex(1) Range: 1.256 -- -R-- EnumValtransferSwitchPoleLine(2) Textual Convention: LineEnumeration Values: lineL1(1), lineL2(2), lineL3(3), lineNeutral(4) -- -R-- Integer32 transferSwitchPoleIn1Node(3) -- -R-- Integer32 transferSwitchPoleIn2Node(4) -- -R-- Integer32 transferSwitchPoleOutNode(5) --powerMeter(10) --powerMeterConfigurationTable(2) --powerMeterConfigurationEntry(1) Index: pduId -- -RW- Unsigned powerMeterPhaseCTRating(2).Page 16
SNMP MIB User Guide 5 OBJECT INDEXING 5.2 ColumnarObjects–SingleIndex This section explains the use of SNMP tables in the PDU2-MIB that are indexed by a singlevalue. Considerthefollowingexample: nameplateTable OBJECT-TYPE SYNTAX SEQUENCE OF NameplateEntryStruct. DESCRIPTION "A list of PDU nameplate entries. The number of
