# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

# 7.3 Initializing the SNMP Interface

In order for SNMP consoles to communicate with the ACMS Remote Manager through SNMP, the Remote Manager SNMP interface must have been started. The SNMP interface runs as a separate thread in the Remote Manager and can be started or stopped at any time without restarting the Remote Manager.

The SNMP interface is started using the SET INTERFACE command. The current state of the interface can be determined using the SHOW INTERFACE command. Refer to Section 4.5 for more information about using ACMSCFG and ACMSMGR to start and stop interfaces.

During startup, the SNMP interface first performs some housekeeping tasks and then attempts to register with the SNMP master agent.

In order for the SNMP interface to initialize successfully, the following conditions must be met:

- The ACMS$SNMP account on the Remote Manager node must exist.
- The ACMS$MGMT_READ, ACMS$MGMT_WRITE, ACMS$MGMT_OPER, and ACMS$MGMT_SYSUPD rights identifiers must exist. At least one of these identifiers must be granted to the ACMS$SNMP account.
- The SNMP master agent must be running on the Remote Manager node.

If any of the initialization tasks fail, or if registration fails, the SNMP interface writes error messages to the Remote Manager log and the thread exits. In this case, users should check the Remote Manager log for messages, correct the problem, and restart the interface.

During initialization, the Remote Manager establishes a timeout that the master agent will use when communicating with it. The timeout is based on the value of the Remote Manager parameter SNMP_AGENT_TIME_OUT.

If initialization is successful, the SNMP interface thread waits for incoming SNMP requests. The wait times out periodically (based on the Remote Manager parameters SNMP_SEL_TIME_OUT and SNMP_ARE_YOU_THERE stored in the Parameter table), and checks to make sure the SNMP master agent is still running by sending an "are you there" message to the master agent. If the master agent responds, the Remote Manager continues to wait for incoming messages. If the master agent does not respond, the SNMP interface thread attempts to restart the connection. If the restart fails, the SNMP thread exits.

# 7.4 SNMP Tables

The tables in Chapter 9 and the tables defined in the ACMS MIB map to each other on a one-to-one basis. However, data types are slightly different between SNMP and RPC, most significantly in the use of the gauge structure type. Section 7.4.1 describes data type mapping.

When accessing any of the ACMS MIB tables, it is important to keep in mind the dynamic nature of the ACMS run-time system. ACMS entities may be stopped and restarted; collection states for the entities may change dynamically; new processes (especially EXC and CPs) may be created. It is also important to understand that the size of some ACMS MIB tables may change when either the ACMS run-time system is restarted, or even as certain processes are started and stopped.

If the proper access strategies are not used when getting or setting ACMS MIB data, unpredictable and erroneous results can occur.

Different access strategies must be used for different types of tables. In the ACMS MIB, there are three types of tables. Specific access strategies for each table type are discussed in separate sections, as follows:

- Single-row tables (see Section 7.4.2)
- Static tables (see Section 7.4.3)
- Dynamic tables (see Section 7.4.4)

Also refer to Section 7.4.5 for a discussion of how the Server and Task Group tables are indexed.

Regardless of the type of table, identity and state validation should be performed for all ACMS entity tables (ACC, TSC, CP, QTI, EXC, server, task group).

Identity validation is performed by storing the PID field of the process occupying the row the first time the row is accessed. Then, when revisiting the table, get the PID along with the data values. Then check that the PID has not changed. If it has, the data refers to a new process.

Note that the process name is not a good means of identifying a process, because process names can be reused between entity executions.

Also note PID is not an ID class field for servers and task groups. For these two entity types, the EXC PID should be used.

State validation is performed by checking the collection state for the class that contains the field. For instance, if the exc-current-waiting-tasks-num (in the EXC run-time class) is being monitored, ensure that the exc-rt-coll-state is enabled (equal to 1). Otherwise, the value in that field is no longer being updated by the EXC, and is no longer accurate.

## 7.4.1 Data Type Mapping

The ACMS Remote Manager implements three data types:

- Integer
- String
- Gauge

The integer and string data types map directly to the SNMP INTEGER and DisplayString data types.

The gauge data type defined for the Remote Manager is not the same as the SNMP Gauge type. In order to avoid confusion, the Remote Manager SNMP interface maps the Remote Manager gauge fields to SNMP INTEGER and DisplayString data types. So for each Remote Manager gauge data type, three fields are defined in the MIB: the current field value, the maximum (or minimum) field value, and the maximum (or minimum) field value time.

For example, consider the ACC run-time field current_appls. This is defined as a Remote Manager gauge data type in Section 9.2. In the MIB, three fields are defined:

    acc-current-appls-num            INTEGER,
    acc-current-appls-max            INTEGER,
    acc-current-appls-time           DisplayString

This is the case for all Remote Manager gauge data types. For Remote Manager min gauge data types, there is a -min field instead of a -max field. For both gauge data types, time is expressed in the form DD-MMM-YYYY HH:MM:SS.hh.

## 7.4.2 Single-Row Tables

Access to single-row tables is straightforward, because only a single row is ever accessed. The following are single-row tables:

- ACC table
- QTI table
- TSC table
- Parameter table
- Remote Manager table

Bounds checking need not be performed. However, for Entity tables (ACC, QTI, TSC), both identity and state validation must be performed.

## 7.4.3 Static Tables

Static tables are sized when the parent process starts and do not change as long as the parent process is running. For each static table, there is a field in the table of the parent process that indicates the upper bound of the static table.

Table 7-1 shows the static tables, their parent process, and the field that indicates the upper bound of the table.

Table 7-1 Static Tables
Table | Parent Process | Upper Bound (field and table)
--- | --- | ---
CP | TSC | tsc-cp-slots-active in the TSC table
EXC | ACC | acc-max-appl-active in the ACC table
Server | EXC | exc-server-types in the EXC table
Task Group | EXC | exc-task-groups in the EXC table
Interfaces | Remote Manager | rmIfCt in the Remote Manager table
Collection | Remote Manager | totl-entity-slots in the Parameter table

In static tables, table data is not always contiguous and table rows can be reused. The PID field should be used to establish process identity.

For example, consider the following CP table. Assume that the first CP is permanent, and the second two are not.

    Table Row   CP process name   CP PID
    1           ACMS01CP001000    2040013D
    2           ACMS01CP002000    2040013E
    3           ACMS01CP003000    2040013F

An SNMP console searching this table sequentially would find all three CP instances; access to table row 4 would return an error. However, if the users attached to the CP in table row 2 log out, the CP terminates and the table now looks like this:

    Table Row   CP process name   CP PID
    1           ACMS01CP001000    2040013D
    2
    3           ACMS01CP003000    2040013F

An SNMP console searching this table sequentially and stopping when the first error is returned would find only the first CP. Access to the second row would return an error. Therefore, when scanning static tables, it is important to examine all rows of the table before terminating the scan; that is, perform a loop based on the tsc-cp-slots-active field in the TSC table.

Finally, consider what happens if a new CP now starts. The table would look as follows:

    Table Row   CP process name   CP PID
    1           ACMS01CP001000    2040013D
    2           ACMS01CP002000    20400140
    3           ACMS01CP003000    2040013F

Table row 2 is now valid again, but a different process occupies it. Therefore, any cached information for table row 2 is invalid and must be refreshed with the data from the new process.

## 7.4.4 Dynamic Tables

Dynamic tables do not have a fixed upper bound; they grow and shrink as entries are added and removed. However, data in dynamic tables is always contiguous, so there are never invalid rows stored between valid rows. When a row becomes invalid because it is empty or unoccupied, it is removed from the table and the remaining rows are renumbered.

The following are dynamic tables:

- User table
- Log table
- Trap table

To see how a dynamic table changes when a table row is removed, assume that a user table has the following contents:

    Table row   User Name   Client Id
    1           User1       1
    2           User2       2
    3           User3       3
    4           User4       4

If User2 logs out, the contents of the table would change as follows:

    Table row   User Name   Client Id
    1           User1       1
    2           User3       3
    3           User4       4

As with static tables, you must ensure that the table row being accessed has not been reused or renumbered. Among dynamic tables, only the Trap and Error Filter tables allow updates. Note that entries are never deleted or modified in the Log table; new entries are always appended to the end.

## 7.4.5 Servers and Task Groups

The Servers and Task Group tables are indexed by a compound index. For both tables, the first key value is the table row of the owning EXC; the second key value is the Server or Task Group row. When fetching or setting Server or Task Group rows, you must first determine the EXC (application) they belong to, and then determine the particular server or task group.

For example, assume the EXC table has a total of four rows. Application Appl1 occupies row 1, and has two servers (ServerA and ServerB) and one task group (TaskGroupA). Application Appl2 occupies row 3 and has two servers (ServerC and ServerD) and two task groups (TaskGroupB, TaskGroupC). EXC table rows 2 and 4 are unused. Table 7-2 and Table 7-3 list the contents of each table.

Table 7-2 EXC Table (OID 1.3.6.1.4.1.36.2.18.48.13)
Row | Contents
--- | ---
1 | Appl1
2 | (unused)
3 | Appl2
4 | (unused)

Table 7-3 Server Table (OID 1.3.6.1.4.1.36.2.18.48.13)
Key 1 (EXC) | Key 2 (Server) | Contents
--- | --- | ---
1 | 1 | ServerA
1 | 2 | ServerB
3 | 1 | ServerC
3 | 2 | ServerD

Table 7-4 Task Group Table (OID 1.3.6.1.4.1.36.2.18.48.13)
Key 1 (EXC) | Key 2 (Task Group) | Contents
--- | --- | ---
1 | 1 | TaskGroupA
3 | 1 | TaskGroupB
3 | 2 | TaskGroupC

In order to access the ser-server-name field for ServerA in application Appl1, the OID would be 1.3.6.1.4.1.36.2.18.48.14.1.3.1.1 To access the same field for ServerD in Appl2, the OID would be 1.3.6.1.4.1.36.2.18.48.14.1.3.3.2.

You can always determine from the OID which application a server or task group belongs to because ACMS requires that each server be given a unique name within the application.

# 7.5 SNMP GET Operations

SNMP get requests are satisfied at the time they are received by the subagent. Get requests can take one of three forms: get, get next, and get bulk.

- Get operations are simple requests for single data items.
- Get next requests are iterative requests for logically sequential information.
- Get bulk requests obtain a logical sequence of information in a single request.

The SNMP subagent for ACMS supports only the first operation. SNMP "walks", if performed, return unpredictable results.

OIDs for ACMS Management tables are documented in the file MIB_OID.LIS available from the directory ACMS$RM_EXAMPLES. The MIB definition for the ACMS subtree is also provided in ACMS$RM_EXAMPLES, in the file MGMTMIB.MY.

In order for SNMP get requests to complete successfully, the following conditions must be met:

- The ACMS$SNMP account on the Remote Manager node must be granted the ACMS$MGMT_READ identifier.
- The SNMP interface must already be started.
- The ACMS run-time system must already be started (to access ACMS entity information).

General eSNMP return codes are returned from the Remote Manager for SNMP get requests (see Section 7.10). For details about a specific error, refer to the Remote Manager log.

# 7.6 SNMP SET Operations

SNMP set requests are executed at the time they are received by the subagent and are applied to the running system. However, not all fields that can be set are dynamic; the actual implementation of modification may not occur until the affected entities are restarted.

For more discussion about updates that modify the ACMS run-time system, see Section 5.4.

OIDs for ACMS Management tables are documented in the file MIB_OID.LIS available from the directory ACMS$RM_EXAMPLES. The MIB definition for the ACMS subtree is also provided in ACMS$RM_EXAMPLES, in the file MGMTMIB.MY.

In order for SNMP set requests to complete successfully, the following conditions must be met:

- Depending on the operation being performed, the ACMS$SNMP account on the Remote Manager node must be granted one or more of the following identifiers: ACMS$MGMT_WRITE, ACMS$MGMT_OPER, ACMS$MGMT_OPER, or ACMS$MGMT_SYSUPD (see Appendix B).
- The SNMP interface must already be started.
- The ACMS run-time system must already be started (to update ACMS entity information).

General eSNMP return codes for SNMP get requests are returned from the Remote Manager (see Section 7.10). For details about a specific error, refer to the Remote Manager log.

# 7.7 Using SNMP to Start and Stop ACMS Entities

To start and stop ACMS entities (or to stop the Remote Manager), the Remote Manager allows SNMP users to modify the ID class field running_state. In general, ID class fields are read only. However, since SNMP does not support a START or STOP command, the SET command must be used.

Modifications to the running_state fields are not performed directly by the Remote Manager. Instead, the Remote Manager uses ACMSOPER commands to request the shutdown or startup of the ACMS entity. The ACMS entities update the running_state field when they start or stop.

For instance, to start the ACMS run-time system, an SNMP console program issues an SNMP SET command for the ACC running_state OID, specifying the value "started". The Remote Manager interprets this message as an attempt to start the system and issues the appropriate ACMSOPER command.

The SNMP set call is synchronous. That is, it does not complete until the ACMS operation has completed.

Failure messages related to start or stop requests are written to the Remote Manager log.

# 7.8 SNMP Traps

SNMP traps provide a means of automatically notifying the system support team when a warning or error condition exists. Users configure SNMP traps in the SNMP trap table; when a matching condition or event occurs, an SNMP trap is generated. SNMP management consoles listen for SNMP traps and then respond in a console-dependent (and usually user-configurable) manner.

See Section 9.13 for a discussion of the Trap table and the format of trap messages.

At run time, SNMP traps can be generated as the result of either an ACMS process starting or stopping, or an event that occurred within the Remote Manager (for example, a failure in communications with ACMS).

ACMS system managers configure traps by modifying the Trap table, either by using the ACMSCFG utility prior to Remote Manager startup or by using the ACMSMGR utility after the Remote Manager has been started. Changes made using ACMSCFG do not affect the running system until the Remote Manager is restarted; changes made using ACMSMGR are not saved when the Remote Manager stops.

The configuration process is the same with either utility. You use the ADD TRAP command to add new traps, use the DELETE TRAP command to remove traps, and use the SET TRAP command to modify traps.

Keep in mind that although you can add, delete, or modify entries in the trap table at almost any time, traps will not be generated unless the SNMP interface is started. In addition, traps are not queued if the SNMP interface is disabled.

The combination of entity, name, and parameter uniquely identify a trap in the Trap table. For each trap, a minimum and a maximum value can be specified, along with a severity. Minimum and maximum trap values specify thresholds that trigger traps when the associated parameter is either greater than or less than the threshold. Minimum and maximum trap values are parameter specific.

A special value of -1 is used as a placeholder when creating a trap for which a minimum or maximum does not apply. In many situations, only the minimum or maximum value setting is meaningful. In this instance, set the desired field (minimum or maximum) to the threshold value, and set the other to -1.

Two trap parameters are supported:

- EXISTS (see Section 7.8.1)
- EVENT_SEVERITY (see Section 7.8.2)

## 7.8.1 EXISTS Traps

The trap parameter EXISTS allows traps to be generated based on whether an ACMS process starts or stops.

Specifying a minimum trap value of 1 for a process specifies, in effect, that a trap should be generated whenever the process stops --- that is, when the process existence is less than 1.

Specifying a maximum value of 0 specifies that a trap should be generated whenever the process starts --- that is, when the processes existence is greater than 0.

A minimum value of 0 or a maximum value of 1, while valid, is basically useless, since the EXISTS parameter is never greater than 1 or less than 0.

## 7.8.2 EVENT_SEVERITY Traps

The trap parameter EVENT_SEVERITY allows traps to be generated based on the facility and severity of events being logged to the Remote Manager log. For example, an EVENT_SEVERITY trap can be configured for Remote Manager SNMP events with severity higher than WARNING (such as ERROR or FATAL). Any time a Remote Manager SNMP operation fails with a severity higher than WARNING, an SNMP trap is generated.

Other facilities that can be monitored are:

- * (all)
- MGR (Remote Manager main process)
- PROCMON (process monitor thread)
- RPC (RPC interface thread)
- SNAP (data snapshot thread)
- SNMP (SNMP interface thread)
- SEC (security routines)
- LOG (event logging thread)
- TIMER (internal timer thread)
- DCL (DCL subprocess management thread)
- MSG_PROC (processes incoming ACMS errors)
- TRAP (trap sender thread)

Use care when you configure traps so that you do not create unnecessary traps. In general, traps are intended to be used to signal significant events. For instance, specifying a minimum severity of FATAL or ERROR causes all informational and warning messages to generate traps. This is probably not a good use of network or console resources.

Previous | Next | Contents | Index