# Chapter 14

| # Device Modeling

> The purpose of this chapter is to discuss the device modeling interface that allows users to make their managed nodes discoverable by the SunMC Discovery and Create Node applications.

> As an Independent Software Vendor (ISV) and a user of the Sun Management Center Developer Environment, you can update files within your environment to help SunMC identify the devices on your system. For example, each device has a device identification string that when read by the SunMC software can help SunMC associate the behavior of that host. You can customize the configuration files on your system to help SunMC represent your machines appropriately.

> To help SunMC recognize and represent the devices on your machines, you need to update the configuration file in the following two locations:

- At the server level
- At the agent level

> This chapter provides the following secions:

- The Server Layer Interface
- The Agent Layer Interface

> It also details key values, formats, and arguments that need to be defined within the configuration file.

> > Note - Device modelling works only with Sun Management Center 3.0 version and above. This means that you can deploy any changes only on top of supported versions of Sun Management Center Software.

### Sun Management Center Framework

> Sun Management Center is an extensible framework for system management. This product consists of three layers, agent, server and console:

- The agent component runs on the managed nodes.
- The console clients connect to the server program to manage the nodes that are running the agents.
- The server, a centralized program, enables the console clients to talk to various agents and provides a secured environment for such communication.

### Devices Within SunMC

> Each device or topology entity belongs to the topology object type, or a known type, in order for the console and server programs to represent the entity appropriately. Any manageable device belongs to one of the known device types for the topology to represent that device. You can define the appropriate data for a new device type in the configuration file so that SunMC can represent that device as a recognizable icon in the SunMC console.

### Modeling a Device

> Typically, modeling a new device in Sun Management Center involves the following:

- providing the topological aspects of the new entity (such as, icon definitions) to the Sun Management Center Server layer.
- populating the identification parameters in manageable entities, such as identification strings, OIDs, and others.

> You can configure the topological aspects of a new topology object by defining your device as one of the following topology object types:

- group
- node
- segment
- composite

> Once the topological information for a new object is defined, it is used in operations, such as creating a node and discovering objects, and the like.

### Editing the Configuration File

> To identify new device parameters or to change the parameters that already exist, edit the configuration file. The configuration file is a file where you define your machine name and type, including the device ID, object ID (OID), `familytype`. This file resides at both the server and the agent levels.

> The assumption is that you have the infrastructure to edit the files on the target node in case there is a need for additional setup. Similarly, you need to deploy the necessary server configuration files on the server component.

### Configuring the Topology

> Sun Management Center allows you to configure the topological aspects of a new device or topology object. Using the Sun Management Center Developer Environment Software, you can configure the OID for a new node type object.

> The topology configuration of the new object type is persistent across multiple invocations of the server program. You can delete the topology configuration of the new object type when required.

> On the managed node, the OID information is persistent:

- across the invocations of the agent.
- across the installations, unless you choose to clear the state of the previous installation.

> On a managed node, you can provide the OID information during the Agent component setup of a new node type. If needed, you can change the OID at any later point of time.

> On a Sun Management Center Server node, you can configure a new topology object type by executing a configuration program. You can also delete a topology object type configuration by executing a configuration program.

## Server Layer Interface

> This section describes the following:

- Modeling Your Devices at the Server Level
- The es-device Script
- The Configuration File (devcfgfile)
- Example Configuration File

### Modeling Your Devices at the Server Level

> To ensure that SunMC recognizes and represents your devices appropriately, you must go through the following steps:

| 1. | Define your devices in the configuration file (`devcfgfile`) using the formats detailed in the following sections

|  | Note that the definitions of your devices must be in a format that is recognized by SunMC.

| 2. | Stop the server.

|  | Make sure of this if the server is running.

| 3. | Run the `es-device` script on the `devcfgfile.`

|  | This is to ensure that new definitions in the configuration file are updated.

| 4. | Restart the server.

|  | SunMC will now recognize and represent your devices on your system as defined.

### The `es-device` Script

> The es-device script in the Sun Management Center server is an interface that allows you to add new or third-party device types to Sun Management Center during installation. To do this, compose a configuration file that contains the information about the device to be modeled and use it as an argument to the
> `es-device` script to add and/or delete the device into the Sun Management Center's known device list.

> The `es-device` script parses the input file and validates all the entries. The file may have entries for more than one new devices.

#### Synopsis

> The `es-device` script is installed in the following directory:

>     <SunMC_Install_Directory>/SUNWsymon/sbin/

> > Note - The `es-device` script can only be run by a super user.

> The script takes two arguments:

- The first argument specifies the operation to be performed. (You can either add or delete a new device. Note that you can execute one of the options (`-a|-d)` at a time.)
- The second argument specifies the path to the user-defined data file (`devcfgfile`) for the new device to be added or deleted.

> For example:

>     es-device -a|-d devcfgfile

> where:

> TABLE 14-1 `es-device` Command Description
> -a | Adds a new device. | Example: es-device -a /tmp/userdata
> -d | Deletes the device. | Example: es-device -d /tmp/userdata

> > Note - The script can only execute one of the options (`-a|-d)` at a time.

### The Configuration File (`devcfgfile`)

> You can add or delete multiple devices using one data file by providing a Sun Management Center specified delimiter between device information. The delimiter is one or more numbers of "`-`" in a single line. For each object type that is being added, you have to define a set of mandatory key value pairs.

> Only the objects belonging to the Group, Node and Segment types can be defined using this model. The mandatory keys for each type of this object are defined in this section.

> The file devcfgfile contains key value pairs. The key and value fields are separated by spaces. Each line defines one key value pair. This section also gives the configuration file format for various types of objects. The keys used in the format are described in detail in the section "Key Descriptions".

#### Object Types

> In the following sections, the keys <Group_Object_Type>, <Node_Object_Type>, <Segment_Object_Type> and <Composite_Object_Type> are replaced by the actual values for the keys that you enter. For a configuration file example, refer to section "Example Configuration File".

> Group Type Object

> The Configuration file for defining a new Group Type Object is as follows:

> CODE EXAMPLE 14-1 Group Type Object Configuration File

>     <Group_Object_Type> implements Group {
>     	User_Name	<value>
>     	Group_Type	<value>
>     	I18n_Key	<value>
>     	Properties_File	<value>
>     	Large_Icon	<value>
>     	Small_Icon	<value>
>     }

> Node Type Object

> The Configuration file for defining a new Node Type object is as follows:

> CODE EXAMPLE 14-2 Node Type Object Configuration File

>     <Node_Object_Type> implements Node {
>     	User_Name	<value>
>     	Monitor_Via	<value>
>     	Node_Type	<value>
>     	i18n_Key	<value>
>     	Properties_File	<value>
>     	Search_Parameter	<value>
>     	Large_Icon	<value>
>     	Small_Icon	<value>
>     }

> Segment Type Object

> The Configuration file for defining a new Segment Type object is as follows:

> CODE EXAMPLE 14-3 Segment Type Object Configuration File

>     <Segment_Object_Type> implements Segment {
>     	User_Name	<value>
>     	Segment_Type	<value>
>     	I18n_Key	<value>
>     	Properties_File	<value>
>     	Large_Icon	<value>
>     	Small_Icon	<value>
>     }

> Composite Type Object

> The Configuration file for defining a new Composite Type object is as follows:

> CODE EXAMPLE 14-4 Composite Type Object Configuration File

>     <Composite_Object_Type> implements Composite {
>     	User_Name	<value>
>     	Composite_Type	<value>
>     	I18n_Key	<value>
>     	Properties_File	<value>
>     	Large_Icon	<value>
>     	Small_Icon	<value>
>     }

> After the new device has been added to the Sun Management Center server, restart the console if you want to display the correct newly-added i18n value.

#### Key Descriptions

> This section includes information on each key description.

> User_Name

> This is the user name. It must be unique, similar to a package name. The name must not contain any spaces.

> Group_Type

> The type of group object to be created. Valid types are:

- General
- IpBased

> Group_Object_Type

> New group object type the user wants to create. The name should not contain white spaces and must be unique. The Sun Management Center software has the following group object types:

- General Group Type: Building, Campus, General
- Ip_Based Group Type: Network, Subnet

> Monitor_Via

> This value must be given to add a node object. Valid values are described in the following table:

> TABLE 14-2 Valid Types for `Monitor_Via`
> Valid `Monitor_Via` Types | Description
> --- | ---
> Host | If Sun Management Center Agent exists on the monitored system
> Platform | If Sun Management Center Agent exists on the monitored system
> Module | If users would like to use a special icon for a module, see Sun Management Center Developer Environment Reference Manual for more information on how to add icons to modules.
> Proxy | This is for SNMP proxy managed modules. A module writer defines a special icon for the module.
> SNMP | The monitored system is running the snmpdx.
> ICMP | For monitored systems not running snmpdx or Sun Management Center agent. These are ping-able hosts.
> None | Non Monitored

> Node_Type

> Following are the valid node types if Monitor_Via is set to host, platform, SNMP, ICMP or none

- Router
- Concentrator
- Workstation
- Printer (Not valid for ICMP)
- PC
- Server

> If `Monitor_Via` is set to `module` or `proxy`, the valid node type is `module`. The agent <module>`-d.x` file must contain the following line in order to display this object in the hierarchy and topology views:

>     consoleHint:family = <Node_Object_Type>

> An example of the Solaris Managed Object and Property Models follows:

> CODE EXAMPLE 14-5 Solaris Managed Object and Property Models

>     Example
>     #
>     # Solaris Managed Object and Property Models
>     #
>             _rules = { [ use PROC ]
>                     .....
>             }
>             consoleHint:family = Solaris
>             # cpu Managed Object
>             cpu = { [ use MANAGED-OBJECT ]
>                   .......
>             }

> Node_Object_Type

> This is the new machine type or module type to add. The value for this has to be unique. The following table presents the node object types currently existing in Sun Management Center:

> TABLE 14-3 Node Object Types
> Router | Concentrator | Workstation | Printer | PC
> Cisco500 | General | Ultra1 | HpJetDirect | X86
> General | Ultra | 2 | General | Pentium
> |  | Ultra 5 |  | Laptop
> |  | Ultra 10 |  |
> |  | Ultra 30 |  |
> |  | Ultra 60 |  |
> |  | Ultra 80 |  |
> |  | SparcStation 1 |  |
> |  | SparcStation 2 |  |
> |  | SparcStation 5 |  |
> |  | SparcStation 10 |  |
> |  | SparcStation 20 |  |
> |  | General |  |

> The following is a list of the applicable servers:

> TABLE 14-4 Applicable Servers in SunManagementCenter
> sun4d-SPARCserver-1000
> sun4d-SPARCserver-1000
> sun4d-SPARCcenter-2000
> sun4d-SPARCcenter-2000
> sun4u-Ultra-Enterprise-150
> sun4u-Ultra-Enterprise-250
> sun4u-Ultra-Enterprise-450
> sun4u-Ultra-Enterprise-220R
> sun4u-Ultra-Enterprise-420R
> sun4u-Ultra-Enterprise-3000
> sun4u-Ultra-Enterprise-3500
> sun4u-Ultra-Enterprise-4000,5000
> sun4u-Ultra-Enterprise-4500,5500
> sun4u-Ultra-Enterprise-4000,5000
> sun4u-Ultra-Enterprise-4500,5500
> sun4u-Ultra-Enterprise-6000
> sun4u-Ultra-Enterprise-6500
> sun4u-Ultra-Enterprise-10000
> sun-Enterprise-10000-platform
> sun-server
> nonagent-sun4d-SPARCserver-1000
> nonagent-sun4d-SPARCserver-1000
> nonagent-sun4d-SPARCcenter-2000
> nonagent-sun4d-SPARCcenter-2000
> nonagent-sun4u-Ultra-Enterprise-150
> nonagent-sun4u-Ultra-Enterprise-250
> nonagent-sun4u-Ultra-Enterprise-450
> nonagent-sun4u-Ultra-Enterprise-220R
> nonagent-sun4u-Ultra-Enterprise-420R
> nonagent-sun4u-Ultra-Enterprise-3000
> nonagent-sun4u-Ultra-Enterprise-3500
> nonagent-sun4u-Ultra-Enterprise-4000,5000
> nonagent-sun4u-Ultra-Enterprise-4500,5500
> nonagent-sun4u-Ultra-Enterprise-4000,5000
> nonagent-sun4u-Ultra-Enterprise-4500,5500
> nonagent-sun4u-Ultra-Enterprise-6000
> nonagent-sun4u-Ultra-Enterprise-6500
> nonagent-sun4u-Ultra-Enterprise-10000
> nonagent-sun-Enterprise-10000-platform
> nonagent-sun-server

> Segment_Type

> The type of segment object. Valid types are:

- Bus
- Ring

> Segment_Object_Type

> New segment object type. The name should not contain white spaces and must be unique. We currently have the following Segment object types in Sun Management Center

- Bus: Ethernet, IPX
- Ring: FDDI

> Composite_Object_Type

#### i18n_key

> This is the i18n key the user provides for the new object to be created. This key follows java conventions. It must be valid and unique. The key must be defined in the properties file. For more information, see "Properties_File".

> Properties_File

> This is the path to the user properties file. The file name must be of the type <User_Name.properties> to be valid. This file contains value for the i18n key specified for the new object being created. If the file exists previously, it will be overwritten.

> Search_Parameter

> This is the search pattern that the Sun Management Center discovery process uses for discovering hosts with legacy SNMP agents. The format for this is:

>     sysOID|sysDescriptor|

> For this pattern to be valid, provide either both `sysoid` and `sysdescriptor`, or any one or none in the following manner.

> > Note - The `|' character is the field delimiter.

> The syntax for the search parameter is:

>     sysoid|sysdescriptor|
>     sysoid||
>     |sysdescriptor|
>     ||

> An example follows:

>     1.3.6.1.4.1.42.2.1.2.2.3.1|SUNW,Grover|
>     SUNW-Ultra-60|
>     1.3.6.1.4.1.42.2.1.2.3.1.2.3||

> Large_Icon

> This is the path to the large icon file. If a file with the same name for this user exists previously, it will be overwritten.

> Small_Icon

> This is the path to the small icon file. If a file with the same name for this user exists previously it will be overwritten.

> Device_Id

> This is a unique string and must be the same as the gsi model string returned from the gsi library.

### Example Configuration File

> This section contains various examples of configuration files:

- Example Data Node - Host
- Example Data for Node - SNMP
- Example Data for Node - Module
- Example Data for Group - IPBASED
- Example Data for Segment - Bus

#### Example Data Node - Host

CODE EXAMPLE 14-6 Example Data for Host Node

    Ultra-100 implements Node {
    	User_name xxx
    	Monitor_via host
    	Node_Type workstation
    	i18n_Key xxx:agent-Ultra-100
    	Properties_File /tmp/xxx.properties
    	Search_Parameter ||
    	Large_Icon /tmp/Ultra-100-large.gif
    	Small_Icon /tmp/Ultra-100-small.gif
    	device_id Ultra-100
    }

> > Note - If a device is modelled as a Node Object type and if the `Monitor_via` is set to "host," then the `Hardware_module` key-value is mandatory. The value should be the name of the hardware module for that platform (for example,
> > `config-readerdt` for desktop).

#### Example Data for Node - SNMP

CODE EXAMPLE 14-7 Example Data for SNMP Node

    Nonagent-Ultra-100 implements Node {
    	User_name xxx
    	Monitor_via snmp
    	Node_Type workstation
    	i18n_Key xxx:workstation-Ultra-100
    	Properties_File /tmp/xxx.properties
    	Search_Parameter 1.3.4.2.5.42.6|Ultra-100|
    	Large_Icon /tmp/xxx1.gif
    	Small_Icon /tmp/xxx2.gif
    	device_id Ultra-100
    }

#### Example Data for Node - Module

CODE EXAMPLE 14-8 Example Data for Module Node

    Module-Ultra-100 implements Node {
    	User_name xxx
    	Monitor_via module
    	Node_Type module
    	i18n_Key xxx:module-Ultra-100
    	Properties_File /tmp/xxx.properties
    	Search_Parameter ||
    	Large_Icon /tmp/laptop-large.gif
    	Small_Icon /tmp/laptop-small.gif
    	device_id Ultra-100
    }

#### Example Data for Group - IPBASED

CODE EXAMPLE 14-9 Example Data for IPBased Group

    WAN implements group {
    	User_name xxx
    	Group_Type ipbased
    	i18n_Key xxx:WAN
    	Properties_File /tmp/xxx.properties
    	Search_Parameter ||
    	Large_Icon /tmp/WAN-large.gif
    	Small_Icon /tmp/WAN-small.gif
    }

#### Example Data for Segment - Bus

CODE EXAMPLE 14-10 Example Data for Bus Segment

    line implements segment {
    	User_name xxx
    	segment_Type bus
    	i18n_Key xxx:line
    	Properties_File /tmp/xxx.properties
    	Search_Parameter ||
    	Large_Icon /tmp/line-large.gif
    	Small_Icon /tmp/line-small.gif
    }

## Agent Layer Interface

> This section describes the following:

- Modeling Your Devices at the Agent Level
- The deviceinfo Script
- Agent Configuration File
- Example deviceinfo.conf File

### Modeling Your Devices at the Agent Level

> To ensure that SunMC recognizes and represents your devices appropriately, you must go through the following steps:

| 1. | Stop the agent if the agent is running.

| 2. | Deploy the configuration file (`devcfgfile`). This means that you have to create, replace or update the configuration file at the specified location using the formats detailed in the following sections.

|  | Note that the definitions of your devices must be in a format that is recognized by SunMC.

| 3. | Start the agent.

|  | SunMC will now recognize and represent your devices on your system as defined.

### The `deviceinfo` Script

> The deviceinfo script is used by the setup script to find the OID and familytype for the known PROM strings. PROM strings identify each device.

> The deviceinfo script is installed in the following directory:

>     </opt>/SUNWsymon/base/bin/sparc-sun-solaris<OS>/

> The deviceinfo script will get the PROM string and check of the PROM string as one of the known string values.

- If the PROM string is already known, then the script prints the following and return a success value:
  - `DID`
  - `OID`
  - `FamilyType`
- If the PROM string is not known, then the `deviceinfo` program will return an error message.

### Agent Configuration File

> The configuration file is located in the `/var/opt/SUNWsymon/cfg/` directory, and is named `deviceinfo.conf`.

> After running the Sun Management Center setup script at the agent layer, verify to see if the `deviceinfo.conf` configuration file exists in the following location:

>     /var/opt/SUNWsymon/cfg/deviceinfo.conf

> If it does not exist, then the Sun Management Center setup script populates this configuration file.

#### Key Value Pairs

> The configuration file contains the following key value pairs. Each key value paris is specified on a new line in the file. All lines starting with a `#' character are considered to be comment lines.

> DID (Device ID)

> This is a unique string and must be the same as the `gsi` model string returned from the `gsi` library.

> OID

> This is the standard `sysoid` for the system.

> Node_Object_Type

> This information has to be same as the new device or machine type (`Node_object_Type`) field entered by the user at the server layer in the users data file.

### Example `deviceinfo.conf` File

TABLE 14-5 Example of `deviceinfo.conf` File
DID | Sun-Ultra-60
OID | 1.3.6.1.4.1.42.2.12.3.1.6
Node_Object_Type | sun4u-Sun-Ultra-60

> > Note - In Sun Management Center 2.1.1, the Node_Object_Type is referred to as `FAMILYTYPE`. For backward compatibility, Sun Management Center 3.0 supports either of the two keywords If Node_Object_Type is present, then this string will be taken by the agent. In the absence of Node_Object_Type, the agent will search for `FAMILYTYPE`.

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