Modeling Gateway. Toolkit Guide. Document 5069

Transcription

1

2 Notice Copyright Notice Copyright 2002-Present by Aprisma Management Technologies, Inc. All rights reserved worldwide. Use, duplication, or disclosure by the United States government is subject to the restrictions set forth in DFARS (c)(1)(ii) and FAR Liability Disclaimer Aprisma Management Technologies, Inc. ( Aprisma ) reserves the right to make changes in specifications and other information contained in this document without prior notice. In all cases, the reader should contact Aprisma to inquire if any changes have been made. The hardware, firmware, or software described in this manual is subject to change without notice. IN NO EVENT SHALL APRISMA, ITS EMPLOYEES, OFFICERS, DIRECTORS, AGENTS, OR AFFILIATES BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING OUT OF OR RELATED TO THIS MANUAL OR THE INFORMATION CONTAINED IN IT, EVEN IF APRISMA HAS BEEN ADVISED OF, HAS KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES. Trademark, Service Mark, and Logo Information SPECTRUM, IMT, and the SPECTRUM IMT/VNM logo are registered trademarks of Aprisma Management Technologies, Inc., or its affiliates. APRISMA, APRISMA MANAGEMENT TECHNOLOGIES, the APRISMA MANAGEMENT TECHNOLOGIES logo, MANAGE WHAT MATTERS, DCM, VNM, SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, SPECTRUM Security Manager, and Virtual Network Machine are unregistered trademarks of Aprisma Management Technologies, Inc., or its affiliates. For a complete list of Aprisma trademarks, service marks, and trade names, go to: All referenced trademarks, service marks, and trade names identified in this document, whether registered or unregistered, are the intellectual property of their respective owners. No rights are granted by Aprisma Management Technologies, Inc., to use such marks, whether by implication, estoppel, or otherwise. If you have comments or concerns about trademark or copyright references, please send an to spectrum-docs@aprisma.com; we will do our best to help. Restricted Rights Notice (Applicable to licenses to the United States government only.) This software and/or user documentation is/are provided with RESTRICTED AND LIMITED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR (June 1987) Alternate III(g)(3) (June 1987), FAR (June 1987), or DFARS (c)(1)(ii) (June 1988), and/or in similar or successor clauses in the FAR or DFARS, or in the DOD or NASA FAR Supplement, as applicable. Contractor/manufacturer is Aprisma Management Technologies, Inc. In the event the government seeks to obtain the software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall control the terms of the government's license. Virus Disclaimer Aprisma makes no representations or warranties to the effect that the licensed software is virus-free. Aprisma has tested its software with current virus-checking technologies. However, because no antivirus system is 100-percent effective, we strongly recommend that you write protect the licensed software and verify (with an antivirus system with which you have confidence) that the licensed software, prior to installation, is virus-free. Contact Information Aprisma Management Technologies, Inc., 273 Corporate Drive, Portsmouth, NH USA Phone: U.S. toll-free: Web site: Page 2

3 Contents Notice... 2 Preface... 7 Intended Audience... 7 How to Use This Guide... 7 Additional References... 8 Text Conventions... 8 ydocument Feedback... 9 Online Documents... 9 Overview Prerequisites for Developers...10 A SPECTRUM Gateway for Topology...10 Architecture Using the Toolkit Formatting the in an Input File...16 Creating an XML Input File...16 Hierarchical Views...17 Models and Model Types...17 SPECTRUM Attributes...18 Intelligent Models and Management Views...19 XML Input File Syntax...19 The Root Element...19 Model-Oriented Elements...20 Task-Oriented Elements...21 Creating Information...22 Representing the Same Device in Multiple Views...24 Synchronizing Information between SPECTRUM and the Third-Party base...25 Connections...27 Page 3

4 Updating Information...29 Destroying Information...30 The tirc.xml Resource File...31 Working with a Comma-Delimited Input File...31 Importing the Input File...32 Moving the topimport Tool...32 Running the topimport Tool...33 Viewing Import Information...34 The View...34 Events and Alarms...35 The Error Log and the Debug Log...36 Appendix A: Element Definition Connection...38 Syntax...38 Usage...38 Attribute Definitions...38 Destroy...39 Syntax...39 Usage...39 Attribute Definitions...39 Device...40 Syntax...40 Usage...40 Attribute Definitions...40 EventModel...42 Syntax...42 Usage...42 Attribute Definitions...42 GenericView...43 Syntax...43 Usage...43 Attribute Definitions...43 Page 4

5 GenericView_Container...44 Syntax...44 Usage...44 Attribute Definitions...44 Import...45 Syntax...45 Usage...45 Attribute Definition...46 Location...46 Syntax...46 Usage...46 Attribute Definitions...46 Location_Container...47 Syntax...47 Usage...47 Attribute Definitions...47 Port...49 Syntax...49 Usage...49 Attribute Definitions...49 Schedule...50 Syntax...50 Usage...50 Attribute Definitions...51 Topology...52 Syntax...52 Usage...53 Attribute Definitions...53 Topology_Container...53 Syntax...53 Usage...54 Attribute Definitions...54 Update...55 Page 5

6 Syntax...55 Usage...55 Attribute Definitions...55 Appendix B- XML Examples Example 1: Importing into the Topology View...56 Example 2: Creating Connections...57 Example 3: Updating and Destroying...58 Example 4: Creating, Updating and Destroying...60 Appendix C- The Document Type Definition Appendix D - The tirc.xml Resource File Index Page 6

7 Preface In this section: Intended Audience [Page 7] How to Use This Guide [Page 7] Additional References [Page 8] Text Conventions [Page 8] ydocument Feedback [Page 9] Online Documents [Page 9] Intended Audience This guide is intended for SPECTRUM developers and VARs (Value Added Resellers) who want to import network topology information into the SpectroSERVER database. This document focuses primarily on the use of the SPECTRUM toolkit for accepting network topology information from a third-party database via an XML file. How to Use This Guide This guide describes how to use the SPECTRUM toolkit to integrate third-party management systems with SPECTRUM. It is organized as follows: Overview: This section gives an overview of the capabilities of the SPECTRUM toolkit. Architecture: This section illustrates how the components of a SPECTRUM toolkit work together to bring network topology data into SPECTRUM. Mechanics of Integration: This section walks through each step necessary to complete the integration. The following topics are discussed: - Creating an XML input file. - Creating a comma-delimited input file. - Importing the input file. Page 7

8 - Viewing import results in the SpecroGRAPH. Appendix A: This section is a full reference for all elements and attributes included in the Document Type Definition file. Appendix B: This section has several sample XML files for your reference. Appendix C: This section contains the Document Type Definition. Appendix D: This section contains the tirc.xml resource file. Additional References The Integrator Guide (5068): An overview of all of SPECTRUM s integration points. SPECTRUM Concepts Guide (0647): An overview of SPECTRUM s functionality and terminology. Text Conventions The following text conventions are used in this document: Element Convention Used Example User-supplied parameter names Courier and italic in angle brackets <>. The user needs to type the password in place of <password>. On-screen text Courier The following line displays: path= /audit User-typed text Courier Type the following path name: C:\ABC\lib\db Cross-references References to SPECTRUM documents (title and number) Functionality enabled by SPECTRUM Alarm Notification Manager (SANM) Underlined and hypertextblue Italic SANM in brackets []. See ydocument Feedback [Page 9]. SPECTRUM Installation Guide (0675) [SANM] AGE_FIELD_ID Page 8

9 ydocument Feedback Please send feedback regarding SPECTRUM documents to the following address: Thank you for helping us improve our documentation. Online Documents SPECTRUM documents are available online at: Check this site for the latest updates and additions. Page 9

10 Overview In this section: Prerequisites for Developers [Page 10] A SPECTRUM Gateway for Topology [Page 10] Prerequisites for Developers Before using a programmatic on non-programmatic toolkit (including the SPECTRUM toolkit), developers should have significant exposure to the SPECTRUM product, and should read the SPECTRUM Concepts Guide (0647)to familiarize themselves with the underlying concepts of SPECTRUM. In addition, this document assumes a working knowledge of XML and the concept of a Document Type Definition (DTD). A detailed understanding of the network topology to be imported is also assumed. An ability to use the UNIX or Windows NT operating system to navigate through the file system, copy and delete files, and create and edit text files is necessary. A SPECTRUM Gateway for Topology The SPECTRUM toolkit allows integrators to import network topology data from an existing database into the SPECTRUM knowledge base. The toolkit includes a Document Type Definition (DTD) that defines XML elements and attributes. Using the DTD elements, you can create an XML file that describes devices, ports, and connections on your network. This XML file can create new topology data in SPECTRUM, update existing data, or destroy data that is no longer correct. Additionally, the elements and attributes used in the XML syntax can be expanded and customized to suit the needs of most integrations. The toolkit also provides the capability to use comma-delimited ASCII text files to import information specifies Frame Relay and/or ATM connections. You can also import this connection information using the XML functionality mentioned above. Once the network topology data exists in SPECTRUM, you can manage these devices like any other models created manually or by AutoDiscovery. You can view the results of the import, as well as any diagnostic information about each import. Page 10

11 Populating SPECTRUM with dynamic network topology information on an ongoing basis was previously a difficult task. Neither AutoDiscovery nor manual modeling is suited to the constant updates necessary in a changing environment. Modeling connectivity using AutoDiscovery can also be a challenge with various physical infrastructures like those found in a cable MSO, ATM, or Frame Relay environment. SPECTRUM is an effective solution for these problems. Page 11

12 Architecture The SPECTRUM toolkit has several components that function together to import your network data. The first component is a source for the network topology data. This source is often a third-party database, such as a provisioning database, that stores the network topology data you would like to represent in SPECTRUM. During the integration process, you take data from the third-party database and create an input file. Depending on the content, this input file may be an XML file or a comma-delimited ASCII file. The XML input file gives you the widest range of import options and is the main focus of this document. The comma-delimited file allows you to create connections for Frame Relay and ATM circuits. When creating an XML input file, you must work with the provided Document Type Definition (DTD) file and the tirc.xml file. The DTD defines the XML elements, attributes and their associated syntax rules. The tirc.xml file shows which SPECTRUM model types and attributes are available for use. This file relates the SPECTRUM model type names and other attribute names with the unique hexadecimal identifier that SPECTRUM uses for that model type or attribute. The tirc.xml file can be customized to suit the needs of a specific integration. Additions to the tirc.xml file will need to be added to the DTD. Once you create the first input file, it can act as a template for multiple data sets representing the same type of input. For example, if you create an XML file for importing devices, you can use this file over and over again by substituting the device specific topology data. The import tool is a command line utility that reads network topology information from the input file and sends the data to the SpectroSERVER database. The tool is able to import data for display in the SPECTRUM Location and Topology view. You can also import data into a customized view tailored to fit the needs of your integration. With the data from the XML file, the import tool can create, destroy, and update connections, devices, and container models. The SPECTRUM also provides mechanisms to ensure the safety and accuracy of each database import, such as maintaining an audit trail that includes a record of each creation, deletion, association, and update made. You can view information about the import within a GIB view in the SpectroGRAPH. If any type of critical failure occurs during the import process, SPECTRUM generates an event that reports the error. All errors Page 12

13 and their possible causes are logged in an error log file. You can also turn on a debug log that helps you locate the source of problems or inaccuracies. The first figure below illustrates the use of an XML file for importing data. flows from the third-party database and is formatted in the XML file, using the DTD and tirc.xml for syntax purposes. The import tool then interprets the XML file and sends data into SPECTRUM through SPECTRUM s CORBA interface. Page 13

14 Resource File Enumeration of Model Types and Attributes Third Party base Topology XML File Element Definition XML Formatted Topology T O PI M PO R T T O O L Topology C I O N R T B E A R F A C E Spectro SERVER DTD The next figure illustrates the use of a comma-delimited ASCII text file to import Frame Relay and/or ATM connection information. Page 14

15 Third Party base ATM/Frame Relay Connection Comma Delimited ASCII File Comma Delimited ATM/Frame Relay Connection T O P I M P O R T T O O L Connection C I O N R T B E A R F A C E Spectro SERVER Page 15

16 Using the Toolkit In this section: There are four main tasks to complete when using the Toolkit. 1. Extracting Topology The first step is to extract the network topology data from the thirdparty database. Since each database system is different, you should refer to the documentation for the database you are working with to complete this step. 2. Formatting the in an Input File [Page 16] In this step you will create the either an XML or a comma-delimited input file to format the data for the import tool. 3. Importing the Input File [Page 32] Once the input file is created, use the import tool to send the data into SPECTRUM. 4. Viewing Import Information [Page 34] You are able to see the progress and results of the import in the view in SpectroGRAPH. Formatting the in an Input File There are two types of input files used to import data with the Modeling Gateway, XML files and comma-delimited files. XML input files can be used to create or destroy models and connections, and update attribute values and connectivity information. The syntax in the document type definition provided with the defines the elements to be used in the XML input file. Comma-delimited files can only be used to create ATM and Frame Relay connections. The sections below outline how to create each of the types of input files. Creating an XML Input File To understand the elements that are used to create an XML input file, you must be familiar with how SPECTRUM models a network infrastructure. The following section gives you an overview of this philosophy and how it Page 16

17 applies to the XML elements used in an XML input file. If you are comfortable with these concepts, you may want to skip this section and proceed to the XML Input File Syntax [Page 19] section. Hierarchical Views A view in SPECTRUM is a way to organize data so it can be displayed or manipulated. There are two main types of views, management views and hierarchical views. Management views focus on various ways to represent data concerning a specific device. The hierarchical views represent ways to structure your network data. When you structure your network data in the XML file, you choose from elements that represent each of the hierarchical views. There are two types of hierarchical views, Topology and Location. The Topology view is really an abstraction of networking components. When working with this view, you represent the physical or logical components of your network and group these components with logical connectivity in mind. You can choose to graphically represent connections using pipes that show how devices are connected at the port or device level. The Location view organizes your network data by physical location. Using this view you can depict your network in terms of geography. You can start with your global offices and go right to the wiring closet on each floor of each building in each region where your offices are located. Models and Model Types There are numerous model types that have been predefined in SPECTRUM. When model types are instantiated in the SPECTRUM interface to represent a specific network entity, they are referred to as models. There are two major categories of model types, intelligent model types and container model types. Intelligent model types can be instantiated to represent actual devices that operate on the network. They have IP and MAC addresses and SPECTRUM can communicate directly with these devices using SNMP. Container model types are instantiated into models that act primarily as a way of grouping models together. Models can be grouped together based on the type of hierarchical view being used. For example, if you were using the Topology view, you might create a LAN model to group together certain devices on a segment of your network. If you were using the Location view, you might create a Room model to group the devices in one room of your building. A container model may contain other container models, intelligent models, or both, depending on the specific model type. For example, a network Page 17

18 container model could contain an intelligent model that represents a router, and it can also contain a LAN container model that represents a range of IP addresses. On the other hand, a Building model can only contain container models- a Floor, a Section, or a Room. The elements defined in the DTD let you depict your network topology using any of the hierarchical views and their respective container model types. You can also use any of the instantiable intelligent model types. Intelligent model types are not dependent on the type of hierarchical view used. Note that not all model types defined in the SPECTRUM knowledge base can actually be used to create a model in the SpectroGRAPH. Some are used as base model types from which other model types are derived. For more information on this subject, please refer to the SPECTRUM Concepts Guide (0647). There are two methods used to model devices in SPECTRUM. The first method is to use the IP address or the DNS name of the device. With this information, SPECTRUM contacts the device and creates a model using the model type that best represents the functionality of the device. The second method is to choose the model type to base the model on. You still must provide an IP address or a DNS name so SPECTRUM can communicate with the device, however the model type you choose is instantiated regardless of SPECTRUM s assessment of the device s functionality. To create a container model, you select the model type since there is no physical device for SPECTRUM to communicate with. SPECTRUM Attributes Each model type has a set of attributes associated with it. Each attribute describes the model type in some way. When a model is instantiated, the attributes take on values that reflect the device that the model represents and describes the model s current state. For example, the model type Host_Sun has the attribute IPAddress. If a model of the type Host_Sun is instantiated, the value of this attribute reflects the IP address of the device that the model represents. It is important to note that XML syntax also uses the term attribute. XML attributes describe additional information about an element. In SPECTRUM XML syntax, some XML attributes are used to give value to SPECTRUM attributes. For clarity, attributes defined by SPECTRUM are Page 18

19 referred to as SPECTRUM attributes, XML attributes are referred to simply as attributes. Intelligent Models and Management Views As mentioned above, a model representing an SNMP-compliant device within the SpectroGRAPH, must have either an IP Address or a DNS name to identify that device. Once the device model is created, SPECTRUM communicates with the device and gathers device-specific information about MIB variables, ports, and applications. This information can be viewed in one of several different management views, which provide current network device status information and records of network events. For example, the Device Topology (DevTop) view represents a device in terms of its ports and port connections. You can use the DevTop view to examine existing connections to a device or make new connections to other devices. The Application view contains application models that SPECTRUM automatically creates to monitor a device s applications. Other views include information on performance, configuration, and SPECTRUM attribute values. When you use the XML elements to create your device model, SPECTRUM automatically creates management views along with application models and ports based on the type of model you have instantiated, and interaction with the physical device through querying SNMP MIB objects. You have the ability to create connections between these ports and modify SPECTRUM port attribute information using an XML input file. XML Input File Syntax Use the syntax rules defined in the DTD file to generate the XML file. Below is an overview of the functionality of each of the DTD elements. The following explanations and examples do not cover all attributes of each element. For a complete reference on each element and its attributes, see Appendix A: Element Definition [Page 37]. The Root Element The elements defined in the DTD exist in a hierarchical structure that parallels the network representation within SPECTRUM. The root element that must be used with each XML import file is the Import element. XML syntax rules specify that the root element is the outermost element and denotes the beginning and end of the XML file. Therefore, the Import element surrounds the rest of the XML elements used in your document. Page 19

20 Model-Oriented Elements The model-oriented elements define physical or logical components of your network. They are listed below: Topology_Container Location_Container Device Schedule Port Connection GenericView_Container The container-type elements are used to create models that define logical ways of grouping network elements based on the type of SPECTRUM hierarchal view they are in. Each of these container-type elements can exist in one of the specific hierarchical views. The Topology_Container element creates a model that groups other models according to physical or logical connectivity. Since the Topology_Container element creates container models, you must use the model_type attribute to identify the specific container you would like to use. There is an enumeration of possible model_type values in the DTD. A LAN is an example of a Topology_Container model_type value. You must also specify the name of the Topology_Container using the name attribute. The name and model_type attributes give values to the SPECTRUM attributes Model_Name and Modeltype_Name. These values uniquely identify the model created. Topology_Containers can contain other Topology_Container elements, devices, or connections. Topology_Container models are always placed in SPECTRUM s topology view. The Location_Container element groups other models according to physical or geographical location. A Building and a Room are both examples of Location_Container element model type values. Since the Location_Container element creates container models, you must use the model_type attribute to identify the specific container you would like to use. There is an enumeration of possible model_type values in the DTD. You must also specify the name of the Location_Container using the name attribute. The name and model_type attributes give values to the SPECTRUM attributes Model_Name and Modeltype_Name. These values uniquely identify the model created. Page 20

21 The Device element defines a device on the network. It is used with other elements to create, update, or destroy an instance of a device model in SPECTRUM. If you are working with an SNMP device, you must provide a valid, unique IP address or DNS name to uniquely identify the device using the ip_dnsname attribute. This allows SPECTRUM to communicate with the device and select the most appropriate model type based on the device s functionality. If SNMP communication with the device is either not supported or not allowed, the is_managed attribute should be set to false. The ip_dnsname must be set to a unique string, but it does not need to be a valid IP address or DNS name. In this case, the model_type attribute must be set so SPECTRUM knows which model type to use to represent the device. Possible model_type values for devices are enumerated in the tirc.xml resource file. The Schedule element defines when a device model will be put into maintenance mode. When a device model is in maintenance mode, management traffic to the device and its components is suspended. This prevents SPECTRUM from generating any events or alarms on the device model while you are performing maintenance on the device. Ports are automatically created for a device when you create the device model. The Port element lets you modify some SPECTRUM port attribute values, or specify a port-level connection. You can specify different kinds of ports, including a Frame Relay or ATM circuit. You must provide values for the identifier_name and identifier_value attributes to identify the port on the device. The possible values for identifier_name are enumerated in the DTD. The identifier_value should be the value of the identifier chosen by the identifier_name attribute. A Port element must always be specified as a child of a device element. The Connection element defines a physical or logical connection between two devices and therefore must contain two device child elements. If a Port element is specified in the Device element, the connection is resolved on the port level for that device. When using the Connection element, you can choose whether or not to create pipes that graphically represent these connections within the SpectroGRAPH. Connections can only be created in the Topology view. Task-Oriented Elements The rest of the elements defined in the DTD are task-oriented elements. These elements and their attributes help define the type of action the input file generates. It is possible to create new topology information, update, overwrite or delete existing topology information. An individual input file may use zero or one of each of these elements, with the exception of the Page 21

22 Connection element. As many Connection elements as necessary can be utilized. Topology Location GenericView Connection Update Destroy Creating Information Task-oriented elements define what action you would like to take with your XML file. The Topology and Location elements are used when you would like to create new network topology data in SPECTRUM. These elements define the hierarchical view where you would like to create the data. You can then use the corresponding model elements as child elements to create models for the network entities. Use the GenericView element to customize a view for specific integration needs. Topology View To import your network data into SPECTRUM s Topology view, construct your XML file using the Topology element inside the Import root element. The Topology element can contain: Topology_Container elements to create a specific kind of container model Device elements to create a specific type of device model Connection elements to create connections between two devices Using the hierarchy and syntax rules outlined in the DTD definition, you can accurately express your network s physical and logical connectivity. The following is a basic example that shows a LAN container created in the Topology view and a device within that container. For information on creating connections, see the Connections [Page 27] section. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Topology> Page 22

23 <Topology_Container model_type = LAN name = Sample_LAN security_string = public subnet_address= subnet_mask = > <Device ip_dnsname= community_string= public /> </Topology_Container> </Toplogy> </Import> The Import element is the root element and is always contained in the input file. The Topology element indicates that you are going to create models in the Topology view. The Topology_Container element creates a container model. Since this model is a logical component rather than a physical component of the network, SPECTRUM does not have the ability to contact it and define the model type using an IP address or a DNS name. To indicate the type of contain model to create, you must provide a value for the model_type attribute. The possible model_type attribute values are listed in the DTD and under the Topology_Container listing in Appendix A. The name attribute is required and must specify a unique name for the model. The other attributes specified are optional. The Device element creates a model inside the LAN Topology_Container model. The ip_dnsname attribute is a required attribute for the Device element. If the device can be contacted by SPECTRUM, the IP Address or the DNS name is used to find the device. When SPECTRUM locates the device, it determines the appropriate model type to use to create the model. If the device is not SNMP compliant, assign any string value to the ip_dnsname attribute, and use the model_type attribute to define what type of model SPECTRUM should create. For a complete reference of these elements and their possible attributes, see Appendix A: Element Definition [Page 37]. Location View To create your topology information in the Location View of SPECTRUM, construct your XML file using the Location element inside the Import root element. The Location element can contain Location_Container elements to create a specific kind of container model, or Device elements to create a specific type of device model. Page 23

24 The following is a basic example that shows a Site container created in the Location view and a device within that container. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Location> <Location_Container model_type = Site name = My_Town > <Device ip_dnsname= community_string= public /> </Location_Container> </Location> </Import> The Import element is the root element and is always contained in the input file. The Location element indicates that you are creating models in the Location view. The Location_Container element creates a container model. Since this model is a logical component rather than a physical component of the network, SPECTRUM does not have the ability to contact it and define the model type using an IP address or a DNS name. To indicate the type of contain model to create, you must provide a value for the model_type attribute. The possible model_type attribute values are listed in the DTD and under the Location_Container element definition in Appendix A. The name attribute is required and must specify a unique name for the model. The Device element creates a model inside the Site Location_Container model. The ip_dnsname attribute is a required attribute for the Device element. If the device can be contacted by SPECTRUM, the IP Address or the DNS name is used to find the device. When SPECTRUM locates the device, it determines the appropriate model type to use to create the model. If the device is not SNMP compliant, assign any string value to the ip_dnsname attribute, and use the model_type attribute to define what type of model SPECTRUM should create. For a complete reference of these elements and their possible attributes, see Appendix A: Element Definition [Page 37]. Representing the Same Device in Multiple Views It is possible to create an XML file that represents a device in multiple views. When doing this, it is highly recommended that each of the Device Page 24

25 elements used to create a model of this device have identical attributes and attribute values. If they are not identical, the import tool will attempt to merge all of the attributes and values of these Device elements to create a set of consistent attributes and values. If an attribute is specified in each of these Device elements, but different values are used, the value used by the last Device element listed in the XML file will override all previous values for that attribute in the other Device elements used to create a model of that device. It is important to remember that some attributes have default values. For example, the default value of the attribute community_string is public. Therefore, if you specify an attribute and value in one Device element used to represent device A, it is recommended that you specify it in any other Device element used to represent device A to ensure that a default value for that attribute is not used to override the previously specified value. In the example below device is created in the Topology and Location views. Note that the attributes and values used to describe the device is the same for both views. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <!-- Topology View import --> <Topology discover_connections="false" complete_topology="false"> <Device ip_dnsname=" " community_string="zippo" /> </Topology> <!-- Location View import --> <Location complete_topology="true"> <Location_Container model_type="site" name="durham"> <Device ip_dnsname=" " community_string= zippo /> </Location_Container> </Location> </Import> Synchronizing Information between SPECTRUM and the Third-Party base The Topology, Location, Topology_Container, and Lan_Container elements have an attribute called complete_topology. If you set the value of this attribute to true, then you are indicating that the XML file defines all Page 25

26 of the models and connections that SPECTRUM needs to know about. When the XML file is imported into SPECTRUM, any models that exist in that SPECTRUM view, but are not represented in the XML file, are sent to the lost and found. If there are sub-containers in the view, SPECTRUM refers to the value of the complete_topology attribute set in the element specifying the sub-container. If the complete_topology attribute value is not specified in the sub-container element, the value is inherited from the parent element. Thus, if the parent element has a complete_topology setting of true and the sub-container element does not specify a setting for complete_topology, the complete_topology value for the sub-container is also true. When SPECTRUM imports the XML file, all models that exist either directly in the view you are importing into or in the sub-container of that view, but do not exist in the XML file, will be sent to the lost and found. This attribute is useful when synchronizing the data in your thirdparty database with the data in SPECTRUM. In the example below, complete_topology is set to true within the Topology element. Except for models specified in this input file, all existing models in the Topology view would be sent to the lost and found. With this sample input file there are only two models specified, the LAN Topology Container and the device at IP address If these models did not exist, they would be created. If they already existed, SPECTRUM would update their SPECTRUM attribute values based on the attribute values in the input file. Any other model existing in the Topology view (with the exception of the VNM) would be sent to the lost and found. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Topology complete_topology= true > <Topology_Container model_type = LAN name = Sample_LAN security_string = public subnet_address= subnet_mask = > <Device ip_dnsname= community_string= public /> </Topology_Container> </Toplogy> </Import> If the complete_topology attribute were used in the Topology_Container element instead of the Topology element, SPECTRUM would only remove unspecified models from that Topology_Container down through the hierarchy. Page 26

27 Connections A SPECTRUM connection represents a physical or logical link between two devices. It is possible to create connections two different ways in the XML input file. The first method makes use of SPECTRUM s AutoDiscovery function. This is done via the discover_connections attribute of the Topology element. When this attribute is set to true, AutoDiscovery runs on the newly created device models and connectivity for these devices is established. For more information on AutoDiscovery, see the AutoDiscovery User s Guide (0727). <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Topology discover_connections= true > <Topology_Container model_type = LAN name = Sample_LAN security_string = public subnet_address= subnet_mask = > <Device ip_dnsname= community_string= public /> <Device ip_dnsname= community string= public /> </Topology_Container> </Toplogy> </Import> The second way to create connections is to use the Connection element, which connects devices that are already created. Connections can be specified between two ports, between a device and a port, or between two devices. Connectivity information allows SPECTRUM to properly detect and diagnose faults on your network. Specifying connectivity between devices allows SPECTRUM to isolate faults to the device, but specifying port level connections is preferred. Port level connections are a finer grade of connectivity allowing SPECTRUM to resolve the connections and analyze faults at the port level. If you specify a connection between two devices, but do not specify either one or both ports used in the connection, SPECTRUM will automatically attempt to determine these ports. If this process is successful, SPECTRUM resolves the connection to the port level. If SPECTRUM is unable to determine both ports used in the connection, and if at least one of these devices is a manageable device, SPECTRUM will Page 27

28 generate an error indicating a connection failure. This error will be written to the error log file (see The Error Log and the Debug Log [Page 36]). If SPECTRUM is only able to determine one of the ports, then the connection will only be resolved to the port level on one side of the connection, the other side will remain resolved to the device level. If both devices are unmanageable devices, SPECTRUM will establish the connection at the device level. The following example creates a connection between two existing ports; each port belonging to a different device. The Connection element identifies both the Port and Device elements to be linked. The connection is resolved at the port level for both devices because a Port element is specified within each Device element. The Connection element has an optional attribute called create_pipes. When create_pipes is set to true, a graphical representation of the connection is created in the SpectroGRAPH. By default create_pipes is set to true. Set create_pipes to false for circuit link connections to avoid having a large number of connections crowd the view. In this example, connect_pipes is set to false, so a graphical representation of the connection is not created in SPECTRUM. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Connection create_pipes= false > <Device ip_dnsname= > <Port identifier_name = frcircuittableinstance identifier_value= /> </Device> <Device ip_dnsname = > <Port identifier_name= frcircuittableinstance identifier_value= /> </Device> </Connection> </Import> This example above specifies a connection between DLCI ports. Since the value of the identifier_name attribute is frcircuittableinstance, the port is identified using the OID instance value from the frcircuittable object in the MIB. The OID instance value is specified using the identifier_value attribute. Page 28

29 The Connection element be been contained within a Topology element or a Topology_Container element to indicate the hierarchical placement of the devices. This does not change the results of the input file. Note: will not report an error if you attempt to import an XML file that contains multiple Connection elements using the same Port element. It is not possible for a single port to have multiple connections. If the same port is specified in multiple Connection elements, the last Connection element in the XML file will override all previous Connection elements specifying that port. Updating Information The Update element is used to update SPECTRUM attribute information for existing models. The Update element can enclose Container elements and/ or Device elements. The value of Port attributes is updated using the appropriate Device element. Below is an example of an update input file where two different attributes for two separate models are updated. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Update> <Topology_Container model_type= LAN name= Sample model_name = newlan /> <Device ip_dnsname= Test1 poll_interval= 1108 /> </Update> </Import> The first updated attribute is the model_name attribute of the LAN container model. The model name is changed from Sample to newlan. Note the use of the attributes name and model_name. Both of these attributes exist to change the SPECTRUM attribute Model_Name. Use the name attribute with the current name as the value to identify the container model. Then use the model_name attribute to specify the new name of the container model. Next, the example changes the value of the poll interval for the device from Test1 to Assigning a new value to the poll_interval attribute overwrites the old value. Note that the Topology_Container element and the Device element are not nested and do not represent any sort of hierarchy. The only hierarchy that can be specified within the Update element is the hierarchy of a Device and Page 29

30 a Port. Nesting a Container and a Device within an Update element processes syntactically, but produces irregular results. Destroying Information The Destroy element deletes container models, device models, and connections. When you destroy a device, all port and application models associated with the device are also destroyed. In the example below, the LAN topology container called newlan is destroyed. Note that all models within this container are sent to the SPECTRUM lost and found, unless they are specified to be destroyed. This example also destroys a connection between two devices (Test1 and Test2), which is specified at the port level. <?xml version = 1.0 standalone = no?> <!DOCTYPE Import SYSTEM.import.dtd > <Import> <Destroy> <Topology_Container model_type= LAN name= newlan /> <Connection> <Device ip_dnsname= Test1 > <Port identifier_name= ifindex identifier_value= 1 /> </Device> <Device ip_dnsname= Test2 > <Port identifier_name= ipaddress identifier_value = /> </Device> </Connection> </Destroy> </Import> The Topology_Container and Connection are not nested in the example above. The only hierarchy that should be expressed in the Destroy element is the Connection, Device, and Port hierarchy necessary to delete connections at the port level. An example of this hierarchy is shown above where the connection between a port on Test1 and a port on Test2 is deleted. The actual devices, Test1 and Test2, are not deleted. To destroy a model representing a device that has already been removed from the network, use the IP address of the device rather than the DNS name when specifying the ip_dnsname attribute of the Device in the Destroy element of an XML file. This is important because once the device Page 30

31 has been removed from the network, the DNS entry for that device will no longer exist, and the cannot identify the appropriate model to delete. The tirc.xml Resource File The Topology_Container, Location_Container, and Device elements have a model_type attribute that must have a value equal to a valid SPECTRUM model type. SPECTRUM uniquely identifies model types using a hexadecimal number. These hexadecimal values have been enumerated in the resource file tirc.xml. This file pairs and a text value for the model type with the unique hexadecimal identifier. The text values are then shown in the DTD. Many of the attributes defined in the DTD correspond to SPECTRUM attributes. SPECTRUM attributes are uniquely identified in SPECTRUM using a hexadecimal number. Rather than use these hexadecimal values in the DTD or in the XML file, the tirc.xml file pairs the SPECTRUM attributes hexadecimal identifiers with more intuitive text-based names. Both the ModelType element and the Attribute element of the tirc.xml file can be customized. Working with a Comma-Delimited Input File In addition to specifying ATM and Frame Relay connectivity via an XML input file, the toolkit can accept ATM and Frame Relay connectivity information via a comma-delimited ASCII text file. This file can be used to import information about connections between two ATM circuits, two Frame Relay circuits, or an ATM and a Frame Relay circuit. You have the option to specify that a live pipe be created in the SpectroGRAPH to represent the connection. Multiple connections can be specified in the same input file. The device models involved in these connections must already exist in SPECTRUM. Following is the format for the input file: <Device_IP>, <OID>, <Device_IP>, <OID>, <CircuitName>, <CircuitID>, <Pipe> Device_IP is the IP address of each device involved in the connection. This parameter is required for each device. OID is the OID instance of frcircuittable, atmvcltable or atmvpltable to specify the circuit link on the device. This parameter is required for each device. Page 31

32 CircuitName is an optional parameter specifying the name of the circuit involved. CircuitID is an optional parameter specifying the ID of the circuit involved. Pipe is an optional parameter with two possible values, CREATE_PIPE or NO_CREATE_PIPE. If the value is set to CREATE_PIPE, live pipes will be created between the connections specified. If the value is set to NO_CREATE_PIPE, live pipes will not be created between the connections specified. If no value is specified for this parameter, a default value of CREATE_PIPE is assumed. The following example shows an input file that specifies the connection between two frame relay circuits. There will be a live pipe created between these two ports , 4.161, , 2.161, FR_Circuit_Name, Circuit_Id_123, CREATE_PIPE Importing the Input File Once you have set up the input file, use the import tool to send the network data into the SpectroSERVER database. The import tool is a command line utility that is located in SPECTRUM s SS-Tools directory and can be run on a SpectroSERVER or on another host machine. If you would like to run the tool on another machine, you must move the tool and all of its support files to that machine. Moving the topimport Tool The toolkit provides a script that packs up the topimport tool so that it can be sent via FTP to another machine. The script ensures that the relative directory structure of the tool and its support files is retained when the files are moved. The following steps show you how to move these files: 1. On the SpectroSERVER, check to make sure the environmental variable SPECROOT is set to the SPECTRUM installation directory path. 2. Run the script that packs up the tool and its support files. The script can be found in SPECTRUM s SS-Tools directory and is called packtool.pl. To run the script from the Bash shell or other Unix shell, type: Page 32

33 <Spectrum_Installation_Path>/SS-Tools/packtool.pl topimport Where <Spectrum_Installation_Path> is the directory structure where SPECTRUM is installed on your SpectroSERVER. 3. The script generates an executable file called topimport_bundle (Unix) or topimport_bundle.exe (Windows) that contains the topimport tool and all of its support files. 4. On the third-party host, create a new directory to unpack the topimport tool and its support files, i.e. /disk/spectrum. 5. FTP the topimport_bundle or topimport_bundle.exe file from the SpectroSERVER to the third-party host, and place it in the directory created in step 4. Be sure to use binary mode during the FTP process. 6. Once the file is on the third-party host, execute the file from the DOS, Bash, or other Unix shell. The topimport tool and its support files will unpack into the appropriate directory structure. The topimport tool can now be run from this host machine. Note: Both servers involved in this process must be running the same operating system. You cannot pack the tool on a Windows server and unpack it on a Unix machine or vise versa. Running the topimport Tool In order to run the topimport tool from a machine other than the SpectroSERVER, you must set the SPECROOT (Unix) or SPECPATH (Windows) environmental variable on this machine equal to the path to the directory where you placed the topimport_bundle or topimport_bundle.exe file. For example, if you are working in the Unix environment and placed the topimport_bundle file in /disk/spectrum as in step 4 in Moving the topimport Tool [Page 32], then you must set SPECROOT=/disk/Spectrum. If you are working in the Windows environment and placed the topimport_bundle.exe file in C:\disk\Spectrum, then you must set SPECPATH=C:\disk\Spectrum. The syntax to run the tool is outlined below. It takes 4 arguments, two are required and two are optional. topimport -vnm <vnm_name> -i <input_file> [-o <outputfile>] [-debug] Page 33