test

Solaris WBEM Services Administration Guide

Chapter 3 Using SNMP Services for WBEM (Tasks)

SNMP Services for WBEM includes two components, the SNMP Adapter for WBEM and the SNMP Provider.

Here is a list of the information in this chapter.

SNMP Adapter for WBEM

Intended for use by system administrators, the SNMP Adapter for WBEM enables Simple Network Management Protocol (SNMP) management applications to access system management information that is provided by Solaris WBEM Services.

Used with snmpdx, the Master Agent of the Solstice Enterprise AgentsTM technology, the SNMP Adapter for WBEM maps SNMP requests into equivalent WBEM Common Information Model (CIM) properties or instances. The Master Agent is described in snmpdx(1M).

The SNMP Adapter for WBEM also remaps the response from the CIM Object Manager into an SNMP response, which is returned to the management application.

A mapping file contains the corresponding Object Identifier (OID), class name, property name, and Abstract Syntax Notation One (ASN.1) type for each object. You can create your own mapping files.

How the SNMP Adapter for WBEM Works

The Solaris operating environment initializes WBEM Services before starting the Solstice Enterprise Agents Master Agent. By default, the SNMP Adapter for WBEM, or Adapter, is disabled. However, once you enable the Adapter, the Solstice Enterprise Agents Master Agent (snmpdx) starts the Adapter automatically. The Adapter is described in snmpXwbemd(1M).

An SNMP Manager passes an SNMP Get-request to the Solstice Enterprise Agents Master Agent. The Master Agent then sends the Get-request to the Adapter, which uses the mapping files in /var/sadm/wbem/snmp/map to translate the objects in the Get-request into corresponding CIM objects. The Adapter also translates the CIM objects into SNMP objects in a Get-response.

Note –

At present, only Get-request and scalar objects are supported in Solaris 9. Get-next-request, Get-bulk-request, and Set-request as well as other objects are not currently supported.

The Adapter searches this directory alphabetically for the first file to which the extension .map is appended. The Adapter then reads all mapping files in the directory and caches their contents. The Adapter uses the contents of these files to translate the objects that are specified in the Get-request into corresponding CIM objects. The Adapter subsequently ignores duplicate OIDs in the mapping files in the directory. For example, if this OID appears in 002SUNWlvma.map:

1.3.6.1.2.1.1.1.0 My_ComputerSystem Description SnmpString

and the same OID appears in 050SUNWwbcou.map, which the Adapter reads after 002SUNWlvma.map:

1.3.6.1.2.1.1.1.0 Solaris_ComputerSystem Description SnmpString

then the Adapter ignores the OID that is specified in 050SUNWwbcou.map.

The Adapter subsequently generates a Get-response for each Get-request that an SNMP Manager submits. If the Adapter cannot find a corresponding entry in any mapping file, the Adapter returns a Get-response error.

How the Master Agent Routes a Request: SNMP Adapter for WBEM Compared to the Sun SNMP Agent

Until the release of the SNMP Adapter for WBEM, when an SNMP Manager sent a Get-request for an SNMP MIB-2 variable to the Solstice Enterprise Agents Master Agent, the Master Agent routed the request to the Sun SNMP MIB-2 Agent (mibiisa). Because the Adapter also handles SNMP MIB-2 requests, what happens if the Sun SNMP Agent and the SNMP Adapter for WBEM are both running at the same time? How does the Master Agent route a request?

The Master Agent builds a node table based on the subtrees that are defined in each subagent registration file. The mibiisa subagent registers the entire MIB-2 subtree and the Sun Microsystems MIB subtree. The Adapter registers the MIB-2.system subtree and the hostRsrc subtree. The Master Agent does not allow two agents to register the same subtree.

The Sun SNMP MIB-2 Agent is described in mibiisa(1M). The Master Agent is described in the Solstice Enterprise Agents 1.0 User Guide.

At initialization, the Master Agent creates a node table that contains each subtree that is registered. The Master Agent forwards each Get-request to the agent whose subtree best matches the OID that is included in the request. A request for mib-2.system.5.0, for example, is forwarded to the Adapter. A request for mib-2.interfaces.1.0, on the other hand, is forwarded to the mibiisa subagent. If the OID is not defined within any subtree that is registered by the Master Agent, the Master Agent returns an error in the Get-response.

The SNMP Adapter for WBEM supports SNMP V1 requests only.

Configuring the Adapter and Mapping SNMP to CIM Objects

Configuration Files

The files you use to configure the SNMP Adapter for WBEM, which are located in /etc/snmp/conf/, are described in this section.

In snmpXwbem.acl, you define the access control list policies that are associated with the Adapter, in this format:

#pragma ident  "@(#)snmpXwbem.acl   1.2   01/04/18 SMI"
#Copyright (c) 2001 by Sun Microsystems, Inc.
#All rights reserved.

#        Configuration file of the SNMP subagent for WBEM

##################
# access control #
##################
# The list of community names needed for read/write access
# to the entire MIB.

# If the list is empty, the only valid community name is "public"
# and its access type is read-only
#
# A * in the managers list indicates requests can be received from
# any host.

acl = {
        {
                communities = public, private
                access = read-only
                managers = * 
        }
}

###################
# trap parameters #
###################
trap = {
}

A comma-separated list of communities and a comma-separated list of managers are allowed. The access policies are read-only. An empty trap clause is required. Traps are not supported by the Adapter in Solaris 9.

In snmpXwbem.reg, you define the Object Identifier (OID) of the subtree for which the Adapter is responsible, in this format:

#pragma ident   "@(#)snmpXwbem.reg      1.3    01/10/04 SMI"
#
#Copyright (c) 2001 by Sun Microsystems, Inc.
#All rights reserved.

#       Configuration file of the SNMP subagent for WBEM

##########
# macros # 
##########

# The following 3 macros are predefined:
#
#       mib-2 =         1.3.6.1.2.1
#       enterprise =    1.3.6.1.4.1
#       sun =           1.3.6.1.4.1.42
#
# You can define your own macros, so that you can
# manipulate strings instead of OIDs in defining the agent.
# See the "agent" section below.

macros = {
        system = mib-2.1    
        hostRsrc = mib-2.25
}


##########
# agent  #
##########

# You must fill in at least the following fields:
#
# - name:               the name of your agent (for example, the executable
#                       file name of your agent)
#
# - subtrees:           the list of OIDs / subtrees of OIDs your agent
#                       supports. The listed items must be separated by
#                       a comma.
#
# You can also change or add the following fields:
#
# - timeout:            the number of micro-seconds the SNMP Relay will
#                       wait for a response from your agent
#
# - watch-dog-time:     the number of seconds the SNMP Relay will wait to
#                       test whether the subagent is active, if there has
#                       been no activity for the watch-dog-time interval
#
# - port:               the UDP port number on which you will start
#                       your agent

agents =
{
        {
                name = "WBEMsubagent"
                subtrees = { system, hostRsrc }
                timeout = 20000000
                watch-dog-time = 240
        }
}

The unit of measure for timeout is microseconds. The unit of measure for watch-dog-time is seconds. By default, the Master Agent tries to start the Adapter every four minutes (or number of seconds to which watch-dog-time is set).

Note –

The Master Agent automatically determines the port to be used by the Adapter.

In snmpXwbem.rsrc-, you define a pointer to the registration file and you define how the SNMP Master Agent is to start the Adapter, in this format:

#pragma ident   "@(#)snmpXwbem.rsrc-   1.2   01/04/18 SMI"
#Copyright (c) 2001 by Sun Microsystems, Inc.
#All rights reserved.

#        Configuration file of the SNMP subagent for WBEM

##########
# agents #
##########
resource =
{
         {
                 registration_file = "/etc/snmp/conf/snmpXwbem.reg"
                 security = "/etc/snmp/conf/snmpXwbem.acl"
                 policy = "spawn"
                 type = "legacy"
                 command = "/usr/sadm/lib/wbem/snmpXwbemd -p $PORT"
         }
}

Mapping Files

When the Master Agent passes a Get-request to the SNMP Adapter for WBEM, the Adapter uses the mapping files in /var/sadm/wbem/snmp/map to translate the Get-request into a CIM object request. The Solaris operating environment includes a mapping file for you in this directory. You can also define your own mapping file for the CIM instrumentation that you want to view through an SNMP Manager.

This section shows the contents of a mapping file that the Solaris environment provides, and describes what you need to know to create an Adapter mapping file.

Contents of the Mapping File That Is Included in Solaris

This example shows the contents of the mapping file that the Solaris operating environment includes for you: 

#
#pragma ident    "@(#)050SUNWwbcou.map    1.0    01/04/03 SMI"
#
# Copyright (c) 2001 by Sun Microsystems, Inc.
# All rights reserved.
#
# *** Description of contents ***
#
# First non-commented non-blank line contains required Version label.
# Remaining non-commented non-blank lines are considered map entries 
# used as described below:
#
# Column 1 - SNMP OID - Uniquely describes an SNMP variable
# Column 2 - CIM Class Name - CIM class associated with this variable
# Column 3 - CIM Property Name - CIM property that maps to SNMP OID variable
# Column 4 - ASN.1 type - SNMP datatype that dictates how data is mapped 
#            to/from SNMP requests.  Supported types are: SnmpString, SnmpOid,
#            SnmpTimeticks, SnmpCounter, SnmpInt, SnmpGauge, SnmpIpAddress, 
#            SnmpOpaque)
# Column 5 and greater are ignored
#
Version 1.0

1.3.6.1.2.1.1.1.0 Solaris_ComputerSystem Description SnmpString
1.3.6.1.2.1.1.3.0 Solaris_OperatingSystem LastBootUpTime SnmpTimeticks
1.3.6.1.2.1.1.4.0 Solaris_ComputerSystem PrimaryOwnerContact SnmpString
1.3.6.1.2.1.1.5.0 Solaris_ComputerSystem Name SnmpString

1.3.6.1.2.1.25.1.5.0 Solaris_OperatingSystem NumberOfUsers SnmpGauge
1.3.6.1.2.1.25.1.6.0 Solaris_OperatingSystem NumberOfProcesses SnmpGauge
1.3.6.1.2.1.25.1.7.0 Solaris_OperatingSystem MaxNumberOfProcesses SnmpGauge
1.3.6.1.2.1.25.1.2.0 Solaris_OperatingSystem LocalDateTime SnmpString

The contents of this mapping file associate the SNMP MIB-2 System Group scalar objects with their corresponding CIM objects.

MIB-2 System Group Scalar Object 

CIM Object 

sysDescr

Solaris_ComputerSystem.Description

sysUpTime

Solaris_OperatingSystem.LastBootUpTime

sysContact

Solaris_ComputerSystem.PrimaryOwnerContact

sysName

Solaris_ComputerSystem.Name

The contents of this mapping file also associate the SNMP Host Resources MIB objects with their corresponding CIM objects.

SNMP Host Resources MIB Object 

CIM Object 

hrSystemNumUsers

Solaris_OperatingSystem.NumberOfUsers

hrSystemProcesses

Solaris_OperatingSystem.NumberOfProcesses

hrSystemMaxProcesses

Solaris_OperatingSystem.MaxNumberOfProcesses

hrSystemDate

Solaris_OperatingSystem.LocalDateTime

The syntax of the contents of a mapping file is described in Syntax of the Contents of a Mapping File.

Note –

At present, the only way to retrieve host resource data is through the CIM Object Manager, as Solaris does not currently provide an SNMP Host Resource agent.

Syntax of a Mapping File Name

To ensure that the Adapter reads your mapping file, name the file according to this syntax:

alphanumeric-string.map

alphanumeric-string represents an alphanumeric string. For example, here is the name of the mapping file that Solaris includes:

050SUNWwbcou.map

You include the three digits to ensure that the Adapter reads the files in a more precise order. For example, 002SUNWlvma.map is read before 050SUNWwbcou.map.

Note –

You must allow root to at least read the mapping files that you create.

$ chmod 400 002SUNWlvma.map

Syntax of the Contents of a Mapping File

The following table describes the elements and the syntax of the contents of a mapping file.

Table 3–1 Contents of a Mapping File

Element 

Description 

Required? 

 

#

A comment, which is always ignored. 

No 

 

Version 1.0

The version of the mapping file. The text string that specifies the version must be the first uncommented line. If you do not specify a version as shown, the mapping file is ignored.  

Yes 

 

1.3.6.1.2.1.1.1.0

The SNMP Object Identifier, or OID, which is the key you want to extract from the SNMP request. The SNMP OID describes an SNMP variable. Because the Adapter currently supports scalars only, the OID must end with the text string .0.

Yes 

 

Solaris_ComputerSystem

The CIM class name that is associated with the variable. 

Yes 

 

Description

The CIM property name that defines a characteristic of the specified class and that maps to the SNMP OID variable. 

Yes 

 

SnmpString

The ASN.1 data type. Values that you can specify, including how they are mapped, are:

  • SnmpString – Move string, number, or CIM LocalDateTime into SnmpString.

  • SnmpInt – Move CIM number data types (including a string in number format) into SnmpInt (signed, 32-bit integer).

  • SnmpCounter – Move CIM number data types (including string in number format) into SnmpCounter (unsigned, 32-bit integer).

  • SnmpGauge – Move CIM number data types (including string in number format) into SnmpGauge (unsigned, 32-bit integer).

  • SnmpTimeticks – Move the time difference, represented in hundredths of a second, into SnmpTimeticks. This value is calculated by subtracting the CIM value from the current time. For example, sysUpTime is calculated by subtracting bootTime from currentTime.

  • SnmpIpAddress – Move string into SnmpIpAddress. You must specify the string in IP address format.

  • SnmpOid – Move string into SnmpOid. You must specify the string in OID format.

  • SnmpOpaque – Move vector of bytes into SnmpOpaque.

Yes 

Installing and Using the SNMP Adapter for WBEM (Task Map)

The following table identifies the procedures that you need to follow to install, start, stop, and use the SNMP Adapter for WBEM, the Adapter.

Task 

Description 

For Instructions 

Install the SNMP Adapter for WBEM. 

Install the Adapter when you install the Solaris operating environment. 

How to Install the SNMP Adapter for WBEM

Start the SNMP Adapter for WBEM. 

Start the SNMP Adapter for WBEM by moving snmpXwbem.rsrc- into snmpXwbem.rsrc.

How to Start the SNMP Adapter for WBEM

Disable or stop the SNMP Adapter for WBEM. 

Stop the SNMP Adapter for WBEM by using the pkill command.

How to Disable the SNMP Adapter for WBEM

Force the SNMP Adapter for WBEM to reread the mapping file directory. 

Force the SNMP Adapter for WBEM to reread the mapping file directory by updating snmpXwbem.reg so that it includes the new subtree, and by using the pkill command.

How to Force the SNMP Adapter for WBEM to Reread the Mapping File Directory

Installing and Using the SNMP Adapter for WBEM

This section describes how to install, start, stop, and use the SNMP Adapter for WBEM.

How to Install the SNMP Adapter for WBEM

    Install the Solaris operating environment on your system.

    The Adapter software is installed on your system along with the Solaris software.

How to Start the SNMP Adapter for WBEM

When you are ready to retrieve data from the CIM Object Manager through your SNMP application, follow these steps to start the Adapter.

  1. Become superuser.

  2. Stop the Master Agent.


    # /etc/init.d/init.snmpdx stop

  3. Change directory to /etc/snmp/conf.

  4. Move snmpXwbem.rsrc- into the Adapter resource file.


    # mv snmpXwbem.rsrc- snmpXwbem.rsrc

  5. Restart the Master Agent.


    # /etc/init.d/init.snmpdx start

How to Disable the SNMP Adapter for WBEM

When you are finished retrieving data from the CIM Object Manager or to modify a file in /etc/snmp/conf, you need to disable the Adapter. Follow these steps.

  1. Become superuser.

  2. Stop the Master Agent.


    # /etc/init.d/init.snmpdx stop

  3. Stop the Adapter.


    # /usr/bin/pkill -9 -x -u 0 snmpXwbemd

  4. Change directory to /etc/snmp/conf.

  5. Temporarily rename snmpXwbem.rsrc.


    # mv snmpXwbem.rsrc snmpXwbem.rsrc-

  6. Restart the Master Agent.


    # /etc/init.d/init.snmpdx start

How to Force the SNMP Adapter for WBEM to Reread the Mapping File Directory

After you place a new mapping file or update an existing mapping file in /var/sadm/wbem/snmp/map, you must signal the Adapter to reread all mapping files in the directory. You specify the signal SIGHUP to signal the Adapter.

Follow these steps to force the Adapter to reread all mapping files (without having to restart the CIM Object Manager).

  1. Become superuser.

  2. Does a new mapping file or a new entry in a mapping file reference a subtree that is not registered by the Adapter?

    • If yes, go to the next step.

    • If no, go to Step 5.

  3. Update /etc/snmp/conf/snmpXwbem.reg so that it includes the new subtree.

  4. Stop and restart the Master Agent.

    # /etc/init.d/init.snmpdx stop

    # /etc/init.d/init.snmpdx start

  5. Signal the Adapter that you have updated a mapping file. 


    # /usr/bin/pkill -1 -x -u 0 snmpXwbemd

Troubleshooting Problems With the SNMP Adapter for WBEM

This section lists specific console error messages that you might encounter when using the Adapter.

If you encounter errors, problems, or unexpected results that are not described in this section or if you want to troubleshoot problems more precisely, use the Solaris Management Console Log Viewer to view log data.

Instructions that describe how to start the Solaris Management Console Log Viewer are presented in Viewing Log Data Through Log Viewer.

Sending and Receiving Requests

Error Message


ERROR: sending request to Adapter Service.
 

ERROR: receiving request from Adapter Service.

Cause

Either snmpXwbemd believes WBEM is enabled but cannot communicate with the Adapter Service, or the request timed out.

Solution

Send another request. If sending another request fails, verify that the request and response FIFOs do not contain pending messages, that is, contain 0 bytes.

  1. Type:

    # cd /var/sadm/wbem/snmp

  2. Type:

    # ls -l

    The request and response FIFOs are listed.

  3. Does either FIFO contain pending messages (contain more than 0 bytes)?

    If yes, go to step Step 4.

    If no:

    1. Ensure that you need to stop WBEM by using the Solaris Management Console Log Viewer to view log data and determine the problem.

      Instructions that describe how to start the Solaris Management Console Log Viewer are presented in Viewing Log Data Through Log Viewer.

    2. If necessary, stop WBEM.

      # /etc/init.d/init.wbem stop

    3. Go to Step 9.

  4. Stop WBEM.

    # /etc/init.d/init.wbem stop

  5. Stop the Master Agent.

    # /etc/init.d/init.snmpdx stop

  6. Change to the directory in which the FIFOs are located.

    # cd /var/sadm/wbem/snmp

  7. Remove both FIFOs.

    # rm _adapter_rcv.fifo

    # rm _adapter_snd.fifo

  8. Restart the Master Agent.

    # /etc/init.d/init.snmpdx start

  9. If you stopped WBEM in Step 3 or in Step 4, restart it.

    # /etc/init.d/init.wbem start

FIFO Cannot Be Opened

Error Message


ERROR: request FIFO cannot be opened.
 

ERROR: response FIFO cannot be opened.

Cause

A protocol problem occurred either when the Adapter received a request or when the Adapter processed a response.

Solution

Send another request. If sending another request fails, verify that the request and response FIFOs do not contain pending messages, that is, contain 0 bytes.

  1. Type:

    # cd /var/sadm/wbem/snmp

  2. Type:

    # ls -l

    The request and response FIFOs are listed.

  3. Does either FIFO contain pending messages (contain more than 0 bytes)?

    If yes, go to step Step 4.

    If no:

    1. Ensure that you need to stop WBEM by using the Solaris Management Console Log Viewer to view log data and determine the problem.

      Instructions that describe how to start the Solaris Management Console Log Viewer are presented in Viewing Log Data Through Log Viewer.

    2. If necessary, stop WBEM.

      # /etc/init.d/init.wbem stop

    3. Go to Step 9.

  4. Stop WBEM.

    # /etc/init.d/init.wbem stop

  5. Stop the Master Agent.

    # /etc/init.d/init.snmpdx stop

  6. Change to the directory in which the FIFOs are located.

    # cd /var/sadm/wbem/snmp

  7. Remove both FIFOs.

    # rm _adapter_rcv.fifo

    # rm _adapter_snd.fifo

  8. Restart the Master Agent.

    # /etc/init.d/init.snmpdx start

  9. If you stopped WBEM in Step 3 or in Step 4, restart it.

    # /etc/init.d/init.wbem start

FIFO Cannot Be Created

Error Message


ERROR: FIFO cannot be created.

Cause

A system error occurred when the Adapter attempted to create the request or the response FIFO.

Solution

Verify that /var/sadm/wbem/snmp exists and has write access.

WBEM Services Are Not Started

Error Message


ERROR: WBEM Services are not started.

Cause

The Master Agent cannot detect if WBEM Services have started and are running.

Solution

Restart WBEM and wait the number of seconds to which watch-dog-time in snmpXwbem.reg is set.


# /etc/init.d/init.wbem start

After a period of time, the Master Agent starts the Adapter automatically. By default, the Master Agent tries to start the Adapter every four minutes (or number of seconds to which watch-dog-time is set).

Note –

If you do not want to wait for the Master Agent to start the Adapter automatically, stop and then restart the Master Agent.

# /etc/init.d/init.snmpdx stop

# /etc/init.d/init.snmpdx start

The Master Agent immediately starts the Adapter.

SNMP Provider

The SNMP Provider is a software component that provides information about managed elements to the CIM Object Manager, including configuration information about an SNMP device.

Note –

The SNMP Provider supports traps by listening to port 162 for SNMP V1 and SNMP V2 traps. To display the events that are generated by these traps, you must subscribe to CIM_SNMPTrapIndication.

Generating a MOF File From an SNMP MIB File

When you want to access Simple Network Management Protocol (SNMP) information through the SNMP Provider, you use a Management Information Base (MIB) file to generate a Managed Object Format (MOF) file. The mib2mof command generates qualifiers that enable the SNMP Provider to map CIM operations that are performed on the CIM classes in the MOF file to SNMP operations. The mib2mof command is described in mib2mof(1M).

Note –

The SNMP Provider supports SNMP traps. Traps are reported in the CIM process indication event CIM_SNMPTrapIndication. When a client subscribes to the provider for this event, the provider listens on port 162 for SNMP V1 and SNMP V2 traps. The information is copied from the trap to the indication. Then, the indication is delivered to the client.

The MOF files that describe the CIM Schema and the Solaris Schema are located in /usr/sadm/mof. MOF files are described in more detail in the Solaris WBEM SDK Developer's Guide.

How to Generate a MOF File From an SNMP MIB File

  1. Become superuser.

  2. Type the command:


    # mib2mof SNMP_MIB_filename

    Example: 


    # /usr/sadm/bin/mib2mof sysctl.mib