Download 1. Use Cases

EasySNMP
Application Design Document
Team Members:
Morad Ankri
Tomer Heber
Dima Yagudaev
Mauro Rois
Academic Advisor: Yuval Elovici
Technicl Advisor: Danny Zadok
EasySNMP
Revision Control
Rev.
Detailed Description
Paragraph Reference
1.0
Original version
2.0
Change save/load
network from database to
file
Changed - 1.2.1, 1.2.2,
3.1.1.5, 3.1.1.9
Remove connect items in
the network
Removed - 1.2.10, 2.1.1.5,
4.2.1.5
Removed - 1.2.3, 1.2.4,
2.1.1.14, 2.1.1.15, 2.3,
3.1.1.6, 3.1.1.7, 3.1.1.8,
4.1.1.7, 4.2.1.14 ,4.2.1.15 ,
4.4.1.5-9
2
Approved by
Date
11-6-2008
EasySNMP
Table of Contents
1. USE CASES ______________________________________________________________ 6
1.1 SNMPAGENT ____________________________________________________________ 6
1.1.1 BUILD MIB TREE _________________________________________________________ 6
1.1.2 INITIALIZATION___________________________________________________________ 7
1.1.3 HARDWARE WAS CHANGED __________________________________________________ 8
1.1.4 HANDLE AN SNMP GET REQUEST ______________________________________________ 9
1.1.5 HANDLE AN SNMP SET REQUEST _____________________________________________ 10
1.1.6 TRAP GENERATION _______________________________________________________ 11
1.1.7 AGENT'S CONFIGURATION FILE WAS CHANGED ____________________________________ 12
1.1.8 CHECK FOR TRAPS________________________________________________________ 13
1.1.9 CHECK FOR SYSTEM CONFIGURATION CHANGES ____________________________________ 14
1.2 SITE BUILDER ____________________________________________________________ 15
1.2.1 LOAD STORED SYSTEM DIAGRAM FROM FILE ______________________________________ 15
1.2.2 SAVE NETWORK DIAGRAM TO FILE _____________________________________________ 17
1.2.3 ADD AN ITEM TO NETWORK DIAGRAM __________________________________________ 17
1.2.4 REMOVE AN ITEM FROM NETWORK DIAGRAM _____________________________________ 19
1.2.5 COPY AN ITEM FROM NETWORK DIAGRAM _______________________________________ 20
1.2.6 CUT AN ITEM FROM NETWORK DIAGRAM ________________________________________ 21
1.2.7 PASTE A COPIED ITEM TO A NETWORK DIAGRAM ___________________________________ 22
1.2.8 ADD/EDIT SYSTEM/VIRTUAL OBJECT ON A MOSCAD ITEM ____________________________ 23
1.2.9 CONFIGURE PORTS OF I/O ITEM ______________________________________________ 24
1.2.10 OPEN PROPERTIES WINDOW OF AN ITEM _______________________________________ 25
1.3 DEPLOYMENT MANAGER ____________________________________________________ 26
1.3.1 VALIDATE NETWORK DIAGRAM _______________________________________________ 26
1.3.2 BUILD CONFIGURATION FILES ________________________________________________ 27
1.3.3 DEPLOY CONFIGURATION FILES _______________________________________________ 28
2. DATA MODEL ___________________________________________________________ 30
2.1 DESCRIPTION OF DATA OBJECTS _______________________________________________ 30
2.1.1 SITEBUILDER ___________________________________________________________ 30
2.1.2 DEPLOYMENT MANAGER ___________________________________________________ 36
2.1.3 SNMPAGENT - AGENT ____________________________________________________ 37
2.1.4 SNMPAGENT - MIBBUILDER________________________________________________ 39
2.1.5 MONITOR _____________________________________________________________ 40
2.2 DATA OBJECTS RELATIONSHIP ________________________________________________ 43
2.2.1 SITEBUILDER ___________________________________________________________ 43
2.2.2 DEPLOYMENT MANAGER ___________________________________________________ 44
3
EasySNMP
2.2.3 SNMPAGENT __________________________________________________________ 44
2.3 DATABASES _____________________________________________________________ 44
3. BEHAVIORAL ANALYSIS ___________________________________________________ 45
3.1 SEQUENCE DIAGRAMS ______________________________________________________ 45
3.1.1 SITEBUILDER ___________________________________________________________ 45
3.1.2 DEPLOYMENT MANAGER ___________________________________________________ 49
3.1.3 SNMPAGENT __________________________________________________________ 51
3.3 EVENTS ________________________________________________________________ 59
3.2.1 SNMPAGENT __________________________________________________________ 59
3.3 STATES ________________________________________________________________ 59
3.3.1 SNMPAGENT __________________________________________________________ 59
4. OBJECT-ORIENTED ANALYSIS_______________________________________________ 61
4.1 CLASS DIAGRAMS _________________________________________________________ 61
4.1.1 SITEBUILDER ___________________________________________________________ 61
4.1.2 DEPLOYMENT MANAGER ___________________________________________________ 65
4.1.3 SNMPAGENT __________________________________________________________ 66
4.2 CLASS DESCRIPTION _______________________________________________________ 67
4.2.1 SITEBUILDER ___________________________________________________________ 67
4.2.2 DEPLOYMENT MANAGER ___________________________________________________ 71
4.2.3 SNMPAGENT - AGENT ____________________________________________________ 74
4.2.4 SNMPAGENT - MIBBUILDER________________________________________________ 76
4.2.5 SNMPAGENT - MONITOR __________________________________________________ 80
4.3 PACKAGES ______________________________________________________________ 84
4.3.1 SITEBUILDER ___________________________________________________________ 84
4.3.1 SNMPAGENT __________________________________________________________ 85
4.4.1 SITEBUILDER ___________________________________________________________ 86
4.4.2 DEPLOYMENT MANAGER ___________________________________________________ 88
4.4.3 SNMPAGENT – AGENT ___________________________________________________ 88
4.4.4 SNMPAGENT – MIBBUILDER _______________________________________________ 91
4.4.5 SNMPAGENT – MONITOR _________________________________________________ 93
5. SYSTEM ARCHITECTURE___________________________________________________ 95
6. USER INTERFACE DRAFT __________________________________________________ 97
6.1 SITEBUILDER ____________________________________________________________ 97
6.1.1 MAIN WINDOW _________________________________________________________ 97
4
EasySNMP
6.1.2 LOADING/STORING NETWORK DIALOG BOXES _____________________________________ 98
6.2 DEPLOYMENT MANAGER ____________________________________________________ 99
6.2.1 DEPLOYING NETWORK CONFIGURATION DIALOG BOX ________________________________ 99
7. TESTING ______________________________________________________________ 100
7.1 SITEBUILDER ___________________________________________________________ 100
7.2 DEPLOYMENT MANAGER ___________________________________________________ 100
7.3 SNMP AGENT __________________________________________________________ 100
7.3.1 FUNCTIONAL REQUIREMENTS _______________________________________________ 100
7.3.2 NON-FUNCTIONAL REQUIREMENTS ___________________________________________ 100
8. TASK LIST _____________________________________________________________ 101
8.1 SITEBUILDER ___________________________________________________________ 101
8.2 DEPLOYMENT MANAGER ___________________________________________________ 102
8.3 SNMPAGENT - AGENT ____________________________________________________ 103
8.4 SNMPAGENT - MIBBUILDER________________________________________________ 104
8.5 SNMPAGENT - MONITOR __________________________________________________ 105
9. APPENDIX _____________________________________________________________ 107
9.1 SNMP MESSAGE FORMATS _________________________________________________ 107
9.1.1 SNMP VARIABLE BINDING FORMAT __________________________________________ 107
9.1.2 SNMP VERSION 1 (SNMPV1) MESSAGE FORMAT ________________________________ 107
9.1.3 COMMUNITY-BASED SNMP VERSION 2 (SNMPV2C) MESSAGE FORMAT _________________ 111
9.2 ASN.1 _______________________________________________________________ 115
9.2.1 ASN.1 OVERVIEW ______________________________________________________ 115
9.2.2 BASIC ENCODING RULES __________________________________________________ 115
9.2.3 LISTING OF UNIVERSAL TAGS _______________________________________________ 116
5
EasySNMP
1. Use Cases
1.1 SNMPAgent
1.1.1 Build MIB Tree
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
UC1: Build MIBTree
The MIB builder will construct a MIBTree as defined in the
configuration file passed to the MOSCAD and in the
predefined meta structure of the MIB. The MIBTree will be
used by the Agent module to obtain and set values in the
system and will also be used to register traps in the Monitor
module.
The System has been turned on
Or
A new configuration file has been loaded into the MOSCAD.
1. The MIBTree has been passed to the Agent module.
2. Traps have been registered in the Monitor module.
Whenever the agent is restarted or the configuration file was
6
EasySNMP
Normal Course of
Events
Alternatives
Exceptions
Includes
changed – Rare.
1. Build the MIBTree from the Meta MIB structure (RFC
and Motorola predefined).
2. Parse the configuration file and finish the
construction of the MIBTree according to the parsed
information in the configuration file.
3. Pass the MIBTree to the Agent module.
4. Register Traps (TrapInfo objects) to the Monitor
module using/scanning the MIBTree.
2a. If the configuration file is unavailable or could not be
parsed, do nothing and skip to line no.3
1. Failed to obtain information from the Moscad.
2. Elements defined in the configuration file do not
appear in the physical layer (MOSCAD).
n/a
1.1.2 Initialization
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
UC2: Initialization
The Agent’s operation once the system has started.
n/a
A MIB file was built according to the current hardware I/O
modules and user configuration.
The agent start its operation.
7
EasySNMP
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
n/a
Whenever the system is restarted or turned on.
1. Call UC1 – Build MIB File.
2. Activate the agent.
n/a
n/a
Includes
UC1 – Build MIB File.
1.1.3 Hardware was changed
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
UC3: Hardware I/O module was added or removed
The Agent’s operations once hardware change was detected.
(E.g. an I/O module was removed from the Moscad).
The current settings of the hardware I/O modules that
attached to the MOSCAD are different from the previous
one.
A MIB file is built according to the current settings of the
MOSCAD I/O modules.
User
According to frequency of hardware module changes.
1. The user changes the hardware installed on the MOSCAD.
2. The agent detects the change and calls UC1 – Build MIB
file.
8
EasySNMP
Alternatives
Exceptions
n/a
n/a
Includes
UC1 – Build MIB File.
1.1.4 Handle an SNMP get request
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
UC4: Handle an SNMP get request
While listening to requests from the SNMP Manager, the
Agent receives a get request from the SNMP Manager.
Agent was already initialized and is listening to requests from
the SNMP Manager.
The request is a valid SNMP get request.
The agent creates the response message containing the
values of the requested objects and sends it to the manager.
SNMP manager
Very frequent.
9
EasySNMP
Normal Course of
Events
Alternatives
Exceptions
Includes
1. The SNMP manager sends an SNMP request to the agent.
2. The agent receives an SNMP request and parses it.
3. The agent creates the response message.
4. The agent fills the response with the values requested.
5. The agent sends the response to the manager.
n/a
If the agent is unable to send the response for the get
messages it drops the response and continue normally.
n/a
1.1.5 Handle an SNMP set request
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
UC5: Handle a SNMP set request
While listening to requests from the SNMP Manager, the
Agent receives a set request from the SNMP Manager.
Agent was already initialized and is listening to requests from
10
EasySNMP
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
the SNMP Manager.
The request is a valid SNMP set request.
The agent creates a response message that contains the
value of the specified object after the set operation.
SNMP manager
As needed
1. The SNMP manager sends an SNMP request to the agent.
2. The agent receives an SNMP request and parses it.
3. The agent creates the response message.
4. The agent checks the permissions of the specified object
in the message.
5. The agent sets the new value for the object according to
the message.
4. The agent puts the current value of the object in the
response message.
5. The agent sends the response to the manager.
2.a If the specified object in the message has read-only
permission, then the agent will send an error message.
If the agent is unable to send the response for the get
messages it drops the response and continue normally.
n/a
1.1.6 Trap generation
Sequence diagram:
Use case:
Name
Description
UC6: Trap generation
During a scan of the monitored objects the agent detects
that according to its configuration it has to generate a trap.
11
EasySNMP
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
The destination for the traps is defined in the agent and the
agent has detected that it has to generate a trap.
The trap was send.
SNMP manager
As needed.
1. The agent detects that it has to send a trap.
2. The agent builds a trap message and fills it with
information about what cause the trap (The information
appears in the MIB file).
3. The agent sends the trap to the SNMP manager.
n/a
If the agent is unable to send the trap it drops it and
continues to work normally.
n/a
1.1.7 Agent's configuration file was changed
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
UC7: Agent's configuration file was changed
A change is detected in the agents configuration file.
The configuration file is valid.
A MIB file is built and the agent is working by the new
configuration.
n/a
As needed.
12
EasySNMP
Normal Course of
Events
Exceptions
1. A change is detected in the agent configuration file.
2. The agent validates the file.
3. The agent calls UC1 – build MIB file.
2.a If the file is corrupted or written wrongly the agent drops
the file and continue working normally.
n/a
Includes
UC1 – build MIB file.
Alternatives
1.1.8 Check for traps
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
UC9: Check for traps
Continuously check the monitored objects and detect
anomalies.
A MIB file was created and the agent is running.
n/a
n/a
Continuously.
1. Find the next monitored object.
2. Get the value of the monitored object.
13
EasySNMP
Exceptions
3. Check if the current value is valid.
4. Go to the next monitored object.
4.a The value of the monitored object is not valid – call UC6
trap generation for this object.
n/a
Includes
UC6 – Trap generation
Alternatives
1.1.9 Check for system configuration changes
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
UC10: Check for system configuration changes
Periodically check for changes in the system configuration.
A MIB file was created and the agent is running.
n/a
n/a
Periodically.
1. Get the current system identification value.
14
EasySNMP
Events
Alternatives
Exceptions
Includes
2. Check if current system identification value didn't
changed from last time.
3. Get the current configuration file identification value.
4. Check if current configuration file identification value
didn't changed from last time.
2.a The current system identification value changed from last
time - call UC3 - hardware I/O module was added or
removed.
4.a The current configuration file identification value
changed from last time - call UC7 - agent's configuration file
was changed.
n/a
UC3 - Hardware I/O module was added or removed.
UC7 - Agent's configuration file was changed.
1.2 Site Builder
1.2.1 Load stored system diagram from file
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
UC11: Load stored network diagram from file
User loads a stored network diagram from file
n/a
A network diagram is loaded in to the system and visually
presented on the drawing grid.
User
As required.
1. The user selects "Load network" from the menu/toolbar.
2. The tool presents a “open file” dialog box
3. User selects a file to load.
4. The tool loads the selected network diagram.
5. The tool updates its data structures to include the
loaded network diagram.
6. The tool places a visual representation of the loaded
network diagram on the drawing grid.
 The user can cancel the process of loading the system
diagram in steps 3-6. In this case the use case is
terminated.
15
EasySNMP
Exceptions
4.a The tool could not open the selected file.
The tool presents an appropriate error message.
Use case continues from step 3.
5.a The selected file is not valid in terms of Site Builder's
data structure.
The tool presents an appropriate error message.
Use case continues from step 3.
7.a The selected network diagram is not valid.
The tool presents an appropriate error message.
Use case terminates here.
Includes
16
EasySNMP
1.2.2 Save network diagram to file
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
UC12: Save network diagram to file
User saves network diagram to a file.
n/a
A network diagram is stored on the selected file.
User
As required.
1. The user selects "Save network diagram" from the
menu/toolbar.
2. The tool presents a “save network” dialog box.
3. User selects a file name.
4. The tool stores the selected network diagram to the
selected file.
 The user can cancel the process of saving the network
diagram in steps 3-4. In this case the use case is
terminated.
2.a A file with the selected name already exists.
The tool presents an question of whether to overwrite
the existing file or not.
If the user selects to not overwrite the existing diagram,
the uses case continues from step 3.
4.a The tool could not write to the selected file.
The tool presents an appropriate error message.
Use case continues from step 3.
Includes
1.2.3 Add an item to network diagram
Sequence diagram:
17
EasySNMP
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC13: Add an item to network diagram
User adds an item to network diagram.
n/a
The item is part of network diagram.
User
As required.
1. The user selects the new item's type.
2. The user places the selected item on drawing grid.
3. The tool updates its data structures to include the new
item.
4. The tool adds a visual representation of the item on the
drawing grid.
n/a
n/a
n/a
18
EasySNMP
1.2.4 Remove an item from network diagram
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC14: Remove an item from network diagram
User removes an item from network diagram.
n/a
The item is not part of the network diagram.
User
As required.
1. The user selects an item out of a network diagram.
2. The user selects to remove the item.
3. The tool updates its data structures to according to
removal of the item.
4. The tool removes a visual representation of the item on
the drawing grid.
n/a
n/a
n/a
19
EasySNMP
1.2.5 Copy an item from network diagram
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC15: Copy an item from network diagram
User copies an item from network diagram.
n/a
The item is stored to the tool's clipboard.
User
As required.
1. The user selects an item out of a network diagram.
2. The user selects to copy an item.
3. The tool updates its clipboard to include the copied
item.
n/a
n/a
n/a
20
EasySNMP
1.2.6 Cut an item from network diagram
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC16: Cut an item from network diagram
User cuts an item from network diagram.
n/a
The item is not part of the network diagram.
The item is stored to the tool's clipboard.
User
As required.
1. The user selects an item out of a network diagram.
2. The user selects to cut an item.
3. The tool updates its clipboard to include the cut item.
4. The tool updates its data structures to according to
cutting of the item.
5. The tool removes a visual representation of the item on
the drawing grid.
n/a
n/a
n/a
21
EasySNMP
1.2.7 Paste a copied item to a network diagram
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC17: Paste an copied item to a network diagram
User pastes a copied item to a network diagram.
n/a
The item is part of network diagram.
User
As required.
1. The user selects to paste an item.
2. The tool updates its data structures to include the
newly pasted item.
3. The tool adds a visual representation of the item on the
drawing grid.
2.a There is no stored item in the tool's clipboard.
Use case terminates here.
n/a
n/a
22
EasySNMP
1.2.8 Add/Edit system/virtual object on a MOSCAD item
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
UC19: Add/Edit system/virtual object on a MOSCAD item
User adds/edits user-defined attribute on a MOSCAD/ACE
item.
n/a
n/a
User
As required.
1. UC21 on MOSCAD/ACE item.
2. The user selects the "System Objects"/"Virtual Objects"
tab.
3. The user asks to add/edit a system/virtual object
4. The user fills all the necessary details of the
system/virtual object.
5. The user confirms his changes.
6. The tool updates its data structures according to the
user's changes.


Exceptions
Includes
The user can cancel the process of adding/editing
system/virtual object in steps 3 and 4. In this case the
use case is terminated.
The user can add/edit another system/virtual object in
steps 4 and 5. In this case the use case loops back to
step 3.
n/a
UC21
23
EasySNMP
1.2.9 Configure ports of I/O item
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC20: Configure ports of I/O item
User configures ports of an I/O item.
n/a
n/a
User
As required.
1. UC21 on I/O item.
2. The user fills some or all of the necessary details of the
I/O ports.
3. The user confirms his changes.
4. The tool updates its data structures according to the
user's changes.
 The user can cancel the process of configuring I/O
item's ports in steps 2 and 3. In this case the use case is
terminated.
n/a
UC21
24
EasySNMP
1.2.10 Open properties window of an item
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC21: Open properties window of an item
User opens properties window of a selected tem.
n/a
n/a
User
As required.
1. The user selects an item.
2. The user selects to open the item's properties window.
3. The tool opens a dialog with the selected item's
properties.
n/a
n/a
n/a
25
EasySNMP
1.3 Deployment Manager
1.3.1 Validate network diagram
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
UC22: Validate network diagram
The user whishes to validate the overall structure described
in currently open (in Site Builder) network diagram
There is a document of network diagram currently open in
Site Builder.
n/a
User
As required.
1. User selects "Validate" from the menu/toolbar.
2. The tool validates the network diagram.
3. The tool notifies the user that the network is valid.
3.a The network diagram found invalid.
The tool presents an appropriate error message.
n/a
n/a
26
EasySNMP
1.3.2 Build configuration files
Sequence diagram:
Use case:
Name
Description
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
UC23: Build configuration files
The user whishes to validate the overall structure described
in currently open (in Site Builder) network diagram and build
configuration files for each MOSCAD in the diagram.
n/a
n/a
User
As required.
1. User selects "Build" from the menu/toolbar.
2. UC22.
3. The tool creates configuration files for each MOSCAD.
4. The tool stores the created files to a predefined
location.
5. The tool notifies the user that configuration files were
27
EasySNMP
Alternatives
Exceptions
Includes
created successfully.
3.a UC22 ended abnormally. The system diagram found
invalid.
The tool presents an appropriate error message.
Use case terminates here.
4.a The tool could not store configuration files to a
predefined location.
The tool presents an appropriate error message.
Use case terminates here.
UC22
1.3.3 Deploy configuration files
Sequence diagram:
Use case:
Name
Description
UC24: Deploy configuration files
The user whishes to validate the overall structure described
in currently open (in Site Builder) network diagram, build
configuration files for each MOSCAD in the diagram and send
28
EasySNMP
Pre-Conditions
Post-Conditions
Actors
Frequency of Use
Normal Course of
Events
Alternatives
Exceptions
Includes
the built configuration files to each MOSCAD.
n/a
n/a
User, MOSCAD
As required.
1. User selects "Deploy" from the menu/toolbar.
2. UC22.
3. UC23.
4. The user selects which of the MOSCAD devices in the
diagram are to receive their configuration files.
5. The tool uploads configuration files (stored in
predefined location) to each MOSCAD. Each MOSCAD
receives his configuration files.
6. The tool notifies the user that configuration files were
sent successfully to the selected MOSCAD.
3.a UC22 ended abnormally. The network diagram found
invalid.
The tool presents an appropriate error message.
Use case terminates here.
4.a UC23 ended abnormally. Configuration files were not
created.
The tool presents an appropriate error message.
Use case terminates here.
6.a The tool could not send configuration files to some or
all MOSCAD devices.
The tool presents an appropriate error message.
UC22
UC23
29
EasySNMP
2. Data Model
2.1 Description of Data Objects
2.1.1 SiteBuilder
2.1.1.1 Network
Class Description:
This class represents a whole network diagram, the root object of the network. This
class will hold the areas and sites.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the Network.
 m_version
Type: string
Description: Represents the version tag of the Network.
 m_creationDate
Type: DateTime
Description: Represents the date & time the network was created, the first time it was
stored onto a file.
 m_modificationDate
Type: DateTime
Description: Represents the date & time the network was modified, the last time it
was stored onto a file.
 m_areas
Type: List<Area>
Description: Represents the list of Areas the Network aggregates.
 m_sites
Type: List<Site>
Description: Represents the list of Sites the Network aggregates.
2.1.1.2 Area
Class Description:
This class represents an area, a logical group which holds several sites.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the Area.
30
EasySNMP
 m_sites
Type: List<Site>
Description: Represents the list of Sites the Area aggregates.
2.1.1.3 Site
Class Description:
This class represents a site. A site is an ACE3600 device and all IO modules attached to
it.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the Site.
 m_ioModules
Type: List<IOModule>
Description: Represents the list of IOModule objects the Site aggregates.
 m_hostResources
Type: List<MonitoredObject>
Description: Represents the list of host resources the Site aggregates.
 m_virtualObjects
Type: List< MonitoredObject >
Description: Represents the list of virtual objects the Site aggregates.
 m_portsGroups
Type: List<PortsGroup>
Description: Represents the list of PortsGroup objects which contains ports of the
Site's IO modules.
2.1.1.4 MonitoredObject
Class Description:
This class represents a monitored object.
A monitored object can be on of the two
 Host Resource, a, known in advance, monitored object that exists in every site
 Virtual Object, an, unknown in advance, explicitly defined by users for a specific
site, monitored object.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the MonitoredObject.
 m_dataType
Type: string
Description: Represents the data-type of the MonitoredObject.
31
EasySNMP
 m_minValue
Type: float
Description: Represents the minimal valid value.
 m_maxValue
Type: float
Description: Represents the maximal valid value.
 m_trapOnInvalidRange
Type: bool
Description: Indicates whether traps will be sent when the value exceeds the valid
range (less than m_minValue or greater than m_maxValue).
 m_deltaTime
Type: int
Description: Represents the time interval for checking valid value differences (in
milliseconds) .
 m_validValueDifference
Type: float
Description: Represents the maximal valid value difference (in m_deltaTime time).
 m_trapOnAnomalousValueChange
Type: bool
Description: Indicates whether traps will be sent when the value change in
m_deltaTime is greater than m_validValueDifference).
 m_samplingTime
Type: uint
Description: Represents the sampling time of the monitored object (in milliseconds).
2.1.1.5 IOModule
Class Description:
This abstract class represents an IO device.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the IOModule.
 m_type
Type: string
Description: Represents the type string of the IOModule.
 m_portsCount
Type: uint
Description: Represents the number of ports the IOModule holds.
2.1.1.6 DigitalModule : IOModule
Class Description:
32
EasySNMP
This class represents an IO module of only digital ports. A concrete class (derives from
IOModule).
Main Attributes:
 m_type
Type: DigitalModuleType (Input / Output / Mixed)
Description: Represents the type of the DigitalModule (all Input, all Output or Mixed).
 m_ports
Type: List<DigitalPort>
Description: Represents the list of DigitalPort objects the DigitalModule aggregates.
2.1.1.7 AnalogInputModule : IOModule
Class Description:
This class represents an IO module of only analog input ports. A concrete class
(derives from IOModule).
Main Attributes:
 m_ports
Type: List<AnalogPort>
Description: Represents the list of AnaloglPort objects the AnalogInputModule
aggregates.
2.1.1.8 DigitalAnalogModule : IOModule
Class Description:
This class represents an IO module of mixed ports (digital and analog). A concrete
class (derives from IOModule).
Main Attributes:
 m_ports
Type: List<IOPort>
Description: Represents the list of IOPort objects the DigitalAnalogOutput aggregates.
2.1.1.9 IOPort
Class Description:
This abstract class represents an IO port.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the IOPort.
33
EasySNMP
2.1.1.10 DigitalPort : IOPort
Class Description:
This class represents a digital IO port. A concrete class (derives from IOPort).
Main Attributes:
 m_direction
Type: DigitalPortDirection (Input / Output)
Description: Represents the direction of the DigitalPort (Input or Output).
 m_setText
Type: string
Description: Represents the text assigned to the value "1" of the port.
 m_clearText
Type: string
Description: Represents the text assigned to the value "0" of the port.
 m_trapsOn
Type: TrapsOn (None / OnSet / OnClear)
Description: Represents the type of the traps (None, OnSet or OnClear).
 m_trapsSeverity
Type: TrapsSeverity (Informative / Attentive / Critical)
Description: Represents the severity of the traps (when m_trapsOn is OnSet or
OnClear).
 m_bounceTime
Type: uint
Description: Represents the bouncing time of the port (in milliseconds), the time
period for stability indication.
 m_samplingTime
Type: uint
Description: Represents the sampling time of the port (in milliseconds).
2.1.1.11 AnalogPort : IOPort
Class Description:
This class represents an analog IO port. A concrete class (derives from IOPort).
Main Attributes:
 m_minValue
Type: int
Description: Represents the minimal valid value.
 m_maxValue
Type: int
Description: Represents the maximal valid value.
 m_trapsOnInvalidRange
Type: bool
34
EasySNMP






Description: Indicates whether traps will be sent when the value exceeds the valid
range (less than m_minValue or greater than m_maxValue).
m_invalidRangeTrapsSeverity
Type: TrapsSeverity (Informative / Attentive / Critical)
Description: Represents the severity of the "invalid ranges" traps (when
m_trapsOnInvalidRange is set).
m_deltaTime
Type: int
Description: Represents the time interval for checking valid value differences (in
milliseconds) .
m_validValueDifference
Type: float
Description: Represents the maximal valid value difference (in m_deltaTime time).
m_trapsOnAnomalousValueChange
Type: bool
Description: Indicates whether traps will be sent when the value change in
m_deltaTime is greater than m_validValueDifference).
m_anomalousValueChangeTrapsSeverity
Type: TrapsSeverity (Informative / Attentive / Critical)
Description: Represents the severity of the "anomalous vale change" traps (when
m_trapsOnAnomalousValueChange is set).
m_samplingTime
Type: uint
Description: Represents the sampling time of the port (in milliseconds).
2.1.1.12 PortsGroup
Class Description:
This class represents a group of ports, a logical group which enables users to logically
differentiate ports.
Main Attributes:
 m_name
Type: string
Description: Represents the name of the PortsGroup.
 m_ports
Type: List<IOPort>
Description: Represents the list of IOPort objects.
2.1.1.13 NetworkInfo
Class Description:
This class is responsible to hold the complete data of a Network exactly as it stored in
the file. This class is used for efficiently loading a network from a file.
35
EasySNMP
Main Attributes:
 m_networkData
Type: DataSet (.NET class).
Description: this object is holding all the network information that was stored in the
file.
2.1.2 Deployment Manager
2.1.2.1 DeploymentController
Class Description:
This class is the main controller of the deployment mananger module, it responsible
for controlling the flow of the deployment process.
Main Attributes:
 m_validator
Type: ConfigValidator
Description: A class that responsible for validating a specified network.
 m_builder
Type: ConfigBuilder
Description: A class that responsible for building the sites configuration files from a
specified network.
 m_downloader
Type: ConfigDownloader
Description: A class that responsible for downloading the configuration files to each
site on a specified network.
2.1.2.2 ConfigValidator
Class Description:
This class is responsible for validating a specified network.
2.1.2.3 ConfigBuilder
Class Description:
This class is responsible for building the sites configuration files from a specified
network.
2.1.2.4 ConfigDownloader
Class Description:
This class is responsible for downloading the configuration files to each site on a
specified network.
36
EasySNMP
2.1.3 SNMPAgent - Agent
2.1.3.1 AgentController
Class Description:
Controls the work flow of the agent. It receives packets and use other classes (will be
described further on) to decode, create the response, fill the response, encode it and
send it.
It is also responsible for sending traps generated by the Monitor to all the NMSs
registered.
Main Attributes:
 m_trapDestinationList
Type: List<TarpDestinationItem>
Description: Represents the list of TrapDestinationItem objects.
2.1.3.2 SNMPMessage
Class Description:
A data structure for holding SNMP messages (all the message types).
Main Attributes:
 m_version
Type: SNMPVersion (SNMPv1 1 / SNMPv2c)
Description: Represents the version of the SNMP message.
 m_community
Type: string
Description: Represents the community string.
 m_pduType
Type: Predefined enum type (see SNMPv1 Common PDU Format)
Description: Represents the PDU type inside the message.
 m_requestID
Type: int
Description: See SNMPv1 Common PDU Format.
 m_errorStatus
Type: Predefined enum type (see SNMPv1 Common PDU Format)
Description: See SNMPv1 Common PDU Format.
 m_errorIndex
Type: int
Description: See SNMPv1 Common PDU Format
 m_varBindList
Type: Bind container
Description: See SNMPv1 Common PDU Format.
37
EasySNMP
 m_nonRepeaters
Type: int
Description: Used only for get-bulk message (see SNMPv2 GetBulkRequest-PDU
Format).
 m_maxRepetitions
Type: int
Description: Used only for get-bulk message (see SNMPv2 GetBulkRequest-PDU
Format)..
 m_enterprise
Type: Sequence of int
Description: Used only for trap of SNMPv1 (see SNMPv1 Trap-PDU Format).
 m_agentAddr
Type: NetworkAddress
Description: Used only for trap of SNMPv1 (see SNMPv1 Trap-PDU Format).
 m_genericTrap
Type: Predefined enum type (see SNMPv1 Trap-PDU Format)
Description: Used only for trap of SNMPv1 (see SNMPv1 Trap-PDU Format).
 m_trapDestinationList
Type: int
Description: Used only for trap of SNMPv1 (see SNMPv1 Trap-PDU Format).
 m_trapDestinationList
Type: TimeTicks
Description: Used only for trap of SNMPv1 (see SNMPv1 Trap-PDU Format).
2.1.3.3 Bind
Class Description:
A bind inside an SNMP message.
Main Attributes:
 m_OID
Type: Sequence of int
Description: Represents the OID of the Bind.
 m_type
Type: enum of the types defined in ASN.1 (see Listing of Universal Tags).
Description: Represents the type of the OID.
 m_length
Type: Predefined enum type (see Listing of Universal Tags)
Description: Represents the size of the value.
 m_value
Type: void *
Description: Represents the value of the OID.
38
EasySNMP
2.1.4 SNMPAgent - MIBBuilder
2.1.4.1 MIBBuilder
Class Description:
This class builds a MIBTree according to the static MIB file and according to the
parsed config file received from the deployment manager. (The file is also parsed by
the MIB builder). After the MIBTree is constructed it passes it to the Agent module,
and also passes relevant TrapInfo to the Monitor module based on the constructed
MIBTree.
Main Attributes:
 m_MIBTree
Type: MIBObject
Description: The MIBTree constructed according to the MIB file and the parsed config
file (MIB describes the Meta model, and the config file holds values to be placed in the
MIBTree).
2.1.4.2 MIBObject (abstract)
Class Description:
Every element in the MIBTree extends the MIBObject class. Each MIBObject holds
information regarding an element in the system (Managed Objects, Network
Elements, Virtual Managed Object, CPU speed and more…).
Main Attributes:
 m_Info
Type: void *
Description: Additional information needed by the internal methods of the MIBObject
(e.g. physical location of an I/O device in the MOSCAD…).
2.1.4.3 MIBNode
Class Description:
This class represents a node in the MIBTree. Each node may have 0 or more "sons".
The keys can be of many types and values, therefore each MIBNode holds a unique
dictionary that translates a key to an index. The returned index represents the
location of the "son" who owns that key.
Main Attributes:
 m_Dictionary
Type: Dictionary
Description: Holds pairs of <string,int>. The first element is a string representation of
a key to a "son" in the tree. The other element is its index value in the MIBTree.
39
EasySNMP
 m_Sons
Type: MIBObject[]
Description: Points to all the sons of this node.
2.1.4.4 MIBTable
Class Description:
This class represents a leaf in the MIBTree. The leaf's value is a table (multiple values).
The columns of the table are predefined in the MIB file. Rows can be added and values
can be changed in a table (If defined so in the MIB file).
Main Attributes:
 m_Table
Type: Table
Description: A table that holds values (For example Managed Objects table).
2.1.4.5 MIBScalar
Class Description:
This class represents a leaf in the MIBTree. The leaf's value is a scalar (single value).
2.1.5 Monitor
2.1.5.1 MonitorController
Class Description:
This class is the main controller of monitoring module, it responsible to check for traps
and report about them to the agent.
Main Attributes:
 m_trapsQueue
Type: List<TrapInfo>
Description: list of SNMP-elements that are need to be monitored for traps in the
system.
 m_prevSystemID
Type: int
Description: a unique number that identifies the last time that the system hardware
was changed.
 m_prevConfigurationID
Type: int
Description: a unique number that identifies the last time that the agent’s
configuration file was changed.
40
EasySNMP
2.1.5.2 TrapInfo
Class Description:
This is an abstract class that represents a ScalarMIBObject that is needed to be
monitored and the conditions for sending traps for this monitored object.
Main Attributes:
 m_oid
Type: string
Description: Represents the OID of this trap in the MIB file.
 m_monitoredMIBObject
Type: ScalarMIBObject
Description: contains a reference to the monitored ScalarMIBObject that this TrapInfo
represents.
 m_associatedMIBObjects
Type: List<ScalarMIBObject>
Description: contains the associated MIB objects of this trap according to the MIB file.
 m_samplingTime
Type: uint
Description: Represents the sampling time for this value (in milliseconds).
 m_lastSamplingTime
Type: uint
Description: Represents the last sampling time of this value (in milliseconds).
2.1.5.3 BooleanTrapInfo
Class Description:
This class extends the TrapInfo class and represents a ScalarMIBObject that has
Boolean value (digital value).
Main Attributes:
 m_trapOn
Type: boolean
Description: Determine on which kind of change the trap is occur (when the value is
changed to false or when it is changed to true).
 m_bounceTime
Type: uint
Description: Represents the bouncing time for this value (in milliseconds), the time
period for stability indication.
 m_previousSamples
Type: Queue<bool>
Description: Represents the previous samples of this SNMP-element within the
m_samplingTime interval.
41
EasySNMP
2.1.5.4 NumericTrapInfo
Class Description:
This is an abstract class that extends the TrapInfo class. This class represents a
ScalarMIBObject that has numeric value.
Main Attributes:
 m_trapOnInvalidRange
Type: bool
Description: Indicates whether traps will be sent when the value exceeds the valid
range (less than m_minValue or greater than m_maxValue).
 m_deltaTime
Type: int
Description: Represents the time interval for checking valid value difference (in
milliseconds).
 m_validValueDifference
Type: float
Description: Represents the maximal valid value difference (in m_deltaTime time).
 m_trapOnAnomalousValueChange
Type: bool
Description: Indicates whether traps will be sent when the value change in
m_deltaTime is greater than m_validValueDifference).
2.1.5.5 IntegerTrapInfo
Class Description:
This class extends the NumericTrapInfo class and represents a ScalarMIBObject that
has integer value.
Main Attributes:
 m_minValue
Type: int
Description: Represents the minimal valid value.
 m_maxValue
Type: int
Description: Represents the maximal valid value.
 m_previousSamples
Type: Queue<int>
Description: Represents the previous samples of this SNMP-element within the
m_samplingTime interval.
2.1.5.6 FloatTrapInfo
Class Description:
42
EasySNMP
This class extends the NumericTrapInfo class and represents a ScalarMIBObject that
has float value.
Main Attributes:
 m_minValue
Type: float
Description: Represents the minimal valid value.
 m_maxValue
Type: float
Description: Represents the maximal valid value.
 m_previousSamples
Type: Queue< float>
Description: Represents the previous samples of this SNMP-element within the
m_samplingTime interval.
2.2 Data Objects Relationship
2.2.1 SiteBuilder
43
EasySNMP
2.2.2 Deployment Manager
2.2.3 SNMPAgent
2.3 Databases
n/a
44
EasySNMP
3. Behavioral Analysis
3.1 Sequence Diagrams
3.1.1 SiteBuilder
3.1.1.1 Add NEW Area to Network
The same sequence of events applies to:
 Adding NEW Site to Network
 Adding NEW Site to Area
 Adding NEW IOModule to Site
 Adding NEW VirtualObject to Site
 Adding NEW PortsGroup to Site
45
EasySNMP
3.1.1.2 Add Existing Area to Network
The same sequence of events applies to:
 Adding EXISTING Site to Network
 Adding EXISTING Site to Area
 Adding EXISTING IOModule to Site
 Adding EXISTING VirtualObject to Site
 Adding EXISTING PortsGroup to Site
46
EasySNMP
3.1.1.3 Add IOPort to PortsGroup
3.1.1.4 Remove Area from Network
The same sequence of events applies to:
 Removing Site from Network
47
EasySNMP





Removing Site from Area
Removing IOModule from Site
Removing VirtualObject from Site
Removing PortsGroup from Site
Removing IOPort from PortsGroup
48
EasySNMP
3.1.2 Deployment Manager
3.1.2.1 Validate Network
49
EasySNMP
3.1.2.2 Build Configuration Files
50
EasySNMP
3.1.2.3 Download configuration files
3.1.3 SNMPAgent
3.1.3.1 Agent Initialization
51
EasySNMP
3.1.3.2 Build MIB Tree
52
EasySNMP
3.1.3.3 Start MonitorController
53
EasySNMP
3.1.3.4 Handle SNMP request
54
EasySNMP
3.1.3.5 Check for Traps
55
EasySNMP
3.1.3.6 Send trap message
56
EasySNMP
3.1.3.7 Check for system configuration changes
57
EasySNMP
3.1.3.8 Hardware or configuration was changed
58
EasySNMP
3.3 Events
3.2.1 SNMPAgent
 At startup the MIBBuilder builds the MIB tree, and then it starts the AgentController
and MonitorController. When both the AgentController and MonitorController are
running the MOSCAD is ready to process SNMP requests and sends traps to the NMSs.
 At shutdown all the modules receive a signal to stop. Each of the modules frees the
memory that is under its responsibility and stop running.
 When an I/O module is add or removed then the Agent will act as if a shutdown event
following a startup event occurred.
 When a new configuration file is downloaded to the MOSCAD, then the Agent will act as
if a shutdown event following a startup event occurred.
 When the Monitor detects an trap that has to be reported to the NMSs:
 The Monitor passes the trap data to the AgentController using the sendTrap method.
The AgentController builds the SNMP trap (SNMPMessage) and encodes it to using the
SNMPServices. The SNMPServices encodes the message with its SNMPEncoder.
The AgentController sends the encoded trap using the ComunicationInterface to all the
NMSs registered .
 An NMS sends an SNMP command to the Agent.
The Communication Interface receives the UDP packet, extracts the data part and
passes it to the AgentController.
The AgentController decodes it using the SNMPServices that return an SNMP message
(SNMPMessage). The SNMPServices decodes the packet with its SNMPDecoder.
The AgentController build a SNMP response message (SNMPMessage).
The AgentController apply the command on each OID in the command using its
MIBObject and puts the return value in the response.
When the response is ready the AgentController encodes it to using the SNMPServices.
The SNMPServices encodes the message with its SNMPEncoder.
The AgentController sends the encoded response using the ComunicationInterface to
the NMS.
3.3 States
3.3.1 SNMPAgent
The SNMPAgent has 3 main states:
59
EasySNMP
 Build MIB Tree.
 Wait and response to SNMP requests.
 Check for traps.
The states and the triggers to move between the states are described in the flowing state
diagram:
60
EasySNMP
4. Object-Oriented Analysis
4.1 Class Diagrams
4.1.1 SiteBuilder
4.1.1.1 Network, Area, Site
61
EasySNMP
4.1.1.2 MonitoredObject, InterSiteConnection, PortsGroup
4.1.1.3 IOModule
62
EasySNMP
4.1.1.4 IOPort
4.1.1.5 IOModule-IOPort Relations
63
EasySNMP
4.1.1.6 Site's, PortsGroup's Relations
4.1.1.7 SiteBuilder – The whole diagram
64
EasySNMP
4.1.2 Deployment Manager
65
EasySNMP
4.1.3 SNMPAgent
66
EasySNMP
4.2 Class Description
4.2.1 SiteBuilder
4.2.1.1 Network
Description:
A data structure, represent the network (system) object. A network object contains
area & site objects.
Main Methods:
4.2.1.1.1 AddArea
Adds the supplied area to the network's areas collection.
Parameters:
 area : Area [in] – The area to add to the network's areas collection.
Invariants:
 area is part of only one areas collection.
Pre-Conditions:
 area is not null.
Post-Conditions:
 The area is part of the network's areas collection.
4.2.1.1.2 RemoveArea
Removes the supplied area from the network's areas collection.
Parameters:
 area : Area [in] – The area to remove from the network's areas collection.
Post-Conditions:
 The area is not part of the network's areas collection.
4.2.1.1.3 RemoveAllAreas
Clears the network's areas collection.
Post-Conditions:
 The network's areas collection is empty.
4.2.1.1.4 AddSite
Adds the supplied site to the network's sites collection.
The description is similar to the AddArea method.
4.2.1.1.5 RemoveSite
Removes the supplied site from the network's sites collection.
The description is similar to the RemoveArea method.
4.2.1.1.6 RemoveAllSites
Clears the network's sites collection.
67
EasySNMP
The description is similar to the RemoveAllAreas method.
4.2.1.1.7 Touch
Update the modification date & time of the network to NOW.
Post-Conditions:
 The networks modification date & time is updated to NOW.
4.2.1.2 Area
Description:
A data structure, represent the area object. An area object contains site objects.
Main Methods:
4.2.1.3.1 AddSite
Adds the supplied site to the area's sites collection.
The description is similar to the Network.AddArea method.
4.2.1.2.2 RemoveSite
Removes the supplied site from the area's sites collection.
The description is similar to the Network.RemoveArea method.
4.2.1.2.3 RemoveAllSites
Clears the area's sites collection.
The description is similar to the Network.RemoveAllAreas method.
4.2.1.3 Site
Description:
A data structure, represent the site object. A site object contains IO module objects.
Main Methods:
4.2.1.3.1 AddIOModule
Adds the supplied IO module to the site's IO modules collection.
The description is similar to the Network.AddArea method.
4.2.1.2.2 RemoveIOModule
Removes the supplied IO module from the site's IO modules collection.
The description is similar to the Network.RemoveArea method.
4.2.1.2.3 RemoveAllIOModules
Clears the site's IO modules collection.
The description is similar to the Network.RemoveAllAreas method.
68
EasySNMP
4.2.1.3.4 AddVirtualObject
Adds the supplied virtual object to the site's virtual objects collection.
The description is similar to the Network.AddArea method.
4.2.1.2.5 RemoveVirtualObject
Removes the supplied virtual object from the site's virtual objects collection.
The description is similar to the Network.RemoveArea method.
4.2.1.2.6 RemoveAllVirtualObjects
Clears the site's virtual objects collection.
The description is similar to the Network.RemoveAllAreas method.
4.2.1.3.7 AddHostResource
Adds the supplied host resource to the site's host resources collection.
The description is similar to the Network.AddArea method.
4.2.1.3.8 AddPortsGroup
Adds the supplied ports group to the site's ports groups collection.
The description is similar to the Network.AddArea method.
4.2.1.3.9 RemovePortsGroup
Removes the supplied ports group from the site's ports groups collection.
The description is similar to the Network.RemoveArea method.
4.2.1.3.10 RemoveAllPortsGroups
Clears the site's ports groups collection.
The description is similar to the Network.RemoveAllAreas method.
4.2.1.4 PortsGroup
Description:
A data structure, represent the ports group object. A ports group object contains IO
port objects.
Main Methods:
4.2.1.4.1 AddIOPort
Adds the supplied IO ports to the ports group's IO ports collection.
Parameters:
 ioPort : IOPort [in] – The IO port to add to the ports group's IO ports collection.
Pre-Conditions:
 ioPort is not null.
Post-Conditions:
 The IO port is part of the ports group's IO ports collection.
69
EasySNMP
4.2.1.4.2 RemoveIOPort
Removes the supplied IO port from the ports group's IO ports collection.
The description is similar to the Network.RemoveArea method.
4.2.1.4.3 RemoveAllIOPorts
Clears the ports group's IO ports collection.
The description is similar to the Network.RemoveAllAreas method.
4.2.1.5 MonitoredObject
Description:
A data structure, represent the monitored (by a site) object. A monitored object can
be a virtual object (defined by users) or a host resource, a predefined monitored
object.
4.2.1.6 IOModule
Description:
A data structure, represent the IO module object.
Abstract, concrete derivers: DigitalModule, AnalogInputModule, DigitalAnalogModule.
4.2.1.7 DigitalModule
Description:
A data structure, represent the digital IO module object.
Concrete, derives from abstract IOModule.
4.2.1.8 AnalogInputModule
Description:
A data structure, represent the analog input IO module object.
Concrete, derives from abstract IOModule.
4.2.1.9 DigitalAnalogModule
Description:
A data structure, represent the digital/analog IO module object.
Concrete, derives from abstract IOModule.
70
EasySNMP
4.2.1.10 IOPort
Description:
A data structure, represent the IO module object.
Abstract, concrete derivers: DigitalPort, AnalogPort.
4.2.1.11 DigitalPort
Description:
A data structure, represent the digital IO port object.
Concrete, derives from abstract IOPort.
4.2.1.12 AnalogPort
Description:
A data structure, represent the analog IO port object.
Concrete, derives from abstract IOPort.
4.2.1.13 NetworkData
Description:
This class is responsible to hold the complete data of a Network exactly as it stored in
the file. This class is used for efficiently loading a network from a file.
Main Methods:
This class contains only get methods. These methods are used for retrieving the
network data.
4.2.2 Deployment Manager
4.2.2.1 DeploymentController
Description:
This class is the main controller of the deployment manager module, it responsible for
controlling the flow of the deployment process.
Main Methods:
4.2.2.1.1 Validate
Responsible for the control flow of the network validation.
Parameters:
 network: Network [in] – the network that is needed to be validated.
Returen value:
71
EasySNMP
 boolean – indicate whether the network is valid or not.
Pre-Conditions:
 The network parameter is not null.
4.2.2.1.2 buildConfigFiles
Responsible for the control flow of building the configuration files of the specified
network.
Parameters:
 network: Network [in] – the network that the configuration files are needed to
be build for.
Returen value:
 boolean – indicate whether the operation succeed or not.
Pre-Conditions:
 The network parameter is not null.
Post-Conditions:
 If the operation was successful then a configuration file was built for each site in
the specified network.
4.2.2.1.3 downloadConfigFiles
Responsible for the control flow of building the configuration files of the specified
network.
Parameters:
 network: Network [in] – the network that the configuration files are needed to
be build for.
 selectedSites: List<Site> [in] – the sites that the configuration files will be
downloaded to.
Returen value:
 boolean – indicate whether the operation succeed or not.
Pre-Conditions:
 The network parameter is not null.
Post-Conditions:
 If the operation was successful then the configuration files were downloaded to
each site in the specified list.
4.2.2.2 ConfigValidator
Description:
This class is responsible for validating a specified network.
Main Methods:
4.2.2.2.1 Validate
Validate the specified network.
Parameters:
72
EasySNMP
 network: Network [in] – the network that is needed to be validated.
Returen value:
 boolean – indicate whether the network is valid or not.
Pre-Conditions:
 The network parameter is not null.
4.2.2.2.2 validateSite
Validate the specified site.
Parameters:
 siet: Site [in] – the site that is needed to be validated.
Returen value:
 boolean – indicate whether the site is valid or not.
Pre-Conditions:
 The site parameter is not null.
4.2.2.3 ConfigBuilder
Description:
This class is responsible for building the sites configuration files from a specified
network.
Main Methods:
4.2.2.3.1 buildConfigForSite
Build configuration file for the specified site.
Parameters:
 site: Site [in] – the site that the configuration files are needed to build for.
Returen value:
 string – the content of the configuration file.
Pre-Conditions:
 The site parameter is not null.
4.2.2.4 ConfigDownloader
Description:
This class is responsible for downloading the configuration files to each site on a
specified network.
Main Methods:
4.2.2.4.1 downloadConfigFile
Download the specified configuration file to the specified site.
Parameters:
 site: Site [in] – the site that the configuration files is needed to downloaded to.
 siteConfig: File [in] – the configuration file for the site.
Returen value:
73
EasySNMP
 boolean – indicate whether the download was successful or not.
Pre-Conditions:
 The site parameter is not null.
 The siteConfig file existing.
4.2.3 SNMPAgent - Agent
4.2.3.1 AgentController
Description:
Controls the work flow of the agent. It receives packets and use other classes (will be
described further on) to decode, create the response, fill the response, encode it and
send it.
It is also responsible for sending traps generated by the Monitor to all the NMSs
registered.
Main Methods:
4.2.3.1.1 start
When applied the agent will start responding to requests and sending traps.
Parameters:
 mibObject : MIBObject [in] – The MIB object based on which the agent will be
run.
4.2.3.1.2 stop
When applied the agent will stop responding to requests and sending traps.
4.2.3.1.3 messageReceive
Used by the CommunicationInterface to pass an incoming message to the
AgentController for processing.
Parameters:
 packet : Packet [in] – The packet to process.
4.2.3.1.4 sendTrap
Used by the Monitor when it generates a trap. The method will send the trap to all
the NMSs registered.
Parameters:
 trapData : TrapData [in] – The trap data to send.
4.2.3.2 CommunicationInterface
Description:
74
EasySNMP
The Communication Interface uses MOSCADs API to listen to port 161 (UDP) for SNMP
messages and to send the responses and traps to the NMSs.
Main Methods:
4.2.3.2.1 sendUDPPacket
Sends packet to destination using the UDP protocol.
Parameters:
 packet : Packet [in] – The packet to send.
 destination : NetLocation [in] – The address & port of the remote peer.
4.2.3.2.2 receiveUDPPacket
Listen to a UDP port and pass the packet received to the AgentController.
Parameters:
 uint : port [in] – The port to listen to.
4.2.3.3 SNMPServices
Description:
Provides encoding and decoding services.
Main Methods:
4.2.3.3.1 encodeMsg
Transforms SNMP messages ('C' object) to raw data according to the ASN.1 standard
and SNMP protocol.
Parameters:
 msg : SNMPMessage [in] – The SNMP message to encode.
4.2.3.3.2 decodeMsg
Transform SNMP raw data to SNMP message ('C' object).
It does the opposite of the SNMP Encoder.
Parameters:
 Packet : packet [in] – The packet to decode.
4.2.3.4 SNMPEncoder
Description:
Provides encoding services.
Main Methods:
4.2.3.4.1 encodeMsg
75
EasySNMP
Transforms SNMP messages ('C' object) to raw data according to the ASN.1 standard
and SNMP protocol.
Parameters:
 msg : SNMPMessage [in] – The SNMP message to encode.
4.2.3.5 SNMPDecoder
Description:
Provides decoding services.
Main Methods:
4.2.3.5.1 decodeMsg
Transform SNMP raw data to SNMP message ('C' object).
It does the opposite of the SNMP Encoder.
Parameters:
 Packet : packet [in] – The packet to decode.
4.2.4 SNMPAgent - MIBBuilder
4.2.4.1 MIBBuilder
Description:
A controller class. Constructs a MIBTree and passes it to the Agent module. Creates
TrapInfo’s objects (using the MIBTree) and passes them to the Monitor module.
Main Methods:
4.2.4.1.1 init
Creates the MIBTree and passes relevant information to the Monitor and Agent
modules.
Pre-Conditions:
 The MOSCAD was just turned on (Initialization)
or
The configuration file was changed.
Post-Conditions:
 A MIBTree was created and the Agent and Monitor modules received their
required information.
4.2.4.2 MIBObject
Description:
76
EasySNMP
The basic element in the MIBTree (every node or leaf in the MIBTree “is a”
MIBObject).
Main Methods:
4.2.4.2.1 get
Used to obtain a value of a specific element with the given OID.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The OID element is readable.
Post-Conditions:
 A value is returned.
4.2.4.2.2 set
Used to set a new value for a specific element with the given OID.
Parameters:
 oid : string [in] – A string representation of the OID.
 newValue : int [in] – The new value to change to.
Pre-Conditions:
 The OID element is writable.
Post-Conditions:
 A value is changed.
4.2.4.2.3 getNext
Used to obtain a value of the “successor” element with the given OID.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The successor OID element is readable.
Post-Conditions:
 A value is returned.
4.2.4.3 MIBNode
Description:
A node element in the MIBTree (extends MIBObject).
Main Methods:
4.2.4.3.1 get
Passes the get command to one of his sons. The OID describes to which son he
needs to pass the get command.
Parameters:
77
EasySNMP
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The OID string contains his OID in it.
Post-Conditions:
 The get command is passed to one of his sons removing his OID from the OID
string.
4.2.4.3.2 set
Passes the set command to one of his sons. The OID describes to which son he needs
to pass the set command.
Parameters:
 oid : string [in] – A string representation of the OID.
 newValue : int [in] – The new value to change to.
Pre-Conditions:
 The OID string contains his OID in it.
Post-Conditions:
 The set command is passed to one of his sons removing his OID from the OID
string.
4.2.4.3.3 getNext
Passes the get command to one of his sons. The OID describes to which son he
needs to pass the get command.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The OID string contains his OID in it.
Post-Conditions:
 The get command is passed to one of his sons removing his OID from the OID
string. But if that son is a leaf, passes to the next son the get command removing
his OID from the OID string.
4.2.4.4 MIBScalar
Description:
A scalar element in the MIBTree (holds one value).
Main Methods:
4.2.4.4.1 get
Used to obtain and return the value this element points to.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The OID element is readable.
78
EasySNMP
Post-Conditions:
 A value is returned.
4.2.4.4.2 set
Used to set a new value to the value this element points to.
Parameters:
 oid : string [in] – A string representation of the OID.
 newValue : int [in] – The new value to change to.
Pre-Conditions:
 The OID element is writable.
Post-Conditions:
 A value that this element points to, is changed to the value of newValue.
4.2.4.4.3 getNext
Used to obtain a value of the “successor” element with the given OID.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The successor OID element is readable.
Post-Conditions:
 A value is returned from the MIBScalar closest to this MIBScalar.
4.2.4.5 MIBTable
Description:
A table element in the MIBTree (holds multiple values).
Main Methods:
4.2.4.5.1 get
Used to obtain and return the value this element points to in the table.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The OID element is in the table.
Post-Conditions:
 A value is returned.
4.2.4.5.2 set
Used to set a new value to the value this element points to in the table.
Parameters:
 oid : string [in] – A string representation of the OID.
 newValue : int [in] – The new value to change to.
79
EasySNMP
Pre-Conditions:
 The OID element in the table is writable.
Post-Conditions:
 A value that this element points to in the table, is changed to the value of
newValue.
4.2.4.5.3 getNext
Used to obtain a value of the “successor” element with the given OID, meaning the
next line in the table.
Parameters:
 oid : string [in] – A string representation of the OID.
Pre-Conditions:
 The successor OID element is readable in the table (next row).
Post-Conditions:
 A value is returned from the next row in the table.
4.2.5 SNMPAgent - Monitor
4.2.5.1 MonitorController
Description:
This class is the main controller of monitoring module, it responsible to check for traps
and report about them to the agent.
Main Methods:
4.2.5.1.1 start
Start the execution of the MonitorController using the specified TrapInfo objects.
The TrapInfo objects will be inserted to the traps queue according to the next time
that each trap is needed to be executed. After all the TrapInfo objects are inserted to
the queue the MonitorController will start to check each trap.
Parameters:
 traps: TrapInfo[] [in] – The objects that are needed to be monitored.
Post-Conditions:
 The order of the items in m_trapsQueue is according to the next time that each
TrapInfo is needed to be checked
 The MonitorController is working.
4.2.5.1.2 initSystemIdentificationValue
Find the last identification value of the system hardware configuration and keep it in
m_prevSystemID.
Post-Conditions:
 m_prevSystemID attribute contains the current system identification value.
80
EasySNMP
4.2.5.1.3 initConfigurationIdentification
Find the last identification value of the configuration files and keep it in
m_prevConfigurationID.
Post-Conditions:
 m_prevConfigurationID attribute contains the current configuration file
identification value.
4.2.5.1.4 getSystemIdentificationValue
Retrieve the last identification value of the system hardware configuration (return
m_prevSystemID).
Returen value:
 int – the value of the current system hardware identification.
4.2.5.1.5 getConfigurationIdentification
Retrieve the last identification value of the configuration files (return
m_prevcConfigurationID).
Returen value:
 int – the value of the current system hardware identification.
4.2.5.1.6 getNextTrapToCheck
Return the next TrapInfo object that is needed to be checked.
Returen value:
 TrapInfo – the next TrapInfo that is needed to be checked.
Invariant:
 The order of the items in m_trapsQueue is according to the next time that each
TrapInfo is needed to be checked.
Post-Conditions:
 The returned TrapInfo object is removed from the m_trapsQueue queue.
4.2.5.1.7 insertTrapToQueue
Calculate the next time that the specified trap is needed to be check and insert it to
the correct position in the traps queue.
Invariant:
 The order of the items in m_trapsQueue is according to the next time that each
TrapInfo is needed to be checked.
Post-Conditions:
 The specified trap is inserted into m_trapsQueue queue in the correct position.
4.2.5.2 TrapInfo
Description:
This is an abstract class that represents a ScalarMIBObject that is needed to be
monitored and the conditions for sending traps for this monitored object.
81
EasySNMP
Main Methods:
4.2.5.2.1 checkIfValid
Retrieve the current value of this TrapInfo and determine if this monitored object
state is valid (each type of TrapInfo object has different logic to determine if the
monitored object is valid).
After that the monitored object is sampled the current value is inserted into the
m_previousSamples queue and the oldest value in the queue is removed.
Returen value:
 boolean – indicate whether the monitored object is valid or not.
Post-Conditions:
 The new sampled value is inserted into m_previousSamples.
4.2.5.2.2 getTrapData
Retrieve the associated ScalarMIBObjects of this trap and their current values.
Returen value:
 ScalarMIBObject[] – the associated ScalarMIBObjects of this TrapInfo.
4.2.5.3 BooleanTrapInfo
Description:
This class extends the TrapInfo class and represents a ScalarMIBObject that has
Boolean value (digital value).
Main Methods:
4.2.5.3.1 checkIfValid
Override the method of the parent object. BooleanTrapInfo determines if the state
of his monitored object is valid according to the m_trapOn and the m_bounceTime
attributes. The monitored object is not valid if the value of the monitored object is
equal to m_trapOn for m_bounceTime milliseconds.
Returen value:
 boolean – indicate whether the monitored object is valid or not.
Invariant:
 m_previousSamples contains samples within the m_bounceTime frame.
Post-Conditions:
 The new sampled value is inserted into m_previousSamples.
4.2.5.4 NumericTrapInfo
Description:
This is an abstract class that extends the TrapInfo class. This class represents a
ScalarMIBObject that has numeric value.
Main Methods:
82
EasySNMP
4.2.5.4.1 checkIfValid
Override the method of the parent object. NumericTrapInfo can determine if the
state of his monitored object is valid according to two conditions:
1. If m_trapOnInvalidRange is true – the monitored object is invalid if the current
value of the monitored object is not between m_minValue and m_maxValue.
2. If m_trapOnAnomalousValueChange is true – the monitored objet is invalid if the
value of this object changed in more then m_validValueDifference in
m_deltaTime milliseconds.
Returen value:
 boolean – indicate whether the monitored object is valid or not.
Invariant:
 m_previousSamples contains samples within the m_deltaTime frame.
Post-Conditions:
 The new sampled value is inserted into m_previousSamples.
4.2.5.5 IntegerTrapInfo
Description:
This class extends the NumericTrapInfo class and represents a ScalarMIBObject that
has integer value.
Main Methods:
4.2.5.5.1 checkIfValid
The same logic as in NumericTrapInfo except that the type of the m_minValue and
m_maxValue are integers.
4.2.5.6 FloatTrapInfo
Description:
This class extends the NumericTrapInfo class and represents a ScalarMIBObject that
has float value.
Main Methods:
4.2.5.6.1 checkIfValid
The same logic as in NumericTrapInfo except that the type of the m_minValue and
m_maxValue are floats.
83
EasySNMP
4.3 Packages
4.3.1 SiteBuilder
The SiteBuilder is composed of four main packages:
 Domain package – contains the SiteBuilder data objects.
 SiteBuilder package – contains the SiteBuilder control objects.
 Persistence package – contains the objects that support saving and loading of a
network.
 DeploymentManager package – contains the deployment manager control
objects.
Persistence
84
EasySNMP
4.3.1 SNMPAgent
The SNMPAgent is composed of three main packages:
 MIBBuilder package – contains the data objects and the control objects that are
responsible for building the MIB tree structure of the site.
 SNMPAgent package – contains the data objects and the control objects that are
responsible for the SNMP communication.
 Monitor package – contains the data objects and the control objects that are
responsible for checking the values of the monitored parameters and sending trap
when invalid values are found.
85
EasySNMP
4.4 Unit Testing
4.4.1 SiteBuilder
4.4.1.1 Network.AddArea(Area area)
No. Description
1
2
3
4
Expected Result
Call the method with an Area instance such
as:
1. The area is not part of another
network's areas collection.
2. The area is not (already) part of the
network's areas collection.
3. The network's areas collection does not
contain another area with the name
identical to the name of the new area.
Call the method with an Area instance such
as:
1. The area is part of another network's
areas collection.
Call the method with an Area instance such
as:
1. The area is already part of the
network's areas collection.
Call the method with an Area instance such
as:
1. The network's area collection contains
another area with the name identical to
the name of the new area.
1. The area is added to the
network's areas collection.
1. The area is removed from its
previous network's areas
collection.
2. The area is added to the
network's areas collection.
1. No changes are made to the
network's areas collection.
1. The area is assigned a new autogenerated name.
2. The area is added to the
network's areas collection.
The exact unit tests will be performed on:
 Network.AddSite(Site site)
 Area.AddSite(Site site)
 Site.AddIOModule(IOModule ioModule)
 Site.AddVirtualObject(VirtualObject virtualObject)
 Site.AddHostResource(HostResource hostResource)
 Site.AddPortsGroup(PortsGroup portsGroup)
4.4.1.2 Network.RemoveArea(Area area)
No. Description
Expected Result
86
EasySNMP
1
2
Call the method with an Area instance such
as:
1. The area is part of the network's areas
collection.
Call the method with an Area instance such
as:
1. The area is not part of the network's
areas collection.
1. The area is removed from the
network's areas collection.
1. An error is returned, indicating
that the specified area is not
found in network's areas
collection.
The exact unit tests will be performed on:
 Network.RemoveSite(Site site)
 Area.RemoveSite(Site site)
 Site.RemoveIOModule(IOModule ioModule)
 Site.RemoveVirtualObject(VirtualObject virtualObject)
 Site.RemovePortsGroup(PortsGroup portsGroup)
4.4.1.3 Network.RemoveAllAreas()
No. Description
1
2
Expected Result
Call the method when:
1. The network's areas collection has
some areas.
Call the method when:
1. The network's areas collection is
empty.
1. The area is removed from the
network's areas collection.
1. No changes are made to the
network's areas collection.
The exact unit tests will be performed on:
 Network.RemoveAllSites()
 Area.RemoveAllSites()
 Site.RemoveAllIOModules()
 Site.RemoveAllVirtualObjects()
 Site.RemoveAllPortsGroups()
4.4.1.4 Network.Touch()
No. Description
1
Expected Result
Call the method.
1. The modification date & time of
the network is updated to NOW.
87
EasySNMP
4.4.1.5 NetworkData
This class contains only get methods. We will check them by creating a NetworkData object,
call each get method and compare the result with the expected result.
4.4.2 Deployment Manager
4.4.2.1 DeploymentController.Validate / buildConfigFiles /
downloadConfigFiles
No.
1
Description
Expected Result
These are control methods and they will be
tested in the acceptance tests section.
4.4.2.2 ConfigValidator.Validate
No.
1
Description
Expected Result
Call the method with different types of
networks (valid and not valid).
1. Compare the method result to
the expected result.
4.4.2.3 ConfigValidator.validateSite
No.
1
Description
Expected Result
Call the method with different types of sites
(valid and not valid).
1. Compare the method result to
the expected result.
4.4.2.4 ConfigBuilder. buildConfigForSite
No.
Description
Expected Result
Call the method with different types of sites.
1. Compare the returned
configuration file to the
expected configuration.
1
4.4.2.5 ConfigDownloader.downloadConfigFile
This method needs to download a file to an ACE3600, this method will be checked in the
acceptance tests
4.4.3 SNMPAgent – Agent
We will use the following mockups and proxies:
 MIBObject testMIB - A hard coded mockup of a small MIB tree
 MOSCADProxyBridge - A proxy bridge for the MOSCAD API. We will write the code and
test it under Windows so the proxy will connect MOSCAD API with Windows API.
88
EasySNMP
4.4.3.1 AgentController.start(MIBObject testObject)
No. Description
1
Expected Result
Call the method with an instance of
MIBObject that is a hard coded mockup of
a small MIB tree.
1. The agent will start responding to
SNMP requests and send traps.
4.4.3.2 AgentController.stop()
No. Description
1
Expected Result
Call the method.
1. The agent will stop responding to
SNMP requests and send traps.
4.4.3.3 AgentController.messageReceive(Packet packet)
No. Description
1
2
3
Expected Result
Call the method with a packet with a "get"
command containing all.
Call the method with a packet with a "set"
command containing all.
Call the method with a packet with a "get
next" command containing all.
1. The agent builds the response
according to the testMIB.
1. The agent builds the response
according to the testMIB and the
OID are set to the new value.
1. The agent builds the response
according to the testMIB.
4.4.3.4 AgentController.sendTrap(TrapData trapData)
No. Description
1
Expected Result
Call the method with a hard coded trap
data of a trap that contains all data types.
1. The agent will create the trap
message according to the
trapData.
4.4.3.5 CommunicationInterface.sendUDPPacket
(packet, destination)
No. Description
1
Expected Result
Call the method with a SNMP packet,
destination address & port.
89
1. The NMS receive the expected
message.
EasySNMP
4.4.3.6 CommunicationInterface.receiveUDPPacket(port)
No. Description
1
Expected Result
Call the method with the port 161.
1. The agent receives packets from
an NMS.
4.4.3.7 SNMPServices.encodeMsg(snmpMessage)
No. Description
1
2
Expected Result
Call the method with a SNMP response
containing all data types.
Call the method with a SNMP trap
containing all data types.
1. The message is encoded as
expected.
1. The message is encoded as
expected.
4.4.3.8 SNMPServices.decodeMsg(packet)
No. Description
1
2
3
Expected Result
Call the method with a SNMP packet with a
"get" command containing all data types.
Call the method with a SNMP packet with a
"set" command containing all data types.
Call the method with a SNMP packet with a
"get next" command containing all data
types.
1. A SNMPMessage is created as
expected.
1. A SNMPMessage is created as
expected.
1. A SNMPMessage is created as
expected.
4.4.3.9 SNMPEncoder.encodeMsg(snmpMessage)
No. Description
1
2
Expected Result
Call the method with a SNMP response
containing all data types.
Call the method with a SNMP trap
containing all data types.
1. The message is encoded as
expected.
1. The message is encoded as
expected.
4.4.3.10 SNMPDecoder.decodeMsg(packet)
No. Description
1
2
Expected Result
Call the method with a SNMP packet with a
"get" command containing all data types.
Call the method with a SNMP packet with a
"set" command containing all data types.
90
1. A SNMPMessage is created as
expected.
1. A SNMPMessage is created as
expected.
EasySNMP
3
Call the method with a SNMP packet with a
"get next" command containing all data
types.
1. A SNMPMessage is created as
expected.
4.4.4 SNMPAgent – MIBBuilder
Note:
All the unit tests defined in MIBObject will be tested on all 3 classes which extends the
MIBObject (MIBTable, MIBScalar and MIBNode).
4.4.4.1 MIBBuilder.init()
No. Description
Expected Result
1
Call the method without a configuration
file.
2
Call the method with an invalid
configuration file.
Call the method with different
configuration files:
3
1. A very large configuration file.
2. A configuration file with a wide variety
of traps.
3. An empty (but valid) configuration file.
1. A built valid MIBTree without
added information from a
configuration file.
1. A built valid MIBTree without
added information from a
configuration file.
1. A built valid MIBTree filled with
the information obtained from
the configuration file.
4.4.4.2 MIBObject.get()
No. Description
1
2
3
Expected Result
1. Call the method with an invalid OID.
2. Check on MIBNode, MIBTable and
MIBScalar.
Call the method with an OID that ends at a
MIBNode.
Call the method with different variations:
1. from a MIBNode.
2. from a MIBScalar.
3. from a MIBTable.
91
1. null.
1. null.
1. A scalar value (integer).
EasySNMP
4.4.4.3 MIBObject.set()
No. Description
1
2
3
4
5
6
Expected Result
1. Call the method with an invalid OID.
2. Check on MIBNode, MIBTable and
MIBScalar.
Call the method with an OID that ends at a
MIBNode.
1. Call the method with an invalid
newValue (e.g expecting a value of 0 or
1 and trying to set to 5) and an OID.
2. Call the get method on the same OID.
1. Call the method with a valid OID and
value, but the OID leads to a non
writable element.
2. Call the get method on the same OID.
1. Call the method with different
variations of valid OID and a valid
newValue that leads to a writable
element:
 from a MIBNode.
 from a MIBScalar.
 from a MIBTable.
2. Call the get method with different
variations.
Manipulate the OID string, and see that it
arrives to the expected node/leaf.
1. null.
1. null.
1. Value hasn’t changed.
1. Value hasn’t changed.
1. Value has changed to the new
value, newValue.
1. The expected MIBObject.
4.4.4.4 MIBObject.getNext()
No. Description
1
2
3
4
5
Expected Result
Call the method with an invalid OID.
Call the method with an OID that ends at a
MIBNode.
Call the method with an OID that leads to a
leaf that has no next leaf.
Call the method with an OID that leads to a
leaf that has a next leaf (A brother).
Call the method with an OID of an element
(Row and column) that sits in a table.
92
1. null.
1. null.
1. Returned a value of the next leaf
of the closest leaf of his uncle
(Recursive).
1. Returned the value of his brother
in the MIBTree.
1. Returned the value of the
element in the next column.
2. If reached the last column, return
EasySNMP
6
Manipulate the OID string, and see that it
arrives to the expected node/leaf.
value of first column in next row.
1. The expected MIBObject.
4.4.5 SNMPAgent – Monitor
4.4.5.1 MonitorController.start(TrapInfo[] traps)
No.
1
Description
Expected Result
This is a control method and it will be tested in
the acceptance tests section.
4.4.5.2 MonitorController.initSystemIdentificationValue()
No.
1
Description
Expected Result
Call the method using the MOSCAD API proxy
that return a predefined value.
1.
The predefined value should be
return using the
getSystemIdentificationValue
method.
4.4.5.3 MonitorController.initConfigurationIdentification()
No.
1
Description
Expected Result
Call the method using predefined configuration
file that contains the configuration
identification value.
1.
The identification value should be
return using the
getConfigurationIdentification
method.
4.4.5.4 MonitorController.getNextTrapToCheck()
No.
1
Description
Expected Result
We will use a preconfigured set of TrapInfo
objects to init the MonitorController and use
the MOSCAD API proxy to mimic the system
clock. The test will be made of series of calls to
getNextTrapToCheck()
1.
On each call to
getNextTrapToCheck() the returned
TrapInfo object will be compared to
an expected object (according to
the preconfigured set of TrapInfo
objects).
4.4.5.5 MonitorController.insertTrapToQueue(TrapInfo trap)
No.
Description
Expected Result
93
EasySNMP
Call the method with different TrapInfo objects.
1.
1
After each call to
insertTrapToQueue() we will check
that TrapInfo object was inserted to
the correct position in
m_trapsQueue.
4.4.5.6 BooleanTrapInfo.checkIfValid()
No.
Description
Expected Result
Call the method with different TrapInfo objects
each with different attributes.
1.
1
2.
Compare each call result to a known
answer.
Check the after each call that
m_previousSamples queue is
updated.
4.4.5.7 BooleanTrapInfo.getTrapData()
No.
1
Description
Expected Result
We will init the TrapInfo object with stubs of
ScalarMIBObject and call the getTrapData()
method.
1.
4.4.5.8 IntegerTrapInfo.checkIfValid()
Same as in BooleanTrapInfo.checkIfValid().
4.4.5.9 IntegerTrapInfo.getTrapData()
Same as in BooleanTrapInfo. getTrapData().
4.4.5.10 FloatTrapInfo.checkIfValid()
Same as in BooleanTrapInfo.checkIfValid().
4.4.5.11 FloatTrapInfo.getTrapData()
Same as in BooleanTrapInfo. getTrapData().
94
The return value will be compared
to the objects that we used to init
the TrapInfo.
EasySNMP
5. System Architecture
Deployment diagram of the system:
The system composed of two main components:
 SiteBuilder.
 SNMP Agent.
The SiteBuilder is a windows application (will be written in C# and will need a .NET
framework 2 to run).
The SiteBuilder is composed of two modules:
 SiteBuilder module.
 Deployment manager.
The SiteBuilder is used for designing the network and its sites, define which system and user
variables will be monitored on each site and save and load networks designs from a file.
The Deployment manager is used for building configuration file for each site based on the
network design and for downloading the configuration files to the site.
The SNMP Agent is a real-time application for MOSCAD ACE3600, it will be written in c.
The SNMP Agent is composed of three main modules:
 MIB Builder.
 SNMP agent.
 Monitoring module.
The main goal of the SNMP Agent is to communicate with a third party application that is
called SNMP manager and to provide the SNMP manger necessary information regarding the
site that the agent is being running on.
The MIB Builder is the first module that is executed when the SNMP Agent is running, this
module is responsible for identifying the I/O modules that are connected to the ACE3600
(the site) and using the site configuration file (that was downloaded to the site using the
deployment manager) build a MIB tree with all the data that the site can provide to the
SNMP manager.
95
EasySNMP
After that the MIB tree is ready the SNMP Agent module and the Monitoring module will be
run simultaneously on the site.
The SNMP Agent module is responsible for the actual communication with the SNMP
manger using SNMP protocol version 2c. The agent can receive SNMP requests from the
SNMP manager, retrieve the requested data from the MIB tree and return the answer to the
SNMP manager.
The monitoring module is responsible for monitoring system and user variables and report
to the SNMP Agent module when an anomaly is found on such variable (these variables are
configured by the user in the SiteBuilder).
When the SNMP Agent module receives from the monitoring module that some variable
value is anomalous it sends this information to the SNMP manager.
96
EasySNMP
6. User Interface Draft
6.1 SiteBuilder
6.1.1 Main window
SiteBuilder's main window is divided (roughly) into 6 main sections as illustrated in the
following image.
Menu
Toolbar
Toolbox
Network
Explorer
Network
Grid
Properties
A brief description of the sections:
 Menu – The main menu through which the user can invoke all the SiteBuilder's
functionalities such as:
o Loading/Storing network diagrams.
o Editing network components.
o Plug-ins management.
o Access to help topics.
 Toolbar – A reflection of the 'Menu' section in a form of a quick-access tool buttons.
 Network Grid - The main working surface, where the current network's items are
displayed, added to, removed from and manipulated.
97
EasySNMP
 Network Explorer – A reflection of the 'Network Grid' section in a form of hierarchal
tree display.
 Toolbox – Displays the network items (components) extracted from the loaded plug-ins,
such as ACE3600 moscad, IO modules and others.
 Properties section will display properties of a selected item (selected through the
Network Grid or through the Network Explorer)
6.1.2 Loading/Storing network dialog boxes
Both, Loading & Storing, network diagrams will be done through the same dialog box,
illustrated in the following image.
Selected database
Network diagrams
browser
Selected network diagram
This dialog box will enable users to select a directory, browse the network files on that
directory and load/store the network.
98
EasySNMP
6.2 Deployment Manager
6.2.1 Deploying network configuration dialog box
This dialog box (illustrated in the below image) appears when the user selects to deploy the
network's configuration to the ACE3600 devices and after the network has passed the
validation and the configuration files are built.
Network’s ACE3600
components list
This dialog box displays a list of the current network's ACE3600 components and enables
users to select the ACE3600 components to which the configuration is to be downloaded to.
99
EasySNMP
7. Testing
7.1 SiteBuilder
The SiteBuilder is mainly a GUI application that does not contain business logic therefore the
acceptance tests will be done manually.
7.2 Deployment Manager
The Deployment manager is a GUI application that is part of the SiteBuilder. The acceptance
tests for this module will also be done manually as part of the SiteBuilder tests.
7.3 SNMP Agent
7.3.1 Functional Requirements
For the agent's functional testing we will use a predefined configuration file and upload it to
the MOSCAD.
For testing most of the functional requirements we will use a SNMP manager that will be
provided by Motorola. These tests will be done manually.
For testing the trap checking and handling mechanism we will build another application that
will be run on the MOSCAD and communicate with a PC GUI application and together they
will change the values of a preconfigured monitored objects (like digital I/O port) and while
doing so it will trigger a traps (this trap will be reflected in the NMS).
7.3.2 Non-Functional Requirements
For testing the nonfunctional requirements we will extend the previously described test tool
application to monitor the system performance (e.g. CPU utilization, memory usage, etc…).
For checking the response times we will build a debug version of the agent. This version will
supply the response time information to the test tool and the average times will be
displayed in the test tool GUI application.
100
EasySNMP
8. Task List
8.1 SiteBuilder
ID
Title
Starting
Date
(est)
Duration
in days
(est)
Plug-ins
Infrastructure
1
2
Management
2
2
First Plug-in – The
main components
3
4
Description
Building the infrastructure for
plug-ins. Creating as simple as
possible interface for future
plug-ins development.
Building a simple plug-in
management engine, enabling
loading/unloading plug-ins,
selecting specific components,
etc.
Building the first and main
plug-in. The first plug-in will
supply the core SiteBuilder's
components such as ACE3600,
IO Modules, etc.
Core/Engine
Toolbox window
4
7
Properties window
5
4
The Engine
6
14
Building a dynamic Toolbox
window which will display it's
content according to the
loaded plug-ins.
Building a selection-sensitive
properties window, this will
display properties of a selected
item and will enable editing
those properties.
Building the core engine of the
application. Dragging, copying,
cutting, pasting, selecting and
other core capabilities.
Visual
Drawings
7
2
101
Drawing the various required
images, for menus, toolbars,
the components (of the first
plug-in) and so on.
EasySNMP
Integration
8
9
Integration with
Database module
2
Integration with
Deployment
Manager
2
Embedding the Database
module into the application
and re-coordination of the
mutual interface[s].
Embedding the Deployment
Manager into the application
and re-coordination of the
mutual interface[s].
Documentation
Help Topic
10
4
Writing help topics for the
entire application, including
the database module and the
deployment manager.
Test & Bug fixes
Tests, adjustments &
Bug fixing
11
12
During this period the
application's first version will
be distributed to other team
members and Motorola
representative for receiving
any comments, reporting of
bugs and fixing them.
8.2 Deployment Manager
ID
Title
1
2
3
ConfigValidator
ConfigBuilder
ConfigDownloader
4
5
DeploymentControll
er
Unit tests
6
GUI
7
Integration with
SiteBuilder
Starting
Date
(est)
Duration
in days
(est)
3
3
3-4
3
2
4
2
102
Description
Build the ConfigValidator class.
Build the ConfigBuilder class.
Build the ConfigDownloader
class.
Build the
DeploymentController class.
Complete the missing unit
tests.
Build the GUI for the
deployment manager.
Integrate the deployment
manager with the Site Builder.
EasySNMP
8.3 SNMPAgent - Agent
ID
1
2
3
4
5
6
Title
Decoding the SNMP
packet header
Decoding SNMPv1
general PDU
Decoding SNMPv2
general PDU
Decoding SNMPv2
get-bulk PDU
Create the binds in
the message
Create the message
Starting
Duration
Date
in days
(est)
(est)
SNMP Decoding
8/1/08
1
10/1/08
1-2
1-2
1-2
1-2
0.5
Description
The first step in decoding a
SNMP packet.
The second step in decoding a
general SNMPv1 message.
The second step in decoding a
SNMPv2 message.
The second step in decoding a
SNMPv2 get-bulk message.
The third step in decoding a
SNMP message.
The last step in decoding a
SNMP message.
SNMP Encoding
7
8
9
10
Encoding the SNMP
packet header
Encoding SNMPv1
general PDU
Encoding SNMPv2
general PDU
Encoding SNMPv1
trap PDU
1
1-2
1-2
1-2
The first step in encoding a
SNMP message.
The second step in encoding a
general SNMPv1 message.
The second step in encoding a
SNMPv2 message.
The second step in decoding a
SNMPv1 trap message.
Communication
11
12
Listen to SNMP
messages
Send a UDP packet
0.5
0.5
Using the MOSCAD API to
listen to port 161.
Using the MOSCAD API to send
UDP messages.
AgentController
13
14
15
16
Receiving SNMP
packets and decode
them
Creating the SNMP
response
Fill the SNMP
response
Encode the response
and send it to all the
0.5
0.5
1
0.5
103
The first step in processing a
SNMP message.
The second step in processing
a SNMP message.
The third step in processing a
SNMP message.
The last step in processing a
SNMP message.
EasySNMP
NMSs registered
Send traps
17
1-2
Receive traps from the
Monitor, create the message,
encode it and send it
Finalizing
18
Code adjustments
and testing
3-4
Almost final adjustments and
test all my modules at work.
8.4 SNMPAgent - MIBBuilder
ID
Title
1
Build Tools and Data
Structures
Create a MIBTree
data structure
2
3
4
5
Starting
Date
(est)
Duration
in days
(est)
1/1/08
14
15/1/08
30
15/2/08
30
15/3/08
15
1/4/08
Until the
project is
over.
Constructing a basic
MIBTree
Parsing the
configuration file
Building a complete
MIBTree
104
Description
String Tokenizer, Dictionary,
Vector, List, Table.
The MIBTree data structure
holding all the MIBObject, and
the implementation of get,
getNext and set methods for
MIBNodes.
A basic MIBTree will contain
only a few parts that are
described in the Meta Models
(Will mostly exclude RFC
elements), will include the NE,
VMO, MO, Traps and other
important table leafs. Also the
implementation of get,
getNext and set methods for
MIBScalar and MIBTable.
Parsing the configuration file
and building a MIBTree
according to it.
Adding RFC elements and
other important Motorola
defined elements to the
MIBTree, while implementing a
specific get and set methods
for each of the leafs (MIBScalar
or MIBTable).
EasySNMP
8.5 SNMPAgent - Monitor
Starting
Duration
ID
Title
Date
in days
Description
(est)
(est)
Build infrastructure, data objects and controller
Build queue ADT
Build a queue ADT in C
1
2
including unit tests.
Build monitoring
Build simple monitoring data
data objects
objects (TrapInfo,
BooleanTrapInfo, etc…) that
2
3
include the functionality that is
needed for validation checking
only.
Build simple
Build the main functionality of
3
2-3
MonitorController
the MonitorControlller.
Tests on the
Test the current built code on
4
1-2
MOSCAD
the MOSCAD.
Check CPU utilization
Build simple version of the test
tool application and check the
CPU utilization of the monitor
5
1-2
module on the MOSCAD (To
make sure that we can satisfy
the nonfunctional
requirements).
Extend the module functionality, integrate with MIBBuilder module and complete unit
tests
Extend the
Add the needed functionality
functionality of the
for the objects in the monitor
TrapInfo objects the
module (TrapInfo objects and
6
1-2
MonitorController
MonitorController) to fit the
interface between MIBBuilder
and the monitor module.
Unit tests
Complete the needed unit
tests that check the interface
7
2-3
with the MIBBuilder objects
(using stubs and proxies – this
is not real code integration).
Complete the test
Extend the test tool application
8
4
tool
and add GUI in the PC part of
105
EasySNMP
9
Final code
adjustment and
Testing
2-3
106
this application.
Test the complete module
using the test tool including
stress tests and find the stress
limits of the module.
EasySNMP
9. Appendix
9.1 SNMP Message Formats
9.1.1 SNMP Variable Binding Format
Subfield
Name
Object Name
Object Value
Syntax
Size (bytes)
Sequence
of Integer
Variable
Variable
Variable
Description
Object Name: The numeric object identifier of
the MIB object, specified as a sequence of
integers. For example, the object sysLocation
has the object identifier 1.3.6.1.2.1.1.6, so it
would be specified as “1 3 6 1 2 1 1 6” using
ASN.1
Object Value: In any type of “get” request, this
subfield is a “placeholder”; it is structured using
the appropriate syntax for the object but has no
value (since the “get” request is asking for that
value!)
In a “set” request (SetRequest-PDU) or in a reply
message carrying requested data (GetResponsePDU or Response-PDU), the value of the object
is placed here.
9.1.2 SNMP Version 1 (SNMPv1) Message Format
The SNMP general message format was, of course, first used to define the format of
messages in the original SNMP Protocol, SNMP version 1 (SNMPv1). This first version
of SNMP is probably best known for its relative simplicity, compared to the versions
that followed it. This is reflected in its message format, which is quite straightforward.
The general message format in SNMPv1 is a “wrapper” consisting of a small header
and an encapsulated PDU. Not very many header fields were needed in SNMPv1
because the community-based security method in SNMPv1 is very rudimentary.
9.1.2.1 SNMP Version 1 (SNMPv1) General Message Format
Field Name
Syntax
Version
Integer
Size
(bytes)
4
Description
Version Number: Describes the SNMP version number
of this message; used for ensuring compatibility
between versions. For SNMPv1, this value is actually 0,
not 1.
107
EasySNMP
Community
Octet
String
Variable
PDU
—
Variable
Community String: Defines an access environment for a
group of NMSs. NMSs within the community are said to
exist within the same administrative domain.
Community names serve as a weak form of
authentication because devices that do not know the
proper community name are precluded from SNMP
operations.
Protocol Data Unit: The PDU being communicated as
the body of the message.
9.1.2.2 SNMPv1 PDU Formats
All of the PDUs in SNMPv1 have the same format, with one exception: Trap-PDU. The exact
semantics of each field in the PDU depends on the particular message. For example, the
ErrorStatus field only has meaning in a reply and not a request, and object values are used
differently in requests and replies as well.
9.1.2.2.1 SNMPv1 Common PDU Format
GetRequest-PDU, GetNextRequest-PDU, SetRequest-PDU and GetResponse-PDU:
Field
Name
Syntax
Size
(bytes)
Description
108
EasySNMP
PDU
Type
Integer
(Enumerated)
4
Request
ID
Integer
4
Error
Status
Integer
(Enumerated)
4
Error
Index
Integer
4
Variable
Bindings
Variable
Variable
Request Identifier: A number used to match requests with
replies. It is generated by the device that sends a request and
copied into this field in a GetResponse-PDU by the responding
SNMP entity.
Error Index: When Error Status is non-zero, this field contains a
pointer that specifies which object generated the error. Always
zero in a request.
Variable Bindings: A set of name-value pairs identifying the MIB
objects in the PDU, and in the case of a SetRequest-PDU or
109
EasySNMP
GetResponse-PDU, containing their values.
9.1.2.2.2 SNMPv1 Trap-PDU Format
The SNMPv1 Trap PDU Consists of Eight Fields:
Field
Name
PDU Type
Enterprise
Syntax
Integer
(Enumerated)
Sequence of
Integer
Size
(bytes)
4
Variable
Agent
Addr
NetworkAddress
4
Generic
Trap
Specific
Trap
Time
Stamp
Integer
(Enumerated)
Integer
4
TimeTicks
4
Variable
Bindings
Variable
Variable
4
Description
PDU Type: An integer value that indicates the
PDU type, which is 4 for a Trap-PDU message.
Enterprise: An object identifier for a group,
which indicates the type of object that
generated the trap.
Agent Address: The IP address of the SNMP
agent that generated the trap. This is of course
also in the IP header at lower levels but
inclusion in the SNMP message format allows
for easier trap logging within SNMP. Also, in the
case of a multihomed host, this specifies the
preferred address.
Generic Trap Code: A code value specifying one
of a number of predefined “generic” trap types.
Specific Trap Code: A code value indicating an
implementation-specific trap type.
Time Stamp: The amount of time since the
SNMP entity sending this message last
initialized or reinitialized. Used to time stamp
traps for logging purposes.
Variable Bindings: A set of name-value pairs
identifying the MIB objects in the PDU.
110
EasySNMP
9.1.3 Community-Based SNMP Version 2 (SNMPv2c) Message
Format
This version of SNMPv2 was intended to keep the new protocol enhancements introduced
by SNMPv2p but go back to the simple SNMPv1 security model. As such, the defining
document for SNMPv2c, RFC 1901, specifies that its overall message format is the same as
that of SNMPv1, except that the version number is changed.
9.1.3.1 Community-Based SNMP Version 2 (SNMPv2c) General
Message Format
Field Name
Syntax
Size
(bytes)
4
Version
Integer
Community
Octet
String
Variable
PDU
—
Variable
Description
Version Number: Describes the SNMP version number
of this message; used for ensuring compatibility
between versions. For SNMPv2c, this value is 1.
Community String: Identifies the SNMP community in
which the sender and recipient of this message are
located.
Protocol Data Unit: The PDU being communicated as
the body of the message.
9.1.3.2 SNMP Version 2 (SNMPv2) Common PDU Format
Field Name
Syntax
PDU Type
Integer
(Enumerated)
Size
Description
(bytes)
4
111
EasySNMP
Request ID
Integer
4
Error
Status
Integer
(Enumerated)
4
Error Index
Integer
Variable
Bindings
Variable
Request Identifier: A number used to match requests with
replies. It is generated by the device that sends a request and
copied into this field in a Response-PDU by the responding
SNMP entity.
Error Status: An integer value that is used in a Response-PDU
to tell the requesting SNMP entity the result of its request. A
value of zero indicates that no error occurred; the other
values indicate what sort of error happened.
Note that the first six values (0 to 5) are maintained as used in
SNMPv1 for compatibility, but SNMPv2 adds many new error
codes that provide more specific indication of the exact
nature of an error in a request. The genErr code is still used
only when none of specific error types (either the old codes or
the new ones) apply.
4
Error Index: When Error Status is non-zero, this field contains
a pointer that specifies which object generated the error.
Always zero in a request.
Variabl Variable Bindings: A set of name-value pairs identifying the
e
MIB objects in the PDU, and in the case of messages other
than requests, containing their values.
9.1.3.3 SNMP Version 2 (SNMPv2) PDU Error Status Field Values
Error
Status
Value
0
Error Code
1
tooBig
2
3
noSuchName
badValue
4
readOnly
5
genErr
6
noAccess
noError
Description
No error occurred. This code is also used in all request
PDUs, since they have no error status to report.
The size of the Response-PDU would be too large to
transport.
The name of a requested object was not found.
A value in the request didn't match the structure that the
recipient of the request had for the object. For example,
an object in the request was specified with an incorrect
length or type.
An attempt was made to set a variable that has an Access
value indicating that it is read-only.
An error occurred other than one indicated by a more
specific error code in this table.
Access was denied to the object for security reasons.
112
EasySNMP
7
8
9
10
11
12
13
14
15
16
17
18
wrongType
The object type in a variable binding is incorrect for the
object.
wrongLength
A variable binding specifies a length incorrect for the
object.
wrongEncoding
A variable binding specifies an encoding incorrect for the
object.
wrongValue
The value given in a variable binding is not possible for
the object.
noCreation
A specified variable does not exist and cannot be created.
inconsistentValue
A variable binding specifies a value that could be held by
the variable but cannot be assigned to it at this time.
resourceUnavailable An attempt to set a variable required a resource that is
not available.
commitFailed
An attempt to set a particular variable failed.
undoFailed
An attempt to set a particular variable as part of a group
of variables failed, and the attempt to then undo the
setting of other variables was not successful.
authorizationError A problem occurred in authorization.
notWritable
The variable cannot be written or created.
inconsistentName The name in a variable binding specifies a variable that
does not exist.
9.1.3.4 SNMPv2 GetBulkRequest-PDU Format
Field Name
Syntax
Size
(bytes)
4
PDU Type
Integer
(Enumerated)
Request ID
Integer
4
Non
Repeaters
Integer
4
Max
Repetitions
Integer
4
Variable
Variable
Variable
Description
PDU Type: An integer value that indicates the
PDU type, which is 5 for a GetBulkRequest-PDU
message.
Request Identifier: A number used to match
requests with replies. It is generated by the
device that sends a request and copied into this
field in a Response-PDU by the responding
SNMP entity.
Non Repeaters: Specifies the number of nonrepeating, regular objects at the start of the
variable list in the request.
Max Repetitions: The number of iterations in
the table to be read for the repeating objects
that follow the non-repeating objects.
Variable Bindings: A set of name-value pairs
113
EasySNMP
Bindings
identifying the MIB objects in the PDU.
9.1.3.5 SNMPv2 Packet Example
An SNMP GetRequest packet for the microphoneMute parameter on a Rane NM 1 (OID:
1.3.6.1.4.1.2680.1.2.7.3.2.0). It is important to remember that changing the number of
bytes of any field in the SNMP message requires changing the Length byte of all the outer
layers that enclose the edited field. For example, changing the GetRequest below to a
SetRequest that sets the microphoneMute to a Value of 1 (0x01) requires changing the
PDU data type to SetRequest (0xA3) and the Value field to an integer (0x04) of length 0x01
and data 0x01. However, increasing the length of the Value field also increases the length
of the Varbind, Varbind List, PDU, and SNMP message fields.
114
EasySNMP
9.2 ASN.1
9.2.1 ASN.1 Overview
Constructing a message requires some knowledge of the data types specified by
ASN.1, which fall into two categories: primitive and complex. ASN.1 primitive data
types include Integer, Octet (byte, character) String, Null, Boolean and Object
Identifier. The Object Identifier type is central to the SNMP message, because a
field of the Object Identifier type holds the OID used to address a parameter in the
SNMP agent. To expand the programmer's ability to organize data, ASN.1 allows
primitive data types to be grouped together into complex data types.
ASN.1 offers several complex data types necessary for building SNMP messages.
One complex data type is the Sequence. A Sequence is simply a list of data fields.
Each field in a Sequence can have a different data type. ASN.1 also defines the
SNMP PDU (Protocol Data unit) data types, which are complex data types specific
to SNMP. The PDU field contains the body of an SNMP message. Two PDU data
types available are GetRequest and SetRequest, which hold all the necessary data
to get and set parameters, respectively. Ultimately the SNMP message is a
structure built entirely from fields of ASN.1 data types. However, specifying the
correct data type is not enough. If the SNMP message is a Sequence of fields with
varying data types, how can a recipient know where one field ends and another
begins, or the data type of each field? Avoid these problems by conforming to the
Basic Encoding Rules.
9.2.2 Basic Encoding Rules
Follow the Basic Encoding Rules when laying out the bytes of an SNMP message.
The most fundamental rule states that each field is encoded in three parts: Type,
Length, and Data. Type specifies the data type of the field using a single byte
identifier. For a brief table of some data types and their identifiers, see Table 1.
Length specifies the length in bytes of the following Data section, and Data is the
actual value communicated (the number, string, OID, etc). One way to visualize
encoding a field is shown in Figure 1.
Figure 1. Format: BER Encoded Field (Primitive Data Type)
Some data types, like Sequences and PDUs, are built from several smaller fields.
Therefore, a complex data type is encoded as nested fields, as shown in Figure 2.
115
EasySNMP
Figure 2. Format: BER Encoded Fields (Complex Data Type)
There are two more Basic Encoding Rules necessary for encoding an SNMP message. Both
apply to encoding OIDs. The first rule applies when encoding the first two numbers in the
OID. According to BER, the first two numbers of any OID (x.y) are encoded as one value
using the formula (40*x)+y. The first two numbers in an SNMP OID are always 1.3.
Therefore, the first two numbers of an SNMP OID are encoded as 43 or 0x2B, because
(40*1)+3 = 43. After the first two numbers are encoded, the subsequent numbers in the
OID are each encoded as a byte. However, a special rule is required for large numbers
because one byte (eight bits) can only represent a number from 0-255. For example, the
number 2680 in the Rane NM 1 microphoneMute OID '1.3.6.1.4.1.2680.1.2.7.3.2.0' cannot
be encoded using a single byte. The rule for large numbers states that only the lower 7 bits
in the byte are used for holding the value (0-127). The highest order bit is used as a flag to
let the recipient know that this number spans more than one byte. Therefore, any number
over 127 must be encoded using more than one byte. According to this rule, the number
2680 must be encoded 0x94 0x78. Since the most significant bit is set in the first byte
(0x94), the recipient knows to use the lower 7 bits from each byte (0x14 and 0x78) and
decode the two bytes as (0x14 *128) + 0x78 = 2680.
9.2.3 Listing of Universal Tags
Universal Tag Number
0
1
2
3
4
5
6
7
8
9
10
11
12
13
16
17
18
Description
reserved for BER
BOOLEAN
INTEGER
BIT STRING
OCTET STRING
NULL
OBJECT IDENTIFIER
ObjectDescriptor
INSTANCE OF, EXTERNAL
REAL
ENUMERATED
EMBEDDED PDV
UTF8String
RELATIVE-OID
SEQUENCE, SEQUENCE OF
SET, SET OF
NumericString
116
EasySNMP
19
20
21
22
23
24
25
26
27
28
29
30
PrintableString
TeletexString, T61String
VideotexString
IA5String
UTCTime
GeneralizedTime
GraphicString
VisibleString, ISO646String
GeneralString
UniversalString
CHARACTER STRING
BMPString
117