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:
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.
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.
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.
You can start the topology export utility from the main console window or the CLI, which is described in Import and Export CLI Interface.
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.
You can start the topology import utility from the main console window or the CLI, which is described in Import and Export CLI Interface.
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.
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.
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:
Replaces the conflicting data with new values.
Replaces all conflicting data. The dialog box does not appear when the data conflict occurs again, and the old value is replaced
Do not update the conflicting data.
The dialog box does not appear when another data conflict occurs. All conflicts are ignored and are left unchanged.
Stops the import operation.
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.
The import command retrieves previously exported topology data for the specified domain from a file.
The import command takes the following parameters:
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.
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.
The value of the filename parameter is the name of the file from which the topology information should be retrieved.
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.
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 |
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.
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.
The export command saves the topology data for a domain, or for all domains, to a file.
The export command takes the following parameters:
The value of the comment parameter is an annotation to be included in the file.
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.
The value of the filename parameter is the name of the file to which the topology information should be exported.
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.
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
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" |
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.
The following list identifies the topology data that the import and export utilities process.
The record information about every domain, group and host.
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.
The relationship information describes the topology hierarchy, entity background and layout.
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.
The file is separated into four parts:
Magic information
DTD (Document Type Declaration)
Header information
Data blocks
The magic information identifies that the file is an XML format file. Typically, this information appears as follows:
<? XML version = 1.0 ?> |
The DTD information defines the structure of the document. The DTD of an export file resembles the following example.
<!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> ]> |
The header information is used to record the general information, such as the following:
User
Data
Version
Platform
Product
Data blocks contain the topology hierarchy architecture and entities.
The following figure illustrates the topology for the 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>