HP WBEM Services Software Developer’s Kit for HP-UX Provider and Client Developer’s Guide Version 1.5 Manufacturing Part Number: T1434-90009 Sept 2003 © Copyright 2000-2003 Hewlett-Packard Company.
Legal Notices The information contained in this document is subject to change without notice. Warranty. 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.
PA-RISC and HP-UX are registered trademarks of Hewlett-Packard Company. PDF is a registered trademark of Adobe Systems Inc. Internet Explorer, Windows, WMI and Visio are registered trademarks of Microsoft Corporation. Solaris and Java are registered trademarks of Sun Microsystems, Inc. UML is a registered trademark of Object Management Group, Inc. Itanium is a registered trademark of Intel Corporation. UNIX is a registered trademark of The Open Group.
Contents 1. Introduction to WBEM, CIM, CIM Server, and Providers A Common Model of Systems and Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlled Extensibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client-Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CIM Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Key Values: Uniquely Specifying an Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multi-Threading for Concurrent Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Provider Programming Interfaces . . . . .
Contents Propagated Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Associations and Aggregations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Client Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents C. Code Example Showing CIM DateTime Conversion D. Example Provider Data Sheet Provider Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up This Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using This Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Links to More Information . . . . . . . . . . . . . . .
Printing History Table 1 Printing Date Part Number Edition September 2002 electronic release only First September 2003 T1434-90009 Second The last printing date and part number indicate the current edition, which applies to the A011.05 version of HP WBEM Services Software Developer’s Guide for HP-UX, Client and Developer’s Guide. The printing date changes when a new edition is printed. (Minor corrections and updates which are incorporated at reprint do not cause the date to change.
Preface Audience This document is intended for use by software professionals who will design, implement and/or support clients or providers for HP WBEM Services for HP-UX. Requisite Knowledge Developers should be familiar with the following topics: • Object-oriented design and programming concepts • The C++ programming language • The Common Information Model (CIM), as described on the DMTF (Distributed Management Task Force) web site: http://www.dmtf.org.
Navigation and Document Conventions Typefont is used to help identify CIM element names. (Italic type is used for other things as well, including titles and for emphasis.) Typefont is used to set off user-specified names, commands and filenames, and when introducing a new term. The names of functions and methods will generally be indicated with parentheses, for example, getInstance(). The word “function” will refer to a C++ function, and the word “method” will refer to a CIM operation.
1 Chapter 1 Introduction to WBEM, CIM, CIM Server, and Providers 13
Introduction to WBEM, CIM, CIM Server, and Providers A Common Model of Systems and Devices A Common Model of Systems and Devices Web-Based Enterprise Management (WBEM) is a set of standards, developed by the DMTF, to unify the management of enterprise computing environments, allowing a variety of information processing elements from different vendors to be managed in a uniform way.
Introduction to WBEM, CIM, CIM Server, and Providers A Common Model of Systems and Devices all of the properties of its parent, or superclass, and possibly other properties of its own. All of its properties would in turn be inherited by any subclasses. Inheritance offers an important benefit for client applications, since a client need not be developed to explicitly know about platform-specific features.
Introduction to WBEM, CIM, CIM Server, and Providers Controlled Extensibility Controlled Extensibility The hierarchical, inheritance-based nature of CIM allows it to be easily extended to account for differences on different operating systems. For example, there is no exact equivalent in Windows of the "mount point" concept of UNIX platforms. Conversely, there is no consistent notion in UNIX of the "registered user" (owner) of the operating system or other software components.
Introduction to WBEM, CIM, CIM Server, and Providers Client-Server Architecture Client-Server Architecture Another component of the WBEM standards, xmlCIM (a specialization of the eXtensible Markup Language or XML), defines the encoding that CIM clients and servers use to comunicate about CIM objects, and the operations that can be performed on them. An example of a typical XML exchange is shown in the Appendix B, XML Example.
Introduction to WBEM, CIM, CIM Server, and Providers The CIM Server The CIM Server A WBEM/CIM Server can operate directly on the underlying system by calling the system's commands, services, and library functions, or it can pass requests from clients onward to plug-in modules called Object Providers or simply Providers. This plug-in approach is preferred for general-purpose computer systems, which may have hundreds of different classes of objects and an almost unlimited number of possible configurations.
Introduction to WBEM, CIM, CIM Server, and Providers Providers Providers Providers get information about the system and fulfill other requests on behalf of client applications. Clients deal with instances of the classes of objects defined by CIM. An instance is a representation of a single manageable entity (such as a disk); it contains data obtained from the system by a provider. Providers perform the conversion between CIM and the platform's commands, services and data formats.
Introduction to WBEM, CIM, CIM Server, and Providers Providers Figure 1-1 Figure: HP WBEM Services for HP-UX System Architecture Two types of providers are currently supported by HP WBEM Services for HP-UX: Instance and Method. The instance provider allows manipulation of instances of classes, and of properties of those instances. The method provider allows clients to invoke extrinsic methods on instances.
Introduction to WBEM, CIM, CIM Server, and Providers Providers • enumerateInstances: returns all the instances of a class • enumerateInstanceNames: returns the names of all instances of a class (see the section on Key Values: Uniquely Specifying an Instance for information about instance names) • modifyInstance: replaces the values of specific properties of an instance • deleteInstance: deletes a specified instance Method providers implement just one function: invokeMethod.
Introduction to WBEM, CIM, CIM Server, and Providers Providers 22 Chapter 1
2 The Software Development Kit (SDK) The SDK for HP WBEM Services for HP-UX is distributed as an SD depot, bundle T1434BA. Installed with the swinstall utility.
The Software Development Kit (SDK) Product Contents Product Contents The following files are copied to the target system by the installation procedure: • Header files containing the C++ Client API and the C++ Provider API (.h) • Documentation: — API descriptions in HTML format — Readme file for example providers and clients • Examples: — Instance Provider — Method Provider — Enumerate Instances Client — Invoke Method Client • Example contents: — Sources — Makefile • Provider examples: — Schema (.
The Software Development Kit (SDK) System Requirements System Requirements Supported Platforms For the list of currently supported platforms, see the Release Notes for this product and for HP WBEM Services for HP-UX. HP WBEM Services documents are posted at http://www.docs.hp.com/hpux/netsys.
The Software Development Kit (SDK) Installation Installation Use the HP-UX swinstall utility to install the Software Development Kit. After the installation has completed, the user may build any of the examples included in the development kit to verify that the installation was successful.
The Software Development Kit (SDK) Removal Removal Use the HP-UX swremove utility to remove the Software Development Kit, product bundle number T1434BA.
The Software Development Kit (SDK) Removal 28 Chapter 2
3 Schema Design and Implementation Schema design is the process wherein real-world entities (such as processors, disks, software, or user accounts) are transformed into a Chapter 3 29
Schema Design and Implementation logical representation. The schema contains three kinds of information: • a definition of the details of each entity • the operations the entity supports • how classes of these entities are related to one another on a managed system Since real-world entities have attributes (properties) about themselves and actions (methods) they can perform, these are also aspects of the design of a schema.
Schema Design and Implementation Schema Design Schema Design The schema design process begins once required information and capabilities have been identified. The first prerequisite is to define use models. It is important to understand what information and capabilities clients require, and also how they support given tasks.
Schema Design and Implementation Schema Design Strategies for identifying client-use models include: • Consider one or more client use cases or scenarios (potential clients may be GUI-based tools or CLIs). • Identify which information needs to be provided. • Determine which actions must be performed. • Determine logical groupings of the information/actions. In addition, one may need to consider how the client-use model would be affected if the schema is hosted on several heterogeneous platforms.
Schema Design and Implementation Schema Design • Statistics are statistical information relevant to a given managed element. An example use is representing resource utilization of a running process. • Diagnostics are diagnostic invocation, settings, and results. An example use is disk diagnostics. • An Indication is the representation of the occurrence of an event. An example use is disk errors.
Schema Design and Implementation Schema Design Note that associations and aggregations inherit. That is, if a superclass has an association to another class x, all subclasses also inherit an association relationship to x. Also, it is possible to create specialized subclasses of the association if required (for example to define additional properties or methods). Next consider ancillary objects that should be associated with the primary managed elements.
Schema Design and Implementation Schema Design STEP 3: Consult DMTF Model DMTF has developed a general-purpose, implementation-independent schema for use in a large variety of applications, such as general computer systems, network devices, embedded systems, and storage arrays.
Schema Design and Implementation Schema Design be confident that clients which have implemented using the standard CIM schema will be able to find desired management data in expected places in the schema hierarchy. During this process of refining the draft schema through examination of the DMTF CIM schema, it may also be interesting to identify properties and methods for some of the classes as a means to better understand the objects being modeled.
Schema Design and Implementation Schema Design When searching the DMTF schema for applicable modeling elements, one may discover that the structure of the CIM data does not readily match the domain of interest. This is usually recognized by noting that the designed management data is broadly scattered across many classes, and that for most classes a provider would be able to fill in very few values for properties or instrument very few of the methods.
Schema Design and Implementation Schema Design • Try to place the property as high in the class hierarchy as possible while maintaining appropriate meaning. Note that changes to the DMTF schema need to be worked through an appropriate DMTF working group as discussed in MOF File Content Guidelines below. • Consider if the property would still make sense in a lower subclass derived at some point in the future.
Schema Design and Implementation Schema Design Rules about Key properties when creating a subclass include: • If a superclass already has (or inherits) key properties, no key properties may be added to or deleted from its subclasses. • All concrete classes must have keys. (A concrete class is a class that may have instances.) In conjunction with the identification of keys for a given class, one must consider possible associations with the class.
Schema Design and Implementation Schema Design Validate Schema with Client Use Models At this point in the process, it is useful to refer back to the client-use models derived in STEP 1: Define High-Level Client-Use Models above. A successful schema design will be clear and simple to use for management applications. Aspects of the client-use models and scenarios to consider include: • Ensure that all the information required is available as properties on the expected objects.
Schema Design and Implementation Schema Design Schema Interfaces Between Providers (Associations and Aggregations) A significant consideration (see also Provider Design Considerations below) in understanding a provider's interaction with other providers is that of how classes instrumented by separate providers are related. In CIM, classes are related via associations and aggregations.
Schema Design and Implementation Schema Design Standard CIM practice does not permit removal of classes, properties, or methods for minor version updates; instead deprecation is permitted through the Deprecate qualifier. Thus, while deprecation is possible, it does imply continued provider support of the deprecated schema, enabling clients to continue functioning with deprecated schema, re-implementing to the new schema over time.
Schema Design and Implementation Schema Design installed, identifying them as appropriate subclasses of CIM_USBDevice (for example ACME_USBPrinter or ACME_USBMouse). However, very little is known about an attached device which does not have a driver. Such an unknown device could be modeled as a separate "unknown" subclass such as ACME_UnknownUSBDevice.
Schema Design and Implementation Schema Design Determine Qualifiers Qualifiers are attached to classes, properties, and methods. Select necessary and sufficient qualifiers for each. Particular qualifiers to consider include: • Association to indicate a class is an association; • Description which should be used for all properties, methods, and classes to describe their purpose; • Version which is required to ensure clarity of which definition is being used for a given class.
Schema Design and Implementation Schema Design Performance considerations in case (3) usually involve situations where a large number of instances are retrieved (and perhaps filtered) to obtain the necessary information. An example of this case would be an application which wishes to show the total disk space available on a platform.
Schema Design and Implementation Schema Implementation Schema Implementation In addition to the DMTF-specified syntax for MOF files as described in the CIM specification and the guidance provided by the DMTF MOF Style Guide, additional factors should be considered for the development, testing, and on-going maintenance of MOF files. MOF File Content Guidelines MOF is the standard format for defining CIM objects.
Schema Design and Implementation Schema Implementation • Instance Definitions Instances can be defined in MOF. The result of these definitions is that a provider supporting instances of the class receives a request to create an instance with the values specified in the MOF file.
Schema Design and Implementation Schema Implementation • Deletion of a class, property, or method • Movement of a class within the hierarchy in any direction except "down" as a side effect of a new superclass being inserted in the line of descent above • Changing a property's type or a method's signature (method type, parameter type, names of parameters, number of parameters) • Decreasing Max or increasing Min cardinalities of associations A detailed specification of changes which cause a major revi
Schema Design and Implementation Schema Implementation it could be accomplished if a provider could be certain that all clients using the class, property, or method were upgraded simultaneously with the provider. This is very difficult to ensure and is not recommended. Class "Version" qualifiers The DMTF uses the major and minor version numbers to reflect which version of the CIM schema originated a class. The format for class version numbers is "m.n.
Schema Design and Implementation Schema Implementation newest version (with correct version number) of the class should be used with a new release of any of the MOFs which all share the same superclass.
4 Provider Implementation This section has information and examples to help you design and implement a provider.
Provider Implementation Provider Basics Provider Basics The provider development task has three components: • define the resources or system parameters to be manipulated as CIM objects (the schema) • write C++ functions as described in the Provider API specifications (built as a shared library). For API information, see HP WBEM Services Software Developers Kit documentation in /opt/wbem/html directory.
Provider Implementation Provider Basics 5. Write two MOF files: one defines the schema to be instrumented, and the other is used to register the provider 6. Design the provider and make implementation decisions 7. Implement the provider 8. Build the provider 9. Test and debug the provider 10. Document, package, and release the provider We recommend that developers start by writing the Provider Data Sheet (PDS).
Provider Implementation Provider Design Considerations Provider Design Considerations Flow Of A Client Request The following is a high-level description of the control flow of a client request: • A client issues a request for data or an operation; the request is encoded in xmlCIM by the Client API (if used) and sent to the CIM server.
Provider Implementation Provider Design Considerations for HP-UX, the provider functions are called in the process context of the CIM Server. However, the provider must not assume that it is running in the same process as the CIM Server. The process context in which a provider runs is determined by the CIM Server, and is not configurable. This means that it is not possible to set environment variables, working directory, permission mask, or any other environment parameters before a provider is activated.
Provider Implementation Provider Design Considerations Example 4-1 PG_ProviderModule: An abridged MOF declaration class PG_ProviderModule : CIM_LogicalElement { [ Key ] string Name; string Vendor; string Version; string InterfaceType; string InterfaceVersion; string Location; uint16 OperationalStatus[]; string OtherStatusDescription; uint32 start(); uint32 stop(); }; A shared library (provider module) may contain more than one provider.
Provider Implementation Provider Design Considerations Name = "DynamicInfoModule"; Location = "DynamicInfoModule"; Vendor = "ACME Computer Corp."; Version = "2.0.0"; InterfaceType = "C++Default"; InterfaceVersion = "2.1.0"; // required // required // required // required }; The Location property is used to construct the path of the shared library containing the provider module as described in Figure 4-2, above. The extension is either .sl or .
Provider Implementation Provider Design Considerations The ProviderModuleName property is a string whose value must be the same (case insensitive) as the Name property of an instance of PG_ProviderModule. The Name property in PG_Provider is the string the CIM Server will pass to the PegasusCreateProvider function when it needs a pointer to the provider (the first time it calls a function in the provider).
Provider Implementation Provider Design Considerations extern "C" CIMProvider * PegasusCreateProvider(const String &providerName) { // create new provider instance on heap and return its // address.
Provider Implementation Provider Design Considerations PG_ProviderCapabilities The class PG_ProviderCapabilities is used to associate a provider with the class for which it supplies instances, methods, indications, or associations in the specified namespace. Example 4-6 shows the definition of PG_ProviderCapabilities in a MOF declaration: Example 4-6 PG_ProviderCapabilities: An abridged MOF declaration class PG_ProviderCapabilities : CIM_ManagedElement { [ Key, Propagated ("PG_Provider.
Provider Implementation Provider Design Considerations • SupportedProperties lists the properties supported by this provider. If this array is NULL, the provider MUST support all of the properties defined in the class. If the provider does not support all of the properties, the properties supported MUST be included in the array. • SupportedMethods lists the methods supported by this provider. If this array is NULL, the provider MUST support all the methods defined in the class.
Provider Implementation Provider Design Considerations ClassName = "ACME_ComputerSystem"; // required namespaces = { "root/cimv2" }; // required ProviderType = { 2 }; // 2=InstanceProvider // required SupportedProperties = NULL; // NULL=All properties SupportedMethods = NULL; // NULL=All methods }; The instance of PG_ProviderCapabilities in Example 4-8 informs the CIM Server as follows: • This capability instance is for a provider named ACME_ComputerSystemProvider in the module ComputerSystemModule.
Provider Implementation Provider Design Considerations A provider may implement more than one interface, but there can be no more than one Instance Provider for a class in a namespace! Often, it is useful to implement several interfaces in the same provider, as this allows the platform-specific code that accesses system resources to be shared. • The SupportedProperties property is an array of strings, each of which name a property of the instrumented class.
Provider Implementation Provider Design Considerations is built (PG_ProviderModule.Location), and the schema element with which it is associated (PG_ProviderCapabilities.ClassName). However, for clarity, it is useful to choose names that help to identify the element. The conventions evident in the previous example show how this may be done. Key Values: Uniquely Specifying an Instance Most providers manipulate instances or instance references (also called object paths) in some way.
Provider Implementation Provider Design Considerations • SystemName The Name property in the instance of the system that identified the object in question. A typical value could be a fully qualified IP hostname, such as idsys.hp.com. The values returned for these properties by different providers must be consistent. That is, all providers that return the SystemCreationClassName and SystemName keys must return consistent values for these keys when referring to the same scope.
Provider Implementation Provider Design Considerations The unique name of the instance within the scope defined by the previous keys. In many classes, this non-propagated key will be called Name, DeviceID, Handle or something that allows the user to understand that it will contain a value that is unique within that class of object. It is entirely up to the provider to determine the value of a Name (or analogous) key.
Provider Implementation Provider Design Considerations Use of Empty String Key Values While the full set of keys is necessary to uniquely identify an instance within a namespace, it is useful to allow clients to specify empty strings for key values when there is no ambiguity. For example, when a client submits a getInstance() operation to a CIM Server, it is clear that the value of the SystemName key will normally be the same as the system to which the client has connected.
Provider Implementation Provider Design Considerations unique symbols, because the functions are declared in differently named provider classes. However, it is possible to declare global symbols (technically, named ::), and these may indeed "collide" with symbols of the same name. This issue is not unique to C++ nor to HP WBEM Services for HP-UX providers. Care should be taken to avoid the use of global symbol names whenever possible.
Provider Implementation Provider Design Considerations As previously mentioned, providers run under the root user ID. Providers must use the username to determine whether the user has permission to perform the requested operation. This determination must be made in addition to the namespace authorization that the CIM Server may have performed. The provider must not perform any operation that would be unauthorized for the user on whose behalf it is executing the request.
Provider Implementation The Provider Programming Interfaces The Provider Programming Interfaces This section discusses the provider interfaces at a general level. Specific information about the functions, their interface, arguments and data types, can be found in the HP WBEM Services Software Developer’s Kit documentation in the /opt/wbem/html directory.
Provider Implementation The Provider Programming Interfaces Main Arguments Most provider API functions take a class or an instance reference (an instance of the C++ CIMObjectPath class, sometimes called an instance name or object path) as the principle argument. A reference uniquely identifies an object (a class definition or an instance). It specifies a class name and, if an instance reference, the set of keys that uniquely identify the object.
Provider Implementation The Provider Programming Interfaces Handling Error Conditions All errors must be reported to the CIM Server by throwing an exception. The exception codes are listed in the API documentation in the Software Developers Kit, in the /opt/wbem/html directory. PegasusCreateProvider and the Provider Class Constructor and Destructor As previously discussed, a provider is an instance of a C++ class derived from one or more of the provider interfaces.
Provider Implementation The Provider Programming Interfaces // specifier is not required for a global instance declaration, // as shown. ExampleProvider exp; extern "C" CIMProvider* PegasusCreateProvider(const String &providerName) { // return the address of the global provider instance if String::equalNoCase(providerName, "ExampleProvider") return &exp; else return 0; } The provider constructor and destructor should do as little as possible.
Provider Implementation The Provider Programming Interfaces ResponseHandler processing() and complete() functions without calling deliver(). In either case, the client will receive an empty response. If the instance named by getInstance(), modifyInstance(), or deleteInstance() does not exist, the provider must throw a CIMObjectNotFoundException exception. Method Provider A MethodProvider implements methods that are defined in a class.
Provider Implementation Building Providers Building Providers For detailed information on the following material, please refer to the documentation for the HP-UX C++ compiler (aCC) and linker (ld) at http://www.docs.hp.com/hpux/dev. The provider C++ source file must be compiled with the aCC compiler. The options are: • -c (optional) Causes the compiler to stop after the compilation phase and generate an object file output (.o) instead of continuing on to the link phase.
Provider Implementation Building Providers • -I/opt/wbem/include Instructs the compiler where to look for header files that are needed to compile providers • -DPEGASUS_PLATFORM_HPUX_PARISC_ACC (PA) -DPEGASUS_PLATFORM_HPUX_IA64_ACC (IA) Defines compile-time macro needed to control conditional compilation on HP-UX The shared library should be linked with the aCC command using the following options (shared libraries could also be linked with the ld command, but using aCC automatically links the necessary C
Provider Implementation Building Providers Inserts into the list of dynamically linked shared libraries: — For PA: /opt/wbem/lib/libpegcommon.sl and /opt/wbem/lib/libpegprovider.sl — For IA: /opt/wbem/lib/libpegcommon.so and /opt/wbem/lib/libpegprovider.so Other options may be specified, as needed, as long as they do not conflict with those shown above. The following example shows a Makefile constructed according to the previous discussion.
Provider Implementation Testing and Debugging Providers Testing and Debugging Providers The following kinds of testing should be considered: • Installation • Schema modification during installation: verify that guidelines for upgrading schema are observed. (See Chapter 3, Rules for Updating Schema.
Provider Implementation Testing and Debugging Providers Note that the ownership and permissions on both the link and the target file (and its path) must not rely on the fact that the current CIM Server runs under the root user ID. 2. Create schema definitions for the class or classes that the provider serves (if not already done) by using the cimmof command to compile and load MOF files containing the class definitions. For example: $ cimmof TestClass.mof Since TestClass.
Provider Implementation Testing and Debugging Providers providers remain loaded until a system administrator invokes a command to stop and unload them. The cimprovider command is used for this purpose, and is described in the cimprovider man page. The steps required to stop and unload a provider so that a new shared library can be installed are: 1. Stop the provider using the cimprovider command. (Note that this command actually operates on the provider module and stops all providers in the module.
Provider Implementation Testing and Debugging Providers $ cimprovider -e -m TestProviderModule Enabling provider module... Provider module enabled successfully. Again, if the provider was removed in order to update the Provider Registration, rather than simply stopped, then it must be re-registered with cimmof, rather than re-enabled with cimprovider, as described in the previous section on Installing and Running a Provider.
Provider Implementation Packaging and Release Packaging and Release Providers for HP WBEM Services for HP-UX are software products. They may be delivered through any vehicle suitable for the delivery of a software product intended for installation on HP-UX. The Software Distributor facility (SD) is particularly well suited for this purpose (SD is described on HP's web site at http://software.hp.com/products/SD_AT_HP/faqs/general.html).
Provider Implementation Packaging and Release • Provider Data Sheet (PDS) A description of the provider which includes a list of properties and methods served by the provider. This component is not required for a provider package, but is strongly encouraged.
Provider Implementation Packaging and Release • Executable binary (built as a shared library) • Schema being instrumented and provider registration (installed with either the cimmof command or a client application The following directory is reserved for the required components listed above: /opt/wbem/providers/lib Installation of the schema instrumented and provider registration are the responsibility of the provider developer, and are normally performed in the provider’s SD configure script.
Provider Implementation Packaging and Release procedure, or by a client program that has been implemented specifically for this purpose. In either case, it is imperative that the schema update follow the Rules for Updating Schema described previously. Upgrading an Existing Provider The basic steps in upgrading a provider are: • Check for prerequisites • Disable the provider. (See section on Stopping the Provider in this chapter.
Provider Implementation Operation Operation Starting the Provider A provider is started automatically by the CIM Server when a client requests an operation on a class that it services and the module containing the provider is not currently disabled. The cimprovider -l command can be used to verify that the provider module has been loaded. The cimprovider command can be used to disable and enable the provider module. Please see the cimprovider man page for more information.
Provider Implementation Documentation Documentation Provider Data Sheet The Provider Data Sheet is a description of the important characteristics of the provider. It lists: • System requirements (dependencies) • Files included in the bundle • Installation steps (quick guide) • Class(es) supported • interfaces that are implemented • Properties and methods • Exceptions thrown • Files and environment variables used A Example Provider Data Sheet is included in the Appendix D.
Provider Implementation Special Issues: Coexistence With Other Manageability Products Special Issues: Coexistence With Other Manageability Products HP WBEM Services for HP-UX can co-exist with other applications. Providers can co-exist with other applications as long as they do not both require exclusive use of the same resource. • SNMP SNMP and HP WBEM Services for HP-UX can run on the same system simultaneously.
5 Client Implementation A WBEM client application is any software application that makes manageability requests (CIM operations) of a CIM server using the CIM-XML protocol over HTTP. Clients can range from general purpose to extremely specific.
Client Implementation heterogeneous platform environments or to operate on a particular platform, manage only the local system on which they are running, or manage one or more remote systems or entities. Platforms may be general-purpose servers or specific-purpose devices such as printers or storage arrays.
Client Implementation Discovery Discovery Discovering Platforms HP WBEM Services for HP-UX listens for HTTP communication on port 5989 (for encrypted communication, the default behavior) or 5988 (for unencrypted communication). A client can attempt to connect to either of these ports to determine if a CIM Server is running.
Client Implementation Discovery name will begin enumeration at the root level in the namespace. A value of true will return all derived classes. The CIM_ERR_INVALID_CLASS status will be returned if the specified class does not exist. Thus, for a client to discover if schema of interest is supported on the target platform, it can perform enumerateClassNames operations for the classes that it would use.
Client Implementation Navigating Schema Navigating Schema An important consideration in client design is what methodologies will be used in navigating the schema presented by CIM servers on various managed platforms. A correct understanding of the use of keys and associations in schema navigation can facilitate greater efficiency and performance of client/server interactions as well as enabling interoperability across heterogeneous managed systems.
Client Implementation Navigating Schema string Name; uint16 OSType; string OtherTypeDescription; . . . // additional properties and methods . . . }; Key properties may be defined for an abstract class (a class with the Abstract qualifier). If a class has a concrete class as its parent, it must have the same keys. Only concrete classes can have instances. Keys on Subclasses A class inherits all the keys of its superclass.
Client Implementation Navigating Schema subclasses of CIM_LogicalDevice) might have common values for DeviceID, having values for CreationClassName which match their individual class names ensures uniqueness. Enumerating Instance Names When a client performs the enumerateInstanceNames CIM operation, it specifies a namespace and a class name. The CIM server then returns values of the key properties for instances of that class within the specified namespace.
Client Implementation Navigating Schema • Process within an Operating System running on a Computer System For each of these examples, an instance of the first class is more completely defined by understanding within which instance of the second class it is scoped. Note that in the last example, a process is scoped within the context of both its operating system and its computer system.
Client Implementation Navigating Schema Finding Associated Instances The use of propagated keys effectively creates associations between classes without explicitly defining an association class for which instances would need to exist in order for a client to be able to find associated objects. When a client receives an instance of an explicitly defined association class, the paths to referenced objects are obtained directly from the properties of the association instance.
Client Implementation Navigating Schema only one instance in the namespace (e.g. CIM_System) and then use that information in performing a getInstance operation on the scoped class (e.g. CIM_LogicalDevice). This short cut may not be available with all providers; if it is, this should be identified in the provider's documentation. Associations and Aggregations Associations are classes that contain two or more references to instances of other classes.
Client Implementation Navigating Schema Aggregations are a special form of assocation. Aggregations have all the attributes of associations, however with the additional semantics that classes scoped to another class via an aggregation make up the scoping class (instead of merely being "associated" with it). Best Practices Listed below are several client application "best practices" for navigating schema.
Client Implementation Navigating Schema properties defined in subclasses should be returned (just those properties inherited from superclasses and local to the class specified in the operation). HP WBEM Services only supports the value TRUE for the DeepInheritance flag. Local Only Flag The LocalOnly flag indicates that the enumerateInstance and getInstance operations should return only properties defined in the designated class and none of those defined in superclasses.
Client Implementation Client Security Considerations Client Security Considerations As discussed in the section on provider security, the HP WBEM Services for HP-UX CIM Server performs authentication (test for valid user and, if remote, password) and authorization (test for permission to perform an operation on an object in a namespace, if enabled) on all requests. Also, the CIM Server can be configured to accept encrypted or unencrypted communication.
Client Implementation Client Security Considerations More information on the authentication and encryption algorithms used may be found in the HP WBEM Services for HP-UX System Administrator's Guide on docs.hp.com/hpux/netsys. Since the client may not know in advance which port the target system has been configured to use, it can attempt to connect to one first, then the other. The preferred order would be to try encrypted port 5989 first when connecting to HP-UX systems.
Client Implementation Client Development Best Practices Client Development Best Practices This section describes several best practices for the development of WBEM client applications. Using Provider Data Sheets Provider Data Sheets (PDSs) greatly help an implementer of client applications to understand the available management functionality. Provider developers are expected to publish a PDS for their provider.
Client Implementation Client Development Best Practices Prototyping with wbemexec When analyzing the appropriate techniques for schema navigation and determining the type of data available on a managed system, it is often useful to prototype the functionality using the general-purpose wbemexec client included with HP WBEM Services for HP-UX. wbemexec takes a CIM-XML request from a file or standard input, sends it to a CIM server, receives the response, and displays it to standard output.
Client Implementation Client Development Use Cases Client Development Use Cases By way of example, several use cases are described below. These use cases illustrate issues that WBEM client developers may encounter in designing and implementing their applications. A general description and recommended best practices are included with each use case. General System Information Description Some clients only need general system information describing the platform and its running operating system.
Client Implementation Client Development Use Cases to see if this case exists. If so, the class can be accessed using the enumerateInstance operation with the DeepInheritance flag set to TRUE. In addition, it may be useful to support some general mechanism for the user to invoke methods specific to subclasses. Multiple Dynamic Instances Description Some clients may need to retrieve dynamic information.
Client Implementation Client Development Use Cases Special Considerations Clients may be able to simplify their discovery processing to identify that the appropriate namespace and schema elements are present on the target platform. Also, it may be useful to check the version of the provider to ensure that it can support the client requests. Best Practices It is useful to perform appropriate discovery operations during initial connection to a target platform.
Client Implementation Building Clients Building Clients Clients should be compiled and linked with the aCC C++ compiler. The make utility can be used to control this. The following example Makefile illustrates the necessary compilation and link flags for building a client. LIBRARIES = -L/opt/wbem/lib -lpegcommon -lpegclient INCLUDE = -I/opt/wbem/include ACC_OPTIONS = $(PLATFORM_ACC_OPTIONS) $(INCLUDE) OUTPUT = $(PROGRAM) CURRENTPATH = $(PWD) OBJECTS = $(SOURCES:.cpp=.o) .cpp.
Client Implementation Sample Clients Sample Clients The sample client programs included with the SDK illustrate the use of EnumerateInstances and InvokeMethod client APIs. The sample client programs are located in the /opt/wbem/sample/Clients directory.
Client Implementation Packaging and Release Packaging and Release A WBEM client program is a conventional, independent HP-UX application, in that HP WBEM Services for HP-UX does not invoke it or depend on it. For this reason, conventional HP-UX application packaging and release processes may be employed without need for special consideration. Extensive information for developers can be found on software.hp.com.
A CIM Naming Guidelines A goal of WBEM is to make client access to managed systems as platform- and OS-independent as possible.
CIM Naming Guidelines code to handle a plethora of implementations. This section defines naming conventions for CIM namespaces, classes, properties, and methods.
CIM Naming Guidelines namespaces namespaces namespaces are the contexts within which schemas are defined. Within a given namespace, the instances of the classes defined are guaranteed to be unique. Different namespaces may be created to group related information, to define separate views of managed resources, or to limit client authorization to access certain objects.
CIM Naming Guidelines namespaces this namespace are distinct from those which have are considered to be special purpose, for example those for the purpose of security or some specialized system view. The name of the Managed System namespace corresponds to the context within which the managed objects are placed (for example platform vendor, OS), and the major version of the CIM schema supported. For systems manufactured by the fictitious ACME Corporation, the default namespace within which CIM version 2.
CIM Naming Guidelines namespaces In addition, giving related namespaces similar names adds clarity about their associated purposes. For example, applicationXYZ could be a namespace for objects related to a particular application, and applicationXYZ/special-auth could be used for special objects that have additional client authorization constraints.
CIM Naming Guidelines Classes Classes Class names are defined within the context of a particular namespace. Naming conventions for classes help clarify the managed domain a class is scoped to support. Adhering to the naming conventions also has the added benefit of making it possible for clients to find class extensions across the various platforms and devices supported by a vendor.
CIM Naming Guidelines Classes Subclassing to Specialize The normal case for subclassing is when a class represents a subset of instances of its superclass. In these cases, the most important naming convention is to use the most descriptive and precise name possible. Creating intermediate subclasses should be considered if applicable. One should also consider the potential for definition of additional subclasses in some future schema release.
CIM Naming Guidelines Classes Subclassing to Add Properties/Methods Extending the schema to create a new subclass is also appropriate when adding properties or methods to a DMTF class. In addition, overriding a property or method (such as to include the write qualifier on a property) is also a valid reason to create a subclass.
CIM Naming Guidelines Properties and Methods Properties and Methods Properties and methods are defined for individual classes and inherited by their subclasses. Property and Method names should be constructed of one or more words, each of which begins with a capital letter.
CIM Naming Guidelines Properties and Methods Examples from Elsewhere with the Schema When a needed property or method is not defined in a superclass, the best policy is to look elsewhere in the schema for a similar property or method. It is possible that other classes may exist which bear similarities to the class being defined. These other classes may have similar properties or methods that if used in the class being defined could make use of the class more intuitive to the client application user.
B Appendix B XML Example 121
XML Example The following example shows a request to get the names of instances of the CIM_ComputerSystem class (there is generally only one instance), followed by a response containing the name of the system. Items showing important elements of the message are highlighted. Example B-1 Request sent by client PAGE 123XML Example ACME_ComputerSystem idsys.hp.com ...
XML Example 124 Appendix B
C Code Example Showing CIM DateTime Conversion The following code fragment shows how a time value obtained from a library function call can be converted to the CIM DateTime format.
Code Example Showing CIM DateTime Conversion information on the CIM DateTime format can be found in the CIM Specification on the DMTF web site. #include ... { ... struct tm *t = localtime(); // localtime() used as an example char tmp[26]; sprintf(tmp, "%04d%02d%02d%02d%02d%02d.000000%c%03d", t->tm_year+1900, t->tm_mon+1, //HP-UX stores month 0-11 t->tm_mday, t->tm_hour, t->tm_min, t->tm_sec, (timezone>0)?'-':'+', labs(timezone/60 - (t->tm_isdst? 60:0))); CIMDateTime d(tmp); ...
D Example Provider Data Sheet HP-UX operating system CIM provider Appendix D 127
Example Provider Data Sheet Provider Overview Provider Overview Description—The Operating System Provider makes available operating system information such as operating system type, version, last boot up time, local date and time, number of users, swap space size, and free physical memory. The Operating System Provider instruments the CIM_OperatingSystem class and PG_OperatingSystem subclass. Not all properties of the CIM_OperatingSystem are currently supported.
Example Provider Data Sheet Setting Up This Provider Setting Up This Provider Installing this provider—The Operating System Provider is contained within an operating system provider module (it is the only provider within that module). The provider module is bundled with HP WBEM Services for HP-UX including: • Schema MOF file: PG_OperatingSystem20.mof (in /etc/opt/wbem/mof) • Provider registration MOF file: PG_OperatingSystem20R.mof (in /etc/opt/wbem/mof) • Provider module executable: libOSProvider.
Example Provider Data Sheet Using This Provider Using This Provider Schema supported by this provider—This provider supports the CIM_OperatingSystem and PG_OperatingSystem classes. Tables 1 through 4 describe the properties and methods supported by the provider. Table 1 describes the properties of the CIM_OperatingSystem class. It has three columns.
Example Provider Data Sheet Using This Provider Table D-1 CIM_OperatingSystem Properties (Continued) Property Inheritance Property Value (and data source) string Status Inherited from CIM_ManagedSystem Element HP-UX: Returns "Unknown" (although if the OS is running enough for CIM Server to function, may consider "OK", but would need to distinguish it from "Degraded" or "Stopping").
Example Provider Data Sheet Using This Provider Table D-1 CIM_OperatingSystem Properties (Continued) Property Inheritance Property Value (and data source) string Name [Key] Inherited from CIM_ManagedSystem Element (and made one of 4 keys of CIM_OperatingSyst em) HP-UX: Returns the name of this system from the sysname field of the uname() system call. uint16 OSType Local to CIM_OperatingSyst em HP-UX: Returns 8 (defined by DMTF as the value to set for HP-UX).
Example Provider Data Sheet Using This Provider Table D-1 Appendix D CIM_OperatingSystem Properties (Continued) Property Name Property Inheritance Property Value (and data source) Uint32 NumberOfLicensed Users Local to CIM_OperatingSyst em HP-UX: Returns number of licensed users from interpreting the version string of the uname() system call (0 if unlimited or 128 or 256). Uint32 NumberOfUsers Local to CIM_OperatingSyst em HP-UX: Returns the number of ut_usrs from getutent calls.
Example Provider Data Sheet Using This Provider Table D-1 134 CIM_OperatingSystem Properties (Continued) Property Name Property Inheritance Property Value (and data source) Uint64 FreePhysicalMemo ry (in KiloBytes) Local to CIM_OperatingSyst em HP-UX: Returns information from the pstat() system call (psd_free). Uint64 TotalVisibleMemo rySize (in KiloBytes) Local to CIM_OperatingSyst em HP-UX: Returns information from the pstat() system call; physical memory adjusted for page size.
Example Provider Data Sheet Using This Provider Table D-1 CIM_OperatingSystem Properties (Continued) Property Name Property Inheritance Uint32 MaxProcessesPerU ser Local to CIM_OperatingSyst em Property Value (and data source) HP-UX: Returns the _SC_CHILD_MAX value from sysconf() system call. Table 2 describes the properties of the PG_OperatingSystem class. It has three columns.
Example Provider Data Sheet Using This Provider on the PG_ subclass (as the CIM Server will invoke subclass providers on enumerations). The provider current registers as an instance provider and a method provider. Table 3 describes the intrinsic methods supported by this provider. It has three columns. The first is the method name, the second is a description of the providerís actions based on invoking that method, and the third is a list of any exceptions that could result from invoking the method.
Example Provider Data Sheet Using This Provider Table D-3 intrinsic methods for CIM_OperatingSystem and PG_OperatingSystem (Continued) Method Name Description Exceptions Thrown DeleteInstance Returns Not Supported. CIM_ERR_NOT_SUPPORT ED Initialize Not Supported. None Terminate Not Supported. None CreateInstance Returns Not Supported. CIM_ERR_NOT_SUPPORT ED Table 4 describes the extrinsic methods supported by this provider. It has three columns.
Example Provider Data Sheet Links to More Information Links to More Information • Additional provider documentation There is currently no additional documentation for this provider beyond this information. See also man pages for information on the various commands and system calls noted in the descriptions above. • WBEM information For a CIM tutorial, go to http://www.dmtf.org/education/cimtutorial.php. For information about HP WBEM Services for HP-UX, see software.hp.com and hp.
E Factors for Estimating Provider Effort This section summarizes the factors to consider when determining how much time it will take to design, implement, test and release a provider.
Factors for Estimating Provider Effort This is just a tool to help with estimates. Providers can take as little as two weeks to as long as several months depending on a variety of factors. Each item below adds time to the schedule. To get a very rough estimate of provider effort, answer the questions below and add the days together. • Schema complexity Defining the schema can be very simple or can be very complex and time consuming.
Factors for Estimating Provider Effort — Don't know exactly how to get the information but someone else does and can help you - 3 Days — Have to test the calls or don't know how to get the information and no one else does either - ranges greatly • Static vs.
Factors for Estimating Provider Effort • Number of different interfaces, operating systems and platforms that will be supported If you are supporting Windows, Linux and HP-UX on PA-RISC and IPF, you will have much more work then if you have one set of calls to make. If you have multiple interfaces required for the same information (for example, across OS types and versions and different hardware), it will take longer to code and test.
Factors for Estimating Provider Effort Testing, quality goals, robustness, equipment availability, dependencies, high availability requirements, experience with WBEM, C++, HP WBEM Services for HP-UX.
Factors for Estimating Provider Effort 144 Appendix E
F Appendix F Glossary 145
Glossary Common Information Model (CIM) A hierarchical object-based model developed by the DMTF that defines a large number of concepts common to most computer systems. The CIM specification can be found on the DMTF web site. CIM Client An application that issues CIM operation requests to a CIM server. CIM Object Manager (CIM Server) The CIM Server manages the definitions of CIM objects, and directs the flow of information between clients and providers in a CIM server.
Glossary An industry wide standards organization committed to making computing resources and environments easier to use, understand, configure, and manage. (web site http://www.dmtf.org/) Extensible Markup Language (XML) A simplified subset of SGML that offers powerful and extensible data modeling capabilities. An XML Document is a collection of data represented in XML. An XML Schema is a grammar that describes the structure of an XML Document.
Glossary The actual item in the system environment that is accessed by the provider. For example, a Network Interface Card, an Operating System kernel parameter, a system user, a print spooler. Managed Object Format (MOF) A compiled language for defining classes and instances. The MOF compiler compiles .mof text files, adding the data to the CIM Object Manager Repository. MOF eliminates the need to write code, thus providing a simple and fast technique for modifying the CIM Object Manager Repository.
Glossary Provides basic provider information to software professionals who will design, implement, enhance, and/or support client applications that will use this provider. It contains information about what this provider does, what interfaces it uses, how to install it and what platforms and operating systems are supported. An example and template are included in this manual.
Glossary being Primates, have all of the Attributes (or Properties) or Primates, but have additional properties, such as Nationality. By convention, in a UML diagram of CIM classes, only properties specific to a class, and not those inherited from the parent class and those above, are shown. But the inherited properties are also understood to be present.
