Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Zero-configuration networking wikipedia , lookup
List of wireless community networks by region wikipedia , lookup
SIP extensions for the IP Multimedia Subsystem wikipedia , lookup
Cracking of wireless networks wikipedia , lookup
Airborne Networking wikipedia , lookup
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