19.1 SNMP Proxy Agent Operation

The proxy agent runs on Sun workstations--either the one on which the management application is running or another workstation on the network. SunNet Manager management applications, such as the Console, communicate with the SNMP proxy agent (na.snmp) using the same RPC-based protocol as with other SunNet Manager agents. The SNMP proxy agent communicates with other devices using the SNMP protocol defined in RFC 1157, as shown in Figure 19-1.

Console (or other

RPC SNMP

SNMP

SNMP

manager)

proxy

Agent

Figure 19-1 SNMP Proxy Agent

The proxy agent allows you to manage any number of management information bases (MIBs) in which you can define either standard SNMP MIB objects or enterprise-specific objects. The proxy agent uses a schema file to map objects described in a MIB and SunNet Manager attributes. A schema file is the representation of a MIB used by SunNet Manager. How to generate schema files from MIBs is discussed later in this chapter. To ensure successful operation, a schema file must have a set of object definitions that are identical to those in the MIB--see Figure 19-2.

Figure 19-2

Several SNMP schemas are supplied with SunNet Manager:

• snmp.schema describes MIB I, as defined by RFC 1156.
• snmp-mibII.schema describes MIB II, as defined by RFC 1213.
• snmpv2-mibII.schema describes MIB II, as used by SNMP version 2. See the "SNMP Version 2 Support" section for a description of SNMPv2 support in the current release of SNM.

sun-snmp.schema describes the MIB associated with the SNMP agent (snmpd) for Sun workstations. This schema file provides MIB II support with Sun enterprise-specific extensions. For more information about the schemas for various RFC MIBs, refer to the snmpd(8) manual page.

Except for the two MIB II files (which differ only in the RPC number specified), each of the schema files listed above is a subset of the file that follows it. That is, snmp.schema is a subset of the two MIB II files, which are, in turn, are a subset of sun-snmp.schema

The SNMP proxy agent can simultaneously access any of the above-mentioned schemas, as well as other enterprise-specific schemas that you might create. Both the Console and the SNMP proxy agent need to access the same schema information. If the SNMP proxy agent and the Console are running on different systems, identical schema files must be accessible to both systems. The Console uses the Schema Locations setting of the Console Properties Locations category to locate the directories where the schema files reside. SNMP schema files on the Console are treated like any other schema files; they define groups, tables, attributes, etc., for the user interface. The SNMP proxy agent uses the keyword na.snmp.schemas in the snm.conf file to locate the directories where the SNMP schema files reside.

The following section describes in detail how the SNMP proxy agent works. Note that many of the operations of the proxy agent are defined by arguments passed in the request or with keywords in the snm.conf file on the proxy system. You should refer to the snm.conf(5) manual pages for the keywords that are related to the SNMP proxy agent.

When the SNMP proxy agent starts up (normally via inetd) it loads all the SNMP schemas located in the directories specified by the keyword na.snmp.schemas in the snm.conf file on its host system. Only SNMP-related schemas (schemas that contain an rpcid keyword value of '100122') are loaded.

When the SunNet Manager SNMP proxy agent receives a request for an SNMP agent on a particular device, it performs the following sequence of operations:

1. It checks whether there are any new or modified SNMP related schema files since the last request. If the proxy agent finds a new or modified schemas in any of the directories specified by the na.snmp.schemas keyword in the snm.conf file on the proxy's system, it loads the schema file.

2. It passes the request to an existing agent subprocess or forks a new subprocess, if needed, to handle the request. A single subprocess can handle multiple SNMP requests from an instance of a management application. The maximum number of subprocesses that the SNMP proxy agent can fork is set by the keyword na.snmp.max-subprocs in the snm.conf file. At

installation, this value is set to 20. The maximum number of requests that a subprocess can handle is set by the keyword na.snmp.max-requests in the snm.conf file. At installation, this value is set to 50.

3. It checks whether the request contained any optional arguments. Requests sent by the SNM management applications may include arguments in an SNMP request. For example, the Console sends SNMP-related arguments that are defined in the target element's Properties window. (Refer to the "Properties" section for information about the element's Properties window.) These arguments can include:

   a. The name of the schema to be used with the request. If, for some reason, the specified schema does not contain the attribute group specified in the request, the proxy agent attempts to use the schema specified by the keyword na.snmp.default-schema in the snm.conf file on its host system. At installation, the default schema is set to be:

• /usr/snm/agents/snmp-mibII.schema for Solaris 1.x installations
• /opt/SUNWconn/snm/agent/snmp-mibII.schema for Solaris 2.x installations.

This schema supports the MIB II definition.

b. Acommunity name that specifies the SNMP community name the proxy agent is to use when reading or writing attribute values. If no community name is specified, public is used for both Get and Set requests.

c. Arequest timeout that specifies the number of seconds the proxy agent is to wait for a response to a request sent to the target system. If no request timeout is specified, the proxy agent uses the value specified by the keyword na.snmp.request_timeout in the snm.conf file on its system. At installation, the value is set to 5 (seconds).

4. This step only applies if the proxy agent receives a request from a management application that is not an SNM version 2.3 or later management application. If you are using the proxy agent for the current product with the Console, skip to Step 5.

   If no schema name is specified in the request, the proxy agent searches various schemas for the attribute group specified in the request. Schemas are searched in the following order:

   a. The schema(s) specified for the target device in the SNMP host file on the proxy system. The SNMP host file also specifies the community names and request timeout to be used for the request.

Versions of the SNMP proxy agent prior to SunNet Manager 2.3 required that you define an SNMP host file so that the proxy agent could determine the correct schema file to use for each request. When used with the current version of the Console or other management application, the SNMP proxy agent does not require the SNMP host file to determine which schema file to use for each request. However, an SNMP host file will need to be defined in the following cases:

1. If you want to define the handling of traps on a per-device basis. 2. If the management application you are using with the current version SNMP proxy does not supply the schema name in a request.

The location of the SNMP host file is specified by the keyword na.snmp.hostfile in the snm.conf file on the proxy system. See the na.snmp.hostfile(5) man page for more information about the contents of the SNMP host file.

b. The schema specified by the keyword na.snmp.default-schema. If this schema is used, community names are assumed to be public and the request timeout is assumed to be 5.

5. The proxy agent then sends an SNMP message to the device and waits for a response.

   If the proxy agent is sending a Get request, the proxy sends up to three SNMP requests per reporting interval. (The maximum number of SNMP requests sent is specified by the keyword na.snmp.max_attempts in the snm.conf file--by default the value is set to 3.) For each PDU sent, the proxy waits for the specified request timeout for a response from the device. As mentioned previously, the request timeout can be an optional argument in the request. If it is not specified in the request, request timeout is either the request timeout value specified in the SNMP host file for the device or the value of the keyword na.snmp.request_timeout in the snm.conf file.

   If the proxy agent does not receive a response after sending three SNMP requests, it sends a "No response from system" report to the Console. (The keyword na.snmp.trap-if-no-response in the snm.conf on the proxy system determines whether the proxy agent sends a trap or an error report. At installation, the keyword's value is true--send a trap report.) The proxy agent then waits until the next reporting interval to send out another set of SNMP requests. If no reporting interval has been specified in the request, the proxy agent sends out SNMP requests every 30 seconds. If the proxy

agent does not receive a response when the last report is due, it sends both an error report and a trap report to the Console if na.snmp.trap-if-no-response is true.

If the proxy agent is sending a Set request, the proxy waits for the specified request timeout for a response before timing out. There is no attempt to re-send the request. The reason for this is as follows: Because UDP is the transport mechanism, there is no guarantee of message delivery, thus there is no way to determine whether the request or the response to the request was lost. If you do not receive a response from your initial Set request, you should perform a Get request to see whether or not the Set operation was successful.

6. When the proxy agent receives a response from the target device, it sends a report to the SNM rendezvous.

   If the proxy agent does not receive an acknowledgment from the rendezvous within a specified time, the proxy agent terminates the request. The specified time that the proxy waits for the rendezvous to acknowledge the report is specified by the na.snmp.report_timeout keyword in the snm.conf file. At installation, the keyword's value is set to 5 (seconds).

Normally, if the SNMP proxy agent is not performing any requests, it will exit. The keyword na.snmp.exit-if-no-requests in the snm.conf file allows you to specify otherwise.

Asynchronous or unexpected reports (traps) from SNMP agents are handled by the trap daemon na.snmp-trap, which may run on one or more machines on the network. The daemon listens for incoming traps on the SNMP trap port and translates them to SunNet Manager traps. The trap daemon uses an SNMP trap file, which contains information on enterprise-specific traps and attribution of events to pseudo-devices. Refer to the section on "SNMP Host Files" for more information about SNMP traps.

19.1.1 Trap Filtering

Setting Host Specific Trap Filters Starting with version 2.3, you can specify filters based on certain hosts. What you specify overrides any enterprise-specific filter. The keyword, <host>, can be used in the snm.conf file followed by the ip_address or host name and a

priority keyword. Each line beginning with the keyword <host> can be followed by subsequent lines describing the action, description, or priority for each trap.

Precedence Values The snm.conf file specifies general priority for all traps. The trap daemon compares oid entries with specific settings specified in snmp.traps when it receives a trap. If a particular trap has an oid entry in snmp.traps, the na.snmp-trap daemon will take priority. The na.snmp-trap daemon searches for the hostname of the target trap. If the name is present, the daemon will use it as its priority.

19.2 Schema Files

If you do not already have a schema file for the device you want to manage, use the SNM mib2schema utility to convert an existing MIB file for the device.

---

Note - Nested groups or nested tables are not supported in SNM schema files.

---

You may need to manually edit the resulting schema file produced by mib2schema. The areas that are likely to require changes are:

• When mib2schema encounters an OCTET STRING, it inserts -C ??? in place of a format string. If you want to format octet strings in a particular way, search the schema file for occurrences of -C ??? to replace ??? with the required format string. If a format string is specified, the SNMP proxy agent formats each octet of the attribute value it receives from an SNMP agent before sending the attribute value to a SunNet Manager rendezvous. You may, however, choose not to enter any format string. In this case, the contents of the OCTET STRING will be printed as is.

  The format string is the same as the sprintf(3S) format argument. Up to 16 octets can be formatted; each byte is sent to sprintf as a separate, unsigned character. For example, the format string:

%02.2X:%02.2X:%02.2X:%02.2X:%02.2X:%02.2X

causes an OCTET STRING containing a 48-bit Ethernet address to be formatted in standard colon notation (for example, 08:00:20:07:8F:93).

---

Note - The format string and the length of the OCTET STRING to be formatted must match. All bytes specified in the format string are displayed. If the OCTET STRING is smaller than the format string, unexpected characters may be displayed in the formatted output.

---

Note that the -C format parameter is only used if the parameter -T STRING is specified for the attribute. If the parameter -T STRING is specified and -C format is not specified, the attribute is displayed as either octets or as a string, depending upon whether the attribute is an octet or display string.

An example of the characteristics string for the ifPhysAddress attribute in the ifStatus table is shown below:

"-N ifPhysAddress -O 1.3.6.1.2.1.2.2.1.6 -T STRING -A RO -C %2.2X:%2.2X:%2.2X:%2.2X:%2.2X:%2.2X -X equal -F 0"

This results in the display:

ifPhysAddress=08:00:20:09:A0:D5

• Some SNMP devices cannot return groups or tables with a large number of attributes; this is due to local space limitations. When this happens, the SNMP proxy agent returns an error message that the response is "too big". This means that very large groups or tables need to be split into smaller groups or tables to be received by the SNMP proxy. mib2schema does not automatically split groups or tables. Generally, if a group has more than 15 fields, it is a good idea to split the fields up into smaller groups. You can choose your own name for subgroups.

In addition to the schema file, the mib2schema utility produces an object identifier file (with the .oid suffix) that contains a table of object identifiers and names. Run the build_oid utility to add the contents of the resulting object identifier file to the SNM Object Identifier Database. See the build_oid(1) manual page for more information.

mib2schema may also produce a trap definition file (with the.traps suffix), depending upon whether traps were specified in the MIB. Refer to (refer to Section 19.4, "Asynchronous Event Reports (Traps)," on page 19-12 for more information about using the trap definition file.

If mib2schema cannot determine the key for a table characteristics field in the schema file, it inserts -K ??? into the schema file.

19.3 SNMP Host Files

The SNMP host file maps a request with a schema file. It also maps devices with trap files (refer to Section 19.4, "Asynchronous Event Reports (Traps)," on page 19-12. Create an SNMP host file only for the following conditions:

• You want to specify the handling of traps on a per-device basis.
• You are using the current version of the SNMP proxy agent with an SNM 1.x version management application.
• You are using a 1.x version of the SNMP proxy agent.

---

Note - If you do not meet any of the above conditions, you do not need to create an SNMP host file.

---

The name of the SNMP host file is defined by the na.snmp.hostfile keyword in the snm.conf file. The default location for the hosts file is:

• /var/adm/snm/snmp.hosts for Solaris 1.x environments
• /var/opt/SUNWconn/snm/snmp.hosts for Solaris 2.x environments.

Each line in the SNMP host file specifies information for a single device. The line contains five to seven fields, defined below (the first five fields are mandatory):

<host-name> <read-community> <write-community> <request-timeout> <schema-file> <trap-file> <vendor-proxy>

where:

<host-name>

is the name of the SNMP device. This name must match the element instance name (system name) of the device in a Console view. The name is not case sensitive.

<read-community>

is the SNMP community name the proxy agent uses when reading attribute values from <host-name> and when sending traps.

<write-community>

is the SNMP community name the proxy agent uses when writing attribute values to <host-name>.

<request-timeout>

is the number of seconds the proxy agent waits for an SNMP response from <host-name>.

<schema-file>

is a colon-separated list of the names of the agent schema files that contain the group and attribute definitions for <host-name>. Each name must be an absolute path name that begins with a 'slash' (/). Note that each schema file must reside in a directory that is specified by the keyword na.snmp.schemas in the snm.conf file on the proxy system.

<trap-file> (optional) is the name of the trap file that contains the trap definitions for <host-name>. This must be either an absolute path name that begins with a slash (/) or "-" to specify the default trap file. Note that the directory in which the trap file resides must be a directory that is specified by the keyword na.snmp.schemas in the snm.conf file on the proxy system. Note that the Console displays the entries in the most recently submitted trap file. If the SNMP host file points to two different trap files, data in the most recent one will be read. Refer to Section 19.4, "Asynchronous Event Reports (Traps)," on page 19-12 for more information about traps and the trap file.

<vendor-proxy> (optional) is an optional field that specifies the name of a proxy system. If this field is set, the SNMP request is not sent to <host-name>, but will be sent instead to <vendor-proxy>. This parameter should be specified only when a vendor has supplied an SNMP proxy agent to manage a particular device or set of devices. In this situation, the vendor's SNMP proxy agent communicates with the SunNet Manager SNMP proxy agent via SNMP, but communicates with the target device using either SNMP or a different protocol. If you specify this field, you must specify a value for <trap-file>.

An example of an SNMP host file with three device entries is shown below:

sunbox public private 5 /opt/SUNWconn/snm/agents/sun-snmp.schema device1 admin admin 10 /snm/vendor/device1.schema /snm/vendor/device1trap.schema device2 public administrator 10 /snm/vendor/device2.schema - proximo

19.4 Asynchronous Event Reports (Traps)

SNMP agents may return unsolicited or unexpected reports called traps. SNMP defines six generic trap types for the following conditions:

0    coldStart
1    warmStart
2    linkDown
3    linkUp
4    authenticationFailure
5    egpNeighborLoss

In addition, trap type 6 is used for enterprise-specific traps. Enterprise-specific traps contain an enterprise object identifier (OID) and an enterprise-specific trap number.

19.4.1 Trap Daemon Operation

The SNMP trap daemon (na.snmp-trap) is installed with SunNet Manager agents and daemons, normally in the agents directory. The trap daemon translates received SNMP traps into SunNet Manager traps and forwards them to the Event Dispatcher on one or more management stations.

When the SunNet Manager SNMP trap daemon receives a trap, it performs the following sequence of operations:

1. It first determines what to do with the received trap. The SNMP trap daemon uses an SNMP trap file to carry out the following tasks:

• Translate trap type numbers to ASCII strings
• Determine if a trap should be discarded
• Determine the database element (glyph) to which a trap should be attributed (in cases where elements represent pseudo-devices -- components that do not have their own IP address but share the network address of a device they are parts of, or attached to)

Refer to Section 19.4.2, "SNMP Trap File," on page 19-14 for more information about creating trap files.

To locate the appropriate trap file, the trap daemon first checks the SNMP host file to see if there is an entry for the device. The SNMP host file allows you to map specific devices to trap files. Refer to Section 19.3, "SNMP Host Files," on page 19-10 for more information about the SNMP host file.

If the trap daemon cannot find a trap file for the device in the SNMP host file, it then searches a default trap file. The default trap file is specified by the na.snmp-trap.default-trapfile keyword in the snm.conf file on the system where the trap daemon is running. Normally, the file name is:

• /var/adm/snm/snmp.traps for Solaris 1.x installations
• /var/opt/SUNWconn/snm/snmp.traps for Solaris 2.x installations.

  The default trap file allows you to specify the handling of traps on an enterprise or host basis.

  If the trap daemon cannot find an entry for a trap type in a trap file defined in the SNMP host file or in the default trap file, it forwards the trap to the Event Dispatcher on the management station(s) using the precedence values described in "Precedence Values" on page 19-8.

  If the trap daemon encounters any kind of syntax error while reading a trap file, it sends an error message indicating the line of the error and forwards the trap.

2. If the trap is not discarded, the trap daemon then searches through the loaded schema files for an OID match.

   A trap may include a list of variables and their values that provide further information about the cause of the trap. Normally, the variable is in the form of a raw object identifier (OID). If the trap includes such variables, the SNMP trap daemon can translate the raw OIDs into ASCII text. If the variable is an enumerator data type, the trap daemon translates the variable's integer value into an equivalent ASCII string. The translation for each variable can be specified in a SNMP schema file that contains the OID.

   When the trap daemon is started up, it loads the following files:

   a. Schema files in the directories specified by the keyword na.snmp.schemas in the snm.conf file

b. The schema file specified by the keyword na.snmp.default-schema in the snm.conf file. This file is normally snmp-mibII.schema in the agents directory.

c. snmp-mibII.schema (in the agents directory), if it is not specified as the value of the keyword na.snmp.default-schema.

---

Note - The SNMP trap daemon does not load duplicate schema files. A particular OID can only be defined in one schema file.

---

If an OID match is found in a schema file, the trap daemon performs the translation before sending the trap to the Event Dispatcher. Since enumeration types for traps are not supported by SunNet Manager, the trap daemon translates enumerations to a string if it can find the enumeration definition in a schema file. Otherwise, the enumeration is returned as an integer. If the trap daemon is unable to find an OID match in the loaded schema files, the raw OID is forwarded to the Event Dispatcher.

Normally, if the trap daemon finds an OID match in a schema file, it only forwards translated attribute name/value pairs to the Event Dispatcher. The keyword na.snmp-trap.raw in the snm.conf file allows you to specify that the SNMP trap daemon return raw OIDs and their values without translation, in addition to the translated attribute names and values--see the snm.conf(5) manual page for more information.

3. The trap daemon then forwards the trap to the Event Dispatcher. By default, the trap daemon na.snmp-trap sends trap reports to the Event Dispatcher on the machine on which the trap daemon is installed. The keyword na.snmp-trap.rendez in the snm.conf file allows you to specify the names of one or more manager systems that should receive the traps processed by the SNMP trap daemon -- see the snm.conf(5) man page for more information.

19.4.2 SNMP Trap File

As mentioned previously, the SNMP trap daemon uses a trap file to:

• Translate enterprise-specific trap type numbers to ASCII strings
• Determine trap priority
• Determine if a trap should be discarded

• Determine which database element (glyph) a trap should be attributed to (in cases where elements represent pseudo-devices -- components that do not have their own IP address but share the network address of a device they are parts of, or attached to)

If you used the mib2schema utility to create your schema file and traps were specified in the MIB, mib2schema generates a trap file. Otherwise, you need to create a trap file for any of the above-mentioned purposes.

See Chapter 8, "Managing SNMP Devices" for information on setting trap priorities.

---

Note - If you use glyph entries in the trap file, the associated SNMP trap daemon must run on the host which has the SNM database where these elements reside. The trap daemon cannot be distributed to machines where the SNM Console is not installed because the trap daemon must access the SNM database to retrieve the properties of the specified elements.

---

19.4.2.1 Trap File Entries for Enterprise and Host-Specific Traps

The trap file may contain one or more lists of generic, enterprise-specific or host-specific traps. Each list begins with a line containing the keyword enterprise followed by the enterprise object identifier. Subsequent lines contain a trap number, trap name, and, optionally, the keyword discard. Comments may be added by beginning a line with a pound sign (#). The syntax for the trap file is shown below:

enterprise <enterprise-object-ID> <trap-number> <trap-name> [discard]

<enterprise-object-ID>

is the enterprise object identifier. If you want to discard generic traps, specify zero for the <enterprise-object-ID>.

<trap-number>

is an integer that represents the trap number of an enterprise-specific trap. If you want to discard a generic trap, specify the trap type number: 0, 1, 2, 3, 4, or 5.

<trap-name>

is the ASCII string associated with the <trap-number>. <trap-name> can be up to 127 characters in length; blanks are not allowed.

The keyword discard specifies that the trap daemon should not forward the trap to the Event Dispatcher. As mentioned previously, traps are treated as high priority events. You can specify the discard keyword for traps that you do not wish to be notified about, such as system reboots.

For example, the first example below defines enterprise-specific traps for the Sun enterprise and specifies that generic trap type 0: is to be discarded. The second example defines host-specific traps for the host Odyssey.

# generic traps enterprise 0 0 cold-start discard # Sun Microsystems traps enterprise 1.3.6.1.4.1.42 1 CPU_Failure high 2 Power_Supply_Failure low 3 Network_Connection_Failure medium 4 Over_Heating discard 5 RealTimeClock_Failure discard

# #Sample traps # host Odyssey 1 CPU_Failure high 2 Power_Supply_Failure medium 3 Network_Connection_Failure high

When searching the SNMP trap file for matches, the SNMP trap daemon only compares as much of the enterprise identifier as specified in the SNMP trap file. For example, a file with the line:

enterprise 1.3

would match all enterprises beginning with 1.3. Since the searching is performed from the top of the file, you should place more restrictive enterprise identifiers before less restrictive ones.

If you define a single trap file that applies to all or most of your SNMP devices, you should make this file the default trap file. For example, suppose that you do not want to see any generic traps for most of the SNMP devices in your management domain. You would define a trap file that specifies that generic trap types 0 through 5 be discarded and make this the default trap file. If there are a couple of critical devices for which you want to see generic trap types, define another trap file that does not specify that the generic trap types be discarded. Create an entry for each device in the SNMP host file and specify the second trap file. Because the trap daemon searches the SNMP host file first to match a trap to a device name, generic traps will be returned for only those devices specified in the SNMP host file.

You create the SNMP host file on the system where the trap daemon resides. Refer to "SNMP Host Files" for information on creating the host file. If you have only one trap file that applies to all your SNMP devices, you can specify the trap file as the default trap file--you would not need to create an SNMP host file.

19.4.2.2 Attributing Traps to Glyphs

Glyph entries in the trap file allow the user to attribute traps to database elements that represent pseudo-devices -- network components that do not have their own IP address but share the network address of a device that they are components of, or to which they are attached.

An example would be glyphs that represent the ports on a hub. In this case the trap-attribution feature would allow the SNMP trap daemon to determine which port is the source of the event. When a trap is generated (for example, due to a hub port failure), the appropriate Console effect -- such as blinking or color by priority -- would then be applied to the glyph for that port rather than to the hub as a whole, facilitating fault-isolation.

If you have vendor software whose MIB supports this trap-distribution feature, there are five tasks that must be accomplished to enable it for your Console:

• The agent schema file that supports the trap-distribution feature -- either provided by the vendor or created from the vendor MIB using the mib2schema utility -- must be installed in the agents directory.

• An appropriate glyph entry must be added to an SNMP trap file on the system where the SNMP trap daemon runs (and this must be the system on which the SNM Console runs).
• The snmp.hosts file must also exist on the system where the trap daemon runs and must contain an entry that identifies the SNMP trap file to be used for interpreting traps from the originating device.
• An element definition must be provided for the pseudo-device in the elements.schema file (or a separate element schema file in the agents directory) and this definition must contain a field used to correlate this pseudo-device with a particular glyph. This field must match the appropriate field used by the enterprise-specific agent schema.
• An icon and iconmask to represent the pseudo-device must exist in one of the directories specified for icon locations in the Console properties sheet.

For information on creating an agent schema from a vendor MIB, refer to Section 19.2, "Schema Files," on page 19-8." How to point the SNM Console to the location of the icon and iconmask is discussed in "Locations" in Chapter 17, "Props Menu."

The other tasks can be accomplished as follows:

1. Trap File Glyph Entries

   The glyph entry in the trap file must begin with the keyword glyph and have the following syntax:

glyph <trap_attribute> <database_user_name> <component_type> <component_property>

<trap_attribute>

is the attribute whose value will be matched against the value of the property in the component property sheet to determine the glyph to be associated with the trap.

<database_user_name>

is the name of the runtime SNM database without the "db." prefix. The user name must be provided because the trap daemon could have been started by the inetd process; in that case, the user owning the trap daemon will not be the same as the user running the Console. This field is used to create the SNM_NAME environment variable required to access the SNM database.

<component_type>

is the type of the component whose property is to be compared (for example, component.pseudo).

<component_property>

is the property of the component whose value will be compared against the trap attribute value.

A sample glyph entry would be the following:

glyph ifPortKey alfred component.hubport PortKey

In this example, ifPortKey is in the variable binding list of the trap Protocol Data Unit (PDU). To determine if this trap should be attributed to a particular glyph, the trap daemon is to look at the value of the property PortKey for an element. The trap is to be attributed to that glyph if the glyph's PortKey value matches the value passed in the trap's ifPortKey variable. alfred is the name of the SNM database user and component.hubport is the element type.

2. SNMP Host File Entry

   An entry must be added to the SNMP hosts file only if a schema file other than the trap daemon's default SNMP schema file is to be used to enable the trap-distribution feature. The hosts file resides in the same directory as the trap file. The syntax of host file entries is as follows:

<host-name> <read-community> <write-community> <request-timeout> <schema-file> <trap-file> <vendor-proxy>

For other types of host file entry, <host-name> is the name of the SNMP device. However, for the glyph-distribution feature, <host-name> is to be the name of the host where the proxy agent resides. In a standard host file entry, the proxy system name is specified in the <vendor-proxy> field. However, for purposes of the pseudo-device trap-attribution feature, the optional <vendor-proxy> field is never used since this information is specified in the <host-

name> field. For more information about the SNMP host file, refer to Section 19.3, "SNMP Host Files," on page 19-10." An example of a host file entry to implement the trap-distribution feature would be the following:

bigguy public private 20 /opt/SUNWconn/snm/agents/snmp- pseudodev.schema /var/opt/SUNWconn/snm/snmp.traps

In this example, "bigguy" is the name of the host where the SNMP proxy agent resides. /opt/SUNWconn/snm/agents/snmp-pseudodev.schema is the vendor agent schema; the only reason the host file is necessary is to point to this file.

3. Adding an Element Definition for the Pseudo-device

   You will need to add a component definition for the glyph that represents the pseudio-device. The component definition is created in the form of a record definition as in the following example:

record component.hubport ( # generic sun 4 string[64] Name string[40] User string[40] Location string[80] Description netaddress Port_Key string[40] SNMP_RdCommunity string[40] SNMP_WrCommunity string[64] SNMP_Vendor_Proxy int SNMP_Timeout ) # Glyphs for components instance elementGlyph( ( component.hubport hubport.icon) )

The fields in this element definition will be displayed in the properties sheet for glyphs of this type, as shown in Step 19-3.

Figure 19-3

Note that underscores in the element definition are displayed as spaces in the field names. In this example, the Port Key field gives the attribute -- a user-defined port number -- that is used to match traps to glyphs. (This "Port Key" value is in the same format as an IP address though it is not an IP address.) For information on how to create element definitions, see the section on "Element Instance Definition." This definition can be added to the elements.schema file or to another element schema file in the agents directory.

This component definition must include a field that will have the same value as the SNMP trap attribute that will be matched with it. The following restrictions apply:

• The trap attribute to be matched with the component property must be in the variable binding list in the trap PDU. This follows the regular members of a trap message, which are the following:

• Version
• Community
• Enterprise
• Agent address
• Generic trap type
• Specific trap type for enterprise-specific trap
• Time stamp

• For purposes of matching the element property to the SNMP attribute, only the SNMP types listed in Table 19-1 are supported.

Table 19-1

SNMP Type	SNMP Attribute Type	Element Schema Attribute Type
INTEGER	int	int
INTEGER	enum	enum
OCTET STRING	string	string
IPAddress	netaddress	netaddress
NetworkAddress	netaddress	netaddress
OBJECT IDENTIFIER	objectid	string

19.4.3 Trap Reports on the Console

On a Console system, trap reports are logged with other event and error reports and are displayed by selecting the Console's View >> Event/Trap Reports menu item.

Changes in a glyph's state that results from a trap are propagated through the Console's view hierarchy as if an event had occurred. You determine the priority of an SNMP trap as described in Chapter 8, "Managing SNMP Devices." The type of signal that the Console uses to indicate received traps is specified in the Events and Traps category of the Console's Properties window. By default, the Console blinks the glyph of the target element when a trap is received.

19.4.4 Interpreting a Trap Report

A typical trap report logged in the Event/Trap Reports window looks like the following:

Figure 19-4

The lines in the trap report are described below:

The header is the line at the top which shows the date, time and hostname of the device which generated the trap.

sequence a counter showing the sequence number of the trap; also keeps track of the number of traps generated since the device was last booted

receive-time the time the Console received the trap

version returned by the device which generated the trap

community the SNMP trap community name sent by the device which generated the trap

enterprise enterprise name of the device which generated the trap

source-time length of time between when the device was booted and when the trap was generated

trap-type whether this trap is generic or enterprise-specific

trap-no where in the sequence of traps this one falls

trap-name a name you have specified or a default name

priority the priority of this trap (low, medium or high)

Note that underscores in the element definition are displayed as spaces in the field names. In this example, the Port Key field gives the attribute -- a user-defined port number -- that is used to match traps to glyphs. (This "Port Key" value is in the same format as an IP address though it is not an IP address.) For information on how to create element definitions, see the section on "Element Instance Definition." This definition can be added to the elements.schema file or to another element schema file in the agents directory.

This component definition must include a field that will have the same value as the SNMP trap attribute that will be matched with it. The following restrictions apply:

• The trap attribute to be matched with the component property must be in the variable binding list in the trap PDU. This follows the regular members of a trap message, which are the following:

  · Version

  · Community

• Enterprise
• Agent address
• Generic trap type
• Specific trap type for enterprise-specific trap
• Time stamp

• For purposes of matching the element property to the SNMP attribute, only the SNMP types listed in Step 19-2 are supported.

Table 19-2

SNMP Type	SNMP Attribute Type	Element Schema Attribute Type
INTEGER	int	int
INTEGER	enum	enum
OCTET STRING	string	string
IPAddress	netaddress	netaddress
NetworkAddress	netaddress	netaddress
OBJECT IDENTIFIER	objectid	string

19.4.5 Trap Reports on the Console

On a Console system, trap reports are logged with other event and error reports and are displayed by selecting the Console's View >> Event/Trap Reports menu item.

Changes in a glyph's state that results from a trap are propagated through the Console's view hierarchy as if an event had occurred. SNMP traps are treated as high-priority events. The type of signal that the Console uses to indicate received traps is specified in the Events and Traps category of the Console's Properties window. By default, the Console blinks the glyph of the target element when a trap is received.

19.4.5.1 Remaining Fields

Remaining fields, if any, are variables whose values are returned by the trap. Some traps do not return variables. These values are usually relevant to the reason the trap was generated. When the trap daemon receives a trap, it attempts to translate variables from OIDs into ASCII text before forwarding the trap. See the section on "Trap Daemon Operation" for more information.

19.4.6 Mapping SNMP Object IDs to Strings

One of the data types supported by SunNet Manager is an object identifier. Since object identifiers are numeric (for example, 1.2.3.4.5), a database is provided so the Console can display the object identifier using a more meaningful string. The Object Identifier Database (OID) provides the information for this mapping. The build_oid utility builds the OID. The Console uses the database to interpret object identifiers.

You will probably want to build the OID when new object identifiers are added to the database. Input files for build_oid are ASCII files with the suffix .oid. Each file has a descriptive name followed by its object identifier. If the descriptive name contains special characters, enclose it in double quotes. You can include comment lines by beginning them with a pound sign (#). When mib2schema is used to convert a MIB to a schema file, it also generates a .oid file.

To locate input files, build_oid uses the directories specified by SNMHOME/agents and SNMHOME/schemas. If you have not defined the SNMHOME environment variable, the directories are:

• /usr/snm/agents and /usr/snm/struct for Solaris 1.x installations
• /opt/SUNWconn/snm/agents and /opt/SUNWconn/snm/struct for Solaris 2.x installations

You can also specify other directories as input arguments (see the build_oid(1) man page for more information). SunNet Manager provides three input files which are normally found in the /usr/snm/agents directory:

• enterprises.oid contains the mappings for a variety of enterprise and organization identifiers.
• snmp.oid contains the mappings for object identifiers for MIB I of the SNMP protocol.

• sun-snmp.oid contains the mappings for object identifiers referenced by the Sun SNMP agent, snmpd. The Sun agent implements a superset of MIB II; thus, this file also serves as a snmp-mibII.oid file.

The environment variable SNMDBDIR specifies the directory for writing the output database oid.dbase. If you have not specified the SNMDBDIR environment variable, the directories are:

/var/adm/snm for Solaris 1.x installations

/var/opt/SUNWconn/snm for Solaris 2.x installations.

19.5 SNMP Version 2 Support

This section assumes you are familiar with SNMPv2 concepts. Instructions for installing and de-installing SNMPv2 are in your installation guide for Solaris 2.x/x86.

SunNet Manager provides a proxy agent that supports SNMPv2. This proxy agent allow you to get data and event information from and set attribute values for devices managed through SNMPv2.

There is also an SNMP agent for Sun workstations called the snmpv2d daemon. The Console communicates with this daemon through the SNMP proxy agent. The snmpv2d daemon also allows Sun workstations to be managed by other SNMPv2 and SNMP stations. For more information about the snmpv2d daemon, see the snmpv2d(8) man page.

The following sections discuss the differences between SNMP and SNMPv2. For information about the SNMPv2 configuration files, see the following man pages:

v2install(1), acl.pty(5), agt.pty(5), context.pty(5), mgr.cnf(5), mgr.pty(5), snmpv2d.conf(5), and view.pty(5).

---

Note - When the Discover tool locates SNMP devices on your network, it cannot determine whether the devices support functionality specific to SNMPv2.

---

19.5.1 SNMPv2 Enhancements

The key enhancements from SNMP to SNMPv2 are in the following categories:

• Structure of Management Information (SMI)
• Protocol operations
• Manager-to-manager capability
• Security

19.5.1.1 Structure of Management Information

The SMI for SNMPv2 is based on the SMI for SNMP. The SNMPv2 SMI provides more extensive specification and documentation of managed objects and MIBs.

Several new data types were created for SNMPv2. These include a 64 bit-counter (Counter 64) and the UInteger32 type which allows representation of integers in the range 0 to 2³² - 1.

The SNMPv2 OBJECT-TYPE macro includes an optional UNITS clause, which contains a textual definition of the units associated with an object. This clause is useful for any object that represents a measurement in units (ex. "seconds"). The OBJECT-TYPE macro for SNMPv2 also incudes a MAX-ACCESS clause which allows you to specify the maximum level of access.

19.5.1.2 Protocol Operations

SNMPv2 has three new protocol data units (PDU). The SNMPv2 trap PDU works in a way similar to that of the SNMP trap PDU, but it uses the same format as most other SNMPv2 PDUs. This eases the receiver processing task.

A major enhancement for SNMPv2 is the GetBulkRequest PDU. This PDU can significantly minimize the number of protocol exchanges required to retrieve a large amount of management information.

The third additional PDU is the InformRequest PDU. This is sent by an SNMPv2 manager, on behalf of an application, to another SNMPv2 manager. The PDU provides management information to an application using the second SNMPv2 manager.

19.5.1.3 Manager-to-Manager Capability

Manager-to-Manager operations are supported through the use of the manager-to-manager MIB. This MIB is a set of objects which describe the behavior of an SNMPv2 entity acting in a manager roll. For more information, see RFC 1451.

19.5.1.4 Security

SNMPv2 uses the Secure SNMP (S-SNMP) party concept for security. Improvements over S-SNMP include the elimination of ordered delivery mechanism and simplification of the clock synchronization algorithm. In addition, SNMPv2 introduces the context concept. Contexts provide for more efficient storage of access control and MIB view information. SNMPv2 uses both DES and MD5 for message security and authentication.

19.5.2 SNMPv2 Files

You can install SNMPv2 as an agent (snmpv2d), a manager (na.snmpv2), or both. The required files are installed as part of the current product. Installation steps are the same for both agents and managers. After the current SunNet Manager product is installed, create the three configuration files required by the v2install script. The files are:

• agents - contains names of hosts on which the snmpv2d agent will be installed
• mgrs.v1 - contains names of hosts that will be running SNMPv1 managers (na.snmp)
• mgrs.v2 - contains names of hosts that will be running SNMPv2 managers (na.snmpv2)

See the v2install(1) man page for detailed information about these files.

Procedures for installing (or removing) SNMPv2 software are in your installation guide for Solaris 2.x/x86.

19.5.3 Using the v2mib2schema Program

A program, v2mib2schema, has been included with the current product to allow you to translate your own SNMPv2 MIBs to SNM schema files.

Be aware that SunNet Manager schemas do not have the flexibility of SNMPv2 MIBs, so changes to the MIB may be necessary before v2mib2schema can successfully parse it.

Although v2mib2schema parses TEXTUAL-CONVENTIONS clauses, it currently ignores them, so later references to the new types will cause syntax errors. See the v2mib2schema(5) man page for more details.