Previous Next Contents Generated Index Home


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.


Implementing a Composite Object

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.

es-device -a example-composite.conf

  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:

es-dt -a -h <hostname> -p <port> -o <OID> -n <not> -l <label>


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.

/opt/SUNWsymon/sbin/es-stop -a

  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 -l Composite_Object_Label

This deletes the label, Composite_Object_Label. You can also use the following command that deletes by Node_Object_Type:

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.

/opt/SUNWsymon/sbin/es-start -a

  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.

es-device -d example-composite.conf

  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.


Discovery Object Table Definition

The Discovery Object Table is defined as follows:

CODE  EXAMPLE  13-1 Discovery Object Table
Discovery_object = { [ use MANAGED-OBJECT ]
	magic_number = { [ use STRING MANAGED-PROPERTY ]
		consoleHint:hidden = true
	}
	dot_table = { [ use MANAGED-OBJECT-TABLE ]
		dot_tableEntry = { [ use MANAGED-OBJECT-TABLE-ENTRY ]
        	index = entry
        	entry = { [ use STRING MANAGED-PROPERTY ]
			consoleHint:hidden = true
        	}
		dot_uniqueID = { [ use STRING MANAGED-PROPERTY ]
		}
		dot_topology_parent =  { [ use STRING MANAGED-PROPERTY ]
		}
		dot_composite_type =  { [ use INTEGER MANAGED-PROPERTY ]
		}
		dot_ip_address =  { [ use IPADDRESS MANAGED-PROPERTY ]
		}
		dot_agent_port =  { [ use INTEGER MANAGED-PROPERTY ]
		}
		dot_node_object_type =  { [ use STRING MANAGED-PROPERTY ]
		}
		dot_label =  { [ use STRING MANAGED-PROPERTY ]
		}
		dot_description =  { [ use STRING MANAGED-PROPERTY ]
		}
	}
}

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.  


    dot_composite_type


    2 - composite_group

    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.


    1 - composite_modeled_agent

    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.


    3 - composite_agent

    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.


    5 - composite_module

    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.


    Special Behavior

    Some of the composite objects treat the fields in the Discovery Object table in unique ways. This is described as follows:


    2 - composite_group

    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.


    1 - composite_modeled_agent

    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.


    3 - composite_agent

    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.


    5 - composite_module

    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.


    Filtering

    This describes how Discovery Filtering is handled by the various composite types:


    2 - composite_group

    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.


    1 - composite_modeled_agent

    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.


    3 - composite_agent

    The composite_agent is not subject to filtering based on host name pattern or OS type.


    5 - composite_module

    The composite_module is not subject to any filtering criteria.


    Adding a Reference to the Discovery Object Table

    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.  


    Object Identification (OID)

    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.


    Troubleshooting


    Finding the Composite Object when Running a Discovery Request

       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.


    Examples

    This section includes the following examples:


    Discovery Object Table Module Data Realization File

    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
    }
    


    Discovery Object Table MIB

    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
    

     



    Previous Next Contents Generated Index Home

    Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.