3 MESH SNMP interface
This chapter describes a MESH adaptation for SNMP.
There is one MIB defined:
OTP-MESH-MIB
. This MIB can be found in themibs
directory in the MESH distribution. It is more closely described in the following sections.3.1 MESH SNMP adaptation
The MESH SNMP adaptation consists of functionality for translating the MESH events and alarms to SNMP traps, an SNMP MIB used to interface the MESH application remotely, and an API to be used when modifying the adaptation in a desired way.
3.1.1 OTP-MESH-MIB
This MIB implements managed objects for the basic MESH service in OTP. It consists of five tables, five variables, and a number of trap definitions.
The OTP-MESH-MIB is written according to SNMPv2.3.1.1.1 The typeTable
The
typeTable
has one entry for every measurement type known to the system.The
typeTable
consists of measurement type attributes that are both readable and writable. Through this table the manager may register measurement types, unregister them, and change their administrative state.The table has the following attributes:
typeName
typeInfo
typeCallbackMod
typeAdminState
typeMeasArgs
typeMaxInst
typeStatus
Each measurement type has a unique index,
typeName
, which remains constant as long as the measurement type entry isn't explicitly destroyed. This index is aDisplayString
, which will be translated to an atom inside the MESH SNMP adaptation. That is, all measurement type names have to be atoms, should the MESH SNMP adaptation be used!The
typeInfo
attribute may contain any information describing the measurement type.
The default value of this attribute is the empty list ("").The
typeCallbackMod
attribute defines the interface type module to use when communicating with the measurement type in question.The
typeAdminState
defines the current administrative state of the measurement type, i.e., whether it shall belocked
,unlocked
orshutting_down
. These values are enumerated: 1 ==unlocked
, 2 ==shutting_down
and 3 ==locked
.
The default value isunlocked
.The
typeMeasArgs
specifies the arguments that, when the type is locked, shall be forwarded to the (active) measurement objects belonging to the specified measurement type. It shall be noted that these arguments are ONLY used when the type is locked, never else!
The arguments are given as anDisplayString
, which is translated by the MESH SNMP adaptation to an Erlang term. That is, if one wants the list[1,2,3,4]
to be forwarded to the measurement objects, this attribute shall be set to"[1,2,3,4]"
.
The default value is the empty list ([]).The
typeMaxInst
specifies the number of measurement objects that are allowed within this type.
The default value is 50.The
typeStatus
attribute is used to create new entrys (i.e., to register measurement types), and to change the state of existing entries.
It shall be noted that only active entries corresponds to registered measurement types!3.1.1.1.1 Examples
We assume the system is up and running, and that the MESH SNMP has been started according to the description found in the earlier chapter "Services". We also assume we have started an SNMP agent and a manager, and that we have loaded the OTP-MESH-MIB in both of them, as well as the MIBs EVA requires.
Now assume we want to register a measurement type calleddiversity1
, which uses the interface modulediversity
. The original administrative state shall beunlocked
, and we allow 5 measurement objects to be started within this type:1> snmp_mgr:s([{[typeInfo | "diversity1"],"A simple measurement type"}, {[typeCallbackMod | "diversity1"],"diversity"}, {[typeAdminState | "diversity1"], 1}, {[typeMaxInst | "diversity1"],5}, {[typeStatus | "diversity1"], 4}]). ok * Got PDU: Response, Request Id:209647922 [typeInfo,100,105,118,101,114,115,105,116,121,49] = "A simple measurement type" [typeCallbackMod,100,105,118,101,114,115,105,116,121,49] = "diversity" [typeAdminState,100,105,118,101,114,115,105,116,121,49] = 1 [typeMaxInst,100,105,118,101,114,115,105,116,121,49] = 5 [typeStatus,100,105,118,101,114,115,105,116,121,49] = 4And if we now look at this new entry:
2> snmp_mgr:gn([[typeName,""]]). ok * Got PDU: Response, Request Id:223586022 [typeInfo,100,105,118,101,114,115,105,116,121,49] = "A simple measurement type" 3> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:66538327 [typeCallbackMod,100,105,118,101,114,115,105,116,121,49] = "diversity" 4> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:166382073 [typeAdminState,100,105,118,101,114,115,105,116,121,49] = 1 5> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:118759047 [typeMeasArgs,100,105,118,101,114,115,105,116,121,49] = [] 6> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:215999470 [typeMaxInst,100,105,118,101,114,115,105,116,121,49] = 5 7> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:254918516 [typeStatus,100,105,118,101,114,115,105,116,121,49] = 1We may also decide to set the administrative state to
locked
:8> snmp_mgr:s([{[typeAdminState | "diversity1"], 3}]). ok * Got PDU: Response, Request Id:14458468 [typeAdminState,100,105,118,101,114,115,105,116,121,49] = 3And if we want to unregister the type and remove it from the system:
9> snmp_mgr:s([{[typeStatus | "diversity1"], 6}]). ok * Got PDU: Response, Request Id:186830689 [typeStatus,100,105,118,101,114,115,105,116,121,49] = 63.1.1.2 The typeInfoTable
The
typeInfoTable
has one entry for every measurement type known to the system.The
typeInfoTable
consists of measurement type attributes that are readable only.The table has the following attributes:
typeInfoName
typeInfoCurrInst
The
typeInfoName
is the index field; each measurement type corresponds to one entry. This index remains constant as long as the measurement type entry isn't explicitly destroyed. This index is aDisplayString
, which will be translated to an atom inside the MESH SNMP adaptation.The
typeInfoCurrInst
attribute contains the current number of active measurement objects belonging to this specific measurement type.3.1.1.3 The measTable
The
measTable
has one entry for every measurement object known to the system.The
measTable
consists of measurement object attributes that are both readable and writable. Through this table the manager may create measurement objects, delete them, and change their administrative state (i.e., start and stop them).The table has the following attributes:
measId
measType
measInfo
measResId
measAdminState
measArgs
measStatus
Each measurement object has a unique index,
measId
, which remains constant as long as the measurement object entry isn't explicitly destroyed. This index is aDisplayString
, which will be translated to an atom inside the MESH SNMP adaptation. That is, all measurement object names have to be atoms, should the MESH SNMP adaptation be used!The
measType
attribute specifies the measurement type the measurement object belongs to. This attribute is also given as aDisplayString
, which will be translated to an atom inside the MESH SNMP adaptation.
Note that the specified measurement type has to be registered, otherwise the create operation will fail!The
measInfo
attribute may contain any information describing the measurement object.
The default value of this attribute is the empty list ("").The
measResId
attribute is aDisplayString
specifying the resources the measurement object is assumed to use. This string will be translated to an Erlang term inside the MESH SNMP adaptation.The
measAdminState
defines the current administrative state of the measurement object, i.e., whether it shall bestarted
orstopped
. These values are enumerated: 1 ==started
and 2 ==stopped
.
The default value isstarted
.The
measArgs
specifies the arguments that, when the mesurement object is created, deleted, started, stopped, or reset, shall be forwarded to it. It shall be noted that these arguments are NOT used when the type is locked; in that case the argument list specified in thetypeTable
is used instead! The arguments are given as anDisplayString
, which is translated by the MESH SNMP adaptation to an Erlang term. That is, if one wants the list[1,2,3,4]
to be forwarded to the measurement object, this attribute shall be set to"[1,2,3,4]"
.
The default value is the empty list ([]).The
measStatus
attribute is used to create new entrys (i.e., to create new measurement objects), and to change the state of existing entries.
It shall be noted that only active entries correspond to created measurement objects!3.1.1.3.1 Examples
We assume the same system state as in the previous example, and also that we have registered a measurement type "diversity1".
Now assume we want to create a measurement object calleddiv11
. This object shall use a resource identified with the integer 0 (zero), the original administrative state shall bestarted
, and the initial arguments shall be the list[1,2,3]
:10> snmp_mgr:s([{[measType | "div11"],"diversity1"}, {[measInfo | "div11"],"A simple measurement object"}, {[measResId | "div11"],"0"}, {[measAdminState | "div11"],1}, {[measArgs | "div11"],"[1,2,3]"}, {[measStatus | "div11"],4}]). ok * Got PDU: Response, Request Id:12669132 [measType,100,105,118,49,49] = "diversity1" [measInfo,100,105,118,49,49] = "A simple measurement object" [measResId,100,105,118,49,49] = "0" [measAdminState,100,105,118,49,49] = 1 [measArgs,100,105,118,49,49] = "[1,2,3]" [measStatus,100,105,118,49,49] = 4And if we now look at this new entry:
11> snmp_mgr:gn([[measId,""]]). ok * Got PDU: Response, Request Id:115469191 [measType,100,105,118,49,49] = "diversity1" 12> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:139112371 [measInfo,100,105,118,49,49] = "A simple measurement object" 13> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:164740948 [measResId,100,105,118,49,49] = "0" 14> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:76656359 [measAdminState,100,105,118,49,49] = 1 15> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:105654964 [measArgs,100,105,118,49,49] = [1,2,3] 16> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:59931249 [measStatus,100,105,118,49,49] = 1We may also look at the updated measurement type information:
17> snmp_mgr:g([[typeInfoCurrInst | "diversity1"]]). ok * Got PDU: Response, Request Id:252519077 [typeInfoCurrInst,100,105,118,101,114,115,105,116,121,49] = 1We may stop the measurement object:
18> snmp_mgr:s([{[measAdminState | "div11"],2}]). ok * Got PDU: Response, Request Id:262901542 [measAdminState,100,105,118,49,49] = 2And we may start the object again, with some new arguments:
19> snmp_mgr:s([{[measAdminState | "div11"],1},{[measArgs | "div11"],"[4,5,6]"}]). ok * Got PDU: Response, Request Id:257409456 [measAdminState,100,105,118,49,49] = 1 [measArgs,100,105,118,49,49] = "[4,5,6]"And finally we may also delete our measurement object, supplying the string "free_resources" as terminating arguments (remember that this string will be interpreted as an Erlang term in the MESH SNMP adaptation - in this case as an atom!):
20> snmp_mgr:s([{[measArgs | "div11"],"free_resources"},{[measStatus | "div11"], 6}]). ok * Got PDU: Response, Request Id:152978686 [measArgs,100,105,118,49,49] = "free_resources" [measStatus,100,105,118,49,49] = 6To convince ourselves that the measurement object has disappeared, we may look at the current number of instances belonging to measurement type
diversity1
:21> snmp_mgr:g([[typeInfoCurrInst | "diversity1"]]). ok * Got PDU: Response, Request Id:136894792 [typeInfoCurrInst,100,105,118,101,114,115,105,116,121,49] = 03.1.1.4 The measInfoTable
The
measInfoTable
has one entry for every measurement object known to the system.The
typeInfoTable
consists of measurement object attributes that are readable only.The table has the following attributes:
measInfoId
measInfoLastVal
measInfoLastValTime
measInfoLastValInfo
measInfoMaxTideCurr
measInfoMaxTidePrev
measInfoMinTideCurr
measInfoMinTidePrev
measInfoLastReset
The
MeasInfoId
is the index field; each measurement object corresponds to one entry. This index remains constant as long as the measurement object entry isn't explicitly destroyed. This index is aDisplayString
, which will be translated to an atom inside the MESH SNMP adaptation.The
measInfoLastVal
attribute contains, as aDisplayString
, the last measurement value the Measurement Handler has received from the specified measurement object.The
measInfoLastValTime
attribute contains, as aDisplayString
, the time the last measurement value was obtained by the measurement object.The
measInfoLastValInfo
attribute contains, as aDisplayString
, additional information about the the last measurement value the Measurement Handler has received.The
measInfoMaxTideCurr
attribute contains, as aDisplayString
, thecurrent
value in the maximum tidemark associated with the specified measurement object.The
measInfoMaxTidePrev
attribute contains, as aDisplayString
, theprevious
value in the maximum tidemark associated with the specified measurement object.The
measInfoMinTideCurr
attribute contains, as aDisplayString
, thecurrent
value in the minimum tidemark associated with the specified measurement object.The
measInfoMinTidePrev
attribute contains, as aDisplayString
, theprevious
value in the minimum tidemark associated with the specified measurement object.The
measInfoLastReset
attribute contains, using theDateAndTime
format (see MIB SNMPv2-TC), the date and time of the last reset.
NOTE: If the measurement object never has been reset, the list[0,0,0,0,0,0,0,0]
will be returned.3.1.1.4.1 Examples
We assume that we have the measurement object
div11
(see previous example) running, that is, reporting measurement values, and also that this measurement object has been reset once.22> snmp_mgr:gn([[measInfoId, ""]]). ok * Got PDU: Response, Request Id:256037314 [measInfoLastVal,100,105,118,49,49] = "100" 23> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:244235445 [measInfoLastValTime,100,105,118,49,49] = "{19,52,37}" 24> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:141582032 [measInfoLastValInfo,100,105,118,49,49] = [] 25> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:182241904 [measInfoMaxTideCurr,100,105,118,49,49] = "100" 26> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:211213648 [measInfoMaxTidePrev,100,105,118,49,49] = "100" 27> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:210013650 [measInfoMinTideCurr,100,105,118,49,49] = "0" 28> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:2594486 [measInfoMinTidePrev,100,105,118,49,49] = "0" 29> snmp_mgr:gn(). ok * Got PDU: Response, Request Id:46299549 [measInfoLastReset,100,105,118,49,49] = [19,98,7,8,17,52,33,0]3.1.1.5 The threshTable
The
threshTable
has one entry for every threshold known to the system.The
threshTable
consists of threshold attributes that are both readable and writable. Through this table the manager may set upper and lower thresholds, remove them, and change their administrative state (i.e., enable and disable them).The table has the following attributes:
threshMeasId
threshId
threshType
threshVal1
threshVal2
threshAdminState
threshStatus
The
threshMeasId
and thethreshId
fields are the indices; this is due to the fact that a threshold is identified uniquely by the threshold identifier together with the measurement object it belongs to. Each threshold in the system corresponds to one entry. The two indices remain constant as long as the threshold entry isn't explicitly destroyed.
ThethreshMeasId
index field is aDisplayString
, which will be translated to an atom inside the MESH SNMP adaptation. ThethreshId
index field is an integer.
NOTE: All threshold identifiers have to be integers, should the MESH SNMP adaptation be used!The
threshType
attribute decides whether the threshold is anupper
threshold or alower
one. These two types are enumerated: 1 ==upper
and 2 ==lower
.
The default value isupper
.The
threshVal1
attributes sets the threshold value that triggers the threshold. The value is given as aDisplayString
, which is converted to an Erlang term in the MESH SNMP adaptation.
The default value is "0" (zero).The
threshVal2
attributes sets the threshold value that un-triggers the threshold. The value is given as aDisplayString
, which is converted to an Erlang term in the MESH SNMP adaptation.
The default value is the one thatthreshVal1
was set to.The
threshAdminState
tells whether the threshold shall beenabled
ordisabled
. These states are enumerated: 1 ==enabled
and 2 ==disabled
. The default value isenabled
.The
threshStatus
attribute is used to create new entrys (i.e., to set new thresholds), and to change the state of existing entries.
It shall be noted that only active entries correspond to set thresholds!3.1.1.5.1 Examples
We assume that we have the same measurement object
div11
as in the previous example. We want to set an upper threshold, having the integer 1 as identifier, and with original administrative stateenabled
. After the creation we disable it, enable it again, and finally deletes it:30> snmp_mgr:s([{[threshType | "div11" ++ [1]], 1}, {[threshVal1 | "div11" ++ [1]], "90"}, {[threshVal2 | "div11" ++ [1]], "85"}, {[threshAdminState | "div11" ++ [1]], 1}, {[threshStatus | "div11" ++ [1]], 4}]). ok * Got PDU: Response, Request Id:124268928 [threshType,100,105,118,49,49,1] = 1 [threshVal1,100,105,118,49,49,1] = "90" [threshVal2,100,105,118,49,49,1] = "85" [threshAdminState,100,105,118,49,49,1] = 1 [threshStatus,100,105,118,49,49,1] = 4 31> snmp_mgr:s([{[threshAdminState | "div11" ++ [1]], 2}]). ok * Got PDU: Response, Request Id:165662114 [threshAdminState,100,105,118,49,49,1] = 2 32> snmp_mgr:s([{[threshAdminState | "div11" ++ [1]], 1}]). ok * Got PDU: Response, Request Id:225312294 [threshAdminState,100,105,118,49,49,1] = 1 33> snmp_mgr:s([{[threshStatus | "div11" ++ [1]], 6}]). ok * Got PDU: Response, Request Id:153618962 [threshStatus,100,105,118,49,49,1] = 63.1.1.6 The watchdogNofTypes variable
This variable is used to set the allowed (total) number of measurement types that are allowed in the system.
3.1.1.7 The watchdogNofMeas variable
This variable is used to set the allowed (total) number of measurement objects that are allowed in the system.
3.1.1.8 The currentNofTypes variable
This variable is used to read the current (total) number of measurement types in the system.
3.1.1.9 The currentNofMeas variable
This variable is used to read the current (total) number of measurement objects in the system.
3.1.1.10 The currentNofMeas variable
This variable is used to reset measurement objects. The measurement object is entered as a
DisplayString
, which is interpreted as an atom inside the MESH SNMP adaptation. Reset arguments are taken from the correspondingmeasArgs
field in themeasTable
. That is, themeasArgs
field has to be set to the desired value BEFORE this variable is set!
NOTE: the reset operation is allowed in all measTable row/measurement object states, as long as the row exists, but the operation is only meaningful (i.e., will only have any real effect) when the row state is 'active'.
NOTE: this variable is intended to be write-only; however, this is not allowed in SNMP, meaning the variable has to be read-write. If the user tries to read the current value, it shall be noted that it is only the last reset request made using SNMP that is shown! That is, measurement objects/applications/supervisors may, in the managed system, have ordered reset themselves - these reset orders are NOT visible through this variable!