Writing Monitors for the Event Monitoring Service Third Edition Manufacturing Part Number: B7611-90016 December 1999 © Copyright 1999 Hewlett-Packard Company
Legal Notices The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Contents 1. Understanding the Event Monitoring Service Event Monitoring Service Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 EMS Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 EMS Resource Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 Client and Target Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17 EMS with ServiceGuard . . . . . . . . . . . . . . . . . . .
Contents rm_create. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Function Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Returned Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 Usage Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 rm_notify. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48 Function Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Function Prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 58 58 58 3. Creating a Resource Monitor Implementing a Resource Monitor . . . . . . . . . . . . . . . .
Contents Processing a Monitor Request Event . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 Replying to Monitor Request Events. . . . . . . . . . . . . . . . . . . . . . . . . . .95 Monitor Request Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 Processing a Resource Update Event . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 5. Writing a Target Application Target Application Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Processing a Notification Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Processing a Restart Notification Object . . . . . . . . . . . . . . .
Understanding the Event Monitoring Service 1 Understanding the Event Monitoring Service The Event Monitoring Service (EMS) provides a mechanism for monitoring system resources and sending notifications about these system resources when they change in an observable way. This document, Writing Monitors for the Event Monitoring Service, describes how to create resource monitors that work with EMS. This section describes the EMS components and the monitor components.
Understanding the Event Monitoring Service Event Monitoring Service Overview Event Monitoring Service Overview The Event Monitoring Service (EMS) monitors system resources. Use EMS to configure monitoring requests, check resource status, and send notification when configured conditions are met. EMS monitors provide instrumentation (knowledge about resources). EMS framework provides registration and notification mechanisms. EMS can work in a high availability environment.
Understanding the Event Monitoring Service Event Monitoring Service Overview traps, such as OpenView NNM or IT/O. You need to set up the application to recognize the SNMP traps generated. — email This option does not require any extra handling. Specify the email address when the monitoring request is created. — syslog and textlog This option does not require any extra handling. Specify the log file when the monitoring request is created. Syslog and textlog notifications go to the local system.
Understanding the Event Monitoring Service Event Monitoring Service Overview The persistence client ensures that monitors that are running, continue to run. If the persistence client detects that a monitor is not running, it restarts the monitor. If the node reboots, the persistence client restarts the monitors and reissues all monitoring requests. Developers use the EMS API to create additional monitors for use with client and TCP target applications, such as the EMS GUI or ServiceGuard.
Understanding the Event Monitoring Service Event Monitoring Service Overview through many methods, including: • EMS GUI • ServiceGuard • monconfig utility • resls or resdata commands 2. The EMS API provides the interface between the client request and the registrar. There is a one to one correspondence between the client and registrar. 3. The registrar refers to the dictionary for a list of available resources and related monitors. The resources listed in the dictionary are passed back to the client. 4.
Understanding the Event Monitoring Service Event Monitoring Service Overview how to send event notification A completed monitoring request identifies: • what resources to monitor • what events to watch for and how often • what notifications to send when an event occurs • where to send notifications Events are defined for either of two resource state types: • periodic checking against either thresholds or state/value changes • continuous checking for asynchronous events 8.
Understanding the Event Monitoring Service EMS Requirements EMS Requirements The following are system requirements for the Event Monitoring Service: • All hardware you intend to monitor, such as disks and LAN cards, have been configured and tested prior to configuring EMS. • EMS must be installed on an HP 9000 Series 700 or Series 800 system running HP-UX version 10.20 or later. When installing one or more EMS components, check that the version levels for the other components are compatible.
Understanding the Event Monitoring Service EMS Resource Classes EMS Resource Classes EMS groups resources into classes in a hierarchy similar to that of a filesystem structure. Figure 1-2 is a example of a resource hierarchy.
Understanding the Event Monitoring Service Client and Target Applications Client and Target Applications This section describes some of the client and target application options and processes. Target applications can be written using the EMS API. EMS with ServiceGuard ServiceGuard can be configured with EMS to monitor the health of selected resources, such as disks. Based on the status of the resources, ServiceGuard can decide to fail packages over.
Understanding the Event Monitoring Service Client and Target Applications instance. An example of a full resource path for the physical volume status of the device /dev/dsk/c0t1d2 belonging to volume group vgDataBase, is /vg/vgDataBase/pv_pvlink/status/c0t1d2. 2. Specify when to collect value. Select either: • When value is ... If you are setting up a request for an asynchronous monitor, this is the only option available.
Understanding the Event Monitoring Service Client and Target Applications • console • syslog • textlog EMS and Target Applications Target applications receive notification messages about the monitored resources. To help configure your Network Node Manager and IT/Operations or other system management software for EMS, refer to the Writing Monitors for the Event Monitoring Service (HP Part Number B7611-90016) developer’s kit web page: 1. Go to the web site: http://software.hp.com. 2.
Understanding the Event Monitoring Service Resource Monitors Resource Monitors Resource monitors are applications written to gather and report information about specific resources on the system. The resource monitor: • Provides a list of resources that can be monitored • Provides information about the resources • Monitors the resources it supports • Provides values or events to the EMS API notification The EMS framework evaluates the data.
Understanding the Event Monitoring Service Resource Monitors Configuring Resource Monitors To configure EMS monitors use either the Event Monitoring Service (EMS) through SAM or the package configuration area of ServiceGuard GUI or edit the package configuration ascii file. Writing Resource Monitors The EMS API provides a method for writing new resource monitors.
Understanding the Event Monitoring Service EMS Framework Components EMS Framework Components This section describes the EMS framework components. The EMS API The EMS API is the interface between the registrar, client applications, target applications, and resource monitors as illustrated in Figure 1-1. The EMS API is provided as part of the EMS product.
Understanding the Event Monitoring Service EMS Framework Components between clients and monitors. One registrar process is started each time a client application calls rm_client_connect(), so a registrar is always connected to one client. Depending on the requests sent by the client, the registrar may be connected to 0, 1, 2, or more resource monitors concurrently. The information in the messages contains enough information to allow the registrar to route the requests and replies correctly.
Understanding the Event Monitoring Service EMS Framework Components The Resource Dictionary The resource dictionary is the mechanism by which the resource monitor identifies itself to EMS. The purpose of the resource dictionary is to give a preliminary picture of the resource naming hierarchy on a given system. It provides a mechanism for monitors to register with EMS and indicates to the registrar which resource monitor should be contacted when information is needed about a certain resource.
The EMS Application Programming Interface (API) 2 The EMS Application Programming Interface (API) This section describes the functions used to write monitors for EMS. The EMS API can be called from any program written in C or C++. The EMS API has been designed to expand and still maintain binary compatibility. The users of the EMS API (client applications and resource monitors) operate on opaque resource monitor objects.
The EMS Application Programming Interface (API) Functions Functions The EMS API provides the functions listed in Table 2-1: Table 2-1 EMS API Functions rm_copy() Replicates an object. rm_create() Creates an object of the type specified by the user. rm_destroy() Frees the memory associated with an object. rm_get() Returns a data item within an object. rm_get_next_event() Blocks for an event from the EMS API. rm_log() Prints a user-defined message to a log file.
The EMS Application Programming Interface (API) Functions EMS Data Types The EMS API and the objects within EMS use several data types. These types are described in Table 2-2: Table 2-2 Data Types Type Size on HP-UX 10.20 Description char * 32 bits A character pointer (also referred to as a string). fd_set 256 bytes A bit array capable of holding 256 bytes (2048 bits). Used with select(2) in rm_get_next_event(). int 32 bits A 32-bit signed integer.
The EMS Application Programming Interface (API) Functions Table 2-2 Data Types Type Size on HP-UX 10.20 Description rm_object_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store the various object types defined by the EMS API. rm_option_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store constants that are defined for certain object fields. rm_return_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum.
The EMS Application Programming Interface (API) Functions EMS Resource Types Resources in the Event Monitoring Service must be defined to have one of the types listed in Table 2-3: Table 2-3 Resource Types Type Description RM_ENUMERATED_ TYPE The resource is an Enumerated Type, which assumes values from a predefined set of states. The states are made up of state names and associated state values.
The EMS Application Programming Interface (API) Functions Table 2-3 Resource Types Type Description RM_NOT_READY RM_NOT_READY has been implemented for the subclass reply and the monitor reply.
The EMS Application Programming Interface (API) Functions example, it may make sense to have a “LAN Utilization” resource that is an RM_FLOAT64_TYPE, since it will assume values between 0.0 and 1.0. Of course, each physical resource may be referred to by multiple logical resources. Each logical resource that is monitored will have just one type, however.
The EMS Application Programming Interface (API) Logging and Tracing Logging and Tracing For the specifications for the user-callable logging function, see rm_print, rm_perror, rm_log, and rm_strerror. By default, only User Events, Panics, and Errors are logged. User Events are defined when the monitor implements rm_log () API or other logging API.To see log messages with a lower severity, and to see internal trace information for debugging purposes, use the RM_LOG_LEVEL environment variable.
The EMS Application Programming Interface (API) Logging and Tracing logging is applied at the EMS application level, it subsequently is applied to all EMS elements, clients, registrars, and monitors. Client applications log to /etc/opt/resmon/log/client.log, resource monitors log to /etc/opt/resmon/log/api.log, and the Registrar logs to /etc/opt/resmon/log/registrar.log. When a log file reaches 500K bytes, EMS creates a backup copy of it and starts a new file.
The EMS Application Programming Interface (API) Function Descriptions Function Descriptions This section describes the function prototype, parameters, returned value, and usage notes.
The EMS Application Programming Interface (API) Function Descriptions rm_copy Called by resource monitors to clone an object. Function Prototype rm_object_addr rm_copy ( const rm_object_addr obj, rm_error_type *error_code ); Parameters error_code Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. obj The object to be copied. Returned Value Upon successful completion, rm_copy() returns the new object.
The EMS Application Programming Interface (API) Function Descriptions rm_create Used by resource monitors to create objects. Function Prototype rm_object_addr rm_create ( rm_object_type type, rm_error_type *error_code ); Parameters error_code Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. type The type of object the user wishes to create. Valid values (defined in resmon.
The EMS Application Programming Interface (API) Function Descriptions rm_destroy Used by resource monitors and target applications to destroy objects that are no longer needed. Function Prototype void rm_destroy (rm_object_addr obj); Parameters obj The object to be destroyed. Usage Notes This function deallocates memory using free(3C). Any references to fields inside the object are invalid once the object has been destroyed.
The EMS Application Programming Interface (API) Function Descriptions rm_get Used by resource monitors and target applications to retrieve data from an object. The caller passes the object and field identifier of interest, and rm_get() uses the supplied address to store the data. Function Prototype int rm_get ( const rm_object_addr obj, rm_field_type field, void *addr, rm_error_type *error_code ); Parameters addr An address where the result will be stored.
The EMS Application Programming Interface (API) Function Descriptions the function. Valid values are listed in the file /opt/resmon/include/resmon.h. field A value that identifies which portion of the object is of interest. The valid field specifiers associated with each object are described in the chapters, “Creating a Resource Monitor” and “Writing a Target Application.” obj The object that contains the data item to be retrieved. Returned Value Upon successful completion, rm_get() returns 0.
The EMS Application Programming Interface (API) Function Descriptions rm_get_next_event This function is used by monitors to determine when a message is ready to be received from the EMS API. Normally, this function blocks until a message has been received from the EMS API.
The EMS Application Programming Interface (API) Function Descriptions Table 2-6 rm_return_type return_type Parameter Values Type Description RM_SELECT_EVENT A call to select(2) returned with one of the user-specified file descriptors selected. The numfds, readfds, writefds, and exceptfds fields should be examined for useful data. See select(2) for more information. RM_SUBCLASS_ REQUEST_EVENT A Subclass Request message has been received from the EMS API.
The EMS Application Programming Interface (API) Function Descriptions Table 2-7 rm_select_type select_data Parameter Fields Field Name Type Description exceptfds fd_set On input specifies the file descriptors to be checked for having error conditions pending, and on output indicates which file descriptors have error conditions pending.
The EMS Application Programming Interface (API) Function Descriptions Table 2-7 rm_select_type select_data Parameter Fields Field Name Type Description timeout struct timeva l * If the timeout argument is not a null pointer, it points to an object of type struct timeval that specifies a maximum interval to wait for the selection to complete. Resource monitors that can block indefinitely should set this field to NULL. See select(2) for more information.
The EMS Application Programming Interface (API) Function Descriptions In order to minimize potential timeouts when communicating with a monitor, call rm_monitor_start and rm_get_next_event (in that order) as soon as possible in your monitor code. The following events will cause rm_get_next_event() to return: • A message arrives from the Registrar. This message will be a Subclass Request or Monitor Request.
The EMS Application Programming Interface (API) Function Descriptions rm_log Used by resource monitors to print user-defined messages to an EMS log file. Resource monitors log messages to /etc/opt/resmon/log/api.log. Function Prototype void rm_log (sbit32 log_level, char *fmt, /* [arg,] */ ... ); Parameters [arg, ...] Arguments, similar to printf(3S). fmt A format, similar to printf(3S). log_level Identifies the severity level of the message.
The EMS Application Programming Interface (API) Function Descriptions rm_monitor_start Called by resource monitors before using any other functions that are part of the EMS API. The purpose of this function is to register the process as a resource monitor with the EMS API and to allow the EMS API to initialize the communication path to the Registrar.
The EMS Application Programming Interface (API) Function Descriptions rm_monitor_stop Called by resource monitors to terminate communications with the EMS API and the Registrar. This function should be called in response to an RM_TERMINATE_EVENT. Function Prototype void rm_monitor_stop ( void ); Parameters None. Returned Value None. Usage Notes The rm_monitor_stop() function closes the EMS log file /etc/opt/resmon/log/api.log, which disables the EMS logging functions.
The EMS Application Programming Interface (API) Function Descriptions rm_notify This function is used by monitors to inform EMS of an event or the current value of a resource. If EMS determines that the resource value meets the notification criteria specified in a monitor request, then EMS will send notification to a target application. This function is called for the following event types: • RM_RESOURCE_UPDATE_EVENT This is the most common call through the EMS request processes.
The EMS Application Programming Interface (API) Function Descriptions recovery is not required of resource monitors, however. Some resource monitors have the ability to asynchronously detect changes in the resource values they support. For example, a resource monitor that uses the rm_select_data structure in rm_get_next_event() might be notified via a named pipe that a resource value has changed.
The EMS Application Programming Interface (API) Function Descriptions rm_perror Used by resource monitors to print an error message to an EMS log file. Resource monitors log messages to /etc/opt/resmon/log/api.log. Function Prototype void rm_perror ( const char *user_string, rm_error_type error_code ); Parameters error_code The error that occurred from a previously-called EMS API function. user_string A user-defined error string.
The EMS Application Programming Interface (API) Function Descriptions rm_print Used by resource monitors to print an ASCII dump of an object to an EMS log file. Resource monitors use the log file /etc/opt/resmon/log/api.log. Function Prototype void rm_print ( const rm_object_addr obj ); Parameters obj The object to be formatted. Returned Value None. Usage Notes The message will be logged at logging level RM_AUDIT_LVL. See the section, “Logging and Tracing” for more details.
The EMS Application Programming Interface (API) Function Descriptions rm_send_reply Used by resource monitors to send replies to the Registrar. Function Prototype int rm_send_reply ( rm_object_addr obj, rm_error_type *error_code ); Parameters error_code Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. obj The object returned by rm_get_next_event(), with new values set as appropriate by the resource monitor.
The EMS Application Programming Interface (API) Function Descriptions rm_set Used by resource monitors to store data in an object. The caller passes the object and data identifier of interest, and rm_set() assigns a user-supplied address to store the result. Function Prototype int rm_set ( rm_object_addr obj, rm_field_type field, (value or address of)data, rm_error_type *error_code ); Parameters data Depending on the type of the field specified, this parameter will be a value or address.
The EMS Application Programming Interface (API) Function Descriptions Table 2-9 data Parameter Values Field Type Value or Address rm_set Action void * Address rm_set() allocates memory to expand the size of the object obj by enough bytes to hold the value. Value pointed to by data is stored into the object obj. error_code Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h.
The EMS Application Programming Interface (API) Function Descriptions Examples Examples of using rm_set() with the various data type are given below. The model is similar to that provided by printf(3S) (where %d means the argument is a value and %s says it is an address). 1. RmTargetPort is a ubit16 type. The data is passed by value. /* Example 1 */ rm_set(obj, RmTargetPort, 5707, &error_code); /* Example 2 */ ubit32 port = 5707; rm_set(obj, RmTargetPort, port, &error_code); 2. RmMsgTag is a ubit32 type.
The EMS Application Programming Interface (API) Function Descriptions &error_code); /* RIGHT */ /* Example 2 -- A string threshold value */ rm_value_type threshold_value; threshold_value.str = “DOWN”; rm_set(obj, RmThresholdType, RM_STRING_TYPE, &error_code); rm_set(obj, RmThresholdValue, &threshold_value, &error_code); 5. RmSubclassChildObject is an rm_object_addr. The data is passed by reference.
The EMS Application Programming Interface (API) Function Descriptions rm_strerror Used by resource monitors and target applications to format an EMS error message to a buffer. Resource monitors that are also target applications may call their own logging after calling rm_strerror(). Resource monitors may also call rm_log(), but target applications normally cannot.
The EMS Application Programming Interface (API) Function Descriptions rm_uncompress_object Used by target applications to decipher a notification message using the built-in TCP/IP or UDP/IP notification method. Function Prototype rm_object_addr rm_uncompress_object ( char *buf, rm_error_type *error_code ); Parameters buf The ASCII data representing a Notify Object. This data was received in a TCP/IP or UDP/IP notification message sent by EMS.
Creating a Resource Monitor 3 Creating a Resource Monitor A resource monitor is the expert on a particular resource instance or resource class. A resource monitor responds to requests for information about what resources can be monitored, provides information about each resource, and checks the status of the resource as (asynchronously or synchronously) requested. A sample monitor program is supplied in the /opt/resmon/devkit/source/sampmon directory.
Creating a Resource Monitor Implementing a Resource Monitor Implementing a Resource Monitor Follow these steps to write and install a resource monitor in the EMS: Step 1. Write the monitor. The rest of this chapter explains how to write a monitor using the EMS API. The EMS API functions are explained in the chapter, “The EMS Application Programming Interface (API).” Step 2. Add the monitor to the resource dictionary. The resource dictionary files are ASCII files that you can edit with any text editor.
Creating a Resource Monitor Writing the Monitor Writing the Monitor The EMS API, Registrar, and resource dictionary directory are provided as part of the EMS product. For each resource monitor you create, you provide: • A resource dictionary. Refer to the section “Defining the Resource Dictionary Hierarchy” for information on writing this. • The resource monitor binary file. The balance of this chapter describes how to write this. • A man page. This is optional, but strongly suggested.
Creating a Resource Monitor Writing the Monitor — Subclass events refer to “Processing a Subclass Request Event.” — Monitor request events refer to “Processing a Monitor Request Event.” — Resource update events refer to “Processing a Resource Update Event.” — Unregister events refer to “Processing an Unregister Event.” — Terminate events refer to “Processing a Terminate Event.” — Asynchronous notifications refer to “Processing an Asynchronous Notification.
Creating a Resource Monitor Writing the Monitor Log File Recommendations To log error messages, log to the api.log using the rm_log() function. Startup and Initialization Considerations This section describes the startup and initialization sequence performed by EMS. For proper operation of your resource monitor, ensure that your monitor does not conflict with the actions of the Registrar. Registrar Considerations The registrar is started via inetd(1M).
Creating a Resource Monitor Writing the Monitor monitors cannot be started from an HP-UX shell. They must be started by the registrar. File Descriptor Considerations The resource monitor is started by the Registrar. Before starting the resource monitor process, the Registrar opens several file descriptors on behalf of the resource monitor, including a communication channel between the Registrar and the resource monitor.
Creating a Resource Monitor Writing the Monitor When you write the resource monitor, do not have it read from file descriptor 0 (normally STDIN); it will be done automatically by the rm_get_next_event() function. Environment Considerations A resource monitor’s environment is inherited from the Registrar, which is inherited from inetd(1M). Resource monitors should not expect user-type environment variables to be present. In particular, HOME, DISPLAY, LANG, and NLSPATH will not be set.
Creating a Resource Monitor Writing the Monitor Table 3-2 Monitor Info Object Fields Field Name Type Description RmMonitor Description char * A pointer to a null-terminated string of up to 2048 characters that gives a detailed description of the types of resources supported by the resource monitor. For readability, newline characters should be included to limit each line to 72 characters or less. Do not include tabs in this string. This field must be set by the resource monitor.
Creating a Resource Monitor Writing the Monitor Table 3-2 Monitor Info Object Fields Field Name Type Description RmMonitorVendor Name char * A pointer to a null-terminated string of up to 80 characters that describes the company producing the monitor. This field must be set by the resource monitor. The string passed into rm_set() will be copied by EMS into a buffer allocated with malloc(3C). EMS will call rm_destroy() to free this space when the monitor calls rm_monitor_stop().
Creating a Resource Monitor Writing the Monitor Sample Code int register_me(int argc, char **argv) { rm_error_type error_code; if (rm_monitor_start(argc, argv, &error_code) == -1) { rm_perror(“Error in rm_monitor_start“, error_code); return -1; } /* Supply information about this monitor to EMS. Use the rm_monitor_info */ /* global variable for this purpose.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy Defining the Resource Dictionary Hierarchy The resource dictionary directory is provided as part of the EMS product. You provide a resource dictionary, or dictionary entry, for each resource monitor you create. The resource dictionary is installed as a set of files in the /etc/opt/resmon/dictionary directory. A resource class that contains zero (0) or more logical resources.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy current value and therefore cannot be polled by EMS. Default is S (state). NOTE Although, once installed the resource dictionary files and entries may be reviewed, generally they will not be changed. However, it is permissible to make changes to an installed resource dictionary file. For example, an initiating option may need to be changed. To document the options available for your monitor, add a man page for your resource monitor.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy in a Subclass Reply. Refer to the section, “Processing a Subclass Request Event.” • For resource classes that contain a static list of resource instances, whose names never change, create an entry in the resource dictionary for each resource instance. File Naming The /etc/opt/resmon/dictionary/DEFAULT file contains the structure and hierarchy of expected resource classes. EMS delivers the topmost resources in this file.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy Wildcarding The SAM interface to EMS allows users to select all resource instances in a resource class, if all instances are of the same type. For example, the resource class /vg/vg_name/lv/status/* contains a resource instance to monitor the status of every logical volume defined in the volume group represented by vg_name.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy • DESCRIPTION: text Optional. The DESCRIPTION allows humans to understand what information a particular resource class or instance provides. It displays when a user selects “View Description” in MC/ServiceGuard, MC/LockManager, or the SAM interface to EMS. The description should be less than 80 characters, if possible, but it can be up to 2047 characters. It cannot contain tabs or newline (\n) characters.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy • RESOURCE_NAME: resource_name Required. The RESOURCE_NAME is the key identifier that allows a resource monitor to be integrated into EMS. resource_name is a full path name (starting with /). This can be either a class name or an instance, with nothing to differentiate between the two. / is the class delimiter. • STATE_TYPE: [A|S|B] Defaulted. The STATE_TYPE specifies the method used by the monitor to collect the status of information.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy Figure 3-1 State and Asynchronous Resource Class Example Resource Dictionary Examples This section provides samples of resource dictionaries. The following is the resource dictionary entry for a Disk Monitor, diskmond. This resource dictionary contains the minimum resource dictionary information. RESOURCE_NAME: /vg MONITOR: /etc/opt/resmon/lbin/diskmond -l STATE_TYPE: S The resource dictionary, diskmond.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy # Job queue from the HP-UX MIB RESOURCE_NAME: /system/jobQueue5Min MONITOR: /etc/opt/resmon/lbin/mibmond STATE: S # Job queue from the HP-UX MIB RESOURCE_NAME: /system/jobQueue15Min MONITOR: /etc/opt/resmon/lbin/mibmond STATE: S # Number of users from the HP-UX MIB RESOURCE_NAME: /system/numUsers MONITOR: /etc/opt/resmon/lbin/mibmond STATE: S # Define a container for the filesystem resources RESOURCE_NAME: /system/filesystem DESCRIPTION
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy • Resource monitor lanmond: All resources under /net/interfaces/lan/status are controlled by the lanmond resource monitor. All subclasses and resource instances beneath the /net/interfaces/lan/status level are dynamic. • Resource monitor mibmond: The mibmond resources are explicitly defined. This allows you to specifically define resource criteria.
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy /hubs /multiplexors /switches /net /interfaces /lan /fddi /token_ring /ethernet /switched /x25 /fibre_channel /atm /subnetwork /processes /protocols /tcp /udp /ip /system /cpu /events /memory /io_interfaces /status /peripherals /mass_storage /printer /routers /storage /events /disks /disk_arrays /enclosures /tapes /status /disks /disk_arrays /enclosures /tapes Default Resource Dictionary The following is sample of the /system portion of
Creating a Resource Monitor Defining the Resource Dictionary Hierarchy The default resource dictionary file is /etc/opt/resmon/dictionary/DEFAULT. # @(#) A.03.00 EMS DEFAULT Dictionary # (c) Copyright Hewlett-Packard Company 1998 # # WARNING:Changing this file may disable EMS monitors.Use caution.
Creating a Resource Monitor Processing a Subclass Request Event Processing a Subclass Request Event The Subclass Request is a message that a client sends to get the definition of a particular resource class or instance. The Subclass Request Event is specified by a return_type of RM_SUBCLASS_REQUEST_EVENT from rm_get_next_event(). Include in the reply information that describes the resource, plus the names of any subclasses that exist below the resource.
Creating a Resource Monitor Processing a Subclass Request Event RmOVSeverity field to RM_OV_ENUMERATION. The enumeration is an RM_OV_ENUMERATION if the values are used to convey severity level of the event. The severity StateValues have the following meaning: 1 - normal event 2 - warning event 3 - minor warning event 4 - major warning event 5 - critical event • Send the message. Subclass Objects When a Subclass Request Event occurs the monitor receives a subclass reply object.
Creating a Resource Monitor Processing a Subclass Request Event Table 3-3 Subclass Reply Object Fields Field Name Type Description RmDescription char * A description of a resource class or instance. The description will be text that would help someone understand what the resource is. This field is a string of up to 2048 characters with a terminating null. For readability, newline characters should be included to limit each line to 72 characters or less. Do not include tabs in this string.
Creating a Resource Monitor Processing a Subclass Request Event Table 3-3 Subclass Reply Object Fields Field Name Type Description RmResource Name char * A pointer to a null-terminated string of up to 256 characters that identifies the resource class or instance. The RmResourceName contains the full path name of the resource class or instance. See the section, “The Resource Dictionary” for more details.
Creating a Resource Monitor Processing a Subclass Request Event Table 3-3 Subclass Reply Object Fields Field Name Type Description RmStateObject rm_object _addr An object in the Resource State List. The Resource State List is included only when the RmResourceType is RM_ENUMERATED_TYPE. The resource monitor must create each object in the Resource State List with rm_create() using an object type of RM_RESOURCE_STATE_OBJECT. RmStateType rm_option _type A field that is set by the monitor.
Creating a Resource Monitor Processing a Subclass Request Event The purpose of the Resource State List is to identify all of the possible state values that a resource of type RM_ENUMERATED_TYPE might take. Each object in the Resource State List contains the fields listed in Table 3-4: Table 3-4 Resource State Object Fields Field Name Type Description RmObjectType rm_object _type The object type. For a Resource State object, the value is RM_RESOURCE_STATE_OBJECT.
Creating a Resource Monitor Processing a Subclass Request Event Table 3-5 Subclass List Object Fields Field Name Type Description RmSubclass Name char * A pointer to a null-terminated string of up to 256 characters that identifies the resource class or instance. The RmResourceName may contain either the full path name of the resource class or instance or the portion immediately following the resource class.
Creating a Resource Monitor Processing a Subclass Request Event int send_subclass_reply(rm_object_addr obj) { rm_error_type error_code; char *resource_name; rm_object_addr subclass, state_obj; int rc; rm_get(obj, RmResourceName, &resource_name, &error_code); /*************************************************************************/ /* Check that the resource requested is one we support.
Creating a Resource Monitor Processing a Subclass Request Event rc = rm_set(subclass, RmSubclassName, “string”, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } rc = rm_set(obj, RmSubclassChildObject, subclass, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } /***********************************************************************/ /* Define a resource instance called “sbit32”.
Creating a Resource Monitor Processing a Subclass Request Event rc = rm_set(subclass, RmSubclassName, “ubit32”, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } rc = rm_set(obj, RmSubclassChildObject, subclass, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } /***********************************************************************/ /* Define a resource instance called “enum”.
Creating a Resource Monitor Processing a Subclass Request Event rc = rm_set(obj, RmSubclassChildObject, subclass, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } } /***************************************************************************/ /* Also check the resource instances for a match.
Creating a Resource Monitor Processing a Subclass Request Event rc = rm_set(obj, RmDescription, “This resource instance returns random value s between 0 and 11,\ninclusive.”, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } } else if (strcmp(resource_name, “/samples/ubit32”) == 0) { /*************************************************************************/ /* The “ubit32” resource instance is an unsigned 32-bit integer resource.
Creating a Resource Monitor Processing a Subclass Request Event /*************************************************************************/ /* The “enum” resource instance is an enumerated type resource that */ /* can assume the values “UP”, “DOWN”, and “UNKNOWN”.
Creating a Resource Monitor Processing a Subclass Request Event /*************************************************************************/ /* Define the state called “DOWN”, which has a value of 1.
Creating a Resource Monitor Processing a Subclass Request Event rc = rm_set(state_obj, RmStateName, UNKNOWN_STATE_NAME, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } rc = rm_set(obj, RmStateObject, state_obj, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } } else { /***********************************************************************/ /* This is not a resource we support.
Creating a Resource Monitor Processing a Monitor Request Event Processing a Monitor Request Event A Monitor Request asks the resource monitor whether it is ready to monitor the resource specified. If so, the monitor will reply with a positive Monitor Reply. The Monitor Request Event is specified by a return_type of RM_MONITOR_REQUEST_EVENT from rm_get_next_event(). Replying to Monitor Request Events To process a monitor request event for your resource monitor, include the following information.
Creating a Resource Monitor Processing a Monitor Request Event — RM_QUERY_REQUEST This checks one time only. There is no unregister associated with it. Monitor Request Objects When a Monitor Request Event occurs, rm_get_next_event() creates a Monitor Reply object that the resource monitor should use to reply to the request. The following fields of the Monitor Reply object are defined.
Creating a Resource Monitor Processing a Monitor Request Event Table 3-6 Monitor Reply Object Fields Field Name RmLifetime Option Type Description Valid values continued: RM_PREVIEW_REGISTER This is a request to verify monitoring request parameters. It currently verifies the polling interval and the resource name. The monitor request is never registered. This preview request only exists for verification, which is complete once the Monitor Reply has been sent. No unregister request is needed.
Creating a Resource Monitor Processing a Monitor Request Event Table 3-6 Monitor Reply Object Fields Field Name Type Description RmMonitorReply rm_option _type Indicates whether a resource monitor was found that could monitor the resource. The resource monitor must set the value of this field. Valid values are as follows: RM_ACCEPT The resource monitor agrees to monitor the resource. The EMS API will register the monitor request by creating an Info Block attached to the resource monitor’s process.
Creating a Resource Monitor Processing a Monitor Request Event Table 3-6 Monitor Reply Object Fields Field Name RmMonitorReply Type Description Valid values are as follows: (continued) RM_POLLTIME The resource monitor does not support the polling interval specified by the client in the RmPollingInterval field of the Monitor Request object. The client should resend the request with a longer polling interval. If the monitor is using this, also set RmPollingMinimum.
Creating a Resource Monitor Processing a Monitor Request Event Table 3-6 Monitor Reply Object Fields Field Name Type Description Valid values are as follows: (continued) RmMonitorReply RM_RESOURCE_NOT_SUPPORTED The resource is not supported by this resource monitor. RM_TARGET_NOT_AVAILABLE (Reserved) This value is reserved for use by the Registrar. RmObjectType rm_object _type The object type. For a Monitor Reply, the value is RM_MONITOR_REPLY_OBJECT.
Creating a Resource Monitor Processing a Monitor Request Event Table 3-6 Monitor Reply Object Fields Field Name Type Description RmPolling Interval ubit32 Specifies in seconds how often rm_get_next_event() generates an RM_RESOURCE_UPDATE_EVENT. This event signals the resource monitor that it should check whether the value of the resource meets the notification criteria. If it determines how often notification messages are sent.
Creating a Resource Monitor Processing a Monitor Request Event Table 3-6 Monitor Reply Object Fields Field Name Type Description RmResourceType rm_option _type Defines what form the resource’s values assume. Valid values are shown below. See the section, “EMS Resource Types” for an explanation of these values. RM_RESOURCE_CLASS_TYPE RM_STRING_TYPE RM_ENUMERATED_TYPE RM_SBIT32_TYPE RM_UBIT32_TYPE RM_FLOAT64_TYPE RM_ERROR_TYPE The resource monitor must set the value of this field.
Creating a Resource Monitor Processing a Monitor Request Event * /samples/string * /samples/sbit32 * /samples/ubit32 * /samples/float64 * /samples/enum * Checks that polling interval requested is greater than minimum. * * Parms: * obj The object that was created by rm_get_next_event(). * This object is destroyed outside of this function.
Creating a Resource Monitor Processing a Monitor Request Event /*************************************************************************/ /* The "string" resource instance is a character string.
Creating a Resource Monitor Processing a Monitor Request Event else if (strcmp(resource_name, "/samples/enum") == 0) { /*************************************************************************/ /* The "enum" resource instance is an enumerated type resource that */ /* can assume the values "UP", "DOWN", and "UNKNOWN".
Creating a Resource Monitor Processing a Monitor Request Event /*************************************************************************/ /* Send the message.
Creating a Resource Monitor Processing a Resource Update Event Processing a Resource Update Event The Resource Update Event occurs when the EMS API needs an update on the value of a resource. The resource monitor should be developed to respond to this event by obtaining the current value of the resource. The polling interval between Resource Update Events is set by the client application in the monitor request.
Creating a Resource Monitor Processing a Resource Update Event • Set RmClientCfgFile if appropriate. • Call rm_notify() to provide the value back to EMS. • Let the EMS API decide whether to send a notification message. Resource Update Objects When a Resource Update Event occurs, rm_get_next_event() creates a Resource Update object that the resource monitor should use to set the current value of the resource. The following fields of the Resource Update object are defined.
Creating a Resource Monitor Processing a Resource Update Event Table 3-7 Resource Update Object Fields Field Name Type Description RmMonitor ReturnData void * A pointer to up to 10,000 bytes of binary data to be passed in a notification to the target application. The resource monitor must set this field. The EMS API will not alter or use this address. It is intended for exclusive use by the resource monitor. Its use is optional.
Creating a Resource Monitor Processing a Resource Update Event Table 3-7 Resource Update Object Fields Field Name Type Description RmMonitor ReturnDataLen ubit32 The number of bytes in the RmMonitorReturnData field. The resource monitor must set this field. The RmMonitorReturnData field may contain up to 10,000 bytes. The RmMonitorReturnDataLen must be set before the RmMonitorReturnData field.
Creating a Resource Monitor Processing a Resource Update Event Table 3-7 Resource Update Object Fields Field Name Type Description RmResourceName char * A pointer to a null-terminated string of up to 256 characters that identifies the resource instance for which this request applies. The RmResourceName contains the full path name of the resource class or instance. See the section, “The Resource Dictionary” for more details.
Creating a Resource Monitor Processing a Resource Update Event Table 3-7 Resource Update Object Fields Field Name Type Description RmResourceType rm_option _type Specifies the type of the resource, as defined by the resource monitor.
Creating a Resource Monitor Processing a Resource Update Event Table 3-7 Resource Update Object Fields Field Name Type Description RmResource Value rm_value_ type * A pointer to the current value of the resource. If the RmResourceType is RM_ERROR_TYPE, this field is not meaningful.
Creating a Resource Monitor Processing a Resource Update Event Table 3-8 Resource State Object Fields Field Name Type Description RmStateName char * A state name. This field is a string of up to 256 characters with a terminating null. RmStateValue sbit32 Identifies a signed 32-bit numeric value associated with the string. Sample Code This code fragment shows how a resource monitor might respond to a Resource Update Event.
Creating a Resource Monitor Processing a Resource Update Event rm_get(obj, RmResourceName, &resource_name, &error_code); /*************************************************************************/ /* Check that the resource value requested is one we support. */ /*************************************************************************/ if (strcmp(resource_name, “/samples/enum”) == 0) { /***********************************************************************/ /* Resource-specific function.
Creating a Resource Monitor Processing a Resource Update Event if (strcmp(state, UP_STATE_NAME) == 0) { rc = rm_set(state_obj, RmStateValue, 0, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } } else if (strcmp(state, DOWN_STATE_NAME) == 0) { rc = rm_set(state_obj, RmStateValue, 1, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } } else if (strcmp(state, UNKNOWN_STATE_NAME) == 0) { rc = rm_set(state_obj, RmStateValue, 2, &error_code);
Creating a Resource Monitor Processing a Resource Update Event rm_set(obj, RmResourceType, RM_STRING_TYPE, &error_code); timer = time(NULL); value.str = ctime(&timer); rm_set(obj, RmResourceValue, &value, &error_code); } else if (strcmp(resource_name, “/samples/sbit32”) == 0) { /*************************************************************************/ /* Get a random number between 0 and 11. */ /* Why didn’t we stop at 10? */ /* This one goes to 11.
Creating a Resource Monitor Processing a Resource Update Event rc = rm_set(obj, RmResourceValue, &value, &error_code); if (rc == -1) { rm_perror(“Error in rm_set“, error_code); return -1; } } else { /***********************************************************************/ /* This case would be used if the resource name was not what we */ /* expected.
Creating a Resource Monitor Processing an Unregister Event Processing an Unregister Event The Unregister Event is a signal from the EMS API that one of the monitor requests previously active for this resource monitor has been unregistered by a client. No reply is expected from the resource monitor when this event occurs. Replying to Unregister Events To write a unregister event for your resource monitor, include the following information.
Creating a Resource Monitor Processing an Unregister Event Object fields. Table 3-9 Unregister Object Fields Field Name Type Description RmLifetime Option ubit32 Determines how long this monitor request should last if it is accepted. Valid values are: RM_NON_PERSISTENT_REQUEST The monitor request should exist as long as the resource monitor exists (or until a client sends an Unregister Monitor Request). If the resource monitor process dies or if the system is rebooted, the monitor request will vanish.
Creating a Resource Monitor Processing an Unregister Event Table 3-9 Unregister Object Fields Field Name Type Description Valid values continued: RmLifetime Option RM_PREVIEW_UNREGISTER This is a request to verify the password for an Unregister Request. The Request ID is also verified. The request does not get unregistered when this lifetime option is used. This should be used only when RmOperationType is RM_UNREGISTER.
Creating a Resource Monitor Processing an Unregister Event Table 3-9 Unregister Object Fields Field Name Type Description RmResource Name char * A pointer to a null-terminated string of up to 256 characters that identifies the resource instance for which the Monitor Request was sent. The RmResourceName contains the full path name of the resource instance. See the section, “The Resource Dictionary” for more details.
Creating a Resource Monitor Processing an Unregister Event void process_requests(void) { rm_object_addr obj; rm_return_type return_type; rm_error_type error_code; rm_select_type select_data; struct timeval timeout; while (1) { /*************************************************************************/ /* Setting the select_data to NULL means we are willing to wait */ /* indefinitely for an event. */ /* */ /* This code shows how to set a user timeout of 10 seconds.
Creating a Resource Monitor Processing an Unregister Event case RM_MONITOR_REQUEST_EVENT: send_monitor_reply(obj); break; case RM_RESOURCE_UPDATE_EVENT: update_resource(obj); break; case RM_SELECT_EVENT: /***********************************************************************/ /* Since we do not set the select_data, we will not get this event.
Creating a Resource Monitor Processing a Terminate Event Processing a Terminate Event The Terminate Event is a signal from the EMS API that no activity has been detected that required the attention of the resource monitor for a significant period of time (defined to be 60 minutes). The resource monitor may call rm_monitor_stop() and shut down. Any message received from the Registrar will reset the termination timer. If a monitor request is registered, the timer will not be used.
Creating a Resource Monitor Processing a Terminate Event void process_requests(void) { rm_object_addr obj; rm_return_type return_type; rm_error_type error_code; rm_select_type select_data; struct timeval timeout; while (1) { /*************************************************************************/ /* Setting the select_data to NULL means we are willing to wait */ /* indefinitely for an event. */ /* */ /* This code shows how to set a user timeout of 10 seconds.
Creating a Resource Monitor Processing a Terminate Event case RM_MONITOR_REQUEST_EVENT: send_monitor_reply(obj); break; case RM_RESOURCE_UPDATE_EVENT: update_resource(obj); break; case RM_SELECT_EVENT: /***********************************************************************/ /* Since we do not set the select_data, we will not get this event.
Creating a Resource Monitor Processing an Asynchronous Notification Processing an Asynchronous Notification Use asynchronous notification to respond to a message that arrives from some source other than the EMS API. This event applies only to resource monitors that use the select(2) parameters. The way the RM_SELECT_EVENT and RM_TIMEOUT_EVENT events are handled by the resource monitor is dependent on their implementation. Use the same methods you use for standard select(2) events.
Creating a Resource Monitor Defining an Internal Timeout Defining an Internal Timeout Use an internal timeout to indicate that the time interval specified by the resource monitor has expired without any messages arriving. This event applies only to resource monitors that use the select(2) parameters. Its purpose is to allow a status check that is not bound by the EMS request timing limits.
Creating a Resource Monitor Defining an Internal Timeout void ems_wait_for_request (int *status) { rm_object_addr obj; /* EMS object address rm_return_type ems_response; /* EMS response to rm_get_next_event rm_error_type error_code; /* Error returned from EMS API calls rm_select_type registered_fds; /* File descriptor bit mask for select() rm_select_type select_data; /* Contains timeout & fds for select() struct timeval timer; /* Polling interval timeout time_t start_time; /* Time when the last interval st
Creating a Resource Monitor Defining an Internal Timeout timer.tv_sec = (time_t)timeout; timer.tv_usec = (long)0; select_data.
Creating a Resource Monitor Defining an Internal Timeout case RM_RESOURCE_UPDATE_EVENT: update_resource (obj); break; case RM_SELECT_EVENT: /* ** When a file descripter indicates there is data ready, ** report the data as asynchronous events */ process_select_event(); break; case RM_TIMEOUT_EVENT: process_timeout_event(); break; default: break; } /* switch */ rm_destroy (obj); /* It's our responsibility to deallocate the object */ } /* while */ return; } /* ems_wait_for_request */ 132 Chapter 3
Testing a Resource Monitor with montest 4 Testing a Resource Monitor with montest The sections in this chapter are as follows: • About the montest Tool • Using montest • How montest Works • Sample montest output • montest Error Messages Chapter 4 133
Testing a Resource Monitor with montest About the montest Tool About the montest Tool In order to verify the successful operation of a resource monitor, all communication paths to and from the resource monitor must be exercised.
Testing a Resource Monitor with montest Using montest Using montest To invoke the montest tool, issue the following command: $ /opt/resmon/devkit/montest/montest [-f filename] The filename is the full path name of a montest script. If you specify the -f filename option, montest executes the script and sends the output to a log file in the /var/opt/resmon/log/montest directory. Log files are called emsloghh:mm:ss, where hh:mm:ss is the time the file was created.
Testing a Resource Monitor with montest How montest Works How montest Works The montest tool performs the following tasks in the process of verifying the user’s resource monitor: 1. Verifies the resource name. Successful name verification means that the resource was listed in the resource dictionary or that the resource monitor was able to receive an RM_SUBCLASS_REQUEST and send the appropriate RM_SUBCLASS_REPLY back to the Registrar.
Testing a Resource Monitor with montest How montest Works 3. Sets up a target application to listen on a TCP port for responses from the resource monitor each time the notification criteria is satisfied. Successful notification verifies communication between the resource and the resource monitor and between the resource monitor and the target application that montest sets up. The target application uses Berkeley sockets to receive notification messages from the resource monitor.
Testing a Resource Monitor with montest Sample montest output Sample montest output Following are some examples of montest output from an interactive session. These examples do not show the instructions that montest displays before it prompts you for information. Running montest for a Resource Class In the following example, the user typed /samples when montest prompted for the resource name. The /samples resource class includes five resource instances.
Testing a Resource Monitor with montest Sample montest output Resource Name ===> /samples/sbit32 Resource /samples/sbit32 is verified. Description: This resource instance returns random values between 0 and 11, inclusive. User Data (in quotes) ===> “FORCED notification every 6 seconds” Polling Interval [1 - 86400 Sec.
Testing a Resource Monitor with montest Sample montest output Resource /samples/sbit32 is verified. Description: This resource instance returns random values between 0 and 11, inclusive. User Data (in quotes) ===> “using greater than 8 and RETURN” Polling Interval [1 - 86400 Sec.
Testing a Resource Monitor with montest montest Error Messages montest Error Messages This section explains the meaning of some of the messages that the montest utility may display. Bad Monitor Request - error_code This error indicates that the Registrar did not accept a monitor request. See the file /opt/resmon/include/resmon.h for information on the cause of the failure.
Testing a Resource Monitor with montest montest Error Messages 142 Chapter 4
Writing a Target Application 5 Writing a Target Application The sections in this chapter are as follows: • Target Application Overview • Processing a Notification Message • Processing a Restart Notification Object Chapter 5 143
Writing a Target Application Target Application Overview Target Application Overview A target application is a process that receives notification messages when the EMS API detects that a resource value has met the notification criteria. The target application does not necessarily use the EMS API. Depending upon the notification method of a particular monitor request, the target application may be able to process the notification message without using any of the facilities of the EMS API.
Writing a Target Application Target Application Overview Table 5-1 EMS API Functions Used by Target Applications rm_strerror() Format an error message to a buffer. rm_uncompress() Converts a TCP/IP or UDP/IP notification message into an EMS object. Sample Code /*****************************************************************************/ /* TCP_TARGET.C */ /* Using the specified TCP port, waits for a message to arrive on that port.
Writing a Target Application Target Application Overview main(int argc, char **argv) { int addrlen, tcpport, optval; int msglen, objlen, sock, datasock; struct sockaddr_in saddr, clientaddr_in; char *buf, *buf_offset; char header[HEADER_LEN]; char errbuf[200]; struct hostent *hp; time_t timer; rm_object_addr obj; rm_object_type object_type; rm_error_type error_code; if (argc < 2) { fprintf(stderr, "Usage: %s \n", argv[0]); exit(1); } /******************************************************************
Writing a Target Application Target Application Overview if (listen(sock, 20) == -1) { perror("Error in listen()"); exit(1); } memset(&clientaddr_in, 0, sizeof(struct sockaddr_in)); clientaddr_in.sin_family = AF_INET; clientaddr_in.
Writing a Target Application Target Application Overview /*************************************************************************/ /* Read data off of the socket */ /*************************************************************************/ msglen = recvfrom (datasock, buf, objlen + HEADER_LEN, 0, &clientaddr_in, &addrlen); buf[HEADER_LEN+objlen] = ’\0’; if (msglen == -1) { perror("recvfrom() returned -1"); exit(1); } /*************************************************************************/ /* Print me
Writing a Target Application Target Application Overview /*************************************************************************/ /* Check object type */ /*************************************************************************/ if (rm_get(obj, RmObjectType, &object_type, &error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get object type: %s", errbuf); } /*************************************************************************/ /* Format and print object
Writing a Target Application Processing a Notification Message Processing a Notification Message This section applies only to target applications that receive notification messages via TCP or UDP. Other notification methods may define different ways to transport the information from the resource monitor to the target application. The format of the notification message is as follows: A 9 byte header is followed by a message buffer.
Writing a Target Application Processing a Notification Message The following fields are defined for a Notify Object: Table 5-2 Notify Object Fields Field Name Type Description RmMonitor ReturnData void * A pointer to up to 10,000 bytes of binary data to be passed in a notification to the target application. The EMS API will not alter or use this address. It is intended for exclusive use by the resource monitor. Its use is optional.
Writing a Target Application Processing a Notification Message Table 5-2 Notify Object Fields Field Name Type Description RmResource Name char * A pointer to a null-terminated string of up to 255 characters that identifies the resource instance for which the Notification Message was sent. The RmResourceName contains the full path name of the resource instance. See the section, “The Resource Dictionary” for more details.
Writing a Target Application Processing a Notification Message Table 5-2 Notify Object Fields Field Name Type Description RmResource Value rm_value_ type * A pointer to the current value of the resource. If the RmResourceType is RM_ERROR_TYPE, this field is not meaningful.
Writing a Target Application Processing a Notification Message Sample Code /*****************************************************************************/ /* Name: format_notify_object */ /* */ /* Description: Extracts, formats and prints various fields of a notify */ /* object. Assumes object passed in is notify object. */ /* */ /* Parameters: obj Notify object */ /* */ /* Return: None.
Writing a Target Application Processing a Notification Message /*************************************************************************/ /* Format and print user data buffer based on length */ /*************************************************************************/ if (user_data_len) { if (rm_get(notify_obj, RmUserData, &user_data, &error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get user data: %s", errbuf); printf("User Data:'???\n"); } else { strncpy
Writing a Target Application Processing a Notification Message case RM_STRING_TYPE: printf("RM_STRING_TYPE\n"); break; case RM_ENUMERATED_TYPE: printf("RM_ENUMERATED_TYPE\n"); break; case RM_ERROR_TYPE: printf("RM_ERROR_TYPE\n"); break; default: printf("???\n"); break; } /* switch */ if (rm_get(notify_obj, RmResourceValue, &value, &error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get resource value: %s", errbuf); printf("Resource Value:???\n"); } else { /****
Writing a Target Application Processing a Notification Message case RM_ENUMERATED_TYPE: value_obj = value.obj; if (rm_get(value_obj, RmStateName, &value, &error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get state name of resource value: %s", errbuf); printf("???"); } else { printf("%s", value.
Writing a Target Application Processing a Restart Notification Object Processing a Restart Notification Object A Restart Notification object identifies resources that were affected by an outage of a resource monitor. This occurs when a resource monitor process unexpectedly dies, or when a system that is being monitored is rebooted.
Writing a Target Application Processing a Restart Notification Object Table 5-3 Restart Notification Object Fields Field Name Type Description RmMonitor Description char * A pointer to a null-terminated string of up to 2048 characters that gives a detailed description of the types of resources supported by the resource monitor. The description is set by the resource monitor in the Monitor Info object. See the section, “Startup and Initialization Considerations.
Writing a Target Application Processing a Restart Notification Object Table 5-3 Restart Notification Object Fields Field Name Type Description RmMonitor VersionString char * A pointer to a null-terminated string of up to 20 characters that is the version number of the monitor. The version string is set by the resource monitor in the Monitor Info object. See the section, “Startup and Initialization Considerations.” RmNext ResourceEntry rm_object _addr The next object in the Resource List.
Writing a Target Application Processing a Restart Notification Object Resource List Entries have the following fields defined: Table 5-4 Resource List Entry Fields Field Name Type Description RmMonitor RestartType rm_option _type Identifies the cause of the outage. RM_RESTART means that the resource monitor was restarted by EMS due to an unexpected failure. RM_REBOOT means the monitor was restarted after a system reboot. RmObjectType rm_object _type The object type.
Writing a Target Application Processing a Restart Notification Object Sample Code /*****************************************************************************/ /* Name: format_restart_object */ /* */ /* Description: Extracts, formats and prints various fields of a restart */ /* object. Assumes object passed in is restart object. */ /* */ /* Parameters: obj restart object */ /* */ /* Return: None.
Writing a Target Application Processing a Restart Notification Object if (rm_get(restart_obj, RmMonitorTitle, &monitor_name, &error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get monitor name: %s", errbuf); printf ("Monitor Name:???\n"); } else { printf ("Monitor Name:%s\n", monitor_name); } if (rm_get(restart_obj, RmMonitorCommand, &monitor_path, &error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get monitor com
Writing a Target Application Processing a Restart Notification Object else { printf ("Impacted Resources:%s\n", resource_name); } do { if (rm_get(restart_obj,RmNextResourceEntry,&res_entry, &error_code)==-1) { rm_strerror(error_code, errbuf, sizeof(errbuf)); fprintf(stderr, "Could not get next resource from list: %s", errbuf); printf ("???\n"); } else if (res_entry != (rm_object_addr)NULL) { if (rm_get(res_entry,RmResourceName,&resource_name,&error_code) == -1) { rm_strerror(error_code, errbuf, sizeof(errb
Glossary A-K L-Z asynchronous monitor A monitor that monitors resource instances (or resource classes) asynchronously. It is event driven and sends notifications when events occur. It does not keep track of the current state or value of each resource it monitors. MC/ServiceGuard This is a software product that allows a user to customize and control resources that are to be highly available. In the event of a resource failure, MC/ServiceGuard transfers control to back-up resources.
monitoring requests. polling interval specifies how often the resource monitor should check the resource value to see if it satisfies the notification criteria. Valid values are 1-86400 seconds (24 hours). Registrar The Registrar process provides the link between resource status consumers (clients) and resource status providers (resource monitors). resource May be any entity an application developer names.
state information. Stateless monitors do not keep any history of past conditions. target The target application is notified when a monitored resource reaches the condition for which notification was requested. For example, the target application could be MC/ServiceGuard or ITO. texlog The notification type that logs EMS event notification to a text file. The file contains plain ASCII text.
Index A asterisk (*), in monitor request, 72 B backup log files, 33 Bad Monitor Request message, montest, 141 C catalog file, EMS, 64 client configuring, 60 D data types, 27 DEBUG, logging level, 32 DESCRIPTION, in resource dictionary, 73 dumping EMS objects, 51 E EMS catalog file, 64 other documentation, 60 EMS API, 22, 26 data types, 27 functions used by targets, 144 list of functions, 26 logging, 32, 45, 50, 51, 57, 65 resource types, 29 supported languages, 25 EMS, high availability, 10 ems_cmds file,
Index default hierarchy, 77 duplicate records, 71 examples, 75 file naming, 71 location of, 24 syntax, 72 wildcarding, 72 resource discovery, 70 Resource List, 161 resource monitor command to invoke, 73 environment values, 65 named pipe, 64 startup and initialization, 23, 64 testing, 134 Resource State object, 85, 113 copying, 54 resource types, 29 Resource Update Event, 48, 107 Resource Update object, 107 RESOURCE_NAME, in resource dictionary, 74 Restart Notification object, 158 RM_ACCEPT monitor reply, 9
Index RmMonitorReply, 96, 119 RmMonitorRestartType, 158, 161 RmMonitorReturnData, 108, 151 RmMonitorReturnDataLen, 108, 151 RmMonitorTitle, 65, 158 RmMonitorVendorName, 65, 158 RmMonitorVersionString, 65, 158 RmNextResourceEntry, 158 RmNumResources, 158 RmObjectType, 65, 85, 96, 108, 113, 119, 151, 158, 161 RmRequestID, 119 RmResourceName, 96, 108, 119, 151, 161 RmResourceType, 96, 108, 151 RmResourceValue, 108, 151 RmStateName, 85, 113 RmStateValue, 85, 113 RmSubclassName, 85 RmTargetHostname, 151 RmTarge
