Sun Management Center 3.6.1 User's Guide

Chapter 19 Importing and Exporting Topology Information

The topology import and export utilities enable you to import and export the topology database from or to an ASCII file that uses XML markup. The import utility enables you to read data from a file and update the topology database and the data of the topology agent object. The export utility reverses this operation.

This chapter explains the following topics:

Topology Import and Export Concepts

The topology import and export utilities are used to do the following tasks:

Dump the topology data as backup regularly.
Transfer data between different topology servers.
Restore the data from backup if the topology data is damaged.
Convert the data into another file format, and load the data into another management system in a third-party management platform.

You can access these functions from the Sun Management Center console main window or the CLI. You must specify the complete topology data and the domains to be imported or exported. The tool supports several methods of data handling, including overwrite and append.

The import and export utilities support domain level operation. You can specify one domain to export or the whole topology hierarchy.
You can recover backup data through the import utility.
You can import objects of any domain to one domain.
You can back up existing data through the export utility.
You can export data in incremental mode.
You can export topology information from the main console window only when the current topology hierarchy contains data.

Topology Import and Export Architecture

The topology import and export utilities communicate with the Sun Management Center server through client APIs. The import and export ASCII file resides on the console system. This file provides information through the client APIs to the server. The server sends that information to the topology agent which interacts with the topology database. The following figure shows the software structure that supports these utilities.

Figure 19–1 Software Structure for Importing and Exporting Topology

Diagram shows import/export file communicating with console import/export
tool which communicates with server side through topology agent to database.

For export, two modes are provided: Append and Overwrite. In Overwrite mode, the dumped data replaces the contents of an existing file. In Append mode, the dumped data is added to the end of the file.

For import, two modes are provided to process the domain information that is contained in the dumped file. The first mode is to ignore the domain information. All objects are created in the specified or home domain. The second mode is to import domain information together with all other objects. In this case, new domains can be created. All nondomain objects are created in the corresponding domain.

Exporting Topology Information

You can start the topology export utility from the main console window or the CLI, which is described in Import and Export CLI Interface.

To Export Topology Data From the Main Console Window

Choose Export Topology from the Tools menu in the main console window.

The Export Topology dialog box appears.

Select a domain from the Export Domain Name list.

The list shows all domains managed by the topology agent. You can select one domain to export. To export multiple domains, you can repeat the preceding operation to export another domain in the append mode.

Type the name of the file to be exported, or select an existing file by using the Browse button.

To export a file, you must have permission to write to the file or to create the file. Otherwise, an error message is displayed and the operation exits.

Determine whether to append data to or overwrite data in an existing file.

Append mode appends the data at the end of the file. Overwrite mode overwrites the file. When Append mode is used in the export, a more restrictive check is performed on the file. The existing file must be a valid import and export data file. A valid data file is a well-formed XML file with correct import and export file document type declaration (DTD).

Choose the number of days for which the data is valid from the Valid for Days menu.

You can choose from the following values:
- 7 days
- 15 days
- 30 days
- 90 days
By default, topology export data is valid for an unlimited number of days.

(Optional) Provide comments about this export function.

Click OK to export the data to the specified file and close the Export Topology window.

Importing Topology Information

You can start the topology import utility from the main console window or the CLI, which is described in Import and Export CLI Interface.

To Import Topology Data From a File

Select Import Topology from the Tools menu in the main console.

The Import Topology window appears.

Type the full path name to the file that contains topology data to import.

Tip –
You can also use the Browse button to find the file.

Determine whether to import everything in the topology or only groups and entities.
- Follow – Imports groups and domain information. The groups and entities are created in the domain contained in the file.
- Ignore – Ignores the domain information and imports only groups and entities to the target domain that you specify.

Select the domain to which to import the data from the Name list.

All data is imported into the home domain by default.

Note –
You can specify the location in the topology hierarchy to which the data will import only if you chose the Ignore option in the previous step.

Click OK to import the data and close the Import Topology window.

The import utility updates the topology database. Therefore, a warning dialog box allows you to confirm the operation before the data is imported.

The warning dialog box tells you when the input file was generated and who generated the file. This warning helps you to ensure that the correct data file is being used.

Several additional checks are performed:
- Exported data files include information about the validity time of the file. If you are trying to import an out-of-date file, you receive an error message and the operation stops.
- The import utility checks that the file exists and that the file is readable. If these checks fail, you receive an error message, and the operation stops.
- For the import utility to analyze the import file, the file format must be correct. If the file is formatted incorrectly, the import utility generates an error message.
- If the entity exists in the current topology hierarchy, another warning dialog box asks whether the entity should be replaced. Select one of the following options:
  
  Replace
  
  Replaces the conflicting data with new values.
  
  Replace All
  
  Replaces all conflicting data. The dialog box does not appear when the data conflict occurs again, and the old value is replaced
  
  Ignore
  
  Do not update the conflicting data.
  
  Ignore All
  
  The dialog box does not appear when another data conflict occurs. All conflicts are ignored and are left unchanged.
  
  Cancel Import
  
  Stops the import operation.

Import and Export CLI Interface

You can invoke the import and export utilities from CLI with the following commands:

# /opt/SUNWsymon/sbin/es-cli
> login
Host: servername
Login: username
Password: password
Login successful!
> export parameter
> import parameter

See Import Command Parameters and Export Command Parameters for information about appropriate command parameters.

Topology Import Utility

The import command retrieves previously exported topology data for the specified domain from a file.

Import Command Parameters

The import command takes the following parameters:

domain: The value of the domain parameter is the name of the domain whose topology is to be imported. If no domain is specified, all domains are imported.
domainmode: The value of the domainmode parameter determines whether new domains are created from the imported topology. If the value is follow, then group and domain topology are imported into the current topology, and new domains can be created. If the value is ignore, then only groups and entities are imported to the specified target domain.
filename: The value of the filename parameter is the name of the file from which the topology information should be retrieved.
nodemode: The value of the nodemode parameter determines whether the imported topology replaces the existing topology. If the value of the nodemode parameter is replace, then conflicting data is replaced with the imported values. If the value of the nodemode parameter is ignore, then conflicting data is not updated.

The explicit assignment in the command line overrides the same assignment in the parameter file. For example, if mode=ignore is assigned in the command line and mode=follow is assigned in the parameter file, then mode=ignore is used.

Example 19–1 Importing Topology Data from a File

In the following example, previously exported topology is imported from the file /home/examples/snapshot. New domains are created as necessary, and conflicting data is replaced by the imported topology.

> import filename=/home/examples/snapshot domainmode=follow \
nodemode=replace

Confirmation Messages

The import utility prompts you to answer the following items before the operation is done or when the data conflicts:

Warning message for confirmation – The following message asks you to confirm the import operation.

The data being used is exported by <user name> on <mm/dd/yyyy>.
The import operation will modify your topology database, are you sure you want to do this?
[Yes/No]

Enter y for Yes or n for No.

Output Messages for the Import Command

This section describes the messages that might appear as a result of the import command.

import: Results 1/1

State=Success

Message=The topology data is successfully imported.

Cause:

Success.

Description:

The operation completed successfully.

filename: No such file.

Cause:

File does not exist.

Description:

The specified file does not exist. The command line might use two files: a data file that provides the import data source, and a parameter file that provides a parameter list.

import: Cannot open filename.

Cause:

Permission denied.

Description:

The file cannot be opened for reading.

import: File format is not supported.

Cause:

Format wrong.

Description:

The source file is not a valid database file for exporting data.

import: File out-of-date (xx days).

Cause:

Data out-of-date.

Description:

You are using out-of-date data.

import: Authentication failed.

Cause:

Authentication failed.

Description:

The current user has no authority to create objects in the topology hierarchy.

import: Wrong parameter file.

Cause:

Parameter file error.

Description:

The parameter file should be a list of name = value pairs. If the format is not correct, the application generates an error message and stops.

import: illegal parameter - <para>.

Use -h option to get usage.

Cause:

Illegal parameter.

Description:

An illegal parameter has been passed to the import operation. Use import -h to view the available options and the available parameters.

Topology Export Utility

The export command saves the topology data for a domain, or for all domains, to a file.

Export Command Parameters

The export command takes the following parameters:

comment

The value of the comment parameter is an annotation to be included in the file.

domain

The value of the domain parameter is the name of the domain whose topology is to be exported. If no domain is specified, all domains are exported.

filename

The value of the filename parameter is the name of the file to which the topology information should be exported.

mode

The value of the mode parameter determines how the topology information is incorporated into the file. If the value is append, then the data is appended to the contents of the file. If the value is overwrite, then the previous contents of the file are replaced by the new data.

validity

The value of the validity parameter is the length of time in days for which the data is valid. The following values are legal values for the validity parameter:

Unlimited
7
15
30
90

Example 19–2 Exporting Default Domain Topology to a File

In the following example, the Default Domain is saved to a file that is named snapshot. The original contents of snapshot are overwritten by the new data. The new data is assumed to be valid for an unlimited period of time. The comment specifies that this data is for the system testing group.

> export filename=/home/examples/snapshot \
domain="Default Domain" mode=overwrite validity=Unlimited \
comment="System Test Group"

Output Messages for the Export Command

The following list shows the messages that might appear as a result of the export command.

Export: Results 1/1

State=Success

Message=The topology data is successfully exported.

Cause:

Success.

Description:

The operation completed successfully.

export: Cannot open file.

Cause:

File does not exist.

Description:

The parameter file does not exist.

filename: Permission denied.

Cause:

File error.

Description:

The file cannot be created or be opened for writing.

export: File format not supported.

Cause:

Format wrong.

Description:

The error occurs when appending the export data to a file that is not a valid export data file.

export: The domain <domainname> does not exist

Cause:

Object error.

Description:

The domain that you want to export does not exist.

export: Wrong parameter file.

Cause:

Parameter file error.

Description:

The parameter file contains a list of name = value pairs. If the file format is not correct, the application notifies you and stops.

export: The current user is different from the last one.

Cause:

User conflict.

Description:

The error occurs when you try overwrite or append the data to an existing data file created by others. You cannot modify or overwrite export data that another user created.

export: Data is out-of-date.

Cause:

Data is too old.

Description:

You are using an out-of-date export file. This message only occurs when you export data in append mode.

export: illegal parameter - <para>.

Please use -h option to get usage.

Cause:

Illegal parameter.

Description:

An illegal parameter was passed to the export operation.

Import and Export File Contents

The following list identifies the topology data that the import and export utilities process.

Entity information: The record information about every domain, group and host.
Adornment information: The adornment information about domains and groups. The adornment information contains only the layout and background index instead of the background content. For example, the information about background only contains the GIF file name, not the GIF file.
Relationship information: The relationship information describes the topology hierarchy, entity background and layout.

File Format Description

The Import/Export file describes the import and export data. You can use any text editor to edit this file. The file includes information about every entity in the topology hierarchy. Because the append export mode can append more object information to the file, the format is easy to extend and analyze. The exported data is saved in XML format.

File Format Design

The file is separated into four parts:

Magic information
DTD (Document Type Declaration)
Header information
Data blocks

Magic Information

The magic information identifies that the file is an XML format file. Typically, this information appears as follows:

<? XML version = 1.0 ?>

DTD (Document Type Declaration)

The DTD information defines the structure of the document. The DTD of an export file resembles the following example.

Example 19–3 Import and Export File DTD

<!ELEMENT ENTITY (ENTITY* ADORNMENT*)>	
/* Entity element describes a entity. If it is a group, it may 
   contain groups and adornment. */
		<!ATTLIST ENTITY			/* Entity attributes */
			desc		CDATA
			full_desc	CDATA
			hostname	CDATA
			ip	CDATA
			netmask	CDATA
			architecture	CDATA
			family	CDATA
			polling_type	CDATA
			url	CDATA
			x_coord	CDATA
			y_coord	CDATA
			topology_type	CDATA
			event_dest	CDATA
			trap_dest	CDATA
			target_host	CDATA
			target_ip	CDATA
			read_info	CDATA
			write_info	CDATA>
	<!ELEMENT ADORNMENT>
		<!ATTLIST ADORNMENT
			x_coord	CDATA
			y_coord	CDATA
			type	CDATA
			configuration	CDATA>
	]>

Header Information

The header information is used to record the general information, such as the following:

User
Data
Version
Platform
Product

Data Blocks

Data blocks contain the topology hierarchy architecture and entities.

Topology and Export File Example

The following figure illustrates the topology for the My New domain.

Figure 19–2 My New Topology Example

Partial Sun Management Center console window shows a fairly small
network that has a campus, three host objects, a subnet, and a folder.

Example 19–4 Export File for My New Domain

This example shows a topology export file for the My New domain.

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
  <HEAD>	
    <USER>jkang</USER>
    <DATE>1/7/1999</DATE>
    <VALIDITY>7 days</VALIDITY>
    <PRODUCT>Sun Management Center</PRODUCT>
    <VERSION>3.6.1</VERSION>
    <COMMENTS>This is an example.</COMMENTS>
  </HEAD>
   <DOMAIN name="my new">
      <ENTITY arch="SunOS 5.8" config="" desc="wizard" entityId="e-1" 
        family="sun4u-Sun-Ultra-2" fulldesc="wizard" hostname="wizard" 
        ipAddr="129.158.168.63" isPoll="false" isSoftGroupLink="false" 
        netMask="255.255.255.0" pollType="ahost" readInfo="" targetHost="" 
        targetIp="" targetUrl="snmp://129.158.168.63:1100/sym//base/mibman/modules" 
        type="" writeInfo="" xCoord="23" yCoord="39" 
      />
      <ENTITY arch="SunOS 5.8" config="" desc="atom" entityId="e-2" 
        family="sun4u-Sun-Ultra-2" fulldesc="" hostname="u30-1" 
        ipAddr="129.158.168.113" isPoll="false" isSoftGroupLink="false" 
        netMask="255.255.255.0" pollType="ahost" readInfo="" 
        targetHost="" targetIp="" 
        targetUrl="snmp://129.158.168.113:161/sym//base/mibman/modules" 
        type="" writeInfo="" xCoord="75" yCoord="39" 
      />
      <ENTITY arch="" config="" desc="campus" entityId="e-3" family="campus-view" 
        fulldesc="" hostname="" ipAddr="" isPoll="true" isSoftGroupLink="false" 
        netMask="" pollType="aview" readInfo="espublic" targetHost="" targetIp="" 
        targetUrl="snmp://129.158.168.63:164/mod/topology+view-101" 
        type="" writeInfo="" xCoord="27" yCoord="111">
        <ENTITY arch="" config="" desc="building" entityId="e-1" 
          family="building-view" fulldesc="" hostname="" ipAddr="" 
          isPoll="true" isSoftGroupLink="false" netMask="" pollType="aview" 
          readInfo="espublic" targetHost="" targetIp="" 
          targetUrl="snmp://129.158.168.63:164/mod/topology+view-102" 
          type="" writeInfo="" xCoord="" yCoord="">
          <ENTITY arch="SunOS 5.8" config="" desc="Wizard" entityId="e-1"
            family="sun4u-Sun-Ultra-2" fulldesc="" hostname="wizard" 
            ipAddr="129.158.168.63" isPoll="false" isSoftGroupLink="false" 
            netMask="255.255.255.0" pollType="ahost" readInfo="" 
            targetHost="" targetIp=""
            targetUrl="snmp://129.158.168.63:1100/sym//base/mibman/modules" 
            type="" writeInfo="" xCoord="" yCoord="" 
          />
          <ENTITY arch="SunOS 5.8" config="" desc="aaa" entityId="e-2" 
            family="sun4u-Sun-Ultra-2" fulldesc="" hostname="wizard" 
            ipAddr="129.158.168.63" isPoll="false" isSoftGroupLink="false" 
            netMask="255.255.255.0" pollType="ahost" readInfo="" 
            targetHost="" targetIp=""
            targetUrl="snmp://129.158.168.63:1100/sym//base/mibman/modules" 
            type="" writeInfo="" xCoord="" yCoord="" 
          />
          <ENTITY arch="SunOS 5.8" config="" desc="atom" entityId="e-3" 
            family="sun4u-Sun-Ultra-2" fulldesc="" hostname="u30-1" 
            ipAddr="129.158.168.113" isPoll="false" isSoftGroupLink="false" 
            netMask="255.255.255.0" pollType="ahost" readInfo="" 
            targetHost="" targetIp="" 
            targetUrl="snmp://129.158.168.113:161/sym//base/mibman/modules" 
            type="" writeInfo="" xCoord="" yCoord="" 
          />
      </ENTITY>
    </ENTITY>
    <ENTITY arch="" config="" desc="129.158.0.0" entityId="e-4" 
       family="network-view" fulldesc="129.158.0.0" hostname="129.158.0.0" 
       ipAddr="129.158.0.0 isPoll="true" isSoftGroupLink="false" 
       netMask="255.255.255.0" pollType="aview" 
       readInfo="espublic" targetHost="129.158.0.0" targetIp="129.158.0.0" 
       targetUrl="snmp://129.158.168.63:164/mod/topology+view-103" type="" 
       writeInfo="" xCoord="38" yCoord="181">
       <ENTITY arch="" config="" desc="129.158.168.0" entityId="e-1" 
          family="subnetwork-view" fulldesc="129.158.168.0" 
          hostname="129.158.168.0" ipAddr="129.158.168.0" 
          isPoll="true" isSoftGroupLink="false" netMask="255.255.255.0" 
          pollType="aview" readInfo="espublic" targetHost="129.158.168.0" 
          targetIp="129.158.168.0" 
          targetUrl="snmp://129.158.168.63:164/mod/topology+view-104" 
          type="" writeInfo="" xCoord="" yCoord="">
          <ENTITY arch="SunOS 5.8" config="" desc="wizard" entityId="e-1" 
           family="sun4u-Sun-Ultra-2" 
           fulldesc="SUNW,Ultra-2" hostname="wizard" ipAddr="129.158.168.63" 
           isPoll="false" isSoftGroupLink="false" netMask="255.255.255.0" 
           pollType="ahost" readInfo="public" targetHost="" targetIp="" 
           targetUrl="snmp://129.158.168.63:1100/sym//base/mibman/modules"
           type="" writeInfo="" 
           xCoord="" yCoord="" 
          />
        </ENTITY>
      </ENTITY>
      <ENTITY arch="" config="" desc="myworkstation" entityId="e-5" 
        family="nonagent-sun4u-Sun-Ultra30" fulldesc="" hostname="wizard" 
        ipAddr="129.158.168.63" isPoll="false" isSoftGroupLink="false" 
        netMask="" pollType="snmp" readInfo="public" targetHost="" 
        targetIp="" targetUrl="snmp://wizard:1100/oid//1.3.6.1.2.1.1.7.0"
        type="" writeInfo="private" xCoord="52" yCoord="253" 
      />
      <ENTITY arch="SunOS 5.8" config="" desc="System Group" entityId="e-6" 
        family="base-agent" fulldesc="MIB tree branch" hostname="wizard" 
        ipAddr="129.158.168.63" isPoll="false" isSoftGroupLink="false" 
        netMask="255.255.255.255" pollType="amod" readInfo="" 
        targetHost="wizard" targetIp="129.158.168.63"
        targetUrl="snmp://129.158.168.63:1100/mod/mib2-simple/system" 
        type="" writeInfo="" xCoord="52" yCoord="329" 
      />	
   <ADORNMENT Config="bus" Id="adorn-7" Type="layout" XCoord="0" YCoord="0" />
   </DOMAIN>
</DOCUMENT>