[Erlang Systems]

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 the mibs 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:

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 a DisplayString, 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 be locked, unlocked or shutting_down. These values are enumerated: 1 == unlocked, 2 == shutting_down and 3 == locked.
The default value is unlocked.

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 an DisplayString, 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 called diversity1, which uses the interface module diversity. The original administrative state shall be unlocked, 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] = 4

And 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] = 1

We 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] = 3

And 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] = 6
3.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:

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 a DisplayString, 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:

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 a DisplayString, 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 a DisplayString, 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 a DisplayString 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 be started or stopped. These values are enumerated: 1 == started and 2 == stopped.
The default value is started.

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 the typeTable is used instead! The arguments are given as an DisplayString, 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 called div11. This object shall use a resource identified with the integer 0 (zero), the original administrative state shall be started, 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] = 4

And 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] = 1

We 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] = 1

We 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] = 2

And 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] = 6

To 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] = 0
3.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:

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 a DisplayString, which will be translated to an atom inside the MESH SNMP adaptation.

The measInfoLastVal attribute contains, as a DisplayString, the last measurement value the Measurement Handler has received from the specified measurement object.

The measInfoLastValTime attribute contains, as a DisplayString, the time the last measurement value was obtained by the measurement object.

The measInfoLastValInfo attribute contains, as a DisplayString, additional information about the the last measurement value the Measurement Handler has received.

The measInfoMaxTideCurr attribute contains, as a DisplayString, the current value in the maximum tidemark associated with the specified measurement object.

The measInfoMaxTidePrev attribute contains, as a DisplayString, the previous value in the maximum tidemark associated with the specified measurement object.

The measInfoMinTideCurr attribute contains, as a DisplayString, the current value in the minimum tidemark associated with the specified measurement object.

The measInfoMinTidePrev attribute contains, as a DisplayString, the previous value in the minimum tidemark associated with the specified measurement object.

The measInfoLastReset attribute contains, using the DateAndTime 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:

The threshMeasId and the threshId 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.
The threshMeasId index field is a DisplayString, which will be translated to an atom inside the MESH SNMP adaptation. The threshId 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 an upper threshold or a lower one. These two types are enumerated: 1 == upper and 2 == lower.
The default value is upper.

The threshVal1 attributes sets the threshold value that triggers the threshold. The value is given as a DisplayString, 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 a DisplayString, which is converted to an Erlang term in the MESH SNMP adaptation.
The default value is the one that threshVal1 was set to.

The threshAdminState tells whether the threshold shall be enabled or disabled. These states are enumerated: 1 == enabled and 2 == disabled. The default value is enabled.

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 state enabled. 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] = 6
3.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 corresponding measArgs field in the measTable. That is, the measArgs 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!

Copyright © 1991-98 Ericsson Telecom AB