Sun Microsystems WDR Guide

Download

WDR Developer’s Guide

Creating WBEM-Based System Management

Applications

Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054 U.S.A.

Part No. 816-1984-11 September 2002

Send comments about this document to: docfeedback@sun.com

Copyright 2002Sun Microsystems, Inc.,4150 NetworkCircle, SantaClara, CA95054 U.S.A.All rightsreserved. This product ordocument isdistributed underlicenses restrictingits use,copying, distribution,and decompilation.No partof thisproduct or

document may be reproduced inany formby anymeans withoutprior writtenauthorization ofSun andits licensors,if any.Third-party software,including fonttechnology,is copyrighted and licensed from Sun suppliers.

Parts of the product maybe derivedfrom BerkeleyBSD systems,licensed fromthe University of California. UNIX is a registered trademarkin the U.S. and other countries, exclusively licensed through X/OpenCompany,Ltd.

Sun, Sun Microsystems,the Sunlogo, AnswerBook2,docs.sun.com, SunFire, Sun4U,SunSwift, Java,JDK, andSolaris aretrademarks, registeredtrademarks, orservice marksof SunMicrosystems, Inc. in the U.S. and other countries. All SPARC trademarks areused underlicense and are trademarksor registeredtrademarks of SPARCInternational, Inc. in the U.S. and other countries. Productsbearing SPARCtrademarks arebased uponan architecturedeveloped by Sun Microsystems, Inc.

The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems,Inc. forits usersand licensees.Sun acknowledges the pioneering effortsof Xeroxin researchingand developing the concept of visual or graphical user interfaces for the computer industry.Sun holds a non-exclusive license fromXerox tothe XeroxGraphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements.

Federal Acquisitions: CommercialSoftware—Government UsersSubject toStandard License Termsand Conditions. DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,

INCLUDING ANY IMPLIED WARRANTYOF MERCHANTABILITY,FITNESS FOR A PARTICULARPURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2002 Sun Microsystems, Inc.,4150 NetworkCircle, SantaClara, CA95054 Etats-Unis.Tousdroits réservés. Ce produit oudocument estdistribué avecdes licencesqui enrestreignent l’utilisation, la copie, la distribution, et la décompilation. Aucune

partie de ce produit oudocument nepeut êtrereproduite sous aucune forme, par quelque moyen que ce soit, sans l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, et qui comprend latechnologie relativeaux policesde caractères,est protégépar uncopyright etlicencié pardes fournisseursde Sun.

Des parties de ce produitpourront êtredérivées des systèmes Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d’autres payset licenciéeexclusivement parX/Open Company,Ltd.

Sun, Sun Microsystems,le logoSun, AnswerBook2,docs.sun.com, SunFire, Sun4U,SunSwift, Java,JDK, etSolaris sontdes marquesde fabrique ou des marques déposées,ou marquesde service,de SunMicrosystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marquesde fabriqueou desmarques déposéesde SPARCInternational, Inc.aux Etats-Uniset dans d’autrespays. Lesproduits portantles marquesSPARCsont basés sur une architecturedéveloppée parSun Microsystems,Inc.

L’interfaced’utilisation graphique OPEN LOOK et Sun™ a été développée par Sun Microsystems, Inc.pour sesutilisateurs etlicenciés. Sun reconnaîtles effortsde pionniersde Xeroxpour la rechercheet ledéveloppement duconcept desinterfaces d’utilisationvisuelle ougraphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox surl’interface d’utilisationgraphique Xerox,cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outrese conformentaux licences écrites de Sun.

Achats fédéraux : logiciel commercial- Lesutilisateurs gouvernementauxdoivent respecterles conditionsdu contratde licencestandard. LA DOCUMENTATIONEST FOURNIE “ENL’ETAT” ET TOUTES AUTRESCONDITIONS, DECLARATIONSETGARANTIES EXPRESSES

OU TACITESSONT FORMELLEMENTEXCLUES, DANSLA MESUREAUTORISEE PARLA LOIAPPLICABLE, YCOMPRIS NOTAMMENT TOUTEGARANTIE IMPLICITERELATIVEA LAQUALITE MARCHANDE,A L’APTITUDE A UNE UTILISATION PARTICULIEREOU A L’ABSENCEDE CONTREFAÇON.

Please Recycle

Preface xiii

Before You Read This Book xiii How This Book Is Organized xiv Using UNIX Commands xiv Typographic Conventions xv Shell Prompts xv Related Documentation xvi Accessing Sun Documentation Online xvi Sun Welcomes Your Comments xvi

1. Introduction to WDR 1

Hardware Required for WDR 1

Hardware Required for MSP on Sun Fire 6800/4810/4800/3800 Systems 1

Software Required for WDR 2

Software Required for Sun Fire 15K/12K Systems 2

Software Required for Sun Fire 6800/4810/4800/3800 Systems 2 About Web-Based Enterprise Management (WBEM) 2 Common Information Model (CIM) 3

Platform-Specific and Common MOF Files 4 Operations that WDR Performs 4

iii

Administrator Security Models 5

WDR Security 5

Sun Fire 6800/4810/4800/3800 System Groups 5

Sun Fire 15K and 12K System Groups 6 Solaris WBEM Services 7 CIM Object Manager (CIMOM) 8 WBEM Providers 8 Solaris WBEM Software Development Kit (SDK) 9

2. Using Solaris WBEM Services in WDR 11

Overview of Solaris WBEM Services 11

Layers of Solaris WBEM Services 12

Solaris WBEM Services Application Layer 12

Sun WBEM User Manager and SMC Users Tool 12 Solaris Management Console (SMC) WBEM Log Viewer 13 Managed Object Format (MOF) Compiler 13

The mofcomp Command 13

Compiling a MOF File 15

▼ How to Compile a MOF File 15

The mofcomp Password Security Advisory 16 Solaris WBEM Services Management Layer 16

About the CIM Object Manager 16 Manually Starting and Stopping the CIM Object Manager 17

▼ To Start the CIM Object Manager 17 ▼ To Stop the CIM Object Manager 18

Solaris WBEM Services Provider Layer 18

Solaris Providers 18

WBEM Security Services 19

Authentication 19

iv WDR Developer’s Guide • September 2002

Authorization 19 Replay Protection 19 Digital Signatures 20 Implementing Security 20

WBEM Access Control Lists 20

Using the Sun WBEM User Manager 21

▼ To Start the Sun WBEM User Manager 21 ▼ To Grant Default Access Rights to a User 22 ▼ To Change a User’s Access Rights 22 ▼ To Remove a User’s Access Rights 22 ▼ To Set Access Rights for a Namespace 23 ▼ To Remove Access Rights for a Namespace 23

Using APIs to Set Access Control 23

The Solaris_UserAcl Class 24

▼ To Set Access Control on a User 25

The Solaris_NamespaceAcl Class 26

▼ To Set Access Control on a Namespace 26

Starting Solaris Management Console (SMC) Users Tool 27

▼ To Start SMC Users Tool 27

Solaris WBEM Logging Services 28 Solaris WBEM Services Log Files 29

Solaris WBEM Services Log File Rules 29 Solaris WBEM Services Log File Format 30

Solaris WBEM Log Classes 30

Solaris_LogRecord Class 31 Solaris_LogService Class 31

Using the APIs to Enable Solaris WBEM Logging 32

Writing Data to a Solaris WBEM Log File 32

Contents v

▼ To Create an Instance of Solaris_LogRecord to Write Data 32

Reading Data from a Solaris WBEM Log File 35

▼ To Get an Instance of the Solaris_LogRecord Class and Read Data 35

Setting Solaris WBEM Logging Properties 38

▼ To Set Solaris WBEM Logging Properties 38

Solaris WBEM Log Viewer 39

▼ To Start SMC and Solaris Log Viewer 39

3. Using Process Indications 41

The CIM Event Model 41 How Indications are Generated 42 How Subscriptions Are Created 43 Adding a CIM Listener 44

▼ To Add a CIM Listener 44

Creating an Event Filter 44

▼ To Create an Event Filter 46

Creating an Event Handler 46

▼ To Create a CIM Event Handler 48

Binding an Event Filter to an Event Handler 48

▼ To Bind an Event Filter to an Event Handler 48

4. Classes, Domains, Associations, and Indications in WDR 51

WDR CIM Class Hierarchy Diagram 52 CIM Attachment Point Classes 53

CIM Solaris_WDRAttachmentPoint Class 53

Position in the Class Hierarchy 53

Description 53

Direct Known Subclasses 54

CIM Solaris_WDRAttachmentPoint Class Properties 54

vi WDR Developer’s Guide • September 2002

CIM Solaris_WDRAttachmentPoint Class Methods 55

CIM Solaris_CHSystemBoard Class 58

Position in the Class Hierarchy 58 Description 58 Direct Known Subclasses 58 CIM Solaris_CHSystemBoard Class Properties 59 CIM Solaris_CHSystemBoard Class Methods 59

CIM Solaris_CHCPU Class 61

Position in the Class Hierarchy 62 Description 62 Direct Known Subclasses 62 CIM Solaris_CHCPU Class Properties 62 CIM Solaris_CHCPU Class Methods 62

CIM Solaris_CHMemory Class 63

Position in the Class Hierarchy 63 Description 63 Direct Known Subclasses 63 CIM Solaris_CHMemory Properties 64 CIM Solaris_CHMemory Class Methods 64

CIM Solaris_CHController Class 65

Position in the Class Hierarchy 65 Description 65 Direct Known Subclasses 65 CIM Solaris_CHController Class Properties 65 CIM Solaris_CHController Class Methods 65

CIM Slot Classes 66

CIM Solaris_WDRSlot Class 66

Position in the Class Hierarchy 66

Contents vii

Description 66

Direct Known Subclasses 66

CIM Solaris_WDRSlot Properties 67

CIM Solaris_WDRSlot Methods 67

CIM Solaris_XCSlot Class 69

Position in the Class Hierarchy 69

Description 69

Direct Known Subclasses 70

CIM Solaris_XCSlot Properties 71

CIM Solaris_XCSlot Methods 71

CIM Solaris_SGSlot Class 72

Position in the Class Hierarchy 72

Description 72

Direct Known Subclasses 72

CIM Solaris_SGSlot Properties 73

CIM Solaris_SGSlot Methods 74 CIM Solaris_WDRDomain Classes 74

CIM Solaris_WDRDomain Class 74

Position in the Class Hierarchy 74

Description 74

Direct Known CIM Subclasses 75

CIM Solaris_WDRDomain Class Properties 75

CIM Solaris_XCDomain Class 75

Position in the Class Hierarchy 75

Description 75

Direct Known CIM Subclasses 76

CIM Solaris_XCDomain Class Properties 77

CIM Solaris_SGDomain Class 79

viii WDR Developer’s Guide • September 2002

Position in the Class Hierarchy 79 Description 79 Direct Known CIM Subclasses 79 CIM Solaris_SGDomain Class Properties 80

WDR Schema Associations and Aggregations 81

CIM Solaris_DomainHasAttachmentPoints Aggregation 81

Description 81 CIM Solaris_DomainHasAttachmentPoints Aggregation Properties 82

CIM Solaris_DomainHasSlots Aggregation 82

Description 82 CIM Solaris_DomainHasSlots Aggregation Properties 83

Solaris_SlotHasSystemBoard Association 83

Description 83 CIM Solaris_SlotHasSystemBoard Association Properties 83

Solaris_SystemBoardHasProcessors Aggregation 84

Description 84 CIM Solaris_SystemBoardHasProcessors Aggregation Properties 84

Solaris_SystemBoardHasMemory Aggregation 84

Description 84 CIM Solaris_SystemBoardHasMemory Aggregation Properties 85

Solaris_SystemBoardHasControllers Aggregation 85

Description 85

CIM Solaris_SystemBoardHasControllers Aggregation Properties 86 CIM Process Indication Classes 86 The WDR Indication Class Hierarchy Diagram 87

Solaris_WDRIndication Class 87 Solaris_SGBoardPresenceChange Indication 88

Description 88

Contents ix

Solaris_SGBoardPresenceChange Properties 88

Solaris_SGDomainACLChange Indication 88

Description 88 Solaris_SGDomainACLChange Properties 89

Solaris_SGDomainStateChange Indication 89

Description 89 Solaris_SGDomainStateChange Properties 90

Solaris_SGSlotAssignmentChange Indication 90

Description 90 Solaris_SGSlotAssignmentChange Properties 91

Solaris_SGBoardStateChange Indication 91

Description 91 Solaris_SGBoardStateChange Properties 92

Solaris_SGSlotAvailabilityChange Indication 92

Description 92 Solaris_SGSlotAvailabilityChange Properties 93

Solaris_XCSystemBoardConfigChange Indication 93

Description 93 Solaris_XCSystemBoardConfigChange Properties 94

Solaris_XCEnvironmentalIndication Indication 94

Description 94

Solaris_XCEnvironmentalIndication Properties 94 Solaris_XCComponentRemove Indication 94 Solaris_XCComponentInsert Indication 95 Solaris_XCBoardPowerOn Indication 95 Solaris_XCBoardPowerOff Indication 95 Solaris_XCDomainIndication Indication 95

Description 95

x WDR Developer’s Guide • September 2002

Solaris_XCDomainIndication Properties 96 Solaris_XCDomainConfigChange Indication 96 Solaris_XCDomainUp Indication 96 Solaris_XCDomainDown Indication 96 Solaris_XCDomainStop Indication 97 Solaris_XCDomainStateChange Indication 97

Description 97

Solaris_XCDomainStateChange Properties 97

5. Programming Techniques in WDR 99

Caching System State Information 99 Working with an EventProvider 100

▼ To Subscribe to and Read WDR Indications 100 ▼ To Implement an Event Listener 102 ▼ To Bind an Event Filter to an Event Handler 102

Working with an InstanceProvider 107 Working with an AssociatorProvider 108 Working with a MethodProvider 109

A. MOF Files 111

WDR_Core1.0.mof File 111 WDR_SG1.0.mof File 122 WDR_XC1.0.mof File 130

Index 139

Contents xi

xii WDR Developer’s Guide • September 2002

Preface

This WDR Developer’s Guide is intended for use by systems administrators who want to develop applications that perform DR operations remotely using WBEM, which is an industry standard for Web-based enterprise management.

Developers can write WDR client applications in languages such as Java™, using software development kits (SDKs) such as the Sun WBEM SDK.

Before You Read This Book

This book is intended for the Sun Fire™ 15K, 12K, 6800, 4810, 4800, and 3800 system platform administrator who has a working knowledge of UNIX® systems, particularly those based on the Solaris™ operating environment. If you do not have such knowledge, first read the Solaris user and system administrator books provided with this system, and consider UNIX system administration training.

xiii

How This Book Is Organized

Chapter 1, “Introduction to DR,” provides an overview of WDR, and describes the kind of tasks that WDR enables you to perform.

Chapter 2, “Using Solaris WBEM Services in WDR,” describes the different layers in Solaris WBEM Services, which are included in the Solaris operating environment.

Chapter 3, “Using Process Indications,” describes process indications, which are notifications of system events to which each WDR client can subscribe.

Chapter 4, “Classes, Domains, Associations, Indications in WDR” introduces all the classes, indications (of system events), and associations that WDR provides to the developer. All methods and properties that the developer needs to use are described in this chapter.

Chapter 5, “Programming Techniques in WDR” presents programming techniques that the developer may find useful in creating WDR applications that simplify and automate systems administration on Sun Fire 15K/12K and 6800/4810/4800/3800 systems.

Using UNIX Commands

This document does not contain information on basic UNIX®commands and procedures such as shutting down the system, booting the system, and configuring devices.

See one or more of the following for this information:

■ Solaris Handbook for Sun Peripherals

■ Online documentation for the Solaris™ operating environment

■ Other software documentation that you received with your system

xiv WDR Developer’s Guide • September 2002

Typographic Conventions

TABLEP-1

Typeface Meaning Examples

AaBbCc123 The names of commands, files,

and directories; on-screen computer output

AaBbCc123

AaBbCc123 Book titles, new words or terms,

What you type, when contrasted with on-screen computer output

words to be emphasized

Edit your .login file. Use ls -a to list all files.

% You have mail. % su

Password:

Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this.

Command-line variable; replace with a real name or value

To delete a file, type rm filename.

Shell Prompts

TABLEP-2

Shell Prompt

C shell machine_name% C shell superuser machine_name# Bourne shell and Korn shell $ Bourne shell and Korn shell superuser #

Preface xv

Introduction to WDR

WDR (WBEM dynamic reconfiguration) provides an application program interface (API) that software applications can use to perform dynamic reconfiguration (DR) operations remotely on the following systems:

■ Sun Fire 15K

■ Sun Fire 12K

■ Sun Fire 6800

■ Sun Fire 4810

■ Sun Fire 4800

■ Sun Fire 3800

Software developers and systems administrators can use the WDR API to create custom applications that remotely perform crucial system management functions such as load balancing. WDR provides an alternative to the current, conventional method of performing DR operations, which are achieved either on the Sun Fire System Controller (SC) or on the Solaris domain (using the cfgadm system library).

Hardware Required for WDR

On Sun Fire 6800/4810/4800/3800 systems, WDR runs on an external host that is referred to as the Midframe Service Processor (MSP). On Sun Fire 15K and 12K systems, WDR runs on the System Controller (SC).

Hardware Required for MSP on Sun Fire 6800/4810/4800/3800 Systems

The minimum hardware requirements for an MSP are:

■ Sun4U™ architecture

■ 8 GB disk space

■ 128 MB RAM

■ CD-ROM drive

■ SunSwift™ card or, ideally, a QuadFast Ethernet card

Software Required for WDR

WDR can be used on Sun Fire 6800/4810/4800/3800 and Sun Fire 15K/12K system domains that run the Solaris 8 2/02 and Solaris 9 software. WDR is not bundled with other software, such as the Solaris operating environment

Software Required for Sun Fire 15K/12K Systems

To enable WDR, both the WDR software and Solaris WBEM Services software must be installed on the SC. Further, the System Management Services (SMS) version 1.2 software must be installed on the SC.

Software Required for Sun Fire 6800/4810/4800/3800 Systems

To enable WDR, both the WDR software and Solaris WBEM Services software must be installed on the MSP.

About Web-Based Enterprise Management (WBEM)

The WDR interface is based on the Web-based Enterprise Management (WBEM) industry standard, which enables Web-based management of systems, networks, and devices on a variety of platforms. WBEM was developed by members of the Distributed Management Task Force (DMTF), who represent many industry leaders.

WBEM is comprised of three principal components:

2 WDR Developer’s Guide • September 2002

■ A method of modeling managed objects. WBEM uses the Common Information

Model (CIM) to create classes that represent managed objects. These classes have properties that represent the attributes and states of managed objects; and methods that represent operations that can be performed on managed objects.

■ A means of encoding CIM information so that it can be sent over the wire. WBEM

uses Extensible Markup Language (XML), a powerful and extensible subset of SGML, to encode CIM classes.

■ A way of encapsulating XML operations for transmission over the wire. WBEM

uses XML/HTTP or RMI for sending operations that get information from, set the properties of, and perform operations on, managed objects

To summarize: in WBEM, managed objects are represented as CIM classes, properties, and methods; CIM operations are represented as either XML/HTTP or RMI messages; and those messages are sent over the wire.

A comprehensive description of the WBEM standard is beyond the scope of this document. However, complete information about WBEM is available from a variety of sources, including the DMTF Web site at www.dmtf.org.

Common Information Model (CIM)

WDR is a Sun Fire system-specific extension of the CIM schema that is used to represent:

■ Resources on Sun Fire systems that can be managed using DR,

■ Events that relate to DR or affect the state of the WDR model,

■ DR platform resources such as attachment points, which are represented by the

AttachmentPoint class and its subclasses,

■ The containers of DR platform resources, such as domains and slots,

■ Events that affect the existence and/or state of objects in the WDR schema,

■ Associations between objects in the WDR schema, and

■ DR operations themselves.

The architecture of the Sun Fire 6800/4810/4800/3800 systems differs significantly from that of the Sun Fire 15K and 12K systems. WDR includes CIM schema that reflect the architectures of all the different Sun Fire systems on which it is used.

Some of the objects in the CIM schema are common to all Sun Fire systems; other objects are used only on the Sun Fire 6800/4810/4800/3800 systems; while other objects are used only on the Sun Fire 15K and 12K systems.

The commonalities between the system architectures are captured in platformindependent superclasses; the differences are captured in platform-specific subclasses of those platform-independent superclasses.

Chapter 1 Introduction to WDR 3

Platform-Specific and Common MOF Files

The CIM schema used by WDR is expressed in three Managed Object Format (MOF) files, which are ASCII text files that define all the objects that represent managed resources on Sun Fire systems.

■ WDR_core1.0.mof defines the common elements of Sun Fire 15K/12K, and

6800/4810/4800/3800 systems.

■ WDR_XC1.0.mof defines elements specific to Sun Fire 15K/12K systems.

■ WDR_SG1.0.mof defines elements specific to Sun Fire 6800/4810/4800/3800

systems.

In addition to providing a schema, the MOF file also provides the software developer or systems administrator with a formal definition of the objects that comprise the WDR CIM schema.

Note – For a formal definition of CIM, see Common Information Model, Implementing

the Object Model for Enterprise Management, Winston Bumpus et al., Wiley Computer

Operations that WDR Performs

WDR can perform the following dynamic reconfiguration operations remotely:

■ Add a system board (a CPU/memory board) to a domain that is running the

Solaris software. DR first connects the board electrically to the system, putting it into a connected state. DR then configures the system board so that it is fully available to all applications running in the domain; the board is put into the configured state.

■ Move a system board from one domain to another domain, via an unconfigure

operation followed by a configure operation.

■ Remove a system board from a domain and make it available for use by other

domains.

■ List all attachment points that are currently available to domains on the system.

■ Display information about the current state of a s pecified system board, such as

its power status, availability, and domain assignment.

■ Retrieve the memory configuration of a configured system board.

■ Retrieve information about the impact on memory, such as memory drain

information, that is associated with detaching a configured system board.

4 WDR Developer’s Guide • September 2002

The functionality of WDR is the same as the underlying functionality of DR itself; WDR adds no additional operations to DR. However, WDR does enhance DR by providing information about domains and slots; associations between classes; and event notification.

WDR is designed to perform DR operations efficiently, without any noticeable degradation of performance.

Administrator Security Models

WDR enforces the administrator security models on Sun Fire 15K/12K and 6800/4810/4800/3800 systems.

For complete information about implementing security at the Sun Fire 6800/4810/4800/3800 system level, see the Sun Fire 6800/4810/4800/3800 Systems Platform Administration Manual (part number 805-7373).

For complete information about implementing security at the Sun Fire 15K/12K system level, see the System Management Services (SMS) 1.2 Administrator Guide for Sun Fire 15K/12K Systems (part number 816-5259).

In addition, security that is available through Solaris WBEM Services is described in Chapter 2 “Using Solaris WBEM Services in WDR.”

WDR Security

The /etc/group file shows the groups to which the currently logged in user is subscribed.

Sun Fire 6800/4810/4800/3800 System Groups

The /etc/group file, which shows group membership on a Sun Fire 6800/4810/4800/3800 system, can be edited manually.

Chapter 1 Introduction to WDR 5

The following table shows all the operations that users can perform based on their group membership:

TABLE1-1 Permitted Tasks Based on Group - Sun Fire 6800/4810/4800/3800

Group Tasks that the User Can Perform

None (all users) Enumerate domains and slots

spltadm Assign and unassign boards spltop No special privileges sdxadm Where x represent a domain, can:

• Enumerate attachment points in domain x.

• Enumerate all attachment points if the user is in the sdxadm group in all domains.

• Change an attachment point state, assign, unassign, power-on, and power-off a board that is in domain x’s available component list.

sdxop Where x represent a domain, can:

• Enumerate attachment points in domain x.

• Enumerate all attachment points if the user is in the sdxop group in all domains.

Sun Fire 15K and 12K System Groups

To modify the /etc/group file, which shows group membership on a Sun Fire15K or 12K system, you run the /opt/SUNWSMS/bin/smsconfig script with arguments. See the System Management Services (SMS) 1.2 Administrator Guide for Sun Fire 15K/12K Systems for more information.

6 WDR Developer’s Guide • September 2002

The following table shows all the operations that users can perform based on their group membership:

TABLE1-2 Permitted Tasks Based on Group - Sun Fire 15K and 12K

Group Tasks that the User Can Perform

platadmn Assign, unassign, power-on, and power-off boards platoper No special privileges dmnxadm Where x represent a domain, can:

• Enumerate attachment points in domain x.

• Enumerate all attachment points if the user is in the dmnxadm group in all domains.

• Change an attachment point state, assign, unassign, power-on, and power-off a board that is in domain x’s available component list.

dmnxrcfg Where x represent a domain, can:

• Enumerate attachment points in domain x.

• Enumerate all attachment points if the user is in the dmnxrcfg group in all domains.

• Change an attachment point state, assign, unassign, power-on, and power-off a board that is in domain x’s available component list.

Solaris WBEM Services

WDR is an extension of the Solaris WBEM Services software, which is included in the Solaris 8 2/02 and Solaris 9 operating environments. Solaris WBEM Services software provides secure access and manipulation of management data, and enables software developers to create client applications that manage system resources in the Solaris environment.

Solaris WBEM Services software consists of components that function at three levels:

■ The Application Layer, where WBEM clients process and display data from

managed resources. Application Layer services includes the WBEM Workshop; the WBEM User Manager, which allows administrators to add and remove authorized WBEM users and set their access privileges; and the MOF compiler.

■ The Management Layer, where the CIM API (which forms the boundary between

the Application and Management Layers) enables the administrator to perform operations such as viewing and creating classes and instances of managed resources from the CIMOM. The CIMOM, the CIM Repository, and the Provider interface all reside at the Management Layer.

Chapter 1 Introduction to WDR 7

■ The Provider Layer. At this layer resides the Solaris Provider, which provides the

CIMOM instances of managed resources in the Solaris operating environment, and gets and sets information about managed resources. The Solaris Provider forms the interface between CIMOM and managed system resources.

Solaris WBEM Services components interact with the Solaris software and with the system hardware. For more information about the Solaris WBEM Services software, visit the Solaris WBEM Web site at www.sun.com/software/solaris/wbem.

Developers of load balancing and other system management applications can use Solaris WBEM Services software to obtain information about the current level of resource utilization on a Sun Fire system domain. WDR itself does not provide system performance data.

CIM Object Manager (CIMOM)

The CIMOM manages CIM objects on a WBEM system. The CIMOM transfers information between WBEM clients, the CIMOM Repository, and to managed resources via providers. The CIMOM accepts connections from management applications using the RMI protocol, and provides the following services to connected clients:

■ Management services. The CIMOM checks the semantics and syntax of CIM data,

and distributes data between applications, the CIM Repository, and managed resources.

■ Security services that enable administrators to control user access to CIM

information.

■ Logging services that consist of classes that developers can use to create

applications that dynamically record CIMOM event data to, and retrieve it from, alogrecord.

■ XML services that convert XML data into CIM classes, which enables XML-based

WBEM clients to communicate with the CIMOM.

WBEM Providers

WDR contains several provider classes, which are expressed in the MOF files. WBEM providers are classes that act as intermediaries between the CIMOM and managed objects on a system. WBEM providers get information from, set information on, and may perform operations on, managed devices. WBEM providers forward retrieved information to the CIMOM, which is a part of the Solaris WBEM Services software, for delivery to the requesting clients.

8 WDR Developer’s Guide • September 2002

When the CIMOM receives a request for information that is not available in the CIMOM Repository, it forwards the request to a provider. The provider receives requests for information, and returns the information, using APIs.

Solaris WBEM Software Development Kit (SDK)

Developers of WDR applications can use the Solaris WBEM SDK. However, there is no requirement to use the Solaris WBEM SDK because WDR uses a standard set of protocols. For more information about the Solaris WBEM SDK visit the Sun Developer Connection at:

www.sun.com/solaris/wbem

Chapter 1 Introduction to WDR 9

10 WDR Developer’s Guide • September 2002

CHAPTER

Using Solaris WBEM Services in WDR

Overview of Solaris WBEM Services

Solaris WBEM Services provide the WDR application developer with a variety of WBEM services on domains that are running either the Solaris 8 2/02 or Solaris 9 operating environment. Solaris WBEM Services, which are included with the Solaris software, make it easier for developers to create applications that use WBEM to manage systems running Solaris software.

This developer’s guide provides information about only those Solaris WBEM Services with which a WDR application developer needs to become familiar. Complete information about Solaris WBEM Services is available at the following Web site:

http://www.sun.com/solaris/wbem

Solaris WBEM Services provide secure access to information about managed resources, which in turn enable applications that use WDR to get information about, and manage, system resources. A built-in Solaris Provider allows access to information about managed resources such as hardware and software state information, performance metrics, and other data that are needed by management applications to perform load balancing and to respond to device failovers.

Solaris WBEM Services uses the Common Information Model (CIM) to create a schema that represents managed objects in a system running Solaris software. CIM objects are specified in a Managed Object Format (MOF) file, which is provided with WDR and compiled when WDR is installed.

Layers of Solaris WBEM Services

Solaris WBEM Services is a software package that resides at three layers. At each layer reside software components that are important to WDR application developers:

■ Application Layer

■ Management Layer

■ Provider Layer

Solaris WBEM Services Application Layer

The following Solaris WBEM Services Application Layer software programs, which are especially useful to WDR application developers, are described in detail in this chapter:

■ Solaris Management Console (SMC) WBEM Log Viewer on page 13

■ Managed Object Format (MOF) Compiler on page 13

■ Using the Sun WBEM User Manager on page 21

■ Starting Solaris Management Console (SMC) Users Tool on page 27

Sun WBEM User Manager and SMC Users Tool

The Sun WBEM User Manager and SMC Users Tool applications enable systems administrators to add and remove authorized users and to set their access privileges to managed resources.

There are two separate mechanisms for administering security with domains running the Solaris software: WBEM access control list (ACL) and Solaris role-based access control (RBAC).

You use the WBEM User Manager to add users to existing ACLs and to grant them either read or read-write access privileges.

You use the Users Tool in the Solaris Management Console (SMC) to add users, and to grant user roles and privileges, using RBAC.

See the section “WBEM Security Services” on page 19 for more information about administering WBEM security, including details of ACL- and RBAC-based system security.

12 WDR Developer’s Guide • September 2002

Solaris Management Console (SMC) WBEM Log Viewer

The SMC WBEM Log Viewer displays log files that include information such as the names of users who issued logged commands, and the client computers on which the logged commands were issued.

Solaris WBEM Services includes APIs to enable logging of system events. See the section “Solaris WBEM Logging Services” on page 28 (and subsequent sections) for complete information about log files; rules associated with log files; log file formats; classes that developers can use to record system events; and using APIs to enable logging services.

Managed Object Format (MOF) Compiler

The MOF Compiler is used to compile MOF files, which are ASCII text files that specify objects in a CIM schema that represent managed objects in a system running Solaris software.

WDR includes three MOF files that define schema comprised of objects that represent managed resources. One MOF file is used for all Sun Fire systems; another is used only on Sun Fire 15K and 12K systems; and the third is used for Sun Fire 6800, 4810, 4800, or 3800 systems.

The MOF compiler reads statements in a MOF file that define classes and instances, and then adds them to the CIM Object Manager Repository, which is a central storage area for information about management data.

The mofcomp Command

To start the MOF compiler and compile a MOF file, use the mofcomp command:

/usr/sadm/bin/mofcomp [-help] [-v] [-sc] [-si] [-sq] [-version] [-c cimom_hostname] [-u username] [-p password] filename

Chapter 2 Using Solaris WBEM Services in WDR 13

Where:

TABLE2-1 Arguments to the mofcomp Command

Argument Description

-help

-v

-sc

-si

-sq

-version

-c cimom_hostname

Lists the arguments to the mofcomp command. Runs the compiler in verbose mode, which displays all

compiler messages. Runs the compiler with the “set class” option, which updates

a class if it already exists and contains no instances, and returns an error if the class does not already exist. If you do not specify the -sc option, the compiler adds a CIM class to the connected namespace, and returns an error if the class already exists.

Runs the compiler with the “set instance” option, which updates an instance if it already exists, and returns an error message if it does not. If you do not specify the -si option, the compiler adds a CIM instance to the connected namespace, and returns an error if the instance already exists.

Runs the compiler with the “set qualifier types” option, which updates a qualifier if it already exists, and returns an error message if it does not. If you do not specify the -sq option, the compiler adds a CIM qualifier type to the connected namespace, and returns an error if the qualifier type already exists.

Displays the version number of the MOF compiler. Specifies a system that is running the CIM Object Manager.

14 WDR Developer’s Guide • September 2002

TABLE2-1 Arguments to the mofcomp Command

Argument Description

-u username

-p password

filename

Specifies the user name for connecting to the CIM Object Manager.Use the -u username option for compilations that require privileged access to the CIM Object Manager.

If you specify both -p and -u, you must type the password on the command line, which can pose a security risk. A more secure way to specify a password is to specify -u but not -p, so that the compiler will prompt you for the password. See the section “The mofcomp Password Security Advisory” on page 16 below.

Specifies a password for connecting to the CIM Object Manager. Use this option for compilations that require privileged access to the CIM Object Manager.

The name of the MOF file to be compiled.

Compiling a MOF File

You can compile a MOF file whether its filename contains or does not contain a.mof extension. The MOF files that describe the CIM and Solaris Schemas are located in /usr/sadm/mof.

▼ How to Compile a MOF File

1. To run the MOF Compiler with no options, type the following:

# mofcomp filename

For example,

# mofcomp /usr/sadm/mof/Solaris_Application1.0.mof

The MOF file named Solaris_Application1.0.mof is compiled into the CIM Object Manager Repository.

Chapter 2 Using Solaris WBEM Services in WDR 15

The mofcomp Password Security Advisory

If you run the mofcomp command with the -p option, or with the -p and -u options, and you include a password on the command line, another user can subsequently run the ps command or the history command to display your password. The system does not display a security warning.

Note – If you run a command that requires you to provide your password on the

command line, immediately change your password after running the command. This will prevent another user from displaying your current password.

The following examples show unsafe (insecure) usage:

% mofcomp -p Log8Rif % mofcomp -up molly Log8Rif

If you use the mofcomp command in either of the preceding ways, make sure to change your password immediately after running the command.

Solaris WBEM Services Management Layer

The Solaris WBEM Services Management Layer software program that is useful to WDR application developers is the Common Information Model (CIM) Object Manager.

About the CIM Object Manager

Solaris WBEM Services includes the CIM Object Manager, which manages objects in a WBEM-enabled system. Each CIM object represents a managed system object, such as a CPU, an I/O board, or an attachment point.

The CIM Object Manager first accepts connections to management applications using either the RMI or XML/HTTP protocol; sets up a connection to the CIM Object Repository; and then awaits requests from client applications for services, which include:

16 WDR Developer’s Guide • September 2002

■ Management services that check the semantics and syntax of CIM data operations

to ensure that they comply with the latest CIM specification; and that distribute management data between applications (such as WDR applications), the CIM Repository, and managed resources.

■ Security services that authenticate user login requests and control access to

system resources.

■ Logging services that record system events

After WBEM clients are connected to a WBEM-enabled system, they can request WBEM operations such as creating, viewing, and deleting CIM classes and instances; retrieving the values of properties; and enumerating instances of classes, or classes within a specified class hierarchy.

Manually Starting and Stopping the CIM Object Manager

Normally, the CIM Object Manager is started automatically during installation and whenever you boot a domain by a utility called /etc/init.d/init.wbem.In addition to the CIM Object Manager, the command starts the Solaris Management Console (SMC); both run as a single process.

You should not need to start and stop the CIM Object Manager manually, but you can do so if the need should arise. The init.wbem utility has the following syntax:

/etc/init.d/init.wbem start|stop|status

The start option starts the CIM Object Manager on the domain from which it is invoked. The stop option stops the CIM Object Manager on the domain. The status option gets the status of the CIM Object Manager on the domain.

▼ To Start the CIM Object Manager

1. Enter the following command at the system prompt to become a root user:

%su

2. At the root system prompt (#) type the root password for the domain when prompted to do so.

3. Start the CIM Object Manager by typing the following command:

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

Chapter 2 Using Solaris WBEM Services in WDR 17

▼ To Stop the CIM Object Manager

1. Enter the following command at the system prompt to become a root user:

%su

2. When prompted, enter the root password for the domain at the root system prompt (#).

3. Stop the CIM Object Manager by entering the following command:

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

Solaris WBEM Services Provider Layer

The Solaris WBEM Services Provider Layer includes the Solaris Provider software program, which is especially useful to WDR application developers.

Solaris Providers

A Solaris Provider is a class that communicates with managed objects. Providers provide the CIM Object Manager with instances of managed resources on systems running the Solaris operating environment, and retrieve and set information on managed devices.

When a WDR application attempts to access CIM data about managed resources, WBEM first validates the user login information on the domain. Users are granted Read Only access by default. See the section “WBEM Security Services” on page 19 for more information about WBEM system security.

The CIM Object Manager uses object provider APIs to communicate with providers. After an application requests dynamic data from the CIM Object Manager, the CIM Object Manager responds via the provider APIs to pass the requested information to the provider.

Providers can be either native providers, which are machine-specific, or they can be written using the portable, machine-independent Java Native Interface (JNI), which is part of the Java™ Development Kit (JDK™).

18 WDR Developer’s Guide • September 2002

WBEM Security Services

There are three principal security features that protect CIM objects from intrusion on a WBEM-enabled system:

■ Authentication

■ Authorization

■ Replay protection

Authentication

Authentication is the process of verifying the identity of a user, device, or other entity in a Sun Fire system. Authentication is frequently used to give valid users access to system resources; and to deny access to users who cannot be authenticated.

When a user logs in and enters a user name and password, the client uses the password to generate an encrypted digest that the server verifies. When the user is authenticated, the CIM Object Manager grants a MAC token and establishes a client session. All subsequent operations occur within that secure client session, and contain a MAC token that uses the session key that was negotiated during the authentication process. (A MAC is a token parameter added to a remote call which contains security information used to authenticate that message.)

Authorization

Authorization is the process of granting to a user, program, or process the right to access system resources. Authorization occurs after authentication.

After the CIM Object Manager has authenticated the user’s identity, that identity can be used to verify whether the user should be allowed to execute an application or any of its related tasks. The CIM Object Manager supports capability-based authorization, which allows a privileged user to assign read and write access to other users. Such authorizations are added to existing Solaris user accounts.

Replay Protection

Replay protection prevents an unauthorized client picking up and sending another client’s message to the server by validating a session key.

Chapter 2 Using Solaris WBEM Services in WDR 19

A client cannot copy another client’s last message that was sent to the CIM Object Manager. The CIM Object Manager uses a MAC for each message, based on the session key that was negotiated during authentication, to guarantee that all communications in the client-server session is indeed with the same client that initiated the session and participated in client-server authentication.

The MAC is used to confirm that each message actually came from the client that was originally authenticated for the session, and that the message was not being replayed by another client. This type of mechanism is used in WBEM to verify RMI messages. The session key that was negotiated during the user authentication exchange is used to encrypt the security information in the message’s MAC token.

Digital Signatures

WBEM Security Services does not perform digital signing of messages.

Implementing Security

You use WBEM Access Control Lists to administer security within the Solaris operating environment.

WBEM Access Control Lists

Access Control List-based security is implemented using classes that are defined in the Solaris_Acl1.0.mof file. Access Control List-based security, which is specific to Solaris WBEM Services, provides a default authorization scheme for Solaris WBEM Services, and applies to all CIM operations. Instances of these classes determine the default authorizations that are assigned to WBEM users and/or namespaces.

To add users to existing Access Control Lists and assign to them either read or readwrite access privileges, use the Sun WBEM User Manager, which is described in the section Sun WBEM User Manager. The Sun WBEM User Manager is located at /usr/sadm/bin/wbemadmin.

For more information, see the section “Using the Sun WBEM User Manager” on page 21.

20 WDR Developer’s Guide • September 2002

Using the Sun WBEM User Manager

The Sun WBEM User Manager allows privileged users to add and delete authorized users and to set their access privileges to CIM objects on a WBEM-enabled system. Each user must have a Solaris user account.

You can use the Sun WBEM User Manager to set access privileges on individual namespaces or on a user/namespace combination. When you add a user and select a namespace, the user has default read access to the CIM objects within the specified namespace.

You can restrict access by all users to a namespace, and then grant individual users read, read-write, or write access to that namespace.

You cannot set access rights to individual managed objects. However, you can set access rights for all managed objects within a namespace and on a per-user basis.

If you log in as root, you can use the WBEM User Manager to set the following types of access to CIM objects:

■ Read Only — Allows read-only access to objects within the CIM schema. Users

with Read Only privileges can retrieve instances and classes, but cannot create, delete, nor modify CIM objects. The default user access.

■ Read/Write — Allows full read, write, and delete access to all CIM classes and

instances.

■ Write — Allows write and delete, but not read access to all CIM classes and

instances.

■ None — Allows no access to CIM classes and instances.

▼ To Start the Sun WBEM User Manager

1. Enter the following command on the command line as root:

# /usr/sadm/bin/wbemadmin

The Sun WBEM User Manager is loaded, and the Login dialog is displayed. To use context-sensitive help, click on fields in the dialog to display the Context Help panel.

2. In the Login dialog, enter the user name in the User Name field.

You must have Read access to the root\security namespace to log in. By default, Solaris users have guest privileges, which grant them Read access to the default namespaces. Users with Read access can view, but not change, user privileges.

To grant access rights to users, you must log in either as root or as a user with Write access to the root\security namespace.

Chapter 2 Using Solaris WBEM Services in WDR 21

3. In the Login dialog, enter the password for the user account in the Password field.

4. Click OK.

The User Manager dialog is displayed. It contains a list of users and their access rights to WBEM objects within the namespaces on the current domain.

▼ To Grant Default Access Rights to a User

1. Start the Sun WBEM User Manager.

2. Click Add in the Users Access portion of the User Manager dialog.

A dialog is displayed that lists all available namespaces on the domain.

3. Type the Solaris user’s account name in the User Name field.

4. Select a namespace from the list of available namespaces.

5. Click OK.

The user name is added to the list of users shown in the User Manager dialog.

6. Click OK to save the changes and close the User Manager dialog. Or, click Apply to save the changes and leave the dialog open.

The user now has Read Only access to CIM objects in the selected namespaces.

▼ To Change a User’s Access Rights

1. Start the Sun WBEM User Manager.

2. Select the user from the list whose access rights you want to change.

3. To grant Read Only access to the user, click the Read check box. To grant the user Write access, click the Write check box.

4. Click OK to save the changes and close the User Manager dialog. Or, click Apply to save the changes and leave the dialog open.

▼ To Remove a User’s Access Rights

1. Start the Sun WBEM User Manager.

2. In the Users Access portion of the User Manager dialog, select the user from the list whose access rights you want to remove.

22 WDR Developer’s Guide • September 2002

3. Click Delete to revoke the user’s access rights to the namespace.

A confirmation dialog prompts you to confirm that you want to revoke the user’s access rights. Click OK to proceed.

4. Click OK to save the changes and close the User Manager dialog. Or, click Apply to save the changes and leave the dialog open.

▼ To Set Access Rights for a Namespace

1. Start the Sun WBEM User Manager.

2. In the Namespace Access portion of the User Manager dialog, click Add.

A dialog is displayed that lists all the namespaces that are available in the domain.

3. Select the namespace for which you want to set access rights.

By default users have Read Only access to namespaces, and the Read check box is checked. To allow Write access, click the Write check box. To allow Read/Write access click both the Read and Write check boxes. To allow no access to the namespace, make sure both the Read and Write check boxes are not checked.

4. Click OK to save the changes and close the User Manager dialog. Or, click Apply to save the changes and leave the dialog open.

▼ To Remove Access Rights for a Namespace

1. Start the Sun WBEM User Manager.

2. In the Namespace Access portion of the User Manager dialog, select the namespace whose access rights you want to remove and click Delete.

This removes access control from the namespace, and removes the namespace from the list of namespaces displayed in the User Manager dialog box.

3. Click OK to save the changes and close the User Manager dialog. Or, click Apply to save the changes and leave the dialog open.

Using APIs to Set Access Control

You can use the Sun WBEM SDK APIs to set access control on a namespace or on a per-user basis. The following security classes are stored in the root\security namespace:

Chapter 2 Using Solaris WBEM Services in WDR 23

■ Solaris_Acl - Base class for Solaris access control lists (ACLs). This class

defines the string property capability and sets its default value to “r” (read only).

■ Solaris_UserAcl - Represents the access control that a user has to the CIM

objects within the specified namespace.

■ Solaris_NamespaceAcl - Represents the access control on a namespace.

You can set access control on individual users to the CIM objects within a namespace by creating an instance of the Solaris_UserACL class and then using the APIs to change the access rights for that instance. Similarly, you can set access control on namespaces by creating an instance of the Solaris_NameSpaceACL class and then using APIs, such as the setInstance method, to set the access rights for that instance.

An effective way to combine the use of these two classes is to first use the Solaris_NameSpaceACL class to restrict access to all users to the objects in a namespace. Then use the Solaris_UserACL class to grant selected users access to the namespace.

Note – Access control lists (ACLs) are governed by a standard being developed by

the DMTF. Although the Solaris ACL schema are currently CIM-compliant, they will need to change when the DMTF finalizes the ACL standard. Programs you write using the Solaris ACL schema classes are subject to that risk.

The Solaris_UserAcl Class

The Solaris_UserAcl class extends the Solaris_Acl base class, from which it inherits the string property capability that has a default value of “r” (Read Only).

You can set access privileges by setting the capability property of the Solaris_UserAcl class to one of the following values:

TABLE2-2 Settings of the capability Property

Access Right Description

r Read Only rw Read/Write w Write none Only

24 WDR Developer’s Guide • September 2002

In addition to the capability property, the Solaris_UserAcl class defines the following two key properties. Only one instance of the namespace-username ACL pair can exist in a namespace.

TABLE2-3 Key Properties of the Solaris_UserAcl class

Property Data Type Purpose

nspace string Identifies the namespace to which this ACL applies. username string Identifies the user to which this ACL applies.

▼ To Set Access Control on a User

1. Create an instance of the Solaris_UserAcl class, using code such as the following:

... /* Create a namespace object initialized with root\security

(name of namespace) on the local host. */ CIMNameSpace cns = new CIMNameSpace("", "root\security"); // Connect to the root\security namespace as root. cc = new CIMClient(cns, "root", "root_password"); // Get the Solaris_UserAcl class cimclass = cc.getClass(new CIMObjectPath("Solaris_UserAcl"); // Create a new instance of the Solaris_UserAcl class ci = cimclass.newInstance(); ...

2. Set the capability property to the desired access rights, using code such as the following:

... /* Change the access rights (capability) to read/write for

user Guest on objects in the root\molly namespace.*/ ci.setProperty("capability", new CIMValue(new String("rw")); ci.setProperty("nspace", new CIMValue(new String("root\

molly")); ci.setProperty("username", new CIMValue(new String("guest")); ...

Chapter 2 Using Solaris WBEM Services in WDR 25

3. Update the newly created instance using code such as the following:

... // Pass the updated instance to the CIM Object Manager cc.setInstance(new CIMObjectPath(), ci); ...

The Solaris_NamespaceAcl Class

The Solaris_NamespaceAcl class extends the Solaris_Acl base class, from which it inherits the string property capability whose default value is ”r” (Read Only for GUEST and all users). The Solaris_NamespaceAcl class defines the following key property:

Property Data Type Purpose

nspace string Identifies the namespace to which this access control list

(ACL) applies. Only one instance of the namespace ACL can exist in a namespace.

▼ To Set Access Control on a Namespace

1. Create an instance of the Solaris_namespaceACL class, using code such as the following:

... /* Create a namespace object initialized with root\security

CIMObjectPath("Solaris_namespaceAcl"); // Create a new instance of the Solaris_namespaceAcl class ci = cimclass.newInstance(); ...

26 WDR Developer’s Guide • September 2002

2. Set the capability property to grant the desired access rights, using code such as the following:

... /* Create a namespace object initialized with root\security

CIMObjectPath("Solaris_namespaceAcl"); // Create a new instance of the Solaris_namespaceAcl class ci = cimclass.newInstance(); ...

3. Update the newly created instance, using code such as the following:

// Pass the updated instance to the CIM Object Manager cc.setInstance(new CIMObjectPath(), ci);

Starting Solaris Management Console (SMC) Users Tool

The SMC Users tool lets you add users to existing roles and grant RBAC rights to existing users. RBAC rights are managed in the Rights portion of the SMC Users tool.

▼ To Start SMC Users Tool

1. Enter the following command to change to the location of the SMC invocation command:

# cd /usr/sbin

2. Type the following command to start the SMC:

# smc

Chapter 2 Using Solaris WBEM Services in WDR 27

3. After the application is loaded and the user interface is displayed, double-click “This Computer” (or single-click the expand/compress icon next to “This Computer”) in the left-hand Navigation panel to expand the tree beneath “This Computer.”

4. Double-click “System Configuration” (or single-click the expand/compress icon next to “System Configuration”) in the left-hand Navigation panel to expand the tree beneath “System Configuration.” The Users icon is displayed.

5. Click the Users icon to start the Users Tool.

Note – For more information about using the Solaris Management Console, see the

smc(1m) man page.

Solaris WBEM Logging Services

WBEM Logging services enable systems administrators to monitor system events and to determine how they occurred.

The logging service records all those actions that the service provider has been programmed to return, and that are completed by Solaris WBEM Services components. In addition, informational and error content can be recorded to a log.

For example, if a user disables a serial port, this information can be logged automatically by a serial port provider. Or, if a system error or other failure occurs, the administrator can check the log record to trace the cause of the occurrence.

All components, applications, and providers start logging automatically, in response to events. For example, the CIM Object Manager automatically logs events after it is installed and started.

You can set up logging for applications and providers that you develop for the WBEM environment. For information, see the section “Using the APIs to Enable Solaris WBEM Logging” on page 32.

You can view log data in the Solaris Management Console (SMC) Log Viewer to debug the logging functionality that you have set up. For more information about viewing log files, see the section “Solaris WBEM Log Viewer” on page 39, and the smc(1m) man page.

28 WDR Developer’s Guide • September 2002

Solaris WBEM Services Log Files

When you set up an application or a provider to log events, its events are recorded in log files. All log records are stored in the path: /var/sadm/wbem/log. Log files use the following naming convention:

wbem_log.#

where # is a number appended to indicate the version of the log file. A log file appended with a “.1” is the most recently-saved version, such as

wbem_log.1. A log file appended with a “.2” is the next oldest version, and so on. All versions of the log file co-exist as an archive in /var/sadm/wbem/log.

Log files are renamed with a .1 file extension, and saved when one of the following two conditions are met:

■ The current file reaches the file size limit specified by the

Solaris_LogServiceProperties class. Default values are set in the wbemService.properties file.

For information about how the properties of the Solaris_LogServiceProperties class control how a log file is used, see the section “Solaris WBEM Services Log File Rules” on page 29.

■ The clearLog() method of the Solaris_LogService class is invoked on the

current log file. For information about the Solaris_LogService class and its methods, see the

section “Solaris_LogService Class” on page 31.

Solaris WBEM Services Log File Rules

The Solaris_LogServiceProperties class is defined in Solaris_Core1.0.mof. The Solaris_LogServiceProperties class has properties that control the following attributes of a log file:

■ The directory where the log file is written

■ The name of the log file

■ The size allowed for a log file before it is renamed with a .1 file extension and

saved.

■ The number of log files you can have in the archive

■ The ability to write log data to SysLog, the default logging system of the Solaris

operating environment

Chapter 2 Using Solaris WBEM Services in WDR 29

To specify any of these attributes for an application that writes data to a log file, create a new instance of the Solaris_LogServiceProperties class and set the values of its associated properties. See the section “Setting Solaris WBEM Logging Properties” on page 38 for detailed information about how to set property values of the new instance.

Solaris WBEM Services Log File Format

The logging service provides three categories of log records: application, system, and security. Log records may be informational, or may record data derived from errors or warnings. A standard set of fields is defined for the data that can be presented in logs; however, logs do not necessarily use all fields. For example, an informational log may provide a brief message describing an event. An error log may provide a more detailed message.

Some log data fields are required to identify data in the CIM Repository. These fields are properties flagged with a read-only key qualifier in the Solaris_LogRecord class. You cannot set the values of these fields. You can, however, set the values of any of the following fields in your log files:

■ Category — The type of log record

■ Severity — The severity of conditions that caused data to be written to a log

file

■ AppName — The name of the application from which the data was obtained

■ UserName — The name of the individual who was using the application when

log data was generated

■ ClientMachineName — The name of the computer on which an incident

occurred that generated log data.

■ ServerMachineName —- The name of the server on which an incident occurred

that generated log data

■ SummaryMessage — A brief message describing the occurrence

■ DetailedMessage — A detailed message describing the occurrence

■ Data — Context information that applications and providers can present to

interpret a log message.

Solaris WBEM Log Classes

Solaris WBEM Logging Services uses two Solaris Schema classes: Solaris_LogRecord and Solaris_LogService .

30 WDR Developer’s Guide • September 2002

Solaris_LogRecord Class

The Solaris_LogRecord class is defined in the Solaris_Core1.0.mof file to model an entry in a log file. When an application or provider calls the Solaris_LogRecord class in response to an event, the Solaris_LogRecord class causes all data generated by the event to be written to a log file. To see the definition of the Solaris_LogRecord class as part of the Solaris Provider, view the Solaris_Core1.0.mof file in a text editor. The Solaris_Core1.0.mof file is located in /usr/sadm/mof.

The Solaris_LogRecord class uses a vector of properties and key qualifiers to specify attributes of the events, system, user, and application or provider that generate data. Read-only qualifier values are generated transparently for use between the application and the CIM Repository. For example, the value RecordID uniquely identifies the log entry but is not displayed as part of the log format when you view generated data.

You can set the values of writable qualifier values. For example, you can set the qualifier values of properties such as ClientMachineName and ServerMachineName, which identify the system on which an event occurs.

When the SysLogFlag property is set to true, then a detailed message of the log record is automatically sent to the syslog daemon on UNIX systems.

Solaris_LogService Class

The Solaris_LogService class controls the operation of the logging service and defines the ways in which log data is handled. This class has a set of methods that an application can use to distribute data about a particular event to the CIM Object Manager from the issuing application. The data becomes a trigger that generates a response from the CIM Object Manager, such as a retrieval of data from the CIM Repository.

The Solaris_LogService class uses the following methods:

■ clearLog — Renames, and saves a current log file or deletes a saved log file.

■ getNumRecords — Returns the number of records in a particular log file.

■ listLogFiles — Returns a list of all log files stored in /usr/sadm/wbem/log.

■ getCurrentLogFileName — Returns the name of the most recent log file.

■ getNumLogFiles — Returns the number of log files stored in

/usr/sadm/wbem/log.

■ getLogFileSize — Returns the size, in megabytes, of a particular log file.

■ getSyslogSwitch — Enables log data to be sent to SysLog, the logging service

of the Solaris operating environment.

■ getLogStorageName — Returns the name of the host computer or device where

log files are stored.

Chapter 2 Using Solaris WBEM Services in WDR 31

■ getLogFileDir — Returns the path and name of the directory where log files

are stored.

The Solaris_LogServiceProperties class lets you set logging properties. See the section “Setting Solaris WBEM Logging Properties” on page 38.

You can view the definition of the Solaris_LogService class in the Solaris_Core1.0.mof file, which is located in /usr/sadm/mof.

Using the APIs to Enable Solaris WBEM Logging

Currently, you can view log file content in Log Viewer. However, you can develop your own log viewer if you prefer to view log files in a customized manner. You can use the logging application programming interfaces (APIs) to develop a log viewer. The APIs enable you to:

■ Write data from an application to a log file

■ Read data from a log file to your log viewer

■ Set logging properties that specify how logging is handled

Writing Data to a Solaris WBEM Log File

Enabling an application to write data to a log file involves the following main tasks:

■ Creating a new instance of the Solaris_LogRecord class

■ Specifying the properties that will be written to the log file and setting values for

the property qualifiers

■ Setting the new instance and properties to print

▼ To Create an Instance of Solaris_LogRecord

to Write Data

1. Import all the necessary Java classes. The minimum classes are:

import java.rmi.*; import com.sun.wbem.client.CIMClient; import com.sun.wbem.cim.CIMInstance; import com.sun.wbem.cim.CIMValue;

32 WDR Developer’s Guide • September 2002

import com.sun.wbem.cim.CIMProperty; import com.sun.wbem.cim.CIMNameSpace; import com.sun.wbem.cim.CIMObjectPath; import com.sun.wbem.cim.CIMClass; import com.sun.wbem.cim.CIMException; import com.sun.wbem.solarisprovider.*; import java.util.*;

2. Declare the public class CreateLog and create instances of the following classes: CIMClient, CIMObjectPath, and CIMNameSpace:

public class CreateLog {

public static void main(String args[]) throws CIMException {

if ( args.length != 3) {

System.out.println("Usage: CreateLog host username password");

System.exit(1); } CIMClient cc = null; CIMObjectPath cop = null; try {

CIMNameSpace cns = new CIMNameSpace(args[0]);

cc = new CIMClient(cns, args[1], args[2]);

3. Specify the vector of properties to be returned. Set values for the properties of the qualifiers.

Vector keys = new Vector(); CIMProperty logsvcKey; logsvcKey = new CIMProperty("category"); logsvcKey.setValue(new CIMValue(new Integer(2))); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("severity"); logsvcKey.setValue(new CIMValue(new Integer(2))); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("AppName"); logsvcKey.setValue(new CIMValue("SomeApp")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("UserName"); logsvcKey.setValue(new CIMValue("molly")); keys.addElement(logsvcKey);

Chapter 2 Using Solaris WBEM Services in WDR 33

logsvcKey = new CIMProperty("ClientMachineName"); logsvcKey.setValue(new CIMValue("dragonfly")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("ServerMachineName"); logsvcKey.setValue(new CIMValue("spider")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("SummaryMessage"); logsvcKey.setValue(new CIMValue("brief_description")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("DetailedMessage"); logsvcKey.setValue(new CIMValue("detailed_description")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("data"); logsvcKey.setValue(new CIMValue("0xfe 0x45 0xae 0xda")); keys.addElement(logsvcKey); logsvcKey = new CIMProperty("SyslogFlag"); logsvcKey.setValue(new CIMValue(new Boolean(true))); keys.addElement(logsvcKey);

4. Declare the new instance of the CIMObjectPath class for the log record.

CIMObjectPath logreccop = new CIMObjectPath("Solaris_LogRecord", keys);

5. Declare the new instance of Solaris_LogRecord. Set the vector of properties to write to a file.

CIMInstance ci = new CIMInstance();

ci.setClassName("Solaris_LogRecord"); ci.setProperties(keys); //System.out.println(ci.toString());

cc.setInstance(logreccop,ci); } catch (Exception e) {

System.out.println("Exception: "+e);

e.printStackTrace(); }

6. Close the session after data has been written to the log file.

// close session. if(cc != null) {

34 WDR Developer’s Guide • September 2002

cc.close();

}

Reading Data from a Solaris WBEM Log File

Enabling an application to read data from a log file to a log viewer involves the following tasks:

■ Enumerating instances of the Solaris_LogRecord class

■ Getting the desired instance

■ Printing properties of the instance to an output device, typically a user interface

for the log viewer

▼ To Get an Instance of the Solaris_LogRecord

Class and Read Data

1. Import all the necessary Java classes. The classes listed below are the minimum required:

import java.rmi.*; import com.sun.wbem.client.CIMClient; import com.sun.wbem.cim.CIMInstance; import com.sun.wbem.cim.CIMValue; import com.sun.wbem.cim.CIMProperty; import com.sun.wbem.cim.CIMNameSpace; import com.sun.wbem.cim.CIMObjectPath; import com.sun.wbem.cim.CIMClass; import com.sun.wbem.cim.CIMException; import com.sun.wbem.solarisprovider.*; import java.util.*; import java.util.Enumeration;

2. Declare the class ReadLog .

public class ReadLog

{ public static void main(String args[]) throws CIMException {

Chapter 2 Using Solaris WBEM Services in WDR 35

if ( args.length != 3)

{

System.out.println("Usage: ReadLog host username password"); System.exit(1);

}

3. Set the CIMClient , CIMObjectPath, and CIMNameSpace values of the ReadLog class.

CIMClient cc = null; CIMObjectPath cop = null; try { CIMNameSpace cns = new CIMNameSpace(args[0]); cc = new CIMClient(cns, args[1], args[2]); cop = new CIMObjectPath("Solaris_LogRecord");

4. Enumerate the instances of Solaris_LogRecord.

Enumeration e = cc.enumInstances(cop, true);

for (; e.hasMoreElements(); ) {

5. Send the property values to an output device.

System.out.println("---------------------------------"); CIMObjectPath op = (CIMObjectPath)e.nextElement(); CIMInstance ci = cc.getInstance(op); System.out.println("Record ID : " + (((Long)ci.getProperty("RecordID").getValue().getValue()).longValue

()));

System.out.println("Log filename : " +

((String)ci.getProperty("FileName").getValue().getValue()));

int categ = 0

(((Integer)ci.getProperty("category").getValue().getValue()).intV alue());

if (categ == 0)

System.out.println("Category : Application Log");

else if (categ == 1)

System.out.println("Category : Security Log");

else if (categ == 2)

System.out.println("Category : System Log");

int severity =

(((Integer)ci.getProperty("severity").getValue().getValue()).intV alue());

if (severity == 0)

36 WDR Developer’s Guide • September 2002

System.out.println("Severity : Informational");

else if (severity == 1)

System.out.println("Severity : Warning Log!");

else if (severity == 2)

System.out.println("Severity : Error!!");

System.out.println("Log Record written by :" +

((String)ci.getProperty("AppName").getValue().getValue()));

System.out.println("User : " +

((String)ci.getProperty("UserName").getValue().getValue()));

System.out.println("Client Machine : " +

((String)ci.getProperty("ClientMachineName").getValue().getValue( )));

System.out.println("Server Machine : " + ((String)ci.getProperty("ServerMachineName").getValue().getValue()) );

System.out.println("Summary Message : " +

((String)ci.getProperty("SummaryMessage").getValue().getValue()) );

System.out.println("Detailed Message : " +

((String)ci.getProperty("DetailedMessage").getValue().getValue() ));

System.out.println("Additional data : " +

((String)ci.getProperty("data").getValue().getValue()));

boolean syslogflag =

((Boolean)ci.getProperty("syslogflag").getValue().getValue()). booleanValue();

if (syslogflag == true) {

System.out.println("Record was written to syslog as well");

} else {

System.out.println("Record was not written to syslog"); } System.out.println("---------------------------------");

6. Return an error message to the user if an error condition occurs.

... catch (Exception e) {

System.out.println("Exception: "+e); e.printStackTrace(); } ...

7. Close the session when the data has been read from the file.

Chapter 2 Using Solaris WBEM Services in WDR 37

// close session.

if(cc != null) {

cc.close();

}

Setting Solaris WBEM Logging Properties

You can create an instance of the Solaris_LogServiceProperties class and set property values for the instance to control how your application or provider handles logging.

▼ To Set Solaris WBEM Logging Properties

The following code example shows how to set logging properties. Properties are stored in the /var/sadm/lib/wbem/WbemServices.properties file.

public class SetProps {

public static void main(String args[]) throws CIMException {

if ( args.length != 3) {

System.out.println("Usage: SetProps host username password");

System.exit(1); } CIMClient cc = null; try {

CIMNameSpace cns = new CIMNameSpace(args[0]);

cc = new CIMClient(cns, args[1], args[2]);

CIMObjectPath logpropcop = new

CIMObjectPath("Solaris_LogServiceProperties");

Enumeration e = cc.enumInstances(logpropcop, true);

for (; e.hasMoreElements(); ) {

CIMObjectPath op = (CIMObjectPath)e.nextElement(); CIMInstance ci = cc.getInstance(op); ci.setProperty("Directory", new CIMValue("/tmp/bar1/")); ci.setProperty("FileSize", new CIMValue("10")); ci.setProperty("NumFiles", new CIMValue("2"));

38 WDR Developer’s Guide • September 2002

ci.setProperty("SyslogSwitch", new CIMValue("off")); cc.setInstance(logpropcop,ci);

} } catch (Exception e) {

System.out.println("Exception: "+e);

e.printStackTrace(); } // close session. if(cc != null) {

cc.close();

} }

Solaris WBEM Log Viewer

You can view all details of a log record in the Solaris Management Console (SMC) Log Viewer, an application that provides a graphical user interface for viewing recorded data. For more information on the SMC, see the man page smc(1M).

After you have created a log record, you can start the SMC and then its Log Viewer.

▼ To Start SMC and Solaris Log Viewer

1. Change to the location of the SMC invocation command by typing the following:

# cd /usr/sbin

2. Start SMC by typing the following command:

# smc

3. In the Navigation panel, double-click This Computer (or single-click the expand/compress icon next to it) to expand the tree beneath it. Double-click System Status and the Log Viewer icon will be displayed.

4. Click the Log Viewer icon to start the application.

Chapter 2 Using Solaris WBEM Services in WDR 39

40 WDR Developer’s Guide • September 2002

CHAPTER

Using Process Indications

This chapter describes CIM process indications; how they are used to communicate the occurrence of events; and the classes that enable clients to subscribe to receive CIM process indications. This chapter includes the following topics:

■ “The CIM Event Model” on page 41

■ “How Indications are Generated” on page 42

■ “How Subscriptions Are Created” on page 43

■ “Adding a CIM Listener” on page 44

■ “Creating an Event Filter” on page 44

■ “Creating an Event Handler” on page 46

■ “Binding an Event Filter to an Event Handler” on page 48

For more information about process indication classes, see Chapter 4, “Classes, Domains, Associations, and Indications in WDR.”

Note – For more in-depth information on the CIM Event Model, see the Distributed

Management Task Force white paper at http://www.dmtf.org/education/whitepapers.php.

The CIM Event Model

Tip – The CIM Event API is located at

/usr/sadm/lib/wbem/doc/javax/wbem/client/CIMEvent.html.

An event is a real-world occurrence. A process indication is an object that is created as a result of the occurrence of an event. It is important to distinguish between the event; and the process indication, which is a notification of the event. In CIM, events are not published; process indications are published.

A process indication is a subtype of a class that has an association with zero or more triggers (descriptions of changes in data that result from events) that can create instances of the Indication class. The WBEM implementation does not have an explicitly defined object that represents a trigger. Triggers are implied either by the operations on basic objects of the system (create, delete, and modify on classes, instances, and namespaces) or by events in the managed environment. When an event takes place, the WBEM provider generates a process indication that something happened in the system.

For example, with a Service class, when the service stops and a trigger is engaged, it results in a process indication that serves as notification that the service stopped.

You can view the related CIM classes in the Solaris WBEM Services schema at /usr/sadm/lib/wbem/doc/mofhtml/index.html. The class is structured as follows:

■ Root class: CIM_Indication

■ Superclass: CIM_ClassIndication

■ Subclasses: CIM_ClassCreation

■ CIM_ClassDeletion

■ CIM_ClassModification

■ Superclass: CIM_InstIndication

■ Subclasses: CIM_InstCreation

■ CIM_InstDeletion

■ CIM_InstMethodRecall

■ CIM_InstRead

■ Superclass: CIM_ProcessIndication

The CIM_ProcessIndication superclass resides at the top of the “The WDR Indication Class Hierarchy Diagram” on page 87.

How Indications are Generated

CIM events can be classified as either life cycle events or process events. A life cycle event is a built-in (intrinsic) CIM event that occurs in response to a change to data in which a class or class instance is created, modified, or deleted. A process event is a user-defined (extrinsic) event that is not described by a life cycle event.

Administrators can change the event polling interval and the default polling behavior of the CIM Object Manager by editing the properties in the cimom.properties file. For instructions on editing the cimom.properties file, see the Solaris WBEM Services Administrator’s Guide (part number 806-6468-10).

42 WDR Developer’s Guide • September 2002

Event providers generate indications in response to requests made by the CIM Object Manager. The CIM Object Manager analyzes subscription requests and uses the EventProvider interface to contact the appropriate provider, requesting that it generate the appropriate indications. When the provider generates the indication, the CIM Object Manager routes the indication to the destinations specified by the CIM_IndicationHandler instances. These instances are created by the subscribers.

How Subscriptions Are Created

A client application can subscribe to be notified of CIM events. A subscription is a declaration of interest in one or more streams of indications.

An application that subscribes for indications of CIM events describes:

■ The events in which it is interested.

■ The action that the CIM Object Manager must take when each event occurs.

The occurrence of an event is represented as an instance of one of the subclasses of the CIM_Indication class. An indication is generated only when a client subscribes for the event.

To create a subscription, specify an instance of the CIMListener interface and create instances of the following subclasses of the CIM_Indication class:

CIM_IndicationFilter — Defines the criteria for generating an indication and which data should be returned in the indication.

CIM_IndicationHandler — Describes how to process and handle an indication. May include a destination and a protocol for delivering indications.

CIM_IndicationSubscription — An association that binds an event filter with an event handler.

An application can create one or more event filters with one or more event handlers. Event indications are not delivered until the application creates the event subscription.

Chapter 3 Using Process Indications 43

Adding a CIM Listener

To register for indications of CIM events, add an instance of the CIMListener interface. The CIM Object Manager generates indications for CIM events that are specified by the event filter when a client subscription is created.

The CIMListener interface must implement the indicationOccurred method which takes the argument CIMEvent. This method is invoked when an indication is available for delivery.

▼ To Add a CIM Listener

Use code such as the following to add a CIM listener:

// Connect to the CIM Object Manager cc = new CIMClient(); // Register the CIM Listener cc.addCIMListener(new CIMListener() {

public void indicationOccured(CIMEvent e) { }

});

Creating an Event Filter

Event filters describe the types of events to be delivered and the conditions under which they are delivered. An application creates an event filter by creating an instance of the CIM_IndicationFilter class and defining values for its properties. Event filters belong to a namespace. Each event filter works only on events that belong to the namespace to which the filter also belongs.

44 WDR Developer’s Guide • September 2002

The CIM_IndicationFilter class has string properties that an application can set to identify the filter uniquely, specify a query string, and set the query language used to parse the query string, as shown in the following table. Currently, only the WBEM Query Language is supported.

TABLE3-1 Properties in the CIM_IndicationFilter Class

Property Description Required/Optional

SystemCreationClassName The name of the system on

which the creation class for the filter resides, or to which it applies

SystemName The name of the system on

which the filter resides, or to which it applies

CreationClassName The name of the class or

subclass that was used to create the filter

Name The unique name of the

filter

SourceNamespace The path to a local

namespace where the CIM indications originate

Query A query expression that

defines the conditions under which indications are generated. Currently, only Level 1 WBEM Query Language expressions are supported. To learn how to construct WQL query expressions, see the section “Querying” in the Sun

WBEM SDK Developer’s Guide (part number 806-

6831-10).

QueryLanguage The language in which the

query expression is written.

Optional. The default for this key property is the

CIMSystem.Creation ClassName

Optional. The default for this key property is the name of the system on which the CIM Object Manager is running.

Optional. The CIM Object Manager assigns

CIM_IndicationFilter

as the default for this key property.

Optional. The CIM Object Manager assigns a unique name.

Optional. The default is null.

Required

Required. The default is WQL (WBEM Query Language).

Chapter 3 Using Process Indications 45

▼ To Create an Event Filter

1. Create an instance of the CIM_IndicationFilter Class, using code such as the following:

CIMClass cimfilter = cc.getClass

(new CIMObjectPath(‘‘CIM_IndicationFilter’’), true, true, true, null);CIMInstance ci = cimfilter.newInstance();

2. Specify the name of the event filter, using code such as the following:

Name = ‘‘filter_all_new_solarisdiskdrives’’;

3. Create a WQL string to identify event indications to be returned, using code such as the following:

String filterString = ‘‘SELECT *

FROM CIM_InstCreation WHERE sourceInstance is ISA Solaris_DiskDrive’’

4. Set property values in the cimfilter instance to identify the name of the filter, the filter string that selects CIM events, and the query language used to parse the query string, using code such as the following.

Note – Currently, only the WBEM Query Language can be used to parse query

strings.

ci.setProperty(‘‘Name’’;, new

CIMValue("filter_all_new_solarisdiskdrives”)); ci.setProperty("Query", new CIMValue(filterString)); ci.setProperty("QueryLanguage", new CIMValue("WQL");)

5. Create an instance from the cimfilter instance and store it in the CIM Object Manager Repository, using code such as the following:

CIMObjectPath filter = cc.createInstance(new CIMObjectPath(), ci);

Creating an Event Handler

The Solaris Event MOF extends the CIM_IndicationHandler class by creating the Solaris_JAVARXMIDelivery class to handle delivery of indications of CIM events to client applications using the RMI protocol. RMI clients must instantiate the Solaris_JAVAXRMIDelivery class to set up an RMI delivery location. Clients can use only RMI to receive events; HTTP is not supported.

46 WDR Developer’s Guide • September 2002

An application sets the properties in the CIM_IndicationHandler class to uniquely name the handler and identify the UID of its owner.

TABLE3-2 Properties in the CIM_IndicationHandler Class

Property Description Required/Optional

SystemCreationClassName The name of the system on

which the creation class for the handler resides, or to which it applies

SystemName The name of the system on

which the handler resides, or to which it applies

CreationClassName The name of the class or

subclass that was used to create the handler

Name The unique name of the

handler

Owner The name of the entity that

created, or that maintains, this handler. The provider can check this value to determine whether to authorize a handler to receive an indication.

Optional. Set by the CIM Object Manager.

Optional. The default for this key property is the name of the system on which the CIM Object Manager is running.

Optional. The CIM Object Manager assigns the appropriate class as the default for this key property.

Required. The client application must assign a unique name.

Optional. The default value is the Solaris user name of the user who is creating the instance.

Chapter 3 Using Process Indications 47

▼ To Create a CIM Event Handler

To create a CIM event handler, use code such as the following:

// Create an instance of the Solaris_RMIDelivery class. CIMClass rmidelivery = cc.getClass(new CIMObjectPath

(‘‘Solaris_RMIDelivery’’;), false, true, true, null);

CIMInstance ci = rmidelivery.newInstance();

//Create a new instance (delivery) from //the rmidelivery instance. CIMObjectPath delivery = cc.createInstance(new CIMObjectPath(), ci);

Binding an Event Filter to an Event Handler

An application binds an event filter to an event handler by creating an instance of the CIM_IndicationSubscription class. When a CIM_IndicationSubscription is created, indications for the events specified by the event filter are delivered.

▼ To Bind an Event Filter to an Event Handler

The following example code creates a subscription (filterdelivery) and defines the filter property to the filter object that was created in “Creating an Event Filter” on page 44, and defines the handler property to the delivery object created in “To Create a CIM Event Handler” on page 48:

CIMClass filterdelivery = cc.getClass(new

CIMObjectPath(‘’CIM_IndicationSubscription’’), true, true, true, null);

ci = filterdelivery.newInstance();

//Create a property called “filter” that refers to the filter //instance. ci.setProperty("filter", new CIMValue(filter));

48 WDR Developer’s Guide • September 2002

//Create a property called handler that refers to the delivery //instance. ci.setProperty("handler", new CIMValue(delivery));

CIMObjectPath indsub = cc.createInstance(new CIMObjectPath(), ci);

Chapter 3 Using Process Indications 49

50 WDR Developer’s Guide • September 2002

CHAPTER

Classes,Domains,Associations, and Indications in WDR

This chapter describes the classes, domains, associations, and indications that are part of the WDR CIM class hierarchy, which is depicted i n the diagram below.

Chapter 4 contains five sections:

■ “CIM Attachment Point Classes” on page 53

■ “CIM Slot Classes” on page 66

■ “CIM Solaris_WDRDomain Classes” on page 74

■ “WDR Schema Associations and Aggregations” on page 81

■ “CIM Process Indication Classes” on page 86

WDR CIM Class Hierarchy Diagram

Solaris_WDRDomain

• Id

Solaris_SGDomain

• BoardRelationship

• KeySwitchPosition

• State

CIM_CollectionOfMSEs

Solaris_DomainHasAttachmentPoints

Solaris_XCDomain

• ActiveEthernetBoard

• AdminGroup

• BoardRelationship

• KeySwitchPosition

• ReconfigGroup

• State

Solaris_CHCPU

• ECache

Solaris_DomainhasSlots

• ID

• Speed

Solaris_SystemBoardHasProcessors

Solaris_WDRAttachmentPoint

• Busy

• ClassName

• Condition

• DomainID

• LogicalID

• MiscInfo

• OccupantState

• PhysicalID

• ReceptacleState

• StatusTime

• Type

• Configure()

• Connect()

• Disconnect()

• Test()

• Unconfigure()

Solaris_CHSystemBoard

• Assigned

• PoweredOn

CIM_LogicalElement

Solaris_CHMemory

• Deleted

• Interleaved

• Permanent

• PhysicalAddress

• Remaining

• Size

• Source

• Target

• Unconfigurable

Solaris_CHController

• Device

• Referenced

Solaris_SystemBoardHasControllers

Solaris_WDRSlot

• Empty

• LogocalID

• Assign()

• Unassign()

Solaris_XCSlot Solaris_SGSlot

• AssignedDomain

• AssignmentState

• BoardType

• PowerState

• TestState

Solaris_SlotHasSystemBoard

CIM_LogicalElement

• AssignedDomain

• AssignmentState

• BoardType

• PowerState

• TestState

52 WDR Developer’s Guide • September 2002

• Assign()

• PowerOff()

• PowerOn()

• Unassign()

Solaris_SystemBoardHasMemory

Legend

Properties Methods

Children/Parent class Association

CIM Attachment Point Classes

Attachment point classes provide logical elements that represent attachment points in Sun Fire 15K, 12K, 6800, 4810, 4800, or 3800 systems. An attachment point is an interface to a physical location in Sun Fire 15K, 12K, 6800, 4810, 4800, or 3800 systems where you can use WDR to configure system boards, CPUs, and memory modules in domains that are running the Solaris operating environment. An attachment point is comprised of a receptacle and an occupant. When you insert an occupant into a receptacle or remove it from a receptacle, the attachment point’s state changes.

Note – For more information about attachment points, refer to the cfgadm(1M)

man page (all Sun Fire models) and the cfgadm_sbd(1M) man page (Sun Fire 15K and 12K only).

Attachment point classes are similar to Slot classes insofar as they represent physical locations in Sun Fire 15K, 12K, 6800, 4810, 4800, or 3800 systems where you can use WDR. (See the section “CIM Slot Classes” on page 66.) However, Slot classes provide logical elements that represent only system board and I/O boards, and not CPUs, memory, and I/O controllers. Slots are a type of attachment point whose scope is limited only to boards.

CIM Solaris_WDRAttachmentPoint Class

Position in the Class Hierarchy

CIM_LogicalElement

| +--Solaris_WDRAttachmentPoint

Description

Represents the core Configuration Administration information. (For more information see the cfgadm(1M) man page.) This information is gathered using the libcfgadm library on domains.

Chapter 4 Classes, Domains, Associations, and Indications in WDR 53

Direct Known Subclasses

CIM Solaris_CHCPU Class, CIM Solaris_CHSystemBoard Class, CIM Solaris_CHController Class, and CIM Solaris_CHMemory Class

CIM Solaris_WDRAttachmentPoint Class Properties

Note – For more information about attachment points, refer to the cfgadm(1M) man

page (all Sun Fire systems), and the cfgadm_sbd(1M) man page (Sun Fire 15K and 12K systems only).

TABLE4-1 CIM Solaris_WDRAttachmentPoint Properties

Property Data Type Description

ClassName string The class of attachment point. For example, “sbd” represents a

system board.

Busy uint32 Indicates whether the attachment point is currently in a state

transition.

Condition uint32 The condition of the attachment point. Possible values: Unknown,

OK, Failing, Failed, and Unusable

LogicalID string The logical identifier of the attachment point

PhysicalID string The physical identifier of the attachment point. For example:

/devices/pseudo/dr@0::SB6

DomainID uint32 The domain to which this attachment point is assigned or available.

On Sun Fire 15K systems, domains are numbered between 0 and 17. On Sun Fire 12K systems, domains are numbered between 0 and 8. On Sun Fire 3800, 4800, and 4810 systems, domains are numbered 0 and 1 (maximum two domains). On Sun Fire 6800 systems, domains are numbered between 0 and 3 (maximum four domains).

OccupantState uint32 The occupant state of the attachment point. Possible values: None,

Configured, and Unconfigured

ReceptacleState uint32 The receptacle state of the attachment point. Possible values: None,

Empty, Disconnected, and Connected

Type string The type of the attachment point. Either cpun, pcin, or memn,

where n is the number of the component.

54 WDR Developer’s Guide • September 2002

TABLE4-1 CIM Solaris_WDRAttachmentPoint Properties

MiscInfo string Driver-specific information that the driver sets. A list of name-value

pairs. Depends on the value of the Type property.

For example, if the Type property is cpun, the MiscInfo property contains is populated with the following information: the Processor ID, the Processor speed, and the Ecache memory size in MB.

StatusTime datetime The date and time of the latest status change to the attachment

point, in the following format:

yyyymmddhhmmss.mmmmmmsutc

Where:

yyyy represents the year, mm represents the month, dd represents the day, hh represents the hour, mm represents the minutes, ss represents the seconds,

CIM Solaris_WDRAttachmentPoint Class Methods

There are five Solaris_WDRAttachmentPoint methods, which you use to add attachment point resources to, and remove them from, live domains; and test the status of attachment points.

Note – For more information about Solaris_WDRAttachmentPoint Class

methods, refer to the following man pages: cfgadm(1M), cfgadm_sbd(1M), and rcfgadm(1M).

Method Return Codes

All the Solaris_WDRAttachmentPoint methods return an sint32 value that indicates whether the method executed successfully. A return value of zero indicates successful execution, and a non-zero value indicates that an error occurred, as follows:

0 = Configuration operation succeeded 1 = Configuration operation cancelled

Chapter 4 Classes, Domains, Associations, and Indications in WDR 55

2 = Configuration administration not supported 3 = Configuration operation not supported 4 = Insufficient privileges 5 = Component system is busy, try again 6 = System is busy, try again 7 = Data error 8 = Library error 9 = No Library found 10 = Insufficient condition 11 = Configuration operation invalid 12 = Hardware specific failure 13 = Attachment point not found 14 = No attachment point with specified attributes found

Note – For more information about how clients invoke methods see the Sun WBEM

API Specification in the WBEM SDK, which can be found at

/usr/sadm/lib/wbem/doc/index.html. Before you use invokeMethod(), you populate the inParams vector with all the [IN] (input) parameters, in the exact order shown; and populate the outParams vector with an empty string. After invokeMethod() returns, the outParams vector will contain any error string that might have been generated by the corresponding DR operation; or will be an empty string.

56 WDR Developer’s Guide • September 2002

CIM Solaris_WDRAttachmentPoint Method Descriptions

TABLE4-2 CIM Solaris_WDRAttachmentPoint Methods

Name Description

Configure Configures the attachment point into a Solaris domain.

Parameters:

• boolean — force [IN] Forces the Configure operation, which might otherwise fail due to

the condition of the attachment point or other hardware-dependent considerations. Hardware-specific safety and integrity checks can prevent the force option from having any effect.

• string — hardwareOpts [IN] These options are passed to the cfgadm hardware-specific

plug-in. WDR currently interfaces with the cfgadm_sbd plug-in indirectly. If you specify

-o nopoweroff, the disconnect function leaves the board powered on. If you specify -o unassign, the disconnect function unassigns the board from the domain.

If you unassign a board from a domain, you can assign it to another domain. However, if it is assigned to another domain, it is not available to the domain from which is was unassigned.

• uint32 — retries [IN] Specifies the number of times the dynamic reconfiguration (DR)

request is retried on the domain. The default is zero.

• uint32 — retryDelay [IN] Specifies the time interval, in seconds, between retries. This

option cannot be used alone and must be specified with the -r retry_count option. The default value is zero, meaning that the DR request is retried immediately.

• string — error [OUT] The specified string will contain any error string returned by the

corresponding DR command; or will be empty if the command does not return an error string.

Unconfigure Removes the resources of the attachment point from the Solaris domain in which it is currently

configured.

The parameters used by this method are the same as those shown for the Configure method above.

Connect Changes the receptacle state to connected.

The parameters used by this method are the same as those shown for the Configure method above.

Disconnect Disables normal communication, to, or, from the occupant in a receptacle.

The parameters used by this method are the same as those shown for the Configure method above.

Chapter 4 Classes, Domains, Associations, and Indications in WDR 57

TABLE4-2 CIM Solaris_WDRAttachmentPoint Methods

Test Explicitly requests that the board be tested using POST, even if the board has already been

tested.

Note: Calling the Connect method tests the board using POST, making a call to the Test method unnecessary.

Parameters:

• boolean — verbose [IN] Does not perceptibly affect the function of this method because

DR command output is not available to the client.

• string — hardwareOpts [IN] Used in the same way as the hardwareOpts parameter

described for the Configure method above.

• string — error [OUT] Used in the same way as the error parameter described for the

Configure method above.

CIM Solaris_CHSystemBoard Class