Chapter 9 Entity MIB

This chapter describes the implementation of the Entity MIB and the associated API functions in the System Management Agent. The demonstration module demo_module_11 is used to explain how to use the MIB and the tables that are defined in the MIB. The chapter contains the following topics:

• About the Entity MIB

• SMA Entity MIB Implementation

• Entity MIB API

• Header Files for Entity MIB Functions

• Tips for Using Entity MIB Functions

• demo_module_11 Code Example for Entity MIB

About the Entity MIB

The Entity MIB is defined by the Internet Engineering Task Force RFC 2737 at http://www.ietf.org/rfc/rfc2737.txt. This chapter does not describe the Entity MIB in detail. You should read RFC 2737 before reading this chapter.

The Entity MIB provides a mechanism for presenting hierarchies of physical entities by using SNMP tables. The Entity MIB contains the following groups, which describe the physical elements and logical elements of a managed system:

entityPhysical group

The entityPhysical group describes the identifiable physical resources that are managed by the agent. Resources include the chassis, boards, power supplies, sensors, and so on.

Physical entities are represented by rows in the entPhysicalTable, where one row is provided for each hardware resource. The rows are called entries. A particular row is referred to as an instance. Each table entry has a unique index, entPhysicalIndex, and contains several objects that represent common characteristics of the hardware resource. One object, entPhysicalContainedIn, points to the index of another row in this table. This object is used to indicate whether an entity is contained within another entity. A row for a system board might use entPhysicalContainedIn to specify the index of the row that represents the chassis where the board is installed.

entityLogical group

The entityLogical group describes the logical entities managed by the agent. Logical entities represent nonphysical, abstract elements that provide services. The abstract elements are controlled by higher levels of management. For example, logical entities might represent elements of platform hardware management. Such elements might include functions such as OS reboot, hardware reset, and power control. Logical entities might also represent administrative domains such as Solaris domains or service controllers.

Logical entities are represented as rows in the entLogicalTable, which provides one row for each logical entity. Each table row has a unique index, entLogicalIndex, and contains objects for the logical entity's name, description, and type.

Each row also contains security information that is applicable to SNMPv1, SNMPv2c, and SNMPv3 to allow access to the logical entity's MIB information. If an agent represents multiple logical entities with this MIB, the agent must implement the entityLogical group for all logical entities that are known to the agent. If an agent represents one logical entity, or multiple logical entities within a single naming scope, the agent can omit implementation of this group.

entityMapping group

The entityMapping group describes the objects that represent the associations between elements for which a single agent provides management information. These elements include multiple logical entities, physical components, interfaces, and port identifiers.

The entityMapping group contains the following tables:

• The entPhysicalContainsTable provides a hierarchy of the hardware resources that are represented in the entPhysicalTable. The entPhysicalContainsTable table is two-dimensional, indexed first by the entPhysicalIndex of the containing entry, and second by the entPhysicalChildIndex of the contained entries.

• The entLPMappingTable is the logical-physical mapping table. The entLPMappingTable makes associations between logical entities and physical entities by mapping the indexes of the entLogicalTable to the indexes of entPhysicalTable For example, the table could map a firewall to a particular board.

• The entAliasMappingTable represents mappings of logical entity and physical component to external MIB identifiers.

entityGeneral group

This table describes objects that represent general entity information for which a single agent provides management information. Currently, only one object exists in this group. The object records the time interval between agent startup and the last change to the Physical Entity Table or Physical Mapping Table.

The RFC 2737 and the ENTITY-MIB.txt file describe these tables in more detail. The ENTITY-MIB.txt file is located in the /etc/sma/snmp/mibs directory.

SMA Entity MIB Implementation

The System Management Agent provides a module called libentity.so for use with the Entity MIB. This module is contained in the /usr/sfw/include directory.

The libentity.so module performs the following tasks when loaded:

• Registers OIDs for the Entity MIB

• Creates empty tables for the groups described and defined in RFC 2737

• Handles the rules and constraints of the Entity MIB tables and maintains table integrity as specified in RFC 2737

• Provides Entity API functions that support a module's ability to add, delete, and modify objects in the OID space of the Entity MIB

If you want your module to use the Entity MIB, you must load the libentity.so module into the agent before you load your module.

Using the Entity MIB

To use the Entity MIB, you must write a module to create objects that reflect the devices that you want to manage. You use the objects to populate the empty tables that are created by the libentity.so module. Your module must use the API functions that are documented in Entity MIB API. Use demo_module_11, which is described in demo_module_11 Code Example for Entity MIB, to see how that module uses the API functions. The demo_module_11 also contains table header files that you need to use the API functions. See Header Files for Entity MIB Functions.

After you write your module, you can use the following procedure to set up the agent to use the Entity MIB and your module.

How to Set Up the Agent to Use the Entity MIB

1. As root, add the appropriate dlmod statement for your operating system in the agent's configuration file /etc/sma/snmp/snmpd.conf.

   • On a 64-bit Solaris Operating System on SPARC:

     dlmod entity /usr/sfw/lib/sparcv9/libentity.so

   • On a 32-bit Solaris Operating System:

     dlmod entity /usr/sfw/lib/libentity.so

2. In the /etc/sma/snmp/snmpd.conf file, insert a dlmod statement for your module after the dlmod statement for the libentity.so.

   For example, suppose your module is named libacmerouter.so. The module is located in /home/username/lib. You would enter the following line:

   dlmod acmerouter /home/username/lib/libacmerouter.so

   Your module must be loaded after the entity module because your module is dependent upon the entity module.

3. Restart the SNMP agent.

   # svcadm restart svc:/application/management/sma:default

Entity MIB API

This section lists and describes the API functions that are provided in the libentity.so module. Use these functions in your module when you want to use the Entity MIB.

Physical Table Functions

The entPhysicalTable contains one row for each physical entity. The table contains at least one row for an overall physical entity. Each table entry provides objects to help an NMS to identify and characterize the entry. Other objects in the table entry help an NMS to relate the particular entry to other entries in the table.

The following functions are for use with the entPhysicalTable in the Entity MIB.

• allocPhysicalEntry()

• getPhysicalEntry()

• deletePhysicalTableEntry()

• makePhysicalTableEntryStale()

• makePhysicalTableEntryLive()

• getPhysicalStaleEntry()

• getAllChildrenFromPhysicalContainedIn()

allocPhysicalEntry()

Synopsis

Description

Allocates an entry in the entPhysicalTable. The physidx parameter is the requested physical index. If physidx= 0, the function tries to use the first available index in the table. If physidx= 1 or greater, the function tries to use the specified index. If the specified index is in use, the function returns the first available index in the table. As a result, the returned index might not be the same as the requested physical index.

The memory that is associated with newPhysEntry can be freed. The function creates an internal copy of the data.

The entPhysicalEntry_t structure definition is shown in entPhysicalEntry_t Structure. Special cases for newPhysEntry values are handled as shown in the following table.

Returns

index

allocated to the physical entry.

-1

if an error occurs when adding the entry. Check the log for more details.

getPhysicalEntry()

Synopsis

Description

Gets the actual physical table entry for the specified index. The caller must not change the values or release the memory of the entry that is returned. The entPhysicalEntry_t structure definition is shown in entPhysicalEntry_t Structure.

Returns

getPhysicalEntry() returns the entry for the specified index.

Returns NULL if an error occurs while finding the entry, or if a stale entry exists. In this context, stale means that the entry details are present in the agent memory but should not be displayed during any SNMP operation.

deletePhysicalTableEntry()

Synopsis

Description

Deletes the physical table entry that is associated with the specified xPhysicalIndex. The instances of xPhysicalIndex in the entAliasMappingTable, entLPMappingTable and the entPhysicalContainsTable are also deleted to maintain integrity among the various Entity MIB tables.

Returns

0

for success.

-1

if the xPhysicalIndex is not found.

-2

if a stale entry was found for the xPhysicalIndex. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation.

makePhysicalTableEntryStale()

Synopsis

Description

Makes the physical table entry that is associated with the xPhysicalIndex become stale. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation. The index that was allocated to a stale entry is not allocated to another entry.

When you make an entry become stale, the instances of xPhysicalIndex in the entAliasMappingTable, entLPMappingTable and entPhysicalContainsTable are also deleted. The deletion maintains integrity among the various Entity MIB tables. Before you make an entry stale, you might want to store the entries that are to be deleted from the tables.

The physical table entry can be made available or “live” again by calling the makePhysicalTableEntryLive() functions, which is described in makePhysicalTableEntryLive().

Returns

0

for success.

-1

if the xPhysicalIndex is not found.

-2

if a stale entry already exists for xPhysicalIndex.

makePhysicalTableEntryLive()

Synopsis

Description

Makes the stale physical table entry associated with the xPhysicalIndex live. In this context, “live” means that the entry details that are present in the agent memory are displayed during SNMP operations. The entry can be made stale by calling the makePhysicalTableEntryStale() function. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation.

If a stale entry is made live again, you must recreate the corresponding entries that were deleted in the entPhysicalContainsTable, the entLPMappingTable, and the entAliasMappingTable. Use the appropriate functions for adding an entry to each table: addPhysicalContainsTableEntry(), addLPMappingTableEntry(), and addAliasMappingTableEntry().

Returns

0

for success.

-1

if the xPhysicalIndex is not found.

-2

if a live entry already exists for xPhysicalIndex.

getPhysicalStaleEntry()

Synopsis

Description

The caller must not change the values or release the memory of the entry that is returned.

Gets the stale physical table index structure for the specified index. In this context, stale means that the entry details are present in the agent memory but are not displayed during any SNMP operation. The entPhysicalEntry_t structure definition is shown in entPhysicalEntry_t Structure.

Returns

Returns the index structure for the specified index.

Returns NULL if an error occurs while finding the entry, or if a live entry exists.

getAllChildrenFromPhysicalContainedIn()

Synopsis

Description

Gets the indexes for all children in the entPhysicalTable that have parentIndex as their parent in the entPhysicalContainedIn field.

Returns

Returns an array of integer indexes with null termination.

Returns NULL if no children, or invalid index, or not enough memory when allocating the array.

Physical Contains Table Functions

The entPhysicalContainsTable exposes the container relationships between physical entities. This table provides the same information that can be found by constructing the virtual containment tree for a given entPhysicalTable, but in a more direct format.

The following functions are for use with the entPhysicalContainsTable in the Entity MIB:

• addPhysicalContainsTableEntry()

• deletePhysicalContainsTableEntry()

• deletePhysicalContainsParentIndex()

• deletePhysicalContainsChildIndex()

• getPhysicalContainsChildren()

addPhysicalContainsTableEntry()

Synopsis

Description

Adds an entry to the entPhysicalContainsTable table for the specified entPhysicalIndex and childIndex. The entPhysicalContainedIn OID that is present in the entPhysicalTable for the childIndex might be replaced by the OID for entPhysicalIndex. The OID is replaced if the entPhysicalIndex has a lower index than the original index.

Returns

0

for successful addition.

-1

for failure to add.

-2

for stale index.

1

if the entry already exists for the specified entPhysicalIndex and childIndex.

deletePhysicalContainsTableEntry()

Synopsis

Description

Deletes the parentIndex or childIndex entry that is present in the entPhysicalContainsTable.

Returns

0

for success.

-1

for failure.

-2

for stale entry, either parent or child, or both.

deletePhysicalContainsParentIndex()

Synopsis

Description

Deletes all entries in the entPhysicalContainsTable where the parent index is equal to the specified parentIndex.

Returns

number

of children successfully deleted for the specified parent.

-1

for failure.

-2

for stale parent entry.

deletePhysicalContainsChildIndex()

Synopsis

Description

Deletes all entries in the entPhysicalContains table where the child index is equal to the specified childIndex.

Returns

number

of parents successfully deleted for the specified child.

-1

for failure.

-2

for stale child entry.

getPhysicalContainsChildren()

Synopsis

Description

Get the indexes for all the children of the specified parent in the entPhysicalContainsTable.

Returns

Returns an array of integer indexes, with null termination.

Returns NULL if children exist, or if not enough memory exists when allocating the array. The array is a copy that should be freed when done.

Logical Table Functions

The entLogicalTable table contains one row per logical entity. For agents that implement more than one naming scope, at least one entry must exist. Agents that instantiate all MIB objects within a single naming scope are not required to implement this table.

The following functions are for use with the entLogicalTable in the Entity MIB:

• allocLogicalEntry()

• deleteLogicalTableEntry()

• makeLogicalTableEntryStale()

• makeLogicalTableEntryLive()

• getLogicalStaleEntry()

allocLogicalEntry()

Synopsis

Description

Allocates an entry in the Logical Table. The logidx parameter is the requested logical index. If logidx= 0, the function tries to use the first available index in the table. If logidx= 1 or greater, the function tries to use the specified index. If the specified index is in use, the function returns the first available index in the table. As a result, the returned index might not be the same as the requested logical index.

The allocLogicalEntry() function returns the logical index that is allocated to the entry. The memory that is associated with xnewLogicalEntry can be freed. The function creates a internal copy of the data.

The entLogicalEntry_t structure definition is shown in entLogicalEntry_t Structure. Special cases for xnewLogicalEntry values are handled as shown in the following table.

Returns

Returns the index allocated to the logical entry.

Returns -1 for error in adding the entry. Check the log for more details.

getLogicalTableEntry()

Synopsis

Description

This function gets the logical table index structure for a particular index. The caller must not change the value or release the memory of the entry that is returned. The entLogicalEntry_t structure definition is shown in entLogicalEntry_t Structure.

Returns

Returns the entry that is associated with xLogicalIndex.

Returns NULL on error in finding the entry, or if a stale entry exists.

deleteLogicalTableEntry()

Synopsis

Description

Deletes the logical table entry that is associated with the xLogicalIndex. The instances of xLogicalIndex in the entAliasMappingTable and the entLPMappingTable are also deleted to maintain integrity among the various Entity MIB tables.

Returns

0

for success.

-1

if the xLogicalIndex is not found.

-2

if a stale entry was found for xLogicalIndex.

makeLogicalTableEntryStale()

Synopsis

Description

Makes the logical table entry associated with the xLogicalIndex become stale. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation. The index that was allocated to a stale entry is not allocated to another entry.

When you make an entry become stale, the instances of xLogicalIndex in the entAliasMappingTable, entLPMappingTable and entPhysicalContainsTable are also deleted. The deletion maintains integrity among the various Entity MIB tables. Before you make an entry stale, you might want to store the entries that are to be deleted from the other tables.

The stale logical table entry can be made available again by calling the makeLogicalTableEntryLive() function, which is described in makeLogicalTableEntryLive().

Returns

0

for success.

-1

if the xLogicalIndex is not found.

–2

if a stale entry was found for xLogicalIndex.

makeLogicalTableEntryLive()

Synopsis

Description

Makes the stale logical table entry associated with the xLogicalIndex become live. In this context, “live” means that the entry details that are present in the agent memory are displayed during any SNMP operations. The entry can be made stale by calling the makeLogicalTableEntryStale() function.

If an entry is made live again, you must recreate the corresponding entries that were deleted in the entPhysicalContainsTable, the entLPMappingTable, and the entAliasMappingTable. Use the appropriate functions for adding an entry to each table: addPhysicalContainsTableEntry(), addLPMappingTableEntry(), and addAliasMappingTableEntry().

Returns

0

for success.

-1

if the xLogicalIndex is not found.

–2

if a live entry already exists for xLogicalIndex.

getLogicalStaleEntry()

Synopsis

Description

Gets the stale logical table index structure for the specified index. The caller must not change the values or release the memory of the entry that is returned. The entLogicalEntry_t structure definition is shown in entLogicalEntry_t Structure.

Returns

Returns the stale entry for the specified index.

Returns NULL if the entry is not found, or if a live entry exists.

LP Mapping Table Functions

The entLPMappingTable contains zero or more rows that associate logical entities to physical equipment. For each logical entity that is known by this agent, there are zero or more mappings to the physical resources that are used to realize that logical entity. An agent should limit the number and nature of entries in this table so that only meaningful and non-redundant information is returned. See the /etc/sma/snmp/mibs/ENTITY-MIB.txt file for more information about the entLPMappingTable.

The following functions are for use with the entLPMappingTable:

• addLPMappingTableEntry()

• deleteLPMappingTableEntry()

• deleteLPMappingLogicalIndex()

• deleteLPMappingPhysicalIndex()

addLPMappingTableEntry()

Synopsis

Description

Adds an entry to the entLPMappingTable with the xentLogicalIndex as the primary index and xentPhysicalIndex as the secondary index.

Returns

0

for successful addition.

1

if the entry already exists for the given xentPhysicalIndex and xentLogicalIndex.

-1

for failure to add.

-2

for stale index.

deleteLPMappingTableEntry()

Synopsis

Description

Deletes the entry of the LP Mapping table that uses the specified xentLogicalIndex as the primary index and xentPhysicalIndex as the secondary index.

Returns

0

for successful deletion.

-1

for failure to delete.

-2

for stale entry, either logical index or physical index, or both.

deleteLPMappingLogicalIndex()

Synopsis

Description

Deletes all the entries of the entLPMappingTable that have the xentLogicalIndex as the primary index.

Returns

number

of successfully deleted entries.

-1

for failure.

-2

for stale logical entry.

deleteLPMappingPhysicalIndex()

Synopsis

Description

Deletes all the entries of the entLPMappingTable that have xentPhysicalIndex as the secondary index.

Returns

number

of successfully deleted entries.

–1

if no entry was deleted.

-2

for stale physical entry.

Alias Mapping Table Functions

The entAliasMappingTable contains zero or more rows that represent mappings of logical entity and physical entities for ports to external MIB identifiers. Each physical port in the system can be associated with a mapping to an external identifier. The external identifier is associated with a particular logical entity's naming scope. A wildcard mechanism is provided to indicate that an identifier is associated with more than one logical entity.

The following functions are for use with the entAliasMappingTable in the Entity MIB:

• addAliasMappingTableEntry()

• deleteAliasMappingTableEntry()

• deleteAliasMappingLogicalIndex()

• deleteAliasMappingPhysicalIndex()

addAliasMappingTableEntry()

Synopsis

Description

Adds an entry to the entAliasMappingTable with the xentPhysicalIndex as the primary index and xentLogicalIndex as the secondary index. xAliasMapId is the alias (OID) for the entry and xAliasMapIdSize is the size in bytes of xAliasMapId.

Note that if entAliasMapId = NULL, the request is rejected.

Returns

0

for successful addition.

1

if the entry already exists for the given xentPhysicalIndex and xentLogicalIndex.

-1

for failure.

-2

for stale entry.

deleteAliasMappingTableEntry()

Synopsis

Description

Deletes the entry in the entAliasMappingTable that has xentPhysicalIndex as the primary index and xentLogicalIndex as the secondary index.

Returns

0

for successful deletion.

-1

for entry not found.

-2

for stale entry.

deleteAliasMappingLogicalIndex()

Synopsis

Description

Deletes all entries of the entAliasMappingTable that have xentLogicalIndex as the secondary index.

This function cannot be used to delete all indexes that have an xentLogicalIndex of zero. Use the deleteAliasMappingTableEntry() function to delete such entries one at a time, with the appropriate xentPhysicalIndex specified.

Returns

number

of entries successfully deleted.

-1

for entry not found.

-2

for stale logical entry.

deleteAliasMappingPhysicalIndex()

Synopsis

Description

Deletes all entries in the entAliasMappingTable whose primary index matches the specified xentPhysicalIindex.

Returns

number

of entries successfully deleted.

–1

for entry not found.

–2

for stale physical entry.

Header Files for Entity MIB Functions

Data declarations and defines that are needed by the Entity MIB functions are included in header files. The following header files in /usr/demo/sma_snmp/demo_module_11 can be copied and modified for use with your own modules:

The structures defined in entPhysicalTable.h and entLogicalTable.h are shown in the following sections.

entPhysicalEntry_t Structure

The entPhysicalTable.h header file contains the typedef for the entPhysicalEntry_t structure. This structure is representative of the entPhysicalTable columns that are defined in RFC 2737. The entPhysicalEntry_t is defined as follows:

typedef struct entPhysicalEntry_s {
    int_l entPhysicalIndex;
    char *entPhysicalDescr;
    oid *entPhysicalVendorType;
    int_l entPhysicalVendorTypeSize;
    int_l entPhysicalContainedIn;
    int_l entPhysicalClass;
    int_l entPhysicalParentRelPos;
    char *entPhysicalName;
    char *entPhysicalHardwareRev;
    char *entPhysicalFirmwareRev;
    char *entPhysicalSoftwareRev;
    char *entPhysicalSerialNum;
    char *entPhysicalMfgName;
    char *entPhysicalModelName;
    char *entPhysicalAlias;
    char *entPhysicalAssetID;
    int_l entPhysicalIsFRU;
    struct entPhysicalEntry_s *pNextEntry;
} entPhysicalEntry_t;

entLogicalEntry_t Structure

The entLogicalTable.h header file contains the typedef for the entLogicalEntry_tstructure. This structure is representative of the entLogicalTable columns that are defined in RFC 2737. The entLogicalEntry_t is defined as follows:

typedef struct entLogicalEntry_s {

   int_l   entLogicalIndex;
   char *entLogicalDescr;
   oid  *entLogicalType;
   int_l   entLogicalTypeSize;
   char *entLogicalCommunity;
   char *entLogicalTAddress;
   oid  *entLogicalTDomain; 
   int_l   entLogicalTDomainSize; 
   char *entLogicalContextEngineId;
   char *entLogicalContextName;
   struct entLogicalEntry_s* pNextEntry;

} entLogicalEntry_t;

Tips for Using Entity MIB Functions

Creating physical or logical entries

Create the appropriate physical entries or logical entries first, before creating the entries in the three mapping tables: entLPMappingTable, entAliasMappingTable, and the entPhysicalContainsTable.

Multiple parents

For physical entries that have more than one parent, all relationships must be defined in the entPhysicalContainsTable. For example, suppose you want to define that C is contained in A with the entPhysicalContainedIn field. You also want to define that C is also contained in B. In this case, you must define that C is contained in A, and C is contained in B in the entPhysicalContainsTable.

Recursive Relationships

Recursive relationships are not allowed in the entPhysicalTable and entPhysicalContainsTable. For example, suppose B is contained in A, and C is contained in B. In this case, A cannot be contained in C. The parent/child relationship is defined both in the entPhysicalContainedIn field of the entPhysicalTable() function and in the entPhysicalContainsTable. The recursive check safeguard is already built into the addPhysicalContainsTableEntry() function.

Uniqueness

When you specify entPhysicalParentRelPos, the allocPhysicalEntry() function does not check for uniqueness. For example, you can specify that A and B are contained in C by setting both entPhysicalParentRelPos fields to the same value. However, doing so would violate RFC 2737. The uniqueness of many fields is not necessarily checked by the functions. You must be aware of this fact during the design phase.

Deleting physical or logical entries

Deleting an entry is similar to making the entry stale. Both deleted and stale entries no longer show up in tables when performing SNMP operations. Whether you delete an entry or make an entry stale, the corresponding entries are automatically deleted in the three mapping tables. Note that you cannot undelete these corresponding mapping tables entries. This deletion is done to maintain the integrity of the tables.

The difference between deleting an entry and making the entry stale is that a stale entry can be restored. Stale entries can be made live with functions that are designed for that purpose. A deleted entry cannot be restored.

Deleting Parents

The integrity of the entPhysicalTable and entPhysicalContainsTable are not maintained if you delete a parent before you delete the subsequent generations. The deletePhysicalTableEntry() function does not recursively remove the parent and its subsequent generations. The function only removes the specified entry from the tables. If you do not delete a parent's generations before deleting the parent, you leave orphaned children. This practice is a violation of RFC 2737.

When you delete a parent of a multi-parent child, the entPhysicalContainedIn parameter is reset automatically to the lowest of the remaining parent index. RFC 2737 requires this reset. The entPhysicalParentRelPos parameter is then out of place. No API function lets you change that parameter. You can modify the entPhysicalParentRelPos parameter by manipulating the entry that is returned by the getPhysicalTableEntry() function. However, this approach for modifying entPhysicalParentRelPos is not supported. If you decide to try this approach, use caution.

Traps

A notification trap is sent out whenever a change is made to any of the five tables, such as the creation or deletion of entries. A mechanism exists to suppress traps from being sent too frequently. The throttling period is five seconds.

RFC Constraints and errors

The Entity MIB implementation has some constraints, which are dictated by RFC 2737. The only mechanism to notify the user about an error is through the error codes. You must understand the RFC thoroughly to be aware of the constraints.

demo_module_11 Code Example for Entity MIB

The /usr/demo/sma_snmp/demo_module_11 code example shows how the Entity MIB module can be used. The demo module is designed to populate the empty MIB tables that are created when the libentity.so module is dynamically loaded into the agent. The data that is loaded is described in this section.

You should examine the code in demo_module_11, especially the code in the MyTable.c file. The file README_demo_module_11 in that directory includes procedures for building and using the example.

The demo_module_11 example refers to a system with the following components that need to be managed:

• Two boards, with two CPU modules on each board

• One board that contains three ports

• Two logical domains

• Two firewall instances

These components can be divided into the following entities:

• 14 physical entities

  1 chassis

  
  

  3 slots in the chassis

  
  

  3 boards in the slots

  
  

  4 CPU modules in two boards

  
  

  3 ports in one board

  
  

• 4 logical entities

  2 domains

  
  

  2 firewalls

  
  

Some of the physical entities are contained in other physical entities. The logical entities are associated with particular physical entities. The Entity MIB tables should be populated to show the relationships among the various entities.

The following examples demonstrate how the MIB tables could be populated for this system.

Example 9–1 Physical Entities for demo_module_11

The entPhysicalTable might be populated with the following values:

• One field-replaceable physical chassis:

  entPhysicalDescr.1 ==             'Sun Chassis Model b1000'
  entPhysicalVendorType.1 ==        sun.chassisTypes.1
  entPhysicalContainedIn.1 ==       0
  entPhysicalClass.1 ==             chassis(3)
  entPhysicalParentRelPos.1 ==      -1
  entPhysicalName.1 ==              'b1000'
  entPhysicalHardwareRev.1 ==       'A(1.00.02)'
  entPhysicalSoftwareRev.1 ==       ''
  entPhysicalFirmwareRev.1 ==       ''
  entPhysicalSerialNum.1 ==         'C100076544'
  entPhysicalMfgName.1 ==           'Sun Microsystems'
  entPhysicalModelName.1 ==         'CHS-1000'
  entPhysicalAlias.1 ==             'cl-SJ17-3-006:rack1:rtr-U3'
  entPhysicalAssetID.1 ==           '0007372293'
  entPhysicalIsFRU.1 ==             true(1)
  

• Slot 1 within the chassis:

  entPhysicalDescr.2 ==             'Sun Chassis Slot Type AA'
  entPhysicalVendorType.2  ==       sun.slotTypes.1
  entPhysicalContainedIn.2 ==       1
  entPhysicalClass.2 ==             container(5)
  entPhysicalParentRelPos.2 ==      1
  entPhysicalName.2 ==              'S1'
  entPhysicalHardwareRev.2 ==       'B(1.00.01)'
  entPhysicalSoftwareRev.2 ==       ''
  entPhysicalFirmwareRev.2 ==       ''
  entPhysicalSerialNum.2 ==         ''
  entPhysicalMfgName.2 ==           'Sun Microsystems'
  entPhysicalModelName.2 ==         'SLT-AA97'
  entPhysicalAlias.2 ==             ''
  entPhysicalAssetID.2 ==           ''
  entPhysicalIsFRU.2 ==             false(2)
  

• Slot 2 within the chassis:

  entPhysicalDescr.3 ==             'Sun Chassis Slot Type AA'
  entPhysicalVendorType.3 =         sun.slotTypes.1
  entPhysicalContainedIn.3 ==       1
  entPhysicalClass.3 ==             container(5)
  entPhysicalParentRelPos.3 ==      2
  entPhysicalName.3 ==              'S2'
  entPhysicalHardwareRev.3 ==       '1.00.07'
  entPhysicalSoftwareRev.3 ==       ''
  entPhysicalFirmwareRev.3 ==       ''
  entPhysicalSerialNum.3 ==         ''
  entPhysicalMfgName.3 ==           'Sun Microsystems'
  entPhysicalModelName.3 ==         'SLT-AA97'
  entPhysicalAlias.3 ==             ''
  entPhysicalAssetID.3 ==           ''
  entPhysicalIsFRU.3 ==             false(2)
  

• Slot 3 within the chassis:

  entPhysicalDescr.4 ==             'Sun Chassis Slot Type AA'
  entPhysicalVendorType.4 =         sun.slotTypes.1
  entPhysicalContainedIn.4 ==       1
  entPhysicalClass.4 ==             container(5)
  entPhysicalParentRelPos.4 ==      3
  entPhysicalName.4 ==              'S3'
  entPhysicalHardwareRev.4 ==       '1.00.07'
  entPhysicalSoftwareRev.4 ==       ''
  entPhysicalFirmwareRev.4 ==       ''
  entPhysicalSerialNum.4 ==         ''
  entPhysicalMfgName.4 ==           'Sun Microsystems'
  entPhysicalModelName.4 ==         'SLT-AA97'
  entPhysicalAlias.4 ==             ''
  entPhysicalAssetID.4 ==           ''
  entPhysicalIsFRU.4 ==             false(2)
  

• Board 1 within Slot 1:

  entPhysicalDescr.5 ==             'Sun CPU-100'
  entPhysicalVendorType.5  ==       sun.moduleTypes.14
  entPhysicalContainedIn.5 ==       2
  entPhysicalClass.5 ==             module(9)
  entPhysicalParentRelPos.5 ==      1
  entPhysicalName.5 ==              'M1'
  entPhysicalHardwareRev.5 ==       '1.00.07'
  entPhysicalSoftwareRev.5 ==       '1.5.1'
  entPhysicalFirmwareRev.5 ==       'A(1.1)'
  entPhysicalSerialNum.5 ==         'C100087363'
  entPhysicalMfgName.5 ==           'Sun Microsystems'
  entPhysicalModelName.5 ==         'R10-FE00'
  entPhysicalAlias.5 ==             'rtr-U3:m1:SJ17-3-eng'
  entPhysicalAssetID.5 ==           '0007372562'
  entPhysicalIsFRU.5 ==             true(1)
  

• First CPU, in Board 1, within Slot 1:

  entPhysicalDescr.6 ==             'Sun Ultrasparc-III 400MHz'
  entPhysicalVendorType.6  ==       sun.cpuTypes.2
  entPhysicalContainedIn.6 ==       5
  entPhysicalClass.6 ==             other(1)
  entPhysicalParentRelPos.6 ==      1
  entPhysicalName.6 ==              'P1'
  entPhysicalHardwareRev.6 ==       'G(1.02)'
  entPhysicalSoftwareRev.6 ==       ''
  entPhysicalFirmwareRev.6 ==       '1.1'
  entPhysicalSerialNum.6 ==         ''
  entPhysicalMfgName.6 ==           'Sun Microsystems'
  entPhysicalModelName.6 ==         'SFE-400M'
  entPhysicalAlias.6 ==             ''
  entPhysicalAssetID.6 ==           ''
  entPhysicalIsFRU.6 ==             false(2)
  

• Second CPU, in Board 1, within Slot 1:

  entPhysicalDescr.7 ==             'Sun Ultrasparc-III 400MHz'
  entPhysicalVendorType.7  ==       sun.cpuTypes.2
  entPhysicalContainedIn.7 ==       5
  entPhysicalClass.7 ==             other(1)
  entPhysicalParentRelPos.7 ==      2
  entPhysicalName.7 ==              'P2'
  entPhysicalHardwareRev.7 ==       'G(1.02)'
  entPhysicalSoftwareRev.7 ==       ''
  entPhysicalFirmwareRev.7 ==       '1.1'
  entPhysicalSerialNum.7 ==         ''
  entPhysicalMfgName.7 ==           'Sun Microsystems'
  entPhysicalModelName.7 ==         'SFE-400M'
  entPhysicalAlias.7 ==             ''
  entPhysicalAssetID.7 ==           ''
  entPhysicalIsFRU.7 ==             false(2)
  

• Board 2 within Slot 2:

  entPhysicalDescr.8 ==             'Sun CPU-200'
  entPhysicalVendorType.8  ==       sun.moduleTypes.15
  entPhysicalContainedIn.8 ==       3
  entPhysicalClass.8 ==             module(9)
  entPhysicalParentRelPos.8 ==      1
  entPhysicalName.8 ==              'M2'
  entPhysicalHardwareRev.8 ==       '2.01.00'
  entPhysicalSoftwareRev.8 ==       '3.0.7'
  entPhysicalFirmwareRev.8 ==       'A(1.2)'
  entPhysicalSerialNum.8 ==         'C100098732'
  entPhysicalMfgName.8 ==           'Sun Microsystems'
  entPhysicalModelName.8 ==         'R10-FE0C'
  entPhysicalAlias.8 ==             'rtr-U3:m2:SJ17-2-eng'
  entPhysicalAssetID.8 ==           '0007373982'
  entPhysicalIsFRU.8 ==             true(1)
  

• Third CPU, in Board 2, within Slot 2:

  entPhysicalDescr.9 ==             'Sun Ultrasparc-III 400MHz'
  entPhysicalVendorType.9 ==        sun.cpuTypes.5
  entPhysicalContainedIn.9 ==       8
  entPhysicalClass.9 ==             other(1)
  entPhysicalParentRelPos.9 ==      1
  entPhysicalName.9 ==              'P3'
  entPhysicalHardwareRev.9 ==       'CC(1.07)'
  entPhysicalSoftwareRev.9 ==       '2.0.34'
  entPhysicalFirmwareRev.9 ==       '1.1'
  entPhysicalSerialNum.9 ==         ''
  entPhysicalMfgName.9 ==           'Sun Microsystems'
  entPhysicalModelName.9 ==         'SFE-400M'
  entPhysicalAlias.9 ==             ''
  entPhysicalAssetID.9 ==           ''
  entPhysicalIsFRU.9 ==             false(2)
  

• Fourth CPU, in Board 2, within Slot 2:

  entPhysicalDescr.10 ==            'Sun Ultrasparc-III 400MHz'
  entPhysicalVendorType.10 ==       sun.cpuTypes.2
  entPhysicalContainedIn.10 ==      8
  entPhysicalClass.10 ==            other(1)
  entPhysicalParentRelPos.10 ==     2
  entPhysicalName.10 ==             'P4'
  entPhysicalHardwareRev.10 ==      'G(1.04)'
  entPhysicalSoftwareRev.10 ==      ''
  entPhysicalFirmwareRev.10 ==      '1.3'
  entPhysicalSerialNum.10 ==        ''
  entPhysicalMfgName.10 ==          'Sun Microsystems'
  entPhysicalModelName.10 ==        'SFE-400M'
  entPhysicalAlias.10 ==            ''
  entPhysicalAssetID.10 ==          ''
  entPhysicalIsFRU.10 ==            false(2)
  

• Board 3 within Slot 3:

  entPhysicalDescr.11 ==             'Sun port-200'
  entPhysicalVendorType.11  ==       sun.moduleTypes.25
  entPhysicalContainedIn.11 ==       4
  entPhysicalClass.11 ==             module(9)
  entPhysicalParentRelPos.11 ==      1
  entPhysicalName.11 ==              'M2'
  entPhysicalHardwareRev.11 ==       '2.01.00'
  entPhysicalSoftwareRev.11 ==       '3.0.7'
  entPhysicalFirmwareRev.11 ==       'A(1.2)'
  entPhysicalSerialNum.11 ==         'C100098732'
  entPhysicalMfgName.11 ==           'Sun Microsystems'
  entPhysicalModelName.11 ==         'R11-C100'
  entPhysicalAlias.11 ==             'rtr-U3:m2:SJ17-2-eng'
  entPhysicalAssetID.11 ==           '0007373982'
  entPhysicalIsFRU.11 ==             true(1)
  

• Port 1, in Board 3, within Slot 3:

  entPhysicalDescr.12 ==             'Sun Ethernet-100 Port'
  entPhysicalVendorType.12 ==        sun.portTypes.5
  entPhysicalContainedIn.12 ==       11
  entPhysicalClass.12 ==             port(10)
  entPhysicalParentRelPos.12 ==      1
  entPhysicalName.12 ==              'P3'
  entPhysicalHardwareRev.12 ==       'CC(1.07)'
  entPhysicalSoftwareRev.12 ==       '2.0.34'
  entPhysicalFirmwareRev.12 ==       '1.1'
  entPhysicalSerialNum.12 ==         ''
  entPhysicalMfgName.12 ==           'Sun Microsystems'
  entPhysicalModelName.12 ==         'SFE-P100'
  entPhysicalAlias.12 ==             ''
  entPhysicalAssetID.12 ==           ''
  entPhysicalIsFRU.12 ==             false(2)
  

• Port 2, in Board 3, within Slot 3:

  entPhysicalDescr.13 ==            'Sun Ethernet-100 Port'
  entPhysicalVendorType.13 ==       sun.portTypes.5
  entPhysicalContainedIn.13 ==      11
  entPhysicalClass.13 ==            port(10)
  entPhysicalParentRelPos.13 ==     2
  entPhysicalName.13 ==             'Ethernet B'
  entPhysicalHardwareRev.13 ==      'G(1.04)'
  entPhysicalSoftwareRev.13 ==      ''
  entPhysicalFirmwareRev.13 ==      '1.3'
  entPhysicalSerialNum.13 ==        ''
  entPhysicalMfgName.13 ==          'Sun Microsystems'
  entPhysicalModelName.13 ==        'SFE-P100'
  entPhysicalAlias.13 ==            ''
  entPhysicalAssetID.13 ==          ''
  entPhysicalIsFRU.13 ==            false(2)
  

• Port 3, in Board 3, within Slot 3:

  entPhysicalDescr.14 ==            'Sun Ethernet-100 Port'
  entPhysicalVendorType.14 ==       sun.portTypes.5
  entPhysicalContainedIn.14 ==      11
  entPhysicalClass.14 ==            port(10)
  entPhysicalParentRelPos.14 ==     3
  entPhysicalName.14 ==             'Ethernet B'
  entPhysicalHardwareRev.14 ==      'G(1.04)'
  entPhysicalSoftwareRev.14 ==      ''
  entPhysicalFirmwareRev.14 ==      '1.3'
  entPhysicalSerialNum.14 ==        ''
  entPhysicalMfgName.14 ==          'Sun Microsystems'
  entPhysicalModelName.14 ==        'SFE-P100'
  entPhysicalAlias.14 ==            ''
  entPhysicalAssetID.14 ==          ''
  entPhysicalIsFRU.14 ==            false(2)
  

Example 9–2 Logical Entities for demo_module_11

The entLogicalTable is populated with the following values when you run demo_module_11:

• Logical Domain “A”

  entLogicalDescr.1 ==              'Domain A'
  entLogicalType.1 ==               solaris
  entLogicalCommunity.1 ==          'public-dom1'
  entLogicalTAddress.1 ==           124.125.126.127:161
  entLogicalTDomain.1 ==            SunExampleDomain
  entLogicalContextEngineID.1 ==    ''
  entLogicalContextName.1 ==        ''
  

• Logical Domain “B”

  entLogicalDescr.2 ==              'Domain B'
  entLogicalType.2 ==               solaris
  entLogicalCommunity.2 ==          'public-dom2'
  entLogicalTAddress.2 ==           124.125.126.128:161
  entLogicalTDomain.2 ==            SunExampleDomain
  entLogicalContextEngineID.2 ==    ''
  entLogicalContextName.2 ==        ''
  

• Firewall 1

  entLogicalDescr.3 ==              'Sun Firewall v2.1.1'
  entLogicalType.3  ==              dot1dFirewall
  entLogicalCommunity.3 ==          'public-firewall1'
  entLogicalTAddress.3 ==           124.125.126.129:161
  entLogicalTDomain.3 ==            SunExampleDomain
  entLogicalContextEngineID.3 ==    ''
  entLogicalContextName.3 ==        ''
  

• Firewall 2

  entLogicalDescr.4 ==              'Sun Firewall v2.1.1'
  entLogicalType.4 ==               dot1dFirewall
  entLogicalCommunity.4 ==          'public-firewall2'
  entLogicalTAddress.4 ==           124.125.126.130:161
  entLogicalTDomain.4 ==            SunExampleDomain
  entLogicalContextEngineID.4 ==    ''
  entLogicalContextName.4 ==        ''
  

entLogicalTable does not support SNMPv3 in this example.

Example 9–3 Logical to Physical Mappings for demo_module_11

The entLPMappingsTable is populated with the objects and values in the right column of the following table when you run demo_module_11.

entLPPhysicalIndex.1.5  == 5
entLPPhysicalIndex.1.12 == 12

entLPPhysicalIndex.2.8  == 8
entLPPhysicalIndex.2.13 == 13
entLPPhysicalIndex.2.14 == 14

entLPPhysicalIndex.3.6  == 6
entLPPhysicalIndex.3.12 == 12

entLPPhysicalIndex.4.9  == 9
entLPPhysicalIndex.4.13 == 13
entLPPhysicalIndex.4.14 == 14

Example 9–4 Physical to Logical to MIB Alias Mappings for demo_module_11

The entAliasMappingTable is populated with the following objects and values when you run demo_module_11.

If the ifIndex values are shared by all logical entities, the entAliasMappingTable might be populated as follows:

entAliasMappingIdentifier.12.0 ==  ifIndex.1
entAliasMappingIdentifier.13.0 ==  ifIndex.2
entAliasMappingIdentifier.14.0 ==  ifIndex.3

The first index in the entAliasMappingIdentifier signifies the physical index. In this case, physical entities with the indexes 12, 13, and 14 are Port 1, Port 2, and Port 3. In the preceding entAliasMappingIdentifier assignments, Port 1 is mapped to ifIndex.1, Port 2 is mapped to ifIndex.2, and Port 3 is mapped to ifIndex.3. This mapping is for all logical entities that use each of these ports.

If the ifIndex values are not shared by all logical entities, the entAliasMappingTable might be populated as follows:

entAliasMappingIdentifier.12.0 ==  ifIndex.1
entAliasMappingIdentifier.12.3 ==  ifIndex.101
entAliasMappingIdentifier.13.0 ==  ifIndex.2
entAliasMappingIdentifier.13.3 ==  ifIndex.102
entAliasMappingIdentifier.14.0 ==  ifIndex.3
entAliasMappingIdentifier.14.3 ==  ifIndex.103

In this case, one logical entity is mapped differently. Firewall 1, which is entLogicalIndex.3, is mapped as follows:

• ifIndex.101 on Port 1

• ifIndex.102 on Port 2

• ifIndex.103 on Port 3

Example 9–5 Physical Contains Table Entries for demo_module_11

The following table shows the containment relationships among the physical entities. The right column of the table lists the entries added to the entPhysicalContainsTable of the Entity MIB by demo_module_11.