Chapter 13 |
Composite Objects |
The composite object interface allows you to define your own composite objects. You can define a hierarchy of groups, modeled agents, agents, and/or modules. Once a composite objects is properly defined, you can add it to the topology view by using the discovery interface or by using the "Edit -> Create an Object..." menu choice from the main window of the Sun Management Center software.
You can implement the Discovery Object Table as a Sun Management Center module or by taking the Discovery Object Table MIB, provided in "Discovery Object Table MIB", and implementing the Discovery Object Table in a language that supports SNMP. You can then use the es-dt script on the Sun Management Center agent machine to add a reference to the Discovery Object Table. The composite object can now be discovered or added with "Edit->Create an Object."
This chapter provides examples on how to customize Sun Management Center using the Interface for the Discovery of Composite Objects. A troubleshooting section provides information on common problems.
This section describes procedures that relate to discovering composite objects.
![]() |
To Add a Composite Object |
1. | Implement your Discovery Object Table on an agent machine in one of the following ways: |
Note - After implementing the Discovery Object Table as a module, it must be properly loaded on a Sun Management Center agent or platform agent machine.
2. | Model the composite object by using the es-device script on the Sun Management Center server machine.
|
where example-composite.conf is the es-device input file. |
Note - Note that the device is modeled on the server machine. Refer to Chapter 14 for more information. Note also that running es-device with the appropriate input file adds the composite object to the "Edit -> Create an Object..." menu choice on the Sun Management Center main console window. Though these are listed in the menu, they will not successfully allow you to add a composite object until all the three steps listed in this section are performed.
3. | Add a Reference to the Discovery Object Table: |
a. | Stop the Sun Management Center agent process. |
b. | Run the es-dt script with the -a option, for example, to add a composite
object, enter the following:
|
Note - The user does not necessarily run the es-dt command on the same agent machine where the Discovery Object Table is installed. When using the Discovery Interface or "Edit -> Create an Object..." to build the composite object, specify the machine where the es-dt script was executed.
The above command adds a composite object that is defined at the specified hostname/port/OID. The label and Node_Object_Type (not) fields should correspond to the top-level composite_group object implemented in the Discovery Object Table. Restart the Sun Management Center console for any internationalized text to properly appear. |
c. | Restart the Sun Management Center agent process. |
![]() |
To Remove a Composite Object |
Note - The user does not necessarily run the es-dt command on the same agent machine where the Discovery Object Table is installed.
Note the following:
1. | Remove the reference to the Discovery Object Table with the following procedure: |
a. | Stop the Sun Management Center Agent process.
|
b. | Run the es-dt script with the -d option on the same Sun Management Center
agent machine where the reference to the Discovery Object Table was added
(this means the same machine where the es-dt script was run with the -a
option).
|
es-dt -d -n Node_Object_Type |
Note - All Discovery Object Table references have a unique label, so deleting by label will delete a single entry. Multiple references can have the same Node_Object_Type, so deleting by Node_Object_Type can delete more than one value.
c. | Restart the Sun Management Center agent process.
|
2. | If you implemented the Discovery Object Table as a module, unload the Discovery Object Table implementation from the agent or platform agent machine where it was installed. |
For more information on loading and unloading a module, refer to "Loading & Unloading a Module in the Platform Agent". |
3. | Delete the Discovery Object Table implementation from the agent machine where it was installed. |
You must remove the module files that you implemented to create the Discovery Object Table, or, if you implemented this in your own language with the provided MIB, delete the implementation you wrote. |
4. | Remove any device models associated with the composite object by using the es-device script on the Sun Management Center server machine.
|
where example-composite.conf is the es-device input file. This is related to the note in Step 2 from the section on "To Add a Composite Object". |
You must remove the device modelling in order for the console to no longer show the Composite Object in the "Composite" tab of the "Edit->Create an Object..." window. This is done by running the es-device command with the -d option. Refer to Chapter 14 for more information.
The Discovery Object Table is defined as follows:
The fields are as follows:
TABLE 13-1 Discovery Object Table Descriptions magic_number This value must be hard coded to "53444f54", which is the hex representation of "SDOT", or Sun Management Center Discovery Object Table. This is used by the discovery process for table data validation. The discovery process will log an error message if the magic number validation fails.
entry This index is required for SNMP table ordering to insure that the table rows are in the appropriate order for discovery. The value must be unique for each row, a sequential number is sufficient.
dot_uniqueID This unique ID is stored in the database as the entity's unique key and is used to retrieve the entity in question. This can be set to any value; the topology has no restriction. The dot_unqiueID field for each entry in the composite object should be a static value, and not change over time. It is important that when discovery is rerun that the discovered entity is given the same uniqueID value. The person implementing the Discovery Object Table module is responsible for creating unique values for dot_uniqueID that will not conflict with any others. Sun Management Center internally uses the values: network_ipaddress, subnet_ipaddress, host_ipaddress, group_ipaddress (where ipaddress is the IP address of the machine), so values of this format should be avoided.
dot_topology_parent This is the dot_uniqueID value of the object's parent. Only objects of type composite_group can be a parent. An empty string or an invalid value will cause this object to be placed at the root of the Sun Management Center domain. There should only be one root-level parent for each composite object, and it must be specified on the first row of the Discovery Object Table.
dot_composite_type This integer field identifies what type of topology object is represented by this row in the Discovery Object Table. The following choices are available:
2 - composite_group 1 - composite_modeled_agent 3 - composite_agent 5 - composite_module See the following section describing the dot_composite_type for more information about these choices.
dot_ip_address For objects of composite_modeled_agent, composite_agent, and composite_module this corresponds to the IP address of the Sun Management Center agent. There is no IP address associated for objects of type composite_group, so this field is used to fill the dot_label and dot_description fields if they have zero-length entries.
dot_agent_port This corresponds to the port number of a Sun Management Center agent. For composite_modeled_agent and composite_agent objects, this field can be set to -1 which indicates that the normal set of port numbers will be used during discovery.
dot_node_object_type For objects of type composite_group, composite_agent, and composite_module this corresponds to the Node_Object_Type the user entered into the es-device script. Note that the user of the es-device script enters a Node_Object_Type for each row in the Discovery Object Table. This is used to specify things like the icon for each object within the composite object. If an invalid value is specified, the icon is a blue folder. See the "Special Behavior" section below to see how this field is handled for objects of type composite_modeled_agent.
dot_label The label string used for the object. For composite_modeled_agent objects, an empty string means default to the hostname. Otherwise, the results are not defined when an empty string is provided for this field. For composite_group, an empty string defaults to the dot_ip_address field.
dot_description The description string used when creating the object. An empty string may be specified if no description for the object is desired. Refer to the section on "Special Behavior" below for more information to see how this field is handled for objects of type composite_module.
A composite group must be the first entry of the composite object and cannot contain another composite_group. It can contain a composite_modeled_agent, composite_agent, and composite_module.
This is an icon, which when you click on it, displays the details window for the agent. A composite_modeled_agent represents an agent machine that is running the Sun Management Center agent process.
This is an icon, which when you click on it, displays the details window for the agent. A composite_agent represents an agent machine that is not running the Sun Management Center agent process.
This is an icon, which when you click on it, displays the details window for the agent containing just the specified module. A composite_module represents a module loaded on a Sun Management Center agent machine.
Some of the composite objects treat the fields in the Discovery Object table in unique ways. This is described as follows:
A composite_group must be the first row of the Discovery Object Table. This first row should be the only entry that has no value in the dot_topology_parent field.
Objects of this type try to determine the Node_Object_Type of the Sun Management Center agent and use that value instead of the value specified in the dot_node_object_type field. The value specified in the dot_node_object_type field is only used if the node_object_type of the agent cannot be determined. If the node_object_type of the agent cannot be determined and no value is specified for dot_node_object_type, the value "generic-host" is used.
If the dot_agent_port number is specified, discovery will look for the Sun Management Center agent on the UDP port instead of the port numbers specified in the Discovery Request.
If the agent does not respond as a Sun Management Center agent, then the dot_node_object_type is prepended with the string "nonagent-". Keep this in mind when modelling the Composite Object with the es-device script.
The name of the module must be specified in the dot_description field for this object. The dot_description value must be the same as the param:module value specified in the module's Module Parameter (-m.x) File on the Sun Management Center agent machine.
This describes how Discovery Filtering is handled by the various composite types:
The composite_group is subject to filtering by the Discovery process. The Discovery Request can either include or exclude the composite_group object. If the composite_group is included then the objects within that composite_group are included or excluded depending on the filter conditions (for example, OS, Architecture, etc.). If the composite_group is excluded, then the objects within that composite_group are also excluded. The composite_group is not subject to filtering based on host name pattern or OS type.
The composite_modeled_agent is subject to all filtering criteria as applicable to Sun Management Center agents. If no filtering criteria is specified, then the composite_modeled_object will be added to the topology regardless of whether the host responds to ICMP/SNMP/Sun Management Center SNMP requests. If filtering criteria is set and the composite_modeled_agent does not respond to the above requests, then the composite_modeled_agent is not added to the topology.
The composite_agent is not subject to filtering based on host name pattern or OS type.
The composite_module is not subject to any filtering criteria.
The es-dt script adds a reference to the Discovery Object Table. This script can be run on any Sun Management Center agent machine not necessarily the same machine that has the Discovery Object Table module loaded.
When using the Discovery Interface or "Edit -> Create an Object..." to build the composite object, to build the composite object, specify the machine where the
es-dt script was executed.Note that you must stop the Sun Management Center agent before running this script and restart the agent after the script is finished. You must restart the Sun Management Center console for any internationalized text to properly appear.
The correct syntax, where the -a, -d, and -t arguments are mutually exclusive, is as follows:
% es-dt -a | -d | -v [-s] -h hostname -l label -n not -o OID -p port
The arguments with their descriptions follow:
CODE EXAMPLE 13-2 Adding a Reference to Discovery Object Table Reference Description a Add a reference. d Delete a reference. v View references. This is the default option. s Add/Delete/View on the Platform Agent. By default the operation is performed on the Agent. h hostname Agent hostname of machine running the Discovery Object Table. l label Unique label for the Composite Object to add or delete. n not Node_Object_Type for the Composite Object to add. o OID Discovery Object Table OID to add. p port Agent port of machine running the Discovery Object Table.
If the Discovery Object Table is implemented as a module, the Discovery_OID should point to the "discovery" object in the MIB, and not the root of the module or some other location. For example, assume the module's data realization (-d.x) file contains the following:
discovery = { oid = 50 magic_number = { [ ... ] } discoveryObjectTable = { }
If this Discovery Object Table module is loaded at the OID "1.3.6.1.4.1.42.2.12.2.2.120" (which is specified in the module parameter (-m.x) file), then the OID of the "discovery" object would be "1.3.6.1.4.1.42.2.12.2.2.120.50" as in the example module data realization (-d.x) file above.
You can implement more than one Discovery Object Table in the same module with the following code:
discovery_one = { oid = 50 [ ... ] } discovery_two = { oid = 51 [ ... ] }
In this module, theDdiscovery Object Table can have two entries, one pointing to the OID of the discovery_one object, and the other pointing to the OID of the discovery_two object.
![]() |
Check the Discovery Request Log. Click on the "Log" button in the Discovery Requests Window. |
Note - Do not try to run a Discovery Request immediately after starting the agent machine where the Discovery Object Table is loaded, or the machine where the es-dt script was executed. It takes a few minutes for the Discovery processes to start properly after starting the Sun Management Center agent.
![]() |
When the es-dt script is executed or if the Discovery Object Table is Modified |
![]() |
If you make changes to the Discovery Object Table or after you execute the es-dt script, you must close any Host Detail Window and restart the agent to see the changes in future Discovery requests. |
![]() |
Running the Discovery Interface |
To run the discovery interface, refer to chapter 6 in the Sun Management Center User's Guide.
This section includes the following examples:
The following file is an example module Data Acquisition (DAQ) that implements the Discovery Object Table. This file is implemented in Tcl.
CODE EXAMPLE 13-3 Discovery Object Table Model Data Realization Example Code proc refreshDiscoveryObjectTable { } { set index 0 set ip_address [ host2ip [ info hostname ] ] set port 161 set rowa [ list [ incr index ] "Example_Composite_Object" \ "" 2 $ip_address $port \ "Example_Composite_Object_Type" "Example_Composite_Object" \ "Example Composite Object" ] set rowb [ list [ incr index ] "Snmp_Agent" \ "Example_Composite_Object" 3 $ip_address $port \ "Nonagent-Snmp" "Snmp_Agent" \ "SNMP Agent" ] set rowc [ list [ incr index ] "Modeled_Agent" \ "Example_Composite_Object" 1 $ip_address $port \ "" "Modeled_Agent" \ "Modeled Agent" ] set rowd [ list [ incr index ] "Module" \ "Example_Composite_Object" 5 $ip_address $port \ "MIB2-Module" "MIB2-Module" \ "mib2-simple" ] set listtoreturn "$rowa $rowb $rowc $rowd" return $listtoreturn }
Use the following information to implement your own Discovery Object Table.
CODE EXAMPLE 13-4 Sun Management Center MIB2 Definitions Copyright 1999 - Sun Microsystems, Inc. All Rights Reserved. Sun Management Center DOTABLE-SUNMANAGEMENTCENTER-MIB2 DEFINITIONS ::= BEGIN IMPORTS enterprises, MODULE-IDENTITY, OBJECT-TYPE, Integer32, IpAddress FROM SNMPv2-SMI OBJECT-GROUP FROM SNMPv2-CONF DisplayString FROM SNMPv2-TC; dotable MODULE-IDENTITY LAST-UPDATED "0001191326Z" ORGANIZATION "Sun Microsystems Inc." CONTACT-INFO " Sun Microsystems Inc. Customer Support Postal: 901 San Antonio Road Palo Alto, CA-94303-4900 USA Tel: 650-960-1300 E-mail: service@sun.com" DESCRIPTION "The Discovery Object Table defines the topology object(s) which should be created. Each of these objects is defined by a row in the Discovery Object Table. This module is defined by Discovery Object Table provider so only the format of the table is standard. User can change the OID for this module and give that new OID when running es-dt. REVISION "0001191326Z" DESCRIPTION "Rev 1.0 19th jan 2000 13:26, Initial version Of MIB." ::= { modules 15 } sun OBJECT IDENTIFIER ::= { enterprises 42 } prod OBJECT IDENTIFIER ::= { sun 2 } sunsymon OBJECT IDENTIFIER ::= { prod 12 } agent OBJECT IDENTIFIER ::= { sunsymon 2 } modules OBJECT IDENTIFIER ::= { agent 2 } discovery OBJECT-GROUP OBJECTS { magicnumber, entry, dotuniqueID,dottopologyparent, dotcompositetype, dotipaddr, dotagentport, dotnodeobjecttype, dotlabel, dotdescription } STATUS current DESCRIPTION "" ::= { dotable 1 } --discovery OBJECT IDENTIFIER ::= { dtable 1 } magicnumber OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "This value is hard coded to 53444f54, which is the hex representation of SDOT, or Sun Management Center Discovery Object Table. This is used by the discovery process for table data validation. The discovery process will log a message in case the magic number validation fails." ::= { discovery 1 } discoveryTable OBJECT-TYPE SYNTAX SEQUENCE OF DiscoveryTableEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The discovery object table defines the topology object(s) which should be created." ::= { discovery 2 } discoveryTableEntry OBJECT-TYPE SYNTAX DiscoveryTableEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "" INDEX { entry } ::= { discoveryTable 1 } DiscoveryTableEntry ::= SEQUENCE { entry DisplayString, dotuniqueID DisplayString, dottopologyparent DisplayString, dotcompositetype DisplayString, dotipaddr IpAddress, dotagentport Integer32, dotnodeobjecttype DisplayString, dotlabel DisplayString, dotdescription DisplayString } entry OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "The index is required for SNMP table ordering, by the process building the table, to insure that the table rows are in the appropriate order for discovery. The index can be a sequential number or a combination or IP address, port and OID. This field is not processed by the discovery process. It is ignored." ::= { discoveryTableEntry 1 } dotuniqueID OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "The creator of the module is responsible for creating a unique topology name which will not conflict with any other topology names (e.g. discovery, TM GUI (createtopology object frame)." ::= { discoveryTableEntry 2 } dottopologyparent OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "It may have the following values: 1. An empty string means that the object should be placed at the root of the Sun Management Center domain. 2. Otherwise this is a unique name identifying this object's parent. If this parent does not exist, then discovery will place the object at the topology root." ::= { discoveryTableEntry 3 } dotcompositetype OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "This field identifies what type of topology object this table entry represents. The following types are supported: 1 - composite_modeled_agent 2 - composite_group 3 - composite_agent 5 - composite_module" ::= { discoveryTableEntry 4 } dotipaddr OBJECT-TYPE SYNTAX IpAddress MAX-ACCESS read-only STATUS current DESCRIPTION "For composite_modeled_agent, composite_agent objects and composite_module types, this contains the IP address for the object's host. For object of type composite_group, this field is used for filling the name and ip_address. This field is used to fill the label and description fields if they are of 0 length." ::= { discoveryTableEntry 5 } dotagentport OBJECT-TYPE SYNTAX Integer32 MAX-ACCESS read-only STATUS current DESCRIPTION "For composite_modeled_agent and composite_agent type objects. If this field is -1, no port number is specified and discovery will use its regular set of port numbers during discovery. Otherwise, use this port number when attempting to discover the Sun Management Center agent executing on this host." ::= { discoveryTableEntry 6 } dotnodeobjecttype OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "For composite_modeled_agent objects, this is to be treated as a 'hint' that is overridden by the family type that discovery gets from mibman if the host is running a Sun Management Center agent. This field will only be used if a Sun Management Center agent is not discovered on the host therefore the family type should be set to nonagent-*. For composite_agent and composite_group objects, this is the family type with which the object should be created." ::= { discoveryTableEntry 7 } dotlabel OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "The label string used when creating the object. For composite_modeled_agent objects, an empty string means default to hostname. Otherwise, it is an undefined to specify an empty string for the dot_label field." ::= { discoveryTableEntry 8 } dotdescription OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "The description string used when creating the object. An empty string may be specified if no description for the object is desired. For composite_module object type this field is used to specify the name of the module that will be used by the discovery process to create a Sun Management Center URL that will be used to check for the health of the module." ::= { discoveryTableEntry 9 } END